@provos/ironcurtain 0.1.0

package/dist/trusted-process/policy-types.d.ts

@@ -0,0 +1,6 @@
+import type { PolicyDecisionStatus } from '../types/mcp.js';
+export interface EvaluationResult {
+    decision: PolicyDecisionStatus;
+    rule: string;
+    reason: string;
+}

package/dist/trusted-process/policy-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=policy-types.js.map

package/dist/trusted-process/policy-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-types.js","sourceRoot":"","sources":["../../src/trusted-process/policy-types.ts"],"names":[],"mappings":""}

package/dist/trusted-process/sandbox-integration.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Sandbox Integration -- Wraps MCP server processes in OS-level sandboxes.
+ *
+ * Each sandboxed server is spawned via a separate `srt` CLI process with
+ * its own settings file, giving each server independent sandbox infrastructure
+ * (filesystem restrictions, network proxy, and process isolation).
+ *
+ * The proxy process itself never calls SandboxManager.initialize() -- it
+ * only uses the stateless isSupportedPlatform() and checkDependencies()
+ * for the availability check.
+ */
+import type { MCPServerConfig, SandboxAvailabilityPolicy } from '../config/types.js';
+/**
+ * Result of resolving a server's sandbox configuration.
+ * Discriminated union: sandboxed servers carry the resolved config,
+ * unsandboxed servers carry the reason they were exempted.
+ */
+export type ResolvedSandboxConfig = {
+    readonly sandboxed: true;
+    readonly config: ResolvedSandboxParams;
+} | {
+    readonly sandboxed: false;
+    readonly reason: 'opt-out' | 'platform-unavailable';
+};
+/**
+ * Fully resolved sandbox parameters ready for srt settings.
+ * All relative paths have been resolved to absolute paths.
+ * The session sandbox directory has been injected into allowWrite.
+ */
+export interface ResolvedSandboxParams {
+    readonly allowWrite: readonly string[];
+    readonly denyRead: readonly string[];
+    readonly denyWrite: readonly string[];
+    readonly network: false | {
+        readonly allowedDomains: readonly string[];
+        readonly deniedDomains: readonly string[];
+    };
+}
+/** Result of checking sandbox-runtime availability. */
+export interface SandboxAvailabilityResult {
+    readonly platformSupported: boolean;
+    readonly errors: string[];
+    readonly warnings: string[];
+}
+/**
+ * Checks sandbox dependencies and returns a structured result.
+ *
+ * Wraps SandboxManager.isSupportedPlatform() and checkDependencies()
+ * into a single call. Does NOT throw -- callers inspect the result and
+ * decide based on sandboxPolicy.
+ */
+export declare function checkSandboxAvailability(): SandboxAvailabilityResult;
+/**
+ * Resolves the effective sandbox configuration for a single MCP server.
+ *
+ * Applies defaults when `sandbox` is omitted, injects the session
+ * sandbox directory into allowWrite, and resolves relative paths.
+ */
+export declare function resolveSandboxConfig(serverConfig: MCPServerConfig, sessionSandboxDir: string, platformAvailable: boolean, policy: SandboxAvailabilityPolicy): ResolvedSandboxConfig;
+/**
+ * Writes a per-server srt settings JSON file.
+ *
+ * Each sandboxed server gets its own settings file at
+ * `{settingsDir}/{serverName}.srt-settings.json`.
+ *
+ * Returns the absolute path to the written file.
+ */
+export declare function writeServerSettings(serverName: string, config: ResolvedSandboxParams, settingsDir: string): string;
+/**
+ * Transforms a server's spawn parameters (command + args) into a
+ * sandbox-wrapped command suitable for StdioClientTransport.
+ *
+ * For sandboxed servers: returns `{ command: 'srt', args: ['-s', settingsPath, '-c', escapedCmd] }`.
+ * For unsandboxed servers: returns the original command/args unchanged.
+ */
+export declare function wrapServerCommand(serverName: string, command: string, args: readonly string[], sandboxConfig: ResolvedSandboxConfig, settingsDir: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * Cleans up per-server settings files created by writeServerSettings().
+ * Called during proxy shutdown. Safe to call even if no files were written.
+ */
+export declare function cleanupSettingsFiles(settingsDir: string): void;
+/**
+ * Annotates an MCP error response when it looks like a sandbox block.
+ *
+ * When a sandboxed server returns an error matching common sandbox-blocked
+ * patterns (EPERM, EACCES, etc.) and the policy engine had allowed the call,
+ * this prefixes the error with [SANDBOX BLOCKED] to signal OS containment.
+ */
+export declare function annotateSandboxViolation(errorMessage: string, serverSandboxed: boolean): string;

package/dist/trusted-process/sandbox-integration.js

@@ -0,0 +1,184 @@
+/**
+ * Sandbox Integration -- Wraps MCP server processes in OS-level sandboxes.
+ *
+ * Each sandboxed server is spawned via a separate `srt` CLI process with
+ * its own settings file, giving each server independent sandbox infrastructure
+ * (filesystem restrictions, network proxy, and process isolation).
+ *
+ * The proxy process itself never calls SandboxManager.initialize() -- it
+ * only uses the stateless isSupportedPlatform() and checkDependencies()
+ * for the availability check.
+ */
+import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
+import { writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join, resolve, dirname, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { quote } from 'shell-quote';
+// ── Constants ──────────────────────────────────────────────────────────────
+/** Sensitive directories blocked from reads by default. */
+const DEFAULT_DENY_READ = ['~/.ssh', '~/.gnupg', '~/.aws'];
+/**
+ * Resolve the absolute path to the `srt` binary in node_modules.
+ * Walks up from the package root to handle npm's dependency hoisting,
+ * where bins may be in a parent node_modules/.bin/ directory.
+ */
+const __sandboxDirname = dirname(fileURLToPath(import.meta.url));
+const SRT_BIN = resolveNodeModulesBin('srt', resolve(__sandboxDirname, '..', '..'));
+/** Pattern matching common OS-level permission errors from sandbox containment. */
+const SANDBOX_BLOCK_PATTERN = /EACCES|EPERM|Operation not permitted|Permission denied|read-only file system/i;
+// ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Checks sandbox dependencies and returns a structured result.
+ *
+ * Wraps SandboxManager.isSupportedPlatform() and checkDependencies()
+ * into a single call. Does NOT throw -- callers inspect the result and
+ * decide based on sandboxPolicy.
+ */
+export function checkSandboxAvailability() {
+    const platformSupported = SandboxManager.isSupportedPlatform();
+    if (!platformSupported) {
+        return { platformSupported, errors: [], warnings: [] };
+    }
+    const { errors, warnings } = SandboxManager.checkDependencies();
+    return { platformSupported, errors, warnings };
+}
+/**
+ * Resolves the effective sandbox configuration for a single MCP server.
+ *
+ * Applies defaults when `sandbox` is omitted, injects the session
+ * sandbox directory into allowWrite, and resolves relative paths.
+ */
+export function resolveSandboxConfig(serverConfig, sessionSandboxDir, platformAvailable, policy) {
+    if (serverConfig.sandbox === false) {
+        return { sandboxed: false, reason: 'opt-out' };
+    }
+    if (!platformAvailable) {
+        if (policy === 'enforce') {
+            throw new Error('[sandbox] Server requires sandboxing but platform is unavailable ' +
+                'and sandboxPolicy is "enforce".');
+        }
+        return { sandboxed: false, reason: 'platform-unavailable' };
+    }
+    const sandboxConfig = serverConfig.sandbox ?? {};
+    const fsConfig = sandboxConfig.filesystem ?? {};
+    const networkConfig = sandboxConfig.network;
+    const allowWrite = buildAllowWrite(sessionSandboxDir, fsConfig.allowWrite ?? []);
+    const denyRead = fsConfig.denyRead ?? DEFAULT_DENY_READ;
+    const denyWrite = fsConfig.denyWrite ?? [];
+    const network = resolveNetworkConfig(networkConfig);
+    return {
+        sandboxed: true,
+        config: { allowWrite, denyRead, denyWrite, network },
+    };
+}
+/**
+ * Writes a per-server srt settings JSON file.
+ *
+ * Each sandboxed server gets its own settings file at
+ * `{settingsDir}/{serverName}.srt-settings.json`.
+ *
+ * Returns the absolute path to the written file.
+ */
+export function writeServerSettings(serverName, config, settingsDir) {
+    const settingsPath = join(settingsDir, `${serverName}.srt-settings.json`);
+    const network = config.network === false
+        ? { allowedDomains: [], deniedDomains: [] }
+        : { allowedDomains: config.network.allowedDomains, deniedDomains: config.network.deniedDomains };
+    const settings = {
+        network,
+        filesystem: {
+            denyRead: config.denyRead,
+            allowWrite: config.allowWrite,
+            denyWrite: config.denyWrite,
+        },
+    };
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    return settingsPath;
+}
+/**
+ * Transforms a server's spawn parameters (command + args) into a
+ * sandbox-wrapped command suitable for StdioClientTransport.
+ *
+ * For sandboxed servers: returns `{ command: 'srt', args: ['-s', settingsPath, '-c', escapedCmd] }`.
+ * For unsandboxed servers: returns the original command/args unchanged.
+ */
+export function wrapServerCommand(serverName, command, args, sandboxConfig, settingsDir) {
+    if (!sandboxConfig.sandboxed) {
+        return { command, args: [...args] };
+    }
+    const settingsPath = join(settingsDir, `${serverName}.srt-settings.json`);
+    // Resolve relative paths in args to absolute so the command works when
+    // the proxy sets cwd to the sandbox directory.
+    const resolvedArgs = args.map(a => (!isAbsolute(a) && !a.startsWith('-') ? resolve(a) : a));
+    const cmdString = quote([command, ...resolvedArgs]);
+    return {
+        command: SRT_BIN,
+        args: ['-s', settingsPath, '-c', cmdString],
+    };
+}
+/**
+ * Cleans up per-server settings files created by writeServerSettings().
+ * Called during proxy shutdown. Safe to call even if no files were written.
+ */
+export function cleanupSettingsFiles(settingsDir) {
+    try {
+        rmSync(settingsDir, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort cleanup; OS temp rotation handles leftovers
+    }
+}
+/**
+ * Annotates an MCP error response when it looks like a sandbox block.
+ *
+ * When a sandboxed server returns an error matching common sandbox-blocked
+ * patterns (EPERM, EACCES, etc.) and the policy engine had allowed the call,
+ * this prefixes the error with [SANDBOX BLOCKED] to signal OS containment.
+ */
+export function annotateSandboxViolation(errorMessage, serverSandboxed) {
+    if (!serverSandboxed)
+        return errorMessage;
+    if (!SANDBOX_BLOCK_PATTERN.test(errorMessage))
+        return errorMessage;
+    return `[SANDBOX BLOCKED] ${errorMessage}`;
+}
+// ── Internal helpers ───────────────────────────────────────────────────────
+/**
+ * Builds the allowWrite list with the session sandbox dir always included.
+ * Relative paths are resolved against the session sandbox directory.
+ */
+function buildAllowWrite(sessionSandboxDir, additionalPaths) {
+    const resolved = additionalPaths.map(p => isAbsolute(p) ? p : resolve(sessionSandboxDir, p));
+    return [sessionSandboxDir, ...resolved];
+}
+/**
+ * Resolves network config to the canonical form.
+ * `undefined` and `false` both mean no network access.
+ */
+function resolveNetworkConfig(config) {
+    if (!config)
+        return false;
+    return {
+        allowedDomains: config.allowedDomains,
+        deniedDomains: config.deniedDomains ?? [],
+    };
+}
+/**
+ * Resolves a binary name in node_modules/.bin/ by walking up from startDir.
+ * Handles npm's dependency hoisting where bins may live in a parent node_modules/.bin/.
+ */
+function resolveNodeModulesBin(binName, startDir) {
+    let dir = startDir;
+    for (;;) {
+        const candidate = join(dir, 'node_modules', '.bin', binName);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: assume it's directly under the package root
+    return join(startDir, 'node_modules', '.bin', binName);
+}
+//# sourceMappingURL=sandbox-integration.js.map

package/dist/trusted-process/sandbox-integration.js.map

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

package/dist/types/argument-roles.d.ts

@@ -0,0 +1,112 @@
+/**
+ * ArgumentRole Registry -- Central definition of argument role semantics.
+ *
+ * Each role is paired with metadata describing its security semantics
+ * and a normalizer function for canonicalizing argument values. This
+ * eliminates scattered hardcoded role strings and enables annotation-driven
+ * normalization instead of fragile heuristics.
+ *
+ * Roles are organized into categories that determine which structural
+ * invariant applies in the policy engine:
+ *   - path: filesystem path containment checks
+ *   - url: domain allowlist checks
+ *   - opaque: no structural invariant (semantic meaning only)
+ */
+export type RoleCategory = 'path' | 'url' | 'opaque';
+export type ArgumentRole = 'read-path' | 'write-path' | 'delete-path' | 'write-history' | 'delete-history' | 'fetch-url' | 'git-remote-url' | 'branch-name' | 'commit-message' | 'none';
+export interface RoleDefinition {
+    readonly description: string;
+    readonly isResourceIdentifier: boolean;
+    readonly category: RoleCategory;
+    readonly normalize: (value: string) => string;
+    /** Extract the policy-relevant value (e.g., domain from URL). */
+    readonly prepareForPolicy?: (value: string) => string;
+    /**
+     * Context-aware resolution for values that need sibling arguments.
+     * E.g., resolving named git remote "origin" to its URL using the
+     * `path` argument from the same tool call.
+     */
+    readonly resolveForPolicy?: (value: string, allArgs: Record<string, unknown>) => string;
+    /**
+     * Guidance for the LLM annotation prompt. Built into the prompt
+     * dynamically from the registry -- no manual prompt maintenance.
+     */
+    readonly annotationGuidance: string;
+    /**
+     * When set, this role is only relevant for the named MCP servers.
+     * Roles without serverNames are universal (included for all servers).
+     */
+    readonly serverNames?: readonly string[];
+}
+/** Expands a leading `~` or `~/` to the current user's home directory. */
+export declare function expandTilde(filePath: string): string;
+/**
+ * Resolves a filesystem path to its canonical real path, following symlinks.
+ *
+ * Tries three strategies in order:
+ * 1. `realpathSync(path)` — works for existing paths, follows all symlinks
+ * 2. `realpathSync(parent) + basename` — works for new files in existing dirs
+ * 3. `path.resolve(path)` — fallback for entirely new paths
+ *
+ * This is security-critical: without symlink resolution, a symlinked
+ * directory inside the sandbox could escape containment checks.
+ */
+export declare function resolveRealPath(filePath: string): string;
+/** Tilde expansion + symlink resolution to produce a canonical real path. */
+export declare function normalizePath(value: string): string;
+/** Normalizes an HTTP(S) URL to a canonical form. Returns value as-is on parse failure. */
+export declare function normalizeUrl(value: string): string;
+/** Extracts the hostname from an HTTP(S) URL. Returns value as-is on parse failure. */
+export declare function extractDomain(value: string): string;
+/** Normalizes a git URL (HTTP or SSH format). SSH URLs are returned as-is. */
+export declare function normalizeGitUrl(value: string): string;
+/** Extracts the domain from a git URL (HTTP or SSH format). */
+export declare function extractGitDomain(value: string): string;
+/**
+ * Resolves a git remote value to a URL for policy evaluation.
+ *
+ * If the value is already a URL (contains :// or matches SSH pattern),
+ * returns it as-is. Otherwise, treats it as a named remote and runs
+ * `git remote get-url <name>` in the repository directory (found via
+ * the `path` sibling argument).
+ *
+ * Uses execFileSync (not execSync) to avoid command injection --
+ * the value comes from agent-controlled tool call arguments.
+ *
+ * When resolution fails (repo doesn't exist, remote not found, git
+ * not installed), returns the original value. This causes the domain
+ * check to escalate (the value won't match any allowed domain),
+ * which is the correct behavior -- escalate when we can't verify.
+ */
+export declare function resolveGitRemote(value: string, allArgs: Record<string, unknown>): string;
+export declare const ARGUMENT_ROLE_REGISTRY: ReadonlyMap<ArgumentRole, RoleDefinition>;
+/** Returns the RoleDefinition for a role. Throws if not registered. */
+export declare function getRoleDefinition(role: ArgumentRole): RoleDefinition;
+/** Returns all roles where isResourceIdentifier is true. */
+export declare function getResourceRoles(): ArgumentRole[];
+/** Type guard: returns true if the value is a valid ArgumentRole string. */
+export declare function isArgumentRole(value: string): value is ArgumentRole;
+/** All role values as a tuple for z.enum() compatibility. */
+export declare function getArgumentRoleValues(): [ArgumentRole, ...ArgumentRole[]];
+/**
+ * Returns roles relevant to a specific MCP server.
+ * Universal roles (no serverNames) are always included.
+ * Server-specific roles are included only when the server matches.
+ */
+export declare function getRolesForServer(serverName: string): [ArgumentRole, RoleDefinition][];
+/** Returns all roles with the given category. */
+export declare function getRolesByCategory(category: RoleCategory): ArgumentRole[];
+/** Returns path-category roles only. Used by Phase 1a/1b structural invariants. */
+export declare function getPathRoles(): ArgumentRole[];
+/** Returns url-category roles only. Used by Phase 1c domain checks. */
+export declare function getUrlRoles(): ArgumentRole[];
+/**
+ * Path roles that Phase 1b sandbox containment is allowed to auto-resolve.
+ *
+ * Basic filesystem operations (read, write, delete) are safe within the
+ * sandbox boundary. Higher-risk path roles like `write-history` and
+ * `delete-history` are NOT sandbox-safe: even when the repo path is inside
+ * the sandbox, these operations require Phase 2 policy evaluation (and
+ * typically human approval) because they can destroy git history.
+ */
+export declare const SANDBOX_SAFE_PATH_ROLES: ReadonlySet<ArgumentRole>;