@spfn/auth 0.2.0-beta.11 → 0.2.0-beta.12

package/README.md

@@ -1,6 +1,6 @@
 # @spfn/auth - Technical Documentation
 
-**Version:** 0.2.0-beta.11
+**Version:** 0.2.0-beta.12
 **Status:** Alpha - Internal Development
 
 > **Note:** This is a technical documentation for developers working on the @spfn/auth package.
@@ -18,6 +18,7 @@
 - [Module Exports](#module-exports)
 - [Email & SMS Services](#email--sms-services)
 - [Server-Side API](#server-side-api)
+- [OAuth Authentication](#oauth-authentication)
 - [Database Schema](#database-schema)
 - [RBAC System](#rbac-system)
 - [Next.js Adapter](#nextjs-adapter)
@@ -34,10 +35,11 @@
 
 - **Asymmetric JWT Authentication** - Client-signed tokens using ES256/RS256
 - **User Management** - Email/phone-based identity with bcrypt hashing
+- **OAuth Authentication** - Google OAuth 2.0 (Authorization Code Flow), extensible to other providers
 - **Multi-Factor Authentication** - OTP verification via email/SMS
 - **Session Management** - Public key rotation with 90-day expiry
 - **Role-Based Access Control** - Flexible RBAC with runtime role/permission management
-- **Next.js Integration** - Session helpers and server-side guards
+- **Next.js Integration** - Session helpers, server-side guards, and OAuth interceptors
 
 ### Design Principles
 
@@ -130,6 +132,16 @@ SPFN_AUTH_JWT_EXPIRES_IN=7d
 SPFN_AUTH_BCRYPT_SALT_ROUNDS=10
 SPFN_AUTH_SESSION_TTL=7d
 
+# Google OAuth
+SPFN_AUTH_GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
+SPFN_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-...
+SPFN_APP_URL=http://localhost:3000
+
+# Google OAuth (Optional)
+SPFN_AUTH_GOOGLE_REDIRECT_URI=http://localhost:8790/_auth/oauth/google/callback
+SPFN_AUTH_OAUTH_SUCCESS_URL=/auth/callback
+SPFN_AUTH_OAUTH_ERROR_URL=http://localhost:3000/auth/error?error={error}
+
 # AWS SES (Email)
 SPFN_AUTH_AWS_REGION=ap-northeast-2
 SPFN_AUTH_AWS_SES_ACCESS_KEY_ID=AKIA...
@@ -719,9 +731,11 @@ import {
   loginRegisterInterceptor,
   generalAuthInterceptor,
   keyRotationInterceptor,
+  oauthUrlInterceptor,
+  oauthFinalizeInterceptor,
 } from '@spfn/auth/nextjs/api';
 
-// Auto-registers interceptors on import
+// Auto-registers interceptors on import (including OAuth)
 import '@spfn/auth/nextjs/api';
 ```
 
@@ -1019,6 +1033,266 @@ Change password.
 
 ---
 
+## OAuth Authentication
+
+### Overview
+
+`@spfn/auth`는 OAuth 2.0 Authorization Code Flow를 지원합니다. 현재 Google OAuth가 구현되어 있으며, 다른 provider (GitHub, Kakao, Naver)는 동일한 패턴으로 확장 가능합니다.
+
+**핵심 설계:**
+- 환경 변수만으로 설정 (`SPFN_AUTH_GOOGLE_CLIENT_ID`, `SPFN_AUTH_GOOGLE_CLIENT_SECRET`)
+- Next.js 인터셉터 기반 자동 세션 관리 (키쌍 생성 → pending session → full session)
+- 기존 이메일 계정과 자동 연결 (Google verified_email 확인 시에만)
+
+---
+
+### Authentication Flow
+
+```
+┌──────────┐     ┌──────────────┐     ┌──────────┐     ┌──────────┐
+│  Client  │     │  Next.js RPC │     │  Backend │     │  Google  │
+│ (Browser)│     │  (Interceptor)│     │  (SPFN)  │     │  OAuth   │
+└────┬─────┘     └──────┬───────┘     └────┬─────┘     └────┬─────┘
+     │                   │                  │                 │
+     │ 1. Click Login    │                  │                 │
+     ├──────────────────>│                  │                 │
+     │                   │                  │                 │
+     │    2. Generate keypair (ES256)       │                 │
+     │    3. Create encrypted state         │                 │
+     │       (publicKey, keyId in JWE)      │                 │
+     │    4. Save privateKey to             │                 │
+     │       pending session cookie         │                 │
+     │                   │                  │                 │
+     │                   │ 5. Forward with  │                 │
+     │                   │    state in body │                 │
+     │                   ├─────────────────>│                 │
+     │                   │                  │                 │
+     │                   │ 6. Return Google │                 │
+     │                   │    Auth URL      │                 │
+     │                   │<─────────────────┤                 │
+     │                   │                  │                 │
+     │ 7. Redirect to Google               │                 │
+     │<──────────────────┤                  │                 │
+     │                   │                  │                 │
+     │ 8. User consents  │                  │                 │
+     ├───────────────────┼──────────────────┼────────────────>│
+     │                   │                  │                 │
+     │                   │    9. Callback with code + state   │
+     │                   │                  │<────────────────┤
+     │                   │                  │                 │
+     │                   │  10. Verify state, exchange code   │
+     │                   │      Create/link user account      │
+     │                   │      Register publicKey             │
+     │                   │                  │                 │
+     │ 11. Redirect to /auth/callback       │                 │
+     │     ?userId=X&keyId=Y&returnUrl=/    │                 │
+     │<─────────────────────────────────────┤                 │
+     │                   │                  │                 │
+     │ 12. OAuthCallback │                  │                 │
+     │     component     │                  │                 │
+     │     calls finalize│                  │                 │
+     ├──────────────────>│                  │                 │
+     │                   │                  │                 │
+     │   13. Interceptor reads pending      │                 │
+     │       session cookie, verifies       │                 │
+     │       keyId match, creates full      │                 │
+     │       session cookie                 │                 │
+     │                   │                  │                 │
+     │ 14. Session set,  │                  │                 │
+     │     redirect to   │                  │                 │
+     │     returnUrl     │                  │                 │
+     │<──────────────────┤                  │                 │
+     │                   │                  │                 │
+```
+
+---
+
+### Setup
+
+#### 1. Google Cloud Console
+
+1. [Google Cloud Console](https://console.cloud.google.com/) > APIs & Services > Credentials
+2. Create OAuth 2.0 Client ID (Web application)
+3. Add Authorized redirect URI: `http://localhost:8790/_auth/oauth/google/callback`
+4. Copy Client ID and Client Secret
+
+#### 2. Environment Variables
+
+```bash
+# Required
+SPFN_AUTH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+SPFN_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-your-secret
+
+# Next.js app URL (for OAuth callback redirect)
+SPFN_APP_URL=http://localhost:3000
+
+# Optional
+SPFN_AUTH_GOOGLE_REDIRECT_URI=http://localhost:8790/_auth/oauth/google/callback  # default
+SPFN_AUTH_OAUTH_SUCCESS_URL=/auth/callback  # default
+```
+
+#### 3. Next.js Callback Page
+
+```tsx
+// app/auth/callback/page.tsx
+export { OAuthCallback as default } from '@spfn/auth/nextjs/client';
+```
+
+#### 4. Login Button
+
+```typescript
+import { authApi } from '@spfn/auth';
+
+const handleGoogleLogin = async () =>
+{
+    const response = await authApi.getGoogleOAuthUrl.call({
+        body: { returnUrl: '/dashboard' },
+    });
+    window.location.href = response.authUrl;
+};
+```
+
+---
+
+### OAuth Routes
+
+#### `GET /_auth/oauth/google`
+
+Google OAuth 시작 (리다이렉트 방식). 브라우저를 Google 로그인 페이지로 직접 리다이렉트합니다.
+
+**Query:**
+```typescript
+{
+  state: string;  // Encrypted OAuth state (JWE)
+}
+```
+
+---
+
+#### `POST /_auth/oauth/google/url`
+
+Google OAuth URL 획득 (인터셉터 방식). 인터셉터가 state를 자동 생성하여 주입합니다.
+
+**Request:**
+```typescript
+{
+  returnUrl?: string;  // Default: '/'
+}
+```
+
+**Response:**
+```typescript
+{
+  authUrl: string;  // Google OAuth URL
+}
+```
+
+---
+
+#### `GET /_auth/oauth/google/callback`
+
+Google에서 리다이렉트되는 콜백. code를 token으로 교환하고 사용자를 생성/연결합니다.
+
+**Query (from Google):**
+```typescript
+{
+  code?: string;              // Authorization code
+  state?: string;             // OAuth state
+  error?: string;             // Error code
+  error_description?: string; // Error description
+}
+```
+
+**Result:** Next.js 콜백 페이지로 리다이렉트 (`/auth/callback?userId=X&keyId=Y&returnUrl=/`)
+
+---
+
+#### `POST /_auth/oauth/finalize`
+
+OAuth 세션 완료. 인터셉터가 pending session에서 full session을 생성합니다.
+
+**Request:**
+```typescript
+{
+  userId: string;
+  keyId: string;
+  returnUrl?: string;
+}
+```
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  returnUrl: string;
+}
+```
+
+---
+
+#### `GET /_auth/oauth/providers`
+
+활성화된 OAuth provider 목록을 반환합니다.
+
+**Response:**
+```typescript
+{
+  providers: ('google' | 'github' | 'kakao' | 'naver')[];
+}
+```
+
+---
+
+### Security
+
+- **State 암호화**: JWE (A256GCM)로 state 파라미터 암호화. CSRF 방지용 nonce 포함.
+- **Pending Session**: OAuth 리다이렉트 중 privateKey를 JWE로 암호화한 HttpOnly 쿠키에 저장. 10분 TTL.
+- **KeyId 검증**: finalize 시 pending session의 keyId와 응답의 keyId 일치 확인.
+- **Email 검증**: `verified_email`이 true인 경우에만 기존 계정에 자동 연결. 미검증 이메일로 기존 계정 연결 시도 시 에러.
+- **Session Cookie**: `HttpOnly`, `Secure` (production), `SameSite=strict`.
+
+---
+
+### OAuthCallback Component
+
+`@spfn/auth/nextjs/client`에서 제공하는 클라이언트 컴포넌트입니다.
+
+```tsx
+import { OAuthCallback } from '@spfn/auth/nextjs/client';
+
+// 기본 사용
+export default function CallbackPage()
+{
+    return <OAuthCallback />;
+}
+
+// 커스터마이징
+export default function CallbackPage()
+{
+    return (
+        <OAuthCallback
+            apiBasePath="/api/rpc"
+            loadingComponent={<MySpinner />}
+            errorComponent={(error) => <MyError message={error} />}
+            onSuccess={(userId) => console.log('Logged in:', userId)}
+            onError={(error) => console.error(error)}
+        />
+    );
+}
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiBasePath` | `string` | `'/api/rpc'` | RPC API base path |
+| `loadingComponent` | `ReactNode` | Built-in | 로딩 중 표시할 컴포넌트 |
+| `errorComponent` | `(error: string) => ReactNode` | Built-in | 에러 표시 컴포넌트 |
+| `onSuccess` | `(userId: string) => void` | - | 성공 콜백 |
+| `onError` | `(error: string) => void` | - | 에러 콜백 |
+
+---
+
 ## Database Schema
 
 ### Core Tables
@@ -1252,7 +1526,7 @@ CREATE TABLE user_profiles (
 
 #### `user_social_accounts`
 
-OAuth provider accounts (future feature).
+OAuth provider accounts (Google, GitHub, etc.).
 
 ```sql
 CREATE TABLE user_social_accounts (
@@ -1469,10 +1743,22 @@ import '@spfn/auth/nextjs/api';
 **Target Routes:**
 - `/_auth/login`, `/_auth/register` - Login/register interceptor
 - `/_auth/keys/rotate` - Key rotation interceptor
+- `/_auth/oauth/:provider/url` - OAuth URL interceptor (keypair + state generation)
+- `/_auth/oauth/finalize` - OAuth finalize interceptor (pending session → full session)
 - All other authenticated routes - General auth interceptor
 
 ---
 
+### OAuth Client Component (`@spfn/auth/nextjs/client`)
+
+```typescript
+import { OAuthCallback, type OAuthCallbackProps } from '@spfn/auth/nextjs/client';
+```
+
+OAuth 콜백 페이지용 `'use client'` 컴포넌트. 자세한 사용법은 [OAuth Authentication](#oauth-authentication) 섹션 참조.
+
+---
+
 ## Testing
 
 ### Setup Test Environment
@@ -1818,7 +2104,7 @@ ls migrations/
 
 - [ ] **React hooks** - useAuth, useSession, usePermissions
 - [ ] **UI components** - LoginForm, RegisterForm, AuthProvider
-- [ ] **OAuth integration** - Google, GitHub, etc.
+- [x] **OAuth integration** - Google (implemented), GitHub/Kakao/Naver (planned)
 - [ ] **2FA support** - TOTP/authenticator apps
 - [ ] **Password reset flow** - Complete email-based reset
 - [ ] **Email change flow** - Verification for email updates
@@ -1958,6 +2244,6 @@ MIT License - See LICENSE file for details.
 
 ---
 
-**Last Updated:** 2026-01-25
-**Document Version:** 2.3.0 (Technical Documentation)
-**Package Version:** 0.2.0-beta.11
+**Last Updated:** 2026-01-27
+**Document Version:** 2.4.0 (Technical Documentation)
+**Package Version:** 0.2.0-beta.12

package/dist/{authenticate-CU6_zQaa.d.ts → authenticate-xfEpwIjH.d.ts}

@@ -376,6 +376,63 @@ interface AuthInitOptions {
     sessionTtl?: string | number;
 }
 
+/**
+ * @spfn/auth - OAuth Service
+ *
+ * OAuth 인증 비즈니스 로직
+ * - Google OAuth Authorization Code Flow
+ * - 소셜 계정 연결/생성
+ * - publicKey는 state에서 추출하여 등록
+ */
+
+interface OAuthStartParams {
+    provider: SocialProvider;
+    returnUrl: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm: KeyAlgorithmType;
+}
+interface OAuthStartResult {
+    authUrl: string;
+}
+interface OAuthCallbackParams {
+    provider: SocialProvider;
+    code: string;
+    state: string;
+}
+interface OAuthCallbackResult {
+    redirectUrl: string;
+    userId: string;
+    keyId: string;
+    isNewUser: boolean;
+}
+/**
+ * OAuth 로그인 시작 - Provider 로그인 페이지로 리다이렉트할 URL 생성
+ *
+ * Next.js에서 키쌍을 생성한 후, publicKey를 state에 포함하여 호출
+ */
+declare function oauthStartService(params: OAuthStartParams): Promise<OAuthStartResult>;
+/**
+ * OAuth 콜백 처리 - Code를 Token으로 교환하고 사용자 생성/연결
+ *
+ * state에서 publicKey를 추출하여 서버에 등록
+ * Next.js는 반환된 userId, keyId로 세션을 구성
+ */
+declare function oauthCallbackService(params: OAuthCallbackParams): Promise<OAuthCallbackResult>;
+/**
+ * OAuth 에러 리다이렉트 URL 생성
+ */
+declare function buildOAuthErrorUrl(error: string): string;
+/**
+ * OAuth provider가 활성화되어 있는지 확인
+ */
+declare function isOAuthProviderEnabled(provider: SocialProvider): boolean;
+/**
+ * 활성화된 모든 OAuth provider 목록
+ */
+declare function getEnabledOAuthProviders(): SocialProvider[];
+
 /**
  * @spfn/auth - Main Router
  *
@@ -387,6 +444,7 @@ interface AuthInitOptions {
  *
  * Routes:
  * - Auth: /_auth/exists, /_auth/codes, /_auth/login, /_auth/logout, etc.
+ * - OAuth: /_auth/oauth/google, /_auth/oauth/google/callback, etc.
  * - Invitations: /_auth/invitations/*
  * - Users: /_auth/users/*
  */
@@ -479,6 +537,50 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         emailVerified: boolean;
         phoneVerified: boolean;
     }>;
+    oauthGoogleStart: _spfn_core_route.RouteDef<{
+        query: _sinclair_typebox.TObject<{
+            state: _sinclair_typebox.TString;
+        }>;
+    }, {}, Response>;
+    oauthGoogleCallback: _spfn_core_route.RouteDef<{
+        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>;
+    oauthStart: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "github" | "kakao" | "naver">[]>;
+            returnUrl: _sinclair_typebox.TString;
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+        }>;
+    }, {}, OAuthStartResult>;
+    oauthProviders: _spfn_core_route.RouteDef<{}, {}, {
+        providers: ("google" | "github" | "kakao" | "naver")[];
+    }>;
+    getGoogleOAuthUrl: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        authUrl: string;
+    }>;
+    oauthFinalize: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            userId: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        success: boolean;
+        returnUrl: string;
+    }>;
     getInvitation: _spfn_core_route.RouteDef<{
         params: _sinclair_typebox.TObject<{
             token: _sinclair_typebox.TString;
@@ -642,4 +744,4 @@ declare module 'hono' {
  */
 declare const authenticate: _spfn_core_route.NamedMiddleware<"auth">;
 
-export { VerificationPurposeSchema as $, type AuthSession as A, type ChangePasswordParams as B, type CheckAccountExistsResult as C, sendVerificationCodeService as D, verifyCodeService as E, type SendVerificationCodeParams as F, type VerifyCodeParams as G, type VerifyCodeResult as H, INVITATION_STATUSES as I, registerPublicKeyService as J, KEY_ALGORITHM as K, type LoginResult as L, rotateKeyService as M, revokeKeyService as N, type RegisterPublicKeyParams as O, type PermissionConfig as P, type RotateKeyParams as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type RevokeKeyParams as T, type UserProfile as U, type VerificationTargetType as V, authenticate as W, EmailSchema as X, PhoneSchema as Y, PasswordSchema as Z, TargetTypeSchema as _, type RegisterResult as a, type RotateKeyResult as b, type ProfileInfo as c, USER_STATUSES as d, SOCIAL_PROVIDERS as e, type VerificationPurpose as f, VERIFICATION_TARGET_TYPES as g, VERIFICATION_PURPOSES as h, PERMISSION_CATEGORIES as i, type PermissionCategory as j, type AuthInitOptions as k, type KeyAlgorithmType as l, mainAuthRouter as m, type InvitationStatus as n, type UserStatus as o, type SocialProvider as p, type AuthContext as q, checkAccountExistsService as r, registerService as s, loginService as t, logoutService as u, changePasswordService as v, type CheckAccountExistsParams as w, type RegisterParams as x, type LoginParams as y, type LogoutParams as z };
+export { getEnabledOAuthProviders as $, type AuthSession as A, type ChangePasswordParams as B, type CheckAccountExistsResult as C, sendVerificationCodeService as D, verifyCodeService as E, type SendVerificationCodeParams as F, type VerifyCodeParams as G, type VerifyCodeResult as H, INVITATION_STATUSES as I, registerPublicKeyService as J, KEY_ALGORITHM as K, type LoginResult as L, rotateKeyService as M, revokeKeyService as N, type OAuthStartResult as O, type PermissionConfig as P, type RegisterPublicKeyParams as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type RotateKeyParams as T, type UserProfile as U, type VerificationTargetType as V, type RevokeKeyParams as W, oauthStartService as X, oauthCallbackService as Y, buildOAuthErrorUrl as Z, isOAuthProviderEnabled as _, type RegisterResult as a, type OAuthStartParams as a0, type OAuthCallbackParams as a1, type OAuthCallbackResult as a2, authenticate as a3, EmailSchema as a4, PhoneSchema as a5, PasswordSchema as a6, TargetTypeSchema as a7, VerificationPurposeSchema as a8, type RotateKeyResult as b, type ProfileInfo as c, USER_STATUSES as d, SOCIAL_PROVIDERS as e, type VerificationPurpose as f, VERIFICATION_TARGET_TYPES as g, VERIFICATION_PURPOSES as h, PERMISSION_CATEGORIES as i, type PermissionCategory as j, type AuthInitOptions as k, type KeyAlgorithmType as l, mainAuthRouter as m, type InvitationStatus as n, type UserStatus as o, type SocialProvider as p, type AuthContext as q, checkAccountExistsService as r, registerService as s, loginService as t, logoutService as u, changePasswordService as v, type CheckAccountExistsParams as w, type RegisterParams as x, type LoginParams as y, type LogoutParams as z };

package/dist/config.d.ts

@@ -214,6 +214,58 @@ declare const authEnvSchema: {
     } & {
         key: "SPFN_AUTH_AWS_SES_FROM_NAME";
     };
+    SPFN_APP_URL: {
+        description: string;
+        default: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_APP_URL";
+    };
+    SPFN_AUTH_GOOGLE_CLIENT_ID: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_GOOGLE_CLIENT_ID";
+    };
+    SPFN_AUTH_GOOGLE_CLIENT_SECRET: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_GOOGLE_CLIENT_SECRET";
+    };
+    SPFN_AUTH_GOOGLE_REDIRECT_URI: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_GOOGLE_REDIRECT_URI";
+    };
+    SPFN_AUTH_OAUTH_SUCCESS_URL: {
+        description: string;
+        required: boolean;
+        default: string;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_OAUTH_SUCCESS_URL";
+    };
+    SPFN_AUTH_OAUTH_ERROR_URL: {
+        description: string;
+        required: boolean;
+        default: string;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_OAUTH_ERROR_URL";
+    };
 };
 
 declare const env: _spfn_core_env.InferEnvType<{
@@ -404,6 +456,58 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "SPFN_AUTH_AWS_SES_FROM_NAME";
     };
+    SPFN_APP_URL: {
+        description: string;
+        default: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_APP_URL";
+    };
+    SPFN_AUTH_GOOGLE_CLIENT_ID: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_GOOGLE_CLIENT_ID";
+    };
+    SPFN_AUTH_GOOGLE_CLIENT_SECRET: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_GOOGLE_CLIENT_SECRET";
+    };
+    SPFN_AUTH_GOOGLE_REDIRECT_URI: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_GOOGLE_REDIRECT_URI";
+    };
+    SPFN_AUTH_OAUTH_SUCCESS_URL: {
+        description: string;
+        required: boolean;
+        default: string;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_OAUTH_SUCCESS_URL";
+    };
+    SPFN_AUTH_OAUTH_ERROR_URL: {
+        description: string;
+        required: boolean;
+        default: string;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_AUTH_OAUTH_ERROR_URL";
+    };
 }>;
 
 export { env, authEnvSchema as envSchema };

package/dist/config.js

@@ -231,6 +231,67 @@ var authEnvSchema = defineEnvSchema({
       required: false,
       examples: ["MyApp", "Your Company"]
     })
+  },
+  SPFN_APP_URL: {
+    ...envString({
+      description: "Next.js application URL. Used for OAuth callback redirects.",
+      default: "http://localhost:3000",
+      required: false,
+      examples: [
+        "https://app.example.com",
+        "http://localhost:3000"
+      ]
+    })
+  },
+  // ============================================================================
+  // OAuth Configuration - Google
+  // ============================================================================
+  SPFN_AUTH_GOOGLE_CLIENT_ID: {
+    ...envString({
+      description: "Google OAuth 2.0 Client ID. When set, Google OAuth routes are automatically enabled.",
+      required: false,
+      examples: ["123456789-abc123.apps.googleusercontent.com"]
+    })
+  },
+  SPFN_AUTH_GOOGLE_CLIENT_SECRET: {
+    ...envString({
+      description: "Google OAuth 2.0 Client Secret",
+      required: false,
+      sensitive: true,
+      examples: ["GOCSPX-abcdefghijklmnop"]
+    })
+  },
+  SPFN_AUTH_GOOGLE_REDIRECT_URI: {
+    ...envString({
+      description: "Google OAuth callback URL. Defaults to {SPFN_API_URL}/_auth/oauth/google/callback",
+      required: false,
+      examples: [
+        "https://api.example.com/_auth/oauth/google/callback",
+        "http://localhost:8790/_auth/oauth/google/callback"
+      ]
+    })
+  },
+  SPFN_AUTH_OAUTH_SUCCESS_URL: {
+    ...envString({
+      description: "OAuth callback page URL. This page should use OAuthCallback component to finalize session.",
+      required: false,
+      default: "/auth/callback",
+      examples: [
+        "/auth/callback",
+        "https://app.example.com/auth/callback"
+      ]
+    })
+  },
+  SPFN_AUTH_OAUTH_ERROR_URL: {
+    ...envString({
+      description: "URL to redirect after OAuth error. Use {error} placeholder for error message.",
+      required: false,
+      default: "http://localhost:3000/auth/error?error={error}",
+      examples: [
+        "https://app.example.com/auth/error?error={error}",
+        "http://localhost:3000/auth/error?error={error}"
+      ]
+    })
   }
 });