🔐 @sourceregistry/node-jwt

A minimal, secure, and production-ready JWT (JSON Web Token) library for Node.js with zero dependencies. Supports all standard signing algorithms (HMAC, RSA, ECDSA, EdDSA, RSASSA-PSS), automatic algorithm detection, JWK/JWKS, and full claim validation.

✨ Why another JWT library? Most JWT libraries are bloated, have security pitfalls, or lack proper TypeScript support. This library is:

• Tiny
• Secure by default
• TypeScript-first with full JSDoc
• Zero external dependencies
• 100% test coverage
• Dual API: Sync and Promise-based
• Automatic algorithm detection based on key type
• Full JWK/JWKS support (import/export, toPublicJWK, x5c/x5t, RFC 7638 thumbprints, kid-based key selection)

📦 Installation

npm install @sourceregistry/node-jwt

Requires Node.js ≥ 16

🚀 Quick Start

Sync API (default)

import { sign, verify, decode } from '@sourceregistry/node-jwt';

// Sign (algorithm auto-detected)
const token = sign(
  { sub: '1234567890', name: 'John Doe', iat: Math.floor(Date.now() / 1000) },
  'your-secret-key'
);

// Verify
const result = verify(token, 'your-secret-key', { issuer: 'https://example.com' });
if (result.valid) {
  console.log('Payload:', result.payload);
} else {
  console.error('JWT Error:', result.error.code, result.error.reason);
}

// Decode (unsafe)
const { header, payload, signature } = decode(token);

Promise API (/promises)

import { sign, verify, decode } from '@sourceregistry/node-jwt/promises';

// Sign (algorithm auto-detected)
const token = await sign(
  { sub: '1234567890', name: 'John Doe', iat: Math.floor(Date.now() / 1000) },
  'your-secret-key'
);

// Verify
try {
  const { payload } = await verify(token, 'your-secret-key', {
    issuer: 'https://example.com',
    audience: 'my-app',
    algorithms: ['HS256']
  });
  console.log('Payload:', payload);
} catch (error) {
  console.error('JWT Error:', error.code, error.reason);
}

// Decode (unsafe)
const { header, payload, signature } = await decode(token);

🧠 Algorithm Autodetection (New)

When options.alg is omitted, the library automatically selects the correct JWT algorithm based on the signing key.

🔑 Autodetection Rules

💡 Node.js exposes OpenSSL curve names (prime256v1, secp384r1, etc.). These are automatically normalized to JOSE algorithms.

❌ Autodetection Errors

Autodetection fails for unsupported keys:

• Unsupported EC curve
• Unsupported RSA-PSS hash algorithm (e.g. sha1)
• Unsupported asymmetric key type (e.g. DSA)

🔑 Supported Algorithms

Keys may be PEM, DER, JWK, or Node.js KeyObject.

🧩 JWK / JWKS Support

• Import/export JWK: importJWK(), exportJWK()
• Convert to public-only JWK: toPublicJWK()
• Compute RFC 7638 thumbprint: getJWKThumbprint()
• Support x5c/x5t (X.509 cert chain + SHA-1 thumbprint)
• Normalize JWKS with auto-generated kid and x5t
• Resolve keys from JWKS by kid for verification

🔹 Example: JWKS Key Selection

import { JWKS, JWK } from '@sourceregistry/node-jwt';

const keyPair = generateKeyPairSync('rsa', { modulusLength: 2048 });
const jwk = JWK.toPublic(keyPair.publicKey);
const jwks = JWKS.normalize({ keys: [jwk] });

// Retrieve key by kid
const keyObject = JWKS.toKeyObject(jwks, jwk.kid);

🛡️ Security Features

• ✅ Safe algorithm autodetection
• ✅ Strict algorithm whitelisting (algorithms option)
• ✅ Full RSASSA-PSS and Ed25519 support
• ✅ Time claim validation (exp, nbf, iat) with clock skew
• ✅ Claim validation (iss, sub, aud, jti)
• ✅ Maximum token age enforcement
• ✅ Timing-safe signature comparison
• ✅ No insecure defaults

📚 API Reference

sign(payload, secret, options?)

• alg (optional) — If omitted, algorithm is auto-detected
• kid — Key ID
• typ — Token type (default: "JWT")

verify(token, secret, options?)

Includes algorithm whitelist protection and full claim validation.

Error Codes include:

• INVALID_TOKEN
• INVALID_ALGORITHM
• ALGORITHM_NOT_ALLOWED
• INVALID_SIGNATURE
• TOKEN_EXPIRED
• TOKEN_NOT_ACTIVE
• TOKEN_TOO_OLD
• MISSING_* / INVALID_*

decode(token)

Decode a JWT without verification (unsafe).

🧪 Testing

• 100% branch coverage
• All algorithms + autodetection paths
• All failure modes
• Sync + Promise APIs
• Full JWK/JWKS coverage (import/export, x5c/x5t, thumbprint, kid selection)

npm test
npm run test:coverage

📦 Exports

🙌 Contributing

PRs welcome! Please add tests and maintain full coverage.

🔐 Security issues? Report responsibly: a.p.a.slaa@projectsource.nl

🔗 GitHub: https://github.com/SourceRegistry/node-jwt 📦 npm: https://www.npmjs.com/package/@sourceregistry/node-jwt