machine-bridge-mcp 3.0.0-beta.17 → 3.0.0-beta.21

package/src/worker/mcp-stream-dispatch.ts

@@ -1,10 +1,13 @@
-import type { PendingCallOutcome, PendingCallRecord } from "./pending-call-contract.ts";
-import { PendingCallRegistrationError, PendingCallRegistry } from "./pending-calls.ts";
-import type { DaemonSocketRegistry } from "./daemon-sockets.ts";
+import type { PendingCallOutcome } from "./pending-call-contract.ts";
+import type { JsonRpcMessage, McpResumptionStore } from "./mcp-resumption.ts";
+import {
+  McpPendingCallConflictError,
+  McpPendingCallLimitError,
+} from "./mcp-pending-call-store.ts";
+import type { PendingStreamTransform } from "./mcp-pending-call-records.ts";
 import { publicWorkerToolError, WorkerToolError } from "./errors.ts";
 import { workerErrorClass } from "./http.ts";
 import { rpcResult, textToolResult } from "./mcp-jsonrpc.ts";
-import type { JsonRpcMessage, McpResumptionStore } from "./mcp-resumption.ts";
 import { randomToken } from "./oauth-state.ts";
 import type { WorkerObservability } from "./observability.ts";
 
@@ -17,7 +20,6 @@ export type StreamCallAuthorization = {
 };
 
 type StartStreamCallInput = {
-  pending: PendingCallRegistry;
   resumption: McpResumptionStore;
   observability: WorkerObservability;
   streamId: string;
@@ -27,11 +29,13 @@ type StartStreamCallInput = {
   arguments: Record<string, unknown>;
   socket: WebSocket;
   daemonInstanceId: string;
+  connectionId: string;
   timeoutMs: number;
   authorization: StreamCallAuthorization;
-  onTimeout: (record: PendingCallRecord) => Error;
+  transientActiveCount: number;
+  maximumPendingCalls: number;
+  transform?: PendingStreamTransform;
   onSendFailure: () => void | Promise<void>;
-  transformResult?: (value: unknown) => unknown;
 };
 
 type ImmediateOutcomeInput = {
@@ -50,9 +54,10 @@ export function buildServerInfoResult(input: {
   oauth: Record<string, unknown>;
   authorization: Record<string, any>;
   daemon: Record<string, any>;
-  tools: string[];
-  pending: PendingCallRegistry;
-  daemonRegistry: DaemonSocketRegistry;
+  effectiveTools: string[];
+  advertisedTools: string[];
+  pendingSnapshot: Record<string, unknown>;
+  daemonRegistry: import("./daemon-sockets.ts").DaemonSocketRegistry;
   observability: WorkerObservability;
 }): Record<string, unknown> {
   const probing = input.daemonRegistry.probingSockets().length;
@@ -68,7 +73,7 @@ export function buildServerInfoResult(input: {
     authority_summary: input.authorization.summary,
     daemon: input.daemon,
     worker: {
-      pending_calls: input.pending.snapshot(),
+      pending_calls: input.pendingSnapshot,
       daemon_candidates: candidates,
       daemon_probes: probing,
       sockets_live: {
@@ -79,14 +84,15 @@ export function buildServerInfoResult(input: {
       },
       observability: input.observability.snapshot(),
     },
-    tools: input.tools,
+    tools: input.effectiveTools,
     tools_scope: "authenticated_account_effective_tools_before_host_filtering",
     tool_delivery: {
       full_profile_scope: "daemon-capability-ceiling-before-account-filtering",
       daemon_advertised_tool_count: input.daemon.tool_count,
-      relay_advertised_tool_count: input.tools.length,
-      effective_account_tool_count: input.tools.length,
-      relay_advertised_scope: "authenticated_account_effective_tools_before_host_filtering",
+      relay_advertised_tool_count: input.advertisedTools.length,
+      effective_account_tool_count: input.effectiveTools.length,
+      relay_advertised_scope: "stable_authenticated_account_catalog_before_host_filtering",
+      effective_scope: "live_daemon_and_account_intersection_before_host_filtering",
       host_exposed_tools_known_to_server: false,
       host_may_expose_subset: true,
     },
@@ -95,30 +101,28 @@ export function buildServerInfoResult(input: {
 
 export async function startEventDrivenStreamCall(input: StartStreamCallInput): Promise<void> {
   const callId = randomToken("call");
-  const settle = createStreamSettlement({
-    resumption: input.resumption,
-    observability: input.observability,
-    streamId: input.streamId,
-    requestId: input.requestId,
-    tool: input.tool,
-    transformResult: input.transformResult,
-  });
   try {
-    input.pending.registerEvent({
-      id: callId,
-      socket: input.socket,
+    await input.resumption.calls.activate({
+      streamId: input.streamId,
+      callId,
       daemonInstanceId: input.daemonInstanceId,
+      connectionId: input.connectionId,
       clientRequestKey: input.clientRequestKey,
       tool: input.tool,
       timeoutMs: input.timeoutMs,
-      onTimeout: input.onTimeout,
-      settle,
+      transform: input.transform,
+      transientActiveCount: input.transientActiveCount,
+      maximumPendingCalls: input.maximumPendingCalls,
     });
   } catch (error) {
-    if (error instanceof PendingCallRegistrationError) throw new WorkerToolError(error.code, error.message, error.retryable);
+    if (error instanceof McpPendingCallLimitError) {
+      throw new WorkerToolError("limit_exceeded", error.message, true);
+    }
+    if (error instanceof McpPendingCallConflictError) {
+      throw new WorkerToolError("conflict", error.message);
+    }
     throw error;
   }
-  input.resumption.activate(input.streamId);
   input.observability.callStarted(input.tool);
   try {
     input.socket.send(JSON.stringify({
@@ -130,7 +134,9 @@ export async function startEventDrivenStreamCall(input: StartStreamCallInput): P
       authorization: input.authorization,
     }));
   } catch {
-    await input.pending.reject(callId, new WorkerToolError("network_error", "failed to send daemon tool call", true), input.socket);
+    const error = new WorkerToolError("network_error", "failed to send daemon tool call", true);
+    await input.resumption.calls.complete(callId, input.connectionId, streamTerminalMessage(input.requestId, { ok: false, error }));
+    input.observability.callFinished(input.tool, error.code);
     await input.onSendFailure();
   }
 }
@@ -144,28 +150,7 @@ export async function persistImmediateStreamOutcome(input: ImmediateOutcomeInput
   }
 }
 
-function createStreamSettlement(input: {
-  resumption: McpResumptionStore;
-  observability: WorkerObservability;
-  streamId: string;
-  requestId: string | number;
-  tool: string;
-  transformResult?: (value: unknown) => unknown;
-}): (outcome: PendingCallOutcome) => Promise<void> {
-  return async (outcome) => {
-    const normalized = normalizeOutcome(outcome, input.transformResult);
-    const code = normalized.ok ? "" : publicWorkerToolError(normalized.error).code;
-    const message = streamTerminalMessage(input.requestId, normalized);
-    try {
-      await input.resumption.complete(input.streamId, message);
-    } catch (error) {
-      input.observability.event("error", "mcp.stream.persist.failed", { error_class: workerErrorClass(error) });
-    }
-    input.observability.callFinished(input.tool, code);
-  };
-}
-
-function streamTerminalMessage(
+export function streamTerminalMessage(
   requestId: string | number,
   outcome: PendingCallOutcome,
   transformResult?: (value: unknown) => unknown,
@@ -179,7 +164,10 @@ function streamTerminalMessage(
   return message;
 }
 
-function normalizeOutcome(outcome: PendingCallOutcome, transformResult?: (value: unknown) => unknown): PendingCallOutcome {
+export function normalizeOutcome(
+  outcome: PendingCallOutcome,
+  transformResult?: (value: unknown) => unknown,
+): PendingCallOutcome {
   if (!outcome.ok || !transformResult) return outcome;
   try { return { ok: true, value: transformResult(outcome.value) }; }
   catch (error) { return { ok: false, error: error instanceof Error ? error : new Error("stream result transformation failed") }; }

package/src/worker/mcp-stream-proxy.ts

@@ -1,14 +1,12 @@
-import relayContract from "../shared/relay-contract.json" with { type: "json" };
 import { applyCors, baseUrl, json } from "./http.ts";
 import { acceptsEventStream, resumeJsonRpcResponse, streamJsonRpcResponse } from "./mcp-stream.ts";
 import type { McpStreamChannel } from "./mcp-stream-channel.ts";
-import type { JsonRpcMessage } from "./mcp-resumption.ts";
+import { DEFAULT_SUBSCRIBE_RETRY_DELAYS_MS, subscribeTerminalMessage } from "./mcp-stream-subscription.ts";
 
 export const MCP_STREAM_PROXY_MODE_HEADER = "x-machine-bridge-internal-mcp-stream-mode";
 export const MCP_STREAM_PROXY_ID_HEADER = "x-machine-bridge-internal-mcp-stream-id";
 const MCP_STREAM_DESCRIPTOR_HEADER = "x-machine-bridge-mcp-stream-descriptor";
 const STREAM_ID_PATTERN = /^stream_[A-Za-z0-9_-]{43}$/;
-const MAX_TERMINAL_MESSAGE_BYTES = relayContract.maximumResumableMessageBytes + 1024;
 
 type StreamProxyMode = "prepare" | "subscribe" | "";
 type StreamDescriptorKind = "initial" | "resume" | "complete";
@@ -21,6 +19,7 @@ export async function proxyMcpEventStream(input: {
   bridge: BridgeFetcher;
   extraOrigins: string;
   ctx: StreamExecutionContext;
+  subscribeRetryDelaysMs?: readonly number[];
 }): Promise<Response | null> {
   const url = new URL(input.request.url);
   const eligible = input.request.method === "GET"
@@ -39,8 +38,11 @@ export async function proxyMcpEventStream(input: {
     );
   }
 
-  const terminal = subscribeTerminalMessage(input.bridge, input.request.url, descriptor.stream_id);
-  input.ctx.waitUntil(terminal.then(() => undefined, () => undefined));
+  const terminal = subscribeTerminalMessage(
+    input.bridge,
+    () => withProxyHeaders(new Request(input.request.url, { method: "GET" }), "subscribe", descriptor.stream_id),
+    input.subscribeRetryDelaysMs ?? DEFAULT_SUBSCRIBE_RETRY_DELAYS_MS,
+  );
   const options = {
     streamId: descriptor.stream_id,
     keepAlive: (promise: Promise<void>) => input.ctx.waitUntil(promise),
@@ -94,70 +96,6 @@ function withProxyHeaders(request: Request, mode: Exclude<StreamProxyMode, "">,
   return new Request(sanitized, { method: mode === "subscribe" ? "GET" : sanitized.method, headers });
 }
 
-async function subscribeTerminalMessage(
-  bridge: BridgeFetcher,
-  requestUrl: string,
-  streamId: string,
-): Promise<JsonRpcMessage> {
-  const internal = withProxyHeaders(new Request(requestUrl, { method: "GET" }), "subscribe", streamId);
-  const response = await bridge.fetch(internal);
-  if (response.status === 200) return await readJsonRpcResponse(response);
-  if (response.status !== 101 || !response.webSocket) {
-    throw new Error(`internal MCP stream subscription failed (${response.status})`);
-  }
-  const socket = response.webSocket;
-  socket.accept();
-  return await terminalMessageFromSocket(socket);
-}
-
-function terminalMessageFromSocket(socket: WebSocket): Promise<JsonRpcMessage> {
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const fail = (message: string) => {
-      if (settled) return;
-      settled = true;
-      reject(new Error(message));
-    };
-    const succeed = (message: JsonRpcMessage) => {
-      if (settled) return;
-      settled = true;
-      resolve(message);
-      try { socket.close(1000, "terminal received"); } catch { /* Peer may have already completed the close handshake. */ }
-    };
-    socket.addEventListener("message", (event) => {
-      if (settled) return;
-      try {
-        const text = webSocketText(event.data);
-        if (new TextEncoder().encode(text).byteLength > MAX_TERMINAL_MESSAGE_BYTES) throw new Error("terminal message is too large");
-        succeed(jsonRpcMessage(JSON.parse(text)));
-      } catch (error) {
-        fail(error instanceof Error ? error.message : "invalid terminal message");
-        try { socket.close(1008, "invalid terminal message"); } catch { /* socket may already be closing */ }
-      }
-    });
-    socket.addEventListener("close", () => fail("internal MCP stream subscription closed before terminal result"));
-    socket.addEventListener("error", () => fail("internal MCP stream subscription failed"));
-  });
-}
-
-async function readJsonRpcResponse(response: Response): Promise<JsonRpcMessage> {
-  return jsonRpcMessage(await response.json());
-}
-
-function jsonRpcMessage(value: unknown): JsonRpcMessage {
-  if (!value || typeof value !== "object" || Array.isArray(value) || (value as { jsonrpc?: unknown }).jsonrpc !== "2.0") {
-    throw new Error("internal MCP stream subscription returned an invalid JSON-RPC message");
-  }
-  return value as JsonRpcMessage;
-}
-
-function webSocketText(value: unknown): string {
-  if (typeof value === "string") return value;
-  if (value instanceof ArrayBuffer) return new TextDecoder("utf-8", { fatal: true }).decode(value);
-  if (ArrayBuffer.isView(value)) return new TextDecoder("utf-8", { fatal: true }).decode(value);
-  throw new Error("terminal message must be text or binary UTF-8");
-}
-
 async function readDescriptor(response: Response): Promise<StreamDescriptor> {
   const value: unknown = await response.json();
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("MCP stream descriptor is invalid");

package/src/worker/mcp-stream-subscription.ts

@@ -0,0 +1,98 @@
+import relayContract from "../shared/relay-contract.json" with { type: "json" };
+import type { JsonRpcMessage } from "./mcp-resumption.ts";
+import { createThrottledEdgeLogger } from "./worker-edge-log.ts";
+
+const MAX_TERMINAL_MESSAGE_BYTES = relayContract.maximumResumableMessageBytes + 1024;
+export const DEFAULT_SUBSCRIBE_RETRY_DELAYS_MS = [0, 100, 300] as const;
+type BridgeFetcher = { fetch(request: Request): Promise<Response> };
+const logSubscriptionFailure = createThrottledEdgeLogger();
+
+export async function subscribeTerminalMessage(
+  bridge: BridgeFetcher,
+  createRequest: () => Request,
+  retryDelaysMs: readonly number[],
+): Promise<JsonRpcMessage> {
+  const delays = retryDelaysMs.length > 0 ? retryDelaysMs.slice(0, 4) : [0];
+  let lastError: unknown = new Error("internal MCP stream subscription failed");
+  for (const rawDelay of delays) {
+    const delayMs = Math.max(0, Math.min(2_000, Math.floor(Number(rawDelay) || 0)));
+    if (delayMs > 0) await delay(delayMs);
+    try {
+      const response = await bridge.fetch(createRequest());
+      if (response.status === 200) return await readJsonRpcResponse(response);
+      if (response.status !== 101 || !response.webSocket) {
+        const retryable = response.status === 429 || response.status >= 500;
+        throw new StreamSubscriptionError(`internal MCP stream subscription failed (${response.status})`, retryable);
+      }
+      const socket = response.webSocket;
+      socket.accept();
+      return await terminalMessageFromSocket(socket);
+    } catch (error) {
+      lastError = error;
+      if (error instanceof StreamSubscriptionError && !error.retryable) break;
+    }
+  }
+  logSubscriptionFailure("warn", "mcp.stream.subscription.failed", { attempts: delays.length });
+  throw lastError;
+}
+
+class StreamSubscriptionError extends Error {
+  readonly retryable: boolean;
+  constructor(message: string, retryable: boolean) {
+    super(message);
+    this.name = "StreamSubscriptionError";
+    this.retryable = retryable;
+  }
+}
+
+function terminalMessageFromSocket(socket: WebSocket): Promise<JsonRpcMessage> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (message: string, retryable: boolean) => {
+      if (settled) return;
+      settled = true;
+      reject(new StreamSubscriptionError(message, retryable));
+    };
+    const succeed = (message: JsonRpcMessage) => {
+      if (settled) return;
+      settled = true;
+      resolve(message);
+      try { socket.close(1000, "terminal received"); } catch { /* Peer may have closed first. */ }
+    };
+    socket.addEventListener("message", (event) => {
+      if (settled) return;
+      try {
+        const text = webSocketText(event.data);
+        if (new TextEncoder().encode(text).byteLength > MAX_TERMINAL_MESSAGE_BYTES) throw new Error("terminal message is too large");
+        succeed(jsonRpcMessage(JSON.parse(text)));
+      } catch (error) {
+        fail(error instanceof Error ? error.message : "invalid terminal message", false);
+        try { socket.close(1008, "invalid terminal message"); } catch { /* socket may already be closing */ }
+      }
+    });
+    socket.addEventListener("close", () => fail("internal MCP stream subscription closed before terminal result", true));
+    socket.addEventListener("error", () => fail("internal MCP stream subscription failed", true));
+  });
+}
+
+async function readJsonRpcResponse(response: Response): Promise<JsonRpcMessage> {
+  return jsonRpcMessage(await response.json());
+}
+
+function jsonRpcMessage(value: unknown): JsonRpcMessage {
+  if (!value || typeof value !== "object" || Array.isArray(value) || (value as { jsonrpc?: unknown }).jsonrpc !== "2.0") {
+    throw new Error("internal MCP stream subscription returned an invalid JSON-RPC message");
+  }
+  return value as JsonRpcMessage;
+}
+
+function webSocketText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof ArrayBuffer) return new TextDecoder("utf-8", { fatal: true }).decode(value);
+  if (ArrayBuffer.isView(value)) return new TextDecoder("utf-8", { fatal: true }).decode(value);
+  throw new Error("terminal message must be text or binary UTF-8");
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/worker/oauth-controller.ts

@@ -1,6 +1,6 @@
 import { DEFAULT_ACCOUNT_ROLE, normalizeAccountRole, type AccountRole } from "./access.ts";
 import { accountAdminAuthorized, consumeAccountAdminNonce, handleAccountAdminOperation } from "./account-admin.ts";
-import { exchangeOAuthToken } from "./oauth-tokens.ts";
+import { exchangeOAuthToken, type OAuthRefreshEvent } from "./oauth-tokens.ts";
 import {
   AUTH_BLOCK_SECONDS, accountByName, authorizationIdentity, emptyOAuthStore,
   isCurrentOAuthStore, pruneAuthFailures, pruneClientRecordByExpiry, pruneRecordByExpiry, randomToken,
@@ -44,13 +44,21 @@ export class OAuthController {
   private readonly env: OAuthControllerEnv;
   private readonly serverName: string;
   private readonly serverVersion: string;
+  private readonly onRefreshEvent?: (event: OAuthRefreshEvent) => void;
   private oauthQueue: Promise<void> = Promise.resolve();
 
-  constructor(ctx: DurableObjectState, env: OAuthControllerEnv, serverName: string, serverVersion: string) {
+  constructor(
+    ctx: DurableObjectState,
+    env: OAuthControllerEnv,
+    serverName: string,
+    serverVersion: string,
+    onRefreshEvent?: (event: OAuthRefreshEvent) => void,
+  ) {
     this.ctx = ctx;
     this.env = env;
     this.serverName = serverName;
     this.serverVersion = serverVersion;
+    this.onRefreshEvent = onRefreshEvent;
   }
 
   private async oauthStore(): Promise<OAuthStore> {
@@ -283,6 +291,7 @@ export class OAuthController {
       serverName: this.serverName,
       loadOAuthStore: () => this.oauthStore(),
       withLock: (callback) => this.withOAuthLock(callback),
+      onRefreshEvent: this.onRefreshEvent,
     });
   }
 

package/src/worker/oauth-refresh-exchange.ts

@@ -0,0 +1,147 @@
+import { consumeDpopProof, type VerifiedDpopProof } from "./dpop.ts";
+import { HttpError, json } from "./http.ts";
+import {
+  consumedRefreshRetrySource,
+  loadOAuthRefreshStore,
+  MAX_REFRESH_RETRY_ISSUES,
+  OAUTH_REFRESH_STORE_KEY,
+  recordConsumedRefreshRetry,
+  recordConsumedRefreshToken,
+  revokeOAuthRefreshFamily,
+} from "./oauth-refresh-families.ts";
+import {
+  issueTokenPair,
+  saveOAuthStores,
+  tokenResponse,
+  type IssuedTokenPair,
+  type OAuthTokenExchangeOptions,
+} from "./oauth-token-issuance.ts";
+import { normalizeOAuthScope, safeEqual, sha256Hex, type OAuthRefreshToken, type OAuthStore } from "./oauth-state.ts";
+
+export async function exchangeRefreshToken(
+  body: Record<string, unknown>,
+  base: string,
+  options: OAuthTokenExchangeOptions,
+  dpop?: VerifiedDpopProof,
+): Promise<Response> {
+  const refreshToken = String(body.refresh_token ?? "");
+  if (!/^mcp_rt_[A-Za-z0-9_-]{43}$/.test(refreshToken)) return reject(options);
+  return options.withLock(async () => {
+    const now = Math.floor(Date.now() / 1000);
+    const oauthStore = await options.loadOAuthStore();
+    const refreshStore = await loadOAuthRefreshStore(oauthStore, options.storage);
+    const refreshKey = `sha256:${await sha256Hex(refreshToken)}`;
+    const record = refreshStore.tokens[refreshKey];
+    if (!record) {
+      const consumed = refreshStore.consumed[refreshKey];
+      if (!consumed || consumed.expires_at <= now) return reject(options);
+      const retrySource = consumedRefreshRetrySource(consumed, now);
+      if (retrySource) {
+        const validation = await validateRefreshGrant(retrySource, body, base, options, dpop, oauthStore, false);
+        if (validation.response) return rejected(options, validation.response);
+        if (dpop && !(await consumeDpopProof(options.storage, dpop))) return rejectDpop(options);
+        const issued = await issueTokenPair(
+          oauthStore,
+          refreshStore,
+          retrySource,
+          options.tokenVersion,
+          retrySource.dpop_jkt,
+          { derivationSeed: refreshToken, issuedAt: consumed.consumed_at },
+        );
+        recordConsumedRefreshRetry(consumed);
+        validation.client.last_used_at = now;
+        await saveOAuthStores(oauthStore, refreshStore, options.storage);
+        options.onRefreshEvent?.("retry_issued");
+        return tokenResponse(issued, retrySource.scope, retrySource.dpop_jkt);
+      }
+      if (Number.isSafeInteger(consumed.retry_until) && consumed.retry_until! >= now
+        && Number(consumed.retry_issues) >= MAX_REFRESH_RETRY_ISSUES) {
+        options.onRefreshEvent?.("retry_exhausted");
+        return json({
+          error: "temporarily_unavailable",
+          error_description: "concurrent refresh retry limit reached; retry with the newest token response",
+        }, 429, { "retry-after": "1" });
+      }
+      revokeOAuthRefreshFamily(oauthStore, refreshStore, consumed.family_id, consumed.expires_at);
+      await saveOAuthStores(oauthStore, refreshStore, options.storage);
+      options.onRefreshEvent?.("family_revoked");
+      return json({ error: "invalid_grant" }, 400);
+    }
+
+    const validation = await validateRefreshGrant(record, body, base, options, dpop, oauthStore, true);
+    if (validation.response) return rejected(options, validation.response);
+    if (dpop && !(await consumeDpopProof(options.storage, dpop))) return rejectDpop(options);
+    let issued: IssuedTokenPair;
+    try {
+      issued = await issueTokenPair(
+        oauthStore,
+        refreshStore,
+        record,
+        options.tokenVersion,
+        record.dpop_jkt,
+        { derivationSeed: refreshToken, issuedAt: now },
+      );
+    } catch (error) {
+      if (!(error instanceof HttpError) || error.code !== "invalid_grant") throw error;
+      delete refreshStore.tokens[refreshKey];
+      await options.storage.put(OAUTH_REFRESH_STORE_KEY, refreshStore);
+      return reject(options);
+    }
+    delete refreshStore.tokens[refreshKey];
+    recordConsumedRefreshToken(oauthStore, refreshStore, refreshKey, record, record.family_expires_at, now);
+    validation.client.last_used_at = now;
+    await saveOAuthStores(oauthStore, refreshStore, options.storage);
+    options.onRefreshEvent?.("rotated");
+    return tokenResponse(issued, record.scope, record.dpop_jkt);
+  });
+}
+
+async function validateRefreshGrant(
+  record: OAuthRefreshToken,
+  body: Record<string, unknown>,
+  base: string,
+  options: OAuthTokenExchangeOptions,
+  dpop: VerifiedDpopProof | undefined,
+  oauthStore: OAuthStore,
+  allowDpopBinding: boolean,
+): Promise<{ client: OAuthStore["clients"][string]; response?: never } | { client?: never; response: Response }> {
+  if (record.dpop_jkt && record.dpop_jkt !== dpop?.jkt) return { response: json({ error: "invalid_dpop_proof" }, 400) };
+  if (!record.dpop_jkt && dpop?.jkt) {
+    if (!allowDpopBinding) return { response: json({ error: "invalid_dpop_proof" }, 400) };
+    record.dpop_jkt = dpop.jkt;
+  }
+  if (String(body.client_id ?? "") !== record.client_id) {
+    return { response: json({ error: "invalid_grant", error_description: "client mismatch" }, 400) };
+  }
+  if (String(body.resource ?? record.resource) !== record.resource || record.resource !== `${base}/mcp`) {
+    return { response: json({ error: "invalid_target", error_description: "resource mismatch" }, 400) };
+  }
+  if (body.scope !== undefined && normalizeOAuthScope(body.scope, options.serverName) !== record.scope) {
+    return { response: json({ error: "invalid_scope" }, 400) };
+  }
+  if (!options.tokenVersion) throw new HttpError(503, "server_error", "OAuth token version is not configured");
+  const account = oauthStore.accounts[record.account_id];
+  const client = oauthStore.clients[record.client_id];
+  if (!record.version || !(await safeEqual(record.version, options.tokenVersion)) || !account || !account.active
+    || account.version !== record.account_version || account.role !== record.role || !client
+    || client.trusted_account_id !== account.account_id || client.trusted_account_version !== account.version
+    || client.trusted_role !== account.role) {
+    return { response: json({ error: "invalid_grant" }, 400) };
+  }
+  return { client };
+}
+
+function reject(options: OAuthTokenExchangeOptions): Response {
+  options.onRefreshEvent?.("rejected");
+  return json({ error: "invalid_grant" }, 400);
+}
+
+function rejectDpop(options: OAuthTokenExchangeOptions): Response {
+  options.onRefreshEvent?.("rejected");
+  return json({ error: "invalid_dpop_proof" }, 400);
+}
+
+function rejected(options: OAuthTokenExchangeOptions, response: Response): Response {
+  options.onRefreshEvent?.("rejected");
+  return response;
+}