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

package/dist/server.d.ts

@@ -1,13 +1,18 @@
-import { k as AuthInitOptions, l as KeyAlgorithmType, n as InvitationStatus, f as VerificationPurpose, j as PermissionCategory, q as AuthContext } from './dto-Bb2qFUO6.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, b as RegisterResult, T as RevokeKeyParams, Q as RotateKeyParams, c 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-Bb2qFUO6.js';
+import { i as AuthInitOptions, d as VerificationPurpose, h as PermissionCategory, j as AuthContext } from './authenticate-B_HkYBzq.js';
+export { u as ChangePasswordParams, p as CheckAccountExistsParams, C as CheckAccountExistsResult, a1 as EmailSchema, I as IssueOneTimeTokenResult, s as LoginParams, L as LoginResult, t as LogoutParams, Z as OAuthCallbackParams, _ as OAuthCallbackResult, Y as OAuthStartParams, O as OAuthStartResult, a3 as PasswordSchema, a2 as PhoneSchema, q as RegisterParams, F as RegisterPublicKeyParams, a as RegisterResult, H as RevokeKeyParams, G as RotateKeyParams, b as RotateKeyResult, x as SendVerificationCodeParams, S as SendVerificationCodeResult, a4 as TargetTypeSchema, f as VERIFICATION_PURPOSES, e as VERIFICATION_TARGET_TYPES, a5 as VerificationPurposeSchema, V as VerificationTargetType, y as VerifyCodeParams, z as VerifyCodeResult, m as authRouter, $ as authenticate, Q as buildOAuthErrorUrl, o as changePasswordService, k as checkAccountExistsService, W as getEnabledOAuthProviders, X as getGoogleAccessToken, T as isOAuthProviderEnabled, J as issueOneTimeTokenService, l as loginService, n as logoutService, N as oauthCallbackService, M as oauthStartService, a0 as optionalAuth, B as registerPublicKeyService, r as registerService, E as revokeKeyService, D as rotateKeyService, v as sendVerificationCodeService, w as verifyCodeService, K as verifyOneTimeTokenService } from './authenticate-B_HkYBzq.js';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { K as KeyAlgorithmType, b as InvitationStatus, d as SocialProvider } from './types-B1CzVZkU.js';
+export { I as INVITATION_STATUSES, a as KEY_ALGORITHM, S as SOCIAL_PROVIDERS, U as USER_STATUSES, c as UserStatus } from './types-B1CzVZkU.js';
 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';
+export { S as SessionData, g as getSessionInfo, s as sealSession, a as shouldRefreshSession, u as unsealSession } from './session-Dbvz9Sdp.js';
+import { SSETokenStore, SSETokenManager } from '@spfn/core/event/sse';
 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';
 
 /**
@@ -78,6 +83,23 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        publicId: drizzle_orm_pg_core.PgColumn<{
+            name: "public_id";
+            tableName: "users";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         email: drizzle_orm_pg_core.PgColumn<{
             name: "email";
             tableName: "users";
@@ -112,6 +134,23 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        username: drizzle_orm_pg_core.PgColumn<{
+            name: "username";
+            tableName: "users";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         passwordHash: drizzle_orm_pg_core.PgColumn<{
             name: "password_hash";
             tableName: "users";
@@ -150,11 +189,11 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "users";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -250,8 +289,10 @@ declare function getUserByIdService(userId: number): Promise<{
     createdAt: Date;
     updatedAt: Date;
     id: number;
+    publicId: string;
     email: string | null;
     phone: string | null;
+    username: string | null;
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
@@ -267,8 +308,10 @@ declare function getUserByEmailService(email: string): Promise<{
     createdAt: Date;
     updatedAt: Date;
     id: number;
+    publicId: string;
     email: string | null;
     phone: string | null;
+    username: string | null;
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
@@ -284,8 +327,10 @@ declare function getUserByPhoneService(phone: string): Promise<{
     createdAt: Date;
     updatedAt: Date;
     id: number;
+    publicId: string;
     email: string | null;
     phone: string | null;
+    username: string | null;
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
@@ -302,17 +347,49 @@ declare function updateLastLoginService(userId: number): Promise<void>;
  * Update user data
  */
 declare function updateUserService(userId: number, updates: Partial<NewUser>): Promise<void>;
+/**
+ * Check if username is available
+ *
+ * @returns true if the username is available (not taken and not reserved)
+ */
+declare function checkUsernameAvailableService(username: string): Promise<boolean>;
+/**
+ * Update username with reserved word and duplicate check
+ *
+ * @param userId - User ID (string, number, or bigint)
+ * @param username - New username or null to clear
+ * @throws ReservedUsernameError if username is reserved
+ * @throws UsernameAlreadyTakenError if username is already in use by another user
+ */
+declare function updateUsernameService(userId: string | number | bigint, username: string | null): Promise<{
+    createdAt: Date;
+    updatedAt: Date;
+    id: number;
+    publicId: string;
+    email: string | null;
+    phone: string | null;
+    username: string | null;
+    passwordHash: string | null;
+    passwordChangeRequired: boolean;
+    roleId: number;
+    status: "active" | "inactive" | "suspended";
+    emailVerifiedAt: Date | null;
+    phoneVerifiedAt: Date | null;
+    lastLoginAt: Date | null;
+}>;
 
 /**
  * @spfn/auth - RBAC Initialization Service
  *
  * Initialize roles, permissions, and their mappings
+ * Uses hash-based change detection to skip unnecessary DB operations
  */
 
 /**
  * Initialize auth package with RBAC system
  *
- * Creates built-in roles, permissions, and custom configurations
+ * Creates built-in roles, permissions, and custom configurations.
+ * Uses hash-based change detection - skips DB operations when config is unchanged.
  *
  * @param options - Initialization options
  *
@@ -880,11 +957,11 @@ declare const userInvitations: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "user_invitations";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -897,11 +974,11 @@ declare const userInvitations: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "user_invitations";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -1032,6 +1109,7 @@ declare function createInvitation(params: {
     roleId: number;
     invitedBy: number;
     expiresInDays?: number;
+    expiresAt?: Date;
     metadata?: Record<string, any>;
 }): Promise<Invitation>;
 /**
@@ -1258,9 +1336,11 @@ declare function getAuthSessionService(userId: string | number | bigint): Promis
         category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
     }[];
     userId: number;
+    publicId: string;
     email: string | null;
     emailVerified: boolean;
     phoneVerified: boolean;
+    hasPassword: boolean;
 }>;
 
 /**
@@ -1305,6 +1385,16 @@ interface UpdateProfileParams {
  * ```
  */
 declare function getUserProfileService(userId: string | number | bigint): Promise<UserProfile$1>;
+/**
+ * Update user locale
+ *
+ * @param userId - User ID
+ * @param locale - Locale code (e.g., 'en', 'ko', 'ja')
+ * @returns Updated locale
+ */
+declare function updateLocaleService(userId: string | number | bigint, locale: string): Promise<{
+    locale: string;
+}>;
 /**
  * Update user profile (upsert)
  *
@@ -1326,369 +1416,6 @@ declare function getUserProfileService(userId: string | number | bigint): Promis
  */
 declare function updateUserProfileService(userId: string | number | bigint, params: UpdateProfileParams): Promise<ProfileInfo>;
 
-/**
- * @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
- *
- * Implement this interface to create custom email templates
- *
- * @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
- *
- * @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>
- *         `,
- *     }),
- * });
- * ```
- */
-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>;
-
 /**
  * @spfn/auth - Database Schema Definition
  *
@@ -1771,11 +1498,11 @@ declare const userProfiles: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "user_profiles";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -1791,7 +1518,7 @@ declare const userProfiles: drizzle_orm_pg_core.PgTableWithColumns<{
             columnType: "PgText";
             data: string;
             driverParam: string;
-            notNull: true;
+            notNull: false;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -2065,11 +1792,11 @@ declare const userPublicKeys: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "user_public_keys";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -2318,11 +2045,11 @@ declare const userSocialAccounts: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "user_social_accounts";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -2905,11 +2632,11 @@ declare const rolePermissions: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "role_permissions";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -2922,11 +2649,11 @@ declare const rolePermissions: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "role_permissions";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -3014,11 +2741,11 @@ declare const userPermissions: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "user_permissions";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -3031,11 +2758,11 @@ declare const userPermissions: drizzle_orm_pg_core.PgTableWithColumns<{
             name: `${string}_id`;
             tableName: "user_permissions";
             dataType: "number";
-            columnType: "PgBigSerial53";
+            columnType: "PgBigInt53";
             data: number;
-            driverParam: number;
+            driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -3101,6 +2828,73 @@ declare const userPermissions: drizzle_orm_pg_core.PgTableWithColumns<{
 type UserPermission = typeof userPermissions.$inferSelect;
 type NewUserPermission = typeof userPermissions.$inferInsert;
 
+/**
+ * @spfn/auth - Auth Metadata Entity
+ *
+ * Key-value store for auth system metadata
+ * Used for storing RBAC config hash and other system-level settings
+ */
+declare const authMetadata: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "auth_metadata";
+    schema: string;
+    columns: {
+        key: drizzle_orm_pg_core.PgColumn<{
+            name: "key";
+            tableName: "auth_metadata";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        value: drizzle_orm_pg_core.PgColumn<{
+            name: "value";
+            tableName: "auth_metadata";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "auth_metadata";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+type AuthMetadataEntity = typeof authMetadata.$inferSelect;
+type NewAuthMetadataEntity = typeof authMetadata.$inferInsert;
+
 /**
  * Users Repository
  *
@@ -3125,8 +2919,10 @@ declare class UsersRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         id: number;
+        publicId: string;
         email: string | null;
         phone: string | null;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3143,8 +2939,10 @@ declare class UsersRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         id: number;
+        publicId: string;
         email: string | null;
         phone: string | null;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3161,8 +2959,50 @@ declare class UsersRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         id: number;
+        publicId: string;
+        email: string | null;
+        phone: string | null;
+        username: string | null;
+        passwordHash: string | null;
+        passwordChangeRequired: boolean;
+        roleId: number;
+        status: "active" | "inactive" | "suspended";
+        emailVerifiedAt: Date | null;
+        phoneVerifiedAt: Date | null;
+        lastLoginAt: Date | null;
+    }>;
+    /**
+     * 사용자명으로 사용자 조회
+     * Read replica 사용
+     */
+    findByUsername(username: string): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        publicId: string;
         email: string | null;
         phone: string | null;
+        username: string | null;
+        passwordHash: string | null;
+        passwordChangeRequired: boolean;
+        roleId: number;
+        status: "active" | "inactive" | "suspended";
+        emailVerifiedAt: Date | null;
+        phoneVerifiedAt: Date | null;
+        lastLoginAt: Date | null;
+    }>;
+    /**
+     * Public ID(UUID)로 사용자 조회
+     * Read replica 사용
+     */
+    findByPublicId(publicId: string): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        publicId: string;
+        email: string | null;
+        phone: string | null;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3179,8 +3019,10 @@ declare class UsersRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         id: number;
+        publicId: string;
         email: string | null;
         phone: string | null;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3189,6 +3031,35 @@ declare class UsersRepository extends BaseRepository {
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
     } | null>;
+    /**
+     * ID로 사용자 + Role 조회 (leftJoin)
+     * Read replica 사용
+     *
+     * roleId가 null인 유저는 role: null 반환
+     */
+    findByIdWithRole(id: number): Promise<{
+        user: {
+            createdAt: Date;
+            updatedAt: Date;
+            id: number;
+            publicId: string;
+            email: string | null;
+            phone: string | null;
+            username: string | null;
+            passwordHash: string | null;
+            passwordChangeRequired: boolean;
+            roleId: number;
+            status: "active" | "inactive" | "suspended";
+            emailVerifiedAt: Date | null;
+            phoneVerifiedAt: Date | null;
+            lastLoginAt: Date | null;
+        };
+        role: {
+            name: string;
+            displayName: string;
+            priority: number;
+        } | null;
+    } | null>;
     /**
      * 사용자 생성
      * Write primary 사용
@@ -3197,6 +3068,8 @@ declare class UsersRepository extends BaseRepository {
         email: string | null;
         phone: string | null;
         id: number;
+        publicId: string;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3215,8 +3088,10 @@ declare class UsersRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         id: number;
+        publicId: string;
         email: string | null;
         phone: string | null;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3233,8 +3108,10 @@ declare class UsersRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         id: number;
+        publicId: string;
         email: string | null;
         phone: string | null;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3251,8 +3128,10 @@ declare class UsersRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         id: number;
+        publicId: string;
         email: string | null;
         phone: string | null;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3269,6 +3148,8 @@ declare class UsersRepository extends BaseRepository {
         email: string | null;
         phone: string | null;
         id: number;
+        publicId: string;
+        username: string | null;
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
@@ -3309,9 +3190,12 @@ declare class UsersRepository extends BaseRepository {
      */
     fetchMinimalUserData(userId: number): Promise<{
         userId: number;
+        publicId: string;
         email: string | null;
+        username: string | null;
         isEmailVerified: boolean;
         isPhoneVerified: boolean;
+        hasPassword: boolean;
     }>;
     /**
      * Full user data 조회 (user profile용)
@@ -3322,7 +3206,9 @@ declare class UsersRepository extends BaseRepository {
      */
     fetchFullUserData(userId: number): Promise<{
         userId: number;
+        publicId: string;
         email: string | null;
+        username: string | null;
         isEmailVerified: boolean;
         isPhoneVerified: boolean;
         lastLoginAt: Date | null;
@@ -3830,6 +3716,7 @@ declare class PermissionsRepository extends BaseRepository {
      */
     deleteById(id: number): Promise<{
         description: string | null;
+        metadata: Record<string, any> | null;
         id: number;
         name: string;
         displayName: string;
@@ -3839,7 +3726,6 @@ declare class PermissionsRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         category: "auth" | "custom" | "user" | "rbac" | "system" | null;
-        metadata: Record<string, any> | null;
     }>;
 }
 declare const permissionsRepository: PermissionsRepository;
@@ -4030,7 +3916,7 @@ declare class UserProfilesRepository extends BaseRepository {
         updatedAt: Date;
         id: number;
         userId: number;
-        displayName: string;
+        displayName: string | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4045,6 +3931,10 @@ declare class UserProfilesRepository extends BaseRepository {
         jobTitle: string | null;
         metadata: Record<string, any> | null;
     }>;
+    /**
+     * User ID로 locale만 조회 (경량)
+     */
+    findLocaleByUserId(userId: number): Promise<string>;
     /**
      * User ID로 프로필 조회
      */
@@ -4053,7 +3943,7 @@ declare class UserProfilesRepository extends BaseRepository {
         updatedAt: Date;
         id: number;
         userId: number;
-        displayName: string;
+        displayName: string | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4072,12 +3962,12 @@ declare class UserProfilesRepository extends BaseRepository {
      * 프로필 생성
      */
     create(data: NewUserProfile): Promise<{
+        metadata: Record<string, any> | null;
         userId: number;
         id: number;
-        displayName: string;
+        displayName: string | null;
         createdAt: Date;
         updatedAt: Date;
-        metadata: Record<string, any> | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4099,7 +3989,7 @@ declare class UserProfilesRepository extends BaseRepository {
         updatedAt: Date;
         id: number;
         userId: number;
-        displayName: string;
+        displayName: string | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4122,7 +4012,7 @@ declare class UserProfilesRepository extends BaseRepository {
         updatedAt: Date;
         id: number;
         userId: number;
-        displayName: string;
+        displayName: string | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4141,12 +4031,12 @@ declare class UserProfilesRepository extends BaseRepository {
      * 프로필 삭제 (by ID)
      */
     deleteById(id: number): Promise<{
+        metadata: Record<string, any> | null;
         userId: number;
         id: number;
-        displayName: string;
+        displayName: string | null;
         createdAt: Date;
         updatedAt: Date;
-        metadata: Record<string, any> | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4164,12 +4054,12 @@ declare class UserProfilesRepository extends BaseRepository {
      * 프로필 삭제 (by User ID)
      */
     deleteByUserId(userId: number): Promise<{
+        metadata: Record<string, any> | null;
         userId: number;
         id: number;
-        displayName: string;
+        displayName: string | null;
         createdAt: Date;
         updatedAt: Date;
-        metadata: Record<string, any> | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4190,12 +4080,12 @@ declare class UserProfilesRepository extends BaseRepository {
      * 새로 생성 시 displayName은 필수 (없으면 'User'로 설정)
      */
     upsertByUserId(userId: number, data: Partial<Omit<NewUserProfile, 'userId'>>): Promise<{
+        metadata: Record<string, any> | null;
         userId: number;
         id: number;
-        displayName: string;
+        displayName: string | null;
         createdAt: Date;
         updatedAt: Date;
-        metadata: Record<string, any> | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4216,7 +4106,7 @@ declare class UserProfilesRepository extends BaseRepository {
      */
     fetchProfileData(userId: number): Promise<{
         profileId: number;
-        displayName: string;
+        displayName: string | null;
         firstName: string | null;
         lastName: string | null;
         avatarUrl: string | null;
@@ -4335,12 +4225,12 @@ declare class InvitationsRepository extends BaseRepository {
      */
     create(data: NewInvitation): Promise<{
         email: string;
+        metadata: Record<string, any> | null;
         id: number;
         roleId: number;
         createdAt: Date;
         updatedAt: Date;
         status: "pending" | "accepted" | "expired" | "cancelled";
-        metadata: Record<string, any> | null;
         token: string;
         invitedBy: number;
         expiresAt: Date;
@@ -4369,12 +4259,12 @@ declare class InvitationsRepository extends BaseRepository {
      */
     deleteById(id: number): Promise<{
         email: string;
+        metadata: Record<string, any> | null;
         id: number;
         roleId: number;
         createdAt: Date;
         updatedAt: Date;
         status: "pending" | "accepted" | "expired" | "cancelled";
-        metadata: Record<string, any> | null;
         token: string;
         invitedBy: number;
         expiresAt: Date;
@@ -4502,6 +4392,155 @@ 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;
+
+/**
+ * Auth Metadata Repository
+ *
+ * Key-value 기반 시스템 메타데이터 저장소
+ * RBAC 설정 해시 등 시스템 설정값 관리
+ */
+
+declare class AuthMetadataRepository extends BaseRepository {
+    /**
+     * 키로 값 조회
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * 키-값 저장 (upsert)
+     */
+    set(key: string, value: string): Promise<void>;
+}
+declare const authMetadataRepository: AuthMetadataRepository;
+
 /**
  * @spfn/auth - Password Helpers
  *
@@ -4846,6 +4885,29 @@ interface RoleGuardOptions {
  */
 declare const roleGuard: _spfn_core_route.NamedMiddlewareFactory<"roleGuard", [options: RoleGuardOptions]>;
 
+/**
+ * One-Time Token Authentication Middleware
+ *
+ * Authenticates requests using a one-time token instead of JWT.
+ * Extracts token from query parameter `?token=xxx` or `Authorization: OTT xxx` header.
+ *
+ * On success, injects AuthContext identical to the `authenticate` middleware,
+ * making it transparent to downstream handlers using `getAuth(c)`.
+ *
+ * Auto-skips the global 'auth' middleware.
+ *
+ * @example
+ * ```typescript
+ * export const uploadFile = route.post('/files/upload')
+ *     .use([oneTimeTokenAuth])
+ *     .handler(async (c) => {
+ *         const { userId } = getAuth(c);
+ *         // handle file upload...
+ *     });
+ * ```
+ */
+declare const oneTimeTokenAuth: _spfn_core_route.NamedMiddleware<"oneTimeTokenAuth">;
+
 /**
  * Auth Context Helpers
  *
@@ -4872,6 +4934,32 @@ declare const roleGuard: _spfn_core_route.NamedMiddlewareFactory<"roleGuard", [o
 declare function getAuth(c: Context | {
     raw: Context;
 }): AuthContext;
+/**
+ * Get optional auth context from route context
+ *
+ * Returns AuthContext if authenticated, undefined otherwise.
+ * Use with `optionalAuth` middleware for routes that serve both
+ * authenticated and unauthenticated users.
+ *
+ * @example
+ * ```typescript
+ * export const getProducts = route.get('/products')
+ *   .use([optionalAuth])
+ *   .handler(async (c) => {
+ *     const auth = getOptionalAuth(c);
+ *
+ *     if (auth)
+ *     {
+ *       return getPersonalizedProducts(auth.userId);
+ *     }
+ *
+ *     return getPublicProducts();
+ *   });
+ * ```
+ */
+declare function getOptionalAuth(c: Context | {
+    raw: Context;
+}): AuthContext | undefined;
 /**
  * Get authenticated user from route context
  *
@@ -4889,6 +4977,8 @@ declare function getUser(c: Context | {
     email: string | null;
     phone: string | null;
     id: number;
+    publicId: string;
+    username: string | null;
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
@@ -4913,6 +5003,38 @@ declare function getUser(c: Context | {
 declare function getUserId(c: Context | {
     raw: Context;
 }): string;
+/**
+ * Get authenticated user's role from route context
+ *
+ * @returns Role name or null if user has no role
+ *
+ * @example
+ * ```typescript
+ * app.bind(adminContract, [authenticate], async (c) => {
+ *     const role = getRole(c);
+ *     // 'admin' | 'superadmin' | null
+ * });
+ * ```
+ */
+declare function getRole(c: Context | {
+    raw: Context;
+}): string | null;
+/**
+ * Get authenticated user's locale from route context
+ *
+ * @returns Locale string (e.g., 'en', 'ko')
+ *
+ * @example
+ * ```typescript
+ * app.bind(contract, [authenticate], async (c) => {
+ *     const locale = getLocale(c);
+ *     // 'en' | 'ko' | ...
+ * });
+ * ```
+ */
+declare function getLocale(c: Context | {
+    raw: Context;
+}): string;
 /**
  * Get current key ID from route context
  *
@@ -4985,56 +5107,6 @@ declare function shouldRotateKey(createdAt: Date, rotationDays?: number): {
     daysRemaining: number;
 };
 
-/**
- * @spfn/auth - Client Session Management
- *
- * Uses Jose JWE (JSON Web Encryption) to securely store session data in cookies
- * More efficient than Iron Session with better Edge Runtime support
- */
-
-interface SessionData {
-    userId: string;
-    privateKey: string;
-    keyId: string;
-    algorithm: KeyAlgorithmType;
-}
-/**
- * Seal session data into encrypted JWT (JWE)
- *
- * @param data - Session data to encrypt
- * @param ttl - Time to live in seconds (default: 7 days)
- * @returns Encrypted JWT string
- */
-declare function sealSession(data: SessionData, ttl?: number): Promise<string>;
-/**
- * Unseal encrypted JWT (JWE) to session data
- *
- * @param jwt - Encrypted JWT string
- * @returns Session data
- * @throws Error if session is invalid or expired
- */
-declare function unsealSession(jwt: string): Promise<SessionData>;
-/**
- * Get session metadata without decrypting
- *
- * @param jwt - Encrypted JWT string
- * @returns Session metadata or null if invalid
- */
-declare function getSessionInfo(jwt: string): Promise<{
-    issuedAt: Date;
-    expiresAt: Date;
-    issuer: string;
-    audience: string;
-} | null>;
-/**
- * Check if session is about to expire (within threshold)
- *
- * @param jwt - Encrypted JWT string
- * @param thresholdHours - Hours before expiry to trigger refresh (default: 24)
- * @returns True if session should be refreshed
- */
-declare function shouldRefreshSession(jwt: string, thresholdHours?: number): Promise<boolean>;
-
 /**
  * @spfn/auth - Global Configuration
  *
@@ -5042,12 +5114,17 @@ declare function shouldRefreshSession(jwt: string, thresholdHours?: number): Pro
  */
 /**
  * Cookie names used by SPFN Auth
+ *
+ * Names include a port-based suffix so that multiple dev instances
+ * on different ports don't overwrite each other's cookies.
  */
 declare const COOKIE_NAMES: {
     /** Encrypted session data (userId, privateKey, keyId, algorithm) */
-    readonly SESSION: "spfn_session";
+    readonly SESSION: string;
     /** Current key ID (for key rotation) */
-    readonly SESSION_KEY_ID: "spfn_session_key_id";
+    readonly SESSION_KEY_ID: string;
+    /** Pending OAuth session (privateKey, keyId, algorithm) - temporary during OAuth flow */
+    readonly OAUTH_PENDING: string;
 };
 /**
  * Parse duration string to seconds
@@ -5104,6 +5181,157 @@ 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;
+    metadata?: Record<string, unknown>;
+}
+interface CreateOAuthStateParams {
+    provider: string;
+    returnUrl: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm: KeyAlgorithmType;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 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>;
+
+/**
+ * One-Time Token Manager
+ *
+ * Singleton wrapper around SSETokenManager for one-time token authentication.
+ * Used for direct API access (file uploads, SSE streaming, etc.) bypassing RPC proxy.
+ */
+
+/**
+ * Initialize the one-time token manager
+ *
+ * Called during auth lifecycle initialization.
+ * Creates a singleton SSETokenManager instance.
+ *
+ * @param config - Optional configuration
+ * @param config.ttl - Token time-to-live in milliseconds (default: 30000)
+ * @param config.store - Custom token store (e.g., CacheTokenStore for Redis)
+ */
+declare function initOneTimeTokenManager(config?: {
+    ttl?: number;
+    store?: SSETokenStore;
+}): void;
+/**
+ * Get the one-time token manager instance
+ *
+ * @throws Error if initOneTimeTokenManager() has not been called
+ *
+ * @example
+ * ```typescript
+ * import { getOneTimeTokenManager } from '@spfn/auth/server';
+ *
+ * // Use as SSE tokenManager
+ * .eventsConfig({
+ *     auth: {
+ *         enabled: true,
+ *         tokenManager: getOneTimeTokenManager(),
+ *     },
+ * })
+ * ```
+ */
+declare function getOneTimeTokenManager(): SSETokenManager;
+
 /**
  * @spfn/auth - Centralized Logger
  *
@@ -5116,7 +5344,9 @@ declare const authLogger: {
         general: _spfn_core_logger.Logger;
         login: _spfn_core_logger.Logger;
         keyRotation: _spfn_core_logger.Logger;
+        oauth: _spfn_core_logger.Logger;
     };
+    session: _spfn_core_logger.Logger;
     service: _spfn_core_logger.Logger;
     setup: _spfn_core_logger.Logger;
     email: _spfn_core_logger.Logger;
@@ -5197,6 +5427,168 @@ interface AuthLifecycleConfig {
  *   .build();
  * ```
  */
-declare function createAuthLifecycle(options?: AuthInitOptions): AuthLifecycleConfig;
+/**
+ * Options for createAuthLifecycle
+ */
+interface AuthLifecycleOptions extends AuthInitOptions {
+    /**
+     * One-time token configuration
+     *
+     * Enables one-time token issuance for direct API access
+     * (file uploads, SSE streaming, etc.)
+     *
+     * @example
+     * ```typescript
+     * createAuthLifecycle({
+     *     oneTimeToken: { ttl: 60000 },  // 60 seconds
+     * })
+     * ```
+     */
+    oneTimeToken?: {
+        /**
+         * Token time-to-live in milliseconds
+         * @default 30000
+         */
+        ttl?: number;
+        /**
+         * Custom token store (e.g., CacheTokenStore for Redis/Valkey)
+         *
+         * When provided, tokens are stored in the external store instead of in-memory Map.
+         * Required for multi-instance deployments where token issuance and verification
+         * may happen on different server instances.
+         *
+         * @example
+         * ```typescript
+         * import { CacheTokenStore } from '@spfn/core/event/sse';
+         * import { getCache } from '@spfn/core/cache';
+         *
+         * createAuthLifecycle({
+         *     oneTimeToken: {
+         *         store: new CacheTokenStore(getCache()),
+         *     },
+         * })
+         * ```
+         */
+        store?: SSETokenStore;
+    };
+}
+declare function createAuthLifecycle(options?: AuthLifecycleOptions): AuthLifecycleConfig;
+
+/**
+ * @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;
+    metadata?: {
+        [x: string]: unknown;
+    } | undefined;
+    userId: string;
+    provider: "email" | "phone" | "google";
+}>;
+/**
+ * auth.invitation.created - 초대 생성 이벤트
+ *
+ * 발행 시점:
+ * - createInvitation() 성공 시
+ * - resendInvitation() 성공 시
+ *
+ * @example
+ * ```typescript
+ * invitationCreatedEvent.subscribe(async (payload) => {
+ *     const inviteUrl = `${APP_URL}/invite/${payload.token}`;
+ *     await notificationService.send({
+ *         channel: 'email',
+ *         to: payload.email,
+ *         subject: 'You are invited!',
+ *         html: renderInviteEmail({ inviteUrl, ...payload.metadata }),
+ *     });
+ * });
+ * ```
+ */
+declare const invitationCreatedEvent: _spfn_core_event.EventDef<{
+    metadata?: {
+        [x: string]: unknown;
+    } | undefined;
+    email: string;
+    roleId: number;
+    token: string;
+    invitedBy: string;
+    expiresAt: string;
+    invitationId: string;
+    isResend: boolean;
+}>;
+/**
+ * auth.invitation.accepted - 초대 수락 이벤트
+ *
+ * 발행 시점:
+ * - acceptInvitation() 성공 시
+ *
+ * @example
+ * ```typescript
+ * invitationAcceptedEvent.subscribe(async (payload) => {
+ *     await onboardingService.start(payload.userId);
+ * });
+ * ```
+ */
+declare const invitationAcceptedEvent: _spfn_core_event.EventDef<{
+    metadata?: {
+        [x: string]: unknown;
+    } | undefined;
+    email: string;
+    userId: string;
+    roleId: number;
+    invitedBy: string;
+    invitationId: string;
+}>;
+/**
+ * Auth event payload types
+ */
+type AuthLoginPayload = typeof authLoginEvent._payload;
+type AuthRegisterPayload = typeof authRegisterEvent._payload;
+type InvitationCreatedPayload = typeof invitationCreatedEvent._payload;
+type InvitationAcceptedPayload = typeof invitationAcceptedEvent._payload;
 
-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 RoleGuardOptions, type RolePermission, RolePermissionsRepository, RolesRepository, type SMSProvider, type SendEmailParams, type SendEmailResult, type SendSMSParams, type SendSMSResult, type SessionData, type SessionPayload, type TokenPayload, type UpdateProfileParams, 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, getUserRole, getVerificationCodeTemplate, getWelcomeTemplate, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initializeAuth, invitationsRepository, keysRepository, listInvitations, parseDuration, permissions, permissionsRepository, registerEmailProvider, registerEmailTemplates, registerSMSProvider, removePermissionFromRole, requireAnyPermission, requirePermissions, requireRole, resendInvitation, roleGuard, rolePermissions, rolePermissionsRepository, roles, rolesRepository, sealSession, sendEmail, sendSMS, setRolePermissions, shouldRefreshSession, shouldRotateKey, unsealSession, updateLastLoginService, updateRole, updateUserProfileService, updateUserService, userInvitations, userPermissions, userPermissionsRepository, userProfiles, userProfilesRepository, userPublicKeys, userSocialAccounts, users, usersRepository, validateInvitation, validatePasswordStrength, verificationCodes, verificationCodesRepository, verifyClientToken, verifyKeyFingerprint, verifyPassword, verifyToken };
+export { type AuthConfig, AuthContext, type AuthLifecycleConfig, type AuthLifecycleOptions, type AuthLoginPayload, type AuthMetadataEntity, AuthMetadataRepository, AuthProviderSchema, type AuthRegisterPayload, COOKIE_NAMES, type CreateOAuthStateParams, type GoogleTokenResponse, type GoogleUserInfo, type Invitation, type InvitationAcceptedPayload, type InvitationCreatedPayload, InvitationStatus, InvitationsRepository, KeyAlgorithmType, type KeyPair, KeysRepository, type NewAuthMetadataEntity, 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 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, authMetadata, authMetadataRepository, authRegisterEvent, authSchema, cancelInvitation, checkUsernameAvailableService, 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, getLocale, getOneTimeTokenManager, getOptionalAuth, getRole, getRoleByName, getRolePermissions, getSessionTtl, getUser, getUserByEmailService, getUserByIdService, getUserByPhoneService, getUserId, getUserPermissions, getUserProfileService, getUserRole, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initOneTimeTokenManager, initializeAuth, invitationAcceptedEvent, invitationCreatedEvent, invitationsRepository, isGoogleOAuthEnabled, keysRepository, listInvitations, oneTimeTokenAuth, parseDuration, permissions, permissionsRepository, refreshAccessToken, removePermissionFromRole, requireAnyPermission, requirePermissions, requireRole, resendInvitation, roleGuard, rolePermissions, rolePermissionsRepository, roles, rolesRepository, setRolePermissions, shouldRotateKey, socialAccountsRepository, updateLastLoginService, updateLocaleService, updateRole, updateUserProfileService, updateUserService, updateUsernameService, userInvitations, userPermissions, userPermissionsRepository, userProfiles, userProfilesRepository, userPublicKeys, userSocialAccounts, users, usersRepository, validateInvitation, validatePasswordStrength, verificationCodes, verificationCodesRepository, verifyClientToken, verifyKeyFingerprint, verifyOAuthState, verifyPassword, verifyToken };