@spfn/auth 0.2.0-beta.61 → 0.2.0-beta.64

package/README.md

@@ -1540,10 +1540,12 @@ OAuth 세션 완료. 인터셉터가 pending session에서 full session을 생
 **Response:**
 ```typescript
 {
-  providers: ('google' | 'github' | 'kakao' | 'naver')[];
+  providers: ('google' | 'github' | 'kakao' | 'naver' | 'superself')[];
 }
 ```
 
+> 등록(`registerOAuthProvider`)되고 `isEnabled()`가 true인 provider만 반환됩니다.
+
 ---
 
 ### Google API Access
@@ -1585,6 +1587,62 @@ const data = await response.json();
 
 ---
 
+### Custom OAuth Providers (Pluggable)
+
+OAuth provider 분기는 하드코딩이 아니라 **registry 기반**입니다. 내장 `google` provider는 패키지 로드 시 자기 등록되며, 외부 패키지(예: `@superself/auth`)는 `registerOAuthProvider()`로 런타임에 provider를 끼울 수 있습니다.
+
+#### `OAuthProvider` 인터페이스
+
+```typescript
+import type { OAuthProvider, NormalizedIdentity, OAuthTokens } from '@spfn/auth/server';
+
+interface NormalizedIdentity {
+    providerUserId: string;
+    email: string | null;
+    emailVerified: boolean;
+    name?: string;
+    avatar?: string;
+}
+
+interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn: number;   // seconds
+}
+
+interface OAuthProvider {
+    id: SocialProvider;                                          // SOCIAL_PROVIDERS 중 하나
+    isEnabled(): boolean;                                        // 필수 설정 충족 여부
+    getAuthUrl(state: string, scopes?: string[]): string;        // authorize URL 생성
+    exchangeCodeForTokens(code: string): Promise<OAuthTokens>;   // code → token
+    getUserInfo(accessToken: string): Promise<NormalizedIdentity>; // 사용자 정보 정규화
+    refreshTokens?(refreshToken: string): Promise<OAuthTokens>;  // (선택) 토큰 갱신
+}
+```
+
+#### 등록 API
+
+```typescript
+import { registerOAuthProvider, getOAuthProvider, getRegisteredProviders } from '@spfn/auth/server';
+
+registerOAuthProvider(myProvider);          // 동일 id 재등록 시 override
+getOAuthProvider('superself');              // OAuthProvider | undefined
+getRegisteredProviders();                   // OAuthProvider[]
+```
+
+provider를 등록하면 범용 시작 엔드포인트 `POST /_auth/oauth/start`(및 `oauthStartService`/`oauthCallbackService`)가 자동으로 해당 provider를 처리합니다.
+
+#### 통합 계약 ⚠️
+
+- **콜백 route는 소비 측 책임**입니다. 이 패키지는 `GET /_auth/oauth/google/callback`(google 고정)만 제공합니다. 커스텀 provider는 자신의 콜백 route에서 `oauthCallbackService({ provider, code, state })`를 호출해야 흐름이 완결됩니다.
+- **콜백 route는 `Transactional()`로 감싸세요.** `oauthCallbackService`는 사용자 생성/연결과 소셜 계정 저장을 순차로 수행하므로, 중간 실패 시 orphan user가 남지 않으려면 트랜잭션이 필요합니다. (내장 google 콜백 route도 `.use([Transactional()])`를 사용합니다.)
+- `SOCIAL_PROVIDERS` enum에 provider id가 포함되어 있어야 합니다. (현재: `google`, `github`, `kakao`, `naver`, `superself`)
+- 등록은 모듈 로드 시점의 side-effect입니다. 번들러에서 `package.json`에 `"sideEffects": false`를 추가하면 내장 google 등록이 tree-shake될 수 있으니 주의하세요.
+
+> **이벤트 영향**: `auth.login` / `auth.register` 이벤트의 `provider` 필드에 이제 모든 `SOCIAL_PROVIDERS` 값이 들어올 수 있습니다. 구독자의 `switch(provider)`에 새 값 처리를 추가하세요.
+
+---
+
 ### Security
 
 - **State 암호화**: JWE (A256GCM)로 state 파라미터 암호화. CSRF 방지용 nonce 포함.

package/dist/{authenticate-B_HkYBzq.d.ts → authenticate-mfVRzeIK.d.ts}

@@ -1,5 +1,5 @@
 import * as _spfn_core_route from '@spfn/core/route';
-import { K as KeyAlgorithmType, d as SocialProvider } from './types-B1CzVZkU.js';
+import { K as KeyAlgorithmType, d as SocialProvider } from './types-B4auHIax.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 import { User } from '@spfn/auth/server';
@@ -364,6 +364,88 @@ declare function issueOneTimeTokenService(userId: string): Promise<IssueOneTimeT
  */
 declare function verifyOneTimeTokenService(token: string): Promise<string | null>;
 
+/**
+ * OAuth Provider 추상화
+ *
+ * Provider별로 하드코딩된 분기를 제거하기 위한 공통 인터페이스와 registry.
+ * - 내장 provider(google)는 패키지 로드 시점에 자기 등록(dogfood)
+ * - 외부 패키지(@superself/auth 등)는 registerOAuthProvider()로 런타임 등록
+ *
+ * @spfn/auth는 토큰 issuer가 아니라 소비(client) 측이므로,
+ * 이 추상화는 "authorize URL 생성 → code 교환 → 사용자 정보 정규화"까지만 다룬다.
+ */
+
+/**
+ * Provider 사용자 정보를 공통 형태로 정규화한 신원
+ *
+ * provider별 응답 형태(snake_case 등)를 service에 노출하지 않기 위한 경계.
+ */
+interface NormalizedIdentity {
+    providerUserId: string;
+    email: string | null;
+    emailVerified: boolean;
+    name?: string;
+    avatar?: string;
+}
+/**
+ * 정규화된 OAuth 토큰 응답
+ *
+ * @property expiresIn - access token 만료까지 남은 초(seconds)
+ */
+interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn: number;
+}
+/**
+ * OAuth provider 구현 인터페이스
+ *
+ * google, superself 등 모든 provider가 이 형태를 만족해야 registry에 등록된다.
+ */
+interface OAuthProvider {
+    id: SocialProvider;
+    /**
+     * provider가 사용 가능한 상태인지(필수 env 등) 확인
+     */
+    isEnabled(): boolean;
+    /**
+     * provider 로그인 페이지로 보낼 authorization URL 생성
+     *
+     * @param state - CSRF 방지용 암호화 state
+     * @param scopes - 요청할 scope (미지정 시 provider 기본값)
+     */
+    getAuthUrl(state: string, scopes?: string[]): string;
+    /**
+     * authorization code를 토큰으로 교환
+     */
+    exchangeCodeForTokens(code: string): Promise<OAuthTokens>;
+    /**
+     * access token으로 사용자 정보를 조회하고 공통 형태로 정규화
+     */
+    getUserInfo(accessToken: string): Promise<NormalizedIdentity>;
+    /**
+     * refresh token으로 access token 갱신 (provider가 지원하는 경우)
+     *
+     * 저장된 provider 토큰을 이후 API 호출에 재사용할 때 사용한다.
+     * 미구현 provider는 갱신 불가로 간주한다.
+     */
+    refreshTokens?(refreshToken: string): Promise<OAuthTokens>;
+}
+/**
+ * OAuth provider 등록 (public)
+ *
+ * 동일 id로 다시 등록하면 덮어쓴다(외부 패키지의 override 허용).
+ */
+declare function registerOAuthProvider(provider: OAuthProvider): void;
+/**
+ * 등록된 provider 조회. 미등록이면 undefined.
+ */
+declare function getOAuthProvider(id: SocialProvider): OAuthProvider | undefined;
+/**
+ * 등록된 모든 provider 목록
+ */
+declare function getRegisteredProviders(): OAuthProvider[];
+
 /**
  * @spfn/auth - OAuth Service
  *
@@ -396,6 +478,13 @@ interface OAuthCallbackResult {
     keyId: string;
     isNewUser: boolean;
 }
+/**
+ * registry에서 provider를 찾아 사용 가능한지 검증 후 반환
+ *
+ * 미등록과 비활성을 구분해 디버깅 신호를 남긴다.
+ * 라우트 레이어에서도 재사용한다(중복 조회/non-null 단언 제거).
+ */
+declare function requireEnabledProvider(provider: SocialProvider): OAuthProvider;
 /**
  * OAuth 로그인 시작 - Provider 로그인 페이지로 리다이렉트할 URL 생성
  *
@@ -414,11 +503,11 @@ declare function oauthCallbackService(params: OAuthCallbackParams): Promise<OAut
  */
 declare function buildOAuthErrorUrl(error: string): string;
 /**
- * OAuth provider가 활성화되어 있는지 확인
+ * OAuth provider가 등록되어 있고 활성화되어 있는지 확인
  */
 declare function isOAuthProviderEnabled(provider: SocialProvider): boolean;
 /**
- * 활성화된 모든 OAuth provider 목록
+ * 활성화된 모든 OAuth provider 목록 (registry 기반)
  */
 declare function getEnabledOAuthProviders(): SocialProvider[];
 /**
@@ -531,7 +620,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
             id: number;
             name: string;
             displayName: string;
-            category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
+            category: "custom" | "user" | "auth" | "rbac" | "system" | undefined;
         }[];
         userId: number;
         publicId: string;
@@ -556,7 +645,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }, {}, Response>;
     oauthStart: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{
-            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver">[]>;
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
             returnUrl: _sinclair_typebox.TString;
             publicKey: _sinclair_typebox.TString;
             keyId: _sinclair_typebox.TString;
@@ -566,7 +655,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         }>;
     }, {}, OAuthStartResult>;
     oauthProviders: _spfn_core_route.RouteDef<{}, {}, {
-        providers: ("google" | "github" | "kakao" | "naver")[];
+        providers: ("google" | "github" | "kakao" | "naver" | "superself")[];
     }>;
     getGoogleOAuthUrl: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{
@@ -588,6 +677,36 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         keyId: string;
         returnUrl: string;
     }>;
+    oauthProviderStart: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        query: _sinclair_typebox.TObject<{
+            state: _sinclair_typebox.TString;
+        }>;
+    }, {}, Response>;
+    oauthProviderCallback: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        query: _sinclair_typebox.TObject<{
+            code: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error_description: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, Response>;
+    getProviderOAuthUrl: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        body: _sinclair_typebox.TObject<{
+            returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        authUrl: string;
+    }>;
     getInvitation: _spfn_core_route.RouteDef<{
         params: _sinclair_typebox.TObject<{
             token: _sinclair_typebox.TString;
@@ -896,4 +1015,4 @@ declare const authenticate: _spfn_core_route.NamedMiddleware<"auth">;
  */
 declare const optionalAuth: _spfn_core_route.NamedMiddleware<"optionalAuth">;
 
-export { authenticate as $, type AuthSession as A, registerPublicKeyService as B, type CheckAccountExistsResult as C, rotateKeyService as D, revokeKeyService as E, type RegisterPublicKeyParams as F, type RotateKeyParams as G, type RevokeKeyParams as H, type IssueOneTimeTokenResult as I, issueOneTimeTokenService as J, verifyOneTimeTokenService as K, type LoginResult as L, oauthStartService as M, oauthCallbackService as N, type OAuthStartResult as O, type PermissionConfig as P, buildOAuthErrorUrl as Q, type RoleConfig as R, type SendVerificationCodeResult as S, isOAuthProviderEnabled as T, type UserProfile as U, type VerificationTargetType as V, getEnabledOAuthProviders as W, getGoogleAccessToken as X, type OAuthStartParams as Y, type OAuthCallbackParams as Z, type OAuthCallbackResult as _, type RegisterResult as a, optionalAuth as a0, EmailSchema as a1, PhoneSchema as a2, PasswordSchema as a3, TargetTypeSchema as a4, VerificationPurposeSchema as a5, type RotateKeyResult as b, type ProfileInfo as c, type VerificationPurpose as d, VERIFICATION_TARGET_TYPES as e, VERIFICATION_PURPOSES as f, PERMISSION_CATEGORIES as g, type PermissionCategory as h, type AuthInitOptions as i, type AuthContext as j, checkAccountExistsService as k, loginService as l, mainAuthRouter as m, logoutService as n, changePasswordService as o, type CheckAccountExistsParams as p, type RegisterParams as q, registerService as r, type LoginParams as s, type LogoutParams as t, type ChangePasswordParams as u, sendVerificationCodeService as v, verifyCodeService as w, type SendVerificationCodeParams as x, type VerifyCodeParams as y, type VerifyCodeResult as z };
+export { type OAuthCallbackParams as $, type AuthSession as A, type VerifyCodeResult as B, type CheckAccountExistsResult as C, registerPublicKeyService as D, rotateKeyService as E, revokeKeyService as F, type RegisterPublicKeyParams as G, type RotateKeyParams as H, type IssueOneTimeTokenResult as I, type RevokeKeyParams as J, issueOneTimeTokenService as K, type LoginResult as L, verifyOneTimeTokenService as M, oauthStartService as N, type OAuthStartResult as O, type PermissionConfig as P, oauthCallbackService as Q, type RoleConfig as R, type SendVerificationCodeResult as S, buildOAuthErrorUrl as T, type UserProfile as U, type VerificationTargetType as V, isOAuthProviderEnabled as W, requireEnabledProvider as X, getEnabledOAuthProviders as Y, getGoogleAccessToken as Z, type OAuthStartParams as _, type RegisterResult as a, type OAuthCallbackResult as a0, authenticate as a1, optionalAuth as a2, EmailSchema as a3, PhoneSchema as a4, PasswordSchema as a5, TargetTypeSchema as a6, VerificationPurposeSchema as a7, type NormalizedIdentity as a8, type OAuthTokens as a9, registerOAuthProvider as aa, getOAuthProvider as ab, getRegisteredProviders as ac, type RotateKeyResult as b, type ProfileInfo as c, type VerificationPurpose as d, VERIFICATION_TARGET_TYPES as e, VERIFICATION_PURPOSES as f, PERMISSION_CATEGORIES as g, type PermissionCategory as h, type AuthInitOptions as i, type OAuthProvider as j, type AuthContext as k, checkAccountExistsService as l, mainAuthRouter as m, loginService as n, logoutService as o, changePasswordService as p, type CheckAccountExistsParams as q, registerService as r, type RegisterParams as s, type LoginParams as t, type LogoutParams as u, type ChangePasswordParams as v, sendVerificationCodeService as w, verifyCodeService as x, type SendVerificationCodeParams as y, type VerifyCodeParams as z };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as _spfn_core_nextjs from '@spfn/core/nextjs';
-import { R as RoleConfig, P as PermissionConfig, C as CheckAccountExistsResult, S as SendVerificationCodeResult, a as RegisterResult, L as LoginResult, b as RotateKeyResult, I as IssueOneTimeTokenResult, O as OAuthStartResult, U as UserProfile, c as ProfileInfo, m as mainAuthRouter } from './authenticate-B_HkYBzq.js';
-export { i as AuthInitOptions, A as AuthSession, g as PERMISSION_CATEGORIES, h as PermissionCategory, f as VERIFICATION_PURPOSES, e as VERIFICATION_TARGET_TYPES, d as VerificationPurpose, V as VerificationTargetType } from './authenticate-B_HkYBzq.js';
+import { R as RoleConfig, P as PermissionConfig, C as CheckAccountExistsResult, S as SendVerificationCodeResult, a as RegisterResult, L as LoginResult, b as RotateKeyResult, I as IssueOneTimeTokenResult, O as OAuthStartResult, U as UserProfile, c as ProfileInfo, m as mainAuthRouter } from './authenticate-mfVRzeIK.js';
+export { i as AuthInitOptions, A as AuthSession, g as PERMISSION_CATEGORIES, h as PermissionCategory, f as VERIFICATION_PURPOSES, e as VERIFICATION_TARGET_TYPES, d as VerificationPurpose, V as VerificationTargetType } from './authenticate-mfVRzeIK.js';
 import * as _spfn_core_route from '@spfn/core/route';
 import { HttpMethod } from '@spfn/core/route';
-export { I as INVITATION_STATUSES, b as InvitationStatus, a as KEY_ALGORITHM, K as KeyAlgorithmType, S as SOCIAL_PROVIDERS, d as SocialProvider, U as USER_STATUSES, c as UserStatus } from './types-B1CzVZkU.js';
+export { I as INVITATION_STATUSES, b as InvitationStatus, a as KEY_ALGORITHM, K as KeyAlgorithmType, S as SOCIAL_PROVIDERS, d as SocialProvider, U as USER_STATUSES, c as UserStatus } from './types-B4auHIax.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import '@spfn/auth/server';
 
@@ -170,7 +170,7 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
             id: number;
             name: string;
             displayName: string;
-            category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
+            category: "custom" | "user" | "auth" | "rbac" | "system" | undefined;
         }[];
         userId: number;
         publicId: string;
@@ -195,7 +195,7 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
     }, {}, Response>;
     oauthStart: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{
-            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver">[]>;
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
             returnUrl: _sinclair_typebox.TString;
             publicKey: _sinclair_typebox.TString;
             keyId: _sinclair_typebox.TString;
@@ -205,7 +205,7 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
         }>;
     }, {}, OAuthStartResult>;
     oauthProviders: _spfn_core_route.RouteDef<{}, {}, {
-        providers: ("google" | "github" | "kakao" | "naver")[];
+        providers: ("google" | "github" | "kakao" | "naver" | "superself")[];
     }>;
     getGoogleOAuthUrl: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{
@@ -227,6 +227,36 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
         keyId: string;
         returnUrl: string;
     }>;
+    oauthProviderStart: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        query: _sinclair_typebox.TObject<{
+            state: _sinclair_typebox.TString;
+        }>;
+    }, {}, Response>;
+    oauthProviderCallback: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        query: _sinclair_typebox.TObject<{
+            code: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error_description: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, Response>;
+    getProviderOAuthUrl: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        body: _sinclair_typebox.TObject<{
+            returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        authUrl: string;
+    }>;
     getInvitation: _spfn_core_route.RouteDef<{
         params: _sinclair_typebox.TObject<{
             token: _sinclair_typebox.TString;

package/dist/index.js

@@ -191,6 +191,9 @@ var routeMap = {
   oauthProviders: { method: "GET", path: "/_auth/oauth/providers" },
   getGoogleOAuthUrl: { method: "POST", path: "/_auth/oauth/google/url" },
   oauthFinalize: { method: "POST", path: "/_auth/oauth/finalize" },
+  oauthProviderStart: { method: "GET", path: "/_auth/oauth/:provider" },
+  oauthProviderCallback: { method: "GET", path: "/_auth/oauth/:provider/callback" },
+  getProviderOAuthUrl: { method: "POST", path: "/_auth/oauth/:provider/url" },
   listRoles: { method: "GET", path: "/_auth/admin/roles" },
   createAdminRole: { method: "POST", path: "/_auth/admin/roles" },
   updateAdminRole: { method: "PATCH", path: "/_auth/admin/roles/:id" },
@@ -333,7 +336,7 @@ var BUILTIN_ROLE_PERMISSIONS = {
 var KEY_ALGORITHM = ["ES256", "RS256"];
 var INVITATION_STATUSES = ["pending", "accepted", "expired", "cancelled"];
 var USER_STATUSES = ["active", "inactive", "suspended"];
-var SOCIAL_PROVIDERS = ["google", "github", "kakao", "naver"];
+var SOCIAL_PROVIDERS = ["google", "github", "kakao", "naver", "superself"];
 
 // ../../node_modules/.pnpm/@sinclair+typebox@0.34.41/node_modules/@sinclair/typebox/build/esm/type/guard/value.mjs
 var value_exports = {};