@12-apps/mcp 3.16.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/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/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;
     },

package/src/oauth/refresh-lineage.ts

@@ -0,0 +1,77 @@
+import type { RefreshTokenStore, StoredRefreshToken } from "./stores";
+
+/**
+ * The walk over `rotatedFrom`, and the revocation the replay rule spends it on.
+ *
+ * Split out of `./refresh.ts` because it is the one part of that file with no
+ * opinion about tokens: it takes a family of rows, follows the links between
+ * them, and revokes what it reaches. It knows nothing about grace windows,
+ * scopes, error codes or the request being served — which is also why it takes a
+ * {@link RefreshTokenStore} rather than the refresh context, keeping the
+ * dependency pointing one way.
+ */
+
+/**
+ * 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[]>;
+}
+
+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);
+  }
+  return { byHash, childrenOf };
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+export async function revokeLineage(
+  store: RefreshTokenStore,
+  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 store.listFamily(scopedTo.userEmail, scopedTo.clientId);
+  const lineage = collectLineage(buildLineageIndex(family), seedHash);
+  await store.revokeHashes([...lineage], new Date());
+}