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

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 {
@@ -529,6 +541,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 +573,7 @@ interface TokenRowDb {
   permissions: string | null;
   created_via: string;
   subject: string | null;
+  rotated_to: string | null;
 }
 
 function rowToRefreshToken(row: TokenRowDb): RefreshTokenRow {
@@ -568,6 +589,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 +621,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);
+}

package/src/oauth-handlers.ts

@@ -51,9 +51,13 @@ import { consumeFirstClientAutoApproveWindow } from "./hub-settings.ts";
 import { VAULT_VERBS, inferAudience } from "./jwt-audience.ts";
 import {
   ACCESS_TOKEN_TTL_SECONDS,
+  REFRESH_GRACE_MS,
   RefreshTokenInsertError,
+  type RefreshTokenRow,
   findRefreshToken,
   findTokenRowByJti,
+  linkRotation,
+  liveFamilyRefreshRows,
   revokeFamily,
   signAccessToken,
   signRefreshToken,
@@ -2223,10 +2227,46 @@ async function handleTokenRefresh(
     // Replay of an already-rotated refresh token. Per RFC 6819 §5.2.2.3 the
     // working assumption is theft — the legitimate client received a new
     // refresh token at the prior rotation, so anyone presenting the old one
-    // either lost a race (rare) or stole it (the case we must defend
-    // against). Either way: revoke every descendant in the family so the
-    // attacker can't keep refreshing, and force the legitimate client to
-    // re-authorize. Cheaper than tracking which call was first.
+    // either lost a race or stole it (the case we must defend against).
+    //
+    // ONE-GENERATION GRACE WINDOW (hub#685). Benign concurrent/retried
+    // refreshes — a multi-tab SPA, a bfcache/stale-tab resume, a network
+    // retry — legitimately present the *just-rotated* token a moment after
+    // it rotated. To avoid forcing those real clients to re-login, we let
+    // through the SINGLE immediately-previous token, and ONLY it, for
+    // ~REFRESH_GRACE_MS. The grace case rotates the live tip and converges
+    // the replaying client onto the current token; it does NOT mint a
+    // second live token into a forked lineage.
+    //
+    // The window is narrow ON PURPOSE — both conditions must hold:
+    //   (a) WINDOW: this row was revoked within the last REFRESH_GRACE_MS.
+    //   (b) IMMEDIATE-PREDECESSOR: this row's recorded successor (rotated_to)
+    //       IS the family's single live refresh row. That proves it's the
+    //       direct parent of the current tip — not an older ancestor (whose
+    //       successor is itself revoked) and not a sibling fork.
+    //
+    // HARD SECURITY INVARIANT: anything outside (a)∧(b) — an OLDER/ancestor
+    // token, any replay past the window, a family with zero or multiple live
+    // tips (already a theft-revoked or forked family) — falls through to the
+    // unchanged zero-tolerance path: revokeFamily + invalid_grant. The grace
+    // window NEVER tolerates more than the one immediate predecessor, and
+    // never beyond REFRESH_GRACE_MS.
+    const live = liveFamilyRefreshRows(db, row.familyId, now);
+    const revokedAtMs = new Date(row.revokedAt).getTime();
+    const withinWindow =
+      now.getTime() - revokedAtMs <= REFRESH_GRACE_MS && now.getTime() >= revokedAtMs;
+    const tip = live.length === 1 ? live[0]! : null;
+    const isImmediatePredecessor =
+      tip !== null && row.rotatedTo !== null && row.rotatedTo === tip.jti;
+    if (withinWindow && isImmediatePredecessor && tip) {
+      // Benign replay of the immediate predecessor. Rotate the live tip and
+      // hand the client the new pair — it converges on the current lineage
+      // (single live token preserved), no family revocation. Equivalent to
+      // what the client would have received had it presented the tip itself.
+      return await rotateAndRespond(db, tip, deps, now);
+    }
+    // Genuine theft (or a too-late replay): revoke every descendant so the
+    // attacker can't keep refreshing, and force re-authorization.
     revokeFamily(db, row.familyId, now);
     return jsonResponse(
       { error: "invalid_grant", error_description: "refresh_token revoked" },
@@ -2239,17 +2279,34 @@ async function handleTokenRefresh(
       400,
     );
   }
-  // Rotate: revoke the old refresh row, mint a new access + refresh pair
-  // bound to the same family so a future replay of *any* descendant can
-  // walk the chain.
-  //
+  return await rotateAndRespond(db, row, deps, now);
+}
+
+/**
+ * Rotate a single live refresh-token row: revoke it, mint + insert a new
+ * access + refresh pair bound to the same family, and link old→new
+ * (`rotated_to`) so a future grace-window check can identify the direct
+ * predecessor (hub#685). Returns the spec-shaped token response.
+ *
+ * Both call sites pass a row that is live at the moment of the call: the
+ * normal path passes the presented (non-revoked) token; the grace path
+ * passes the family's single live tip. Used for both so the benign-replay
+ * client receives exactly what a direct refresh of the tip would yield.
+ */
+async function rotateAndRespond(
+  db: Database,
+  row: RefreshTokenRow,
+  deps: OAuthDeps,
+  now: Date,
+): Promise<Response> {
+  const refreshUserId = row.userId ?? "";
   // Mint the access token *before* opening the rotation transaction. JWT
   // signing is async (jose returns a Promise) and bun:sqlite's
   // `db.transaction()` is sync — running async work inside the closure
   // would silently break atomicity. Once we have the JWT, the UPDATE
-  // (revoke old) + INSERT (mint new refresh row) commit or roll back as
-  // a unit, so a mid-rotation crash can't dead-old-without-replacement
-  // (#107).
+  // (revoke old) + INSERT (mint new refresh row) + link (rotated_to) commit
+  // or roll back as a unit, so a mid-rotation crash can't
+  // dead-old-without-replacement (#107).
   const audience = inferAudience(row.scopes);
   const access = await signAccessToken(db, {
     sub: refreshUserId,
@@ -2271,7 +2328,7 @@ async function handleTokenRefresh(
   try {
     refresh = db.transaction(() => {
       db.prepare("UPDATE tokens SET revoked_at = ? WHERE jti = ?").run(now.toISOString(), row.jti);
-      return signRefreshToken(db, {
+      const minted = signRefreshToken(db, {
         jti: access.jti,
         userId: refreshUserId,
         clientId: row.clientId,
@@ -2279,6 +2336,10 @@ async function handleTokenRefresh(
         familyId: row.familyId,
         now: deps.now,
       });
+      // Link old→new so the grace-window check (hub#685) can tell the
+      // immediate predecessor apart from an older ancestor on replay.
+      linkRotation(db, row.jti, access.jti);
+      return minted;
     })();
   } catch (err) {
     // Concurrent rotation: a sibling refresh of the same row already

package/src/rate-limit.ts

@@ -1,7 +1,12 @@
 /**
  * Rate-limit primitives for hub auth-surface endpoints.
  *
- * Two limiters today (one floor each — neither is the primary defense):
+ * Each limiter is a floor, not the primary defense. Two are highlighted below
+ * for their contrasting threat models; the rest (`/login/2fa`, vault-token
+ * mint, public signup) are documented at their `export const` definitions.
+ * The public-signup limiter is the deliberate OUTLIER — generous, not tight —
+ * because its endpoint is meant to be redeemed by a room of people sharing one
+ * egress IP (see `SIGNUP_MAX_ATTEMPTS`).
  *
  *   - `/login` (per-IP, hub#187 / hub#188): 5 attempts / 15 min.
  *     Lands as a floor under brute-force after hub#187 collapsed the
@@ -109,6 +114,27 @@ export const VAULT_TOKEN_MINT_WINDOW_MS = 10 * 60 * 1000;
  * minutes is generous for a human and still chokes a stolen-cookie flood.
  */
 export const VAULT_TOKEN_MINT_MAX_ATTEMPTS = 10;
+/**
+ * `POST /account/setup/<token>` (public invite redemption / signup) window
+ * length: 15 minutes — same window as `/login`, but a MUCH larger cap (below)
+ * because the threat model is the opposite. A public multi-use signup link is
+ * meant to be redeemed by a ROOM OF PEOPLE, and a demo room shares ONE NAT'd
+ * egress IP — so a per-IP `/login`-sized cap (5/15min) would 429 the ~6th
+ * legitimate signer. This bucket is deliberately generous so a shared egress
+ * IP comfortably handles a cohort, while still being a floor against an
+ * attacker scripting account creation against an open link (the invite's
+ * own `max_uses` + expiry are the primary bound; this is the abuse floor).
+ * Separate bucket from `/login` so a signup flurry never burns the login
+ * window, and vice-versa.
+ */
+export const SIGNUP_WINDOW_MS = 15 * 60 * 1000;
+/**
+ * `POST /account/setup/<token>` attempts allowed per IP per window. 60 is
+ * comfortably above a single demo room behind one NAT (and well above any
+ * legitimate human's retries) while still capping a scripted-abuse rate to
+ * ~4/min sustained. The 61st attempt within the window is denied.
+ */
+export const SIGNUP_MAX_ATTEMPTS = 60;
 /** Sentinel for the IP-extraction priority chain when nothing parsed. */
 export const UNKNOWN_IP_SENTINEL = "unknown";
 
@@ -246,6 +272,16 @@ export const vaultTokenMintRateLimiter = new RateLimiter(
   VAULT_TOKEN_MINT_WINDOW_MS,
 );
 
+/**
+ * `POST /account/setup/<token>` rate limiter — per-IP, 60 attempts / 15 min
+ * (public invite redemption / signup). DELIBERATELY generous: a public
+ * multi-use signup link is redeemed by a room of people sharing one NAT'd
+ * egress IP, so a `/login`-sized cap would 429 legitimate signers mid-demo.
+ * Separate bucket from `/login` so the two never share a window. The invite's
+ * own `max_uses` + expiry are the primary bound; this is the abuse floor.
+ */
+export const signupRateLimiter = new RateLimiter(SIGNUP_MAX_ATTEMPTS, SIGNUP_WINDOW_MS);
+
 /**
  * Backwards-compat shim for hub#188's call sites: the original
  * top-level `checkAndRecord` was the login limiter. New code should
@@ -266,6 +302,7 @@ export function __resetForTests(): void {
   changePasswordRateLimiter.reset();
   totpRateLimiter.reset();
   vaultTokenMintRateLimiter.reset();
+  signupRateLimiter.reset();
 }
 
 /**