@udibo/oauth2 0.1.0

package/esm/identity/mfa/mod.d.ts

@@ -0,0 +1,42 @@
+/**
+ * MFA primitives for apps that own their login: TOTP (RFC 6238) and single-use
+ * recovery codes, plus a small orchestrator over an app-owned store — the same
+ * thin-seam philosophy as the rest of the identity layer. Built entirely on
+ * Web Crypto and `@std`; no other dependencies.
+ *
+ * - {@link generateTotpSecret} / {@link buildOtpauthUri} /
+ *   {@link generateTotpCode} / {@link verifyTotpCode} — the TOTP math, with a
+ *   constant-time verify that reports the matched time step for replay
+ *   rejection.
+ * - {@link generateRecoveryCodes} / {@link hashRecoveryCode} /
+ *   {@link verifyRecoveryCode} — readable single-use fallback codes, hashed at
+ *   rest.
+ * - {@link MfaService} over an app-implemented {@link MfaStore} — enrollment
+ *   (pending → confirmed), verification with atomic replay and burn handling,
+ *   regeneration, disable, plus the layer's usual seams (`rateLimiter`,
+ *   `onEvent` for `mfa.*` audit events). {@link MemoryMfaStore} ships for
+ *   dev/tests.
+ *
+ * The library stops at the primitives: whether MFA is optional or required,
+ * where challenges happen, and sessions are the app's policy and belong in
+ * its routes.
+ *
+ * @example Wire MFA into an app
+ * ```ts
+ * import { MemoryMfaStore, MfaService } from "@udibo/oauth2/identity/mfa";
+ *
+ * const mfa = new MfaService({ store: new MemoryMfaStore() });
+ * const { otpauthUri } = await mfa.startEnrollment(user.id, {
+ *   issuer: "Example",
+ *   accountName: user.email,
+ * });
+ * // render otpauthUri as a QR, then:
+ * const confirmation = await mfa.confirmEnrollment(user.id, submittedCode);
+ * ```
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { buildOtpauthUri, decodeTotpSecret, type GeneratedTotpSecret, generateTotpCode, type GenerateTotpCodeOptions, generateTotpSecret, type OtpauthUriOptions, type TotpAlgorithm, type TotpVerification, verifyTotpCode, type VerifyTotpCodeOptions, } from "./totp.js";
+export { type GeneratedRecoveryCodes, generateRecoveryCodes, type GenerateRecoveryCodesOptions, hashRecoveryCode, normalizeRecoveryCode, RECOVERY_CODE_LENGTH, type RecoveryCodeVerification, verifyRecoveryCode, type VerifyRecoveryCodeOptions, } from "./recovery-codes.js";
+export { MemoryMfaStore, type MfaEnrollmentConfirmation, type MfaEnrollmentStart, type MfaEnrollmentStatus, MfaService, type MfaServiceOptions, type MfaStore, type MfaTotpOptions, type MfaTotpRecord, type MfaVerification, type MfaVerifyFailureReason, type MfaVerifyOptions, type StartEnrollmentOptions, } from "./service.js";

package/esm/identity/mfa/mod.js

@@ -0,0 +1,42 @@
+/**
+ * MFA primitives for apps that own their login: TOTP (RFC 6238) and single-use
+ * recovery codes, plus a small orchestrator over an app-owned store — the same
+ * thin-seam philosophy as the rest of the identity layer. Built entirely on
+ * Web Crypto and `@std`; no other dependencies.
+ *
+ * - {@link generateTotpSecret} / {@link buildOtpauthUri} /
+ *   {@link generateTotpCode} / {@link verifyTotpCode} — the TOTP math, with a
+ *   constant-time verify that reports the matched time step for replay
+ *   rejection.
+ * - {@link generateRecoveryCodes} / {@link hashRecoveryCode} /
+ *   {@link verifyRecoveryCode} — readable single-use fallback codes, hashed at
+ *   rest.
+ * - {@link MfaService} over an app-implemented {@link MfaStore} — enrollment
+ *   (pending → confirmed), verification with atomic replay and burn handling,
+ *   regeneration, disable, plus the layer's usual seams (`rateLimiter`,
+ *   `onEvent` for `mfa.*` audit events). {@link MemoryMfaStore} ships for
+ *   dev/tests.
+ *
+ * The library stops at the primitives: whether MFA is optional or required,
+ * where challenges happen, and sessions are the app's policy and belong in
+ * its routes.
+ *
+ * @example Wire MFA into an app
+ * ```ts
+ * import { MemoryMfaStore, MfaService } from "@udibo/oauth2/identity/mfa";
+ *
+ * const mfa = new MfaService({ store: new MemoryMfaStore() });
+ * const { otpauthUri } = await mfa.startEnrollment(user.id, {
+ *   issuer: "Example",
+ *   accountName: user.email,
+ * });
+ * // render otpauthUri as a QR, then:
+ * const confirmation = await mfa.confirmEnrollment(user.id, submittedCode);
+ * ```
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { buildOtpauthUri, decodeTotpSecret, generateTotpCode, generateTotpSecret, verifyTotpCode, } from "./totp.js";
+export { generateRecoveryCodes, hashRecoveryCode, normalizeRecoveryCode, RECOVERY_CODE_LENGTH, verifyRecoveryCode, } from "./recovery-codes.js";
+export { MemoryMfaStore, MfaService, } from "./service.js";

package/esm/identity/mfa/recovery-codes.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Recovery-code primitives for MFA — the single-use fallback a user redeems
+ * when their authenticator is unavailable.
+ *
+ * Codes are generated from a Crockford-style alphabet (no `I`, `L`, `O`, or
+ * `U`, so nothing reads ambiguously off paper) as two 8-character groups —
+ * 80 bits of entropy per code. Only SHA-256 hashes are meant to be stored:
+ * at 80 bits an unsalted fast hash is sufficient — even a full offline
+ * keyspace sweep is infeasible, so a leaked hash table stays unbroken and the
+ * deterministic hash doubles as an exact-match storage key for atomic
+ * burn-on-use. Online guessing should be rate-limited like any credential.
+ * Verification is constant-time against every stored hash and reports which
+ * one matched so the app can delete ("burn") it — **single use is the app's
+ * storage responsibility**.
+ *
+ * @module
+ */
+/**
+ * The length of a normalized recovery code (separators stripped). A submitted
+ * value of any other length cannot be a recovery code, so callers can skip
+ * hashing and storage lookups for it.
+ */
+export declare const RECOVERY_CODE_LENGTH = 16;
+/**
+ * Normalize a recovery code to its canonical stored form: uppercase with
+ * separators (anything non-alphanumeric) stripped. Hashing and verification
+ * apply this automatically, so users can submit codes in any case and with or
+ * without the display hyphens.
+ */
+export declare function normalizeRecoveryCode(code: string): string;
+/**
+ * Hash a recovery code for storage: hex-encoded SHA-256 of the normalized
+ * code, the same stored-hash format the package's other high-entropy
+ * credentials use. Fast on purpose — see the module doc for why the code's
+ * entropy makes a slow hash unnecessary. Store only the hash; the plaintext
+ * code is shown to the user once at generation time.
+ */
+export declare function hashRecoveryCode(code: string): Promise<string>;
+/** Options for {@link generateRecoveryCodes}. */
+export interface GenerateRecoveryCodesOptions {
+    /** How many codes to generate. Defaults to `10`. */
+    count?: number;
+}
+/** A freshly generated recovery-code set (see {@link generateRecoveryCodes}). */
+export interface GeneratedRecoveryCodes {
+    /**
+     * The plaintext codes, e.g. `"4Q7MB2XW-9ZHT3KVR"`. Show them to the user
+     * exactly once; they are not recoverable afterwards.
+     */
+    codes: string[];
+    /**
+     * The hash of each code, index-aligned with `codes` — persist these (see
+     * {@link hashRecoveryCode}).
+     */
+    hashes: string[];
+}
+/**
+ * Generate a set of single-use recovery codes plus the hashes to store.
+ * Persist `hashes`, display `codes` once, and delete a hash when
+ * {@link verifyRecoveryCode} reports its index matched.
+ *
+ * @example Issue codes on MFA enrollment
+ * ```ts
+ * const { codes, hashes } = await generateRecoveryCodes();
+ * await store.setRecoveryHashes(user.id, hashes);
+ * // display `codes` to the user exactly once
+ * ```
+ */
+export declare function generateRecoveryCodes(options?: GenerateRecoveryCodesOptions): Promise<GeneratedRecoveryCodes>;
+/** Options for {@link verifyRecoveryCode}. */
+export interface VerifyRecoveryCodeOptions {
+    /** The code the user submitted (any case, separators optional). */
+    code: string;
+    /** The stored hashes for the user's unused codes. */
+    hashes: string[];
+}
+/** The outcome of {@link verifyRecoveryCode}. */
+export type RecoveryCodeVerification = {
+    valid: false;
+} | {
+    valid: true;
+    /**
+     * The index of the matching hash. Burn it with an atomic delete-by-value
+     * (a conditional `DELETE` on the hash, never read-filter-write) so the
+     * code cannot be redeemed again — the library does not do this for you at
+     * this level ({@link MfaService} does, atomically).
+     */
+    index: number;
+};
+/**
+ * Check a submitted recovery code against the stored hashes. Comparison is
+ * constant-time and every hash is checked even after a match, so timing does
+ * not reveal whether or where a match occurred. On success the caller must
+ * burn the matched hash (see {@link RecoveryCodeVerification}).
+ */
+export declare function verifyRecoveryCode(options: VerifyRecoveryCodeOptions): Promise<RecoveryCodeVerification>;

package/esm/identity/mfa/recovery-codes.js

@@ -0,0 +1,80 @@
+/**
+ * Recovery-code primitives for MFA — the single-use fallback a user redeems
+ * when their authenticator is unavailable.
+ *
+ * Codes are generated from a Crockford-style alphabet (no `I`, `L`, `O`, or
+ * `U`, so nothing reads ambiguously off paper) as two 8-character groups —
+ * 80 bits of entropy per code. Only SHA-256 hashes are meant to be stored:
+ * at 80 bits an unsalted fast hash is sufficient — even a full offline
+ * keyspace sweep is infeasible, so a leaked hash table stays unbroken and the
+ * deterministic hash doubles as an exact-match storage key for atomic
+ * burn-on-use. Online guessing should be rate-limited like any credential.
+ * Verification is constant-time against every stored hash and reports which
+ * one matched so the app can delete ("burn") it — **single use is the app's
+ * storage responsibility**.
+ *
+ * @module
+ */
+import { sha256Hash } from "../../server/utils/hash.js";
+import { timingSafeMatchIndex } from "../../utils/_timing-safe.js";
+const RECOVERY_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const DEFAULT_COUNT = 10;
+/**
+ * The length of a normalized recovery code (separators stripped). A submitted
+ * value of any other length cannot be a recovery code, so callers can skip
+ * hashing and storage lookups for it.
+ */
+export const RECOVERY_CODE_LENGTH = 16;
+/**
+ * Normalize a recovery code to its canonical stored form: uppercase with
+ * separators (anything non-alphanumeric) stripped. Hashing and verification
+ * apply this automatically, so users can submit codes in any case and with or
+ * without the display hyphens.
+ */
+export function normalizeRecoveryCode(code) {
+    return code.toUpperCase().replaceAll(/[^0-9A-Z]/g, "");
+}
+/**
+ * Hash a recovery code for storage: hex-encoded SHA-256 of the normalized
+ * code, the same stored-hash format the package's other high-entropy
+ * credentials use. Fast on purpose — see the module doc for why the code's
+ * entropy makes a slow hash unnecessary. Store only the hash; the plaintext
+ * code is shown to the user once at generation time.
+ */
+export function hashRecoveryCode(code) {
+    return sha256Hash(normalizeRecoveryCode(code));
+}
+/**
+ * Generate a set of single-use recovery codes plus the hashes to store.
+ * Persist `hashes`, display `codes` once, and delete a hash when
+ * {@link verifyRecoveryCode} reports its index matched.
+ *
+ * @example Issue codes on MFA enrollment
+ * ```ts
+ * const { codes, hashes } = await generateRecoveryCodes();
+ * await store.setRecoveryHashes(user.id, hashes);
+ * // display `codes` to the user exactly once
+ * ```
+ */
+export async function generateRecoveryCodes(options) {
+    const count = options?.count ?? DEFAULT_COUNT;
+    const bytes = crypto.getRandomValues(new Uint8Array(count * RECOVERY_CODE_LENGTH));
+    const codes = [];
+    for (let i = 0; i < count; i++) {
+        const raw = Array.from(bytes.subarray(i * RECOVERY_CODE_LENGTH, (i + 1) * RECOVERY_CODE_LENGTH), (byte) => RECOVERY_ALPHABET[byte % RECOVERY_ALPHABET.length]).join("");
+        codes.push(`${raw.slice(0, 8)}-${raw.slice(8)}`);
+    }
+    const hashes = await Promise.all(codes.map(hashRecoveryCode));
+    return { codes, hashes };
+}
+/**
+ * Check a submitted recovery code against the stored hashes. Comparison is
+ * constant-time and every hash is checked even after a match, so timing does
+ * not reveal whether or where a match occurred. On success the caller must
+ * burn the matched hash (see {@link RecoveryCodeVerification}).
+ */
+export async function verifyRecoveryCode(options) {
+    const submitted = await hashRecoveryCode(options.code);
+    const index = timingSafeMatchIndex(options.hashes, submitted);
+    return index === undefined ? { valid: false } : { valid: true, index };
+}

package/esm/identity/mfa/service.d.ts

@@ -0,0 +1,338 @@
+/**
+ * The MFA orchestrator: a small service that wires the TOTP and recovery-code
+ * primitives to an app-owned {@link MfaStore} — the same thin storage seam as
+ * every other layer here. It owns the lifecycle rules (pending vs. active
+ * secrets, TOTP replay rejection, recovery-code burning); the app owns the
+ * rows, the routes, and the policy for *when* MFA is required.
+ *
+ * @module
+ */
+import { type IdentityEventHook } from "../events.js";
+import { type RateLimiterLike } from "../rate-limit.js";
+import { type TotpAlgorithm } from "./totp.js";
+/**
+ * A user's TOTP state as the store persists it. `secretBase32` is a symmetric
+ * key — encrypt it at rest. A record may hold only a pending secret (enrollment
+ * started but unconfirmed) or only an active one.
+ */
+export interface MfaTotpRecord {
+    /** The active, confirmed secret. Absent until enrollment is confirmed. */
+    secretBase32?: string;
+    /**
+     * The highest time-step counter a code has been accepted for — the replay
+     * guard. Present whenever `secretBase32` is.
+     */
+    lastStep?: number;
+    /** A generated-but-unconfirmed secret awaiting {@link MfaService.confirmEnrollment}. */
+    pendingSecretBase32?: string;
+}
+/**
+ * App-owned persistence for {@link MfaService}, keyed by user id. Implement it
+ * over your database; {@link MemoryMfaStore} ships for dev and tests. The
+ * service never reads or writes anything else — encrypt `secretBase32` /
+ * `pendingSecretBase32` at rest however your app seals secrets (they are
+ * symmetric keys, not hashes).
+ *
+ * Three methods are the concurrency guards of the whole design and **must be
+ * atomic** in a real implementation (a conditional `UPDATE`/`DELETE`, not a
+ * read-then-write): {@link activateTotp}, {@link advanceLastStep}, and
+ * {@link consumeRecoveryHash}.
+ */
+export interface MfaStore {
+    /** Return the user's TOTP record, or `undefined` when none exists. */
+    getTotp(userId: string): Promise<MfaTotpRecord | undefined>;
+    /**
+     * Save a pending (unconfirmed) secret, preserving any active credential.
+     * A repeat call overwrites the previous pending secret.
+     */
+    setPendingTotp(userId: string, secretBase32: string): Promise<void>;
+    /**
+     * Atomically promote the pending secret to active — but only when the
+     * stored pending secret still equals `secretBase32` (the secret the
+     * confirmation code was verified against): set `secretBase32`, set
+     * `lastStep`, clear the pending value, and return `true`. Return `false`
+     * without changing anything when the pending secret is missing or has been
+     * replaced by a newer enrollment.
+     */
+    activateTotp(userId: string, secretBase32: string, lastStep: number): Promise<boolean>;
+    /** Delete the user's TOTP record entirely (active and pending). */
+    clearTotp(userId: string): Promise<void>;
+    /**
+     * Atomically advance the replay guard: persist `step` and return `true`
+     * only when it is greater than the stored `lastStep` (e.g.
+     * `UPDATE … SET last_step = $step WHERE last_step < $step`). Return `false`
+     * otherwise — a concurrent request already spent this step, so the caller
+     * treats the code as replayed.
+     */
+    advanceLastStep(userId: string, step: number): Promise<boolean>;
+    /** Return the user's unused recovery-code hashes (empty when none). */
+    getRecoveryHashes(userId: string): Promise<string[]>;
+    /**
+     * Replace the user's recovery-code hashes with exactly this set — used for
+     * initial issue, regeneration, and disable (`[]`).
+     */
+    setRecoveryHashes(userId: string, hashes: string[]): Promise<void>;
+    /**
+     * Atomically delete one stored hash and return whether it existed (e.g.
+     * `DELETE … WHERE user_id = $user AND hash = $hash` checking the row
+     * count). This is what makes a recovery code single-use under concurrent
+     * redemption — never implement it as read-filter-write.
+     */
+    consumeRecoveryHash(userId: string, hash: string): Promise<boolean>;
+}
+/** TOTP parameters an {@link MfaService} applies to every credential it manages. */
+export interface MfaTotpOptions {
+    /** Code length. Defaults to `6`. */
+    digits?: number;
+    /** Time-step length in seconds. Defaults to `30`. */
+    periodSeconds?: number;
+    /** HMAC hash. Defaults to `"SHA-1"` (see {@link TotpAlgorithm}). */
+    algorithm?: TotpAlgorithm;
+    /**
+     * Clock-skew windows accepted on each side of the current step during
+     * {@link MfaService.verify} and {@link MfaService.confirmEnrollment}.
+     * Defaults to `1`.
+     */
+    windows?: number;
+}
+/** Options for {@link MfaService}. */
+export interface MfaServiceOptions {
+    /** The app-owned persistence seam. */
+    store: MfaStore;
+    /**
+     * TOTP parameters. Set them once at construction — changing them later
+     * invalidates codes for already-enrolled authenticators.
+     */
+    totp?: MfaTotpOptions;
+    /** How many recovery codes to issue on confirm/regenerate. Defaults to `10`. */
+    recoveryCodeCount?: number;
+    /**
+     * Throttles {@link verify} per user id (a 6-digit code is brute-forceable
+     * without one). When the limit is hit the service emits
+     * `mfa.verify.rate_limited` and — under `protectionMode: "enforce"` —
+     * throws an `IdentityError` with code `rate_limited`. A successful
+     * verification resets the user's window, so legitimate sign-ins never
+     * accumulate toward a lockout.
+     */
+    rateLimiter?: RateLimiterLike;
+    /**
+     * `"enforce"` (default) applies the rate limit; `"log-only"` emits the
+     * event but lets the attempt through, for observing limits before turning
+     * them on.
+     */
+    protectionMode?: "enforce" | "log-only";
+    /** Receives `mfa.*` {@link IdentityEvent}s for audit capture. */
+    onEvent?: IdentityEventHook;
+}
+/** Options for {@link MfaService.startEnrollment}. */
+export interface StartEnrollmentOptions {
+    /** The service name shown in the authenticator app (e.g. `"Udibo"`). */
+    issuer: string;
+    /** The account label shown under the issuer (typically the user's email). */
+    accountName: string;
+}
+/** The result of {@link MfaService.startEnrollment}. */
+export interface MfaEnrollmentStart {
+    /** The pending secret in base32, for manual entry into an authenticator. */
+    base32: string;
+    /** The `otpauth://` URI to render as a QR code. */
+    otpauthUri: string;
+}
+/** The result of {@link MfaService.confirmEnrollment}. */
+export type MfaEnrollmentConfirmation = {
+    confirmed: false;
+} | {
+    confirmed: true;
+    /**
+     * The plaintext recovery codes. Display them to the user exactly once;
+     * only their hashes are stored.
+     */
+    recoveryCodes: string[];
+};
+/** Per-call options for {@link MfaService.verify} and {@link MfaService.confirmEnrollment}. */
+export interface MfaVerifyOptions {
+    /**
+     * Restrict which factor the code is checked against. Defaults to trying
+     * TOTP first, then recovery — pass `"totp"` when your UI has a dedicated
+     * recovery-code screen and the authenticator field must never silently burn
+     * a recovery code.
+     */
+    method?: "totp" | "recovery";
+    /** Epoch milliseconds to verify against. Defaults to `Date.now()`. */
+    timestamp?: number;
+}
+/**
+ * Why {@link MfaService.verify} rejected a code, on the invalid branch of
+ * {@link MfaVerification}. Mirrors the `reason` on the `mfa.verify.failed`
+ * event — same source of truth — so a caller need not subscribe to `onEvent`
+ * to tell the two apart:
+ *
+ * - `"replayed"` — a *valid* TOTP code whose time step was already spent. A
+ *   UI can say "that code was already used, wait for the next one"; it is also
+ *   the classic signal of an intercepted or reused code.
+ * - `"invalid"` — a wrong code, a non-recovery string, or a code submitted by
+ *   a user with no active credential (indistinguishable on purpose).
+ */
+export type MfaVerifyFailureReason = "invalid" | "replayed";
+/** The result of {@link MfaService.verify}. */
+export type MfaVerification = {
+    valid: false;
+    /** Why the code was rejected — see {@link MfaVerifyFailureReason}. */
+    reason: MfaVerifyFailureReason;
+} | {
+    valid: true;
+    method: "totp";
+} | {
+    valid: true;
+    method: "recovery";
+    /**
+     * How many unused recovery codes remain — surface it so the UI can
+     * prompt regeneration when low.
+     */
+    remainingRecoveryCodes: number;
+};
+/**
+ * A user's TOTP enrollment stage, as {@link MfaService.enrollmentStatus}
+ * reports it:
+ *
+ * - `"none"` — no credential and no enrollment in progress.
+ * - `"pending"` — {@link MfaService.startEnrollment} ran but
+ *   {@link MfaService.confirmEnrollment} has not; a secret is stored but does
+ *   not yet authenticate. An enrollment screen can resume instead of minting a
+ *   fresh secret (which would invalidate the one already in the authenticator).
+ * - `"active"` — a confirmed credential that {@link MfaService.verify} accepts.
+ */
+export type MfaEnrollmentStatus = "none" | "pending" | "active";
+/**
+ * Orchestrates TOTP enrollment, verification, and recovery codes over an
+ * app-owned {@link MfaStore}.
+ *
+ * Lifecycle: {@link startEnrollment} stores a *pending* secret (ignored by
+ * {@link verify}, so an unconfirmed enrollment can never lock a user out);
+ * {@link confirmEnrollment} proves the user's authenticator works, activates
+ * the secret, and issues recovery codes; {@link verify} accepts either a TOTP
+ * code (rejecting replays via the stored last step) or a recovery code
+ * (burning it on use). Replacing an active credential requires
+ * {@link disable} first — gate that route behind a fresh re-authentication,
+ * or a hijacked session could silently swap the user's authenticator.
+ * Deciding *when* to demand a code — sign-in policy, step-up, admin reset —
+ * is the app's job.
+ *
+ * @example Enroll, confirm, and verify
+ * ```ts
+ * const mfa = new MfaService({ store, rateLimiter });
+ * const { otpauthUri } = await mfa.startEnrollment(user.id, {
+ *   issuer: "Udibo", accountName: user.email,
+ * });
+ * // …render QR, user scans and submits a code…
+ * const confirmation = await mfa.confirmEnrollment(user.id, code);
+ * // …later, at sign-in…
+ * const result = await mfa.verify(user.id, submittedCode);
+ * ```
+ */
+export declare class MfaService {
+    #private;
+    /**
+     * Builds the service around an app-owned {@link MfaStore}.
+     *
+     * @throws {TypeError} on unusable configuration — non-positive-integer
+     * `digits`/`periodSeconds`/`recoveryCodeCount` or negative `windows` — so a
+     * miswired deploy fails at construction instead of silently rejecting every
+     * code an enrolled user submits.
+     */
+    constructor(options: MfaServiceOptions);
+    /**
+     * Begin TOTP enrollment: generates a fresh secret, stores it as *pending*,
+     * and returns what the enrollment screen needs. Repeating the call replaces
+     * the pending secret.
+     *
+     * @throws {IdentityError} `mfa_already_enrolled` when an active credential
+     * exists — replacing an authenticator requires {@link disable} first (behind
+     * re-authentication), so a stolen session cannot silently swap it.
+     */
+    startEnrollment(userId: string, options: StartEnrollmentOptions): Promise<MfaEnrollmentStart>;
+    /**
+     * Confirm enrollment by verifying a code against the *pending* secret. On
+     * success the secret becomes active, a fresh recovery-code set is generated
+     * and stored, and the plaintext codes are returned for one-time display.
+     * Returns `{ confirmed: false }` when the code is wrong, no enrollment is
+     * pending, or the pending secret changed under a concurrent enrollment. If
+     * storing the recovery codes fails after activation, the just-activated
+     * credential is rolled back and the error rethrown — a failure leaves the
+     * user *not* enrolled (free to retry), never enrolled without the recovery
+     * codes they were promised.
+     *
+     * @throws {IdentityError} `mfa_already_enrolled` when an active credential
+     * exists (see {@link startEnrollment}).
+     */
+    confirmEnrollment(userId: string, code: string, options?: Pick<MfaVerifyOptions, "timestamp">): Promise<MfaEnrollmentConfirmation>;
+    /**
+     * Verify a second-factor code: first as TOTP against the *active* secret
+     * (pending secrets are ignored — they need {@link confirmEnrollment}), then
+     * as a recovery code (restrict with {@link MfaVerifyOptions.method}). An
+     * accepted TOTP code atomically advances the stored last step, so the same
+     * code is rejected on replay even under concurrent submission; an accepted
+     * recovery code is atomically burned, so it is single-use. Without an
+     * active credential every code is rejected — recovery codes are a fallback
+     * *for* the enrolled factor, so stale hashes can never authenticate a user
+     * whose MFA was disabled. A successful verification resets the per-user
+     * rate-limit window. On failure the result carries a
+     * {@link MfaVerifyFailureReason} — `"replayed"` for a valid-but-spent TOTP
+     * code, `"invalid"` otherwise — so a caller can distinguish a reused code
+     * from a wrong one without subscribing to `onEvent`.
+     *
+     * @throws {IdentityError} `rate_limited` when a `rateLimiter` is configured,
+     * the per-user limit is hit, and `protectionMode` is `"enforce"`.
+     */
+    verify(userId: string, code: string, options?: MfaVerifyOptions): Promise<MfaVerification>;
+    /** Whether the user has an *active* (confirmed) TOTP credential. */
+    isEnrolled(userId: string): Promise<boolean>;
+    /**
+     * The user's TOTP enrollment stage — `"none"`, `"pending"`, or `"active"`
+     * (see {@link MfaEnrollmentStatus}). Unlike {@link isEnrolled}, this also
+     * reveals a started-but-unconfirmed enrollment, so an enrollment screen can
+     * resume a pending secret the user already scanned rather than calling
+     * {@link startEnrollment} again and invalidating it.
+     */
+    enrollmentStatus(userId: string): Promise<MfaEnrollmentStatus>;
+    /**
+     * Remove the user's MFA entirely: recovery codes first, then active and
+     * pending secrets — so a partial failure can only leave MFA still *on*,
+     * never a "disabled" account whose old recovery codes still authenticate.
+     * Gate the route that calls this behind a fresh re-authentication —
+     * disabling MFA is what an account takeover wants most.
+     */
+    disable(userId: string): Promise<void>;
+    /**
+     * Replace the user's recovery codes with a fresh set and return the
+     * plaintext for one-time display. All previously issued codes stop working.
+     *
+     * @throws {IdentityError} `mfa_not_enrolled` when the user has no active
+     * TOTP enrollment.
+     */
+    regenerateRecoveryCodes(userId: string): Promise<string[]>;
+}
+/**
+ * In-memory {@link MfaStore} for development and tests. State is lost on
+ * restart; back the contract with a database (secrets encrypted at rest,
+ * conditional writes for the atomic methods) for production.
+ */
+export declare class MemoryMfaStore implements MfaStore {
+    #private;
+    /** Return a copy of the user's TOTP record, or `undefined`. */
+    getTotp(userId: string): Promise<MfaTotpRecord | undefined>;
+    /** Store a pending secret, keeping any active credential. */
+    setPendingTotp(userId: string, secretBase32: string): Promise<void>;
+    /** Promote the matching pending secret to active; `false` when it changed. */
+    activateTotp(userId: string, secretBase32: string, lastStep: number): Promise<boolean>;
+    /** Delete the user's TOTP record. */
+    clearTotp(userId: string): Promise<void>;
+    /** Advance the replay guard only forward; `false` when the step was spent. */
+    advanceLastStep(userId: string, step: number): Promise<boolean>;
+    /** Return the user's stored recovery hashes (empty when none). */
+    getRecoveryHashes(userId: string): Promise<string[]>;
+    /** Replace the user's recovery hashes with exactly this set. */
+    setRecoveryHashes(userId: string, hashes: string[]): Promise<void>;
+    /** Delete one hash, reporting whether it was present. */
+    consumeRecoveryHash(userId: string, hash: string): Promise<boolean>;
+}