@sourceregistry/node-jwt

🔐 @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 (Trying😉)
• 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

Key Type	Detection Logic	Selected Algorithm
Symmetric (string / Buffer)	Default HMAC	HS256
RSA private key	PKCS#1 v1.5	RS256
RSA-PSS private key	Hash algorithm in key	PS256 / PS384 / PS512
EC P-256 (prime256v1)	Curve name	ES256
EC P-384 (secp384r1)	Curve name	ES384
EC P-521 (secp521r1)	Curve name	ES512
EC secp256k1	Curve name	ES256K
Ed25519	Key type	EdDSA

💡 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

Algorithm	Type	Secret Type
HS256 / HS384 / HS512	HMAC	string | Buffer
RS256 / RS384 / RS512	RSA	Private / Public key
PS256 / PS384 / PS512	RSA-PSS	Private / Public key
ES256 / ES384 / ES512	ECDSA	Private / Public key
ES256K	ECDSA (secp256k1)	Private / Public key
EdDSA	Ed25519	Private / Public key

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
• Load remote JWKS with caching via JWKS.fromWeb()

🔹 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);

🔹 Example: Remote JWKS (fromWeb)

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

const jwks = await JWKS.fromWeb('https://issuer.example', {
  ttl: 60_000,
  timeoutMs: 2_000
});

const jwk = await jwks.key('my-kid');
const keyObject = jwk?.toKeyObject();
const keys = await jwks.list();
const rsaKeys = await jwks.find({ kty: 'RSA' });
const firstSigKey = await jwks.findFirst({ use: 'sig' });

// Force refresh
await jwks.refresh(); // returns resolver for chaining

// Access cached JWKS snapshot
const current = jwks.export();

fromWeb() options:

• fetch — custom fetch implementation (for runtimes/framework adapters)
• ttl — cache TTL in ms (0 disables automatic refresh)
• timeoutMs — network timeout in ms
• endpointOverride — custom endpoint (absolute or relative)
• overrideEndpointCheck — skip automatic /.well-known/jwks.json append
• cache — custom cache backend with { get(key), set(key, value) }

fromWeb() resolver methods:

• key(kid) — returns a normalized key (or undefined) extended with toKeyObject()
• list() — returns all normalized keys
• find(query) — returns normalized matching keys
• findFirst(query) — returns first normalized match or undefined
• refresh() — forces reload and returns the resolver instance
• export() — returns the current cached JWKS snapshot

🔹 Local Examples

See runnable examples in:

• examples/jwt.example.ts
• examples/jwks.example.ts

🛡️ 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

✅ Production Checklist

Use this profile in production verification paths:

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

const result = verify(token, publicKeyOrSecret, {
  algorithms: ['RS256'],           // pin expected algorithm(s)
  issuer: 'https://issuer.example',
  audience: 'my-service',
  clockSkew: 30,                   // seconds
  maxTokenAge: 3600                // seconds
});

Recommended operational checks:

• Pin algorithms in every verify call (do not rely on implicit acceptance).
• Always validate issuer and audience for external tokens.
• Use short token lifetimes and enforce maxTokenAge.
• Rotate keys regularly and configure JWKS cache ttl for your threat model.
• Monitor and alert on verification failures (INVALID_SIGNATURE, INVALID_CLAIM, INVALID_OPTIONS).

🔏 ECDSA Signature Format: DER vs JOSE (New)

For ECDSA algorithms (ES256, ES384, ES512, ES256K) there are two common signature encodings:

• DER (ASN.1) — what Node.js produces by default
• JOSE (r || s raw signature) — required by the JWT/JWS spec and used by systems like VAPID/Web Push (WNS)

Default behavior

By default, this library outputs DER signatures for ES* algorithms to match Node.js/OpenSSL defaults.

Enable JOSE output

To generate spec-compliant JOSE ECDSA signatures, set:

• signatureFormat: "jose" in sign()

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

const token = sign(
  { sub: "123", iat: Math.floor(Date.now() / 1000) },
  ecPrivateKey,
  { alg: "ES256", signatureFormat: "jose" }
);

// Verify JOSE-signed token
const result = verify(token, ecPublicKey, { signatureFormat: "jose" });

Auto-detect verification (optional)

If enabled in your version, verify() can also validate JOSE ECDSA signatures without specifying signatureFormat (it will try DER first, then JOSE). If you want strict behavior, pass signatureFormat: "der" or signatureFormat: "jose" explicitly.

💡 For VAPID/Web Push (e.g. Windows WNS endpoints), you typically need ES256 with signatureFormat: "jose".

📚 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

• High 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

Import	Description
@sourceregistry/node-jwt	Sync API
@sourceregistry/node-jwt/promises	Promise API

🙌 Contributing

PRs welcome! Please add tests and maintain full coverage.

🔐 Security issues? Report responsibly: [e-mail]

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