@openparachute/hub 0.5.14-rc.8 → 0.6.0

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,
+  );
+}

package/src/two-factor-store.ts

@@ -0,0 +1,181 @@
+/**
+ * Persistence for hub-login TOTP 2FA (hub#473). Reads/writes the three
+ * `users` columns added in migration v11: `totp_secret`, `totp_backup_codes`
+ * (JSON array of argon2id hashes), `totp_enrolled_at`.
+ *
+ * The pure crypto lives in `totp.ts`; this is the storage seam. The login +
+ * enroll handlers compose both. Backup-code consumption is done here inside a
+ * DB transaction so verify-then-remove is atomic against concurrent login
+ * POSTs (two requests can't both consume the same code).
+ */
+import type { Database } from "bun:sqlite";
+import { findBackupCodeIndex, generateBackupCodes, verifyTotpCode } from "./totp.ts";
+
+export interface TotpState {
+  /** Base32 secret, or null if 2FA isn't enrolled for this user. */
+  secret: string | null;
+  /** argon2id hashes of the remaining single-use backup codes. */
+  backupCodes: string[];
+  /** ISO-8601 enrollment timestamp, or null. */
+  enrolledAt: string | null;
+}
+
+interface TotpRow {
+  totp_secret: string | null;
+  totp_backup_codes: string | null;
+  totp_enrolled_at: string | null;
+}
+
+function parseBackupCodes(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((c): c is string => typeof c === "string");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read a user's TOTP state. Returns `secret: null` (not enrolled) when the
+ * row is missing — callers treat "no row" identically to "not enrolled."
+ */
+export function getTotpState(db: Database, userId: string): TotpState {
+  const row = db
+    .query<TotpRow, [string]>(
+      "SELECT totp_secret, totp_backup_codes, totp_enrolled_at FROM users WHERE id = ?",
+    )
+    .get(userId);
+  if (!row) return { secret: null, backupCodes: [], enrolledAt: null };
+  return {
+    secret: row.totp_secret && row.totp_secret.length > 0 ? row.totp_secret : null,
+    backupCodes: parseBackupCodes(row.totp_backup_codes),
+    enrolledAt: row.totp_enrolled_at,
+  };
+}
+
+/** Cheap "is 2FA on for this user?" check — true iff a non-empty secret is stored. */
+export function isTotpEnrolled(db: Database, userId: string): boolean {
+  return getTotpState(db, userId).secret !== null;
+}
+
+/** Number of unused backup codes remaining for a user. */
+export function backupCodesRemaining(db: Database, userId: string): number {
+  return getTotpState(db, userId).backupCodes.length;
+}
+
+export interface EnrollResult {
+  /** Plaintext backup codes — show ONCE; never retrievable after. */
+  backupCodes: string[];
+  /** Enrollment timestamp persisted on the row. */
+  enrolledAt: string;
+}
+
+/**
+ * Persist a confirmed enrollment: store the (already-verified) secret, mint +
+ * store a fresh set of backup-code hashes, stamp `totp_enrolled_at`. Returns
+ * the plaintext backup codes for one-time display. Overwrites any prior
+ * enrollment (re-enroll rotates the secret + codes).
+ *
+ * The caller MUST have verified a live code against `secret` before calling
+ * this (proves the authenticator was provisioned correctly). The async hash
+ * happens before the write (single statement, no transaction needed).
+ */
+export async function persistEnrollment(
+  db: Database,
+  userId: string,
+  secret: string,
+  now: () => Date = () => new Date(),
+): Promise<EnrollResult> {
+  const { codes, hashes } = await generateBackupCodes();
+  const enrolledAt = now().toISOString();
+  const result = db
+    .prepare(
+      `UPDATE users
+         SET totp_secret = ?, totp_backup_codes = ?, totp_enrolled_at = ?, updated_at = ?
+       WHERE id = ?`,
+    )
+    .run(secret, JSON.stringify(hashes), enrolledAt, enrolledAt, userId);
+  if (result.changes === 0) {
+    throw new Error(`persistEnrollment: no user row for id ${userId}`);
+  }
+  return { backupCodes: codes, enrolledAt };
+}
+
+/** Clear all TOTP state for a user (disenroll). Idempotent. */
+export function clearEnrollment(
+  db: Database,
+  userId: string,
+  now: () => Date = () => new Date(),
+): void {
+  const stamp = now().toISOString();
+  db.prepare(
+    `UPDATE users
+       SET totp_secret = NULL, totp_backup_codes = NULL, totp_enrolled_at = NULL, updated_at = ?
+     WHERE id = ?`,
+  ).run(stamp, userId);
+}
+
+export type SecondFactorResult =
+  | { ok: true; via: "totp" }
+  | { ok: true; via: "backup_code" }
+  | { ok: false };
+
+/**
+ * Verify a submitted second factor for a user during login. Tries the TOTP
+ * code first; if that fails, tries each stored backup code. On a backup-code
+ * match the code is **consumed** — removed from the stored list inside a
+ * transaction so a concurrent login can't reuse it.
+ *
+ * Returns which factor succeeded (for logging / "X backup codes left"
+ * messaging) or `{ ok: false }`. A user who isn't enrolled returns `ok:false`
+ * — but the login handler only reaches this when `totp_secret` is set, so that
+ * path is defensive.
+ *
+ * `markUsed` is forwarded to {@link verifyTotpCode}'s replay cache (tests set
+ * false to reuse a code; production leaves it true).
+ */
+export async function verifySecondFactor(
+  db: Database,
+  userId: string,
+  submitted: string,
+  markUsed = true,
+): Promise<SecondFactorResult> {
+  const state = getTotpState(db, userId);
+  if (!state.secret) return { ok: false };
+
+  const code = submitted.trim();
+  if (!code) return { ok: false };
+
+  // TOTP path: a 6-digit numeric is almost certainly a TOTP attempt. Try it
+  // first (cheap, no DB write on success beyond the in-memory replay cache).
+  if (verifyTotpCode(state.secret, code, markUsed)) {
+    return { ok: true, via: "totp" };
+  }
+
+  // Backup-code path. Find a matching hash, then consume it transactionally.
+  if (state.backupCodes.length === 0) return { ok: false };
+  const idx = await findBackupCodeIndex(code, state.backupCodes);
+  if (idx < 0) return { ok: false };
+
+  // Consume inside a transaction: re-read the stored list, confirm the code
+  // we matched is still present (defends against a concurrent login that
+  // consumed it between our read and this write), splice it out, write back.
+  let consumed = false;
+  db.transaction(() => {
+    const fresh = getTotpState(db, userId);
+    // The matched hash (by value) must still be in the current list.
+    const matchedHash = state.backupCodes[idx]!;
+    const freshIdx = fresh.backupCodes.indexOf(matchedHash);
+    if (freshIdx < 0) return; // already consumed by a racing request
+    const remaining = fresh.backupCodes.filter((_, j) => j !== freshIdx);
+    db.prepare("UPDATE users SET totp_backup_codes = ? WHERE id = ?").run(
+      JSON.stringify(remaining),
+      userId,
+    );
+    consumed = true;
+  })();
+
+  return consumed ? { ok: true, via: "backup_code" } : { ok: false };
+}