tr-jwt

JSON Web Token encode/decode helpers for Node.js using JWK keys.

The package signs and verifies compact JWT tokens and validates standard registered claims during decode.

Both a synchronous and a promise-returning asynchronous API are provided.

Reference

Installation

npm install tr-jwt

Node.js >=24.0.0 is required.

Exports

const { encode, encodeAsync, decode, decodeAsync } = require('tr-jwt');

encode(alg, jwk, data, opts)

Creates and signs a compact JWT.

• alg: signing algorithm
• jwk: signing key
• data: payload object
• opts: optional claims merged into the payload

Supported algorithms:

• HS256, HS384, HS512
• ES256, ES384, ES512
• RS256, RS384, RS512
• ML-DSA-44, ML-DSA-65, ML-DSA-87

Supported registered claims:

• exp
• nbf
• iat
• iss
• sub
• aud
• jti

Example:

const { encode, decode } = require('tr-jwt');
const { macKeyGen } = require('tr-jwk');

const key = macKeyGen('ES256');
const token = encode('ES256', key, { sub: '1234' }, { exp: Math.floor(Date.now() / 1000) + 3600 });
const payload = decode(token, key);

Behavior:

• Header is always emitted as { typ: "JWT", alg, ... }
• kid is copied from the JWK when present
• claim values are validated before signing

decode(token, jwk)

Verifies the compact JWT signature and returns the decoded payload object.

Accepted verification keys:

• HMAC: oct JWK
• EC: public or private EC JWK
• RSA: public or private RSA JWK
• ML-DSA: public or private JWK

Validation performed during decode:

• signature verification
• JSON header and payload decoding
• claim shape validation
• exp expiry check
• nbf not-before check

encodeAsync(alg, jwk, data, opts)

Asynchronous counterpart of encode. Takes the same arguments, performs the same validation, and returns a promise resolving to the compact JWT string. Asymmetric signing (EC, RSA, ML-DSA) uses the asynchronous node:crypto signing primitive and does not block the event loop. Invalid input rejects the returned promise.

const token = await encodeAsync('ES256', key, { sub: '1234' });

decodeAsync(token, jwk)

Asynchronous counterpart of decode. Takes the same arguments, performs the same signature verification and claim validation, and returns a promise resolving to the decoded payload object. A token that fails verification or validation rejects the returned promise.

Tokens produced by encode and encodeAsync are identical in format and can be verified interchangeably with decode or decodeAsync.

Notes

• Payload must be a JSON object.
• Compact serialization only.
• aud may be a string or an array of strings.

Author

Timo J. Rinne [email protected] — https://github.com/rinne/

Copyright

Copyright © 2023–2026 Timo J. Rinne [email protected]. See COPYING for the full MIT license text.

License

MIT License