vigiles 2.4.0 → 2.6.0

package/dist/run-hook.d.ts

@@ -1,3 +1,5 @@
+import { type SandboxMode, type EgressAttempt } from "./sandbox.js";
+export type { EgressAttempt };
 /** A hook event payload (the JSON Claude Code writes to the hook's stdin). */
 export interface HookInput {
     /** e.g. "PreToolUse", "PostToolUse", "Stop", "SessionStart", "PreCompact". */
@@ -38,6 +40,41 @@ export interface RunHookOptions {
     readonly env?: Record<string, string>;
     /** Per-run timeout ms. Default 10000. */
     readonly timeoutMs?: number;
+    /**
+     * Provenance of the hook command. `true` (default) means YOU authored it — the
+     * usual case at this tier, a command written inline in the test — so it runs
+     * directly. `false` marks it foreign (a vendored third-party hook script),
+     * which makes confinement the DEFAULT: with no explicit `sandbox`, an untrusted
+     * hook behaves as `sandbox: "auto"` — confined under bubblewrap, or refused if
+     * none is available — so foreign code is never run unconfined by accident. This
+     * mirrors the harness tier, where trust follows `plugin`/`pluginDir`
+     * provenance (`specTrusted` in `src/sandbox.ts`); the unit tier takes a raw
+     * command string with no provenance signal, so you declare it here.
+     */
+    readonly trusted?: boolean;
+    /**
+     * Confine the hook under bubblewrap (Linux). When unset, the mode follows
+     * {@link RunHookOptions.trusted}: a trusted hook runs directly (`false`), an
+     * untrusted one is confined-or-refused (`"auto"`). Set it explicitly to
+     * override: `"auto"`/`"strict"` force confinement (a no-egress namespace with a
+     * cleared environment — your `opts.env` is added back — or a **refusal** if no
+     * bwrap is available), and `false` is the opt-out that runs even untrusted code
+     * unconfined. macOS/Windows have no bwrap, so `"auto"`/`"strict"` throw there —
+     * see `src/sandbox.ts`.
+     */
+    readonly sandbox?: SandboxMode;
+    /**
+     * Record the hook's network egress. Implies confinement (the recorder lives in
+     * the sandbox netns, so this forces a sandboxed run and refuses if no sandbox is
+     * available). A recording proxy on loopback captures every `host:port` a
+     * proxy-honoring tool (npm/pip/curl/fetch) tries to reach — surfaced as
+     * {@link HookRunResult.egress} — while the netns still **blocks** it (nothing
+     * actually leaves). Use it to test what a hook/skill phones home to, or which
+     * registry an install would hit. Raw-socket egress is blocked but not recorded
+     * (it never reaches the proxy) — the block is the boundary, the record is
+     * best-effort observability over it.
+     */
+    readonly recordEgress?: boolean;
 }
 export interface HookRunResult {
     readonly exitCode: number;
@@ -50,6 +87,17 @@ export interface HookRunResult {
      * `permissionDecision:"deny"` all set `blocked = true`.
      */
     readonly blocked: boolean;
+    /**
+     * Network egress the hook attempted, recorded then blocked. Empty unless
+     * {@link RunHookOptions.recordEgress} was set (and the run was confined).
+     */
+    readonly egress: readonly EgressAttempt[];
+    /**
+     * Files the hook wrote to its work dir (relative paths), recorded on confined
+     * runs — what a hook touched on disk. Empty on a direct (unconfined) run.
+     * Assert over it with `assertNoWrite` / `assertWroteOnly`.
+     */
+    readonly filesWritten: readonly string[];
     /**
      * The decision the hook expressed, preferring the structured
      * `permissionDecision` ("allow"|"deny"|"ask") then legacy `decision`
@@ -67,11 +115,43 @@ export declare function decideHook(exitCode: number, json: HookOutput | null): {
     blocked: boolean;
     decision: HookRunResult["decision"];
 };
+/** The raw fields of a hook spawn that the result parser needs. */
+export interface HookSpawnResult {
+    readonly status: number | null;
+    readonly signal: string | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** Egress attempts captured by the in-sandbox recorder (recordEgress only). */
+    readonly egress?: readonly EgressAttempt[];
+    /** Files the hook wrote to its work dir (confined runs). */
+    readonly filesWritten?: readonly string[];
+}
+/** Spawn a hook (command + piped event) — the injectable seam over the real spawn. */
+export type HookSpawner = (command: string, input: HookInput, opts: RunHookOptions) => HookSpawnResult;
+/** The spawn seams `runHookWith` needs, so its decision logic is testable. */
+export interface RunHookDeps {
+    /** Whether bubblewrap confinement is available (Linux + bwrap). */
+    readonly available: boolean;
+    /** Run the command directly (unconfined). */
+    readonly direct: HookSpawner;
+    /** Run the command confined under bubblewrap. */
+    readonly sandboxed: HookSpawner;
+}
+/**
+ * The hook-run orchestration with injectable spawn seams: pick direct vs.
+ * confined via the safe-by-default policy (`decideSandbox`), then parse the exit
+ * code + stdout into a normalized decision. Exported so all three branches
+ * (direct / sandbox / refuse) are unit-tested with fake spawners — no real
+ * bwrap. `runHook` is this with the real seams.
+ */
+export declare function runHookWith(command: string, input: HookInput, opts: RunHookOptions, deps: RunHookDeps): HookRunResult;
 /**
  * Run a hook command, piping `input` as JSON to its stdin, and report the exit
  * code + parsed decision. Synchronous (so it can be used inside an eval's
  * `measure` too). `command` is run through a shell, so the same command string a
- * plugin ships (with args / env refs) works verbatim.
+ * plugin ships (with args / env refs) works verbatim. Mark a hook you didn't
+ * write with `trusted: false` and it is confined by default (or pass `sandbox:
+ * "auto"` directly) — see {@link RunHookOptions.trusted}.
  */
 export declare function runHook(command: string, input: HookInput, opts?: RunHookOptions): HookRunResult;
 //# sourceMappingURL=run-hook.d.ts.map

package/dist/run-hook.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseHookOutput = parseHookOutput;
 exports.decideHook = decideHook;
+exports.runHookWith = runHookWith;
 exports.runHook = runHook;
 /**
  * vigiles — the *unit* tier for Claude Code hooks.
@@ -33,6 +34,10 @@ exports.runHook = runHook;
  * logic here, then assert it fires in the assembled machine there.
  */
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const sandbox_js_1 = require("./sandbox.js");
 /** Parse stdout as a hook JSON decision (pure, testable without a process). */
 function parseHookOutput(stdout) {
     const s = stdout.trim();
@@ -56,12 +61,50 @@ function decideHook(exitCode, json) {
     return { blocked, decision };
 }
 /**
- * Run a hook command, piping `input` as JSON to its stdin, and report the exit
- * code + parsed decision. Synchronous (so it can be used inside an eval's
- * `measure` too). `command` is run through a shell, so the same command string a
- * plugin ships (with args / env refs) works verbatim.
+ * The hook-run orchestration with injectable spawn seams: pick direct vs.
+ * confined via the safe-by-default policy (`decideSandbox`), then parse the exit
+ * code + stdout into a normalized decision. Exported so all three branches
+ * (direct / sandbox / refuse) are unit-tested with fake spawners — no real
+ * bwrap. `runHook` is this with the real seams.
  */
-function runHook(command, input, opts = {}) {
+function runHookWith(command, input, opts, deps) {
+    // Confinement follows provenance: a trusted hook (the default) runs directly;
+    // marking a hook untrusted defaults it to "auto" (confine-or-refuse), so
+    // foreign code is never run unconfined by accident. An explicit `sandbox`
+    // overrides the default either way. The trust fed to decideSandbox stays
+    // `false` at this tier — a raw command has no provenance, so an explicit
+    // "auto"/"strict" here is always a request to *confine*, not "trusted→direct".
+    // recordEgress needs the netns recorder, so it forces confinement too.
+    const mode = opts.sandbox ??
+        (opts.trusted === false || opts.recordEgress ? "auto" : false);
+    const decision = (0, sandbox_js_1.decideSandbox)({
+        trusted: false,
+        mode,
+        available: deps.available,
+    });
+    if (decision.action === "throw")
+        throw new Error(decision.reason);
+    const res = decision.action === "sandbox"
+        ? deps.sandboxed(command, input, opts)
+        : deps.direct(command, input, opts);
+    const exitCode = res.status ?? (res.signal ? 1 : 0);
+    const stdout = res.stdout ?? "";
+    const stderr = res.stderr ?? "";
+    const json = parseHookOutput(stdout);
+    const { blocked, decision: dec } = decideHook(exitCode, json);
+    return {
+        exitCode,
+        stdout,
+        stderr,
+        json,
+        blocked,
+        egress: res.egress ?? [],
+        filesWritten: res.filesWritten ?? [],
+        decision: dec,
+    };
+}
+/** Run the hook command directly through a shell (the default, unconfined). */
+function directSpawn(command, input, opts) {
     const res = (0, node_child_process_1.spawnSync)(command, {
         shell: true,
         cwd: opts.cwd,
@@ -70,11 +113,146 @@ function runHook(command, input, opts = {}) {
         encoding: "utf-8",
         timeout: opts.timeoutMs ?? 10000,
     });
-    const exitCode = res.status ?? (res.signal ? 1 : 0);
-    const stdout = res.stdout ?? "";
-    const stderr = res.stderr ?? "";
-    const json = parseHookOutput(stdout);
-    const { blocked, decision } = decideHook(exitCode, json);
-    return { exitCode, stdout, stderr, json, blocked, decision };
+    return {
+        status: res.status,
+        signal: res.signal,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+    };
+}
+/* v8 ignore start -- spawns real bwrap; exercised by the bwrap-gated integration
+   test (skipped without bwrap). The decision logic is runHookWith (unit-tested
+   with fakes); the confinement argv is bwrapArgs/setenvArgs and the egress log
+   parse is parseEgressLog (all unit-tested). */
+// When recordEgress is on: co-launch the recorder on loopback, point HTTP(S)_PROXY
+// at it, run the hook, then stop it. Paths come in via env (no shell escaping).
+const EGRESS_WRAPPER = [
+    'node "$VIG_EGRESS_ENTRY" "$VIG_EGRESS_LOG" "$VIG_EGRESS_PORT" &',
+    "EPID=$!",
+    "i=0",
+    'while [ ! -s "$VIG_EGRESS_PORT" ] && [ "$i" -lt 100 ]; do sleep 0.05; i=$((i+1)); done',
+    'export HTTP_PROXY="http://127.0.0.1:$(cat "$VIG_EGRESS_PORT")"',
+    'export HTTPS_PROXY="$HTTP_PROXY" http_proxy="$HTTP_PROXY" https_proxy="$HTTP_PROXY"',
+    // Node's fetch (undici) ignores the proxy env unless this is set — without it a
+    // hook that uses fetch() (e.g. an update check) would bypass the recorder.
+    "export NODE_USE_ENV_PROXY=1",
+    'sh -c "$VIG_HOOK_CMD"',
+    "code=$?",
+    'kill "$EPID" 2>/dev/null',
+    'exit "$code"',
+].join("\n");
+function egressProxyEntry() {
+    return ([
+        (0, node_path_1.join)(__dirname, "egress-proxy.js"),
+        (0, node_path_1.join)(__dirname, "..", "dist", "egress-proxy.js"),
+    ].find((p) => (0, node_fs_1.existsSync)(p)) ?? (0, node_path_1.join)(__dirname, "egress-proxy.js"));
+}
+/** Map every file under `dir` to a content signature (size:mtime), recursively. */
+function snapshotTree(dir) {
+    const out = {};
+    const walk = (d, rel) => {
+        for (const name of (0, node_fs_1.readdirSync)(d)) {
+            const full = (0, node_path_1.join)(d, name);
+            const r = rel ? `${rel}/${name}` : name;
+            const st = (0, node_fs_1.statSync)(full);
+            if (st.isDirectory())
+                walk(full, r);
+            else
+                out[r] = `${String(st.size)}:${String(st.mtimeMs)}`;
+        }
+    };
+    try {
+        walk(dir, "");
+    }
+    catch {
+        /* dir removed mid-walk — best effort */
+    }
+    return out;
+}
+function sandboxedSpawn(command, input, opts) {
+    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-sbx-"));
+    const home = (0, node_path_1.join)(ioDir, "home");
+    (0, node_fs_1.mkdirSync)(home);
+    // The hook's confined writable work dir: the caller's cwd if given, else a
+    // dedicated `work/` under the IO dir (kept separate from the egress log/home so
+    // those don't pollute the filesWritten diff).
+    const work = opts.cwd ?? (0, node_path_1.join)(ioDir, "work");
+    (0, node_fs_1.mkdirSync)(work, { recursive: true });
+    try {
+        const baseArgs = [
+            ...(0, sandbox_js_1.bwrapArgs)({
+                cwd: work,
+                ioDir,
+                home,
+                path: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+            }),
+            ...(0, sandbox_js_1.setenvArgs)(opts.env ?? {}),
+        ];
+        const spawnOpts = {
+            cwd: work,
+            env: process.env,
+            input: JSON.stringify(input),
+            encoding: "utf-8",
+            timeout: opts.timeoutMs ?? 10000,
+        };
+        const before = snapshotTree(work);
+        let res;
+        let egress = [];
+        if (opts.recordEgress) {
+            const egressLog = (0, node_path_1.join)(ioDir, "egress.ndjson");
+            const portFile = (0, node_path_1.join)(ioDir, "egress.port");
+            (0, node_fs_1.writeFileSync)(egressLog, "");
+            res = (0, node_child_process_1.spawnSync)("bwrap", [
+                ...baseArgs,
+                "--setenv",
+                "VIG_EGRESS_ENTRY",
+                egressProxyEntry(),
+                "--setenv",
+                "VIG_EGRESS_LOG",
+                egressLog,
+                "--setenv",
+                "VIG_EGRESS_PORT",
+                portFile,
+                "--setenv",
+                "VIG_HOOK_CMD",
+                command,
+                "sh",
+                "-c",
+                EGRESS_WRAPPER,
+            ], spawnOpts);
+            egress = (0, sandbox_js_1.parseEgressLog)((0, node_fs_1.existsSync)(egressLog) ? (0, node_fs_1.readFileSync)(egressLog, "utf-8") : "");
+        }
+        else {
+            res = (0, node_child_process_1.spawnSync)("bwrap", [...baseArgs, "sh", "-c", command], spawnOpts);
+        }
+        return {
+            status: res.status,
+            signal: res.signal,
+            stdout: res.stdout ?? "",
+            stderr: res.stderr ?? "",
+            egress,
+            filesWritten: (0, sandbox_js_1.diffTrees)(before, snapshotTree(work)),
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(ioDir, { recursive: true, force: true });
+    }
+}
+const REAL_DEPS = {
+    available: (0, sandbox_js_1.sandboxAvailable)(),
+    direct: directSpawn,
+    sandboxed: sandboxedSpawn,
+};
+/* v8 ignore stop */
+/**
+ * Run a hook command, piping `input` as JSON to its stdin, and report the exit
+ * code + parsed decision. Synchronous (so it can be used inside an eval's
+ * `measure` too). `command` is run through a shell, so the same command string a
+ * plugin ships (with args / env refs) works verbatim. Mark a hook you didn't
+ * write with `trusted: false` and it is confined by default (or pass `sandbox:
+ * "auto"` directly) — see {@link RunHookOptions.trusted}.
+ */
+function runHook(command, input, opts = {}) {
+    return runHookWith(command, input, opts, REAL_DEPS);
 }
 //# sourceMappingURL=run-hook.js.map

package/dist/sandbox.d.ts

@@ -0,0 +1,107 @@
+import { type ModelTurn, type ModelRequest } from "./mock-model.js";
+/**
+ * How to treat code execution. `"auto"` (default) is safe-by-default: trusted
+ * code runs directly, untrusted code is sandboxed if possible and otherwise
+ * refuses. `false` is the dangerous opt-out — run unconfined (you audited it, or
+ * you trust the outer container). `"strict"` forces confinement even for trusted
+ * code and throws if no sandbox is available.
+ */
+export type SandboxMode = "auto" | "strict" | false;
+/**
+ * Whether this environment can ACTUALLY confine untrusted code under bubblewrap.
+ * **Linux only.** Critically, `bwrap --version` succeeding is NOT enough: many CI
+ * runners and hardened hosts ship bubblewrap but disable the **unprivileged user
+ * namespaces** it depends on, so a real confined exec fails even though the binary
+ * is present. We probe that real capability — a throwaway `bwrap --unshare-all …
+ * true` — and cache it, so we never *claim* confinement we can't deliver.
+ * `decideSandbox` then correctly refuses untrusted code in such an environment
+ * (rather than running it in a "sandbox" that doesn't actually sandbox), and the
+ * sandbox-gated tests skip instead of failing. The result is cached because the
+ * probe spawns a process and the answer can't change within a run.
+ */
+export declare function sandboxAvailable(): boolean;
+/**
+ * Is this spec's executed code trusted? Inline `settings`/`files` you authored
+ * are trusted; any external `plugin` / `pluginDir` brings in third-party hooks
+ * and is NOT — committing it to your repo is the same trust decision as a
+ * dependency, so the trust boundary follows provenance: foreign = confined.
+ */
+export declare function specTrusted(spec: {
+    plugin?: string;
+    pluginDir?: string;
+}): boolean;
+/** The chosen action for a run: execute directly, confine it, or refuse. */
+export type SandboxDecision = {
+    readonly action: "direct";
+} | {
+    readonly action: "sandbox";
+} | {
+    readonly action: "throw";
+    readonly reason: string;
+};
+/**
+ * The pure safe-by-default policy. Untrusted code NEVER runs unconfined unless
+ * the caller explicitly opted out (`mode: false`). This is the whole security
+ * contract, isolated as a pure function so it is exhaustively unit-tested.
+ */
+export declare function decideSandbox(opts: {
+    trusted: boolean;
+    mode: SandboxMode;
+    available: boolean;
+}): SandboxDecision;
+/**
+ * The bubblewrap confinement argv (everything before the command): a fresh
+ * network namespace (`--unshare-all`, loopback-only, no egress), a read-only
+ * system, writable mounts limited to the work dir, the IO dir, and a fresh empty
+ * HOME (inside the IO dir so it needs no mountpoint on the read-only root, and so
+ * no host credentials/config leak in), and a **cleared environment** —
+ * `--clearenv` drops every host variable (API keys, cloud creds) and only PATH /
+ * HOME / TMPDIR are set back, so untrusted code can't even read your secrets.
+ * Pure, so the confinement shape is asserted in a unit test.
+ */
+export declare function bwrapArgs(opts: {
+    cwd: string;
+    ioDir: string;
+    home: string;
+    path: string;
+}): string[];
+/**
+ * `--setenv K V` pairs to add back specific variables after `--clearenv` — e.g.
+ * a hook's configured env (the `GUARD=path` a plugin's command relies on), which
+ * `bwrapArgs`' `--clearenv` would otherwise drop. Pure, so it's unit-tested.
+ */
+export declare function setenvArgs(env: Record<string, string>): string[];
+/** Parse the in-sandbox mock's ndjson request log into {@link ModelRequest}s. */
+export declare function parseRequestLog(ndjson: string): ModelRequest[];
+/** A network egress attempt a confined hook made — recorded, then blocked. */
+export interface EgressAttempt {
+    readonly host: string;
+    readonly port: number;
+    /** ms epoch when the attempt was recorded. */
+    readonly ts: number;
+}
+/**
+ * Parse the egress recorder's ndjson log into {@link EgressAttempt}s. Pure, so
+ * the record-shape and the malformed-line tolerance are unit-tested without a
+ * sandbox. A line missing host/port is skipped (a partially-flushed final line).
+ */
+export declare function parseEgressLog(ndjson: string): EgressAttempt[];
+/**
+ * The files in `after` that are new or changed vs `before` — i.e. what a confined
+ * run wrote to its work dir. Each tree maps a relative path to a content
+ * signature (size + mtime). Pure, so the diff is unit-tested without a sandbox.
+ */
+export declare function diffTrees(before: Readonly<Record<string, string>>, after: Readonly<Record<string, string>>): string[];
+/** The raw output of a sandboxed run: exit code, captured stdout, and requests. */
+export interface SandboxRunOut {
+    readonly code: number;
+    readonly stdout: string;
+    readonly requests: readonly ModelRequest[];
+}
+export declare function runSandboxed(opts: {
+    cwd: string;
+    claudeArgs: readonly string[];
+    script: readonly ModelTurn[];
+    timeoutMs: number;
+}): Promise<SandboxRunOut>;
+//# sourceMappingURL=sandbox.d.ts.map