@provos/ironcurtain 0.4.0 → 0.4.1

package/dist/trusted-process/mcp-proxy-server.d.ts

@@ -25,4 +25,114 @@
  *   AUTO_APPROVE_API_KEY   -- (optional) API key for the auto-approve model's provider
  *   AUTO_APPROVE_LLM_LOG_PATH -- (optional) path to JSONL file for auto-approve LLM logging
  */
-export {};
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+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 McpRoot } from './mcp-client-manager.js';
+import { CallCircuitBreaker } from './call-circuit-breaker.js';
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { MCPServerConfig, SandboxAvailabilityPolicy } from '../config/types.js';
+export interface ProxiedTool {
+    serverName: string;
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ClientState {
+    client: Client;
+    roots: McpRoot[];
+    rootsRefreshed?: () => void;
+}
+/** Parsed environment configuration for the proxy server. */
+export interface ProxyEnvConfig {
+    auditLogPath: string;
+    serversConfig: Record<string, MCPServerConfig>;
+    generatedDir: string;
+    protectedPaths: string[];
+    sessionLogPath: string | undefined;
+    allowedDirectory: string | undefined;
+    containerWorkspaceDir: string | undefined;
+    escalationDir: string | undefined;
+    serverCredentials: Record<string, string>;
+    sandboxPolicy: SandboxAvailabilityPolicy;
+}
+/** Result of sandbox availability validation. */
+export interface SandboxValidationResult {
+    sandboxAvailable: boolean;
+}
+/** MCP tool call response shape returned by handleCallTool. */
+export interface ToolCallResponse {
+    content: unknown;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** 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;
+    containerWorkspaceDir: string | undefined;
+    escalationDir: string | undefined;
+    autoApproveModel: LanguageModelV3 | null;
+}
+/**
+ * Reads and validates proxy environment variables.
+ * Returns a typed config object or calls process.exit(1) on missing required vars.
+ */
+export declare function parseProxyEnvConfig(): ProxyEnvConfig;
+/**
+ * Validates sandbox availability against the configured policy.
+ * Logs warnings to session log. Throws when enforce mode is active
+ * but sandboxing is unavailable.
+ */
+export declare function validateSandboxAvailability(sandboxPolicy: SandboxAvailabilityPolicy, sessionLogPath: string | undefined, platform: string): SandboxValidationResult;
+/**
+ * Resolves per-server sandbox configurations and writes srt settings
+ * files for sandboxed servers. Returns the config map and the temp
+ * settings directory path.
+ */
+export declare function resolveServerSandboxConfigs(serversConfig: Record<string, MCPServerConfig>, allowedDirectory: string | undefined, sandboxAvailable: boolean, sandboxPolicy: SandboxAvailabilityPolicy): {
+    resolvedSandboxConfigs: Map<string, ResolvedSandboxConfig>;
+    settingsDir: string;
+    serverCwdPaths: Map<string, string>;
+};
+/** Builds a lookup map from tool name to ProxiedTool for routing. */
+export declare function buildToolMap(allTools: ProxiedTool[]): Map<string, ProxiedTool>;
+/**
+ * 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;
+}): AuditEntry;
+/**
+ * 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 extracted from the CallTool handler
+ * for independent unit testing.
+ */
+export declare function handleCallTool(toolName: string, rawArgs: Record<string, unknown>, deps: CallToolDeps): Promise<ToolCallResponse>;
+/**
+ * Selects and validates the proxy transport based on environment variables.
+ * Returns 'tcp', 'uds', or 'stdio' along with the transport options.
+ */
+export declare function selectTransportConfig(): {
+    kind: 'tcp';
+    port: number;
+    portFilePath: string | undefined;
+} | {
+    kind: 'uds';
+    socketPath: string;
+} | {
+    kind: 'stdio';
+};