@fluojs/jwt

HTTP-agnostic JWT token core that handles signing access tokens and verifying them into a normalized JwtPrincipal.

Table of Contents

• Installation
• When to use
• Quick Start
• Common Patterns
• Configuration Guardrails
• Public API
• Related Packages
• Example Sources

Installation

npm install @fluojs/jwt

When to Use

• When you need to issue or verify JWT access tokens in a backend application.
• When you want a stable JwtPrincipal shape (subject, roles, scopes) regardless of the underlying token claim variants.
• When implementing refresh token rotation with replay detection.

Quick Start

Register the Module

Configure the JWT module with your signing keys and policy.

Import JWT support through JwtModule.forRoot(...) or JwtModule.forRootAsync(...).

import { Module } from '@fluojs/core';
import { JwtModule } from '@fluojs/jwt';

@Module({
  imports: [
    JwtModule.forRoot({
      algorithms: ['HS256'],
      secret: 'your-secure-secret',
      issuer: 'my-api',
      audience: 'my-app',
      accessTokenTtlSeconds: 3600,
    }),
  ],
})
export class AuthModule {}

Async Registration with Injected Settings

Use JwtModule.forRootAsync(...) when your JWT settings must come from another provider and still need to resolve into the standard module contract.

Async registration exports the same JWT provider surface as the synchronous path, including RefreshTokenService; resolving that service still requires refreshToken options to be configured.

forRootAsync(...) resolves one module-level JwtVerifierOptions object from the providers listed in inject. It does not receive per-request state. For tenant-specific secrets or identity providers, keep tenant lookup in your application auth layer and use token metadata such as kid with configured keys[], jwksUri, or secretOrKeyProvider to select verification material during token verification.

import { Module, type Token } from '@fluojs/core';
import { JwtModule } from '@fluojs/jwt';

const JWT_SETTINGS = Symbol('jwt-settings');

@Module({
  imports: [
    JwtModule.forRootAsync({
      inject: [JWT_SETTINGS],
      useFactory: async (settings) => ({
        accessTokenTtlSeconds: 900,
        algorithms: ['HS256'],
        audience: 'my-app',
        issuer: settings.issuer,
        secret: settings.secret,
      }),
    }),
  ],
  providers: [
    {
      provide: JWT_SETTINGS as Token<{ issuer: string; secret: string }>,
      useValue: {
        issuer: 'my-api',
        secret: 'your-secure-secret',
      },
    },
  ],
})
export class AuthModule {}

Sign and Verify Tokens

Inject DefaultJwtSigner to issue tokens and DefaultJwtVerifier to validate them.

import { DefaultJwtSigner, DefaultJwtVerifier } from '@fluojs/jwt';

// Sign
const token = await signer.signAccessToken({
  sub: 'user-123',
  roles: ['admin'],
  scopes: ['read:profile'],
});

// Verify
const principal = await verifier.verifyAccessToken(token);
// principal: { subject: 'user-123', roles: ['admin'], scopes: ['read:profile'], ... }

When you use JwtService.sign(payload, { expiresIn }), the per-call expiresIn override always wins over any pre-existing payload.exp value so token lifetime stays deterministic at the call site. expiresIn accepts a non-negative number of seconds or short duration strings such as 60s, 15m, 1h, or 7d. Numeric seconds preserve fractional JWT NumericDate precision; string durations remain whole-second literals.

Common Patterns

Asymmetric Signing (RS256/ES256)

Use public/private key pairs for enhanced security across distributed systems.

const signer = new DefaultJwtSigner({
  algorithms: ['RS256'],
  privateKey: '...PEM...',
});

const verifier = new DefaultJwtVerifier({
  algorithms: ['RS256'],
  publicKey: '...PEM...',
});

Principal Normalization

@fluojs/jwt automatically unifies scope (string) and scopes (array) claims into a single scopes: string[] property in the JwtPrincipal, ensuring consistent behavior for authorization guards.

Remote JWKS verification

When verification keys come from a remote JWKS endpoint, keep the fetch path bounded so auth traffic cannot hang on a slow or stalled identity provider.

const verifier = new DefaultJwtVerifier({
  algorithms: ['RS256'],
  jwksRequestTimeoutMs: 5_000,
  jwksUri: 'https://issuer.example.com/.well-known/jwks.json',
});

jwksRequestTimeoutMs defaults to 5_000 and aborts the outbound JWKS fetch once that budget is exceeded.

JWKS keys are cached for jwksCacheTtl milliseconds (600_000 by default) and the in-memory cache is bounded by jwksCacheMaxEntries (100 by default). Expired entries are pruned before lookups, the oldest retained key is evicted when the bound is exceeded, and JwtModule calls the managed DefaultJwtVerifier shutdown hook so retained remote key material is cleared during module teardown. Manually constructed verifiers or clients should still call JwksClient.dispose() / DefaultJwtVerifier.dispose() during manual shutdown or identity-provider reconfiguration. A jwksCacheTtl of 0 disables key retention while still using bounded fetch timeouts.

JwtService.verify(token, options) applies per-call algorithm and claim-policy overrides (issuer, audience, clockSkewSeconds, maxAge, requireExp) without rebuilding the underlying JWKS client or static key-resolution cache. Per-call verification does not replace configured key sources such as jwksUri, keys[], publicKey, secret, or secretOrKeyProvider.

When multiple compatible keys are configured, kid disambiguates the verification key. A single compatible static key can verify tokens without kid; JWKS-backed verification relies on the remote key set and its cache policy.

For multi-tenant systems, prefer putting a tenant-specific kid in issued token headers and configuring compatible key sources up front. secretOrKeyProvider is called with the decoded token header only, so request headers, route params, or other request-context tenant hints must be handled by application-level strategy/guard code before calling the JWT verifier.

Refresh tokens

RefreshTokenService uses a dedicated HMAC refresh-token path. Configure refreshToken.secret separately from access-token signing keys. Rotation can use RefreshTokenStore.rotate(...) to atomically mark the current token as consumed and persist the replacement token in the same durable store operation, so a successful rotation never consumes the old token without a stored successor. Stores that only implement the older atomic consume(...) hook remain supported, but durable replacement persistence depends on the store-owned rotate(...) operation.

Configuration Guardrails

JWT signing and verification require at least one supported algorithm in algorithms. The built-in signer supports HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, and ES512; configuration with an empty algorithm list fails fast instead of issuing or accepting ambiguous tokens.

Access-token TTL must also be a positive finite number. When accessTokenTtlSeconds is omitted, DefaultJwtSigner uses the documented 3600 second default. Fractional seconds are preserved in the JWT NumericDate exp claim; when the option is provided as 0, a negative number, or a non-finite value, signing fails with JwtConfigurationError before a token is issued.

Verification fails closed on malformed time policy. exp, nbf, and iat claims that participate in verification must be finite JWT NumericDate numbers, and clockSkewSeconds must be a non-negative finite number. Non-finite values are rejected instead of extending expiration, not-before, or age checks. A token is expired when verifier time reaches its exp NumericDate; equality is treated as expired unless positive clock skew still covers the boundary.

The root @fluojs/jwt import surface is safe to load before selecting a runtime-specific authentication path: Node.js node:crypto primitives are loaded lazily only when signing, verification, JWKS key parsing, or refresh-token id generation actually executes. This preserves the existing public exports while avoiding Node-specific crypto work at module import time.

Public API Overview

Core Classes

• JwtModule: The main entry point for DI registration.
• DefaultJwtSigner: Handles token issuance with default claim filling.
• DefaultJwtVerifier: Handles token validation and normalization.
• JwtService: A convenience facade combining signing and verification.
• JwksClient: Fetches and caches remote JWKS keys with bounded request timeouts.
• RefreshTokenService: Issues, rotates, and revokes refresh tokens when refreshToken options are configured.

Types

• JwtPrincipal: The normalized identity object (subject, roles, scopes, claims).
• JwtVerifierOptions: Configuration for algorithms, keys, and validation policy.
• SignOptions and VerifyOptions: Per-call signing and verification overrides.
• JwtClaims, JwtSigner, JwtVerifier, JwtKeyEntry, JwtAlgorithm: Public signing and verification contracts.
• RefreshTokenOptions, RefreshTokenStore, RefreshTokenRecord, RefreshTokenConsumeInput, RefreshTokenRotateInput, and RefreshTokenConsumeResult: Refresh-token storage, rotation, and replay-detection contracts.

Errors and diagnostics

• JwtVerificationError, JwtInvalidTokenError, JwtExpiredTokenError, JwtConfigurationError: Typed JWT failures.
• createJwtPlatformStatusSnapshot(...) and createJwtPlatformDiagnosticIssues(...): Status and diagnostic helpers.
• JWT_OPTIONS, HMAC_HASH, ASYMMETRIC_HASH: Exported tokens/constants used by the module and verification layer.

Deprecated compatibility helpers

• normalizeRefreshTokenOptions(...): Retained only for root-import compatibility with existing callers. Prefer JwtModule.forRoot(...) / JwtModule.forRootAsync(...) plus RefreshTokenService instead of calling package normalization internals.

Related Packages

• @fluojs/passport: The auth execution layer that uses this core for guards and strategies.
• @fluojs/config: Recommended for managing secrets and JWT options across environments.

Example Sources

• packages/jwt/src/module.test.ts: Module registration and DI patterns.
• packages/jwt/src/signing/signer.test.ts: Token signing examples.
• examples/auth-jwt-passport/src/auth/auth.service.ts: Real-world token issuance.