@spfn/auth 0.2.0-beta.5 → 0.2.0-beta.51

package/README.md

@@ -1,6 +1,6 @@
 # @spfn/auth - Technical Documentation
 
-**Version:** 0.1.0-alpha.88
+**Version:** 0.2.0-beta.15
 **Status:** Alpha - Internal Development
 
 > **Note:** This is a technical documentation for developers working on the @spfn/auth package.
@@ -12,12 +12,14 @@
 
 - [Overview](#overview)
 - [Installation](#installation)
+- [Admin Account Setup](#6-admin-account-setup)
 - [Architecture](#architecture)
 - [Package Structure](#package-structure)
 - [Module Exports](#module-exports)
 - [Email & SMS Services](#email--sms-services)
-- [Email Templates](#email-templates)
 - [Server-Side API](#server-side-api)
+- [Events](#events)
+- [OAuth Authentication](#oauth-authentication)
 - [Database Schema](#database-schema)
 - [RBAC System](#rbac-system)
 - [Next.js Adapter](#nextjs-adapter)
@@ -34,10 +36,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
 
@@ -74,64 +77,98 @@ export default defineServerConfig()
     .build();
 ```
 
-#### Register Router in `router.ts`
+#### Register Router and Global Middleware in `router.ts`
 
 ```typescript
 import { defineRouter } from '@spfn/core/route';
-import { authRouter } from '@spfn/auth/server';
+import { authRouter, authenticate } from '@spfn/auth/server';
+import { getHealth } from './routes/health';
+import { createOrder } from './routes/orders';
 
 export const appRouter = defineRouter({
-    // Auth routes (fixed namespace)
-    auth: authRouter,
-
+    getHealth,
+    createOrder,
     // ... your other routes
-});
+})
+.packages([authRouter])    // Auth routes (/_auth/* namespace)
+.use([authenticate]);      // Global auth middleware on all routes
+
+export type AppRouter = typeof appRouter;
 ```
 
-### 3. Configure Client (Next.js)
+> **Important:** Public routes must explicitly skip auth with `.skip(['auth'])`.
+> See the [Authentication Guide](https://spfn.dev/docs/guides/authentication) for details.
 
-#### Register Router Metadata and Errors in `api-client.ts`
+### 3. Configure Next.js Interceptor
+
+Register the auth interceptor in your RPC proxy route. This handles session cookies, JWT signing, and key management automatically.
 
 ```typescript
+// app/api/rpc/[routeName]/route.ts
+import '@spfn/auth/nextjs/api';  // Must be first! Registers auth interceptor
+import { appRouter } from '@/server/router';
+import { createRpcProxy } from '@spfn/core/nextjs/server';
+
+export const { GET, POST } = createRpcProxy({ router: appRouter });
+```
+
+Your API client needs no auth-specific configuration:
+
+```typescript
+// src/lib/api-client.ts
 import { createApi } from '@spfn/core/nextjs';
 import type { AppRouter } from '@/server/router';
-import { appMetadata as authAppMetadata } from "@spfn/auth";
-import { authErrorRegistry } from "@spfn/auth/errors";
-import { appMetadata } from '@/server/router.metadata';
-import { errorRegistry } from "@spfn/core/errors";
-
-export const api = createApi<AppRouter>({
-    metadata: { ...appMetadata, ...authAppMetadata },
-    errorRegistry: errorRegistry.concat(authErrorRegistry),
-});
+
+export const api = createApi<AppRouter>();
+```
+
+The built-in `authApi` is also available for auth-only calls:
+
+```typescript
+import { authApi } from '@spfn/auth';
+const session = await authApi.getAuthSession.call({});
 ```
 
 ### 4. Environment Variables
 
+Auth requires variables in **two separate files**: `.env.server` (SPFN backend) and `.env.local` (Next.js).
+
+#### `.env.server` (SPFN Backend)
+
 ```bash
 # Required
-SPFN_AUTH_JWT_SECRET=your-secret-key
+DATABASE_URL=postgresql://user:pass@localhost:5432/myapp_dev
 SPFN_AUTH_VERIFICATION_TOKEN_SECRET=your-verification-secret
-DATABASE_URL=postgresql://...
 
-# Next.js (required)
-SPFN_AUTH_SESSION_SECRET=your-32-char-secret
+# Admin account (required — at least one format)
+SPFN_AUTH_ADMIN_ACCOUNTS='[{"email":"admin@example.com","password":"Admin!@34","role":"superadmin"}]'
 
 # Optional
+SPFN_AUTH_JWT_SECRET=your-jwt-secret
 SPFN_AUTH_JWT_EXPIRES_IN=7d
 SPFN_AUTH_BCRYPT_SALT_ROUNDS=10
 SPFN_AUTH_SESSION_TTL=7d
 
-# AWS SES (Email)
-SPFN_AUTH_AWS_REGION=ap-northeast-2
-SPFN_AUTH_AWS_SES_ACCESS_KEY_ID=AKIA...
-SPFN_AUTH_AWS_SES_SECRET_ACCESS_KEY=...
-SPFN_AUTH_AWS_SES_FROM_EMAIL=noreply@yourdomain.com
+# Google OAuth (optional)
+SPFN_AUTH_GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
+SPFN_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-...
+```
+
+#### `.env.local` (Next.js)
+
+```bash
+# Required
+DATABASE_URL=postgresql://user:pass@localhost:5432/myapp_dev
+SPFN_API_URL=http://localhost:8790
+
+# Required for session cookies (minimum 32 characters)
+SPFN_AUTH_SESSION_SECRET=my-super-secret-session-key-at-least-32-chars-long
 
-# AWS SNS (SMS)
-SPFN_AUTH_AWS_SNS_ACCESS_KEY_ID=AKIA...
-SPFN_AUTH_AWS_SNS_SECRET_ACCESS_KEY=...
-SPFN_AUTH_AWS_SNS_SENDER_ID=MyApp
+# Optional
+SPFN_AUTH_SESSION_TTL=7d
+
+# Email/SMS — configure via @spfn/notification
+# See @spfn/notification README for AWS SES/SNS settings
 ```
 
 ### 5. Run Migrations
@@ -144,6 +181,83 @@ pnpm spfn db generate
 pnpm spfn db migrate
 ```
 
+### 6. Admin Account Setup
+
+Admin accounts are automatically created on server startup via `createAuthLifecycle()`.
+Choose one of the following methods:
+
+#### Method 1: JSON Format (Recommended)
+
+Best for multiple accounts with full configuration:
+
+```bash
+SPFN_AUTH_ADMIN_ACCOUNTS='[
+  {"email": "superadmin@example.com", "password": "secure-pass-1", "role": "superadmin"},
+  {"email": "admin@example.com", "password": "secure-pass-2", "role": "admin"},
+  {"email": "manager@example.com", "password": "secure-pass-3", "role": "user"}
+]'
+```
+
+**JSON Schema:**
+```typescript
+interface AdminAccountConfig {
+  email: string;           // Required
+  password: string;        // Required
+  role?: string;           // Default: 'user' (options: 'user', 'admin', 'superadmin')
+  phone?: string;          // Optional
+  passwordChangeRequired?: boolean;  // Default: true
+}
+```
+
+#### Method 2: CSV Format
+
+For multiple accounts with simpler configuration:
+
+```bash
+SPFN_AUTH_ADMIN_EMAILS=admin@example.com,manager@example.com
+SPFN_AUTH_ADMIN_PASSWORDS=admin-pass,manager-pass
+SPFN_AUTH_ADMIN_ROLES=superadmin,admin
+```
+
+#### Method 3: Single Account (Legacy)
+
+Simplest format for a single superadmin:
+
+```bash
+SPFN_AUTH_ADMIN_EMAIL=admin@example.com
+SPFN_AUTH_ADMIN_PASSWORD=secure-password
+```
+
+> **Note:** This method always creates a `superadmin` role account.
+
+#### Default Behavior
+
+All admin accounts created via environment variables have:
+- `emailVerifiedAt`: Auto-verified (current timestamp)
+- `passwordChangeRequired`: `true` (must change on first login)
+- `status`: `active`
+
+#### Programmatic Creation
+
+You can also create admin accounts programmatically:
+
+```typescript
+import { usersRepository, getRoleByName, hashPassword } from '@spfn/auth/server';
+
+// After initializeAuth() has been called
+const role = await getRoleByName('admin');
+const passwordHash = await hashPassword('secure-password');
+
+await usersRepository.create({
+  email: 'admin@example.com',
+  passwordHash,
+  roleId: role.id,
+  emailVerifiedAt: new Date(),
+  passwordChangeRequired: true,
+  status: 'active',
+});
+```
+
 ---
 
 ## Architecture
@@ -335,20 +449,15 @@ packages/auth/
 
 ### Common Module (`@spfn/auth`)
 
-**Entities:**
+**API Client:**
 ```typescript
-import {
-  users,
-  userPublicKeys,
-  verificationCodes,
-  roles,
-  permissions,
-  rolePermissions,
-  userPermissions,
-  userInvitations,
-  userSocialAccounts,
-  userProfiles
-} from '@spfn/auth';
+import { authApi } from '@spfn/auth';
+
+// Type-safe API calls
+const session = await authApi.getAuthSession.call({});
+const result = await authApi.login.call({
+  body: { email, password, fingerprint, publicKey, keyId }
+});
 ```
 
 **Types:**
@@ -359,6 +468,9 @@ import type {
   VerificationCode,
   Role,
   Permission,
+  AuthSession,
+  UserProfile,
+  ProfileInfo,
   // ... etc
 } from '@spfn/auth';
 ```
@@ -380,6 +492,34 @@ import type {
 } from '@spfn/auth';
 ```
 
+**Validation Patterns:**
+```typescript
+import {
+  UUID_PATTERN,
+  EMAIL_PATTERN,
+  BASE64_PATTERN,
+  FINGERPRINT_PATTERN,
+  PHONE_PATTERN,
+} from '@spfn/auth';
+```
+
+**Route Map (for RPC Proxy):**
+```typescript
+import { authRouteMap } from '@spfn/auth';
+
+// Use in Next.js RPC proxy (app/api/rpc/[routeName]/route.ts)
+import '@spfn/auth/nextjs/api';  // Auto-register auth interceptors
+import { routeMap } from '@/generated/route-map';
+import { authRouteMap } from '@spfn/auth';
+import { createRpcProxy } from '@spfn/core/nextjs/proxy';
+
+export const { GET, POST } = createRpcProxy({
+    routeMap: { ...routeMap, ...authRouteMap }
+});
+```
+
+> **Note:** Database entities (`users`, `userPublicKeys`, etc.) are exported from `@spfn/auth/server`, not the common module.
+
 ---
 
 ### Server Module (`@spfn/auth/server`)
@@ -456,22 +596,13 @@ import {
 
   // Session
   getAuthSessionService,
-  getUserProfileService,
 
-  // Email
-  sendEmail,
-  registerEmailProvider,
-
-  // SMS
-  sendSMS,
-  registerSMSProvider,
+  // User Profile
+  getUserProfileService,
+  updateUserProfileService,
 
-  // Email Templates
-  registerEmailTemplates,
-  getVerificationCodeTemplate,
-  getWelcomeTemplate,
-  getPasswordResetTemplate,
-  getInvitationTemplate,
+  // OAuth - Google API Access
+  getGoogleAccessToken,
 } from '@spfn/auth/server';
 ```
 
@@ -494,11 +625,13 @@ import {
 ```typescript
 import {
   authenticate,
+  optionalAuth,
   requirePermissions,
+  requireAnyPermission,
   requireRole,
 } from '@spfn/auth/server';
 
-// Usage
+// Usage - all permissions required
 app.bind(
   myContract,
   [authenticate, requirePermissions('user:delete')],
@@ -506,6 +639,27 @@ app.bind(
     // Handler
   }
 );
+
+// Usage - any of the permissions
+app.bind(
+  myContract,
+  [authenticate, requireAnyPermission('content:read', 'admin:access')],
+  async (c) => {
+    // User has either content:read OR admin:access
+  }
+);
+
+// Usage - optional auth (public route with optional user context)
+// Auto-skips global 'auth' middleware — no .skip(['auth']) needed
+export const getProducts = route.get('/products')
+  .use([optionalAuth])
+  .handler(async (c) => {
+    const auth = getOptionalAuth(c);  // AuthContext | undefined
+    if (auth) {
+      return getPersonalizedProducts(auth.userId);
+    }
+    return getPublicProducts();
+  });
 ```
 
 **Helpers:**
@@ -513,6 +667,7 @@ app.bind(
 import {
   // Context
   getAuth,
+  getOptionalAuth,
   getUser,
   getUserId,
   getKeyId,
@@ -610,9 +765,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';
 ```
 
@@ -679,141 +836,24 @@ export default async function DashboardPage()
 
 ## Email & SMS Services
 
-### Email Service
+> **⚠️ DEPRECATED:** Email and SMS functionality has been moved to `@spfn/notification` package.
 
-The email service uses AWS SES by default, with fallback to console logging in development.
+### Migration Guide
 
-**Send Email:**
 ```typescript
-import { sendEmail } from '@spfn/auth/server';
+// Before (deprecated)
+import { sendEmail, sendSMS } from '@spfn/auth/server';
 
-await sendEmail({
-  to: 'user@example.com',
-  subject: 'Welcome!',
-  text: 'Plain text content',
-  html: '<h1>HTML content</h1>',
-  purpose: 'welcome',  // for logging
-});
+// After (recommended)
+import { sendEmail, sendSMS } from '@spfn/notification/server';
 ```
 
-**Custom Email Provider:**
-```typescript
-import { registerEmailProvider } from '@spfn/auth/server';
+The `@spfn/notification` package provides:
+- Multi-channel support (Email, SMS, Slack, Push)
+- Template system with variable substitution
+- Multiple provider support (AWS SES, SNS, SendGrid, Twilio, etc.)
 
-// Register SendGrid provider
-registerEmailProvider({
-  name: 'sendgrid',
-  sendEmail: async ({ to, subject, text, html }) => {
-    // Your SendGrid implementation
-    return { success: true, messageId: '...' };
-  },
-});
-```
-
----
-
-### SMS Service
-
-The SMS service uses AWS SNS by default.
-
-**Send SMS:**
-```typescript
-import { sendSMS } from '@spfn/auth/server';
-
-await sendSMS({
-  phone: '+821012345678',  // E.164 format
-  message: 'Your code is: 123456',
-  purpose: 'verification',
-});
-```
-
-**Custom SMS Provider:**
-```typescript
-import { registerSMSProvider } from '@spfn/auth/server';
-
-// Register Twilio provider
-registerSMSProvider({
-  name: 'twilio',
-  sendSMS: async ({ phone, message }) => {
-    // Your Twilio implementation
-    return { success: true, messageId: '...' };
-  },
-});
-```
-
----
-
-## Email Templates
-
-### Built-in Templates
-
-| Template | Function | Purpose |
-|----------|----------|---------|
-| `verificationCode` | `getVerificationCodeTemplate` | Verification codes (registration, login, password reset) |
-| `welcome` | `getWelcomeTemplate` | Welcome email after registration |
-| `passwordReset` | `getPasswordResetTemplate` | Password reset link |
-| `invitation` | `getInvitationTemplate` | User invitation |
-
-**Usage:**
-```typescript
-import { getVerificationCodeTemplate, sendEmail } from '@spfn/auth/server';
-
-const { subject, text, html } = getVerificationCodeTemplate({
-  code: '123456',
-  purpose: 'registration',
-  expiresInMinutes: 5,
-  appName: 'MyApp',
-});
-
-await sendEmail({ to: 'user@example.com', subject, text, html });
-```
-
----
-
-### Custom Templates
-
-Register custom templates to override defaults with your brand design:
-
-```typescript
-import { registerEmailTemplates } from '@spfn/auth/server';
-
-// Register at app initialization (e.g., server.config.ts)
-registerEmailTemplates({
-  // Override verification code template
-  verificationCode: ({ code, purpose, expiresInMinutes, appName }) => ({
-    subject: `[${appName}] Your verification code`,
-    text: `Your code: ${code}\nExpires in ${expiresInMinutes} minutes.`,
-    html: `
-      <div style="font-family: Arial, sans-serif;">
-        <img src="https://myapp.com/logo.png" alt="Logo" />
-        <h1>Verification Code</h1>
-        <div style="font-size: 32px; font-weight: bold;">${code}</div>
-        <p>This code expires in ${expiresInMinutes} minutes.</p>
-      </div>
-    `,
-  }),
-
-  // Override invitation template
-  invitation: ({ inviteLink, inviterName, roleName, appName }) => ({
-    subject: `${inviterName} invited you to ${appName}`,
-    text: `Accept invitation: ${inviteLink}`,
-    html: `
-      <h1>You're Invited!</h1>
-      <p>${inviterName} invited you to join ${appName} as ${roleName}.</p>
-      <a href="${inviteLink}">Accept Invitation</a>
-    `,
-  }),
-});
-```
-
-**Template Parameters:**
-
-| Template | Parameters |
-|----------|------------|
-| `verificationCode` | `code`, `purpose`, `expiresInMinutes?`, `appName?` |
-| `welcome` | `email`, `appName?` |
-| `passwordReset` | `resetLink`, `expiresInMinutes?`, `appName?` |
-| `invitation` | `inviteLink`, `inviterName?`, `roleName?`, `appName?` |
+For documentation, see `@spfn/notification` package README.
 
 ---
 
@@ -1027,6 +1067,574 @@ Change password.
 
 ---
 
+#### `GET /_auth/users/username/check`
+
+Check if a username is available.
+
+**Query:**
+```typescript
+{
+  username: string;  // Min 1 char
+}
+```
+
+**Response:**
+```typescript
+{
+  available: boolean;
+}
+```
+
+---
+
+#### `PATCH /_auth/users/username`
+
+Update authenticated user's username. Validates uniqueness before updating.
+
+**Request:**
+```typescript
+{
+  username: string | null;  // New username or null to clear
+}
+```
+
+**Response:** Updated user object.
+
+**Errors:**
+- `409 UsernameAlreadyTakenError` - Username is already in use by another user
+
+---
+
+## Events
+
+`@spfn/auth`는 `@spfn/core/event`를 사용하여 인증 관련 이벤트를 발행합니다. 이를 통해 로그인/회원가입 시 추가 로직(환영 이메일, 분석, 알림 등)을 디커플링된 방식으로 처리할 수 있습니다.
+
+### Available Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `auth.login` | 로그인 성공 | 이메일/전화 로그인, OAuth 기존 사용자 |
+| `auth.register` | 회원가입 성공 | 이메일/전화 회원가입, OAuth 신규 사용자 |
+| `auth.invitation.created` | 초대 생성/재발송 | createInvitation, resendInvitation |
+| `auth.invitation.accepted` | 초대 수락 | acceptInvitation |
+
+---
+
+### Event Payloads
+
+#### `auth.login`
+
+```typescript
+{
+  userId: string;
+  provider: 'email' | 'phone' | 'google';
+  email?: string;
+  phone?: string;
+}
+```
+
+#### `auth.register`
+
+```typescript
+{
+  userId: string;
+  provider: 'email' | 'phone' | 'google';
+  email?: string;
+  phone?: string;
+  metadata?: Record<string, unknown>;  // 가입 시 전달된 커스텀 메타데이터
+}
+```
+
+`metadata`는 클라이언트가 register/OAuth 요청 body에 포함한 값이 그대로 전달됩니다.
+레퍼럴 코드, UTM 파라미터 등 앱 고유 데이터를 이벤트 구독자에게 전달할 때 사용합니다.
+
+#### `auth.invitation.created`
+
+```typescript
+{
+  invitationId: string;
+  email: string;
+  token: string;
+  roleId: number;
+  invitedBy: string;
+  expiresAt: string;           // ISO 8601
+  isResend: boolean;           // true면 재발송
+  metadata?: Record<string, unknown>;
+}
+```
+
+#### `auth.invitation.accepted`
+
+```typescript
+{
+  invitationId: string;
+  email: string;
+  userId: string;              // 생성된 사용자 ID
+  roleId: number;
+  invitedBy: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+---
+
+### Subscribing to Events
+
+```typescript
+import { authLoginEvent, authRegisterEvent } from '@spfn/auth/server';
+
+// 로그인 이벤트 구독
+authLoginEvent.subscribe(async (payload) => {
+    console.log('User logged in:', payload.userId, payload.provider);
+    await analytics.trackLogin(payload.userId);
+});
+
+// 회원가입 이벤트 구독 (metadata 활용)
+authRegisterEvent.subscribe(async (payload) => {
+    console.log('New user registered:', payload.userId);
+    if (payload.email) {
+        await emailService.sendWelcome(payload.email);
+    }
+
+    // 레퍼럴 코드 처리
+    const refCode = payload.metadata?.refCode as string;
+    if (refCode) {
+        await referralService.link(payload.userId, refCode);
+    }
+});
+```
+
+클라이언트에서 metadata를 전달하는 방법:
+
+```typescript
+// 이메일/전화 가입
+authApi.register.call({
+    body: { email, password, metadata: { refCode: 'CODE', utm_source: 'google' } }
+});
+
+// OAuth 가입
+authApi.oauthStart.call({
+    body: { provider: 'google', returnUrl: '/dashboard', metadata: { refCode: 'CODE' } }
+});
+```
+
+#### 초대 이벤트 구독 (이메일 발송 연동)
+
+```typescript
+import { invitationCreatedEvent, invitationAcceptedEvent } from '@spfn/auth/server';
+
+// 초대 생성 시 이메일 발송
+invitationCreatedEvent.subscribe(async (payload) => {
+    const inviteUrl = `${APP_URL}/invite/${payload.token}`;
+
+    await notificationService.send({
+        channel: 'email',
+        to: payload.email,
+        subject: payload.isResend ? '초대가 재발송되었습니다' : '초대장이 도착했습니다',
+        html: renderInviteEmail({
+            inviteUrl,
+            inviterName: payload.metadata?.inviterName,
+            message: payload.metadata?.message,
+        }),
+        tracking: {
+            category: 'invitation',
+            metadata: { invitationId: payload.invitationId },
+        },
+    });
+});
+
+// 초대 수락 시 온보딩 처리
+invitationAcceptedEvent.subscribe(async (payload) => {
+    await onboardingService.start(payload.userId);
+});
+```
+
+초대 생성 시 커스텀 만료 시간 지정:
+
+```typescript
+// expiresAt이 expiresInDays보다 우선
+authApi.createInvitation.call({
+    body: {
+        email: 'user@example.com',
+        roleId: 2,
+        expiresAt: '2026-03-20T00:00:00Z',
+        metadata: { inviterName: '홍길동', message: '함께 일해요!' },
+    }
+});
+```
+
+---
+
+### Job Integration
+
+`@spfn/core/job`과 연동하여 백그라운드 작업을 실행할 수 있습니다.
+
+```typescript
+import { job, defineJobRouter } from '@spfn/core/job';
+import { authRegisterEvent } from '@spfn/auth/server';
+
+// 회원가입 시 환영 이메일 발송 Job
+const sendWelcomeEmailJob = job('send-welcome-email')
+    .on(authRegisterEvent)
+    .handler(async ({ userId, email }) => {
+        if (email) {
+            await emailService.sendWelcome(email);
+        }
+    });
+
+// 회원가입 시 기본 설정 생성 Job
+const createDefaultSettingsJob = job('create-default-settings')
+    .on(authRegisterEvent)
+    .handler(async ({ userId }) => {
+        await settingsService.createDefaults(userId);
+    });
+
+export const jobRouter = defineJobRouter({
+    sendWelcomeEmailJob,
+    createDefaultSettingsJob,
+});
+```
+
+---
+
+### Event Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│              loginService() / registerService()                  │
+│                    oauthCallbackService()                        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    authLoginEvent.emit()
+                   authRegisterEvent.emit()
+                              │
+          ┌───────────────────┼───────────────────┐
+          ▼                   ▼                   ▼
+    ┌──────────┐       ┌──────────┐       ┌──────────┐
+    │ Backend  │       │   Job    │       │   SSE    │
+    │ Handler  │       │  Queue   │       │  Stream  │
+    └──────────┘       └──────────┘       └──────────┘
+    .subscribe()       .on(event)         (optional)
+          │                 │
+          ▼                 ▼
+    [Analytics,       [Background
+     Logging]          Processing]
+```
+
+---
+
+### Type Exports
+
+```typescript
+import type {
+    AuthLoginPayload,
+    AuthRegisterPayload,
+} from '@spfn/auth/server';
+```
+
+---
+
+## 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_SCOPES=email,profile  # default (comma-separated)
+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')[];
+}
+```
+
+---
+
+### Google API Access
+
+OAuth 로그인 후 저장된 access token으로 Google API를 호출할 수 있습니다.
+
+#### Custom Scopes 설정
+
+`SPFN_AUTH_GOOGLE_SCOPES` 환경변수로 추가 스코프를 요청합니다. 미설정 시 `email,profile`이 기본값입니다.
+
+```bash
+# Gmail + Calendar 읽기 권한 추가
+SPFN_AUTH_GOOGLE_SCOPES=email,profile,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/calendar.readonly
+```
+
+> **Note:** Google Cloud Console에서 해당 API를 활성화해야 합니다.
+
+#### Access Token 사용
+
+`getGoogleAccessToken(userId)`은 유효한 access token을 반환합니다. 토큰이 만료 임박(5분 이내) 또는 만료 상태이면 자동으로 refresh token을 사용하여 갱신합니다.
+
+```typescript
+import { getGoogleAccessToken } from '@spfn/auth/server';
+
+// 항상 유효한 토큰 반환 (만료 시 자동 갱신)
+const token = await getGoogleAccessToken(userId);
+
+// Gmail API 호출
+const response = await fetch(
+    'https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10',
+    { headers: { Authorization: `Bearer ${token}` } }
+);
+const data = await response.json();
+```
+
+**에러 케이스:**
+- Google 계정 미연결 → `'No Google account linked'`
+- Refresh token 없음 → `'Google refresh token not available'` (재로그인 필요)
+
+---
+
+### 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
@@ -1038,8 +1646,10 @@ Main user identity table.
 ```sql
 CREATE TABLE users (
   id BIGSERIAL PRIMARY KEY,
+  public_id UUID NOT NULL UNIQUE DEFAULT gen_random_uuid(),
   email TEXT UNIQUE,
   phone TEXT UNIQUE,
+  username TEXT UNIQUE,
   password_hash TEXT NOT NULL,
   password_change_required BOOLEAN DEFAULT false,
   role_id BIGINT REFERENCES roles(id) NOT NULL,
@@ -1057,7 +1667,9 @@ CREATE TABLE users (
 ```
 
 **Key Points:**
+- `public_id` is a UUID v4 for external-facing URLs and APIs (never expose internal `id`)
 - At least one of `email` OR `phone` required
+- `username` is unique and nullable (optional display/mention identifier)
 - `passwordHash` is bcrypt ($2b$10$..., 60 chars)
 - `roleId` references roles table (NOT NULL)
 
@@ -1167,7 +1779,7 @@ CREATE TABLE permissions (
 
 **Built-in Permissions:**
 - `auth:self:manage`
-- `user:read`, `user:write`, `user:delete`
+- `user:read`, `user:write`, `user:delete`, `user:invite`
 - `rbac:role:manage`, `rbac:permission:manage`
 
 ---
@@ -1260,7 +1872,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 (
@@ -1327,7 +1939,7 @@ await initializeAuth({
 
 **Permissions:**
 - `auth:self:manage` - Change password, rotate keys
-- `user:read`, `user:write`, `user:delete`
+- `user:read`, `user:write`, `user:delete`, `user:invite`
 - `rbac:role:manage`, `rbac:permission:manage`
 
 ---
@@ -1335,7 +1947,7 @@ await initializeAuth({
 ### Middleware Usage
 
 ```typescript
-import { authenticate, requirePermissions, requireRole } from '@spfn/auth/server';
+import { authenticate, requirePermissions, requireAnyPermission, requireRole } from '@spfn/auth/server';
 
 // Single permission
 app.bind(
@@ -1355,6 +1967,15 @@ app.bind(
   }
 );
 
+// Any of the permissions (at least one required)
+app.bind(
+  viewContentContract,
+  [authenticate, requireAnyPermission('content:read', 'admin:access')],
+  async (c) => {
+    // User has either content:read OR admin:access
+  }
+);
+
 // Role-based
 app.bind(
   adminDashboardContract,
@@ -1468,10 +2089,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
@@ -1817,7 +2450,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
@@ -1957,6 +2590,6 @@ MIT License - See LICENSE file for details.
 
 ---
 
-**Last Updated:** 2025-12-07
-**Document Version:** 2.2.0 (Technical Documentation)
-**Package Version:** 0.1.0-alpha.88
+**Last Updated:** 2026-02-23
+**Document Version:** 2.6.0 (Technical Documentation)
+**Package Version:** 0.2.0-beta.15