@fluojs/passport 1.0.0-beta.2 → 1.0.0-beta.4

package/README.ko.md

@@ -114,6 +114,24 @@ export class AuthModule {}
 
 `CookieAuthStrategy`는 `@fluojs/jwt`가 정규화한 JWT principal 계약을 보존하며, `subject`, `claims`, `issuer`, `audience`, `roles`, `scopes`를 그대로 전달합니다.
 
+보호된 라우트는 계속 `@UseAuth(...)`를 사용해야 합니다. `requireAccessToken: false`를 설정해도 쿠키가 없을 때는 이제 익명 principal이 아니라 명시적인 미인증 결과를 반환하므로, 보호된 라우트는 요청을 계속 거부합니다.
+
+로그인 사용자와 게스트 호출자를 모두 허용하려는 라우트에서만 `@UseOptionalAuth(...)`를 사용하세요.
+
+```typescript
+import { Controller, Get, type RequestContext } from '@fluojs/http';
+import { UseOptionalAuth } from '@fluojs/passport';
+
+@Controller('/session')
+export class SessionController {
+  @Get('/')
+  @UseOptionalAuth('cookie')
+  getSession(_input: never, ctx: RequestContext) {
+    return { subject: ctx.principal?.subject ?? null };
+  }
+}
+```
+
 ### 리프레시 토큰 수명 주기
 
 패키지에서 제공하는 `RefreshTokenStrategy`와 `RefreshTokenService`를 사용하여 안전한 토큰 로테이션 및 폐기 기능을 구현할 수 있습니다.
@@ -157,6 +175,7 @@ export class AuthController {
 
 ### 데코레이터
 - `@UseAuth(strategyName)`: `AuthGuard`를 부착하고 사용할 전략을 설정합니다.
+- `@UseOptionalAuth(strategyName)`: `AuthGuard`를 부착하지만 전략이 자격 증명 누락을 보고하면 스코프가 없는 라우트는 계속 진행할 수 있게 합니다.
 - `@RequireScopes(...scopes)`: 특정 권한(스코프) 요구 사항을 강제합니다.
 
 ### 주요 클래스

package/README.md

@@ -114,6 +114,24 @@ Import `CookieAuthModule.forRoot(...)` alongside `PassportModule.forRoot(...)` w
 
 `CookieAuthStrategy` preserves the normalized JWT principal contract from `@fluojs/jwt`, including `subject`, `claims`, `issuer`, `audience`, `roles`, and `scopes`.
 
+Protected routes must keep using `@UseAuth(...)`. If you configure `requireAccessToken: false`, a missing cookie now resolves to an explicit unauthenticated result instead of an anonymous principal, so protected routes still reject the request.
+
+Use `@UseOptionalAuth(...)` only on routes that intentionally support both signed-in and guest callers:
+
+```typescript
+import { Controller, Get, type RequestContext } from '@fluojs/http';
+import { UseOptionalAuth } from '@fluojs/passport';
+
+@Controller('/session')
+export class SessionController {
+  @Get('/')
+  @UseOptionalAuth('cookie')
+  getSession(_input: never, ctx: RequestContext) {
+    return { subject: ctx.principal?.subject ?? null };
+  }
+}
+```
+
 ### Refresh Token Lifecycle
 
 The package provides a built-in `RefreshTokenStrategy` and `RefreshTokenService` to handle secure token rotation and revocation.
@@ -157,6 +175,7 @@ Import `RefreshTokenModule.forRoot(...)` alongside `PassportModule.forRoot(...)`
 
 ### Decorators
 - `@UseAuth(strategyName)`: Attaches `AuthGuard` and sets the active strategy.
+- `@UseOptionalAuth(strategyName)`: Attaches `AuthGuard` but allows routes without scopes to continue when the strategy reports missing credentials.
 - `@RequireScopes(...scopes)`: Enforces specific scope requirements.
 
 ### Core Classes

package/dist/cookie/cookie-auth.d.ts

@@ -6,7 +6,7 @@ import type { AuthStrategy, AuthStrategyResult } from '../types.js';
  */
 export declare const COOKIE_AUTH_OPTIONS: unique symbol;
 /**
- * Configures cookie names and fallback behavior for cookie-based authentication.
+ * Configures cookie names and missing-cookie behavior for cookie-based authentication.
  */
 export interface CookieAuthOptions {
     accessTokenCookieName?: string;
@@ -26,6 +26,11 @@ export declare const DEFAULT_COOKIE_AUTH_OPTIONS: Required<CookieAuthOptions>;
 export declare function normalizeCookieAuthOptions(options?: CookieAuthOptions): Required<CookieAuthOptions>;
 /**
  * Authenticates requests by reading and verifying JWTs from HTTP cookies.
+ *
+ * @remarks
+ * When `requireAccessToken` is `false`, missing cookies now resolve to an explicit
+ * unauthenticated result. Protected routes still reject that result unless they opt in
+ * with `@UseOptionalAuth(...)`.
  */
 export declare class CookieAuthStrategy implements AuthStrategy {
     private readonly verifier;

package/dist/cookie/cookie-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-auth.d.ts","sourceRoot":"","sources":["../../src/cookie/cookie-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAkD,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,iBAAiB,CAInE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAMnG;AAED;;GAEG;AACH,qBACa,kBAAmB,YAAW,YAAY;IAInD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAH3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;gBAGnC,QAAQ,EAAE,kBAAkB,EAC7C,OAAO,CAAC,EAAE,iBAAiB;IAKvB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA+CvE;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,WAAW,CAAC"}
+{"version":3,"file":"cookie-auth.d.ts","sourceRoot":"","sources":["../../src/cookie/cookie-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,KAAK,EAAsB,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMxF;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAkD,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,iBAAiB,CAInE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAMnG;AAED;;;;;;;GAOG;AACH,qBACa,kBAAmB,YAAW,YAAY;IAInD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAH3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;gBAGnC,QAAQ,EAAE,kBAAkB,EAC7C,OAAO,CAAC,EAAE,iBAAiB;IAKvB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAyCvE;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,WAAW,CAAC"}

package/dist/cookie/cookie-auth.js

@@ -7,13 +7,17 @@ function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side
 import { Inject } from '@fluojs/core';
 import { DefaultJwtVerifier } from '@fluojs/jwt';
 import { AuthenticationRequiredError } from '../errors.js';
+const unauthenticatedCookieAuthResult = {
+  authenticated: false
+};
+
 /**
  * Provides cookie-auth strategy options through dependency injection.
  */
 export const COOKIE_AUTH_OPTIONS = Symbol.for('fluo.passport.cookie-auth-options');
 
 /**
- * Configures cookie names and fallback behavior for cookie-based authentication.
+ * Configures cookie names and missing-cookie behavior for cookie-based authentication.
  */
 
 /**
@@ -41,6 +45,11 @@ export function normalizeCookieAuthOptions(options) {
 
 /**
  * Authenticates requests by reading and verifying JWTs from HTTP cookies.
+ *
+ * @remarks
+ * When `requireAccessToken` is `false`, missing cookies now resolve to an explicit
+ * unauthenticated result. Protected routes still reject that result unless they opt in
+ * with `@UseOptionalAuth(...)`.
  */
 let _CookieAuthStrategy;
 class CookieAuthStrategy {
@@ -59,20 +68,14 @@ class CookieAuthStrategy {
       if (this.options.requireAccessToken) {
         throw new AuthenticationRequiredError('Access token cookie is required.');
       }
-      return {
-        claims: {},
-        subject: 'anonymous'
-      };
+      return unauthenticatedCookieAuthResult;
     }
     const accessToken = cookies[this.options.accessTokenCookieName];
     if (!accessToken) {
       if (this.options.requireAccessToken) {
         throw new AuthenticationRequiredError('Access token cookie is required.');
       }
-      return {
-        claims: {},
-        subject: 'anonymous'
-      };
+      return unauthenticatedCookieAuthResult;
     }
     try {
       const principal = await this.verifier.verifyAccessToken(accessToken);

package/dist/cookie/cookie-manager.d.ts

@@ -1,5 +1,8 @@
 import type { FrameworkResponse } from '@fluojs/http';
 import { type CookieAuthOptions } from './cookie-auth.js';
+/**
+ * Describes the cookie options contract.
+ */
 export interface CookieOptions {
     httpOnly?: boolean;
     secure?: boolean;
@@ -8,15 +11,27 @@ export interface CookieOptions {
     domain?: string;
     maxAge?: number;
 }
+/**
+ * Describes the set cookie options contract.
+ */
 export interface SetCookieOptions extends CookieOptions {
     accessTokenTtlSeconds?: number;
     refreshTokenTtlSeconds?: number;
 }
+/**
+ * Describes the cookie manager config contract.
+ */
 export interface CookieManagerConfig extends CookieAuthOptions {
     cookieOptions?: CookieOptions;
 }
 type NormalizedCookieOptions = Omit<Required<CookieOptions>, 'domain' | 'maxAge'> & Pick<CookieOptions, 'domain' | 'maxAge'>;
+/**
+ * Provides the default cookie options value.
+ */
 export declare const DEFAULT_COOKIE_OPTIONS: NormalizedCookieOptions;
+/**
+ * Represents the cookie manager.
+ */
 export declare class CookieManager {
     private readonly options;
     private readonly cookieOptions;
@@ -29,6 +44,12 @@ export declare class CookieManager {
     setAuthCookies(response: FrameworkResponse, accessToken: string, accessTokenTtlSeconds?: number, refreshToken?: string, refreshTokenTtlSeconds?: number): void;
     private appendSetCookie;
 }
+/**
+ * Create cookie manager.
+ *
+ * @param config The config.
+ * @returns The create cookie manager result.
+ */
 export declare function createCookieManager(config?: CookieManagerConfig): CookieManager;
 export {};
 //# sourceMappingURL=cookie-manager.d.ts.map

package/dist/cookie/cookie-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-manager.d.ts","sourceRoot":"","sources":["../../src/cookie/cookie-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAA+B,KAAK,iBAAiB,EAA8B,MAAM,kBAAkB,CAAC;AAEnH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,KAAK,uBAAuB,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAC/E,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAE3C,eAAO,MAAM,sBAAsB,EAAE,uBAOpC,CAAC;AAuCF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;gBAE5C,MAAM,CAAC,EAAE,mBAAmB;IAYxC,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAa3F,qBAAqB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAa5F,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IASzD,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAS1D,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAKlD,cAAc,CACZ,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,MAAM,EACnB,qBAAqB,CAAC,EAAE,MAAM,EAC9B,YAAY,CAAC,EAAE,MAAM,EACrB,sBAAsB,CAAC,EAAE,MAAM,GAC9B,IAAI;IAQP,OAAO,CAAC,eAAe;CAWxB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAE/E"}
+{"version":3,"file":"cookie-manager.d.ts","sourceRoot":"","sources":["../../src/cookie/cookie-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAA+B,KAAK,iBAAiB,EAA8B,MAAM,kBAAkB,CAAC;AAEnH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,KAAK,uBAAuB,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAC/E,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,uBAOpC,CAAC;AAuCF;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;gBAE5C,MAAM,CAAC,EAAE,mBAAmB;IAYxC,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAa3F,qBAAqB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAa5F,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IASzD,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAS1D,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAKlD,cAAc,CACZ,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,MAAM,EACnB,qBAAqB,CAAC,EAAE,MAAM,EAC9B,YAAY,CAAC,EAAE,MAAM,EACrB,sBAAsB,CAAC,EAAE,MAAM,GAC9B,IAAI;IAQP,OAAO,CAAC,eAAe;CAWxB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAE/E"}

package/dist/cookie/cookie-manager.js

@@ -1,4 +1,20 @@
 import { normalizeCookieAuthOptions } from './cookie-auth.js';
+
+/**
+ * Describes the cookie options contract.
+ */
+
+/**
+ * Describes the set cookie options contract.
+ */
+
+/**
+ * Describes the cookie manager config contract.
+ */
+
+/**
+ * Provides the default cookie options value.
+ */
 export const DEFAULT_COOKIE_OPTIONS = {
   httpOnly: true,
   secure: true,
@@ -35,6 +51,10 @@ function buildClearCookieHeader(name, options) {
     maxAge: 0
   });
 }
+
+/**
+ * Represents the cookie manager.
+ */
 export class CookieManager {
   options;
   cookieOptions;
@@ -88,6 +108,13 @@ export class CookieManager {
     response.setHeader('Set-Cookie', cookies.length === 1 ? cookies[0] : cookies);
   }
 }
+
+/**
+ * Create cookie manager.
+ *
+ * @param config The config.
+ * @returns The create cookie manager result.
+ */
 export function createCookieManager(config) {
   return new CookieManager(config);
 }

package/dist/decorators.d.ts

@@ -19,6 +19,26 @@ type ClassOrMethodDecoratorLike = StandardClassDecoratorFn & StandardMethodDecor
  * @returns A class-or-method decorator that stores the auth requirement metadata.
  */
 export declare function UseAuth(strategy: string): ClassOrMethodDecoratorLike;
+/**
+ * Declares a strategy that may leave `requestContext.principal` unset when credentials are absent.
+ *
+ * @remarks
+ * Use this decorator only for routes that intentionally accept both authenticated and
+ * unauthenticated callers. Scope requirements still require a resolved principal.
+ *
+ * @example
+ * ```ts
+ * @UseOptionalAuth('cookie')
+ * @Get('/session')
+ * getSession(_input: unknown, ctx: RequestContext) {
+ *   return { subject: ctx.principal?.subject ?? null };
+ * }
+ * ```
+ *
+ * @param strategy Strategy name previously registered through `PassportModule.forRoot(...)`.
+ * @returns A class-or-method decorator that stores the optional auth requirement metadata.
+ */
+export declare function UseOptionalAuth(strategy: string): ClassOrMethodDecoratorLike;
 /**
  * Declares scope requirements that `AuthGuard` must enforce after authentication succeeds.
  *

package/dist/decorators.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,0BAA0B,CAE5E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,0BAA0B,CAE7E"}

package/dist/decorators.js

@@ -70,6 +70,32 @@ export function UseAuth(strategy) {
   });
 }
 
+/**
+ * Declares a strategy that may leave `requestContext.principal` unset when credentials are absent.
+ *
+ * @remarks
+ * Use this decorator only for routes that intentionally accept both authenticated and
+ * unauthenticated callers. Scope requirements still require a resolved principal.
+ *
+ * @example
+ * ```ts
+ * @UseOptionalAuth('cookie')
+ * @Get('/session')
+ * getSession(_input: unknown, ctx: RequestContext) {
+ *   return { subject: ctx.principal?.subject ?? null };
+ * }
+ * ```
+ *
+ * @param strategy Strategy name previously registered through `PassportModule.forRoot(...)`.
+ * @returns A class-or-method decorator that stores the optional auth requirement metadata.
+ */
+export function UseOptionalAuth(strategy) {
+  return createAuthRequirementDecorator({
+    optional: true,
+    strategy
+  });
+}
+
 /**
  * Declares scope requirements that `AuthGuard` must enforce after authentication succeeds.
  *

package/dist/guard.d.ts.map

@@ -1 +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;AA8EpB;;;;;;;;;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;CA8DxD"}
+{"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,EAKjB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAsFpB;;;;;;;;;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;CAkExD"}

package/dist/guard.js

@@ -13,10 +13,16 @@ import { getAuthRequirement } from './metadata.js';
 function isAuthHandledResult(result) {
   return typeof result === 'object' && result !== null && 'handled' in result && result.handled === true;
 }
+function isAuthOptionalResult(result) {
+  return typeof result === 'object' && result !== null && 'authenticated' in result && result.authenticated === false;
+}
 function resolvePrincipal(result) {
   if (isAuthHandledResult(result)) {
     return result.principal;
   }
+  if (isAuthOptionalResult(result)) {
+    return undefined;
+  }
   return result;
 }
 function isRecord(value) {
@@ -131,6 +137,9 @@ class AuthGuard {
         return true;
       }
       if (!principal) {
+        if (isAuthOptionalResult(result) && requirement?.optional && !requirement.scopes?.length) {
+          return true;
+        }
         throw new AuthenticationFailedError('Authentication strategy did not return a principal.');
       }
       if (!isPrincipal(principal)) {

package/dist/internal-tokens.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Provides the passport options value.
+ */
 export declare const PASSPORT_OPTIONS: unique symbol;
+/**
+ * Provides the auth strategy registry value.
+ */
 export declare const AUTH_STRATEGY_REGISTRY: unique symbol;
 //# sourceMappingURL=internal-tokens.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"internal-tokens.d.ts","sourceRoot":"","sources":["../src/internal-tokens.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAAmC,CAAC;AACjE;;GAEG;AACH,eAAO,MAAM,sBAAsB,eAAyC,CAAC"}

package/dist/internal-tokens.js

@@ -1,4 +1,11 @@
 const PASSPORT_OPTIONS_KEY = 'fluo.passport.options';
 const AUTH_STRATEGY_REGISTRY_KEY = 'fluo.passport.strategy-registry';
+
+/**
+ * Provides the passport options value.
+ */
 export const PASSPORT_OPTIONS = Symbol.for(PASSPORT_OPTIONS_KEY);
+/**
+ * Provides the auth strategy registry value.
+ */
 export const AUTH_STRATEGY_REGISTRY = Symbol.for(AUTH_STRATEGY_REGISTRY_KEY);

package/dist/metadata.d.ts

@@ -1,6 +1,27 @@
 import { type MetadataPropertyKey } from '@fluojs/core';
 import type { AuthRequirement } from './types.js';
+/**
+ * Define auth requirement.
+ *
+ * @param target The target.
+ * @param requirement The requirement.
+ * @param propertyKey The property key.
+ */
 export declare function defineAuthRequirement(target: Function | object, requirement: AuthRequirement, propertyKey?: MetadataPropertyKey): void;
+/**
+ * Get own auth requirement.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @returns The get own auth requirement result.
+ */
 export declare function getOwnAuthRequirement(target: Function | object, propertyKey?: MetadataPropertyKey): AuthRequirement | undefined;
+/**
+ * Get auth requirement.
+ *
+ * @param controllerType The controller type.
+ * @param propertyKey The property key.
+ * @returns The get auth requirement result.
+ */
 export declare function getAuthRequirement(controllerType: Function, propertyKey?: MetadataPropertyKey): AuthRequirement | undefined;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -1 +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"}
+{"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;AAmElD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAkCtI;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAAG,SAAS,CAM/H;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAAG,SAAS,CA6B3H"}

package/dist/metadata.js

@@ -1,4 +1,4 @@
-import { metadataSymbol } from '@fluojs/core/internal';
+import { getStandardConstructorMetadataBag, getStandardMetadataBag } 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');
@@ -11,11 +11,13 @@ function normalizeRequirement(requirement) {
     return undefined;
   }
   const strategy = requirement.strategy;
+  const optional = requirement.optional;
   const scopes = normalizeDeclaredScopes(requirement.scopes);
-  if (!strategy && !scopes) {
+  if (!strategy && !scopes && optional !== true) {
     return undefined;
   }
   return {
+    optional,
     scopes,
     strategy
   };
@@ -38,17 +40,21 @@ function invalidateRequirementCache(controllerType, propertyKey) {
     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;
+  const map = getStandardConstructorMetadataBag(target)?.[standardMethodRequirementKey];
   return normalizeRequirement(map?.get(propertyKey));
 }
+
+/**
+ * Define auth requirement.
+ *
+ * @param target The target.
+ * @param requirement The requirement.
+ * @param propertyKey The property key.
+ */
 export function defineAuthRequirement(target, requirement, propertyKey) {
   const normalizedRequirement = normalizeRequirement(requirement);
   if (propertyKey === undefined) {
@@ -76,12 +82,28 @@ export function defineAuthRequirement(target, requirement, propertyKey) {
     invalidateRequirementCache(controllerType, propertyKey);
   }
 }
+
+/**
+ * Get own auth requirement.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @returns The get own auth requirement result.
+ */
 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));
 }
+
+/**
+ * Get auth requirement.
+ *
+ * @param controllerType The controller type.
+ * @param propertyKey The property key.
+ * @returns The get auth requirement result.
+ */
 export function getAuthRequirement(controllerType, propertyKey) {
   if (propertyKey === undefined) {
     if (mergedClassRequirementCache.has(controllerType)) {

package/dist/scope.d.ts

@@ -1,5 +1,24 @@
 import type { AuthRequirement } from './types.js';
+/**
+ * Normalize declared scopes.
+ *
+ * @param scopes The scopes.
+ * @returns The normalize declared scopes result.
+ */
 export declare function normalizeDeclaredScopes(scopes: unknown): string[] | undefined;
+/**
+ * Normalize principal scopes.
+ *
+ * @param claims The claims.
+ * @returns The normalize principal scopes result.
+ */
 export declare function normalizePrincipalScopes(claims: Record<string, unknown>): string[] | undefined;
+/**
+ * Merge auth requirements.
+ *
+ * @param base The base.
+ * @param extra The extra.
+ * @returns The merge auth requirements result.
+ */
 export declare function mergeAuthRequirements(base: AuthRequirement | undefined, extra: AuthRequirement | undefined): AuthRequirement | undefined;
 //# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAoBlD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAO7E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,SAAS,CAW9F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,GAAG,SAAS,EACjC,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,eAAe,GAAG,SAAS,CAuB7B"}

package/dist/scope.js

@@ -11,6 +11,13 @@ function normalizeScopeItems(items) {
   }
   return normalized.length > 0 ? normalized : undefined;
 }
+
+/**
+ * Normalize declared scopes.
+ *
+ * @param scopes The scopes.
+ * @returns The normalize declared scopes result.
+ */
 export function normalizeDeclaredScopes(scopes) {
   if (!Array.isArray(scopes)) {
     return undefined;
@@ -18,6 +25,13 @@ export function normalizeDeclaredScopes(scopes) {
   const scopeItems = scopes.filter(scope => typeof scope === 'string');
   return normalizeScopeItems(scopeItems);
 }
+
+/**
+ * Normalize principal scopes.
+ *
+ * @param claims The claims.
+ * @returns The normalize principal scopes result.
+ */
 export function normalizePrincipalScopes(claims) {
   if (Array.isArray(claims.scopes)) {
     const scopes = claims.scopes.filter(scope => typeof scope === 'string');
@@ -28,16 +42,26 @@ export function normalizePrincipalScopes(claims) {
   }
   return undefined;
 }
+
+/**
+ * Merge auth requirements.
+ *
+ * @param base The base.
+ * @param extra The extra.
+ * @returns The merge auth requirements result.
+ */
 export function mergeAuthRequirements(base, extra) {
   if (!base && !extra) {
     return undefined;
   }
   const scopes = normalizeDeclaredScopes([...(base?.scopes ?? []), ...(extra?.scopes ?? [])]);
+  const optional = extra && Object.hasOwn(extra, 'optional') ? extra.optional : base?.optional === true && extra?.strategy ? false : base?.optional;
   const strategy = extra?.strategy ?? base?.strategy;
-  if (!strategy && !scopes) {
+  if (!strategy && !scopes && optional !== true) {
     return undefined;
   }
   return {
+    optional,
     scopes,
     strategy
   };

package/dist/types.d.ts

@@ -4,16 +4,22 @@ import type { Guard, GuardContext, Principal } from '@fluojs/http';
 export interface AuthRequirement {
     /** Named strategy to resolve from the strategy registry. */
     strategy?: string;
+    /** Allows the request to continue without a resolved principal. */
+    optional?: boolean;
     /** Required scopes that must be present on the resolved principal. */
     scopes?: string[];
 }
+/** Authentication result variant used when a route explicitly allows missing credentials. */
+export interface AuthOptionalResult {
+    authenticated: false;
+}
 /** Authentication result variant used when a strategy fully handled the response. */
 export interface AuthHandledResult {
     handled: true;
     principal?: Principal;
 }
 /** Return type of an `AuthStrategy.authenticate(...)` call. */
-export type AuthStrategyResult = Principal | AuthHandledResult;
+export type AuthStrategyResult = Principal | AuthHandledResult | AuthOptionalResult;
 /** Strategy contract implemented by authentication adapters. */
 export interface AuthStrategy {
     authenticate(context: GuardContext): MaybePromise<AuthStrategyResult>;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnE,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAE/D,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC,kBAAkB,CAAC,CAAC;CACvE;AAED,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAEjF,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAkB,SAAQ,KAAK;IAC9C,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnE,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,KAAK,CAAC;CACtB;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEpF,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC,kBAAkB,CAAC,CAAC;CACvE;AAED,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAEjF,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAkB,SAAQ,KAAK;IAC9C,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/package.json

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