From 71c538cfa42b2e5694dbc491bc0d5fef90894dc0 Mon Sep 17 00:00:00 2001
From: Alex Price <github@alexprice.dev>
Date: Tue, 21 Jul 2026 12:23:56 +0100
Subject: [PATCH 1/4] Add optional first-party proof-of-work captcha to login

Layered bot defense on POST /login to stop spam magic-link signups:
rate-limit (activates the dormant middleware), a honeypot field, and an
optional self-hosted proof-of-work captcha. The captcha signs challenges
with the existing CRYPTO_PEPPER (no third party, account, new secret, or
CSP change) and is off unless CAPTCHA_ENABLED=true, so /login is unchanged
by default. Ships a zero-dep client solver bundle and full test coverage.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .env.example                                  |   8 +
 package.json                                  |   4 +-
 src/client/captcha.test.ts                    |  90 ++++++++
 src/client/captcha.ts                         | 211 ++++++++++++++++++
 src/server/components/captcha-widget.test.tsx |  35 +++
 src/server/components/captcha-widget.tsx      |  46 ++++
 src/server/controllers/auth/login.test.ts     | 136 +++++++++++
 src/server/controllers/auth/login.tsx         |  34 ++-
 src/server/services/assets.test.ts            |   1 +
 src/server/services/assets.ts                 |   2 +-
 src/server/services/captcha.test.ts           | 144 ++++++++++++
 src/server/services/captcha.ts                | 160 +++++++++++++
 src/server/templates/login.tsx                |  25 ++-
 src/server/utils/env.ts                       |   7 +
 14 files changed, 898 insertions(+), 5 deletions(-)
 create mode 100644 src/client/captcha.test.ts
 create mode 100644 src/client/captcha.ts
 create mode 100644 src/server/components/captcha-widget.test.tsx
 create mode 100644 src/server/components/captcha-widget.tsx
 create mode 100644 src/server/services/captcha.test.ts
 create mode 100644 src/server/services/captcha.ts

diff --git a/.env.example b/.env.example
index 6204811..aa30426 100644
--- a/.env.example
+++ b/.env.example
@@ -36,3 +36,11 @@ FROM_NAME=Billet
 # Retry-After value in seconds (default 3600).
 # MAINTENANCE_MODE=true
 # MAINTENANCE_RETRY_AFTER=3600
+
+# Optional — set to "true" to add a proof-of-work captcha to the /login form,
+# blocking automated spam sign-ups. Self-hosted with no third party or account: it
+# signs challenges with CRYPTO_PEPPER, so no extra secret is needed. A honeypot and
+# per-IP rate limit protect /login regardless of this flag. CAPTCHA_DIFFICULTY tunes
+# the client's work (search space size; default 100000).
+# CAPTCHA_ENABLED=true
+# CAPTCHA_DIFFICULTY=100000
diff --git a/package.json b/package.json
index e823068..0690d39 100644
--- a/package.json
+++ b/package.json
@@ -4,11 +4,11 @@
   "version": "1.0.0",
   "scripts": {
     "build": "bun run build:client && bun run build:css",
-    "build:client": "bun build ./src/client/main.ts --outdir ./dist/assets --minify --external preact --external preact/hooks --external preact/jsx-dev-runtime --external preact/jsx-runtime",
+    "build:client": "bun build ./src/client/main.ts ./src/client/captcha.ts --outdir ./dist/assets --minify --external preact --external preact/hooks --external preact/jsx-dev-runtime --external preact/jsx-runtime",
     "build:css": "bun build ./src/client/style.css --outdir ./dist/assets --entry-naming main.css --minify",
     "start": "bun run src/server/main.ts",
     "dev": "bun run dev:client & bun run dev:server & bun run dev:css",
-    "dev:client": "bun --watch build ./src/client/main.ts --outdir ./dist/assets --external preact --external preact/hooks --external preact/jsx-dev-runtime --external preact/jsx-runtime",
+    "dev:client": "bun --watch build ./src/client/main.ts ./src/client/captcha.ts --outdir ./dist/assets --external preact --external preact/hooks --external preact/jsx-dev-runtime --external preact/jsx-runtime",
     "dev:server": "bun --watch run src/server/main.ts",
     "dev:css": "bun build ./src/client/style.css --outdir ./dist/assets --entry-naming main.css --watch",
     "test": "NODE_ENV=test bun run src/server/test-utils/run-tests.ts",
diff --git a/src/client/captcha.test.ts b/src/client/captcha.test.ts
new file mode 100644
index 0000000..dc94e72
--- /dev/null
+++ b/src/client/captcha.test.ts
@@ -0,0 +1,90 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  clearUsedChallenges,
+  issueChallenge,
+  verifyCaptcha,
+} from "../server/services/captcha";
+import { init, sha256hex, solve } from "./captcha";
+
+const mountChallenge = (challenge: ReturnType<typeof issueChallenge>): void => {
+  const form = document.createElement("form");
+
+  const mount = document.createElement("div");
+  mount.setAttribute("data-captcha", "");
+  mount.dataset.salt = challenge.salt;
+  mount.dataset.challenge = challenge.challenge;
+  mount.dataset.expires = String(challenge.expires);
+  mount.dataset.maxnumber = String(challenge.maxnumber);
+  mount.dataset.signature = challenge.signature;
+
+  const status = document.createElement("span");
+  status.className = "captcha-status";
+  mount.appendChild(status);
+
+  const input = document.createElement("input");
+  input.type = "hidden";
+  input.name = "captcha_solution";
+
+  form.appendChild(mount);
+  form.appendChild(input);
+  document.body.appendChild(form);
+};
+
+describe("captcha client solver", () => {
+  const original = {
+    enabled: process.env.CAPTCHA_ENABLED,
+    difficulty: process.env.CAPTCHA_DIFFICULTY,
+  };
+
+  beforeEach(() => {
+    process.env.CAPTCHA_ENABLED = "true";
+    process.env.CAPTCHA_DIFFICULTY = "2000";
+    clearUsedChallenges();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (original.enabled === undefined) delete process.env.CAPTCHA_ENABLED;
+    else process.env.CAPTCHA_ENABLED = original.enabled;
+    if (original.difficulty === undefined)
+      delete process.env.CAPTCHA_DIFFICULTY;
+    else process.env.CAPTCHA_DIFFICULTY = original.difficulty;
+    clearUsedChallenges();
+  });
+
+  test("sha256hex matches known NIST vectors (parity with node:crypto)", () => {
+    expect(sha256hex("abc")).toBe(
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+    );
+    expect(sha256hex("")).toBe(
+      "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    );
+  });
+
+  test("solve finds the answer for a real challenge", async () => {
+    const challenge = issueChallenge();
+    const answer = await solve(challenge);
+    expect(answer).not.toBeNull();
+    expect(sha256hex(`${challenge.salt}${answer}`)).toBe(challenge.challenge);
+  });
+
+  test("init fills the hidden field with a server-verifiable payload", async () => {
+    const challenge = issueChallenge();
+    mountChallenge(challenge);
+
+    await init();
+
+    const input = document.querySelector<HTMLInputElement>(
+      'input[name="captcha_solution"]',
+    );
+    expect(input?.value).toBeTruthy();
+    // The end-to-end proof: the client-produced payload verifies server-side,
+    // which can only pass if the hand-written SHA-256 matches node:crypto.
+    expect(verifyCaptcha(input?.value ?? null)).toBe(true);
+  });
+
+  test("init is a no-op when there is no mount", async () => {
+    await init();
+    expect(document.body.innerHTML).toBe("");
+  });
+});
diff --git a/src/client/captcha.ts b/src/client/captcha.ts
new file mode 100644
index 0000000..9e47d97
--- /dev/null
+++ b/src/client/captcha.ts
@@ -0,0 +1,211 @@
+// First-party proof-of-work captcha solver. Standalone, zero-dependency bundle
+// (no Preact / no importmap) loaded only on the login page when CAPTCHA_ENABLED is
+// on. It reads the challenge the server embedded in the mount element, brute-forces
+// the answer, and writes the solved payload into a hidden form field.
+//
+// The field/attribute names below MUST match src/server/services/captcha.ts. The
+// client cannot import that module (it pulls in node:crypto), so the literals are
+// duplicated here; a test cross-checks a client-produced payload against the server
+// verifier to catch drift.
+
+const SOLUTION_FIELD = "captcha_solution";
+// Yield to the event loop every N hashes so a large search never freezes the tab.
+const YIELD_EVERY = 5000;
+
+interface Challenge {
+  salt: string;
+  challenge: string;
+  expires: number;
+  maxnumber: number;
+  signature: string;
+}
+
+// --- Minimal synchronous SHA-256 -------------------------------------------------
+// Self-authored (no npm dep). Returns lowercase hex, matching Node's
+// createHash("sha256") for UTF-8 input, which the server relies on to verify.
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+  0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+  0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+const toHex8 = (x: number): string => (x >>> 0).toString(16).padStart(8, "0");
+
+export const sha256hex = (input: string): string => {
+  const bytes = new TextEncoder().encode(input);
+  const bitLen = bytes.length * 8;
+  const withOne = bytes.length + 1;
+  const pad = (56 - (withOne % 64) + 64) % 64;
+  const total = withOne + pad + 8;
+
+  const msg = new Uint8Array(total);
+  msg.set(bytes);
+  msg[bytes.length] = 0x80;
+  const dv = new DataView(msg.buffer);
+  dv.setUint32(total - 8, Math.floor(bitLen / 0x100000000));
+  dv.setUint32(total - 4, bitLen >>> 0);
+
+  let h0 = 0x6a09e667;
+  let h1 = 0xbb67ae85;
+  let h2 = 0x3c6ef372;
+  let h3 = 0xa54ff53a;
+  let h4 = 0x510e527f;
+  let h5 = 0x9b05688c;
+  let h6 = 0x1f83d9ab;
+  let h7 = 0x5be0cd19;
+
+  const w = new Uint32Array(64);
+  for (let off = 0; off < total; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = dv.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const a15 = w[i - 15];
+      const a2 = w[i - 2];
+      const s0 = rotr(a15, 7) ^ rotr(a15, 18) ^ (a15 >>> 3);
+      const s1 = rotr(a2, 17) ^ rotr(a2, 19) ^ (a2 >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+    }
+
+    let a = h0;
+    let b = h1;
+    let c = h2;
+    let d = h3;
+    let e = h4;
+    let f = h5;
+    let g = h6;
+    let h = h7;
+
+    for (let i = 0; i < 64; i++) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (h + s1 + ch + K[i] + w[i]) | 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (s0 + maj) | 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + t1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) | 0;
+    }
+
+    h0 = (h0 + a) | 0;
+    h1 = (h1 + b) | 0;
+    h2 = (h2 + c) | 0;
+    h3 = (h3 + d) | 0;
+    h4 = (h4 + e) | 0;
+    h5 = (h5 + f) | 0;
+    h6 = (h6 + g) | 0;
+    h7 = (h7 + h) | 0;
+  }
+
+  return (
+    toHex8(h0) +
+    toHex8(h1) +
+    toHex8(h2) +
+    toHex8(h3) +
+    toHex8(h4) +
+    toHex8(h5) +
+    toHex8(h6) +
+    toHex8(h7)
+  );
+};
+
+// --- Solver ----------------------------------------------------------------------
+
+const readChallenge = (mount: HTMLElement): Challenge | null => {
+  const { salt, challenge, expires, maxnumber, signature } = mount.dataset;
+  if (!salt || !challenge || !expires || !maxnumber || !signature) return null;
+  return {
+    salt,
+    challenge,
+    expires: Number(expires),
+    maxnumber: Number(maxnumber),
+    signature,
+  };
+};
+
+export const solve = async (c: Challenge): Promise<number | null> => {
+  for (let n = 0; n <= c.maxnumber; n++) {
+    if (sha256hex(`${c.salt}${n}`) === c.challenge) return n;
+    if (n % YIELD_EVERY === 0) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+  return null;
+};
+
+const encodePayload = (c: Challenge, n: number): string =>
+  btoa(
+    JSON.stringify({
+      salt: c.salt,
+      challenge: c.challenge,
+      expires: c.expires,
+      signature: c.signature,
+      number: n,
+    }),
+  );
+
+export const init = async (): Promise<void> => {
+  const mount = document.querySelector<HTMLElement>("[data-captcha]");
+  if (!mount) return;
+
+  const input = document.querySelector<HTMLInputElement>(
+    `input[name="${SOLUTION_FIELD}"]`,
+  );
+  if (!input) return;
+
+  const challenge = readChallenge(mount);
+  if (!challenge) return;
+
+  const status = mount.querySelector<HTMLElement>(".captcha-status");
+  const form = mount.closest("form");
+
+  // If the user submits before the proof is ready, hold the submit and replay it
+  // once solved — so a fast typist never trips the server-side check.
+  let solved = false;
+  let submitPending = false;
+  form?.addEventListener("submit", (event) => {
+    if (!solved) {
+      event.preventDefault();
+      submitPending = true;
+    }
+  });
+
+  const answer = await solve(challenge);
+  if (answer === null) {
+    // Couldn't solve (e.g. tampered challenge) — leave the field empty; the server
+    // rejects and re-renders a fresh challenge.
+    if (status) status.textContent = "Verification unavailable — please retry.";
+    return;
+  }
+
+  input.value = encodePayload(challenge, answer);
+  solved = true;
+  if (status) status.textContent = "Verified.";
+  if (submitPending) form?.requestSubmit();
+};
+
+// Auto-run when loaded as the standalone bundle. Harmless in tests (no mount → no-op)
+// so specs can set up a fixture and call init() themselves.
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => {
+      void init();
+    });
+  } else {
+    void init();
+  }
+}
diff --git a/src/server/components/captcha-widget.test.tsx b/src/server/components/captcha-widget.test.tsx
new file mode 100644
index 0000000..b265113
--- /dev/null
+++ b/src/server/components/captcha-widget.test.tsx
@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { CaptchaWidget } from "./captcha-widget";
+
+const challenge = {
+  salt: "test-salt",
+  challenge: "deadbeef",
+  expires: 1_700_000_000_000,
+  maxnumber: 100_000,
+  signature: "abc123",
+};
+
+describe("CaptchaWidget", () => {
+  test("renders nothing when no challenge is passed", () => {
+    expect(renderToString(<CaptchaWidget challenge={null} />)).toBe("");
+    expect(renderToString(<CaptchaWidget />)).toBe("");
+  });
+
+  test("renders the mount, hidden field, and solver script when enabled", () => {
+    const html = renderToString(<CaptchaWidget challenge={challenge} />);
+
+    expect(html).toContain("data-captcha");
+    expect(html).toContain('data-salt="test-salt"');
+    expect(html).toContain('data-challenge="deadbeef"');
+    expect(html).toContain('data-signature="abc123"');
+    expect(html).toContain('name="captcha_solution"');
+    expect(html).toContain("/assets/captcha.js");
+  });
+
+  test("never leaks the answer to the client", () => {
+    const html = renderToString(<CaptchaWidget challenge={challenge} />);
+    // Only the target hash and search bounds are exposed — nothing named "answer".
+    expect(html).not.toContain("answer");
+  });
+});
diff --git a/src/server/components/captcha-widget.tsx b/src/server/components/captcha-widget.tsx
new file mode 100644
index 0000000..bd4f0d8
--- /dev/null
+++ b/src/server/components/captcha-widget.tsx
@@ -0,0 +1,46 @@
+import type { JSX } from "react";
+import { getAssetUrl } from "../services/assets";
+import {
+  CAPTCHA_SOLUTION_FIELD,
+  type CaptchaChallenge,
+} from "../services/captcha";
+
+interface CaptchaWidgetProps {
+  challenge?: CaptchaChallenge | null;
+}
+
+/**
+ * Renders the proof-of-work captcha into a login form. Emits the challenge as
+ * data-* attributes for the client solver, a hidden field it fills with the solved
+ * payload, and the standalone solver bundle. Renders nothing when captcha is
+ * disabled (no challenge passed), so the login form is unchanged in that case.
+ *
+ * The script is emitted here rather than in BaseLayout so only the login response
+ * loads it, and everything is same-origin — no CSP change is required.
+ */
+export const CaptchaWidget = ({
+  challenge,
+}: CaptchaWidgetProps): JSX.Element | null => {
+  if (!challenge) {
+    return null;
+  }
+
+  return (
+    <>
+      <div
+        data-captcha
+        data-salt={challenge.salt}
+        data-challenge={challenge.challenge}
+        data-expires={String(challenge.expires)}
+        data-maxnumber={String(challenge.maxnumber)}
+        data-signature={challenge.signature}
+        className="captcha-widget"
+        aria-live="polite"
+      >
+        <span className="captcha-status">Verifying you're human…</span>
+      </div>
+      <input type="hidden" name={CAPTCHA_SOLUTION_FIELD} />
+      <script type="module" src={getAssetUrl("/assets/captcha.js")} defer />
+    </>
+  );
+};
diff --git a/src/server/controllers/auth/login.test.ts b/src/server/controllers/auth/login.test.ts
index dd346b7..a0c811d 100644
--- a/src/server/controllers/auth/login.test.ts
+++ b/src/server/controllers/auth/login.test.ts
@@ -1,10 +1,38 @@
 import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { createHash } from "node:crypto";
 import { SQL } from "bun";
+import { clearRateLimitLog } from "../../middleware/rate-limit";
+import { clearUsedChallenges, issueChallenge } from "../../services/captcha";
 import type { LoginState } from "../../templates/login";
 import { createBunRequest, findSetCookie } from "../../test-utils/bun-request";
 import { cleanupTestData } from "../../test-utils/helpers";
 import { stateHelpers } from "../../utils/state";
 
+// Solve a challenge the way the client would, for the captcha-enabled tests.
+const solveChallenge = (
+  challenge: ReturnType<typeof issueChallenge>,
+): string => {
+  let answer = 0;
+  for (let n = 0; n <= challenge.maxnumber; n++) {
+    if (
+      createHash("sha256").update(`${challenge.salt}${n}`).digest("hex") ===
+      challenge.challenge
+    ) {
+      answer = n;
+      break;
+    }
+  }
+  return Buffer.from(
+    JSON.stringify({
+      salt: challenge.salt,
+      challenge: challenge.challenge,
+      expires: challenge.expires,
+      signature: challenge.signature,
+      number: answer,
+    }),
+  ).toString("base64");
+};
+
 if (!process.env.DATABASE_URL) {
   throw new Error("DATABASE_URL is required for tests");
 }
@@ -22,6 +50,9 @@ import { login } from "./login";
 describe("Login Controller", () => {
   beforeEach(async () => {
     await cleanupTestData(db);
+    // Guards share process-wide state; reset so tests don't leak into each other.
+    clearRateLimitLog();
+    clearUsedChallenges();
   });
 
   afterAll(async () => {
@@ -232,4 +263,109 @@ describe("Login Controller", () => {
       expect(tokens).toHaveLength(1);
     });
   });
+
+  describe("POST /login bot defense", () => {
+    test("silently discards a submission with the honeypot filled", async () => {
+      const formData = new FormData();
+      formData.append("email", "bot@example.com");
+      formData.append("company_website", "http://spam.example");
+
+      const request = createBunRequest("http://localhost:3000/login", {
+        method: "POST",
+        body: formData,
+      });
+
+      const response = await login.create(request);
+
+      // Feigns success so the bot gets no signal...
+      expect(response.status).toBe(303);
+      const setCookie = findSetCookie(request, "flash_state");
+      expect(setCookie).toContain("email-sent");
+
+      // ...but creates no user and issues no magic link.
+      const users =
+        await db`SELECT id FROM users WHERE email = 'bot@example.com'`;
+      expect(users).toHaveLength(0);
+    });
+
+    test("returns 429 once the per-IP rate limit is exceeded", async () => {
+      const send = () => {
+        const formData = new FormData();
+        formData.append("email", "flood@example.com");
+        return login.create(
+          createBunRequest("http://localhost:3000/login", {
+            method: "POST",
+            body: formData,
+          }),
+        );
+      };
+
+      // Limit is 5 per window; the 6th request is throttled.
+      for (let i = 0; i < 5; i++) {
+        expect((await send()).status).toBe(303);
+      }
+      expect((await send()).status).toBe(429);
+    });
+
+    describe("with captcha enabled", () => {
+      const original = process.env.CAPTCHA_ENABLED;
+      const originalDifficulty = process.env.CAPTCHA_DIFFICULTY;
+
+      beforeEach(() => {
+        process.env.CAPTCHA_ENABLED = "true";
+        process.env.CAPTCHA_DIFFICULTY = "2000";
+      });
+
+      afterAll(() => {
+        if (original === undefined) delete process.env.CAPTCHA_ENABLED;
+        else process.env.CAPTCHA_ENABLED = original;
+        if (originalDifficulty === undefined)
+          delete process.env.CAPTCHA_DIFFICULTY;
+        else process.env.CAPTCHA_DIFFICULTY = originalDifficulty;
+      });
+
+      test("rejects a missing or invalid captcha solution", async () => {
+        const formData = new FormData();
+        formData.append("email", "human@example.com");
+        // No captcha_solution field.
+
+        const request = createBunRequest("http://localhost:3000/login", {
+          method: "POST",
+          body: formData,
+        });
+
+        const response = await login.create(request);
+
+        expect(response.status).toBe(303);
+        const setCookie = findSetCookie(request, "flash_state");
+        expect(setCookie).toContain("validation-error");
+        expect(setCookie).toContain("Verification failed");
+
+        const users =
+          await db`SELECT id FROM users WHERE email = 'human@example.com'`;
+        expect(users).toHaveLength(0);
+      });
+
+      test("issues the magic link when the captcha is solved", async () => {
+        const formData = new FormData();
+        formData.append("email", "human@example.com");
+        formData.append("captcha_solution", solveChallenge(issueChallenge()));
+
+        const request = createBunRequest("http://localhost:3000/login", {
+          method: "POST",
+          body: formData,
+        });
+
+        const response = await login.create(request);
+
+        expect(response.status).toBe(303);
+        const setCookie = findSetCookie(request, "flash_state");
+        expect(setCookie).toContain("email-sent");
+
+        const users =
+          await db`SELECT id FROM users WHERE email = 'human@example.com'`;
+        expect(users).toHaveLength(1);
+      });
+    });
+  });
 });
diff --git a/src/server/controllers/auth/login.tsx b/src/server/controllers/auth/login.tsx
index 2f24b7c..81b17b1 100644
--- a/src/server/controllers/auth/login.tsx
+++ b/src/server/controllers/auth/login.tsx
@@ -1,6 +1,13 @@
 import type { BunRequest } from "bun";
 import { redirectIfAuthenticated } from "../../middleware/auth";
+import { rateLimit } from "../../middleware/rate-limit";
 import { createMagicLink } from "../../services/auth";
+import {
+  captchaEnabled,
+  HONEYPOT_FIELD,
+  issueChallenge,
+  verifyCaptcha,
+} from "../../services/captcha";
 import { getEmailService } from "../../services/email";
 import type { LoginState } from "../../templates/login";
 import { Login } from "../../templates/login";
@@ -15,12 +22,37 @@ export const login = {
     if (authRedirect) return authRedirect;
 
     const state = getFlash(req);
+    const challenge = captchaEnabled() ? issueChallenge() : null;
 
-    return render(<Login state={state} />);
+    return render(<Login state={state} challenge={challenge} />);
   },
 
   async create(req: BunRequest): Promise<Response> {
+    // Layered bot defense, cheapest guard first — each short-circuits.
+    // 1. Rate limit: reject floods before parsing the body. Tighter than the
+    //    default (10/5s) since every request here can send an email.
+    const limited = rateLimit(req, 5, 60_000);
+    if (limited) return limited;
+
     const formData = await req.formData();
+
+    // 2. Honeypot: a filled hidden field means a bot. Feign success — create
+    //    nothing, send nothing — so the bot has no signal to adapt to.
+    if (formData.get(HONEYPOT_FIELD)) {
+      setFlash(req, { state: "email-sent" });
+      return redirect("/login");
+    }
+
+    // 3. Captcha: no-op (passes) when disabled; otherwise the proof of work must
+    //    verify. This is the real defense against automated submissions.
+    if (!verifyCaptcha(formData.get("captcha_solution") as string | null)) {
+      setFlash(req, {
+        state: "validation-error",
+        error: "Verification failed. Please try again.",
+      });
+      return redirect("/login");
+    }
+
     const email = formData.get("email") as string;
 
     if (!email || !email.includes("@")) {
diff --git a/src/server/services/assets.test.ts b/src/server/services/assets.test.ts
index d01594f..bf46342 100644
--- a/src/server/services/assets.test.ts
+++ b/src/server/services/assets.test.ts
@@ -39,6 +39,7 @@ describe("assets (production)", () => {
   beforeAll(() => {
     mkdirSync("dist/assets", { recursive: true });
     writeFileSync("dist/assets/main.js", "console.log('test')");
+    writeFileSync("dist/assets/captcha.js", "console.log('captcha')");
     writeFileSync("dist/assets/main.css", "body { color: red }");
   });
 
diff --git a/src/server/services/assets.ts b/src/server/services/assets.ts
index fd0c120..fe2e591 100644
--- a/src/server/services/assets.ts
+++ b/src/server/services/assets.ts
@@ -2,7 +2,7 @@ import { log } from "./logger";
 
 const assetHashes = new Map<string, string>();
 
-const ASSETS_TO_HASH = ["main.js", "main.css"];
+const ASSETS_TO_HASH = ["main.js", "captcha.js", "main.css"];
 const DIST_ASSETS_PATH = "dist/assets";
 
 export async function initAssets(): Promise<void> {
diff --git a/src/server/services/captcha.test.ts b/src/server/services/captcha.test.ts
new file mode 100644
index 0000000..f4701a6
--- /dev/null
+++ b/src/server/services/captcha.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import {
+  captchaEnabled,
+  clearUsedChallenges,
+  issueChallenge,
+  verifyCaptcha,
+} from "./captcha";
+
+// Solve a challenge the way the client would, returning the base64 payload the
+// server expects. Difficulty is kept tiny in tests so the brute force is instant.
+const solveChallenge = (
+  challenge: ReturnType<typeof issueChallenge>,
+  overrides: Partial<{
+    salt: string;
+    challenge: string;
+    expires: number;
+    signature: string;
+    number: number;
+  }> = {},
+): string => {
+  let answer = 0;
+  for (let n = 0; n <= challenge.maxnumber; n++) {
+    if (
+      createHash("sha256").update(`${challenge.salt}${n}`).digest("hex") ===
+      challenge.challenge
+    ) {
+      answer = n;
+      break;
+    }
+  }
+  const payload = {
+    salt: challenge.salt,
+    challenge: challenge.challenge,
+    expires: challenge.expires,
+    signature: challenge.signature,
+    number: answer,
+    ...overrides,
+  };
+  return Buffer.from(JSON.stringify(payload)).toString("base64");
+};
+
+describe("Captcha Service", () => {
+  const original = {
+    enabled: process.env.CAPTCHA_ENABLED,
+    difficulty: process.env.CAPTCHA_DIFFICULTY,
+  };
+
+  beforeEach(() => {
+    process.env.CAPTCHA_ENABLED = "true";
+    process.env.CAPTCHA_DIFFICULTY = "2000";
+    clearUsedChallenges();
+  });
+
+  afterEach(() => {
+    if (original.enabled === undefined) delete process.env.CAPTCHA_ENABLED;
+    else process.env.CAPTCHA_ENABLED = original.enabled;
+    if (original.difficulty === undefined)
+      delete process.env.CAPTCHA_DIFFICULTY;
+    else process.env.CAPTCHA_DIFFICULTY = original.difficulty;
+    clearUsedChallenges();
+  });
+
+  describe("when disabled", () => {
+    test("captchaEnabled reflects the flag", () => {
+      delete process.env.CAPTCHA_ENABLED;
+      expect(captchaEnabled()).toBe(false);
+    });
+
+    test("verifyCaptcha passes through any payload, even null", () => {
+      delete process.env.CAPTCHA_ENABLED;
+      expect(verifyCaptcha(null)).toBe(true);
+      expect(verifyCaptcha("garbage")).toBe(true);
+    });
+  });
+
+  describe("when enabled", () => {
+    test("captchaEnabled is true", () => {
+      expect(captchaEnabled()).toBe(true);
+    });
+
+    test("accepts a correctly solved challenge", () => {
+      const challenge = issueChallenge();
+      expect(verifyCaptcha(solveChallenge(challenge))).toBe(true);
+    });
+
+    test("rejects a null or malformed payload", () => {
+      expect(verifyCaptcha(null)).toBe(false);
+      expect(verifyCaptcha("")).toBe(false);
+      expect(verifyCaptcha("not-base64-json")).toBe(false);
+      expect(verifyCaptcha(Buffer.from("{}").toString("base64"))).toBe(false);
+    });
+
+    test("rejects a wrong proof-of-work answer", () => {
+      const challenge = issueChallenge();
+      const bad = solveChallenge(challenge, {
+        number: challenge.maxnumber + 7,
+      });
+      expect(verifyCaptcha(bad)).toBe(false);
+    });
+
+    test("rejects a tampered challenge (signature mismatch)", () => {
+      const challenge = issueChallenge();
+      // Flip the target hash without re-signing.
+      const tampered = solveChallenge(challenge, {
+        challenge: `${challenge.challenge.slice(0, -1)}0`,
+      });
+      expect(verifyCaptcha(tampered)).toBe(false);
+    });
+
+    test("rejects a tampered expiry (signature mismatch)", () => {
+      const challenge = issueChallenge();
+      const tampered = solveChallenge(challenge, {
+        expires: challenge.expires + 60_000,
+      });
+      expect(verifyCaptcha(tampered)).toBe(false);
+    });
+
+    test("rejects a past-dated (expired) payload", () => {
+      // Expiry is checked before the signature, so a past `expires` is rejected
+      // outright regardless of the rest of the payload.
+      const challenge = issueChallenge();
+      const expiredPayload = solveChallenge(challenge, {
+        expires: Date.now() - 1000,
+      });
+      expect(verifyCaptcha(expiredPayload)).toBe(false);
+    });
+
+    test("rejects replaying a previously accepted solution", () => {
+      const challenge = issueChallenge();
+      const payload = solveChallenge(challenge);
+      expect(verifyCaptcha(payload)).toBe(true);
+      // Same signature can't be spent twice.
+      expect(verifyCaptcha(payload)).toBe(false);
+    });
+
+    test("issued challenges are unique per call", () => {
+      const a = issueChallenge();
+      const b = issueChallenge();
+      expect(a.salt).not.toBe(b.salt);
+      expect(a.signature).not.toBe(b.signature);
+    });
+  });
+});
diff --git a/src/server/services/captcha.ts b/src/server/services/captcha.ts
new file mode 100644
index 0000000..fcf7c0a
--- /dev/null
+++ b/src/server/services/captcha.ts
@@ -0,0 +1,160 @@
+import { createHash, randomInt } from "node:crypto";
+import { computeHMAC, generateSecureToken, verifyHMAC } from "../utils/crypto";
+
+// First-party proof-of-work captcha. No third party, no account, no new secret:
+// challenges are signed with the app's existing CRYPTO_PEPPER (via computeHMAC),
+// so this is self-hosted and stateless. Modeled on the Altcha protocol but built
+// against Billet's own crypto. Enabled per-app with CAPTCHA_ENABLED=true; when off,
+// verifyCaptcha() passes everything through so callers stay unconditional.
+
+// Shared field names — the login template, controller, and client solver must all
+// agree on these. The client bundle hardcodes the same literals (it cannot import
+// this module, which pulls in node:crypto), and a test cross-checks the two.
+export const HONEYPOT_FIELD = "company_website";
+export const CAPTCHA_SOLUTION_FIELD = "captcha_solution";
+
+// How hard the client has to work: it brute-forces a number in [0, maxnumber].
+// ~100k SHA-256 hashes is sub-second for a real browser but a real cost at spam
+// scale. Tunable per-app with CAPTCHA_DIFFICULTY.
+const DEFAULT_DIFFICULTY = 100_000;
+
+// Generous validity window: the challenge is embedded in the login page render, so
+// this covers a user who leaves the tab open before submitting. A failed verify
+// re-renders a fresh challenge anyway.
+const CHALLENGE_TTL_MS = 30 * 60 * 1000;
+
+const USED_CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+
+export interface CaptchaChallenge {
+  salt: string;
+  challenge: string; // target SHA-256 hex the client must reproduce
+  expires: number; // epoch ms
+  maxnumber: number; // search space size
+  signature: string; // HMAC over `${salt}:${challenge}:${expires}`
+}
+
+interface CaptchaSolution {
+  salt: string;
+  challenge: string;
+  expires: number;
+  signature: string;
+  number: number; // the client's found answer
+}
+
+// Single-use replay guard: a solved signature can only be spent once. Stateless
+// otherwise — mirrors the in-memory map + interval cleanup in rate-limit.ts.
+const usedSignatures = new Map<string, number>();
+
+export const captchaEnabled = (): boolean =>
+  process.env.CAPTCHA_ENABLED === "true";
+
+const difficulty = (): number => {
+  const configured = Number(process.env.CAPTCHA_DIFFICULTY);
+  return Number.isFinite(configured) && configured > 0
+    ? Math.floor(configured)
+    : DEFAULT_DIFFICULTY;
+};
+
+const sha256hex = (value: string): string =>
+  createHash("sha256").update(value).digest("hex");
+
+const signChallenge = (
+  salt: string,
+  challenge: string,
+  expires: number,
+): string => computeHMAC(`${salt}:${challenge}:${expires}`);
+
+// Build a fresh challenge. The answer is never sent to the client — it must be
+// rediscovered by brute force.
+export const issueChallenge = (): CaptchaChallenge => {
+  const maxnumber = difficulty();
+  const salt = generateSecureToken(16);
+  const expires = Date.now() + CHALLENGE_TTL_MS;
+  const answer = randomInt(0, maxnumber + 1);
+  const challenge = sha256hex(`${salt}${answer}`);
+  const signature = signChallenge(salt, challenge, expires);
+  return { salt, challenge, expires, maxnumber, signature };
+};
+
+const parseSolution = (payload: string): CaptchaSolution | null => {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(Buffer.from(payload, "base64").toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof decoded !== "object" || decoded === null) return null;
+  const s = decoded as Record<string, unknown>;
+  if (
+    typeof s.salt !== "string" ||
+    typeof s.challenge !== "string" ||
+    typeof s.signature !== "string" ||
+    typeof s.expires !== "number" ||
+    typeof s.number !== "number"
+  ) {
+    return null;
+  }
+  return {
+    salt: s.salt,
+    challenge: s.challenge,
+    signature: s.signature,
+    expires: s.expires,
+    number: s.number,
+  };
+};
+
+// The security boundary. Returns true only when the payload is a genuine, unexpired,
+// unmodified, actually-solved, not-yet-spent challenge we issued. Passes through
+// (true) when captcha is disabled so callers need no feature check of their own.
+export const verifyCaptcha = (payload: string | null): boolean => {
+  if (!captchaEnabled()) return true;
+  if (!payload) return false;
+
+  const solution = parseSolution(payload);
+  if (!solution) return false;
+
+  const { salt, challenge, expires, signature, number } = solution;
+
+  // 1. Not expired.
+  if (expires <= Date.now()) return false;
+
+  // 2. We issued it and salt/challenge/expires are unmodified (timing-safe).
+  let signatureValid: boolean;
+  try {
+    signatureValid = verifyHMAC(`${salt}:${challenge}:${expires}`, signature);
+  } catch {
+    // Malformed signature (wrong length/non-hex) throws in timingSafeEqual.
+    return false;
+  }
+  if (!signatureValid) return false;
+
+  // 3. The proof of work was actually performed.
+  if (sha256hex(`${salt}${number}`) !== challenge) return false;
+
+  // 4. Single-use: reject replays, then mark spent.
+  if (usedSignatures.has(signature)) return false;
+  usedSignatures.set(signature, expires);
+
+  return true;
+};
+
+const cleanupUsedSignatures = (): void => {
+  const now = Date.now();
+  for (const [signature, expires] of usedSignatures.entries()) {
+    if (expires <= now) usedSignatures.delete(signature);
+  }
+};
+
+// Test seam — clear the replay guard between cases.
+export const clearUsedChallenges = (): void => {
+  usedSignatures.clear();
+};
+
+// Don't let the cleanup timer keep the process (or the test runner) alive. The
+// `unref` guard is because the happy-dom test preload can swap in a browser-style
+// setInterval that returns a plain number with no unref().
+const cleanupTimer: { unref?: () => void } = setInterval(
+  cleanupUsedSignatures,
+  USED_CLEANUP_INTERVAL_MS,
+);
+cleanupTimer.unref?.();
diff --git a/src/server/templates/login.tsx b/src/server/templates/login.tsx
index 240ebd2..98fbeb7 100644
--- a/src/server/templates/login.tsx
+++ b/src/server/templates/login.tsx
@@ -1,7 +1,10 @@
+import { CaptchaWidget } from "../components/captcha-widget";
 import { Flash } from "../components/flash";
 import { FormField } from "../components/form-field";
 import { BaseLayout } from "../components/layouts";
 import { Logo } from "../components/logo";
+import type { CaptchaChallenge } from "../services/captcha";
+import { HONEYPOT_FIELD } from "../services/captcha";
 
 export interface LoginState {
   state?: "email-sent" | "validation-error";
@@ -10,9 +13,10 @@ export interface LoginState {
 
 export interface LoginProps {
   state?: LoginState;
+  challenge?: CaptchaChallenge | null;
 }
 
-export const Login = ({ state }: LoginProps) => {
+export const Login = ({ state, challenge }: LoginProps) => {
   return (
     <BaseLayout
       title="Login - Billet"
@@ -61,6 +65,25 @@ export const Login = ({ state }: LoginProps) => {
                   />
                 </FormField>
 
+                {/* Honeypot — a real field hidden off-screen. Bots fill it; humans
+                    never see it. Submissions with it set are silently discarded. */}
+                <input
+                  type="text"
+                  name={HONEYPOT_FIELD}
+                  tabIndex={-1}
+                  autoComplete="off"
+                  aria-hidden="true"
+                  style={{
+                    position: "absolute",
+                    left: "-9999px",
+                    width: "1px",
+                    height: "1px",
+                    opacity: 0,
+                  }}
+                />
+
+                <CaptchaWidget challenge={challenge} />
+
                 <button type="submit" className="login-submit">
                   Send magic link
                 </button>
diff --git a/src/server/utils/env.ts b/src/server/utils/env.ts
index 958b38f..13584d4 100644
--- a/src/server/utils/env.ts
+++ b/src/server/utils/env.ts
@@ -48,5 +48,12 @@ export function validateEnv(): void {
     process.exit(1);
   }
 
+  // CAPTCHA_ENABLED is optional and self-contained: the proof-of-work captcha signs
+  // challenges with the already-required CRYPTO_PEPPER, so there is no new secret to
+  // conditionally require. Just surface that it's on.
+  if (process.env.CAPTCHA_ENABLED === "true") {
+    log.info("env", "Login captcha enabled (proof-of-work)");
+  }
+
   log.info("env", "Environment variables validated");
 }

From 5b12abfeb88bedf070397b1ba1167b1c1e405cf5 Mon Sep 17 00:00:00 2001
From: Alex Price <github@alexprice.dev>
Date: Tue, 21 Jul 2026 13:00:00 +0100
Subject: [PATCH 2/4] Hide captcha status label visually (screen-reader-only)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The proof of work runs silently, so drop the visible "Verifying…/Verified."
label that cluttered the login form. Kept as an sr-only aria-live region so
assistive tech still gets feedback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/server/components/captcha-widget.tsx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/server/components/captcha-widget.tsx b/src/server/components/captcha-widget.tsx
index bd4f0d8..de0c801 100644
--- a/src/server/components/captcha-widget.tsx
+++ b/src/server/components/captcha-widget.tsx
@@ -35,9 +35,12 @@ export const CaptchaWidget = ({
         data-maxnumber={String(challenge.maxnumber)}
         data-signature={challenge.signature}
         className="captcha-widget"
-        aria-live="polite"
       >
-        <span className="captcha-status">Verifying you're human…</span>
+        {/* No visible label — the proof of work runs silently. Kept as a
+            screen-reader-only live region so assistive tech still gets feedback. */}
+        <span className="captcha-status sr-only" aria-live="polite">
+          Verifying you're human…
+        </span>
       </div>
       <input type="hidden" name={CAPTCHA_SOLUTION_FIELD} />
       <script type="module" src={getAssetUrl("/assets/captcha.js")} defer />

From 1681405bfc209487daa422e080b064412a3514ee Mon Sep 17 00:00:00 2001
From: Alex Price <github@alexprice.dev>
Date: Tue, 21 Jul 2026 19:38:17 +0100
Subject: [PATCH 3/4] docs: document optional login captcha in README

Add the signup-spam defense (honeypot + rate limit + optional proof-of-work
captcha) to the Security feature list, the environment variable table
(CAPTCHA_ENABLED, CAPTCHA_DIFFICULTY), and a setup note.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/README.md b/README.md
index 6ce292d..c6e183c 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,7 @@ A complete magic-link email auth flow: users enter their email, receive a login
 
 - **CSRF protection** using the synchronizer token pattern with timing-safe comparison and origin validation
 - **Rate limiting** middleware with configurable sliding-window limits per IP
+- **Signup spam defense** on the login form — an always-on honeypot and per-IP rate limit, plus an optional first-party proof-of-work captcha (no third party, account, or extra secret; off by default, enable with `CAPTCHA_ENABLED`)
 - **Session fixation prevention** — sessions are regenerated on login
 - **Environment validation** at startup — the server fails fast with clear error messages if required variables are missing
 - **Response hardening** — security headers on every response (nosniff, frame/clickjacking protection, an enforcing Content Security Policy, Permissions-Policy, HSTS in production), plus `/.well-known/security.txt` and Subresource Integrity on third-party scripts — see [runbooks/SECURITY.md](runbooks/SECURITY.md)
@@ -281,6 +282,8 @@ A `railway.json` is included with build and start commands pre-configured. Deplo
 | `CRYPTO_PEPPER` | Yes | Secret key for session tokens — run `bun run generate:pepper` to get one (see below) |
 | `APP_URL` | Yes | Your app's public URL — you'll get this from Railway after your first deploy (e.g. `https://my-app.up.railway.app`) |
 | `PORT` | No | Server port — auto-set by Railway, defaults to `3000` locally |
+| `CAPTCHA_ENABLED` | No | Set to `true` to add a proof-of-work captcha to the login form. Off by default; `/login` is unchanged when unset |
+| `CAPTCHA_DIFFICULTY` | No | Tunes the captcha's client-side work (search-space size). Defaults to `100000` (~sub-second for a real browser) |
 
 > **Generating `CRYPTO_PEPPER`:** This is a secret key used to secure session tokens. Run `bun run generate:pepper` to get a value. Use a different value for each environment (development, production, etc).
 
@@ -290,6 +293,8 @@ A `railway.json` is included with build and start commands pre-configured. Deplo
 
 > **Security:** The HTTP hardening (security headers, CSP, HSTS, SRI) works out of the box, but set `SECURITY_CONTACT` (the `security.txt` reporting address) and add the registrar-level records before launch — see [runbooks/SECURITY.md](runbooks/SECURITY.md) for that plus the TLS, HSTS-preload, CAA, and DNSSEC steps.
 
+> **Signup spam:** The login form always carries a honeypot and per-IP rate limit. If bots still create accounts with random emails, set `CAPTCHA_ENABLED=true` to add a first-party proof-of-work captcha — it signs challenges with your existing `CRYPTO_PEPPER`, so there's no third party, account, or extra secret to configure.
+
 > **Privacy:** The default site needs no cookie banner (zero non-essential storage). The moment you add analytics, ads, or embeds, you must add an opt-in consent banner and a privacy policy — see [runbooks/PRIVACY.md](runbooks/PRIVACY.md) for wiring up `@alexpricedev/billet-cookie-consent`, the required policy disclosures, and GPC handling.
 
 > **CI & merge protection:** CI runs on every PR, but check results are advisory until you require them. A fork doesn't inherit branch protection, so nothing stops an auto-merge (GitHub's or Conductor's) from merging a red build — enable required status checks once per repo. See [runbooks/CI.md](runbooks/CI.md).

From dffcf1f27d74580e9796491aebdf36e37fdcc9ef Mon Sep 17 00:00:00 2001
From: Alex Price <github@alexprice.dev>
Date: Wed, 22 Jul 2026 11:17:19 +0100
Subject: [PATCH 4/4] Added new captcha mention to home

---
 src/server/templates/home.tsx | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/server/templates/home.tsx b/src/server/templates/home.tsx
index 742609a..f9b640b 100644
--- a/src/server/templates/home.tsx
+++ b/src/server/templates/home.tsx
@@ -155,8 +155,9 @@ export const Home = ({ user, csrfToken }: HomeProps) => (
         <div className="feature-card">
           <h3>Security</h3>
           <p>
-            CSRF protection, rate limiting, a Content Security Policy, HSTS, and
-            security headers on every response
+            CSRF protection, rate limiting, an optional proof-of-work captcha, a
+            Content Security Policy, HSTS, and security headers on every
+            response
           </p>
         </div>
         <div className="feature-card">