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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3-rc.2",
+  "version": "0.7.3-rc.3",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/jwt-sign.test.ts

@@ -10,7 +10,9 @@ import {
   RefreshTokenInsertError,
   findRefreshToken,
   findTokenRowByJti,
+  linkRotation,
   listActiveRevocations,
+  liveFamilyRefreshRows,
   recordTokenMint,
   revokeTokenByJti,
   signAccessToken,
@@ -623,3 +625,80 @@ describe("token registry (hub#212 Phase 1)", () => {
     }
   });
 });
+
+// hub#685 — rotation-grace primitives. The grace decision in
+// `handleTokenRefresh` is built on these two helpers; unit-cover them
+// directly so the security-load-bearing predecessor check has a tight test.
+describe("rotation grace primitives (hub#685)", () => {
+  test("rotatedTo is null on a freshly minted row, set by linkRotation", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      signRefreshToken(db, {
+        jti: "pred",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-1",
+      });
+      expect(findTokenRowByJti(db, "pred")?.rotatedTo).toBeNull();
+
+      signRefreshToken(db, {
+        jti: "succ",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-1",
+      });
+      linkRotation(db, "pred", "succ");
+      expect(findTokenRowByJti(db, "pred")?.rotatedTo).toBe("succ");
+      // Successor itself has not rotated yet.
+      expect(findTokenRowByJti(db, "succ")?.rotatedTo).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("liveFamilyRefreshRows returns only un-revoked, un-expired refresh rows in the family", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      const t0 = new Date("2026-06-24T00:00:00Z");
+      for (const jti of ["a", "b", "c"]) {
+        signRefreshToken(db, {
+          jti,
+          userId: u.id,
+          clientId: "parachute-hub",
+          scopes: ["vault:read"],
+          familyId: "fam-x",
+          now: () => t0,
+        });
+      }
+      // A different family — must never leak in.
+      signRefreshToken(db, {
+        jti: "other",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-y",
+        now: () => t0,
+      });
+      // Revoke one of the three.
+      revokeTokenByJti(db, "b", t0);
+
+      const live = liveFamilyRefreshRows(db, "fam-x", t0)
+        .map((r) => r.jti)
+        .sort();
+      expect(live).toEqual(["a", "c"]);
+
+      // Evaluated PAST the 30-day TTL: every row in the family is expired,
+      // so none count as a live tip — the grace path can't rotate into one.
+      const afterExpiry = new Date(t0.getTime() + REFRESH_TOKEN_TTL_MS + 1);
+      expect(liveFamilyRefreshRows(db, "fam-x", afterExpiry)).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/oauth-handlers.test.ts

@@ -14,7 +14,12 @@ import {
   openFirstClientAutoApproveWindow,
   setSetting,
 } from "../hub-settings.ts";
-import { findTokenRowByJti, validateAccessToken } from "../jwt-sign.ts";
+import {
+  REFRESH_GRACE_MS,
+  findTokenRowByJti,
+  signRefreshToken,
+  validateAccessToken,
+} from "../jwt-sign.ts";
 import {
   authorizationServerMetadata,
   buildServicesCatalog,
@@ -2262,6 +2267,7 @@ describe("handleToken — full OAuth dance", () => {
         refresh_token: initial.refresh_token,
         client_id: reg.client.clientId,
       });
+      const rotateAt = new Date("2026-06-24T00:00:00Z");
       const refreshRes = await handleToken(
         db,
         new Request(`${ISSUER}/oauth/token`, {
@@ -2269,13 +2275,16 @@ describe("handleToken — full OAuth dance", () => {
           body: refreshForm,
           headers: { "content-type": "application/x-www-form-urlencoded" },
         }),
-        { issuer: ISSUER },
+        { issuer: ISSUER, now: () => rotateAt },
       );
       expect(refreshRes.status).toBe(200);
       const rotated = (await refreshRes.json()) as { refresh_token: string };
       expect(rotated.refresh_token).not.toBe(initial.refresh_token);
 
-      // Old refresh token should now fail (revoked).
+      // Old refresh token replayed PAST the one-generation grace window
+      // should fail (revoked) — the immediate-predecessor grace (hub#685)
+      // only tolerates a replay within REFRESH_GRACE_MS. Replay an hour
+      // later: genuine zero-tolerance rejection.
       const replayRes = await handleToken(
         db,
         new Request(`${ISSUER}/oauth/token`, {
@@ -2283,7 +2292,7 @@ describe("handleToken — full OAuth dance", () => {
           body: refreshForm,
           headers: { "content-type": "application/x-www-form-urlencoded" },
         }),
-        { issuer: ISSUER },
+        { issuer: ISSUER, now: () => new Date(rotateAt.getTime() + 60 * 60 * 1000) },
       );
       expect(replayRes.status).toBe(400);
       const err = (await replayRes.json()) as Record<string, unknown>;
@@ -4125,6 +4134,284 @@ describe("refresh-token rotation + /oauth/revoke (#73)", () => {
     }
   });
 
+  // hub#685 — one-generation rotation grace window. A benign concurrent /
+  // retried refresh of the *immediately-previous* (just-rotated) token within
+  // REFRESH_GRACE_MS must NOT revoke the family (multi-tab SPA, bfcache/
+  // stale-tab resume, network retry). Genuine theft — an older ancestor, or
+  // any replay past the window — MUST still revoke the family.
+  describe("rotation grace window (hub#685)", () => {
+    function liveRefreshCount(
+      db: Awaited<ReturnType<typeof makeDb>>["db"],
+      familyId: string,
+    ): number {
+      const r = db
+        .query<{ n: number }, [string]>(
+          "SELECT COUNT(*) AS n FROM tokens WHERE family_id = ? AND revoked_at IS NULL AND refresh_token_hash IS NOT NULL",
+        )
+        .get(familyId);
+      return r?.n ?? -1;
+    }
+
+    async function refreshAt(
+      db: Awaited<ReturnType<typeof makeDb>>["db"],
+      clientId: string,
+      refreshToken: string,
+      at: Date,
+    ): Promise<Response> {
+      return handleToken(
+        db,
+        tokenRequest(
+          new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: clientId,
+          }),
+        ),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest, now: () => at },
+      );
+    }
+
+    test("benign concurrent refresh of the immediate predecessor within the window succeeds, no family revocation", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        // First (legitimate) rotation at t0 — `initial` becomes the immediate
+        // predecessor; rotated1 is the single live tip.
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        expect(r1.status).toBe(200);
+        const rotated1 = (await r1.json()) as { refresh_token: string };
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // A moment later (5s, well within REFRESH_GRACE_MS) a stale tab /
+        // retry replays `initial`. Benign: succeeds, and converges the client
+        // onto the lineage rather than revoking the family.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 5_000),
+        );
+        expect(replay.status).toBe(200);
+        const replayed = (await replay.json()) as { refresh_token: string; access_token: string };
+        expect(replayed.refresh_token).toBeTruthy();
+        expect(replayed.access_token).toBeTruthy();
+
+        // No family-wide revocation: exactly one live refresh row remains
+        // (the grace path rotated the tip → its successor is the new tip).
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // The token handed back is usable for a normal subsequent refresh.
+        const next = await refreshAt(
+          db,
+          reg.client.clientId,
+          replayed.refresh_token,
+          new Date(t0.getTime() + 10_000),
+        );
+        expect(next.status).toBe(200);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("genuine reuse of an OLDER ancestor (two generations back) revokes the family even within the window", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        // Two legitimate rotations: initial → rotated1 → rotated2. `initial`
+        // is now an ancestor (its successor rotated1 is itself revoked).
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        const rotated1 = (await r1.json()) as { refresh_token: string };
+        const r2 = await refreshAt(
+          db,
+          reg.client.clientId,
+          rotated1.refresh_token,
+          new Date(t0.getTime() + 1_000),
+        );
+        expect(r2.status).toBe(200);
+
+        // Replay the ANCESTOR `initial` still within the window. Condition (b)
+        // fails — its successor (rotated1) is not the live tip — so this is
+        // treated as theft: family revoked.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 2_000),
+        );
+        expect(replay.status).toBe(400);
+        expect(((await replay.json()) as Record<string, unknown>).error).toBe("invalid_grant");
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("replay of the immediate predecessor AFTER the window revokes the family", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        expect(r1.status).toBe(200);
+
+        // Replay the immediate predecessor 1ms PAST the window. Condition (a)
+        // fails: zero-tolerance theft handling applies.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + REFRESH_GRACE_MS + 1),
+        );
+        expect(replay.status).toBe(400);
+        expect(((await replay.json()) as Record<string, unknown>).error).toBe("invalid_grant");
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("window boundary: exactly at the edge succeeds, one ms past fails", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+
+        // Just inside (=== REFRESH_GRACE_MS): benign success, family intact.
+        const aPair = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const aFamily = familyIdFor(db, aPair.refresh_token);
+        const a0 = new Date("2026-06-24T00:00:00Z");
+        await refreshAt(db, reg.client.clientId, aPair.refresh_token, a0);
+        const inEdge = await refreshAt(
+          db,
+          reg.client.clientId,
+          aPair.refresh_token,
+          new Date(a0.getTime() + REFRESH_GRACE_MS),
+        );
+        expect(inEdge.status).toBe(200);
+        expect(liveRefreshCount(db, aFamily)).toBe(1);
+
+        // One ms past the edge: theft handling, family revoked.
+        const bPair = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const bFamily = familyIdFor(db, bPair.refresh_token);
+        const b0 = new Date("2026-06-24T01:00:00Z");
+        await refreshAt(db, reg.client.clientId, bPair.refresh_token, b0);
+        const outEdge = await refreshAt(
+          db,
+          reg.client.clientId,
+          bPair.refresh_token,
+          new Date(b0.getTime() + REFRESH_GRACE_MS + 1),
+        );
+        expect(outEdge.status).toBe(400);
+        expect(liveRefreshCount(db, bFamily)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("repeated benign replays of the same predecessor each converge on a live tip (idempotent-equivalent)", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+
+        // First benign replay of `initial`: succeeds, rotates the tip.
+        const replay1 = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 1_000),
+        );
+        expect(replay1.status).toBe(200);
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // A SECOND replay of the SAME predecessor `initial`. Its successor is
+        // now revoked (the first replay rotated the tip), so `initial` is no
+        // longer the direct predecessor of the single live tip → theft. The
+        // grace window protects exactly ONE generation, not unbounded replay.
+        const replay2 = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 2_000),
+        );
+        expect(replay2.status).toBe(400);
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("already-forked family (multiple live tips) does NOT take the grace path — family revoked", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        // One legitimate rotation → `initial` is the immediate predecessor of
+        // the single live tip (live count == 1, the benign precondition).
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        expect(r1.status).toBe(200);
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // Inject a SECOND live refresh row into the same family — simulating a
+        // family that has already forked into multiple live lineages (an
+        // already-compromised state). Now live count != 1, so `tip` is null.
+        signRefreshToken(db, {
+          jti: "injected-fork-jti",
+          userId: user.id,
+          clientId: reg.client.clientId,
+          scopes: ["vault:default:read"],
+          familyId: family,
+          now: () => t0,
+        });
+        expect(liveRefreshCount(db, family)).toBe(2);
+
+        // Replay the immediate predecessor WITHIN the window. Even though (a)
+        // holds and `initial.rotatedTo` is set, the single-live-tip check
+        // fails (2 live rows) → no grace → zero-tolerance family revocation.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 1_000),
+        );
+        expect(replay.status).toBe(400);
+        expect(((await replay.json()) as Record<string, unknown>).error).toBe("invalid_grant");
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
   test("/oauth/revoke refresh_token: revokes the row, second use rejected", async () => {
     const { db, cleanup } = await makeDb();
     try {

package/src/hub-db.ts

@@ -451,6 +451,29 @@ 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;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {

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