@spfn/auth 0.2.1 → 0.3.0-beta.2

package/dist/authenticate-55LeXHqZ.d.ts

@@ -0,0 +1,1447 @@
+import * as _spfn_core_route from '@spfn/core/route';
+import { K as KeyAlgorithmType, h as KeyPlatformType, j as SocialProvider } from './types-DYyhze28.js';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static } from '@sinclair/typebox';
+import { Context } from 'hono';
+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;
+    deviceName?: string;
+    platform?: KeyPlatformType;
+    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;
+    deviceName?: string;
+    platform?: KeyPlatformType;
+}
+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;
+/**
+ * Optional device labels a client may send when registering a key.
+ *
+ * Display only: the key list uses them to tell one device from another, and
+ * nothing is authorized or refused by either value, so a client that lies about
+ * them gains nothing. Both are omitted by every key registered before they
+ * existed, hence optional rather than defaulted.
+ */
+declare const DeviceNameSchema: _sinclair_typebox.TString;
+declare const PlatformSchema: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ios" | "android" | "web" | "desktop">[]>;
+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;
+    /** Device label for the key list. Display only — nothing is authorized by it. */
+    deviceName?: string;
+    platform?: KeyPlatformType;
+}
+interface RotateKeyParams {
+    userId: number;
+    oldKeyId: string;
+    newKeyId: string;
+    newPublicKey: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+    /** Omitted: the replaced key's label carries over, so rotation keeps its name. */
+    deviceName?: string;
+    platform?: KeyPlatformType;
+}
+interface RotateKeyResult {
+    success: boolean;
+    keyId: string;
+}
+interface RevokeKeyParams {
+    userId: number;
+    keyId: string;
+    reason: string;
+}
+interface RevokeAllKeysParams {
+    userId: number;
+    /** The key the request itself is signed with — spared unless includeCurrent. */
+    currentKeyId: string;
+    /** true signs the caller out too. Default false: "my other devices". */
+    includeCurrent?: boolean;
+    reason: string;
+}
+interface RevokeAllKeysResult {
+    revokedCount: number;
+    currentKeyRevoked: boolean;
+}
+/** One registered device as the account surface shows it. */
+interface KeySummary {
+    keyId: string;
+    deviceName?: string;
+    platform?: string;
+    algorithm: KeyAlgorithmType;
+    /** First bytes of the fingerprint — enough to tell two entries apart. */
+    fingerprintPrefix: string;
+    /**
+     * Milliseconds since the Unix epoch, not an ISO string.
+     *
+     * One representation of a moment across the whole surface: a generated Swift
+     * or Kotlin client reads an integer with no date formatter, and
+     * `ISO8601DateFormatter` rejecting fractional seconds by default stops being
+     * a way for the two SDKs to disagree about the same value.
+     */
+    createdAtMillis: number;
+    lastUsedAtMillis?: number;
+    expiresAtMillis?: number;
+    /** The TTL has run out. The key still reads as active; authenticate refuses it. */
+    isExpired: boolean;
+    /** False once revoked. Only ever false when the caller asked for revoked keys. */
+    isActive: boolean;
+    /** When it was revoked, for the "what did I cut off, and when" reading. */
+    revokedAtMillis?: number;
+}
+interface ListKeysParams {
+    userId: number;
+    /** Also return keys already revoked. Default false: only what can still sign. */
+    includeRevoked?: boolean;
+}
+/** How much of the fingerprint the list returns. */
+declare const KEY_FINGERPRINT_PREFIX_LENGTH = 8;
+/**
+ * Register a new public key for a user
+ *
+ * `keyId` is UNIQUE across all users, so the lookup must ignore `isActive` —
+ * filtering on it misses a revoked row and the insert then fails on the unique
+ * index, rolling the whole login transaction back into a 500. Reuse is refused
+ * with a domain error instead, telling the client to generate a fresh keyId.
+ *
+ * @throws KeyIdAlreadyRegisteredError keyId가 이미 쓰인 값일 때 (자기 폐기 키 재사용 · 남의 키)
+ * @throws InvalidKeyFingerprintError fingerprint가 publicKey와 맞지 않을 때
+ */
+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.
+ *
+ * Returns false when the key does not belong to this user, so a caller acting
+ * on a key id from outside (the device list) can answer "not found" instead of
+ * reporting a revocation that never happened. The repository already scopes the
+ * update by userId, so someone else's key is never touched either way.
+ */
+declare function revokeKeyService(params: RevokeKeyParams): Promise<boolean>;
+/**
+ * List the caller's active keys — one entry per device that can sign for them.
+ *
+ * `isExpired` is computed rather than stored: an expired key keeps `isActive`
+ * true (nothing flips it), and `authenticate` refuses it at request time. A list
+ * that showed it as simply "active" would be telling the user something the
+ * server does not act on.
+ *
+ * The fingerprint is truncated. Its full value is what a native sign-in must
+ * send as its nonce (issue #63), and an account page has no use for it beyond
+ * telling two entries apart.
+ */
+declare function listKeysService(params: ListKeysParams): Promise<KeySummary[]>;
+/**
+ * Revoke every active key the user has, optionally sparing the current one.
+ *
+ * The caller's own key is spared by default, so "sign out my other devices"
+ * does not also end the session making the request. Passing
+ * `includeCurrent: true` is the full sign-out, which until now was reachable
+ * only as a side effect of changing a password.
+ */
+declare function revokeAllKeysService(params: RevokeAllKeysParams): Promise<RevokeAllKeysResult>;
+
+/**
+ * @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;
+    /**
+     * 같은 로그인에서 SDK가 함께 받은 provider access token (선택).
+     *
+     * id_token만으로는 알 수 없는 claim을 provider API로 보강하려는 provider가 쓴다
+     * (카카오: id_token에 email_verified가 없어 /v2/user/me의 이메일 유효·인증 플래그를 본다).
+     *
+     * ⚠️ 클라이언트가 보낸 검증되지 않은 값이다. 다른 사용자의 토큰일 수 있으므로,
+     * 이 값으로 조회한 신원은 반드시 id_token의 sub와 대조한 뒤에만 신뢰해야 한다.
+     */
+    accessToken?: string;
+}
+interface OAuthCodeExchangeOptions {
+    /** Provider가 callback에 돌려준 원본 state. 일부 provider는 token 교환에도 요구한다. */
+    state: string;
+}
+/**
+ * Provider가 서비스로 보내는 연동 해제 알림의 원재료
+ *
+ * provider마다 전달 방식(query/form/JSON, 헤더 인증)이 달라 route가 정규화해 넘긴다.
+ * fields는 query string과 body(form/JSON)를 병합한 문자열 맵이다.
+ */
+interface UnlinkNotifyRequest {
+    /** Authorization 헤더 원문 (없으면 null) */
+    authorization: string | null;
+    fields: Record<string, string>;
+}
+/**
+ * 검증에 성공한 연동 해제 알림
+ */
+interface UnlinkNotification {
+    providerUserId: string;
+    /** provider가 전달한 해제 경로 (kakao referrer_type 등) */
+    reason?: string;
+}
+/**
+ * 연동 해제 알림 검증 실패
+ *
+ * API 에러 응답 체계를 타지 않는다 — route가 잡아 status만 반환한다.
+ * (provider 웹훅은 사람이 아닌 provider 서버가 호출자라서 에러 본문이 무의미하다)
+ */
+declare class UnlinkNotifyRejection extends Error {
+    readonly status: 400 | 401 | 403;
+    constructor(status: 400 | 401 | 403, message: 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>;
+    /**
+     * Provider발 연동 해제 알림(웹훅)을 검증하고 대상 사용자를 식별한다.
+     *
+     * 인증 없는 공개 엔드포인트로 들어오므로 provider별 규격(카카오: 어드민 키 헤더,
+     * 네이버: HMAC 서명 + AES 복호화)의 검증을 통과해야만 처리된다.
+     * 검증 실패는 UnlinkNotifyRejection을 던진다.
+     */
+    verifyUnlinkNotification?(request: UnlinkNotifyRequest): Promise<UnlinkNotification>;
+    /**
+     * 연동 해제 알림 처리 성공 시 응답할 HTTP status (미지정 시 200)
+     *
+     * 네이버는 204 No Content를 요구한다.
+     */
+    unlinkNotifyAckStatus?: 200 | 204;
+}
+/**
+ * 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>;
+interface UnlinkNotifyResult {
+    /** provider 규격이 요구하는 성공 응답 status */
+    ackStatus: 200 | 204;
+    /** 대상 소셜 계정을 찾아 삭제했는지 (미존재·이미 삭제면 false) */
+    handled: boolean;
+}
+/**
+ * Provider발 연동 해제 알림(unlink-notify) 처리
+ *
+ * 검증(verifyUnlinkNotification)을 통과한 요청만 여기 도달한다.
+ * 소셜 계정 연결 row를 삭제해 저장 토큰(access/refresh)까지 함께 파기하고,
+ * 후속 정책(계정 탈퇴 연계 등)은 auth.oauth.unlinked 이벤트 구독에 맡긴다.
+ *
+ * 대상 계정이 없어도 성공으로 응답한다 — provider 재전송·이미 해제된 계정에
+ * 대한 알림은 정상 시나리오다.
+ */
+declare function oauthUnlinkNotifyService(provider: SocialProvider, notification: UnlinkNotification): Promise<UnlinkNotifyResult>;
+
+/**
+ * @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;
+    /** 키 목록에 보일 기기 라벨 (선택). 표시용이라 권한 판정에 쓰이지 않는다. */
+    deviceName?: string;
+    platform?: KeyPlatformType;
+    /**
+     * SDK가 id_token과 함께 받은 provider access token (선택).
+     *
+     * provider가 id_token만으로 확인할 수 없는 claim을 보강할 때만 쓴다. 없으면 provider는
+     * id_token이 담은 정보만으로 신원을 정규화한다.
+     */
+    accessToken?: string;
+    /** Apple은 첫 로그인에만 이름을 별도로 주므로 클라이언트가 전달할 수 있다. */
+    profile?: {
+        name?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+interface OAuthNativeResult {
+    userId: string;
+    keyId: string;
+    isNewUser: boolean;
+}
+/**
+ * native id_token 로그인 처리
+ *
+ * @throws NativeSignInUnsupportedError 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">[]>;
+            deviceName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            platform: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ios" | "android" | "web" | "desktop">[]>>;
+        }>;
+    }, 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>;
+            deviceName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            platform: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ios" | "android" | "web" | "desktop">[]>>;
+        }>;
+    }, 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">[]>;
+            deviceName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            platform: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ios" | "android" | "web" | "desktop">[]>>;
+        }>;
+    }, RotateKeyResult>;
+    listKeys: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            includeRevoked: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        }>;
+    }, {}, {
+        keys: KeySummary[];
+    }>;
+    revokeKey: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            keyId: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        keyId: string;
+        selfRevoked: boolean;
+    }>;
+    revokeAllKeys: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            includeCurrent: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        }>;
+    }, {}, RevokeAllKeysResult>;
+    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;
+            accessToken: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ES256" | "RS256">[]>;
+            deviceName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            platform: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ios" | "android" | "web" | "desktop">[]>>;
+            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>;
+    oauthUnlinkNotify: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+    }, {}, void | Response>;
+    oauthUnlinkNotifyGet: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
+        }>;
+    }, {}, void | Response>;
+    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;
+            name: string;
+            id: number;
+            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;
+            name: string;
+            id: number;
+            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;
+            name: string;
+            id: number;
+            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;
+    }>;
+    issueOpsToken: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            name: _sinclair_typebox.TString;
+            scopes: _sinclair_typebox.TArray<_sinclair_typebox.TString>;
+            expiresInDays: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TNumber, _sinclair_typebox.TNull]>>;
+        }>;
+    }, {}, {
+        token: string;
+        opsToken: {
+            id: number;
+            name: string;
+            scopes: string[];
+            expiresAt: string | null;
+            revokedAt: string | null;
+            lastUsedAt: string | null;
+            createdAt: string | null;
+        };
+    }>;
+    listOpsTokens: _spfn_core_route.RouteDef<{}, {}, {
+        opsTokens: {
+            id: number;
+            name: string;
+            scopes: string[];
+            expiresAt: string | null;
+            revokedAt: string | null;
+            lastUsedAt: string | null;
+            createdAt: string | null;
+        }[];
+    }>;
+    revokeOpsToken: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TNumber;
+        }>;
+    }, {}, {
+        opsToken: {
+            id: number;
+            name: string;
+            scopes: string[];
+            expiresAt: string | null;
+            revokedAt: string | null;
+            lastUsedAt: string | null;
+            createdAt: string | null;
+        };
+    }>;
+}>;
+
+/**
+ * The auth-profile registry the authenticate middleware dispatches on.
+ *
+ * A request that names `x-spfn-auth-profile` is answered by the verifier
+ * registered for that profile — an O(1) map lookup, never a per-profile if
+ * chain in the middleware body. A request that names no profile falls through
+ * to the existing Bearer path untouched.
+ *
+ * Every verifier converges on the same `AuthContext` the Bearer path sets, so
+ * downstream permission/tenant code consumes one principal shape and never
+ * branches on how it was authenticated.
+ *
+ * The clientProofV1 verifier reuses the phase-1 admission pieces (header
+ * shape, canonical body, proof-input assembly, ECDSA verification) with two
+ * production substitutions: the key directory is `user_public_keys` via
+ * `keysRepository`, and the replay ledger is the pluggable store from
+ * `client-proof/replay-store` (memory default, Redis opt-in). The admission
+ * order is the contract's — revocation → session → expiry → replay → proof —
+ * and the non-disclosure rule holds: an unregistered keyId shares
+ * PROOF_INVALID with a failed signature, while a revoked or expired key
+ * answers SESSION_REVOKED before the proof is ever examined.
+ *
+ * @module server/middleware/auth-profiles
+ */
+
+/** What a verified request leaves in the context — one shape for every scheme. */
+interface AuthContext {
+    user: User;
+    userId: string;
+    keyId: string;
+    role: string | null;
+    locale: string;
+    /** How the principal was authenticated. Informational — downstream code never branches on it. */
+    scheme: 'bearer' | 'clientProofV1' | 'oneTimeToken';
+}
+/** A profile's verifier: admits the request and returns the principal, or throws. */
+interface AuthProfileVerifier {
+    verify(c: Context): Promise<AuthContext>;
+}
+/**
+ * Routes a request to its profile verifier.
+ *
+ * - no profile header → null: the caller continues on the Bearer path;
+ * - profile header + Authorization header → rejected (mixing prohibited);
+ * - unknown profile value → rejected (unknownProfilePolicy: reject).
+ *
+ * Shared by authenticate and optionalAuth so "presented but invalid" refuses
+ * identically on both — only the "presented nothing" outcome differs.
+ */
+declare function selectAuthProfile(c: Context): AuthProfileVerifier | null;
+/**
+ * Loads the user for an authenticated key and applies the account-status
+ * rules. One implementation for every scheme: the Bearer path and the profile
+ * verifiers call this, so a status added here gates both identically.
+ */
+declare function resolveAuthenticatedUser(userId: number): Promise<{
+    user: User;
+    role: string | null;
+    locale: string;
+}>;
+/** What the profile path produced for one request. */
+type AuthProfileOutcome = {
+    kind: 'none';
+} | {
+    kind: 'authenticated';
+    auth: AuthContext;
+} | {
+    kind: 'refused';
+    response: Response;
+};
+/**
+ * The profile path from dispatch to answer — what `authenticate` and
+ * `optionalAuth` both run before their own Bearer code.
+ *
+ * `none` means the request named no profile and the caller continues on the
+ * Bearer path. A refusal comes back as a built response rather than a throw:
+ * the answer a proven call gets is the contract's own envelope, and an error
+ * handed to the generic error handler is classified by its class name instead.
+ */
+declare function runAuthProfile(c: Context): Promise<AuthProfileOutcome>;
+
+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 { type UnlinkNotifyResult as $, type AuthInitOptions as A, PasswordSchema as B, type ChangePasswordParams as C, DeviceNameSchema as D, EmailSchema as E, PhoneSchema as F, PlatformSchema as G, type RegisterParams as H, type IssueOneTimeTokenResult as I, type RegisterPublicKeyParams as J, type KeySummary as K, type LoginResult as L, type RevokeAllKeysParams as M, type NativeVerifyOptions as N, type OAuthStartResult as O, type PermissionConfig as P, type RevokeKeyParams as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type RotateKeyParams as T, type UserProfile as U, VERIFICATION_PURPOSES as V, type SendVerificationCodeParams as W, TargetTypeSchema as X, type UnlinkNotification as Y, UnlinkNotifyRejection as Z, type UnlinkNotifyRequest as _, type RegisterResult as a, VerificationPurposeSchema as a0, type VerifyCodeParams as a1, type VerifyCodeResult as a2, authenticate as a3, buildOAuthErrorUrl as a4, changePasswordService as a5, getEnabledOAuthProviders as a6, getGoogleAccessToken as a7, getOAuthProvider as a8, getRegisteredProviders as a9, isOAuthProviderEnabled as aa, issueOneTimeTokenService as ab, listKeysService as ac, loginService as ad, logoutService as ae, oauthCallbackService as af, oauthNativeService as ag, oauthStartService as ah, oauthUnlinkNotifyService as ai, optionalAuth as aj, registerOAuthProvider as ak, registerPublicKeyService as al, registerService as am, requireEnabledProvider as an, resolveAuthenticatedUser as ao, revokeAllKeysService as ap, revokeKeyService as aq, rotateKeyService as ar, runAuthProfile as as, selectAuthProfile as at, sendVerificationCodeService as au, verifyCodeService as av, verifyOneTimeTokenService as aw, type RotateKeyResult as b, type RevokeAllKeysResult as c, type OAuthNativeResult as d, type ProfileInfo as e, type AuthSession as f, PERMISSION_CATEGORIES as g, type PermissionCategory as h, VERIFICATION_TARGET_TYPES as i, type VerificationPurpose as j, type VerificationTargetType as k, type OAuthProvider as l, mainAuthRouter as m, type AuthContext as n, type AuthProfileOutcome as o, type AuthProfileVerifier as p, KEY_FINGERPRINT_PREFIX_LENGTH as q, type LoginParams as r, type LogoutParams as s, type NormalizedIdentity as t, type OAuthCallbackParams as u, type OAuthCallbackResult as v, type OAuthCodeExchangeOptions as w, type OAuthNativeParams as x, type OAuthStartParams as y, type OAuthTokens as z };