@fluojs/jwt 1.0.0-beta.1 → 1.0.0-beta.2

package/README.ko.md

@@ -10,6 +10,7 @@ HTTP에 독립적인 JWT 토큰 코어로, 액세스 토큰의 서명 및 검증
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [일반적인 패턴](#일반적인-패턴)
+- [설정 가드레일](#설정-가드레일)
 - [공개 API 개요](#공개-api-개요)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -56,6 +57,8 @@ export class AuthModule {}
 
 JWT 설정이 다른 provider에서 와야 한다면, `JwtModule.forRootAsync(...)`를 사용해도 표준 module contract 안에서 안전하게 등록할 수 있습니다.
 
+비동기 등록도 동기 경로와 동일한 JWT provider surface를 export하며, 여기에는 `RefreshTokenService`가 포함됩니다. 단, 이 서비스를 실제로 resolve하려면 `refreshToken` 옵션이 구성되어 있어야 합니다.
+
 ```typescript
 import { Module, type Token } from '@fluojs/core';
 import { JwtModule } from '@fluojs/jwt';
@@ -145,6 +148,14 @@ const verifier = new DefaultJwtVerifier({
 
 `jwksRequestTimeoutMs`의 기본값은 `5_000`이며, 예산을 넘기면 진행 중인 JWKS fetch를 abort합니다.
 
+`JwtService.verify(token, options)`는 호출 단위의 알고리즘/클레임 정책 재정의(`issuer`, `audience`, `clockSkewSeconds`, `maxAge`, `requireExp`)를 적용하더라도, 내부 JWKS client나 정적 key-resolution cache를 다시 만들지 않습니다. 호출 단위 검증은 `jwksUri`, `keys[]`, `publicKey`, `secret`, `secretOrKeyProvider` 같은 구성된 key source 자체를 교체하지는 않습니다.
+
+## 설정 가드레일
+
+JWT 서명과 검증에는 `algorithms`에 지원되는 알고리즘이 하나 이상 필요합니다. 기본 signer는 `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`를 지원하며, 빈 알고리즘 목록은 모호한 토큰을 발행하거나 수락하지 않도록 즉시 실패합니다.
+
+액세스 토큰 TTL도 양의 유한 숫자여야 합니다. `accessTokenTtlSeconds`를 생략하면 `DefaultJwtSigner`는 문서화된 기본값인 `3600`초를 사용합니다. 소수 초는 JWT NumericDate `exp` 클레임에 그대로 보존됩니다. `0`, 음수 또는 유한하지 않은 값이 제공되면 토큰을 발행하기 전에 `JwtConfigurationError`로 실패합니다.
+
 ## 공개 API 개요
 
 ### 주요 클래스

package/README.md

@@ -10,6 +10,7 @@ HTTP-agnostic JWT token core that handles signing access tokens and verifying th
 - [When to use](#when-to-use)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
+- [Configuration Guardrails](#configuration-guardrails)
 - [Public API](#public-api)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -56,6 +57,8 @@ export class AuthModule {}
 
 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.
+
 ```typescript
 import { Module, type Token } from '@fluojs/core';
 import { JwtModule } from '@fluojs/jwt';
@@ -145,6 +148,14 @@ const verifier = new DefaultJwtVerifier({
 
 `jwksRequestTimeoutMs` defaults to `5_000` and aborts the outbound JWKS fetch once that budget is exceeded.
 
+`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`.
+
+## 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.
+
 ## Public API Overview
 
 ### Core Classes

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAiC,MAAM,cAAc,CAAC;AAQhH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIrD,KAAK,UAAU,GAAG,WAAW,CAAC;AAmF9B;;GAEG;AACH,qBAAa,SAAS;IACpB,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;IAQvD,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,GAAG,UAAU;IAShF,OAAO,CAAC,MAAM,CAAC,YAAY;CAgB5B"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAiC,MAAM,cAAc,CAAC;AAOhH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIrD,KAAK,UAAU,GAAG,WAAW,CAAC;AAyE9B;;GAEG;AACH,qBAAa,SAAS;IACpB,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;IAQvD,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,GAAG,UAAU;IAShF,OAAO,CAAC,MAAM,CAAC,YAAY;CAgB5B"}

package/dist/module.js

@@ -6,7 +6,6 @@ function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.descrip
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { Inject } from '@fluojs/core';
 import { defineModuleMetadata } from '@fluojs/core/internal';
-import { RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
 import { JwtConfigurationError } from './errors.js';
 import { normalizeRefreshTokenOptions, RefreshTokenService } from './refresh/refresh-token.js';
 import { JwtService } from './service.js';
@@ -21,26 +20,16 @@ function resolveRefreshTokenOptions(value) {
 let _AsyncRefreshTokenSer;
 class AsyncRefreshTokenServiceRegistrar {
   static {
-    [_AsyncRefreshTokenSer, _initClass] = _applyDecs(this, [Inject(JWT_OPTIONS, DefaultJwtSigner, DefaultJwtVerifier, RUNTIME_CONTAINER)], []).c;
+    [_AsyncRefreshTokenSer, _initClass] = _applyDecs(this, [Inject(JWT_OPTIONS, DefaultJwtSigner, DefaultJwtVerifier)], []).c;
   }
-  registered = false;
-  constructor(options, signer, verifier, container) {
+  constructor(options, _signer, _verifier) {
     this.options = options;
-    this.signer = signer;
-    this.verifier = verifier;
-    this.container = container;
   }
   onModuleInit() {
-    if (!this.options.refreshToken || this.registered) {
+    if (!this.options.refreshToken) {
       return;
     }
-    const refreshTokenOptions = resolveRefreshTokenOptions(this.options);
-    this.container.register({
-      provide: RefreshTokenService,
-      scope: 'transient',
-      useFactory: () => new RefreshTokenService(refreshTokenOptions, this.signer, this.verifier)
-    });
-    this.registered = true;
+    resolveRefreshTokenOptions(this.options);
   }
   static {
     _initClass();
@@ -49,7 +38,7 @@ class AsyncRefreshTokenServiceRegistrar {
 function createJwtModuleProviders(optionsProvider, includeRefreshTokenService, refreshTokenServiceScope, deferRefreshTokenServiceRegistration = false) {
   const providers = [optionsProvider, DefaultJwtVerifier, DefaultJwtSigner, JwtService];
   if (includeRefreshTokenService) {
-    providers.push(deferRefreshTokenServiceRegistration ? _AsyncRefreshTokenSer : {
+    providers.push({
       inject: [JWT_OPTIONS, DefaultJwtSigner, DefaultJwtVerifier],
       provide: RefreshTokenService,
       scope: refreshTokenServiceScope,
@@ -59,6 +48,9 @@ function createJwtModuleProviders(optionsProvider, includeRefreshTokenService, r
         return new RefreshTokenService(refreshTokenOptions, signer, verifier);
       }
     });
+    if (deferRefreshTokenServiceRegistration) {
+      providers.push(_AsyncRefreshTokenSer);
+    }
   }
   return providers;
 }
@@ -80,7 +72,7 @@ export class JwtModule {
       provide: JWT_OPTIONS,
       scope: 'singleton',
       useFactory: options.useFactory
-    }, true, false, 'transient', true);
+    }, true, true, 'transient', true);
   }
   static createModule(optionsProvider, includeRefreshTokenProvider, includeRefreshTokenExport, refreshTokenServiceScope, deferRefreshTokenServiceRegistration = false) {
     class JwtRuntimeModule {}

package/dist/refresh/refresh-token.d.ts

@@ -1,5 +1,8 @@
 import type { DefaultJwtSigner } from '../signing/signer.js';
 import type { DefaultJwtVerifier } from '../signing/verifier.js';
+/**
+ * Describes the refresh token store contract.
+ */
 export interface RefreshTokenStore {
     save(token: RefreshTokenRecord): Promise<void>;
     find(tokenId: string): Promise<RefreshTokenRecord | undefined>;
@@ -7,13 +10,22 @@ export interface RefreshTokenStore {
     revokeBySubject(subject: string): Promise<void>;
     consume?(input: RefreshTokenConsumeInput): Promise<RefreshTokenConsumeResult>;
 }
+/**
+ * Describes the refresh token consume input contract.
+ */
 export interface RefreshTokenConsumeInput {
     tokenId: string;
     subject: string;
     family: string;
     now: Date;
 }
+/**
+ * Defines the refresh token consume result type.
+ */
 export type RefreshTokenConsumeResult = 'consumed' | 'already_used' | 'expired' | 'not_found' | 'mismatch' | 'invalid';
+/**
+ * Describes the refresh token record contract.
+ */
 export interface RefreshTokenRecord {
     id: string;
     subject: string;
@@ -22,6 +34,9 @@ export interface RefreshTokenRecord {
     used: boolean;
     createdAt: Date;
 }
+/**
+ * Describes the refresh token options contract.
+ */
 export interface RefreshTokenOptions {
     secret: string;
     expiresInSeconds: number;
@@ -29,7 +44,16 @@ export interface RefreshTokenOptions {
     rotation: boolean;
     store: RefreshTokenStore;
 }
+/**
+ * Normalize refresh token options.
+ *
+ * @param options The options.
+ * @returns The normalize refresh token options result.
+ */
 export declare function normalizeRefreshTokenOptions(options: RefreshTokenOptions | undefined): RefreshTokenOptions;
+/**
+ * Represents the refresh token service.
+ */
 export declare class RefreshTokenService {
     private readonly signer;
     private readonly verifier;

package/dist/refresh/refresh-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refresh-token.d.ts","sourceRoot":"","sources":["../../src/refresh/refresh-token.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAC/D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GAAG,mBAAmB,CA2B1G;AAQD,qBAAa,mBAAmB;IAK5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAG5C,OAAO,EAAE,mBAAmB,EACX,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,kBAAkB;IAKzC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMnD,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IA+DhG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAI3C,2BAA2B;YA6B3B,mBAAmB;CA4BlC"}
+{"version":3,"file":"refresh-token.d.ts","sourceRoot":"","sources":["../../src/refresh/refresh-token.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAC/D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC/E;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GAAG,mBAAmB,CA2B1G;AAQD;;GAEG;AACH,qBAAa,mBAAmB;IAK5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAG5C,OAAO,EAAE,mBAAmB,EACX,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,kBAAkB;IAKzC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMnD,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IA+DhG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAI3C,2BAA2B;YA6B3B,mBAAmB;CA4BlC"}

package/dist/refresh/refresh-token.js

@@ -1,5 +1,32 @@
 import { randomUUID } from 'node:crypto';
 import { JwtConfigurationError, JwtExpiredTokenError, JwtInvalidTokenError } from '../errors.js';
+
+/**
+ * Describes the refresh token store contract.
+ */
+
+/**
+ * Describes the refresh token consume input contract.
+ */
+
+/**
+ * Defines the refresh token consume result type.
+ */
+
+/**
+ * Describes the refresh token record contract.
+ */
+
+/**
+ * Describes the refresh token options contract.
+ */
+
+/**
+ * Normalize refresh token options.
+ *
+ * @param options The options.
+ * @returns The normalize refresh token options result.
+ */
 export function normalizeRefreshTokenOptions(options) {
   if (!options) {
     throw new JwtConfigurationError('JWT refresh token options are not configured.');
@@ -20,6 +47,9 @@ export function normalizeRefreshTokenOptions(options) {
     ...options
   };
 }
+/**
+ * Represents the refresh token service.
+ */
 export class RefreshTokenService {
   options;
   constructor(options, signer, verifier) {

package/dist/service.d.ts

@@ -92,10 +92,9 @@ export interface VerifyOptions {
  * patterns.
  */
 export declare class JwtService {
-    private readonly options;
     private readonly signer;
     private readonly verifier;
-    constructor(options: JwtVerifierOptions, signer: DefaultJwtSigner, verifier: DefaultJwtVerifier);
+    constructor(_options: JwtVerifierOptions, signer: DefaultJwtSigner, verifier: DefaultJwtVerifier);
     /**
      * Signs a JWT access token from arbitrary claim payload plus optional claim overrides.
      *

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAa,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAe,MAAM,uBAAuB,CAAC;AAExE,KAAK,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAoD1C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,MAAM,GAAG,YAAY,EAAE,CAAC;IAChD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBACa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,kBAAkB;IAG/C;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBnE;;;;;;;;;;;;;;;;;;OAkBG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC;IAiB7E;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAmB/B"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAa,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAe,MAAM,uBAAuB,CAAC;AAExE,KAAK,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAoD1C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,MAAM,GAAG,YAAY,EAAE,CAAC;IAChD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBACa,UAAU;IAGnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFzB,QAAQ,EAAE,kBAAkB,EACX,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,kBAAkB;IAG/C;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBnE;;;;;;;;;;;;;;;;;;OAkBG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ7E;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAmB/B"}

package/dist/service.js

@@ -74,8 +74,7 @@ class JwtService {
   static {
     [_JwtService, _initClass] = _applyDecs(this, [Inject(JWT_OPTIONS, DefaultJwtSigner, DefaultJwtVerifier)], []).c;
   }
-  constructor(options, signer, verifier) {
-    this.options = options;
+  constructor(_options, signer, verifier) {
     this.signer = signer;
     this.verifier = verifier;
   }
@@ -130,16 +129,7 @@ class JwtService {
    * @throws {JwtConfigurationError} When the active verifier configuration cannot validate the token.
    */
   async verify(token, options) {
-    const verifier = options ? new DefaultJwtVerifier({
-      ...this.options,
-      algorithms: options.algorithms ?? this.options.algorithms,
-      audience: options.audience ?? this.options.audience,
-      clockSkewSeconds: options.clockSkewSeconds ?? this.options.clockSkewSeconds,
-      issuer: options.issuer ?? this.options.issuer,
-      maxAge: options.maxAge ?? this.options.maxAge,
-      requireExp: options.requireExp ?? this.options.requireExp
-    }) : this.verifier;
-    const principal = await verifier.verifyAccessToken(token);
+    const principal = options ? await this.verifier.verifyAccessTokenWithOverrides(token, options) : await this.verifier.verifyAccessToken(token);
     return principal.claims;
   }
 

package/dist/signing/jwks.d.ts

@@ -1,4 +1,7 @@
 import { type KeyObject } from 'node:crypto';
+/**
+ * Represents the jwks client.
+ */
 export declare class JwksClient {
     private readonly uri;
     private readonly cacheTtl;

package/dist/signing/jwks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../../src/signing/jwks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAa9D,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IALnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4D;gBAG/D,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAgB,EAC1B,gBAAgB,GAAE,MAAc;IAGnD,OAAO,CAAC,YAAY;IAId,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;YA+BtC,SAAS;CAqCxB"}
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../../src/signing/jwks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAa9D;;GAEG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IALnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4D;gBAG/D,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAgB,EAC1B,gBAAgB,GAAE,MAAc;IAGnD,OAAO,CAAC,YAAY;IAId,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;YA+BtC,SAAS;CAqCxB"}

package/dist/signing/jwks.js

@@ -1,5 +1,8 @@
 import { createPublicKey } from 'node:crypto';
 import { JwtConfigurationError, JwtInvalidTokenError } from '../errors.js';
+/**
+ * Represents the jwks client.
+ */
 export class JwksClient {
   cache = new Map();
   constructor(uri, cacheTtl = 600_000, requestTimeoutMs = 5_000) {

package/dist/signing/signer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signing/signer.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,SAAS,EAAe,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAyB5F;;GAEG;AACH,qBACa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;gBAEtB,OAAO,EAAE,kBAAkB;IAMlD,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1D,OAAO,CAAC,4BAA4B;YAYtB,SAAS;CAkFxB"}
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signing/signer.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,SAAS,EAAe,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA0D5F;;GAEG;AACH,qBACa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;gBAEtB,OAAO,EAAE,kBAAkB;IAOlD,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1D,OAAO,CAAC,4BAA4B;YAYtB,SAAS;CAkFxB"}

package/dist/signing/signer.js

@@ -17,11 +17,34 @@ function resolveSigningKeyEntry(options, algorithm) {
   if (!Array.isArray(keys) || keys.length === 0) {
     return undefined;
   }
-  if (algorithm in HMAC_HASH) {
+  if (hasOwnAlgorithmMapping(HMAC_HASH, algorithm)) {
     return keys.find(entry => typeof entry.secret === 'string' && entry.secret.length > 0);
   }
   return keys.find(entry => entry.privateKey !== undefined);
 }
+function hasOwnAlgorithmMapping(mappings, algorithm) {
+  return typeof algorithm === 'string' && Object.hasOwn(mappings, algorithm);
+}
+function isSupportedSigningAlgorithm(algorithm) {
+  return hasOwnAlgorithmMapping(HMAC_HASH, algorithm) || hasOwnAlgorithmMapping(ASYMMETRIC_HASH, algorithm);
+}
+function assertSigningAlgorithms(algorithms) {
+  if (!Array.isArray(algorithms) || algorithms.length === 0) {
+    throw new JwtConfigurationError('JWT signer requires at least one allowed JWT algorithm.');
+  }
+  for (const algorithm of algorithms) {
+    if (!isSupportedSigningAlgorithm(algorithm)) {
+      throw new JwtConfigurationError(`JWT signer received unsupported JWT algorithm "${String(algorithm)}".`);
+    }
+  }
+}
+function resolveAccessTokenTtlSeconds(options) {
+  const ttl = options.accessTokenTtlSeconds ?? 3600;
+  if (!Number.isFinite(ttl) || ttl <= 0) {
+    throw new JwtConfigurationError('JWT accessTokenTtlSeconds must be a positive finite number.');
+  }
+  return ttl;
+}
 
 /**
  * Issues access and refresh tokens with the configured signing keys and algorithms.
@@ -34,7 +57,8 @@ class DefaultJwtSigner {
   refreshAlgorithms;
   constructor(options) {
     this.options = options;
-    this.refreshAlgorithms = this.options.algorithms.filter(algorithm => algorithm in HMAC_HASH);
+    assertSigningAlgorithms(options.algorithms);
+    this.refreshAlgorithms = this.options.algorithms.filter(algorithm => hasOwnAlgorithmMapping(HMAC_HASH, algorithm));
   }
   async signAccessToken(claims) {
     return this.signToken(claims, this.options, false);
@@ -56,9 +80,9 @@ class DefaultJwtSigner {
   async signToken(claims, options, hmacOnly) {
     const algorithm = options.algorithms.find(alg => {
       if (hmacOnly) {
-        return alg in HMAC_HASH;
+        return hasOwnAlgorithmMapping(HMAC_HASH, alg);
       }
-      return alg in HMAC_HASH || alg in ASYMMETRIC_HASH;
+      return isSupportedSigningAlgorithm(alg);
     });
     if (!algorithm) {
       if (hmacOnly) {
@@ -66,9 +90,9 @@ class DefaultJwtSigner {
       }
       throw new JwtConfigurationError('JWT signer requires at least one supported algorithm (HS256/HS384/HS512/RS256/RS384/RS512/ES256/ES384/ES512) in the allowed algorithms list.');
     }
-    const isAsymmetric = algorithm in ASYMMETRIC_HASH;
+    const isAsymmetric = hasOwnAlgorithmMapping(ASYMMETRIC_HASH, algorithm);
     const now = Math.floor(Date.now() / 1000);
-    const ttl = options.accessTokenTtlSeconds ?? 3600;
+    const ttl = resolveAccessTokenTtlSeconds(options);
     const payload = {
       ...claims,
       aud: claims.aud ?? options.audience,

package/dist/signing/verifier-internal.d.ts

@@ -0,0 +1,14 @@
+import type { JwtPrincipal, JwtVerifierOptions } from '../types.js';
+import { DefaultJwtVerifier } from './verifier.js';
+type AccessTokenVerificationOverrides = Pick<JwtVerifierOptions, 'algorithms' | 'audience' | 'clockSkewSeconds' | 'issuer' | 'maxAge' | 'requireExp'>;
+/**
+ * Applies supported per-call access-token overrides through the verifier's public API.
+ *
+ * @param verifier Configured verifier whose shared key-resolution state should be reused.
+ * @param token Compact JWT string to verify.
+ * @param overrides Per-call algorithm and claim-policy overrides.
+ * @returns The normalized principal for the verified access token.
+ */
+export declare function verifyAccessTokenWithOverrides(verifier: DefaultJwtVerifier, token: string, overrides: Partial<AccessTokenVerificationOverrides>): Promise<JwtPrincipal>;
+export {};
+//# sourceMappingURL=verifier-internal.d.ts.map

package/dist/signing/verifier-internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier-internal.d.ts","sourceRoot":"","sources":["../../src/signing/verifier-internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,KAAK,gCAAgC,GAAG,IAAI,CAC1C,kBAAkB,EAClB,YAAY,GAAG,UAAU,GAAG,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CACpF,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,CAAC,gCAAgC,CAAC,GACnD,OAAO,CAAC,YAAY,CAAC,CAEvB"}

package/dist/signing/verifier-internal.js

@@ -0,0 +1,11 @@
+/**
+ * Applies supported per-call access-token overrides through the verifier's public API.
+ *
+ * @param verifier Configured verifier whose shared key-resolution state should be reused.
+ * @param token Compact JWT string to verify.
+ * @param overrides Per-call algorithm and claim-policy overrides.
+ * @returns The normalized principal for the verified access token.
+ */
+export function verifyAccessTokenWithOverrides(verifier, token, overrides) {
+  return verifier.verifyAccessTokenWithOverrides(token, overrides);
+}

package/dist/signing/verifier.d.ts

@@ -11,6 +11,7 @@ export declare const HMAC_HASH: Partial<Record<JwtAlgorithm, string>>;
  * Maps supported asymmetric JWT algorithms to their Node.js hash names.
  */
 export declare const ASYMMETRIC_HASH: Partial<Record<JwtAlgorithm, string>>;
+type AccessTokenVerificationOverrides = Pick<JwtVerifierOptions, 'algorithms' | 'audience' | 'clockSkewSeconds' | 'issuer' | 'maxAge' | 'requireExp'>;
 /**
  * Verifies JWT access and refresh tokens against the configured key sources.
  */
@@ -22,6 +23,18 @@ export declare class DefaultJwtVerifier {
     private readonly refreshVerificationOptions;
     constructor(options: JwtVerifierOptions);
     verifyAccessToken(token: string): Promise<JwtPrincipal>;
+    /**
+     * Verifies a JWT access token with per-call claim-policy overrides while reusing configured key sources.
+     *
+     * @remarks
+     * This override path is intentionally limited to algorithm and claim-validation policy.
+     * It does not replace configured JWKS/static keys or the shared `secretOrKeyProvider`.
+     *
+     * @param token Compact JWT string to verify.
+     * @param overrides Per-call algorithm and claim-policy overrides layered on top of module defaults.
+     * @returns The normalized principal for the verified access token.
+     */
+    verifyAccessTokenWithOverrides(token: string, overrides: Partial<AccessTokenVerificationOverrides>): Promise<JwtPrincipal>;
     verifyRefreshToken(token: string): Promise<JwtPrincipal>;
     private createRefreshVerificationOptions;
     private verifyToken;
@@ -35,4 +48,5 @@ export declare class DefaultJwtVerifier {
     private validateIssuerAndAudience;
     private resolveJwksPublicKey;
 }
+export {};
 //# sourceMappingURL=verifier.d.ts.map

package/dist/signing/verifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/signing/verifier.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,WAAW,eAAiC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAI3D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAOjE,CAAC;AAuMF;;GAEG;AACH,qBACa,kBAAkB;IAMjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAqB;IAC/D,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAiC;gBAE/C,OAAO,EAAE,kBAAkB;IAYlD,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIvD,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ9D,OAAO,CAAC,gCAAgC;YAsB1B,WAAW;IA+BzB,OAAO,CAAC,kBAAkB;YAUZ,oBAAoB;YAgBpB,wBAAwB;YAsBxB,8BAA8B;YAsB9B,kBAAkB;IAWhC,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,yBAAyB;YAiBnB,oBAAoB;CAOnC"}
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/signing/verifier.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAG1G;;GAEG;AACH,eAAO,MAAM,WAAW,eAAiC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAI3D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAOjE,CAAC;AAiCF,KAAK,gCAAgC,GAAG,IAAI,CAC1C,kBAAkB,EAClB,YAAY,GAAG,UAAU,GAAG,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CACpF,CAAC;AA+LF;;GAEG;AACH,qBACa,kBAAkB;IAMjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAqB;IAC/D,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAiC;gBAE/C,OAAO,EAAE,kBAAkB;IAalD,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI7D;;;;;;;;;;OAUG;IACG,8BAA8B,CAClC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,CAAC,gCAAgC,CAAC,GACnD,OAAO,CAAC,YAAY,CAAC;IAqBlB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ9D,OAAO,CAAC,gCAAgC;YAsB1B,WAAW;IA+BzB,OAAO,CAAC,kBAAkB;YAUZ,oBAAoB;YAgBpB,wBAAwB;YAsBxB,8BAA8B;YAsB9B,kBAAkB;IAWhC,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,yBAAyB;YAiBnB,oBAAoB;CAOnC"}

package/dist/signing/verifier.js

@@ -7,8 +7,9 @@ function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side
 import { createHmac, createVerify, timingSafeEqual } from 'node:crypto';
 import { Inject } from '@fluojs/core';
 import { JwtConfigurationError, JwtExpiredTokenError, JwtInvalidTokenError } from '../errors.js';
-import { JwksClient } from './jwks.js';
 import { normalizeRefreshTokenOptions } from '../refresh/refresh-token.js';
+import { JwksClient } from './jwks.js';
+
 /**
  * Provides the resolved JWT verifier options through dependency injection.
  */
@@ -34,8 +35,24 @@ export const ASYMMETRIC_HASH = {
   ES384: 'sha384',
   ES512: 'sha512'
 };
+function hasOwnAlgorithmMapping(mappings, alg) {
+  return typeof alg === 'string' && Object.hasOwn(mappings, alg);
+}
+function isSupportedAlgorithm(alg) {
+  return hasOwnAlgorithmMapping(HMAC_HASH, alg) || hasOwnAlgorithmMapping(ASYMMETRIC_HASH, alg);
+}
+function assertJwtAlgorithms(algorithms, context) {
+  if (!Array.isArray(algorithms) || algorithms.length === 0) {
+    throw new JwtConfigurationError(`${context} requires at least one allowed JWT algorithm.`);
+  }
+  for (const algorithm of algorithms) {
+    if (!isSupportedAlgorithm(algorithm)) {
+      throw new JwtConfigurationError(`${context} received unsupported JWT algorithm "${String(algorithm)}".`);
+    }
+  }
+}
 function isAllowedAlgorithm(alg, allowed) {
-  return typeof alg === 'string' && allowed.includes(alg) && (alg in HMAC_HASH || alg in ASYMMETRIC_HASH);
+  return isSupportedAlgorithm(alg) && allowed.includes(alg);
 }
 function isFiniteNumericDate(value) {
   return typeof value === 'number' && Number.isFinite(value);
@@ -175,6 +192,7 @@ class DefaultJwtVerifier {
   refreshVerificationOptions;
   constructor(options) {
     this.options = options;
+    assertJwtAlgorithms(options.algorithms, 'JWT verifier');
     this.jwksClient = options.jwksUri ? new JwksClient(options.jwksUri, options.jwksCacheTtl, options.jwksRequestTimeoutMs) : undefined;
     this.keyResolutionState = createKeyResolutionState(options.keys);
     this.refreshVerificationOptions = options.refreshToken ? this.createRefreshVerificationOptions(normalizeRefreshTokenOptions(options.refreshToken)) : undefined;
@@ -183,6 +201,31 @@ class DefaultJwtVerifier {
   async verifyAccessToken(token) {
     return this.verifyToken(token, this.options, this.keyResolutionState, this.jwksClient);
   }
+
+  /**
+   * Verifies a JWT access token with per-call claim-policy overrides while reusing configured key sources.
+   *
+   * @remarks
+   * This override path is intentionally limited to algorithm and claim-validation policy.
+   * It does not replace configured JWKS/static keys or the shared `secretOrKeyProvider`.
+   *
+   * @param token Compact JWT string to verify.
+   * @param overrides Per-call algorithm and claim-policy overrides layered on top of module defaults.
+   * @returns The normalized principal for the verified access token.
+   */
+  async verifyAccessTokenWithOverrides(token, overrides) {
+    const algorithms = overrides.algorithms ?? this.options.algorithms;
+    assertJwtAlgorithms(algorithms, 'JWT verifier');
+    return this.verifyToken(token, {
+      ...this.options,
+      algorithms,
+      audience: overrides.audience ?? this.options.audience,
+      clockSkewSeconds: overrides.clockSkewSeconds ?? this.options.clockSkewSeconds,
+      issuer: overrides.issuer ?? this.options.issuer,
+      maxAge: overrides.maxAge ?? this.options.maxAge,
+      requireExp: overrides.requireExp ?? this.options.requireExp
+    }, this.keyResolutionState, this.jwksClient);
+  }
   async verifyRefreshToken(token) {
     if (!this.refreshVerificationOptions) {
       throw new JwtConfigurationError('JWT refresh token options are not configured.');
@@ -190,7 +233,7 @@ class DefaultJwtVerifier {
     return this.verifyToken(token, this.refreshVerificationOptions, this.refreshKeyResolutionState, undefined);
   }
   createRefreshVerificationOptions(refreshToken) {
-    const algorithms = this.options.algorithms.filter(algorithm => algorithm in HMAC_HASH);
+    const algorithms = this.options.algorithms.filter(algorithm => hasOwnAlgorithmMapping(HMAC_HASH, algorithm));
     if (algorithms.length === 0) {
       throw new JwtConfigurationError('JWT refresh token verifier requires at least one HMAC algorithm (HS256/HS384/HS512) in the allowed algorithms list.');
     }
@@ -228,7 +271,7 @@ class DefaultJwtVerifier {
     return segments;
   }
   async verifyTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState, jwksClient) {
-    if (header.alg in HMAC_HASH) {
+    if (hasOwnAlgorithmMapping(HMAC_HASH, header.alg)) {
       await this.verifyHmacTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState);
       return;
     }

package/dist/status.d.ts

@@ -1,10 +1,16 @@
 import type { PlatformDiagnosticIssue, PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/**
+ * Describes the jwt platform status snapshot contract.
+ */
 export interface JwtPlatformStatusSnapshot {
     readiness: PlatformReadinessReport;
     health: PlatformHealthReport;
     ownership: PlatformSnapshot['ownership'];
     details: Record<string, unknown>;
 }
+/**
+ * Describes the jwt status adapter input contract.
+ */
 export interface JwtStatusAdapterInput {
     componentId?: string;
     readinessCritical?: boolean;
@@ -14,6 +20,18 @@ export interface JwtStatusAdapterInput {
     refreshTokenDependencyId?: string;
     signingKeySource?: 'shared-secret' | 'key-pair' | 'jwks' | 'key-provider';
 }
+/**
+ * Create jwt platform status snapshot.
+ *
+ * @param input The input.
+ * @returns The create jwt platform status snapshot result.
+ */
 export declare function createJwtPlatformStatusSnapshot(input: JwtStatusAdapterInput): JwtPlatformStatusSnapshot;
+/**
+ * Create jwt platform diagnostic issues.
+ *
+ * @param input The input.
+ * @returns The create jwt platform diagnostic issues result.
+ */
 export declare function createJwtPlatformDiagnosticIssues(input: JwtStatusAdapterInput): PlatformDiagnosticIssue[];
 //# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,gBAAgB,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,MAAM,GAAG,cAAc,CAAC;CAC3E;AAwCD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,qBAAqB,GAAG,yBAAyB,CA4CvG;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,EAAE,CAqBzG"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,gBAAgB,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,MAAM,GAAG,cAAc,CAAC;CAC3E;AAwCD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,qBAAqB,GAAG,yBAAyB,CA4CvG;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,EAAE,CAqBzG"}

package/dist/status.js

@@ -1,3 +1,11 @@
+/**
+ * Describes the jwt platform status snapshot contract.
+ */
+
+/**
+ * Describes the jwt status adapter input contract.
+ */
+
 function isRefreshTokenStoreReady(input) {
   if (!input.refreshTokenEnabled) {
     return true;
@@ -29,6 +37,13 @@ function createHealth(input) {
     status: 'degraded'
   };
 }
+
+/**
+ * Create jwt platform status snapshot.
+ *
+ * @param input The input.
+ * @returns The create jwt platform status snapshot result.
+ */
 export function createJwtPlatformStatusSnapshot(input) {
   const componentId = input.componentId ?? 'jwt.default';
   const refreshStoreReady = isRefreshTokenStoreReady(input);
@@ -65,6 +80,13 @@ export function createJwtPlatformStatusSnapshot(input) {
     readiness: createReadiness(input)
   };
 }
+
+/**
+ * Create jwt platform diagnostic issues.
+ *
+ * @param input The input.
+ * @returns The create jwt platform diagnostic issues result.
+ */
 export function createJwtPlatformDiagnosticIssues(input) {
   if (isRefreshTokenStoreReady(input)) {
     return [];

package/dist/types.d.ts

@@ -1,12 +1,21 @@
 import type { KeyObject } from 'node:crypto';
 import type { RefreshTokenOptions } from './refresh/refresh-token.js';
+/**
+ * Defines the jwt algorithm type.
+ */
 export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512';
+/**
+ * Describes the jwt key entry contract.
+ */
 export interface JwtKeyEntry {
     kid: string;
     secret?: string;
     privateKey?: string | KeyObject;
     publicKey?: string | KeyObject;
 }
+/**
+ * Describes the jwt verifier options contract.
+ */
 export interface JwtVerifierOptions {
     algorithms: JwtAlgorithm[];
     accessTokenTtlSeconds?: number;
@@ -29,6 +38,9 @@ export interface JwtVerifierOptions {
     publicKey?: string | KeyObject;
     refreshToken?: RefreshTokenOptions;
 }
+/**
+ * Describes the jwt claims contract.
+ */
 export interface JwtClaims extends Record<string, unknown> {
     aud?: string | string[];
     exp?: number;
@@ -39,6 +51,9 @@ export interface JwtClaims extends Record<string, unknown> {
     scopes?: string[];
     sub?: string;
 }
+/**
+ * Describes the jwt principal contract.
+ */
 export interface JwtPrincipal {
     subject: string;
     issuer?: string;
@@ -47,9 +62,15 @@ export interface JwtPrincipal {
     scopes?: string[];
     claims: Record<string, unknown>;
 }
+/**
+ * Describes the jwt verifier contract.
+ */
 export interface JwtVerifier {
     verifyAccessToken(token: string): Promise<JwtPrincipal>;
 }
+/**
+ * Describes the jwt signer contract.
+ */
 export interface JwtSigner {
     signAccessToken(claims: JwtClaims): Promise<string>;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED,MAAM,WAAW,SAAU,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,SAAS;IACxB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD"}

package/package.json

@@ -9,7 +9,7 @@
     "signing",
     "verification"
   ],
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,9 +36,9 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.1",
-    "@fluojs/di": "^1.0.0-beta.1",
-    "@fluojs/runtime": "^1.0.0-beta.1"
+    "@fluojs/core": "^1.0.0-beta.2",
+    "@fluojs/di": "^1.0.0-beta.4",
+    "@fluojs/runtime": "^1.0.0-beta.4"
   },
   "devDependencies": {
     "vitest": "^3.2.4"