@cdoing/core 0.1.0

package/src/sandbox/filesystem.ts

@@ -0,0 +1,135 @@
+/**
+ * Sandbox Filesystem — checks read/write access against sandbox rules.
+ */
+
+import * as path from "path";
+import { matchPath } from "../utils/path-matching";
+import type { SandboxConfig, SandboxCheckResult } from "./types";
+
+/**
+ * Check whether reading a file is allowed by sandbox rules.
+ * Only blocks paths listed in denyRead.
+ */
+export function checkReadAccess(
+  filePath: string,
+  config: SandboxConfig,
+  workingDir: string,
+  projectDir: string,
+): SandboxCheckResult {
+  if (!config.enabled) return { allowed: true };
+
+  const resolved = path.resolve(filePath);
+
+  for (const deny of config.filesystem.denyRead) {
+    if (matchPath(resolved, deny, projectDir, workingDir)) {
+      return { allowed: false, reason: `Sandbox: read access denied for ${resolved} (matches denyRead rule "${deny}")` };
+    }
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * Check whether writing to a file is allowed by sandbox rules.
+ * DenyWrite takes priority, then path must be within workingDir or allowWrite paths.
+ */
+export function checkWriteAccess(
+  filePath: string,
+  config: SandboxConfig,
+  workingDir: string,
+  projectDir: string,
+): SandboxCheckResult {
+  if (!config.enabled) return { allowed: true };
+
+  const resolved = path.resolve(filePath);
+  const normalizedWorkingDir = path.resolve(workingDir);
+
+  // Check denyWrite first (deny always wins)
+  for (const deny of config.filesystem.denyWrite) {
+    if (matchPath(resolved, deny, projectDir, workingDir)) {
+      return { allowed: false, reason: `Sandbox: write access denied for ${resolved} (matches denyWrite rule "${deny}")` };
+    }
+  }
+
+  // Allow writes within workingDir
+  if (resolved === normalizedWorkingDir || resolved.startsWith(normalizedWorkingDir + path.sep)) {
+    return { allowed: true };
+  }
+
+  // Check allowWrite paths
+  for (const allow of config.filesystem.allowWrite) {
+    if (matchPath(resolved, allow, projectDir, workingDir)) {
+      return { allowed: true };
+    }
+  }
+
+  return { allowed: false, reason: `Sandbox: write access denied for ${resolved} (outside working directory and not in allowWrite)` };
+}
+
+/**
+ * Best-effort heuristic: parse a shell command to detect read/write targets.
+ * Returns denied if any detected target violates sandbox rules.
+ */
+export function checkShellCommandPaths(
+  command: string,
+  config: SandboxConfig,
+  workingDir: string,
+  projectDir: string,
+): SandboxCheckResult {
+  if (!config.enabled) return { allowed: true };
+
+  // Detect write targets: >, >>, tee
+  const writeTargets = extractWriteTargets(command);
+  for (const target of writeTargets) {
+    const resolved = path.isAbsolute(target) ? target : path.resolve(workingDir, target);
+    const check = checkWriteAccess(resolved, config, workingDir, projectDir);
+    if (!check.allowed) return check;
+  }
+
+  // Detect read targets: cat, less, head, tail, more
+  const readTargets = extractReadTargets(command);
+  for (const target of readTargets) {
+    const resolved = path.isAbsolute(target) ? target : path.resolve(workingDir, target);
+    const check = checkReadAccess(resolved, config, workingDir, projectDir);
+    if (!check.allowed) return check;
+  }
+
+  return { allowed: true };
+}
+
+/** Extract file paths that appear as write targets in a shell command */
+function extractWriteTargets(command: string): string[] {
+  const targets: string[] = [];
+
+  // Match >> or > followed by optional space and a file path
+  const redirectRegex = />{1,2}\s*([^\s;|&]+)/g;
+  let match;
+  while ((match = redirectRegex.exec(command)) !== null) {
+    targets.push(match[1]);
+  }
+
+  // Match tee followed by optional flags and file path
+  const teeRegex = /\btee\s+(?:-[a-zA-Z]\s+)*([^\s;|&]+)/g;
+  while ((match = teeRegex.exec(command)) !== null) {
+    targets.push(match[1]);
+  }
+
+  return targets;
+}
+
+/** Extract file paths that appear as read targets in a shell command */
+function extractReadTargets(command: string): string[] {
+  const targets: string[] = [];
+
+  // Match cat, less, head, tail, more followed by optional flags and file path
+  const readRegex = /\b(?:cat|less|head|tail|more)\s+(?:-[a-zA-Z0-9]+\s+)*([^\s;|&]+)/g;
+  let match;
+  while ((match = readRegex.exec(command)) !== null) {
+    // Skip if it looks like a flag
+    if (!match[1].startsWith("-")) {
+      targets.push(match[1]);
+    }
+  }
+
+  return targets;
+}

package/src/sandbox/index.ts

@@ -0,0 +1,9 @@
+export { SandboxManager } from "./manager";
+export type {
+  SandboxConfig,
+  SandboxMode,
+  SandboxFilesystemConfig,
+  SandboxNetworkConfig,
+  SandboxCheckResult,
+} from "./types";
+export { defaultSandboxConfig } from "./types";

package/src/sandbox/manager.ts

@@ -0,0 +1,213 @@
+/**
+ * Sandbox Manager — orchestrates filesystem and network sandbox enforcement.
+ *
+ * Loads sandbox configuration from .claude/settings.json files using the
+ * same hierarchy as the permission system (local → shared → user).
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import type { SandboxConfig, SandboxCheckResult, SandboxMode } from "./types";
+import { defaultSandboxConfig } from "./types";
+import { checkReadAccess, checkWriteAccess, checkShellCommandPaths } from "./filesystem";
+import { checkDomainAccess, buildSandboxedEnv } from "./network";
+
+const HOME_DIR = os.homedir();
+const USER_SETTINGS_FILE = path.join(HOME_DIR, ".claude", "settings.json");
+
+export class SandboxManager {
+  private config: SandboxConfig;
+  private workingDir: string;
+  private projectDir: string;
+  private sessionApprovedDomains = new Set<string>();
+  private domainPromptFn: ((domain: string) => Promise<boolean>) | null = null;
+
+  constructor(workingDir: string, projectDir?: string) {
+    this.workingDir = path.resolve(workingDir);
+    this.projectDir = projectDir ? path.resolve(projectDir) : this.workingDir;
+    this.config = defaultSandboxConfig();
+    this.loadConfig();
+  }
+
+  // ── Config loading ──────────────────────────────────────────────────────────
+
+  /**
+   * Load and merge sandbox config from settings files.
+   * Precedence: local project → shared project → user (highest to lowest).
+   * Arrays are merged (not replaced) across scopes.
+   */
+  loadConfig(): void {
+    const candidates = [
+      path.join(this.projectDir, ".claude", "settings.local.json"),
+      path.join(this.projectDir, ".claude", "settings.json"),
+      USER_SETTINGS_FILE,
+    ];
+
+    const merged = defaultSandboxConfig();
+
+    for (const filePath of candidates) {
+      try {
+        if (!fs.existsSync(filePath)) continue;
+        const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (!data.sandbox) continue;
+
+        const sb = data.sandbox;
+
+        // enabled: any scope can enable
+        if (sb.enabled === true) merged.enabled = true;
+
+        // mode: highest-precedence scope wins (first found)
+        if (sb.mode && merged.mode === "regular") {
+          merged.mode = sb.mode as SandboxMode;
+        }
+
+        // Filesystem arrays are merged
+        if (sb.filesystem) {
+          if (Array.isArray(sb.filesystem.allowWrite)) {
+            merged.filesystem.allowWrite.push(...sb.filesystem.allowWrite);
+          }
+          if (Array.isArray(sb.filesystem.denyWrite)) {
+            merged.filesystem.denyWrite.push(...sb.filesystem.denyWrite);
+          }
+          if (Array.isArray(sb.filesystem.denyRead)) {
+            merged.filesystem.denyRead.push(...sb.filesystem.denyRead);
+          }
+        }
+
+        // Network: merge domains
+        if (sb.network) {
+          if (Array.isArray(sb.network.allowedDomains)) {
+            merged.network.allowedDomains.push(...sb.network.allowedDomains);
+          }
+          if (sb.network.allowManagedDomainsOnly === true) {
+            merged.network.allowManagedDomainsOnly = true;
+          }
+        }
+
+        // Excluded commands: merge
+        if (Array.isArray(sb.excludedCommands)) {
+          merged.excludedCommands.push(...sb.excludedCommands);
+        }
+
+        // allowUnsandboxedCommands: false from any scope wins (restrictive)
+        if (sb.allowUnsandboxedCommands === false) {
+          merged.allowUnsandboxedCommands = false;
+        }
+      } catch {
+        // Skip malformed files
+      }
+    }
+
+    // Deduplicate arrays
+    merged.filesystem.allowWrite = [...new Set(merged.filesystem.allowWrite)];
+    merged.filesystem.denyWrite = [...new Set(merged.filesystem.denyWrite)];
+    merged.filesystem.denyRead = [...new Set(merged.filesystem.denyRead)];
+    merged.network.allowedDomains = [...new Set(merged.network.allowedDomains)];
+    merged.excludedCommands = [...new Set(merged.excludedCommands)];
+
+    this.config = merged;
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────────
+
+  getConfig(): Readonly<SandboxConfig> {
+    return this.config;
+  }
+
+  isEnabled(): boolean {
+    return this.config.enabled;
+  }
+
+  getMode(): SandboxMode {
+    return this.config.mode;
+  }
+
+  setDomainPromptFn(fn: (domain: string) => Promise<boolean>): void {
+    this.domainPromptFn = fn;
+  }
+
+  approveDomain(domain: string): void {
+    this.sessionApprovedDomains.add(domain);
+  }
+
+  // ── Access checks ─────────────────────────────────────────────────────────
+
+  checkFileRead(filePath: string): SandboxCheckResult {
+    return checkReadAccess(filePath, this.config, this.workingDir, this.projectDir);
+  }
+
+  checkFileWrite(filePath: string): SandboxCheckResult {
+    return checkWriteAccess(filePath, this.config, this.workingDir, this.projectDir);
+  }
+
+  /**
+   * Check if a shell command is allowed by sandbox rules.
+   * Returns denied if dangerouslyDisableSandbox is used but not allowed.
+   */
+  checkShellCommand(command: string, dangerouslyDisableSandbox?: boolean): SandboxCheckResult {
+    if (!this.config.enabled) return { allowed: true };
+
+    // Handle dangerouslyDisableSandbox escape hatch
+    if (dangerouslyDisableSandbox) {
+      if (!this.config.allowUnsandboxedCommands) {
+        return {
+          allowed: false,
+          reason: "Sandbox: dangerouslyDisableSandbox is not allowed (allowUnsandboxedCommands is false)",
+        };
+      }
+      // Allowed to bypass sandbox — permission system still applies
+      return { allowed: true };
+    }
+
+    // Check if command is excluded from sandbox
+    if (this.isExcludedCommand(command)) {
+      return { allowed: true };
+    }
+
+    // Check command paths heuristically
+    return checkShellCommandPaths(command, this.config, this.workingDir, this.projectDir);
+  }
+
+  /**
+   * Check if network access to a URL is allowed.
+   * If the domain needs user approval, triggers the domain prompt.
+   */
+  async checkNetworkAccess(url: string): Promise<SandboxCheckResult> {
+    const result = checkDomainAccess(url, this.config, this.sessionApprovedDomains);
+
+    if (result.promptUser && result.domain && this.domainPromptFn) {
+      const approved = await this.domainPromptFn(result.domain);
+      if (approved) {
+        this.sessionApprovedDomains.add(result.domain);
+        return { allowed: true };
+      }
+      return {
+        allowed: false,
+        reason: `Sandbox: user denied network access to domain "${result.domain}"`,
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * Check if a command prefix matches any excluded command.
+   */
+  isExcludedCommand(command: string): boolean {
+    const trimmed = command.trimStart();
+    for (const excluded of this.config.excludedCommands) {
+      if (trimmed === excluded || trimmed.startsWith(excluded + " ") || trimmed.startsWith(excluded + "\t")) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get a sandboxed environment for shell command execution.
+   */
+  getShellEnv(): NodeJS.ProcessEnv {
+    return buildSandboxedEnv(this.config, process.env);
+  }
+}

package/src/sandbox/network.ts

@@ -0,0 +1,101 @@
+/**
+ * Sandbox Network — domain access checks and environment restrictions.
+ */
+
+import type { SandboxConfig, SandboxCheckResult } from "./types";
+
+/**
+ * Check whether accessing a URL is allowed by sandbox network rules.
+ */
+export function checkDomainAccess(
+  url: string,
+  config: SandboxConfig,
+  sessionApprovedDomains: Set<string>,
+): SandboxCheckResult {
+  if (!config.enabled) return { allowed: true };
+
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return { allowed: false, reason: `Sandbox: invalid URL "${url}"` };
+  }
+
+  // Check against allowed domains (exact or subdomain match)
+  if (isDomainAllowed(hostname, config.network.allowedDomains)) {
+    return { allowed: true };
+  }
+
+  // Check session-approved domains
+  if (sessionApprovedDomains.has(hostname)) {
+    return { allowed: true };
+  }
+
+  // Check if any parent domain was session-approved
+  for (const approved of sessionApprovedDomains) {
+    if (hostname.endsWith("." + approved)) {
+      return { allowed: true };
+    }
+  }
+
+  // Domain not allowed
+  if (config.network.allowManagedDomainsOnly) {
+    return {
+      allowed: false,
+      reason: `Sandbox: network access denied for domain "${hostname}" (not in allowedDomains and allowManagedDomainsOnly is enabled)`,
+    };
+  }
+
+  // Prompt user for approval
+  return {
+    allowed: false,
+    promptUser: true,
+    domain: hostname,
+    reason: `Sandbox: domain "${hostname}" is not in the allowed list`,
+  };
+}
+
+/**
+ * Check if a hostname matches any of the allowed domains.
+ * Supports exact match and subdomain match (e.g., "github.com" matches "api.github.com").
+ */
+function isDomainAllowed(hostname: string, allowedDomains: string[]): boolean {
+  for (const domain of allowedDomains) {
+    if (hostname === domain || hostname.endsWith("." + domain)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Build a sandboxed environment for shell command execution.
+ * Sets proxy env vars as a best-effort network restriction.
+ */
+export function buildSandboxedEnv(
+  config: SandboxConfig,
+  baseEnv: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+  if (!config.enabled) return { ...baseEnv };
+
+  const env = { ...baseEnv };
+
+  // Remove potentially dangerous env vars that could leak credentials
+  const sensitiveVars = [
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "NPM_TOKEN",
+    "DOCKER_PASSWORD",
+  ];
+
+  for (const v of sensitiveVars) {
+    // Only remove if sandbox is actively restricting network
+    if (config.network.allowedDomains.length > 0 || config.network.allowManagedDomainsOnly) {
+      delete env[v];
+    }
+  }
+
+  return env;
+}

package/src/sandbox/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Sandbox Types — configuration and check result interfaces.
+ */
+
+export interface SandboxFilesystemConfig {
+  /** Additional paths (beyond workingDir) where writes are allowed */
+  allowWrite: string[];
+  /** Paths where writes are denied */
+  denyWrite: string[];
+  /** Paths where reads are denied */
+  denyRead: string[];
+}
+
+export interface SandboxNetworkConfig {
+  /** Whitelisted domains for network access */
+  allowedDomains: string[];
+  /** If true, block non-allowed domains without prompting the user */
+  allowManagedDomainsOnly: boolean;
+}
+
+/** Sandbox operation mode */
+export type SandboxMode = "auto-allow" | "regular";
+
+/** Full sandbox configuration (loaded from settings files) */
+export interface SandboxConfig {
+  enabled: boolean;
+  mode: SandboxMode;
+  filesystem: SandboxFilesystemConfig;
+  network: SandboxNetworkConfig;
+  /** Commands that bypass the sandbox (e.g. "docker") */
+  excludedCommands: string[];
+  /** Whether dangerouslyDisableSandbox param is respected */
+  allowUnsandboxedCommands: boolean;
+}
+
+/** Result of a sandbox access check */
+export interface SandboxCheckResult {
+  allowed: boolean;
+  reason?: string;
+  /** For network checks: whether the user should be prompted about a new domain */
+  promptUser?: boolean;
+  /** The domain being requested (when promptUser is true) */
+  domain?: string;
+}
+
+/** Returns a default (disabled) sandbox config */
+export function defaultSandboxConfig(): SandboxConfig {
+  return {
+    enabled: false,
+    mode: "regular",
+    filesystem: {
+      allowWrite: [],
+      denyWrite: [],
+      denyRead: [],
+    },
+    network: {
+      allowedDomains: [],
+      allowManagedDomainsOnly: false,
+    },
+    excludedCommands: [],
+    allowUnsandboxedCommands: true,
+  };
+}