JWT +

Premium JWT module for BoxLang+ providing complete JWS signing, JWE encryption, and a fluent token builder with RFC 7518 / RFC 7519 compliance.

This module is only available to +/++ subscribers but can be installed in conjunction with the bx-plus Module with a limited trial.

The bx-jwt module is a production-ready BoxLang library for creating, signing, verifying, encrypting, and decrypting JSON Web Tokens (JWT/JWE). It implements:

• JWS (JSON Web Signature) — signed tokens using HMAC, RSA, or EC keys

• JWE (JSON Web Encryption) — encrypted tokens using RSA or symmetric keys

• RFC 7518 — JSON Web Algorithms

• RFC 7519 — JSON Web Token

🚀 Key Features

• 🔑 HMAC Signing — HS256, HS384, HS512 with RFC 7518 minimum key length enforcement

• 🔐 RSA Signing — RS256, RS384, RS512

• 📐 EC Signing — ES256 (P-256), ES384 (P-384), ES512 (P-521)

• 🔒 JWE Encryption — RSA-OAEP-256, direct symmetric (dir) with A256GCM

• 🗝️ Named Key Registry — register keys by name in module config; reference by name in BIFs

• 🏗️ Fluent Builder — jwtNew() returns a chainable builder for elegant token creation

• ♻️ Token Refresh — jwtRefresh() re-issues tokens with fresh time claims

• 🔓 Decode Without Verify — jwtDecode() to inspect headers/claims before choosing a key

• ✅ Boolean Validation — jwtValidate() returns true/false without throwing

• 🔧 Key Generation — jwtGenerateSecret() and jwtGenerateKeyPair() helpers

• ⏱️ Clock Skew — configurable tolerance for exp / nbf validation

• 📋 Default Claims — auto-inject iss, aud, exp, iat, jti from module settings

• 🚫 alg:none Protection — unconditionally rejects unsigned tokens

• 📋 Algorithm Allowlist — restrict permitted algorithms via module settings

📦 Installation

# Operating Systems using the Quick Installer
install-bx-module bx-jwt

# Using CommandBox for web servers
box install bx-jwt

🎯 Registered BIFs

This module registers the following Built-In Functions (BIFs):

Function	Purpose	Documentation
jwtNew()	Returns a fluent JwtBuilder for chainable token construction	Fluent Builder
jwtCreate()	Signs a payload and returns a compact JWS token string	JWTCreate
jwtVerify()	Verifies a JWS signature & claims; throws on failure	JWTVerify
jwtValidate()	Like jwtVerify() but returns true/false instead of throwing	JWTValidate
jwtDecode()	Decodes a JWS token without verifying the signature	JWTDecode
jwtRefresh()	Re-issues a token with fresh iat, jti, optional new exp	JWTRefresh
jwtEncrypt()	Encrypts a payload as a compact JWE token	JWTEncrypt
jwtDecrypt()	Decrypts a JWE token and returns the claims struct	JWTDecrypt
jwtGenerateSecret()	Generates a cryptographically random Base64 HMAC secret (default: 256)	JWTGenerateSecret
jwtGenerateKeyPair()	Generates an RSA or EC key pair as PEM strings	JWTGenerateKeyPair

⚡ Quick Start

Sign & Verify (HMAC)

secret  = jwtGenerateSecret( 256 );
token   = jwtCreate( { sub: "user-123", iss: "my-api", roles: [ "admin" ] }, secret, "HS256" );
payload = jwtVerify( token, secret, "HS256" );
writeOutput( payload.sub ); // user-123

Sign & Verify (RSA)

keys    = jwtGenerateKeyPair( "RS256" );
token   = jwtCreate( { sub: "user-123" }, keys.privateKey, "RS256" );
payload = jwtVerify( token, keys.publicKey, "RS256" );

Fluent Builder

token = jwtNew()
    .subject( "user-123" )
    .issuer( "my-api" )
    .audience( "mobile-client" )
    .claim( "roles", [ "admin", "user" ] )
    .expireIn( 3600 )
    .header( "kid", "v1" )
    .sign( secret, "HS256" );

Encrypt & Decrypt (JWE)

token   = jwtEncrypt( { sub: "user-123", ssn: "123-45-6789" }, secret, { keyAlgorithm: "dir", encAlgorithm: "A256GCM" } );
payload = jwtDecrypt( token, secret, { keyAlgorithm: "dir", encAlgorithm: "A256GCM" } );

📚 Usage Guides

• Signing (JWS) — HMAC, RSA, and EC signing patterns

• Encryption (JWE) — RSA-OAEP and symmetric encryption

• Key Management — the named key registry and runtime keys

• Fluent Builder — jwtNew() chainable API walkthrough

• Key Rotation — kid-based rotation patterns

• Security Best Practices — allowlists, key sizes, clock skew

• Configuration — full ModuleConfig settings reference

🔌 Reference

• Built-In Functions — one page per BIF

• Fluent API (JwtBuilder) — chainable methods reference

• Algorithms — supported JWS/JWE algorithm tables

✅ Requirements

• BoxLang Runtime 1.0.0+

• BoxLang+ License (learn more)

📄 License

Licensed under the BoxLang Plus Subscription License.