Askr
Server & APIs

JWT

Use jwt with the current published Askr packages.

  • @askrjs/auth/jwt0.0.3

How to use jwt

Create a validator with explicit issuer, audience, key selection, and clock policy; reject tokens before turning claims into a principal.

  1. Import the published @askrjs/auth/jwt entrypoint.
  2. Keep jwt configuration next to the component, route, or server composition root that owns it.
  3. Handle pending, unavailable, cancellation, and failure states, then verify the production path.
import { createJwtValidator } from '@askrjs/auth/jwt';

const validateAccessToken = createJwtValidator({
  issuer: env.OIDC_ISSUER,
  audience: env.API_AUDIENCE,
  jwks: keySet,
});

Token verification

createJwtValidator(options: JwtValidatorOptions) from @askrjs/auth/jwt returns a JwtValidator whose validate(token) is an async method returning the decoded Principal on success. It checks the signature against the configured key set and confirms the issuer and, if provided, audience claims match before returning anything - a token that fails any of those checks never reaches your handler.

Claims and clocks

JwtValidatorOptions requires issuer and jwks; audience is optional and can be a single string or a list of accepted values. clock defaults to Date.now but can be overridden - useful for tests - and clockSkewSeconds gives exp/nbf checks tolerance for clock drift between services. OidcIdTokenOptions reuses this exact shape and adds a required nonce, which is what validateOidcIdToken() checks the ID token's nonce claim against to catch replay.

Key selection

jwks is a JwksProvider: either a static JsonWebKeySet or a function that returns one, which lets you fetch and cache keys from a JWKS endpoint however you like. Each key in the set is an AskrJsonWebKey, extending the standard JsonWebKey with optional kid, alg, and use fields, so the validator can pick the exact key referenced by the token's header instead of trying every key in the set against every token.

Failure handling

Validation failures throw a JwtValidationError carrying a typed code - malformed_token, unsupported_algorithm, unknown_key, invalid_signature, or invalid_claim - so calling code can tell a garbled client token apart from a JWKS endpoint that's missing the key it needs. createJwtIssuer(options: JwtIssuerOptions) is the write side: give it privateKey, kid, issuer, audience, and ttlSeconds, and the returned JwtIssuer exposes issue(principal) to sign tokens plus a validator property already configured to check tokens it issued.