@spfn/auth 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/server.d.ts

@@ -1,13 +1,14 @@
-import { k as AuthInitOptions, l as KeyAlgorithmType, n as InvitationStatus, f as VerificationPurpose, j as PermissionCategory, q as AuthContext } from './dto-CLYtuAom.js';
-export { B as ChangePasswordParams, w as CheckAccountExistsParams, C as CheckAccountExistsResult, X as EmailSchema, I as INVITATION_STATUSES, K as KEY_ALGORITHM, y as LoginParams, L as LoginResult, z as LogoutParams, Z as PasswordSchema, Y as PhoneSchema, x as RegisterParams, O as RegisterPublicKeyParams, a as RegisterResult, T as RevokeKeyParams, Q as RotateKeyParams, b as RotateKeyResult, e as SOCIAL_PROVIDERS, F as SendVerificationCodeParams, S as SendVerificationCodeResult, p as SocialProvider, _ as TargetTypeSchema, d as USER_STATUSES, o as UserStatus, h as VERIFICATION_PURPOSES, g as VERIFICATION_TARGET_TYPES, $ as VerificationPurposeSchema, V as VerificationTargetType, G as VerifyCodeParams, H as VerifyCodeResult, m as authRouter, W as authenticate, v as changePasswordService, r as checkAccountExistsService, t as loginService, u as logoutService, J as registerPublicKeyService, s as registerService, N as revokeKeyService, M as rotateKeyService, D as sendVerificationCodeService, E as verifyCodeService } from './dto-CLYtuAom.js';
+import { k as AuthInitOptions, l as KeyAlgorithmType, n as InvitationStatus, f as VerificationPurpose, j as PermissionCategory, p as SocialProvider, q as AuthContext } from './authenticate-BmzJ6hTF.js';
+export { B as ChangePasswordParams, w as CheckAccountExistsParams, C as CheckAccountExistsResult, a5 as EmailSchema, I as INVITATION_STATUSES, K as KEY_ALGORITHM, y as LoginParams, L as LoginResult, z as LogoutParams, a2 as OAuthCallbackParams, a3 as OAuthCallbackResult, a1 as OAuthStartParams, O as OAuthStartResult, a7 as PasswordSchema, a6 as PhoneSchema, x as RegisterParams, Q as RegisterPublicKeyParams, a as RegisterResult, W as RevokeKeyParams, T as RotateKeyParams, b as RotateKeyResult, e as SOCIAL_PROVIDERS, F as SendVerificationCodeParams, S as SendVerificationCodeResult, a8 as TargetTypeSchema, d as USER_STATUSES, o as UserStatus, h as VERIFICATION_PURPOSES, g as VERIFICATION_TARGET_TYPES, a9 as VerificationPurposeSchema, V as VerificationTargetType, G as VerifyCodeParams, H as VerifyCodeResult, m as authRouter, a4 as authenticate, Z as buildOAuthErrorUrl, v as changePasswordService, r as checkAccountExistsService, $ as getEnabledOAuthProviders, a0 as getGoogleAccessToken, _ as isOAuthProviderEnabled, t as loginService, u as logoutService, Y as oauthCallbackService, X as oauthStartService, J as registerPublicKeyService, s as registerService, N as revokeKeyService, M as rotateKeyService, D as sendVerificationCodeService, E as verifyCodeService } from './authenticate-BmzJ6hTF.js';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { UserProfile as UserProfile$1 } from '@spfn/auth';
+import { UserProfile as UserProfile$1, ProfileInfo } from '@spfn/auth';
 import { BaseRepository } from '@spfn/core/db';
 import { Context } from 'hono';
 import * as _spfn_core_route from '@spfn/core/route';
 import { Algorithm } from 'jsonwebtoken';
 import * as _spfn_core_logger from '@spfn/core/logger';
-import '@sinclair/typebox';
+import * as _spfn_core_event from '@spfn/core/event';
+import * as _sinclair_typebox from '@sinclair/typebox';
 import '@spfn/auth/server';
 
 /**
@@ -406,6 +407,19 @@ declare function hasAnyPermission(userId: string | number | bigint, permissionNa
  * ```
  */
 declare function hasAllPermissions(userId: string | number | bigint, permissionNames: string[]): Promise<boolean>;
+/**
+ * Get user's role name
+ *
+ * @param userId - User ID
+ * @returns Role name or null if user has no role
+ *
+ * @example
+ * ```typescript
+ * const role = await getUserRole('123');
+ * // 'admin' or null
+ * ```
+ */
+declare function getUserRole(userId: string | number | bigint): Promise<string | null>;
 /**
  * Check if user has a specific role
  *
@@ -1253,10 +1267,30 @@ declare function getAuthSessionService(userId: string | number | bigint): Promis
 /**
  * @spfn/auth - User Profile Service
  *
- * Service for retrieving user profile information
+ * Service for retrieving and updating user profile information
  * Returns full user info with profile data
  */
 
+/**
+ * Profile update parameters
+ * All fields are optional, empty string will be converted to null
+ */
+interface UpdateProfileParams {
+    displayName?: string;
+    firstName?: string;
+    lastName?: string;
+    avatarUrl?: string;
+    bio?: string;
+    locale?: string;
+    timezone?: string;
+    dateOfBirth?: string;
+    gender?: string;
+    website?: string;
+    location?: string;
+    company?: string;
+    jobTitle?: string;
+    metadata?: Record<string, any>;
+}
 /**
  * Get user profile information
  *
@@ -1272,369 +1306,26 @@ declare function getAuthSessionService(userId: string | number | bigint): Promis
  * ```
  */
 declare function getUserProfileService(userId: string | number | bigint): Promise<UserProfile$1>;
-
-/**
- * @spfn/auth - Email Template Types
- *
- * Type definitions for customizable email templates
- */
-/**
- * Common template result
- */
-interface EmailTemplateResult {
-    subject: string;
-    text: string;
-    html: string;
-}
-/**
- * Verification code template parameters
- */
-interface VerificationCodeParams {
-    code: string;
-    purpose: 'registration' | 'login' | 'password_reset' | string;
-    expiresInMinutes?: number;
-    appName?: string;
-}
 /**
- * Email template provider interface
+ * Update user profile (upsert)
  *
- * Implement this interface to create custom email templates
+ * Creates profile if not exists, updates if exists
+ * Empty strings are converted to null
  *
- * @example
- * ```typescript
- * import { registerEmailTemplates } from '@spfn/auth/server';
- *
- * registerEmailTemplates({
- *     verificationCode: (params) => ({
- *         subject: 'Your Code',
- *         text: `Code: ${params.code}`,
- *         html: `<h1>Code: ${params.code}</h1>`,
- *     }),
- * });
- * ```
- */
-interface EmailTemplateProvider {
-    /**
-     * Verification code email template
-     */
-    verificationCode?(params: VerificationCodeParams): EmailTemplateResult;
-    /**
-     * Welcome email template (after registration)
-     */
-    welcome?(params: {
-        email: string;
-        appName?: string;
-    }): EmailTemplateResult;
-    /**
-     * Password reset email template
-     */
-    passwordReset?(params: {
-        resetLink: string;
-        expiresInMinutes?: number;
-        appName?: string;
-    }): EmailTemplateResult;
-    /**
-     * Invitation email template
-     */
-    invitation?(params: {
-        inviteLink: string;
-        inviterName?: string;
-        roleName?: string;
-        appName?: string;
-    }): EmailTemplateResult;
-}
-
-/**
- * @spfn/auth - Email Template Registry
- *
- * Manages custom email template registration and fallback to defaults
- */
-
-/**
- * Register custom email templates
- *
- * Templates not provided will fall back to defaults
- *
- * @param templates - Custom template implementations
+ * @param userId - User ID
+ * @param params - Profile fields to update
+ * @returns Updated profile info
  *
  * @example
  * ```typescript
- * import { registerEmailTemplates } from '@spfn/auth/server';
- *
- * // Override verification code template with custom design
- * registerEmailTemplates({
- *     verificationCode: ({ code, purpose, expiresInMinutes }) => ({
- *         subject: `[MyApp] Your verification code`,
- *         text: `Your code is: ${code}`,
- *         html: `
- *             <div style="font-family: Arial;">
- *                 <h1>Welcome to MyApp!</h1>
- *                 <p>Your code: <strong>${code}</strong></p>
- *             </div>
- *         `,
- *     }),
+ * const profile = await updateUserProfileService(123, {
+ *     displayName: 'John Doe',
+ *     bio: 'Software Engineer',
+ *     location: '', // will be saved as null
  * });
  * ```
  */
-declare function registerEmailTemplates(templates: Partial<EmailTemplateProvider>): void;
-/**
- * Get verification code template
- *
- * Uses custom template if registered, otherwise falls back to default
- */
-declare function getVerificationCodeTemplate(params: VerificationCodeParams): EmailTemplateResult;
-/**
- * Get welcome template
- */
-declare function getWelcomeTemplate(params: {
-    email: string;
-    appName?: string;
-}): EmailTemplateResult;
-/**
- * Get password reset template
- */
-declare function getPasswordResetTemplate(params: {
-    resetLink: string;
-    expiresInMinutes?: number;
-    appName?: string;
-}): EmailTemplateResult;
-/**
- * Get invitation template
- */
-declare function getInvitationTemplate(params: {
-    inviteLink: string;
-    inviterName?: string;
-    roleName?: string;
-    appName?: string;
-}): EmailTemplateResult;
-
-/**
- * @spfn/auth - Email Service Types
- *
- * Type definitions for email sending service
- */
-/**
- * Parameters for sending email
- */
-interface SendEmailParams {
-    /**
-     * Recipient email address
-     */
-    to: string;
-    /**
-     * Email subject
-     */
-    subject: string;
-    /**
-     * Plain text content
-     */
-    text?: string;
-    /**
-     * HTML content
-     */
-    html?: string;
-    /**
-     * Purpose of the email (for logging)
-     */
-    purpose?: string;
-}
-/**
- * Result of sending email
- */
-interface SendEmailResult {
-    /**
-     * Whether email was sent successfully
-     */
-    success: boolean;
-    /**
-     * Message ID from email provider (if successful)
-     */
-    messageId?: string;
-    /**
-     * Error message (if failed)
-     */
-    error?: string;
-}
-/**
- * Email Provider Interface
- *
- * Implement this interface to create custom email providers
- *
- * @example
- * ```typescript
- * import { EmailProvider, registerEmailProvider } from '@spfn/auth/server/services/email';
- *
- * const sendgridProvider: EmailProvider = {
- *     name: 'sendgrid',
- *     sendEmail: async (params) => {
- *         // Your SendGrid implementation
- *         return { success: true, messageId: '...' };
- *     }
- * };
- *
- * registerEmailProvider(sendgridProvider);
- * ```
- */
-interface EmailProvider {
-    /**
-     * Provider name (e.g., 'aws-ses', 'sendgrid', 'custom')
-     */
-    name: string;
-    /**
-     * Send email via this provider
-     *
-     * @param params - Email parameters
-     * @returns Send result
-     */
-    sendEmail(params: SendEmailParams): Promise<SendEmailResult>;
-}
-
-/**
- * @spfn/auth - Email Provider Management
- *
- * Manages email provider registration and fallback behavior
- */
-
-/**
- * Register a custom email provider
- *
- * @param provider - Custom email provider implementation
- *
- * @example
- * ```typescript
- * import { registerEmailProvider } from '@spfn/auth/server/services/email';
- *
- * const sendgridProvider = {
- *     name: 'sendgrid',
- *     sendEmail: async (params) => {
- *         // SendGrid implementation
- *         return { success: true, messageId: '...' };
- *     }
- * };
- *
- * registerEmailProvider(sendgridProvider);
- * ```
- */
-declare function registerEmailProvider(provider: EmailProvider): void;
-/**
- * Send email using the registered provider
- *
- * Falls back to development mode (console only) if no provider is registered
- *
- * @param params - Email parameters
- * @returns Send result
- */
-declare function sendEmail(params: SendEmailParams): Promise<SendEmailResult>;
-
-/**
- * @spfn/auth - SMS Service Types
- *
- * Type definitions for SMS sending service
- */
-/**
- * Parameters for sending SMS
- */
-interface SendSMSParams {
-    /**
-     * Phone number in E.164 format (e.g., +821012345678)
-     */
-    phone: string;
-    /**
-     * SMS message content
-     */
-    message: string;
-    /**
-     * Purpose of the SMS (for logging)
-     */
-    purpose?: string;
-}
-/**
- * Result of sending SMS
- */
-interface SendSMSResult {
-    /**
-     * Whether SMS was sent successfully
-     */
-    success: boolean;
-    /**
-     * Message ID from SMS provider (if successful)
-     */
-    messageId?: string;
-    /**
-     * Error message (if failed)
-     */
-    error?: string;
-}
-/**
- * SMS Provider Interface
- *
- * Implement this interface to create custom SMS providers
- *
- * @example
- * ```typescript
- * import { SMSProvider, registerSMSProvider } from '@spfn/auth/server/services/sms';
- *
- * const twilioProvider: SMSProvider = {
- *     name: 'twilio',
- *     sendSMS: async (params) => {
- *         // Your Twilio implementation
- *         return { success: true, messageId: '...' };
- *     }
- * };
- *
- * registerSMSProvider(twilioProvider);
- * ```
- */
-interface SMSProvider {
-    /**
-     * Provider name (e.g., 'aws-sns', 'twilio', 'custom')
-     */
-    name: string;
-    /**
-     * Send SMS via this provider
-     *
-     * @param params - SMS parameters
-     * @returns Send result
-     */
-    sendSMS(params: SendSMSParams): Promise<SendSMSResult>;
-}
-
-/**
- * @spfn/auth - SMS Provider Management
- *
- * Manages SMS provider registration and fallback behavior
- */
-
-/**
- * Register a custom SMS provider
- *
- * @param provider - Custom SMS provider implementation
- *
- * @example
- * ```typescript
- * import { registerSMSProvider } from '@spfn/auth/server/services/sms';
- *
- * const twilioProvider = {
- *     name: 'twilio',
- *     sendSMS: async (params) => {
- *         // Twilio implementation
- *         return { success: true, messageId: '...' };
- *     }
- * };
- *
- * registerSMSProvider(twilioProvider);
- * ```
- */
-declare function registerSMSProvider(provider: SMSProvider): void;
-/**
- * Send SMS using the registered provider
- *
- * Falls back to development mode (console only) if no provider is registered
- *
- * @param params - SMS parameters
- * @returns Send result
- */
-declare function sendSMS(params: SendSMSParams): Promise<SendSMSResult>;
+declare function updateUserProfileService(userId: string | number | bigint, params: UpdateProfileParams): Promise<ProfileInfo>;
 
 /**
  * @spfn/auth - Database Schema Definition
@@ -4130,6 +3821,32 @@ declare class UserProfilesRepository extends BaseRepository {
         company: string | null;
         jobTitle: string | null;
     }>;
+    /**
+     * 프로필 Upsert (by User ID)
+     *
+     * 프로필이 없으면 생성, 있으면 업데이트
+     * 새로 생성 시 displayName은 필수 (없으면 'User'로 설정)
+     */
+    upsertByUserId(userId: number, data: Partial<Omit<NewUserProfile, 'userId'>>): Promise<{
+        userId: number;
+        id: number;
+        displayName: string;
+        createdAt: Date;
+        updatedAt: Date;
+        metadata: Record<string, any> | null;
+        firstName: string | null;
+        lastName: string | null;
+        avatarUrl: string | null;
+        bio: string | null;
+        locale: string | null;
+        timezone: string | null;
+        dateOfBirth: string | null;
+        gender: string | null;
+        website: string | null;
+        location: string | null;
+        company: string | null;
+        jobTitle: string | null;
+    }>;
     /**
      * User ID로 프로필 데이터 조회 (formatted)
      *
@@ -4148,6 +3865,7 @@ declare class UserProfilesRepository extends BaseRepository {
         location: string | null;
         company: string | null;
         jobTitle: string | null;
+        metadata: Record<string, any> | null;
         createdAt: Date;
         updatedAt: Date;
     } | null>;
@@ -4422,6 +4140,136 @@ declare class InvitationsRepository extends BaseRepository {
 }
 declare const invitationsRepository: InvitationsRepository;
 
+/**
+ * Social Accounts Repository
+ *
+ * OAuth 소셜 계정 데이터 관리를 위한 Repository
+ * BaseRepository를 상속받아 자동 트랜잭션 컨텍스트 지원 및 Read/Write 분리
+ */
+
+/**
+ * Social Accounts Repository 클래스
+ */
+declare class SocialAccountsRepository extends BaseRepository {
+    /**
+     * provider와 providerUserId로 소셜 계정 조회
+     * Read replica 사용
+     */
+    findByProviderAndProviderId(provider: SocialProvider, providerUserId: string): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number;
+        provider: "google" | "github" | "kakao" | "naver";
+        providerUserId: string;
+        providerEmail: string | null;
+        accessToken: string | null;
+        refreshToken: string | null;
+        tokenExpiresAt: Date | null;
+    }>;
+    /**
+     * userId로 모든 소셜 계정 조회
+     * Read replica 사용
+     */
+    findByUserId(userId: number): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number;
+        provider: "google" | "github" | "kakao" | "naver";
+        providerUserId: string;
+        providerEmail: string | null;
+        accessToken: string | null;
+        refreshToken: string | null;
+        tokenExpiresAt: Date | null;
+    }[]>;
+    /**
+     * userId와 provider로 소셜 계정 조회
+     * Read replica 사용
+     */
+    findByUserIdAndProvider(userId: number, provider: SocialProvider): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number;
+        provider: "google" | "github" | "kakao" | "naver";
+        providerUserId: string;
+        providerEmail: string | null;
+        accessToken: string | null;
+        refreshToken: string | null;
+        tokenExpiresAt: Date | null;
+    }>;
+    /**
+     * 소셜 계정 생성
+     * Write primary 사용
+     */
+    create(data: NewUserSocialAccount): Promise<{
+        userId: number;
+        id: number;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: "google" | "github" | "kakao" | "naver";
+        providerUserId: string;
+        providerEmail: string | null;
+        accessToken: string | null;
+        refreshToken: string | null;
+        tokenExpiresAt: Date | null;
+    }>;
+    /**
+     * 토큰 정보 업데이트
+     * Write primary 사용
+     */
+    updateTokens(id: number, data: {
+        accessToken?: string | null;
+        refreshToken?: string | null;
+        tokenExpiresAt?: Date | null;
+    }): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number;
+        provider: "google" | "github" | "kakao" | "naver";
+        providerUserId: string;
+        providerEmail: string | null;
+        accessToken: string | null;
+        refreshToken: string | null;
+        tokenExpiresAt: Date | null;
+    }>;
+    /**
+     * 소셜 계정 삭제
+     * Write primary 사용
+     */
+    deleteById(id: number): Promise<{
+        userId: number;
+        id: number;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: "google" | "github" | "kakao" | "naver";
+        providerUserId: string;
+        providerEmail: string | null;
+        accessToken: string | null;
+        refreshToken: string | null;
+        tokenExpiresAt: Date | null;
+    }>;
+    /**
+     * userId와 provider로 소셜 계정 삭제
+     * Write primary 사용
+     */
+    deleteByUserIdAndProvider(userId: number, provider: SocialProvider): Promise<{
+        userId: number;
+        id: number;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: "google" | "github" | "kakao" | "naver";
+        providerUserId: string;
+        providerEmail: string | null;
+        accessToken: string | null;
+        refreshToken: string | null;
+        tokenExpiresAt: Date | null;
+    }>;
+}
+declare const socialAccountsRepository: SocialAccountsRepository;
+
 /**
  * @spfn/auth - Password Helpers
  *
@@ -4715,6 +4563,57 @@ declare const requireAnyPermission: _spfn_core_route.NamedMiddlewareFactory<"any
  */
 declare const requireRole: _spfn_core_route.NamedMiddlewareFactory<"role", string[]>;
 
+/**
+ * @spfn/auth - Role Guard Middleware
+ *
+ * Middleware for role-based access control with allow/deny options
+ */
+/**
+ * Role guard options
+ */
+interface RoleGuardOptions {
+    /**
+     * Roles to allow (OR condition)
+     * User must have at least one of these roles
+     */
+    allow?: string[];
+    /**
+     * Roles to deny
+     * User with any of these roles will be rejected
+     */
+    deny?: string[];
+}
+/**
+ * Role-based access control middleware
+ *
+ * Must be used after authenticate middleware
+ *
+ * @param options - Role guard options (allow/deny)
+ * @returns Middleware function
+ *
+ * @example Allow specific roles
+ * ```typescript
+ * export const adminRoute = route.get('/admin')
+ *   .use([authenticate, roleGuard({ allow: ['admin', 'superadmin'] })])
+ *   .handler(async (c) => { ... });
+ * ```
+ *
+ * @example Deny specific roles
+ * ```typescript
+ * export const publicRoute = route.get('/content')
+ *   .use([authenticate, roleGuard({ deny: ['banned', 'suspended'] })])
+ *   .handler(async (c) => { ... });
+ * ```
+ *
+ * @example Combined allow and deny
+ * ```typescript
+ * export const managerRoute = route.get('/manage')
+ *   .use([authenticate, roleGuard({ allow: ['admin', 'manager'], deny: ['suspended'] })])
+ *   .handler(async (c) => { ... });
+ * ```
+ */
+declare const roleGuard: _spfn_core_route.NamedMiddlewareFactory<"roleGuard", [options: RoleGuardOptions]>;
+
 /**
  * Auth Context Helpers
  *
@@ -4917,6 +4816,8 @@ declare const COOKIE_NAMES: {
     readonly SESSION: "spfn_session";
     /** Current key ID (for key rotation) */
     readonly SESSION_KEY_ID: "spfn_session_key_id";
+    /** Pending OAuth session (privateKey, keyId, algorithm) - temporary during OAuth flow */
+    readonly OAUTH_PENDING: "spfn_oauth_pending";
 };
 /**
  * Parse duration string to seconds
@@ -4973,6 +4874,114 @@ declare function getAuthConfig(): AuthConfig;
  */
 declare function getSessionTtl(override?: string | number): number;
 
+/**
+ * Google OAuth 2.0 Client
+ *
+ * Authorization Code Flow 구현
+ * - getGoogleAuthUrl: Google 로그인 URL 생성
+ * - exchangeCodeForTokens: Code를 Token으로 교환
+ * - getGoogleUserInfo: 사용자 정보 조회
+ */
+interface GoogleTokenResponse {
+    access_token: string;
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+    token_type: string;
+    id_token?: string;
+}
+interface GoogleUserInfo {
+    id: string;
+    email: string;
+    verified_email: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string;
+    locale?: string;
+}
+/**
+ * Google OAuth가 활성화되어 있는지 확인
+ */
+declare function isGoogleOAuthEnabled(): boolean;
+/**
+ * Google OAuth 설정 가져오기
+ */
+declare function getGoogleOAuthConfig(): {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+};
+/**
+ * Google 로그인 URL 생성
+ *
+ * @param state - CSRF 방지용 state 파라미터 (암호화된 returnUrl + nonce 포함)
+ * @param scopes - 요청할 OAuth scopes (기본: env 또는 email, profile)
+ */
+declare function getGoogleAuthUrl(state: string, scopes?: string[]): string;
+/**
+ * Authorization Code를 Token으로 교환
+ *
+ * @param code - Google에서 받은 authorization code
+ */
+declare function exchangeCodeForTokens(code: string): Promise<GoogleTokenResponse>;
+/**
+ * Access Token으로 Google 사용자 정보 조회
+ *
+ * @param accessToken - Google access token
+ */
+declare function getGoogleUserInfo(accessToken: string): Promise<GoogleUserInfo>;
+/**
+ * Refresh Token으로 새 Access Token 획득
+ *
+ * @param refreshToken - Google refresh token
+ */
+declare function refreshAccessToken(refreshToken: string): Promise<GoogleTokenResponse>;
+
+/**
+ * OAuth State Management
+ *
+ * CSRF 방지를 위한 state 파라미터 암호화/복호화
+ * - returnUrl: OAuth 성공 후 리다이렉트할 URL
+ * - nonce: CSRF 방지용 일회용 토큰
+ * - provider: OAuth provider (google, github 등)
+ * - publicKey, keyId, fingerprint, algorithm: 클라이언트 키 정보
+ * - expiresAt: state 만료 시간
+ */
+
+interface OAuthState {
+    returnUrl: string;
+    nonce: string;
+    provider: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm: KeyAlgorithmType;
+}
+interface CreateOAuthStateParams {
+    provider: string;
+    returnUrl: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm: KeyAlgorithmType;
+}
+/**
+ * OAuth state 생성 및 암호화
+ *
+ * @param params - state 생성에 필요한 파라미터
+ * @returns 암호화된 state 문자열
+ */
+declare function createOAuthState(params: CreateOAuthStateParams): Promise<string>;
+/**
+ * OAuth state 복호화 및 검증
+ *
+ * @param encryptedState - 암호화된 state 문자열
+ * @returns 복호화된 state 객체
+ * @throws Error if state is invalid or expired (JWE exp claim으로 자동 검증)
+ */
+declare function verifyOAuthState(encryptedState: string): Promise<OAuthState>;
+
 /**
  * @spfn/auth - Centralized Logger
  *
@@ -4985,6 +4994,7 @@ declare const authLogger: {
         general: _spfn_core_logger.Logger;
         login: _spfn_core_logger.Logger;
         keyRotation: _spfn_core_logger.Logger;
+        oauth: _spfn_core_logger.Logger;
     };
     service: _spfn_core_logger.Logger;
     setup: _spfn_core_logger.Logger;
@@ -5068,4 +5078,61 @@ interface AuthLifecycleConfig {
  */
 declare function createAuthLifecycle(options?: AuthInitOptions): AuthLifecycleConfig;
 
-export { type AuthConfig, AuthContext, COOKIE_NAMES, type EmailProvider, type EmailTemplateProvider, type EmailTemplateResult, type Invitation, InvitationStatus, InvitationsRepository, KeyAlgorithmType, type KeyPair, KeysRepository, type NewInvitation, type NewPermission, type NewPermissionEntity, type NewRole, type NewRoleEntity, type NewRolePermission, type NewUser, type NewUserPermission, type NewUserProfile, type NewUserPublicKey, type NewUserSocialAccount, type NewVerificationCode, type Permission, type PermissionEntity, PermissionsRepository, type Role, type RoleEntity, type RolePermission, RolePermissionsRepository, RolesRepository, type SMSProvider, type SendEmailParams, type SendEmailResult, type SendSMSParams, type SendSMSResult, type SessionData, type SessionPayload, type TokenPayload, type User, type UserPermission, UserPermissionsRepository, type UserProfile, UserProfilesRepository, type UserPublicKey, type UserSocialAccount, UsersRepository, type VerificationCode, type VerificationCodeParams, VerificationCodesRepository, VerificationPurpose, acceptInvitation, addPermissionToRole, authLogger, authSchema, cancelInvitation, configureAuth, createAuthLifecycle, createInvitation, createRole, decodeToken, deleteInvitation, deleteRole, expireOldInvitations, generateClientToken, generateKeyPair, generateKeyPairES256, generateKeyPairRS256, generateToken, getAllRoles, getAuth, getAuthConfig, getAuthSessionService, getInvitationByToken, getInvitationTemplate, getInvitationWithDetails, getKeyId, getKeySize, getPasswordResetTemplate, getRoleByName, getRolePermissions, getSessionInfo, getSessionTtl, getUser, getUserByEmailService, getUserByIdService, getUserByPhoneService, getUserId, getUserPermissions, getUserProfileService, getVerificationCodeTemplate, getWelcomeTemplate, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initializeAuth, invitationsRepository, keysRepository, listInvitations, parseDuration, permissions, permissionsRepository, registerEmailProvider, registerEmailTemplates, registerSMSProvider, removePermissionFromRole, requireAnyPermission, requirePermissions, requireRole, resendInvitation, rolePermissions, rolePermissionsRepository, roles, rolesRepository, sealSession, sendEmail, sendSMS, setRolePermissions, shouldRefreshSession, shouldRotateKey, unsealSession, updateLastLoginService, updateRole, updateUserService, userInvitations, userPermissions, userPermissionsRepository, userProfiles, userProfilesRepository, userPublicKeys, userSocialAccounts, users, usersRepository, validateInvitation, validatePasswordStrength, verificationCodes, verificationCodesRepository, verifyClientToken, verifyKeyFingerprint, verifyPassword, verifyToken };
+/**
+ * @spfn/auth - Auth Events
+ *
+ * 인증 관련 이벤트 정의
+ * - auth.login: 로그인 성공 시 (기존 사용자만)
+ * - auth.register: 회원가입 성공 시 (OAuth 신규 가입 포함)
+ */
+/**
+ * Auth provider type
+ */
+declare const AuthProviderSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">, _sinclair_typebox.TLiteral<"google">]>;
+/**
+ * auth.login - 로그인 성공 이벤트
+ *
+ * 발행 시점:
+ * - 이메일/전화 로그인 성공 시
+ * - OAuth 기존 사용자 로그인 시
+ *
+ * @example
+ * ```typescript
+ * authLoginEvent.subscribe(async (payload) => {
+ *     await analytics.trackLogin(payload.userId, payload.provider);
+ * });
+ * ```
+ */
+declare const authLoginEvent: _spfn_core_event.EventDef<{
+    email?: string | undefined;
+    phone?: string | undefined;
+    userId: string;
+    provider: "email" | "phone" | "google";
+}>;
+/**
+ * auth.register - 회원가입 성공 이벤트
+ *
+ * 발행 시점:
+ * - 이메일/전화 회원가입 성공 시
+ * - OAuth 신규 사용자 가입 시
+ *
+ * @example
+ * ```typescript
+ * authRegisterEvent.subscribe(async (payload) => {
+ *     await emailService.sendWelcome(payload.email);
+ * });
+ * ```
+ */
+declare const authRegisterEvent: _spfn_core_event.EventDef<{
+    email?: string | undefined;
+    phone?: string | undefined;
+    userId: string;
+    provider: "email" | "phone" | "google";
+}>;
+/**
+ * Auth event payload types
+ */
+type AuthLoginPayload = typeof authLoginEvent._payload;
+type AuthRegisterPayload = typeof authRegisterEvent._payload;
+
+export { type AuthConfig, AuthContext, type AuthLoginPayload, AuthProviderSchema, type AuthRegisterPayload, COOKIE_NAMES, type CreateOAuthStateParams, type GoogleTokenResponse, type GoogleUserInfo, type Invitation, InvitationStatus, InvitationsRepository, KeyAlgorithmType, type KeyPair, KeysRepository, type NewInvitation, type NewPermission, type NewPermissionEntity, type NewRole, type NewRoleEntity, type NewRolePermission, type NewUser, type NewUserPermission, type NewUserProfile, type NewUserPublicKey, type NewUserSocialAccount, type NewVerificationCode, type OAuthState, type Permission, type PermissionEntity, PermissionsRepository, type Role, type RoleEntity, type RoleGuardOptions, type RolePermission, RolePermissionsRepository, RolesRepository, type SessionData, type SessionPayload, SocialAccountsRepository, SocialProvider, type TokenPayload, type UpdateProfileParams, type User, type UserPermission, UserPermissionsRepository, type UserProfile, UserProfilesRepository, type UserPublicKey, type UserSocialAccount, UsersRepository, type VerificationCode, VerificationCodesRepository, VerificationPurpose, acceptInvitation, addPermissionToRole, authLogger, authLoginEvent, authRegisterEvent, authSchema, cancelInvitation, configureAuth, createAuthLifecycle, createInvitation, createOAuthState, createRole, decodeToken, deleteInvitation, deleteRole, exchangeCodeForTokens, expireOldInvitations, generateClientToken, generateKeyPair, generateKeyPairES256, generateKeyPairRS256, generateToken, getAllRoles, getAuth, getAuthConfig, getAuthSessionService, getGoogleAuthUrl, getGoogleOAuthConfig, getGoogleUserInfo, getInvitationByToken, getInvitationWithDetails, getKeyId, getKeySize, getRoleByName, getRolePermissions, getSessionInfo, getSessionTtl, getUser, getUserByEmailService, getUserByIdService, getUserByPhoneService, getUserId, getUserPermissions, getUserProfileService, getUserRole, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initializeAuth, invitationsRepository, isGoogleOAuthEnabled, keysRepository, listInvitations, parseDuration, permissions, permissionsRepository, refreshAccessToken, removePermissionFromRole, requireAnyPermission, requirePermissions, requireRole, resendInvitation, roleGuard, rolePermissions, rolePermissionsRepository, roles, rolesRepository, sealSession, setRolePermissions, shouldRefreshSession, shouldRotateKey, socialAccountsRepository, unsealSession, updateLastLoginService, updateRole, updateUserProfileService, updateUserService, userInvitations, userPermissions, userPermissionsRepository, userProfiles, userProfilesRepository, userPublicKeys, userSocialAccounts, users, usersRepository, validateInvitation, validatePasswordStrength, verificationCodes, verificationCodesRepository, verifyClientToken, verifyKeyFingerprint, verifyOAuthState, verifyPassword, verifyToken };