@fluojs/passport 1.0.0-beta.1

package/dist/cookie/cookie-manager.js

@@ -0,0 +1,93 @@
+import { normalizeCookieAuthOptions } from './cookie-auth.js';
+export const DEFAULT_COOKIE_OPTIONS = {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'strict',
+  path: '/',
+  domain: undefined,
+  maxAge: undefined
+};
+function buildCookieHeader(name, value, options) {
+  const parts = [`${name}=${value}`];
+  if (options.maxAge !== undefined && options.maxAge >= 0) {
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+  if (options.path) {
+    parts.push(`Path=${options.path}`);
+  }
+  if (options.domain) {
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (options.secure) {
+    parts.push('Secure');
+  }
+  if (options.httpOnly) {
+    parts.push('HttpOnly');
+  }
+  if (options.sameSite) {
+    parts.push(`SameSite=${options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)}`);
+  }
+  return parts.join('; ');
+}
+function buildClearCookieHeader(name, options) {
+  return buildCookieHeader(name, '', {
+    ...options,
+    maxAge: 0
+  });
+}
+export class CookieManager {
+  options;
+  cookieOptions;
+  constructor(config) {
+    this.options = normalizeCookieAuthOptions(config);
+    this.cookieOptions = {
+      httpOnly: config?.cookieOptions?.httpOnly ?? DEFAULT_COOKIE_OPTIONS.httpOnly,
+      secure: config?.cookieOptions?.secure ?? DEFAULT_COOKIE_OPTIONS.secure,
+      sameSite: config?.cookieOptions?.sameSite ?? DEFAULT_COOKIE_OPTIONS.sameSite,
+      path: config?.cookieOptions?.path ?? DEFAULT_COOKIE_OPTIONS.path,
+      domain: config?.cookieOptions?.domain ?? DEFAULT_COOKIE_OPTIONS.domain,
+      maxAge: config?.cookieOptions?.maxAge ?? DEFAULT_COOKIE_OPTIONS.maxAge
+    };
+  }
+  setAccessTokenCookie(response, token, ttlSeconds) {
+    const cookie = buildCookieHeader(this.options.accessTokenCookieName, token, {
+      ...this.cookieOptions,
+      maxAge: ttlSeconds ?? this.cookieOptions.maxAge
+    });
+    this.appendSetCookie(response, cookie);
+  }
+  setRefreshTokenCookie(response, token, ttlSeconds) {
+    const cookie = buildCookieHeader(this.options.refreshTokenCookieName, token, {
+      ...this.cookieOptions,
+      maxAge: ttlSeconds ?? this.cookieOptions.maxAge
+    });
+    this.appendSetCookie(response, cookie);
+  }
+  clearAccessTokenCookie(response) {
+    const cookie = buildClearCookieHeader(this.options.accessTokenCookieName, this.cookieOptions);
+    this.appendSetCookie(response, cookie);
+  }
+  clearRefreshTokenCookie(response) {
+    const cookie = buildClearCookieHeader(this.options.refreshTokenCookieName, this.cookieOptions);
+    this.appendSetCookie(response, cookie);
+  }
+  clearAllCookies(response) {
+    this.clearAccessTokenCookie(response);
+    this.clearRefreshTokenCookie(response);
+  }
+  setAuthCookies(response, accessToken, accessTokenTtlSeconds, refreshToken, refreshTokenTtlSeconds) {
+    this.setAccessTokenCookie(response, accessToken, accessTokenTtlSeconds);
+    if (refreshToken) {
+      this.setRefreshTokenCookie(response, refreshToken, refreshTokenTtlSeconds);
+    }
+  }
+  appendSetCookie(response, cookie) {
+    const existingCookies = response.headers['Set-Cookie'];
+    const cookies = Array.isArray(existingCookies) ? existingCookies : existingCookies ? [existingCookies] : [];
+    cookies.push(cookie);
+    response.setHeader('Set-Cookie', cookies.length === 1 ? cookies[0] : cookies);
+  }
+}
+export function createCookieManager(config) {
+  return new CookieManager(config);
+}

package/dist/decorators.d.ts

@@ -0,0 +1,42 @@
+type StandardClassDecoratorFn = (value: Function, context: ClassDecoratorContext) => void;
+type StandardMethodDecoratorFn = (value: Function, context: ClassMethodDecoratorContext) => void;
+type ClassOrMethodDecoratorLike = StandardClassDecoratorFn & StandardMethodDecoratorFn;
+/**
+ * Declares which registered auth strategy should protect a controller or route handler.
+ *
+ * @remarks
+ * This decorator also applies {@link AuthGuard}, so callers do not need to add a
+ * separate `@UseGuards(AuthGuard)` in the common passport flow.
+ *
+ * @example
+ * ```ts
+ * @UseAuth('jwt')
+ * @Get('/profile')
+ * getProfile() {}
+ * ```
+ *
+ * @param strategy Strategy name previously registered through `PassportModule.forRoot(...)`.
+ * @returns A class-or-method decorator that stores the auth requirement metadata.
+ */
+export declare function UseAuth(strategy: string): ClassOrMethodDecoratorLike;
+/**
+ * Declares scope requirements that `AuthGuard` must enforce after authentication succeeds.
+ *
+ * @remarks
+ * Scope requirements merge with any controller-level auth metadata, so method
+ * decorators can narrow access without redefining the base strategy.
+ *
+ * @example
+ * ```ts
+ * @UseAuth('jwt')
+ * @RequireScopes('profile:read')
+ * @Get('/profile')
+ * getProfile() {}
+ * ```
+ *
+ * @param scopes Scope values that must all be present on the resolved principal.
+ * @returns A class-or-method decorator that appends scope requirements to auth metadata.
+ */
+export declare function RequireScopes(...scopes: string[]): ClassOrMethodDecoratorLike;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAQA,KAAK,wBAAwB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC1F,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AACjG,KAAK,0BAA0B,GAAG,wBAAwB,GAAG,yBAAyB,CAAC;AAuEvF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,0BAA0B,CAEpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,0BAA0B,CAE7E"}

package/dist/decorators.js

@@ -0,0 +1,95 @@
+import { UseGuards } from '@fluojs/http';
+import { AuthGuard } from './guard.js';
+import { getOwnAuthRequirement } from './metadata.js';
+import { mergeAuthRequirements } from './scope.js';
+const standardClassRequirementKey = Symbol.for('fluo.passport.standard.class-auth');
+const standardMethodRequirementKey = Symbol.for('fluo.passport.standard.method-auth');
+function isStandardClassContext(context) {
+  return typeof context === 'object' && context !== null && 'kind' in context && context.kind === 'class';
+}
+function getStandardMetadataBag(metadata) {
+  return metadata;
+}
+function defineStandardAuthRequirement(metadata, requirement, propertyKey) {
+  const bag = getStandardMetadataBag(metadata);
+  if (propertyKey === undefined) {
+    const merged = mergeAuthRequirements(bag[standardClassRequirementKey] ?? undefined, requirement);
+    if (merged) {
+      bag[standardClassRequirementKey] = merged;
+      return;
+    }
+    delete bag[standardClassRequirementKey];
+    return;
+  }
+  const current = bag[standardMethodRequirementKey];
+  const map = current ?? new Map();
+  const merged = mergeAuthRequirements(map.get(propertyKey), requirement);
+  if (merged) {
+    map.set(propertyKey, merged);
+  } else {
+    map.delete(propertyKey);
+  }
+  bag[standardMethodRequirementKey] = map;
+}
+function applyAuthRequirement(targetOrValue, contextOrPropertyKey, patch) {
+  if (isStandardClassContext(contextOrPropertyKey)) {
+    defineStandardAuthRequirement(contextOrPropertyKey.metadata, mergeAuthRequirements(getOwnAuthRequirement(targetOrValue), patch));
+    UseGuards(AuthGuard)(targetOrValue, contextOrPropertyKey);
+    return;
+  }
+  defineStandardAuthRequirement(contextOrPropertyKey.metadata, patch, contextOrPropertyKey.name);
+  UseGuards(AuthGuard)(targetOrValue, contextOrPropertyKey);
+}
+function createAuthRequirementDecorator(patch) {
+  const decorator = (targetOrValue, contextOrPropertyKey) => {
+    applyAuthRequirement(targetOrValue, contextOrPropertyKey, patch);
+  };
+  return decorator;
+}
+
+/**
+ * Declares which registered auth strategy should protect a controller or route handler.
+ *
+ * @remarks
+ * This decorator also applies {@link AuthGuard}, so callers do not need to add a
+ * separate `@UseGuards(AuthGuard)` in the common passport flow.
+ *
+ * @example
+ * ```ts
+ * @UseAuth('jwt')
+ * @Get('/profile')
+ * getProfile() {}
+ * ```
+ *
+ * @param strategy Strategy name previously registered through `PassportModule.forRoot(...)`.
+ * @returns A class-or-method decorator that stores the auth requirement metadata.
+ */
+export function UseAuth(strategy) {
+  return createAuthRequirementDecorator({
+    strategy
+  });
+}
+
+/**
+ * Declares scope requirements that `AuthGuard` must enforce after authentication succeeds.
+ *
+ * @remarks
+ * Scope requirements merge with any controller-level auth metadata, so method
+ * decorators can narrow access without redefining the base strategy.
+ *
+ * @example
+ * ```ts
+ * @UseAuth('jwt')
+ * @RequireScopes('profile:read')
+ * @Get('/profile')
+ * getProfile() {}
+ * ```
+ *
+ * @param scopes Scope values that must all be present on the resolved principal.
+ * @returns A class-or-method decorator that appends scope requirements to auth metadata.
+ */
+export function RequireScopes(...scopes) {
+  return createAuthRequirementDecorator({
+    scopes
+  });
+}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+import { FluoError, type FluoErrorOptions } from '@fluojs/core';
+/**
+ * Error thrown when a requested authentication strategy cannot be resolved.
+ */
+export declare class AuthStrategyResolutionError extends FluoError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when an anonymous user attempts to access a protected resource.
+ */
+export declare class AuthenticationRequiredError extends FluoError {
+    constructor(message?: string, options?: Omit<FluoErrorOptions, 'code'>);
+}
+/**
+ * Error thrown when authentication credentials are provided but invalid.
+ */
+export declare class AuthenticationFailedError extends FluoError {
+    constructor(message?: string, options?: Omit<FluoErrorOptions, 'code'>);
+}
+/**
+ * Error thrown when an authentication token is well-formed but expired.
+ */
+export declare class AuthenticationExpiredError extends FluoError {
+    constructor(message?: string, options?: Omit<FluoErrorOptions, 'code'>);
+}
+//# 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,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhE;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,SAAS;gBAC5C,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,SAAS;gBAC5C,OAAO,SAA6B,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;CAG/F;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;gBAC1C,OAAO,SAA2B,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;CAG7F;AAED;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;gBAC3C,OAAO,SAAsC,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;CAGxG"}

package/dist/errors.js

@@ -0,0 +1,48 @@
+import { FluoError } from '@fluojs/core';
+
+/**
+ * Error thrown when a requested authentication strategy cannot be resolved.
+ */
+export class AuthStrategyResolutionError extends FluoError {
+  constructor(message) {
+    super(message, {
+      code: 'AUTH_STRATEGY_RESOLUTION_ERROR'
+    });
+  }
+}
+
+/**
+ * Error thrown when an anonymous user attempts to access a protected resource.
+ */
+export class AuthenticationRequiredError extends FluoError {
+  constructor(message = 'Authentication required.', options = {}) {
+    super(message, {
+      ...options,
+      code: 'AUTHENTICATION_REQUIRED'
+    });
+  }
+}
+
+/**
+ * Error thrown when authentication credentials are provided but invalid.
+ */
+export class AuthenticationFailedError extends FluoError {
+  constructor(message = 'Authentication failed.', options = {}) {
+    super(message, {
+      ...options,
+      code: 'AUTHENTICATION_FAILED'
+    });
+  }
+}
+
+/**
+ * Error thrown when an authentication token is well-formed but expired.
+ */
+export class AuthenticationExpiredError extends FluoError {
+  constructor(message = 'Authentication token has expired.', options = {}) {
+    super(message, {
+      ...options,
+      code: 'AUTHENTICATION_EXPIRED'
+    });
+  }
+}

package/dist/guard.d.ts

@@ -0,0 +1,39 @@
+import { type GuardContext } from '@fluojs/http';
+import type { AuthGuardContract, AuthStrategyRegistry, PassportModuleOptions } from './types.js';
+/**
+ * HTTP guard that resolves the active auth strategy, authenticates the request,
+ * and writes the resulting principal back to `requestContext.principal`.
+ *
+ * @remarks
+ * `AuthGuard` preserves the public contract documented in `@fluojs/passport`:
+ * authentication failures become canonical `401 Unauthorized` responses, scope
+ * mismatches become `403 Forbidden`, and strategies may short-circuit the
+ * response by returning `{ handled: true }` after committing the response.
+ */
+export declare class AuthGuard implements AuthGuardContract {
+    private readonly strategies;
+    private readonly options;
+    constructor(strategies?: AuthStrategyRegistry, options?: PassportModuleOptions);
+    /**
+     * Executes the configured auth strategy for the current route and enforces any declared scopes.
+     *
+     * @example
+     * ```ts
+     * @Controller('/profile')
+     * class ProfileController {
+     *   @Get('/')
+     *   @UseAuth('jwt')
+     *   @RequireScopes('profile:read')
+     *   getProfile() {}
+     * }
+     * ```
+     *
+     * @param context HTTP guard context for the active handler invocation.
+     * @returns `true` when the request may continue through the HTTP pipeline.
+     * @throws {AuthStrategyResolutionError} When no active strategy can be determined or resolved.
+     * @throws {UnauthorizedException} When the strategy reports missing, expired, or invalid authentication.
+     * @throws {ForbiddenException} When the authenticated principal is missing required scopes.
+     */
+    canActivate(context: GuardContext): Promise<true>;
+}
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6C,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAa5F,OAAO,KAAK,EACV,iBAAiB,EAIjB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAkCpB;;;;;;;;;GASG;AACH,qBACa,SAAU,YAAW,iBAAiB;IAE/C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,UAAU,GAAE,oBAAyB,EACrC,OAAO,GAAE,qBAA0B;IAGtD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CA0DxD"}

package/dist/guard.js

@@ -0,0 +1,124 @@
+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 { ForbiddenException, UnauthorizedException } from '@fluojs/http';
+import { Inject } from '@fluojs/core';
+import { ContainerResolutionError } from '@fluojs/di';
+import { AuthenticationExpiredError, AuthenticationFailedError, AuthenticationRequiredError, AuthStrategyResolutionError } from './errors.js';
+import { AUTH_STRATEGY_REGISTRY, PASSPORT_OPTIONS } from './internal-tokens.js';
+import { getAuthRequirement } from './metadata.js';
+function isAuthHandledResult(result) {
+  return typeof result === 'object' && result !== null && 'handled' in result && result.handled === true;
+}
+function resolvePrincipal(result) {
+  if (isAuthHandledResult(result)) {
+    return result.principal;
+  }
+  return result;
+}
+function hasRequiredScopes(principal, scopes) {
+  return scopes.every(scope => principal.scopes?.includes(scope));
+}
+function isAuthenticationFailure(error) {
+  return error instanceof AuthenticationRequiredError || error instanceof AuthenticationExpiredError || error instanceof AuthenticationFailedError;
+}
+function hasRegisteredStrategy(registry, strategyName) {
+  return Object.hasOwn(registry, strategyName);
+}
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * HTTP guard that resolves the active auth strategy, authenticates the request,
+ * and writes the resulting principal back to `requestContext.principal`.
+ *
+ * @remarks
+ * `AuthGuard` preserves the public contract documented in `@fluojs/passport`:
+ * authentication failures become canonical `401 Unauthorized` responses, scope
+ * mismatches become `403 Forbidden`, and strategies may short-circuit the
+ * response by returning `{ handled: true }` after committing the response.
+ */
+let _AuthGuard;
+class AuthGuard {
+  static {
+    [_AuthGuard, _initClass] = _applyDecs(this, [Inject(AUTH_STRATEGY_REGISTRY, PASSPORT_OPTIONS)], []).c;
+  }
+  constructor(strategies = {}, options = {}) {
+    this.strategies = strategies;
+    this.options = options;
+  }
+
+  /**
+   * Executes the configured auth strategy for the current route and enforces any declared scopes.
+   *
+   * @example
+   * ```ts
+   * @Controller('/profile')
+   * class ProfileController {
+   *   @Get('/')
+   *   @UseAuth('jwt')
+   *   @RequireScopes('profile:read')
+   *   getProfile() {}
+   * }
+   * ```
+   *
+   * @param context HTTP guard context for the active handler invocation.
+   * @returns `true` when the request may continue through the HTTP pipeline.
+   * @throws {AuthStrategyResolutionError} When no active strategy can be determined or resolved.
+   * @throws {UnauthorizedException} When the strategy reports missing, expired, or invalid authentication.
+   * @throws {ForbiddenException} When the authenticated principal is missing required scopes.
+   */
+  async canActivate(context) {
+    const requirement = getAuthRequirement(context.handler.controllerToken, context.handler.methodName);
+    const strategyName = requirement?.strategy ?? this.options.defaultStrategy;
+    if (!strategyName) {
+      if (requirement?.scopes?.length) {
+        throw new AuthStrategyResolutionError('Auth requirement exists without an active strategy.');
+      }
+      return true;
+    }
+    if (!hasRegisteredStrategy(this.strategies, strategyName)) {
+      throw new AuthStrategyResolutionError(`No auth strategy registered for ${strategyName}.`);
+    }
+    const strategyToken = this.strategies[strategyName];
+    const strategy = await context.requestContext.container.resolve(strategyToken).catch(error => {
+      if (error instanceof ContainerResolutionError) {
+        throw new AuthStrategyResolutionError(`Failed to resolve auth strategy "${strategyName}": ${toErrorMessage(error)}`);
+      }
+      throw error;
+    });
+    try {
+      const result = await strategy.authenticate(context);
+      const principal = resolvePrincipal(result);
+      if (isAuthHandledResult(result) && !principal) {
+        if (!context.requestContext.response.committed) {
+          throw new AuthenticationFailedError('Auth strategy returned handled:true without a principal but did not commit a response.');
+        }
+        return true;
+      }
+      if (!principal) {
+        throw new AuthenticationFailedError('Authentication strategy did not return a principal.');
+      }
+      if (requirement?.scopes?.length && !hasRequiredScopes(principal, requirement.scopes)) {
+        throw new ForbiddenException('Access denied.');
+      }
+      context.requestContext.principal = principal;
+      return true;
+    } catch (error) {
+      if (isAuthenticationFailure(error)) {
+        throw new UnauthorizedException('Authentication required.', {
+          cause: error
+        });
+      }
+      throw error;
+    }
+  }
+  static {
+    _initClass();
+  }
+}
+export { _AuthGuard as AuthGuard };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './account/account-linking.js';
+export * from './cookie/cookie-auth.js';
+export * from './cookie/cookie-auth-module.js';
+export * from './cookie/cookie-manager.js';
+export * from './decorators.js';
+export * from './errors.js';
+export * from './guard.js';
+export * from './refresh/jwt-refresh-token-adapter.js';
+export * from './metadata.js';
+export * from './module.js';
+export * from './adapters/passport-js.js';
+export * from './refresh/refresh-token.js';
+export * from './status.js';
+export * from './types.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,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,wCAAwC,CAAC;AACvD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export * from './account/account-linking.js';
+export * from './cookie/cookie-auth.js';
+export * from './cookie/cookie-auth-module.js';
+export * from './cookie/cookie-manager.js';
+export * from './decorators.js';
+export * from './errors.js';
+export * from './guard.js';
+export * from './refresh/jwt-refresh-token-adapter.js';
+export * from './metadata.js';
+export * from './module.js';
+export * from './adapters/passport-js.js';
+export * from './refresh/refresh-token.js';
+export * from './status.js';
+export * from './types.js';

package/dist/internal-tokens.d.ts

@@ -0,0 +1,3 @@
+export declare const PASSPORT_OPTIONS: unique symbol;
+export declare const AUTH_STRATEGY_REGISTRY: unique symbol;
+//# sourceMappingURL=internal-tokens.d.ts.map

package/dist/internal-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-tokens.d.ts","sourceRoot":"","sources":["../src/internal-tokens.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,eAAmC,CAAC;AACjE,eAAO,MAAM,sBAAsB,eAAyC,CAAC"}

package/dist/internal-tokens.js

@@ -0,0 +1,4 @@
+const PASSPORT_OPTIONS_KEY = 'fluo.passport.options';
+const AUTH_STRATEGY_REGISTRY_KEY = 'fluo.passport.strategy-registry';
+export const PASSPORT_OPTIONS = Symbol.for(PASSPORT_OPTIONS_KEY);
+export const AUTH_STRATEGY_REGISTRY = Symbol.for(AUTH_STRATEGY_REGISTRY_KEY);

package/dist/metadata.d.ts

@@ -0,0 +1,6 @@
+import { type MetadataPropertyKey } from '@fluojs/core';
+import type { AuthRequirement } from './types.js';
+export declare function defineAuthRequirement(target: Function | object, requirement: AuthRequirement, propertyKey?: MetadataPropertyKey): void;
+export declare function getOwnAuthRequirement(target: Function | object, propertyKey?: MetadataPropertyKey): AuthRequirement | undefined;
+export declare function getAuthRequirement(controllerType: Function, propertyKey?: MetadataPropertyKey): AuthRequirement | undefined;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAIxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAwElD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAkCtI;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAAG,SAAS,CAM/H;AAED,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAAG,SAAS,CA6B3H"}

package/dist/metadata.js

@@ -0,0 +1,105 @@
+import { metadataSymbol } from '@fluojs/core/internal';
+import { mergeAuthRequirements, normalizeDeclaredScopes } from './scope.js';
+const standardClassRequirementKey = Symbol.for('fluo.passport.standard.class-auth');
+const standardMethodRequirementKey = Symbol.for('fluo.passport.standard.method-auth');
+const classRequirementStore = new WeakMap();
+const methodRequirementStore = new WeakMap();
+const mergedClassRequirementCache = new WeakMap();
+const mergedMethodRequirementCache = new WeakMap();
+function normalizeRequirement(requirement) {
+  if (!requirement) {
+    return undefined;
+  }
+  const strategy = requirement.strategy;
+  const scopes = normalizeDeclaredScopes(requirement.scopes);
+  if (!strategy && !scopes) {
+    return undefined;
+  }
+  return {
+    scopes,
+    strategy
+  };
+}
+function toCacheValue(requirement) {
+  return requirement ?? null;
+}
+function invalidateRequirementCache(controllerType, propertyKey) {
+  mergedClassRequirementCache.delete(controllerType);
+  if (propertyKey === undefined) {
+    mergedMethodRequirementCache.delete(controllerType);
+    return;
+  }
+  const methodCache = mergedMethodRequirementCache.get(controllerType);
+  if (!methodCache) {
+    return;
+  }
+  methodCache.delete(propertyKey);
+  if (methodCache.size === 0) {
+    mergedMethodRequirementCache.delete(controllerType);
+  }
+}
+function getStandardMetadataBag(target) {
+  return target[metadataSymbol];
+}
+function getStandardClassRequirement(target) {
+  return normalizeRequirement(getStandardMetadataBag(target)?.[standardClassRequirementKey]);
+}
+function getStandardMethodRequirement(target, propertyKey) {
+  const constructor = target.constructor;
+  const map = constructor ? getStandardMetadataBag(constructor)?.[standardMethodRequirementKey] : undefined;
+  return normalizeRequirement(map?.get(propertyKey));
+}
+export function defineAuthRequirement(target, requirement, propertyKey) {
+  const normalizedRequirement = normalizeRequirement(requirement);
+  if (propertyKey === undefined) {
+    const controllerType = target;
+    if (normalizedRequirement) {
+      classRequirementStore.set(controllerType, normalizedRequirement);
+    } else {
+      classRequirementStore.delete(controllerType);
+    }
+    invalidateRequirementCache(controllerType);
+    return;
+  }
+  let map = methodRequirementStore.get(target);
+  if (!map) {
+    map = new Map();
+    methodRequirementStore.set(target, map);
+  }
+  if (normalizedRequirement) {
+    map.set(propertyKey, normalizedRequirement);
+  } else {
+    map.delete(propertyKey);
+  }
+  const controllerType = target.constructor;
+  if (controllerType) {
+    invalidateRequirementCache(controllerType, propertyKey);
+  }
+}
+export function getOwnAuthRequirement(target, propertyKey) {
+  if (propertyKey === undefined) {
+    return mergeAuthRequirements(classRequirementStore.get(target), getStandardClassRequirement(target));
+  }
+  return mergeAuthRequirements(methodRequirementStore.get(target)?.get(propertyKey), getStandardMethodRequirement(target, propertyKey));
+}
+export function getAuthRequirement(controllerType, propertyKey) {
+  if (propertyKey === undefined) {
+    if (mergedClassRequirementCache.has(controllerType)) {
+      return mergedClassRequirementCache.get(controllerType) ?? undefined;
+    }
+    const requirement = getOwnAuthRequirement(controllerType);
+    mergedClassRequirementCache.set(controllerType, toCacheValue(requirement));
+    return requirement;
+  }
+  const methodCache = mergedMethodRequirementCache.get(controllerType);
+  if (methodCache?.has(propertyKey)) {
+    return methodCache.get(propertyKey) ?? undefined;
+  }
+  const requirement = mergeAuthRequirements(getOwnAuthRequirement(controllerType), getOwnAuthRequirement(controllerType.prototype, propertyKey));
+  if (methodCache) {
+    methodCache.set(propertyKey, toCacheValue(requirement));
+  } else {
+    mergedMethodRequirementCache.set(controllerType, new Map([[propertyKey, toCacheValue(requirement)]]));
+  }
+  return requirement;
+}