@ultimat3/mcp 23.0.0 → 25.0.0

package/src/app-tools.ts

@@ -9,10 +9,13 @@
 // `frameworkResources` and `mcpHttpRoute` exist.
 
 import type { ErrorAudience } from '@ultimat3/core';
-import type { RateLimitStore } from '@ultimat3/http';
+import type { RequestFacts as McpRequestFacts, RateLimitStore } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { AnyAppToolDefinition, AppTools } from './app-tool';
 import { appToolPrimitives } from './app-tool';
+import type { McpAuditHook } from './audit-hook';
+import { withConfirmations } from './confirmation-gate';
+import type { McpConfirmations } from './confirmations';
 import { McpToolDuplicateError } from './errors';
 import { exposedPrimitives } from './exposed';
 import { toolsFrom, toolsListed } from './from-action';
@@ -20,15 +23,15 @@ import type { McpResourceGroups, McpSurfaceOption } from './meta-surface';
 import type { McpOAuth } from './oauth-metadata';
 import type { ListedPrimitive } from './projectable';
 import { asProjectable } from './projectable';
-import type { AnyMcpTool, McpVerbClass } from './registry';
+import type { AnyMcpTool } from './registry';
 import type { McpPrompt, McpResource } from './resources';
 import { toPrompts } from './resources';
 import type { McpScopes } from './scopes';
 import { withScopes } from './scopes';
-import type { CreateMcpServerInput } from './server';
-import { createMcpServer, type McpServer } from './server';
+import type { McpServerInput } from './server';
+import { type McpServer, mcpServer } from './server';
 import type { McpInstructions } from './server-voice';
-import type { McpRouteDescriptor, ResolvedToken } from './transport-http';
+import type { McpRateLimits, McpRouteDescriptor, ResolvedToken } from './transport-http';
 import { mcpHttpRoute } from './transport-http';
 
 /** Schema map behind the authored `tools` record; inferred per tool, never written by hand. */
@@ -121,8 +124,27 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
    * `x policy explain …`, which stays in the log line. `'developer'` restores the author's fix.
    */
   readonly errorAudience?: ErrorAudience;
-  /** Bearer-token resolution. Omit to expose no HTTP route (stdio/embedded only). */
-  resolveToken?(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
+  /**
+   * Bearer-token resolution, handed how the request arrived (`McpRequestFacts`) as a second
+   * argument it may ignore. Omit to expose no HTTP route (stdio/embedded only).
+   */
+  resolveToken?(
+    token: string,
+    facts: McpRequestFacts,
+  ): Promise<ResolvedToken | null> | ResolvedToken | null;
+  /**
+   * Every gate decision as data — each `tools/call` and `resources/read` outcome and every refused
+   * token — after its `mcp.*` log line is written. What an action or query DID still goes to
+   * core's `setAuditSink`; this is what the gate decided, mostly before anything ran. A hook that
+   * throws changes no answer (`audit-hook.ts`).
+   */
+  readonly onAudit?: McpAuditHook | undefined;
+  /**
+   * Tools whose every call waits for a person: `mcpConfirmations({ tools, store, permission })`,
+   * which IS the approve/reject action — register it like any other so a person can reach it. A
+   * name it gates that this server does not project is `X_MCP_CONFIRMATION_TOOL_UNKNOWN` at boot.
+   */
+  readonly confirmations?: McpConfirmations | undefined;
   /** Mount path. Defaults to `/mcp`. */
   readonly path?: string;
   /**
@@ -133,10 +155,11 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
    */
   readonly bodyLimitBytes?: number | undefined;
   /**
-   * Requests per minute per caller, by class. Defaults to `MCP_RATE_LIMITS` and is ENFORCED by the
-   * route, so this is the app's one knob over what an agent may spend here.
+   * Requests per minute per caller, by class — defaults to `MCP_RATE_LIMITS` — and failed
+   * authentications per minute per address (`unauthenticated`). ENFORCED by the route, so this is
+   * the app's one knob over what an agent, or a stranger guessing tokens, may spend here.
    */
-  readonly rateLimits?: Readonly<Record<McpVerbClass, number>> | undefined;
+  readonly rateLimits?: McpRateLimits | undefined;
   /**
    * Where those buckets are counted. Forwarded rather than left to the route's per-process default
    * because an app behind N replicas has no other way to reach it — and N processes each holding
@@ -215,9 +238,10 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
     { source: "include: 'exposed'", tools: included },
     { source: 'tools:', tools: written },
   ]);
-  const projected = withScopes(named, input.scopes);
+  // Scopes, then the gate: the gate wraps `handle`, which every resolve reaches last.
+  const projected = withConfirmations(withScopes(named, input.scopes), input.confirmations);
 
-  const config: CreateMcpServerInput = {
+  const config: McpServerInput = {
     tools: projected,
     resources: input.resources ?? [],
     prompts: toPrompts(input.prompts ?? []),
@@ -226,8 +250,9 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
     ...(input.groups === undefined ? {} : { groups: input.groups }),
     ...(input.instructions === undefined ? {} : { instructions: input.instructions }),
     errorAudience: input.errorAudience ?? 'caller',
+    ...(input.onAudit === undefined ? {} : { onAudit: input.onAudit }),
   };
-  const server = createMcpServer(config);
+  const server = mcpServer(config);
 
   const resolveToken = input.resolveToken;
   const route =

package/src/audit-hook.ts

@@ -0,0 +1,108 @@
+// `onAudit`: the gate's decisions, as data, handed on AFTER `audit.ts` has written the log line —
+// one audit path with a second destination, never a second path. Core's `AuditSink` records what
+// an action or query DID (`surface: 'mcp'`); this records what the MCP gate decided, mostly before
+// any primitive ran: hidden, scope-denied, invalid-args, a refused token. No `AuditRecord` can
+// carry those — there is no `ctx`, often no primitive, and nothing ran.
+
+import type { Clock, Logger } from '@ultimat3/core';
+import { logger, stringField, systemClock } from '@ultimat3/core';
+import type { RequestFacts as McpRequestFacts } from '@ultimat3/http';
+import type { McpAuditEntry, McpResourceAuditEntry } from './audit';
+import { auditResourceRead, auditToolCall } from './audit';
+
+/** Why the transport refused before a caller existed. The 429 is `throttled` whichever came first. */
+export type McpAuthRefusal = 'missing-token' | 'rejected-token' | 'not-an-agent' | 'throttled';
+
+/** One decision. `at` is the auditor's clock, never `new Date()`; the token never travels. */
+export type McpAuditEvent =
+  | ({ readonly kind: 'tool-call'; readonly at: Date } & McpAuditEntry)
+  | ({ readonly kind: 'resource-read'; readonly at: Date } & McpResourceAuditEntry)
+  | {
+      readonly kind: 'auth-refused';
+      readonly at: Date;
+      readonly reason: McpAuthRefusal;
+      /** The HTTP status the caller was answered: 401, 403 or 429. */
+      readonly status: number;
+      readonly facts: McpRequestFacts;
+    };
+
+/**
+ * Where the app keeps them: a table, a SIEM, a queue. Fire-and-forget by design — see `deliver`.
+ * `mcpServer({ onAudit })` and `defineAppMcp({ onAudit })`; the route reads its server's.
+ */
+export type McpAuditHook = (event: McpAuditEvent) => void | Promise<void>;
+
+export interface McpAuditor {
+  toolCall(entry: McpAuditEntry): void;
+  resourceRead(entry: McpResourceAuditEntry): void;
+  authRefused(reason: McpAuthRefusal, status: number, facts: McpRequestFacts): void;
+}
+
+export interface McpAuditorInput {
+  readonly onAudit?: McpAuditHook | undefined;
+  /** Stamps `at`. Defaulted, never read inline, so a test can freeze it. */
+  readonly clock?: Clock | undefined;
+  /** Where the lines go. The process logger unless a test reads them. */
+  readonly log?: Logger | undefined;
+}
+
+export function mcpAuditor(input: McpAuditorInput = {}): McpAuditor {
+  const log = input.log ?? logger;
+  const clock = input.clock ?? systemClock;
+  const hook = input.onAudit;
+  return {
+    toolCall(entry) {
+      auditToolCall(entry, log);
+      if (hook !== undefined) deliver(hook, { kind: 'tool-call', at: clock.now(), ...entry }, log);
+    },
+    resourceRead(entry) {
+      auditResourceRead(entry, log);
+      if (hook !== undefined) {
+        deliver(hook, { kind: 'resource-read', at: clock.now(), ...entry }, log);
+      }
+    },
+    authRefused(reason, status, facts) {
+      // `warn`, the level of every refusal a prober can drive: a token walk is the same shape as a
+      // tool-name walk one step earlier. The address and path carry the decision; the user agent
+      // and origin stay in the event only — caller-controlled text an alert rule has no use for.
+      log.warn(`mcp.auth.${reason}`, {
+        surface: 'mcp',
+        reason,
+        status,
+        path: facts.path,
+        ...(facts.address === null ? {} : { address: facts.address }),
+      });
+      if (hook !== undefined) {
+        deliver(hook, { kind: 'auth-refused', at: clock.now(), reason, status, facts }, log);
+      }
+    },
+  };
+}
+
+/** The auditor a server built without `onAudit` uses: the log line, and nothing else. */
+export const LOG_ONLY_AUDITOR: McpAuditor = mcpAuditor();
+
+/**
+ * A hook that throws or rejects changes NO answer. The log line — the record that cannot be turned
+ * off — is already written, and a refusal that turned into a 500 when the app's sink was down
+ * would be a signal a prober could read. So the failure is reported, once, at `error`, carrying the
+ * thrown value's `code` when it has one and never its message: a sink's message names a host.
+ * Not awaited, so a slow sink cannot hold a JSON-RPC answer; a hook that must not lose an event
+ * queues it itself.
+ */
+function deliver(hook: McpAuditHook, event: McpAuditEvent, log: Logger): void {
+  const failed = (thrown: unknown): void => {
+    const code = stringField(thrown, 'code');
+    log.error('mcp.audit-hook.failed', {
+      surface: 'mcp',
+      event: event.kind,
+      ...(code === undefined ? {} : { code }),
+    });
+  };
+  try {
+    const pending = hook(event);
+    if (pending instanceof Promise) pending.catch(failed);
+  } catch (thrown) {
+    failed(thrown);
+  }
+}

package/src/audit.ts

@@ -23,6 +23,11 @@ export type McpOutcome =
   | 'policy-denied'
   /** Arguments failed the schema the agent was handed. Not an authz outcome. */
   | 'invalid-args'
+  /**
+   * Did not run because no live human approval exists for this exact call: one is pending, or the
+   * one there was expired. Expected — `mcpConfirmations` answers it by design — so `info`.
+   */
+  | 'unconfirmed'
   /**
    * The handler threw something that is not an authz denial: a non-authz framework refusal
    * (`db.migrate` aimed at prod), or a bug. Both want a human — a projected action rejecting
@@ -39,6 +44,7 @@ export type McpOutcome =
 const DENIAL_CODES: ReadonlySet<string> = new Set([
   'X_ADMIN_DENIED',
   'X_FORBIDDEN',
+  'X_MCP_CONFIRMATION_REJECTED',
   'X_UNAUTHENTICATED',
 ]);
 
@@ -54,9 +60,19 @@ const DENIAL_CODES: ReadonlySet<string> = new Set([
  */
 const ARGUMENT_CODES: ReadonlySet<string> = new Set(['X_ADMIN_INVALID']);
 
+/**
+ * `mcpConfirmations`' answers for a call no live approval covers. A rejection is NOT here: a human
+ * saying no is a denial, and it belongs in the bucket the denial alert reads.
+ */
+const UNCONFIRMED_CODES: ReadonlySet<string> = new Set([
+  'X_MCP_CONFIRMATION_PENDING',
+  'X_MCP_CONFIRMATION_EXPIRED',
+]);
+
 /** Classify a code a tool threw. Denials are outcome 3; everything else wants a human. */
 export function outcomeForCode(code: string): McpOutcome {
   if (DENIAL_CODES.has(code)) return 'policy-denied';
+  if (UNCONFIRMED_CODES.has(code)) return 'unconfirmed';
   return ARGUMENT_CODES.has(code) ? 'invalid-args' : 'failed';
 }
 
@@ -108,6 +124,7 @@ const LEVEL: ReadonlyMap<McpOutcome, 'info' | 'warn' | 'error'> = new Map([
   ['scope-denied', 'warn'],
   ['policy-denied', 'warn'],
   ['invalid-args', 'info'],
+  ['unconfirmed', 'info'],
   ['failed', 'error'],
 ]);
 // An outcome is a closed union, so the `Map` is total; `?? 'error'` is the type's witness, not a

package/src/caller-context.ts

@@ -5,7 +5,7 @@
 // came to answer differently by transport.
 
 import type { Actor } from '@ultimat3/core';
-import { createContext, hasContext, runWithContext, withChildContext } from '@ultimat3/core';
+import { ctxOf, hasContext, runWithContext, withChildContext } from '@ultimat3/core';
 
 /**
  * Run `fn` with `actor` as the ambient identity, whether or not a request is already in flight.
@@ -18,7 +18,5 @@ import { createContext, hasContext, runWithContext, withChildContext } from '@ul
  * reads off `ctx.actor` the same identity by construction rather than by two call sites agreeing.
  */
 export function asCallerContext<T>(actor: Actor, fn: () => T): T {
-  return hasContext()
-    ? withChildContext({ actor }, fn)
-    : runWithContext(createContext({ actor }), fn);
+  return hasContext() ? withChildContext({ actor }, fn) : runWithContext(ctxOf({ actor }), fn);
 }

package/src/confirmation-decide.ts

@@ -0,0 +1,116 @@
+// The decision action's handle: `view` shows a person the request exactly as the agent sent it;
+// `approve` / `reject` take a decision once, and an approval only for those same arguments. The
+// policy already ran (the factory's `can(…)`, agent refusal and tenant default included), so this
+// file decides STATE, never who.
+
+import type { Clock, SealKeySource, UltimateError } from '@ultimat3/core';
+import { compareFingerprint, openText } from '@ultimat3/core';
+import type { JsonValue } from '@ultimat3/schema';
+import {
+  McpConfirmationArgumentsMismatchError,
+  McpConfirmationDecidedError,
+  McpConfirmationExpiredError,
+  McpConfirmationUnknownError,
+} from './confirmation-errors';
+import {
+  MCP_CONFIRMATION_ARGUMENTS_PURPOSE,
+  MCP_CONFIRMATION_DIGEST_PURPOSE,
+} from './confirmation-gate';
+import type { McpConfirmation, McpConfirmationStore } from './confirmation-store';
+
+export interface DecisionAsked {
+  readonly id: string;
+  readonly decision: 'view' | 'approve' | 'reject';
+  /** What the person approves — the `arguments` `view` returned. Required to approve. */
+  readonly arguments?: Readonly<Record<string, JsonValue>> | undefined;
+}
+
+export interface DecisionAnswer {
+  readonly id: string;
+  readonly tool: string;
+  readonly status: 'pending' | 'approved' | 'rejected';
+  readonly expiresAt: Date;
+  readonly decidedAt: Date | null;
+  /** The arguments the agent sent, opened — what the person sees and what an approval binds to. */
+  readonly arguments: Record<string, JsonValue>;
+}
+
+export interface DecideDeps {
+  readonly store: McpConfirmationStore;
+  readonly clock: Clock;
+  readonly sealKeys: SealKeySource;
+}
+
+export async function decideConfirmation(
+  deps: DecideDeps,
+  asked: DecisionAsked,
+  deciderId: string,
+): Promise<DecisionAnswer> {
+  const row = await deps.store.get(asked.id);
+  if (row === undefined) throw new McpConfirmationUnknownError(asked.id);
+  const shown = await openArguments(row, deps.sealKeys);
+  if (asked.decision === 'view') return answer(row, shown);
+  const at = deps.clock.now();
+  const refused = stateRefusal(row, at);
+  if (refused !== undefined) throw refused;
+  if (asked.decision === 'approve') assertSameArguments(row, asked.arguments);
+  const status = asked.decision === 'approve' ? 'approved' : 'rejected';
+  const decided = await deps.store.decide(row.id, status, deciderId, at);
+  // The CAS lost to a concurrent decision or the expiry: re-read and say which.
+  if (decided === undefined) {
+    const now = await deps.store.get(row.id);
+    throw (now === undefined ? undefined : stateRefusal(now, at)) ?? expired(row);
+  }
+  return answer(decided, shown);
+}
+
+/**
+ * The approval binds to what the person was SHOWN: the keyed digest of the arguments they send back
+ * must match the row's, timing-safe (`compareFingerprint`). A swap between `view` and `approve` —
+ * or an approval sent with no arguments at all — decides nothing. `unverifiable` is a rotated
+ * signing secret: no approval, and the agent's next call opens a fresh confirmation anyway.
+ */
+function assertSameArguments(row: McpConfirmation, sent: DecisionAsked['arguments']): void {
+  const subject = { id: row.id, tool: row.tool, expiresAt: row.expiresAt };
+  if (sent === undefined) {
+    throw new McpConfirmationArgumentsMismatchError({ ...subject, reason: 'missing' });
+  }
+  const verdict = compareFingerprint(row.inputDigest, sent, MCP_CONFIRMATION_DIGEST_PURPOSE);
+  if (verdict === 'match') return;
+  throw new McpConfirmationArgumentsMismatchError({
+    ...subject,
+    reason: verdict === 'unverifiable' ? 'rotated' : 'different',
+  });
+}
+
+/** Why a row cannot be decided now: already decided, or past its expiry (or consumed as such). */
+function stateRefusal(row: McpConfirmation, at: Date): UltimateError | undefined {
+  if (row.status !== 'pending')
+    return new McpConfirmationDecidedError({ ...row, status: row.status });
+  if (row.consumedAt !== null || row.expiresAt.getTime() <= at.getTime()) return expired(row);
+  return undefined;
+}
+
+const expired = (row: McpConfirmation): UltimateError =>
+  new McpConfirmationExpiredError({ ...row, at: 'decision' });
+
+async function openArguments(
+  row: McpConfirmation,
+  sealKeys: SealKeySource,
+): Promise<Record<string, JsonValue>> {
+  const text = await openText(row.sealedArguments, {
+    purpose: MCP_CONFIRMATION_ARGUMENTS_PURPOSE,
+    ...sealKeys,
+  });
+  // Sealed by this package from a validated argument record, so the parse is of our own JSON.
+  return JSON.parse(text) as Record<string, JsonValue>;
+}
+
+const answer = (row: McpConfirmation, shown: Record<string, JsonValue>): DecisionAnswer => ({
+  id: row.id,
+  tool: row.tool,
+  status: row.status,
+  expiresAt: row.expiresAt,
+  decidedAt: row.decidedAt,
+  arguments: shown,
+});

package/src/confirmation-errors.ts

@@ -0,0 +1,137 @@
+// The refusals of `mcpConfirmations`: the agent's call that waits for a human, the human's decision
+// that came too late or twice, and the boot that gates a tool nobody projects. Split from
+// `errors.ts` for its ceiling. Each `cause` names the confirmation id: it is the one fact both the
+// agent relaying the request and the human deciding it need.
+
+import { UltimateError } from '@ultimat3/core';
+
+interface Subject {
+  readonly id: string;
+  readonly tool: string;
+  readonly expiresAt: Date;
+}
+
+/** The instant, in UTC — an ISO string carries its own zone, so no reader has to guess one. */
+const until = (subject: Subject): string => subject.expiresAt.toISOString();
+
+const meta = (subject: Subject) => ({
+  confirmation: subject.id,
+  tool: subject.tool,
+  expiresAt: until(subject),
+});
+
+/** The decision action, by the name it was registered under — or how to find it before then. */
+const decider = (name: string): string =>
+  name.length > 0 ? name : 'the mcpConfirmations() action';
+
+/** The call did not run: a human has to approve this exact call first. */
+export class McpConfirmationPendingError extends UltimateError {
+  constructor(subject: Subject & { readonly decider: string }) {
+    super({
+      code: 'X_MCP_CONFIRMATION_PENDING',
+      cause: `${subject.tool} needs a human's approval before it runs: confirmation ${subject.id} is pending until ${until(subject)}`,
+      fix: `confirmations({ id, decision: 'view' })   # as a person, through ${decider(subject.decider)}, with id ${subject.id}; then confirmations({ id, decision: 'approve', arguments }) with exactly what view returned (or decision: 'reject'), and the agent repeats the same tools/call before ${until(subject)}`,
+      callerFix: `ask a person who may approve it to view confirmation ${subject.id} and approve it with exactly the arguments it shows, then call ${subject.tool} again with exactly the same arguments before ${until(subject)}`,
+      meta: meta(subject),
+    });
+  }
+}
+
+/** The confirmation lapsed — before the call came back for it, or before a human decided it. */
+export class McpConfirmationExpiredError extends UltimateError {
+  constructor(subject: Subject & { readonly at: 'call' | 'decision' }) {
+    super({
+      code: 'X_MCP_CONFIRMATION_EXPIRED',
+      cause: `confirmation ${subject.id} for ${subject.tool} expired at ${until(subject)}${subject.at === 'call' ? '; the call did not run' : ' and can no longer be decided'}`,
+      fix:
+        subject.at === 'call'
+          ? `{ method: 'tools/call', params: { name, arguments } }   # ${subject.tool} again with the same arguments opens a new confirmation; decide it before expiry, or raise mcpConfirmations({ ttlMs })`
+          : `mcpConfirmations({ ttlMs })   # raise it if people need longer; ask the agent to call ${subject.tool} again, which opens a new confirmation`,
+      meta: meta(subject),
+    });
+  }
+}
+
+/** A person rejected this exact call. Audited as a denial — a human saying no is one. */
+export class McpConfirmationRejectedError extends UltimateError {
+  constructor(subject: Subject) {
+    super({
+      code: 'X_MCP_CONFIRMATION_REJECTED',
+      cause: `a person rejected confirmation ${subject.id}: ${subject.tool} did not run`,
+      fix: `{ method: 'tools/call', params: { name, arguments } }   # ${subject.tool} with arguments changed after asking the person who rejected ${subject.id}; the same arguments are rejected again`,
+      meta: meta(subject),
+    });
+  }
+}
+
+/** Approve or reject on a row already decided: a decision is taken once. */
+export class McpConfirmationDecidedError extends UltimateError {
+  constructor(subject: Subject & { readonly status: string }) {
+    super({
+      code: 'X_MCP_CONFIRMATION_DECIDED',
+      cause: `confirmation ${subject.id} for ${subject.tool} was already ${subject.status}; a decision is taken once`,
+      fix: `{ method: 'tools/call', params: { name, arguments } }   # ${subject.id} is final; the agent calling ${subject.tool} again opens a new confirmation to decide`,
+      meta: { ...meta(subject), status: subject.status },
+    });
+  }
+}
+
+/** No confirmation has this id — mistyped, from another deployment, or purged after its expiry. */
+export class McpConfirmationUnknownError extends UltimateError {
+  constructor(id: string) {
+    super({
+      code: 'X_MCP_CONFIRMATION_UNKNOWN',
+      cause: `no MCP confirmation has id ${id}`,
+      fix: `confirmations({ id, decision: 'view' })   # with the id from the X_MCP_CONFIRMATION_PENDING answer the agent received; one past its expiry may be purged — ask the agent to call the tool again`,
+      meta: { confirmation: id },
+    });
+  }
+}
+
+/** `mcpConfirmations({ tools })` names a tool this server does not project — or none at all. */
+export class McpConfirmationToolUnknownError extends UltimateError {
+  constructor(input: { readonly unknown: readonly string[]; readonly known: readonly string[] }) {
+    const known = input.known.length === 0 ? '(none)' : input.known.join(', ');
+    super({
+      code: 'X_MCP_CONFIRMATION_TOOL_UNKNOWN',
+      cause:
+        input.unknown.length === 0
+          ? 'mcpConfirmations({ tools: [] }) gates no tool, so every call it was meant to hold would run unconfirmed'
+          : `mcpConfirmations({ tools }) names ${input.unknown.join(', ')}, which this MCP server does not project — that call would run unconfirmed`,
+      fix: `mcpConfirmations({ tools: [...] })   # name tools this server projects: ${known}`,
+      meta: { unknown: [...input.unknown], known: [...input.known] },
+    });
+  }
+}
+
+/** The store could not settle which row is open for a call, three times running. Retryable. */
+export class McpConfirmationContestedError extends UltimateError {
+  constructor(tool: string) {
+    super({
+      code: 'X_MCP_CONFIRMATION_CONTESTED',
+      cause: `identical ${tool} calls from one agent kept opening and consuming its confirmation concurrently`,
+      fix: `{ method: 'tools/call', params: { name, arguments } }   # retry ${tool} once the agent's concurrent identical calls finish — send one at a time`,
+      meta: { tool },
+    });
+  }
+}
+
+/**
+ * An approval that does not carry the arguments the agent sent: none, different ones (a swap
+ * between the view and the decision), or a row keyed under a rotated signing secret.
+ */
+export class McpConfirmationArgumentsMismatchError extends UltimateError {
+  constructor(subject: Subject & { readonly reason: 'missing' | 'different' | 'rotated' }) {
+    const why = {
+      missing: 'the approval carried no arguments',
+      different: 'the approval carried arguments other than the ones the agent sent',
+      rotated: 'the confirmation was keyed under a signing secret this process no longer holds',
+    }[subject.reason];
+    super({
+      code: 'X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH',
+      cause: `confirmation ${subject.id} for ${subject.tool} was not decided: ${why}`,
+      fix: `confirmations({ id, decision: 'view' })   # for ${subject.id}, then confirmations({ id, decision: 'approve', arguments }) with exactly the arguments it returns; a rotated one: ask the agent to call ${subject.tool} again`,
+      meta: { ...meta(subject), reason: subject.reason },
+    });
+  }
+}

package/src/confirmation-gate.ts

@@ -0,0 +1,101 @@
+// The agent's side of `mcpConfirmations`: a gated tool's `handle`, wrapped. It runs AFTER the
+// registry's visibility → scope → args and the tool's caller-only `admit`, and BEFORE the tool's own
+// `handle` — where a projected action's full policy runs. So the order is visibility → scope →
+// args → admit → confirmation → policy, and a caller the tool refuses outright never opens a row.
+
+import { keyedFingerprint, seal, uuidV7 } from '@ultimat3/core';
+import {
+  McpConfirmationContestedError,
+  McpConfirmationExpiredError,
+  McpConfirmationPendingError,
+  McpConfirmationRejectedError,
+  McpConfirmationToolUnknownError,
+} from './confirmation-errors';
+import type { McpConfirmations } from './confirmations';
+import type { AnyMcpTool, McpCaller, McpToolResult, ToolArgs } from './registry';
+
+/**
+ * The gated catalog. Refuses at boot a name the catalog does not hold — that call would run with
+ * no person ever asked, which is exactly the silent pass the gate exists to remove.
+ */
+export function withConfirmations(
+  tools: readonly AnyMcpTool[],
+  confirmations: McpConfirmations | undefined,
+): readonly AnyMcpTool[] {
+  if (confirmations === undefined) return tools;
+  const known = tools.map((tool) => tool.name);
+  const unknown = confirmations.tools.filter((name) => !known.includes(name));
+  if (unknown.length > 0) throw new McpConfirmationToolUnknownError({ unknown, known });
+  const gated = new Set(confirmations.tools);
+  return tools.map((tool) => (gated.has(tool.name) ? gate(tool, confirmations) : tool));
+}
+
+/** What the arguments are sealed FOR — bound into the AES-GCM tag, so they open as nothing else. */
+export const MCP_CONFIRMATION_ARGUMENTS_PURPOSE = 'mcp-confirmation.arguments';
+
+/** Separates this use of the signing secret from every other keyed fingerprint. */
+export const MCP_CONFIRMATION_DIGEST_PURPOSE = 'mcp-confirmation';
+
+/**
+ * The digest an approval binds to: core's `keyedFingerprint` over the VALIDATED arguments (defaults
+ * applied, the reserved `idempotencyKey` included) — HMAC-SHA-256 under a key derived from the
+ * app's signing secret, 128 bits, `h1:<key id>:<mac>`. Keyed, never a plain hash, because the row
+ * PERSISTS it: an unkeyed digest of `{ accountNumber }` is brute-forced from a database read. And it
+ * binds: a second input sharing an approved digest needs the key.
+ *
+ * The store finds the open row by EQUALITY on this string, so the key id is part of the lookup:
+ * after a secret rotation the same call computes a different value, matches no row, and opens a
+ * FRESH confirmation — never a mismatch error, never the old approval. Rows under the old key are
+ * orphaned until `purge`. Equality, not `compareFingerprint`: the caller cannot compute the value,
+ * so the lookup's timing says nothing, and `unverifiable` could only describe a row this call
+ * never finds.
+ */
+export function inputDigest(args: ToolArgs): string {
+  return keyedFingerprint(args, MCP_CONFIRMATION_DIGEST_PURPOSE);
+}
+
+function gate(tool: AnyMcpTool, confirmations: McpConfirmations): AnyMcpTool {
+  const { store, clock, ttlMs, sealKeys } = confirmations;
+  return {
+    ...tool,
+    confirms: true,
+    async handle(args: ToolArgs, caller: McpCaller): Promise<McpToolResult> {
+      // Caller-only half of the policy first: one who may never call this opens no row for a person
+      // to look at. Throws the same denial `handle` would, rendered by the server.
+      tool.admit?.(caller);
+      const now = clock.now();
+      const draft = {
+        id: uuidV7(clock),
+        actorId: caller.actor.id,
+        orgId: caller.actor.orgId ?? null,
+        tool: tool.name,
+        inputDigest: inputDigest(args),
+        // Sealed, never plaintext at rest: the person deciding reads them through the decision
+        // action's `view`, and approves only by sending them back (`confirmation-decide.ts`).
+        sealedArguments: await seal(JSON.stringify(args), {
+          purpose: MCP_CONFIRMATION_ARGUMENTS_PURPOSE,
+          ...sealKeys,
+        }),
+        createdAt: now,
+        expiresAt: new Date(now.getTime() + ttlMs),
+      };
+      // Bounded: `consume` loses only to a concurrent identical call by the same agent, which then
+      // carries the outcome; this one opens the next row on the following pass.
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        const { row, created } = await store.open(draft);
+        const subject = { id: row.id, tool: tool.name, expiresAt: row.expiresAt };
+        const live = row.expiresAt.getTime() > now.getTime();
+        if (created || (row.status === 'pending' && live)) {
+          throw new McpConfirmationPendingError({ ...subject, decider: confirmations.name });
+        }
+        // Every other state is an OUTCOME, delivered once: taking it is what frees this call to
+        // ask again, and what makes one approval run one call.
+        if (!(await store.consume(row.id, now))) continue;
+        if (row.status === 'rejected') throw new McpConfirmationRejectedError(subject);
+        if (!live) throw new McpConfirmationExpiredError({ ...subject, at: 'call' });
+        return tool.handle(args, caller);
+      }
+      throw new McpConfirmationContestedError(tool.name);
+    },
+  };
+}