@openparachute/hub 0.7.2 → 0.7.3-rc.10

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
@@ -451,6 +454,110 @@ const MIGRATIONS: readonly Migration[] = [
       ALTER TABLE invites ADD COLUMN username TEXT;
     `,
   },
+  {
+    version: 14,
+    sql: `
+      -- Refresh-token rotation grace window (hub#685). Records the successor
+      -- a refresh-token row rotated INTO, so the refresh handler can tell the
+      -- *immediately-previous* token (the single benign concurrent/retried
+      -- refresh a multi-tab / bfcache / network-retry client legitimately
+      -- presents) apart from a genuine replay of an older ancestor (theft).
+      --
+      -- \`rotated_to\` is the jti of the row minted when this row rotated. NULL
+      -- on every row that has not (yet) rotated: live tokens, revoked-by-
+      -- /oauth/revoke tokens, revoked-by-family-sweep tokens, and every
+      -- pre-v14 row (no backfill — pre-v14 rotations left no successor link,
+      -- so they fall through to the zero-tolerance theft path exactly as
+      -- before; the grace window only ever helps rows minted post-v14).
+      --
+      -- The successor link is the ONLY structural ordering signal we need:
+      -- created_at alone can't distinguish the direct predecessor from an
+      -- older ancestor under burst issuance (ties), and the grace decision is
+      -- security-load-bearing, so it must be exact, not heuristic.
+      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/hub-origin.ts

@@ -14,6 +14,70 @@
 
 export const HUB_ORIGIN_ENV = "PARACHUTE_HUB_ORIGIN";
 
+/**
+ * The env var carrying the SET of origins the hub legitimately answers on,
+ * comma-separated (multi-origin iss-set, onboarding-streamline 2026-06-25).
+ *
+ * Supervised resource servers (vault, scribe) read this in addition to the
+ * single canonical `PARACHUTE_HUB_ORIGIN` and widen their accepted-`iss` check
+ * from one string to this set — so a token minted under one URL of a
+ * multi-URL box (loopback ∪ `<ip>.sslip.io` ∪ a custom domain behind Caddy)
+ * validates when the resource is reached via another URL of the SAME box. The
+ * signing key is stable + origin-independent, so only the `iss` string varies.
+ *
+ * SECURITY INVARIANT: the value MUST be the hub's `buildHubBoundOrigins`
+ * output — configured issuer ∪ loopback aliases ∪ expose-state public origin ∪
+ * platform origin — published BY THE HUB. It must NEVER contain an unvalidated
+ * request `Host` / `X-Forwarded-Host`. Accepting `iss ∈ this-set` is safe
+ * ONLY because the resource server's JWKS signature verify runs first and
+ * proves the hub minted the token.
+ *
+ * `PARACHUTE_HUB_ORIGIN` (the single canonical origin) is ALWAYS written
+ * alongside this var for back-compat: a resource server on an older
+ * scope-guard that doesn't read `PARACHUTE_HUB_ORIGINS` keeps its existing
+ * single-origin behavior.
+ */
+export const HUB_ORIGINS_ENV = "PARACHUTE_HUB_ORIGINS";
+
+/**
+ * Serialize an origin SET into the comma-separated `PARACHUTE_HUB_ORIGINS`
+ * wire form. Dedupes, drops empties, preserves first-seen order. Returns
+ * `undefined` when nothing survives (caller skips setting the env var so a
+ * resource server falls back to single-origin behavior). Pair with
+ * `buildHubBoundOrigins` to produce `origins`.
+ */
+export function serializeHubOrigins(origins: readonly string[]): string | undefined {
+  const seen = new Set<string>();
+  for (const raw of origins) {
+    if (typeof raw !== "string") continue;
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    if (trimmed.length > 0) seen.add(trimmed);
+  }
+  if (seen.size === 0) return undefined;
+  return Array.from(seen).join(",");
+}
+
+/**
+ * Parse the comma-separated `PARACHUTE_HUB_ORIGINS` wire form back into an
+ * origin array. Tolerant of surrounding whitespace + trailing slashes + empty
+ * segments. The resource-server inverse of `serializeHubOrigins`; lives here
+ * (rather than only in the consumer adapters) so the hub's own injection tests
+ * can round-trip against the canonical parser. Returns `[]` for an
+ * absent/empty/garbage value.
+ */
+export function parseHubOrigins(raw: string | undefined): string[] {
+  if (!raw) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const seg of raw.split(",")) {
+    const trimmed = seg.trim().replace(/\/+$/, "");
+    if (trimmed.length === 0 || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
 export interface DeriveHubOriginOpts {
   /** Explicit user override (e.g., `--hub-origin`). Wins over everything else. */
   override?: string;

package/src/hub-server.ts

@@ -96,6 +96,8 @@
  *   /api/users/vaults             (GET)        → vault-name list for assigned-vault picker (host:admin)
  *   /api/users/<id>               (DELETE)     → hard-delete user + revoke tokens (host:admin)
  *   /api/users/<id>/reset-password (POST)      → admin-initiated password reset (host:admin)
+ *   /api/vault-caps               (GET)        → list vaults + persisted storage caps (host:admin)
+ *   /api/vault-caps/<name>        (PUT)        → set/update a vault's storage cap (host:admin)
  *   /login                        (GET + POST) → operator password login
  *   /login/2fa                    (POST)       → second-factor (TOTP/backup) step
  *                                                 (hub#473; reached after a correct
@@ -221,6 +223,7 @@ import {
   handleResetUserPassword,
   handleUpdateUserVaults,
 } from "./api-users.ts";
+import { handleListVaultCaps, handleSetVaultCap } from "./api-vault-caps.ts";
 import { gateUiAudience, resolveUiMount } from "./audience-gate.ts";
 import {
   CHROME_OPT_OUT_PREFIXES,
@@ -3351,6 +3354,30 @@ export function hubFetch(
         });
       }
 
+      // Per-vault storage caps (B5 admin visibility / D-slice). GET lists every
+      // vault from services.json joined with its persisted cap; PUT /:name
+      // sets/updates a cap. host:admin-gated, same gate flavor as /api/users.
+      if (pathname === "/api/vault-caps") {
+        if (!getDb) return dbNotConfigured();
+        return handleListVaultCaps(req, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          manifestPath,
+        });
+      }
+      if (pathname.startsWith("/api/vault-caps/")) {
+        if (!getDb) return dbNotConfigured();
+        const name = decodeURIComponent(pathname.slice("/api/vault-caps/".length));
+        if (!name || name.includes("/")) {
+          return new Response("not found", { status: 404 });
+        }
+        return handleSetVaultCap(req, name, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          manifestPath,
+        });
+      }
+
       // Canonical login/logout. The handlers themselves are unchanged from
       // when they lived at /admin/login + /admin/logout; the rename surfaced
       // via #231-followup so the URL reflects the surface's actual scope

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

package/src/jwt-sign.ts

@@ -32,6 +32,18 @@ import { getActiveSigningKey, getAllPublicKeys } from "./signing-keys.ts";
 
 export const ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
 export const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * One-generation rotation grace window (hub#685). When a presented refresh
+ * token has already been rotated (revoked), a refresh of the *immediately-
+ * previous* token within this window is treated as a benign concurrent /
+ * retried refresh (multi-tab SPA, bfcache/stale-tab resume, a network retry)
+ * rather than theft — it converges the client on the live tip instead of
+ * revoking the whole family. The window is deliberately short: it tolerates
+ * the brief overlap of a real client racing itself, NOT a delayed replay.
+ * Genuine theft (an OLDER ancestor, or ANY replay past the window) still
+ * revokes the family per RFC 6819 §5.2.2.3. See `handleTokenRefresh`.
+ */
+export const REFRESH_GRACE_MS = 30_000;
 export const SIGNING_ALGORITHM = "RS256";
 
 export interface SignAccessTokenOpts {
@@ -43,9 +55,20 @@ export interface SignAccessTokenOpts {
   clientId: string;
   /**
    * Hub origin — sets the `iss` claim. Required: every consumer (vault,
-   * scribe, channel) validates `iss` against `PARACHUTE_HUB_ORIGIN`, and a
-   * missing claim is rejected. Callers derive this via `deriveHubOrigin()`
-   * or thread it from `OAuthDeps.issuer`.
+   * scribe, agent) validates `iss`, and a missing claim is rejected. Callers
+   * derive this via `deriveHubOrigin()` or thread it from `OAuthDeps.issuer`
+   * (the per-request origin from `resolveIssuer`).
+   *
+   * Multi-origin iss-set (onboarding-streamline 2026-06-25): consumers no
+   * longer pin `iss` to a SINGLE `PARACHUTE_HUB_ORIGIN`. The hub publishes the
+   * SET of origins it legitimately answers on via `PARACHUTE_HUB_ORIGINS`
+   * (`buildHubBoundOrigins` — issuer ∪ loopback ∪ expose-state ∪ platform),
+   * and a scope-guard ≥0.5.0 consumer accepts `iss` ∈ that set. So a token
+   * minted here with one URL of a multi-URL box validates when the resource is
+   * reached via another URL of the SAME box. Mint stays per-request as-is: the
+   * canonical configured origin (the intended Caddy/zero-SSH deploy) is minted
+   * on every request AND is a member of the published set, so mint and validate
+   * already align — no clamp needed here.
    */
   issuer: string;
   /**
@@ -529,6 +552,14 @@ export interface RefreshTokenRow {
   createdVia: TokenCreatedVia;
   /** JSON-encoded fine-grained constraints (auth-architecture-shape.md §11.3). */
   permissions: string | null;
+  /**
+   * jti of the refresh-token row this row rotated INTO (set by
+   * `linkRotation` inside the rotation transaction). NULL until this row
+   * rotates, and NULL on every pre-v14 row. Powers the one-generation
+   * rotation grace window (hub#685): only the row whose `rotatedTo` is the
+   * family's single live tip is the benign immediate-predecessor.
+   */
+  rotatedTo: string | null;
 }
 
 /**
@@ -553,6 +584,7 @@ interface TokenRowDb {
   permissions: string | null;
   created_via: string;
   subject: string | null;
+  rotated_to: string | null;
 }
 
 function rowToRefreshToken(row: TokenRowDb): RefreshTokenRow {
@@ -568,6 +600,7 @@ function rowToRefreshToken(row: TokenRowDb): RefreshTokenRow {
     createdAt: row.created_at,
     createdVia: (row.created_via as TokenCreatedVia) ?? "oauth_refresh",
     permissions: row.permissions,
+    rotatedTo: row.rotated_to ?? null,
   };
 }
 
@@ -599,3 +632,39 @@ export function revokeFamily(db: Database, familyId: string, now: Date): number
     .run(now.toISOString(), familyId);
   return Number(res.changes);
 }
+
+/**
+ * Record that `predecessorJti` rotated INTO `successorJti`. Called INSIDE the
+ * rotation transaction (alongside the revoke-old + insert-new) so the
+ * successor link, the predecessor's `revoked_at`, and the new row commit or
+ * roll back as a unit. Powers the one-generation rotation grace window
+ * (hub#685): a benign concurrent/retried refresh of the immediate
+ * predecessor can be told apart from a genuine replay of an older ancestor.
+ */
+export function linkRotation(db: Database, predecessorJti: string, successorJti: string): void {
+  db.prepare("UPDATE tokens SET rotated_to = ? WHERE jti = ?").run(successorJti, predecessorJti);
+}
+
+/**
+ * The live (un-revoked AND un-expired) refresh-token rows in a family as of
+ * `now`. The grace window asks "is there exactly one live tip, and is the
+ * presented (revoked) row its direct predecessor?" — so callers inspect this
+ * set. Two filters matter:
+ *   - `refresh_token_hash IS NOT NULL` — the family can also contain
+ *     access-token rows sharing the jti/family, irrelevant to rotation lineage.
+ *   - `expires_at > now` — an expired-but-not-revoked tip is not a valid
+ *     rotation target, so the grace path must never rotate into it. Keeping
+ *     "live" exhaustive here means the single caller doesn't re-check expiry.
+ */
+export function liveFamilyRefreshRows(
+  db: Database,
+  familyId: string,
+  now: Date,
+): RefreshTokenRow[] {
+  const rows = db
+    .query<TokenRowDb, [string, string]>(
+      "SELECT * FROM tokens WHERE family_id = ? AND revoked_at IS NULL AND refresh_token_hash IS NOT NULL AND expires_at > ?",
+    )
+    .all(familyId, now.toISOString());
+  return rows.map(rowToRefreshToken);
+}