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

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.

package/src/admin-login-ui.ts

@@ -175,7 +175,16 @@ export interface InviteSetupProps {
   role: string;
   /** Whether redemption provisions a vault at all (shows the vault row iff true). */
   provisionVault: boolean;
+  /**
+   * Whether to collect the redeemer's email (B2). True for public-signup
+   * (multi-use) links — the operator must be able to reach the stranger who
+   * signed up; false for legacy single-use admin/friends invites. Default
+   * false (omitted) preserves the friends flow's no-email form.
+   */
+  collectEmail?: boolean;
   username?: string;
+  /** Echoed email value on a re-render so the redeemer doesn't retype it. */
+  email?: string;
   vaultName?: string;
   errorMessage?: string;
 }
@@ -194,12 +203,28 @@ export function renderInviteSetup(props: InviteSetupProps): string {
     pinnedUsername,
     role,
     provisionVault,
+    collectEmail,
     username,
+    email,
     vaultName,
     errorMessage,
   } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
   const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
+  const emailAttr = email ? ` value="${escapeAttr(email)}"` : "";
+
+  // Email row (B2): shown ONLY for public-signup (multi-use) links so the
+  // operator can reach the stranger who signed up. `type=email` gets the
+  // browser's built-in client-side format check (the server re-validates).
+  const emailRow = collectEmail
+    ? `
+        <label class="field">
+          <span class="field-label">Email</span>
+          <input type="email" name="email" autocomplete="email" required
+            spellcheck="false" autocapitalize="off"${emailAttr} />
+          <span class="field-hint">So your hub operator can reach you.</span>
+        </label>`
+    : "";
 
   // Username row: pre-named → read-only display (the server ENFORCES the
   // invite's username; the disabled input never submits and the handler
@@ -304,6 +329,7 @@ export function renderInviteSetup(props: InviteSetupProps): string {
       <form method="POST" action="/account/setup/${escapeAttr(token)}" class="auth-form">
         ${renderCsrfHiddenInput(csrfToken)}
         ${usernameRow}
+        ${emailRow}
         <label class="field">
           <span class="field-label">Password</span>
           <input type="password" name="password" autocomplete="new-password"
@@ -405,7 +431,7 @@ const STYLES = `
     letter-spacing: 0.01em;
     font-family: ${FONT_MONO};
   }
-  input[type=text], input[type=password] {
+  input[type=text], input[type=password], input[type=email] {
     font: inherit;
     width: 100%;
     padding: 0.6rem 0.75rem;
@@ -415,7 +441,7 @@ const STYLES = `
     color: ${PALETTE.fg};
     transition: border-color 0.15s ease, background 0.15s ease;
   }
-  input[type=text]:focus, input[type=password]:focus {
+  input[type=text]:focus, input[type=password]:focus, input[type=email]:focus {
     outline: none;
     border-color: ${PALETTE.accent};
     background: ${PALETTE.cardBg};
@@ -461,10 +487,10 @@ const STYLES = `
     .card { background: #25221d; border-color: #3a362f; box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3); }
     h1 { color: #f0ece4; }
     .subtitle, .field-label { color: #a8a29a; }
-    input[type=text], input[type=password] {
+    input[type=text], input[type=password], input[type=email] {
       background: #1f1c18; border-color: #3a362f; color: #e8e4dc;
     }
-    input[type=text]:focus, input[type=password]:focus {
+    input[type=text]:focus, input[type=password]:focus, input[type=email]:focus {
       background: #25221d;
     }
     .brand-tag { border-color: #3a362f; color: #a8a29a; }

package/src/admin-vaults.ts

@@ -68,6 +68,7 @@ import { revokeTokensNamingVault, signAccessToken } from "./jwt-sign.ts";
 import { findService, type readManifest, readManifestLenient } from "./services-manifest.ts";
 import { enrichedPath } from "./spawn-path.ts";
 import { removeVaultAssignments } from "./users.ts";
+import { removeVaultCap } from "./vault-caps.ts";
 import { RESERVED_VAULT_NAMES, VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 import { type WellKnownVaultEntry, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
 
@@ -577,6 +578,7 @@ interface CascadeSummary {
   grants_dropped: number;
   user_vaults_removed: number;
   invites_invalidated: number;
+  vault_cap_removed: boolean;
   connections_torn_down: number;
   /**
    * Vault-backed channel-daemon entries still referencing the deleted vault
@@ -596,6 +598,7 @@ function emptyCascadeSummary(): CascadeSummary {
     grants_dropped: 0,
     user_vaults_removed: 0,
     invites_invalidated: 0,
+    vault_cap_removed: false,
     connections_torn_down: 0,
     orphaned_channels: [],
     vault_removed: false,
@@ -648,7 +651,8 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
  *      it empties — a (user,client) grant can span multiple vaults);
  *   3. `user_vaults` rows;
  *   4. unredeemed invites pinned to the vault (redemption would resurrect
- *      the name);
+ *      the name); the per-vault storage-cap row (v15) so a re-created
+ *      same-name vault doesn't inherit a stale cap;
  *   5. connections whose source/provisioned vault is the deleted vault
  *      (via `teardownConnection`, which post-B0 also revokes the registered
  *      long-lived mints) + a report-only scan of the agent's `/api/channels`
@@ -753,6 +757,10 @@ export async function handleDeleteVault(
   // --- 4. Unredeemed invites pinned to the vault. ----------------------------
   summary.invites_invalidated = revokeInvitesForVault(deps.db, name, now);
 
+  // --- 4b. Per-vault storage cap row (v15). ----------------------------------
+  // A re-created same-name vault must not inherit a stale cap; drop it.
+  summary.vault_cap_removed = removeVaultCap(deps.db, name) > 0;
+
   // --- 5. Connections teardown (+ legacy channel scan, report-only). --------
   // Runs BEFORE the CLI remove so the vault daemon is still alive to accept
   // the trigger-deregister calls.

package/src/api-invites.ts

@@ -15,6 +15,18 @@
  *
  * Wire shape is snake_case (matches `/api/users`). An invite's raw token
  * NEVER appears in a GET/list response — only in the POST-create `url`.
+ *
+ * v15 (DEMO-PREP Workstream B) extends POST /api/invites with `max_uses`
+ * (multi-use public-signup links, default 1 = single-use) and
+ * `vault_cap_bytes` (per-vault storage cap stamped at provision, B4). A
+ * multi-use PROVISIONING link with no explicit `vault_cap_bytes` auto-defaults
+ * to ~1 GB (DEFAULT_VAULT_CAP_BYTES) so a public link never provisions
+ * uncapped by omission; single-use friends links stay uncapped unless opted
+ * in. The list/create wire shape gains `max_uses`, `used_count`, `email`
+ * (latest redeemer, B2), and `vault_cap_bytes`. `expires_in` already bounded
+ * the link lifetime (B1's expiry). A multi-use link can't pre-name a username
+ * or pin a single new vault name (every seat past the first would collide —
+ * rejected at mint).
  */
 import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
@@ -32,6 +44,7 @@ import {
   usernameReservedByPendingInvite,
 } from "./invites.ts";
 import { getUserByUsernameCI, validateUsername } from "./users.ts";
+import { DEFAULT_VAULT_CAP_BYTES } from "./vault-caps.ts";
 import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 import { listVaultNamesFromPath } from "./vault-names.ts";
 
@@ -47,6 +60,18 @@ export interface ApiInvitesDeps {
 const ALLOWED_ROLES = new Set(["read", "write"]);
 /** Cap an invite TTL so a typo can't mint a ~forever link. 90 days. */
 const MAX_INVITE_TTL_SECONDS = 90 * 24 * 60 * 60;
+/**
+ * Cap `max_uses` (v15) so a typo can't mint a runaway public-signup link on a
+ * shared box. 1000 is comfortably above any demo cohort while still bounding
+ * the abuse surface. The DEMO-PREP shared box uses small values (tens of seats).
+ */
+const MAX_INVITE_USES = 1000;
+/**
+ * Ceiling on a per-vault cap an invite may carry (v15, B4). 100 GiB — far
+ * above the ~1 GB default, but bounds a fat-finger that would make the cap
+ * meaningless on a shared box. The minimum is 1 byte (a positive integer).
+ */
+const MAX_VAULT_CAP_BYTES = 100 * 1024 * 1024 * 1024;
 
 interface InviteWireShape {
   /** sha256 hash — the stable id for list/revoke. NOT the raw token. */
@@ -57,6 +82,14 @@ interface InviteWireShape {
   role: string;
   provision_vault: boolean;
   default_mirror: string | null;
+  /** v15 — how many accounts this link may create (1 = single-use). */
+  max_uses: number;
+  /** v15 — how many it has created so far. */
+  used_count: number;
+  /** v15 — most-recent redeemer's email (B2), or null. */
+  email: string | null;
+  /** v15 — per-vault storage cap to stamp at provision (B4), or null (uncapped). */
+  vault_cap_bytes: number | null;
   expires_at: string;
   used_at: string | null;
   redeemed_user_id: string | null;
@@ -73,6 +106,10 @@ function toWire(invite: Invite, status: InviteStatus): InviteWireShape {
     role: invite.role,
     provision_vault: invite.provisionVault,
     default_mirror: invite.defaultMirror,
+    max_uses: invite.maxUses,
+    used_count: invite.usedCount,
+    email: invite.email,
+    vault_cap_bytes: invite.vaultCapBytes,
     expires_at: invite.expiresAt,
     used_at: invite.usedAt,
     redeemed_user_id: invite.redeemedUserId,
@@ -100,6 +137,10 @@ interface CreateInviteBody {
   provisionVault: boolean;
   defaultMirror: string | null;
   expiresInSeconds: number;
+  /** v15 — how many accounts the link may create (default 1 = single-use). */
+  maxUses: number;
+  /** v15 — per-vault storage cap (bytes) to stamp at provision, or null (uncapped). */
+  vaultCapBytes: number | null;
 }
 
 interface ParseErr {
@@ -283,9 +324,71 @@ async function parseCreateBody(
     expiresInSeconds = Math.floor(rawExpiry);
   }
 
+  // max_uses — v15. Default 1 (single-use, the legacy shape). A positive
+  // integer ≤ MAX_INVITE_USES. >1 = a multi-use public-signup link.
+  let maxUses = 1;
+  const rawMaxUses =
+    Object.hasOwn(obj, "max_uses") && obj.max_uses !== undefined
+      ? obj.max_uses
+      : Object.hasOwn(obj, "maxUses") && obj.maxUses !== undefined
+        ? obj.maxUses
+        : undefined;
+  if (rawMaxUses !== undefined && rawMaxUses !== null) {
+    if (
+      typeof rawMaxUses !== "number" ||
+      !Number.isInteger(rawMaxUses) ||
+      rawMaxUses < 1 ||
+      rawMaxUses > MAX_INVITE_USES
+    ) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: `"max_uses" must be an integer between 1 and ${MAX_INVITE_USES}`,
+      };
+    }
+    maxUses = rawMaxUses;
+  }
+
+  // vault_cap_bytes — v15, B4. Optional per-vault storage cap stamped at
+  // provision. null/omitted = uncapped (legacy). A positive integer
+  // ≤ MAX_VAULT_CAP_BYTES.
+  let vaultCapBytes: number | null = null;
+  const rawCap =
+    Object.hasOwn(obj, "vault_cap_bytes") && obj.vault_cap_bytes !== undefined
+      ? obj.vault_cap_bytes
+      : Object.hasOwn(obj, "vaultCapBytes") && obj.vaultCapBytes !== undefined
+        ? obj.vaultCapBytes
+        : undefined;
+  if (rawCap !== undefined && rawCap !== null) {
+    if (
+      typeof rawCap !== "number" ||
+      !Number.isInteger(rawCap) ||
+      rawCap < 1 ||
+      rawCap > MAX_VAULT_CAP_BYTES
+    ) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: `"vault_cap_bytes" must be a positive integer ≤ ${MAX_VAULT_CAP_BYTES} (100 GiB)`,
+      };
+    }
+    vaultCapBytes = rawCap;
+  }
+
   return {
     ok: true,
-    body: { vaultName, username, role, provisionVault, defaultMirror, expiresInSeconds },
+    body: {
+      vaultName,
+      username,
+      role,
+      provisionVault,
+      defaultMirror,
+      expiresInSeconds,
+      maxUses,
+      vaultCapBytes,
+    },
   };
 }
 
@@ -303,8 +406,16 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
   }
   const parsed = await parseCreateBody(req);
   if (!parsed.ok) return jsonError(parsed.status, parsed.error, parsed.description);
-  const { vaultName, username, role, provisionVault, defaultMirror, expiresInSeconds } =
-    parsed.body;
+  const {
+    vaultName,
+    username,
+    role,
+    provisionVault,
+    defaultMirror,
+    expiresInSeconds,
+    maxUses,
+    vaultCapBytes,
+  } = parsed.body;
   const now = (deps.now ?? (() => new Date()))();
 
   // Shape gates over the three supported invite shapes:
@@ -330,6 +441,42 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
       'a provisioned vault\'s sole user must hold write — use role "write", or share an existing vault (provision_vault=false + vault_name) for read-only access',
     );
   }
+
+  // Multi-use coherence gates (v15). A link that creates many accounts can't:
+  //   - pre-name a username (one name can't be reused across redeemers), or
+  //   - pin a single NEW vault name (every redeemer would collide on it —
+  //     the redeem path's freshly-created invariant rejects the 2nd onward).
+  // Either combination would make every seat past the first dead-on-arrival,
+  // so reject at mint. (A multi-use SHARED-vault invite — provision_vault=false
+  // + an existing vault_name — IS coherent: many users joining one vault; it's
+  // not blocked here.)
+  if (maxUses > 1) {
+    if (username !== null) {
+      return jsonError(
+        400,
+        "invalid_request",
+        "a multi-use link (max_uses > 1) can't pre-name a username — one username can't be shared across signups. Omit \"username\".",
+      );
+    }
+    if (provisionVault && vaultName !== null) {
+      return jsonError(
+        400,
+        "invalid_request",
+        'a multi-use provisioning link (max_uses > 1) can\'t pin a single vault name — every signup would collide on it. Omit "vault_name" so each signup names their own vault.',
+      );
+    }
+  }
+
+  // A per-vault cap only applies to a vault THIS link provisions. Pinning a
+  // cap on a non-provisioning invite (account-only or shared-existing-vault)
+  // has nothing to stamp — reject the contradiction at mint.
+  if (vaultCapBytes !== null && !provisionVault) {
+    return jsonError(
+      400,
+      "invalid_request",
+      '"vault_cap_bytes" only applies to a provisioning invite (provision_vault=true) — a non-provisioning link has no vault to cap',
+    );
+  }
   if (vaultName !== null && !provisionVault) {
     const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
     const known = new Set(listVaultNamesFromPath(manifestPath));
@@ -358,6 +505,17 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
     }
   }
 
+  // Auto-apply the ~1 GB default cap to a PUBLIC-SIGNUP (multi-use,
+  // provisioning) link when the admin didn't set one explicitly — the
+  // DEMO-PREP decision is "1 GB per vault, configurable," so a multi-use
+  // signup link on a shared box should never provision UNcapped by omission.
+  // An explicit cap (any value, validated above) is honored as-is; a
+  // single-use friends link stays uncapped unless the admin opts in.
+  const effectiveVaultCapBytes =
+    vaultCapBytes === null && maxUses > 1 && provisionVault
+      ? DEFAULT_VAULT_CAP_BYTES
+      : vaultCapBytes;
+
   const issued = issueInvite(deps.db, {
     createdBy: authUserId,
     vaultName,
@@ -366,6 +524,8 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
     provisionVault,
     defaultMirror,
     expiresInSeconds,
+    maxUses,
+    vaultCapBytes: effectiveVaultCapBytes,
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });
   const status = inviteStatus(issued.invite, now);

package/src/api-users.ts

@@ -88,6 +88,8 @@ export interface UserWireShape {
   id: string;
   username: string;
   password_changed: boolean;
+  /** Contactable email captured at signup (v15, B2), or null. Visible to admin. */
+  email: string | null;
   assigned_vaults: string[];
   created_at: string;
 }
@@ -97,6 +99,7 @@ function toWire(u: User): UserWireShape {
     id: u.id,
     username: u.username,
     password_changed: u.passwordChanged,
+    email: u.email,
     assigned_vaults: [...u.assignedVaults],
     created_at: u.createdAt,
   };

package/src/hub-db.ts

@@ -4,7 +4,10 @@
  * issuer — signing keys (v1), users + opaque refresh tokens (v2), OAuth
  * clients + auth-codes + grants + browser sessions (v3), TOTP 2FA
  * enrollment on the users row (v11, hub#473), and one-time invite links
- * (v12, the `invites` table; v13 adds the pre-named `username` column).
+ * (v12, the `invites` table; v13 adds the pre-named `username` column;
+ * v14 adds refresh-token rotation grace; v15 generalizes invites into
+ * multi-use public-signup links + email-as-username + the `vault_caps`
+ * per-vault storage-cap table).
  *
  * Each open() runs `migrate()` to bring the schema up to date. A
  * `schema_version` table records every applied migration so re-opens are
@@ -474,6 +477,87 @@ const MIGRATIONS: readonly Migration[] = [
       ALTER TABLE tokens ADD COLUMN rotated_to TEXT;
     `,
   },
+  {
+    version: 15,
+    sql: `
+      -- Multi-use public signup links + email-as-username + per-vault caps
+      -- (DEMO-PREP-2026-06-25 Workstream B: B1 multi-use invite, B2 email
+      -- capture, B4 public signup page; the cap value is persisted now so
+      -- B3's vault-side enforcement — a separate Phase-2 PR — can read it).
+      --
+      -- (1) FOUR columns on \`invites\` generalize the single-use link into a
+      --     multi-use, capped one. Backwards compatible: every pre-v15 invite
+      --     redeems exactly as before because the defaults reproduce the old
+      --     single-use semantics.
+      --
+      --   * max_uses (INTEGER NOT NULL DEFAULT 1) — how many accounts ONE link
+      --     may create. DEFAULT 1 = the historical single-use invite, so every
+      --     pre-v15 row and every default-shaped new row stays single-use. A
+      --     public signup link mints with a higher value (e.g. 25 demo seats).
+      --   * used_count (INTEGER NOT NULL DEFAULT 0) — how many accounts the link
+      --     HAS created. Redeem refuses once used_count >= max_uses. Replaces
+      --     the boolean used_at as the exhaustion signal for multi-use links;
+      --     used_at is RETAINED (stamped on the FIRST redeem) so legacy
+      --     single-use lookups + the admin list's "redeemed" status keep
+      --     working unchanged.
+      --   * email (TEXT, nullable) — the redeemer's email captured at signup
+      --     as the contactable identity (B2). NULL on every pre-v15 invite and
+      --     on admin-issued links that don't collect email; set per-redemption
+      --     for public-signup links. Stored so the operator can reach signups.
+      --     (One link → many signups means one invite row can't hold every
+      --     redeemer's email; this column holds the MOST-RECENT redeemer's
+      --     email for a single-use link, and the per-account email lives on the
+      --     users row — see (3). For multi-use the canonical per-user email is
+      --     users.email.)
+      --   * vault_cap_bytes (INTEGER, nullable) — the per-vault storage cap to
+      --     STAMP onto each vault this link provisions (B4). NULL on every
+      --     pre-v15 invite + admin-issued links that don't set a cap (those
+      --     provision uncapped, the historical behavior); set to ~1 GB on a
+      --     public-signup link so each provisioned vault gets a vault_caps row
+      --     for the Phase-2 enforcement PR to read. The cap travels on the
+      --     invite (not a server-wide default) so different links can carry
+      --     different caps.
+      --
+      -- (2) ONE column on \`users\`: email-as-contactable-identity (B2). The
+      --     username stays the login + URL identity ([a-z0-9_-]); email is the
+      --     separate contact field the operator sees + uses to reach a signup.
+      --     Nullable: every pre-v15 account (wizard admin, env-seeded admin,
+      --     pre-named friend invites) predates email capture and keeps NULL.
+      --     NOT UNIQUE — two people behind one shared mailbox, or an operator
+      --     re-using their address across test accounts, shouldn't be blocked
+      --     at the schema. Validation (format) happens at the API/redeem edge.
+      --
+      -- (3) NEW \`vault_caps\` table — the per-vault storage cap, persisted at
+      --     provision time (B4: "persist a per-vault cap value at provision
+      --     time EVEN THOUGH vault-side enforcement lands in a separate
+      --     Phase-2 PR — at minimum store the cap so the later PR can read +
+      --     enforce it"). Keyed by vault_name (the same instance-name space
+      --     used across services.json / user_vaults / invites.vault_name; no
+      --     FK — vault names resolve through services.json, not a DB row, the
+      --     established pattern). cap_bytes is the byte ceiling (default
+      --     ~1 GB stamped by the public-signup flow), guarded by a
+      --     CHECK (cap_bytes > 0) so a direct DB write can't seed a 0/negative
+      --     cap the Phase-2 reader would misinterpret. No backfill — existing
+      --     vaults have no cap row, which the Phase-2 enforcement reads as
+      --     "uncapped" (only vaults provisioned through a capped signup get a
+      --     row).
+      ALTER TABLE invites ADD COLUMN max_uses INTEGER NOT NULL DEFAULT 1;
+      ALTER TABLE invites ADD COLUMN used_count INTEGER NOT NULL DEFAULT 0;
+      ALTER TABLE invites ADD COLUMN email TEXT;
+      ALTER TABLE invites ADD COLUMN vault_cap_bytes INTEGER;
+      ALTER TABLE users ADD COLUMN email TEXT;
+      CREATE TABLE vault_caps (
+        vault_name TEXT PRIMARY KEY,
+        -- CHECK (cap_bytes > 0): guard against a 0/negative cap from a direct
+        -- DB write making the Phase-2 enforcement reader treat the vault as
+        -- "0-byte ceiling" (everything over cap) or nonsense. The mint + redeem
+        -- paths already validate positivity; this is the at-rest backstop.
+        cap_bytes INTEGER NOT NULL CHECK (cap_bytes > 0),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {