@softure-ai/mcp-access 0.2.9 → 0.4.0

package/dist/schema.js

@@ -1,8 +1,8 @@
 // Drizzle view of the module's tables (migrations/0001_create_access_tokens.sql,
-// 0002_create_oauth_grants.sql and 0003_create_oauth_registration_window.sql). The migrations are the
-// source of truth; this file only types the queries.
+// 0002_create_oauth_grants.sql, 0003_create_oauth_registration_window.sql, 0004_create_used_confirmations.sql,
+// 0005_add_api_tokens.sql and 0006_create_operation_tasks.sql). The migrations are the source of truth; this file only types the queries.
 import { users } from "@softure-ai/auth";
-import { boolean, jsonb, pgSchema, smallint, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { bigint, boolean, jsonb, pgSchema, smallint, text, timestamp, uuid } from "drizzle-orm/pg-core";
 export const mcpSchema = pgSchema("mcp");
 export const oauthClients = mcpSchema.table("oauth_clients", {
     id: uuid("id").primaryKey().defaultRandom(),
@@ -56,10 +56,28 @@ export const accessTokens = mcpSchema.table("access_tokens", {
     expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
     lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
     grantId: uuid("grant_id").references(() => oauthGrants.id, { onDelete: "cascade" }),
+    /** `mcp` opens the MCP endpoint; `api` passes `requireApiToken` with its `scopes` (migration 0005). */
+    kind: text("kind").$type().notNull().default("mcp"),
+    scopes: text("scopes").array().$type().notNull().default([]),
 });
 export const oauthRegistrationWindow = mcpSchema.table("oauth_registration_window", {
     id: smallint("id").primaryKey().default(1),
     openedAt: timestamp("opened_at", { withTimezone: true }).notNull(),
     openUntil: timestamp("open_until", { withTimezone: true }).notNull(),
 });
+export const usedConfirmations = mcpSchema.table("used_confirmations", {
+    tokenHash: text("token_hash").primaryKey(),
+    usedAt: timestamp("used_at", { withTimezone: true }).notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+});
+/** MCP Tasks over long operations (#977): a random task id per account and job, until `expiresAt`. */
+export const operationTasks = mcpSchema.table("operation_tasks", {
+    taskId: text("task_id").primaryKey(),
+    userId: uuid("user_id")
+        .notNull()
+        .references(() => users.id, { onDelete: "cascade" }),
+    jobId: bigint("job_id", { mode: "bigint" }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+});
 //# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/server/api-tokens.d.ts

@@ -0,0 +1,64 @@
+import { type Err, type Ok } from "@softure-ai/core";
+import type { ApiTokenIdentity, ApiTokenRefusal } from "../contract.js";
+import { type ApiTokenOptions } from "../options.js";
+import { type McpAccessContext } from "./tokens.js";
+/** The bucket counted per client address before the token is looked up. */
+export declare const API_RATE_LIMIT_BUCKET = "api";
+/** The bucket counted per verified token. */
+export declare const API_TOKEN_RATE_LIMIT_BUCKET = "api-token";
+/** The app's API token settings, or null while `apiTokens` is unset. */
+export declare function getApiTokenOptions(ctx: Pick<McpAccessContext, "config">): ApiTokenOptions | null;
+/** Whether a presented value has the shape of one of the app's API tokens: its prefix and 32 base64url bytes. */
+export declare function isApiTokenShape(options: ApiTokenOptions, token: string): boolean;
+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 declare function issueApiToken(ctx: McpAccessContext, input: IssueApiTokenInput): Promise<IssueApiTokenResult>;
+/** 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 declare function verifyApiToken(ctx: McpAccessContext, token: string): Promise<VerifiedApiToken | null>;
+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 declare function requireApiToken(ctx: McpAccessContext, request: Request, { scopes: required }: RequireApiTokenOptions): Promise<Ok<ApiTokenIdentity> | ApiTokenRefusal>;
+/**
+ * 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 declare function apiTokenErrorResponse(refusal: ApiTokenRefusal): Response;
+//# sourceMappingURL=api-tokens.d.ts.map

package/dist/server/api-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-tokens.d.ts","sourceRoot":"","sources":["../../src/server/api-tokens.ts"],"names":[],"mappings":"AAKA,OAAO,EAAqC,KAAK,GAAG,EAAE,KAAK,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAGxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAA8B,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAAgD,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGlG,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAC3C,6CAA6C;AAC7C,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAKvD,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,GAAG,eAAe,GAAG,IAAI,CAEhG;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAGhF;AAWD,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,mBAAmB,GAC3B,EAAE,CAAC,cAAc,CAAC,GAClB,GAAG,CACC,0BAA0B,GAC1B,0BAA0B,GAC1B,gCAAgC,GAChC,yBAAyB,GACzB,2BAA2B,GAC3B,0BAA0B,CAC7B,CAAC;AAEN;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiBlH;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAE3G;AAiBD,MAAM,WAAW,sBAAsB;IACrC,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,OAAO,EAChB,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,sBAAsB,GAC3C,OAAO,CAAC,EAAE,CAAC,gBAAgB,CAAC,GAAG,eAAe,CAAC,CAmCjD;AAYD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAaxE"}

package/dist/server/api-tokens.js

@@ -0,0 +1,176 @@
+// 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 } from "@softure-ai/core";
+import { randomBytes } from "node:crypto";
+import { consumeRateLimit, identifyClient } from "@softure-ai/security/server";
+import { MAX_PRESENTED_TOKEN_LENGTH } from "../options.js";
+import { getMcpAccessOptions } from "./options.js";
+import { findValidToken, hashAccessToken, insertToken } 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) {
+    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, token) {
+    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) {
+    const random = randomBytes(32).toString("base64url");
+    return { secret: `${prefix}${random}`, secretHash: hashAccessToken(random) };
+}
+/**
+ * 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, input) {
+    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 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, token) {
+    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, token) {
+    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,
+    };
+}
+/**
+ * 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, request, { scopes: required }) {
+    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 = {
+    "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) {
+    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, required) {
+    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) {
+    const options = getModule(ctx.config, "security")?.options;
+    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 })`);
+        }
+    }
+}
+//# sourceMappingURL=api-tokens.js.map

package/dist/server/api-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-tokens.js","sourceRoot":"","sources":["../../src/server/api-tokens.ts"],"names":[],"mappings":"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"}

package/dist/server/confirmation.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import type { McpServerIdentity } from "../contract.js";
+import type { McpAccessContext } from "./tokens.js";
+import { 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 declare const CONFIRMATION_FIELD = "confirmation";
+/** Signs and verifies confirmation tokens. */
+export declare const CONFIRMATION_SECRET_ENV = "MCP_CONFIRMATION_SECRET";
+/** A shorter secret counts as missing: a guessable key lets anyone mint a confirmation. */
+export declare const MIN_CONFIRMATION_SECRET_LENGTH = 32;
+/** How long a confirmation stays valid by default: fifteen minutes. */
+export declare const DEFAULT_CONFIRMATION_TTL_SECONDS = 900;
+/** The `confirmation` field for the tool's input schema, so a strict server lists and accepts it. */
+export declare const confirmationInput: z.ZodOptional<z.ZodString>;
+/** 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 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 declare function withConfirmation<Args extends Readonly<Record<string, unknown>>, Estimate extends ConfirmationEstimate>(handler: (args: Args) => unknown, options: WithConfirmationOptions<Args, Estimate>): (args: ConfirmedToolArgs<Args>) => Promise<CallToolResult>;
+/** Deletes the used tokens past their expiry; a daily job through `pruneMcpAccess`. */
+export declare function pruneUsedConfirmations(ctx: McpAccessContext): Promise<number>;
+/** JSON with every object's keys sorted and `undefined` fields left out, so equal arguments give equal text. */
+export declare function toCanonicalJson(value: unknown): string;
+//# sourceMappingURL=confirmation.d.ts.map

package/dist/server/confirmation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation.d.ts","sourceRoot":"","sources":["../../src/server/confirmation.ts"],"names":[],"mappings":"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"}

package/dist/server/confirmation.js

@@ -0,0 +1,220 @@
+// 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 { en } from "../messages/en.js";
+import { usedConfirmations } from "../schema.js";
+import { getMcpAccessMessages } from "./options.js";
+import { withToolErrors } from "./tools.js";
+/** 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);
+/**
+ * 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(handler, options) {
+    return async (input) => {
+        const { [CONFIRMATION_FIELD]: confirmation, ...rest } = input;
+        const args = rest;
+        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() {
+                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) {
+    const removed = await ctx.db
+        .delete(usedConfirmations)
+        .where(lte(usedConfirmations.expiresAt, ctx.clock.now()))
+        .returning({ tokenHash: usedConfirmations.tokenHash });
+    return removed.length;
+}
+function readConfirmationSecret(options) {
+    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(options, args) {
+    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(options, args, estimate, secret) {
+    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 = {
+        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 }),
+    };
+}
+/**
+ * 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(options, check) {
+    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, secret) {
+    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;
+    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, secret) {
+    return createHmac("sha256", secret).update(`${SIGNED_PREFIX}${encoded}`).digest("base64url");
+}
+function digestArguments(args) {
+    return createHash("sha256").update(toCanonicalJson(args)).digest("base64url");
+}
+function digestCaller(identity) {
+    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) {
+    return JSON.stringify(sortKeys(value)) ?? "null";
+}
+function sortKeys(value) {
+    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) {
+    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,
+    };
+}
+//# sourceMappingURL=confirmation.js.map