@fluojs/jwt 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,169 @@
+# @fluojs/jwt
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+HTTP에 독립적인 JWT 토큰 코어로, 액세스 토큰의 서명 및 검증을 담당하며 검증된 결과를 정규화된 `JwtPrincipal` 객체로 변환합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [일반적인 패턴](#일반적인-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/jwt
+```
+
+## 사용 시점
+
+- 백엔드 애플리케이션에서 JWT 액세스 토큰을 발행하거나 검증해야 할 때.
+- 토큰의 클레임 형식과 관계없이 `JwtPrincipal` (주체, 역할, 스코프) 형태의 일관된 사용자 정보를 얻고 싶을 때.
+- 재사용 감지 기능이 포함된 리프레시 토큰 로테이션을 구현할 때.
+
+## 빠른 시작
+
+### 모듈 등록
+
+서명 키와 정책을 사용하여 JWT 모듈을 설정합니다.
+
+JWT 지원은 `JwtModule.forRoot(...)` 또는 `JwtModule.forRootAsync(...)`를 통해 등록합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { JwtModule } from '@fluojs/jwt';
+
+@Module({
+  imports: [
+    JwtModule.forRoot({
+      algorithms: ['HS256'],
+      secret: 'your-secure-secret',
+      issuer: 'my-api',
+      audience: 'my-app',
+      accessTokenTtlSeconds: 3600,
+    }),
+  ],
+})
+export class AuthModule {}
+```
+
+### 주입된 설정을 사용하는 비동기 등록
+
+JWT 설정이 다른 provider에서 와야 한다면, `JwtModule.forRootAsync(...)`를 사용해도 표준 module contract 안에서 안전하게 등록할 수 있습니다.
+
+```typescript
+import { Module, type Token } from '@fluojs/core';
+import { JwtModule } from '@fluojs/jwt';
+
+const JWT_SETTINGS = Symbol('jwt-settings');
+
+@Module({
+  imports: [
+    JwtModule.forRootAsync({
+      inject: [JWT_SETTINGS],
+      useFactory: async (settings) => ({
+        accessTokenTtlSeconds: 900,
+        algorithms: ['HS256'],
+        audience: 'my-app',
+        issuer: settings.issuer,
+        secret: settings.secret,
+      }),
+    }),
+  ],
+  providers: [
+    {
+      provide: JWT_SETTINGS as Token<{ issuer: string; secret: string }>,
+      useValue: {
+        issuer: 'my-api',
+        secret: 'your-secure-secret',
+      },
+    },
+  ],
+})
+export class AuthModule {}
+```
+
+### 토큰 서명 및 검증
+
+`DefaultJwtSigner`를 주입받아 토큰을 발행하고, `DefaultJwtVerifier`를 통해 검증합니다.
+
+```typescript
+import { DefaultJwtSigner, DefaultJwtVerifier } from '@fluojs/jwt';
+
+// 서명 (Sign)
+const token = await signer.signAccessToken({
+  sub: 'user-123',
+  roles: ['admin'],
+  scopes: ['read:profile'],
+});
+
+// 검증 (Verify)
+const principal = await verifier.verifyAccessToken(token);
+// principal: { subject: 'user-123', roles: ['admin'], scopes: ['read:profile'], ... }
+```
+
+`JwtService.sign(payload, { expiresIn })`를 사용할 때는 payload 안에 기존 `exp` 값이 있더라도 호출 시점의 `expiresIn` 재정의가 항상 우선합니다. 따라서 토큰 수명은 호출 위치에서 결정적으로 제어됩니다.
+
+## 일반적인 패턴
+
+### 비대칭 서명 (RS256/ES256)
+
+분산 시스템에서 보안을 강화하기 위해 공개키/개인키 쌍을 사용합니다.
+
+```typescript
+const signer = new DefaultJwtSigner({
+  algorithms: ['RS256'],
+  privateKey: '...PEM...',
+});
+
+const verifier = new DefaultJwtVerifier({
+  algorithms: ['RS256'],
+  publicKey: '...PEM...',
+});
+```
+
+### 주체 정규화 (Principal Normalization)
+
+`@fluojs/jwt`는 `scope` (문자열)와 `scopes` (배열) 클레임을 자동으로 감지하여 `JwtPrincipal`의 단일 `scopes: string[]` 속성으로 통합합니다. 이를 통해 권한 가드에서 일관된 로직을 적용할 수 있습니다.
+
+### 원격 JWKS 검증
+
+검증 키를 원격 JWKS 엔드포인트에서 가져올 때는, 느리거나 멈춘 identity provider 때문에 인증 경로가 무한정 대기하지 않도록 fetch budget을 명시적으로 제한하세요.
+
+```typescript
+const verifier = new DefaultJwtVerifier({
+  algorithms: ['RS256'],
+  jwksRequestTimeoutMs: 5_000,
+  jwksUri: 'https://issuer.example.com/.well-known/jwks.json',
+});
+```
+
+`jwksRequestTimeoutMs`의 기본값은 `5_000`이며, 예산을 넘기면 진행 중인 JWKS fetch를 abort합니다.
+
+## 공개 API 개요
+
+### 주요 클래스
+- `JwtModule`: DI 등록을 위한 기본 진입점입니다.
+- `DefaultJwtSigner`: 클레임 자동 채우기 기능이 포함된 토큰 발행 클래스입니다.
+- `DefaultJwtVerifier`: 토큰 검증 및 정규화를 담당하는 클래스입니다.
+- `JwtService`: 서명과 검증 기능을 결합한 편의용 파사드(facade)입니다.
+
+### 타입
+- `JwtPrincipal`: 정규화된 사용자 식별 객체 (`subject`, `roles`, `scopes`, `claims`).
+- `JwtVerifierOptions`: 알고리즘, 키, 검증 정책 설정을 위한 타입입니다.
+
+## 관련 패키지
+
+- `@fluojs/passport`: 이 코어 패키지를 사용하여 가드와 전략을 실행하는 인증 계층입니다.
+- `@fluojs/config`: 환경별로 비밀 키와 JWT 옵션을 관리할 때 권장되는 패키지입니다.
+
+## 예제 소스
+
+- `packages/jwt/src/module.test.ts`: 모듈 등록 및 DI 패턴 예제.
+- `packages/jwt/src/signing/signer.test.ts`: 토큰 서명 예제.
+- `examples/auth-jwt-passport/src/auth/auth.service.ts`: 실제 토큰 발행 구현 예제.

package/README.md

@@ -0,0 +1,169 @@
+# @fluojs/jwt
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+HTTP-agnostic JWT token core that handles signing access tokens and verifying them into a normalized `JwtPrincipal`.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/jwt
+```
+
+## When to Use
+
+- When you need to issue or verify JWT access tokens in a backend application.
+- When you want a stable `JwtPrincipal` shape (subject, roles, scopes) regardless of the underlying token claim variants.
+- When implementing refresh token rotation with replay detection.
+
+## Quick Start
+
+### Register the Module
+
+Configure the JWT module with your signing keys and policy.
+
+Import JWT support through `JwtModule.forRoot(...)` or `JwtModule.forRootAsync(...)`.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { JwtModule } from '@fluojs/jwt';
+
+@Module({
+  imports: [
+    JwtModule.forRoot({
+      algorithms: ['HS256'],
+      secret: 'your-secure-secret',
+      issuer: 'my-api',
+      audience: 'my-app',
+      accessTokenTtlSeconds: 3600,
+    }),
+  ],
+})
+export class AuthModule {}
+```
+
+### Async Registration with Injected Settings
+
+Use `JwtModule.forRootAsync(...)` when your JWT settings must come from another provider and still need to resolve into the standard module contract.
+
+```typescript
+import { Module, type Token } from '@fluojs/core';
+import { JwtModule } from '@fluojs/jwt';
+
+const JWT_SETTINGS = Symbol('jwt-settings');
+
+@Module({
+  imports: [
+    JwtModule.forRootAsync({
+      inject: [JWT_SETTINGS],
+      useFactory: async (settings) => ({
+        accessTokenTtlSeconds: 900,
+        algorithms: ['HS256'],
+        audience: 'my-app',
+        issuer: settings.issuer,
+        secret: settings.secret,
+      }),
+    }),
+  ],
+  providers: [
+    {
+      provide: JWT_SETTINGS as Token<{ issuer: string; secret: string }>,
+      useValue: {
+        issuer: 'my-api',
+        secret: 'your-secure-secret',
+      },
+    },
+  ],
+})
+export class AuthModule {}
+```
+
+### Sign and Verify Tokens
+
+Inject `DefaultJwtSigner` to issue tokens and `DefaultJwtVerifier` to validate them.
+
+```typescript
+import { DefaultJwtSigner, DefaultJwtVerifier } from '@fluojs/jwt';
+
+// Sign
+const token = await signer.signAccessToken({
+  sub: 'user-123',
+  roles: ['admin'],
+  scopes: ['read:profile'],
+});
+
+// Verify
+const principal = await verifier.verifyAccessToken(token);
+// principal: { subject: 'user-123', roles: ['admin'], scopes: ['read:profile'], ... }
+```
+
+When you use `JwtService.sign(payload, { expiresIn })`, the per-call `expiresIn` override always wins over any pre-existing `payload.exp` value so token lifetime stays deterministic at the call site.
+
+## Common Patterns
+
+### Asymmetric Signing (RS256/ES256)
+
+Use public/private key pairs for enhanced security across distributed systems.
+
+```typescript
+const signer = new DefaultJwtSigner({
+  algorithms: ['RS256'],
+  privateKey: '...PEM...',
+});
+
+const verifier = new DefaultJwtVerifier({
+  algorithms: ['RS256'],
+  publicKey: '...PEM...',
+});
+```
+
+### Principal Normalization
+
+`@fluojs/jwt` automatically unifies `scope` (string) and `scopes` (array) claims into a single `scopes: string[]` property in the `JwtPrincipal`, ensuring consistent behavior for authorization guards.
+
+### Remote JWKS verification
+
+When verification keys come from a remote JWKS endpoint, keep the fetch path bounded so auth traffic cannot hang on a slow or stalled identity provider.
+
+```typescript
+const verifier = new DefaultJwtVerifier({
+  algorithms: ['RS256'],
+  jwksRequestTimeoutMs: 5_000,
+  jwksUri: 'https://issuer.example.com/.well-known/jwks.json',
+});
+```
+
+`jwksRequestTimeoutMs` defaults to `5_000` and aborts the outbound JWKS fetch once that budget is exceeded.
+
+## Public API Overview
+
+### Core Classes
+- `JwtModule`: The main entry point for DI registration.
+- `DefaultJwtSigner`: Handles token issuance with default claim filling.
+- `DefaultJwtVerifier`: Handles token validation and normalization.
+- `JwtService`: A convenience facade combining signing and verification.
+
+### Types
+- `JwtPrincipal`: The normalized identity object (`subject`, `roles`, `scopes`, `claims`).
+- `JwtVerifierOptions`: Configuration for algorithms, keys, and validation policy.
+
+## Related Packages
+
+- `@fluojs/passport`: The auth execution layer that uses this core for guards and strategies.
+- `@fluojs/config`: Recommended for managing secrets and JWT options across environments.
+
+## Example Sources
+
+- `packages/jwt/src/module.test.ts`: Module registration and DI patterns.
+- `packages/jwt/src/signing/signer.test.ts`: Token signing examples.
+- `examples/auth-jwt-passport/src/auth/auth.service.ts`: Real-world token issuance.

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+import { FluoError } from '@fluojs/core';
+/**
+ * Error thrown when JWT verification fails due to signature or structural issues.
+ */
+export declare class JwtVerificationError extends FluoError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        code?: string;
+    });
+}
+/**
+ * Error thrown when a provided JWT string is malformed or not a valid token.
+ */
+export declare class JwtInvalidTokenError extends JwtVerificationError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a JWT is valid but has exceeded its expiration time.
+ */
+export declare class JwtExpiredTokenError extends JwtVerificationError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the JWT module is misconfigured (e.g. missing keys).
+ */
+export declare class JwtConfigurationError extends FluoError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAM9E;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,oBAAoB;gBAChD,OAAO,SAAiB;CAGrC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,oBAAoB;gBAChD,OAAO,SAAqB;CAGzC;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,OAAO,EAAE,MAAM;CAG5B"}

package/dist/errors.js

@@ -0,0 +1,46 @@
+import { FluoError } from '@fluojs/core';
+
+/**
+ * Error thrown when JWT verification fails due to signature or structural issues.
+ */
+export class JwtVerificationError extends FluoError {
+  constructor(message, options = {}) {
+    super(message, {
+      cause: options.cause,
+      code: options.code ?? 'JWT_VERIFICATION_ERROR'
+    });
+  }
+}
+
+/**
+ * Error thrown when a provided JWT string is malformed or not a valid token.
+ */
+export class JwtInvalidTokenError extends JwtVerificationError {
+  constructor(message = 'Invalid JWT.') {
+    super(message, {
+      code: 'JWT_INVALID_TOKEN'
+    });
+  }
+}
+
+/**
+ * Error thrown when a JWT is valid but has exceeded its expiration time.
+ */
+export class JwtExpiredTokenError extends JwtVerificationError {
+  constructor(message = 'JWT has expired.') {
+    super(message, {
+      code: 'JWT_EXPIRED'
+    });
+  }
+}
+
+/**
+ * Error thrown when the JWT module is misconfigured (e.g. missing keys).
+ */
+export class JwtConfigurationError extends FluoError {
+  constructor(message) {
+    super(message, {
+      code: 'JWT_CONFIGURATION_ERROR'
+    });
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './errors.js';
+export * from './signing/jwks.js';
+export * from './module.js';
+export * from './refresh/refresh-token.js';
+export * from './service.js';
+export * from './signing/signer.js';
+export * from './status.js';
+export * from './types.js';
+export * from './signing/verifier.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './errors.js';
+export * from './signing/jwks.js';
+export * from './module.js';
+export * from './refresh/refresh-token.js';
+export * from './service.js';
+export * from './signing/signer.js';
+export * from './status.js';
+export * from './types.js';
+export * from './signing/verifier.js';

package/dist/module.d.ts

@@ -0,0 +1,13 @@
+import { type AsyncModuleOptions, type Constructor } from '@fluojs/core';
+import type { JwtVerifierOptions } from './types.js';
+type ModuleType = Constructor;
+/**
+ * Registers JWT services and optional refresh-token support for an application module.
+ */
+export declare class JwtModule {
+    static forRoot(options: JwtVerifierOptions): ModuleType;
+    static forRootAsync(options: AsyncModuleOptions<JwtVerifierOptions>): ModuleType;
+    private static createModule;
+}
+export {};
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +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"}

package/dist/module.js

@@ -0,0 +1,93 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+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';
+import { DefaultJwtSigner } from './signing/signer.js';
+import { DefaultJwtVerifier, JWT_OPTIONS } from './signing/verifier.js';
+function resolveRefreshTokenOptions(value) {
+  if (typeof value !== 'object' || value === null || !('refreshToken' in value)) {
+    throw new JwtConfigurationError('JWT refresh token options are not configured.');
+  }
+  return normalizeRefreshTokenOptions(value.refreshToken);
+}
+let _AsyncRefreshTokenSer;
+class AsyncRefreshTokenServiceRegistrar {
+  static {
+    [_AsyncRefreshTokenSer, _initClass] = _applyDecs(this, [Inject(JWT_OPTIONS, DefaultJwtSigner, DefaultJwtVerifier, RUNTIME_CONTAINER)], []).c;
+  }
+  registered = false;
+  constructor(options, signer, verifier, container) {
+    this.options = options;
+    this.signer = signer;
+    this.verifier = verifier;
+    this.container = container;
+  }
+  onModuleInit() {
+    if (!this.options.refreshToken || this.registered) {
+      return;
+    }
+    const refreshTokenOptions = resolveRefreshTokenOptions(this.options);
+    this.container.register({
+      provide: RefreshTokenService,
+      scope: 'transient',
+      useFactory: () => new RefreshTokenService(refreshTokenOptions, this.signer, this.verifier)
+    });
+    this.registered = true;
+  }
+  static {
+    _initClass();
+  }
+}
+function createJwtModuleProviders(optionsProvider, includeRefreshTokenService, refreshTokenServiceScope, deferRefreshTokenServiceRegistration = false) {
+  const providers = [optionsProvider, DefaultJwtVerifier, DefaultJwtSigner, JwtService];
+  if (includeRefreshTokenService) {
+    providers.push(deferRefreshTokenServiceRegistration ? _AsyncRefreshTokenSer : {
+      inject: [JWT_OPTIONS, DefaultJwtSigner, DefaultJwtVerifier],
+      provide: RefreshTokenService,
+      scope: refreshTokenServiceScope,
+      useFactory: (...deps) => {
+        const [options, signer, verifier] = deps;
+        const refreshTokenOptions = resolveRefreshTokenOptions(options);
+        return new RefreshTokenService(refreshTokenOptions, signer, verifier);
+      }
+    });
+  }
+  return providers;
+}
+
+/**
+ * Registers JWT services and optional refresh-token support for an application module.
+ */
+export class JwtModule {
+  static forRoot(options) {
+    return this.createModule({
+      provide: JWT_OPTIONS,
+      scope: 'singleton',
+      useValue: options
+    }, Boolean(options.refreshToken), Boolean(options.refreshToken), 'singleton');
+  }
+  static forRootAsync(options) {
+    return this.createModule({
+      inject: options.inject,
+      provide: JWT_OPTIONS,
+      scope: 'singleton',
+      useFactory: options.useFactory
+    }, true, false, 'transient', true);
+  }
+  static createModule(optionsProvider, includeRefreshTokenProvider, includeRefreshTokenExport, refreshTokenServiceScope, deferRefreshTokenServiceRegistration = false) {
+    class JwtRuntimeModule {}
+    defineModuleMetadata(JwtRuntimeModule, {
+      exports: [JwtService, DefaultJwtVerifier, DefaultJwtSigner, ...(includeRefreshTokenExport ? [RefreshTokenService] : [])],
+      providers: createJwtModuleProviders(optionsProvider, includeRefreshTokenProvider, refreshTokenServiceScope, deferRefreshTokenServiceRegistration)
+    });
+    return JwtRuntimeModule;
+  }
+}

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

@@ -0,0 +1,48 @@
+import type { DefaultJwtSigner } from '../signing/signer.js';
+import type { DefaultJwtVerifier } from '../signing/verifier.js';
+export interface RefreshTokenStore {
+    save(token: RefreshTokenRecord): Promise<void>;
+    find(tokenId: string): Promise<RefreshTokenRecord | undefined>;
+    revoke(tokenId: string): Promise<void>;
+    revokeBySubject(subject: string): Promise<void>;
+    consume?(input: RefreshTokenConsumeInput): Promise<RefreshTokenConsumeResult>;
+}
+export interface RefreshTokenConsumeInput {
+    tokenId: string;
+    subject: string;
+    family: string;
+    now: Date;
+}
+export type RefreshTokenConsumeResult = 'consumed' | 'already_used' | 'expired' | 'not_found' | 'mismatch' | 'invalid';
+export interface RefreshTokenRecord {
+    id: string;
+    subject: string;
+    family: string;
+    expiresAt: Date;
+    used: boolean;
+    createdAt: Date;
+}
+export interface RefreshTokenOptions {
+    secret: string;
+    expiresInSeconds: number;
+    verifyMaxAgeSeconds?: number;
+    rotation: boolean;
+    store: RefreshTokenStore;
+}
+export declare function normalizeRefreshTokenOptions(options: RefreshTokenOptions | undefined): RefreshTokenOptions;
+export declare class RefreshTokenService {
+    private readonly signer;
+    private readonly verifier;
+    private readonly options;
+    constructor(options: RefreshTokenOptions, signer: DefaultJwtSigner, verifier: DefaultJwtVerifier);
+    issueRefreshToken(subject: string): Promise<string>;
+    rotateRefreshToken(currentToken: string): Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    revokeRefreshToken(tokenId: string): Promise<void>;
+    revokeAllForSubject(subject: string): Promise<void>;
+    private issueRefreshTokenWithFamily;
+    private verifyRefreshClaims;
+}
+//# sourceMappingURL=refresh-token.d.ts.map

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

@@ -0,0 +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"}