@fluojs/passport 1.0.4 → 1.0.5

package/README.ko.md

@@ -106,7 +106,21 @@ const googleBridge = createPassportJsStrategyBridge('google', GoogleStrategy, {
 });
 ```
 
-브릿지는 각 Passport.js 전략 실행을 정확히 한 번만 정착(settle)시킵니다. 전략은 바인딩된 Passport 액션(`success`, `fail`, `redirect`, `pass`, `error`) 중 하나를 호출해야 하며, promise rejection, 액션 없이 완료된 promise, 그리고 제한된 action timeout을 초과한 callback-style 실행은 요청을 미해결 상태로 두지 않고 인증 실패로 처리됩니다. 커스텀 `mapPrincipal` 함수는 비어 있지 않은 `subject`와 객체 형태의 `claims`를 포함한 유효한 fluo `Principal`을 반환해야 합니다.
+`createPassportJsStrategyBridge(...)`는 의도적으로 문서화된 manual-composition compatibility helper입니다. 이 helper는 `PassportModule.forRoot(...)`가 소비하는 provider bundle과 대응하는 `AuthStrategyRegistration`을 반환합니다. 애플리케이션은 `PassportModule`을 import하는 같은 module에 bridge provider를 등록하고, `googleBridge.strategy`를 strategy registry에 전달해야 합니다.
+
+```typescript
+@Module({
+  imports: [
+    PassportModule.forRoot({ defaultStrategy: 'google' }, [googleBridge.strategy]),
+  ],
+  providers: [GoogleStrategy, ...googleBridge.providers],
+})
+export class AuthModule {}
+```
+
+이 bridge helper는 third-party Passport.js strategy instance를 `AuthGuard`가 실행하기 전에 provider로 바인딩해야 하므로 Passport.js adapter에 대해 공식적으로 허용되는 module-facade 예외입니다. 애플리케이션-facing 인증 표면은 계속 `PassportModule`, `@UseAuth(...)`, `AuthGuard`이며, 이 helper가 이를 대체하지 않습니다.
+
+브릿지는 각 Passport.js 전략 실행을 정확히 한 번만 정착(settle)시킵니다. 전략은 바인딩된 Passport 액션(`success`, `fail`, `redirect`, `pass`, `error`) 중 하나를 호출해야 하며, promise rejection, 액션 없이 완료된 promise, 그리고 제한된 action timeout을 초과한 callback-style 실행은 요청을 미해결 상태로 두지 않고 인증 실패로 처리됩니다. `handled: true`를 포함한 모든 `AuthStrategyResult`는 전략이 response를 commit한 뒤에는 `principal`을 함께 포함하더라도 완전히 terminal입니다. 이때 `AuthGuard`는 principal validation, scope check, `requestContext.principal` 할당, protected handler 실행을 모두 건너뜁니다. 커스텀 `mapPrincipal` 함수는 비어 있지 않은 `subject`와 객체 형태의 `claims`를 포함한 유효한 fluo `Principal`을 반환해야 합니다.
 
 ### 쿠키 인증 프리셋
 
@@ -140,6 +154,8 @@ export class AuthModule {}
 
 애플리케이션 모듈에서 cookie-auth 지원이 필요하면 `CookieAuthModule.forRoot(...)`, `JwtModule.forRoot(...)`, `PassportModule.forRoot(...)`를 함께 import 하세요. Cookie preset은 `CookieAuthStrategy`와 cookie option을 제공하고, JWT 검증은 여전히 `@fluojs/jwt`에서 오며, passport registry는 여전히 `PassportModule.forRoot(...)`에서 옵니다.
 
+`CookieAuthModule.forRoot(...)`는 애플리케이션 등록을 위한 canonical module-first entrypoint입니다. `createCookieAuthPreset(...)`은 provider graph를 직접 조립하는 host를 위한 compatibility bundle로 공개되어 있으며, 동일한 cookie-auth provider와 대응하는 strategy registration을 반환합니다. 애플리케이션 문서, generated code, 일반 app module에서는 module facade를 우선 사용하세요.
+
 `CookieAuthStrategy`는 `@fluojs/jwt`가 정규화한 JWT principal 계약을 보존하며, `subject`, `claims`, `issuer`, `audience`, `roles`, `scopes`를 그대로 전달합니다.
 
 Cookie access token은 비어 있지 않은 문자열이어야 합니다. `requireAccessToken: false`일 때만 누락된 cookie가 `{ authenticated: false }`로 resolve될 수 있으며, 존재하지만 malformed인 cookie 값은 JWT 검증 전에 항상 인증 실패로 처리됩니다.
@@ -238,7 +254,7 @@ Identity-link 결정을 모델링하려면 `createConservativeAccountLinkPolicy(
 - `CookieAuthStrategy`, `COOKIE_AUTH_STRATEGY_NAME`, `COOKIE_AUTH_OPTIONS`, `DEFAULT_COOKIE_AUTH_OPTIONS`, `DEFAULT_COOKIE_OPTIONS`: Cookie strategy wiring token, preset 기본값, response-cookie 기본값입니다.
 - `CookieAuthOptions`, `CookieAuthPresetConfig`, `CookieManagerConfig`, `CookieOptions`, `SetCookieOptions`: Cookie strategy 및 response cookie 설정 타입입니다.
 - `CookieManager`: HttpOnly access/refresh token cookie를 설정하고 제거하는 유틸리티입니다.
-- Cookie helper: `createCookieAuthPreset`, `createCookieAuthStrategyRegistration`, `createCookieManager`, `normalizeCookieAuthOptions`.
+- Cookie helper: `createCookieAuthPreset`(compatibility-only manual provider bundle), `createCookieAuthStrategyRegistration`(low-level registration helper), `createCookieManager`, `normalizeCookieAuthOptions`.
 
 ### Refresh token preset
 - `RefreshTokenModule`: 내장 refresh-token preset의 모듈 진입점입니다.
@@ -249,7 +265,7 @@ Identity-link 결정을 모델링하려면 `createConservativeAccountLinkPolicy(
 - Refresh helper: `createRefreshTokenStrategyRegistration`.
 
 ### Passport.js bridge
-- `createPassportJsStrategyBridge(...)`: Passport.js strategy를 fluo `AuthStrategy`로 변환합니다.
+- `createPassportJsStrategyBridge(...)`: Passport.js strategy를 fluo `AuthStrategy`로 변환하고 `PassportModule.forRoot(...)`용 provider와 대응하는 strategy registration을 반환하는 compatibility helper입니다.
 - `PassportJsAuthStrategy`, `PassportJsStrategyLike`, `PassportJsPrincipalMapperInput`, `PassportJsPrincipalMapper`, `PassportJsAuthStrategyOptions`, `PassportJsStrategyBridge`: Bridge strategy, mapper, 설정, provider bundle 계약입니다.
 
 ### Account linking
@@ -263,7 +279,7 @@ Identity-link 결정을 모델링하려면 `createConservativeAccountLinkPolicy(
 - `createPassportPlatformDiagnosticIssues(...)`: Empty registry, 누락된 default strategy, cookie preset readiness, refresh-token backing store readiness 문제에 대한 diagnostic issue를 생성합니다.
 - `PassportPlatformStatusSnapshot`, `PassportStatusAdapterInput`: Status helper input/output 계약입니다.
 
-`UseOptionalAuth`는 scope가 필요 없는 route에서만 credential 누락을 우회합니다. Scoped route에는 여전히 principal이 필요합니다. Passport.js bridge의 `redirect()`는 response를 commit하고 protected handler를 건너뛰며, `pass()`와 Passport action 없이 완료된 strategy는 인증 실패입니다. Refresh-token backing store status 및 diagnostic surface는 readiness, health, details, diagnostic cause를 노출하기 전에 secret처럼 보이는 reason 문자열을 redact합니다.
+`UseOptionalAuth`는 scope가 필요 없는 route에서만 credential 누락을 우회합니다. Scoped route에는 여전히 principal이 필요합니다. `handled: true`를 포함한 `AuthHandledResult`는 strategy가 response를 commit한 뒤에만 terminal이며, `principal`을 함께 포함한 결과도 여기에 포함됩니다. Passport.js bridge의 `redirect()`는 response를 commit하고 protected handler를 건너뛰며, `pass()`와 Passport action 없이 완료된 strategy는 인증 실패입니다. Refresh-token backing store status 및 diagnostic surface는 readiness, health, details, diagnostic cause를 노출하기 전에 secret처럼 보이는 reason 문자열을 redact합니다.
 
 ## 관련 패키지
 

package/README.md

@@ -106,7 +106,21 @@ const googleBridge = createPassportJsStrategyBridge('google', GoogleStrategy, {
 });
 ```
 
-The bridge settles each Passport.js strategy execution exactly once. A strategy must call one of the bound Passport actions (`success`, `fail`, `redirect`, `pass`, or `error`); promise rejections, promise completion without an action, and callback-style executions that exceed the bounded action timeout become authentication failures instead of leaving the request unresolved. Custom `mapPrincipal` functions must return a valid fluo `Principal` with a non-empty `subject` and object `claims`.
+`createPassportJsStrategyBridge(...)` is an intentionally documented manual-composition compatibility helper. It returns the provider bundle and matching `AuthStrategyRegistration` needed by `PassportModule.forRoot(...)`; applications should register the bridge providers in the same module that imports `PassportModule` and pass `googleBridge.strategy` to the strategy registry:
+
+```typescript
+@Module({
+  imports: [
+    PassportModule.forRoot({ defaultStrategy: 'google' }, [googleBridge.strategy]),
+  ],
+  providers: [GoogleStrategy, ...googleBridge.providers],
+})
+export class AuthModule {}
+```
+
+This bridge helper is the official exception to the module-facade rule for Passport.js adapters because third-party strategy instances must be bound as providers before `AuthGuard` can execute them. It does not replace `PassportModule`, `@UseAuth(...)`, or `AuthGuard` as the application-facing authentication surface.
+
+The bridge settles each Passport.js strategy execution exactly once. A strategy must call one of the bound Passport actions (`success`, `fail`, `redirect`, `pass`, or `error`); promise rejections, promise completion without an action, and callback-style executions that exceed the bounded action timeout become authentication failures instead of leaving the request unresolved. Any `AuthStrategyResult` with `handled: true` is fully terminal after the strategy commits a response, even if it also includes a `principal`; `AuthGuard` skips principal validation, scope checks, `requestContext.principal` assignment, and the protected handler. Custom `mapPrincipal` functions must return a valid fluo `Principal` with a non-empty `subject` and object `claims`.
 
 ### Cookie Auth Preset
 
@@ -140,6 +154,8 @@ export class AuthModule {}
 
 Import `CookieAuthModule.forRoot(...)`, `JwtModule.forRoot(...)`, and `PassportModule.forRoot(...)` together when you want cookie-auth support in an application module. The cookie preset provides `CookieAuthStrategy` and cookie options; JWT verification still comes from `@fluojs/jwt`, and the passport registry still comes from `PassportModule.forRoot(...)`.
 
+`CookieAuthModule.forRoot(...)` is the canonical module-first entrypoint for application registration. `createCookieAuthPreset(...)` remains public as a compatibility bundle for manual provider composition; it returns the same cookie-auth providers plus the matching strategy registration for hosts that assemble provider graphs themselves. Prefer the module facade in application docs, generated code, and ordinary app modules.
+
 `CookieAuthStrategy` preserves the normalized JWT principal contract from `@fluojs/jwt`, including `subject`, `claims`, `issuer`, `audience`, `roles`, and `scopes`.
 
 Cookie access tokens must be non-empty strings. Missing cookies can resolve to `{ authenticated: false }` only when `requireAccessToken: false`; malformed present cookie values always fail authentication before JWT verification.
@@ -238,7 +254,7 @@ Use `createConservativeAccountLinkPolicy(...)` and `resolveAccountLinking(...)`
 - `CookieAuthStrategy`, `COOKIE_AUTH_STRATEGY_NAME`, `COOKIE_AUTH_OPTIONS`, `DEFAULT_COOKIE_AUTH_OPTIONS`, `DEFAULT_COOKIE_OPTIONS`: Cookie strategy wiring tokens, preset defaults, and response-cookie defaults.
 - `CookieAuthOptions`, `CookieAuthPresetConfig`, `CookieManagerConfig`, `CookieOptions`, `SetCookieOptions`: Cookie strategy and response cookie configuration types.
 - `CookieManager`: Utility for setting and clearing HttpOnly access/refresh token cookies.
-- Cookie helpers: `createCookieAuthPreset`, `createCookieAuthStrategyRegistration`, `createCookieManager`, `normalizeCookieAuthOptions`.
+- Cookie helpers: `createCookieAuthPreset` (compatibility-only manual provider bundle), `createCookieAuthStrategyRegistration` (low-level registration helper), `createCookieManager`, `normalizeCookieAuthOptions`.
 
 ### Refresh Token Preset
 - `RefreshTokenModule`: Module entry point for the built-in refresh-token preset.
@@ -249,7 +265,7 @@ Use `createConservativeAccountLinkPolicy(...)` and `resolveAccountLinking(...)`
 - Refresh helpers: `createRefreshTokenStrategyRegistration`.
 
 ### Passport.js Bridge
-- `createPassportJsStrategyBridge(...)`: Adapts Passport.js strategies to fluo `AuthStrategy`.
+- `createPassportJsStrategyBridge(...)`: Compatibility helper that adapts Passport.js strategies to fluo `AuthStrategy` and returns providers plus the matching strategy registration for `PassportModule.forRoot(...)`.
 - `PassportJsAuthStrategy`, `PassportJsStrategyLike`, `PassportJsPrincipalMapperInput`, `PassportJsPrincipalMapper`, `PassportJsAuthStrategyOptions`, `PassportJsStrategyBridge`: Bridge strategy, mapper, configuration, and provider bundle contracts.
 
 ### Account Linking
@@ -263,7 +279,7 @@ Use `createConservativeAccountLinkPolicy(...)` and `resolveAccountLinking(...)`
 - `createPassportPlatformDiagnosticIssues(...)`: Emits diagnostic issues for empty registries, missing default strategies, cookie preset readiness, and refresh-token backing store readiness.
 - `PassportPlatformStatusSnapshot`, `PassportStatusAdapterInput`: Status helper input/output contracts.
 
-`UseOptionalAuth` only bypasses missing credentials when no scopes are required; scoped routes still need a principal. Passport.js bridge `redirect()` commits the response and skips the protected handler, while `pass()` and strategy completion without a Passport action are authentication failures. Refresh-token backing store status and diagnostic surfaces redact secret-like reason strings before exposing readiness, health, details, or diagnostic causes.
+`UseOptionalAuth` only bypasses missing credentials when no scopes are required; scoped routes still need a principal. `AuthHandledResult` with `handled: true` is terminal only after the strategy commits the response, including results that also carry a `principal`. Passport.js bridge `redirect()` commits the response and skips the protected handler, while `pass()` and strategy completion without a Passport action are authentication failures. Refresh-token backing store status and diagnostic surfaces redact secret-like reason strings before exposing readiness, health, details, or diagnostic causes.
 
 ## Related Packages
 

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,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"}
+{"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;CAmExD"}

package/dist/guard.js

@@ -129,13 +129,13 @@ class AuthGuard {
     });
     try {
       const result = await strategy.authenticate(context);
-      const principal = resolvePrincipal(result);
-      if (isAuthHandledResult(result) && !principal) {
+      if (isAuthHandledResult(result)) {
         if (!context.requestContext.response.committed) {
-          throw new AuthenticationFailedError('Auth strategy returned handled:true without a principal but did not commit a response.');
+          throw new AuthenticationFailedError('Auth strategy returned handled:true but did not commit a response.');
         }
         return true;
       }
+      const principal = resolvePrincipal(result);
       if (!principal) {
         if (isAuthOptionalResult(result) && requirement?.optional && !requirement.scopes?.length) {
           return true;

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

@@ -1 +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"}
+{"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,EAIlB,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;AAoFD;;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

@@ -23,25 +23,46 @@ function resolveSecret(options) {
 }
 function createInMemoryStore() {
   const records = new Map();
+  const pruneExpired = now => {
+    for (const [id, record] of records.entries()) {
+      if (record.expiresAt.getTime() <= now) {
+        records.delete(id);
+      }
+    }
+  };
   return {
     async save(token) {
       records.set(token.id, token);
+      pruneExpired(Date.now());
     },
     async find(tokenId) {
-      return records.get(tokenId);
+      const record = records.get(tokenId);
+      pruneExpired(Date.now());
+      return record;
     },
     async revoke(tokenId) {
+      pruneExpired(Date.now());
       records.delete(tokenId);
     },
     async revokeBySubject(subject) {
+      pruneExpired(Date.now());
       for (const [id, record] of records.entries()) {
         if (record.subject === subject) {
           records.delete(id);
         }
       }
     },
+    async revokeByFamily(family) {
+      pruneExpired(Date.now());
+      for (const [id, record] of records.entries()) {
+        if (record.family === family) {
+          records.delete(id);
+        }
+      }
+    },
     async consume(input) {
       const record = records.get(input.tokenId);
+      pruneExpired(input.now.getTime());
       if (!record) {
         return 'invalid';
       }

package/package.json

@@ -9,7 +9,7 @@
     "guard",
     "strategy"
   ],
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,11 +36,11 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/di": "^1.0.3",
-    "@fluojs/http": "^1.1.0",
-    "@fluojs/jwt": "^1.0.1",
-    "@fluojs/runtime": "^1.1.2",
-    "@fluojs/core": "^1.0.3"
+    "@fluojs/core": "^1.1.0",
+    "@fluojs/di": "^2.0.0",
+    "@fluojs/http": "^2.0.1",
+    "@fluojs/jwt": "^1.1.0",
+    "@fluojs/runtime": "^2.0.1"
   },
   "devDependencies": {
     "vitest": "^3.2.4"