@intutic/cli 1.9.0 → 1.10.1

package/dist/lib/proxyBinary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxyBinary.js","sourceRoot":"","sources":["../../src/lib/proxyBinary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,SAAS,MAAM,WAAW,CAAA;AACtC,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,MAAM,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAAwB,CAAA;AAE/F;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;IACtD,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,iBAAiB,OAAO,GAAG,GAAG,EAAE,CAAC,CAAA;IAC1F,OAAO,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAA;AACzD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB;IAChC,OAAO,gBAAgB,EAAE,IAAI,eAAe,CAAA;AAC9C,CAAC"}

package/dist/lib/sandbox/firecracker.d.ts

@@ -0,0 +1,89 @@
+/**
+ * FirecrackerBackend — VM-grade isolation via a Firecracker microVM (LLD #63 §6,
+ * Increment 4). Same `SandboxBackend` interface as the container backend; the
+ * difference is the boundary: a separate guest kernel over KVM rather than
+ * shared-kernel namespaces.
+ *
+ * The egress model is identical in spirit — the microVM's only route out is the
+ * governing proxy — but enforced on the *host* side, by a default-deny firewall
+ * on the guest's tap interface (the L2 rule shape, scoped to the guest's
+ * source address). That keeps the enforcement outside the guest, where the
+ * agent cannot touch it, which is stronger than the in-container firewall.
+ *
+ * Honesty status (see LLD #63 §7 + TECH_DEBT): the microVM *boots on real KVM*
+ * — validated on a GCE nested-virt host, where Firecracker loaded and ran the
+ * guest kernel through this exact config + API sequence (the launch script this
+ * backend invokes). What is NOT yet validated end-to-end is an agent running to
+ * completion *inside* a fully-booted guest: that needs a matched
+ * kernel+rootfs pair the operator supplies (as an OCI sandbox needs an image
+ * containing the agent). `health()` therefore gates on KVM + the firecracker
+ * binary + the operator-supplied kernel/rootfs, and refuses rather than
+ * pretend — it never falls back to a weaker backend.
+ *
+ * @module
+ */
+import type { SandboxBackend, SandboxHealth, SandboxSpec } from './types.js';
+/** Firecracker-specific inputs, beyond the generic SandboxSpec. */
+export interface FirecrackerOptions {
+    /** Guest kernel image (vmlinux). Operator-supplied. */
+    kernelPath: string;
+    /** Root filesystem image (ext4). Operator-supplied, must contain the agent. */
+    rootfsPath: string;
+    /** Host tap device name. */
+    tapDevice: string;
+    /** Guest IP on the point-to-point tap link. */
+    guestIp: string;
+    /** Host IP on the tap link — the address the guest reaches the proxy at. */
+    hostIp: string;
+    /** Netmask (prefix length) for the tap link. */
+    prefixLen: number;
+    vcpus: number;
+    memMib: number;
+}
+/** The Firecracker VM configuration, as `firecracker --config-file` consumes. */
+export interface FirecrackerConfig {
+    'boot-source': {
+        kernel_image_path: string;
+        boot_args: string;
+    };
+    drives: Array<{
+        drive_id: string;
+        path_on_host: string;
+        is_root_device: boolean;
+        is_read_only: boolean;
+    }>;
+    'network-interfaces': Array<{
+        iface_id: string;
+        host_dev_name: string;
+    }>;
+    'machine-config': {
+        vcpu_count: number;
+        mem_size_mib: number;
+    };
+}
+/**
+ * Build the Firecracker VM config. Pure and exported so the exact boot config
+ * — the one proven to boot a guest kernel on KVM — is asserted without a VM.
+ *
+ * The boot args are load-bearing: `root=/dev/vda rw` (the rootfs is the first
+ * virtio-blk device) and the kernel `ip=` directive that configures the guest's
+ * eth0 on the point-to-point tap link so its only reachable peer is the host.
+ */
+export declare function buildFirecrackerConfig(opts: FirecrackerOptions): FirecrackerConfig;
+/** Dotted-quad netmask for a prefix length (IPv4). */
+export declare function prefixToNetmask(prefix: number): string;
+export declare class FirecrackerBackend implements SandboxBackend {
+    readonly name = "firecracker";
+    private readonly opts;
+    private readonly env;
+    constructor(opts: FirecrackerOptions, env: Record<string, string>);
+    /**
+     * Available only where a microVM can actually run: KVM present, the
+     * firecracker binary on PATH, and the operator's kernel + rootfs readable.
+     * Any of these missing → unavailable, and the caller refuses rather than
+     * downgrade (the honesty rule).
+     */
+    health(): Promise<SandboxHealth>;
+    run(spec: SandboxSpec): Promise<number>;
+}
+//# sourceMappingURL=firecracker.d.ts.map

package/dist/lib/sandbox/firecracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firecracker.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/firecracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE5E,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE;QAAE,iBAAiB,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D,MAAM,EAAE,KAAK,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAA;QAChB,YAAY,EAAE,MAAM,CAAA;QACpB,cAAc,EAAE,OAAO,CAAA;QACvB,YAAY,EAAE,OAAO,CAAA;KACtB,CAAC,CAAA;IACF,oBAAoB,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxE,gBAAgB,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;CAC/D;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,CAkBlF;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD;AASD,qBAAa,kBAAmB,YAAW,cAAc;IACvD,QAAQ,CAAC,IAAI,iBAAgB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;gBAEhC,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAKjE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;IAiBhC,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAoC9C"}

package/dist/lib/sandbox/firecracker.js

@@ -0,0 +1,135 @@
+/**
+ * FirecrackerBackend — VM-grade isolation via a Firecracker microVM (LLD #63 §6,
+ * Increment 4). Same `SandboxBackend` interface as the container backend; the
+ * difference is the boundary: a separate guest kernel over KVM rather than
+ * shared-kernel namespaces.
+ *
+ * The egress model is identical in spirit — the microVM's only route out is the
+ * governing proxy — but enforced on the *host* side, by a default-deny firewall
+ * on the guest's tap interface (the L2 rule shape, scoped to the guest's
+ * source address). That keeps the enforcement outside the guest, where the
+ * agent cannot touch it, which is stronger than the in-container firewall.
+ *
+ * Honesty status (see LLD #63 §7 + TECH_DEBT): the microVM *boots on real KVM*
+ * — validated on a GCE nested-virt host, where Firecracker loaded and ran the
+ * guest kernel through this exact config + API sequence (the launch script this
+ * backend invokes). What is NOT yet validated end-to-end is an agent running to
+ * completion *inside* a fully-booted guest: that needs a matched
+ * kernel+rootfs pair the operator supplies (as an OCI sandbox needs an image
+ * containing the agent). `health()` therefore gates on KVM + the firecracker
+ * binary + the operator-supplied kernel/rootfs, and refuses rather than
+ * pretend — it never falls back to a weaker backend.
+ *
+ * @module
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import { log } from '../logger.js';
+import { binaryOnPath } from '../binaryOnPath.js';
+/**
+ * Build the Firecracker VM config. Pure and exported so the exact boot config
+ * — the one proven to boot a guest kernel on KVM — is asserted without a VM.
+ *
+ * The boot args are load-bearing: `root=/dev/vda rw` (the rootfs is the first
+ * virtio-blk device) and the kernel `ip=` directive that configures the guest's
+ * eth0 on the point-to-point tap link so its only reachable peer is the host.
+ */
+export function buildFirecrackerConfig(opts) {
+    const netmask = prefixToNetmask(opts.prefixLen);
+    const bootArgs = 'console=ttyS0 reboot=k panic=1 pci=off root=/dev/vda rw ' +
+        `ip=${opts.guestIp}::${opts.hostIp}:${netmask}::eth0:off`;
+    return {
+        'boot-source': { kernel_image_path: opts.kernelPath, boot_args: bootArgs },
+        drives: [
+            {
+                drive_id: 'rootfs',
+                path_on_host: opts.rootfsPath,
+                is_root_device: true,
+                is_read_only: false,
+            },
+        ],
+        'network-interfaces': [{ iface_id: 'eth0', host_dev_name: opts.tapDevice }],
+        'machine-config': { vcpu_count: opts.vcpus, mem_size_mib: opts.memMib },
+    };
+}
+/** Dotted-quad netmask for a prefix length (IPv4). */
+export function prefixToNetmask(prefix) {
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    return [24, 16, 8, 0].map((s) => (mask >>> s) & 0xff).join('.');
+}
+/** Path to the validated launch script shipped with the CLI. */
+function launchScriptPath() {
+    // dist layout: dist/lib/sandbox/firecracker.js → ../../../resources/…
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, '../../../resources/sandbox/firecracker-launch.sh');
+}
+export class FirecrackerBackend {
+    name = 'firecracker';
+    opts;
+    env;
+    constructor(opts, env) {
+        this.opts = opts;
+        this.env = env;
+    }
+    /**
+     * Available only where a microVM can actually run: KVM present, the
+     * firecracker binary on PATH, and the operator's kernel + rootfs readable.
+     * Any of these missing → unavailable, and the caller refuses rather than
+     * downgrade (the honesty rule).
+     */
+    async health() {
+        if (!existsSync('/dev/kvm')) {
+            return { available: false, detail: 'no /dev/kvm (needs a KVM host; nested-virt on Intel)' };
+        }
+        if (!existsSync(this.opts.kernelPath)) {
+            return { available: false, detail: `guest kernel not found: ${this.opts.kernelPath}` };
+        }
+        if (!existsSync(this.opts.rootfsPath)) {
+            return { available: false, detail: `guest rootfs not found: ${this.opts.rootfsPath}` };
+        }
+        const hasBinary = await binaryOnPath('firecracker');
+        if (!hasBinary) {
+            return { available: false, detail: 'firecracker binary not on PATH' };
+        }
+        return { available: true, detail: 'kvm + firecracker + kernel + rootfs present' };
+    }
+    async run(spec) {
+        // The launch script is the artifact validated on real KVM: it sets up the
+        // tap, installs the host-side default-deny egress firewall for the guest,
+        // boots the microVM with the config above, runs the agent command in the
+        // guest, and tears everything down. run() is a thin, faithful invoker of it
+        // so the shipped boot path is exactly the proven one.
+        const script = launchScriptPath();
+        if (!existsSync(script)) {
+            log.error(`firecracker launch script missing: ${script}`);
+            return 1;
+        }
+        const args = [
+            script,
+            '--kernel', this.opts.kernelPath,
+            '--rootfs', this.opts.rootfsPath,
+            '--tap', this.opts.tapDevice,
+            '--guest-ip', this.opts.guestIp,
+            '--host-ip', this.opts.hostIp,
+            '--prefix', String(this.opts.prefixLen),
+            '--vcpus', String(this.opts.vcpus),
+            '--mem', String(this.opts.memMib),
+            '--allow', spec.allowCidrs.join(','),
+            '--', ...spec.command,
+        ];
+        return new Promise((resolve) => {
+            const child = spawn('bash', args, {
+                stdio: 'inherit',
+                env: { ...process.env, ...this.env },
+            });
+            child.on('error', (err) => {
+                log.error(`firecracker launch failed: ${err.message}`);
+                resolve(127);
+            });
+            child.on('exit', (code, signal) => resolve(signal ? 128 : (code ?? 0)));
+        });
+    }
+}
+//# sourceMappingURL=firecracker.js.map

package/dist/lib/sandbox/firecracker.js.map

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

package/dist/lib/sandbox/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sandbox backend selection (LLD #63 §6).
+ *
+ * Picks the requested backend, or the best available one. The honesty rule:
+ * a backend whose `health()` is false is never silently swapped for a weaker
+ * one — the caller is told what is unavailable and why, and can decide.
+ *
+ * @module
+ */
+import { type FirecrackerOptions } from './firecracker.js';
+import { OciBackend, type OciRuntime } from './oci.js';
+import type { SandboxBackend } from './types.js';
+export * from './types.js';
+export { buildOciArgs, OciBackend } from './oci.js';
+export { buildFirecrackerConfig, FirecrackerBackend } from './firecracker.js';
+export type SandboxKind = 'oci' | 'firecracker';
+/**
+ * Resolve a container backend, preferring docker then podman. `env` holds the
+ * values the runtime will read for `--env NAME` references (proxy vars, keys).
+ */
+export declare function ociBackend(env: Record<string, string>, runtime?: OciRuntime): OciBackend;
+/**
+ * Firecracker options from env, with defaults. The kernel + rootfs are
+ * operator-supplied (INTUTIC_FC_KERNEL / INTUTIC_FC_ROOTFS), like an OCI image
+ * is operator-supplied — the backend's `health()` refuses if they are missing.
+ */
+export declare function firecrackerOptionsFromEnv(env?: NodeJS.ProcessEnv): FirecrackerOptions;
+/**
+ * Select a backend by kind. Both backends gate on their own `health()`; the
+ * caller refuses when a backend is unavailable rather than downgrading to a
+ * weaker one (the honesty rule, LLD #63 §6).
+ */
+export declare function selectBackend(kind: SandboxKind, env: Record<string, string>, runtime?: OciRuntime): SandboxBackend;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/sandbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE7E,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,aAAa,CAAA;AAE/C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAExF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAWlG;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,UAAU,GACnB,cAAc,CAShB"}

package/dist/lib/sandbox/index.js

@@ -0,0 +1,54 @@
+/**
+ * Sandbox backend selection (LLD #63 §6).
+ *
+ * Picks the requested backend, or the best available one. The honesty rule:
+ * a backend whose `health()` is false is never silently swapped for a weaker
+ * one — the caller is told what is unavailable and why, and can decide.
+ *
+ * @module
+ */
+import { FirecrackerBackend } from './firecracker.js';
+import { OciBackend } from './oci.js';
+export * from './types.js';
+export { buildOciArgs, OciBackend } from './oci.js';
+export { buildFirecrackerConfig, FirecrackerBackend } from './firecracker.js';
+/**
+ * Resolve a container backend, preferring docker then podman. `env` holds the
+ * values the runtime will read for `--env NAME` references (proxy vars, keys).
+ */
+export function ociBackend(env, runtime) {
+    return new OciBackend(runtime ?? 'docker', env);
+}
+/**
+ * Firecracker options from env, with defaults. The kernel + rootfs are
+ * operator-supplied (INTUTIC_FC_KERNEL / INTUTIC_FC_ROOTFS), like an OCI image
+ * is operator-supplied — the backend's `health()` refuses if they are missing.
+ */
+export function firecrackerOptionsFromEnv(env = process.env) {
+    return {
+        kernelPath: env.INTUTIC_FC_KERNEL ?? '',
+        rootfsPath: env.INTUTIC_FC_ROOTFS ?? '',
+        tapDevice: env.INTUTIC_FC_TAP ?? 'tap-intutic',
+        guestIp: env.INTUTIC_FC_GUEST_IP ?? '172.16.0.2',
+        hostIp: env.INTUTIC_FC_HOST_IP ?? '172.16.0.1',
+        prefixLen: Number.parseInt(env.INTUTIC_FC_PREFIX ?? '30', 10),
+        vcpus: Number.parseInt(env.INTUTIC_FC_VCPUS ?? '1', 10),
+        memMib: Number.parseInt(env.INTUTIC_FC_MEM ?? '512', 10),
+    };
+}
+/**
+ * Select a backend by kind. Both backends gate on their own `health()`; the
+ * caller refuses when a backend is unavailable rather than downgrading to a
+ * weaker one (the honesty rule, LLD #63 §6).
+ */
+export function selectBackend(kind, env, runtime) {
+    switch (kind) {
+        case 'oci':
+            return ociBackend(env, runtime);
+        case 'firecracker':
+            return new FirecrackerBackend(firecrackerOptionsFromEnv(), env);
+        default:
+            throw new Error(`unknown sandbox backend '${kind}'`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/sandbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAA2B,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EAAE,UAAU,EAAmB,MAAM,UAAU,CAAA;AAGtD,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAI7E;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAA2B,EAAE,OAAoB;IAC1E,OAAO,IAAI,UAAU,CAAC,OAAO,IAAI,QAAQ,EAAE,GAAG,CAAC,CAAA;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC5E,OAAO;QACL,UAAU,EAAE,GAAG,CAAC,iBAAiB,IAAI,EAAE;QACvC,UAAU,EAAE,GAAG,CAAC,iBAAiB,IAAI,EAAE;QACvC,SAAS,EAAE,GAAG,CAAC,cAAc,IAAI,aAAa;QAC9C,OAAO,EAAE,GAAG,CAAC,mBAAmB,IAAI,YAAY;QAChD,MAAM,EAAE,GAAG,CAAC,kBAAkB,IAAI,YAAY;QAC9C,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,iBAAiB,IAAI,IAAI,EAAE,EAAE,CAAC;QAC7D,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,gBAAgB,IAAI,GAAG,EAAE,EAAE,CAAC;QACvD,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,IAAI,KAAK,EAAE,EAAE,CAAC;KACzD,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAiB,EACjB,GAA2B,EAC3B,OAAoB;IAEpB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,KAAK;YACR,OAAO,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QACjC,KAAK,aAAa;YAChB,OAAO,IAAI,kBAAkB,CAAC,yBAAyB,EAAE,EAAE,GAAG,CAAC,CAAA;QACjE;YACE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAc,GAAG,CAAC,CAAA;IAClE,CAAC;AACH,CAAC"}

package/dist/lib/sandbox/oci.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OciBackend — a genuinely-isolating container sandbox (LLD #63 §6).
+ *
+ * The isolation envelope, and why each piece is here:
+ *   --cap-drop=ALL                 start from zero capabilities
+ *   --cap-add NET_ADMIN,NET_RAW    the entrypoint needs them to install nft…
+ *   --cap-add SETPCAP,SETUID,SETGID …and to drop those + switch user, after
+ *                                  which the agent runs with an EMPTY cap set
+ *   --security-opt no-new-privileges  no setuid-root escalation
+ *   --read-only + tmpfs            immutable rootfs; scratch space in tmpfs
+ *   --pids-limit/--memory/--cpus   fork-bomb / resource-exhaustion bounds
+ *   --add-host host.docker.internal:host-gateway  reach the proxy on the host
+ *   -v <workdir>:/work             the project, the one writable mount
+ *
+ * The entrypoint (resources/sandbox/entrypoint.sh) then default-denies egress
+ * to everything except the proxy + DNS and drops privilege, so the agent cannot
+ * reach the network except through governance and cannot undo the firewall.
+ *
+ * @module
+ */
+import type { SandboxBackend, SandboxHealth, SandboxSpec } from './types.js';
+export type OciRuntime = 'docker' | 'podman';
+/**
+ * Build the container runtime argv for a spec. Pure and exported so the
+ * envelope can be asserted without launching anything — the isolation flags are
+ * security-load-bearing and must not silently drift.
+ */
+export declare function buildOciArgs(runtime: OciRuntime, spec: SandboxSpec): string[];
+export declare class OciBackend implements SandboxBackend {
+    readonly name: string;
+    private readonly runtime;
+    /** Env values to hand the runtime process (referenced by name in argv). */
+    private readonly env;
+    constructor(runtime: OciRuntime, env: Record<string, string>);
+    health(): Promise<SandboxHealth>;
+    run(spec: SandboxSpec): Promise<number>;
+}
+//# sourceMappingURL=oci.d.ts.map

package/dist/lib/sandbox/oci.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oci.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/oci.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE5E,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE5C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CAoC7E;AAED,qBAAa,UAAW,YAAW,cAAc;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;gBAEhC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMtD,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;IAgBhC,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAuB9C"}

package/dist/lib/sandbox/oci.js

@@ -0,0 +1,108 @@
+/**
+ * OciBackend — a genuinely-isolating container sandbox (LLD #63 §6).
+ *
+ * The isolation envelope, and why each piece is here:
+ *   --cap-drop=ALL                 start from zero capabilities
+ *   --cap-add NET_ADMIN,NET_RAW    the entrypoint needs them to install nft…
+ *   --cap-add SETPCAP,SETUID,SETGID …and to drop those + switch user, after
+ *                                  which the agent runs with an EMPTY cap set
+ *   --security-opt no-new-privileges  no setuid-root escalation
+ *   --read-only + tmpfs            immutable rootfs; scratch space in tmpfs
+ *   --pids-limit/--memory/--cpus   fork-bomb / resource-exhaustion bounds
+ *   --add-host host.docker.internal:host-gateway  reach the proxy on the host
+ *   -v <workdir>:/work             the project, the one writable mount
+ *
+ * The entrypoint (resources/sandbox/entrypoint.sh) then default-denies egress
+ * to everything except the proxy + DNS and drops privilege, so the agent cannot
+ * reach the network except through governance and cannot undo the firewall.
+ *
+ * @module
+ */
+import { spawn } from 'node:child_process';
+import { log } from '../logger.js';
+/**
+ * Build the container runtime argv for a spec. Pure and exported so the
+ * envelope can be asserted without launching anything — the isolation flags are
+ * security-load-bearing and must not silently drift.
+ */
+export function buildOciArgs(runtime, spec) {
+    const args = ['run', '--rm'];
+    // -i always (pipe stdin); -t only when we have a real terminal.
+    args.push(spec.tty ? '-it' : '-i');
+    // Capability envelope: drop everything, add back only what the entrypoint
+    // needs to install the firewall and drop privilege.
+    args.push('--cap-drop=ALL');
+    for (const cap of ['NET_ADMIN', 'NET_RAW', 'SETPCAP', 'SETUID', 'SETGID']) {
+        args.push(`--cap-add=${cap}`);
+    }
+    args.push('--security-opt=no-new-privileges');
+    // Immutable rootfs with writable scratch.
+    args.push('--read-only');
+    for (const t of ['/tmp', '/run', '/home/sandbox'])
+        args.push('--tmpfs', t);
+    // Resource bounds.
+    args.push(`--pids-limit=${spec.pidsLimit}`);
+    args.push(`--memory=${spec.memory}`);
+    args.push(`--cpus=${spec.cpus}`);
+    // Reach the proxy on the host.
+    args.push(`--add-host=${spec.proxyHostAlias}:host-gateway`);
+    // The project, read-write; nothing else from the host.
+    args.push('-v', `${spec.workdir}:/work`, '-w', '/work');
+    // Env by name — values come from the launcher's environment at spawn time, so
+    // secrets never land in argv.
+    for (const key of spec.envKeys)
+        args.push('--env', key);
+    args.push(spec.image);
+    // The entrypoint consumes a leading `--` then execs the rest.
+    args.push('--', ...spec.command);
+    return args;
+}
+export class OciBackend {
+    name;
+    runtime;
+    /** Env values to hand the runtime process (referenced by name in argv). */
+    env;
+    constructor(runtime, env) {
+        this.runtime = runtime;
+        this.name = runtime;
+        this.env = env;
+    }
+    async health() {
+        return new Promise((resolve) => {
+            const child = spawn(this.runtime, ['info', '--format', '{{.ServerVersion}}'], {
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            child.on('error', () => resolve({ available: false, detail: `${this.runtime} not found on PATH` }));
+            child.on('exit', (code) => code === 0
+                ? resolve({ available: true, detail: `${this.runtime} daemon reachable` })
+                : resolve({ available: false, detail: `${this.runtime} daemon not reachable` }));
+        });
+    }
+    async run(spec) {
+        const args = buildOciArgs(this.runtime, spec);
+        log.dim(`sandbox: ${this.runtime} ${args.slice(0, 12).join(' ')} …`);
+        return new Promise((resolve) => {
+            const child = spawn(this.runtime, args, {
+                stdio: 'inherit',
+                // Values for the `--env NAME` references live here, not in argv.
+                env: { ...process.env, ...this.env },
+            });
+            child.on('error', (err) => {
+                if (err.code === 'ENOENT') {
+                    log.error(`Sandbox runtime '${this.runtime}' not found. Install Docker or Podman.`);
+                }
+                else {
+                    log.error(`Sandbox failed to start: ${err.message}`);
+                }
+                resolve(127);
+            });
+            child.on('exit', (code, signal) => {
+                if (signal)
+                    resolve(128);
+                else
+                    resolve(code ?? 0);
+            });
+        });
+    }
+}
+//# sourceMappingURL=oci.js.map

package/dist/lib/sandbox/oci.js.map

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

package/dist/lib/sandbox/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Sandbox runtime abstraction (LLD #63 §6).
+ *
+ * A `SandboxBackend` launches an agent command inside an isolated runtime whose
+ * *only* egress is the governing proxy — unifying "isolate the process" with
+ * "force traffic through governance". The container backend ships today; the
+ * Firecracker microVM backend implements the same interface (Increment 4).
+ *
+ * @module
+ */
+/** What to run, and the isolation envelope to run it in. */
+export interface SandboxSpec {
+    /** The agent command + args, e.g. ['claude'] or ['python', 'agent.py']. */
+    command: string[];
+    /** Host directory bind-mounted read-write at /work (the project). */
+    workdir: string;
+    /** Container image. Must contain the agent + nftables + capsh. */
+    image: string;
+    /**
+     * Environment for the sandboxed process, by name. Values are read from the
+     * launcher's own environment at spawn time and referenced by name on the
+     * command line, so secrets (API keys) never appear in argv / `docker inspect`.
+     */
+    envKeys: string[];
+    /** Hostname the sandbox reaches the proxy at (mapped to the host gateway). */
+    proxyHostAlias: string;
+    /** Extra destination CIDRs the sandbox may reach, beyond the proxy + DNS. */
+    allowCidrs: string[];
+    /** Hard resource caps. */
+    memory: string;
+    cpus: string;
+    pidsLimit: number;
+    /** Allocate a TTY (interactive agents). */
+    tty: boolean;
+}
+/** Health of a backend on this host. */
+export interface SandboxHealth {
+    available: boolean;
+    detail: string;
+}
+export interface SandboxBackend {
+    readonly name: string;
+    /** Whether this backend can run here (e.g. docker reachable, KVM present). */
+    health(): Promise<SandboxHealth>;
+    /** Launch the spec; resolves with the process exit code. */
+    run(spec: SandboxSpec): Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/sandbox/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAA;IACtB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAA;CACb;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAChC,4DAA4D;IAC5D,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACxC"}

package/dist/lib/sandbox/types.js

@@ -0,0 +1,12 @@
+/**
+ * Sandbox runtime abstraction (LLD #63 §6).
+ *
+ * A `SandboxBackend` launches an agent command inside an isolated runtime whose
+ * *only* egress is the governing proxy — unifying "isolate the process" with
+ * "force traffic through governance". The container backend ships today; the
+ * Firecracker microVM backend implements the same interface (Increment 4).
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/sandbox/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/sandbox/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/lib/sopFrontMatter.d.ts

@@ -0,0 +1,50 @@
+export type SopRiskTier = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export interface ParsedSopFile {
+    /** From a `title:` front-matter key, else the file's first `# ` heading, else `null` — the caller falls back to the file name. */
+    title: string | null;
+    /** From a `risk_tier:` key, case-insensitively; `null` if unstated or unrecognised — never guessed. */
+    riskTier: SopRiskTier | null;
+    /** From a `version:` key; `null` if unstated. */
+    version: string | null;
+    /**
+     * From a `content_hash:` key — `intutic sops pull`'s own dirty-check
+     * marker, recording the body hash at the moment it wrote the file. `null`
+     * for a file `pull` never wrote (hand-authored, or pushed but not pulled).
+     */
+    contentHash: string | null;
+    /** Everything after the front-matter fence, or the whole trimmed input when there is none. */
+    body: string;
+}
+export declare function parseSopFile(raw: string): ParsedSopFile;
+/**
+ * Render a pulled SOP back into a front-matter-carrying file, with
+ * `content_hash:` recording `sha256(body)` at write time — the marker
+ * `runSopsPull` compares against on a later pull to tell "the DB changed
+ * upstream" (safe to overwrite) from "a human hand-edited this file since
+ * the last pull" (refuse without `--force`).
+ */
+export declare function renderSopFile(sop: {
+    title: string;
+    riskTier: string;
+    version: string;
+    body: string;
+}): string;
+/** `Deploy Checklist` / `deploy checklist!!` → `deploy-checklist`. */
+export declare function slugifyTitle(title: string): string;
+/** `postgres-migration` → `Postgres Migration`; `deploy_checklist.md` → `Deploy Checklist`. */
+export declare function titleFromFileName(fileName: string): string;
+/**
+ * Add `intutic sops pull`'s `content_hash:` marker to a file that already
+ * carries its own front matter — a projected guardrail, whose fence holds
+ * the enforcing keys the proxy reads (LLD #71, Wave 9).
+ *
+ * Not `renderSopFile`: that wraps a second fence around the text, and the
+ * proxy reads only the first, so the enforcing keys would become body prose
+ * and the rule would load, be listed, and never fire. The marker goes INSIDE
+ * the existing fence, as the last line before it closes; the hash is over
+ * what `parseSopFile` will read back as `body`, so the dirty check is the
+ * same one `sops pull` runs. A file with no fence gets one holding only the
+ * marker. Unknown keys are inert to the proxy, so enforcement is unchanged.
+ */
+export declare function withContentHash(raw: string): string;
+//# sourceMappingURL=sopFrontMatter.d.ts.map

package/dist/lib/sopFrontMatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sopFrontMatter.d.ts","sourceRoot":"","sources":["../../src/lib/sopFrontMatter.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAIhE,MAAM,WAAW,aAAa;IAC5B,kIAAkI;IAClI,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,uGAAuG;IACvG,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;IAC5B,iDAAiD;IACjD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAA;CACb;AAaD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAkCvD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb,GAAG,MAAM,CAaT;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAcnD"}