@12-apps/mcp 3.15.0 → 3.17.0

package/prisma/migrations/20260910120000_add_refresh_grace_seal/migration.sql

@@ -0,0 +1,37 @@
+-- @12-apps/mcp: the sealed successor that makes refresh rotation RETRYABLE.
+--
+-- `oauth_refresh_tokens.grace_seal` holds a token's own plaintext, encrypted
+-- (AES-256-GCM) under a key derived by HKDF from the plaintext of the token it
+-- was rotated FROM, with its grace deadline sealed inside the same blob.
+--
+-- WHY THE COLUMN EXISTS. Rotation-on-use with replay revocation cannot tell a
+-- thief from a client that used one token twice for an innocent reason, and
+-- there are two routine innocent reasons: a response lost to a proxy timeout,
+-- and two of the client's own sessions refreshing at the same moment. Both were
+-- punished as theft — the whole lineage revoked, including the successor just
+-- handed to whoever won — which killed a live connection and sent a human back
+-- through the full authorization flow. With this column, re-presenting a
+-- just-consumed token inside the window returns THAT SAME successor instead, so
+-- one successor is still all that ever exists and no second family is created.
+--
+-- WHY IT IS NOT A PLAINTEXT COLUMN. The key is never stored: it is derived from
+-- the parent, which is itself only ever stored hashed. A dump of this table
+-- therefore yields ciphertext and nothing that opens it, so the package's
+-- "hashed, never plaintext" invariant is unchanged. The only party that can open
+-- a seal is one presenting the parent — which is the party being served, and
+-- which already held the token that mints the successor.
+--
+-- The seal is CLEARED whenever a token is consumed or revoked, and that is the
+-- bound on what it costs: a seal opens only under the plaintext it was rotated
+-- from, so spent seals left in place would chain — one historical plaintext plus
+-- a copy of this table would walk forward to the live token offline, with no
+-- server call and therefore no replay detection.
+--
+-- Nullable, but NOT optional: the package writes this field on every rotation,
+-- so a deployment that raises the package version without applying this
+-- migration gets a runtime failure on every refresh, not a quietly disabled
+-- window. Apply it in the same change as the version raise. Guarded with
+-- IF NOT EXISTS like every other statement this package ships, so a host that
+-- already added the column adopts the migration as a no-op.
+ALTER TABLE "oauth_refresh_tokens"
+  ADD COLUMN IF NOT EXISTS "grace_seal" TEXT;

package/src/e2e/globs.ts

@@ -0,0 +1,70 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+/**
+ * Where this package's journeys and their steps live, ON DISK, in the consumer's
+ * `node_modules`.
+ *
+ * `defineBddConfig` takes filesystem globs, not module specifiers — it hands
+ * them to a glob matcher, so `'@12-apps/mcp/features/**'` matches
+ * nothing and, worse, matches nothing SILENTLY: bddgen compiles the features it
+ * found, finds none, and the run is green with zero journeys.
+ *
+ * So the paths are RESOLVED here instead of written down by every consumer. A
+ * host that hard-codes `node_modules/@12-apps/mcp/...` is broken by
+ * pnpm's nested store, by a workspace link, and by this package's own layout
+ * changing; resolving from the package's own entry point is correct under all
+ * three.
+ */
+const require_ = createRequire(import.meta.url);
+
+/**
+ * The package root, found from a file this package definitely exports.
+ * `./package.json` is exported precisely so this lookup needs no guess about
+ * directory depth.
+ */
+function packageRoot(): string {
+  return dirname(require_.resolve('@12-apps/mcp/package.json'));
+}
+
+/** Every packaged `.feature`, for `defineBddConfig({ features })`. */
+export const mcpFeatures: string = join(packageRoot(), 'features/**/*.feature');
+
+/**
+ * The base `defineBddConfig({ featuresRoot })` must be given, and it is NOT
+ * optional decoration.
+ *
+ * bddgen mirrors each feature's path RELATIVE TO `featuresRoot` under
+ * `outputDir`. Left unset it defaults to the config's own directory, so a
+ * feature living under `node_modules/...` compiles to a path Playwright then
+ * IGNORES, because its default `testIgnore` excludes `**\/node_modules/**`.
+ *
+ * The result is the worst kind of green: bddgen reports the features compiled,
+ * Playwright collects zero specs from them, and the run passes with the whole
+ * packaged suite silently absent.
+ *
+ * A host running SEVERAL packaged suites gives `featuresRoot` the directory they
+ * all sit under, since bddgen takes exactly one — and that is safe to do,
+ * because a feature outside it is a hard exit from bddgen, never a quiet
+ * omission.
+ */
+export const mcpFeaturesRoot: string = join(packageRoot(), 'features');
+
+/**
+ * Every packaged step definition, for `defineBddConfig({ steps })`.
+ *
+ * COMPILED JavaScript, and that is the reason this package has a build step at
+ * all while everything else it exports is raw `.ts` through the `exports` map.
+ * Those entries are consumed by an application's BUNDLER, which transpiles
+ * whatever it is pointed at. These are loaded by NODE — `playwright.config.ts`
+ * imports this module, and bddgen imports the step files — and Node refuses to
+ * strip types from anything under `node_modules`
+ * (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). Playwright's own TS transform
+ * does not rescue them either; it skips `node_modules` by design.
+ *
+ * The host's own steps glob must ALSO be listed — that is where its
+ * `defineMcpConnectWorld` call lives, and playwright-bdd imports every step
+ * file before any scenario runs, which is what makes the registration land in
+ * time in every worker.
+ */
+export const mcpSteps: string = join(packageRoot(), 'dist/e2e/steps/**/*.js');

package/src/e2e/index.ts

@@ -0,0 +1,16 @@
+/**
+ * `@12-apps/mcp/e2e` — the packaged AI-connect journeys and the port a host
+ * implements to run them.
+ *
+ * The `e2e` capability the manifest declares. A host adds the three globs to
+ * its bdd config and calls `defineMcpConnectWorld` from inside its own steps
+ * glob; every scenario this package ships then runs in that host, including the
+ * ones added after it integrated. Nothing is copied, so nothing can rot.
+ */
+export { mcpFeatures, mcpFeaturesRoot, mcpSteps } from './globs.js';
+export {
+  defineMcpConnectWorld,
+  mcpConnectWorld,
+  type McpConnectFixtures,
+  type McpConnectWorld,
+} from './world.js';

package/src/e2e/steps/journey.steps.ts

@@ -0,0 +1,136 @@
+import { expect, type Page } from '@playwright/test';
+import { createBdd } from 'playwright-bdd';
+
+import { mcpConnectWorld } from '../world.js';
+
+/**
+ * The packaged AI-connect journeys' step definitions.
+ *
+ * Every locator is a test id THIS package's own components render —
+ * `ai-landing`, `ai-host-select`, `ai-copy-step`, `ai-configure-step`,
+ * `ai-connect-step`, `ai-confirm-waiting`, `mcp-endpoint-url` — which is what
+ * makes the scenarios portable: they mean the same thing in any app mounting
+ * `AiIntegrationOnboarding`. Everything a host owns (sign-in, where the flow is
+ * mounted, which assistants it offers) arrives through the world port.
+ *
+ * ## Why `package.json` declares this file under `sideEffects`
+ *
+ * Every Given/When/Then below runs at IMPORT time — registering a step is the
+ * whole point of the module, and it exports nothing anybody imports by name. To
+ * a bundler doing tree-shaking that reads as dead weight, and dropping it is
+ * licensed: the result is a suite where bddgen reports the features compiled
+ * and every scenario then fails on an undefined step.
+ *
+ * Not one step asserts a SENTENCE. The assistants' names, the button words and
+ * the permission prose are REQUIRED host config (FUT-760) — this package ships
+ * no assistant and no copy of its own — so a spec written against them could
+ * only ever have run in one adopter.
+ */
+const { Given, When, Then } = createBdd();
+
+Given('I am signed in as somebody who may connect an assistant', async ({ page }) => {
+  await mcpConnectWorld().signInAsOwner(page);
+});
+
+When('I open the AI integration screen', async ({ page }) => {
+  await mcpConnectWorld().openAiIntegrationScreen(page);
+  await expect(page.getByTestId('ai-onboarding')).toBeVisible();
+});
+
+Then('the landing explains the permission model before anything is connected', async ({ page }) => {
+  await expect(page.getByTestId('ai-landing')).toBeVisible();
+  // The callout is the point of the landing: an owner is about to hand a third
+  // party a key to their store, and this is the screen that says what the key
+  // opens. It renders BEFORE any assistant is chosen, which is the only moment
+  // the answer is still "nothing".
+  await expect(page.getByTestId('ai-permission-callout')).toBeVisible();
+});
+
+Then('it shows examples of what an assistant can be asked', async ({ page }) => {
+  await expect(page.getByTestId('ai-capability-examples')).toBeVisible();
+});
+
+When('I start the walkthrough', async ({ page }) => {
+  await page.getByTestId('ai-landing-start').click();
+  await expect(page.getByTestId('ai-host-select')).toBeVisible();
+});
+
+When('I choose an assistant that has no one-click install', async ({ page }) => {
+  // The flow BRANCHES on the guide's `pluginUrl`: with one it becomes
+  // Escolher → Instalar → Confirmar and there is no endpoint to copy at all.
+  // The host names a guide that takes the manual path, because which
+  // assistants exist is its configuration and not this package's.
+  await page.getByTestId(`ai-host-card-${mcpConnectWorld().fixtures.manualHostId}`).click();
+});
+
+Then("I am asked to copy the store's endpoint", async ({ page }) => {
+  await expect(page.getByTestId('ai-copy-step')).toBeVisible();
+  await expect(page.getByTestId('mcp-endpoint-url')).toContainText(
+    mcpConnectWorld().fixtures.endpointUrl,
+  );
+});
+
+/** Copying is the ACTION that advances this step — there is no next button. */
+async function copyEndpoint(page: Page): Promise<void> {
+  await page.getByTestId('ai-copy-endpoint').click();
+}
+
+/**
+ * Open the assistant's connector page — the one action that unlocks "next".
+ *
+ * By its OWN id, not `getByRole('link')`: this control is a Button calling
+ * `window.open`, and the only real `<a>` in the step is the DOCS link, which
+ * deliberately does not unlock anything. A role query would have taken the
+ * docs link and then failed on an assertion about the button.
+ */
+async function openConnectorPage(page: Page): Promise<void> {
+  await page.getByTestId(`ai-host-link-${mcpConnectWorld().fixtures.manualHostId}`).click();
+}
+
+When('I copy the endpoint', async ({ page }) => {
+  await copyEndpoint(page);
+});
+
+Then('the walkthrough has moved on to configuring the connector', async ({ page }) => {
+  // The claim is that COPYING advanced it. The copy step offers no "next", so
+  // reaching the configure step at all proves the copy handler drove the
+  // wizard rather than some button the operator happened to press.
+  await expect(page.getByTestId('ai-configure-step')).toBeVisible();
+  await expect(page.getByTestId('ai-copy-step')).toHaveCount(0);
+});
+
+Then('continuing is refused until I open the connector page', async ({ page }) => {
+  // The guard that stops an owner walking past the one step that does the
+  // actual work: the connector page has to be opened before "next" unlocks.
+  await expect(page.getByTestId('ai-configure-next')).toBeDisabled();
+});
+
+Then('once opened, continuing reaches the connect step', async ({ page }) => {
+  await openConnectorPage(page);
+  await expect(page.getByTestId('ai-configure-next')).toBeEnabled();
+  await page.getByTestId('ai-configure-next').click();
+  await expect(page.getByTestId('ai-connect-step')).toBeVisible();
+});
+
+When('I go back a step', async ({ page }) => {
+  await page.getByTestId('ai-step-back').click();
+});
+
+When('I work through configuring and connecting', async ({ page }) => {
+  await openConnectorPage(page);
+  await page.getByTestId('ai-configure-next').click();
+  await expect(page.getByTestId('ai-connect-step')).toBeVisible();
+  await page.getByTestId('ai-connect-done').click();
+});
+
+Then('the confirmation is still waiting for the assistant', async ({ page }) => {
+  // Waiting rather than connected, because nothing has actually connected: the
+  // wizard reaching its last step is not evidence of a live connection, and
+  // this is the step that refuses to claim otherwise.
+  await expect(page.getByTestId('ai-confirm-waiting')).toBeVisible();
+  await expect(page.getByTestId('ai-confirm-connected')).toHaveCount(0);
+});
+
+Then('it offers to test the connection again', async ({ page }) => {
+  await expect(page.getByTestId('ai-confirm-retest')).toBeVisible();
+});

package/src/e2e/world.ts

@@ -0,0 +1,84 @@
+import type { Page } from '@playwright/test';
+
+/**
+ * The port a HOST implements to run the packaged AI-connect journeys.
+ *
+ * These journeys were written because the walkthrough they cover was tested
+ * NOWHERE. `./react` ships the whole flow — the landing, the assistant picker,
+ * the endpoint to copy, the configure and connect steps, the confirmation and
+ * its re-test — and twenty test ids go with it. Not one of them appeared in
+ * this package's own suite, and not one appeared in the origin host's specs
+ * either: that host's `ai.e2e.ts` drives its OWN plan lock and upsell modal,
+ * reaching only `ai-onboarding` and the status board on the way past.
+ *
+ * So the flow a store owner actually walks was covered by nothing, in either
+ * repo. That is the gap the `e2e` capability exists to convert into a
+ * declaration rather than an omission nobody can see.
+ *
+ * What stays the host's: how it signs an owner in, where it mounts the flow,
+ * and which assistant its `hosts` config offers — the guides are REQUIRED
+ * config (FUT-760), so the package has no assistant of its own to name.
+ */
+
+/** Facts about the host that the assertions have to name. */
+export interface McpConnectFixtures {
+  /**
+   * The id of an assistant the host offers whose guide has NO `pluginUrl`.
+   *
+   * The flow BRANCHES on that field: a guide carrying one gets `InstallStep`
+   * (a single "open the install link" button), and a guide without one gets
+   * the three-step manual path — copy the endpoint, configure, connect. These
+   * journeys walk the MANUAL path, so the host has to point at a guide that
+   * takes it. Naming the branch here rather than guessing keeps the scenario
+   * from failing in a host whose first assistant happens to ship a plugin.
+   */
+  manualHostId: string;
+  /** The endpoint URL that host serves, as it is rendered for copying. */
+  endpointUrl: string;
+}
+
+/** What a host must be able to do for these journeys to run in it. */
+export interface McpConnectWorld {
+  /**
+   * Put the browser in a known signed-in state as somebody who may connect an
+   * assistant, with the flow's progress RESET to its first run.
+   *
+   * The reset is load-bearing rather than hygiene: the wizard persists its step
+   * through `@12-apps/onboarding`, so a scenario that advanced it would hand
+   * the next one a flow resuming from the middle — and the landing step, which
+   * two of these scenarios assert, would never render.
+   */
+  signInAsOwner(page: Page): Promise<void>;
+  /** Land on the screen that mounts `AiIntegrationOnboarding`. */
+  openAiIntegrationScreen(page: Page): Promise<void>;
+  fixtures: McpConnectFixtures;
+}
+
+let installed: McpConnectWorld | null = null;
+
+/**
+ * Install the host's implementation. Call this from a module inside the host's
+ * OWN steps glob — playwright-bdd imports every step file before any scenario
+ * runs, so a top-level call there is registered in time, in every worker.
+ */
+export function defineMcpConnectWorld(world: McpConnectWorld): void {
+  installed = world;
+}
+
+/**
+ * The installed world, or a refusal naming the fix.
+ *
+ * Throws rather than returning null: a step that ran against an absent world
+ * would fail on whatever it touched next, somewhere unrelated to the actual
+ * mistake, which is a diagnosis nobody should have to make twice.
+ */
+export function mcpConnectWorld(): McpConnectWorld {
+  if (!installed) {
+    throw new Error(
+      'No mcp e2e world is installed. Call defineMcpConnectWorld({ … }) from a module inside ' +
+        "your own `steps` glob — playwright-bdd imports those before any scenario runs, " +
+        'which is what makes the registration land in every worker.',
+    );
+  }
+  return installed;
+}

package/src/index.ts

@@ -73,6 +73,17 @@ export {
   type McpJsonRpcOptions,
   type McpServerInfo,
 } from "./server/jsonrpc";
+// WHY a call was refused, and what a client should do about it. The RFC gives a
+// resource server three challenge codes, which is not enough to tell a lapsed
+// connection from a misconfigured deployment — so the reason travels alongside.
+export {
+  authFailureData,
+  describeAuthFailure,
+  type McpAuthFailure,
+  type McpAuthFailureData,
+  type McpAuthFailureReason,
+  type McpAuthRecovery,
+} from "./server/auth-failure";
 export {
   buildManifest,
   serializeManifest,

package/src/manifest/index.ts

@@ -53,13 +53,29 @@
  *   three hosts pass differently, which is the opposite of what a surface
  *   contribution is for. When the flow grows a real bound surface, the
  *   inventory grows with it.
- * - **No `env`.** The signing-key variables (`DEFAULT_SIGNING_KEY_ENV`,
- *   `DEFAULT_SIGNING_KEY_ID_ENV`) and `trustedOriginsFromEnv` are NAMES this
- *   package exports for a host to read `process.env` with; the package reads
- *   nothing itself, and the names are overridable per call. Declaring them
- *   would oblige a host to answer for variables it may legitimately have
- *   spelled differently.
- * - **No `e2e`.** This package packages no journeys.
+ * - **No `env`.** Three helpers here DO read `process.env`
+ *   (`trustedOriginsFromEnv`, and `loadSigningKeyFromEnv` for the key and its
+ *   id) — this used to say "the package reads nothing itself", which was
+ *   simply untrue and is the kind of sentence that makes a narrowing unfalsifiable.
+ *   The accurate reason is narrower and still holds: nothing is read at import
+ *   time or unconditionally, so a host that never calls these helpers has no
+ *   environment dependency on this package at all; and where they ARE called,
+ *   the variable's NAME is the caller's — passed as an argument by
+ *   `trustedOriginsFromEnv`, and defaulted but overridable per call by
+ *   `loadSigningKeyFromEnv`. `env` declares variables a host must answer for.
+ *   Declaring these would oblige every host to answer for names it may
+ *   legitimately have spelled differently, or never reads at all.
+ * - **`e2e` IS declared** (`../e2e`). It was narrowed away with "this package
+ *   packages no journeys", which was true as a statement of fact and circular
+ *   as an argument: it packaged none because nobody had written any, while
+ *   `./react` shipped the entire AI-connect walkthrough — landing, assistant
+ *   picker, endpoint copy, configure, connect, confirm — behind twenty test
+ *   ids that NO suite touched. Not this package's (its two React tests cover
+ *   the status board and the step primitives), and not the origin host's,
+ *   whose `ai.e2e.ts` drives its own plan lock and upsell modal and only
+ *   passes `ai-onboarding` on the way. A flow every adopter's owner has to
+ *   walk was covered in neither repo, which is exactly the omission this
+ *   capability exists to turn into a declaration.
  * - **No `jobs`.** Nothing here sweeps: authorization codes are stateless
  *   signed blobs (the partial's header says so — there is no `oauth_codes`
  *   table and nothing to expire), and refresh-token revocation happens on
@@ -86,4 +102,5 @@ export const mcpManifest = {
    */
   observability: { namespace: "mcp" },
   server: ["http"],
+  e2e: { entry: "@12-apps/mcp/e2e", world: { factory: "defineMcpConnectWorld" } },
 } as const satisfies PackageManifest;

package/src/oauth/access-token.ts

@@ -35,14 +35,48 @@ export interface VerifiedAccessToken {
 /** Distinct verification failure reasons the caller maps to OAuth challenges. */
 export type AccessTokenErrorCode = "invalid_token" | "insufficient_scope";
 
-/** A typed verification failure — `code` drives the `WWW-Authenticate` challenge. */
+/**
+ * WHY verification failed, at the granularity an operator and an agent can act on.
+ *
+ * `code` above is the RFC 6750 challenge and there are only three of those, so it
+ * cannot tell "your connection lapsed, refresh it" from "this token is not for
+ * this server". That distinction is the whole difference between an assistant
+ * that tells its user to reconnect this server and one that reports a generic
+ * failure on every tool call, so it is carried alongside rather than folded
+ * into `code`.
+ *
+ * `unverified` stays deliberately COARSE. Signature, issuer and audience collapse
+ * into it because naming which one failed is an oracle for the next attempt.
+ * Expiry is the documented exception — RFC 6750 names it in `error_description`
+ * precisely because a client must be told to refresh — and it leaks nothing: a
+ * token's `exp` is readable by whoever holds the token.
+ */
+export type AccessTokenFailureReason =
+  /** Valid in every other respect, but `exp` has passed. Refresh, do not re-consent. */
+  | "expired"
+  /** Signature, issuer or audience did not hold. Deliberately not narrowed further. */
+  | "unverified"
+  /** Verified, but missing the `sub`/`email` the identity is built from. */
+  | "incomplete"
+  /** No signing key is provisioned, so nothing can verify. An operator problem. */
+  | "not_provisioned"
+  /** A valid token that simply lacks the scope this call needs. */
+  | "insufficient_scope";
+
+/**
+ * A typed verification failure — `code` drives the `WWW-Authenticate` challenge,
+ * {@link AccessTokenError.reason} drives what the caller is actually told.
+ */
 export class AccessTokenError extends Error {
   readonly code: AccessTokenErrorCode;
 
-  constructor(code: AccessTokenErrorCode, message?: string) {
-    super(message ?? code);
+  readonly reason: AccessTokenFailureReason;
+
+  constructor(code: AccessTokenErrorCode, reason: AccessTokenFailureReason, message?: string) {
+    super(message ?? reason);
     this.name = "AccessTokenError";
     this.code = code;
+    this.reason = reason;
   }
 }
 
@@ -131,12 +165,30 @@ function parseScopes(scope: unknown): string[] {
  * signature / wrong issuer / wrong audience / expired / malformed / unconfigured
  * key) from `insufficient_scope` (a valid token lacking the required scope).
  */
+/** jose's code for a token that parsed and verified but whose `exp` has passed. */
+const JWT_EXPIRED_CODE = "ERR_JWT_EXPIRED";
+
+/** Whether a thrown value is jose's expiry error, by its stable `code`. */
+function isExpiry(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { code?: unknown }).code === JWT_EXPIRED_CODE
+  );
+}
+
 /**
  * The cryptographic half: signature, `iss`, `aud`, `exp`.
  *
- * Every jose failure — bad signature, wrong issuer, wrong audience, expiry,
- * malformed token, unknown key — collapses into ONE opaque `invalid_token`. A
- * message naming the failed claim would be an oracle for the next attempt.
+ * Bad signature, wrong issuer, wrong audience, malformed token and unknown key
+ * all collapse into ONE opaque `unverified`. A message naming the failed claim
+ * would be an oracle for the next attempt.
+ *
+ * EXPIRY is separated out, and only expiry. It is the one failure a
+ * well-behaved client is supposed to act on — refresh and retry — and it is the
+ * one the RFC gives a description for, so collapsing it left every lapsed
+ * connection indistinguishable from a broken one. It is not an oracle either:
+ * `exp` is a readable claim of a token the caller already holds.
  */
 async function verifiedPayload(
   loadSigningKey: McpSigningKeyProvider,
@@ -145,7 +197,9 @@ async function verifiedPayload(
 ): Promise<JWTPayload> {
   const key = await loadSigningKey();
   // No signing key configured → nothing can verify (safe-by-default).
-  if (!key) throw new AccessTokenError("invalid_token", "no signing key configured");
+  if (!key) {
+    throw new AccessTokenError("invalid_token", "not_provisioned", "no signing key configured");
+  }
 
   try {
     const { payload } = await jwtVerify(token, await importJWK(key.publicJwk, SIGNING_ALG), {
@@ -156,8 +210,11 @@ async function verifiedPayload(
       currentDate: options.now === undefined ? undefined : new Date(options.now),
     });
     return payload;
-  } catch {
-    throw new AccessTokenError("invalid_token", "token verification failed");
+  } catch (error) {
+    if (isExpiry(error)) {
+      throw new AccessTokenError("invalid_token", "expired", "access token expired");
+    }
+    throw new AccessTokenError("invalid_token", "unverified", "token verification failed");
   }
 }
 
@@ -171,12 +228,17 @@ export async function verifyAccessToken(
   const email = typeof payload.email === "string" ? payload.email : null;
   const subject = typeof payload.sub === "string" ? payload.sub : null;
   if (!email || !subject) {
-    throw new AccessTokenError("invalid_token", "missing subject or email claim");
+    throw new AccessTokenError(
+      "invalid_token",
+      "incomplete",
+      "missing subject or email claim",
+    );
   }
 
   const scopes = parseScopes(payload.scope);
   if (options.requiredScope && !scopes.includes(options.requiredScope)) {
     throw new AccessTokenError(
+      "insufficient_scope",
       "insufficient_scope",
       `token lacks required scope '${options.requiredScope}'`,
     );

package/src/oauth/context.ts

@@ -9,6 +9,7 @@ import {
 } from "./code-replay";
 import { ACCESS_TOKEN_TTL_SECONDS } from "./access-token";
 import { REFRESH_TOKEN_TTL_MS } from "./refresh";
+import { DEFAULT_ROTATION_GRACE_MS } from "./rotation-grace";
 import { loadSigningKeyFromEnv, type McpSigningKeyProvider } from "./keys";
 import type { ProviderAttributionRule } from "./clients";
 import type { McpOauthStores, StoredOAuthClient } from "./stores";
@@ -109,6 +110,22 @@ export interface McpOauthConfig {
   loginCallbackParam?: string;
   accessTokenTtlSeconds?: number;
   refreshTokenTtlMs?: number;
+  /**
+   * How long a just-rotated refresh 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 single-use rule.
+   *
+   * It exists because one client using one token twice is routine — a response
+   * lost to a proxy timeout, or two of its own sessions refreshing at once — and
+   * the strict rule cannot tell either from theft, so it revoked the lineage and
+   * cost a connected user their session. Inside the window the retry is answered
+   * with the SAME successor, so no second family is ever created. It does NOT
+   * merely defer detection by one rotation: two parties left holding one
+   * successor take the retry path again at every rotation, so a collision is
+   * detected only once two uses fall more than this window apart. That trade is
+   * argued in full in `./rotation-grace.ts`.
+   */
+  refreshRotationGraceMs?: number;
   /**
    * The single-use guard for authorization codes — REQUIRED, and required on
    * purpose. Pass a shared atomic store, or the literal `'in-process'` to accept
@@ -169,6 +186,7 @@ export interface McpOauthContext {
   loginCallbackParam: string;
   accessTokenTtlSeconds: number;
   refreshTokenTtlMs: number;
+  refreshRotationGraceMs: number;
   codeReplay: CodeReplayStore;
   /**
    * The resolved consent decision for one authorize request. Always present: with
@@ -197,6 +215,7 @@ function resolveSurface(
   | "loginCallbackParam"
   | "accessTokenTtlSeconds"
   | "refreshTokenTtlMs"
+  | "refreshRotationGraceMs"
 > {
   return {
     scopes: config.scopes ?? [...MCP_SUPPORTED_SCOPES],
@@ -206,6 +225,7 @@ function resolveSurface(
     loginCallbackParam: config.loginCallbackParam ?? "callbackUrl",
     accessTokenTtlSeconds: config.accessTokenTtlSeconds ?? ACCESS_TOKEN_TTL_SECONDS,
     refreshTokenTtlMs: config.refreshTokenTtlMs ?? REFRESH_TOKEN_TTL_MS,
+    refreshRotationGraceMs: config.refreshRotationGraceMs ?? DEFAULT_ROTATION_GRACE_MS,
   };
 }
 

package/src/oauth/index.ts

@@ -40,6 +40,7 @@ export {
   signAccessToken,
   verifyAccessToken,
   type AccessTokenErrorCode,
+  type AccessTokenFailureReason,
   type SignAccessTokenInput,
   type VerifiedAccessToken,
   type VerifyAccessTokenOptions,
@@ -94,6 +95,7 @@ export {
   type RefreshTokenErrorCode,
   type RefreshTokenIdentity,
 } from "./refresh";
+export { DEFAULT_ROTATION_GRACE_MS } from "./rotation-grace";
 export {
   inProcessCodeReplayStore,
   type CodeReplayStore,

package/src/oauth/prisma-stores.ts

@@ -50,7 +50,9 @@ export interface McpOauthPrisma {
       where:
         | { tokenHash: { in: string[] } }
         | { userEmail: string; clientId: string; revokedAt: null };
-      data: { revokedAt: Date };
+      // `graceSeal` rides on every revoke: a revoked row must not keep an
+      // openable seal behind it (see `RefreshTokenStore.revokeHashes`).
+      data: { revokedAt: Date; graceSeal?: null };
     }): Promise<{ count: number }>;
   };
   mcpConnection: {
@@ -98,7 +100,7 @@ interface McpOauthTx {
     create(args: { data: NewRefreshToken }): Promise<unknown>;
     updateMany(args: {
       where: { tokenHash: string; revokedAt: null };
-      data: { revokedAt: Date };
+      data: { revokedAt: Date; graceSeal?: null };
     }): Promise<{ count: number }>;
   };
 }
@@ -145,7 +147,10 @@ function refreshTokenStore(getPrisma: McpOauthPrismaProvider): RefreshTokenStore
       const prisma = await getPrisma();
       await prisma.oAuthRefreshToken.updateMany({
         where: { tokenHash: { in: [...tokenHashes] } },
-        data: { revokedAt: at },
+        // The seals go with the revocation. A dead lineage that still carries
+        // openable seals is a chain anyone holding one of its plaintexts can
+        // still walk offline, which would make the revocation cosmetic.
+        data: { revokedAt: at, graceSeal: null },
       });
     },
     async rotate(successor, parentHash, at) {
@@ -162,7 +167,12 @@ function refreshTokenStore(getPrisma: McpOauthPrismaProvider): RefreshTokenStore
         // use of the parent that now never comes).
         const { count } = await tx.oAuthRefreshToken.updateMany({
           where: { tokenHash: parentHash, revokedAt: null },
-          data: { revokedAt: at },
+          // `graceSeal: null` is part of the claim, not a cleanup. The parent's
+          // seal is openable by the plaintext it was rotated from, so leaving it
+          // behind would chain: one historical plaintext plus a copy of this
+          // table walks forward to the live token offline, hop by hop, with no
+          // server call to detect. Cleared here, at most one hop is ever open.
+          data: { revokedAt: at, graceSeal: null },
         });
         // Lost the claim: write NOTHING. The zero-row update commits as the no-op
         // it is, so there is nothing to roll back.
@@ -177,7 +187,8 @@ function refreshTokenStore(getPrisma: McpOauthPrismaProvider): RefreshTokenStore
       const prisma = await getPrisma();
       const { count } = await prisma.oAuthRefreshToken.updateMany({
         where: { userEmail, clientId, revokedAt: null },
-        data: { revokedAt: new Date() },
+        // Disconnecting a host must leave nothing openable behind either.
+        data: { revokedAt: new Date(), graceSeal: null },
       });
       return count;
     },