@spfn/auth 0.2.0-beta.8 → 0.2.0-beta.81

package/dist/authenticate-ofdEmk6x.d.ts

@@ -0,0 +1,1109 @@
+import * as _spfn_core_route from '@spfn/core/route';
+import { K as KeyAlgorithmType, e as SocialProvider } from './types-1BMx0OX1.js';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static } from '@sinclair/typebox';
+import { User } from '@spfn/auth/server';
+
+/**
+ * Role information for client/API responses
+ */
+interface Role {
+    id: number;
+    name: string;
+    displayName: string;
+    description: string | null;
+    isBuiltin: boolean;
+    isSystem: boolean;
+    isActive: boolean;
+    priority: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Permission information for client/API responses
+ */
+interface Permission {
+    id: number;
+    name: string;
+    displayName: string;
+    description: string | null;
+    category: string | null;
+    isBuiltin: boolean;
+    isSystem: boolean;
+    isActive: boolean;
+    metadata: Record<string, any> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface AuthSession {
+    userId: number;
+    publicId: string;
+    email: string | null;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+    hasPassword: boolean;
+    role: Role;
+    permissions: Permission[];
+}
+interface ProfileInfo {
+    profileId: number;
+    displayName: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    avatarUrl: string | null;
+    bio: string | null;
+    locale: string;
+    timezone: string;
+    website: string | null;
+    location: string | null;
+    company: string | null;
+    jobTitle: string | null;
+    metadata: Record<string, any> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * User Profile Response
+ *
+ * Complete user data including:
+ * - User fields at top level (userId, email, etc.)
+ * - Profile data as nested field (optional)
+ *
+ * Excludes:
+ * - Role and permissions (use auth session API)
+ */
+interface UserProfile {
+    userId: number;
+    publicId: string;
+    email: string | null;
+    username: string | null;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+    lastLoginAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+    profile: ProfileInfo | null;
+}
+
+/**
+ * @spfn/auth - Auth Service
+ *
+ * Core authentication logic: registration, login, logout, password management
+ */
+
+interface RegisterParams {
+    email?: string;
+    phone?: string;
+    verificationToken: string;
+    password: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+    metadata?: Record<string, unknown>;
+}
+interface RegisterResult {
+    userId: string;
+    publicId: string;
+    email?: string;
+    phone?: string;
+}
+interface LoginParams {
+    email?: string;
+    phone?: string;
+    password: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    oldKeyId?: string;
+    algorithm?: KeyAlgorithmType;
+}
+interface LoginResult {
+    userId: string;
+    publicId: string;
+    email?: string;
+    phone?: string;
+    passwordChangeRequired: boolean;
+}
+interface LogoutParams {
+    userId: number;
+    keyId: string;
+}
+interface ChangePasswordParams {
+    userId: number;
+    currentPassword?: string;
+    newPassword: string;
+    passwordHash?: string;
+}
+/**
+ * Register a new user account
+ */
+declare function registerService(params: RegisterParams): Promise<RegisterResult>;
+/**
+ * Authenticate user and create session
+ */
+declare function loginService(params: LoginParams): Promise<LoginResult>;
+/**
+ * Logout user (revoke current key)
+ */
+declare function logoutService(params: LogoutParams): Promise<void>;
+/**
+ * Change user password
+ */
+declare function changePasswordService(params: ChangePasswordParams): Promise<void>;
+
+declare const EmailSchema: _sinclair_typebox.TString;
+declare const PhoneSchema: _sinclair_typebox.TString;
+declare const PasswordSchema: _sinclair_typebox.TString;
+declare const TargetTypeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">]>;
+type VerificationTargetType = Static<typeof TargetTypeSchema>;
+declare const VERIFICATION_TARGET_TYPES: readonly ["email", "phone"];
+declare const VerificationPurposeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">, _sinclair_typebox.TLiteral<"account_deletion">]>;
+type VerificationPurpose = Static<typeof VerificationPurposeSchema>;
+declare const VERIFICATION_PURPOSES: readonly ["registration", "login", "password_reset", "email_change", "phone_change", "account_deletion"];
+
+/**
+ * @spfn/auth - Verification Service
+ *
+ * Handles OTP code generation, validation, and delivery
+ */
+
+interface SendVerificationCodeParams {
+    target: string;
+    targetType: VerificationTargetType;
+    purpose: VerificationPurpose;
+}
+interface SendVerificationCodeResult {
+    success: boolean;
+    expiresAt: string;
+}
+interface VerifyCodeParams {
+    target: string;
+    targetType: VerificationTargetType;
+    code: string;
+    purpose: VerificationPurpose;
+}
+interface VerifyCodeResult {
+    valid: boolean;
+    verificationToken: string;
+}
+/**
+ * Send verification code via email or SMS
+ */
+declare function sendVerificationCodeService(params: SendVerificationCodeParams): Promise<SendVerificationCodeResult>;
+/**
+ * Verify OTP code and return verification token
+ */
+declare function verifyCodeService(params: VerifyCodeParams): Promise<{
+    valid: boolean;
+    verificationToken: string;
+}>;
+
+/**
+ * @spfn/auth - Key Service
+ *
+ * Handles public key registration, rotation, and revocation
+ */
+
+interface RegisterPublicKeyParams {
+    userId: number;
+    keyId: string;
+    publicKey: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+}
+interface RotateKeyParams {
+    userId: number;
+    oldKeyId: string;
+    newKeyId: string;
+    newPublicKey: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+}
+interface RotateKeyResult {
+    success: boolean;
+    keyId: string;
+}
+interface RevokeKeyParams {
+    userId: number;
+    keyId: string;
+    reason: string;
+}
+/**
+ * Register a new public key for a user
+ */
+declare function registerPublicKeyService(params: RegisterPublicKeyParams): Promise<void>;
+/**
+ * Rotate user's public key (revoke old, register new)
+ */
+declare function rotateKeyService(params: RotateKeyParams): Promise<RotateKeyResult>;
+/**
+ * Revoke a user's public key
+ */
+declare function revokeKeyService(params: RevokeKeyParams): Promise<void>;
+
+/**
+ * @spfn/auth - RBAC Type Definitions
+ *
+ * Type definitions for role and permission configuration
+ */
+/**
+ * Permission category enum values
+ * Single source of truth for permission categories
+ */
+declare const PERMISSION_CATEGORIES: readonly ["auth", "user", "rbac", "system", "custom"];
+/**
+ * Permission category type derived from the const array
+ */
+type PermissionCategory = typeof PERMISSION_CATEGORIES[number];
+interface RoleConfig {
+    name: string;
+    displayName: string;
+    description?: string;
+    priority?: number;
+    isSystem?: boolean;
+    isBuiltin?: boolean;
+}
+interface PermissionConfig {
+    name: string;
+    displayName: string;
+    description?: string;
+    category?: PermissionCategory;
+    isSystem?: boolean;
+    isBuiltin?: boolean;
+}
+interface AuthInitOptions {
+    /**
+     * Additional roles to create
+     * Built-in roles (user, admin, superadmin) are automatically included
+     */
+    roles?: RoleConfig[];
+    /**
+     * Additional permissions to create
+     * Built-in permissions are automatically included
+     */
+    permissions?: PermissionConfig[];
+    /**
+     * Role-Permission mappings
+     * Built-in mappings are automatically included
+     * You can extend built-in roles or define mappings for custom roles
+     *
+     * @example
+     * ```typescript
+     * {
+     *   // Extend built-in admin role
+     *   admin: ['project:create', 'project:delete'],
+     *
+     *   // Define custom role permissions
+     *   'project-manager': ['project:create', 'task:assign'],
+     * }
+     * ```
+     */
+    rolePermissions?: Record<string, string[]>;
+    /**
+     * Default role name for new users
+     * Must be a valid role name that exists after initialization
+     * @default 'user'
+     */
+    defaultRole?: string;
+    /**
+     * Default session TTL (Time To Live)
+     *
+     * Supports:
+     * - Number: seconds (e.g., 2592000)
+     * - String: duration format ('30d', '12h', '45m', '3600s')
+     *
+     * Can be overridden at runtime with `remember` parameter.
+     *
+     * @default '7d' (7 days)
+     *
+     * @example
+     * ```typescript
+     * {
+     *   sessionTtl: '30d',  // 30 days
+     * }
+     * ```
+     */
+    sessionTtl?: string | number;
+}
+
+/**
+ * One-Time Token Service
+ *
+ * Issues and verifies one-time tokens for direct API access.
+ */
+interface IssueOneTimeTokenResult {
+    token: string;
+    expiresAt: string;
+}
+/**
+ * Issue a one-time token for the authenticated user
+ *
+ * @param userId - Authenticated user's ID
+ * @returns Token string and ISO expiration timestamp
+ */
+declare function issueOneTimeTokenService(userId: string): Promise<IssueOneTimeTokenResult>;
+/**
+ * Verify and consume a one-time token
+ *
+ * @param token - The one-time token to verify
+ * @returns userId if valid, null if invalid/expired/consumed
+ */
+declare function verifyOneTimeTokenService(token: string): Promise<string | null>;
+
+/**
+ * OAuth Provider 추상화
+ *
+ * Provider별로 하드코딩된 분기를 제거하기 위한 공통 인터페이스와 registry.
+ * - 내장 provider(google)는 패키지 로드 시점에 자기 등록(dogfood)
+ * - 외부 패키지(@superself/auth 등)는 registerOAuthProvider()로 런타임 등록
+ *
+ * @spfn/auth는 토큰 issuer가 아니라 소비(client) 측이므로, 이 추상화는
+ * web 흐름("authorize URL 생성 → code 교환 → 사용자 정보 정규화")과
+ * native 흐름(네이티브/웹 SDK가 받은 id_token 직접 검증)을 다룬다.
+ */
+
+/**
+ * Provider 사용자 정보를 공통 형태로 정규화한 신원
+ *
+ * provider별 응답 형태(snake_case 등)를 service에 노출하지 않기 위한 경계.
+ */
+interface NormalizedIdentity {
+    providerUserId: string;
+    email: string | null;
+    emailVerified: boolean;
+    name?: string;
+    avatar?: string;
+}
+/**
+ * 정규화된 OAuth 토큰 응답
+ *
+ * @property expiresIn - access token 만료까지 남은 초(seconds)
+ */
+interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn: number;
+}
+/**
+ * 네이티브 id_token 검증 옵션
+ */
+interface NativeVerifyOptions {
+    /** 클라이언트가 생성한 raw nonce. provider별 규약(raw 또는 SHA-256 해시)으로 대조된다. */
+    nonce: string;
+}
+interface OAuthCodeExchangeOptions {
+    /** Provider가 callback에 돌려준 원본 state. 일부 provider는 token 교환에도 요구한다. */
+    state: string;
+}
+/**
+ * OAuth provider 구현 인터페이스
+ *
+ * google, superself 등 모든 provider가 이 형태를 만족해야 registry에 등록된다.
+ */
+interface OAuthProvider {
+    id: SocialProvider;
+    /**
+     * provider가 사용 가능한 상태인지(필수 env 등) 확인
+     */
+    isEnabled(): boolean;
+    /**
+     * provider 로그인 페이지로 보낼 authorization URL 생성
+     *
+     * @param state - CSRF 방지용 암호화 state
+     * @param scopes - 요청할 scope (미지정 시 provider 기본값)
+     */
+    getAuthUrl(state: string, scopes?: string[]): string;
+    /**
+     * authorization code를 토큰으로 교환
+     */
+    exchangeCodeForTokens(code: string, options: OAuthCodeExchangeOptions): Promise<OAuthTokens>;
+    /**
+     * access token으로 사용자 정보를 조회하고 공통 형태로 정규화
+     */
+    getUserInfo(accessToken: string): Promise<NormalizedIdentity>;
+    /**
+     * refresh token으로 access token 갱신 (provider가 지원하는 경우)
+     *
+     * 저장된 provider 토큰을 이후 API 호출에 재사용할 때 사용한다.
+     * 미구현 provider는 갱신 불가로 간주한다.
+     */
+    refreshTokens?(refreshToken: string): Promise<OAuthTokens>;
+    /**
+     * 네이티브/웹 SDK가 받은 id_token을 직접 검증하고 신원을 정규화한다.
+     *
+     * authorization code 교환 없이 provider JWKS로 서명을 검증하므로 client secret이
+     * 필요 없다. native sign-in을 지원하는 provider만 구현한다(Apple은 web SDK 부재로
+     * Android·웹도 이 경로를 쓴다).
+     */
+    verifyNativeIdToken?(idToken: string, options: NativeVerifyOptions): Promise<NormalizedIdentity>;
+}
+/**
+ * OAuth provider 등록 (public)
+ *
+ * 동일 id로 다시 등록하면 덮어쓴다(외부 패키지의 override 허용).
+ */
+declare function registerOAuthProvider(provider: OAuthProvider): void;
+/**
+ * 등록된 provider 조회. 미등록이면 undefined.
+ */
+declare function getOAuthProvider(id: SocialProvider): OAuthProvider | undefined;
+/**
+ * 등록된 모든 provider 목록
+ */
+declare function getRegisteredProviders(): OAuthProvider[];
+
+/**
+ * @spfn/auth - OAuth Service
+ *
+ * OAuth 인증 비즈니스 로직
+ * - Google OAuth Authorization Code Flow
+ * - 소셜 계정 연결/생성
+ * - publicKey는 state에서 추출하여 등록
+ */
+
+interface OAuthStartParams {
+    provider: SocialProvider;
+    returnUrl: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm: KeyAlgorithmType;
+    metadata?: Record<string, unknown>;
+    /** CSRF nonce bound into the state; the route sets the matching oauth_csrf cookie. */
+    nonce?: string;
+}
+interface OAuthStartResult {
+    authUrl: string;
+}
+interface OAuthCallbackParams {
+    provider: SocialProvider;
+    code: string;
+    state: string;
+    /**
+     * Value(s) of the oauth_csrf cookie from the callback request. One of them
+     * must equal the nonce bound into the (encrypted) state — otherwise the flow
+     * wasn't initiated by this browser (login CSRF). An array arises because the
+     * cookie name carries the PORT suffix of the process that set it (the Next.js
+     * web process), which differs from the API process in a split deployment, so
+     * the callback collects every spfn_oauth_csrf* candidate. Pass `undefined` or
+     * an empty array when absent; verification then fails closed.
+     */
+    expectedNonce: string | string[] | undefined;
+}
+interface OAuthCallbackResult {
+    redirectUrl: string;
+    userId: string;
+    keyId: string;
+    isNewUser: boolean;
+}
+/**
+ * registry에서 provider를 찾아 사용 가능한지 검증 후 반환
+ *
+ * 미등록과 비활성을 구분해 디버깅 신호를 남긴다.
+ * 라우트 레이어에서도 재사용한다(중복 조회/non-null 단언 제거).
+ */
+declare function requireEnabledProvider(provider: SocialProvider): OAuthProvider;
+/**
+ * OAuth 로그인 시작 - Provider 로그인 페이지로 리다이렉트할 URL 생성
+ *
+ * Next.js에서 키쌍을 생성한 후, publicKey를 state에 포함하여 호출
+ */
+declare function oauthStartService(params: OAuthStartParams): Promise<OAuthStartResult>;
+/**
+ * OAuth 콜백 처리 - Code를 Token으로 교환하고 사용자 생성/연결
+ *
+ * state에서 publicKey를 추출하여 서버에 등록
+ * Next.js는 반환된 userId, keyId로 세션을 구성
+ */
+declare function oauthCallbackService(params: OAuthCallbackParams): Promise<OAuthCallbackResult>;
+/**
+ * OAuth 에러 리다이렉트 URL 생성
+ */
+declare function buildOAuthErrorUrl(error: string): string;
+/**
+ * OAuth provider가 등록되어 있고 활성화되어 있는지 확인
+ */
+declare function isOAuthProviderEnabled(provider: SocialProvider): boolean;
+/**
+ * 활성화된 모든 OAuth provider 목록 (registry 기반)
+ */
+declare function getEnabledOAuthProviders(): SocialProvider[];
+/**
+ * Google access token 조회 (만료 시 자동 리프레시)
+ *
+ * 저장된 토큰이 만료 임박(5분 이내) 또는 만료 상태이면
+ * refresh token으로 자동 갱신 후 DB 업데이트하여 유효한 토큰 반환.
+ *
+ * @param userId - 사용자 ID
+ * @returns 유효한 Google access token
+ */
+declare function getGoogleAccessToken(userId: number): Promise<string>;
+
+/**
+ * @spfn/auth - Native Social Login Service
+ *
+ * 네이티브/웹 SDK가 받은 id_token을 JWKS로 검증하고, 검증된 신원에 클라이언트가 만든
+ * 공개키를 등록한다. 토큰은 발급하지 않는다 — 클라이언트가 등록한 키로 client token을
+ * 직접 서명해 Bearer로 사용한다(client-signs / server-verifies 모델).
+ *
+ * 흐름은 두 단계로 분리한다:
+ *   1) id_token 검증 — 외부 JWKS 네트워크 조회. DB 트랜잭션 밖에서 수행한다.
+ *   2) persist — 사용자 link/create + 공개키 등록을 한 트랜잭션으로. 이벤트는 커밋 후 발행.
+ */
+
+interface OAuthNativeParams {
+    provider: SocialProvider;
+    idToken: string;
+    nonce: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm: KeyAlgorithmType;
+    /** Apple은 첫 로그인에만 이름을 별도로 주므로 클라이언트가 전달할 수 있다. */
+    profile?: {
+        name?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+interface OAuthNativeResult {
+    userId: string;
+    keyId: string;
+    isNewUser: boolean;
+}
+/**
+ * native id_token 로그인 처리
+ *
+ * @throws ValidationError provider가 native sign-in을 지원하지 않을 때
+ * @throws InvalidSocialTokenError id_token 검증 실패 시
+ */
+declare function oauthNativeService(params: OAuthNativeParams): Promise<OAuthNativeResult>;
+
+/**
+ * @spfn/auth - Main Router
+ *
+ * Combines all auth-related routes into a single router
+ */
+/**
+ * Main auth router
+ * Exports all authentication-related routes
+ *
+ * Routes:
+ * - Auth: /_auth/codes, /_auth/login, /_auth/logout, etc.
+ * - OAuth: /_auth/oauth/google, /_auth/oauth/google/callback, etc.
+ * - Invitations: /_auth/invitations/*
+ * - Users: /_auth/users/*
+ * - Deletion: /_auth/deletion/request, /_auth/deletion/cancel
+ * - Admin: /_auth/admin/* (superadmin only)
+ */
+declare const mainAuthRouter: _spfn_core_route.Router<{
+    sendVerificationCode: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            target: _sinclair_typebox.TString;
+            targetType: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">]>;
+            purpose: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">, _sinclair_typebox.TLiteral<"account_deletion">]>;
+        }>;
+    }, {}, SendVerificationCodeResult>;
+    verifyCode: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            target: _sinclair_typebox.TString;
+            targetType: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">]>;
+            code: _sinclair_typebox.TString;
+            purpose: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">, _sinclair_typebox.TLiteral<"account_deletion">]>;
+        }>;
+    }, {}, {
+        valid: boolean;
+        verificationToken: string;
+    }>;
+    register: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            email: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            phone: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            verificationToken: _sinclair_typebox.TString;
+            password: _sinclair_typebox.TString;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
+        }>;
+    }, {
+        body: _sinclair_typebox.TObject<{
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+        }>;
+    }, RegisterResult>;
+    login: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            email: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            phone: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            password: _sinclair_typebox.TString;
+        }>;
+    }, {
+        body: _sinclair_typebox.TObject<{
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+            oldKeyId: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, LoginResult>;
+    logout: _spfn_core_route.RouteDef<{}, {}, void>;
+    rotateKey: _spfn_core_route.RouteDef<{}, {
+        body: _sinclair_typebox.TObject<{
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+        }>;
+    }, RotateKeyResult>;
+    changePassword: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            currentPassword: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            newPassword: _sinclair_typebox.TString;
+        }>;
+    }, {}, void>;
+    getAuthSession: _spfn_core_route.RouteDef<{}, {}, {
+        role: {
+            id: number;
+            name: string;
+            displayName: string;
+            priority: number;
+        };
+        permissions: {
+            id: number;
+            name: string;
+            displayName: string;
+            category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
+        }[];
+        userId: number;
+        publicId: string;
+        email: string | null;
+        emailVerified: boolean;
+        phoneVerified: boolean;
+        hasPassword: boolean;
+    }>;
+    issueOneTimeToken: _spfn_core_route.RouteDef<{}, {}, IssueOneTimeTokenResult>;
+    requestAccountDeletion: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            password: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            verificationToken: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            reason: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            immediate: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        }>;
+    }, {}, {
+        purgeScheduledAt: string;
+    }>;
+    cancelAccountDeletion: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            email: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            phone: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            password: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            verificationToken: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, void>;
+    oauthGoogleStart: _spfn_core_route.RouteDef<{
+        query: _sinclair_typebox.TObject<{
+            state: _sinclair_typebox.TString;
+        }>;
+    }, {}, Response>;
+    oauthGoogleCallback: _spfn_core_route.RouteDef<{
+        query: _sinclair_typebox.TObject<{
+            code: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error_description: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, Response>;
+    oauthStart: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
+            returnUrl: _sinclair_typebox.TString;
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
+        }>;
+    }, {}, OAuthStartResult>;
+    oauthProviders: _spfn_core_route.RouteDef<{}, {}, {
+        providers: ("google" | "apple" | "github" | "kakao" | "naver" | "superself")[];
+    }>;
+    getGoogleOAuthUrl: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        authUrl: string;
+    }>;
+    oauthFinalize: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            userId: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        success: boolean;
+        userId: string;
+        keyId: string;
+        returnUrl: string;
+    }>;
+    oauthProviderStart: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        query: _sinclair_typebox.TObject<{
+            state: _sinclair_typebox.TString;
+        }>;
+    }, {}, Response>;
+    oauthProviderCallback: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        query: _sinclair_typebox.TObject<{
+            code: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            error_description: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, Response>;
+    getProviderOAuthUrl: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        body: _sinclair_typebox.TObject<{
+            returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        authUrl: string;
+    }>;
+    oauthNative: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+        body: _sinclair_typebox.TObject<{
+            idToken: _sinclair_typebox.TString;
+            nonce: _sinclair_typebox.TString;
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+            profile: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+                name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            }>>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
+        }>;
+    }, {}, OAuthNativeResult>;
+    getInvitation: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        email: string;
+        role: string;
+        roleDisplayName: string;
+        invitedBy: string;
+        expiresAt: string;
+        metadata: Record<string, any> | undefined;
+    }>;
+    acceptInvitation: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+            password: _sinclair_typebox.TString;
+        }>;
+    }, {
+        body: _sinclair_typebox.TObject<{
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+        }>;
+    }, {
+        userId: number;
+        email: string;
+        role: string;
+    }>;
+    createInvitation: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            email: _sinclair_typebox.TString;
+            roleId: _sinclair_typebox.TNumber;
+            expiresInDays: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            expiresAt: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TAny>;
+        }>;
+    }, {}, {
+        id: number;
+        email: string;
+        token: string;
+        roleId: number;
+        expiresAt: string;
+        invitationUrl: string;
+    }>;
+    listInvitations: _spfn_core_route.RouteDef<{
+        query: _sinclair_typebox.TObject<{
+            status: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"pending" | "accepted" | "expired" | "cancelled">[]>>;
+            page: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            limit: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        }>;
+    }, {}, {
+        invitations: {
+            id: number;
+            email: string;
+            token: string;
+            roleId: number;
+            invitedBy: number;
+            status: "pending" | "accepted" | "expired" | "cancelled";
+            expiresAt: Date;
+            acceptedAt: Date | null;
+            cancelledAt: Date | null;
+            metadata: Record<string, any> | null;
+            createdAt: Date;
+            updatedAt: Date;
+            role: {
+                id: number;
+                name: string;
+                displayName: string;
+            };
+            inviter: {
+                id: number;
+                email: string | null;
+            };
+        }[];
+        total: number;
+        page: number;
+        limit: number;
+        totalPages: number;
+    }>;
+    cancelInvitation: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TNumber;
+            reason: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        cancelledAt: string;
+    }>;
+    resendInvitation: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TNumber;
+            expiresInDays: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        }>;
+    }, {}, {
+        expiresAt: string;
+    }>;
+    deleteInvitation: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TNumber;
+        }>;
+    }, {}, void>;
+    getUserProfile: _spfn_core_route.RouteDef<{}, {}, UserProfile>;
+    updateUserProfile: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            displayName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            firstName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            lastName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            avatarUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            bio: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            locale: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            timezone: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            dateOfBirth: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            gender: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            website: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            location: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            company: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            jobTitle: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TAny>>;
+        }>;
+    }, {}, ProfileInfo>;
+    checkUsername: _spfn_core_route.RouteDef<{
+        query: _sinclair_typebox.TObject<{
+            username: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        available: boolean;
+    }>;
+    updateUsername: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            username: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNull]>;
+        }>;
+    }, {}, {
+        deletedAt: Date | null;
+        deletedBy: string | null;
+        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" | "pending_deletion" | "deleted";
+        emailVerifiedAt: Date | null;
+        phoneVerifiedAt: Date | null;
+        lastLoginAt: Date | null;
+    }>;
+    updateLocale: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            locale: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        locale: string;
+    }>;
+    listRoles: _spfn_core_route.RouteDef<{
+        query: _sinclair_typebox.TObject<{
+            includeInactive: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        }>;
+    }, {}, {
+        roles: {
+            description: string | null;
+            id: number;
+            name: string;
+            displayName: string;
+            isBuiltin: boolean;
+            isSystem: boolean;
+            isActive: boolean;
+            priority: number;
+            createdAt: Date;
+            updatedAt: Date;
+        }[];
+    }>;
+    createAdminRole: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            name: _sinclair_typebox.TString;
+            displayName: _sinclair_typebox.TString;
+            description: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            priority: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            permissionIds: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TNumber>>;
+        }>;
+    }, {}, {
+        role: {
+            description: string | null;
+            id: number;
+            name: string;
+            displayName: string;
+            isBuiltin: boolean;
+            isSystem: boolean;
+            isActive: boolean;
+            priority: number;
+            createdAt: Date;
+            updatedAt: Date;
+        };
+    }>;
+    updateAdminRole: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TNumber;
+        }>;
+        body: _sinclair_typebox.TObject<{
+            displayName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            description: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            priority: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            isActive: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        }>;
+    }, {}, {
+        role: {
+            description: string | null;
+            id: number;
+            name: string;
+            displayName: string;
+            isBuiltin: boolean;
+            isSystem: boolean;
+            isActive: boolean;
+            priority: number;
+            createdAt: Date;
+            updatedAt: Date;
+        };
+    }>;
+    deleteAdminRole: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TNumber;
+        }>;
+    }, {}, void>;
+    updateUserRole: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            userId: _sinclair_typebox.TNumber;
+        }>;
+        body: _sinclair_typebox.TObject<{
+            roleId: _sinclair_typebox.TNumber;
+        }>;
+    }, {}, {
+        userId: number;
+        roleId: number;
+    }>;
+}>;
+
+interface AuthContext {
+    user: User;
+    userId: string;
+    keyId: string;
+    role: string | null;
+    locale: string;
+}
+declare module 'hono' {
+    interface ContextVariableMap {
+        auth: AuthContext;
+    }
+}
+/**
+ * Authentication middleware
+ *
+ * Verifies client-signed JWT token using stored public key
+ * Must be applied to routes that require authentication
+ *
+ * @example
+ * ```typescript
+ * // In server.config.ts
+ * import { authenticate } from '@spfn/auth/server/middleware';
+ *
+ * export default defineServerConfig()
+ *   .middlewares([authenticate])
+ *   .routes(appRouter)
+ *   .build();
+ *
+ * // In route file - skip auth for public routes
+ * export const publicRoute = route.get('/health')
+ *   .skip(['auth'])  // Type-safe skip
+ *   .handler(async (c) => c.success({ status: 'ok' }));
+ *
+ * // Protected route - auth applied automatically
+ * export const protectedRoute = route.get('/profile')
+ *   .handler(async (c) => {
+ *     const auth = c.get('auth');  // Get auth context
+ *     const { user, userId, keyId } = auth;
+ *     // Or access directly: c.get('auth').user
+ *   });
+ * ```
+ */
+declare const authenticate: _spfn_core_route.NamedMiddleware<"auth">;
+/**
+ * Optional authentication middleware
+ *
+ * Same as `authenticate` but does NOT reject unauthenticated requests.
+ * - No token → continues without auth context
+ * - Invalid token → continues without auth context
+ * - Valid token → sets auth context normally
+ *
+ * Auto-skips the global 'auth' middleware when used at route level.
+ *
+ * @example
+ * ```typescript
+ * // No need for .skip(['auth']) — handled automatically
+ * export const getProducts = route.get('/products')
+ *   .use([optionalAuth])
+ *   .handler(async (c) => {
+ *     const auth = getOptionalAuth(c);  // AuthContext | undefined
+ *
+ *     if (auth)
+ *     {
+ *       return getPersonalizedProducts(auth.userId);
+ *     }
+ *
+ *     return getPublicProducts();
+ *   });
+ * ```
+ */
+declare const optionalAuth: _spfn_core_route.NamedMiddleware<"optionalAuth">;
+
+export { oauthNativeService as $, type AuthSession as A, rotateKeyService as B, type ChangePasswordParams as C, revokeKeyService as D, type RegisterPublicKeyParams as E, type RotateKeyParams as F, type RevokeKeyParams as G, issueOneTimeTokenService as H, type IssueOneTimeTokenResult as I, verifyOneTimeTokenService as J, oauthStartService as K, type LoginResult as L, oauthCallbackService as M, buildOAuthErrorUrl as N, type OAuthStartResult as O, type PermissionConfig as P, isOAuthProviderEnabled as Q, type RoleConfig as R, type SendVerificationCodeResult as S, requireEnabledProvider as T, type UserProfile as U, type VerificationTargetType as V, getEnabledOAuthProviders as W, getGoogleAccessToken as X, type OAuthStartParams as Y, type OAuthCallbackParams as Z, type OAuthCallbackResult as _, type RegisterResult as a, type OAuthNativeParams as a0, authenticate as a1, optionalAuth as a2, EmailSchema as a3, PhoneSchema as a4, PasswordSchema as a5, TargetTypeSchema as a6, VerificationPurposeSchema as a7, type NormalizedIdentity as a8, type OAuthTokens as a9, type NativeVerifyOptions as aa, type OAuthCodeExchangeOptions as ab, registerOAuthProvider as ac, getOAuthProvider as ad, getRegisteredProviders as ae, type RotateKeyResult as b, type OAuthNativeResult as c, type ProfileInfo as d, type VerificationPurpose as e, VERIFICATION_TARGET_TYPES as f, VERIFICATION_PURPOSES as g, PERMISSION_CATEGORIES as h, type PermissionCategory as i, type AuthInitOptions as j, type OAuthProvider as k, type AuthContext as l, mainAuthRouter as m, loginService as n, logoutService as o, changePasswordService as p, type RegisterParams as q, registerService as r, type LoginParams as s, type LogoutParams as t, sendVerificationCodeService as u, verifyCodeService as v, type SendVerificationCodeParams as w, type VerifyCodeParams as x, type VerifyCodeResult as y, registerPublicKeyService as z };