@fluojs/jwt

@fluojs/jwt

English 한국어

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. These dispose methods clear retained JWKS key material and abort active JWKS fetches. 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: after a successful consume, the service saves the replacement through save(...), but only store-owned rotate(...) makes those two writes atomic.

When reuse is detected, stores that implement the optional revokeByFamily(family) capability revoke only the compromised token family. Existing stores remain source-compatible: if revokeByFamily(...) is absent, RefreshTokenService conservatively falls back to revokeBySubject(subject), which also revokes the subject's independent refresh-token families. Implement revokeByFamily(...) in production stores when separate device or session families must remain active after another family is compromised.

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.

Node runtime 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.

Lazy loading is an import-time safety property only. It does not make signing or verification portable across runtimes. Once a signing, verification, JWKS key-parsing, or refresh-token id-generation path executes, that path requires a Node.js-compatible node:crypto implementation (createHmac, createSign, createVerify, createPublicKey, timingSafeEqual, randomUUID). Bun satisfies this through its Node compatibility layer; Deno and Cloudflare Workers do not provide a compatible node:crypto surface for these operations and are not supported JWT signing/verification runtimes. Treat @fluojs/jwt as a Node-runtime auth package: keep import-time loading lazy, but do not assume the package can sign or verify tokens on non-Node runtimes without a compatible node:crypto polyfill.

decode() trust boundary

JwtService.decode(token) reads the JWT payload segment without verifying the signature, alg, exp, nbf, iss, aud, or any other claim. The returned object is unverified input and must never be used for authorization decisions, identity resolution, or any code path that grants access. Use JwtService.verify(token, options) (or DefaultJwtVerifier.verifyAccessToken(token)) first, and read identity from the normalized JwtPrincipal that verification returns.

decode() exists for diagnostics and non-authoritative inspection only, such as reading token metadata for logging or selecting a verification key before calling verify(). Any claim value read from decode() — including sub, roles, scopes, iss, aud, and exp — must be treated as attacker-controlled until verify() succeeds. Never branch on decode() output to allow or deny a request, and never expose decoded claims to downstream code as if they were verified.

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, family-scoped revocation, and replay-detection contracts. RefreshTokenStore.revokeByFamily(...) is optional for compatibility with subject-revocation stores.
• JwtPlatformStatusSnapshot and JwtStatusAdapterInput: Status snapshot and adapter input types exported with the platform diagnostic helpers.

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.