@fluojs/passport 1.0.0-beta.6 → 1.0.0

package/README.ko.md

@@ -34,23 +34,46 @@ npm install @fluojs/passport
 사용할 전략을 정의하고 `PassportModule.forRoot(...)`를 통해 등록합니다.
 
 ```typescript
-import { Module } from '@fluojs/core';
-import { PassportModule } from '@fluojs/passport';
-import { MyJwtStrategy } from './jwt.strategy';
+import { Inject, Module } from '@fluojs/core';
+import type { GuardContext } from '@fluojs/http';
+import { DefaultJwtVerifier, JwtModule } from '@fluojs/jwt';
+import { AuthenticationRequiredError, PassportModule, type AuthStrategy } from '@fluojs/passport';
+
+@Inject(DefaultJwtVerifier)
+export class BearerJwtStrategy implements AuthStrategy {
+  constructor(private readonly verifier: DefaultJwtVerifier) {}
+
+  async authenticate(context: GuardContext) {
+    const authorization = context.requestContext.request.headers.authorization;
+    const [scheme, token] = typeof authorization === 'string' ? authorization.split(' ') : [];
+
+    if (scheme !== 'Bearer' || !token) {
+      throw new AuthenticationRequiredError('Bearer access token is required.');
+    }
+
+    return this.verifier.verifyAccessToken(token);
+  }
+}
 
 @Module({
   imports: [
+    JwtModule.forRoot({
+      algorithms: ['HS256'],
+      audience: 'my-app',
+      issuer: 'my-api',
+      secret: 'your-secure-secret',
+    }),
     PassportModule.forRoot(
       { defaultStrategy: 'jwt' },
-      [{ name: 'jwt', token: MyJwtStrategy }]
+      [{ name: 'jwt', token: BearerJwtStrategy }],
     ),
   ],
-  providers: [MyJwtStrategy],
+  providers: [BearerJwtStrategy],
 })
 export class AuthModule {}
 ```
 
-전략 등록은 `PassportModule.forRoot(...)`로 구성합니다.
+JWT 기반 passport 전략에는 두 가지 module wiring이 모두 필요합니다. `JwtModule.forRoot(...)`는 `DefaultJwtVerifier`를 등록하고, `PassportModule.forRoot(...)`는 `@UseAuth('jwt')`가 resolve할 named strategy를 등록합니다. `DefaultJwtVerifier.verifyAccessToken(...)` 결과를 반환하면 `AuthGuard`가 `requestContext.principal`에 기록하는 정규화 principal 계약(`subject`, `claims`, `issuer`, `audience`, `roles`, `scopes`)이 보존됩니다.
 
 ### 2. 라우트 보호
 
@@ -91,6 +114,7 @@ HTTP 쿠키에서 인증 정보를 읽는 애플리케이션이라면 `CookieAut
 
 ```typescript
 import { Module } from '@fluojs/core';
+import { JwtModule } from '@fluojs/jwt';
 import {
   CookieAuthModule,
   CookieAuthStrategy,
@@ -101,6 +125,10 @@ import {
 @Module({
   imports: [
     CookieAuthModule.forRoot(),
+    JwtModule.forRoot({
+      algorithms: ['HS256'],
+      secret: 'your-secure-secret',
+    }),
     PassportModule.forRoot(
       { defaultStrategy: COOKIE_AUTH_STRATEGY_NAME },
       [{ name: COOKIE_AUTH_STRATEGY_NAME, token: CookieAuthStrategy }],
@@ -110,10 +138,12 @@ import {
 export class AuthModule {}
 ```
 
-애플리케이션 모듈에서 cookie-auth 지원이 필요하면 `CookieAuthModule.forRoot(...)`를 `PassportModule.forRoot(...)`와 함께 import 하세요.
+애플리케이션 모듈에서 cookie-auth 지원이 필요하면 `CookieAuthModule.forRoot(...)`, `JwtModule.forRoot(...)`, `PassportModule.forRoot(...)`를 함께 import 하세요. Cookie preset은 `CookieAuthStrategy`와 cookie option을 제공하고, JWT 검증은 여전히 `@fluojs/jwt`에서 오며, passport registry는 여전히 `PassportModule.forRoot(...)`에서 옵니다.
 
 `CookieAuthStrategy`는 `@fluojs/jwt`가 정규화한 JWT principal 계약을 보존하며, `subject`, `claims`, `issuer`, `audience`, `roles`, `scopes`를 그대로 전달합니다.
 
+Cookie access token은 비어 있지 않은 문자열이어야 합니다. `requireAccessToken: false`일 때만 누락된 cookie가 `{ authenticated: false }`로 resolve될 수 있으며, 존재하지만 malformed인 cookie 값은 JWT 검증 전에 항상 인증 실패로 처리됩니다.
+
 보호된 라우트는 계속 `@UseAuth(...)`를 사용해야 합니다. `requireAccessToken: false`를 설정해도 쿠키가 없을 때는 익명 principal이 아니라 명시적인 미인증 결과를 반환하므로, 보호된 라우트는 요청을 계속 거부합니다.
 
 로그인 사용자와 게스트 호출자를 모두 허용하려는 라우트에서만 `@UseOptionalAuth(...)`를 사용하세요.

package/README.md

@@ -34,23 +34,46 @@ npm install @fluojs/passport
 Define your strategies and register them using `PassportModule.forRoot(...)`.
 
 ```typescript
-import { Module } from '@fluojs/core';
-import { PassportModule } from '@fluojs/passport';
-import { MyJwtStrategy } from './jwt.strategy';
+import { Inject, Module } from '@fluojs/core';
+import type { GuardContext } from '@fluojs/http';
+import { DefaultJwtVerifier, JwtModule } from '@fluojs/jwt';
+import { AuthenticationRequiredError, PassportModule, type AuthStrategy } from '@fluojs/passport';
+
+@Inject(DefaultJwtVerifier)
+export class BearerJwtStrategy implements AuthStrategy {
+  constructor(private readonly verifier: DefaultJwtVerifier) {}
+
+  async authenticate(context: GuardContext) {
+    const authorization = context.requestContext.request.headers.authorization;
+    const [scheme, token] = typeof authorization === 'string' ? authorization.split(' ') : [];
+
+    if (scheme !== 'Bearer' || !token) {
+      throw new AuthenticationRequiredError('Bearer access token is required.');
+    }
+
+    return this.verifier.verifyAccessToken(token);
+  }
+}
 
 @Module({
   imports: [
+    JwtModule.forRoot({
+      algorithms: ['HS256'],
+      audience: 'my-app',
+      issuer: 'my-api',
+      secret: 'your-secure-secret',
+    }),
     PassportModule.forRoot(
       { defaultStrategy: 'jwt' },
-      [{ name: 'jwt', token: MyJwtStrategy }]
+      [{ name: 'jwt', token: BearerJwtStrategy }],
     ),
   ],
-  providers: [MyJwtStrategy],
+  providers: [BearerJwtStrategy],
 })
 export class AuthModule {}
 ```
 
-Register strategies through `PassportModule.forRoot(...)`.
+JWT-based passport strategies require both pieces of module wiring: `JwtModule.forRoot(...)` registers `DefaultJwtVerifier`, and `PassportModule.forRoot(...)` registers the named strategy that `@UseAuth('jwt')` resolves. Returning the `DefaultJwtVerifier.verifyAccessToken(...)` result preserves the normalized principal contract (`subject`, `claims`, `issuer`, `audience`, `roles`, and `scopes`) that `AuthGuard` writes to `requestContext.principal`.
 
 ### 2. Protect Routes
 
@@ -91,6 +114,7 @@ Use `CookieAuthModule.forRoot(...)` when your app authenticates requests from HT
 
 ```typescript
 import { Module } from '@fluojs/core';
+import { JwtModule } from '@fluojs/jwt';
 import {
   CookieAuthModule,
   CookieAuthStrategy,
@@ -101,6 +125,10 @@ import {
 @Module({
   imports: [
     CookieAuthModule.forRoot(),
+    JwtModule.forRoot({
+      algorithms: ['HS256'],
+      secret: 'your-secure-secret',
+    }),
     PassportModule.forRoot(
       { defaultStrategy: COOKIE_AUTH_STRATEGY_NAME },
       [{ name: COOKIE_AUTH_STRATEGY_NAME, token: CookieAuthStrategy }],
@@ -110,10 +138,12 @@ import {
 export class AuthModule {}
 ```
 
-Import `CookieAuthModule.forRoot(...)` alongside `PassportModule.forRoot(...)` when you want cookie-auth support in an application module.
+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(...)`.
 
 `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.
+
 Protected routes must keep using `@UseAuth(...)`. If you configure `requireAccessToken: false`, a missing cookie 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:

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,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"}
+{"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;AAUxF;;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;CA6CvE;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,WAAW,CAAC"}

package/dist/cookie/cookie-auth.js

@@ -10,6 +10,9 @@ import { AuthenticationRequiredError } from '../errors.js';
 const unauthenticatedCookieAuthResult = {
   authenticated: false
 };
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
 
 /**
  * Provides cookie-auth strategy options through dependency injection.
@@ -71,12 +74,15 @@ class CookieAuthStrategy {
       return unauthenticatedCookieAuthResult;
     }
     const accessToken = cookies[this.options.accessTokenCookieName];
-    if (!accessToken) {
+    if (accessToken === undefined || accessToken === '') {
       if (this.options.requireAccessToken) {
         throw new AuthenticationRequiredError('Access token cookie is required.');
       }
       return unauthenticatedCookieAuthResult;
     }
+    if (!isNonEmptyString(accessToken)) {
+      throw new AuthenticationRequiredError('Access token cookie must be a non-empty string.');
+    }
     try {
       const principal = await this.verifier.verifyAccessToken(accessToken);
       return {

package/package.json

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