@softure-ai/mcp-access 0.2.9 → 0.4.0

package/src/server/api-tokens.ts

@@ -0,0 +1,224 @@
+// Personal tokens for an app's plain HTTP routes (#961): a phone Shortcut, an automation tool or a
+// script sends `Authorization: Bearer <prefix>…` and the route calls `requireApiToken`. They share the
+// table, hashing, expiry, limit, privacy and prune with the MCP tokens (`tokens.ts`); the `kind`
+// column keeps the two doors apart. Nothing here imports the MCP SDK: `@softure-ai/mcp-access/tokens`
+// is for an app that has no MCP server.
+import { err, errorLogLabel, getModule, ok, type Err, type Ok } from "@softure-ai/core";
+import { randomBytes } from "node:crypto";
+import { consumeRateLimit, identifyClient } from "@softure-ai/security/server";
+import type { ApiTokenIdentity, ApiTokenRefusal } from "../contract.js";
+import { MAX_PRESENTED_TOKEN_LENGTH, type ApiTokenOptions } from "../options.js";
+import { getMcpAccessOptions } from "./options.js";
+import { findValidToken, hashAccessToken, insertToken, type McpAccessContext } from "./tokens.js";
+import { isWritingEnabled } from "./writes-switch.js";
+
+/** The bucket counted per client address before the token is looked up. */
+export const API_RATE_LIMIT_BUCKET = "api";
+/** The bucket counted per verified token. */
+export const API_TOKEN_RATE_LIMIT_BUCKET = "api-token";
+
+const BEARER_PREFIX = /^Bearer[ \t]+/i;
+const NO_STORE = "no-store";
+
+/** The app's API token settings, or null while `apiTokens` is unset. */
+export function getApiTokenOptions(ctx: Pick<McpAccessContext, "config">): ApiTokenOptions | null {
+  return getMcpAccessOptions(ctx.config).apiTokens ?? null;
+}
+
+/** Whether a presented value has the shape of one of the app's API tokens: its prefix and 32 base64url bytes. */
+export function isApiTokenShape(options: ApiTokenOptions, token: string): boolean {
+  if (token.length > MAX_PRESENTED_TOKEN_LENGTH || !token.startsWith(options.prefix)) return false;
+  return /^[A-Za-z0-9_-]{43}$/.test(token.slice(options.prefix.length));
+}
+
+/**
+ * A new API token: the app's prefix and 32 random bytes. The stored sha256 covers the random part
+ * alone (the secret); the prefix is a label that the shape check requires before any lookup.
+ */
+function createApiSecret(prefix: string): { readonly secret: string; readonly secretHash: string } {
+  const random = randomBytes(32).toString("base64url");
+  return { secret: `${prefix}${random}`, secretHash: hashAccessToken(random) };
+}
+
+export interface IssueApiTokenInput {
+  /** The auth user id of the owner, from the session. */
+  readonly userId: string;
+  readonly name: string;
+  /** Scope names from the form: any values; unknown ones are refused. */
+  readonly scopes: readonly string[];
+}
+
+export interface IssuedApiToken {
+  readonly id: string;
+  /** The plaintext: shown to the owner once, stored nowhere. */
+  readonly token: string;
+  readonly name: string;
+  /** The scopes granted, in the order the app declares them. */
+  readonly scopes: readonly string[];
+  readonly expiresAt: Date;
+}
+
+export type IssueApiTokenResult =
+  | Ok<IssuedApiToken>
+  | Err<
+      | "mcp-access.name_required"
+      | "mcp-access.name_too_long"
+      | "mcp-access.token_limit_reached"
+      | "mcp-access.api_disabled"
+      | "mcp-access.scope_required"
+      | "mcp-access.scope_unknown"
+    >;
+
+/**
+ * Issues an API token with the asked scopes. A scope the app does not declare is refused; a write
+ * scope is granted only while `allowWrites` is on (left out otherwise), and a token needs at least
+ * one scope left. Shares the per-account limit and lock with MCP tokens. Database failures propagate.
+ */
+export async function issueApiToken(ctx: McpAccessContext, input: IssueApiTokenInput): Promise<IssueApiTokenResult> {
+  const apiOptions = getApiTokenOptions(ctx);
+  if (apiOptions === null) return err("mcp-access.api_disabled");
+  const asked = new Set(input.scopes);
+  const declared = new Set(apiOptions.scopes.map((scope) => scope.name));
+  if ([...asked].some((name) => !declared.has(name))) return err("mcp-access.scope_unknown");
+
+  const { allowWrites } = getMcpAccessOptions(ctx.config);
+  const granted = apiOptions.scopes.filter((scope) => asked.has(scope.name) && (scope.access === "read" || allowWrites));
+  if (granted.length === 0) return err("mcp-access.scope_required");
+
+  const scopes = granted.map((scope) => scope.name);
+  const canWrite = granted.some((scope) => scope.access === "write");
+  const result = await insertToken(ctx, { userId: input.userId, name: input.name, kind: "api", canWrite, scopes, secret: createApiSecret(apiOptions.prefix) });
+  if (!result.ok) return result;
+  const { id, token, name, expiresAt } = result.value;
+  return ok({ id, token, name, scopes, expiresAt });
+}
+
+/** The identity behind a valid API token. */
+export interface VerifiedApiToken extends ApiTokenIdentity {
+  readonly expiresAt: Date;
+}
+
+/**
+ * The identity behind an API token, or null for anything unknown, revoked, expired, an MCP token or
+ * any value without the app's prefix. Write scopes count only while writing is enabled (`allowWrites`
+ * and the `mcp-access.writes_enabled` switch). Records the use like an MCP token. Database failures propagate.
+ */
+export async function verifyApiToken(ctx: McpAccessContext, token: string): Promise<VerifiedApiToken | null> {
+  return (await checkApiToken(ctx, token))?.verified ?? null;
+}
+
+/** A verified token and the write scopes it holds that the writes switch keeps from it now. */
+async function checkApiToken(ctx: McpAccessContext, token: string): Promise<{ verified: VerifiedApiToken; withheld: readonly string[] } | null> {
+  const apiOptions = getApiTokenOptions(ctx);
+  if (apiOptions === null || !isApiTokenShape(apiOptions, token)) return null;
+  const row = await findValidToken(ctx, hashAccessToken(token.slice(apiOptions.prefix.length)), "api");
+  if (row === null) return null;
+  const isWriteAllowed = await isWritingEnabled(ctx);
+  const writeScopes = new Set(apiOptions.scopes.filter((scope) => scope.access === "write").map((scope) => scope.name));
+  const withheld = isWriteAllowed ? [] : row.scopes.filter((scope) => writeScopes.has(scope));
+  return {
+    verified: { userId: row.userId, tokenId: row.id, scopes: row.scopes.filter((scope) => !withheld.includes(scope)), expiresAt: row.expiresAt },
+    withheld,
+  };
+}
+
+export interface RequireApiTokenOptions {
+  /** Every scope the route needs; each must be one the app declares in `apiTokens.scopes`. */
+  readonly scopes: readonly string[];
+}
+
+/**
+ * Checks a route's request for a valid API token with every scope in `scopes`, in this order:
+ * the client is identified, its request counted per address (before any lookup, so a flood of
+ * guesses costs nothing), the `Authorization: Bearer` token verified, the request counted per token,
+ * the scopes checked. Expected refusals are values, for `apiTokenErrorResponse`; a failed count or
+ * lookup is logged and answered `mcp-access.api_unavailable`. A scope the app does not declare, or a
+ * missing bucket, is a setup bug and throws.
+ */
+export async function requireApiToken(
+  ctx: McpAccessContext,
+  request: Request,
+  { scopes: required }: RequireApiTokenOptions,
+): Promise<Ok<ApiTokenIdentity> | ApiTokenRefusal> {
+  const apiOptions = getApiTokenOptions(ctx);
+  if (apiOptions === null) {
+    throw new Error("@softure-ai/mcp-access: requireApiToken needs apiTokens in mcpAccess({ ... })");
+  }
+  assertDeclaredScopes(apiOptions, required);
+  assertRateLimitBuckets(ctx);
+
+  const client = identifyClient(ctx, request.headers);
+  if (!client.ok) return client;
+  try {
+    const byAddress = await consumeRateLimit(ctx, { bucket: API_RATE_LIMIT_BUCKET, key: client.value });
+    if (!byAddress.ok) return { ...err("security.rate_limited"), retryAfterSeconds: byAddress.retryAfterSeconds };
+
+    const header = request.headers.get("authorization");
+    if (header === null || !BEARER_PREFIX.test(header)) return err("mcp-access.api_token_missing");
+    const checked = await checkApiToken(ctx, header.replace(BEARER_PREFIX, "").trim());
+    if (checked === null) return err("mcp-access.api_token_invalid");
+    const { verified, withheld } = checked;
+
+    const byToken = await consumeRateLimit(ctx, { bucket: API_TOKEN_RATE_LIMIT_BUCKET, key: `token:${verified.tokenId}` });
+    if (!byToken.ok) return { ...err("security.rate_limited"), retryAfterSeconds: byToken.retryAfterSeconds };
+
+    const missingScopes = required.filter((scope) => !verified.scopes.includes(scope));
+    if (missingScopes.length > 0) {
+      // Write scopes the token holds while writing is off: say so, the token itself is fine.
+      const code = missingScopes.every((scope) => withheld.includes(scope)) ? "mcp-access.api_writes_disabled" : "mcp-access.api_scope_missing";
+      return { ...err(code), missingScopes };
+    }
+    return ok({ userId: verified.userId, tokenId: verified.tokenId, scopes: verified.scopes });
+  } catch (error) {
+    // The token is never logged; the operation and the failure label are.
+    console.error(`@softure-ai/mcp-access: checking an API token failed: ${errorLogLabel(error)}`);
+    return err("mcp-access.api_unavailable");
+  }
+}
+
+const STATUS_BY_CODE: Readonly<Record<ApiTokenRefusal["error"], number>> = {
+  "security.client_unidentified": 400,
+  "mcp-access.api_token_missing": 401,
+  "mcp-access.api_token_invalid": 401,
+  "mcp-access.api_scope_missing": 403,
+  "mcp-access.api_writes_disabled": 403,
+  "security.rate_limited": 429,
+  "mcp-access.api_unavailable": 503,
+};
+
+/**
+ * The HTTP answer to a refusal of `requireApiToken`: JSON `{ error }` (the code without its module), with
+ * `WWW-Authenticate` on 401 and 403 (RFC 6750 §3), `Retry-After` on 429, and never cached.
+ */
+export function apiTokenErrorResponse(refusal: ApiTokenRefusal): Response {
+  const status = STATUS_BY_CODE[refusal.error];
+  const error = refusal.error.slice(refusal.error.indexOf(".") + 1);
+  const headers = new Headers({ "cache-control": NO_STORE });
+  if (status === 401) {
+    headers.set("www-authenticate", refusal.error === "mcp-access.api_token_missing" ? "Bearer" : 'Bearer error="invalid_token"');
+  }
+  if ("missingScopes" in refusal) {
+    headers.set("www-authenticate", `Bearer error="insufficient_scope", scope="${refusal.missingScopes.join(" ")}"`);
+    return Response.json({ error, missingScopes: refusal.missingScopes }, { status, headers });
+  }
+  if ("retryAfterSeconds" in refusal) headers.set("retry-after", String(refusal.retryAfterSeconds));
+  return Response.json({ error }, { status, headers });
+}
+
+function assertDeclaredScopes(apiOptions: ApiTokenOptions, required: readonly string[]): void {
+  const declared = new Set(apiOptions.scopes.map((scope) => scope.name));
+  const unknown = required.filter((scope) => !declared.has(scope));
+  if (unknown.length > 0) {
+    throw new Error(`@softure-ai/mcp-access: requireApiToken asks for scopes apiTokens.scopes does not declare: ${unknown.join(", ")}`);
+  }
+}
+
+/** A missing bucket is a setup bug: thrown, so it reaches the log by name instead of a quiet 503. */
+function assertRateLimitBuckets(ctx: McpAccessContext): void {
+  const options = getModule(ctx.config, "security")?.options as { buckets?: Record<string, unknown> } | undefined;
+  for (const bucket of [API_RATE_LIMIT_BUCKET, API_TOKEN_RATE_LIMIT_BUCKET]) {
+    if (options?.buckets?.[bucket] === undefined) {
+      throw new Error(`@softure-ai/mcp-access: the security module has no "${bucket}" bucket; spread API_TOKEN_RATE_LIMIT_BUCKETS into security({ buckets })`);
+    }
+  }
+}

package/src/server/confirmation.ts

@@ -0,0 +1,316 @@
+// Confirmed tool calls: the `--commit` rule over MCP for a tool that spends money or cannot be undone. A call
+// without `confirmation` only runs the estimate and answers it with a confirmation token; the assistant shows the
+// estimate, the person agrees in the chat, and a second call with the same arguments and the token does the work.
+//
+//   server.registerTool("render_film", { inputSchema: { scene: z.string(), confirmation: confirmationInput } },
+//     withConfirmation((args) => renderFilm(ctx, identity.userId, args), {
+//       ctx, identity, tool: "render_film",
+//       estimate: (args) => estimateFilm(ctx, identity.userId, args), // { total: 12, currency: "credits", ... }
+//     }));
+//
+// The token is a stateless HMAC (`MCP_CONFIRMATION_SECRET`) over the tool, a digest of the canonical JSON of the
+// arguments, a digest of the account and access token, the estimate's total and an expiry. Its payload carries
+// those digests in the clear, so each mismatch gets its own code after the signature has been checked. It is
+// single use: the confirmed call stores its hash (`mcp.used_confirmations`) before the work runs.
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { formatMessage } from "@softure-ai/core";
+import { lte } from "drizzle-orm";
+import { z } from "zod";
+import type { McpServerIdentity } from "../contract.js";
+import { en } from "../messages/en.js";
+import { usedConfirmations } from "../schema.js";
+import { getMcpAccessMessages } from "./options.js";
+import type { McpAccessContext } from "./tokens.js";
+import { withToolErrors, type ToolCaller, type ToolCallHook, type ToolErrorHints } from "./tools.js";
+import type { CallToolResult } from "@modelcontextprotocol/server";
+
+/** The argument that carries the token on the confirmed call. */
+export const CONFIRMATION_FIELD = "confirmation";
+
+/** Signs and verifies confirmation tokens. */
+export const CONFIRMATION_SECRET_ENV = "MCP_CONFIRMATION_SECRET";
+
+/** A shorter secret counts as missing: a guessable key lets anyone mint a confirmation. */
+export const MIN_CONFIRMATION_SECRET_LENGTH = 32;
+
+/** How long a confirmation stays valid by default: fifteen minutes. */
+export const DEFAULT_CONFIRMATION_TTL_SECONDS = 900;
+
+/** The longest token the check looks at; a real one is about 300 characters. */
+const MAX_CONFIRMATION_LENGTH = 2048;
+
+/** The `confirmation` field for the tool's input schema, so a strict server lists and accepts it. */
+export const confirmationInput = z.string().max(MAX_CONFIRMATION_LENGTH).optional().describe(en.confirmation.fieldDescription);
+
+/** The stable codes of a refused confirmed call. */
+export type ConfirmationErrorCode =
+  | "input.confirmation_invalid"
+  | "input.confirmation_other_tool"
+  | "input.confirmation_other_account"
+  | "input.confirmation_expired"
+  | "input.confirmation_arguments_changed"
+  | "input.confirmation_estimate_changed"
+  | "input.confirmation_used";
+
+/** What a call would do and cost: `total` is bound to the token; every other field is shown to the person as it is. */
+export interface ConfirmationEstimate {
+  readonly total: number;
+}
+
+/** The answer of a call that needs the person's yes first. */
+export interface ConfirmationRequest<Estimate extends ConfirmationEstimate = ConfirmationEstimate> {
+  readonly needsConfirmation: true;
+  readonly estimate: Estimate;
+  readonly confirmation: string;
+  /** ISO 8601. */
+  readonly expiresAt: string;
+  /** The fixed sentence that tells the assistant to ask the person before calling again. */
+  readonly message: string;
+}
+
+/** The tool's arguments as the SDK passes them, `confirmation` included. */
+export type ConfirmedToolArgs<Args> = Args & { readonly confirmation?: string | undefined };
+
+export interface WithConfirmationOptions<Args, Estimate extends ConfirmationEstimate> {
+  /** The module context: the database for the used tokens, the clock for the expiry, the config for the copy. */
+  readonly ctx: McpAccessContext;
+  /** The request's identity, as the server factory got it: the token is bound to its account and access token. */
+  readonly identity: Pick<McpServerIdentity, "userId" | "tokenId">;
+  /** The tool's registered name, also its label in the log line and the `onToolCall` record. */
+  readonly tool: string;
+  /** What the call would do and cost, without doing it. Runs on both calls; the second must give the same total. */
+  readonly estimate: (args: Args) => Estimate | Promise<Estimate>;
+  /** How long the person has to agree. Default: 900 seconds. */
+  readonly ttlSeconds?: number;
+  /** Runs the handler at once, without asking, when this answers true, e.g. `(estimate) => estimate.total === 0`. */
+  readonly runWithoutConfirmationWhen?: (estimate: Estimate) => boolean;
+  /** Default: `process.env.MCP_CONFIRMATION_SECRET`, read on every call. */
+  readonly secret?: string;
+  /** Texts per error code, as in `withToolErrors`; they also replace the refusal texts of the dictionary. */
+  readonly hints?: ToolErrorHints;
+  /** Called once after each call with its record (`confirmed` included), as in `withToolErrors`. */
+  readonly onToolCall?: ToolCallHook;
+  /** Who called, for the record, as in `withToolErrors`. */
+  readonly caller?: ToolCaller;
+}
+
+/** The token's signed payload. Short keys keep the token short. */
+interface ConfirmationPayload {
+  /** Format version. */
+  readonly v: 1;
+  /** Tool name. */
+  readonly t: string;
+  /** sha256 of the canonical JSON of the arguments without `confirmation`. */
+  readonly a: string;
+  /** sha256 of the user id and the access token id. */
+  readonly c: string;
+  /** The estimate's total. */
+  readonly n: number;
+  /** Expiry, epoch seconds. */
+  readonly e: number;
+  /** A random nonce, so two estimates of the same input are two tokens. */
+  readonly r: string;
+}
+
+/**
+ * Domain separation: the same key signing anything else can never produce a valid confirmation. Changing it voids
+ * every token in flight, exactly like changing the key.
+ */
+const SIGNED_PREFIX = "softure.mcp-access.confirmation.v1:";
+
+const TOKEN_PATTERN = /^([A-Za-z0-9_-]{1,2000})\.([A-Za-z0-9_-]{43})$/;
+const DIGEST_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+const payloadSchema = z.strictObject({
+  v: z.literal(1),
+  t: z.string().min(1).max(128),
+  a: z.string().regex(DIGEST_PATTERN),
+  c: z.string().regex(DIGEST_PATTERN),
+  n: z.number().finite(),
+  e: z.number().int().positive(),
+  r: z.string().regex(/^[A-Za-z0-9_-]{16,64}$/),
+});
+
+/**
+ * The tool callback for `server.registerTool(name, { inputSchema: { ...fields, confirmation: confirmationInput } },
+ * withConfirmation(handler, options))`. Without `confirmation` it runs `estimate` only and answers a
+ * `ConfirmationRequest` (or runs the handler when `runWithoutConfirmationWhen` says so); with a valid one it runs
+ * the handler with the arguments without `confirmation`. A refusal answers its `input.confirmation_*` text.
+ */
+export function withConfirmation<Args extends Readonly<Record<string, unknown>>, Estimate extends ConfirmationEstimate>(
+  handler: (args: Args) => unknown,
+  options: WithConfirmationOptions<Args, Estimate>,
+): (args: ConfirmedToolArgs<Args>) => Promise<CallToolResult> {
+  return async (input) => {
+    const { [CONFIRMATION_FIELD]: confirmation, ...rest } = input;
+    const args = rest as unknown as Args;
+    let confirmed = false;
+    const recordOptions = {
+      label: options.tool,
+      args: rest,
+      hints: { ...getRefusalTexts(options.ctx), ...options.hints },
+      // Read after the work, when the call has decided whether it ran on a confirmation.
+      get confirmed(): boolean {
+        return confirmed;
+      },
+      ...(options.onToolCall === undefined ? {} : { onToolCall: options.onToolCall }),
+      ...(options.caller === undefined ? {} : { caller: options.caller }),
+    };
+    return withToolErrors(async () => {
+      const secret = readConfirmationSecret(options);
+      const estimate = await runEstimate(options, args);
+      if (confirmation === undefined) {
+        if (options.runWithoutConfirmationWhen?.(estimate) === true) return handler(args);
+        return requestConfirmation(options, args, estimate, secret);
+      }
+      const refusal = await checkConfirmation(options, { token: confirmation, args, estimate, secret });
+      if (refusal !== null) return { ok: false, error: refusal };
+      confirmed = true;
+      return handler(args);
+    }, recordOptions);
+  };
+}
+
+/** Deletes the used tokens past their expiry; a daily job through `pruneMcpAccess`. */
+export async function pruneUsedConfirmations(ctx: McpAccessContext): Promise<number> {
+  const removed = await ctx.db
+    .delete(usedConfirmations)
+    .where(lte(usedConfirmations.expiresAt, ctx.clock.now()))
+    .returning({ tokenHash: usedConfirmations.tokenHash });
+  return removed.length;
+}
+
+function readConfirmationSecret(options: { readonly secret?: string; readonly tool: string }): string {
+  const secret = options.secret ?? process.env[CONFIRMATION_SECRET_ENV];
+  if (secret !== undefined && secret.length >= MIN_CONFIRMATION_SECRET_LENGTH) return secret;
+  // The boundary logs a thrown error by its kind only, so the cause is named here once.
+  console.error(`@softure-ai/mcp-access: tool ${options.tool} needs ${CONFIRMATION_SECRET_ENV} (at least ${String(MIN_CONFIRMATION_SECRET_LENGTH)} characters)`);
+  throw new Error(`@softure-ai/mcp-access: ${CONFIRMATION_SECRET_ENV} is missing or shorter than ${String(MIN_CONFIRMATION_SECRET_LENGTH)} characters`);
+}
+
+async function runEstimate<Args, Estimate extends ConfirmationEstimate>(options: WithConfirmationOptions<Args, Estimate>, args: Args): Promise<Estimate> {
+  const estimate = await options.estimate(args);
+  if (typeof estimate !== "object" || estimate === null || typeof estimate.total !== "number" || !Number.isFinite(estimate.total)) {
+    throw new Error(`@softure-ai/mcp-access: the estimate of tool ${options.tool} has no finite numeric total`);
+  }
+  return estimate;
+}
+
+function requestConfirmation<Args, Estimate extends ConfirmationEstimate>(
+  options: WithConfirmationOptions<Args, Estimate>,
+  args: Args,
+  estimate: Estimate,
+  secret: string,
+): ConfirmationRequest<Estimate> {
+  const ttlSeconds = options.ttlSeconds ?? DEFAULT_CONFIRMATION_TTL_SECONDS;
+  const expiresAtSeconds = Math.floor(options.ctx.clock.now().getTime() / 1000) + Math.max(1, Math.floor(ttlSeconds));
+  const payload: ConfirmationPayload = {
+    v: 1,
+    t: options.tool,
+    a: digestArguments(args),
+    c: digestCaller(options.identity),
+    n: estimate.total,
+    e: expiresAtSeconds,
+    r: randomBytes(16).toString("base64url"),
+  };
+  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const expiresAt = new Date(expiresAtSeconds * 1000).toISOString();
+  return {
+    needsConfirmation: true,
+    estimate,
+    confirmation: `${encoded}.${sign(encoded, secret)}`,
+    expiresAt,
+    message: formatMessage(getMcpAccessMessages(options.ctx.config).confirmation.ask, { expiresAt }),
+  };
+}
+
+interface ConfirmationCheck<Args, Estimate> {
+  readonly token: string;
+  readonly args: Args;
+  readonly estimate: Estimate;
+  readonly secret: string;
+}
+
+/**
+ * The refusal code, or null when the call may run. The signature is checked first, so no field of the payload is
+ * trusted before it; the token is consumed last, so a refused call never uses up a valid confirmation.
+ */
+async function checkConfirmation<Args, Estimate extends ConfirmationEstimate>(
+  options: WithConfirmationOptions<Args, Estimate>,
+  check: ConfirmationCheck<Args, Estimate>,
+): Promise<ConfirmationErrorCode | null> {
+  const payload = readSignedPayload(check.token, check.secret);
+  if (payload === null) return "input.confirmation_invalid";
+  if (payload.t !== options.tool) return "input.confirmation_other_tool";
+  if (payload.c !== digestCaller(options.identity)) return "input.confirmation_other_account";
+  const now = options.ctx.clock.now();
+  if (now.getTime() >= payload.e * 1000) return "input.confirmation_expired";
+  if (payload.a !== digestArguments(check.args)) return "input.confirmation_arguments_changed";
+  if (payload.n !== check.estimate.total) return "input.confirmation_estimate_changed";
+  const inserted = await options.ctx.db
+    .insert(usedConfirmations)
+    .values({ tokenHash: createHash("sha256").update(check.token).digest("hex"), usedAt: now, expiresAt: new Date(payload.e * 1000) })
+    .onConflictDoNothing()
+    .returning({ tokenHash: usedConfirmations.tokenHash });
+  return inserted.length === 0 ? "input.confirmation_used" : null;
+}
+
+/** The payload of a token this secret signed, else null. Never throws. */
+function readSignedPayload(token: string, secret: string): ConfirmationPayload | null {
+  if (token.length > MAX_CONFIRMATION_LENGTH) return null;
+  const match = TOKEN_PATTERN.exec(token);
+  if (match === null) return null;
+  const [, encoded = "", signature = ""] = match;
+  // Both are 43 characters of base64url (the pattern), so the buffers have the same length.
+  if (!timingSafeEqual(Buffer.from(sign(encoded, secret)), Buffer.from(signature))) return null;
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+  } catch {
+    // Signed by this secret but unreadable: only a key shared with another signer could produce that.
+    return null;
+  }
+  const parsed = payloadSchema.safeParse(decoded);
+  return parsed.success ? parsed.data : null;
+}
+
+function sign(encoded: string, secret: string): string {
+  return createHmac("sha256", secret).update(`${SIGNED_PREFIX}${encoded}`).digest("base64url");
+}
+
+function digestArguments(args: unknown): string {
+  return createHash("sha256").update(toCanonicalJson(args)).digest("base64url");
+}
+
+function digestCaller(identity: Pick<McpServerIdentity, "userId" | "tokenId">): string {
+  return createHash("sha256").update(JSON.stringify([identity.userId, identity.tokenId])).digest("base64url");
+}
+
+/** JSON with every object's keys sorted and `undefined` fields left out, so equal arguments give equal text. */
+export function toCanonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value)) ?? "null";
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((item) => (item === undefined ? null : sortKeys(item)));
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value !== "object" || value === null) return value;
+  const entries = Object.entries(value)
+    .filter(([, item]) => item !== undefined)
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+  return Object.fromEntries(entries.map(([key, item]) => [key, sortKeys(item)]));
+}
+
+/** The dictionary's refusal texts per code, with the app's overrides. */
+function getRefusalTexts(ctx: McpAccessContext): Record<ConfirmationErrorCode, string> {
+  const texts = getMcpAccessMessages(ctx.config).confirmation;
+  return {
+    "input.confirmation_invalid": texts.invalid,
+    "input.confirmation_other_tool": texts.otherTool,
+    "input.confirmation_other_account": texts.otherAccount,
+    "input.confirmation_expired": texts.expired,
+    "input.confirmation_arguments_changed": texts.argumentsChanged,
+    "input.confirmation_estimate_changed": texts.estimateChanged,
+    "input.confirmation_used": texts.used,
+  };
+}

package/src/server/health.ts

@@ -1,5 +1,5 @@
 // The module's readiness probe for `GET /api/health` of `@softure-ai/ops`: the tokens table (with
-// its grant column), the grants table and the registration window exist and answer, i.e.
+// its grant column), the grants table, the registration window, the used confirmations and the operation tasks exist and answer, i.e.
 // `softure migrate` ran every file. It reads no rows.
 import { ok, type HealthCheck } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
@@ -11,5 +11,7 @@ export const checkAccessTokensTable: HealthCheck = async (context) => {
   await db.execute(sql`select grant_id from mcp.access_tokens limit 0`);
   await db.execute(sql`select 1 from mcp.oauth_grants join mcp.oauth_clients on oauth_clients.id = oauth_grants.client_id limit 0`);
   await db.execute(sql`select open_until from mcp.oauth_registration_window limit 0`);
+  await db.execute(sql`select expires_at from mcp.used_confirmations limit 0`);
+  await db.execute(sql`select expires_at from mcp.operation_tasks limit 0`);
   return ok();
 };

package/src/server/index.ts

@@ -11,6 +11,21 @@ export {
   type McpServerFactory,
 } from "./endpoint.js";
 export { actionTool, toFormData, type ActionToolOptions, type FormActionHandler } from "./action-tool.js";
+export {
+  CONFIRMATION_FIELD,
+  CONFIRMATION_SECRET_ENV,
+  confirmationInput,
+  DEFAULT_CONFIRMATION_TTL_SECONDS,
+  MIN_CONFIRMATION_SECRET_LENGTH,
+  pruneUsedConfirmations,
+  toCanonicalJson,
+  withConfirmation,
+  type ConfirmationErrorCode,
+  type ConfirmationEstimate,
+  type ConfirmationRequest,
+  type ConfirmedToolArgs,
+  type WithConfirmationOptions,
+} from "./confirmation.js";
 export { createMcpAccessContext } from "./context.js";
 export { isWritingEnabled } from "./writes-switch.js";
 export { checkAccessTokensTable } from "./health.js";
@@ -79,7 +94,7 @@ export type { OAuthClientRow, OAuthTokenEndpointAuthMethod } from "../schema.js"
 export { describeRedirectUri, isAllowedRedirectUri, MAX_CLIENT_NAME_LENGTH, parseClientRegistration, type ClientRegistrationResult, type RegistrationError } from "./oauth-validation.js";
 export { getCodeChallenge, isPkceVerifierValid, isValidCodeChallenge, PKCE_METHOD } from "./pkce.js";
 export { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl, type McpAccessRoutes } from "./options.js";
-export { pruneMcpAccess, type PrunedMcpAccessRecords } from "./prune.js";
+export { pruneMcpAccess, pruneOperationTasks, type PrunedMcpAccessRecords } from "./prune.js";
 export {
   deleteMcpAccessUserData,
   exportMcpAccessUserData,
@@ -103,6 +118,21 @@ export {
   type RevokeAccessTokenInput,
   type VerifiedAccessToken,
 } from "./tokens.js";
+export {
+  API_RATE_LIMIT_BUCKET,
+  API_TOKEN_RATE_LIMIT_BUCKET,
+  apiTokenErrorResponse,
+  getApiTokenOptions,
+  isApiTokenShape,
+  issueApiToken,
+  requireApiToken,
+  verifyApiToken,
+  type IssueApiTokenInput,
+  type IssueApiTokenResult,
+  type IssuedApiToken,
+  type RequireApiTokenOptions,
+  type VerifiedApiToken,
+} from "./api-tokens.js";
 export { createMcpServerFactory, type McpServerFactoryOptions } from "./server-factory.js";
 export {
   registerServerInfoTool,
@@ -113,7 +143,7 @@ export {
   type ServerInfoAnswer,
   type ServerInfoToolOptions,
 } from "./server-info.js";
-export { toStrictToolInput, withStrictToolInput, type StrictToolInputMessages, type StrictToolInputOptions } from "./strict-input.js";
+export { toStrictToolInput, withStrictToolInput, type RenamedFields, type StrictToolInputMessages, type StrictToolInputOptions } from "./strict-input.js";
 export {
   DEFAULT_TOOL_LIST_RELEASE,
   describeToolList,

package/src/server/privacy.ts

@@ -4,12 +4,16 @@
 import { ok, type ModuleContext, type Ok, type PrivacyContributor } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 import { and, asc, eq, isNull } from "drizzle-orm";
-import { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants } from "../schema.js";
+import { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants, operationTasks } from "../schema.js";
 
 /** What mcp-access holds about one user, as it appears in their export. */
 export interface McpAccessUserData {
   readonly accessTokens: readonly {
     readonly name: string;
+    /** `mcp` for an assistant, `api` for the app's HTTP routes. */
+    readonly kind: "mcp" | "api";
+    /** The app scopes of an API token; empty for an MCP token. */
+    readonly scopes: readonly string[];
     readonly canWrite: boolean;
     readonly createdAt: Date;
     readonly expiresAt: Date;
@@ -33,6 +37,8 @@ export async function exportMcpAccessUserData(context: ModuleContext, userId: st
   const tokens = await db
     .select({
       name: accessTokens.name,
+      kind: accessTokens.kind,
+      scopes: accessTokens.scopes,
       canWrite: accessTokens.canWrite,
       createdAt: accessTokens.createdAt,
       expiresAt: accessTokens.expiresAt,
@@ -57,6 +63,8 @@ export async function deleteMcpAccessUserData(context: ModuleContext, userId: st
   // A grant's access tokens go with it by cascade; the next line takes the hand-issued ones.
   await db.delete(oauthGrants).where(eq(oauthGrants.userId, userId));
   await db.delete(accessTokens).where(eq(accessTokens.userId, userId));
+  // MCP tasks hold a job id and dates only, so the export leaves them out; they go with the account.
+  await db.delete(operationTasks).where(eq(operationTasks.userId, userId));
   return ok();
 }