@spfn/auth 0.3.0-beta.24 → 0.3.0-beta.25

package/dist/{machine-principals-ZJd9anVT.d.ts → machine-principals-CdEgxOB1.d.ts}

@@ -1,6 +1,6 @@
-import * as _simplewebauthn_server from '@simplewebauthn/server';
-import { AuthenticationResponseJSON, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON, PublicKeyCredentialCreationOptionsJSON } from '@simplewebauthn/server';
 import { S as SessionBindingType, K as KeyAlgorithmType, h as KeyPlatformType, l as SocialProvider } from './types-CTdoTOxM.js';
+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 * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
@@ -91,288 +91,69 @@ interface UserProfile {
 }
 
 /**
- * @spfn/auth - Passkeys Entity
+ * @spfn/auth - What a sign-in answers with
  *
- * 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.
+ * One module for the shape every path that starts a session returns, and for the
+ * helper that fills in its binding half. It is here rather than in
+ * `auth.service.ts` because three of its readers are upstream of that file —
+ * `key.service` decides the second-factor step-up, `mfa.service` resolves it —
+ * and a type living with one of its producers would put those services in a
+ * cycle with each other.
+ */
+
+/**
+ * The second-factor challenge a stepped-up sign-in hands back (#95).
  *
- * 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.
+ * `secret` is the 32 random bytes the challenge was minted from, and it is the
+ * only form of it that ever leaves the server — the row is addressed by its
+ * hash. It authorizes exactly one thing, `POST /_auth/mfa/verify` for this one
+ * registration, and it is not a bearer credential for anything else.
+ */
+interface MfaChallengeHandle {
+    secret: string;
+    /** Epoch milliseconds the challenge stops verifying at. */
+    expiresAtMillis: number;
+}
+/**
+ * What a sign-in answers with, on every path that starts a session.
  *
- * 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.
+ * **One type with a required discriminant, not a union.** A sign-in on an
+ * account with a second factor and a device it has never seen answers 202 with
+ * `mfaRequired: true` and a challenge instead of a session (#95), and the two
+ * answers have to be one declared type: `authApi.login` infers its result from
+ * this declaration, so a union would make every existing `result.userId` in
+ * every consuming app stop compiling, and the mobile contract's grammar has no
+ * union type either — `DeviceAuthPollResponse` was flattened the same way and
+ * for the same reason. Narrow on `mfaRequired` before reading `userId`.
+ *
+ * `sessionBinding` and `keyExpiresAtMillis` are the carrier #97 needed. The
+ * Next.js proxy generated the device key and sealed the cookie, but only the
+ * backend knows whether the account asked for a bound session and when the key
+ * it just registered runs out — so the sign-in says it here and the interceptor
+ * copies both into `SessionData`. A response without them seals an unbound
+ * session, which is what every account that did not opt in gets and what every
+ * path predating that change keeps getting.
  */
+interface LoginResult {
+    /** true means no session was started: verify the challenge below first. */
+    mfaRequired: boolean;
+    /** Present exactly when `mfaRequired` is true. */
+    challenge?: MfaChallengeHandle;
+    userId?: string;
+    publicId?: string;
+    email?: string;
+    phone?: string;
+    passwordChangeRequired?: boolean;
+    /** `'passkey'` when the key registered by this sign-in is bound. Absent otherwise. */
+    sessionBinding?: SessionBindingType;
+    /** Epoch milliseconds that key expires at. Only sent alongside `sessionBinding`. */
+    keyExpiresAtMillis?: number;
+}
+
 /**
- * Whether the credential can leave the authenticator that minted it.
+ * @spfn/auth - Auth Service
  *
- * `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;
-        }>;
-        secondFactor: 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;
-        }>;
-        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 - Auth Service
- *
- * Core authentication logic: registration, login, logout, password management
+ * Core authentication logic: registration, login, logout, password management
  */
 
 interface RegisterParams {
@@ -422,36 +203,7 @@ interface LoginParams {
     /** Whether proxy-guard recognised the trusted Next.js proxy, from the same helper. */
     webProxy?: boolean;
 }
-/**
- * What a sign-in answers with, on every path that starts a session.
- *
- * The last two fields are the carrier #97 needed. The Next.js proxy generated
- * the device key and sealed the cookie, but only the backend knows whether the
- * account asked for a bound session and when the key it just registered runs
- * out — so the sign-in says it here and the interceptor copies both into
- * `SessionData`. A response without them seals an unbound session, which is what
- * every account that did not opt in gets and what every path predating this
- * change keeps getting.
- */
-interface LoginResult {
-    userId: string;
-    publicId: string;
-    email?: string;
-    phone?: string;
-    passwordChangeRequired: boolean;
-    /** `'passkey'` when the key registered by this sign-in is bound. Absent otherwise. */
-    sessionBinding?: SessionBindingType;
-    /** Epoch milliseconds that key expires at. Only sent alongside `sessionBinding`. */
-    keyExpiresAtMillis?: number;
-}
-/**
- * The binding half of a sign-in answer, as a type.
- *
- * Named because more than one result carries it: a password reset registers a
- * device key exactly as a sign-in does, so its answer has to say so too or the
- * proxy seals a cookie that does not know the key it holds is short-lived.
- */
-type LoginBindingFields = Pick<LoginResult, 'sessionBinding' | 'keyExpiresAtMillis'>;
+
 interface LogoutParams {
     userId: number;
     keyId: string;
@@ -492,94 +244,6 @@ declare function logoutService(params: LogoutParams): Promise<void>;
  */
 declare function changePasswordService(params: ChangePasswordParams): Promise<void>;
 
-/**
- * @spfn/auth - Session Renewal Service
- *
- * What a bound session does when its key runs out: prove, with a fresh WebAuthn
- * assertion, that the person who enrolled the passkey is still at the machine,
- * and get a new short-lived key sealed into the cookie.
- *
- * Neither step is public. The expiring key is named by `expiredKeyId`, and that
- * value reaches the service from `authenticateForRenewal` — the `keyId` of a
- * bearer JWT this very key signed — rather than from the request body, so a
- * caller who does not hold the private half cannot name a key at all. The
- * assertion still has to be signed by a passkey that key's owner enrolled: the
- * signature proves the cookie, and the cookie is the thing that may have been
- * copied.
- *
- * The admission below is run again here all the same. The middleware and the
- * service ask the same four questions of the row, and a service that trusted its
- * caller to have asked them would be one refactor away from not being asked at
- * all.
- *
- * Every refusal is the same refusal. A key that never existed, a stranger's key,
- * an unbound key, a revoked one, one past its grace, an inactive account, a spent
- * challenge, an assertion that did not verify — all `SessionRenewalRefusedError`,
- * with the same body, because anything finer would answer "is this key id live"
- * to whoever asked.
- *
- * Renewal announces nothing. No `auth.login`, no `auth.device.registered`, and
- * `lastLoginAt` does not move: this is the same person on the same device
- * continuing the session they already had, and a subscriber mailing "new sign-in"
- * once a day per device would train its reader to ignore the notice that matters.
- * A `lastLoginAt` that moved every day would make dormant-account detection
- * meaningless for exactly the accounts that turned this protection on.
- */
-
-interface StartSessionRenewParams {
-    /** The key that ran out, read off the JWT the request was signed with. */
-    expiredKeyId: string;
-}
-interface FinishSessionRenewParams extends StartSessionRenewParams {
-    /** The assertion, from `navigator.credentials.get()`. */
-    response: AuthenticationResponseJSON;
-    /**
-     * The new key pair, in the vocabulary the Next.js login interceptor already
-     * writes: `renew/verify` is on that interceptor's path list, so these arrive
-     * exactly as they do on a login.
-     */
-    keyId: string;
-    publicKey: string;
-    fingerprint: string;
-    algorithm?: KeyAlgorithmType;
-}
-/**
- * What a completed renewal answers: a sign-in result, plus the new key's id.
- *
- * The id is the one thing a renewal has that a sign-in does not need to say —
- * `renewSession()` promises it to the app, which has no other way to learn it
- * (the key pair is minted in the proxy and the private half never leaves the
- * cookie). It is not a contract operation, so nothing generated reads it.
- */
-interface SessionRenewResult extends LoginResult {
-    /** The key this renewal registered, the one the session now signs with. */
-    keyId: string;
-}
-/**
- * Step 1 — the challenge the authenticator signs.
- *
- * `allowCredentials` is empty and the account lives only on the challenge row.
- * See `startRenewalCeremonyService`.
- *
- * @throws SessionRenewalRefusedError 갱신할 수 없는 키·계정일 때 (모든 사유 동일)
- */
-declare function startSessionRenewService(params: StartSessionRenewParams): Promise<PublicKeyCredentialRequestOptionsJSON>;
-/**
- * Step 2 — verify the assertion, put a new bound key in place of the old one.
- *
- * The revocation runs first and its answer is the race winner: two verifies that
- * both got past their own challenges meet at the same conditional UPDATE, and
- * only the one that actually revoked the key goes on to register a replacement.
- *
- * The new key inherits the old row's provenance, so the device list keeps saying
- * where this device first appeared rather than re-stamping itself every day. Its
- * expiry is a fresh window from now — renewal is a renewal, not an extension of
- * what the old key had.
- *
- * @throws SessionRenewalRefusedError 갱신할 수 없을 때 (증명 실패 포함, 모든 사유 동일)
- */
-declare function finishSessionRenewService(params: FinishSessionRenewParams): Promise<SessionRenewResult>;
-
 declare const EmailSchema: _sinclair_typebox.TString;
 declare const PhoneSchema: _sinclair_typebox.TString;
 /**
@@ -652,6 +316,7 @@ declare const DeviceAuthPollResponseSchema: _sinclair_typebox.TUnion<[_sinclair_
     intervalMillis: _sinclair_typebox.TInteger;
 }>, _sinclair_typebox.TObject<{
     status: _sinclair_typebox.TLiteral<"approved">;
+    mfaRequired: _sinclair_typebox.TBoolean;
     userId: _sinclair_typebox.TString;
     publicId: _sinclair_typebox.TString;
     email: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
@@ -898,7 +563,7 @@ interface CompletePasswordResetParams {
  * believing the session unbound: no user-agent check for the life of that key,
  * and a sign-out a day later instead of the renewal prompt.
  */
-declare function completePasswordResetService(params: CompletePasswordResetParams): Promise<RegisterResult & LoginBindingFields>;
+declare function completePasswordResetService(params: CompletePasswordResetParams): Promise<LoginResult>;
 
 /**
  * @spfn/auth - Device Auth Service
@@ -986,10 +651,22 @@ interface DeviceAuthPendingResult {
     status: 'pending';
     intervalMillis: number;
 }
-/** Approved and spent: the key is registered and this is the login it produced. */
+/**
+ * Approved and spent: the key is registered and this is the login it produced.
+ *
+ * `LoginResult`'s login fields are optional because a sign-in may answer a
+ * second-factor challenge instead of a session (#95). This branch never can —
+ * the owner already said yes on a device that is signed in, which is itself the
+ * second factor — so the three it always carries are narrowed back to required
+ * and a consumer of the approved branch reads exactly what it always read.
+ */
 type DeviceAuthApprovedResult = {
     status: 'approved';
-} & LoginResult;
+} & LoginResult & {
+    userId: string;
+    publicId: string;
+    passwordChangeRequired: boolean;
+};
 type PollDeviceAuthResult = DeviceAuthPendingResult | DeviceAuthApprovedResult;
 /**
  * Park a new device's key and hand back the codes it needs.
@@ -1039,95 +716,374 @@ declare function denyDeviceAuthService(params: DenyDeviceAuthParams): Promise<vo
 declare function pollDeviceAuthService(params: PollDeviceAuthParams): Promise<PollDeviceAuthResult>;
 
 /**
- * @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).
+ * @spfn/auth - Passkeys Entity
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
  *
- * @throws LastRecoveryCredentialError
+ * 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.
  */
-declare function assertNotLastRecoveryCredential(userId: number): Promise<void>;
-interface StartPasskeyEnrollmentParams {
-    userId: number;
-    keyId: string;
-    currentPassword?: string;
-}
 /**
- * Step 1 of enrollment — options for `navigator.credentials.create()`.
- *
- * An enrolled account steps up first, and every account then meets the
- * recent-authentication rule this route has always had (#95). The order is what
- * makes the two independent: `assertStepUp` is a no-op for an unenrolled
- * account, so the answer such a caller gets is byte-for-byte today's.
+ * Whether the credential can leave the authenticator that minted it.
  *
- * `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.
+ * `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;
+        }>;
+        secondFactor: 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;
+        }>;
+        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()`.
+ *
+ * An enrolled account steps up first, and every account then meets the
+ * recent-authentication rule this route has always had (#95). The order is what
+ * makes the two independent: `assertStepUp` is a no-op for an unenrolled
+ * account, so the answer such a caller gets is byte-for-byte today's.
+ *
+ * `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 {
@@ -1141,94 +1097,607 @@ interface FinishPasskeyEnrollmentResult {
     createdAt: string;
 }
 /**
- * Step 2 of enrollment — verify the attestation and keep the credential.
+ * 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;
+    /** Whether proxy-guard recognised the trusted Next.js proxy, from the same helper. */
+    webProxy?: boolean;
+}
+/**
+ * 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 the second factor for an enrolled account, and then — for every
+ * account, enrolled or not — 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">[]]>;
+/** The doors `auth.login` can name, as a type. */
+type AuthLoginProvider = Static<typeof AuthLoginProviderSchema>;
+/**
+ * Login provider type
+ *
+ * AuthProviderSchema + `'device'` and `'passkey'`.
+ *
+ * `'device'` is how a device-code login names itself: the account was proven on
+ * another device that was already signed in, so no credential was presented here
+ * and none of the values above describes it. `'passkey'` is a WebAuthn assertion
+ * — a credential of the account, but not one of the sign-up channels.
+ *
+ * A separate union rather than a widened AuthProviderSchema. Neither is a way to
+ * register — a device-code request can only ever be approved by an existing
+ * account, and a passkey has to be enrolled from a session that already exists —
+ * and neither is something a provider can unlink, so the two events that mean
+ * those things must not start accepting them.
+ */
+declare const AuthLoginProviderSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">, _sinclair_typebox.TLiteral<"device">, _sinclair_typebox.TLiteral<"passkey">, ..._sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]]>;
+/**
+ * auth.login - 로그인 성공 이벤트
+ *
+ * 발행 시점:
+ * - 이메일/전화 로그인 성공 시
+ * - OAuth 기존 사용자 로그인 시
+ * - 기기 코드 승인이 소비되어 새 기기 키가 등록될 때 (provider: 'device')
+ *
+ * `mfaEnrolled` is computed as the event is emitted (#95) and is the whole of
+ * the package's opinion about the second factor: it never blocks an account
+ * that has none, and this is the hook an app uses to offer enrolment at a first
+ * login. It says nothing about *which* factor and carries no secret.
+ *
+ * @example
+ * ```typescript
+ * authLoginEvent.subscribe(async (payload) => {
+ *     await analytics.trackLogin(payload.userId, payload.provider);
+ *     if (!payload.mfaEnrolled) await suggestSecondFactor(payload.userId);
+ * });
+ * ```
+ */
+declare const authLoginEvent: _spfn_core_event.EventDef<{
+    email?: string | undefined;
+    phone?: string | undefined;
+    userId: string;
+    provider: "email" | "phone" | "passkey" | "google" | "apple" | "github" | "kakao" | "naver" | "superself" | "device";
+    mfaEnrolled: boolean;
+}>;
+/**
+ * Where a device key was registered — the door the new device came through.
  *
- * 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.
+ * 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 function finishPasskeyEnrollmentService(params: FinishPasskeyEnrollmentParams): Promise<FinishPasskeyEnrollmentResult>;
+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">, _sinclair_typebox.TLiteral<"renewal">]>;
+/** The ten doors a device key is registered through. */
+type DeviceRegistrationChannel = Static<typeof DeviceRegistrationChannelSchema>;
 /**
- * Step 1 of sign-in — options for `navigator.credentials.get()`.
+ * auth.device.registered — a new device key was added to an account
  *
- * 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.
+ * 발행 시점:
+ * - a key row was created for an account and the transaction that created it
+ *   committed, on every one of the ten 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.
+ *
+ * `mfaEnrolled` is computed as the event is emitted (#95), so a notice about a
+ * new device can also be the moment an app offers a second factor to the
+ * accounts that have none.
+ *
+ * @example
+ * ```typescript
+ * authDeviceRegisteredEvent.subscribe(async ({ userId, deviceName, ip, channel }) => {
+ *     await notifyOwner(userId, `A new device signed in (${deviceName ?? channel})`);
+ * });
+ * ```
  */
-declare function startPasskeyLoginService(): Promise<PublicKeyCredentialRequestOptionsJSON>;
-interface FinishPasskeyLoginParams {
-    response: AuthenticationResponseJSON;
-    publicKey: string;
+declare const authDeviceRegisteredEvent: _spfn_core_event.EventDef<{
+    deviceName?: string | undefined;
+    platform?: string | undefined;
+    ip?: string | undefined;
+    userAgent?: string | undefined;
     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;
-    /** Whether proxy-guard recognised the trusted Next.js proxy, from the same helper. */
-    webProxy?: boolean;
-}
+    algorithm: string;
+    userId: string;
+    mfaEnrolled: boolean;
+    fingerprintPrefix: string;
+    createdAtMillis: number;
+    channel: "password" | "register" | "passkey" | "oauth-native" | "renewal" | "signup-link" | "invitation" | "oauth" | "device-code" | "password-reset";
+}>;
 /**
- * Step 2 of sign-in — verify the assertion, then sign in exactly as a password
- * login does.
+ * auth.register - 회원가입 성공 이벤트
  *
- * 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.
+ * 발행 시점:
+ * - 이메일/전화 회원가입 성공 시
+ * - 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 function finishPasskeyLoginService(params: FinishPasskeyLoginParams): Promise<LoginResult>;
+declare const authPasswordResetEvent: _spfn_core_event.EventDef<{
+    email: string;
+    userId: string;
+}>;
 /**
- * The caller's live passkeys, newest first.
+ * Auth event payload types
  */
-declare function listPasskeysService(userId: number): Promise<PasskeySummary[]>;
-interface RenamePasskeyParams {
-    userId: number;
-    passkeyId: string;
-    label: string;
-}
+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;
+
 /**
- * Rename a passkey. Owner-scoped, so someone else's id is a 404 and nothing
- * about it is disclosed.
+ * The four doors a second factor is asked for at.
  *
- * No recent-authentication gate: a label is display only, and nothing is
- * authorized by it.
+ * A subset of `DeviceRegistrationChannel`, and the subset is the decision: these
+ * are the four where a stolen first credential — a password, a social account, a
+ * mailbox — is enough to reach a new device on its own. `device-code` and
+ * `passkey` are exempt because each already carried a second proof, and
+ * `register`, `signup-link`, `invitation` and `renewal` cannot apply (a
+ * brand-new account has nothing enrolled, and a renewal replaces a key on a
+ * device that is already signed in).
  */
-declare function renamePasskeyService(params: RenamePasskeyParams): Promise<{
-    passkeyId: string;
-    label: string;
-}>;
-interface RevokePasskeyParams {
-    userId: number;
-    keyId: string;
-    passkeyId: string;
-    currentPassword?: string;
-}
+declare const MFA_CHALLENGE_CHANNELS: readonly ["password", "oauth", "oauth-native", "password-reset"];
+type MfaChallengeChannel = typeof MFA_CHALLENGE_CHANNELS[number];
+/** How many wrong proofs a challenge survives before it is spent for good. */
+declare const MFA_CHALLENGE_ATTEMPT_LIMIT = 5;
 /**
- * Retire a passkey.
+ * The `authLoginEvent` payload this registration would have emitted.
  *
- * Gated on the second factor for an enrolled account, and then — for every
- * account, enrolled or not — 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.
+ * Carried rather than recomputed because it cannot be recomputed: the app's own
+ * `metadata` reached the sign-in in a sealed OAuth state or a request body that
+ * is gone by the time `verify` runs, and the provider is the social provider on
+ * the OAuth channels rather than anything the user row says. Null on
+ * `password-reset`, which announces a reset and never a login.
  *
- * 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.
+ * `mfaEnrolled` is not stored: the account is enrolled by construction — that is
+ * why there is a challenge — and re-reading it at verify keeps the payload
+ * honest if the second factor went away in between.
  */
-declare function revokePasskeyService(params: RevokePasskeyParams): Promise<{
-    passkeyId: string;
+interface DeferredLoginEvent {
+    provider: AuthLoginProvider;
+    email?: string;
+    phone?: string;
+    metadata?: Record<string, unknown>;
+}
+declare const mfaChallenges: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "mfa_challenges";
+    schema: string;
+    columns: {
+        createdAt: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>, {
+            name: string;
+            tableName: "mfa_challenges";
+            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<"mfa_challenges", drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>>, {
+            name: string;
+            tableName: "mfa_challenges";
+            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<"mfa_challenges", drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.PgBigSerial53Builder>, {
+            name: string;
+            tableName: "mfa_challenges";
+            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<"mfa_challenges", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgBigInt53Builder>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "number int53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        challengeHash: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        keyId: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        channel: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<["password", "oauth", "oauth-native", "password-reset"] & [string, ...string[]]>>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "string enum";
+            data: "password" | "oauth-native" | "oauth" | "password-reset";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["password", "oauth", "oauth-native", "password-reset"] & [string, ...string[]];
+            identity: undefined;
+            generated: undefined;
+        }>;
+        keyEpoch: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgIntegerBuilder>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "number int32";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        attempts: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgIntegerBuilder>>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "number int32";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        expiresAt: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTimestampBuilder>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        verifiedAt: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.PgTimestampBuilder, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        loginEvent: drizzle_orm_pg_core.PgBuildColumn<"mfa_challenges", drizzle_orm_pg_core.Set$Type<drizzle_orm_pg_core.PgJsonbBuilder, DeferredLoginEvent>, {
+            name: string;
+            tableName: "mfa_challenges";
+            dataType: "object json";
+            data: DeferredLoginEvent;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+    };
+    dialect: "pg";
 }>;
+type MfaChallenge = typeof mfaChallenges.$inferSelect;
+type NewMfaChallenge = typeof mfaChallenges.$inferInsert;
 
 /**
  * @spfn/auth - Second-Factor Verification Entity
@@ -1374,22 +1843,131 @@ interface AssertStepUpParams {
  * the passkey routes' `assertRecentAuthentication` — and they still run it
  * afterwards; this adds a rule for enrolled accounts rather than replacing one.
  *
- * The unenrolled path therefore costs one indexed lookup and touches no passkey
- * configuration, which is what lets an app with no passkeys at all call it.
+ * The unenrolled path therefore costs one indexed lookup and touches no passkey
+ * configuration, which is what lets an app with no passkeys at all call it.
+ *
+ * @throws StepUpRequiredError when the account is enrolled and the window has passed
+ */
+declare function assertStepUp(params: AssertStepUpParams): Promise<void>;
+/**
+ * Carry a device's verification onto the key that replaces it.
+ *
+ * Called from the two rotation seams — `rotateKeyService`, and the `oldKeyId`
+ * rotation every login path runs through `registerPublicKeyService`. Without
+ * it the window would expire silently on every rotation, which the web proxy
+ * does at each login: a user who stepped up a minute ago would be asked again
+ * with nothing to connect it to.
+ */
+declare function carryStepUpVerification(userId: number, fromKeyId: string, toKeyId: string): Promise<void>;
+interface OpenStepUpChallengeParams {
+    userId: number;
+    /** The inactive key this challenge would activate. */
+    keyId: string;
+    channel: MfaChallengeChannel;
+    /** The account's key generation right now — the challenge dies with it. */
+    keyEpoch: number;
+    /** The login announcement the 202 is holding back, when the channel has one. */
+    loginEvent?: DeferredLoginEvent;
+}
+/**
+ * Mint the challenge a stopped registration hands back.
+ *
+ * The secret is returned once and never stored: only its hash reaches the row,
+ * so a database dump does not yield a spendable challenge, and `verify` finds a
+ * row only for a caller who already had the secret. The row id is not in the
+ * answer at all — it is a sequence, and a sequence on an unauthenticated route
+ * is a thing an attacker walks.
+ */
+declare function openStepUpChallengeService(params: OpenStepUpChallengeParams): Promise<MfaChallengeHandle>;
+/**
+ * The challenge already outstanding for this key, re-secreted, or null.
+ *
+ * Registering the same keyId twice is an ordinary path, not a collision: a
+ * native client reuses its keyId, and an OAuth state replayed from the back
+ * button carries the one it was sealed with. Answering 409 there would refuse a
+ * caller for holding a key that is their own and is waiting on them.
+ *
+ * The row is reused rather than replaced, so the retry inherits the attempts
+ * already spent and the expiry already ticking — retrying is not a way around
+ * either. Only the secret is new, because the first one exists nowhere: the row
+ * holds its hash, and that is the property that keeps a database dump from
+ * yielding a spendable challenge.
+ */
+declare function resumeStepUpChallengeService(userId: number, keyId: string): Promise<MfaChallengeHandle | null>;
+interface VerifyMfaChallengeParams {
+    /** The secret from the 202 body, the callback query, or the pending page. */
+    challenge: string;
+    code?: string;
+    recoveryCode?: string;
+    response?: AuthenticationResponseJSON;
+}
+/**
+ * The sign-in the challenge was standing in for, plus what the proxy needs.
+ *
+ * `keyId` and `challengeHash` are for the Next.js interceptor and nothing else:
+ * it seals a session only when both match the pending cookie it baked at the
+ * 202, which is what stops a cookie minted for one flow from sealing a session
+ * around another flow's key. Neither is a credential — the hash is what the
+ * server already stores, and the key is inactive to anyone without the private
+ * half the proxy is holding.
+ */
+interface VerifyMfaChallengeResult extends LoginResult {
+    keyId: string;
+    challengeHash: string;
+}
+/**
+ * Spend a new-device challenge, which activates the key and starts the session.
+ *
+ * Unauthenticated by construction: the key this would activate is the only one
+ * the caller has and it cannot sign anything yet. The challenge secret is the
+ * whole credential, and it authorizes exactly this — no other route reads it.
+ *
+ * The verified mark is a conditional UPDATE, so two requests carrying the same
+ * secret produce one session and one 401. The key is activated only after that
+ * mark is won, which is what makes "a pending challenge never yields a usable
+ * key" true even under a race.
  *
- * @throws StepUpRequiredError when the account is enrolled and the window has passed
+ * The binding the answer carries was decided at **registration**, not here, and
+ * is read back off the key row. It has to be: the decision reads the owner's
+ * `session_binding` setting together with whether the request came through the
+ * trusted Next.js proxy, and this route is unauthenticated and may be called
+ * from anywhere — deciding it here would let a direct caller ask for a cookie
+ * that believes a bound key is an ordinary one. A bound account that steps up
+ * therefore gets exactly the binding and the expiry its sign-in registered, and
+ * the ten minutes a challenge may sit for come out of that key's short life.
+ *
+ * @throws ValidationError when the body names none or more than one proof
+ * @throws MfaVerificationFailedError for every other refusal, in one body
  */
-declare function assertStepUp(params: AssertStepUpParams): Promise<void>;
+declare function verifyMfaChallengeService(params: VerifyMfaChallengeParams): Promise<VerifyMfaChallengeResult>;
 /**
- * Carry a device's verification onto the key that replaces it.
+ * Options for finishing a new-device step-up with a passkey.
  *
- * Called from the two rotation seams — `rotateKeyService`, and the `oldKeyId`
- * rotation every login path runs through `registerPublicKeyService`. Without
- * it the window would expire silently on every rotation, which the web proxy
- * does at each login: a user who stepped up a minute ago would be asked again
- * with nothing to connect it to.
+ * The step-up challenge stands in for the session this caller does not have yet:
+ * it is what names the account, so the WebAuthn challenge can be minted for the
+ * right owner without the request having to say who that is. `allowCredentials`
+ * is empty for the reason it is everywhere else here (D3), and the ceremony kind
+ * is `'mfa'`, so what comes back cannot be spent as a sign-in.
+ *
+ * @throws MfaVerificationFailedError when the challenge cannot be spent
  */
-declare function carryStepUpVerification(userId: number, fromKeyId: string, toKeyId: string): Promise<void>;
+declare function startMfaChallengeAssertionService(challenge: string): Promise<PublicKeyCredentialRequestOptionsJSON>;
+/**
+ * Drop expired and spent challenges, and the keys they were holding.
+ *
+ * A pending key is unusable by construction, but it is still a key row on an
+ * account nobody is watching, and its challenge is what the owner would be shown
+ * if anything ever listed it. Both go once the challenge can no longer do
+ * anything. A spent one is kept for the same span as an expired one, so a replay
+ * inside the window is answered "already verified" from a row rather than
+ * "unknown" from an absence — the same 401 either way, but the record survives
+ * long enough to be read in a log.
+ *
+ * @returns number of challenge rows deleted
+ */
+declare function sweepMfaChallengesService(): Promise<{
+    deleted: number;
+}>;
 interface TotpEnrolmentResult {
     /** The base32 secret, shown once. Never logged, never returned again. */
     secret: string;
@@ -1484,333 +2062,75 @@ interface MfaStatus {
  * The account's second-factor state.
  *
  * Carries no secret, no otpauth URI and no recovery code — only the counts and
- * names an account screen needs. An unconfirmed enrolment is not a method: it
- * gates nothing, so reporting it would tell the owner they are protected when
- * they are not.
- */
-declare function mfaStatusService(userId: number): Promise<MfaStatus>;
-/**
- * Options for a step-up by passkey assertion.
- *
- * `allowCredentials` is empty, as it is for a sign-in and for the same reason
- * (D3): the discoverable credential on the device names itself, and the owner
- * and the second-factor mark are checked when the assertion comes back. The
- * challenge is minted with kind `'mfa'` and this account's id, so it cannot be
- * presented to `passkeys/login/verify` and a sign-in challenge cannot be
- * presented here.
- */
-declare function startStepUpService(userId: number): Promise<PublicKeyCredentialRequestOptionsJSON>;
-interface StepUpParams {
-    userId: number;
-    /** The device the verification is recorded against. */
-    keyId: string;
-    code?: string;
-    recoveryCode?: string;
-    response?: AuthenticationResponseJSON;
-}
-/**
- * Re-prove the second factor on this device, refreshing its window.
- *
- * The escape hatch the exempt registration channels need: a device-code
- * approval and a passkey sign-in register a key with no verification against
- * it, by design, so the session they create would otherwise fail every
- * sensitive change with no way forward.
- *
- * @throws ValidationError when the body names none or more than one input
- * @throws MfaNotEnrolledError | MfaVerificationFailedError
- */
-declare function stepUpService(params: StepUpParams): Promise<void>;
-/**
- * Check exactly one of the three proofs, and say which one it was.
- *
- * Exactly one: two inputs in a body is a caller trying combinations, and none
- * is a malformed request. Neither is a failed verification, so both are a 400
- * rather than the uniform 401 a wrong proof gets.
- *
- * @throws ValidationError | MfaVerificationFailedError
- */
-declare function verifySecondFactor(params: StepUpParams): Promise<MfaVerificationMethod>;
-/**
- * Drop enrolments nobody ever confirmed.
- *
- * A secret handed out and abandoned is a credential sitting in a table doing
- * nothing; a day is long enough for anyone who meant to finish.
- *
- * @returns number of rows deleted
- */
-declare function sweepUnconfirmedMfaService(): Promise<{
-    deleted: number;
-}>;
-
-/**
- * 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')
- *
- * `mfaEnrolled` is computed as the event is emitted (#95) and is the whole of
- * the package's opinion about the second factor: it never blocks an account
- * that has none, and this is the hook an app uses to offer enrolment at a first
- * login. It says nothing about *which* factor and carries no secret.
- *
- * @example
- * ```typescript
- * authLoginEvent.subscribe(async (payload) => {
- *     await analytics.trackLogin(payload.userId, payload.provider);
- *     if (!payload.mfaEnrolled) await suggestSecondFactor(payload.userId);
- * });
- * ```
- */
-declare const authLoginEvent: _spfn_core_event.EventDef<{
-    email?: string | undefined;
-    phone?: string | undefined;
-    userId: string;
-    provider: "email" | "phone" | "passkey" | "google" | "apple" | "github" | "kakao" | "naver" | "superself" | "device";
-    mfaEnrolled: boolean;
-}>;
-/**
- * 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">, _sinclair_typebox.TLiteral<"renewal">]>;
-/** The ten 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 ten 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.
- *
- * `mfaEnrolled` is computed as the event is emitted (#95), so a notice about a
- * new device can also be the moment an app offers a second factor to the
- * accounts that have none.
- *
- * @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;
-    mfaEnrolled: boolean;
-    channel: "password" | "register" | "passkey" | "oauth-native" | "renewal" | "oauth" | "invitation" | "signup-link" | "password-reset" | "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);
- * });
- * ```
+ * names an account screen needs. An unconfirmed enrolment is not a method: it
+ * gates nothing, so reporting it would tell the owner they are protected when
+ * they are not.
  */
-declare const authDeletionRequestedEvent: _spfn_core_event.EventDef<{
-    userId: string;
-    purgeScheduledAt: string;
-    userPublicId: string;
-    requestedBy: "admin" | "self";
-}>;
+declare function mfaStatusService(userId: number): Promise<MfaStatus>;
 /**
- * auth.deletion.cancelled - 계정 탈퇴 복구 이벤트
+ * Options for a step-up by passkey assertion.
  *
- * 발행 시점:
- * - cancelAccountDeletionService() 성공 시 (유예 기간 내 복구)
+ * `allowCredentials` is empty, as it is for a sign-in and for the same reason
+ * (D3): the discoverable credential on the device names itself, and the owner
+ * and the second-factor mark are checked when the assertion comes back. The
+ * challenge is minted with kind `'mfa'` and this account's id, so it cannot be
+ * presented to `passkeys/login/verify` and a sign-in challenge cannot be
+ * presented here.
  */
-declare const authDeletionCancelledEvent: _spfn_core_event.EventDef<{
-    userId: string;
-    userPublicId: string;
-}>;
+declare function startStepUpService(userId: number): Promise<PublicKeyCredentialRequestOptionsJSON>;
+interface StepUpParams {
+    userId: number;
+    /** The device the verification is recorded against. */
+    keyId: string;
+    code?: string;
+    recoveryCode?: string;
+    response?: AuthenticationResponseJSON;
+}
 /**
- * auth.deletion.completed - 계정 파기 완료 이벤트
+ * Re-prove the second factor on this device, refreshing its window.
  *
- * 발행 시점:
- * - purge job(또는 즉시 파기 경로)이 유저를 파기한 직후
+ * The escape hatch the exempt registration channels need: a device-code
+ * approval and a passkey sign-in register a key with no verification against
+ * it, by design, so the session they create would otherwise fail every
+ * sensitive change with no way forward.
  *
- * PII를 담지 않는다 — userId(내부 순번)/email/phone 없이 userPublicId만 실어
- * 파기 완료 이후에도 구독자가 식별 정보를 다시 축적하지 않도록 한다.
+ * @throws ValidationError when the body names none or more than one input
+ * @throws MfaNotEnrolledError | MfaVerificationFailedError
  */
-declare const authDeletionCompletedEvent: _spfn_core_event.EventDef<{
-    userPublicId: string;
-    purgeStrategy: "anonymize" | "hard-delete";
-}>;
+declare function stepUpService(params: StepUpParams): Promise<void>;
 /**
- * auth.oauth.unlinked - provider발 연동 해제 이벤트
+ * Check exactly one of the three proofs, and say which one it was — or null.
  *
- * 발행 시점:
- * - provider(카카오·네이버 등)가 unlink-notify 웹훅으로 연동 해제를 알려와
- *   소셜 계정 연결과 저장 토큰이 삭제된 직후
+ * Exactly one: two inputs in a body is a caller trying combinations, and none
+ * is a malformed request. Neither is a failed verification, so both are a 400
+ * rather than the uniform 401 a wrong proof gets.
  *
- * 연결 삭제까지는 프레임워크가 수행하고, 그 이후(계정 탈퇴로 이어갈지 등)는
- * 앱 정책이므로 이 이벤트를 구독해 처리한다.
+ * Null rather than a throw for the failure itself, because one caller has
+ * bookkeeping to do before it refuses: the new-device challenge counts the
+ * attempt, and counting it inside a `catch` around the thing that threw would be
+ * two control flows for one answer.
  *
- * @example
- * ```typescript
- * oauthUnlinkedEvent.subscribe(async (payload) => {
- *     await requestAccountDeletionService({ userId: payload.userId, requestedBy: 'self' });
- * });
- * ```
+ * @throws ValidationError when the body names none or more than one input
  */
-declare const oauthUnlinkedEvent: _spfn_core_event.EventDef<{
-    reason?: string | undefined;
-    userId: string;
-    provider: "email" | "phone" | "google" | "apple" | "github" | "kakao" | "naver" | "superself";
-    providerUserId: string;
-}>;
+declare function attemptSecondFactor(params: StepUpParams): Promise<MfaVerificationMethod | null>;
 /**
- * auth.password.reset — an account's password was replaced through a reset link
+ * `attemptSecondFactor`, for the callers whose only answer to a wrong proof is
+ * the uniform 401.
  *
- * 발행 시점:
- * - completePasswordResetService()가 커밋된 직후
+ * @throws ValidationError | MfaVerificationFailedError
+ */
+declare function verifySecondFactor(params: StepUpParams): Promise<MfaVerificationMethod>;
+/**
+ * Drop enrolments nobody ever confirmed.
  *
- * 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.
+ * A secret handed out and abandoned is a credential sitting in a table doing
+ * nothing; a day is long enough for anyone who meant to finish.
  *
- * @example
- * ```typescript
- * authPasswordResetEvent.subscribe(async (payload) => {
- *     await notifyOwner(payload.userId, 'Your password was reset');
- * });
- * ```
+ * @returns number of rows deleted
  */
-declare const authPasswordResetEvent: _spfn_core_event.EventDef<{
-    email: string;
-    userId: string;
+declare function sweepUnconfirmedMfaService(): Promise<{
+    deleted: number;
 }>;
-/**
- * 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
@@ -1859,7 +2179,40 @@ interface RegisterPublicKeyParams {
      * register a device with the owner's notice switched off.
      */
     replacesKeyId?: string;
+    /**
+     * What to announce if this registration is stopped and later verified (#95).
+     *
+     * Read only on a channel that can step up, and only when it does. The login
+     * event has to fire once and with the original channel's payload, and the
+     * app's own `metadata` and the social provider that carried it are gone by
+     * the time `POST /_auth/mfa/verify` runs — so the announcement rides the
+     * challenge row rather than being guessed at from the user row.
+     */
+    loginEvent?: DeferredLoginEvent;
 }
+/**
+ * What a registration settled on: a key, or a second factor still to prove.
+ *
+ * The `pending` branch is the 202 (#95). Its callers answer it to the client and
+ * stop — no session, no event, no `lastLoginAt` — and everything they would have
+ * done happens at `verify` instead.
+ */
+type RegisterPublicKeyResult = ({
+    pending: false;
+} & RegisteredKeyBinding) | {
+    pending: true;
+    challenge: MfaChallengeHandle;
+};
+/**
+ * The binding half of a registration that could not have been stepped up.
+ *
+ * Only four channels can answer `pending`, so a caller on any other one is
+ * reading a case its channel cannot reach. Throwing rather than defaulting is
+ * the honest answer if that ever stops being true: a silent `{}` would seal an
+ * unbound session for a key nobody had proved, which is the one outcome this
+ * whole feature exists to prevent.
+ */
+declare function registeredBinding(result: RegisterPublicKeyResult): RegisteredKeyBinding;
 interface RotateKeyParams {
     userId: number;
     oldKeyId: string;
@@ -1988,11 +2341,16 @@ interface RegisteredKeyBinding {
  * 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.
  *
+ * An enrolled account arriving on a new device gets the key written **inactive**
+ * and a challenge back (#95). Nothing else happens: no device event, no login
+ * event, no `lastLoginAt` — those are what the challenge is holding, and they
+ * fire at `POST /_auth/mfa/verify` or not at all.
+ *
  * @throws KeyIdAlreadyRegisteredError keyId가 이미 쓰인 값일 때 (자기 폐기 키 재사용 · 남의 키)
  * @throws InvalidKeyFingerprintError fingerprint가 publicKey와 맞지 않을 때
  * @throws KeyAlgorithmMismatchError 키의 SPKI 타입이 선언된 algorithm과 다를 때
  */
-declare function registerPublicKeyService(params: RegisterPublicKeyParams): Promise<RegisteredKeyBinding>;
+declare function registerPublicKeyService(params: RegisterPublicKeyParams): Promise<RegisterPublicKeyResult>;
 /**
  * Rotate user's public key (revoke old, register new)
  *
@@ -2358,6 +2716,15 @@ interface OAuthCallbackResult {
     userId: string;
     keyId: string;
     isNewUser: boolean;
+    /**
+     * The step-up challenge this callback is carrying, when it is carrying one.
+     *
+     * Present exactly when the redirect names `mfaChallenge` instead of
+     * `userId`/`keyId` (#95). Returned beside the URL so a caller that does not
+     * parse the query — a test, or an app mounting its own handler — can tell
+     * the two redirects apart.
+     */
+    mfaChallenge?: string;
 }
 /**
  * registry에서 provider를 찾아 사용 가능한지 검증 후 반환
@@ -2466,10 +2833,22 @@ interface OAuthNativeParams {
     };
     metadata?: Record<string, unknown>;
 }
+/**
+ * What a native social sign-in answers with.
+ *
+ * Shaped like `LoginResult` and for the same reason (#95): this channel steps up
+ * too, so the answer is one type carrying a required discriminant and optional
+ * fields rather than a union the typed client and the mobile contract could not
+ * both express. Narrow on `mfaRequired` before reading `userId`.
+ */
 interface OAuthNativeResult {
-    userId: string;
-    keyId: string;
-    isNewUser: boolean;
+    /** true means no key was activated: verify the challenge below first. */
+    mfaRequired: boolean;
+    /** Present exactly when `mfaRequired` is true. */
+    challenge?: MfaChallengeHandle;
+    userId?: string;
+    keyId?: string;
+    isNewUser?: boolean;
 }
 /**
  * native id_token 로그인 처리
@@ -2715,6 +3094,115 @@ declare function disableSessionBindingService(params: DisableSessionBindingParam
 /** The challenge the disabling ceremony signs. Same ceremony renewal uses. */
 declare function startSessionBindingDisableService(userId: number): Promise<PublicKeyCredentialRequestOptionsJSON>;
 
+/**
+ * @spfn/auth - Session Renewal Service
+ *
+ * What a bound session does when its key runs out: prove, with a fresh WebAuthn
+ * assertion, that the person who enrolled the passkey is still at the machine,
+ * and get a new short-lived key sealed into the cookie.
+ *
+ * Neither step is public. The expiring key is named by `expiredKeyId`, and that
+ * value reaches the service from `authenticateForRenewal` — the `keyId` of a
+ * bearer JWT this very key signed — rather than from the request body, so a
+ * caller who does not hold the private half cannot name a key at all. The
+ * assertion still has to be signed by a passkey that key's owner enrolled: the
+ * signature proves the cookie, and the cookie is the thing that may have been
+ * copied.
+ *
+ * The admission below is run again here all the same. The middleware and the
+ * service ask the same four questions of the row, and a service that trusted its
+ * caller to have asked them would be one refactor away from not being asked at
+ * all.
+ *
+ * Every refusal is the same refusal. A key that never existed, a stranger's key,
+ * an unbound key, a revoked one, one past its grace, an inactive account, a spent
+ * challenge, an assertion that did not verify — all `SessionRenewalRefusedError`,
+ * with the same body, because anything finer would answer "is this key id live"
+ * to whoever asked.
+ *
+ * Renewal announces nothing. No `auth.login`, no `auth.device.registered`, and
+ * `lastLoginAt` does not move: this is the same person on the same device
+ * continuing the session they already had, and a subscriber mailing "new sign-in"
+ * once a day per device would train its reader to ignore the notice that matters.
+ * A `lastLoginAt` that moved every day would make dormant-account detection
+ * meaningless for exactly the accounts that turned this protection on.
+ */
+
+interface StartSessionRenewParams {
+    /** The key that ran out, read off the JWT the request was signed with. */
+    expiredKeyId: string;
+}
+interface FinishSessionRenewParams extends StartSessionRenewParams {
+    /** The assertion, from `navigator.credentials.get()`. */
+    response: AuthenticationResponseJSON;
+    /**
+     * The new key pair, in the vocabulary the Next.js login interceptor already
+     * writes: `renew/verify` is on that interceptor's path list, so these arrive
+     * exactly as they do on a login.
+     */
+    keyId: string;
+    publicKey: string;
+    fingerprint: string;
+    algorithm?: KeyAlgorithmType;
+}
+/**
+ * What a completed renewal answers: a sign-in result, plus the new key's id.
+ *
+ * The id is the one thing a renewal has that a sign-in does not need to say —
+ * `renewSession()` promises it to the app, which has no other way to learn it
+ * (the key pair is minted in the proxy and the private half never leaves the
+ * cookie). It is not a contract operation, so nothing generated reads it.
+ */
+interface SessionRenewResult extends LoginResult {
+    /** The key this renewal registered, the one the session now signs with. */
+    keyId: string;
+}
+/**
+ * Step 1 — the challenge the authenticator signs.
+ *
+ * `allowCredentials` is empty and the account lives only on the challenge row.
+ * See `startRenewalCeremonyService`.
+ *
+ * @throws SessionRenewalRefusedError 갱신할 수 없는 키·계정일 때 (모든 사유 동일)
+ */
+declare function startSessionRenewService(params: StartSessionRenewParams): Promise<PublicKeyCredentialRequestOptionsJSON>;
+/**
+ * Step 2 — verify the assertion, put a new bound key in place of the old one.
+ *
+ * The revocation runs first and its answer is the race winner: two verifies that
+ * both got past their own challenges meet at the same conditional UPDATE, and
+ * only the one that actually revoked the key goes on to register a replacement.
+ *
+ * The new key inherits the old row's provenance, so the device list keeps saying
+ * where this device first appeared rather than re-stamping itself every day. Its
+ * expiry is a fresh window from now — renewal is a renewal, not an extension of
+ * what the old key had.
+ *
+ * @throws SessionRenewalRefusedError 갱신할 수 없을 때 (증명 실패 포함, 모든 사유 동일)
+ */
+declare function finishSessionRenewService(params: FinishSessionRenewParams): Promise<SessionRenewResult>;
+
+/**
+ * What `POST /_auth/oauth/finalize` answers with, in both of its branches.
+ *
+ * One type with a required discriminant rather than a union, on the same
+ * reasoning as `LoginResult` (#95): `authApi.oauthFinalize` infers its result
+ * from this, and a union would make every `result.userId` in every callback page
+ * stop compiling. `mfaRequired` false is the 200 and carries `userId`/`keyId`;
+ * true is the 202 and carries `challenge`.
+ */
+interface OAuthFinalizeResponse {
+    success: boolean;
+    mfaRequired: boolean;
+    /** The second-factor challenge, echoed back. Present exactly on the 202. */
+    challenge?: string;
+    userId?: string;
+    keyId?: string;
+    returnUrl: string;
+    sessionBinding?: SessionBindingType;
+    keyExpiresAtMillis?: number;
+}
+
 /**
  * @spfn/auth - Main Router
  *
@@ -2822,7 +3310,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
             deviceName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
             platform: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"ios" | "android" | "web" | "desktop">[]>>;
         }>;
-    }, RegisterResult & LoginBindingFields>;
+    }, LoginResult>;
     login: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{
             email: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
@@ -2863,6 +3351,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         sessionBinding?: "none" | "passkey" | undefined;
         keyExpiresAtMillis?: number | undefined;
         status: "approved";
+        mfaRequired: boolean;
         userId: string;
         publicId: string;
         passwordChangeRequired: boolean;
@@ -2966,6 +3455,19 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     mfaStepUpOptions: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{}>;
     }, {}, _simplewebauthn_server.PublicKeyCredentialRequestOptionsJSON>;
+    mfaVerify: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            challenge: _sinclair_typebox.TString;
+            code: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            recoveryCode: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            response: _sinclair_typebox.TOptional<_sinclair_typebox.TUnknown>;
+        }>;
+    }, {}, VerifyMfaChallengeResult>;
+    mfaVerifyOptions: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            challenge: _sinclair_typebox.TString;
+        }>;
+    }, {}, _simplewebauthn_server.PublicKeyCredentialRequestOptionsJSON>;
     logout: _spfn_core_route.RouteDef<{}, {}, void>;
     rotateKey: _spfn_core_route.RouteDef<{}, {
         body: _sinclair_typebox.TObject<{
@@ -3121,18 +3623,12 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }>;
     oauthFinalize: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{
-            userId: _sinclair_typebox.TString;
-            keyId: _sinclair_typebox.TString;
+            userId: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            keyId: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            mfaChallenge: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
             returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
         }>;
-    }, {}, {
-        sessionBinding?: SessionBindingType;
-        keyExpiresAtMillis?: number;
-        success: boolean;
-        userId: string;
-        keyId: string;
-        returnUrl: string;
-    }>;
+    }, {}, OAuthFinalizeResponse>;
     oauthProviderStart: _spfn_core_route.RouteDef<{
         params: _sinclair_typebox.TObject<{
             provider: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"google" | "apple" | "github" | "kakao" | "naver" | "superself">[]>;
@@ -3830,6 +4326,21 @@ declare const userPublicKeys: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }>;
+        pendingMfaChallengeId: drizzle_orm_pg_core.PgBuildColumn<"user_public_keys", drizzle_orm_pg_core.PgBigInt53Builder, {
+            name: string;
+            tableName: "user_public_keys";
+            dataType: "number int53";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
         createdAt: drizzle_orm_pg_core.PgBuildColumn<"user_public_keys", drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTimestampBuilder>>, {
             name: string;
             tableName: "user_public_keys";
@@ -4243,4 +4754,4 @@ declare const machineAuth: _spfn_core_route.NamedMiddleware<"machineAuth">;
  */
 declare const requireMachineScope: _spfn_core_route.NamedMiddlewareFactory<"machineScope", string[]>;
 
-export { type AuthLoginPayload as $, type AuthInitOptions as A, type Passkey as B, type ConfirmSignupLinkResult as C, type DeviceAuthInfoResult as D, type MfaVerification as E, type FinishPasskeyEnrollmentResult as F, type MfaVerificationMethod as G, type UserPublicKey as H, type IssueOneTimeTokenResult as I, type AuthContext as J, type KeySummary as K, type LoginBindingFields as L, type MfaStatus as M, type NewUserPublicKey as N, type OAuthStartResult as O, type PermissionConfig as P, type ApproveDeviceAuthParams as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type TotpEnrolmentResult as T, type UserProfile as U, VERIFICATION_PURPOSES as V, type AssertStepUpParams as W, type AuthDeletionCancelledPayload as X, type AuthDeletionCompletedPayload as Y, type AuthDeletionRequestedPayload as Z, type AuthDeviceRegisteredPayload as _, type RegisterResult as a, type RevokeAllKeysParams as a$, type AuthPasswordResetPayload as a0, type AuthProfileOutcome as a1, type AuthProfileVerifier as a2, AuthProviderSchema as a3, type AuthRegisterPayload as a4, type BearerOutcome as a5, type BearerRefusal as a6, type ChangePasswordParams as a7, type CompletePasswordResetParams as a8, type CompleteSignupParams as a9, type NativeVerifyOptions as aA, type NewMfaVerification as aB, type NormalizedIdentity as aC, type OAuth2AuthorizeParams as aD, type OAuth2ScopeDescription as aE, type OAuthCallbackParams as aF, type OAuthCallbackResult as aG, type OAuthCodeExchangeOptions as aH, type OAuthNativeParams as aI, type OAuthStartParams as aJ, type OAuthTokens as aK, type OAuthUnlinkedPayload as aL, PASSKEY_DEVICE_TYPES as aM, PASSKEY_LABEL_MAX_LENGTH as aN, type PasskeyDeviceType as aO, PasswordSchema as aP, PhoneSchema as aQ, PlatformSchema as aR, type PollDeviceAuthParams as aS, type PollDeviceAuthResult as aT, PublicKeySchema as aU, type RecentAuthenticationParams as aV, type RegisterParams as aW, type RegisterPublicKeyParams as aX, type RenamePasskeyParams as aY, type RequestPasswordResetParams as aZ, type RequestSignupLinkParams as a_, type ConfirmPasswordResetParams as aa, type ConfirmSignupLinkParams as ab, type ConfirmTotpParams as ac, type DenyDeviceAuthParams as ad, type DeviceAuthApprovedResult as ae, type DeviceAuthInfoParams as af, type DeviceAuthPendingResult as ag, DeviceAuthPollResponseSchema as ah, DeviceNameSchema as ai, type DeviceRegistrationChannel as aj, type DisableSessionBindingParams as ak, EmailSchema as al, FingerprintSchema as am, type FinishPasskeyEnrollmentParams as an, type FinishPasskeyLoginParams as ao, type FinishSessionRenewParams as ap, type InvitationAcceptedPayload as aq, type InvitationCreatedPayload as ar, KEY_FINGERPRINT_PREFIX_LENGTH as as, KeyIdSchema as at, type LoginParams as au, type LogoutParams as av, MFA_VERIFICATION_METHODS as aw, type MachinePrincipal as ax, type MachineVerifierRegistration as ay, type MarkPasskeyParams as az, type RequestSignupLinkResult as b, listOAuth2GrantsService as b$, type RevokeKeyParams as b0, type RevokePasskeyParams as b1, type RotateKeyParams as b2, type SendVerificationCodeParams as b3, type SessionBindingParams as b4, type StartDeviceAuthParams as b5, type StartPasskeyEnrollmentParams as b6, type StartSessionRenewParams as b7, type StepUpParams as b8, TargetTypeSchema as b9, completePasswordResetService as bA, completeSignupService as bB, confirmPasswordResetService as bC, confirmSignupLinkService as bD, confirmTotpEnrolmentService as bE, denyDeviceAuthService as bF, denyOAuth2AuthorizeService as bG, describeOAuth2AuthorizeRequestService as bH, disableMfaService as bI, disableSessionBindingService as bJ, enableSessionBindingService as bK, finishPasskeyEnrollmentService as bL, finishPasskeyLoginService as bM, finishSessionRenewService as bN, getDeviceAuthInfoService as bO, getEnabledOAuthProviders as bP, getGoogleAccessToken as bQ, getMachinePrincipal as bR, getOAuthProvider as bS, getRegisteredProviders as bT, getSessionBindingService as bU, invitationAcceptedEvent as bV, invitationCreatedEvent as bW, isOAuthProviderEnabled as bX, issueOneTimeTokenService as bY, keySessionBindingService as bZ, listKeysService as b_, type UnlinkNotification as ba, UnlinkNotifyRejection as bb, type UnlinkNotifyRequest as bc, type UnlinkNotifyResult as bd, UserCodeSchema as be, VerificationPurposeSchema as bf, type VerifyCodeParams as bg, type VerifyCodeResult as bh, admitBearerKey as bi, approveDeviceAuthService as bj, approveOAuth2AuthorizeService as bk, assertNotLastRecoveryCredential as bl, assertRecentAuthentication as bm, assertStepUp as bn, authDeletionCancelledEvent as bo, authDeletionCompletedEvent as bp, authDeletionRequestedEvent as bq, authDeviceRegisteredEvent as br, authLoginEvent as bs, authPasswordResetEvent as bt, authRegisterEvent as bu, authenticate as bv, bearerAuthContext as bw, buildOAuthErrorUrl as bx, carryStepUpVerification as by, changePasswordService as bz, type RequestPasswordResetResult as c, listPasskeysService as c0, loginService as c1, logoutService as c2, machineAuth as c3, markPasskeySecondFactorService as c4, mfaEnrolledForUser as c5, mfaStatusService as c6, mfaVerifications as c7, oauthCallbackService as c8, oauthNativeService as c9, sendVerificationCodeService as cA, startDeviceAuthService as cB, startPasskeyEnrollmentService as cC, startPasskeyLoginService as cD, startSessionBindingDisableService as cE, startSessionRenewService as cF, startStepUpService as cG, startTotpEnrolmentService as cH, stepUpService as cI, sweepUnconfirmedMfaService as cJ, userPublicKeys as cK, verifyCodeService as cL, verifyOneTimeTokenService as cM, verifySecondFactor as cN, oauthStartService as ca, oauthUnlinkNotifyService as cb, oauthUnlinkedEvent as cc, optionalAuth as cd, passkeys as ce, pollDeviceAuthService as cf, regenerateRecoveryCodesService as cg, registerAuthProfile as ch, registerMachineVerifier as ci, registerOAuthProvider as cj, registerPublicKeyService as ck, registerService as cl, renamePasskeyService as cm, requestPasswordResetService as cn, requestSignupLinkService as co, requireEnabledProvider as cp, requireMachineScope as cq, resolveAuthenticatedUser as cr, revokeAllKeysService as cs, revokeAllOAuth2GrantsForUser as ct, revokeKeyService as cu, revokeOAuth2GrantService as cv, revokePasskeyService as cw, rotateKeyService as cx, runAuthProfile as cy, selectAuthProfile as cz, type ConfirmPasswordResetResult as d, type LoginResult as e, type StartDeviceAuthResult as f, type PasskeySummary as g, type ConfirmTotpResult as h, type RotateKeyResult as i, type RevokeAllKeysResult as j, type SessionBindingResult as k, type SessionRenewResult as l, mainAuthRouter as m, type OAuthNativeResult as n, type ProfileInfo as o, type OAuth2ConsentView as p, type OAuth2AuthorizationCodeIssued as q, type OAuth2GrantSummary as r, type AuthSession as s, PERMISSION_CATEGORIES as t, type PermissionCategory as u, VERIFICATION_TARGET_TYPES as v, type VerificationPurpose as w, type VerificationTargetType as x, type OAuthProvider as y, type NewPasskey as z };
+export { type AuthDeletionCompletedPayload as $, type AuthInitOptions as A, type NewPasskey as B, type ConfirmSignupLinkResult as C, type DeviceAuthInfoResult as D, type Passkey as E, type FinishPasskeyEnrollmentResult as F, type MfaVerification as G, type MfaVerificationMethod as H, type IssueOneTimeTokenResult as I, type NewMfaChallenge as J, type KeySummary as K, type LoginResult as L, type MfaStatus as M, type NewUserPublicKey as N, type OAuthStartResult as O, type PermissionConfig as P, type MfaChallenge as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type TotpEnrolmentResult as T, type UserProfile as U, type VerifyMfaChallengeResult as V, type UserPublicKey as W, type AuthContext as X, type ApproveDeviceAuthParams as Y, type AssertStepUpParams as Z, type AuthDeletionCancelledPayload as _, type RegisterResult as a, type PollDeviceAuthParams as a$, type AuthDeletionRequestedPayload as a0, type AuthDeviceRegisteredPayload as a1, type AuthLoginPayload as a2, type AuthPasswordResetPayload as a3, type AuthProfileOutcome as a4, type AuthProfileVerifier as a5, AuthProviderSchema as a6, type AuthRegisterPayload as a7, type BearerOutcome as a8, type BearerRefusal as a9, MFA_CHALLENGE_ATTEMPT_LIMIT as aA, MFA_CHALLENGE_CHANNELS as aB, MFA_VERIFICATION_METHODS as aC, type MachinePrincipal as aD, type MachineVerifierRegistration as aE, type MarkPasskeyParams as aF, type MfaChallengeChannel as aG, type MfaChallengeHandle as aH, type NativeVerifyOptions as aI, type NewMfaVerification as aJ, type NormalizedIdentity as aK, type OAuth2AuthorizeParams as aL, type OAuth2ScopeDescription as aM, type OAuthCallbackParams as aN, type OAuthCallbackResult as aO, type OAuthCodeExchangeOptions as aP, type OAuthNativeParams as aQ, type OAuthStartParams as aR, type OAuthTokens as aS, type OAuthUnlinkedPayload as aT, type OpenStepUpChallengeParams as aU, PASSKEY_DEVICE_TYPES as aV, PASSKEY_LABEL_MAX_LENGTH as aW, type PasskeyDeviceType as aX, PasswordSchema as aY, PhoneSchema as aZ, PlatformSchema as a_, type ChangePasswordParams as aa, type CompletePasswordResetParams as ab, type CompleteSignupParams as ac, type ConfirmPasswordResetParams as ad, type ConfirmSignupLinkParams as ae, type ConfirmTotpParams as af, type DeferredLoginEvent as ag, type DenyDeviceAuthParams as ah, type DeviceAuthApprovedResult as ai, type DeviceAuthInfoParams as aj, type DeviceAuthPendingResult as ak, DeviceAuthPollResponseSchema as al, DeviceNameSchema as am, type DeviceRegistrationChannel as an, type DisableSessionBindingParams as ao, EmailSchema as ap, FingerprintSchema as aq, type FinishPasskeyEnrollmentParams as ar, type FinishPasskeyLoginParams as as, type FinishSessionRenewParams as at, type InvitationAcceptedPayload as au, type InvitationCreatedPayload as av, KEY_FINGERPRINT_PREFIX_LENGTH as aw, KeyIdSchema as ax, type LoginParams as ay, type LogoutParams as az, type RequestSignupLinkResult as b, getEnabledOAuthProviders as b$, type PollDeviceAuthResult as b0, PublicKeySchema as b1, type RecentAuthenticationParams as b2, type RegisterParams as b3, type RegisterPublicKeyParams as b4, type RegisterPublicKeyResult as b5, type RenamePasskeyParams as b6, type RequestPasswordResetParams as b7, type RequestSignupLinkParams as b8, type RevokeAllKeysParams as b9, authDeletionCancelledEvent as bA, authDeletionCompletedEvent as bB, authDeletionRequestedEvent as bC, authDeviceRegisteredEvent as bD, authLoginEvent as bE, authPasswordResetEvent as bF, authRegisterEvent as bG, authenticate as bH, bearerAuthContext as bI, buildOAuthErrorUrl as bJ, carryStepUpVerification as bK, changePasswordService as bL, completePasswordResetService as bM, completeSignupService as bN, confirmPasswordResetService as bO, confirmSignupLinkService as bP, confirmTotpEnrolmentService as bQ, denyDeviceAuthService as bR, denyOAuth2AuthorizeService as bS, describeOAuth2AuthorizeRequestService as bT, disableMfaService as bU, disableSessionBindingService as bV, enableSessionBindingService as bW, finishPasskeyEnrollmentService as bX, finishPasskeyLoginService as bY, finishSessionRenewService as bZ, getDeviceAuthInfoService as b_, type RevokeKeyParams as ba, type RevokePasskeyParams as bb, type RotateKeyParams as bc, type SendVerificationCodeParams as bd, type SessionBindingParams as be, type StartDeviceAuthParams as bf, type StartPasskeyEnrollmentParams as bg, type StartSessionRenewParams as bh, type StepUpParams as bi, TargetTypeSchema as bj, type UnlinkNotification as bk, UnlinkNotifyRejection as bl, type UnlinkNotifyRequest as bm, type UnlinkNotifyResult as bn, UserCodeSchema as bo, VerificationPurposeSchema as bp, type VerifyCodeParams as bq, type VerifyCodeResult as br, type VerifyMfaChallengeParams as bs, admitBearerKey as bt, approveDeviceAuthService as bu, approveOAuth2AuthorizeService as bv, assertNotLastRecoveryCredential as bw, assertRecentAuthentication as bx, assertStepUp as by, attemptSecondFactor as bz, type RequestPasswordResetResult as c, sweepUnconfirmedMfaService as c$, getGoogleAccessToken as c0, getMachinePrincipal as c1, getOAuthProvider as c2, getRegisteredProviders as c3, getSessionBindingService as c4, invitationAcceptedEvent as c5, invitationCreatedEvent as c6, isOAuthProviderEnabled as c7, issueOneTimeTokenService as c8, keySessionBindingService as c9, registeredBinding as cA, renamePasskeyService as cB, requestPasswordResetService as cC, requestSignupLinkService as cD, requireEnabledProvider as cE, requireMachineScope as cF, resolveAuthenticatedUser as cG, resumeStepUpChallengeService as cH, revokeAllKeysService as cI, revokeAllOAuth2GrantsForUser as cJ, revokeKeyService as cK, revokeOAuth2GrantService as cL, revokePasskeyService as cM, rotateKeyService as cN, runAuthProfile as cO, selectAuthProfile as cP, sendVerificationCodeService as cQ, startDeviceAuthService as cR, startMfaChallengeAssertionService as cS, startPasskeyEnrollmentService as cT, startPasskeyLoginService as cU, startSessionBindingDisableService as cV, startSessionRenewService as cW, startStepUpService as cX, startTotpEnrolmentService as cY, stepUpService as cZ, sweepMfaChallengesService as c_, listKeysService as ca, listOAuth2GrantsService as cb, listPasskeysService as cc, loginService as cd, logoutService as ce, machineAuth as cf, markPasskeySecondFactorService as cg, mfaChallenges as ch, mfaEnrolledForUser as ci, mfaStatusService as cj, mfaVerifications as ck, oauthCallbackService as cl, oauthNativeService as cm, oauthStartService as cn, oauthUnlinkNotifyService as co, oauthUnlinkedEvent as cp, openStepUpChallengeService as cq, optionalAuth as cr, passkeys as cs, pollDeviceAuthService as ct, regenerateRecoveryCodesService as cu, registerAuthProfile as cv, registerMachineVerifier as cw, registerOAuthProvider as cx, registerPublicKeyService as cy, registerService as cz, type ConfirmPasswordResetResult as d, userPublicKeys as d0, verifyCodeService as d1, verifyMfaChallengeService as d2, verifyOneTimeTokenService as d3, verifySecondFactor as d4, type StartDeviceAuthResult as e, type PasskeySummary as f, type ConfirmTotpResult as g, type RotateKeyResult as h, type RevokeAllKeysResult as i, type SessionBindingResult as j, type SessionRenewResult as k, type OAuthFinalizeResponse as l, mainAuthRouter as m, type OAuthNativeResult as n, type ProfileInfo as o, type OAuth2ConsentView as p, type OAuth2AuthorizationCodeIssued as q, type OAuth2GrantSummary as r, type AuthSession as s, PERMISSION_CATEGORIES as t, type PermissionCategory as u, VERIFICATION_PURPOSES as v, VERIFICATION_TARGET_TYPES as w, type VerificationPurpose as x, type VerificationTargetType as y, type OAuthProvider as z };