airlock-bot 0.2.18 → 0.2.20

package/dist/sandbox/index.js

@@ -0,0 +1,147 @@
+import { matches } from '../allowlist/pattern.js';
+import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
+function summarizeSandbox(config) {
+    const summary = [];
+    summary.push(config.network.allowed_domains.length === 0
+        ? 'network:none'
+        : `network:${config.network.allowed_domains.join(',')}`);
+    if (config.filesystem.allow_write.length > 0) {
+        summary.push(`write:${config.filesystem.allow_write.join(',')}`);
+    }
+    if (config.filesystem.allow_read && config.filesystem.allow_read.length > 0) {
+        summary.push(`read:${config.filesystem.allow_read.join(',')}`);
+    }
+    if (config.filesystem.deny_read.length > 0) {
+        summary.push(`deny-read:${config.filesystem.deny_read.join(',')}`);
+    }
+    return summary;
+}
+export function getSandboxDisplayInfo(agentConfig, toolName, resolved) {
+    if (!agentConfig.sandbox.enabled || !resolved)
+        return undefined;
+    const toolOverride = agentConfig.tool_overrides[toolName];
+    const presets = agentConfig.sandbox.presets ?? [];
+    const toolPresets = toolOverride?.sandbox_presets ?? [];
+    return {
+        enabled: true,
+        presets,
+        toolPresets,
+        summary: summarizeSandbox(resolved),
+        config: resolved,
+    };
+}
+/**
+ * Resolve the effective sandbox config for a tool call.
+ * Merges base agent sandbox config with the most specific matching override.
+ * Also checks tool_overrides for alias-specific sandbox config.
+ */
+export function resolveSandboxConfig(sandboxConfig, toolName, toolOverrideSandbox) {
+    const base = {
+        filesystem: { ...sandboxConfig.filesystem },
+        network: { ...sandboxConfig.network },
+    };
+    // Find matching overrides from sandbox.overrides, most specific wins
+    // (exact match > longer prefix > shorter prefix)
+    const matchingOverrides = Object.entries(sandboxConfig.overrides)
+        .filter(([pattern]) => matches(pattern, toolName))
+        .sort((a, b) => b[0].length - a[0].length); // longer patterns first
+    if (matchingOverrides.length > 0) {
+        mergeOverride(base, matchingOverrides[0][1]);
+    }
+    // Tool-specific sandbox from tool_overrides (alias) takes highest priority
+    if (toolOverrideSandbox) {
+        mergeOverride(base, toolOverrideSandbox);
+    }
+    return base;
+}
+function mergeOverride(base, override) {
+    if (override.filesystem) {
+        // allow_write replaces (the tool flavor defines its own restrictions)
+        if (override.filesystem.allow_write !== undefined) {
+            base.filesystem.allow_write = override.filesystem.allow_write;
+        }
+        // deny_read is additive
+        if (override.filesystem.deny_read !== undefined) {
+            base.filesystem.deny_read = [...base.filesystem.deny_read, ...override.filesystem.deny_read];
+        }
+        // deny_write is additive
+        if (override.filesystem.deny_write !== undefined) {
+            base.filesystem.deny_write = [
+                ...base.filesystem.deny_write,
+                ...override.filesystem.deny_write,
+            ];
+        }
+        // allow_read replaces
+        if (override.filesystem.allow_read !== undefined) {
+            base.filesystem.allow_read = override.filesystem.allow_read;
+        }
+    }
+    if (override.network) {
+        // allowed_domains replaces
+        if (override.network.allowed_domains !== undefined) {
+            base.network.allowed_domains = override.network.allowed_domains;
+        }
+        // denied_domains is additive
+        if (override.network.denied_domains !== undefined) {
+            base.network.denied_domains = [
+                ...base.network.denied_domains,
+                ...override.network.denied_domains,
+            ];
+        }
+    }
+}
+/**
+ * Convert a ResolvedSandboxConfig into a SandboxRuntimeConfig suitable for
+ * the @anthropic-ai/sandbox-runtime SandboxManager.
+ */
+export function toSandboxRuntimeConfig(config) {
+    return {
+        filesystem: {
+            allowWrite: config.filesystem.allow_write,
+            denyRead: config.filesystem.deny_read,
+            denyWrite: config.filesystem.deny_write,
+            ...(config.filesystem.allow_read ? { allowRead: config.filesystem.allow_read } : {}),
+        },
+        network: {
+            allowedDomains: config.network.allowed_domains,
+            deniedDomains: config.network.denied_domains,
+        },
+    };
+}
+async function ensureSandboxRuntime(config) {
+    if (typeof SandboxManager.isSupportedPlatform === 'function' &&
+        !SandboxManager.isSupportedPlatform()) {
+        throw new Error('Sandbox runtime is not supported on this platform');
+    }
+    const canInitialize = typeof SandboxManager.initialize === 'function';
+    const isEnabled = typeof SandboxManager.isSandboxingEnabled === 'function'
+        ? SandboxManager.isSandboxingEnabled()
+        : false;
+    if (canInitialize && !isEnabled) {
+        await SandboxManager.initialize(config);
+        return;
+    }
+    if (typeof SandboxManager.updateConfig === 'function') {
+        SandboxManager.updateConfig(config);
+    }
+    if (typeof SandboxManager.waitForNetworkInitialization === 'function') {
+        const ready = await SandboxManager.waitForNetworkInitialization();
+        if (!ready && canInitialize) {
+            await SandboxManager.initialize(config);
+        }
+        return;
+    }
+    if (canInitialize) {
+        await SandboxManager.initialize(config);
+    }
+}
+/**
+ * Wraps a shell command using the SandboxManager programmatic API.
+ * Returns the wrapped command string that includes sandbox restrictions.
+ */
+export async function wrapCommandWithSandbox(command, sandbox) {
+    const runtimeConfig = toSandboxRuntimeConfig(sandbox);
+    await ensureSandboxRuntime(runtimeConfig);
+    return SandboxManager.wrapWithSandbox(command, undefined, runtimeConfig);
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

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

package/dist/tools/exec.d.ts

@@ -1,5 +1,6 @@
 import type { AgentConfig } from '../config/schema.js';
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { type ResolvedSandboxConfig } from '../sandbox/index.js';
 export interface ExecResult {
     exit_code: number | null;
     stdout: string;
@@ -16,5 +17,5 @@ export declare function buildExecTool(): Tool;
  */
 export declare function containsShellInjection(command: string): boolean;
 export declare function evaluateExecCommand(command: string, agentConfig: AgentConfig): ExecDecision;
-export declare function executeExec(command: string, agentConfig: AgentConfig, cwd?: string, timeoutMs?: number): Promise<ExecResult>;
+export declare function executeExec(command: string, agentConfig: AgentConfig, cwd?: string, timeoutMs?: number, sandbox?: ResolvedSandboxConfig): Promise<ExecResult>;
 //# sourceMappingURL=exec.d.ts.map

package/dist/tools/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/tools/exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAG/D,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAOpD,wBAAgB,aAAa,IAAI,IAAI,CAcpC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,YAAY,CAS3F;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,WAAW,EACxB,GAAG,CAAC,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CAmErB"}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/tools/exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEzF,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAOpD,wBAAgB,aAAa,IAAI,IAAI,CAcpC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,YAAY,CAS3F;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,WAAW,EACxB,GAAG,CAAC,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAsErB"}

package/dist/tools/exec.js

@@ -1,5 +1,6 @@
 import { spawn } from 'child_process';
 import { matchesCommand } from '../allowlist/pattern.js';
+import { wrapCommandWithSandbox } from '../sandbox/index.js';
 const MAX_OUTPUT_BYTES = 10 * 1024 * 1024; // 10MB cap on stdout/stderr
 /** Shell metacharacters that allow command chaining / injection */
 const SHELL_INJECTION_RE = /[;|&`$(){}]/;
@@ -38,11 +39,13 @@ export function evaluateExecCommand(command, agentConfig) {
         return 'allow';
     return 'deny'; // fail-closed
 }
-export async function executeExec(command, agentConfig, cwd, timeoutMs) {
+export async function executeExec(command, agentConfig, cwd, timeoutMs, sandbox) {
     const timeout = timeoutMs ?? agentConfig.exec.default_timeout_ms;
     const start = Date.now();
+    // Wrap command with sandbox if config is provided
+    const effectiveCommand = sandbox ? await wrapCommandWithSandbox(command, sandbox) : command;
     return new Promise((resolve, reject) => {
-        const child = spawn('/bin/sh', ['-c', command], {
+        const child = spawn('/bin/sh', ['-c', effectiveCommand], {
             cwd,
             env: agentConfig.exec.env,
             stdio: ['ignore', 'pipe', 'pipe'],

package/dist/tools/exec.js.map

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

package/dist/types.d.ts

@@ -2,6 +2,7 @@ export interface ToolCall {
     tool: string;
     args: Record<string, unknown>;
     agentId: string;
+    meta?: Record<string, unknown>;
 }
 export interface ToolResult {
     success: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D"}

package/examples/gateway.yaml

@@ -31,6 +31,19 @@ providers:
   exec: builtin
   http: builtin
 
+# Optional reusable sandbox presets for policy-wrapped tool variants.
+# See examples/sandbox-presets.yaml for a focused end-to-end example.
+# sandbox_presets:
+#   local_transform:
+#     filesystem:
+#       allow_read: ['.']
+#       allow_write: ['/tmp', '/private/tmp']
+#       deny_read: ['~/.ssh', '~/.aws', '.env']
+#       deny_write: ['.']
+#     network:
+#       allowed_domains: []
+#       denied_domains: []
+
 # Agents
 agents:
   # Helena: full-access developer agent with approval on destructive ops
@@ -61,6 +74,23 @@ agents:
       domain_allowlist:
         - 'api.github.com'
         - '*.sentry.io'
+    # sandbox:
+    #   enabled: true
+    #   presets: ['local_transform']
+    # tool_overrides:
+    #   python/sandboxed:
+    #     alias_of: 'exec/run'
+    #     description: 'Run Python for local transforms only'
+    #   python/full:
+    #     alias_of: 'exec/run'
+    #     description: 'Run Python with broader permissions after approval'
+    #     sandbox:
+    #       filesystem:
+    #         allow_write: ['.', '/tmp', '/private/tmp']
+    #         deny_write: []
+    #       network:
+    #         allowed_domains: ['pypi.org', '*.pythonhosted.org']
+    #         denied_domains: []
 
   # Claude Code: read-only, no approval needed
   claude-code:

package/examples/sandbox-presets.yaml

@@ -0,0 +1,142 @@
+# Sandbox presets + tool variant example.
+#
+# Goal:
+# - give agents a fast-path tool that is broadly allowed because it runs in a
+#   tight sandbox
+# - keep a second full-power variant that still requires approval
+#
+# Run: npx tsx src/index.ts --agent claude-code --config examples/sandbox-presets.yaml
+
+providers:
+  exec: builtin
+
+# Reusable sandbox building blocks.
+# These can be referenced by agents and by individual tool variants.
+sandbox_presets:
+  local_transform:
+    filesystem:
+      # Let the agent read the repo, but only write to temp space.
+      allow_read:
+        - '.'
+      allow_write:
+        - '/tmp'
+        - '/private/tmp'
+      # Additive deny rules protect common secret locations.
+      deny_read:
+        - '~/.ssh'
+        - '~/.aws'
+        - '~/.config/gcloud'
+        - '.env'
+      # Prevent writes back into the repo by default.
+      deny_write:
+        - '.'
+    network:
+      # Empty allowlist means no outbound network.
+      allowed_domains: []
+      denied_domains: []
+
+  github_only:
+    network:
+      allowed_domains:
+        - 'github.com'
+        - '*.github.com'
+        - 'api.github.com'
+      denied_domains: []
+
+agents:
+  claude-code:
+    allow:
+      - 'python/sandboxed'
+      - 'node/sandboxed'
+    ask:
+      - 'python/full'
+      - 'python/github'
+      - 'node/full'
+    deny:
+      - 'exec/run'
+
+    # Agent-level sandbox defaults apply to any tool that resolves through the
+    # sandbox middleware, then tool-specific presets / overrides refine it.
+    sandbox:
+      enabled: true
+      presets:
+        - local_transform
+
+    tool_overrides:
+      # Safe fast path: same underlying capability, but strongly sandboxed.
+      python/sandboxed:
+        alias_of: 'exec/run'
+        description: 'Run Python for local JSON/text transformations only'
+
+      # Full-power variant: same base tool, but leave it approval-gated.
+      python/full:
+        alias_of: 'exec/run'
+        description: 'Run Python with normal permissions after approval'
+        sandbox:
+          filesystem:
+            # Override allow_write so approved runs can modify the repo.
+            allow_write:
+              - '.'
+              - '/tmp'
+              - '/private/tmp'
+            deny_write: []
+          network:
+            # Example broad approved networking.
+            allowed_domains:
+              - 'pypi.org'
+              - '*.pythonhosted.org'
+            denied_domains: []
+
+      # Middle ground: GitHub-only network for scripts that need API access.
+      python/github:
+        alias_of: 'exec/run'
+        description: 'Run Python with GitHub-only network access after approval'
+        sandbox_presets:
+          - github_only
+
+      node/sandboxed:
+        alias_of: 'exec/run'
+        description: 'Run Node.js for local transformations only'
+
+      node/full:
+        alias_of: 'exec/run'
+        description: 'Run Node.js with broader permissions after approval'
+        sandbox:
+          filesystem:
+            allow_write:
+              - '.'
+              - '/tmp'
+              - '/private/tmp'
+            deny_write: []
+          network:
+            allowed_domains:
+              - 'registry.npmjs.org'
+              - '*.npmjs.org'
+            denied_domains: []
+
+    exec:
+      # Example shell policy for the underlying exec provider.
+      # The tool permission still controls whether the tool can be called at all;
+      # these patterns constrain the command strings passed into exec/run.
+      allow:
+        - 'python3 -c *'
+        - 'python -c *'
+        - 'node -e *'
+      ask:
+        - 'python3 *'
+        - 'python *'
+        - 'node *'
+      deny:
+        - 'sudo *'
+        - 'rm -rf *'
+
+approvals:
+  provider:
+    type: stdio
+  timeout_ms: 300000
+  batch_window_ms: 5000
+
+audit:
+  db_path: ':memory:'
+  retention_days: 1
+  redact_fields: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airlock-bot",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Permissions-aware MCP gateway with human-in-the-loop approval for AI agents",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,10 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "configure-agent": "tsx scripts/configure-agent.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:llms": "tsx scripts/generate-llms.ts",
+    "docs:build": "npm run docs:llms && vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "test": "vitest",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
@@ -50,6 +54,7 @@
     "prepublishOnly": "npm run schema && npm run build"
   },
   "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.42",
     "@apidevtools/swagger-parser": "^12.1.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "ai": "^6.0.116",
@@ -77,6 +82,7 @@
     "tsx": "^4.7.0",
     "typescript": "^5.4.0",
     "typescript-eslint": "^8.57.0",
+    "vitepress": "^1.6.4",
     "vitest": "^3.0.0",
     "zod-to-json-schema": "^3.25.1"
   }