Variable: StandardJwt

const StandardJwt: object

Defined in: jwt.ts:382

RFC 9964 ML-DSA JWTs: interoperable with any compliant JOSE implementation.

Type Declaration

generateKeyPair()

readonly generateKeyPair(alg?, options?): object

Generates an ML-DSA key pair as AKP JWKs. The private JWK contains the secret seed as a string (inherent to JWK): store it as carefully as any secret key.

Parameters

alg?

MlDsaJoseAlg = ...

The ML-DSA parameter set (default: the library's default signature algorithm).

options?

kid is copied into both JWKs when non-empty.

kid?

string

Returns

object

The public JWK (no priv) and the private JWK (with priv, the base64url 32-byte seed).

privateJwk

privateJwk: AkpJwk

publicJwk

publicJwk: AkpJwk

Throws

if alg is not ML-DSA-44, ML-DSA-65 or ML-DSA-87.

publicJwk()

readonly publicJwk(privateJwk): AkpJwk

Derives the public JWK from a private one.

Parameters

privateJwk

AkpJwk

An AKP JWK with priv.

Returns

AkpJwk

A JWK with kty, alg, pub and, when the private JWK has a non-empty kid, kid.

Throws

if privateJwk is not an AKP key, lacks pub or priv, or has a priv that is not base64url.

Throws

if its alg is not an ML-DSA JOSE algorithm.

Throws

if priv is not a valid seed.

sign()

readonly sign(claims, privateJwk, options?): string

Signs claims as a compact JWS (alg = the key's ML-DSA level).

The header is { alg, typ: "JWT" } plus kid when the JWK has one. The signature is FIPS 204 ML-DSA with an empty context over header.payload.

Parameters

claims

JwtClaims

Claims to include; they override the generated iss, iat and exp.

privateJwk

AkpJwk

An AKP JWK with priv.

options?

StandardSignOptions = {}

issuer and expiresIn in seconds (default 3600; 0 omits exp).

Returns

string

The compact token.

Throws

if the JWK is malformed or expiresIn is negative or not finite.

Throws

if the JWK's alg is not an ML-DSA JOSE algorithm.

Throws

if priv does not decode to a 32-byte seed.

verify()

readonly verify(token, publicJwk, options?): JwtClaims

Verifies a compact JWS against publicJwk and returns the claims. The algorithm is taken from the key and must equal the header alg; crit headers are rejected.

The signature part must be canonical unpadded base64url.

Parameters

token

string

The compact token.

publicJwk

AkpJwk

An AKP JWK with pub.

options?

StandardVerifyOptions = {}

Claim checks (issuer, audience, validateExp, validateNbf, requireExp, now).

Returns

JwtClaims

The payload claims.

Throws

for an invalid signature or failed claim check.

Throws

if the header alg differs from the key's alg.

Throws

if the JWK's alg is not an ML-DSA JOSE algorithm, or the header has a crit member.

Throws

if the JWK or the token is malformed.

Throws

if pub decodes to a key of the wrong length.

Example

const { publicJwk, privateJwk } = StandardJwt.generateKeyPair('ML-DSA-65');
const token = StandardJwt.sign({ sub: 'alice' }, privateJwk, { expiresIn: 600 });
const claims = StandardJwt.verify(token, publicJwk, { requireExp: true });