@fluojs/passport 1.0.0-beta.1

package/dist/module.d.ts

@@ -0,0 +1,36 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { AuthStrategyRegistration, PassportModuleOptions } from './types.js';
+type PassportModuleType = ModuleType;
+/**
+ * Canonical module-first entrypoint for passport strategy wiring.
+ */
+export declare class PassportModule {
+    /**
+     * Registers passport options, the auth strategy registry, and {@link AuthGuard}.
+     *
+     * @param options Module-level auth defaults such as `defaultStrategy`.
+     * @param strategies Named strategy registrations exposed to `@UseAuth(...)` and the fallback default strategy.
+     * @returns A module definition that exports `AuthGuard` and keeps the strategy registry internal.
+     * @throws {AuthStrategyResolutionError} When duplicate strategy names are registered.
+     *
+     * @example
+     * ```ts
+     * import { Module } from '@fluojs/core';
+     * import { PassportModule } from '@fluojs/passport';
+     *
+     * @Module({
+     *   imports: [
+     *     PassportModule.forRoot(
+     *       { defaultStrategy: 'jwt' },
+     *       [{ name: 'jwt', token: JwtStrategy }],
+     *     ),
+     *   ],
+     *   providers: [JwtStrategy],
+     * })
+     * export class AuthModule {}
+     * ```
+     */
+    static forRoot(options?: PassportModuleOptions, strategies?: AuthStrategyRegistration[]): PassportModuleType;
+}
+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":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EACV,wBAAwB,EAExB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAgBpB,KAAK,kBAAkB,GAAG,UAAU,CAAC;AAmBrC;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,OAAO,CACZ,OAAO,GAAE,qBAA0B,EACnC,UAAU,GAAE,wBAAwB,EAAO,GAC1C,kBAAkB;CAQtB"}

package/dist/module.js

@@ -0,0 +1,63 @@
+import { defineModule } from '@fluojs/runtime';
+import { AuthStrategyResolutionError } from './errors.js';
+import { AuthGuard } from './guard.js';
+import { AUTH_STRATEGY_REGISTRY, PASSPORT_OPTIONS } from './internal-tokens.js';
+function createStrategyRegistry(strategies) {
+  const registry = Object.create(null);
+  for (const strategy of strategies) {
+    if (Object.hasOwn(registry, strategy.name)) {
+      throw new AuthStrategyResolutionError(`Duplicate auth strategy registration for "${strategy.name}".`);
+    }
+    registry[strategy.name] = strategy.token;
+  }
+  return registry;
+}
+function createPassportModuleProviders(options = {}, strategies = []) {
+  return [{
+    provide: PASSPORT_OPTIONS,
+    useValue: {
+      ...options
+    }
+  }, {
+    provide: AUTH_STRATEGY_REGISTRY,
+    useValue: createStrategyRegistry(strategies)
+  }, AuthGuard];
+}
+
+/**
+ * Canonical module-first entrypoint for passport strategy wiring.
+ */
+export class PassportModule {
+  /**
+   * Registers passport options, the auth strategy registry, and {@link AuthGuard}.
+   *
+   * @param options Module-level auth defaults such as `defaultStrategy`.
+   * @param strategies Named strategy registrations exposed to `@UseAuth(...)` and the fallback default strategy.
+   * @returns A module definition that exports `AuthGuard` and keeps the strategy registry internal.
+   * @throws {AuthStrategyResolutionError} When duplicate strategy names are registered.
+   *
+   * @example
+   * ```ts
+   * import { Module } from '@fluojs/core';
+   * import { PassportModule } from '@fluojs/passport';
+   *
+   * @Module({
+   *   imports: [
+   *     PassportModule.forRoot(
+   *       { defaultStrategy: 'jwt' },
+   *       [{ name: 'jwt', token: JwtStrategy }],
+   *     ),
+   *   ],
+   *   providers: [JwtStrategy],
+   * })
+   * export class AuthModule {}
+   * ```
+   */
+  static forRoot(options = {}, strategies = []) {
+    class PassportRootModule extends PassportModule {}
+    return defineModule(PassportRootModule, {
+      exports: [AuthGuard],
+      providers: createPassportModuleProviders(options, strategies)
+    });
+  }
+}

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

@@ -0,0 +1,30 @@
+import { DefaultJwtSigner, DefaultJwtVerifier, type RefreshTokenStore } from '@fluojs/jwt';
+import type { RefreshTokenService } from './refresh-token.js';
+/**
+ * Provides refresh-token module options through dependency injection.
+ */
+export declare const REFRESH_TOKEN_MODULE_OPTIONS: unique symbol;
+/**
+ * Configures refresh-token storage, rotation, and secret material.
+ */
+export interface RefreshTokenModuleOptions {
+    expiresInSeconds?: number;
+    rotation?: boolean;
+    secret: string;
+    store: RefreshTokenStore | 'memory';
+}
+/**
+ * Bridges JWT refresh-token primitives into the passport refresh-token service contract.
+ */
+export declare class JwtRefreshTokenAdapter implements RefreshTokenService {
+    private readonly service;
+    constructor(signer: DefaultJwtSigner, verifier: DefaultJwtVerifier, options: RefreshTokenModuleOptions);
+    issueRefreshToken(subject: string): Promise<string>;
+    rotateRefreshToken(currentToken: string): Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    revokeRefreshToken(tokenId: string): Promise<void>;
+    revokeAllForSubject(subject: string): Promise<void>;
+}
+//# sourceMappingURL=jwt-refresh-token-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-refresh-token-adapter.d.ts","sourceRoot":"","sources":["../../src/refresh/jwt-refresh-token-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAGlB,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,4BAA4B,eAA2D,CAAC;AAErG;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,iBAAiB,GAAG,QAAQ,CAAC;CACrC;AA2ED;;GAEG;AACH,qBACa,sBAAuB,YAAW,mBAAmB;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAG/C,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,yBAAyB;IAuB9B,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAIhG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1D"}

package/dist/refresh/jwt-refresh-token-adapter.js

@@ -0,0 +1,103 @@
+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 { DefaultJwtSigner, DefaultJwtVerifier, JwtConfigurationError, RefreshTokenService as JwtRefreshTokenService } from '@fluojs/jwt';
+/**
+ * Provides refresh-token module options through dependency injection.
+ */
+export const REFRESH_TOKEN_MODULE_OPTIONS = Symbol.for('fluo.passport.refresh-token-module-options');
+
+/**
+ * Configures refresh-token storage, rotation, and secret material.
+ */
+
+function resolveSecret(options) {
+  if (!options.secret) {
+    throw new JwtConfigurationError('Refresh token secret is not configured. Provide it via RefreshTokenModuleOptions.secret.');
+  }
+  return options.secret;
+}
+function createInMemoryStore() {
+  const records = new Map();
+  return {
+    async save(token) {
+      records.set(token.id, token);
+    },
+    async find(tokenId) {
+      return records.get(tokenId);
+    },
+    async revoke(tokenId) {
+      records.delete(tokenId);
+    },
+    async revokeBySubject(subject) {
+      for (const [id, record] of records.entries()) {
+        if (record.subject === subject) {
+          records.delete(id);
+        }
+      }
+    },
+    async consume(input) {
+      const record = records.get(input.tokenId);
+      if (!record) {
+        return 'invalid';
+      }
+      if (record.subject !== input.subject || record.family !== input.family) {
+        return 'invalid';
+      }
+      if (record.expiresAt.getTime() <= input.now.getTime()) {
+        return 'expired';
+      }
+      if (record.used) {
+        return 'already_used';
+      }
+      records.set(input.tokenId, {
+        ...record,
+        used: true
+      });
+      return 'consumed';
+    }
+  };
+}
+
+/**
+ * Bridges JWT refresh-token primitives into the passport refresh-token service contract.
+ */
+let _JwtRefreshTokenAdapt;
+class JwtRefreshTokenAdapter {
+  static {
+    [_JwtRefreshTokenAdapt, _initClass] = _applyDecs(this, [Inject(DefaultJwtSigner, DefaultJwtVerifier, REFRESH_TOKEN_MODULE_OPTIONS)], []).c;
+  }
+  service;
+  constructor(signer, verifier, options) {
+    if (!options.store) {
+      throw new JwtConfigurationError('JwtRefreshTokenAdapter requires a persistent RefreshTokenStore. ' + 'Provide one via RefreshTokenModuleOptions.store, or pass store: \'memory\' to explicitly opt into the in-memory store (single-instance / development only).');
+    }
+    const store = options.store === 'memory' ? createInMemoryStore() : options.store;
+    this.service = new JwtRefreshTokenService({
+      expiresInSeconds: options.expiresInSeconds ?? 604800,
+      rotation: options.rotation ?? true,
+      secret: resolveSecret(options),
+      store
+    }, signer, verifier);
+  }
+  async issueRefreshToken(subject) {
+    return this.service.issueRefreshToken(subject);
+  }
+  async rotateRefreshToken(currentToken) {
+    return this.service.rotateRefreshToken(currentToken);
+  }
+  async revokeRefreshToken(tokenId) {
+    return this.service.revokeRefreshToken(tokenId);
+  }
+  async revokeAllForSubject(subject) {
+    return this.service.revokeAllForSubject(subject);
+  }
+  static {
+    _initClass();
+  }
+}
+export { _JwtRefreshTokenAdapt as JwtRefreshTokenAdapter };

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

@@ -0,0 +1,96 @@
+import type { GuardContext } from '@fluojs/http';
+import { type Token } from '@fluojs/core';
+import { DefaultJwtVerifier } from '@fluojs/jwt';
+import { type ModuleType } from '@fluojs/runtime';
+import type { AuthStrategy, AuthStrategyRegistration, AuthStrategyResult } from '../types.js';
+/**
+ * Defines the operations required to issue, rotate, and revoke refresh tokens.
+ */
+export interface RefreshTokenService {
+    issueRefreshToken(subject: string): Promise<string>;
+    rotateRefreshToken(currentToken: string): Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    revokeRefreshToken(tokenId: string): Promise<void>;
+    revokeAllForSubject(subject: string): Promise<void>;
+}
+/**
+ * Identifies the active refresh-token service implementation in dependency injection.
+ */
+export declare const REFRESH_TOKEN_SERVICE: unique symbol;
+/**
+ * Represents the refresh-token payload accepted by refresh endpoints.
+ */
+export interface RefreshTokenInput {
+    refreshToken: string;
+}
+/**
+ * Captures the token pair returned after a successful refresh-token exchange.
+ */
+export interface RefreshTokenAuthResult {
+    accessToken: string;
+    refreshToken: string;
+    subject: string;
+}
+/**
+ * Identifies the built-in refresh-token authentication strategy.
+ */
+export declare const REFRESH_TOKEN_STRATEGY_NAME = "refresh-token";
+type RefreshTokenModuleType = ModuleType;
+/**
+ * Authenticates refresh-token requests and exchanges them for a fresh token pair.
+ */
+export declare class RefreshTokenStrategy implements AuthStrategy {
+    private readonly refreshTokenService;
+    private readonly verifier;
+    constructor(refreshTokenService: RefreshTokenService, verifier: DefaultJwtVerifier);
+    authenticate(context: GuardContext): Promise<AuthStrategyResult>;
+    private rotateRefreshToken;
+    private extractRefreshToken;
+    private normalizeRefreshToken;
+    private extractVerifiedSubject;
+}
+/**
+ * Creates the passport strategy registration for the built-in refresh-token strategy.
+ *
+ * @returns The named strategy registration consumed by `PassportModule.forRoot(...)`.
+ */
+export declare function createRefreshTokenStrategyRegistration(): AuthStrategyRegistration;
+/**
+ * Canonical module-first entrypoint for refresh-token strategy support.
+ */
+export declare class RefreshTokenModule {
+    /**
+     * Registers the shared refresh-token service alias together with `RefreshTokenStrategy`.
+     *
+     * @param service DI token for the concrete refresh-token service implementation.
+     * @returns A module definition that exports `RefreshTokenStrategy` and `REFRESH_TOKEN_SERVICE`.
+     *
+     * @example
+     * ```ts
+     * import { Module } from '@fluojs/core';
+     * import {
+     *   PassportModule,
+     *   RefreshTokenModule,
+     *   RefreshTokenStrategy,
+     *   REFRESH_TOKEN_STRATEGY_NAME,
+     * } from '@fluojs/passport';
+     *
+     * @Module({
+     *   imports: [
+     *     RefreshTokenModule.forRoot(MyRefreshTokenService),
+     *     PassportModule.forRoot(
+     *       { defaultStrategy: REFRESH_TOKEN_STRATEGY_NAME },
+     *       [{ name: REFRESH_TOKEN_STRATEGY_NAME, token: RefreshTokenStrategy }],
+     *     ),
+     *   ],
+     *   providers: [MyRefreshTokenService],
+     * })
+     * export class AuthModule {}
+     * ```
+     */
+    static forRoot(service: Token<RefreshTokenService>): RefreshTokenModuleType;
+}
+export {};
+//# 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":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,cAAc,CAAC;AACjE,OAAO,EAA0B,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAElE,OAAO,EAAE,kBAAkB,EAA8C,MAAM,aAAa,CAAC;AAC7F,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOhE,OAAO,KAAK,EAAE,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE9F;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAAoD,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,kBAAkB,CAAC;AAI3D,KAAK,sBAAsB,GAAG,UAAU,CAAC;AAEzC;;GAEG;AACH,qBACa,oBAAqB,YAAW,YAAY;IAErD,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,mBAAmB,EAAE,mBAAmB,EACxC,QAAQ,EAAE,kBAAkB;IAGzC,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAwBxD,kBAAkB;IAmBhC,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,qBAAqB;YAYf,sBAAsB;CAQrC;AAaD;;;;GAIG;AACH,wBAAgB,sCAAsC,IAAI,wBAAwB,CAKjF;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAC,GAAG,sBAAsB;CAQ5E"}

package/dist/refresh/refresh-token.js

@@ -0,0 +1,178 @@
+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, InvariantError } from '@fluojs/core';
+import { DefaultJwtVerifier, JwtExpiredTokenError, JwtInvalidTokenError } from '@fluojs/jwt';
+import { defineModule } from '@fluojs/runtime';
+import { AuthenticationExpiredError, AuthenticationFailedError, AuthenticationRequiredError } from '../errors.js';
+
+/**
+ * Defines the operations required to issue, rotate, and revoke refresh tokens.
+ */
+
+/**
+ * Identifies the active refresh-token service implementation in dependency injection.
+ */
+export const REFRESH_TOKEN_SERVICE = Symbol.for('fluo.passport.refresh-token-service');
+
+/**
+ * Represents the refresh-token payload accepted by refresh endpoints.
+ */
+
+/**
+ * Captures the token pair returned after a successful refresh-token exchange.
+ */
+
+/**
+ * Identifies the built-in refresh-token authentication strategy.
+ */
+export const REFRESH_TOKEN_STRATEGY_NAME = 'refresh-token';
+const MALFORMED_REFRESH_TOKEN = Symbol('MALFORMED_REFRESH_TOKEN');
+let _RefreshTokenStrategy;
+/**
+ * Authenticates refresh-token requests and exchanges them for a fresh token pair.
+ */
+class RefreshTokenStrategy {
+  static {
+    [_RefreshTokenStrategy, _initClass] = _applyDecs(this, [Inject(REFRESH_TOKEN_SERVICE, DefaultJwtVerifier)], []).c;
+  }
+  constructor(refreshTokenService, verifier) {
+    this.refreshTokenService = refreshTokenService;
+    this.verifier = verifier;
+  }
+  async authenticate(context) {
+    const request = context.requestContext.request;
+    const refreshToken = this.extractRefreshToken(request);
+    if (refreshToken === MALFORMED_REFRESH_TOKEN) {
+      throw new AuthenticationFailedError('Refresh token is malformed.');
+    }
+    if (!refreshToken) {
+      throw new AuthenticationRequiredError('Refresh token is required.');
+    }
+    const result = await this.rotateRefreshToken(refreshToken);
+    const subject = await this.extractVerifiedSubject(result.accessToken);
+    return {
+      claims: {
+        accessToken: result.accessToken,
+        refreshToken: result.refreshToken
+      },
+      subject
+    };
+  }
+  async rotateRefreshToken(currentToken) {
+    try {
+      return await this.refreshTokenService.rotateRefreshToken(currentToken);
+    } catch (error) {
+      if (error instanceof AuthenticationRequiredError || error instanceof AuthenticationExpiredError || error instanceof AuthenticationFailedError) {
+        throw error;
+      }
+      if (error instanceof JwtExpiredTokenError) {
+        throw new AuthenticationExpiredError('Refresh token has expired.', {
+          cause: error
+        });
+      }
+      if (error instanceof JwtInvalidTokenError) {
+        throw new AuthenticationFailedError('Refresh token is invalid or has been reused.', {
+          cause: error
+        });
+      }
+      throw error;
+    }
+  }
+  extractRefreshToken(request) {
+    if (request.body && typeof request.body === 'object' && 'refreshToken' in request.body) {
+      return this.normalizeRefreshToken(request.body.refreshToken);
+    }
+    const authHeaderRaw = request.headers?.authorization;
+    const authHeader = Array.isArray(authHeaderRaw) ? authHeaderRaw[0] : authHeaderRaw;
+    if (authHeader?.toLowerCase().startsWith('bearer ')) {
+      return this.normalizeRefreshToken(authHeader.slice(7));
+    }
+    const customHeader = request.headers?.['x-refresh-token'];
+    return this.normalizeRefreshToken(Array.isArray(customHeader) ? customHeader[0] : customHeader);
+  }
+  normalizeRefreshToken(token) {
+    if (token === undefined || token === null) {
+      return undefined;
+    }
+    if (typeof token !== 'string') {
+      return MALFORMED_REFRESH_TOKEN;
+    }
+    return token.length > 0 ? token : undefined;
+  }
+  async extractVerifiedSubject(accessToken) {
+    const principal = await this.verifier.verifyAccessToken(accessToken);
+    const sub = principal.claims.sub;
+    if (typeof sub !== 'string' || sub.length === 0) {
+      throw new InvariantError('Refresh token service returned an access token without a valid subject claim.');
+    }
+    return sub;
+  }
+  static {
+    _initClass();
+  }
+}
+export { _RefreshTokenStrategy as RefreshTokenStrategy };
+function createRefreshTokenAliasProviders(service) {
+  return [{
+    provide: REFRESH_TOKEN_SERVICE,
+    useExisting: service
+  }];
+}
+
+/**
+ * Creates the passport strategy registration for the built-in refresh-token strategy.
+ *
+ * @returns The named strategy registration consumed by `PassportModule.forRoot(...)`.
+ */
+export function createRefreshTokenStrategyRegistration() {
+  return {
+    name: REFRESH_TOKEN_STRATEGY_NAME,
+    token: _RefreshTokenStrategy
+  };
+}
+
+/**
+ * Canonical module-first entrypoint for refresh-token strategy support.
+ */
+export class RefreshTokenModule {
+  /**
+   * Registers the shared refresh-token service alias together with `RefreshTokenStrategy`.
+   *
+   * @param service DI token for the concrete refresh-token service implementation.
+   * @returns A module definition that exports `RefreshTokenStrategy` and `REFRESH_TOKEN_SERVICE`.
+   *
+   * @example
+   * ```ts
+   * import { Module } from '@fluojs/core';
+   * import {
+   *   PassportModule,
+   *   RefreshTokenModule,
+   *   RefreshTokenStrategy,
+   *   REFRESH_TOKEN_STRATEGY_NAME,
+   * } from '@fluojs/passport';
+   *
+   * @Module({
+   *   imports: [
+   *     RefreshTokenModule.forRoot(MyRefreshTokenService),
+   *     PassportModule.forRoot(
+   *       { defaultStrategy: REFRESH_TOKEN_STRATEGY_NAME },
+   *       [{ name: REFRESH_TOKEN_STRATEGY_NAME, token: RefreshTokenStrategy }],
+   *     ),
+   *   ],
+   *   providers: [MyRefreshTokenService],
+   * })
+   * export class AuthModule {}
+   * ```
+   */
+  static forRoot(service) {
+    class RefreshTokenRuntimeModule extends RefreshTokenModule {}
+    return defineModule(RefreshTokenRuntimeModule, {
+      exports: [_RefreshTokenStrategy, REFRESH_TOKEN_SERVICE],
+      providers: [_RefreshTokenStrategy, ...createRefreshTokenAliasProviders(service)]
+    });
+  }
+}

package/dist/scope.d.ts

@@ -0,0 +1,5 @@
+import type { AuthRequirement } from './types.js';
+export declare function normalizeDeclaredScopes(scopes: unknown): string[] | undefined;
+export declare function normalizePrincipalScopes(claims: Record<string, unknown>): string[] | undefined;
+export declare function mergeAuthRequirements(base: AuthRequirement | undefined, extra: AuthRequirement | undefined): AuthRequirement | undefined;
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAoBlD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAO7E;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,SAAS,CAW9F;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,GAAG,SAAS,EACjC,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,eAAe,GAAG,SAAS,CAgB7B"}

package/dist/scope.js

@@ -0,0 +1,44 @@
+function normalizeScopeItems(items) {
+  const seen = new Set();
+  const normalized = [];
+  for (const item of items) {
+    const scope = item.trim();
+    if (scope.length === 0 || seen.has(scope)) {
+      continue;
+    }
+    seen.add(scope);
+    normalized.push(scope);
+  }
+  return normalized.length > 0 ? normalized : undefined;
+}
+export function normalizeDeclaredScopes(scopes) {
+  if (!Array.isArray(scopes)) {
+    return undefined;
+  }
+  const scopeItems = scopes.filter(scope => typeof scope === 'string');
+  return normalizeScopeItems(scopeItems);
+}
+export function normalizePrincipalScopes(claims) {
+  if (Array.isArray(claims.scopes)) {
+    const scopes = claims.scopes.filter(scope => typeof scope === 'string');
+    return normalizeScopeItems(scopes);
+  }
+  if (typeof claims.scope === 'string') {
+    return normalizeScopeItems(claims.scope.split(/\s+/));
+  }
+  return undefined;
+}
+export function mergeAuthRequirements(base, extra) {
+  if (!base && !extra) {
+    return undefined;
+  }
+  const scopes = normalizeDeclaredScopes([...(base?.scopes ?? []), ...(extra?.scopes ?? [])]);
+  const strategy = extra?.strategy ?? base?.strategy;
+  if (!strategy && !scopes) {
+    return undefined;
+  }
+  return {
+    scopes,
+    strategy
+  };
+}

package/dist/status.d.ts

@@ -0,0 +1,36 @@
+import type { PlatformDiagnosticIssue, PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/** Snapshot payload describing passport readiness, health, ownership, and diagnostic details. */
+export interface PassportPlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+/** Input contract for deriving passport platform health and readiness diagnostics. */
+export interface PassportStatusAdapterInput {
+    componentId?: string;
+    readinessCritical?: boolean;
+    registeredStrategies: string[];
+    defaultStrategy?: string;
+    cookiePresetEnabled?: boolean;
+    cookiePresetReady?: boolean;
+    refreshTokenEnabled?: boolean;
+    refreshTokenStoreReady?: boolean;
+    refreshTokenStoreReason?: string;
+    refreshTokenDependencyId?: string;
+}
+/**
+ * Creates a platform snapshot for passport strategy wiring and preset readiness.
+ *
+ * @param input Passport readiness inputs such as registered strategies, default strategy, and preset readiness flags.
+ * @returns A platform snapshot containing passport health, readiness, ownership, and structured details.
+ */
+export declare function createPassportPlatformStatusSnapshot(input: PassportStatusAdapterInput): PassportPlatformStatusSnapshot;
+/**
+ * Creates platform diagnostic issues for passport registry and preset readiness problems.
+ *
+ * @param input Passport readiness inputs such as registered strategies, default strategy, and preset readiness flags.
+ * @returns Diagnostic issues describing empty registries, strategy mismatches, and preset dependency failures.
+ */
+export declare function createPassportPlatformDiagnosticIssues(input: PassportStatusAdapterInput): PlatformDiagnosticIssue[];
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +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,iGAAiG;AACjG,MAAM,WAAW,8BAA8B;IAC7C,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,sFAAsF;AACtF,MAAM,WAAW,0BAA0B;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,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;CACnC;AAqFD;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,0BAA0B,GAAG,8BAA8B,CAsDtH;AAED;;;;;GAKG;AACH,wBAAgB,sCAAsC,CAAC,KAAK,EAAE,0BAA0B,GAAG,uBAAuB,EAAE,CAiDnH"}