@shaferllc/keel 0.79.0 → 0.81.0

package/dist/accounts/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Where accounts reads and writes users.
+ *
+ * The module refuses to assume you use a `Model` — it talks to a table through
+ * the query builder, exactly like `billing` parameterizes its billable table. If
+ * your users live somewhere else entirely (an auth service, a legacy schema),
+ * replace the whole thing:
+ *
+ *   setAccountStore({ findById, findByEmail, update });
+ */
+import { type Row } from "../core/database.js";
+/** The columns accounts needs. Everything else on your users table is untouched. */
+export interface AccountUser extends Row {
+    id: string | number;
+    email: string;
+    /** The hashed password. Never the plaintext. */
+    password?: string | null;
+    email_verified_at?: string | null;
+    /** The TOTP secret, encrypted at rest. */
+    two_factor_secret?: string | null;
+    /** Hashed, single-use recovery codes, as a JSON array. */
+    two_factor_recovery_codes?: string | null;
+    two_factor_confirmed_at?: string | null;
+}
+export interface AccountStore {
+    findById(id: string | number): Promise<AccountUser | null>;
+    findByEmail(email: string): Promise<AccountUser | null>;
+    update(id: string | number, values: Row): Promise<void>;
+}
+/** The default store: a table, through the query builder. */
+export declare function tableStore(table: string): AccountStore;
+export declare function setAccountStore(next: AccountStore | undefined): void;
+export declare function accountStore(): AccountStore;

package/dist/accounts/store.js

@@ -0,0 +1,37 @@
+/**
+ * Where accounts reads and writes users.
+ *
+ * The module refuses to assume you use a `Model` — it talks to a table through
+ * the query builder, exactly like `billing` parameterizes its billable table. If
+ * your users live somewhere else entirely (an auth service, a legacy schema),
+ * replace the whole thing:
+ *
+ *   setAccountStore({ findById, findByEmail, update });
+ */
+import { db } from "../core/database.js";
+/** The default store: a table, through the query builder. */
+export function tableStore(table) {
+    return {
+        async findById(id) {
+            return (await db(table).where("id", id).first());
+        },
+        async findByEmail(email) {
+            // Emails are case-insensitive in practice; store them lowercased and look
+            // them up the same way, or "Ada@…" and "ada@…" become two accounts.
+            return (await db(table).where("email", email.toLowerCase()).first());
+        },
+        async update(id, values) {
+            await db(table).where("id", id).update(values);
+        },
+    };
+}
+let store;
+export function setAccountStore(next) {
+    store = next;
+}
+export function accountStore() {
+    if (!store) {
+        throw new Error("No account store. Register AccountsServiceProvider, or call setAccountStore().");
+    }
+    return store;
+}

package/dist/accounts/tokens.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The tokens behind password reset, email verification, and the 2FA challenge.
+ *
+ * There is no tokens table. Keel's `encryption` already carries a **purpose** and
+ * an **expiry inside the ciphertext**, and `decrypt` returns `null` — never throws
+ * — when either is wrong. So a token is self-describing: nothing to store, nothing
+ * to clean up, and no window where a stale row is still redeemable because a cron
+ * job didn't run.
+ *
+ * `purpose` is what stops a token minted for one thing being spent on another. A
+ * verification link cannot be replayed as a password reset, because it will not
+ * decrypt under that purpose. Every token here gets its own.
+ *
+ * The interesting problem is **single use**. A stateless token is, by nature,
+ * replayable until it expires — so a reset link sitting in an inbox (or a proxy
+ * log, or a browser history) would work twice. The fix is to bind the token to
+ * something that *changes when it's spent*: the user's current password hash. Once
+ * the password is reset, the hash is different, the fingerprint no longer matches,
+ * and every token minted against the old one is dead. Single use, no storage.
+ */
+import type { AccountUser } from "./store.js";
+export declare const PURPOSE: {
+    readonly passwordReset: "accounts:password-reset";
+    readonly emailVerification: "accounts:email-verification";
+    readonly twoFactorChallenge: "accounts:2fa-challenge";
+};
+/**
+ * A reset token for this user. Dies on use (the password changes, so the
+ * fingerprint stops matching) and dies on expiry, whichever comes first.
+ */
+export declare function passwordResetToken(user: AccountUser, expiresIn?: number | string): Promise<string>;
+/**
+ * The user this token resets, or `null` — expired, tampered with, minted for a
+ * different purpose, or already spent.
+ */
+export declare function verifyPasswordResetToken(token: string, find: (id: string | number) => Promise<AccountUser | null>): Promise<AccountUser | null>;
+export declare function emailVerificationToken(user: AccountUser, expiresIn?: number | string): Promise<string>;
+/**
+ * The user this token verifies, or `null`.
+ *
+ * The address is baked in, so a link sent to the old address cannot verify a new
+ * one — otherwise changing your email to someone else's and clicking an older link
+ * would mark *their* address as proven.
+ */
+export declare function verifyEmailToken(token: string, find: (id: string | number) => Promise<AccountUser | null>): Promise<AccountUser | null>;
+/**
+ * Proof that someone got the password right — and **nothing more**.
+ *
+ * This is deliberately not a session. The usual implementation logs the user in
+ * and sets a `needs_2fa` flag for middleware to check, which means they hold a
+ * real authenticated session before the second factor: every route that forgets
+ * the middleware, and every `auth()` that only asks "is anyone logged in?", is
+ * bypassable with just a password. Here, nothing is logged in until the code
+ * verifies, so there is no half-authenticated state to forget about.
+ *
+ * Short-lived on purpose: it is the window in which a stolen password is enough.
+ */
+export declare function twoFactorChallenge(user: AccountUser, expiresIn?: number | string): Promise<string>;
+/** Who this challenge is for, or `null` if it's expired, forged, or not a challenge. */
+export declare function verifyTwoFactorChallenge(token: string, find: (id: string | number) => Promise<AccountUser | null>): Promise<AccountUser | null>;

package/dist/accounts/tokens.js

@@ -0,0 +1,116 @@
+/**
+ * The tokens behind password reset, email verification, and the 2FA challenge.
+ *
+ * There is no tokens table. Keel's `encryption` already carries a **purpose** and
+ * an **expiry inside the ciphertext**, and `decrypt` returns `null` — never throws
+ * — when either is wrong. So a token is self-describing: nothing to store, nothing
+ * to clean up, and no window where a stale row is still redeemable because a cron
+ * job didn't run.
+ *
+ * `purpose` is what stops a token minted for one thing being spent on another. A
+ * verification link cannot be replayed as a password reset, because it will not
+ * decrypt under that purpose. Every token here gets its own.
+ *
+ * The interesting problem is **single use**. A stateless token is, by nature,
+ * replayable until it expires — so a reset link sitting in an inbox (or a proxy
+ * log, or a browser history) would work twice. The fix is to bind the token to
+ * something that *changes when it's spent*: the user's current password hash. Once
+ * the password is reset, the hash is different, the fingerprint no longer matches,
+ * and every token minted against the old one is dead. Single use, no storage.
+ */
+import { encryption } from "../core/crypto.js";
+export const PURPOSE = {
+    passwordReset: "accounts:password-reset",
+    emailVerification: "accounts:email-verification",
+    twoFactorChallenge: "accounts:2fa-challenge",
+};
+/**
+ * A reset token for this user. Dies on use (the password changes, so the
+ * fingerprint stops matching) and dies on expiry, whichever comes first.
+ */
+export async function passwordResetToken(user, expiresIn = "60m") {
+    const payload = { id: user.id, fp: await fingerprint(user.password) };
+    return encryption.encrypt(payload, { purpose: PURPOSE.passwordReset, expiresIn });
+}
+/**
+ * The user this token resets, or `null` — expired, tampered with, minted for a
+ * different purpose, or already spent.
+ */
+export async function verifyPasswordResetToken(token, find) {
+    const payload = await encryption.decrypt(token, {
+        purpose: PURPOSE.passwordReset,
+    });
+    if (!payload)
+        return null;
+    const user = await find(payload.id);
+    if (!user)
+        return null;
+    // The password has changed since this was minted — so the token has been spent,
+    // or the user reset it another way. Either way it is not valid twice.
+    if ((await fingerprint(user.password)) !== payload.fp)
+        return null;
+    return user;
+}
+export async function emailVerificationToken(user, expiresIn = "24h") {
+    const payload = { id: user.id, email: user.email.toLowerCase() };
+    return encryption.encrypt(payload, { purpose: PURPOSE.emailVerification, expiresIn });
+}
+/**
+ * The user this token verifies, or `null`.
+ *
+ * The address is baked in, so a link sent to the old address cannot verify a new
+ * one — otherwise changing your email to someone else's and clicking an older link
+ * would mark *their* address as proven.
+ */
+export async function verifyEmailToken(token, find) {
+    const payload = await encryption.decrypt(token, {
+        purpose: PURPOSE.emailVerification,
+    });
+    if (!payload)
+        return null;
+    const user = await find(payload.id);
+    if (!user)
+        return null;
+    if (user.email.toLowerCase() !== payload.email)
+        return null;
+    return user;
+}
+/**
+ * Proof that someone got the password right — and **nothing more**.
+ *
+ * This is deliberately not a session. The usual implementation logs the user in
+ * and sets a `needs_2fa` flag for middleware to check, which means they hold a
+ * real authenticated session before the second factor: every route that forgets
+ * the middleware, and every `auth()` that only asks "is anyone logged in?", is
+ * bypassable with just a password. Here, nothing is logged in until the code
+ * verifies, so there is no half-authenticated state to forget about.
+ *
+ * Short-lived on purpose: it is the window in which a stolen password is enough.
+ */
+export async function twoFactorChallenge(user, expiresIn = "5m") {
+    const payload = { id: user.id };
+    return encryption.encrypt(payload, { purpose: PURPOSE.twoFactorChallenge, expiresIn });
+}
+/** Who this challenge is for, or `null` if it's expired, forged, or not a challenge. */
+export async function verifyTwoFactorChallenge(token, find) {
+    const payload = await encryption.decrypt(token, {
+        purpose: PURPOSE.twoFactorChallenge,
+    });
+    if (!payload)
+        return null;
+    return find(payload.id);
+}
+/* --------------------------------- helpers -------------------------------- */
+/**
+ * A short digest of the stored password hash. Not a secret — it only ever travels
+ * inside an already-encrypted payload — it just has to *change* when the password
+ * does. A user with no password (social login) still gets a stable fingerprint.
+ */
+async function fingerprint(password) {
+    const bytes = new TextEncoder().encode(password ?? "");
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)]
+        .slice(0, 8)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/accounts/totp.d.ts

@@ -0,0 +1,58 @@
+/**
+ * TOTP (RFC 6238) — the authenticator-app second factor.
+ *
+ *   const secret = generateSecret();                  // base32, shown once
+ *   const uri = otpauthUri({ secret, account: "ada@example.com", issuer: "Acme" });
+ *   const ok = await verifyTotp(secret, "492039");
+ *
+ * Deliberately dependency-free and edge-safe: the whole thing is WebCrypto plus
+ * about thirty lines of base32, so it runs unchanged on Workers. TOTP wants
+ * HMAC-SHA1 — not a weakness here (the secret is 160 bits of CSPRNG and the code
+ * lives 30 seconds), and it's what every authenticator app implements.
+ */
+export declare function base32Encode(bytes: Uint8Array): string;
+export declare function base32Decode(input: string): Uint8Array;
+/** A new TOTP secret: 160 bits, base32-encoded. Show it once, store it encrypted. */
+export declare function generateSecret(bytes?: number): string;
+export interface TotpOptions {
+    /** Code length. 6 is what every authenticator app shows. */
+    digits?: number;
+    /** Seconds each code is valid for. */
+    period?: number;
+    /** Unix seconds; defaults to now. */
+    timestamp?: number;
+}
+/** The code for a secret at a moment in time. */
+export declare function totp(secret: string, options?: TotpOptions): Promise<string>;
+export interface VerifyOptions extends TotpOptions {
+    /**
+     * How many periods either side of now to accept. 1 (the default) tolerates a
+     * phone whose clock drifts by up to 30 seconds — which is common enough that 0
+     * generates support tickets, and large values just widen the guessing window.
+     */
+    window?: number;
+}
+/**
+ * Is this the code for that secret, right now?
+ *
+ * Compared in constant time, and every candidate in the window is checked even
+ * after a match, so the time this takes says nothing about which period matched.
+ */
+export declare function verifyTotp(secret: string, code: string, options?: VerifyOptions): Promise<boolean>;
+export interface OtpauthOptions {
+    secret: string;
+    /** Who the account belongs to — shown in the authenticator app. */
+    account: string;
+    /** Your app's name — shown above the account. */
+    issuer: string;
+    digits?: number;
+    period?: number;
+}
+/**
+ * The `otpauth://` URI an authenticator app scans.
+ *
+ * Render it to a QR code **yourself, locally**. Never post it to a QR-image
+ * service: the URI contains the shared secret, so a third-party URL hands your
+ * users' second factor to someone else.
+ */
+export declare function otpauthUri(options: OtpauthOptions): string;

package/dist/accounts/totp.js

@@ -0,0 +1,134 @@
+/**
+ * TOTP (RFC 6238) — the authenticator-app second factor.
+ *
+ *   const secret = generateSecret();                  // base32, shown once
+ *   const uri = otpauthUri({ secret, account: "ada@example.com", issuer: "Acme" });
+ *   const ok = await verifyTotp(secret, "492039");
+ *
+ * Deliberately dependency-free and edge-safe: the whole thing is WebCrypto plus
+ * about thirty lines of base32, so it runs unchanged on Workers. TOTP wants
+ * HMAC-SHA1 — not a weakness here (the secret is 160 bits of CSPRNG and the code
+ * lives 30 seconds), and it's what every authenticator app implements.
+ */
+/* --------------------------------- base32 --------------------------------- */
+// RFC 4648, upper-case, no padding — what authenticator apps expect in a URI.
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+export function base32Encode(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = "";
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    // Whatever's left, left-aligned in a final group.
+    if (bits > 0)
+        out += ALPHABET[(value << (5 - bits)) & 31];
+    return out;
+}
+export function base32Decode(input) {
+    // Users paste secrets by hand: tolerate spaces, lower case, and padding.
+    const clean = input.toUpperCase().replace(/=+$/, "").replace(/\s+/g, "");
+    let bits = 0;
+    let value = 0;
+    const out = [];
+    for (const char of clean) {
+        const index = ALPHABET.indexOf(char);
+        if (index === -1)
+            throw new Error(`"${char}" is not valid base32.`);
+        value = (value << 5) | index;
+        bits += 5;
+        if (bits >= 8) {
+            out.push((value >>> (bits - 8)) & 255);
+            bits -= 8;
+        }
+    }
+    return new Uint8Array(out);
+}
+/* --------------------------------- secrets -------------------------------- */
+/** A new TOTP secret: 160 bits, base32-encoded. Show it once, store it encrypted. */
+export function generateSecret(bytes = 20) {
+    return base32Encode(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+/* ---------------------------------- codes --------------------------------- */
+/** The code for a secret at a moment in time. */
+export async function totp(secret, options = {}) {
+    const digits = options.digits ?? 6;
+    const period = options.period ?? 30;
+    const now = options.timestamp ?? Math.floor(Date.now() / 1000);
+    const counter = Math.floor(now / period);
+    // The counter is a 64-bit big-endian integer. JS bitwise ops are 32-bit, so
+    // the halves are written separately rather than shifted.
+    const message = new Uint8Array(8);
+    new DataView(message.buffer).setUint32(0, Math.floor(counter / 2 ** 32), false);
+    new DataView(message.buffer).setUint32(4, counter >>> 0, false);
+    const key = await crypto.subtle.importKey("raw", base32Decode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, message));
+    // Dynamic truncation (RFC 4226 §5.3): the low nibble of the last byte picks
+    // which four bytes of the MAC become the code.
+    const offset = mac[mac.length - 1] & 0x0f;
+    const binary = ((mac[offset] & 0x7f) << 24) |
+        (mac[offset + 1] << 16) |
+        (mac[offset + 2] << 8) |
+        mac[offset + 3];
+    return String(binary % 10 ** digits).padStart(digits, "0");
+}
+/**
+ * Is this the code for that secret, right now?
+ *
+ * Compared in constant time, and every candidate in the window is checked even
+ * after a match, so the time this takes says nothing about which period matched.
+ */
+export async function verifyTotp(secret, code, options = {}) {
+    const digits = options.digits ?? 6;
+    const period = options.period ?? 30;
+    const window = options.window ?? 1;
+    const now = options.timestamp ?? Math.floor(Date.now() / 1000);
+    const supplied = code.replace(/\s+/g, "");
+    if (!new RegExp(`^\\d{${digits}}$`).test(supplied))
+        return false;
+    let matched = false;
+    for (let drift = -window; drift <= window; drift++) {
+        const candidate = await totp(secret, {
+            digits,
+            period,
+            timestamp: now + drift * period,
+        });
+        // No early return: the loop runs the same number of times either way.
+        if (timingSafeEqual(candidate, supplied))
+            matched = true;
+    }
+    return matched;
+}
+/**
+ * The `otpauth://` URI an authenticator app scans.
+ *
+ * Render it to a QR code **yourself, locally**. Never post it to a QR-image
+ * service: the URI contains the shared secret, so a third-party URL hands your
+ * users' second factor to someone else.
+ */
+export function otpauthUri(options) {
+    const label = `${options.issuer}:${options.account}`;
+    const params = new URLSearchParams({
+        secret: options.secret,
+        issuer: options.issuer,
+        algorithm: "SHA1",
+        digits: String(options.digits ?? 6),
+        period: String(options.period ?? 30),
+    });
+    return `otpauth://totp/${encodeURIComponent(label)}?${params.toString()}`;
+}
+/* --------------------------------- helpers -------------------------------- */
+/** Compare without leaking, through timing, how much of the code was right. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}

package/dist/accounts/two-factor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The two-factor lifecycle: enable, confirm, challenge, recover, disable.
+ *
+ * Enabling is **two steps on purpose**. `enableTwoFactor()` generates a secret and
+ * stores it, but leaves `two_factor_confirmed_at` null — 2FA is not on yet. Only
+ * `confirmTwoFactor()`, which requires a working code from the app, turns it on.
+ * A one-step "enable" locks out every user who scans the QR wrong, mistypes the
+ * secret, or has a phone whose clock is broken — and they cannot get back in,
+ * because getting back in is exactly what's broken.
+ *
+ * The secret is encrypted at rest with its own purpose, so a leaked database does
+ * not hand over everybody's second factor. Recovery codes are hashed, so a leaked
+ * database does not hand over the backdoor either.
+ */
+import { type AccountUser } from "./store.js";
+export interface TwoFactorSetup {
+    /** The plaintext secret. Show it once, for manual entry. */
+    secret: string;
+    /** Render this to a QR code **locally** — it contains the secret. */
+    uri: string;
+    /** Show these once. They are hashed the moment they're stored. */
+    recoveryCodes: string[];
+}
+export interface TwoFactorOptions {
+    /** The name shown in the authenticator app. */
+    issuer?: string;
+    /** How many recovery codes to mint. */
+    recoveryCodes?: number;
+    window?: number;
+}
+/** Is two-factor actually on for this user — confirmed, not merely started? */
+export declare function hasTwoFactor(user: AccountUser): boolean;
+/**
+ * Step one: mint a secret and recovery codes, and store them — but do **not** turn
+ * 2FA on. The user has not proved they can generate a code yet.
+ */
+export declare function enableTwoFactor(user: AccountUser, options?: TwoFactorOptions): Promise<TwoFactorSetup>;
+/**
+ * Step two: a working code turns it on. Returns false if the code is wrong, and
+ * 2FA stays off — which is the whole point of the two-step dance.
+ */
+export declare function confirmTwoFactor(user: AccountUser, code: string, options?: TwoFactorOptions): Promise<boolean>;
+/** Turn it off, and destroy the secret and the codes with it. */
+export declare function disableTwoFactor(user: AccountUser): Promise<void>;
+/** Verify a code from the authenticator app. */
+export declare function verifyTwoFactorCode(user: AccountUser, code: string, options?: TwoFactorOptions): Promise<boolean>;
+/**
+ * Spend a recovery code. Single use: the code is removed on success, so the same
+ * slip of paper cannot be used twice — and someone who reads it over your shoulder
+ * gets one shot at a code you have already burned.
+ */
+export declare function redeemRecoveryCode(user: AccountUser, code: string): Promise<boolean>;
+/** How many recovery codes are left — worth showing when it gets low. */
+export declare function recoveryCodesRemaining(user: AccountUser): Promise<number>;
+/** Mint a fresh set, invalidating the old ones. Shown once. */
+export declare function regenerateRecoveryCodes(user: AccountUser, count?: number): Promise<string[]>;

package/dist/accounts/two-factor.js

@@ -0,0 +1,146 @@
+/**
+ * The two-factor lifecycle: enable, confirm, challenge, recover, disable.
+ *
+ * Enabling is **two steps on purpose**. `enableTwoFactor()` generates a secret and
+ * stores it, but leaves `two_factor_confirmed_at` null — 2FA is not on yet. Only
+ * `confirmTwoFactor()`, which requires a working code from the app, turns it on.
+ * A one-step "enable" locks out every user who scans the QR wrong, mistypes the
+ * secret, or has a phone whose clock is broken — and they cannot get back in,
+ * because getting back in is exactly what's broken.
+ *
+ * The secret is encrypted at rest with its own purpose, so a leaked database does
+ * not hand over everybody's second factor. Recovery codes are hashed, so a leaked
+ * database does not hand over the backdoor either.
+ */
+import { hash, encryption } from "../core/crypto.js";
+import { accountStore } from "./store.js";
+import { generateSecret, otpauthUri, verifyTotp } from "./totp.js";
+const SECRET_PURPOSE = "accounts:2fa-secret";
+/** Is two-factor actually on for this user — confirmed, not merely started? */
+export function hasTwoFactor(user) {
+    return Boolean(user.two_factor_secret && user.two_factor_confirmed_at);
+}
+/**
+ * Step one: mint a secret and recovery codes, and store them — but do **not** turn
+ * 2FA on. The user has not proved they can generate a code yet.
+ */
+export async function enableTwoFactor(user, options = {}) {
+    const secret = generateSecret();
+    const recoveryCodes = makeRecoveryCodes(options.recoveryCodes ?? 8);
+    await accountStore().update(user.id, {
+        two_factor_secret: await encryption.encrypt(secret, { purpose: SECRET_PURPOSE }),
+        two_factor_recovery_codes: await encryption.encrypt(JSON.stringify(await Promise.all(recoveryCodes.map((code) => hash.make(code)))), { purpose: SECRET_PURPOSE }),
+        two_factor_confirmed_at: null,
+    });
+    return {
+        secret,
+        uri: otpauthUri({
+            secret,
+            account: user.email,
+            issuer: options.issuer ?? "Keel",
+        }),
+        recoveryCodes,
+    };
+}
+/**
+ * Step two: a working code turns it on. Returns false if the code is wrong, and
+ * 2FA stays off — which is the whole point of the two-step dance.
+ */
+export async function confirmTwoFactor(user, code, options = {}) {
+    const secret = await secretFor(user);
+    if (!secret)
+        return false;
+    if (!(await verifyTotp(secret, code, { window: options.window ?? 1 })))
+        return false;
+    await accountStore().update(user.id, {
+        two_factor_confirmed_at: new Date().toISOString(),
+    });
+    return true;
+}
+/** Turn it off, and destroy the secret and the codes with it. */
+export async function disableTwoFactor(user) {
+    await accountStore().update(user.id, {
+        two_factor_secret: null,
+        two_factor_recovery_codes: null,
+        two_factor_confirmed_at: null,
+    });
+}
+/** Verify a code from the authenticator app. */
+export async function verifyTwoFactorCode(user, code, options = {}) {
+    const secret = await secretFor(user);
+    if (!secret)
+        return false;
+    return verifyTotp(secret, code, { window: options.window ?? 1 });
+}
+/**
+ * Spend a recovery code. Single use: the code is removed on success, so the same
+ * slip of paper cannot be used twice — and someone who reads it over your shoulder
+ * gets one shot at a code you have already burned.
+ */
+export async function redeemRecoveryCode(user, code) {
+    const codes = await recoveryCodesFor(user);
+    if (!codes.length)
+        return false;
+    const supplied = code.trim().toLowerCase();
+    for (const hashed of codes) {
+        if (!(await hash.verify(hashed, supplied)))
+            continue;
+        const remaining = codes.filter((c) => c !== hashed);
+        await accountStore().update(user.id, {
+            two_factor_recovery_codes: await encryption.encrypt(JSON.stringify(remaining), {
+                purpose: SECRET_PURPOSE,
+            }),
+        });
+        return true;
+    }
+    return false;
+}
+/** How many recovery codes are left — worth showing when it gets low. */
+export async function recoveryCodesRemaining(user) {
+    return (await recoveryCodesFor(user)).length;
+}
+/** Mint a fresh set, invalidating the old ones. Shown once. */
+export async function regenerateRecoveryCodes(user, count = 8) {
+    const codes = makeRecoveryCodes(count);
+    await accountStore().update(user.id, {
+        two_factor_recovery_codes: await encryption.encrypt(JSON.stringify(await Promise.all(codes.map((code) => hash.make(code)))), { purpose: SECRET_PURPOSE }),
+    });
+    return codes;
+}
+/* --------------------------------- internals ------------------------------ */
+/** The decrypted TOTP secret, or null if 2FA was never set up. */
+async function secretFor(user) {
+    if (!user.two_factor_secret)
+        return null;
+    return encryption.decrypt(user.two_factor_secret, { purpose: SECRET_PURPOSE });
+}
+async function recoveryCodesFor(user) {
+    if (!user.two_factor_recovery_codes)
+        return [];
+    const json = await encryption.decrypt(user.two_factor_recovery_codes, {
+        purpose: SECRET_PURPOSE,
+    });
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Recovery codes people can actually read off paper and type back in: no vowels
+ * (so no accidental words), no 0/1/l/o (so no ambiguity with O/I), grouped.
+ */
+function makeRecoveryCodes(count) {
+    const alphabet = "bcdfghjkmnpqrstvwxyz23456789";
+    const codes = [];
+    for (let i = 0; i < count; i++) {
+        const bytes = crypto.getRandomValues(new Uint8Array(10));
+        const chars = [...bytes].map((b) => alphabet[b % alphabet.length]);
+        codes.push(`${chars.slice(0, 5).join("")}-${chars.slice(5).join("")}`);
+    }
+    return codes;
+}