@openparachute/hub 0.5.14-rc.9 → 0.6.0

package/src/setup-wizard.ts

@@ -55,6 +55,7 @@ import {
   renderCsrfHiddenInput,
   verifyCsrfToken,
 } from "./csrf.ts";
+import { type ExposeState, readExposeState } from "./expose-state.ts";
 import {
   SETUP_EXPOSE_MODES,
   type SetupExposeMode,
@@ -207,13 +208,41 @@ export interface DerivedWizardState {
  */
 export const FIRST_VAULT_SHORT: CuratedModuleShort = "vault";
 
+/**
+ * Map a live exposure layer (`expose-state.json`) onto the wizard's
+ * `setup_expose_mode`. The two enums overlap exactly on the layers the
+ * exposure file can carry: `ExposeLayer` is `tailnet | public`, both of
+ * which are valid `SetupExposeMode` values. (There's no `localhost`
+ * exposure layer — running nothing is the absence of a state file, which
+ * `readExposeState` reports as `undefined`, so a missing/unexposed hub
+ * never seeds and the wizard still asks.)
+ *
+ * Returns `undefined` when no exposure is live (or the reader throws on
+ * a malformed file — we swallow that and fall through to "still ask"
+ * rather than crashing the wizard GET).
+ */
+function exposeModeFromLiveState(read: () => ExposeState | undefined): SetupExposeMode | undefined {
+  let state: ExposeState | undefined;
+  try {
+    state = read();
+  } catch {
+    // A corrupt expose-state.json shouldn't brick the wizard. Treat it
+    // as "no live exposure" and let the operator answer the step.
+    return undefined;
+  }
+  if (!state) return undefined;
+  // `ExposeLayer` ⊆ `SetupExposeMode` ("tailnet" | "public").
+  return state.layer;
+}
+
 /**
  * Read DB + services.json to decide which step the wizard should render.
  * Idempotent — re-running after partial setup picks up where it left
  * off. Mostly read-only, with one specific write: on Render (or any
- * platform `detectAutoExposeMode` recognizes), the first call auto-
- * seeds `setup_expose_mode = "public"` so the wizard skips the expose
- * step. Subsequent calls find the setting present and are read-only.
+ * platform `detectAutoExposeMode` recognizes), OR when a live tailscale
+ * exposure (`expose-state.json`) is already up, the first call auto-
+ * seeds `setup_expose_mode` so the wizard skips the expose step.
+ * Subsequent calls find the setting present and are read-only.
  */
 export function deriveWizardState(deps: {
   db: Database;
@@ -224,6 +253,15 @@ export function deriveWizardState(deps: {
    * SetupWizardDeps.env.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Optional injected reader for the live exposure state
+   * (`~/.parachute/expose-state.json`). Defaults to the real
+   * `readExposeState`. Mirrors the `init.ts` seam (`readExposeStateFn`)
+   * so tests can drive the "a tailnet layer is already live" branch
+   * without writing a real state file. When `setup_expose_mode` is
+   * unset, the live exposure layer auto-seeds the setting (see below).
+   */
+  readExposeStateFn?: () => ExposeState | undefined;
 }): DerivedWizardState {
   const hasAdmin = userCount(deps.db) > 0;
   // The wizard's first-vault provisioning uses the curated `vault` short,
@@ -252,6 +290,23 @@ export function deriveWizardState(deps: {
   ) {
     setSetting(deps.db, "setup_expose_mode", "public");
   }
+  // hub#406 team-onboarding bug: `setup_expose_mode` (the wizard's
+  // answer) and `expose-state.json` (the live tailscale exposure) are
+  // orthogonal axes. An operator who ran `parachute expose tailnet`
+  // before opening the wizard has a live tailnet layer but no
+  // `setup_expose_mode` setting — so the wizard re-asked "how will this
+  // hub be reached?" even though tailnet was already up. Auto-seed the
+  // setting from the live exposure layer (tailnet→"tailnet",
+  // public→"public") so the answered-by-action case is treated as
+  // satisfied, mirroring the Render/Fly auto-seed above. Reading the
+  // live state is injected for testability (defaults to the real
+  // reader); a malformed/missing file falls through to "still ask."
+  if (getSetting(deps.db, "setup_expose_mode") === undefined) {
+    const seeded = exposeModeFromLiveState(deps.readExposeStateFn ?? readExposeState);
+    if (seeded !== undefined) {
+      setSetting(deps.db, "setup_expose_mode", seeded);
+    }
+  }
   const hasExposeMode = getSetting(deps.db, "setup_expose_mode") !== undefined;
   let step: WizardStep;
   // Note: `"account"` is a visual-only step in the progress header —
@@ -314,6 +369,14 @@ export interface SetupWizardDeps {
    * without mutating the real process env.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Test seam: inject the live-exposure reader `deriveWizardState`
+   * consults to auto-seed `setup_expose_mode` from a live
+   * `parachute expose tailnet|public` (hub#406). Production omits this
+   * and the real `readExposeState` is used. Mirrors `init.ts`'s
+   * `readExposeStateFn` seam.
+   */
+  readExposeStateFn?: () => ExposeState | undefined;
 }
 
 /**
@@ -446,7 +509,11 @@ export interface RenderAccountStepProps {
 export function renderAccountStep(props: RenderAccountStepProps): string {
   const { csrfToken, errorMessage, username, requireBootstrapToken, bootstrapToken } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
-  const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
+  // Pre-fill "owner" on a fresh render (no prior submission) so the web wizard's
+  // default matches the CLI paths (`set-password`, `setup-wizard`) + the
+  // operator.token convention. Operators can still type any name. On a
+  // validation-failure re-render we echo back what they typed instead.
+  const usernameAttr = ` value="${escapeAttr(username ?? "owner")}"`;
   const tokenAttr = bootstrapToken ? ` value="${escapeAttr(bootstrapToken)}"` : "";
   // Bootstrap-token field comes FIRST when required. An operator who
   // missed the log line is stopped here rather than after filling
@@ -1232,9 +1299,12 @@ function renderMcpTile(
     <h2>Connect Claude Code (MCP)</h2>
     <p>Wire <code>vault:${safeVault}</code> into Claude Code as an MCP server:</p>
     <pre>${escapeHtml(bareCmd)}</pre>
-    <p class="fine">Mint an operator token at
-      <a href="/admin/tokens"><code>/admin/tokens</code></a> and append
-      <code>--header "Authorization: Bearer pvt_..."</code> on first use.</p>
+    <p class="fine">No token needed — the command triggers browser OAuth on
+      first use (you sign in to this hub and approve access). For headless
+      clients that can't do the browser flow, mint a hub token at
+      <a href="/admin/tokens"><code>/admin/tokens</code></a> (or with
+      <code>parachute auth mint-token</code>) and append
+      <code>--header "Authorization: Bearer &lt;token&gt;"</code>.</p>
   </div>`;
 }
 

package/src/tailscale/run.ts

@@ -1,3 +1,5 @@
+import { ensureExecutable, rethrowIfMissing } from "@openparachute/depcheck";
+
 export interface CommandResult {
   code: number;
   stdout: string;
@@ -7,19 +9,34 @@ export interface CommandResult {
 export type Runner = (cmd: readonly string[]) => Promise<CommandResult>;
 
 export async function defaultRunner(cmd: readonly string[]): Promise<CommandResult> {
+  // Pre-flight the binary so a missing `tailscale` surfaces the friendly
+  // install UX (`@openparachute/depcheck`) instead of a raw spawn throw —
+  // closes the no-hint gap where `parachute expose tailnet` on a box without
+  // tailscale died with `Executable not found in $PATH: "tailscale"`.
+  // `cmd[0]` is always present for a real call; guard for the empty edge.
+  const binary = cmd[0];
+  if (binary) ensureExecutable(binary);
   // Inherit env so `tailscale` sees PATH (and HOME for state dir). Bun.spawn
   // defaults to empty env — see api-modules-ops.ts:defaultRun for rationale.
-  const proc = Bun.spawn([...cmd], {
-    stdout: "pipe",
-    stderr: "pipe",
-    env: process.env,
-  });
-  const [stdout, stderr, code] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  return { code, stdout, stderr };
+  try {
+    const proc = Bun.spawn([...cmd], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env,
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { code, stdout, stderr };
+  } catch (err) {
+    // Belt-and-suspenders: a spawn that slips past the pre-flight (binary
+    // removed between which() and spawn, or a race) still surfaces the
+    // friendly MissingDependencyError rather than the raw spawn throw.
+    if (binary) rethrowIfMissing(err, binary);
+    throw err;
+  }
 }
 
 export class TailscaleError extends Error {

package/src/totp.ts

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+/**
+ * TOTP (RFC 6238) primitives + single-use backup codes for hub-login 2FA
+ * (hub#473). The pure crypto layer — no DB, no HTTP. The persistence layer
+ * (`two-factor-store.ts`) reads/writes these against `users` in hub.db; the
+ * login + enroll handlers compose both.
+ *
+ * Approach ported from `parachute-vault/src/two-factor.ts` (the deprecated
+ * vault impl), with two deliberate hub-side changes:
+ *
+ *   - Storage is hub.db's `users` row, not vault's `config.yaml`. That lives
+ *     in `two-factor-store.ts`; this file stays storage-agnostic.
+ *   - Backup codes are hashed with **argon2id** (`@node-rs/argon2`), the same
+ *     hasher hub uses for passwords (`users.ts`), rather than vault's bcrypt.
+ *     One hash family across the hub keeps the dependency surface minimal and
+ *     matches the brief ("same hash as passwords").
+ *
+ * TOTP parameters (interop default — what Google Authenticator / 1Password /
+ * Authy expect): SHA-1, 6 digits, 30s period. Validation accepts a ±1 window
+ * (≈90s effective tolerance) for clock drift. A given (secret, counter) is
+ * single-use within its acceptance lifetime — replays inside the window are
+ * rejected via an in-memory cache.
+ */
+import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
+import * as OTPAuth from "otpauth";
+
+/** Issuer label shown in the authenticator app + encoded in the otpauth URI. */
+export const TOTP_ISSUER = "Parachute Hub";
+/** Number of single-use backup codes minted per enrollment. */
+export const BACKUP_CODE_COUNT = 10;
+/** Length (characters) of each backup code. */
+const BACKUP_CODE_LENGTH = 10;
+/** TOTP secret size in bytes (20 = 160 bits, the RFC 6238 / RFC 4226 default). */
+const TOTP_SECRET_BYTES = 20;
+
+function makeTotp(secretBase32: string, label: string): OTPAuth.TOTP {
+  return new OTPAuth.TOTP({
+    issuer: TOTP_ISSUER,
+    label,
+    algorithm: "SHA1",
+    digits: 6,
+    period: 30,
+    secret: OTPAuth.Secret.fromBase32(secretBase32),
+  });
+}
+
+export interface GeneratedSecret {
+  /** Base32-encoded secret — show to the user for manual authenticator entry. */
+  secret: string;
+  /** `otpauth://totp/...` URI — encode as a QR code for scanning. */
+  otpauthUrl: string;
+}
+
+/**
+ * Generate a fresh TOTP secret + its `otpauth://` provisioning URI. `label`
+ * is the account label rendered in the authenticator app (typically the
+ * username). Does NOT persist anything — the caller stores the returned
+ * `secret` only after the user confirms a code (proving the authenticator
+ * was set up correctly).
+ */
+export function generateTotpSecret(label: string): GeneratedSecret {
+  const secret = new OTPAuth.Secret({ size: TOTP_SECRET_BYTES }).base32;
+  const totp = makeTotp(secret, label);
+  return { secret, otpauthUrl: totp.toString() };
+}
+
+/** Build the `otpauth://` URI for an existing secret (e.g. re-display during enroll). */
+export function otpauthUrlFor(secretBase32: string, label: string): string {
+  return makeTotp(secretBase32, label).toString();
+}
+
+/**
+ * In-memory cache of recently-used TOTP counters, to reject replay inside the
+ * ±1 acceptance window. Key = "sha256(secret):counter"; value = expiry ms.
+ * Bounded — entries auto-expire ~2 min after their window closes. Process-
+ * local (a restart clears it, which is itself fine: the window is 90s).
+ */
+const usedTotpCounters = new Map<string, number>();
+
+function gcUsedTotp(now: number): void {
+  for (const [k, exp] of usedTotpCounters) {
+    if (exp < now) usedTotpCounters.delete(k);
+  }
+}
+
+/**
+ * Verify a 6-digit TOTP code against `secretBase32`. Accepts ±1 window
+ * (prev / current / next 30s period). A given (secret, counter) is single-use
+ * within its acceptance lifetime — replays are rejected.
+ *
+ * `markUsed`: set false in tests that want to verify the same code twice.
+ * Defaults to true in production so a captured code can't be replayed inside
+ * its ~90s validity window.
+ */
+export function verifyTotpCode(secretBase32: string, code: string, markUsed = true): boolean {
+  const trimmed = code.trim().replace(/\s+/g, "");
+  if (!/^\d{6}$/.test(trimmed)) return false;
+  try {
+    const totp = makeTotp(secretBase32, "owner");
+    const delta = totp.validate({ token: trimmed, window: 1 });
+    if (delta === null) return false;
+
+    const now = Date.now();
+    gcUsedTotp(now);
+    const counter = Math.floor(now / 30_000) + delta;
+    // Hash the secret so the in-memory replay cache never holds the plaintext
+    // TOTP secret as a map key (defense in depth against heap dumps / logs).
+    const secretHash = createHash("sha256").update(secretBase32).digest("hex");
+    const key = `${secretHash}:${counter}`;
+    if (usedTotpCounters.has(key)) return false;
+    if (markUsed) {
+      // Expire the entry a bit after the outer edge of the acceptance window.
+      usedTotpCounters.set(key, now + 120_000);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Test-only: reset the replay-protection cache between cases. */
+export function _resetTotpReplayCache(): void {
+  usedTotpCounters.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Backup codes
+// ---------------------------------------------------------------------------
+
+function randomBackupCode(): string {
+  // Lowercase alphanumeric minus ambiguous glyphs (0/o, 1/l/i). Read-aloud
+  // friendly + unambiguous when typed back in. Formatted as two 5-char groups
+  // (`abcde-fghij`) for legibility; the hyphen is cosmetic and stripped on
+  // verify so the user can type it with or without.
+  const alphabet = "abcdefghjkmnpqrstuvwxyz23456789";
+  const bytes = crypto.getRandomValues(new Uint8Array(BACKUP_CODE_LENGTH));
+  let out = "";
+  for (let i = 0; i < BACKUP_CODE_LENGTH; i++) {
+    out += alphabet[bytes[i]! % alphabet.length];
+    if (i === 4) out += "-";
+  }
+  return out;
+}
+
+/** Normalize a backup code for hashing / comparison: lowercase, no whitespace, no hyphens. */
+export function normalizeBackupCode(code: string): string {
+  return code
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, "");
+}
+
+export interface GeneratedBackupCodes {
+  /** Plaintext codes to show the user ONCE (hyphenated for display). */
+  codes: string[];
+  /** argon2id hashes of the normalized codes — what gets stored. */
+  hashes: string[];
+}
+
+/**
+ * Generate {@link BACKUP_CODE_COUNT} fresh backup codes + their argon2id
+ * hashes. The plaintext `codes` are displayed once at enrollment; only the
+ * `hashes` are persisted (as a JSON array). Each code is hashed in its
+ * normalized form so display-formatting (hyphen) never affects verification.
+ */
+export async function generateBackupCodes(): Promise<GeneratedBackupCodes> {
+  const codes: string[] = [];
+  const hashes: string[] = [];
+  for (let i = 0; i < BACKUP_CODE_COUNT; i++) {
+    const code = randomBackupCode();
+    codes.push(code);
+    hashes.push(await argonHash(normalizeBackupCode(code)));
+  }
+  return { codes, hashes };
+}
+
+/**
+ * Check a submitted backup code against a stored hash list. Returns the
+ * **index** of the matching hash (so the caller can splice it out and persist
+ * the shorter list — single-use consumption), or `-1` for no match.
+ *
+ * Pure: does NOT mutate the input list or persist anything. Consumption +
+ * persistence is the store layer's job (`two-factor-store.ts`), which holds
+ * the DB transaction so verify-then-consume is atomic against concurrent
+ * login attempts.
+ */
+export async function findBackupCodeIndex(
+  code: string,
+  hashes: readonly string[],
+): Promise<number> {
+  const normalized = normalizeBackupCode(code);
+  if (!normalized) return -1;
+  for (let i = 0; i < hashes.length; i++) {
+    try {
+      if (await argonVerify(hashes[i]!, normalized)) return i;
+    } catch {
+      // Corrupt / non-argon hash — skip.
+    }
+  }
+  return -1;
+}

package/src/two-factor-handlers.ts

@@ -0,0 +1,287 @@
+/**
+ * `/account/2fa` — user self-service TOTP 2FA enroll / disenroll (hub#473).
+ *
+ *   GET  /account/2fa   — render current state (enrolled → status+disenroll;
+ *                         not enrolled → "set up" CTA).
+ *   POST /account/2fa   — dispatch on the `action` field:
+ *                           start   → generate a secret + render QR/confirm
+ *                           confirm → verify code vs the in-flight secret,
+ *                                     persist enrollment, show backup codes
+ *                           disable → verify current password, clear 2FA
+ *
+ * Auth posture: every endpoint requires an active session (the signed-in user
+ * acts on their OWN account). Same session-or-302-to-/login shape as
+ * `/account/change-password`.
+ *
+ * Enrollment is browser-first (right for headless servers): the secret is
+ * generated server-side, shown as a QR + manual base32 key, and only PERSISTED
+ * after the user confirms a live code (proving the authenticator was set up).
+ * The in-flight secret rides a hidden form field between `start` and `confirm`
+ * — it isn't stored until confirmation, so an abandoned setup leaves no state.
+ *
+ * No JSON layer — server-rendered HTML forms, same as the rest of `/account/*`,
+ * so 2FA setup works without JS.
+ */
+import type { Database } from "bun:sqlite";
+import QRCode from "qrcode";
+import { renderAdminError } from "./admin-login-ui.ts";
+import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
+import { isHttpsRequest } from "./request-protocol.ts";
+import { findActiveSession } from "./sessions.ts";
+import { generateTotpSecret, otpauthUrlFor, verifyTotpCode } from "./totp.ts";
+import {
+  backupCodesRemaining,
+  clearEnrollment,
+  getTotpState,
+  isTotpEnrolled,
+  persistEnrollment,
+} from "./two-factor-store.ts";
+import {
+  renderTwoFactorBackupCodes,
+  renderTwoFactorEnrolled,
+  renderTwoFactorEnrolling,
+  renderTwoFactorNotEnrolled,
+} from "./two-factor-ui.ts";
+import { PASSWORD_MAX_LEN, type User, getUserById, verifyPassword } from "./users.ts";
+
+export interface TwoFactorDeps {
+  db: Database;
+  /** Test seam — defaults to real clock. */
+  now?: () => Date;
+}
+
+function htmlResponse(body: string, status = 200, extra: Record<string, string> = {}): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8", ...extra },
+  });
+}
+
+function redirect(location: string, extra: Record<string, string> = {}): Response {
+  return new Response(null, { status: 302, headers: { location, ...extra } });
+}
+
+/** Resolve the signed-in user, or a Response to return (302 / 401). */
+function requireUser(deps: TwoFactorDeps, req: Request): { user: User } | { response: Response } {
+  const session = findActiveSession(deps.db, req);
+  if (!session) {
+    return { response: redirect(`/login?next=${encodeURIComponent("/account/2fa")}`) };
+  }
+  const user = getUserById(deps.db, session.userId);
+  if (!user) {
+    return { response: redirect("/login") };
+  }
+  return { user };
+}
+
+/** Render the QR SVG for a secret + the enrolling page. */
+async function renderEnrolling(
+  csrfToken: string,
+  secret: string,
+  label: string,
+  errorMessage?: string,
+): Promise<Response> {
+  const otpauthUrl = otpauthUrlFor(secret, label);
+  // Inline SVG — self-contained, no external fetch (privacy posture).
+  const qrSvg = await QRCode.toString(otpauthUrl, {
+    type: "svg",
+    margin: 0,
+    errorCorrectionLevel: "M",
+  });
+  return htmlResponse(
+    renderTwoFactorEnrolling({
+      csrfToken,
+      qrSvg,
+      secret,
+      ...(errorMessage ? { errorMessage } : {}),
+    }),
+  );
+}
+
+/**
+ * GET /account/2fa — render the current 2FA state for the signed-in user.
+ */
+export function handleTwoFactorGet(req: Request, deps: TwoFactorDeps): Response {
+  const got = requireUser(deps, req);
+  if ("response" in got) return got.response;
+  const user = got.user;
+
+  const csrf = ensureCsrfToken(req);
+  const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+
+  if (isTotpEnrolled(deps.db, user.id)) {
+    const state = getTotpState(deps.db, user.id);
+    return htmlResponse(
+      renderTwoFactorEnrolled({
+        csrfToken: csrf.token,
+        enrolledAt: state.enrolledAt,
+        backupCodesRemaining: state.backupCodes.length,
+      }),
+      200,
+      extra,
+    );
+  }
+  // `?disabled=1` — the disenroll POST 302s here so a refresh doesn't re-POST;
+  // surface a one-line confirmation on the not-enrolled page.
+  const disabled = new URL(req.url).searchParams.get("disabled") === "1";
+  return htmlResponse(
+    renderTwoFactorNotEnrolled({
+      csrfToken: csrf.token,
+      ...(disabled ? { notice: "Two-factor authentication has been turned off." } : {}),
+    }),
+    200,
+    extra,
+  );
+}
+
+/**
+ * POST /account/2fa — dispatch on `action`.
+ */
+export async function handleTwoFactorPost(req: Request, deps: TwoFactorDeps): Promise<Response> {
+  const got = requireUser(deps, req);
+  if ("response" in got) {
+    // For a POST without a session, a 302 to /login is fine (browser will
+    // follow with the form lost, which is acceptable — re-auth, then retry).
+    return got.response;
+  }
+  const user = got.user;
+
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  const csrfToken = typeof formCsrf === "string" ? formCsrf : "";
+  if (!verifyCsrfToken(req, csrfToken || null)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid form submission",
+        message: "The form's CSRF token did not match. Reload the page and try again.",
+      }),
+      400,
+    );
+  }
+
+  const action = String(form.get("action") ?? "");
+
+  // --- start: generate a secret, render QR + confirm form ---------------
+  if (action === "start") {
+    // Refuse to start a fresh enrollment if already enrolled — disenroll
+    // first. Prevents accidentally clobbering a working setup.
+    if (isTotpEnrolled(deps.db, user.id)) {
+      return htmlResponse(
+        renderTwoFactorEnrolled({
+          csrfToken,
+          enrolledAt: getTotpState(deps.db, user.id).enrolledAt,
+          backupCodesRemaining: backupCodesRemaining(deps.db, user.id),
+          errorMessage: "Two-factor is already enabled. Turn it off first to re-enroll.",
+        }),
+        409,
+      );
+    }
+    const { secret } = generateTotpSecret(user.username);
+    return renderEnrolling(csrfToken, secret, user.username);
+  }
+
+  // --- confirm: verify code vs the in-flight secret, persist ------------
+  if (action === "confirm") {
+    const secret = String(form.get("secret") ?? "");
+    const code = String(form.get("code") ?? "");
+    // Validate the in-flight secret format before it reaches verifyTotpCode /
+    // persistEnrollment (N1 — cheap defense in depth). The secret is a
+    // server-minted base32 string round-tripped through a hidden form field;
+    // it's session-gated + CSRF'd, but a malformed value (truncated paste,
+    // hand-crafted POST) should be rejected explicitly rather than stored.
+    // base32 alphabet (A–Z, 2–7) + optional `=` padding, ≥16 chars (our secret
+    // is 20 bytes → 32 base32 chars; 16 is a conservative floor).
+    if (!secret || !/^[A-Z2-7]+=*$/i.test(secret) || secret.length < 16) {
+      // Lost / malformed in-flight secret (stale form, bad paste) — restart.
+      return htmlResponse(
+        renderTwoFactorNotEnrolled({
+          csrfToken,
+          errorMessage: "Setup expired. Please start again.",
+        }),
+        400,
+      );
+    }
+    // Defensive: someone POSTing confirm for an already-enrolled account.
+    if (isTotpEnrolled(deps.db, user.id)) {
+      return htmlResponse(
+        renderTwoFactorEnrolled({
+          csrfToken,
+          enrolledAt: getTotpState(deps.db, user.id).enrolledAt,
+          backupCodesRemaining: backupCodesRemaining(deps.db, user.id),
+          errorMessage: "Two-factor is already enabled.",
+        }),
+        409,
+      );
+    }
+    if (!verifyTotpCode(secret, code)) {
+      return renderEnrolling(
+        csrfToken,
+        secret,
+        user.username,
+        "That code didn't match. Make sure your device clock is correct and try the current code.",
+      );
+    }
+    const result = await persistEnrollment(
+      deps.db,
+      user.id,
+      secret,
+      deps.now ?? (() => new Date()),
+    );
+    // Show the backup codes ONCE. Setting no-store so the browser doesn't
+    // cache the page with the plaintext codes in it.
+    return htmlResponse(renderTwoFactorBackupCodes({ codes: result.backupCodes }), 200, {
+      "cache-control": "no-store",
+    });
+  }
+
+  // --- disable: verify current password, clear 2FA ----------------------
+  if (action === "disable") {
+    if (!isTotpEnrolled(deps.db, user.id)) {
+      // Already off — render the not-enrolled page (idempotent).
+      return htmlResponse(
+        renderTwoFactorNotEnrolled({
+          csrfToken,
+          notice: "Two-factor authentication is already off.",
+        }),
+      );
+    }
+    const password = String(form.get("password") ?? "");
+    const state = getTotpState(deps.db, user.id);
+    const renderEnrolledError = (msg: string, status: number): Response =>
+      htmlResponse(
+        renderTwoFactorEnrolled({
+          csrfToken,
+          enrolledAt: state.enrolledAt,
+          backupCodesRemaining: state.backupCodes.length,
+          errorMessage: msg,
+        }),
+        status,
+      );
+    if (!password) {
+      return renderEnrolledError("Enter your current password to turn off two-factor.", 400);
+    }
+    // Cap before argon2id verify (CPU-DoS guard — same posture as /login).
+    if (password.length > PASSWORD_MAX_LEN) {
+      return renderEnrolledError(`Password must be ≤ ${PASSWORD_MAX_LEN} characters.`, 413);
+    }
+    const ok = await verifyPassword(user, password);
+    if (!ok) {
+      return renderEnrolledError("That password is incorrect.", 401);
+    }
+    clearEnrollment(deps.db, user.id, deps.now ?? (() => new Date()));
+    // Redirect to the GET so a refresh doesn't re-POST. The not-enrolled
+    // page renders the success notice via a query flag.
+    return redirect("/account/2fa?disabled=1", {
+      "cache-control": "no-store",
+      "x-secure-context": isHttpsRequest(req) ? "https" : "http",
+    });
+  }
+
+  return htmlResponse(
+    renderAdminError({
+      title: "Unknown action",
+      message: "That two-factor action isn't recognized. Reload the page and try again.",
+    }),
+    400,
+  );
+}