@openparachute/hub 0.7.3-rc.3 → 0.7.3-rc.5

package/src/__tests__/rate-limit.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import {
+  AUTH_IP_CEILING_MAX_ATTEMPTS,
   CHANGE_PASSWORD_MAX_ATTEMPTS,
   CHANGE_PASSWORD_WINDOW_MS,
   MAX_ATTEMPTS,
@@ -7,9 +8,12 @@ import {
   UNKNOWN_IP_SENTINEL,
   WINDOW_MS,
   __resetForTests,
+  authIpCeilingRateLimiter,
   changePasswordRateLimiter,
   checkAndRecord,
   clientIpFromRequest,
+  compositeKey,
+  loginRateLimiter,
 } from "../rate-limit.ts";
 
 afterEach(() => {
@@ -302,3 +306,85 @@ describe("changePasswordRateLimiter — tighter floor for /account/change-passwo
     expect(changePasswordRateLimiter.checkAndRecord("user-a", now).allowed).toBe(true);
   });
 });
+
+// The shared-egress-IP fix: the per-account FLOOR is now keyed by
+// `compositeKey(ip, identity)` so a room of users behind ONE NAT'd /
+// Cloudflare egress IP doesn't pool into one 5-slot bucket. A coarse per-IP
+// CEILING (60/15min) backstops username-rotation across the floors.
+describe("compositeKey + shared-egress-IP login floor", () => {
+  test("normalizes identity: trims + lowercases so casing/whitespace share a bucket", () => {
+    expect(compositeKey("1.2.3.4", "Alice")).toBe("1.2.3.4|alice");
+    expect(compositeKey("1.2.3.4", "  ALICE  ")).toBe("1.2.3.4|alice");
+    // Case-flip evasion is closed: 'Alice' and 'alice' resolve to one key.
+    expect(compositeKey("1.2.3.4", "Alice")).toBe(compositeKey("1.2.3.4", "alice"));
+  });
+
+  // (a) REGRESSION: two distinct usernames from the SAME ip each get a full
+  // independent 5/15min floor (the shared-wifi bug). Before the fix both would
+  // have pooled into one per-IP bucket and the second user's 1st attempt would
+  // have been the 6th overall → 429.
+  test("(a) two usernames from the same IP each get an independent 5/15min floor", () => {
+    const ip = "203.0.113.7";
+    const now = new Date("2026-06-25T12:00:00Z");
+    // Alice exhausts her floor.
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now).allowed).toBe(true);
+    }
+    expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now).allowed).toBe(false);
+    // Bob (same IP, different username) still has a fresh full floor.
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "bob"), now).allowed).toBe(true);
+    }
+    expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "bob"), now).allowed).toBe(false);
+  });
+
+  // (b) a single (ip,username) still denies on the 6th attempt.
+  test("(b) a single (ip,username) still denies on the 6th attempt", () => {
+    const ip = "203.0.113.7";
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now).allowed).toBe(true);
+    }
+    const denied = loginRateLimiter.checkAndRecord(compositeKey(ip, "alice"), now);
+    expect(denied.allowed).toBe(false);
+    expect(denied.retryAfterSeconds).toBe(WINDOW_MS / 1000);
+  });
+
+  // (c) the per-IP ceiling denies on the 61st attempt from one IP even across
+  // rotated usernames (each username's own floor never trips because each only
+  // sees one attempt, but the coarse ceiling caps total per-IP volume).
+  test("(c) per-IP ceiling denies the 61st attempt across rotated usernames", () => {
+    const ip = "203.0.113.7";
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < AUTH_IP_CEILING_MAX_ATTEMPTS; i++) {
+      // Rotate a fresh username every attempt so no per-account floor ever fills.
+      expect(loginRateLimiter.checkAndRecord(compositeKey(ip, `u${i}`), now).allowed).toBe(true);
+      expect(authIpCeilingRateLimiter.checkAndRecord(ip, now).allowed).toBe(true);
+    }
+    // 61st attempt: a brand-new username (floor is fresh) but the ceiling is full.
+    expect(loginRateLimiter.checkAndRecord(compositeKey(ip, "u60"), now).allowed).toBe(true);
+    const ceilingDenied = authIpCeilingRateLimiter.checkAndRecord(ip, now);
+    expect(ceilingDenied.allowed).toBe(false);
+    expect(ceilingDenied.retryAfterSeconds).toBe(WINDOW_MS / 1000);
+  });
+
+  test("the ceiling is per-IP: a different IP is unaffected by another's full ceiling", () => {
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < AUTH_IP_CEILING_MAX_ATTEMPTS; i++) {
+      authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now);
+    }
+    expect(authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now).allowed).toBe(false);
+    expect(authIpCeilingRateLimiter.checkAndRecord("198.51.100.99", now).allowed).toBe(true);
+  });
+
+  test("ceiling matches the signup precedent (60) and `__resetForTests` clears it", () => {
+    expect(AUTH_IP_CEILING_MAX_ATTEMPTS).toBe(60);
+    const now = new Date("2026-06-25T12:00:00Z");
+    for (let i = 0; i < AUTH_IP_CEILING_MAX_ATTEMPTS; i++) {
+      authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now);
+    }
+    expect(authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now).allowed).toBe(false);
+    __resetForTests();
+    expect(authIpCeilingRateLimiter.checkAndRecord("203.0.113.7", now).allowed).toBe(true);
+  });
+});

package/src/__tests__/two-factor-flow.test.ts

@@ -332,6 +332,100 @@ describe("login two-step (TOTP) — hub#473", () => {
     expect(denied.status).toBe(429);
     expect(denied.headers.get("retry-after")).not.toBeNull();
   });
+
+  // Fallback path: when the pending login can't be resolved (bad/expired
+  // token), the floor keys by IP ALONE — NOT the (rotating) pendingToken.
+  // Proven here by sending a DIFFERENT bogus pending cookie on every attempt
+  // from one IP: if the floor keyed by the token each would get a fresh bucket
+  // and never 429; keying by IP, the 6th still trips.
+  test("2FA floor with unresolvable pending tokens keys by IP, not the token", async () => {
+    const buildReq = (bogusToken: string) => {
+      const tf = formBody({ [CSRF_FIELD_NAME]: TEST_CSRF, code: "000000", next: "/admin/vaults" });
+      return new Request("http://hub.test/login/2fa", {
+        method: "POST",
+        headers: {
+          ...tf.headers,
+          cookie: `${CSRF_COOKIE}; ${PENDING_LOGIN_COOKIE_NAME}=${bogusToken}`,
+          "cf-connecting-ip": "203.0.113.77",
+        },
+        body: tf.body,
+      });
+    };
+    for (let i = 0; i < 5; i++) {
+      // A unique bogus token per attempt → never resolves to a pending login.
+      const r = await handleAdminLoginTotpPost(harness.db, buildReq(`bogus-${i}`));
+      expect(r.status).toBe(401); // no pending login → 401, counts toward the IP floor
+    }
+    const denied = await handleAdminLoginTotpPost(harness.db, buildReq("bogus-final"));
+    expect(denied.status).toBe(429);
+    expect(denied.headers.get("retry-after")).not.toBeNull();
+  });
+
+  // (d) The 2FA floor is keyed by (ip,userId), NOT the rotating pendingToken.
+  // Re-POSTing /login mints a FRESH pendingToken for the SAME user — that must
+  // NOT reset the per-account TOTP floor (otherwise an attacker grinds TOTP
+  // forever by re-doing the password step between every 5 code attempts).
+  test("(d) re-POSTing /login (new pendingToken) does NOT reset the per-account TOTP floor", async () => {
+    const u = await createUser(harness.db, "owner", "owner-password-123", {
+      passwordChanged: true,
+    });
+    await persistEnrollment(harness.db, u.id, generateTotpSecret("owner").secret);
+    const ATTACK_IP = "203.0.113.66";
+
+    const passwordPost = async (): Promise<string> => {
+      const pw = formBody({
+        [CSRF_FIELD_NAME]: TEST_CSRF,
+        username: "owner",
+        password: "owner-password-123",
+        next: "/admin/vaults",
+      });
+      const res = await handleAdminLoginPost(
+        harness.db,
+        new Request("http://hub.test/login", {
+          method: "POST",
+          headers: { ...pw.headers, cookie: CSRF_COOKIE, "cf-connecting-ip": ATTACK_IP },
+          body: pw.body,
+        }),
+      );
+      const token = cookieFrom(res, PENDING_LOGIN_COOKIE_NAME);
+      expect(token).toBeTruthy();
+      return token!;
+    };
+
+    const wrongTotp = (pendingToken: string): Request => {
+      const tf = formBody({ [CSRF_FIELD_NAME]: TEST_CSRF, code: "000000", next: "/admin/vaults" });
+      return new Request("http://hub.test/login/2fa", {
+        method: "POST",
+        headers: {
+          ...tf.headers,
+          cookie: `${CSRF_COOKIE}; ${PENDING_LOGIN_COOKIE_NAME}=${pendingToken}`,
+          "cf-connecting-ip": ATTACK_IP,
+        },
+        body: tf.body,
+      });
+    };
+
+    // First password step → pendingToken1.
+    const token1 = await passwordPost();
+    // 4 wrong TOTP attempts against pendingToken1 (all 401, all count toward
+    // the (ip,userId) bucket).
+    for (let i = 0; i < 4; i++) {
+      expect((await handleAdminLoginTotpPost(harness.db, wrongTotp(token1))).status).toBe(401);
+    }
+
+    // Re-do the password step → a BRAND-NEW pendingToken2 (same userId).
+    const token2 = await passwordPost();
+    expect(token2).not.toBe(token1);
+
+    // 5th wrong TOTP — under pendingToken2 but the SAME (ip,userId) bucket →
+    // still the 5th attempt → allowed (401), not reset to fresh.
+    expect((await handleAdminLoginTotpPost(harness.db, wrongTotp(token2))).status).toBe(401);
+    // 6th wrong TOTP → floor full → 429. If the floor were keyed by the
+    // pendingToken, token2 would have a fresh bucket and this would be a 401.
+    const denied = await handleAdminLoginTotpPost(harness.db, wrongTotp(token2));
+    expect(denied.status).toBe(429);
+    expect(denied.headers.get("retry-after")).not.toBeNull();
+  });
 });
 
 describe("/account/2fa handlers — hub#473", () => {

package/src/__tests__/users.test.ts

@@ -23,6 +23,7 @@ import {
   setPassword,
   setUserVaults,
   userCount,
+  validateEmail,
   validatePassword,
   validateUsername,
   vaultVerbsForRole,
@@ -431,6 +432,38 @@ describe("validatePassword", () => {
   });
 });
 
+describe("validateEmail (v15, B2)", () => {
+  test("accepts ordinary addresses, canonicalizing to lowercase/trimmed", () => {
+    const r = validateEmail("  Alice@Example.com ");
+    expect(r.valid).toBe(true);
+    if (r.valid) expect(r.email).toBe("alice@example.com");
+    expect(validateEmail("a.b+tag@sub.domain.co.uk").valid).toBe(true);
+    expect(validateEmail("user_name@x.io").valid).toBe(true);
+  });
+
+  test("rejects malformed shapes", () => {
+    for (const bad of [
+      "",
+      "not-an-email",
+      "@example.com",
+      "alice@",
+      "alice@example",
+      "alice example@x.io",
+      "two@@x.io",
+      "alice@x.c",
+    ]) {
+      expect(validateEmail(bad).valid).toBe(false);
+    }
+  });
+
+  test("rejects over-length addresses (>254)", () => {
+    const long = `${"a".repeat(250)}@x.io`;
+    const r = validateEmail(long);
+    expect(r.valid).toBe(false);
+    if (!r.valid) expect(r.reason).toBe("length");
+  });
+});
+
 describe("resetUserPassword", () => {
   test("returns false when user does not exist", async () => {
     const { db, cleanup } = makeDb();

package/src/__tests__/vault-caps.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Per-vault storage cap store (`src/vault-caps.ts`, migration v15, B4). The
+ * cap is PERSISTED here at provision time; a separate Phase-2 PR reads + enforces
+ * it. These tests cover the read/write/upsert/remove primitives + the "no row
+ * = uncapped" contract the Phase-2 reader relies on.
+ */
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  DEFAULT_VAULT_CAP_BYTES,
+  getVaultCap,
+  getVaultCapBytes,
+  removeVaultCap,
+  setVaultCap,
+} from "../vault-caps.ts";
+
+function makeDb() {
+  const dir = mkdtempSync(join(tmpdir(), "phub-vault-caps-"));
+  const db = openHubDb(hubDbPath(dir));
+  return {
+    db,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("vault-caps", () => {
+  test("default cap constant is ~1 GiB", () => {
+    expect(DEFAULT_VAULT_CAP_BYTES).toBe(1024 * 1024 * 1024);
+  });
+
+  test("no row = uncapped (null) — the Phase-2 reader's contract", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      expect(getVaultCap(db, "nope")).toBeNull();
+      expect(getVaultCapBytes(db, "nope")).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("setVaultCap persists, getVaultCapBytes reads it back", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const now = new Date("2026-06-25T00:00:00Z");
+      const cap = setVaultCap(db, "alice", DEFAULT_VAULT_CAP_BYTES, now);
+      expect(cap.vaultName).toBe("alice");
+      expect(cap.capBytes).toBe(DEFAULT_VAULT_CAP_BYTES);
+      expect(cap.createdAt).toBe(now.toISOString());
+      expect(getVaultCapBytes(db, "alice")).toBe(DEFAULT_VAULT_CAP_BYTES);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("upsert: re-set overwrites cap_bytes, bumps updated_at, preserves created_at", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const t0 = new Date("2026-06-25T00:00:00Z");
+      const t1 = new Date("2026-06-26T00:00:00Z");
+      setVaultCap(db, "alice", 1000, t0);
+      const updated = setVaultCap(db, "alice", 2000, t1);
+      expect(updated.capBytes).toBe(2000);
+      expect(updated.createdAt).toBe(t0.toISOString()); // preserved
+      expect(updated.updatedAt).toBe(t1.toISOString()); // bumped
+      expect(getVaultCapBytes(db, "alice")).toBe(2000);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("removeVaultCap drops the row (cascade parity) — returns count", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      setVaultCap(db, "alice", 1000);
+      expect(removeVaultCap(db, "alice")).toBe(1);
+      expect(getVaultCapBytes(db, "alice")).toBeNull();
+      // Idempotent — removing a missing row is 0.
+      expect(removeVaultCap(db, "alice")).toBe(0);
+    } finally {
+      cleanup();
+    }
+  });
+});

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) {