@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/trusted-process/tool-call-pipeline.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Tool Call Pipeline -- The core security evaluation logic.
+ *
+ * Owns the full tool-call policy pipeline: argument validation,
+ * annotation-driven normalization, policy evaluation, escalation
+ * (file-IPC and in-process), auto-approval, circuit breaking,
+ * whitelist matching, roots expansion, dispatch, and audit logging.
+ */
+import { PolicyEngine } from './policy-engine.js';
+import { AuditLog } from './audit-log.js';
+import { type ResolvedSandboxConfig } from './sandbox-integration.js';
+import type { ToolCallRequest, PolicyDecision } from '../types/mcp.js';
+import type { AuditEntry } from '../types/audit.js';
+import { type ClientState } from './mcp-client-manager.js';
+import { CallCircuitBreaker } from './call-circuit-breaker.js';
+import { type UserContext } from './auto-approver.js';
+import { type ServerContextMap } from './server-context.js';
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+import { type ApprovalWhitelist, type WhitelistCandidateIpc } from './approval-whitelist.js';
+import { type ControlApiClient } from '../docker/proxy-tools.js';
+export interface ProxiedTool {
+    serverName: string;
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+/** Re-exported from `mcp-client-manager.ts` for call-sites that import it from here. */
+export type { ClientState } from './mcp-client-manager.js';
+/**
+ * Delay before retrying a tool call that returned "access denied" immediately
+ * after roots expansion. The filesystem server needs time to async-validate
+ * (fs.realpath, fs.stat) the new roots after receiving the rootsListChanged
+ * notification. Exported for test access.
+ */
+export declare const ROOTS_RACE_RETRY_DELAY_MS = 200;
+/**
+ * Returns true when a user context is safe to act on for auto-approval.
+ *
+ * For PTY sessions (isPtySession=true):
+ *   - source must be 'mux-trusted-input' (set by the trusted mux layer)
+ *   - timestamp must be present, valid, not in the future, and within
+ *     TRUSTED_INPUT_STALENESS_MS of `now`
+ *
+ * For non-PTY sessions:
+ *   - source is not checked (no mux layer in the path)
+ *   - a missing or invalid timestamp does not prevent trust; a valid stale
+ *     timestamp still prevents trust (belt-and-suspenders for future callers)
+ *
+ * @param context - The user context parsed from user-context.json
+ * @param isPtySession - Whether this is a PTY interactive session
+ * @param now - Current time in ms; defaults to Date.now() (injectable for tests)
+ */
+export declare function isUserContextTrusted(context: UserContext, isPtySession: boolean, now?: number): boolean;
+/** Extracts concatenated text from MCP content blocks. */
+export declare function extractTextFromContent(content: unknown): string | undefined;
+/**
+ * Validates tool call arguments against the tool's `inputSchema`.
+ * Returns `null` if valid, or an error message describing the first
+ * problem encountered.
+ *
+ * Checks performed (in order):
+ *   1. Unknown argument names — any key not declared in
+ *      `properties` fails with a listing of valid keys.
+ *   2. Primitive type mismatch — for each provided argument whose
+ *      schema has a `type` string, the JS value's JSON-Schema
+ *      primitive type must match. Does not recurse into object/array
+ *      element shapes.
+ *
+ * Skips validation in two cases:
+ *   - The schema has no `properties` object (nothing to check against).
+ *   - `additionalProperties` is truthy (explicit opt-out).
+ *
+ * NOTE: This is stricter than plain JSON Schema, which treats a
+ * missing `additionalProperties` as equivalent to `true`. Here we
+ * treat it as forbidding unknown keys so typos in tool arguments
+ * fail fast instead of silently passing through to the MCP server.
+ * Servers that genuinely accept extra keys must declare
+ * `additionalProperties: true` explicitly.
+ */
+export declare function validateToolArguments(args: Record<string, unknown>, inputSchema: Record<string, unknown>): string | null;
+/**
+ * Splits a coordinator tool key of the form `server__tool` into its
+ * component parts. Falls back to `('unknown', key)` when the key has
+ * no separator (e.g. a raw tool name passed from an unregistered
+ * caller). Used for audit-log attribution on unknown-tool rejections.
+ */
+export declare function splitToolKey(key: string): [server: string, tool: string];
+/** Builds a lookup map from tool name to ProxiedTool for routing. */
+export declare function buildToolMap(allTools: ProxiedTool[]): Map<string, ProxiedTool>;
+/**
+ * Asserts that no two tools share the same bare name across servers.
+ *
+ * The relay's `CallTool` handler (in `mcp-proxy-server.ts`) routes by
+ * bare tool name via `toolMap`, which is last-write-wins on
+ * collisions. When `SERVER_FILTER` is set, only one backend is loaded
+ * and the check is trivially satisfied; multi-backend modes (e.g. the
+ * pipeline's list resolver) must not load two servers that expose the
+ * same tool name, or calls would silently route to the wrong backend.
+ *
+ * Throws with a descriptive message listing each duplicate tool and
+ * the servers that exposed it. Safe in single-server mode: no work.
+ */
+export declare function assertUniqueToolNames(allTools: readonly ProxiedTool[]): void;
+/**
+ * Creates an audit entry and logs it. Extracted so the audit shape
+ * construction is testable independently.
+ */
+export declare function buildAuditEntry(request: ToolCallRequest, argsForTransport: Record<string, unknown>, policyDecision: PolicyDecision, result: AuditEntry['result'], durationMs: number, options: {
+    escalationResult?: 'approved' | 'denied';
+    sandboxed?: boolean;
+    autoApproved?: boolean;
+    whitelistApproved?: boolean;
+    whitelistPatternId?: string;
+    persona?: string;
+}): AuditEntry;
+/** MCP tool call response shape returned by handleCallTool. */
+export interface ToolCallResponse {
+    content: unknown;
+    isError?: boolean;
+    /**
+     * Internal-only: the realized PolicyDecision from this call. Not part
+     * of the MCP protocol; the field is present on the JS object but the
+     * MCP SDK serializes only `content` and `isError` over stdio.
+     * Used by the coordinator's `handleStructuredToolCall` to surface the
+     * full decision trace to in-process callers.
+     */
+    _policyDecision?: PolicyDecision;
+    [key: string]: unknown;
+}
+/**
+ * In-process escalation callback. When set on `CallToolDeps`, the
+ * coordinator-driven code path invokes this instead of the file-IPC
+ * `waitForEscalationDecision` flow.
+ *
+ * Callers must resolve to `'approved'` or `'denied'` and may optionally
+ * indicate a whitelist pattern to persist (`whitelistSelection`).
+ */
+export interface InProcessEscalation {
+    readonly decision: 'approved' | 'denied';
+    readonly whitelistSelection?: number;
+}
+export type InProcessEscalationFn = (request: ToolCallRequest, reason: string, context?: Readonly<Record<string, string>>, whitelistCandidates?: readonly WhitelistCandidateIpc[]) => Promise<InProcessEscalation>;
+export type EscalationWaitRunner = <T>(wait: () => Promise<T>) => Promise<T>;
+/** Dependencies injected into handleCallTool for testability. */
+export interface CallToolDeps {
+    toolMap: Map<string, ProxiedTool>;
+    policyEngine: PolicyEngine;
+    auditLog: AuditLog;
+    circuitBreaker: CallCircuitBreaker;
+    clientStates: Map<string, ClientState>;
+    resolvedSandboxConfigs: Map<string, ResolvedSandboxConfig>;
+    allowedDirectory: string | undefined;
+    escalationDir: string | undefined;
+    autoApproveModel: LanguageModelV3 | null;
+    serverContextMap: ServerContextMap;
+    /** Ephemeral approval whitelist for this session. */
+    whitelist: ApprovalWhitelist;
+    /** Control API client for virtual proxy tools. Only set in virtual-only mode. */
+    controlApiClient?: ControlApiClient | null;
+    /**
+     * Optional in-process escalation handler. When set, supersedes the
+     * file-IPC escalation path. Used by the coordinator when callers
+     * provide a direct callback (e.g., integration tests).
+     */
+    onEscalation?: InProcessEscalationFn;
+    /**
+     * Optional trusted-user message for auto-approval context. When set,
+     * bypasses the file-based `readUserContext` lookup and feeds this
+     * directly to the auto-approver. Used by the coordinator when the
+     * in-process caller knows the user's last message.
+     */
+    autoApproveUserMessage?: string;
+    /**
+     * Optional wrapper used by ToolCallCoordinator to release its call
+     * mutex while a policy escalation waits on auto-approval or a human.
+     * Direct pipeline callers omit this and keep legacy in-function
+     * behavior.
+     */
+    runEscalationWait?: EscalationWaitRunner;
+    /**
+     * Persona to stamp onto every audit entry emitted by this call.
+     * Supplied by the coordinator from its `currentPersona` field (set by
+     * `loadPolicy`). `undefined` for single-session modes that never call
+     * `loadPolicy`.
+     */
+    persona?: string;
+}
+/**
+ * Optional caller-provided request identity. Structured callers
+ * (e.g. `ToolCallCoordinator.handleStructuredToolCall`) have their
+ * own `requestId`/`timestamp` on the inbound request; passing them
+ * through here preserves correlation between caller-side tracing
+ * and the audit entries emitted by this pipeline.
+ *
+ * When omitted, `handleCallTool` synthesizes both fields internally
+ * (the low-level UTCP path has no externally-assigned request id).
+ */
+export interface RequestContext {
+    readonly requestId: string;
+    readonly timestamp: string;
+}
+/**
+ * Handles a single tool call request: policy evaluation, escalation,
+ * circuit breaker check, and forwarding to the real MCP server.
+ *
+ * This is the core security logic -- the single source of truth for
+ * the policy evaluation pipeline.
+ *
+ * @param requestContext - optional caller-provided requestId/timestamp
+ *        so structured callers keep correlation with audit entries.
+ *        When omitted, both are generated internally.
+ */
+export declare function handleCallTool(toolName: string, rawArgs: Record<string, unknown>, deps: CallToolDeps, requestContext?: RequestContext): Promise<ToolCallResponse>;