vellum 0.0.16 → 0.2.0

package/src/tools/terminal/parser.ts

@@ -0,0 +1,393 @@
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { getLogger } from '../../util/logger.js';
+import { IntegrityError } from '../../util/errors.js';
+import { Parser, Language, type Node as TSNode } from 'web-tree-sitter';
+
+const log = getLogger('shell-parser');
+
+export type DangerousPatternType =
+  | 'pipe_to_shell'
+  | 'base64_execute'
+  | 'process_substitution'
+  | 'sensitive_redirect'
+  | 'dangerous_substitution'
+  | 'env_injection';
+
+export interface DangerousPattern {
+  type: DangerousPatternType;
+  description: string;
+  text: string;
+}
+
+export interface CommandSegment {
+  command: string;
+  program: string;
+  args: string[];
+  operator: '&&' | '||' | ';' | '|' | '';
+}
+
+export interface ParsedCommand {
+  segments: CommandSegment[];
+  dangerousPatterns: DangerousPattern[];
+  hasOpaqueConstructs: boolean;
+}
+
+const SHELL_PROGRAMS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish']);
+const OPAQUE_PROGRAMS = new Set(['eval', 'source']);
+const DANGEROUS_ENV_VARS = new Set([
+  'LD_PRELOAD', 'LD_LIBRARY_PATH',
+  'DYLD_INSERT_LIBRARIES', 'DYLD_LIBRARY_PATH', 'DYLD_FRAMEWORK_PATH',
+  'NODE_OPTIONS', 'NODE_PATH',
+  'PATH', 'PYTHONPATH', 'RUBYLIB',
+]);
+const SENSITIVE_PATH_PREFIXES = [
+  '~/.zshrc', '~/.bashrc', '~/.bash_profile', '~/.profile',
+  '~/.ssh/', '~/.gnupg/', '~/.config/',
+  '/etc/', '/usr/lib/', '/usr/bin/',
+];
+
+// Expected SHA-256 checksums for WASM binaries.
+// Update these when intentionally upgrading web-tree-sitter or tree-sitter-bash.
+// Generate with: shasum -a 256 node_modules/web-tree-sitter/web-tree-sitter.wasm node_modules/tree-sitter-bash/tree-sitter-bash.wasm
+const EXPECTED_CHECKSUMS: Record<string, string> = {
+  'web-tree-sitter.wasm': '3d4c304cb7d59cfac4a2aa23c3408416cbfa2287fe17a9c975da46eb2ead8646',
+  'tree-sitter-bash.wasm': '8292919c88a0f7d3fb31d0cd0253ca5a9531bc1ede82b0537f2c63dd8abe6a7a',
+};
+
+function verifyWasmChecksum(filePath: string, label: string): void {
+  const data = readFileSync(filePath);
+  const hash = createHash('sha256').update(data).digest('hex');
+  const expected = EXPECTED_CHECKSUMS[label];
+  if (!expected) {
+    throw new IntegrityError(
+      `No expected checksum registered for ${label}`,
+    );
+  }
+  if (hash !== expected) {
+    throw new IntegrityError(
+      `WASM integrity check failed for ${label}: expected ${expected}, got ${hash}`,
+    );
+  }
+}
+
+let parserInstance: Parser | null = null;
+let initPromise: Promise<void> | null = null;
+
+function findWasmPath(pkg: string, file: string): string {
+  return join(
+    import.meta.dirname ?? __dirname,
+    '..', '..', '..', 'node_modules', pkg, file,
+  );
+}
+
+async function ensureParser(): Promise<Parser> {
+  if (parserInstance) return parserInstance;
+
+  if (!initPromise) {
+    initPromise = (async () => {
+      const treeSitterWasm = findWasmPath('web-tree-sitter', 'web-tree-sitter.wasm');
+      const bashWasmPath = findWasmPath('tree-sitter-bash', 'tree-sitter-bash.wasm');
+
+      verifyWasmChecksum(treeSitterWasm, 'web-tree-sitter.wasm');
+      verifyWasmChecksum(bashWasmPath, 'tree-sitter-bash.wasm');
+
+      await Parser.init();
+
+      const Bash = await Language.load(bashWasmPath);
+      const parser = new Parser();
+      parser.setLanguage(Bash);
+      parserInstance = parser;
+      log.info('Shell parser initialized (web-tree-sitter + bash, checksums verified)');
+    })();
+  }
+
+  await initPromise;
+  return parserInstance!;
+}
+
+function extractSegments(node: TSNode): CommandSegment[] {
+  const segments: CommandSegment[] = [];
+
+  function walkNode(n: TSNode, operator: CommandSegment['operator']): void {
+    switch (n.type) {
+      case 'program': {
+        for (const child of n.namedChildren) {
+          walkNode(child, '');
+        }
+        break;
+      }
+
+      case 'list': {
+        // list = command (operator command)*
+        for (let i = 0; i < n.childCount; i++) {
+          const child = n.child(i);
+          if (!child) continue;
+          if (child.type === '&&' || child.type === '||' || child.type === ';') {
+            operator = child.type as CommandSegment['operator'];
+          } else if (child.type !== 'comment') {
+            walkNode(child, operator);
+            operator = '';
+          }
+        }
+        break;
+      }
+
+      case 'pipeline': {
+        let first = true;
+        for (const child of n.namedChildren) {
+          walkNode(child, first ? operator : '|');
+          first = false;
+        }
+        break;
+      }
+
+      case 'command': {
+        const words: string[] = [];
+        for (const child of n.namedChildren) {
+          if (child.type === 'command_name' || child.type === 'word' ||
+              child.type === 'string' || child.type === 'raw_string' ||
+              child.type === 'simple_expansion' || child.type === 'expansion' ||
+              child.type === 'command_substitution' || child.type === 'concatenation' ||
+              child.type === 'number') {
+            words.push(child.text);
+          }
+        }
+        if (words.length > 0) {
+          segments.push({
+            command: n.text,
+            program: words[0],
+            args: words.slice(1),
+            operator,
+          });
+        }
+        break;
+      }
+
+      case 'redirected_statement': {
+        for (const child of n.namedChildren) {
+          if (child.type !== 'file_redirect' && child.type !== 'heredoc_redirect' &&
+              child.type !== 'herestring_redirect') {
+            walkNode(child, operator);
+          }
+        }
+        break;
+      }
+
+      case 'subshell':
+      case 'command_substitution':
+      case 'compound_statement':
+      case 'if_statement':
+      case 'while_statement':
+      case 'for_statement':
+      case 'case_statement':
+      case 'function_definition':
+      case 'negated_command': {
+        for (const child of n.namedChildren) {
+          walkNode(child, operator);
+        }
+        break;
+      }
+
+      default: {
+        for (const child of n.namedChildren) {
+          walkNode(child, operator);
+        }
+        break;
+      }
+    }
+  }
+
+  walkNode(node, '');
+  return segments;
+}
+
+function detectDangerousPatterns(node: TSNode, segments: CommandSegment[]): DangerousPattern[] {
+  const patterns: DangerousPattern[] = [];
+
+  for (let i = 1; i < segments.length; i++) {
+    if (segments[i].operator === '|') {
+      const prog = segments[i].program;
+      if (SHELL_PROGRAMS.has(prog) || prog === 'eval' || prog === 'xargs') {
+        patterns.push({
+          type: 'pipe_to_shell',
+          description: `Pipeline into ${prog}`,
+          text: segments[i].command,
+        });
+      }
+    }
+  }
+
+  for (let i = 0; i < segments.length - 1; i++) {
+    if (segments[i].program === 'base64' && segments[i].args.includes('-d')) {
+      if (i + 1 < segments.length && segments[i + 1].operator === '|') {
+        const nextProg = segments[i + 1].program;
+        if (SHELL_PROGRAMS.has(nextProg) || nextProg === 'eval') {
+          patterns.push({
+            type: 'base64_execute',
+            description: 'base64 decoded content piped to shell',
+            text: `${segments[i].command} | ${segments[i + 1].command}`,
+          });
+        }
+      }
+    }
+  }
+
+  function walkForPatterns(n: TSNode): void {
+    if (n.type === 'process_substitution') {
+      patterns.push({
+        type: 'process_substitution',
+        description: 'Process substitution detected',
+        text: n.text,
+      });
+    }
+
+    if (n.type === 'file_redirect') {
+      const dest = n.lastChild;
+      if (dest) {
+        const destText = dest.text;
+        for (const prefix of SENSITIVE_PATH_PREFIXES) {
+          if (destText.startsWith(prefix) || destText.startsWith(prefix.replace('~', '$HOME'))) {
+            patterns.push({
+              type: 'sensitive_redirect',
+              description: `Redirect to sensitive path: ${destText}`,
+              text: n.text,
+            });
+            break;
+          }
+        }
+      }
+    }
+
+    if (n.type === 'command_substitution' && n.parent) {
+      const parent = n.parent;
+      if (parent.type === 'command') {
+        const firstWord = parent.namedChild(0);
+        if (firstWord && (firstWord.text === 'rm' || firstWord.text === 'chmod' || firstWord.text === 'chown')) {
+          patterns.push({
+            type: 'dangerous_substitution',
+            description: `Command substitution as argument to ${firstWord.text}`,
+            text: parent.text,
+          });
+        }
+      }
+    }
+
+    if (n.type === 'variable_assignment') {
+      const varName = n.firstChild;
+      if (varName && varName.type === 'variable_name') {
+        if (DANGEROUS_ENV_VARS.has(varName.text)) {
+          patterns.push({
+            type: 'env_injection',
+            description: `Assignment to dangerous env var: ${varName.text}`,
+            text: n.text,
+          });
+        }
+      }
+    }
+
+    for (const child of n.children) {
+      walkForPatterns(child);
+    }
+  }
+
+  walkForPatterns(node);
+  return patterns;
+}
+
+function detectOpaqueConstructs(node: TSNode, segments: CommandSegment[]): boolean {
+  // Check segments for opaque programs
+  for (const seg of segments) {
+    if (OPAQUE_PROGRAMS.has(seg.program) || seg.program === '.') {
+      return true;
+    }
+    if (SHELL_PROGRAMS.has(seg.program) && (seg.args.includes('-c') || seg.args.includes('-ec'))) {
+      return true;
+    }
+  }
+
+  function walkForOpacity(n: TSNode): boolean {
+    // Heredocs / herestrings
+    if (n.type === 'heredoc_redirect' || n.type === 'heredoc_body' ||
+        n.type === 'herestring_redirect') {
+      return true;
+    }
+
+    // Variable expansion used as command name
+    if (n.type === 'command') {
+      const firstChild = n.namedChild(0);
+      if (firstChild) {
+        // Direct expansion as command (e.g. in some grammars)
+        if (
+          firstChild.type === 'simple_expansion' ||
+          firstChild.type === 'expansion' ||
+          firstChild.type === 'command_substitution'
+        ) {
+          return true;
+        }
+        // tree-sitter-bash wraps the command name in a command_name node,
+        // so check inside it for variable/command substitution
+        if (firstChild.type === 'command_name') {
+          const inner = firstChild.namedChild(0);
+          if (inner && (
+            inner.type === 'simple_expansion' ||
+            inner.type === 'expansion' ||
+            inner.type === 'command_substitution' ||
+            inner.type === 'concatenation'
+          )) {
+            return true;
+          }
+        }
+      }
+    }
+
+    // Hex/octal escape sequences in command position
+    if (n.type === 'ansi_c_string' || n.type === 'ansii_c_string') {
+      if (n.parent?.type === 'command') {
+        const first = n.parent.namedChild(0);
+        if (first && first.equals(n)) {
+          return true;
+        }
+      }
+      if (/\\x[0-9a-fA-F]{2}|\\[0-7]{3}/.test(n.text)) {
+        return true;
+      }
+    }
+
+    // Array expansion as command
+    if (n.type === 'expansion' && n.text.includes('[@]') && n.parent?.type === 'command') {
+      const first = n.parent.namedChild(0);
+      if (first && first.equals(n)) {
+        return true;
+      }
+    }
+
+    for (const child of n.children) {
+      if (walkForOpacity(child)) return true;
+    }
+    return false;
+  }
+
+  return walkForOpacity(node);
+}
+
+export async function parse(command: string): Promise<ParsedCommand> {
+  const parser = await ensureParser();
+  const tree = parser.parse(command);
+  if (!tree) {
+    // Parser couldn't parse — treat as opaque
+    return { segments: [], dangerousPatterns: [], hasOpaqueConstructs: true };
+  }
+  const rootNode = tree.rootNode;
+
+  const segments = extractSegments(rootNode);
+  const dangerousPatterns = detectDangerousPatterns(rootNode, segments);
+  const hasOpaqueConstructs = detectOpaqueConstructs(rootNode, segments);
+
+  tree.delete();
+
+  return { segments, dangerousPatterns, hasOpaqueConstructs };
+}
+
+export { ensureParser };

package/src/tools/terminal/safe-env.ts

@@ -0,0 +1,37 @@
+/**
+ * Environment variables that are safe to pass through to child processes.
+ * Everything else (API keys, tokens, credentials) is stripped to prevent
+ * accidental leakage via agent-spawned commands.
+ *
+ * Shared by the sandbox bash tool and the evaluate_typescript_code tool.
+ */
+const SAFE_ENV_VARS = [
+  'PATH',
+  'HOME',
+  'TERM',
+  'LANG',
+  'EDITOR',
+  'SHELL',
+  'USER',
+  'TMPDIR',
+  'LC_ALL',
+  'LC_CTYPE',
+  'XDG_RUNTIME_DIR',
+  'DISPLAY',
+  'COLORTERM',
+  'TERM_PROGRAM',
+  'SSH_AUTH_SOCK',
+  'SSH_AGENT_PID',
+  'GPG_TTY',
+  'GNUPGHOME',
+] as const;
+
+export function buildSanitizedEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of SAFE_ENV_VARS) {
+    if (process.env[key] != null) {
+      env[key] = process.env[key]!;
+    }
+  }
+  return env;
+}

package/src/tools/terminal/sandbox-diagnostics.ts

@@ -0,0 +1,149 @@
+import { execSync, execFileSync } from 'node:child_process';
+import { isMacOS, isLinux, getSandboxWorkingDir } from '../../util/platform.js';
+import { getConfig } from '../../config/loader.js';
+import type { SandboxConfig } from '../../config/schema.js';
+import { DEFAULT_SANDBOX_IMAGE } from './backends/docker.js';
+
+export interface SandboxCheckResult {
+  label: string;
+  ok: boolean;
+  detail?: string;
+}
+
+export interface SandboxDiagnostics {
+  config: {
+    enabled: boolean;
+    backend: string;
+    dockerImage: string;
+  };
+  /** Why the active backend was selected (config vs platform default). */
+  activeBackendReason: string;
+  checks: SandboxCheckResult[];
+}
+
+function checkDockerCli(): SandboxCheckResult {
+  try {
+    const out = execSync('docker --version', { stdio: 'pipe', timeout: 5000, encoding: 'utf-8' }).trim();
+    return { label: 'Docker CLI installed', ok: true, detail: out };
+  } catch {
+    return { label: 'Docker CLI installed', ok: false, detail: 'docker not found in PATH' };
+  }
+}
+
+function checkDockerDaemon(): SandboxCheckResult {
+  try {
+    execSync('docker info', { stdio: 'pipe', timeout: 10000 });
+    return { label: 'Docker daemon running', ok: true };
+  } catch {
+    return { label: 'Docker daemon running', ok: false, detail: 'daemon not reachable — start Docker Desktop or run "sudo systemctl start docker"' };
+  }
+}
+
+function checkDockerImage(image: string): SandboxCheckResult {
+  try {
+    execFileSync('docker', ['image', 'inspect', image], { stdio: 'pipe', timeout: 10000 });
+    return { label: `Docker image available (${image})`, ok: true };
+  } catch {
+    // The default sandbox image is built locally from Dockerfile.sandbox — docker pull won't work.
+    const remediation = image === DEFAULT_SANDBOX_IMAGE
+      ? 'build with: docker build --no-cache -t vellum-sandbox:latest -f assistant/Dockerfile.sandbox assistant'
+      : `pull with: docker pull ${image}`;
+    return { label: `Docker image available (${image})`, ok: false, detail: remediation };
+  }
+}
+
+function checkDockerMountProbe(image: string): SandboxCheckResult {
+  // Use the same sandbox path and writable-mount probe that the runtime
+  // preflight uses (checkMountProbe in docker.ts) so doctor validates
+  // exactly what runtime enforces.
+  const sandboxRoot = getSandboxWorkingDir();
+  try {
+    execFileSync(
+      'docker',
+      [
+        'run', '--rm',
+        '--mount', `type=bind,src=${sandboxRoot},dst=/workspace`,
+        image, 'test', '-w', '/workspace',
+      ],
+      { stdio: 'pipe', timeout: 15000 },
+    );
+    return { label: 'Docker mount writable', ok: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown error';
+    return {
+      label: 'Docker mount writable',
+      ok: false,
+      detail: 'Cannot bind-mount sandbox root or /workspace is not writable. ' +
+        'If using Docker Desktop, enable file sharing for this path in Settings > Resources > File Sharing. ' +
+        `(${msg})`,
+    };
+  }
+}
+
+function checkNativeBackend(): SandboxCheckResult {
+  if (isMacOS()) {
+    try {
+      execSync('sandbox-exec -n no-network true', { stdio: 'pipe', timeout: 5000 });
+      return { label: 'Native sandbox (macOS sandbox-exec)', ok: true };
+    } catch {
+      return { label: 'Native sandbox (macOS sandbox-exec)', ok: false, detail: 'sandbox-exec not functional' };
+    }
+  }
+  if (isLinux()) {
+    try {
+      execSync('bwrap --ro-bind / / --unshare-net --unshare-pid true', { stdio: 'pipe', timeout: 5000 });
+      return { label: 'Native sandbox (Linux bwrap)', ok: true };
+    } catch {
+      return { label: 'Native sandbox (Linux bwrap)', ok: false, detail: 'bwrap not available — install bubblewrap' };
+    }
+  }
+  return { label: 'Native sandbox', ok: false, detail: `not supported on ${process.platform}` };
+}
+
+function getActiveBackendReason(sandboxConfig: SandboxConfig): string {
+  if (!sandboxConfig.enabled) {
+    return 'Sandbox is disabled in configuration';
+  }
+  if (sandboxConfig.backend === 'docker') {
+    return 'Docker backend selected in configuration (sandbox.backend = "docker")';
+  }
+  return 'Native backend selected in configuration (sandbox.backend = "native")';
+}
+
+/**
+ * Run sandbox backend diagnostics. Checks Docker availability,
+ * native backend availability, and reports current configuration.
+ */
+export function runSandboxDiagnostics(): SandboxDiagnostics {
+  const config = getConfig();
+  const sandboxConfig = config.sandbox;
+
+  const checks: SandboxCheckResult[] = [];
+
+  // Always check native backend availability as a diagnostic signal
+  checks.push(checkNativeBackend());
+
+  // Docker checks: CLI, daemon, image, container execution
+  const cliResult = checkDockerCli();
+  checks.push(cliResult);
+
+  if (cliResult.ok) {
+    const daemonResult = checkDockerDaemon();
+    checks.push(daemonResult);
+
+    if (daemonResult.ok) {
+      checks.push(checkDockerImage(sandboxConfig.docker.image));
+      checks.push(checkDockerMountProbe(sandboxConfig.docker.image));
+    }
+  }
+
+  return {
+    config: {
+      enabled: sandboxConfig.enabled,
+      backend: sandboxConfig.backend,
+      dockerImage: sandboxConfig.docker.image,
+    },
+    activeBackendReason: getActiveBackendReason(sandboxConfig),
+    checks,
+  };
+}

package/src/tools/terminal/sandbox.ts

@@ -0,0 +1,44 @@
+import { NativeBackend } from './backends/native.js';
+import { DockerBackend } from './backends/docker.js';
+import type { SandboxResult, WrapOptions } from './backends/types.js';
+import type { SandboxConfig } from '../../config/schema.js';
+import { getSandboxWorkingDir } from '../../util/platform.js';
+
+export type { SandboxResult, SandboxBackend, WrapOptions } from './backends/types.js';
+
+const nativeBackend = new NativeBackend();
+
+/**
+ * Wrap a shell command for sandboxed execution.
+ *
+ * When sandboxing is disabled, returns a plain bash invocation.
+ * When enabled, delegates to the configured backend (native or docker).
+ * Fails closed if the backend cannot be applied.
+ *
+ * @param options  Per-invocation overrides (e.g. networkMode for proxied bash).
+ */
+export function wrapCommand(
+  command: string,
+  workingDir: string,
+  config: SandboxConfig,
+  options?: WrapOptions,
+): SandboxResult {
+  if (!config.enabled) {
+    return {
+      command: 'bash',
+      args: ['-c', '--', command],
+      sandboxed: false,
+    };
+  }
+
+  if (config.backend === 'docker') {
+    // Always mount the canonical sandbox fs root, not whatever workingDir
+    // happens to be. workingDir may be a subdirectory; the mount source
+    // must be the fixed root so the entire sandbox filesystem is available.
+    const sandboxRoot = getSandboxWorkingDir();
+    const backend = new DockerBackend(sandboxRoot, config.docker);
+    return backend.wrap(command, workingDir, options);
+  }
+
+  return nativeBackend.wrap(command, workingDir, options);
+}