@fluojs/jwt 1.1.0 → 2.0.0

package/README.ko.md

@@ -2,6 +2,8 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
+Node.js 지원 범위는 `>=24.0.0 <27`입니다. 업그레이드 절차는 [Node.js 지원 및 마이그레이션](../../docs/reference/node-support.ko.md)을 참조하세요.
+
 HTTP에 독립적인 JWT 토큰 코어로, 액세스 토큰의 서명 및 검증을 담당하며 검증된 결과를 정규화된 `JwtPrincipal` 객체로 변환합니다.
 
 ## 목차
@@ -61,38 +63,47 @@ JWT 설정이 다른 provider에서 와야 한다면, `JwtModule.forRootAsync(..
 
 `forRootAsync(...)`는 `inject`에 나열된 provider에서 module-level `JwtVerifierOptions` 객체 하나를 resolve합니다. 이 factory는 요청별 상태를 받지 않습니다. 테넌트별 secret이나 identity provider가 필요한 경우 tenant lookup은 애플리케이션의 auth layer에 두고, token verification 중에는 `kid` 같은 token metadata와 미리 구성한 `keys[]`, `jwksUri`, 또는 `secretOrKeyProvider`를 사용해 검증 material을 선택하세요.
 
-```typescript
-import { Module, type Token } from '@fluojs/core';
-import { JwtModule } from '@fluojs/jwt';
+지원되는 계약은 `JwtModule.forRootAsync({ inject, useFactory, global? })`입니다. `JwtModule.forRootAsync(...)`의 `inject`에 지정한 의존성은 JWT options provider가 resolve되기 전에 application module graph에 먼저 등록해야 하며, `useFactory`는 최종 `JwtVerifierOptions`를 반환합니다. 최상위 `global?`은 반환된 module의 가시성을 제어하며, `useFactory`가 반환하는 최종 `JwtVerifierOptions`와는 별개입니다. NestJS dynamic-module `imports`, `useClass`, `useExisting`은 지원되는 typed configuration의 일부가 아니며 dynamic-module 의미도 없습니다. 추가 JavaScript object property는 runtime에서 읽지 않을 뿐 validate하거나 reject하지 않습니다. `JwtModule.forRootAsync(...)`의 의존성은 global로 visible한 module export 또는 `JwtRuntimeModule`이 resolve할 수 있는 application graph의 bootstrap runtime provider에서 와야 합니다. ordinary sibling 또는 parent module의 export만으로는 충분하지 않으며, `AuthModule.providers`에만 local인 provider는 JWT options provider에서 보이지 않습니다. `JwtModule.forRootAsync(...)`는 암묵적 module 또는 provider discovery를 지원하지 않습니다.
 
-const JWT_SETTINGS = Symbol('jwt-settings');
+```typescript
+import { Module } from '@fluojs/core';
+import { ConfigModule, ConfigService } from '@fluojs/config';
+import { JwtModule, type JwtVerifierOptions } from '@fluojs/jwt';
 
 @Module({
   imports: [
-    JwtModule.forRootAsync({
-      inject: [JWT_SETTINGS],
-      useFactory: async (settings) => ({
-        accessTokenTtlSeconds: 900,
-        algorithms: ['HS256'],
-        audience: 'my-app',
-        issuer: settings.issuer,
-        secret: settings.secret,
-      }),
+    ConfigModule.forRoot({
+      processEnv: { JWT_SECRET: process.env.JWT_SECRET },
     }),
-  ],
-  providers: [
-    {
-      provide: JWT_SETTINGS as Token<{ issuer: string; secret: string }>,
-      useValue: {
-        issuer: 'my-api',
-        secret: 'your-secure-secret',
+    JwtModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: async (...deps: unknown[]): Promise<JwtVerifierOptions> => {
+        const [config] = deps;
+        if (!(config instanceof ConfigService)) {
+          throw new TypeError('ConfigService dependency is required');
+        }
+
+        const secret = config.snapshot()['JWT_SECRET'];
+        if (typeof secret !== 'string') {
+          throw new TypeError('JWT_SECRET must be a string');
+        }
+
+        return {
+          accessTokenTtlSeconds: 900,
+          algorithms: ['HS256'],
+          audience: 'my-app',
+          issuer: 'my-api',
+          secret,
+        };
       },
-    },
+    }),
   ],
 })
 export class AuthModule {}
 ```
 
+여기서는 `ConfigModule.forRoot(...)`가 기본으로 `ConfigService`를 global export하므로 `JwtRuntimeModule` options provider가 이를 resolve할 수 있습니다. `AuthModule.providers`에만 선언한 provider는 그 imported module에서 보이지 않습니다.
+
 ### 토큰 서명 및 검증
 
 `DefaultJwtSigner`를 주입받아 토큰을 발행하고, `DefaultJwtVerifier`를 통해 검증합니다.
@@ -152,21 +163,46 @@ const verifier = new DefaultJwtVerifier({
 
 JWKS key는 `jwksCacheTtl` 밀리초 동안 cache되며 기본값은 `600_000`입니다. in-memory cache는 `jwksCacheMaxEntries`로 제한되고 기본값은 `100`입니다. lookup 전 만료된 entry를 정리하고, 제한을 넘으면 가장 오래 보관된 key를 제거합니다. `JwtModule`은 관리 중인 `DefaultJwtVerifier` shutdown hook을 호출하므로 module teardown 중 보관 중인 remote key material이 정리됩니다. 수동으로 생성한 verifier나 client는 수동 shutdown 또는 identity-provider 재설정 시 여전히 `JwksClient.dispose()` / `DefaultJwtVerifier.dispose()`를 호출해야 합니다. 이 dispose method들은 보관 중인 JWKS key material을 정리하고 진행 중인 JWKS fetch를 abort합니다. `jwksCacheTtl`을 `0`으로 설정하면 bounded fetch timeout은 유지하면서 key 보관만 비활성화합니다.
 
-`JwtService.verify(token, options)`는 호출 단위의 알고리즘/클레임 정책 재정의(`issuer`, `audience`, `clockSkewSeconds`, `maxAge`, `requireExp`)를 적용하더라도, 내부 JWKS client나 정적 key-resolution cache를 다시 만들지 않습니다. 호출 단위 검증은 `jwksUri`, `keys[]`, `publicKey`, `secret`, `secretOrKeyProvider` 같은 구성된 key source 자체를 교체하지는 않습니다.
+`DefaultJwtVerifier.verifyAccessTokenWithOverrides(token, options)`는 호출 단위의 알고리즘/클레임 정책 재정의(`algorithms`, `issuer`, `audience`, `clockSkewSeconds`, `maxAge`, `requireExp`)를 적용하더라도, 내부 JWKS client나 정적 key-resolution cache를 다시 만들지 않습니다. 호출 단위 검증은 `jwksUri`, `keys[]`, `publicKey`, `secret`, `secretOrKeyProvider` 같은 구성된 key source 자체를 교체하지는 않습니다.
 
-호환되는 키가 여러 개 설정되어 있으면 `kid`가 검증 키를 구분합니다. 호환되는 정적 키가 하나뿐이면 `kid` 없이도 토큰을 검증할 수 있고, JWKS 기반 검증은 원격 key set과 cache policy를 따릅니다.
+호환되는 키가 여러 개 설정되어 있으면 `kid`가 검증 키를 구분합니다. `keys[]`의 모든 entry는 비어 있지 않고 고유한 `kid`를 가져야 합니다. `DefaultJwtSigner`와 `DefaultJwtVerifier`는 key rotation 중 서명과 검증이 서로 다른 키를 선택하지 않도록 construction 시점에 빈 값 또는 중복 값을 `JwtConfigurationError`로 거부합니다. 호환되는 정적 키가 하나뿐이면 `kid` 없이도 토큰을 검증할 수 있고, JWKS 기반 검증은 원격 key set과 cache policy를 따릅니다.
 
 멀티테넌트 시스템에서는 발행된 토큰 header에 tenant-specific `kid`를 넣고 호환되는 key source를 미리 구성하는 방식을 권장합니다. `secretOrKeyProvider`는 decoded token header만 인자로 받으므로, request header, route param, 기타 request-context tenant hint는 JWT verifier 호출 전에 애플리케이션 수준 strategy/guard 코드에서 처리해야 합니다.
 
 ### 리프레시 토큰
 
-`RefreshTokenService`는 전용 HMAC refresh-token 경로를 사용합니다. `refreshToken.secret`은 access-token 서명 키와 별도로 설정하세요. Rotation은 `RefreshTokenStore.rotate(...)`를 사용해 현재 토큰을 소비 처리하고 대체 토큰을 같은 durable store 작업 안에서 저장할 수 있습니다. 따라서 성공한 rotation은 저장된 후속 토큰 없이 기존 토큰만 소비하지 않습니다. 기존 atomic `consume(...)` hook만 구현한 store도 계속 지원합니다. Consume이 성공하면 service가 `save(...)`로 대체 토큰을 저장하지만, 두 쓰기를 원자적으로 만드는 경로는 store 소유의 `rotate(...)`뿐입니다.
+`RefreshTokenService`는 전용 HMAC refresh-token 경로를 사용합니다. `refreshToken.secret`은 access-token 서명 키와 별도로 설정하세요. access-token `algorithms`가 비대칭 알고리즘만 허용할 때는 `refreshToken.algorithms`에 `['HS256']` 같은 명시적인 HMAC allowlist를 설정하세요. 그렇지 않으면 기존 구성과의 호환성을 위해 top-level HMAC algorithms에서 refresh policy를 파생합니다. 이 policy는 refresh-token 서명과 검증에만 적용되므로 access-token 검증 범위를 넓히지 않습니다.
+
+```typescript
+const options = {
+  algorithms: ['RS256'],
+  privateKey: '...private PEM...',
+  publicKey: '...public PEM...',
+  refreshToken: {
+    algorithms: ['HS256'],
+    secret: 'refresh-secret',
+    expiresInSeconds: 300,
+    rotation: false,
+    store,
+  },
+};
+```
+
+Rotation은 `RefreshTokenStore.rotate(...)`를 사용해 현재 토큰을 소비 처리하고 대체 토큰을 같은 durable store 작업 안에서 저장할 수 있습니다. 따라서 성공한 rotation은 저장된 후속 토큰 없이 기존 토큰만 소비하지 않습니다. 기존 atomic `consume(...)` hook만 구현한 store도 계속 지원합니다. Consume이 성공하면 service가 `save(...)`로 대체 토큰을 저장하지만, 두 쓰기를 원자적으로 만드는 경로는 store 소유의 `rotate(...)`뿐입니다.
 
 재사용을 감지하면 optional `revokeByFamily(family)` capability를 구현한 store는 침해된 token family만 revoke합니다. 기존 store는 source-compatible 상태를 유지합니다. `revokeByFamily(...)`가 없으면 `RefreshTokenService`는 보수적으로 `revokeBySubject(subject)`로 fallback하며, 이 경우 해당 subject의 독립적인 refresh-token family도 함께 revoke됩니다. 다른 family가 침해된 뒤에도 별도 device 또는 session family를 유지해야 하는 production store는 `revokeByFamily(...)`를 구현하세요.
 
+단일 세션 로그아웃에서는 caller가 제시한 compact token을 `revokePresentedRefreshToken(...)`에 전달하세요.
+
+```typescript
+await refreshTokens.revokePresentedRefreshToken(refreshToken);
+```
+
+이 method는 일치하는 record를 revoke하기 전에 signature, expiry, `type`, `jti`, `family`, `sub` claim을 검증합니다. `revokeRefreshToken(tokenId)`는 신뢰할 수 있는 record ID를 이미 가진 caller를 위한 API로 유지됩니다. raw compact token을 이 ID 기반 method에 전달하지 마세요.
+
 ## 설정 가드레일
 
-JWT 서명과 검증에는 `algorithms`에 지원되는 알고리즘이 하나 이상 필요합니다. 기본 signer는 `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`를 지원하며, 빈 알고리즘 목록은 모호한 토큰을 발행하거나 수락하지 않도록 즉시 실패합니다.
+JWT 서명과 access-token 검증에는 `algorithms`에 지원되는 알고리즘이 하나 이상 필요합니다. Refresh-token 서명과 검증은 `refreshToken.algorithms`가 설정되어 있으면 이를 사용하고, 설정되지 않으면 backward compatibility를 위해 top-level HMAC algorithms를 사용합니다. 기본 signer는 `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`를 지원하며, 빈 알고리즘 목록은 모호한 토큰을 발행하거나 수락하지 않도록 즉시 실패합니다.
 
 액세스 토큰 TTL도 양의 유한 숫자여야 합니다. `accessTokenTtlSeconds`를 생략하면 `DefaultJwtSigner`는 문서화된 기본값인 `3600`초를 사용합니다. 소수 초는 JWT NumericDate `exp` 클레임에 그대로 보존됩니다. `0`, 음수 또는 유한하지 않은 값이 제공되면 토큰을 발행하기 전에 `JwtConfigurationError`로 실패합니다.
 
@@ -180,7 +216,7 @@ Lazy loading은 import-time 안전성 속성일 뿐입니다. 서명이나 검
 
 ### `decode()` trust boundary
 
-`JwtService.decode(token)`는 서명, `alg`, `exp`, `nbf`, `iss`, `aud` 또는 기타 클레임을 검증하지 않고 JWT payload segment를 읽습니다. 반환된 객체는 **검증되지 않은 입력(unverified input)**이며, 권한 결정(authorization decisions), 신원 확인(identity resolution), 또는 접근을 허가하는 모든 코드 경로에 사용해서는 안 됩니다. 먼저 `JwtService.verify(token, options)`(또는 `DefaultJwtVerifier.verifyAccessToken(token)`)를 호출하고, 검증이 반환하는 정규화된 `JwtPrincipal`에서 신원을 읽으세요.
+`JwtService.decode(token)`는 서명, `alg`, `exp`, `nbf`, `iss`, `aud` 또는 기타 클레임을 검증하지 않고 JWT payload segment를 읽습니다. 반환된 객체는 **검증되지 않은 입력(unverified input)**이며, 권한 결정(authorization decisions), 신원 확인(identity resolution), 또는 접근을 허가하는 모든 코드 경로에 사용해서는 안 됩니다. 검증된 클레임은 `JwtService.verify(token, options)`로 얻으세요. 정규화된 `JwtPrincipal`이 필요하면 호출 단위 재정의 없이 `DefaultJwtVerifier.verifyAccessToken(token)`을 사용하고, 호출 단위 `algorithms`, `audience`, `issuer`, `clockSkewSeconds`, `maxAge`, `requireExp`를 보존해야 하면 `DefaultJwtVerifier.verifyAccessTokenWithOverrides(token, options)`을 사용하세요.
 
 `decode()`는 진단(diagnostics) 및 비권위적 검사(non-authoritative inspection)에만 사용됩니다. 예를 들어 로깅을 위해 토큰 메타데이터를 읽거나 `verify()` 호출 전에 검증 키를 선택할 때 사용할 수 있습니다. `decode()` 출력에서 읽은 모든 클레임 값 — `sub`, `roles`, `scopes`, `iss`, `aud`, `exp` 포함 — 은 `verify()`가 성공하기 전까지 공격자가 제어한 값으로 취급해야 합니다. `decode()` 출력을 기준으로 요청을 허가하거나 거부하는 분기를 만들지 말고, 검증되지 않은 클레임을 검증된 것처럼 downstream 코드에 노출하지 마세요.
 
@@ -192,7 +228,7 @@ Lazy loading은 import-time 안전성 속성일 뿐입니다. 서명이나 검
 - `DefaultJwtVerifier`: 토큰 검증 및 정규화를 담당하는 클래스입니다.
 - `JwtService`: 서명과 검증 기능을 결합한 편의용 파사드(facade)입니다.
 - `JwksClient`: 제한된 요청 시간 안에서 원격 JWKS 키를 가져오고 캐싱합니다.
-- `RefreshTokenService`: `refreshToken` 옵션이 구성된 경우 refresh token을 발행, 회전, 폐기합니다.
+- `RefreshTokenService`: `refreshToken` 옵션이 구성된 경우 refresh token을 발행, 회전, 폐기합니다. `revokePresentedRefreshToken(...)`은 compact refresh token을 검증한 뒤 record를 revoke하며, `revokeRefreshToken(tokenId)`는 신뢰된 ID를 받는 대안입니다.
 
 ### 타입
 - `JwtPrincipal`: 정규화된 사용자 식별 객체 (`subject`, `roles`, `scopes`, `claims`).
@@ -205,10 +241,11 @@ Lazy loading은 import-time 안전성 속성일 뿐입니다. 서명이나 검
 ### 에러와 diagnostics
 - `JwtVerificationError`, `JwtInvalidTokenError`, `JwtExpiredTokenError`, `JwtConfigurationError`: 타입이 지정된 JWT 실패입니다.
 - `createJwtPlatformStatusSnapshot(...)`, `createJwtPlatformDiagnosticIssues(...)`: status 및 diagnostic helper입니다.
-- `JWT_OPTIONS`, `HMAC_HASH`, `ASYMMETRIC_HASH`: 모듈과 검증 레이어에서 사용하는 export token/constant입니다.
+- `JWT_OPTIONS`, `HMAC_HASH`, `ASYMMETRIC_HASH`: 모듈과 검증 레이어에서 사용하는 export token/constant입니다. `HMAC_HASH`와 `ASYMMETRIC_HASH`는 readonly lookup 값이므로 변경하지 마세요.
 
 ### Deprecated compatibility helper
 - `normalizeRefreshTokenOptions(...)`: 기존 caller의 root import 호환성만을 위해 유지됩니다. package normalization 내부 helper를 직접 호출하기보다 `JwtModule.forRoot(...)` / `JwtModule.forRootAsync(...)`와 `RefreshTokenService`를 사용하세요.
+- `createJwtCoreProviders(...)`: 기존 direct module composition caller의 root import 호환성만을 위해 유지됩니다. registration이 published module surface와 정렬되도록 `JwtModule.forRoot(...)` / `JwtModule.forRootAsync(...)`를 사용하세요.
 
 ## 관련 패키지
 

package/README.md

@@ -2,6 +2,8 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
+Node.js support is `>=24.0.0 <27`. See [Node.js support and migration](../../docs/reference/node-support.md) before upgrading.
+
 HTTP-agnostic JWT token core that handles signing access tokens and verifying them into a normalized `JwtPrincipal`.
 
 ## Table of Contents
@@ -61,38 +63,47 @@ Async registration exports the same JWT provider surface as the synchronous path
 
 `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.
 
-```typescript
-import { Module, type Token } from '@fluojs/core';
-import { JwtModule } from '@fluojs/jwt';
+The supported contract is `JwtModule.forRootAsync({ inject, useFactory, global? })`: dependencies named by `inject` must already be registered in the application module graph before the JWT options provider resolves, and `useFactory` returns the final `JwtVerifierOptions`. The top-level `global?` controls returned module visibility and is distinct from the final `JwtVerifierOptions` returned by `useFactory`. NestJS dynamic-module `imports`, `useClass`, and `useExisting` are not part of the supported typed configuration and have no dynamic-module semantics; extra JavaScript object properties are unread at runtime, not validated or rejected. For `JwtModule.forRootAsync(...)`, dependencies must come from a globally visible module export or bootstrap runtime providers in the application graph that `JwtRuntimeModule` can resolve. An ordinary sibling or parent module export alone, and a provider local only to `AuthModule.providers`, are not visible to the JWT options provider. `JwtModule.forRootAsync(...)` performs no implicit module or provider discovery.
 
-const JWT_SETTINGS = Symbol('jwt-settings');
+```typescript
+import { Module } from '@fluojs/core';
+import { ConfigModule, ConfigService } from '@fluojs/config';
+import { JwtModule, type JwtVerifierOptions } from '@fluojs/jwt';
 
 @Module({
   imports: [
-    JwtModule.forRootAsync({
-      inject: [JWT_SETTINGS],
-      useFactory: async (settings) => ({
-        accessTokenTtlSeconds: 900,
-        algorithms: ['HS256'],
-        audience: 'my-app',
-        issuer: settings.issuer,
-        secret: settings.secret,
-      }),
+    ConfigModule.forRoot({
+      processEnv: { JWT_SECRET: process.env.JWT_SECRET },
     }),
-  ],
-  providers: [
-    {
-      provide: JWT_SETTINGS as Token<{ issuer: string; secret: string }>,
-      useValue: {
-        issuer: 'my-api',
-        secret: 'your-secure-secret',
+    JwtModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: async (...deps: unknown[]): Promise<JwtVerifierOptions> => {
+        const [config] = deps;
+        if (!(config instanceof ConfigService)) {
+          throw new TypeError('ConfigService dependency is required');
+        }
+
+        const secret = config.snapshot()['JWT_SECRET'];
+        if (typeof secret !== 'string') {
+          throw new TypeError('JWT_SECRET must be a string');
+        }
+
+        return {
+          accessTokenTtlSeconds: 900,
+          algorithms: ['HS256'],
+          audience: 'my-app',
+          issuer: 'my-api',
+          secret,
+        };
       },
-    },
+    }),
   ],
 })
 export class AuthModule {}
 ```
 
+Here, `ConfigModule.forRoot(...)` exports `ConfigService` globally by default, so the `JwtRuntimeModule` options provider can resolve it. A provider declared only in `AuthModule.providers` is not visible to that imported module.
+
 ### Sign and Verify Tokens
 
 Inject `DefaultJwtSigner` to issue tokens and `DefaultJwtVerifier` to validate them.
@@ -152,21 +163,46 @@ const verifier = new DefaultJwtVerifier({
 
 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`.
+`DefaultJwtVerifier.verifyAccessTokenWithOverrides(token, options)` applies per-call algorithm and claim-policy overrides (`algorithms`, `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.
+When multiple compatible keys are configured, `kid` disambiguates the verification key. Every `keys[]` entry must have a non-empty, unique `kid`; `DefaultJwtSigner` and `DefaultJwtVerifier` reject empty or duplicate values with `JwtConfigurationError` during construction so key rotation cannot select different keys for signing and verification. 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.
+`RefreshTokenService` uses a dedicated HMAC refresh-token path. Configure `refreshToken.secret` separately from access-token signing keys. Set `refreshToken.algorithms` to an explicit HMAC allowlist (for example, `['HS256']`) when the access-token `algorithms` list is asymmetric-only; otherwise, existing configurations continue to derive the refresh policy from the top-level HMAC algorithms. This policy applies only to refresh-token signing and verification, so it does not widen access-token verification.
+
+```typescript
+const options = {
+  algorithms: ['RS256'],
+  privateKey: '...private PEM...',
+  publicKey: '...public PEM...',
+  refreshToken: {
+    algorithms: ['HS256'],
+    secret: 'refresh-secret',
+    expiresInSeconds: 300,
+    rotation: false,
+    store,
+  },
+};
+```
+
+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.
 
+For single-session logout, pass the compact token that the caller presented to `revokePresentedRefreshToken(...)`:
+
+```typescript
+await refreshTokens.revokePresentedRefreshToken(refreshToken);
+```
+
+This verifies the signature, expiry, `type`, `jti`, `family`, and `sub` claims before revoking the matching record. `revokeRefreshToken(tokenId)` remains available for callers that already hold a trusted record ID; do not pass a raw compact token to that ID-based method.
+
 ## 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.
+JWT signing and access-token verification require at least one supported algorithm in `algorithms`. Refresh-token signing and verification use `refreshToken.algorithms` when configured, or the top-level HMAC algorithms for backward compatibility. 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.
 
@@ -180,7 +216,7 @@ Lazy loading is an import-time safety property only. It does **not** make signin
 
 ### `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.
+`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)` to obtain verified claims. To obtain a normalized `JwtPrincipal`, use `DefaultJwtVerifier.verifyAccessToken(token)` without per-call overrides, or `DefaultJwtVerifier.verifyAccessTokenWithOverrides(token, options)` when preserving per-call `algorithms`, `audience`, `issuer`, `clockSkewSeconds`, `maxAge`, or `requireExp`.
 
 `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.
 
@@ -192,7 +228,7 @@ Lazy loading is an import-time safety property only. It does **not** make signin
 - `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.
+- `RefreshTokenService`: Issues, rotates, and revokes refresh tokens when `refreshToken` options are configured. `revokePresentedRefreshToken(...)` verifies a compact refresh token before revoking its record; `revokeRefreshToken(tokenId)` is the trusted-ID alternative.
 
 ### Types
 - `JwtPrincipal`: The normalized identity object (`subject`, `roles`, `scopes`, `claims`).
@@ -205,10 +241,11 @@ Lazy loading is an import-time safety property only. It does **not** make signin
 ### 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.
+- `JWT_OPTIONS`, `HMAC_HASH`, `ASYMMETRIC_HASH`: Exported tokens/constants used by the module and verification layer. `HMAC_HASH` and `ASYMMETRIC_HASH` are readonly lookup values; do not mutate them.
 
 ### 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.
+- `createJwtCoreProviders(...)`: Retained only for root-import compatibility with existing direct module composition callers. Prefer `JwtModule.forRoot(...)` / `JwtModule.forRootAsync(...)` so registration stays aligned with the published module surface.
 
 ## Related Packages
 

package/dist/module.d.ts

@@ -1,6 +1,15 @@
 import { type AsyncModuleOptions, type Constructor } from '@fluojs/core';
+import type { Provider } from '@fluojs/di';
 import type { JwtVerifierOptions } from './types.js';
 type ModuleType = Constructor;
+/**
+ * Creates the core JWT providers for advanced direct module composition.
+ *
+ * @deprecated Prefer {@link JwtModule.forRoot} or {@link JwtModule.forRootAsync} so JWT registration stays aligned with the published module surface.
+ * @param options JWT verification and signing options used for provider registration.
+ * @returns Providers for the JWT verifier, signer, facade, and optional refresh-token service.
+ */
+export declare function createJwtCoreProviders(options: JwtVerifierOptions): Provider[];
 /**
  * Registers JWT services and optional refresh-token support for an application module.
  */

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,EAAsD,MAAM,cAAc,CAAC;AAOrI,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;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,UAAU;IASvG,OAAO,CAAC,MAAM,CAAC,YAAY;CAkB5B"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAA0C,MAAM,cAAc,CAAC;AAEzH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAK3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIrD,KAAK,UAAU,GAAG,WAAW,CAAC;AAyE9B;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,QAAQ,EAAE,CAM9E;AAED;;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;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,UAAU;IASvG,OAAO,CAAC,MAAM,CAAC,YAAY;CAkB5B"}

package/dist/module.js

@@ -55,6 +55,21 @@ function createJwtModuleProviders(optionsProvider, includeRefreshTokenService, r
   return providers;
 }
 
+/**
+ * Creates the core JWT providers for advanced direct module composition.
+ *
+ * @deprecated Prefer {@link JwtModule.forRoot} or {@link JwtModule.forRootAsync} so JWT registration stays aligned with the published module surface.
+ * @param options JWT verification and signing options used for provider registration.
+ * @returns Providers for the JWT verifier, signer, facade, and optional refresh-token service.
+ */
+export function createJwtCoreProviders(options) {
+  return createJwtModuleProviders({
+    provide: JWT_OPTIONS,
+    scope: 'singleton',
+    useValue: options
+  }, Boolean(options.refreshToken), 'singleton');
+}
+
 /**
  * Registers JWT services and optional refresh-token support for an application module.
  */

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

@@ -0,0 +1,22 @@
+import type { DefaultJwtVerifier } from '../signing/verifier.js';
+import type { JwtClaims } from '../types.js';
+/**
+ * Describes the claims required for a verified refresh token.
+ */
+export interface RefreshTokenClaims extends JwtClaims {
+    family: string;
+    jti: string;
+    type: 'refresh';
+}
+/**
+ * Verifies a compact refresh token and returns its required claims.
+ *
+ * @param verifier Configured verifier for the refresh-token policy.
+ * @param token Compact refresh token to verify.
+ * @returns Verified refresh-token claims with non-empty required identifiers.
+ * @throws {JwtInvalidTokenError} When the token is not a refresh token or lacks required claims.
+ */
+export declare function verifyRefreshTokenClaims(verifier: DefaultJwtVerifier, token: string): Promise<RefreshTokenClaims & {
+    sub: string;
+}>;
+//# sourceMappingURL=refresh-token-claims.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-token-claims.d.ts","sourceRoot":"","sources":["../../src/refresh/refresh-token-claims.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,SAAS;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CA2B/C"}

package/dist/refresh/refresh-token-claims.js

@@ -0,0 +1,37 @@
+import { JwtInvalidTokenError } from '../errors.js';
+
+/**
+ * Describes the claims required for a verified refresh token.
+ */
+
+/**
+ * Verifies a compact refresh token and returns its required claims.
+ *
+ * @param verifier Configured verifier for the refresh-token policy.
+ * @param token Compact refresh token to verify.
+ * @returns Verified refresh-token claims with non-empty required identifiers.
+ * @throws {JwtInvalidTokenError} When the token is not a refresh token or lacks required claims.
+ */
+export async function verifyRefreshTokenClaims(verifier, token) {
+  const principal = await verifier.verifyRefreshToken(token);
+  const claims = principal.claims;
+  if (claims.type !== 'refresh') {
+    throw new JwtInvalidTokenError('JWT is not a refresh token.');
+  }
+  if (typeof claims.jti !== 'string' || claims.jti.length === 0) {
+    throw new JwtInvalidTokenError('Refresh token is missing jti.');
+  }
+  if (typeof claims.family !== 'string' || claims.family.length === 0) {
+    throw new JwtInvalidTokenError('Refresh token is missing family.');
+  }
+  if (typeof claims.sub !== 'string' || claims.sub.length === 0) {
+    throw new JwtInvalidTokenError('Refresh token is missing sub.');
+  }
+  return {
+    ...claims,
+    family: claims.family,
+    jti: claims.jti,
+    sub: claims.sub,
+    type: 'refresh'
+  };
+}

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

@@ -1,5 +1,6 @@
 import type { DefaultJwtSigner } from '../signing/signer.js';
 import type { DefaultJwtVerifier } from '../signing/verifier.js';
+import type { JwtAlgorithm } from '../types.js';
 /**
  * Describes the refresh token store contract.
  */
@@ -46,11 +47,13 @@ export interface RefreshTokenRecord {
  * Describes the refresh token options contract.
  */
 export interface RefreshTokenOptions {
-    secret: string;
-    expiresInSeconds: number;
-    verifyMaxAgeSeconds?: number;
-    rotation: boolean;
-    store: RefreshTokenStore;
+    /** HMAC algorithms allowed for refresh-token signing and verification. Defaults to HMAC algorithms from the top-level policy. */
+    readonly algorithms?: readonly Extract<JwtAlgorithm, 'HS256' | 'HS384' | 'HS512'>[];
+    readonly secret: string;
+    readonly expiresInSeconds: number;
+    readonly verifyMaxAgeSeconds?: number;
+    readonly rotation: boolean;
+    readonly store: RefreshTokenStore;
 }
 /**
  * Normalize refresh token options for legacy root-import callers.
@@ -78,11 +81,19 @@ export declare class RefreshTokenService {
         refreshToken: string;
     }>;
     revokeRefreshToken(tokenId: string): Promise<void>;
+    /**
+     * Revokes the record identified by a verified presented refresh token.
+     *
+     * @param token Compact refresh token to verify before its record is revoked.
+     * @returns A promise that resolves after the verified refresh-token record is revoked.
+     * @throws {JwtInvalidTokenError} When the token is malformed or lacks required refresh claims.
+     * @throws {JwtExpiredTokenError} When the refresh token has expired.
+     */
+    revokePresentedRefreshToken(token: string): Promise<void>;
     revokeAllForSubject(subject: string): Promise<void>;
     private issueRefreshTokenWithFamily;
     private consumeRefreshToken;
     private revokeCompromisedFamily;
     private createRefreshTokenWithFamily;
-    private verifyRefreshClaims;
 }
 //# sourceMappingURL=refresh-token.d.ts.map

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":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGjE;;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,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAC9E,MAAM,CAAC,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC7E;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,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,WAAW,EAAE,kBAAkB,CAAC;CACjC;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;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GAAG,mBAAmB,CA6B1G;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;IAOnD,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IA0EhG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAI3C,2BAA2B;YAQ3B,mBAAmB;YAUnB,uBAAuB;YASvB,4BAA4B;YA+B5B,mBAAmB;CA4BlC"}
+{"version":3,"file":"refresh-token.d.ts","sourceRoot":"","sources":["../../src/refresh/refresh-token.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD;;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,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAC9E,MAAM,CAAC,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC7E;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,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,WAAW,EAAE,kBAAkB,CAAC;CACjC;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,iIAAiI;IACjI,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,OAAO,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,EAAE,CAAC;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GAAG,mBAAmB,CA2C1G;AAED;;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;IAOnD,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IA0EhG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;;;;;;OAOG;IACG,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAI3C,2BAA2B;YAQ3B,mBAAmB;YAUnB,uBAAuB;YASvB,4BAA4B;CA8B3C"}

package/dist/refresh/refresh-token.js

@@ -1,4 +1,6 @@
 import { JwtConfigurationError, JwtExpiredTokenError, JwtInvalidTokenError } from '../errors.js';
+import { SUPPORTED_HMAC_HASH } from '../signing/algorithm-policy.js';
+import { verifyRefreshTokenClaims } from './refresh-token-claims.js';
 
 /**
  * Describes the refresh token store contract.
@@ -39,6 +41,16 @@ export function normalizeRefreshTokenOptions(options) {
   if (!options) {
     throw new JwtConfigurationError('JWT refresh token options are not configured.');
   }
+  if (options.algorithms !== undefined) {
+    if (!Array.isArray(options.algorithms) || options.algorithms.length === 0) {
+      throw new JwtConfigurationError('JWT refresh token algorithms must contain at least one HMAC algorithm.');
+    }
+    for (const algorithm of options.algorithms) {
+      if (typeof algorithm !== 'string' || !Object.hasOwn(SUPPORTED_HMAC_HASH, algorithm)) {
+        throw new JwtConfigurationError(`JWT refresh token received unsupported algorithm "${String(algorithm)}"; only HS256, HS384, and HS512 are allowed.`);
+      }
+    }
+  }
   if (typeof options.secret !== 'string' || options.secret.length === 0) {
     throw new JwtConfigurationError('JWT refresh token secret must be a non-empty string.');
   }
@@ -55,6 +67,7 @@ export function normalizeRefreshTokenOptions(options) {
     ...options
   };
 }
+
 /**
  * Represents the refresh token service.
  */
@@ -73,7 +86,7 @@ export class RefreshTokenService {
     return this.issueRefreshTokenWithFamily(subject, family);
   }
   async rotateRefreshToken(currentToken) {
-    const claims = await this.verifyRefreshClaims(currentToken);
+    const claims = await verifyRefreshTokenClaims(this.verifier, currentToken);
     if (this.options.rotation) {
       if (!this.options.store.rotate && !this.options.store.consume) {
         throw new JwtConfigurationError('Refresh token rotation requires an atomic store.rotate() or store.consume() implementation.');
@@ -140,6 +153,19 @@ export class RefreshTokenService {
   async revokeRefreshToken(tokenId) {
     await this.options.store.revoke(tokenId);
   }
+
+  /**
+   * Revokes the record identified by a verified presented refresh token.
+   *
+   * @param token Compact refresh token to verify before its record is revoked.
+   * @returns A promise that resolves after the verified refresh-token record is revoked.
+   * @throws {JwtInvalidTokenError} When the token is malformed or lacks required refresh claims.
+   * @throws {JwtExpiredTokenError} When the refresh token has expired.
+   */
+  async revokePresentedRefreshToken(token) {
+    const claims = await verifyRefreshTokenClaims(this.verifier, token);
+    await this.options.store.revoke(claims.jti);
+  }
   async revokeAllForSubject(subject) {
     await this.options.store.revokeBySubject(subject);
   }
@@ -193,27 +219,4 @@ export class RefreshTokenService {
       token
     };
   }
-  async verifyRefreshClaims(token) {
-    const principal = await this.verifier.verifyRefreshToken(token);
-    const claims = principal.claims;
-    if (claims.type !== 'refresh') {
-      throw new JwtInvalidTokenError('JWT is not a refresh token.');
-    }
-    if (typeof claims.jti !== 'string' || claims.jti.length === 0) {
-      throw new JwtInvalidTokenError('Refresh token is missing jti.');
-    }
-    if (typeof claims.family !== 'string' || claims.family.length === 0) {
-      throw new JwtInvalidTokenError('Refresh token is missing family.');
-    }
-    if (typeof claims.sub !== 'string' || claims.sub.length === 0) {
-      throw new JwtInvalidTokenError('Refresh token is missing sub.');
-    }
-    return {
-      ...claims,
-      family: claims.family,
-      jti: claims.jti,
-      sub: claims.sub,
-      type: 'refresh'
-    };
-  }
 }

package/dist/signing/algorithm-policy.d.ts

@@ -0,0 +1,4 @@
+import type { JwtAlgorithm } from '../types.js';
+export declare const SUPPORTED_HMAC_HASH: Readonly<Partial<Record<JwtAlgorithm, string>>>;
+export declare const SUPPORTED_ASYMMETRIC_HASH: Readonly<Partial<Record<JwtAlgorithm, string>>>;
+//# sourceMappingURL=algorithm-policy.d.ts.map

package/dist/signing/algorithm-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"algorithm-policy.d.ts","sourceRoot":"","sources":["../../src/signing/algorithm-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAI9E,CAAC;AAEH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAOpF,CAAC"}

package/dist/signing/algorithm-policy.js

@@ -0,0 +1,13 @@
+export const SUPPORTED_HMAC_HASH = Object.freeze({
+  HS256: 'sha256',
+  HS384: 'sha384',
+  HS512: 'sha512'
+});
+export const SUPPORTED_ASYMMETRIC_HASH = Object.freeze({
+  RS256: 'sha256',
+  RS384: 'sha384',
+  RS512: 'sha512',
+  ES256: 'sha256',
+  ES384: 'sha384',
+  ES512: 'sha512'
+});

package/dist/signing/key-entries.d.ts

@@ -0,0 +1,8 @@
+import type { JwtKeyEntry } from '../types.js';
+/**
+ * Rejects static key entries whose IDs cannot unambiguously select one key.
+ *
+ * @param keys Static JWT key entries to validate.
+ */
+export declare function assertJwtKeyEntries(keys: JwtKeyEntry[] | undefined): void;
+//# sourceMappingURL=key-entries.d.ts.map

package/dist/signing/key-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-entries.d.ts","sourceRoot":"","sources":["../../src/signing/key-entries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,SAAS,GAAG,IAAI,CAczE"}

package/dist/signing/key-entries.js

@@ -0,0 +1,18 @@
+import { JwtConfigurationError } from '../errors.js';
+/**
+ * Rejects static key entries whose IDs cannot unambiguously select one key.
+ *
+ * @param keys Static JWT key entries to validate.
+ */
+export function assertJwtKeyEntries(keys) {
+  if (!Array.isArray(keys)) {
+    return;
+  }
+  const keyIds = new Set();
+  for (const entry of keys) {
+    if (typeof entry.kid !== 'string' || entry.kid.length === 0 || keyIds.has(entry.kid)) {
+      throw new JwtConfigurationError('JWT key entries require non-empty unique kid values.');
+    }
+    keyIds.add(entry.kid);
+  }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signing/signer.ts"],"names":[],"mappings":"AAIA,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;CAoFxB"}
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signing/signer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAgB,SAAS,EAAe,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA4D5F;;GAEG;AACH,qBACa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;gBAEtB,OAAO,EAAE,kBAAkB;IAYlD,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;CAoFxB"}

package/dist/signing/signer.js

@@ -7,7 +7,9 @@ function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side
 import { Inject } from '@fluojs/core';
 import { JwtConfigurationError } from '../errors.js';
 import { normalizeRefreshTokenOptions } from '../refresh/refresh-token.js';
-import { ASYMMETRIC_HASH, HMAC_HASH, JWT_OPTIONS } from './verifier.js';
+import { SUPPORTED_ASYMMETRIC_HASH, SUPPORTED_HMAC_HASH } from './algorithm-policy.js';
+import { assertJwtKeyEntries } from './key-entries.js';
+import { JWT_OPTIONS } from './verifier.js';
 function encodeBase64Url(value) {
   return Buffer.from(value).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
 }
@@ -16,7 +18,7 @@ function resolveSigningKeyEntry(options, algorithm) {
   if (!Array.isArray(keys) || keys.length === 0) {
     return undefined;
   }
-  if (hasOwnAlgorithmMapping(HMAC_HASH, algorithm)) {
+  if (hasOwnAlgorithmMapping(SUPPORTED_HMAC_HASH, algorithm)) {
     return keys.find(entry => typeof entry.secret === 'string' && entry.secret.length > 0);
   }
   return keys.find(entry => entry.privateKey !== undefined);
@@ -25,7 +27,7 @@ function hasOwnAlgorithmMapping(mappings, algorithm) {
   return typeof algorithm === 'string' && Object.hasOwn(mappings, algorithm);
 }
 function isSupportedSigningAlgorithm(algorithm) {
-  return hasOwnAlgorithmMapping(HMAC_HASH, algorithm) || hasOwnAlgorithmMapping(ASYMMETRIC_HASH, algorithm);
+  return hasOwnAlgorithmMapping(SUPPORTED_HMAC_HASH, algorithm) || hasOwnAlgorithmMapping(SUPPORTED_ASYMMETRIC_HASH, algorithm);
 }
 function assertSigningAlgorithms(algorithms) {
   if (!Array.isArray(algorithms) || algorithms.length === 0) {
@@ -57,7 +59,10 @@ class DefaultJwtSigner {
   constructor(options) {
     this.options = options;
     assertSigningAlgorithms(options.algorithms);
-    this.refreshAlgorithms = this.options.algorithms.filter(algorithm => hasOwnAlgorithmMapping(HMAC_HASH, algorithm));
+    assertJwtKeyEntries(options.keys);
+    const refreshToken = this.options.refreshToken ? normalizeRefreshTokenOptions(this.options.refreshToken) : undefined;
+    const configuredRefreshAlgorithms = refreshToken?.algorithms;
+    this.refreshAlgorithms = (configuredRefreshAlgorithms ?? this.options.algorithms).filter(algorithm => hasOwnAlgorithmMapping(SUPPORTED_HMAC_HASH, algorithm));
   }
   async signAccessToken(claims) {
     return this.signToken(claims, this.options, false);
@@ -79,7 +84,7 @@ class DefaultJwtSigner {
   async signToken(claims, options, hmacOnly) {
     const algorithm = options.algorithms.find(alg => {
       if (hmacOnly) {
-        return hasOwnAlgorithmMapping(HMAC_HASH, alg);
+        return hasOwnAlgorithmMapping(SUPPORTED_HMAC_HASH, alg);
       }
       return isSupportedSigningAlgorithm(alg);
     });
@@ -89,7 +94,7 @@ 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 = hasOwnAlgorithmMapping(ASYMMETRIC_HASH, algorithm);
+    const isAsymmetric = hasOwnAlgorithmMapping(SUPPORTED_ASYMMETRIC_HASH, algorithm);
     const now = Math.floor(Date.now() / 1000);
     const ttl = resolveAccessTokenTtlSeconds(options);
     const payload = {
@@ -116,7 +121,7 @@ class DefaultJwtSigner {
       if (!privateKey) {
         throw new JwtConfigurationError('JWT private key is not configured.');
       }
-      const hash = ASYMMETRIC_HASH[algorithm];
+      const hash = SUPPORTED_ASYMMETRIC_HASH[algorithm];
       if (!hash) {
         throw new JwtConfigurationError(`No hash mapping for asymmetric algorithm "${algorithm}".`);
       }
@@ -135,7 +140,7 @@ class DefaultJwtSigner {
       if (!secret) {
         throw new JwtConfigurationError('JWT secret is not configured.');
       }
-      const hash = HMAC_HASH[algorithm];
+      const hash = SUPPORTED_HMAC_HASH[algorithm];
       if (!hash) {
         throw new JwtConfigurationError(`No hash mapping for HMAC algorithm "${algorithm}".`);
       }

package/dist/signing/verifier.d.ts

@@ -1,22 +1,27 @@
-import type { OnModuleDestroy } from '@fluojs/runtime';
 import type { JwtAlgorithm, JwtPrincipal, JwtVerifierOptions } from '../types.js';
 /**
  * Provides the resolved JWT verifier options through dependency injection.
  */
 export declare const JWT_OPTIONS: unique symbol;
+/**
+ * Describes the lifecycle hook called when a JWT module is destroyed.
+ */
+export interface JwtModuleDestroyLifecycle {
+    onModuleDestroy(): void | Promise<void>;
+}
 /**
  * Maps supported HMAC JWT algorithms to their Node.js hash names.
  */
-export declare const HMAC_HASH: Partial<Record<JwtAlgorithm, string>>;
+export declare const HMAC_HASH: Readonly<Partial<Record<JwtAlgorithm, string>>>;
 /**
  * Maps supported asymmetric JWT algorithms to their Node.js hash names.
  */
-export declare const ASYMMETRIC_HASH: Partial<Record<JwtAlgorithm, string>>;
+export declare const ASYMMETRIC_HASH: Readonly<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.
  */
-export declare class DefaultJwtVerifier implements OnModuleDestroy {
+export declare class DefaultJwtVerifier implements JwtModuleDestroyLifecycle {
     private readonly options;
     private readonly jwksClient;
     private readonly keyResolutionState;

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

@@ -1 +1 @@
-{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/signing/verifier.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIvD,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;AAmDF,KAAK,gCAAgC,GAAG,IAAI,CAC1C,kBAAkB,EAClB,YAAY,GAAG,UAAU,GAAG,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CACpF,CAAC;AAiMF;;GAEG;AACH,qBACa,kBAAmB,YAAW,eAAe;IAM5C,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;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,eAAe,IAAI,IAAI;IAIvB;;;;;;;;;;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;IAwB3B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,yBAAyB;YAiBnB,oBAAoB;CAOnC"}
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/signing/verifier.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAK1G;;GAEG;AACH,eAAO,MAAM,WAAW,eAAiC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,eAAe,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAA6C,CAAC;AAEpH;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAmD,CAAC;AAmDhI,KAAK,gCAAgC,GAAG,IAAI,CAC1C,kBAAkB,EAClB,YAAY,GAAG,UAAU,GAAG,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CACpF,CAAC;AA2MF;;GAEG;AACH,qBACa,kBAAmB,YAAW,yBAAyB;IAMtD,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;IAclD,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI7D;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,eAAe,IAAI,IAAI;IAIvB;;;;;;;;;;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;YAyB1B,WAAW;IA+BzB,OAAO,CAAC,kBAAkB;YAUZ,oBAAoB;YAgBpB,wBAAwB;YAsBxB,8BAA8B;YAsB9B,kBAAkB;IAWhC,OAAO,CAAC,mBAAmB;IAwB3B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,yBAAyB;YAiBnB,oBAAoB;CAOnC"}

package/dist/signing/verifier.js

@@ -7,38 +7,37 @@ function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side
 import { Inject } from '@fluojs/core';
 import { JwtConfigurationError, JwtExpiredTokenError, JwtInvalidTokenError } from '../errors.js';
 import { normalizeRefreshTokenOptions } from '../refresh/refresh-token.js';
+import { SUPPORTED_ASYMMETRIC_HASH, SUPPORTED_HMAC_HASH } from './algorithm-policy.js';
 import { JwksClient } from './jwks.js';
+import { assertJwtKeyEntries } from './key-entries.js';
 
 /**
  * Provides the resolved JWT verifier options through dependency injection.
  */
 export const JWT_OPTIONS = Symbol.for('fluo.jwt.options');
 
+/**
+ * Describes the lifecycle hook called when a JWT module is destroyed.
+ */
+
 /**
  * Maps supported HMAC JWT algorithms to their Node.js hash names.
  */
-export const HMAC_HASH = {
-  HS256: 'sha256',
-  HS384: 'sha384',
-  HS512: 'sha512'
-};
+export const HMAC_HASH = Object.freeze({
+  ...SUPPORTED_HMAC_HASH
+});
 
 /**
  * Maps supported asymmetric JWT algorithms to their Node.js hash names.
  */
-export const ASYMMETRIC_HASH = {
-  RS256: 'sha256',
-  RS384: 'sha384',
-  RS512: 'sha512',
-  ES256: 'sha256',
-  ES384: 'sha384',
-  ES512: 'sha512'
-};
+export const ASYMMETRIC_HASH = Object.freeze({
+  ...SUPPORTED_ASYMMETRIC_HASH
+});
 function hasOwnAlgorithmMapping(mappings, alg) {
   return typeof alg === 'string' && Object.hasOwn(mappings, alg);
 }
 function isSupportedAlgorithm(alg) {
-  return hasOwnAlgorithmMapping(HMAC_HASH, alg) || hasOwnAlgorithmMapping(ASYMMETRIC_HASH, alg);
+  return hasOwnAlgorithmMapping(SUPPORTED_HMAC_HASH, alg) || hasOwnAlgorithmMapping(SUPPORTED_ASYMMETRIC_HASH, alg);
 }
 function assertJwtAlgorithms(algorithms, context) {
   if (!Array.isArray(algorithms) || algorithms.length === 0) {
@@ -130,7 +129,7 @@ function resolveStaticPublicKey(options, keyState, kid) {
   return keyState.defaultPublicKey ?? options.publicKey;
 }
 async function verifyHmacSignature(algorithm, secret, signingInput, signatureSegment) {
-  const hash = HMAC_HASH[algorithm];
+  const hash = SUPPORTED_HMAC_HASH[algorithm];
   if (!hash) {
     throw new JwtInvalidTokenError();
   }
@@ -146,7 +145,7 @@ async function verifyHmacSignature(algorithm, secret, signingInput, signatureSeg
   }
 }
 async function verifyAsymmetricSignature(algorithm, publicKey, signingInput, signatureSegment) {
-  const hash = ASYMMETRIC_HASH[algorithm];
+  const hash = SUPPORTED_ASYMMETRIC_HASH[algorithm];
   if (!hash) {
     throw new JwtInvalidTokenError();
   }
@@ -171,8 +170,15 @@ function decodeBase64Url(value) {
 }
 function parseJwtPart(value) {
   try {
-    return JSON.parse(decodeBase64Url(value).toString('utf8'));
-  } catch {
+    const parsed = JSON.parse(decodeBase64Url(value).toString('utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      throw new JwtInvalidTokenError('JWT header and payload must be JSON objects.');
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof JwtInvalidTokenError) {
+      throw error;
+    }
     throw new JwtInvalidTokenError();
   }
 }
@@ -212,6 +218,7 @@ class DefaultJwtVerifier {
   constructor(options) {
     this.options = options;
     assertJwtAlgorithms(options.algorithms, 'JWT verifier');
+    assertJwtKeyEntries(options.keys);
     this.jwksClient = options.jwksUri ? new JwksClient(options.jwksUri, options.jwksCacheTtl, options.jwksRequestTimeoutMs, options.jwksCacheMaxEntries) : undefined;
     this.keyResolutionState = createKeyResolutionState(options.keys);
     this.refreshVerificationOptions = options.refreshToken ? this.createRefreshVerificationOptions(normalizeRefreshTokenOptions(options.refreshToken)) : undefined;
@@ -270,7 +277,8 @@ class DefaultJwtVerifier {
     return this.verifyToken(token, this.refreshVerificationOptions, this.refreshKeyResolutionState, undefined);
   }
   createRefreshVerificationOptions(refreshToken) {
-    const algorithms = this.options.algorithms.filter(algorithm => hasOwnAlgorithmMapping(HMAC_HASH, algorithm));
+    const configuredRefreshAlgorithms = refreshToken.algorithms;
+    const algorithms = (configuredRefreshAlgorithms ?? this.options.algorithms).filter(algorithm => hasOwnAlgorithmMapping(SUPPORTED_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.');
     }
@@ -308,7 +316,7 @@ class DefaultJwtVerifier {
     return segments;
   }
   async verifyTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState, jwksClient) {
-    if (hasOwnAlgorithmMapping(HMAC_HASH, header.alg)) {
+    if (hasOwnAlgorithmMapping(SUPPORTED_HMAC_HASH, header.alg)) {
       await this.verifyHmacTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState);
       return;
     }

package/dist/status.d.ts

@@ -1,12 +1,56 @@
-import type { PlatformDiagnosticIssue, PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/**
+ * Describes the readiness state exposed by JWT.
+ */
+export interface JwtPlatformReadinessReport {
+    critical: boolean;
+    reason?: string;
+    status: 'ready' | 'not-ready' | 'degraded';
+    checks?: JwtPlatformCheckResult[];
+}
+/**
+ * Describes the health state exposed by JWT.
+ */
+export interface JwtPlatformHealthReport {
+    reason?: string;
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    checks?: JwtPlatformCheckResult[];
+}
+/**
+ * Describes one named readiness or health probe result exposed by JWT.
+ */
+export interface JwtPlatformCheckResult {
+    name: string;
+    status: 'pass' | 'fail' | 'degraded';
+    message?: string;
+}
+/**
+ * Describes ownership of JWT-managed resources.
+ */
+export interface JwtPlatformOwnership {
+    externallyManaged: boolean;
+    ownsResources: boolean;
+}
+/**
+ * Describes a JWT diagnostic issue.
+ */
+export interface JwtPlatformDiagnosticIssue {
+    cause?: string;
+    code: string;
+    componentId: string;
+    dependsOn?: string[];
+    docsUrl?: string;
+    fixHint?: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+}
 /**
  * Describes the jwt platform status snapshot contract.
  */
 export interface JwtPlatformStatusSnapshot {
-    readiness: PlatformReadinessReport;
-    health: PlatformHealthReport;
-    ownership: PlatformSnapshot['ownership'];
     details: Record<string, unknown>;
+    health: JwtPlatformHealthReport;
+    ownership: JwtPlatformOwnership;
+    readiness: JwtPlatformReadinessReport;
 }
 /**
  * Describes the jwt status adapter input contract.
@@ -33,5 +77,5 @@ export declare function createJwtPlatformStatusSnapshot(input: JwtStatusAdapterI
  * @param input The input.
  * @returns The create jwt platform diagnostic issues result.
  */
-export declare function createJwtPlatformDiagnosticIssues(input: JwtStatusAdapterInput): PlatformDiagnosticIssue[];
+export declare function createJwtPlatformDiagnosticIssues(input: JwtStatusAdapterInput): JwtPlatformDiagnosticIssue[];
 //# 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;;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"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;IAC3C,MAAM,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;IAC7C,MAAM,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,uBAAuB,CAAC;IAChC,SAAS,EAAE,oBAAoB,CAAC;IAChC,SAAS,EAAE,0BAA0B,CAAC;CACvC;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,0BAA0B,EAAE,CAqB5G"}

package/dist/status.js

@@ -1,3 +1,23 @@
+/**
+ * Describes the readiness state exposed by JWT.
+ */
+
+/**
+ * Describes the health state exposed by JWT.
+ */
+
+/**
+ * Describes one named readiness or health probe result exposed by JWT.
+ */
+
+/**
+ * Describes ownership of JWT-managed resources.
+ */
+
+/**
+ * Describes a JWT diagnostic issue.
+ */
+
 /**
  * Describes the jwt platform status snapshot contract.
  */

package/package.json

@@ -9,7 +9,7 @@
     "signing",
     "verification"
   ],
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
     "directory": "packages/jwt"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -36,12 +36,12 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.1.0",
-    "@fluojs/di": "^2.0.0",
-    "@fluojs/runtime": "^2.0.1"
+    "@fluojs/core": "^2.0.0",
+    "@fluojs/di": "^3.0.0"
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11",
+    "@fluojs/runtime": "^3.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",