@12-apps/mcp 3.15.0 → 3.17.0

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

package/src/server/auth-failure.ts

@@ -0,0 +1,145 @@
+/**
+ * What an unauthorized MCP call is TOLD, as opposed to what it is refused with.
+ *
+ * ## The failure this module exists to remove
+ *
+ * A resource server has three RFC 6750 challenge codes and a boolean's worth of
+ * expressiveness, so every way a bearer can fail arrives at the agent as one
+ * opaque refusal. `Authentication required` is what a lapsed connection, a token
+ * minted for a different origin, a surface an operator never switched on, and a
+ * missing scope all look like — identical, and none of them actionable.
+ *
+ * The cost is not cosmetic. An agent that cannot tell those apart cannot tell the
+ * user anything useful either: every tool call fails, the connector still reports
+ * itself connected, and the one thing that would fix the common case — reconnect
+ * it — is the one thing nobody is told to do. Reported from a live deployment as
+ * "every tool call failing, even the ones that read nothing".
+ *
+ * ## The shape of the answer
+ *
+ * Each reason resolves to three things, and they are deliberately separate:
+ *
+ *   - `challenge` — the RFC 6750 code for the `WWW-Authenticate` header. Only
+ *     ever one of the two the spec defines for this situation, because a host's
+ *     OAuth machinery keys off it;
+ *   - `action` — what would actually fix it, for a client that automates;
+ *   - `message` — one sentence an agent can relay to a person. English, like
+ *     everything else a developer or a model reads here; a host that wants its
+ *     own wording supplies it.
+ *
+ * Nothing here narrows `unverified`. Signature, issuer and audience stay
+ * collapsed into one answer on purpose — see `../oauth/access-token.ts` for why
+ * expiry is the single documented exception.
+ */
+
+/** Why a call was refused, across both the transport and the token verifier. */
+export type McpAuthFailureReason =
+  /** No `Authorization` header at all — the client has not connected yet. */
+  | "no_token"
+  /** The token was fine until its `exp` passed. The common one, and recoverable. */
+  | "expired"
+  /** Signature, issuer or audience did not hold. Deliberately not narrowed. */
+  | "unverified"
+  /** Verified, but carrying no usable identity. */
+  | "incomplete"
+  /** The operator has not provisioned signing material, so nothing can verify. */
+  | "not_provisioned"
+  /** The whole MCP surface is switched off for this deployment. */
+  | "surface_disabled"
+  /** A valid token that lacks the scope this particular call needs. */
+  | "insufficient_scope";
+
+/** What a client should do about it. */
+export type McpAuthRecovery =
+  /** Exchange the refresh token for a new access token, then retry. */
+  | "refresh"
+  /** Re-run the authorization flow — a human has to approve it again. */
+  | "reconnect"
+  /** Nothing the client can do; the deployment has to change. */
+  | "contact_operator";
+
+/** The resolved answer for one refusal. */
+export interface McpAuthFailure {
+  reason: McpAuthFailureReason;
+  /** The RFC 6750 code for the `WWW-Authenticate` challenge. */
+  challenge: "invalid_token" | "insufficient_scope";
+  action: McpAuthRecovery;
+  /** One sentence, written to be relayed to a person by an agent. */
+  message: string;
+}
+
+const FAILURES: Record<McpAuthFailureReason, Omit<McpAuthFailure, "reason">> = {
+  no_token: {
+    challenge: "invalid_token",
+    action: "reconnect",
+    message:
+      "This request carried no access token. Ask the user to connect this MCP server in their assistant's connector settings, then retry.",
+  },
+  expired: {
+    challenge: "invalid_token",
+    action: "refresh",
+    message:
+      "The access token has expired. A client that holds a refresh token should renew it and retry; if renewal also fails, ask the user to reconnect this MCP server in their assistant's connector settings.",
+  },
+  unverified: {
+    challenge: "invalid_token",
+    action: "reconnect",
+    message:
+      "The access token could not be verified for this server. Ask the user to reconnect this MCP server in their assistant's connector settings — a token issued for a different deployment will never verify here.",
+  },
+  incomplete: {
+    challenge: "invalid_token",
+    action: "reconnect",
+    message:
+      "The access token verified but carries no usable identity. Ask the user to reconnect this MCP server in their assistant's connector settings.",
+  },
+  not_provisioned: {
+    challenge: "invalid_token",
+    action: "contact_operator",
+    message:
+      "This server has no signing key provisioned, so no access token can be verified. Reconnecting will not help; the deployment's operator has to configure it.",
+  },
+  surface_disabled: {
+    challenge: "invalid_token",
+    action: "contact_operator",
+    message:
+      "The MCP surface is switched off on this deployment. Reconnecting will not help; the deployment's operator has to enable it.",
+  },
+  insufficient_scope: {
+    challenge: "insufficient_scope",
+    action: "reconnect",
+    message:
+      "The access token does not grant the scope this tool needs. Ask the user to reconnect this MCP server and approve the wider scope.",
+  },
+};
+
+/** Resolve a reason to its challenge code, recovery and human-relayable message. */
+export function describeAuthFailure(reason: McpAuthFailureReason): McpAuthFailure {
+  return { reason, ...FAILURES[reason] };
+}
+
+/**
+ * The machine-readable half, carried in the JSON-RPC error's `data` member.
+ *
+ * A model reads `message`; a host that automates its connection lifecycle reads
+ * this. Both travel together so neither has to be inferred from the other.
+ */
+export interface McpAuthFailureData {
+  reason: McpAuthFailureReason;
+  action: McpAuthRecovery;
+  /**
+   * Whether presenting a NEW token could succeed. `false` means the deployment
+   * itself is the problem, so a client that retries forever is wasting its time
+   * and the user's — and should say so rather than loop.
+   */
+  recoverable: boolean;
+}
+
+/** Build the `data` payload for a refusal. */
+export function authFailureData(failure: McpAuthFailure): McpAuthFailureData {
+  return {
+    reason: failure.reason,
+    action: failure.action,
+    recoverable: failure.action !== "contact_operator",
+  };
+}

package/src/server/jsonrpc.ts

@@ -1,5 +1,10 @@
 import type { RequestAuth } from "../types";
 
+import {
+  authFailureData,
+  describeAuthFailure,
+  type McpAuthFailureReason,
+} from "./auth-failure";
 import type { ToolRegistry } from "./registry";
 
 /**
@@ -52,7 +57,12 @@ export interface JsonRpcResponse {
   jsonrpc: "2.0";
   id: string | number | null;
   result?: unknown;
-  error?: { code: number; message: string };
+  /**
+   * `data` is the JSON-RPC 2.0 optional member, and it is what carries the
+   * machine-readable half of a refusal ({@link McpAuthFailureData}) while
+   * `message` carries the half a model relays to a person.
+   */
+  error?: { code: number; message: string; data?: unknown };
 }
 
 /** What a client is told it connected to, in `initialize`'s `serverInfo`. */
@@ -91,8 +101,17 @@ function ok(id: JsonRpcRequest["id"], result: unknown): JsonRpcResponse {
   return { jsonrpc: "2.0", id: id ?? null, result };
 }
 
-function fail(id: JsonRpcRequest["id"], code: number, message: string): JsonRpcResponse {
-  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+function fail(
+  id: JsonRpcRequest["id"],
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: { code, message, ...(data === undefined ? {} : { data }) },
+  };
 }
 
 /** A parsed body is a usable request only if it's an object carrying a string `method`. */
@@ -104,8 +123,22 @@ async function handleToolsCall(
   request: JsonRpcRequest,
   registry: ToolRegistry,
   auth: RequestAuth | null,
+  failure?: McpAuthFailureReason,
 ): Promise<JsonRpcResponse> {
-  if (!auth) return fail(request.id, UNAUTHORIZED_CODE, "Authentication required");
+  if (!auth) {
+    // It used to be the bare string "Authentication required", which is true of
+    // every refusal and useful for none of them: an agent reading it cannot tell
+    // a lapsed connection from a misconfigured server, so it cannot tell the user
+    // to reconnect. The host resolves WHY and passes it in; `no_token` is the
+    // honest default when it says nothing.
+    const described = describeAuthFailure(failure ?? "no_token");
+    return fail(
+      request.id,
+      UNAUTHORIZED_CODE,
+      described.message,
+      authFailureData(described),
+    );
+  }
   const params = (request.params ?? {}) as { name?: string; arguments?: Record<string, unknown> };
   if (!params.name) return fail(request.id, INVALID_PARAMS_CODE, "Missing tool name");
   const result = await registry.callTool(params.name, params.arguments ?? {}, auth);
@@ -135,12 +168,18 @@ function handleInitialize(
  * `tools/call` then returns {@link UNAUTHORIZED_CODE}, which the host surfaces as
  * HTTP 401. Discovery (`initialize`, `ping`, `tools/list`) stays open, so a client
  * can read the surface before it has a token.
+ *
+ * `failure` is WHY `auth` is null, which only the host's verifier knows. It is
+ * optional so an existing caller keeps compiling, and passing it is what turns a
+ * refusal an agent can only report into one it can act on — see
+ * `./auth-failure.ts`.
  */
 export async function handleMcpJsonRpc(
   request: JsonRpcRequest,
   registry: ToolRegistry,
   auth: RequestAuth | null,
   options: McpJsonRpcOptions,
+  failure?: McpAuthFailureReason,
 ): Promise<JsonRpcResponse | null> {
   // A host casts the parsed body to JsonRpcRequest without validating it, so a
   // malformed payload can arrive here: a `null` body/batch element, a non-object,
@@ -157,7 +196,7 @@ export async function handleMcpJsonRpc(
     case "tools/list":
       return ok(request.id, { tools: registry.listTools(auth ?? undefined) });
     case "tools/call":
-      return handleToolsCall(request, registry, auth);
+      return handleToolsCall(request, registry, auth, failure);
     default:
       // JSON-RPC notifications (`notifications/*`) expect no reply — silently
       // ignore any we don't explicitly handle, rather than returning an error.