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

package/dist/machine-principals-B7N8gux0.d.ts

@@ -0,0 +1,3087 @@
+import * as _simplewebauthn_server from '@simplewebauthn/server';
+import { RegistrationResponseJSON, AuthenticationResponseJSON, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON } from '@simplewebauthn/server';
+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 * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import * as _spfn_core_event from '@spfn/core/event';
+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>;
+    /** Client address of the request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the request, already truncated at the route. */
+    userAgent?: string;
+}
+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;
+    /** Client address of the request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the request, already truncated at the route. */
+    userAgent?: string;
+}
+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">[]>;
+/**
+ * Key material as a device sends it, bounded.
+ *
+ * The bounds exist for the one route that takes this material from a caller who
+ * has not authenticated and cannot: `POST /_auth/device/start` persists what it
+ * is given, and a correctly fingerprinted megabyte of base64 would sit in
+ * `device_authorizations` until something swept it — and nothing sweeps it.
+ *
+ * The numbers are what real key material measures, with room to spare. The
+ * package's own generators produce SPKI DER in base64: 124 characters for
+ * ES256 (P-256), 392 for RS256 (RSA-2048). An RSA-4096 key would be 736, an
+ * RSA-8192 key about 1400, and the same 4096-bit key PEM-armoured about 800 —
+ * so 2048 admits every shape of key anyone could reasonably present, while a
+ * megabyte is refused three orders of magnitude before it reaches a row.
+ *
+ * `keyId` is a UUID (36) everywhere this package generates one; 64 leaves room
+ * for a client that prefixes or namespaces its own. `fingerprint` is SHA-256
+ * hex, exactly 64, and nothing else can ever verify against the public key —
+ * 128 is the length a longer digest would need, and no more.
+ */
+declare const PublicKeySchema: _sinclair_typebox.TString;
+declare const KeyIdSchema: _sinclair_typebox.TString;
+declare const FingerprintSchema: _sinclair_typebox.TString;
+/**
+ * The code a person reads off the waiting device and types on their own.
+ *
+ * Loose on purpose: 8 characters plus an optional dash is what is shown, but the
+ * server folds whitespace, dashes and lower case away before looking anything up,
+ * so refusing those spellings here would refuse a code that is on screen. The
+ * bounds exist to stop an unbounded string reaching the database, not to spell
+ * out the format — `USER_CODE_ALPHABET` is the only thing that can match a row.
+ */
+declare const UserCodeSchema: _sinclair_typebox.TString;
+/**
+ * What `POST /_auth/device/poll` answers with.
+ *
+ * A union, because the two answers are different kinds of thing rather than one
+ * shape with optional fields: pending says "ask again in this long", approved is
+ * a completed login carrying exactly what `/_auth/login` returns. `status` is the
+ * discriminant, so a generated client narrows on it instead of testing which
+ * fields happen to be present.
+ *
+ * The mobile contract has no union type, so it exports this as one object with
+ * `status` required and every branch field optional — see
+ * `deviceAuthorization.pollStatusRule` in the bundle. `intervalMillis` is an
+ * integer for the same reason: that grammar carries no floating-point scalar,
+ * and a count of milliseconds never needed one.
+ *
+ * That integer is a promise two things keep, because nothing validates a response
+ * against this schema on the way out. `configureDeviceAuth` refuses an interval
+ * that is not a whole number of milliseconds, so the only value this branch can
+ * carry is one; and `contract-export.test.ts` reads this schema to check the
+ * exported declaration, so writing `Type.Number` here fails the suite instead of
+ * publishing an integer the server does not send.
+ */
+declare const DeviceAuthPollResponseSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TObject<{
+    status: _sinclair_typebox.TLiteral<"pending">;
+    intervalMillis: _sinclair_typebox.TInteger;
+}>, _sinclair_typebox.TObject<{
+    status: _sinclair_typebox.TLiteral<"approved">;
+    userId: _sinclair_typebox.TString;
+    publicId: _sinclair_typebox.TString;
+    email: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    phone: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    passwordChangeRequired: _sinclair_typebox.TBoolean;
+}>]>;
+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 - Verified-Email Signup Service
+ *
+ * A signup where the address is proven before a password exists:
+ *
+ *   request  -> a one-time link is emailed
+ *   confirm  -> the link is exchanged for a short-lived password-setup session
+ *   password -> the account is created, the device registered, the user signed in
+ *
+ * The link token and the setup secret are bearer credentials, so neither is ever
+ * stored. Only their SHA-256 hashes are, and lookup is by hash. A database dump
+ * therefore yields nothing that can be presented to either step.
+ *
+ * The six-digit-code registration path is untouched and remains the default; this
+ * is a second entry point to the same account creation, not a replacement.
+ */
+
+interface RequestSignupLinkParams {
+    email: string;
+    returnPath?: string;
+}
+interface RequestSignupLinkResult {
+    success: boolean;
+    expiresAt: string;
+}
+/**
+ * Step 1 — issue a confirmation link for an address.
+ *
+ * Answers identically whether or not the address already has an account. When it
+ * does, the owner gets a notice instead of a usable link, through the same
+ * dedupe window the six-digit-code path uses.
+ *
+ * Requesting again is how a resend works: every live link for the address is
+ * superseded first, so the newest link is the only one that opens, and any setup
+ * session already opened from an older link dies with it.
+ *
+ * Neither branch sends mail: both hand it to `auth.link-mail`, so the answer
+ * costs the same database work whichever one ran. With no pg-boss initialised
+ * the mail still goes out on this request — see `lib/link-mail-delivery.ts`.
+ */
+declare function requestSignupLinkService(params: RequestSignupLinkParams): Promise<RequestSignupLinkResult>;
+interface ConfirmSignupLinkParams {
+    token: string;
+}
+interface ConfirmSignupLinkResult {
+    email: string;
+    returnPath: string | null;
+    /** Handed to the proxy interceptor, which moves it into an HttpOnly cookie. */
+    setupSecret: string;
+    setupExpiresAt: string;
+}
+/**
+ * Step 2 — exchange a link for a password-setup session.
+ *
+ * Nothing binds the row to a device or a browser, which is what lets someone
+ * request the link on a laptop and open it on a phone.
+ */
+declare function confirmSignupLinkService(params: ConfirmSignupLinkParams): Promise<ConfirmSignupLinkResult>;
+interface CompleteSignupParams {
+    setupSecret?: string;
+    password: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+    deviceName?: string;
+    platform?: KeyPlatformType;
+    metadata?: Record<string, unknown>;
+    /** Client address of the request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the request, already truncated at the route. */
+    userAgent?: string;
+}
+/**
+ * Step 3 — set the password, which is what creates the account.
+ *
+ * Run under `Transactional()`: the user row, the device key and the completion
+ * mark commit together. A device-key failure must not leave an account nobody
+ * can sign into, and a completion mark must not survive a rolled-back account.
+ *
+ * A refusal that is the user's to fix — a weak password, an app policy that
+ * rejects the registration — leaves the setup session usable, so the fix is
+ * retyping the password rather than requesting a fresh email.
+ */
+declare function completeSignupService(params: CompleteSignupParams): Promise<RegisterResult>;
+
+/**
+ * @spfn/auth - Password Reset Service
+ *
+ * Getting back into an account whose password is gone, using the address the
+ * account already proved:
+ *
+ *   request  -> a one-time link is emailed
+ *   confirm  -> the link is exchanged for a short-lived password-setup session
+ *   complete -> the new password is written, everything else is signed out,
+ *               and the browser that reset is signed in on a fresh device key
+ *
+ * Mirrors the verified-email signup slice deliberately — same credentials, same
+ * hashing, same supersede-on-resend, same interceptor moves — with two
+ * differences that matter.
+ *
+ * First, the request answers identically for *every* input and sends mail only
+ * to an account that can be reset. Signup can afford to tell an existing owner
+ * "you already have an account"; a reset cannot send anything to a stranger's
+ * mailbox, because the mail itself would be the answer to "does this address
+ * have an account here".
+ *
+ * Second, completing it is a credential change on a live account, so it carries
+ * the same blast radius as `changePasswordService`: pending device
+ * authorizations are denied and every active key is revoked. Whoever was signed
+ * in on the old password is signed out, including the attacker the reset was
+ * needed for.
+ */
+
+interface RequestPasswordResetParams {
+    email: string;
+    returnPath?: string;
+}
+interface RequestPasswordResetResult {
+    success: boolean;
+    expiresAt: string;
+}
+/**
+ * Step 1 — issue a reset link for an address.
+ *
+ * Answers identically for every input: the same status, the same two fields, and
+ * an `expiresAt` computed the same way whether or not a row was written. An
+ * address with no account, an account that cannot be reset, and an account that
+ * can are indistinguishable to the caller — only the first of the three gets
+ * mail, and it goes to the owner.
+ *
+ * Requesting again is how a resend works: every live link for the account is
+ * superseded first, so the newest link is the only one that opens, and any setup
+ * session already opened from an older link dies with it.
+ *
+ * The eligible branch does not send the mail either — it hands it to
+ * `auth.link-mail` — so the two branches differ by a few database writes and not
+ * by a mail provider's round trip. With no pg-boss initialised the mail still
+ * goes out on this request; see `lib/link-mail-delivery.ts`.
+ */
+declare function requestPasswordResetService(params: RequestPasswordResetParams): Promise<RequestPasswordResetResult>;
+interface ConfirmPasswordResetParams {
+    token: string;
+}
+interface ConfirmPasswordResetResult {
+    email: string;
+    returnPath: string | null;
+    /** Handed to the proxy interceptor, which moves it into an HttpOnly cookie. */
+    setupSecret: string;
+    setupExpiresAt: string;
+}
+/**
+ * Step 2 — exchange a link for a password-setup session.
+ *
+ * Nothing binds the row to a device or a browser, which is what lets someone ask
+ * for the link on a laptop and open it on a phone.
+ */
+declare function confirmPasswordResetService(params: ConfirmPasswordResetParams): Promise<ConfirmPasswordResetResult>;
+interface CompletePasswordResetParams {
+    setupSecret?: string;
+    password: string;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+    deviceName?: string;
+    platform?: KeyPlatformType;
+    /** Client address of the request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the request, already truncated at the route. */
+    userAgent?: string;
+}
+/**
+ * Step 3 — set the new password, which is what completes the reset.
+ *
+ * Run under `Transactional()`: the password, the revocations, the new device key
+ * and the completion mark commit together. A key registration that failed after
+ * the revoke-all would otherwise leave an account with a new password and
+ * nothing signed in.
+ *
+ * A refusal that is the user's to fix — a password the policy rejects, a body
+ * with no device key — leaves the setup session usable, so the fix is retyping
+ * the password rather than asking for a fresh email.
+ */
+declare function completePasswordResetService(params: CompletePasswordResetParams): Promise<RegisterResult>;
+
+/**
+ * @spfn/auth - Device Auth Service
+ *
+ * Device-code login: a device with no key on file yet shows a short code, the
+ * account owner types that code on a device that is already signed in, and the
+ * waiting device's key is registered on approval.
+ *
+ * There is no token to hand over. Every request in this system is signed by the
+ * calling device's own key, so "logging a device in" means one thing — getting
+ * its public key into `user_public_keys` under the right account. That is what
+ * the poll does, and it is why the poll returns exactly what `loginService`
+ * returns: from the client's side the two ways in are indistinguishable.
+ *
+ * | state ↓ op → | info | approve | deny | poll |
+ * | --- | --- | --- | --- | --- |
+ * | pending | device details | → approved | → denied | pending |
+ * | approved | AlreadyHandled | AlreadyHandled | AlreadyHandled | key registered, → consumed |
+ * | denied | AlreadyHandled | AlreadyHandled | AlreadyHandled | Denied |
+ * | consumed | NotFound | NotFound | NotFound | NotFound |
+ * | expired | Expired | Expired | Expired | Expired |
+ * | unknown | NotFound | NotFound | NotFound | NotFound |
+ *
+ * A global revocation — revoke-all, a password change, a deletion request —
+ * refuses the account's live records too, as `denied`, so they land in that row
+ * of the table. See `denyAllActiveByUserId`; the three callers are the three
+ * places that revoke every key at once.
+ */
+
+interface StartDeviceAuthParams {
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+    /** Device label shown to the approver. Display only — nothing is authorized by it. */
+    deviceName?: string;
+    platform?: KeyPlatformType;
+}
+interface StartDeviceAuthResult {
+    /** Returned once. The waiting device polls with it; the server stores only its hash. */
+    deviceCode: string;
+    /** `XXXX-XXXX`, for the waiting device's screen and nowhere else. */
+    userCode: string;
+    expiresAtMillis: number;
+    /** Milliseconds the waiting device should wait between polls. */
+    intervalMillis: number;
+}
+interface DeviceAuthInfoParams {
+    userCode: string;
+}
+/** What the approver is shown about the device asking to be let in. */
+interface DeviceAuthInfoResult {
+    deviceName?: string;
+    /** One of `KEY_PLATFORM`, which is what the route accepts and the column stores. */
+    platform?: KeyPlatformType;
+    /** First bytes of the pending key's fingerprint, as the device list truncates it. */
+    fingerprintPrefix: string;
+    requestedAtMillis: number;
+    expiresAtMillis: number;
+}
+interface ApproveDeviceAuthParams {
+    userCode: string;
+    /** The approver, read from their session. Never from a request body. */
+    userId: number;
+}
+interface DenyDeviceAuthParams {
+    userCode: string;
+}
+interface PollDeviceAuthParams {
+    deviceCode: string;
+    /** Client address of the request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the request, already truncated at the route. */
+    userAgent?: string;
+}
+/** Nobody has answered yet. Not an error — the waiting device waits. */
+interface DeviceAuthPendingResult {
+    status: 'pending';
+    intervalMillis: number;
+}
+/** Approved and spent: the key is registered and this is the login it produced. */
+type DeviceAuthApprovedResult = {
+    status: 'approved';
+} & LoginResult;
+type PollDeviceAuthResult = DeviceAuthPendingResult | DeviceAuthApprovedResult;
+/**
+ * Park a new device's key and hand back the codes it needs.
+ *
+ * The caller is unauthenticated by definition — this is what a device does before
+ * it has any way to prove anything — so nothing here is attributed to an account.
+ * The record gains an owner only when someone approves it.
+ */
+declare function startDeviceAuthService(params: StartDeviceAuthParams): Promise<StartDeviceAuthResult>;
+/**
+ * What the approver sees before deciding.
+ *
+ * This is the whole defence against being talked into approving someone else's
+ * device: the answer names the device that is waiting, so the person holding the
+ * phone can see that it is not theirs. An approval screen that showed only the
+ * code would be asking them to confirm a number they were just told.
+ */
+declare function getDeviceAuthInfoService(params: DeviceAuthInfoParams): Promise<DeviceAuthInfoResult>;
+/**
+ * Bind the record to the approving account.
+ *
+ * The key is not registered here. The waiting device may never come back, and a
+ * key registered for a device that stopped listening is a signing credential
+ * nobody asked for — so approval records the decision and the poll acts on it.
+ *
+ * Answers with the same device description `info` returns, so a client that let
+ * a user approve without looking first can still show them what they just let
+ * in — which is the moment someone talked into approving an attacker's device
+ * has to notice and revoke it.
+ */
+declare function approveDeviceAuthService(params: ApproveDeviceAuthParams): Promise<DeviceAuthInfoResult>;
+/**
+ * Refuse the record, so the waiting device is told no instead of timing out.
+ *
+ * Denying binds no user: the point of refusing is that the account owner wants
+ * nothing to do with the request.
+ */
+declare function denyDeviceAuthService(params: DenyDeviceAuthParams): Promise<void>;
+/**
+ * The waiting device asking whether anyone has answered.
+ *
+ * Approved is the one branch with a side effect, and it is a one-shot: the record
+ * is spent by a conditional update that names `approved`, so of two polls that
+ * arrive together exactly one registers the key. The loser matches nothing and is
+ * answered as if the code were unknown — which by then it is.
+ */
+declare function pollDeviceAuthService(params: PollDeviceAuthParams): Promise<PollDeviceAuthResult>;
+
+/**
+ * @spfn/auth - Passkeys Entity
+ *
+ * A WebAuthn credential the account owner enrolled on one of their devices.
+ * It is a *credential*, not a session: an assertion proves who is asking, and
+ * the ordinary device key in `user_public_keys` is what the request afterwards
+ * is signed with. The two tables therefore never stand in for each other.
+ *
+ * Nothing here is a bearer value, so nothing is hashed. `publicKey` is public by
+ * construction and `credentialId` is a handle the authenticator hands to any
+ * origin that asks — storing either in the clear costs nothing, and the lookup
+ * on `credentialId` has to be a plain equality match on an indexed column.
+ *
+ * Revocation is soft, and `credentialId` stays unique across live and revoked
+ * rows alike: a credential someone cut off must never become enrollable again,
+ * on this account or on another one.
+ */
+/**
+ * Whether the credential can leave the authenticator that minted it.
+ *
+ * `multiDevice` is a synced passkey (iCloud Keychain, Google Password Manager);
+ * `singleDevice` is bound to one authenticator. Reported by the authenticator at
+ * enrollment and shown in the management list, because "this one is only on that
+ * phone" is what the owner needs to know before revoking the other entry.
+ */
+declare const PASSKEY_DEVICE_TYPES: readonly ["singleDevice", "multiDevice"];
+type PasskeyDeviceType = typeof PASSKEY_DEVICE_TYPES[number];
+/** How long a label may be — the key list's `deviceName` bound, for the same reason. */
+declare const PASSKEY_LABEL_MAX_LENGTH = 64;
+declare const passkeys: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "passkeys";
+    schema: string;
+    columns: {
+        createdAt: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        updatedAt: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        id: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.PgBigSerial53Builder>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        userId: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgBigInt53Builder>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "number int53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        credentialId: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        publicKey: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        counter: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgIntegerBuilder>>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "number int32";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        transports: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetDimensions<drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>, 1>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "string";
+            data: string[];
+            driverParam: string | string[];
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        deviceType: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<["singleDevice", "multiDevice"] & [string, ...string[]]>>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "string enum";
+            data: "singleDevice" | "multiDevice";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["singleDevice", "multiDevice"] & [string, ...string[]];
+            identity: undefined;
+            generated: undefined;
+        }>;
+        backedUp: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgBooleanBuilder>>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "boolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        aaguid: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        label: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        lastUsedAt: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.PgTimestampBuilder, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        revokedAt: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.PgTimestampBuilder, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        revokedReason: drizzle_orm_pg_core.PgBuildColumn<"passkeys", drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>, {
+            name: string;
+            tableName: "passkeys";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+    };
+    dialect: "pg";
+}>;
+type Passkey = typeof passkeys.$inferSelect;
+type NewPasskey = typeof passkeys.$inferInsert;
+
+/**
+ * @spfn/auth - Passkey Service
+ *
+ * WebAuthn passkeys as an optional account credential, alongside a password and
+ * a linked social account rather than in place of either.
+ *
+ *   enroll  -> options on an identified session, then verify the attestation
+ *   sign in -> options with no identifier at all, then verify the assertion
+ *   manage  -> list, rename, revoke
+ *
+ * A passkey is not a device key. The assertion proves *who* is asking; the
+ * device key registered right after it is what every later request is signed
+ * with, exactly as after a password login (D2). Nothing in clientProofV1 or in
+ * the JWT path changes because a session started this way.
+ *
+ * Challenges are rows, spent by one conditional UPDATE (D7). Two verifies
+ * arriving with the same challenge therefore produce one winner and one refusal,
+ * across instances, rather than both reading it as live.
+ *
+ * Revoking the last thing an account can sign in with is refused (D6) rather
+ * than warned about, because that state has no undo. A verified email address
+ * counts as one of those things: the password reset flow can always give such an
+ * account a password back.
+ */
+
+/** One enrolled credential as the management surface shows it. */
+interface PasskeySummary {
+    passkeyId: string;
+    label: string | null;
+    deviceType: PasskeyDeviceType;
+    backedUp: boolean;
+    transports: string[];
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+interface RecentAuthenticationParams {
+    userId: number;
+    /** The device key this request is signed with — its age is the signal. */
+    keyId: string;
+    currentPassword?: string;
+}
+/**
+ * Refuse a passkey change unless the caller has recently proved themselves (D4).
+ *
+ * Two ways to satisfy it. The device key this request is signed with was
+ * registered within the window — that is when this device last presented a
+ * credential, and it needs no new state. Or the body carries the account
+ * password.
+ *
+ * An account with no password stored cannot satisfy it with a password, however
+ * plausible the value (E5): the comparison still runs, against a dummy hash, so
+ * "no password on file" costs exactly what "wrong password" costs. Skipping it
+ * would turn response time into an oracle for which accounts are OAuth-only.
+ *
+ * @throws RecentAuthenticationRequiredError
+ */
+declare function assertRecentAuthentication(params: RecentAuthenticationParams): Promise<void>;
+/**
+ * Refuse to remove the only thing an account can sign in with (D6).
+ *
+ * The recovery paths are: another live passkey, a password, a linked social
+ * account, and a verified email address. The last one is new — a password reset
+ * now exists in this package, and an account that can be reset by email can
+ * always get a password back, so the refusal has nothing left to protect.
+ *
+ * What remains refused is the account with none of the four: no other passkey,
+ * no password, no social account, and no verified email — a phone-only account
+ * among them. Nobody, support included, could undo that state.
+ *
+ * @throws LastRecoveryCredentialError
+ */
+declare function assertNotLastRecoveryCredential(userId: number): Promise<void>;
+interface StartPasskeyEnrollmentParams {
+    userId: number;
+    keyId: string;
+    currentPassword?: string;
+}
+/**
+ * Step 1 of enrollment — options for `navigator.credentials.create()`.
+ *
+ * `excludeCredentials` lists the caller's **live** passkeys only, so the
+ * authenticator quietly refuses one already enrolled here. Revoked ones are left
+ * out on purpose: they must not be re-enrolled either, and the check that
+ * refuses them is the global uniqueness check at verify (E11/M10) — listing them
+ * here would hand out credential ids the account no longer uses.
+ */
+declare function startPasskeyEnrollmentService(params: StartPasskeyEnrollmentParams): Promise<PublicKeyCredentialCreationOptionsJSON>;
+interface FinishPasskeyEnrollmentParams {
+    userId: number;
+    response: RegistrationResponseJSON;
+    label?: string;
+}
+interface FinishPasskeyEnrollmentResult {
+    passkeyId: string;
+    label: string | null;
+    createdAt: string;
+}
+/**
+ * Step 2 of enrollment — verify the attestation and keep the credential.
+ *
+ * Runs under `Transactional()`: the challenge is spent and the row written
+ * together, so a failure after the spend leaves the challenge live and the
+ * ceremony retryable, while a success can never be replayed.
+ */
+declare function finishPasskeyEnrollmentService(params: FinishPasskeyEnrollmentParams): Promise<FinishPasskeyEnrollmentResult>;
+/**
+ * Step 1 of sign-in — options for `navigator.credentials.get()`.
+ *
+ * Takes nothing and returns the same shape to everyone: `allowCredentials` is
+ * always empty and the challenge row names no account (D3). There is no input
+ * that could make this answer differ by whether an account exists, which is the
+ * point — the discoverable credential on the device is what names the owner.
+ */
+declare function startPasskeyLoginService(): Promise<PublicKeyCredentialRequestOptionsJSON>;
+interface FinishPasskeyLoginParams {
+    response: AuthenticationResponseJSON;
+    publicKey: string;
+    keyId: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+    oldKeyId?: string;
+    deviceName?: string;
+    platform?: KeyPlatformType;
+    /** Client address of the request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the request, already truncated at the route. */
+    userAgent?: string;
+}
+/**
+ * Step 2 of sign-in — verify the assertion, then sign in exactly as a password
+ * login does.
+ *
+ * The tail from the active-status check onward is the one every identified
+ * sign-in runs (`loginService`, the OAuth flows): revoke the key being replaced,
+ * register the new device key, stamp the last login, announce it after commit.
+ * Passkeys add a way to prove identity, not a second way to hold a session.
+ */
+declare function finishPasskeyLoginService(params: FinishPasskeyLoginParams): Promise<LoginResult>;
+/**
+ * The caller's live passkeys, newest first.
+ */
+declare function listPasskeysService(userId: number): Promise<PasskeySummary[]>;
+interface RenamePasskeyParams {
+    userId: number;
+    passkeyId: string;
+    label: string;
+}
+/**
+ * Rename a passkey. Owner-scoped, so someone else's id is a 404 and nothing
+ * about it is disclosed.
+ *
+ * No recent-authentication gate: a label is display only, and nothing is
+ * authorized by it.
+ */
+declare function renamePasskeyService(params: RenamePasskeyParams): Promise<{
+    passkeyId: string;
+    label: string;
+}>;
+interface RevokePasskeyParams {
+    userId: number;
+    keyId: string;
+    passkeyId: string;
+    currentPassword?: string;
+}
+/**
+ * Retire a passkey.
+ *
+ * Gated on recent authentication, because someone who walked up to an unlocked
+ * laptop should not be able to strip the account's credentials; and on the
+ * last-recovery-credential guard, because there is no undo for the state that
+ * would leave.
+ *
+ * The owner row is locked before the guard runs, and the route's
+ * `Transactional()` is what holds that lock to commit. Without it the guard is a
+ * read-modify-write with a gap: an owner with two passkeys and nothing else who
+ * fires two revokes at once has both count two live credentials, both pass, and
+ * both revoke — the exact state the guard exists to refuse. Locking makes the
+ * second revoke count one.
+ */
+declare function revokePasskeyService(params: RevokePasskeyParams): Promise<{
+    passkeyId: string;
+}>;
+
+/**
+ * Auth provider type
+ *
+ * 직접 인증(email/phone) + 등록 가능한 모든 소셜 provider(SOCIAL_PROVIDERS).
+ */
+declare const AuthProviderSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">, ..._sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]]>;
+/**
+ * auth.login - 로그인 성공 이벤트
+ *
+ * 발행 시점:
+ * - 이메일/전화 로그인 성공 시
+ * - OAuth 기존 사용자 로그인 시
+ * - 기기 코드 승인이 소비되어 새 기기 키가 등록될 때 (provider: 'device')
+ *
+ * @example
+ * ```typescript
+ * authLoginEvent.subscribe(async (payload) => {
+ *     await analytics.trackLogin(payload.userId, payload.provider);
+ * });
+ * ```
+ */
+declare const authLoginEvent: _spfn_core_event.EventDef<{
+    email?: string | undefined;
+    phone?: string | undefined;
+    userId: string;
+    provider: "email" | "phone" | "google" | "apple" | "github" | "kakao" | "naver" | "superself" | "device" | "passkey";
+}>;
+/**
+ * Where a device key was registered — the door the new device came through.
+ *
+ * Required on `RegisterPublicKeyParams` rather than optional with a default: a
+ * new *call site* for key registration must choose one, and a default would let
+ * it inherit somebody else's answer silently. `'register'` and `'signup-link'`
+ * both arrive at `createVerifiedAccount`, so the two name themselves there;
+ * `'invitation'` is the one path that stores a key without the key service.
+ */
+declare const DeviceRegistrationChannelSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"register">, _sinclair_typebox.TLiteral<"signup-link">, _sinclair_typebox.TLiteral<"invitation">, _sinclair_typebox.TLiteral<"password">, _sinclair_typebox.TLiteral<"oauth">, _sinclair_typebox.TLiteral<"oauth-native">, _sinclair_typebox.TLiteral<"device-code">, _sinclair_typebox.TLiteral<"password-reset">, _sinclair_typebox.TLiteral<"passkey">]>;
+/** The nine doors a device key is registered through. */
+type DeviceRegistrationChannel = Static<typeof DeviceRegistrationChannelSchema>;
+/**
+ * auth.device.registered — a new device key was added to an account
+ *
+ * 발행 시점:
+ * - a key row was created for an account and the transaction that created it
+ *   committed, on every one of the nine channels above
+ *
+ * This is the notice an account owner needs and could not get before: a stolen
+ * password used to sign in on a new device was silent, because a login event
+ * says a session began and not what it began on. Rotation is deliberately not
+ * announced — replacing the key of a device that is already signed in is not a
+ * new device, and a notice for it would train the owner to ignore the ones that
+ * matter.
+ *
+ * `ip` and `userAgent` are what the registering request said about itself. Both
+ * are unauthenticated display material: nothing is decided by them, and a field
+ * is absent rather than carrying a placeholder when the request resolved none.
+ *
+ * Neither the full fingerprint nor the public key is carried. The prefix is
+ * enough to point at one entry of `listKeys`, which is what a notice needs.
+ *
+ * @example
+ * ```typescript
+ * authDeviceRegisteredEvent.subscribe(async ({ userId, deviceName, ip, channel }) => {
+ *     await notifyOwner(userId, `A new device signed in (${deviceName ?? channel})`);
+ * });
+ * ```
+ */
+declare const authDeviceRegisteredEvent: _spfn_core_event.EventDef<{
+    deviceName?: string | undefined;
+    platform?: string | undefined;
+    ip?: string | undefined;
+    userAgent?: string | undefined;
+    keyId: string;
+    algorithm: string;
+    userId: string;
+    fingerprintPrefix: string;
+    createdAtMillis: number;
+    channel: "password" | "register" | "oauth-native" | "oauth" | "invitation" | "signup-link" | "password-reset" | "passkey" | "device-code";
+}>;
+/**
+ * auth.register - 회원가입 성공 이벤트
+ *
+ * 발행 시점:
+ * - 이메일/전화 회원가입 성공 시
+ * - OAuth 신규 사용자 가입 시
+ *
+ * @example
+ * ```typescript
+ * authRegisterEvent.subscribe(async (payload) => {
+ *     await emailService.sendWelcome(payload.email);
+ * });
+ * ```
+ */
+declare const authRegisterEvent: _spfn_core_event.EventDef<{
+    email?: string | undefined;
+    phone?: string | undefined;
+    metadata?: {
+        [x: string]: unknown;
+    } | undefined;
+    userId: string;
+    provider: "email" | "phone" | "google" | "apple" | "github" | "kakao" | "naver" | "superself";
+}>;
+/**
+ * auth.invitation.created - 초대 생성 이벤트
+ *
+ * 발행 시점:
+ * - createInvitation() 성공 시
+ * - resendInvitation() 성공 시
+ *
+ * @example
+ * ```typescript
+ * invitationCreatedEvent.subscribe(async (payload) => {
+ *     const inviteUrl = `${APP_URL}/invite/${payload.token}`;
+ *     await notificationService.send({
+ *         channel: 'email',
+ *         to: payload.email,
+ *         subject: 'You are invited!',
+ *         html: renderInviteEmail({ inviteUrl, ...payload.metadata }),
+ *     });
+ * });
+ * ```
+ */
+declare const invitationCreatedEvent: _spfn_core_event.EventDef<{
+    metadata?: {
+        [x: string]: unknown;
+    } | undefined;
+    email: string;
+    token: string;
+    expiresAt: string;
+    roleId: number;
+    invitedBy: string;
+    invitationId: string;
+    isResend: boolean;
+}>;
+/**
+ * auth.invitation.accepted - 초대 수락 이벤트
+ *
+ * 발행 시점:
+ * - acceptInvitation() 성공 시
+ *
+ * @example
+ * ```typescript
+ * invitationAcceptedEvent.subscribe(async (payload) => {
+ *     await onboardingService.start(payload.userId);
+ * });
+ * ```
+ */
+declare const invitationAcceptedEvent: _spfn_core_event.EventDef<{
+    metadata?: {
+        [x: string]: unknown;
+    } | undefined;
+    email: string;
+    userId: string;
+    roleId: number;
+    invitedBy: string;
+    invitationId: string;
+}>;
+/**
+ * auth.deletion.requested - 계정 탈퇴 요청 이벤트
+ *
+ * 발행 시점:
+ * - requestAccountDeletionService() 성공 시 (self/admin 공통)
+ *
+ * @example
+ * ```typescript
+ * authDeletionRequestedEvent.subscribe(async (payload) => {
+ *     await analytics.trackChurnRisk(payload.userId);
+ * });
+ * ```
+ */
+declare const authDeletionRequestedEvent: _spfn_core_event.EventDef<{
+    userId: string;
+    purgeScheduledAt: string;
+    userPublicId: string;
+    requestedBy: "admin" | "self";
+}>;
+/**
+ * auth.deletion.cancelled - 계정 탈퇴 복구 이벤트
+ *
+ * 발행 시점:
+ * - cancelAccountDeletionService() 성공 시 (유예 기간 내 복구)
+ */
+declare const authDeletionCancelledEvent: _spfn_core_event.EventDef<{
+    userId: string;
+    userPublicId: string;
+}>;
+/**
+ * auth.deletion.completed - 계정 파기 완료 이벤트
+ *
+ * 발행 시점:
+ * - purge job(또는 즉시 파기 경로)이 유저를 파기한 직후
+ *
+ * PII를 담지 않는다 — userId(내부 순번)/email/phone 없이 userPublicId만 실어
+ * 파기 완료 이후에도 구독자가 식별 정보를 다시 축적하지 않도록 한다.
+ */
+declare const authDeletionCompletedEvent: _spfn_core_event.EventDef<{
+    userPublicId: string;
+    purgeStrategy: "anonymize" | "hard-delete";
+}>;
+/**
+ * auth.oauth.unlinked - provider발 연동 해제 이벤트
+ *
+ * 발행 시점:
+ * - provider(카카오·네이버 등)가 unlink-notify 웹훅으로 연동 해제를 알려와
+ *   소셜 계정 연결과 저장 토큰이 삭제된 직후
+ *
+ * 연결 삭제까지는 프레임워크가 수행하고, 그 이후(계정 탈퇴로 이어갈지 등)는
+ * 앱 정책이므로 이 이벤트를 구독해 처리한다.
+ *
+ * @example
+ * ```typescript
+ * oauthUnlinkedEvent.subscribe(async (payload) => {
+ *     await requestAccountDeletionService({ userId: payload.userId, requestedBy: 'self' });
+ * });
+ * ```
+ */
+declare const oauthUnlinkedEvent: _spfn_core_event.EventDef<{
+    reason?: string | undefined;
+    userId: string;
+    provider: "email" | "phone" | "google" | "apple" | "github" | "kakao" | "naver" | "superself";
+    providerUserId: string;
+}>;
+/**
+ * auth.password.reset — an account's password was replaced through a reset link
+ *
+ * 발행 시점:
+ * - completePasswordResetService()가 커밋된 직후
+ *
+ * Distinct from a password *change*, which is made from a session that already
+ * proved itself. This one is made by whoever opened a link in a mailbox, so it
+ * is the event an app hangs a "your password was reset" notice on — and the
+ * signal to look at, if the owner says they did not ask for it.
+ *
+ * @example
+ * ```typescript
+ * authPasswordResetEvent.subscribe(async (payload) => {
+ *     await notifyOwner(payload.userId, 'Your password was reset');
+ * });
+ * ```
+ */
+declare const authPasswordResetEvent: _spfn_core_event.EventDef<{
+    email: string;
+    userId: string;
+}>;
+/**
+ * Auth event payload types
+ */
+type AuthLoginPayload = typeof authLoginEvent._payload;
+type AuthRegisterPayload = typeof authRegisterEvent._payload;
+type AuthPasswordResetPayload = typeof authPasswordResetEvent._payload;
+type AuthDeviceRegisteredPayload = typeof authDeviceRegisteredEvent._payload;
+type InvitationCreatedPayload = typeof invitationCreatedEvent._payload;
+type InvitationAcceptedPayload = typeof invitationAcceptedEvent._payload;
+type AuthDeletionRequestedPayload = typeof authDeletionRequestedEvent._payload;
+type AuthDeletionCancelledPayload = typeof authDeletionCancelledEvent._payload;
+type AuthDeletionCompletedPayload = typeof authDeletionCompletedEvent._payload;
+type OAuthUnlinkedPayload = typeof oauthUnlinkedEvent._payload;
+
+/**
+ * @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;
+    /**
+     * Which door this device came through. Required, so that a registration path
+     * added later has to say what it is rather than inherit an answer.
+     */
+    channel: DeviceRegistrationChannel;
+    /** Client address of the registering request, absent when none resolved. */
+    ip?: string;
+    /** `user-agent` of the registering request, already truncated. */
+    userAgent?: string;
+    /**
+     * The key this one replaces on the same device, when a revocation actually
+     * happened. Its presence is what makes this a rotation rather than a new
+     * device, so no event is announced for it.
+     *
+     * Only ever set from a `revokeKeyService` that returned true: an `oldKeyId`
+     * naming somebody else's key, an already-revoked key or nothing at all
+     * revokes nothing, and treating that as a rotation would be a way to
+     * register a device with the owner's notice switched off.
+     */
+    replacesKeyId?: string;
+}
+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.
+     *
+     * Optional because the two branches have different needs and always did: the
+     * sparing branch has to know what to spare, and the `includeCurrent` branch
+     * never reads it. The signed revoke-all link is the caller with no current
+     * key to name — it arrives with no session at all — and requiring a value it
+     * would have to invent is how a claim about a device that made no request
+     * gets into a result.
+     */
+    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;
+    /** One of `KEY_PLATFORM`, which is what the routes accept and the column stores. */
+    platform?: KeyPlatformType;
+    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;
+    /**
+     * Client address the key was registered from, absent when none was resolved
+     * or the key predates the column. Registration only — it does not move when
+     * the device authenticates from somewhere else, which is what makes it
+     * useful for recognising a device that was never yours.
+     */
+    registeredIp?: string;
+    /** `user-agent` of the registering request, on the same terms as above. */
+    registeredUserAgent?: string;
+}
+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와 맞지 않을 때
+ * @throws KeyAlgorithmMismatchError 키의 SPKI 타입이 선언된 algorithm과 다를 때
+ */
+declare function registerPublicKeyService(params: RegisterPublicKeyParams): Promise<void>;
+/**
+ * Rotate user's public key (revoke old, register new)
+ *
+ * @throws InvalidKeyFingerprintError fingerprint가 newPublicKey와 맞지 않을 때
+ * @throws KeyAlgorithmMismatchError 새 키의 SPKI 타입이 선언된 algorithm과 다를 때
+ */
+declare function rotateKeyService(params: RotateKeyParams): Promise<RotateKeyResult>;
+/**
+ * Revoke a user's public key.
+ *
+ * Returns false when this call revoked nothing: the key belongs to somebody
+ * else, or it was already revoked, or there is no such key. A caller acting on
+ * a key id from outside (the device list) can therefore answer "not found"
+ * instead of reporting a revocation that never happened — and the login paths
+ * can tell a device replacement from a brand-new device, which is what decides
+ * whether the owner is told about it. The repository 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.
+ *
+ * Live device authorizations are refused as well, in both modes. A device
+ * waiting on an approved code has no key yet, so it is never the caller's own
+ * device and never the one being spared — but its next poll would register a
+ * brand-new active key, which would undo the revocation seconds after it ran.
+ * That is the whole point of the call: the user has decided nothing else is to
+ * stay signed in.
+ *
+ * `revokedCount` counts keys only, since that is the number the caller's screen
+ * means by "devices signed out"; a code nobody had collected was never a session.
+ */
+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;
+    /** Client address of the callback request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the callback request, already truncated at the route. */
+    userAgent?: string;
+}
+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;
+    /** Client address of the request, from `deviceProvenance` at the route. */
+    ip?: string;
+    /** `user-agent` of the request, already truncated at the route. */
+    userAgent?: 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>;
+
+/**
+ * OAuth 2.1 Authorize Service
+ *
+ * The API half of the consent screen. The screen itself is a page on the web
+ * app, because that is where the session cookie is; it has no database, so it
+ * asks here what to draw (`describeOAuth2AuthorizeRequest`) and tells here what
+ * the user decided (`approveOAuth2Authorize` / `denyOAuth2Authorize`). Both
+ * calls validate the request from scratch — the second must never trust what the
+ * first was shown, since a form can be edited between them.
+ *
+ * Refusals come in two kinds and the split is the security property, not a
+ * presentation choice:
+ *
+ * - **Not redirectable.** An unknown `client_id`, or a `redirect_uri` the client
+ *   never registered. There is no vetted URI to send the error to, and sending
+ *   it to the one the request supplied is precisely the open redirect the
+ *   registration check exists to prevent. These are shown on the screen.
+ * - **Redirectable.** Everything else — a missing PKCE challenge, a missing
+ *   `resource`, an unknown scope, and the user saying no. The client and its
+ *   URI are both vetted by then, so RFC 6749 §4.1.2.1 puts the error back on
+ *   that URI as query parameters, which is the only form the waiting CLI can
+ *   read.
+ */
+/** An authorize request as the web handler forwards it, before anything is trusted. */
+interface OAuth2AuthorizeParams {
+    clientId: string;
+    redirectUri: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: string;
+    resource?: string;
+    scope?: string;
+    state?: string;
+}
+/** One scope, with the sentence the consent screen shows for it. */
+interface OAuth2ScopeDescription {
+    name: string;
+    description: string;
+}
+/** Everything the consent screen needs, and nothing it does not. */
+interface OAuth2ConsentView {
+    clientName: string;
+    /** Host the code would be sent to — the one fact about the client that is checkable. */
+    redirectHost: string;
+    scopes: OAuth2ScopeDescription[];
+    resource: string;
+}
+/** What the web handler turns into the success redirect. */
+interface OAuth2AuthorizationCodeIssued {
+    code: string;
+    /** The presented URI, which matched a registered one. Safe to redirect to. */
+    redirectUri: string;
+    /** Echoed back verbatim, or absent when the request carried none. */
+    state?: string;
+}
+/**
+ * What to draw on the consent screen for this request.
+ *
+ * Read-only: nothing is recorded by looking, so a user who closes the tab has
+ * consented to nothing and left nothing behind.
+ */
+declare function describeOAuth2AuthorizeRequestService(params: OAuth2AuthorizeParams): Promise<OAuth2ConsentView>;
+/**
+ * Record the consent and mint the code.
+ *
+ * The whole request is validated again rather than carried over from the GET:
+ * the form between the two is in the user's browser, and a parameter changed
+ * there must be caught here and not honoured because the screen once looked
+ * right.
+ *
+ * `userId` comes from the approving session. Never from a request body — that
+ * would be the entire authorization.
+ */
+declare function approveOAuth2AuthorizeService(params: OAuth2AuthorizeParams, userId: number): Promise<OAuth2AuthorizationCodeIssued>;
+/**
+ * The user said no.
+ *
+ * Validated first, and validated in full — the same `validate` the approval
+ * runs. `access_denied` goes back to the client on its redirect URI like any
+ * other redirectable error, so the URI has to be one the client registered
+ * before anybody is sent to it; and a request that was malformed was malformed
+ * whichever button was pressed, so answering `access_denied` to it would tell
+ * the waiting client the user refused when in fact it never asked properly.
+ * Nothing is recorded — a refusal is not a grant with a flag on it.
+ */
+declare function denyOAuth2AuthorizeService(params: OAuth2AuthorizeParams): Promise<never>;
+
+/**
+ * OAuth 2.1 Grant Service
+ *
+ * The user's side of the authorization server: what is connected, and the button
+ * that disconnects it. A grant is the unit because it is the thing a person can
+ * recognise — "Claude Code, on this API, with these permissions" — and because
+ * revoking it takes every code and token underneath with it.
+ *
+ * `revokeAllOAuth2GrantsForUser` is the same act performed on the user's behalf
+ * rather than by them, and it sits at the four places that revoke everything:
+ * revoke-all, a password change, a completed password reset, a deletion request.
+ * A global revocation that left a grant alive would leave a refresh token alive,
+ * and a CLI holding one would be signed in again within the hour — which is
+ * exactly the device the user was cutting off.
+ */
+/** One connected client, as the account settings screen lists it. */
+interface OAuth2GrantSummary {
+    id: number;
+    clientId: string;
+    clientName: string;
+    resource: string;
+    scopes: string[];
+    createdAtMillis: number;
+    lastUsedAtMillis?: number;
+}
+/** What a user has connected. Revoked grants are not listed — they are gone. */
+declare function listOAuth2GrantsService(userId: number): Promise<OAuth2GrantSummary[]>;
+/**
+ * Disconnect one client.
+ *
+ * The user id is part of the statement's condition, not a check before it: the
+ * id comes from a URL, and a grant belonging to somebody else must answer as if
+ * it did not exist rather than as if it were merely not theirs.
+ */
+declare function revokeOAuth2GrantService(id: number, userId: number): Promise<void>;
+/**
+ * Revoke every grant a user has — the authorization-server half of a global
+ * revocation, called beside `deviceAuthorizationsRepository.denyAllActiveByUserId`.
+ *
+ * Tokens are revoked as well as the grants. Verification already refuses a token
+ * whose grant is dead, so this changes no decision; it means a `SELECT` against
+ * `oauth2_tokens` after a revoke-all does not show live-looking rows, which is
+ * the sort of thing that gets read as a hole.
+ */
+declare function revokeAllOAuth2GrantsForUser(userId: number): Promise<void>;
+
+/**
+ * @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)
+ * - OAuth 2.1 authorization server: /_auth/oauth2/*, /.well-known/oauth-authorization-server
+ */
+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>;
+    requestSignupLink: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            email: _sinclair_typebox.TString;
+            returnPath: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, RequestSignupLinkResult>;
+    confirmSignupLink: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+        }>;
+    }, {}, ConfirmSignupLinkResult>;
+    completeSignup: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            password: _sinclair_typebox.TString;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
+        }>;
+    }, {
+        body: _sinclair_typebox.TObject<{
+            setupSecret: _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">[]>>;
+        }>;
+    }, RegisterResult>;
+    requestPasswordReset: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            email: _sinclair_typebox.TString;
+            returnPath: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, RequestPasswordResetResult>;
+    confirmPasswordReset: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+        }>;
+    }, {}, ConfirmPasswordResetResult>;
+    completePasswordReset: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            password: _sinclair_typebox.TString;
+        }>;
+    }, {
+        body: _sinclair_typebox.TObject<{
+            setupSecret: _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">[]>>;
+        }>;
+    }, 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>;
+    startDeviceAuth: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            publicKey: _sinclair_typebox.TString;
+            keyId: _sinclair_typebox.TString;
+            fingerprint: _sinclair_typebox.TString;
+            algorithm: _sinclair_typebox.TOptional<_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">[]>>;
+        }>;
+    }, {}, StartDeviceAuthResult>;
+    pollDeviceAuth: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            deviceCode: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        status: "pending";
+        intervalMillis: number;
+    } | {
+        email?: string | undefined;
+        phone?: string | undefined;
+        status: "approved";
+        userId: string;
+        publicId: string;
+        passwordChangeRequired: boolean;
+    }>;
+    getDeviceAuthInfo: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            userCode: _sinclair_typebox.TString;
+        }>;
+    }, {}, DeviceAuthInfoResult>;
+    approveDeviceAuth: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            userCode: _sinclair_typebox.TString;
+        }>;
+    }, {}, DeviceAuthInfoResult>;
+    denyDeviceAuth: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            userCode: _sinclair_typebox.TString;
+        }>;
+    }, {}, void>;
+    passkeyRegisterOptions: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            currentPassword: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, _simplewebauthn_server.PublicKeyCredentialCreationOptionsJSON>;
+    passkeyRegisterVerify: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            response: _sinclair_typebox.TUnknown;
+            label: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, FinishPasskeyEnrollmentResult>;
+    passkeyLoginOptions: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{}>;
+    }, {}, _simplewebauthn_server.PublicKeyCredentialRequestOptionsJSON>;
+    passkeyLoginVerify: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            response: _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">[]>;
+            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>;
+    listPasskeys: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{}>;
+    }, {}, {
+        passkeys: PasskeySummary[];
+    }>;
+    renamePasskey: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            passkeyId: _sinclair_typebox.TString;
+            label: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        passkeyId: string;
+        label: string;
+    }>;
+    revokePasskey: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            passkeyId: _sinclair_typebox.TString;
+            currentPassword: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, {
+        passkeyId: string;
+    }>;
+    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>;
+    confirmRevokeAllLink: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        expiresAt: string;
+        activeKeyCount: number;
+    }>;
+    consumeRevokeAllLink: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+        }>;
+    }, {}, {
+        revokedCount: number;
+    }>;
+    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;
+        keyEpoch: number;
+        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;
+        };
+    }>;
+    registerOAuth2Client: _spfn_core_route.RouteDef<{}, {}, Response>;
+    getOAuth2Authorize: _spfn_core_route.RouteDef<{
+        query: _sinclair_typebox.TObject<{
+            client_id: _sinclair_typebox.TString;
+            redirect_uri: _sinclair_typebox.TString;
+            code_challenge: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            code_challenge_method: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            resource: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            scope: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, OAuth2ConsentView>;
+    createOAuth2AuthorizationCode: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            approve: _sinclair_typebox.TBoolean;
+            client_id: _sinclair_typebox.TString;
+            redirect_uri: _sinclair_typebox.TString;
+            code_challenge: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            code_challenge_method: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            resource: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            scope: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, OAuth2AuthorizationCodeIssued>;
+    oauth2Token: _spfn_core_route.RouteDef<{}, {}, Response>;
+    oauth2Revoke: _spfn_core_route.RouteDef<{}, {}, Response>;
+    listOAuth2Grants: _spfn_core_route.RouteDef<{}, {}, {
+        grants: OAuth2GrantSummary[];
+    }>;
+    revokeOAuth2Grant: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            id: _sinclair_typebox.TNumber;
+        }>;
+    }, {}, {
+        revoked: boolean;
+    }>;
+    oauth2AuthorizationServerMetadata: _spfn_core_route.RouteDef<{}, {}, Response>;
+}>;
+
+/**
+ * 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.
+ *
+ * An app adds its own scheme with `registerAuthProfile` at boot. The dispatch
+ * it joins is the one below, unchanged: a name nobody registered is still
+ * refused, and profile credentials mixed with an Authorization header are
+ * still refused before either path runs.
+ *
+ * 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. The union stays open for the profiles an app
+     * registers itself: the built-in names keep their autocomplete, and a
+     * registered profile names its own scheme without editing this file.
+     */
+    scheme: 'bearer' | 'clientProofV1' | 'oneTimeToken' | (string & {});
+}
+/** 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>;
+/**
+ * Registers an app's own verifier under a profile name.
+ *
+ * Call it at boot, before the first request: the registry is a module-global
+ * read on every dispatch, so a profile registered later is simply a profile
+ * the requests before it did not have. There is no freeze and no
+ * unregistration — an auth surface that can be rearranged at runtime is a
+ * surface an app bug can rearrange.
+ *
+ * A duplicate name throws rather than replacing the verifier that holds it,
+ * `clientProofV1` included. A silent override is how a second import order, or
+ * a copied profile name, quietly swaps the code that decides who is admitted.
+ *
+ * The verifier must expose a callable `verify` — a value that cannot admit
+ * anyone is refused at boot rather than becoming a registry entry the dispatch
+ * reads as "no profile header", which is anonymous passage under
+ * `optionalAuth` for a request that presented profile credentials.
+ *
+ * The verifier returns the same `AuthContext` the Bearer path sets and refuses
+ * by throwing. A resolve that carries no `userId` is refused as a throw too —
+ * "no user" is a refusal, never a principal. A throw is not caught here:
+ * `runAuthProfile` answers the internal clientProofV1 contract refusal and
+ * nothing else, so a verifier's own error reaches the app's generic error
+ * handler exactly as the Bearer path's `UnauthorizedError` does — and never
+ * becomes anonymous passage, not even under `optionalAuth`.
+ *
+ * @example
+ * ```typescript
+ * registerAuthProfile('serviceTokenV1', {
+ *     verify: async (c) =>
+ *     {
+ *         const user = await authenticateServiceToken(c.req.header('x-acme-service-token'));
+ *         if (user === null)
+ *         {
+ *             throw new UnauthorizedError({ message: 'Invalid service token' });
+ *         }
+ *
+ *         return { user, userId: String(user.id), keyId: 'service', role: null, locale: 'en', scheme: 'serviceTokenV1' };
+ *     },
+ * });
+ * ```
+ */
+declare function registerAuthProfile(profileId: string, verifier: AuthProfileVerifier): void;
+
+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('/status')
+ *   .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">;
+
+/** What a verified machine request acts as. Not a user, by construction. */
+interface MachinePrincipal {
+    /** e.g. 'account' | 'service' | registrant-defined */
+    subjectType: string;
+    subjectId: string;
+    scopes: string[];
+    /** verifier-defined extras (claims, token id for audit, …) */
+    claims?: Record<string, unknown>;
+    /** which registered verifier admitted it */
+    scheme: string;
+}
+interface MachineVerifierRegistration {
+    /** unique id; becomes MachinePrincipal.scheme */
+    id: string;
+    /** exactly one discriminator */
+    match: {
+        tokenPrefix: string;
+    } | {
+        kidPrefix: string;
+    };
+    verify(token: string, c: Context): Promise<MachinePrincipal>;
+}
+declare module 'hono' {
+    interface ContextVariableMap {
+        machinePrincipal: MachinePrincipal;
+    }
+}
+/** Read the verified machine principal a handler runs under. */
+declare function getMachinePrincipal(c: Context): MachinePrincipal | null;
+/**
+ * Registers a verifier for one machine credential namespace. Call it at boot.
+ *
+ * Refused at registration: a duplicate `id`, a `match` that does not name
+ * exactly one non-empty discriminator, a verifier without a callable `verify`,
+ * and — the point of the check — a discriminator that shadows or is shadowed by
+ * an already-registered one of the same kind. Two verifiers a token could match
+ * would make admission depend on registration order; that is a boot-time bug,
+ * not something the dispatch should resolve on every request.
+ *
+ * @example
+ * ```typescript
+ * registerMachineVerifier({
+ *     id: 'runtimeJwsV1',
+ *     match: { kidPrefix: 'machine:runtime:' },
+ *     verify: async (token) =>
+ *     {
+ *         const { payload } = await jwtVerify(token, RUNTIME_JWKS);
+ *
+ *         return {
+ *             subjectType: 'account',
+ *             subjectId: String(payload.sub),
+ *             scopes: String(payload.scope ?? '').split(' ').filter(Boolean),
+ *             scheme: 'runtimeJwsV1',
+ *         };
+ *     },
+ * });
+ * ```
+ */
+declare function registerMachineVerifier(reg: MachineVerifierRegistration): void;
+/**
+ * Admits a machine credential, or refuses. Sets `machinePrincipal`; `auth`
+ * stays unset, so `getAuth(c)` is as empty here as on an anonymous request.
+ *
+ * Auto-skips the global 'auth' middleware, like `opsTokenAuth`.
+ *
+ * @example
+ * ```typescript
+ * export const ingest = route.post('/v1/ingest')
+ *   .use([machineAuth, requireMachineScope('events:write')])
+ *   .handler(async (c) => {
+ *     const { subjectType, subjectId } = getMachinePrincipal(c.raw)!;
+ *     // ...
+ *   });
+ * ```
+ */
+declare const machineAuth: _spfn_core_route.NamedMiddleware<"machineAuth">;
+/**
+ * Require the verified machine principal to carry every named scope.
+ *
+ * Fails closed: no principal in the context is a 401, not a pass — a route that
+ * mounted this without `machineAuth` refuses rather than running unauthenticated,
+ * exactly as `requireOpsScope` does. Scopes match exactly; there is no wildcard,
+ * because what a scope string means belongs to the verifier that issued it.
+ *
+ * @example
+ * ```ts
+ * export const ingest = route.post('/v1/ingest')
+ *     .use([machineAuth, requireMachineScope('events:write')])
+ *     .handler(async () => { ... });
+ * ```
+ */
+declare const requireMachineScope: _spfn_core_route.NamedMiddlewareFactory<"machineScope", string[]>;
+
+export { type DenyDeviceAuthParams as $, type AuthInitOptions as A, type AuthDeletionRequestedPayload as B, type ConfirmSignupLinkResult as C, type DeviceAuthInfoResult as D, type AuthDeviceRegisteredPayload as E, type FinishPasskeyEnrollmentResult as F, type AuthLoginPayload as G, type AuthPasswordResetPayload as H, type IssueOneTimeTokenResult as I, type AuthProfileOutcome as J, type KeySummary as K, type LoginResult as L, type AuthProfileVerifier as M, type NewPasskey as N, type OAuthStartResult as O, type PermissionConfig as P, AuthProviderSchema as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type AuthRegisterPayload as T, type UserProfile as U, VERIFICATION_PURPOSES as V, type ChangePasswordParams as W, type CompletePasswordResetParams as X, type CompleteSignupParams as Y, type ConfirmPasswordResetParams as Z, type ConfirmSignupLinkParams as _, type RegisterResult as a, assertRecentAuthentication as a$, type DeviceAuthApprovedResult as a0, type DeviceAuthInfoParams as a1, type DeviceAuthPendingResult as a2, DeviceAuthPollResponseSchema as a3, DeviceNameSchema as a4, type DeviceRegistrationChannel as a5, EmailSchema as a6, FingerprintSchema as a7, type FinishPasskeyEnrollmentParams as a8, type FinishPasskeyLoginParams as a9, type PollDeviceAuthResult as aA, PublicKeySchema as aB, type RecentAuthenticationParams as aC, type RegisterParams as aD, type RegisterPublicKeyParams as aE, type RenamePasskeyParams as aF, type RequestPasswordResetParams as aG, type RequestSignupLinkParams as aH, type RevokeAllKeysParams as aI, type RevokeKeyParams as aJ, type RevokePasskeyParams as aK, type RotateKeyParams as aL, type SendVerificationCodeParams as aM, type StartDeviceAuthParams as aN, type StartPasskeyEnrollmentParams as aO, TargetTypeSchema as aP, type UnlinkNotification as aQ, UnlinkNotifyRejection as aR, type UnlinkNotifyRequest as aS, type UnlinkNotifyResult as aT, UserCodeSchema as aU, VerificationPurposeSchema as aV, type VerifyCodeParams as aW, type VerifyCodeResult as aX, approveDeviceAuthService as aY, approveOAuth2AuthorizeService as aZ, assertNotLastRecoveryCredential as a_, type InvitationAcceptedPayload as aa, type InvitationCreatedPayload as ab, KEY_FINGERPRINT_PREFIX_LENGTH as ac, KeyIdSchema as ad, type LoginParams as ae, type LogoutParams as af, type MachinePrincipal as ag, type MachineVerifierRegistration as ah, type NativeVerifyOptions as ai, type NormalizedIdentity as aj, type OAuth2AuthorizeParams as ak, type OAuth2ScopeDescription as al, type OAuthCallbackParams as am, type OAuthCallbackResult as an, type OAuthCodeExchangeOptions as ao, type OAuthNativeParams as ap, type OAuthStartParams as aq, type OAuthTokens as ar, type OAuthUnlinkedPayload as as, PASSKEY_DEVICE_TYPES as at, PASSKEY_LABEL_MAX_LENGTH as au, type PasskeyDeviceType as av, PasswordSchema as aw, PhoneSchema as ax, PlatformSchema as ay, type PollDeviceAuthParams as az, type RequestSignupLinkResult as b, startDeviceAuthService as b$, authDeletionCancelledEvent as b0, authDeletionCompletedEvent as b1, authDeletionRequestedEvent as b2, authDeviceRegisteredEvent as b3, authLoginEvent as b4, authPasswordResetEvent as b5, authRegisterEvent as b6, authenticate as b7, buildOAuthErrorUrl as b8, changePasswordService as b9, oauthNativeService as bA, oauthStartService as bB, oauthUnlinkNotifyService as bC, oauthUnlinkedEvent as bD, optionalAuth as bE, passkeys as bF, pollDeviceAuthService as bG, registerAuthProfile as bH, registerMachineVerifier as bI, registerOAuthProvider as bJ, registerPublicKeyService as bK, registerService as bL, renamePasskeyService as bM, requestPasswordResetService as bN, requestSignupLinkService as bO, requireEnabledProvider as bP, requireMachineScope as bQ, resolveAuthenticatedUser as bR, revokeAllKeysService as bS, revokeAllOAuth2GrantsForUser as bT, revokeKeyService as bU, revokeOAuth2GrantService as bV, revokePasskeyService as bW, rotateKeyService as bX, runAuthProfile as bY, selectAuthProfile as bZ, sendVerificationCodeService as b_, completePasswordResetService as ba, completeSignupService as bb, confirmPasswordResetService as bc, confirmSignupLinkService as bd, denyDeviceAuthService as be, denyOAuth2AuthorizeService as bf, describeOAuth2AuthorizeRequestService as bg, finishPasskeyEnrollmentService as bh, finishPasskeyLoginService as bi, getDeviceAuthInfoService as bj, getEnabledOAuthProviders as bk, getGoogleAccessToken as bl, getMachinePrincipal as bm, getOAuthProvider as bn, getRegisteredProviders as bo, invitationAcceptedEvent as bp, invitationCreatedEvent as bq, isOAuthProviderEnabled as br, issueOneTimeTokenService as bs, listKeysService as bt, listOAuth2GrantsService as bu, listPasskeysService as bv, loginService as bw, logoutService as bx, machineAuth as by, oauthCallbackService as bz, type RequestPasswordResetResult as c, startPasskeyEnrollmentService as c0, startPasskeyLoginService as c1, verifyCodeService as c2, verifyOneTimeTokenService as c3, type ConfirmPasswordResetResult as d, type StartDeviceAuthResult as e, type PasskeySummary as f, type RotateKeyResult as g, type RevokeAllKeysResult as h, type OAuthNativeResult as i, type ProfileInfo as j, type OAuth2ConsentView as k, type OAuth2AuthorizationCodeIssued as l, mainAuthRouter as m, type OAuth2GrantSummary as n, type AuthSession as o, PERMISSION_CATEGORIES as p, type PermissionCategory as q, VERIFICATION_TARGET_TYPES as r, type VerificationPurpose as s, type VerificationTargetType as t, type OAuthProvider as u, type Passkey as v, type AuthContext as w, type ApproveDeviceAuthParams as x, type AuthDeletionCancelledPayload as y, type AuthDeletionCompletedPayload as z };