@spfn/auth 0.2.0-beta.60 → 0.2.0-beta.62

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-DcOkuB7d.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';
@@ -414,11 +414,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[];
 /**
@@ -556,7 +556,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 +566,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<{

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-DcOkuB7d.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-DcOkuB7d.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';
 
@@ -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<{

package/dist/index.js

@@ -333,7 +333,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 = {};