@12-apps/mcp 3.16.0 → 3.17.0

package/src/oauth/refresh.ts

@@ -1,5 +1,11 @@
 import { createHash, randomBytes } from "node:crypto";
 
+import {
+  DEFAULT_ROTATION_GRACE_MS,
+  openSuccessor,
+  sealSuccessor,
+} from "./rotation-grace";
+import { revokeLineage } from "./refresh-lineage";
 import type { NewRefreshToken, RefreshTokenStore, StoredRefreshToken } from "./stores";
 
 /**
@@ -16,14 +22,28 @@ import type { NewRefreshToken, RefreshTokenStore, StoredRefreshToken } from "./s
  *     + scopes;
  *   - {@link rotateRefreshToken} consumes a token: it issues a NEW token chained
  *     via `rotatedFrom` and revokes the parent, so a token is single-use;
- *   - reuse of an already-rotated/revoked token is a REPLAY: rejected, AND the
- *     whole lineage (every ancestor + descendant reachable through `rotatedFrom`)
- *     is revoked — the OAuth 2.1 refresh-token replay rule;
- *   - CONCURRENT reuse is the same event and gets the same answer. The store's
- *     `rotate` is a claim-once write, so of two simultaneous rotations of one
- *     parent exactly one is issued a successor and the other is treated as the
- *     replay it is. Without that, replay protection would be bypassable by
- *     WINNING a race instead of arriving second (see `RefreshTokenStore.rotate`);
+ *   - reuse of an already-rotated/revoked token OUTSIDE the grace window is a
+ *     REPLAY: rejected, AND the whole lineage (every ancestor + descendant
+ *     reachable through `rotatedFrom`) is revoked — the OAuth 2.1 refresh-token
+ *     replay rule;
+ *   - reuse INSIDE the window is a RETRY, and answers with the successor that
+ *     rotation already minted rather than a second one (`./rotation-grace.ts`).
+ *     A lost response and two concurrent refreshes are the routine reasons one
+ *     client uses one token twice, and punishing them as theft is what cost a
+ *     connected user their session and sent them back through the whole
+ *     authorization flow;
+ *   - CONCURRENT reuse takes that same retry path. The store's `rotate` is a
+ *     claim-once write, so of two simultaneous rotations of one parent exactly
+ *     one successor is ever WRITTEN — that invariant is untouched, and without it
+ *     replay protection would be bypassable by WINNING a race instead of arriving
+ *     second (see `RefreshTokenStore.rotate`). The loser is now handed the
+ *     winner's token instead of destroying it;
+ *   - the cost is real and is NOT a one-rotation deferral: two parties left
+ *     holding one successor take the retry path again at every subsequent
+ *     rotation, so they stay in lockstep for as long as their uses keep falling
+ *     inside the window. What survives is: a collision is detected only when the
+ *     two uses fall more than `graceMs` apart. `./rotation-grace.ts` argues why
+ *     that is the accepted trade and `graceMs: 0` is the way back out;
  *   - rotate may only NARROW scope (new ⊆ original); broadening is rejected and
  *     nothing new is stored.
  */
@@ -74,6 +94,21 @@ export interface RefreshTokenContext {
   store: RefreshTokenStore;
   /** Lifetime of a newly stored token. Default 30 days. */
   ttlMs?: number;
+  /**
+   * How long a just-rotated token keeps answering with the successor it minted,
+   * instead of being treated as a replay. Default
+   * {@link DEFAULT_ROTATION_GRACE_MS}; `0` restores the strict rule.
+   *
+   * This is what makes a rotation RETRYABLE. See `./rotation-grace.ts` for why the
+   * window returns the same successor rather than minting a second one, and why
+   * that keeps replay detection intact.
+   */
+  graceMs?: number;
+}
+
+/** The configured grace window, in milliseconds. `<= 0` disables it. */
+function graceWindowMs(context: RefreshTokenContext): number {
+  return context.graceMs ?? DEFAULT_ROTATION_GRACE_MS;
 }
 
 function expiryOf(context: RefreshTokenContext): Date {
@@ -102,84 +137,115 @@ export async function issueRefreshToken(
   return { refreshToken, scopes: binding.scopes };
 }
 
-/**
- * A pre-built O(1)-lookup index of one `(userEmail, clientId)` token family:
- * `byHash` resolves a hash to its row (to walk ancestors via `rotatedFrom`), and
- * `childrenOf` is the reverse index mapping a parent hash to its direct successor
- * hashes (to walk descendants). Both are built in a single pass so the lineage
- * traversal never re-scans the family (no O(n²) inner loop).
- */
-interface LineageIndex {
-  byHash: Map<string, StoredRefreshToken>;
-  childrenOf: Map<string, string[]>;
+/** Reject any requested scope not already on the token (narrow-only). */
+function narrowedScopes(current: StoredRefreshToken, requested?: string[]): string[] {
+  const scopes = requested ?? current.scopes;
+  const original = new Set(current.scopes);
+  for (const scope of scopes) {
+    if (!original.has(scope)) {
+      throw new RefreshTokenError(
+        "invalid_scope",
+        `scope '${scope}' broadens the refresh token grant`,
+      );
+    }
+  }
+  return scopes;
 }
 
-function buildLineageIndex(family: StoredRefreshToken[]): LineageIndex {
-  const byHash = new Map<string, StoredRefreshToken>();
-  const childrenOf = new Map<string, string[]>();
-  for (const row of family) {
-    byHash.set(row.tokenHash, row);
-    if (!row.rotatedFrom) continue;
-    const siblings = childrenOf.get(row.rotatedFrom) ?? [];
-    siblings.push(row.tokenHash);
-    childrenOf.set(row.rotatedFrom, siblings);
+/** Set equality over scope lists, which are unordered and may repeat. */
+function sameScopes(left: readonly string[], right: readonly string[]): boolean {
+  const wanted = new Set(left);
+  const held = new Set(right);
+  if (wanted.size !== held.size) return false;
+  for (const scope of wanted) {
+    if (!held.has(scope)) return false;
   }
-  return { byHash, childrenOf };
+  return true;
+}
+
+/** The one successor a retry may be answered with: its seal and what it grants. */
+interface RetryTarget {
+  seal: string;
+  scopes: string[];
 }
 
 /**
- * Collect every token hash reachable from `seedHash` — its ancestors (via
- * `rotatedFrom`) and its descendants (via the reverse index) — by a BFS over the
- * pre-built index. Each neighbour lookup is O(1), so the walk is linear in the
- * family size.
+ * Pick the successor a retry is entitled to, or `null` to fall through to the
+ * replay rule.
+ *
+ * FILTER, not find. Two rows sharing one `rotatedFrom` cannot happen while
+ * `rotate` honours its claim-once contract — but the lineage walk in
+ * `./refresh-lineage.ts` already treats multiple children as possible, and
+ * serving an arbitrary one of them would be the quiet half of a broken store, so
+ * an ambiguous family fails closed.
+ *
+ * A REVOKED successor means the lineage already died to a real replay, and grace
+ * must never resurrect it; an expired one is past its own TTL. Neither is a
+ * retry the window was opened to forgive.
  */
-function collectLineage(index: LineageIndex, seedHash: string): Set<string> {
-  const lineage = new Set<string>();
-  const queue = [seedHash];
-  while (queue.length > 0) {
-    const hash = queue.shift();
-    if (!hash || lineage.has(hash)) continue;
-    lineage.add(hash);
-
-    const parent = index.byHash.get(hash)?.rotatedFrom ?? null;
-    if (parent && !lineage.has(parent)) queue.push(parent);
-
-    const children = (index.childrenOf.get(hash) ?? []).filter((child) => !lineage.has(child));
-    queue.push(...children);
-  }
-  return lineage;
+function retryableSuccessor(
+  family: StoredRefreshToken[],
+  tokenHash: string,
+  now: number,
+): RetryTarget | null {
+  const successors = family.filter((row) => row.rotatedFrom === tokenHash);
+  if (successors.length !== 1) return null;
+  const [successor] = successors;
+  if (!successor?.graceSeal || successor.revokedAt) return null;
+  if (successor.expiresAt.getTime() <= now) return null;
+  return { seal: successor.graceSeal, scopes: successor.scopes };
 }
 
 /**
- * Walk a token's rotation lineage (both directions) and revoke every token in it.
- * Called on replay detection, so a leaked refresh token — once reused —
- * invalidates the entire chain it belongs to.
+ * The grace path: a token that was already consumed is being presented again.
+ *
+ * Returns the successor that consumption minted — the SAME one, recovered by
+ * opening the seal with the parent the caller just presented — when every
+ * condition for a retry holds, and `null` when any of them does not, in which
+ * case the caller falls through to the replay rule unchanged.
+ *
+ * The conditions are the security argument, so each is checked rather than
+ * assumed:
+ *
+ *   - exactly one unrevoked, unexpired successor exists ({@link retryableSuccessor});
+ *   - the seal opens with THIS parent, which is what proves the caller held the
+ *     token it claims to be retrying rather than merely knowing its hash;
+ *   - the sealed deadline has not passed. It rides inside the AEAD blob, so it
+ *     cannot be extended by editing the row;
+ *   - the request asks for the same scopes. A retry repeats its original
+ *     request; a different scope set is a NEW decision, and answering it with a
+ *     token minted for the old one would silently ignore what was asked.
  */
-async function revokeLineage(
+async function graceReissue(
   context: RefreshTokenContext,
-  scopedTo: Pick<StoredRefreshToken, "userEmail" | "clientId">,
-  seedHash: string,
-): Promise<void> {
-  // The lineage is confined to one (userEmail, clientId) pair, so load that set
-  // once and walk the `rotatedFrom` links in memory — a small, bounded chain.
-  const family = await context.store.listFamily(scopedTo.userEmail, scopedTo.clientId);
-  const lineage = collectLineage(buildLineageIndex(family), seedHash);
-  await context.store.revokeHashes([...lineage], new Date());
-}
+  current: StoredRefreshToken,
+  tokenHash: string,
+  parentPlaintext: string,
+  requestedScopes?: string[],
+): Promise<IssuedRefreshToken | null> {
+  if (graceWindowMs(context) <= 0) return null;
 
-/** Reject any requested scope not already on the token (narrow-only). */
-function narrowedScopes(current: StoredRefreshToken, requested?: string[]): string[] {
-  const scopes = requested ?? current.scopes;
-  const original = new Set(current.scopes);
-  for (const scope of scopes) {
-    if (!original.has(scope)) {
-      throw new RefreshTokenError(
-        "invalid_scope",
-        `scope '${scope}' broadens the refresh token grant`,
-      );
-    }
+  const now = Date.now();
+  const family = await context.store.listFamily(current.userEmail, current.clientId);
+  const target = retryableSuccessor(family, tokenHash, now);
+  if (!target) return null;
+
+  const opened = openSuccessor(parentPlaintext, target.seal);
+  if (!opened || opened.graceUntil <= now) return null;
+
+  // Inside the window and the seal opened, so this IS the retry it looks like —
+  // but it asks for something else. Refusing is right; refusing as a REPLAY is
+  // not, because that revokes the whole lineage and destroys a live session for
+  // the innocent double-use this window exists to forgive. Say `invalid_scope`
+  // and leave the family alone.
+  if (requestedScopes && !sameScopes(requestedScopes, target.scopes)) {
+    throw new RefreshTokenError(
+      "invalid_scope",
+      "a retry inside the rotation grace window cannot change scope",
+    );
   }
-  return scopes;
+
+  return { refreshToken: opened.successor, scopes: target.scopes };
 }
 
 /**
@@ -216,14 +282,19 @@ export async function rotateRefreshToken(
   if (current.expiresAt.getTime() <= Date.now()) {
     throw new RefreshTokenError("invalid_grant", "refresh token expired");
   }
-  // Already revoked OR already used as the parent of a rotation → REPLAY. Revoke
-  // the whole lineage and reject.
+  // Already revoked OR already used as the parent of a rotation. Inside the grace
+  // window this is a RETRY and answers with the successor that consumption
+  // already minted; outside it, it is the replay it looks like — rejected, with
+  // the whole lineage revoked.
   if (current.revokedAt || (await context.store.hasSuccessor(tokenHash))) {
+    const retried = await graceReissue(context, current, tokenHash, plaintext, newScopes);
+    if (retried) return retried;
     await replay(context, current, tokenHash);
   }
 
   const scopes = narrowedScopes(current, newScopes);
   const successorPlaintext = generateToken();
+  const grace = graceWindowMs(context);
   const claimed = await context.store.rotate(
     {
       tokenHash: hashToken(successorPlaintext),
@@ -233,19 +304,35 @@ export async function rotateRefreshToken(
       scopes,
       expiresAt: expiryOf(context),
       rotatedFrom: tokenHash,
+      // Sealed under the PARENT the caller just presented, so a retry of this
+      // very rotation can be answered with this same token and nothing else can
+      // read it. Omitted entirely when the window is off, so the strict rule
+      // stores nothing extra.
+      graceSeal:
+        grace > 0 ? sealSuccessor(plaintext, successorPlaintext, Date.now() + grace) : null,
     },
     tokenHash,
     new Date(),
   );
   // The checks above are a READ, so a concurrent rotation of the same parent can
   // pass them too; `rotate` is the serialization point and it hands the claim to
-  // exactly one caller. Losing it is the SAME event as the replay branch above —
-  // one token used twice — so it gets the same answer, deliberately: reject, and
-  // revoke the lineage including the winner's fresh successor. Rejecting without
-  // revoking would leave a race-winning attacker holding a live family, which is
-  // the whole attack; and a client that legitimately double-submits already loses
-  // its family in the sequential case, so this is consistent rather than harsher.
-  if (!claimed) await replay(context, current, tokenHash);
+  // exactly one caller. Exactly one successor is therefore ever written — that
+  // part is unchanged, and it is the invariant replay protection rests on.
+  //
+  // What the loser is TOLD changed. It used to be the replay answer: reject, and
+  // revoke the lineage including the successor just handed to the winner. That
+  // is correct against an attacker racing the client, and catastrophic for the
+  // far more common case of one client refreshing twice — it destroyed a working
+  // session and forced a human back through the authorization flow. So the loser
+  // now takes the same grace path as a sequential retry and receives the WINNER's
+  // token: one successor, two callers holding it, no second family. What that
+  // costs is stated honestly in `./rotation-grace.ts` — not a one-rotation
+  // deferral, but detection only once two uses fall more than the window apart.
+  if (!claimed) {
+    const retried = await graceReissue(context, current, tokenHash, plaintext, newScopes);
+    if (retried) return retried;
+    await replay(context, current, tokenHash);
+  }
 
   return { refreshToken: successorPlaintext, scopes };
 }
@@ -256,7 +343,7 @@ async function replay(
   current: StoredRefreshToken,
   tokenHash: string,
 ): Promise<never> {
-  await revokeLineage(context, current, tokenHash);
+  await revokeLineage(context.store, current, tokenHash);
   throw new RefreshTokenError(
     "invalid_grant",
     "refresh token already used (replay) — lineage revoked",

package/src/oauth/rotation-grace.ts

@@ -0,0 +1,216 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "node:crypto";
+
+/**
+ * The sealed successor that makes refresh rotation IDEMPOTENT for the length of a
+ * grace window — the half of `refresh.ts` that lets a legitimate client survive a
+ * lost response or a concurrent refresh without losing its session.
+ *
+ * ## The problem this exists to solve
+ *
+ * Rotation-on-use plus replay revocation is the OAuth 2.1 rule, and it is right:
+ * a stolen refresh token is detected the moment BOTH the thief and the rightful
+ * client use it, and the whole lineage dies. What that rule cannot tell apart is
+ * a thief from a client that used its token twice for an innocent reason, and
+ * there are two of those, both routine:
+ *
+ *   - **the lost response.** The client rotates, the 200 never arrives (a proxy
+ *     timeout, a dropped connection), and it retries with the only token it
+ *     still has — the one the server already consumed.
+ *   - **the concurrent refresh.** Two of the client's own sessions notice an
+ *     expired access token at the same moment and both refresh.
+ *
+ * Without a grace window both are punished as theft: the lineage is revoked,
+ * INCLUDING the successor just handed to whoever won, and the connection is dead
+ * until a human re-runs the whole authorization flow. That is the failure this
+ * module removes.
+ *
+ * ## Why a SEALED successor rather than a second one
+ *
+ * The obvious shortcut — mint a fresh successor for every in-window reuse — is
+ * the one thing that must not happen. It leaves one parent with two live
+ * successors and two independently rotating families, which is precisely the
+ * state replay protection exists to prevent: an attacker holding a stolen token
+ * would only have to fire it alongside the real client to walk away with a
+ * family of its own. So the window returns *the same* successor to every caller
+ * that presents the parent. Reuse becomes idempotent instead of forgiven, and
+ * exactly one successor is ever written.
+ *
+ * ## What detection this actually costs — stated plainly
+ *
+ * It would be convenient to say detection is merely DEFERRED by one rotation.
+ * It is not, and the code does not provide that. Two parties left holding one
+ * successor take this same path again at the next rotation, and again after
+ * that: whichever of them arrives second is inside a fresh window each time, so
+ * they stay in lockstep indefinitely. The honest guarantee is narrower:
+ *
+ *   **a collision is detected only when the two uses fall more than the window
+ *   apart.**
+ *
+ * A thief who replays a freshly stolen token within the window of the real
+ * client's rotation is handed a live token and raises no signal — and that
+ * timing is precisely what the window exists to forgive, so it cannot be
+ * distinguished. This is the accepted cost, and it is why the window is short
+ * by default, why it is configurable, and why `0` restores the strict rule for
+ * a deployment that would rather pay in re-authentications.
+ *
+ * ## Why the key is derived from the parent, and nothing is stored in the clear
+ *
+ * Returning the same successor means recovering its plaintext, and the plaintext
+ * is exactly what `refresh.ts` promises never to persist. So it is not persisted:
+ * it is sealed under a key derived by HKDF from the PARENT's own plaintext, and
+ * only the sealed blob reaches the store. The consequences are the point:
+ *
+ *   - the database alone cannot open it. The parent's plaintext is never stored
+ *     either, so a dump of the tokens table yields ciphertext and no key — the
+ *     "hashed, never plaintext" invariant is unchanged;
+ *   - the only party that CAN open it is a caller presenting the parent, which is
+ *     the caller we mean to serve. It grants no capability that party lacks: it
+ *     already held the parent, and the parent is what mints the successor;
+ *   - the grace deadline is sealed INSIDE the blob rather than kept in a column,
+ *     so an attacker with write access to the row cannot extend the window
+ *     without also being able to forge the AES-GCM tag.
+ *
+ * One honest limit on that last point. The deadline is enforced by the server
+ * when it opens a seal, not by the ciphertext, and a seal is cleared when its
+ * token is consumed or revoked — not when its window lapses. So the ONE hop an
+ * attacker holding a spent parent plaintext plus a table read can take is bounded
+ * by when the successor is next used, which for an idle connection is the refresh
+ * token's TTL rather than `graceMs`. Bounded to one hop either way, because every
+ * consume and every revoke clears the parent's seal; sweeping lapsed seals would
+ * tighten it to the window itself.
+ */
+
+/** AEAD, so a tampered blob fails to open rather than decrypting to garbage. */
+const ALGORITHM = "aes-256-gcm";
+
+/** 96-bit nonce — the size AES-GCM is specified for. */
+const IV_BYTES = 12;
+
+/** AES-256. */
+const KEY_BYTES = 32;
+
+/** GCM authentication tag length in bytes. */
+const TAG_BYTES = 16;
+
+/** Domain separation for the HKDF expansion, so this key is only ever this key. */
+const HKDF_INFO = "12-apps/mcp:refresh-rotation-grace:v1";
+
+/** Version prefix, so a future format change is recognisable rather than corrupt. */
+const SEAL_VERSION = "v1";
+
+/** How long a just-rotated token keeps answering with its successor. */
+export const DEFAULT_ROTATION_GRACE_MS = 30_000;
+
+/**
+ * What a successfully opened seal yields.
+ *
+ * Not exported: `refresh.ts` is the only caller and reads it through inference,
+ * so exporting it would only widen the package's public surface with a name
+ * nobody imports.
+ */
+interface OpenedSuccessor {
+  /** The successor's opaque plaintext — the token to hand back. */
+  successor: string;
+  /** Epoch milliseconds after which the seal must be refused. */
+  graceUntil: number;
+}
+
+/**
+ * Derive the sealing key from the parent's plaintext.
+ *
+ * No salt: an opaque refresh token is already 256 bits of CSPRNG output, so HKDF
+ * is used here for domain separation and length adjustment rather than to
+ * concentrate entropy that is not there.
+ */
+function sealingKey(parentPlaintext: string): Buffer {
+  const derived = hkdfSync(
+    "sha256",
+    Buffer.from(parentPlaintext, "utf8"),
+    Buffer.alloc(0),
+    Buffer.from(HKDF_INFO, "utf8"),
+    KEY_BYTES,
+  );
+  return Buffer.from(derived);
+}
+
+/** base64url without padding, so the blob is safe in any column or URL. */
+function encode(value: Buffer): string {
+  return value.toString("base64url");
+}
+
+/**
+ * Seal `successorPlaintext` so that only a caller holding `parentPlaintext` can
+ * recover it, carrying `graceUntil` inside the sealed blob.
+ *
+ * The deadline is DATA here, not enforcement: {@link openSuccessor} returns it
+ * rather than acting on it, and the caller (`refresh.ts`) is what refuses a
+ * lapsed one. Sealing it inside the AEAD blob is what stops it being edited in
+ * the row; it is not a claim that the ciphertext stops opening on its own. A
+ * seal therefore stays openable-by-its-parent until the row is consumed or
+ * revoked, which for an idle connection is the token's TTL rather than the
+ * window — see the note in the module docblock.
+ */
+export function sealSuccessor(
+  parentPlaintext: string,
+  successorPlaintext: string,
+  graceUntil: number,
+): string {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGORITHM, sealingKey(parentPlaintext), iv);
+  const payload = JSON.stringify({ successor: successorPlaintext, graceUntil });
+  const sealed = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()]);
+  return [SEAL_VERSION, encode(iv), encode(cipher.getAuthTag()), encode(sealed)].join(".");
+}
+
+/** Parse the four-part wire form, or `null` when it is not one. */
+function parts(seal: string): { iv: Buffer; tag: Buffer; body: Buffer } | null {
+  const segments = seal.split(".");
+  if (segments.length !== 4) return null;
+  const [version, iv, tag, body] = segments;
+  if (version !== SEAL_VERSION) return null;
+
+  const decoded = {
+    iv: Buffer.from(iv ?? "", "base64url"),
+    tag: Buffer.from(tag ?? "", "base64url"),
+    body: Buffer.from(body ?? "", "base64url"),
+  };
+  // Lengths are fixed by the algorithm; a wrong one is a malformed blob, and
+  // `createDecipheriv` would throw on it rather than return.
+  if (decoded.iv.length !== IV_BYTES || decoded.tag.length !== TAG_BYTES) return null;
+  return decoded;
+}
+
+/**
+ * Open a seal with the parent's plaintext.
+ *
+ * `null` for every failure — a wrong parent, a tampered or truncated blob, an
+ * unknown version, a payload that is not the expected shape. The caller treats
+ * `null` as "no grace applies" and falls through to the replay rule, so a
+ * failure here is never the difference between secure and insecure; it only
+ * costs the client its retry.
+ */
+export function openSuccessor(parentPlaintext: string, seal: string): OpenedSuccessor | null {
+  const parsed = parts(seal);
+  if (!parsed) return null;
+
+  try {
+    const decipher = createDecipheriv(ALGORITHM, sealingKey(parentPlaintext), parsed.iv);
+    decipher.setAuthTag(parsed.tag);
+    const opened = Buffer.concat([decipher.update(parsed.body), decipher.final()]);
+    const payload: unknown = JSON.parse(opened.toString("utf8"));
+    return readPayload(payload);
+  } catch {
+    // A wrong key fails the GCM tag check, which throws. That is the expected
+    // path for "this is not the parent that sealed it", not an error to report.
+    return null;
+  }
+}
+
+/** Narrow the decrypted JSON to {@link OpenedSuccessor}, or `null`. */
+function readPayload(payload: unknown): OpenedSuccessor | null {
+  if (payload === null || typeof payload !== "object") return null;
+  const { successor, graceUntil } = payload as Record<string, unknown>;
+  if (typeof successor !== "string" || successor === "") return null;
+  if (typeof graceUntil !== "number" || !Number.isFinite(graceUntil)) return null;
+  return { successor, graceUntil };
+}

package/src/oauth/stores.ts

@@ -58,6 +58,38 @@ export interface StoredRefreshToken {
   /** The prior token's hash — the rotation lineage. `null` for a root token. */
   rotatedFrom: string | null;
   revokedAt: Date | null;
+  /**
+   * This token's own plaintext, SEALED under a key derived from the plaintext of
+   * the token it was rotated from (`./rotation-grace.ts`), and readable only by a
+   * caller presenting that parent.
+   *
+   * It is what lets a rotation be retried: within the grace window, re-presenting
+   * the consumed parent returns THIS successor again instead of destroying the
+   * lineage, so a lost response or two concurrent refreshes no longer force the
+   * user through the whole authorization flow again.
+   *
+   * REQUIRED of a store from this version on, even though the type is optional
+   * for the root token that has no parent to seal under. `rotate` writes it on
+   * every successor and CLEARS it on every parent it consumes.
+   *
+   * A PRISMA host that raises the version without the column fails loudly, on
+   * every rotation, because the delegate rejects the unknown key — a dead token
+   * endpoint rather than a degraded one, and the reason to land the migration in
+   * the SAME change as the version raise. A hand-written store has no such
+   * backstop: drop the field there and the window silently never applies, so
+   * implementing this field and its clearing is part of meeting the port, not an
+   * optional extra. `harness/backend/src/mcp-oauth-db.ts` is the worked example.
+   *
+   * Clearing it on consumption is what bounds the exposure, and it is the whole
+   * reason the field is safe to store at all: a seal is openable only by the
+   * plaintext of the token it was rotated from, so leaving spent seals in place
+   * would let anyone holding ONE historical plaintext plus a copy of this table
+   * walk the chain forward offline — hop by hop, with no server call and so no
+   * replay detection — all the way to the live token. With the parent's seal
+   * cleared as it is consumed, at most one hop is ever open, and only while the
+   * successor it points at is still the live token.
+   */
+  graceSeal?: string | null;
 }
 
 /** A token about to be stored (the plaintext never is). */
@@ -70,7 +102,13 @@ export interface RefreshTokenStore {
   hasSuccessor(tokenHash: string): Promise<boolean>;
   /** Every token of one `(userEmail, clientId)` family — the lineage walk's input. */
   listFamily(userEmail: string, clientId: string): Promise<StoredRefreshToken[]>;
-  /** Revoke exactly these hashes (idempotent). */
+  /**
+   * Revoke exactly these hashes (idempotent), CLEARING each row's `graceSeal`.
+   *
+   * A revoked lineage must leave nothing openable behind it — otherwise the
+   * revocation that replay detection exists to perform would still leave the
+   * chain readable to anyone holding one of its plaintexts.
+   */
   revokeHashes(tokenHashes: readonly string[], at: Date): Promise<void>;
   /**
    * CLAIM the parent and store the successor, atomically. The whole of OAuth 2.1
@@ -97,6 +135,12 @@ export interface RefreshTokenStore {
    * live parent AND a live child) but it is not sufficient, and it is the easier
    * half to satisfy by accident.
    */
+  /**
+   * The claim MUST also clear the parent's own `graceSeal`. It is not tidiness:
+   * an uncleared seal is permanently openable by the plaintext it was sealed
+   * under, so a chain of them is an offline path from any historical token to
+   * the live one. Clearing on consumption keeps at most one hop readable.
+   */
   rotate(successor: NewRefreshToken, parentHash: string, at: Date): Promise<boolean>;
   /**
    * Revoke every LIVE token a user holds for one client; returns how many were

package/src/oauth/token-grants.ts

@@ -32,7 +32,9 @@ import {
  *     the stored hash, else `invalid_client` (401).
  *   - **Bound `redirect_uri`:** it must equal the one the code was minted with
  *     (RFC 6749 §4.1.3).
- *   - **Refresh rotation:** client-bound, replay-revoking, narrow-only scope.
+ *   - **Refresh rotation:** client-bound, replay-revoking, narrow-only scope —
+ *     with a grace window in which re-presenting a just-consumed token is a
+ *     RETRY answered with the same successor, not a replay (`./rotation-grace.ts`).
  */
 
 /** Throttle default: don't rewrite liveness on every grant. */
@@ -247,6 +249,7 @@ async function handleRefreshToken(
   const refreshContext = {
     store: context.stores.refreshTokens,
     ttlMs: context.refreshTokenTtlMs,
+    graceMs: context.refreshRotationGraceMs,
   };
 
   // Rotation enforces client binding (the token's stored clientId must equal the