JWT

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

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+

📄 License

Licensed under the BoxLang Plus Subscription License.