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

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 {

package/src/invites.ts

@@ -37,10 +37,23 @@
  * v13): the redemption form shows it read-only and the redeem handler
  * enforces it. NULL = redeemer picks their own.
  *
- * Single-use is enforced by stamping `used_at` on redemption — a replay
- * attempt sees the row with `used_at` set and `redeemInvite` throws
- * `InviteUsedError`. Revocation is a separate `revoked_at` stamp the admin
- * sets before redemption. Expiry is enforced at redeem-time.
+ * MULTI-USE (migration v15, DEMO-PREP-2026-06-25 Workstream B): an invite
+ * carries `max_uses` (how many accounts ONE link may create) + `used_count`
+ * (how many it has). A redeem is refused once `used_count >= max_uses`. A
+ * LEGACY single-use invite is exactly `max_uses = 1` (the column default), so
+ * pre-v15 invites and default-shaped new ones behave identically to before.
+ * `used_at` is RETAINED — stamped on the FIRST redeem — so the admin list's
+ * "redeemed" status and any single-use lookups keep reading the same signal.
+ * Exhaustion is enforced atomically in `recordInviteRedemption` (the
+ * `used_count < max_uses` guard in the UPDATE), so two concurrent redeems of
+ * the last remaining seat can't both succeed.
+ *
+ * Revocation is a separate `revoked_at` stamp the admin sets before
+ * redemption (terminal regardless of remaining uses). Expiry is enforced at
+ * redeem-time. A public-signup link also captures the redeemer's `email`
+ * (B2 — the contactable identity, also stored per-account on `users.email`)
+ * and may carry a `vault_cap_bytes` to stamp onto each provisioned vault (B4
+ * — persisted to `vault_caps` for the Phase-2 enforcement PR to read).
  */
 import type { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
@@ -70,6 +83,24 @@ export interface Invite {
   provisionVault: boolean;
   /** `'internal' | 'off'` mirror knob for the provisioned vault, or null. */
   defaultMirror: string | null;
+  /**
+   * How many accounts this link may create (v15). 1 = legacy single-use
+   * (the column default); >1 = a multi-use public-signup link.
+   */
+  maxUses: number;
+  /** How many accounts this link HAS created (v15). Redeem refused once == maxUses. */
+  usedCount: number;
+  /**
+   * Most-recent redeemer's email (v15, B2), or null. For a multi-use link
+   * the canonical per-account email lives on `users.email`; this column
+   * holds the latest redeemer's for the admin's at-a-glance audit.
+   */
+  email: string | null;
+  /**
+   * Per-vault storage cap (bytes) to stamp onto each provisioned vault
+   * (v15, B4), or null to provision uncapped (legacy behavior).
+   */
+  vaultCapBytes: number | null;
   expiresAt: string;
   usedAt: string | null;
   redeemedUserId: string | null;
@@ -98,6 +129,20 @@ export class InviteUsedError extends Error {
   }
 }
 
+/**
+ * A multi-use link whose seats are all taken (`used_count >= max_uses`). For
+ * a single-use (max_uses=1) link this is the same condition the legacy
+ * `InviteUsedError` named, but the redeem path throws `InviteUsedError` for a
+ * single-use link (familiar "already used" copy) and `InviteExhaustedError`
+ * for a multi-use one ("all signups taken") so the message can differ.
+ */
+export class InviteExhaustedError extends Error {
+  constructor() {
+    super("invite has reached its maximum number of signups");
+    this.name = "InviteExhaustedError";
+  }
+}
+
 export class InviteRevokedError extends Error {
   constructor() {
     super("invite has been revoked");
@@ -113,6 +158,10 @@ interface Row {
   role: string;
   provision_vault: number;
   default_mirror: string | null;
+  max_uses: number;
+  used_count: number;
+  email: string | null;
+  vault_cap_bytes: number | null;
   expires_at: string;
   used_at: string | null;
   redeemed_user_id: string | null;
@@ -129,6 +178,10 @@ function rowToInvite(r: Row): Invite {
     role: r.role,
     provisionVault: r.provision_vault === 1,
     defaultMirror: r.default_mirror,
+    maxUses: r.max_uses,
+    usedCount: r.used_count,
+    email: r.email,
+    vaultCapBytes: r.vault_cap_bytes,
     expiresAt: r.expires_at,
     usedAt: r.used_at,
     redeemedUserId: r.redeemed_user_id,
@@ -142,10 +195,19 @@ export function hashInviteToken(rawToken: string): string {
   return createHash("sha256").update(rawToken).digest("hex");
 }
 
-/** Derive an invite's status from its stamps + the current time. */
+/**
+ * Derive an invite's status from its stamps + the current time.
+ *
+ * Multi-use (v15): an invite is "redeemed" only once every seat is taken
+ * (`usedCount >= maxUses`). A partially-used multi-use link (some seats left,
+ * not expired/revoked) is still "pending" — it can take more signups. A
+ * legacy single-use link (maxUses=1) flips to "redeemed" on its first
+ * redeem, exactly as before, because 1 >= 1. Expired wins over a not-yet-
+ * exhausted link; revoked + exhausted are checked first (terminal).
+ */
 export function inviteStatus(invite: Invite, now: Date = new Date()): InviteStatus {
   if (invite.revokedAt) return "revoked";
-  if (invite.usedAt) return "redeemed";
+  if (invite.usedCount >= invite.maxUses) return "redeemed";
   if (now.getTime() > new Date(invite.expiresAt).getTime()) return "expired";
   return "pending";
 }
@@ -166,6 +228,16 @@ export interface IssueInviteOpts {
   provisionVault?: boolean;
   /** `'internal' | 'off'` mirror knob for the provisioned vault. */
   defaultMirror?: string | null;
+  /**
+   * How many accounts this link may create (v15). Default 1 (single-use,
+   * the legacy shape). Caller validates the upper bound.
+   */
+  maxUses?: number;
+  /**
+   * Per-vault storage cap (bytes) to stamp onto each provisioned vault
+   * (v15, B4). Omit/null = provision uncapped (legacy behavior).
+   */
+  vaultCapBytes?: number | null;
   /** Lifetime in seconds. Default {@link DEFAULT_INVITE_TTL_SECONDS} (7 days). */
   expiresInSeconds?: number;
   now?: () => Date;
@@ -198,12 +270,15 @@ export function issueInvite(db: Database, opts: IssueInviteOpts): IssuedInvite {
   const username = opts.username ?? null;
   const provisionVault = opts.provisionVault ?? true;
   const defaultMirror = opts.defaultMirror ?? null;
+  const maxUses = opts.maxUses ?? 1;
+  const vaultCapBytes = opts.vaultCapBytes ?? null;
 
   db.prepare(
     `INSERT INTO invites
        (token, created_by, vault_name, username, role, provision_vault, default_mirror,
+        max_uses, used_count, email, vault_cap_bytes,
         expires_at, used_at, redeemed_user_id, revoked_at, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, ?)`,
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?, NULL, NULL, NULL, ?)`,
   ).run(
     tokenHash,
     opts.createdBy,
@@ -212,6 +287,8 @@ export function issueInvite(db: Database, opts: IssueInviteOpts): IssuedInvite {
     role,
     provisionVault ? 1 : 0,
     defaultMirror,
+    maxUses,
+    vaultCapBytes,
     expiresAt,
     createdAt,
   );
@@ -226,6 +303,10 @@ export function issueInvite(db: Database, opts: IssueInviteOpts): IssuedInvite {
       role,
       provisionVault,
       defaultMirror,
+      maxUses,
+      usedCount: 0,
+      email: null,
+      vaultCapBytes,
       expiresAt,
       usedAt: null,
       redeemedUserId: null,
@@ -275,7 +356,7 @@ export function usernameReservedByPendingInvite(
   const row = db
     .query<{ token: string }, [string, string]>(
       `SELECT token FROM invites
-       WHERE username = ? AND used_at IS NULL AND revoked_at IS NULL AND expires_at > ?
+       WHERE username = ? AND used_count < max_uses AND revoked_at IS NULL AND expires_at > ?
        LIMIT 1`,
     )
     .get(username, now.toISOString());
@@ -295,11 +376,13 @@ export function listInvites(
 }
 
 /**
- * Validate an invite for redemption WITHOUT consuming it. Throws on every
- * not-redeemable branch (not-found / expired / used / revoked). Returns the
- * invite when it's redeemable. The redemption handler calls this FIRST (so a
- * bad token is rejected before any account/vault work), then does
- * createUser, then `consumeInvite` AFTER the user row commits.
+ * Validate an invite for redemption WITHOUT recording one. Throws on every
+ * not-redeemable branch (not-found / expired / exhausted / revoked). Returns
+ * the invite when it's redeemable. The redemption handler calls this FIRST (so
+ * a bad token is rejected before any account/vault work), then does createUser,
+ * then `recordInviteRedemption` INSIDE the user-row transaction (the atomic
+ * seat-lock — the `< max_uses` UPDATE guard is what actually prevents an
+ * over-seat under concurrency; this early check is the fast-path rejection).
  */
 export function assertInviteRedeemable(
   db: Database,
@@ -308,10 +391,15 @@ export function assertInviteRedeemable(
 ): Invite {
   const invite = findInviteByRawToken(db, rawToken);
   if (!invite) throw new InviteNotFoundError();
-  // Revoked + used are terminal regardless of clock; check them before expiry
-  // so a revoked-then-expired invite reports the more specific reason.
+  // Revoked + exhausted are terminal regardless of clock; check them before
+  // expiry so a revoked-then-expired invite reports the more specific reason.
   if (invite.revokedAt) throw new InviteRevokedError();
-  if (invite.usedAt) throw new InviteUsedError();
+  // Exhaustion (v15): seats all taken. A single-use link (maxUses=1) throws
+  // the familiar InviteUsedError ("already used"); a multi-use one throws
+  // InviteExhaustedError ("all signups taken") so the copy can differ.
+  if (invite.usedCount >= invite.maxUses) {
+    throw invite.maxUses > 1 ? new InviteExhaustedError() : new InviteUsedError();
+  }
   if (now.getTime() > new Date(invite.expiresAt).getTime()) {
     throw new InviteExpiredError();
   }
@@ -319,39 +407,75 @@ export function assertInviteRedeemable(
 }
 
 /**
- * Mark an invite consumed — stamp `used_at` + `redeemed_user_id`. Called
- * Called within the account-creation transaction (or after a committed user
- * row). Single-use + not-revoked is enforced by the
- * `used_at IS NULL AND revoked_at IS NULL` guard in the UPDATE: a racing
- * second redeem — or a concurrent revoke — updates zero rows and the caller
- * treats that as already-consumed/revoked. Race-safe because sqlite
- * serializes writes.
+ * Record ONE redemption against an invite — the multi-use-aware consume
+ * (v15). Atomically:
+ *   - increments `used_count` by 1,
+ *   - stamps `used_at` on the FIRST redeem only (COALESCE keeps the original),
+ *   - records the redeemer's `email` (B2) + `redeemed_user_id` as the
+ *     MOST-RECENT redeemer (the canonical per-account email lives on
+ *     `users.email`; this is the admin's at-a-glance latest).
+ *
+ * Exhaustion + revocation are enforced by the `used_count < max_uses AND
+ * revoked_at IS NULL` guard in the UPDATE: a racing redeem that would take a
+ * seat past the cap — or one racing a revoke — updates zero rows, and the
+ * caller treats that as exhausted/revoked. Race-safe because sqlite
+ * serializes writes (a legacy single-use link is just the max_uses=1 case:
+ * the second concurrent redeem sees `used_count`=1, fails the `< max_uses`
+ * guard, and changes zero rows — exactly the old single-use behavior).
  *
- * Returns `true` if THIS call consumed the invite, `false` otherwise.
+ * Returns `true` if THIS call recorded a redemption, `false` otherwise.
  */
-export function consumeInvite(
+export function recordInviteRedemption(
   db: Database,
   tokenHash: string,
   redeemedUserId: string,
+  email: string | null = null,
   now: Date = new Date(),
 ): boolean {
+  const stamp = now.toISOString();
   const res = db
     .prepare(
-      "UPDATE invites SET used_at = ?, redeemed_user_id = ? WHERE token = ? AND used_at IS NULL AND revoked_at IS NULL",
+      `UPDATE invites
+       SET used_count = used_count + 1,
+           used_at = COALESCE(used_at, ?),
+           redeemed_user_id = ?,
+           email = ?
+       WHERE token = ? AND used_count < max_uses AND revoked_at IS NULL`,
     )
-    .run(now.toISOString(), redeemedUserId, tokenHash);
+    .run(stamp, redeemedUserId, email, tokenHash);
   return res.changes > 0;
 }
 
+/**
+ * Legacy single-use consume — thin wrapper over {@link recordInviteRedemption}
+ * for callers that don't capture email. Retained for backwards compatibility;
+ * the redeem path uses `recordInviteRedemption` directly so it can record the
+ * email. Race-safe + exhaustion-aware via the underlying function.
+ *
+ * Returns `true` if THIS call recorded a redemption, `false` otherwise.
+ */
+export function consumeInvite(
+  db: Database,
+  tokenHash: string,
+  redeemedUserId: string,
+  now: Date = new Date(),
+): boolean {
+  return recordInviteRedemption(db, tokenHash, redeemedUserId, null, now);
+}
+
 /**
  * Revoke a pending invite (admin DELETE). Stamps `revoked_at` only when the
- * invite isn't already used or revoked. Returns `true` if this call revoked
- * it, `false` if it was already consumed/revoked or not found.
+ * invite still has seats left (`used_count < max_uses`) and isn't already
+ * revoked. A multi-use link can be revoked mid-life to cut off its remaining
+ * seats; a fully-exhausted link is terminal and revoke is a no-op. (For a
+ * legacy single-use link `used_count < max_uses` is equivalent to the old
+ * `used_at IS NULL` guard.) Returns `true` if this call revoked it, `false`
+ * if it was already exhausted/revoked or not found.
  */
 export function revokeInvite(db: Database, tokenHash: string, now: Date = new Date()): boolean {
   const res = db
     .prepare(
-      "UPDATE invites SET revoked_at = ? WHERE token = ? AND used_at IS NULL AND revoked_at IS NULL",
+      "UPDATE invites SET revoked_at = ? WHERE token = ? AND used_count < max_uses AND revoked_at IS NULL",
     )
     .run(now.toISOString(), tokenHash);
   return res.changes > 0;
@@ -373,7 +497,7 @@ export function revokeInvitesForVault(
 ): number {
   const res = db
     .prepare(
-      "UPDATE invites SET revoked_at = ? WHERE vault_name = ? AND used_at IS NULL AND revoked_at IS NULL",
+      "UPDATE invites SET revoked_at = ? WHERE vault_name = ? AND used_count < max_uses AND revoked_at IS NULL",
     )
     .run(now.toISOString(), vaultName);
   return Number(res.changes);