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.

Reference

Installation

npm install tr-jwt

Node.js >=24.0.0 is required.

Exports

const { encode, decode } = 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

Notes

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

Author

Timo J. Rinne tri@iki.fi — https://github.com/rinne/

Copyright

Copyright © 2023–2026 Timo J. Rinne tri@iki.fi. See COPYING for the full MIT license text.

License

MIT License