@openparachute/hub 0.7.3-rc.1 → 0.7.3-rc.10

package/src/__tests__/wizard.test.ts

@@ -293,6 +293,29 @@ describe("parseWizardArgs", () => {
     expect(r.opts.vaultMode).toBe("import");
     expect(r.opts.vaultImportRemoteUrl).toBe("https://github.com/me/v.git");
   });
+
+  test("parses --transcribe-mode + --transcribe-key + --config-dir", () => {
+    const r = parseWizardArgs([
+      "--hub-url",
+      "http://x",
+      "--transcribe-mode",
+      "groq",
+      "--transcribe-key",
+      "gsk_test",
+      "--config-dir",
+      "/tmp/ph",
+    ]);
+    expect("error" in r).toBe(false);
+    if ("error" in r) throw new Error(r.error);
+    expect(r.opts.transcribeMode).toBe("groq");
+    expect(r.opts.transcribeApiKey).toBe("gsk_test");
+    expect(r.opts.configDir).toBe("/tmp/ph");
+  });
+
+  test("rejects invalid --transcribe-mode", () => {
+    const r = parseWizardArgs(["--hub-url", "http://x", "--transcribe-mode", "garbage"]);
+    expect("error" in r).toBe(true);
+  });
 });
 
 describe("runCliWizard", () => {
@@ -509,4 +532,127 @@ describe("runCliWizard", () => {
     });
     expect(code).toBe(1);
   });
+
+  test("password validator floor is 12 (matches the server) — an 11-char password is rejected", async () => {
+    const { fetchImpl } = makeFakeHub();
+    const logs: string[] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: (l) => logs.push(l),
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "elevenchar.", // 11 chars
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(1);
+    expect(logs.join("\n")).toContain("at least 12 characters");
+  });
+
+  test("exactly 12 chars passes the validator (no early bounce)", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "twelvecharss", // 12 chars
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(0);
+    expect(state.posted.some((p) => p.path === "/admin/setup/account")).toBe(true);
+  });
+
+  test("transcription step runs between vault and expose when configDir is set", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    const transcribeCmds: string[][] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      configDir: "/tmp/never-written-none-mode",
+      transcribeMode: "none", // none writes nothing + spawns nothing
+      transcribeRunCommand: async (cmd) => {
+        transcribeCmds.push([...cmd]);
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    // The vault + expose POSTs still happened in order.
+    expect(state.posted.map((p) => p.path)).toEqual([
+      "/admin/setup/account",
+      "/admin/setup/vault",
+      "/admin/setup/expose",
+    ]);
+    // mode=none → no transcription subprocess.
+    expect(transcribeCmds).toEqual([]);
+  });
+
+  test("transcription step (cloud) drives the install one-shot via the injected runner", async () => {
+    const { fetchImpl } = makeFakeHub();
+    const transcribeCmds: string[][] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      configDir: "/tmp/never-written-cloud-mode",
+      transcribeMode: "groq",
+      transcribeApiKey: "gsk_wired",
+      platform: "linux",
+      transcribeRunCommand: async (cmd) => {
+        transcribeCmds.push([...cmd]);
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    expect(transcribeCmds[0]).toEqual([
+      "parachute",
+      "install",
+      "scribe",
+      "--scribe-provider",
+      "groq",
+      "--scribe-key",
+      "gsk_wired",
+    ]);
+  });
+
+  test("transcription step is skipped when configDir is absent", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    let ran = false;
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      // no configDir
+      transcribeRunCommand: async () => {
+        ran = true;
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    expect(ran).toBe(false);
+    expect(state.posted.map((p) => p.path)).toEqual([
+      "/admin/setup/account",
+      "/admin/setup/vault",
+      "/admin/setup/expose",
+    ]);
+  });
 });

package/src/account-setup.ts

@@ -6,10 +6,21 @@
  * account-claim flow (`setup-wizard.ts` `handleSetupAccountPost`). A brand-new
  * invitee opens the link with no session and no JS:
  *
- *   GET  → render the "pick username + password (+ vault name)" form.
+ * MULTI-USE (v15, DEMO-PREP-2026-06-25 Workstream B): this same surface is the
+ * PUBLIC SIGNUP PAGE (B4). A multi-use invite link (`max_uses > 1`) lets many
+ * strangers redeem the one link until its seats run out — each redeem creates
+ * a fresh account + vault. Such a link also collects the redeemer's EMAIL (B2,
+ * so the operator can reach signups) and STAMPS a per-vault storage cap (B4)
+ * onto each provisioned vault. A legacy single-use admin/friends invite
+ * (`max_uses = 1`, the default) behaves exactly as before — no email field, no
+ * cap, single redeem.
+ *
+ *   GET  → render the "pick username + password (+ email, + vault name)" form.
  *   POST → redeem: look up the invite by sha256(token), validate it's still
- *          redeemable, validate credentials, provision the vault, create the
- *          user, stamp the invite used, mint a session, 302 → /account/.
+ *          redeemable (seats left, not expired/revoked), validate credentials
+ *          (+ email for public links), provision the vault (stamping its cap),
+ *          create the user, record the redemption (bump used_count, capture
+ *          email), mint a session, 302 → /account/.
  *
  * Redeem ORDERING (the re-usability guarantee, mirroring the wizard):
  *   1. lookup + validate the invite (not-found/expired/used/revoked)
@@ -27,14 +38,17 @@
  *        The vault must still exist in services.json (the vault-delete
  *        cascade revokes pending invites, so this re-check is defense in
  *        depth against manual manifest edits).
- *   4. createUser (the commit point)
- *   5. consumeInvite — stamp used_at + redeemed_user_id ONLY AFTER (4) commits
- *   6. createSession + cookie + 302
+ *   4. createUser (the commit point) — and INSIDE its transaction (the
+ *      `withinTx` hook): recordInviteRedemption (bump used_count + stamp
+ *      used_at/email/redeemed_user_id) AND, for a capped provisioning link,
+ *      setVaultCap. All three commit atomically with the user row.
+ *   5. createSession + cookie + 302
  *
- * Because the invite is consumed only after the user row commits, a
- * createUser exception (UNIQUE collision, disk full, anything) leaves the
- * invite re-usable — the invitee can simply retry. `consumeInvite`'s
- * `used_at IS NULL` guard makes the stamp itself single-use / race-free.
+ * Because the redemption is recorded only inside the user-row transaction, a
+ * createUser exception (UNIQUE collision, disk full, anything) rolls back the
+ * used_count bump + cap write together — the seat stays available and the
+ * invitee can simply retry. `recordInviteRedemption`'s `used_count < max_uses`
+ * guard makes the increment itself exhaustion-safe / race-free.
  *
  * What an invite pre-authorizes: EXACTLY one account + the one named/created/
  * shared vault at the baked-in role — NEVER host:admin, NEVER another vault.
@@ -53,14 +67,15 @@ import { type RunResult, provisionVault } from "./admin-vaults.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import {
+  InviteExhaustedError,
   InviteExpiredError,
   InviteNotFoundError,
   InviteRevokedError,
   InviteUsedError,
   assertInviteRedeemable,
-  consumeInvite,
+  recordInviteRedemption,
 } from "./invites.ts";
-import { checkAndRecord, clientIpFromRequest } from "./rate-limit.ts";
+import { clientIpFromRequest, signupRateLimiter } from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { SESSION_TTL_MS, buildSessionCookie, createSession } from "./sessions.ts";
 import {
@@ -68,9 +83,11 @@ import {
   UsernameTakenError,
   createUser,
   getUserByUsernameCI,
+  validateEmail,
   validatePassword,
   validateUsername,
 } from "./users.ts";
+import { setVaultCap } from "./vault-caps.ts";
 import { validateVaultName } from "./vault-name.ts";
 import { listVaultNamesFromPath } from "./vault-names.ts";
 
@@ -127,6 +144,16 @@ function rejectInvite(err: unknown): Response {
       410,
     );
   }
+  if (err instanceof InviteExhaustedError) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Signups closed",
+        message:
+          "This signup link has reached its maximum number of accounts. Ask your hub operator for a new link.",
+      }),
+      410,
+    );
+  }
   if (err instanceof InviteRevokedError) {
     return htmlResponse(
       renderAdminError({
@@ -166,12 +193,25 @@ export function handleAccountSetupGet(
       pinnedUsername: invite.username,
       role: invite.role,
       provisionVault: invite.provisionVault,
+      collectEmail: collectsEmail(invite),
     }),
     200,
     setCookie,
   );
 }
 
+/**
+ * Whether this redemption captures the redeemer's email (B2). Multi-use
+ * public-signup links collect it (the operator must be able to reach the
+ * stranger who signed up); legacy single-use admin invites don't bother
+ * (the admin already knows who they handed the link to). The signal: a
+ * multi-use link (`max_uses > 1`). Public-signup links always mint with
+ * `max_uses > 1`, so this cleanly distinguishes them from the friends flow.
+ */
+function collectsEmail(invite: { maxUses: number }): boolean {
+  return invite.maxUses > 1;
+}
+
 /** POST /account/setup/<token> — redeem the invite (see file docstring for ordering). */
 export async function handleAccountSetupPost(
   req: Request,
@@ -201,11 +241,15 @@ export async function handleAccountSetupPost(
     );
   }
 
-  // Rate limit — reuse the /login IP bucket so a redeem flood and a login
-  // flood share the same throttle. After CSRF (so a junk cross-site POST
-  // doesn't burn the bucket), before any account/vault work.
+  // Rate limit — a DEDICATED signup bucket (per-IP, 60/15min), NOT the /login
+  // bucket. A public multi-use signup link is redeemed by a room of people
+  // sharing one NAT'd egress IP, so the /login-sized 5/15min cap would 429 the
+  // ~6th legitimate signer mid-demo. Generous-but-bounded: the invite's own
+  // max_uses + expiry are the primary bound; this is the abuse floor. After
+  // CSRF (so a junk cross-site POST doesn't burn the bucket), before any
+  // account/vault work.
   const clientIp = clientIpFromRequest(req);
-  const gate = checkAndRecord(clientIp, now);
+  const gate = signupRateLimiter.checkAndRecord(clientIp, now);
   if (!gate.allowed) {
     return htmlResponse(
       renderAdminError({
@@ -223,6 +267,10 @@ export async function handleAccountSetupPost(
     invite.username !== null ? invite.username : String(form.get("username") ?? "").trim();
   const password = String(form.get("password") ?? "");
   const confirm = String(form.get("password_confirm") ?? "");
+  // Email (B2) — captured only for public-signup links (multi-use). The raw
+  // value is echoed back on a re-render so the redeemer doesn't retype it.
+  const collectEmail = collectsEmail(invite);
+  const emailRaw = String(form.get("email") ?? "").trim();
 
   const csrf = ensureCsrfToken(req);
   const setCookie: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
@@ -236,7 +284,9 @@ export async function handleAccountSetupPost(
         pinnedUsername: invite.username,
         role: invite.role,
         provisionVault: invite.provisionVault,
+        collectEmail,
         username,
+        ...(collectEmail ? { email: emailRaw } : {}),
         ...(vaultNameEcho !== undefined ? { vaultName: vaultNameEcho } : {}),
         errorMessage: message,
       }),
@@ -266,6 +316,21 @@ export async function handleAccountSetupPost(
   if (password !== confirm) {
     return rerender(400, "The two passwords don't match.");
   }
+  // (2b) Email (B2) — required + format-validated ONLY for public-signup
+  // (multi-use) links, where the operator must be able to reach the stranger
+  // who signed up. Legacy single-use admin invites don't collect it. The
+  // canonical form is lowercased/trimmed by validateEmail.
+  let email: string | null = null;
+  if (collectEmail) {
+    if (emailRaw.length === 0) {
+      return rerender(400, "Enter your email so the hub operator can reach you.");
+    }
+    const e = validateEmail(emailRaw);
+    if (!e.valid) {
+      return rerender(400, "Enter a valid email address (e.g. you@example.com).");
+    }
+    email = e.email;
+  }
   // Case-insensitive uniqueness — same gate as /api/users. For a pre-named
   // invite the name can't be changed by the invitee, so a collision (someone
   // took the name between mint and redeem) needs the operator to revoke +
@@ -393,22 +458,33 @@ export async function handleAccountSetupPost(
           : undefined,
       );
     }
+
+    // NOTE: the per-vault storage cap (B4) is PERSISTED below, inside
+    // createUser's transaction (the `withinTx` hook), so the cap write +
+    // redemption record + user insert all commit (or roll back) atomically —
+    // no stranded cap row for a vault whose account creation failed. The
+    // vault itself is provisioned here (the CLI shell-out can't join the
+    // sqlite tx), but the cap METADATA is hub-DB state, so it belongs in the
+    // atomic hook.
   }
 
-  // (4) Create the user + consume the invite ATOMICALLY — the COMMIT POINT.
-  // The invite is consumed INSIDE createUser's transaction (the `withinTx`
-  // hook), so the two single-use guarantees compose:
+  // (4) Create the user + record the redemption ATOMICALLY — the COMMIT POINT.
+  // The redemption is recorded INSIDE createUser's transaction (the `withinTx`
+  // hook), so the seat-accounting guarantees compose:
   //
-  //   - Single-use under concurrency: two redeems of one invite both pass
-  //     `assertInviteRedeemable` above, but only one's `consumeInvite` UPDATE
-  //     (`used_at IS NULL AND revoked_at IS NULL`) changes a row. The loser's
-  //     hook throws `InviteUsedError`, which rolls back ITS user insert — no
-  //     orphan account. Exactly one account results.
+  //   - Exhaustion under concurrency: two redeems of the LAST seat both pass
+  //     `assertInviteRedeemable` above, but only one's `recordInviteRedemption`
+  //     UPDATE (`used_count < max_uses AND revoked_at IS NULL`) changes a row.
+  //     The loser's hook throws (InviteExhaustedError for a multi-use link,
+  //     InviteUsedError for single-use), which rolls back ITS user insert — no
+  //     orphan account. Exactly one account per remaining seat results.
   //   - Re-usable on failure: if createUser throws (UNIQUE collision, etc.)
-  //     before the hook, the invite was never touched; if the hook itself
-  //     throws (lost race), the consume + the user insert roll back together.
-  //     Either way nothing commits, so the invite stays re-usable.
+  //     before the hook, used_count was never bumped; if the hook itself
+  //     throws (lost race), the increment + the user insert roll back together.
+  //     Either way nothing commits, so the seat stays available.
   //
+  // The email (B2) is recorded with the redemption (latest redeemer) AND on
+  // the account row (`users.email`, the canonical per-account field) below.
   // passwordChanged: TRUE (the invitee chose their own password → no force-
   // change). assignedVaults pins them to exactly their one vault at the
   // invite's role. allowMulti because the first admin already exists.
@@ -419,17 +495,27 @@ export async function handleAccountSetupPost(
       passwordChanged: true,
       assignedVaults: vaultName !== null ? [vaultName] : [],
       role: invite.role,
+      ...(email !== null ? { email } : {}),
       withinTx: (newUserId) => {
-        if (!consumeInvite(deps.db, invite.tokenHash, newUserId, now)) {
-          // Lost the redeem race (or a concurrent revoke landed). Throw to
-          // roll back this user insert; surfaced as the used/410 path below.
-          throw new InviteUsedError();
+        if (!recordInviteRedemption(deps.db, invite.tokenHash, newUserId, email, now)) {
+          // Lost the redeem race (or a concurrent revoke landed). Throw the
+          // shape-appropriate error to roll back this user insert; surfaced
+          // as the 410 path below.
+          throw invite.maxUses > 1 ? new InviteExhaustedError() : new InviteUsedError();
+        }
+        // (3b) Persist the per-vault storage cap (B4) atomically with the
+        // account + redemption. Only for a freshly-provisioned vault carrying
+        // an invite cap; legacy/uncapped links leave the vault with no
+        // vault_caps row ("uncapped" for the Phase-2 reader). The vault was
+        // confirmed freshly created above; `setVaultCap` is a plain upsert.
+        if (invite.provisionVault && vaultName !== null && invite.vaultCapBytes !== null) {
+          setVaultCap(deps.db, vaultName, invite.vaultCapBytes, now);
         }
       },
     });
     userId = created.id;
   } catch (err) {
-    if (err instanceof InviteUsedError) {
+    if (err instanceof InviteUsedError || err instanceof InviteExhaustedError) {
       return rejectInvite(err);
     }
     if (err instanceof UsernameTakenError) {

package/src/admin-agent-grants.ts

@@ -80,6 +80,7 @@ import {
 } from "./jwt-sign.ts";
 import { type OAuthClient, deriveVaultScopeFromMcpUrl, realOAuthClient } from "./oauth-client.ts";
 import { type PendingFlow, deleteFlow, getFlowByState, putFlow } from "./oauth-flows-store.ts";
+import { isSafeHubReturnTo } from "./oauth-handlers.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
 import { validateVaultName } from "./vault-name.ts";
@@ -630,10 +631,15 @@ async function approveGrant(req: Request, id: string, deps: AgentGrantsDeps): Pr
   const grant = getGrant(deps.storePath, id);
   if (!grant) return jsonError(404, "not_found", `no grant ${id}`);
 
-  let body: { token?: unknown } = {};
+  // `returnTo` is consumed ONLY by the mcp/OAuth path (approveMcpGrant), which
+  // is the one approve flow that hands the browser off to a remote consent
+  // screen and needs somewhere to land on return. vault/service approvals
+  // complete synchronously and return JSON — there's no redirect, so they
+  // ignore `returnTo` by design.
+  let body: { token?: unknown; returnTo?: unknown } = {};
   try {
     const raw = await req.text();
-    if (raw.trim().length > 0) body = JSON.parse(raw) as { token?: unknown };
+    if (raw.trim().length > 0) body = JSON.parse(raw) as { token?: unknown; returnTo?: unknown };
   } catch {
     return jsonError(400, "invalid_request", "body must be JSON when present");
   }
@@ -748,7 +754,7 @@ async function approveGrant(req: Request, id: string, deps: AgentGrantsDeps): Pr
  */
 async function approveMcpGrant(
   grant: GrantRecord,
-  body: { token?: unknown },
+  body: { token?: unknown; returnTo?: unknown },
   deps: AgentGrantsDeps,
   approvedAt: string,
 ): Promise<Response> {
@@ -850,6 +856,16 @@ async function approveMcpGrant(
       ? discovery.scopesSupported.join(" ")
       : undefined;
 
+  // OPTIONAL `returnTo` — the same-origin (hub-relative) page the operator
+  // started from (the agent ops surface / admin grants page). Stash it on the
+  // flow ONLY when it passes the shared open-redirect guard; absent/invalid →
+  // omit it (the callback then renders the back-compat close-tab page). This is
+  // the open-redirect-load-bearing check — reuse, don't reinvent.
+  const returnTo =
+    typeof body.returnTo === "string" && isSafeHubReturnTo(body.returnTo)
+      ? body.returnTo
+      : undefined;
+
   const flow: PendingFlow = {
     state,
     grantId: grant.id,
@@ -861,6 +877,7 @@ async function approveMcpGrant(
     mcpUrl,
     ...(scope ? { scope } : {}),
     redirectUri,
+    ...(returnTo ? { returnTo } : {}),
     createdAt: (deps.now?.() ?? new Date()).toISOString(),
   };
   putFlow(deps.flowsStorePath, flow, (deps.now?.() ?? new Date()).getTime());
@@ -1040,6 +1057,17 @@ export async function handleOAuthGrantCallback(
   // NEVER log a token.
   console.log(`agent grant approved: id=${grant.id} agent=${grant.agent} kind=mcp mode=oauth`);
 
+  // If the operator started from a hub page (agent ops surface / admin grants),
+  // send them back there instead of a dead-end "close this tab" screen. Re-run
+  // the open-redirect guard DEFENSIVELY at redirect time (the value was already
+  // gated at stash time; this is belt-and-suspenders against a tampered store).
+  // Append `?mcp_connected=1` (preserving any existing query) so the SPA can
+  // react (toast / refetch the grant). Absent/invalid returnTo → the
+  // back-compat close-tab page.
+  if (flow.returnTo && isSafeHubReturnTo(flow.returnTo)) {
+    return redirectToReturn(flow.returnTo);
+  }
+
   return htmlPage(
     200,
     "Connected",
@@ -1047,6 +1075,26 @@ export async function handleOAuthGrantCallback(
   );
 }
 
+/**
+ * 302 back to a same-origin (hub-relative) `returnTo`, appending
+ * `mcp_connected=1` so the SPA can show a success toast / refetch. The caller
+ * MUST have already passed `returnTo` through `isSafeHubReturnTo` — this builds
+ * the URL against a fixed dummy origin purely to merge the query param
+ * correctly, then emits only the path+query (never the origin), so a
+ * scheme-relative value can't leak through into the Location header.
+ */
+function redirectToReturn(returnTo: string): Response {
+  // Parse against a fixed base so query-string merging is correct even when
+  // returnTo already carries `?...`. Only `pathname + search + hash` is emitted.
+  const u = new URL(returnTo, "http://hub.invalid");
+  u.searchParams.set("mcp_connected", "1");
+  const location = `${u.pathname}${u.search}${u.hash}`;
+  return new Response(null, {
+    status: 302,
+    headers: { location, "cache-control": "no-store" },
+  });
+}
+
 /** Minimal server-rendered HTML — NEVER carries a token. */
 function htmlPage(status: number, heading: string, message: string): Response {
   const html = `<!doctype html>

package/src/admin-handlers.ts

@@ -21,7 +21,13 @@ import {
   getPendingLogin,
   parsePendingLoginCookie,
 } from "./pending-login.ts";
-import { checkAndRecord, clientIpFromRequest, totpRateLimiter } from "./rate-limit.ts";
+import {
+  authIpCeilingRateLimiter,
+  clientIpFromRequest,
+  compositeKey,
+  loginRateLimiter,
+  totpRateLimiter,
+} from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import {
   SESSION_TTL_MS,
@@ -167,24 +173,42 @@ export async function handleAdminLoginPost(
     );
   }
   // Rate-limit gate fires *after* CSRF (so a junk cross-site POST doesn't
-  // burn a bucket slot for the victim's IP) but *before* credential check.
+  // burn a bucket slot for the victim) but *before* credential check.
   // Every legitimate login attempt — wrong password, missing user, eventually
-  // failed-2FA (#186) — counts toward the same bucket so an attacker can't
-  // partition the cooldown across stages.
+  // failed-2FA — counts toward the same bucket so an attacker can't partition
+  // the cooldown across stages.
+  //
+  // Two tiers (the shared-egress-IP fix): a coarse per-IP CEILING (60/15min)
+  // backstops username-rotation, then a per-(ip,username) FLOOR (5/15min) so
+  // each account behind a shared NAT / Cloudflare egress IP gets its own
+  // bucket instead of the whole room pooling into one 5-slot per-IP bucket.
+  // `username` is hoisted above the gate because the floor keys on it. The same
+  // `loginRateLimiter` + `compositeKey(ip, username)` scheme backs the
+  // `/oauth/authorize` password door, so both doors share ONE per-account
+  // bucket.
+  const username = String(form.get("username") ?? "");
   const clientIp = clientIpFromRequest(req);
   const now = deps.now ? deps.now() : new Date();
-  const gate = checkAndRecord(clientIp, now);
-  if (!gate.allowed) {
+  // Both checks always run (no short-circuit): a denied `checkAndRecord` does
+  // NOT append a timestamp, so running the floor after a denied ceiling never
+  // double-counts. We need both recorded so each independently tracks its own
+  // bucket (the floor still gates per-account even when the ceiling is fine).
+  const ceiling = authIpCeilingRateLimiter.checkAndRecord(clientIp, now);
+  const floor = loginRateLimiter.checkAndRecord(compositeKey(clientIp, username), now);
+  if (!ceiling.allowed || !floor.allowed) {
+    const retryAfterSeconds = Math.max(
+      ceiling.allowed ? 0 : (ceiling.retryAfterSeconds ?? 1),
+      floor.allowed ? 0 : (floor.retryAfterSeconds ?? 1),
+    );
     return htmlResponse(
       renderAdminError({
         title: "Too many login attempts",
-        message: `Too many login attempts from this IP. Try again in ${gate.retryAfterSeconds ?? 1} seconds.`,
+        message: `Too many login attempts. Try again in ${retryAfterSeconds} seconds.`,
       }),
       429,
-      { "retry-after": String(gate.retryAfterSeconds ?? 1) },
+      { "retry-after": String(retryAfterSeconds) },
     );
   }
-  const username = String(form.get("username") ?? "");
   const password = String(form.get("password") ?? "");
   const next = safeNext(String(form.get("next") ?? ""));
   const csrfToken = typeof formCsrf === "string" ? formCsrf : "";
@@ -314,23 +338,36 @@ export async function handleAdminLoginTotpPost(
   const next = safeNext(String(form.get("next") ?? ""));
   const code = String(form.get("code") ?? "");
 
-  // Rate-limit BEFORE resolving the pending login or verifying the factor.
+  // Rate-limit BEFORE verifying the factor. Resolve the pending login FIRST so
+  // the per-account floor can key on the STABLE userId (NOT the pendingToken,
+  // which a fresh /login success rotates and would reset the bucket). Resolving
+  // here also lets a bad/expired pending token fall back to keying the floor by
+  // IP alone — never by the rotating pendingToken.
   const clientIp = clientIpFromRequest(req);
   const now = deps.now ? deps.now() : new Date();
-  const gate = totpRateLimiter.checkAndRecord(clientIp, now);
-  if (!gate.allowed) {
+  const pendingToken = parsePendingLoginCookie(req.headers.get("cookie"));
+  const pending = getPendingLogin(pendingToken, () => now);
+  // Two tiers (the shared-egress-IP fix): coarse per-IP CEILING (60/15min) +
+  // per-(ip,userId) FLOOR (5/15min). When userId can't be resolved (bad/expired
+  // pending token), key the floor by IP alone — do NOT key by the pendingToken.
+  const ceiling = authIpCeilingRateLimiter.checkAndRecord(clientIp, now);
+  const floorKey = pending ? compositeKey(clientIp, pending.userId) : clientIp;
+  const floor = totpRateLimiter.checkAndRecord(floorKey, now);
+  if (!ceiling.allowed || !floor.allowed) {
+    const retryAfterSeconds = Math.max(
+      ceiling.allowed ? 0 : (ceiling.retryAfterSeconds ?? 1),
+      floor.allowed ? 0 : (floor.retryAfterSeconds ?? 1),
+    );
     return htmlResponse(
       renderAdminError({
         title: "Too many attempts",
-        message: `Too many verification attempts from this IP. Try again in ${gate.retryAfterSeconds ?? 1} seconds.`,
+        message: `Too many verification attempts. Try again in ${retryAfterSeconds} seconds.`,
       }),
       429,
-      { "retry-after": String(gate.retryAfterSeconds ?? 1) },
+      { "retry-after": String(retryAfterSeconds) },
     );
   }
 
-  const pendingToken = parsePendingLoginCookie(req.headers.get("cookie"));
-  const pending = getPendingLogin(pendingToken, () => now);
   if (!pending) {
     // No live pending login — expired, missing, or tampered. Send the user
     // back to the start; clear any stale pending cookie.