@namzu/sandbox 1.1.0

package/dist/backends/firecracker/__tests__/transport.test.js

@@ -0,0 +1,449 @@
+/**
+ * Loopback transport round-trip tests for the Firecracker vsock path.
+ *
+ * These prove the NEW transport (host dialer ↔ in-VM agent) over a
+ * **unix-socket stand-in** — the faithful local peer for AF_VSOCK,
+ * because the production vsock path also terminates on a host
+ * unix socket (see `transport.ts` docblock). The peer is the REAL
+ * `agent/agent.cjs` connection handler (its spawn/jail + NDJSON shapes
+ * verbatim), driven in-process over a temp unix socket; the client is
+ * the REAL {@link VsockAgentTransport}. So one test exercises:
+ *   - exec → streamed stdout/stderr/result NDJSON, accumulated;
+ *   - writeFile / readFile → base64 round-trip through the jail;
+ *   - a simulated resume (server torn down + re-listened) survived by
+ *     the dialer's connect-retry budget — the FC #4713 invariant.
+ *
+ * No docker, no Azure, no AF_VSOCK kernel support required: pure
+ * loopback, safe in CI.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { createServer, connect as netConnect } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createServer as createTlsServer } from 'node:tls';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { VsockAgentTransport } from '../transport.js';
+// The agent is a CommonJS module that reads NAMZU_SANDBOX_WORKSPACE at
+// require-time. Set the env, then require it through createRequire so
+// each test file gets a fresh module bound to its own workspace dir.
+import { createRequire } from 'node:module';
+const require_ = createRequire(import.meta.url);
+let workDir;
+let sockPath;
+let server;
+let agent;
+function startAgentServer(connHandler) {
+    return new Promise((resolve, reject) => {
+        const s = createServer(connHandler);
+        s.on('error', reject);
+        s.listen(sockPath, () => resolve(s));
+    });
+}
+beforeEach(() => {
+    workDir = mkdtempSync(join(tmpdir(), 'fc-agent-test-'));
+    sockPath = join(workDir, 'agent.sock');
+    // Bind the agent's workspace jail to the temp dir BEFORE requiring it.
+    process.env.NAMZU_SANDBOX_WORKSPACE = workDir;
+    // The agent's root-normalization filters env on PRESENCE; `= undefined`
+    // sets the literal string "undefined" and would widen READ/WRITE_ROOTS, so
+    // these must be true deletes.
+    // biome-ignore lint/performance/noDelete: must remove the var, not set "undefined".
+    delete process.env.NAMZU_SANDBOX_READ_ROOTS;
+    // biome-ignore lint/performance/noDelete: must remove the var, not set "undefined".
+    delete process.env.NAMZU_SANDBOX_WRITE_ROOTS;
+    // Fresh module each test so WORKSPACE_ROOT is rebound.
+    delete require_.cache[require_.resolve('../../../../agent/agent.cjs')];
+    agent = require_('../../../../agent/agent.cjs');
+});
+afterEach(async () => {
+    if (server) {
+        await new Promise((r) => server?.close(() => r()));
+        server = undefined;
+    }
+    rmSync(workDir, { recursive: true, force: true });
+});
+describe('VsockAgentTransport over a unix-socket loopback agent', () => {
+    it('streams stdout/stderr/result NDJSON from an exec', async () => {
+        server = await startAgentServer(agent.handleConnection);
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath });
+        const r = await transport.execute({
+            command: '/bin/sh',
+            args: ['-c', 'echo out-line; echo err-line 1>&2; exit 3'],
+        });
+        expect(r.stdout).toContain('out-line');
+        expect(r.stderr).toContain('err-line');
+        expect(r.exitCode).toBe(3);
+        expect(r.timedOut).toBe(false);
+        expect(r.durationMs).toBeGreaterThanOrEqual(0);
+    });
+    it('streams a large multi-chunk stdout intact (delta accumulation)', async () => {
+        server = await startAgentServer(agent.handleConnection);
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath });
+        // 200 lines so the agent emits multiple stdout_delta frames the
+        // FrameReader must reassemble across socket chunks.
+        const r = await transport.execute({
+            command: '/bin/sh',
+            args: ['-c', 'for i in $(seq 1 200); do echo "line-$i"; done'],
+        });
+        expect(r.exitCode).toBe(0);
+        const lines = r.stdout.trim().split('\n');
+        expect(lines.length).toBe(200);
+        expect(lines[0]).toBe('line-1');
+        expect(lines[199]).toBe('line-200');
+    });
+    it('round-trips writeFile/readFile as base64 through the workspace jail', async () => {
+        server = await startAgentServer(agent.handleConnection);
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath });
+        // Binary content (non-UTF8 bytes) proves base64 fidelity, not
+        // just text.
+        const payload = Buffer.from([0x00, 0xff, 0x10, 0x42, 0x00, 0x99, 0xfe]);
+        await transport.writeFile('sub/dir/blob.bin', payload);
+        const read = await transport.readFile('sub/dir/blob.bin');
+        expect(read.equals(payload)).toBe(true);
+    });
+    it('rejects a path that escapes the workspace jail', async () => {
+        server = await startAgentServer(agent.handleConnection);
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath });
+        await expect(transport.readFile('../../../../etc/passwd')).rejects.toThrow(/escapes/);
+    });
+    it('healthz returns true against a live agent', async () => {
+        server = await startAgentServer(agent.handleConnection);
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath });
+        expect(await transport.healthz()).toBe(true);
+    });
+    it('surfaces an exec error event as a thrown error', async () => {
+        server = await startAgentServer(agent.handleConnection);
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath });
+        // Empty command name → agent emits { type: 'error' }.
+        await expect(transport.execute({ command: '' })).rejects.toThrow();
+    });
+    it('survives a simulated resume: server torn down then re-listened, dialer reconnects', async () => {
+        // 1. Agent is up; one exec succeeds.
+        server = await startAgentServer(agent.handleConnection);
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath }, 
+        // Tight retry budget so the test is fast but still proves retry.
+        { connectRetryBudgetMs: 5_000, connectRetryIntervalMs: 50, connectTimeoutMs: 1_000 });
+        const first = await transport.execute({ command: '/bin/sh', args: ['-c', 'echo before'] });
+        expect(first.stdout).toContain('before');
+        // 2. Simulate a resume: the FC vsock driver closes all connections
+        //    and the listener is gone until the agent re-LISTENs. Tear the
+        //    server down entirely.
+        await new Promise((r) => server?.close(() => r()));
+        server = undefined;
+        // 3. Kick off an exec WHILE the agent is still down. The dialer's
+        //    connect-retry budget must hold (ECONNREFUSED) until the agent
+        //    re-listens — this is the FC #4713 / TRANSPORT_RESET-not-
+        //    delivered mitigation: the host re-dials rather than hanging.
+        const pending = transport.execute({ command: '/bin/sh', args: ['-c', 'echo after'] });
+        // 4. After a beat, the agent re-establishes its listen on the SAME
+        //    address (the resume re-listen invariant).
+        await new Promise((r) => setTimeout(r, 300));
+        server = await startAgentServer(agent.handleConnection);
+        const after = await pending;
+        expect(after.stdout).toContain('after');
+        expect(after.exitCode).toBe(0);
+    });
+    it('connect-retry budget gives up with a clear error when the agent never returns', async () => {
+        // No server started at all. The dialer should exhaust its budget
+        // and throw a descriptive error rather than hang forever.
+        const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath }, { connectRetryBudgetMs: 400, connectRetryIntervalMs: 50, connectTimeoutMs: 200 });
+        await expect(transport.healthz()).resolves.toBe(false);
+        await expect(transport.readFile('x')).rejects.toThrow(/could not connect to agent/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Ring-0 mTLS arm — pure-local TLS loopback "relay" (no Azure, no FC host)
+// ---------------------------------------------------------------------------
+//
+// Proves the ADDITIVE `kind:'mtls'` transport arm without a real fleet:
+//   - a `tls.createServer` plays the per-FC-host RELAY (requestCert +
+//     rejectUnauthorized), reads the `SANDBOX <id>` routing preamble,
+//     then bridges verbatim to the SAME `agent.handleConnection` peer
+//     the vsock/unix arms use — so the IDENTICAL framing round-trips.
+//   - the dialer presents the fleet CLIENT cert and verifies the relay
+//     server cert; a WRONG-CA client is rejected at the TLS layer.
+//   - the `SANDBOX <id>` preamble is the FIRST bytes after the
+//     handshake (the relay's routing key), and the caller never writes
+//     a guest `CONNECT 1024` line (the relay issues that host-side).
+//
+// The cert material is a throwaway P-256 test PKI (CA + server leaf +
+// client leaf + an unrelated rogue client) baked in as PEM constants —
+// no openssl/forge at test time, keeping the package dependency-light.
+// Test PKI. Minted offline with: openssl ec/x509 self-signed CA + leaves
+// (server SAN = DNS:sandbox.fc.internal, IP:127.0.0.1). Far-future expiry.
+// `ROGUE_*` chains to a DIFFERENT CA to prove rejectUnauthorized blocks it.
+const CA_CRT = `-----BEGIN CERTIFICATE-----
+MIIBjjCCATWgAwIBAgIUGXUtG14KQr4spNGW7rpfjZGoBIIwCgYIKoZIzj0EAwIw
+HDEaMBgGA1UEAwwRdmFuZGFsLWZjLXRlc3QtY2EwIBcNMjYwNjE2MDgzMjUyWhgP
+MjEyNjA1MjMwODMyNTJaMBwxGjAYBgNVBAMMEXZhbmRhbC1mYy10ZXN0LWNhMFkw
+EwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5l+vjhjm/PX02D55n56EwelgvM1jrqQM
+Z+ezzvMmrZEBGWInvBND3z3kc6nv7snu6fHT2HHOyhwUNoLqmrIg/qNTMFEwHQYD
+VR0OBBYEFP0M8/KZY1ovxyGDci5iuoYXcmZgMB8GA1UdIwQYMBaAFP0M8/KZY1ov
+xyGDci5iuoYXcmZgMA8GA1UdEwEB/wQFMAMBAf8wCgYIKoZIzj0EAwIDRwAwRAIg
+C0xtFDASnwsOYT0GiZwzYWTOBfgmjDWK7ANXQQFNTh4CICVLQwq5eLy3424drEHk
+5Ol/FNKVZcGRjE96rB0mRUOp
+-----END CERTIFICATE-----
+`;
+const SERVER_CRT = `-----BEGIN CERTIFICATE-----
+MIIBsDCCAVWgAwIBAgIUYkXroqlz9blXW8llis6e2OxOc1MwCgYIKoZIzj0EAwIw
+HDEaMBgGA1UEAwwRdmFuZGFsLWZjLXRlc3QtY2EwIBcNMjYwNjE2MDgzMjUyWhgP
+MjEyNjA1MjMwODMyNTJaMBIxEDAOBgNVBAMMB2ZjLWhvc3QwWTATBgcqhkjOPQIB
+BggqhkjOPQMBBwNCAAQodCSHY8Sz5Lh/4K6+SzekkrRCeKMBfmonVb7dUhM0ZWpo
+ePCcRrMcJp5aNxLxEgkl2EMMMMwE3LlLSOX5LZz6o30wezAkBgNVHREEHTAbghNz
+YW5kYm94LmZjLmludGVybmFshwR/AAABMBMGA1UdJQQMMAoGCCsGAQUFBwMBMB0G
+A1UdDgQWBBRXHU1vlX7WvqzcbaNxRxV4f3gfDDAfBgNVHSMEGDAWgBT9DPPymWNa
+L8chg3IuYrqGF3JmYDAKBggqhkjOPQQDAgNJADBGAiEAlqzKqgBf5hxJqd26QwcY
+n3cvEKi4f2BSLe1Rfzr5oSoCIQD0izUOJXLNvmac9cMgV0HvkftBerDKFOcGeGTN
+g3Eunw==
+-----END CERTIFICATE-----
+`;
+const SERVER_KEY = `-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg/ROnYXIkMKnipbLt
+JnFEwXAifgeOv9TGLcK2RojE7jmhRANCAAQodCSHY8Sz5Lh/4K6+SzekkrRCeKMB
+fmonVb7dUhM0ZWpoePCcRrMcJp5aNxLxEgkl2EMMMMwE3LlLSOX5LZz6
+-----END PRIVATE KEY-----
+`;
+const CLIENT_CRT = `-----BEGIN CERTIFICATE-----
+MIIBjjCCATWgAwIBAgIUYkXroqlz9blXW8llis6e2OxOc1QwCgYIKoZIzj0EAwIw
+HDEaMBgGA1UEAwwRdmFuZGFsLWZjLXRlc3QtY2EwIBcNMjYwNjE2MDgzMjUyWhgP
+MjEyNjA1MjMwODMyNTJaMBgxFjAUBgNVBAMMDWNhLXZhbmRhbC1hcHAwWTATBgcq
+hkjOPQIBBggqhkjOPQMBBwNCAASlCMCwjtrQUicWcWsO29R5S7fzjMbbxXvDh8/K
+w57x/PN/uQwLHWCz1Tsyk0FnbrwGP+nPtwrUPIxrLN//euXko1cwVTATBgNVHSUE
+DDAKBggrBgEFBQcDAjAdBgNVHQ4EFgQU2cxDCNrlVkk4ODs6ZPrkC6GzHjkwHwYD
+VR0jBBgwFoAU/Qzz8pljWi/HIYNyLmK6hhdyZmAwCgYIKoZIzj0EAwIDRwAwRAIg
+RghqArNm3bXnWnRi+jkEEJa8mRb2z0Wj4G7SIhtMurUCIBQSllVtICgZB9hvcM0D
+d24fcW4nlfvaZJMJ6dRC1Wle
+-----END CERTIFICATE-----
+`;
+const CLIENT_KEY = `-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgaamj/ycrEuPqpiC2
+IhAYx/M5iN4t4P+B17V4GO54Nb2hRANCAASlCMCwjtrQUicWcWsO29R5S7fzjMbb
+xXvDh8/Kw57x/PN/uQwLHWCz1Tsyk0FnbrwGP+nPtwrUPIxrLN//euXk
+-----END PRIVATE KEY-----
+`;
+const ROGUE_CLIENT_CRT = `-----BEGIN CERTIFICATE-----
+MIIBhjCCASugAwIBAgIUbAYOlW4PQGyXjjRsjCPy62EHUmIwCgYIKoZIzj0EAwIw
+EzERMA8GA1UEAwwIcm9ndWUtY2EwIBcNMjYwNjE2MDgzMjUyWhgPMjEyNjA1MjMw
+ODMyNTJaMBcxFTATBgNVBAMMDHJvZ3VlLWNsaWVudDBZMBMGByqGSM49AgEGCCqG
+SM49AwEHA0IABOPSzdzQTQz3M5CDHLVPguvHd10ncaDV9t4zKUy/PCE+U7GTJwN2
+TtypGnmYEahbcl45j94hwu495P5VbR5ohb6jVzBVMBMGA1UdJQQMMAoGCCsGAQUF
+BwMCMB0GA1UdDgQWBBTf0woauniche3/ps77+Kd0dsbbSDAfBgNVHSMEGDAWgBSX
+Yu0IJlPxi79Gyi5hR1IfS/sqyzAKBggqhkjOPQQDAgNJADBGAiEAxD4N4XWtaHPJ
+yaCOzQP0e5RRyNst3QrhH0NSMyPw89wCIQC+bezLX97TuV1sId53Bo1l9j1TSOMa
+EZotN/Wsq6L+qw==
+-----END CERTIFICATE-----
+`;
+const ROGUE_CLIENT_KEY = `-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgR6fGq27O9eT/hi0Q
+c+L5+lSm5fbDEghVJCo6k7HrG62hRANCAATj0s3c0E0M9zOQgxy1T4Lrx3ddJ3Gg
+1fbeMylMvzwhPlOxkycDdk7cqRp5mBGoW3JeOY/eIcLuPeT+VW0eaIW+
+-----END PRIVATE KEY-----
+`;
+/**
+ * A loopback stand-in for the per-FC-host mTLS relay.
+ *
+ * Terminates mTLS (requestCert + rejectUnauthorized + CA pin), reads the
+ * `SANDBOX <id>\n` routing preamble line, then bridges the rest of the
+ * TLS stream verbatim to a FRESH `net.connect` to `agentSockPath` (the
+ * unix-socket-backed real agent) — exactly the dumb byte-pump the
+ * production relay is. It does NOT speak framing itself and does NOT
+ * send an ack line (matching the transport's no-ack INTEGRATE contract).
+ */
+function startMtlsRelay(agentSockPath, listenPort = 0) {
+    let resolvePreamble;
+    const preamble = new Promise((r) => {
+        resolvePreamble = r;
+    });
+    return new Promise((resolve, reject) => {
+        const server = createTlsServer({
+            requestCert: true,
+            rejectUnauthorized: true,
+            ca: CA_CRT,
+            cert: SERVER_CRT,
+            key: SERVER_KEY,
+            minVersion: 'TLSv1.3',
+        }, (tlsSock) => {
+            // Read exactly the `SANDBOX <id>\n` preamble line, then bridge.
+            let pre = Buffer.alloc(0);
+            const onPreambleData = (chunk) => {
+                pre = Buffer.concat([pre, chunk]);
+                const nl = pre.indexOf(0x0a);
+                if (nl < 0)
+                    return;
+                tlsSock.removeListener('data', onPreambleData);
+                // Pause + unshift any post-preamble bytes so flowing-mode
+                // data is not dropped between removing this listener and
+                // attaching the pipe (the framed request can arrive in the
+                // same OR a later chunk). `pipe` resumes the stream.
+                tlsSock.pause();
+                const line = pre.subarray(0, nl).toString('utf8');
+                const rest = pre.subarray(nl + 1);
+                if (rest.length > 0)
+                    tlsSock.unshift(rest);
+                const m = /^SANDBOX (.+)$/.exec(line);
+                const id = m?.[1];
+                if (id === undefined) {
+                    tlsSock.destroy();
+                    return;
+                }
+                resolvePreamble(id);
+                // 1 inbound mTLS conn -> 1 FRESH local agent connect (the
+                // resume-survival invariant the relay must preserve).
+                const upstream = netConnect({ path: agentSockPath });
+                upstream.on('error', () => tlsSock.destroy());
+                tlsSock.on('error', () => upstream.destroy());
+                upstream.once('connect', () => {
+                    tlsSock.pipe(upstream);
+                    upstream.pipe(tlsSock);
+                });
+            };
+            tlsSock.on('data', onPreambleData);
+        });
+        server.on('error', reject);
+        server.listen(listenPort, '127.0.0.1', () => {
+            const addr = server.address();
+            if (addr === null || typeof addr === 'string') {
+                reject(new Error('relay: no TCP port'));
+                return;
+            }
+            resolve({ server, port: addr.port, preamble: () => preamble });
+        });
+    });
+}
+/** Re-listen the relay on a FIXED port (the host-bridge-restart case). */
+function startMtlsRelayOnPort(agentSockPath, port) {
+    return startMtlsRelay(agentSockPath, port);
+}
+describe('VsockAgentTransport mtls arm over a TLS loopback relay', () => {
+    let agentServer;
+    let relay;
+    afterEach(async () => {
+        if (relay) {
+            await new Promise((r) => relay?.server.close(() => r()));
+            relay = undefined;
+        }
+        if (agentServer) {
+            await new Promise((r) => agentServer?.close(() => r()));
+            agentServer = undefined;
+        }
+    });
+    function mtlsTransport(opts) {
+        if (!relay)
+            throw new Error('relay not started');
+        return new VsockAgentTransport({
+            kind: 'mtls',
+            host: '127.0.0.1',
+            port: relay.port,
+            sandboxId: 'sbx-ring0-abc123',
+            tls: {
+                ca: CA_CRT,
+                cert: CLIENT_CRT,
+                key: CLIENT_KEY,
+                servername: 'sandbox.fc.internal',
+            },
+        }, opts);
+    }
+    it('round-trips exec + write/read + healthz through the mTLS relay', async () => {
+        agentServer = await startAgentServer(agent.handleConnection);
+        relay = await startMtlsRelay(sockPath);
+        const transport = mtlsTransport();
+        const r = await transport.execute({
+            command: '/bin/sh',
+            args: ['-c', 'echo mtls-out; echo mtls-err 1>&2; exit 7'],
+        });
+        expect(r.stdout).toContain('mtls-out');
+        expect(r.stderr).toContain('mtls-err');
+        expect(r.exitCode).toBe(7);
+        const payload = Buffer.from([0x00, 0xff, 0x10, 0x42, 0x00, 0x99, 0xfe]);
+        await transport.writeFile('m/blob.bin', payload);
+        const read = await transport.readFile('m/blob.bin');
+        expect(read.equals(payload)).toBe(true);
+        expect(await transport.healthz()).toBe(true);
+    });
+    it('sends `SANDBOX <id>` as the first bytes after the handshake (no CONNECT line)', async () => {
+        agentServer = await startAgentServer(agent.handleConnection);
+        relay = await startMtlsRelay(sockPath);
+        const transport = mtlsTransport();
+        // Any op drives a dial; the relay records the preamble line.
+        expect(await transport.healthz()).toBe(true);
+        // The caller's first line is the routing preamble, NOT `CONNECT 1024`
+        // — the relay issues the guest CONNECT host-side.
+        await expect(relay.preamble()).resolves.toBe('sbx-ring0-abc123');
+    });
+    it('rejects a client presenting a wrong-CA cert (rejectUnauthorized blocks it)', async () => {
+        agentServer = await startAgentServer(agent.handleConnection);
+        relay = await startMtlsRelay(sockPath);
+        // Rogue client cert chains to a DIFFERENT CA than the relay trusts.
+        const rogue = new VsockAgentTransport({
+            kind: 'mtls',
+            host: '127.0.0.1',
+            port: relay.port,
+            sandboxId: 'sbx-ring0-abc123',
+            tls: {
+                ca: CA_CRT,
+                cert: ROGUE_CLIENT_CRT,
+                key: ROGUE_CLIENT_KEY,
+                servername: 'sandbox.fc.internal',
+            },
+        }, { connectRetryBudgetMs: 600, connectRetryIntervalMs: 50, connectTimeoutMs: 300 });
+        // The relay's `rejectUnauthorized` drops the connection AFTER the
+        // client handshake completes (the client trusts the server CA), so
+        // the failure surfaces as a torn-down round-trip, not a TLS verify
+        // error on the client side. Either way no agent traffic completes:
+        // healthz swallows it into `false`; readFile rejects.
+        expect(await rogue.healthz()).toBe(false);
+        await expect(rogue.readFile('x')).rejects.toThrow();
+    });
+    it('rejects a server whose cert does not chain to the pinned CA (caller-side verify)', async () => {
+        agentServer = await startAgentServer(agent.handleConnection);
+        relay = await startMtlsRelay(sockPath);
+        // The CALLER pins the ROGUE CA, so the relay's good-CA server cert
+        // fails verification — proves the dialer's rejectUnauthorized works.
+        const wrongCaCaller = new VsockAgentTransport({
+            kind: 'mtls',
+            host: '127.0.0.1',
+            port: relay.port,
+            sandboxId: 'sbx-ring0-abc123',
+            tls: {
+                ca: ROGUE_CLIENT_CRT, // not the issuing CA → server cert unverifiable
+                cert: CLIENT_CRT,
+                key: CLIENT_KEY,
+                servername: 'sandbox.fc.internal',
+            },
+        }, { connectRetryBudgetMs: 600, connectRetryIntervalMs: 50, connectTimeoutMs: 300 });
+        await expect(wrongCaCaller.readFile('x')).rejects.toThrow(/could not connect to agent/);
+    });
+    it('survives a simulated resume through the relay (relay torn down then re-listened on the same port)', async () => {
+        agentServer = await startAgentServer(agent.handleConnection);
+        relay = await startMtlsRelay(sockPath);
+        const fixedPort = relay.port;
+        const transport = new VsockAgentTransport({
+            kind: 'mtls',
+            host: '127.0.0.1',
+            port: fixedPort,
+            sandboxId: 'sbx-ring0-abc123',
+            tls: {
+                ca: CA_CRT,
+                cert: CLIENT_CRT,
+                key: CLIENT_KEY,
+                servername: 'sandbox.fc.internal',
+            },
+        }, { connectRetryBudgetMs: 5_000, connectRetryIntervalMs: 50, connectTimeoutMs: 1_000 });
+        const first = await transport.execute({ command: '/bin/sh', args: ['-c', 'echo before'] });
+        expect(first.stdout).toContain('before');
+        // Simulate the FC host bridge going away then coming back (the
+        // network analogue of a vsock re-LISTEN): tear the relay down so the
+        // caller's TLS connect gets ECONNREFUSED, and the per-request fresh
+        // dial must ride the connect-retry budget until the relay is back.
+        await new Promise((r) => relay?.server.close(() => r()));
+        relay = undefined;
+        const pending = transport.execute({ command: '/bin/sh', args: ['-c', 'echo after'] });
+        await new Promise((r) => setTimeout(r, 300));
+        // Re-listen the relay on the SAME port (the host bridge restarts).
+        relay = await startMtlsRelayOnPort(sockPath, fixedPort);
+        const after = await pending;
+        expect(after.stdout).toContain('after');
+        expect(after.exitCode).toBe(0);
+    });
+});
+//# sourceMappingURL=transport.test.js.map

package/dist/backends/firecracker/__tests__/transport.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.test.js","sourceRoot":"","sources":["../../../../src/backends/firecracker/__tests__/transport.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EAA4B,YAAY,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,UAAU,CAAA;AACxF,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAA4C,YAAY,IAAI,eAAe,EAAE,MAAM,UAAU,CAAA;AAEpG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAEpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,uEAAuE;AACvE,sEAAsE;AACtE,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAM/C,IAAI,OAAe,CAAA;AACnB,IAAI,QAAgB,CAAA;AACpB,IAAI,MAA0B,CAAA;AAC9B,IAAI,KAAkB,CAAA;AAEtB,SAAS,gBAAgB,CAAC,WAAgC;IACzD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,MAAM,CAAC,GAAG,YAAY,CAAC,WAAW,CAAC,CAAA;QACnC,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QACrB,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACH,CAAC;AAED,UAAU,CAAC,GAAG,EAAE;IACf,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAA;IACvD,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IACtC,uEAAuE;IACvE,OAAO,CAAC,GAAG,CAAC,uBAAuB,GAAG,OAAO,CAAA;IAC7C,wEAAwE;IACxE,2EAA2E;IAC3E,8BAA8B;IAC9B,oFAAoF;IACpF,OAAO,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAA;IAC3C,oFAAoF;IACpF,OAAO,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAA;IAC5C,uDAAuD;IACvD,OAAO,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAA;IACtE,KAAK,GAAG,QAAQ,CAAC,6BAA6B,CAAgB,CAAA;AAC/D,CAAC,CAAC,CAAA;AAEF,SAAS,CAAC,KAAK,IAAI,EAAE;IACpB,IAAI,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACxD,MAAM,GAAG,SAAS,CAAA;IACnB,CAAC;IACD,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;AAClD,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,uDAAuD,EAAE,GAAG,EAAE;IACtE,EAAE,CAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QACjE,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;QAE3E,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC;YACjC,OAAO,EAAE,SAAS;YAClB,IAAI,EAAE,CAAC,IAAI,EAAE,2CAA2C,CAAC;SACzD,CAAC,CAAA;QACF,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;QACtC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;QACtC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAC1B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC9B,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;QAC/E,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;QAE3E,gEAAgE;QAChE,oDAAoD;QACpD,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC;YACjC,OAAO,EAAE,SAAS;YAClB,IAAI,EAAE,CAAC,IAAI,EAAE,gDAAgD,CAAC;SAC9D,CAAC,CAAA;QACF,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAC1B,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACzC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC9B,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC/B,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qEAAqE,EAAE,KAAK,IAAI,EAAE;QACpF,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;QAE3E,8DAA8D;QAC9D,aAAa;QACb,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;QACvE,MAAM,SAAS,CAAC,SAAS,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAA;QACtD,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAA;QACzD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACxC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC/D,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC3E,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACtF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC3E,MAAM,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC7C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC/D,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC3E,sDAAsD;QACtD,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAA;IACnE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mFAAmF,EAAE,KAAK,IAAI,EAAE;QAClG,qCAAqC;QACrC,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QACvD,MAAM,SAAS,GAAG,IAAI,mBAAmB,CACxC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;QAChC,iEAAiE;QACjE,EAAE,oBAAoB,EAAE,KAAK,EAAE,sBAAsB,EAAE,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,CACpF,CAAA;QACD,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,CAAC,CAAA;QAC1F,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QAExC,mEAAmE;QACnE,mEAAmE;QACnE,2BAA2B;QAC3B,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACxD,MAAM,GAAG,SAAS,CAAA;QAElB,kEAAkE;QAClE,mEAAmE;QACnE,8DAA8D;QAC9D,kEAAkE;QAClE,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,CAAA;QAErF,mEAAmE;QACnE,+CAA+C;QAC/C,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;QAC5C,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QAEvD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAA;QAC3B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QACvC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+EAA+E,EAAE,KAAK,IAAI,EAAE;QAC9F,iEAAiE;QACjE,0DAA0D;QAC1D,MAAM,SAAS,GAAG,IAAI,mBAAmB,CACxC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,EAChC,EAAE,oBAAoB,EAAE,GAAG,EAAE,sBAAsB,EAAE,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAChF,CAAA;QACD,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACtD,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,4BAA4B,CAAC,CAAA;IACpF,CAAC,CAAC,CAAA;AACH,CAAC,CAAC,CAAA;AAEF,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,EAAE;AACF,wEAAwE;AACxE,sEAAsE;AACtE,sEAAsE;AACtE,sEAAsE;AACtE,sEAAsE;AACtE,uEAAuE;AACvE,mEAAmE;AACnE,+DAA+D;AAC/D,uEAAuE;AACvE,qEAAqE;AACrE,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,uEAAuE;AAEvE,yEAAyE;AACzE,2EAA2E;AAC3E,4EAA4E;AAC5E,MAAM,MAAM,GAAG;;;;;;;;;;;CAWd,CAAA;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;;CAYlB,CAAA;AAED,MAAM,UAAU,GAAG;;;;;CAKlB,CAAA;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;CAWlB,CAAA;AAED,MAAM,UAAU,GAAG;;;;;CAKlB,CAAA;AAED,MAAM,gBAAgB,GAAG;;;;;;;;;;;CAWxB,CAAA;AAED,MAAM,gBAAgB,GAAG;;;;;CAKxB,CAAA;AASD;;;;;;;;;GASG;AACH,SAAS,cAAc,CAAC,aAAqB,EAAE,UAAU,GAAG,CAAC;IAC5D,IAAI,eAAqC,CAAA;IACzC,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAS,CAAC,CAAC,EAAE,EAAE;QAC1C,eAAe,GAAG,CAAC,CAAA;IACpB,CAAC,CAAC,CAAA;IAEF,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnD,MAAM,MAAM,GAAG,eAAe,CAC7B;YACC,WAAW,EAAE,IAAI;YACjB,kBAAkB,EAAE,IAAI;YACxB,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,UAAU;YACf,UAAU,EAAE,SAAS;SACrB,EACD,CAAC,OAAkB,EAAE,EAAE;YACtB,gEAAgE;YAChE,IAAI,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YACzB,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,EAAE;gBACxC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;gBACjC,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAC5B,IAAI,EAAE,GAAG,CAAC;oBAAE,OAAM;gBAClB,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;gBAC9C,0DAA0D;gBAC1D,yDAAyD;gBACzD,2DAA2D;gBAC3D,qDAAqD;gBACrD,OAAO,CAAC,KAAK,EAAE,CAAA;gBACf,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;gBACjD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;gBACjC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;oBAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAC1C,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACrC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;gBACjB,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;oBACtB,OAAO,CAAC,OAAO,EAAE,CAAA;oBACjB,OAAM;gBACP,CAAC;gBACD,eAAe,CAAC,EAAE,CAAC,CAAA;gBACnB,0DAA0D;gBAC1D,sDAAsD;gBACtD,MAAM,QAAQ,GAAG,UAAU,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAA;gBACpD,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;gBAC7C,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;gBAC7C,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;oBAC7B,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;oBACtB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;gBACvB,CAAC,CAAC,CAAA;YACH,CAAC,CAAA;YACD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;QACnC,CAAC,CACD,CAAA;QACD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC1B,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,EAAE;YAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAA;YAC7B,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC/C,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAA;gBACvC,OAAM;YACP,CAAC;YACD,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC/D,CAAC,CAAC,CAAA;IACH,CAAC,CAAC,CAAA;AACH,CAAC;AAED,0EAA0E;AAC1E,SAAS,oBAAoB,CAAC,aAAqB,EAAE,IAAY;IAChE,OAAO,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;AAC3C,CAAC;AAED,QAAQ,CAAC,wDAAwD,EAAE,GAAG,EAAE;IACvE,IAAI,WAA+B,CAAA;IACnC,IAAI,KAA8B,CAAA;IAElC,SAAS,CAAC,KAAK,IAAI,EAAE;QACpB,IAAI,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YAC9D,KAAK,GAAG,SAAS,CAAA;QAClB,CAAC;QACD,IAAI,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YAC7D,WAAW,GAAG,SAAS,CAAA;QACxB,CAAC;IACF,CAAC,CAAC,CAAA;IAEF,SAAS,aAAa,CAAC,IAA2D;QACjF,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAA;QAChD,OAAO,IAAI,mBAAmB,CAC7B;YACC,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,kBAAkB;YAC7B,GAAG,EAAE;gBACJ,EAAE,EAAE,MAAM;gBACV,IAAI,EAAE,UAAU;gBAChB,GAAG,EAAE,UAAU;gBACf,UAAU,EAAE,qBAAqB;aACjC;SACD,EACD,IAAI,CACJ,CAAA;IACF,CAAC;IAED,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;QAC/E,WAAW,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QAC5D,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAA;QACtC,MAAM,SAAS,GAAG,aAAa,EAAE,CAAA;QAEjC,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC;YACjC,OAAO,EAAE,SAAS;YAClB,IAAI,EAAE,CAAC,IAAI,EAAE,2CAA2C,CAAC;SACzD,CAAC,CAAA;QACF,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;QACtC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;QACtC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAE1B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;QACvE,MAAM,SAAS,CAAC,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;QAChD,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;QACnD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAEvC,MAAM,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC7C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+EAA+E,EAAE,KAAK,IAAI,EAAE;QAC9F,WAAW,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QAC5D,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAA;QACtC,MAAM,SAAS,GAAG,aAAa,EAAE,CAAA;QAEjC,6DAA6D;QAC7D,MAAM,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC5C,sEAAsE;QACtE,kDAAkD;QAClD,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;IACjE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4EAA4E,EAAE,KAAK,IAAI,EAAE;QAC3F,WAAW,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QAC5D,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAA;QACtC,oEAAoE;QACpE,MAAM,KAAK,GAAG,IAAI,mBAAmB,CACpC;YACC,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,kBAAkB;YAC7B,GAAG,EAAE;gBACJ,EAAE,EAAE,MAAM;gBACV,IAAI,EAAE,gBAAgB;gBACtB,GAAG,EAAE,gBAAgB;gBACrB,UAAU,EAAE,qBAAqB;aACjC;SACD,EACD,EAAE,oBAAoB,EAAE,GAAG,EAAE,sBAAsB,EAAE,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAChF,CAAA;QACD,kEAAkE;QAClE,mEAAmE;QACnE,mEAAmE;QACnE,mEAAmE;QACnE,sDAAsD;QACtD,MAAM,CAAC,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACzC,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAA;IACpD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kFAAkF,EAAE,KAAK,IAAI,EAAE;QACjG,WAAW,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QAC5D,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAA;QACtC,mEAAmE;QACnE,qEAAqE;QACrE,MAAM,aAAa,GAAG,IAAI,mBAAmB,CAC5C;YACC,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,kBAAkB;YAC7B,GAAG,EAAE;gBACJ,EAAE,EAAE,gBAAgB,EAAE,gDAAgD;gBACtE,IAAI,EAAE,UAAU;gBAChB,GAAG,EAAE,UAAU;gBACf,UAAU,EAAE,qBAAqB;aACjC;SACD,EACD,EAAE,oBAAoB,EAAE,GAAG,EAAE,sBAAsB,EAAE,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAChF,CAAA;QACD,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,4BAA4B,CAAC,CAAA;IACxF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mGAAmG,EAAE,KAAK,IAAI,EAAE;QAClH,WAAW,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;QAC5D,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAA;QACtC,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAA;QAC5B,MAAM,SAAS,GAAG,IAAI,mBAAmB,CACxC;YACC,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,kBAAkB;YAC7B,GAAG,EAAE;gBACJ,EAAE,EAAE,MAAM;gBACV,IAAI,EAAE,UAAU;gBAChB,GAAG,EAAE,UAAU;gBACf,UAAU,EAAE,qBAAqB;aACjC;SACD,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,sBAAsB,EAAE,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,CACpF,CAAA;QACD,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,CAAC,CAAA;QAC1F,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QAExC,+DAA+D;QAC/D,qEAAqE;QACrE,oEAAoE;QACpE,mEAAmE;QACnE,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QAC9D,KAAK,GAAG,SAAS,CAAA;QAEjB,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,CAAA;QACrF,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;QAC5C,mEAAmE;QACnE,KAAK,GAAG,MAAM,oBAAoB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAA;QAEvD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAA;QAC3B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QACvC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;AACH,CAAC,CAAC,CAAA"}

package/dist/backends/firecracker/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `microvm:self-hosted` (Firecracker) backend.
+ *
+ * Sibling of `docker/` and `aci-standby-pool/`: same
+ * {@link SandboxBackend} surface, same NDJSON exec-stream + base64
+ * file-IO **wire contract**, different transport and shipping
+ * mechanism.
+ *
+ *  - docker `docker run`s a container and reaches an HTTP worker on a
+ *    host loopback port.
+ *  - aci PUTs an ACI container group and reaches the same HTTP worker
+ *    over the group's IP.
+ *  - firecracker POSTs the owned Azure **orchestrator** to CoW-resume a
+ *    microVM off the golden snapshot, then reaches a **custom vsock
+ *    agent** baked into the golden rootfs over the **vsock transport**
+ *    (`transport.ts`). The wire FORMAT is identical (see `protocol.ts`);
+ *    only the transport differs — HTTP for docker/aci, framed-over-vsock
+ *    for FC, because across an FC snapshot resume a TCP control channel
+ *    is dead-on-arrival while the vsock LISTEN socket survives
+ *    (FC `snapshot-support.md`).
+ *
+ * ## Why this is a remote-copy backend (no host bind-mounts)
+ * A sibling process on the FC host cannot see the microVM's
+ * filesystem, so — exactly like ACI — the workspace is seeded by
+ * archive-sync over the control channel (tar.gz `writeFile` +
+ * in-sandbox `tar -xzf` via `exec`), driven by the Vandal-side
+ * lifecycle (`workspace-sync.ts`). This backend therefore exposes no
+ * `layout` mount rendering; it only needs the `outputs` container path
+ * as the workspace root, which the orchestrator returns as `rootDir`.
+ *
+ * ## Trust model
+ * The microVM is a hardware-virtualization (KVM) trust boundary —
+ * stronger than docker namespaces or ACI's managed isolation. The
+ * vsock control channel never traverses the guest's egress netns; the
+ * agent listens on a fixed AF_VSOCK port captured warm in the golden
+ * snapshot. Auth to the orchestrator rides a caller-supplied
+ * `getToken()` closure (the ACI `getArmToken` pattern) so
+ * `@namzu/sandbox` keeps zero Azure-SDK dependencies.
+ *
+ * ## Auth / SDK-dependency boundary
+ * `getToken()` mirrors ACI's `getArmToken`: the consumer's runtime
+ * owns Managed-Identity / federated-credential picking; this package
+ * only calls the closure on every orchestrator HTTP call so a
+ * long-running sandbox survives token rotation.
+ */
+import type { AgentSnapshotRef, SandboxBackend } from '../../index.js';
+import type { MtlsClientMaterial, SandboxAgentHandle, VsockTransportOptions, WireSandboxAgentHandle } from './transport.js';
+/**
+ * Async callback returning a fresh bearer token for
+ * {@link FirecrackerBackendInternalConfig.orchestratorEndpoint}.
+ * Invoked on every orchestrator HTTP call (mirrors ACI's
+ * `ArmTokenProvider`).
+ */
+export type OrchestratorTokenProvider = () => Promise<string>;
+export interface FirecrackerBackendInternalConfig {
+    /** Base URL of the owned Azure control plane / orchestrator. */
+    readonly orchestratorEndpoint: string;
+    /** Bearer token provider for `orchestratorEndpoint`. */
+    readonly getToken: OrchestratorTokenProvider;
+    /** Golden template / snapshot revision id to resume from. */
+    readonly template?: string;
+    /**
+     * Per-agent captured snapshot to resume INSTEAD of a fresh golden boot
+     * (layered on its base golden). Optional + additive: absent ⇒ the
+     * orchestrator create body is byte-identical and the generic golden-resume
+     * path is unchanged. The orchestrator honors it (routing the claim to a
+     * per-agent resume) only when its own per-agent flag is on; it is the WIRE
+     * carrier the host's per-agent trigger path sets. See {@link AgentSnapshotRef}.
+     */
+    readonly agentSnapshot?: AgentSnapshotRef;
+    /** Fixed guest AF_VSOCK port the agent listens on (contract port). */
+    readonly agentVsockPort?: number;
+    readonly readyTimeoutMs?: number;
+    readonly readyPollIntervalMs?: number;
+    /** Transport tuning forwarded to {@link VsockAgentTransport}. */
+    readonly transport?: VsockTransportOptions;
+    /**
+     * NETWORK-mode mTLS client material (ses_051 P4). When present AND the
+     * orchestrator returns an `mtls` agent handle, this CA/cert/key is MERGED
+     * onto the handle's `tls` block before the transport dials the per-host
+     * relay. The consumer's runtime injects it (mirrors `getToken`); this
+     * package never reads it from disk or fetches it, so it stays Azure-SDK
+     * free. Absent for the single-host VSOCK default (the live proofs).
+     */
+    readonly mtls?: MtlsClientMaterial;
+    /**
+     * CONTROL-plane mTLS client material. When present, the orchestrator
+     * control-plane calls (`POST /sandboxes`, `DELETE /sandboxes/{id}:delete`,
+     * `GET /capacity`) dial over mTLS — presenting this client cert and
+     * verifying the orchestrator's server cert against this CA — INSTEAD of the
+     * plain `fetch`. This secures the control plane when `orchestratorEndpoint`
+     * is reached over the PUBLIC internet (the `ca-vandal-app` → FC-host hop is
+     * not VNet-integrated), where the shared-secret bearer alone would be
+     * exposed. The bearer is STILL sent (defense in depth on top of mTLS).
+     *
+     * Reuses the SAME `{ca,cert,key,servername}` shape as the relay's `mtls`
+     * material — one fleet CA secures both planes. The consumer's runtime
+     * injects the bytes (mirrors `getToken` / `mtls`); the package never reads
+     * them from disk. Absent → the control plane stays plain `fetch` (the
+     * single-host DEFAULT, byte-for-byte unchanged).
+     */
+    readonly controlPlaneMtls?: MtlsClientMaterial;
+}
+/**
+ * Build a {@link SandboxBackend} backed by the owned Firecracker
+ * platform. Construction is synchronous; the orchestrator POST happens
+ * on the first `create()`.
+ */
+export declare function buildFirecrackerBackend(config: FirecrackerBackendInternalConfig): SandboxBackend;
+/**
+ * Turn the orchestrator's WIRE handle into the transport handle the dialer
+ * uses. Two transforms:
+ *
+ *  - `vsock` with a missing/<=0 port → fill the contract port.
+ *  - `mtls` → MERGE the consumer-injected `mtls` cert material onto the
+ *    wire handle (which carries only host/port/sandboxId). The orchestrator
+ *    never ships cert material; without an injected `mtls` block a network
+ *    handle cannot dial, so this throws loud rather than constructing a
+ *    transport that would fail at connect time.
+ *
+ * `unix` + already-correct `vsock` handles pass through untouched.
+ */
+export declare function normalizeHandle(handle: WireSandboxAgentHandle, contractPort: number, mtls: MtlsClientMaterial | undefined): SandboxAgentHandle;
+//# sourceMappingURL=index.d.ts.map

package/dist/backends/firecracker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/firecracker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAcH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAyB,MAAM,gBAAgB,CAAA;AAC7F,OAAO,KAAK,EACX,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,MAAM,gBAAgB,CAAA;AAGvB;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;AAE7D,MAAM,WAAW,gCAAgC;IAChD,gEAAgE;IAChE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAA;IAC5C,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAA;IACzC,sEAAsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAA;IAC1C;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAA;IAClC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAA;CAC9C;AAMD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gCAAgC,GAAG,cAAc,CAQhG;AAgVD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,sBAAsB,EAC9B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,kBAAkB,GAAG,SAAS,GAClC,kBAAkB,CAyBpB"}