apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/sandbox/rpc/git-credential-proxy.js

@@ -0,0 +1,209 @@
+import { chmodSync, existsSync, unlinkSync } from "node:fs";
+import * as net from "node:net";
+import { FrameReader, isRequestObject, writeFrame } from "./framing.js";
+const MAX_CONNECTIONS = 32;
+/**
+ * git's credential protocol is `key=value` lines terminated by a blank line, so any byte
+ * that can end a line or a field can rewrite the request downstream of this point. A
+ * `protocol` of `https\nhost=other.invalid\n\n` is authorized as one identity and served as
+ * another; the same is true of a carriage return, a NUL, or a bare space.
+ */
+const LINE_OR_FIELD_BREAKING = /[\s\u0000-\u001f\u007f-\u009f]/u;
+/**
+ * Structural, not an allowlist. Hardcoding `https` would refuse `ssh` and every custom
+ * scheme a host helper answers for, which is a working feature rather than an attack. What
+ * is refused is anything that is not a scheme: RFC 3986's shape, lowercased first so that
+ * the released identity and the served one cannot differ by case.
+ */
+const SCHEME_SHAPE = /^[a-z][a-z0-9+.-]*$/;
+/** Bounds, so a frame that is within the reader's byte limit is still not an essay. */
+const MAX_HOST_LENGTH = 255;
+const MAX_PROTOCOL_LENGTH = 32;
+/**
+ * Parse one credential request into the single structured identity everything downstream
+ * uses.
+ *
+ * The caller authorizes, releases, and serializes *this* value and never the raw fields,
+ * because the defect this closes is precisely that the string checked against the release
+ * was not the string handed to git.
+ */
+export function parseGitCredentialRequest(request) {
+    const rawProtocol = request.protocol;
+    // git's own helper always sends one; an absent field means "whatever git defaults to",
+    // and https is what this channel has always assumed. A present non-string is a client
+    // that is not git.
+    if (rawProtocol !== undefined && typeof rawProtocol !== "string") {
+        return { ok: false, error: "Request protocol was not a string.", audit: "protocol field was not a string" };
+    }
+    if (typeof request.host !== "string") {
+        return { ok: false, error: "Request named no host.", audit: "host field was absent or not a string" };
+    }
+    const protocol = (rawProtocol ?? "https").toLowerCase();
+    const host = request.host;
+    if (!host)
+        return { ok: false, error: "Request named no host.", audit: "host field was empty" };
+    if (host.length > MAX_HOST_LENGTH) {
+        return { ok: false, error: "Request host is too long.", audit: "host field exceeded its length bound" };
+    }
+    if (LINE_OR_FIELD_BREAKING.test(host)) {
+        return {
+            ok: false,
+            error: "Request host contains a control or whitespace character.",
+            audit: "host field carried a control or whitespace character",
+        };
+    }
+    if (protocol.length > MAX_PROTOCOL_LENGTH) {
+        return { ok: false, error: "Request protocol is too long.", audit: "protocol field exceeded its length bound" };
+    }
+    if (!SCHEME_SHAPE.test(protocol)) {
+        return {
+            ok: false,
+            error: "Request protocol is not a scheme.",
+            audit: "protocol field was not a scheme",
+        };
+    }
+    return { ok: true, request: { protocol, host } };
+}
+/**
+ * Serve git credentials to the sandboxed child without ever putting one inside it.
+ *
+ * ADR 0015 keeps credentials host-owned and hands the child a read-only projection. A git
+ * credential cannot be projected the same way: it is not one file with a stable shape, it
+ * is whatever the host's own helper produces per host. So the credential stays on the host
+ * and only the answer to one question crosses, for one host, once it has been released.
+ *
+ * Two gates, and the first is the one that matters most.
+ *
+ * The host must be reachable by this session. git only asks for a credential after a
+ * server challenged it, so in the ordinary flow the host was already allowed or approved
+ * at the network layer. A request for a host the session cannot reach is therefore not git
+ * doing its job; it is something that went looking for a token. Refusing it costs nothing
+ * real and removes the case where this channel is more useful to an attacker than to git.
+ *
+ * The human must release it. Per ADR 0023 that decision is the supervisor's, because this
+ * socket has no peer authentication -- every descendant in the child's namespace can reach
+ * it, which is precisely the code the boundary exists to contain. Without a releaser the
+ * channel refuses outright, so a headless session cannot hand out a credential at all.
+ *
+ * A release covers one host for the session. It is never persisted and never widened to a
+ * second host, which is what keeps an approval for a push from also releasing a token to
+ * whatever else the session later contacts.
+ */
+export function createGitCredentialProxy(options) {
+    /** Hosts released this session. Never persisted, never widened. */
+    const released = new Set();
+    const pending = new Map();
+    function audit(host, detail) {
+        options.violationStore?.add({
+            kind: "network",
+            command: `git credential ${host}`,
+            detail,
+            timestamp: new Date(),
+        });
+    }
+    async function release(host) {
+        if (released.has(host))
+            return true;
+        if (!options.requestRelease)
+            return false;
+        const inFlight = pending.get(host);
+        if (inFlight)
+            return inFlight;
+        const question = (async () => {
+            try {
+                const approved = await options.requestRelease(host);
+                if (approved)
+                    released.add(host);
+                return approved;
+            }
+            catch {
+                return false;
+            }
+            finally {
+                pending.delete(host);
+            }
+        })();
+        pending.set(host, question);
+        return question;
+    }
+    async function answer(request) {
+        if (!isRequestObject(request))
+            return { ok: false, error: "Malformed request." };
+        if (request.op !== "get") {
+            // Only `get` crosses. `store` and `erase` would let the child rewrite the host's
+            // credential store, which ADR 0015 keeps as an explicit host operation.
+            return { ok: false, error: "Only credential reads are served over this channel." };
+        }
+        const parsed = parseGitCredentialRequest(request);
+        if (!parsed.ok) {
+            // The refused bytes are deliberately not echoed. This tail is read by a human and
+            // rendered in a terminal, and the whole point of the refused field is that it
+            // carries line breaks and control characters.
+            audit("(protocol)", `Refused a credential request whose ${parsed.audit}.`);
+            return { ok: false, error: parsed.error };
+        }
+        const { host, protocol } = parsed.request;
+        if (!options.isHostAllowed(host)) {
+            audit(host, `Refused a credential for ${host}, which this session may not reach.`);
+            return { ok: false, error: "Host is not reachable by this session." };
+        }
+        if (!(await release(host))) {
+            audit(host, `Credential for ${host} was not released.`);
+            return { ok: false, error: "Credential was not released." };
+        }
+        const credential = await options.fillCredential({ host, protocol });
+        if (!credential) {
+            audit(host, `The host credential store had nothing for ${host}.`);
+            return { ok: false, error: "No credential is configured for that host." };
+        }
+        return { ok: true, username: credential.username, password: credential.password };
+    }
+    return new Promise((resolve, reject) => {
+        // A prior launch that never closed leaves a stale socket file that listen() refuses
+        // to bind over, exactly as the network proxy handles.
+        if (existsSync(options.socketPath))
+            unlinkSync(options.socketPath);
+        const sockets = new Set();
+        const server = net.createServer((socket) => {
+            if (sockets.size >= MAX_CONNECTIONS) {
+                socket.destroy();
+                return;
+            }
+            sockets.add(socket);
+            socket.on("close", () => sockets.delete(socket));
+            socket.on("error", () => socket.destroy());
+            const reader = new FrameReader(socket, "Git credential channel", (detail) => audit("(protocol)", `Refused: ${detail}`));
+            void (async () => {
+                try {
+                    const response = await answer(await reader.next());
+                    writeFrame(socket, response);
+                }
+                catch {
+                    // A disconnected or malformed client is the reader's business; there is
+                    // nothing to answer and nothing to record beyond what it already did.
+                }
+                finally {
+                    socket.end();
+                }
+            })();
+        });
+        server.on("error", reject);
+        server.listen(options.socketPath, () => {
+            server.off("error", reject);
+            try {
+                chmodSync(options.socketPath, 0o600);
+            }
+            catch {
+                // The containing directory is already 0700; the mode here is defence in depth.
+            }
+            resolve({
+                close: () => new Promise((closed) => {
+                    for (const socket of sockets)
+                        socket.destroy();
+                    server.close(() => closed());
+                }),
+            });
+        });
+    });
+}
+//# sourceMappingURL=git-credential-proxy.js.map

package/dist/core/sandbox/rpc/git-credential-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-credential-proxy.js","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/git-credential-proxy.ts"],"names":[],"mappings":"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","sourcesContent":["import { chmodSync, existsSync, unlinkSync } from \"node:fs\";\nimport * as net from \"node:net\";\nimport type { SandboxViolationStore } from \"../violations.ts\";\nimport { FrameReader, isRequestObject, writeFrame } from \"./framing.ts\";\n\nconst MAX_CONNECTIONS = 32;\n\nexport interface GitCredentialRequest {\n\treadonly protocol: string;\n\treadonly host: string;\n}\n\nexport interface GitCredential {\n\treadonly username: string;\n\treadonly password: string;\n}\n\nexport interface GitCredentialProxy {\n\tclose(): Promise<void>;\n}\n\n/** A request that survived validation, or the reason it did not. */\nexport type GitCredentialRequestParse =\n\t| { readonly ok: true; readonly request: GitCredentialRequest }\n\t| { readonly ok: false; readonly error: string; readonly audit: string };\n\n/**\n * git's credential protocol is `key=value` lines terminated by a blank line, so any byte\n * that can end a line or a field can rewrite the request downstream of this point. A\n * `protocol` of `https\\nhost=other.invalid\\n\\n` is authorized as one identity and served as\n * another; the same is true of a carriage return, a NUL, or a bare space.\n */\nconst LINE_OR_FIELD_BREAKING = /[\\s\\u0000-\\u001f\\u007f-\\u009f]/u;\n\n/**\n * Structural, not an allowlist. Hardcoding `https` would refuse `ssh` and every custom\n * scheme a host helper answers for, which is a working feature rather than an attack. What\n * is refused is anything that is not a scheme: RFC 3986's shape, lowercased first so that\n * the released identity and the served one cannot differ by case.\n */\nconst SCHEME_SHAPE = /^[a-z][a-z0-9+.-]*$/;\n\n/** Bounds, so a frame that is within the reader's byte limit is still not an essay. */\nconst MAX_HOST_LENGTH = 255;\nconst MAX_PROTOCOL_LENGTH = 32;\n\n/**\n * Parse one credential request into the single structured identity everything downstream\n * uses.\n *\n * The caller authorizes, releases, and serializes *this* value and never the raw fields,\n * because the defect this closes is precisely that the string checked against the release\n * was not the string handed to git.\n */\nexport function parseGitCredentialRequest(request: Record<string, unknown>): GitCredentialRequestParse {\n\tconst rawProtocol = request.protocol;\n\t// git's own helper always sends one; an absent field means \"whatever git defaults to\",\n\t// and https is what this channel has always assumed. A present non-string is a client\n\t// that is not git.\n\tif (rawProtocol !== undefined && typeof rawProtocol !== \"string\") {\n\t\treturn { ok: false, error: \"Request protocol was not a string.\", audit: \"protocol field was not a string\" };\n\t}\n\tif (typeof request.host !== \"string\") {\n\t\treturn { ok: false, error: \"Request named no host.\", audit: \"host field was absent or not a string\" };\n\t}\n\n\tconst protocol = (rawProtocol ?? \"https\").toLowerCase();\n\tconst host = request.host;\n\tif (!host) return { ok: false, error: \"Request named no host.\", audit: \"host field was empty\" };\n\tif (host.length > MAX_HOST_LENGTH) {\n\t\treturn { ok: false, error: \"Request host is too long.\", audit: \"host field exceeded its length bound\" };\n\t}\n\tif (LINE_OR_FIELD_BREAKING.test(host)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: \"Request host contains a control or whitespace character.\",\n\t\t\taudit: \"host field carried a control or whitespace character\",\n\t\t};\n\t}\n\tif (protocol.length > MAX_PROTOCOL_LENGTH) {\n\t\treturn { ok: false, error: \"Request protocol is too long.\", audit: \"protocol field exceeded its length bound\" };\n\t}\n\tif (!SCHEME_SHAPE.test(protocol)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: \"Request protocol is not a scheme.\",\n\t\t\taudit: \"protocol field was not a scheme\",\n\t\t};\n\t}\n\treturn { ok: true, request: { protocol, host } };\n}\n\n/**\n * Serve git credentials to the sandboxed child without ever putting one inside it.\n *\n * ADR 0015 keeps credentials host-owned and hands the child a read-only projection. A git\n * credential cannot be projected the same way: it is not one file with a stable shape, it\n * is whatever the host's own helper produces per host. So the credential stays on the host\n * and only the answer to one question crosses, for one host, once it has been released.\n *\n * Two gates, and the first is the one that matters most.\n *\n * The host must be reachable by this session. git only asks for a credential after a\n * server challenged it, so in the ordinary flow the host was already allowed or approved\n * at the network layer. A request for a host the session cannot reach is therefore not git\n * doing its job; it is something that went looking for a token. Refusing it costs nothing\n * real and removes the case where this channel is more useful to an attacker than to git.\n *\n * The human must release it. Per ADR 0023 that decision is the supervisor's, because this\n * socket has no peer authentication -- every descendant in the child's namespace can reach\n * it, which is precisely the code the boundary exists to contain. Without a releaser the\n * channel refuses outright, so a headless session cannot hand out a credential at all.\n *\n * A release covers one host for the session. It is never persisted and never widened to a\n * second host, which is what keeps an approval for a push from also releasing a token to\n * whatever else the session later contacts.\n */\nexport function createGitCredentialProxy(options: {\n\tsocketPath: string;\n\t/** Whether this session may reach the host at all. */\n\tisHostAllowed: (host: string) => boolean;\n\t/** Ask a human to release the host's credential. Absent means refuse without asking. */\n\trequestRelease?: (host: string) => Promise<boolean>;\n\t/** Resolve the credential on the host, using the host's own configuration. */\n\tfillCredential: (request: GitCredentialRequest) => Promise<GitCredential | undefined>;\n\tviolationStore?: SandboxViolationStore;\n}): Promise<GitCredentialProxy> {\n\t/** Hosts released this session. Never persisted, never widened. */\n\tconst released = new Set<string>();\n\tconst pending = new Map<string, Promise<boolean>>();\n\n\tfunction audit(host: string, detail: string): void {\n\t\toptions.violationStore?.add({\n\t\t\tkind: \"network\",\n\t\t\tcommand: `git credential ${host}`,\n\t\t\tdetail,\n\t\t\ttimestamp: new Date(),\n\t\t});\n\t}\n\n\tasync function release(host: string): Promise<boolean> {\n\t\tif (released.has(host)) return true;\n\t\tif (!options.requestRelease) return false;\n\t\tconst inFlight = pending.get(host);\n\t\tif (inFlight) return inFlight;\n\t\tconst question = (async () => {\n\t\t\ttry {\n\t\t\t\tconst approved = await (options.requestRelease as (h: string) => Promise<boolean>)(host);\n\t\t\t\tif (approved) released.add(host);\n\t\t\t\treturn approved;\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t} finally {\n\t\t\t\tpending.delete(host);\n\t\t\t}\n\t\t})();\n\t\tpending.set(host, question);\n\t\treturn question;\n\t}\n\n\tasync function answer(request: unknown): Promise<object> {\n\t\tif (!isRequestObject(request)) return { ok: false, error: \"Malformed request.\" };\n\t\tif (request.op !== \"get\") {\n\t\t\t// Only `get` crosses. `store` and `erase` would let the child rewrite the host's\n\t\t\t// credential store, which ADR 0015 keeps as an explicit host operation.\n\t\t\treturn { ok: false, error: \"Only credential reads are served over this channel.\" };\n\t\t}\n\t\tconst parsed = parseGitCredentialRequest(request);\n\t\tif (!parsed.ok) {\n\t\t\t// The refused bytes are deliberately not echoed. This tail is read by a human and\n\t\t\t// rendered in a terminal, and the whole point of the refused field is that it\n\t\t\t// carries line breaks and control characters.\n\t\t\taudit(\"(protocol)\", `Refused a credential request whose ${parsed.audit}.`);\n\t\t\treturn { ok: false, error: parsed.error };\n\t\t}\n\t\tconst { host, protocol } = parsed.request;\n\n\t\tif (!options.isHostAllowed(host)) {\n\t\t\taudit(host, `Refused a credential for ${host}, which this session may not reach.`);\n\t\t\treturn { ok: false, error: \"Host is not reachable by this session.\" };\n\t\t}\n\t\tif (!(await release(host))) {\n\t\t\taudit(host, `Credential for ${host} was not released.`);\n\t\t\treturn { ok: false, error: \"Credential was not released.\" };\n\t\t}\n\t\tconst credential = await options.fillCredential({ host, protocol });\n\t\tif (!credential) {\n\t\t\taudit(host, `The host credential store had nothing for ${host}.`);\n\t\t\treturn { ok: false, error: \"No credential is configured for that host.\" };\n\t\t}\n\t\treturn { ok: true, username: credential.username, password: credential.password };\n\t}\n\n\treturn new Promise((resolve, reject) => {\n\t\t// A prior launch that never closed leaves a stale socket file that listen() refuses\n\t\t// to bind over, exactly as the network proxy handles.\n\t\tif (existsSync(options.socketPath)) unlinkSync(options.socketPath);\n\n\t\tconst sockets = new Set<net.Socket>();\n\t\tconst server = net.createServer((socket) => {\n\t\t\tif (sockets.size >= MAX_CONNECTIONS) {\n\t\t\t\tsocket.destroy();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsockets.add(socket);\n\t\t\tsocket.on(\"close\", () => sockets.delete(socket));\n\t\t\tsocket.on(\"error\", () => socket.destroy());\n\t\t\tconst reader = new FrameReader(socket, \"Git credential channel\", (detail) =>\n\t\t\t\taudit(\"(protocol)\", `Refused: ${detail}`),\n\t\t\t);\n\t\t\tvoid (async () => {\n\t\t\t\ttry {\n\t\t\t\t\tconst response = await answer(await reader.next());\n\t\t\t\t\twriteFrame(socket, response);\n\t\t\t\t} catch {\n\t\t\t\t\t// A disconnected or malformed client is the reader's business; there is\n\t\t\t\t\t// nothing to answer and nothing to record beyond what it already did.\n\t\t\t\t} finally {\n\t\t\t\t\tsocket.end();\n\t\t\t\t}\n\t\t\t})();\n\t\t});\n\n\t\tserver.on(\"error\", reject);\n\t\tserver.listen(options.socketPath, () => {\n\t\t\tserver.off(\"error\", reject);\n\t\t\ttry {\n\t\t\t\tchmodSync(options.socketPath, 0o600);\n\t\t\t} catch {\n\t\t\t\t// The containing directory is already 0700; the mode here is defence in depth.\n\t\t\t}\n\t\t\tresolve({\n\t\t\t\tclose: () =>\n\t\t\t\t\tnew Promise((closed) => {\n\t\t\t\t\t\tfor (const socket of sockets) socket.destroy();\n\t\t\t\t\t\tserver.close(() => closed());\n\t\t\t\t\t}),\n\t\t\t});\n\t\t});\n\t});\n}\n"]}

package/dist/core/sandbox/supervisor-temp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The directory the supervisor puts its own private state in.
+ *
+ * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code
+ * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may
+ * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an
+ * unusually long `TMPDIR` exhausts.
+ *
+ * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows
+ * session, because ADR 0005 leaves that platform unsupported and both backends report
+ * `unavailable` before a launch gets this far. It still has to resolve to something real:
+ * these helpers are called before the backend's platform check in one path, and off-platform
+ * in the tests that exercise violation attribution without a macOS host. Returning
+ * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate
+ * "OS sandbox is supported on macOS only."
+ */
+export declare function supervisorTempDirectory(): string;
+//# sourceMappingURL=supervisor-temp.d.ts.map

package/dist/core/sandbox/supervisor-temp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-temp.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor-temp.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD","sourcesContent":["import { tmpdir } from \"node:os\";\n\n/**\n * The directory the supervisor puts its own private state in.\n *\n * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code\n * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may\n * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an\n * unusually long `TMPDIR` exhausts.\n *\n * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows\n * session, because ADR 0005 leaves that platform unsupported and both backends report\n * `unavailable` before a launch gets this far. It still has to resolve to something real:\n * these helpers are called before the backend's platform check in one path, and off-platform\n * in the tests that exercise violation attribution without a macOS host. Returning\n * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate\n * \"OS sandbox is supported on macOS only.\"\n */\nexport function supervisorTempDirectory(): string {\n\treturn process.platform === \"win32\" ? tmpdir() : \"/tmp\";\n}\n"]}

package/dist/core/sandbox/supervisor-temp.js

@@ -0,0 +1,21 @@
+import { tmpdir } from "node:os";
+/**
+ * The directory the supervisor puts its own private state in.
+ *
+ * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code
+ * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may
+ * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an
+ * unusually long `TMPDIR` exhausts.
+ *
+ * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows
+ * session, because ADR 0005 leaves that platform unsupported and both backends report
+ * `unavailable` before a launch gets this far. It still has to resolve to something real:
+ * these helpers are called before the backend's platform check in one path, and off-platform
+ * in the tests that exercise violation attribution without a macOS host. Returning
+ * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate
+ * "OS sandbox is supported on macOS only."
+ */
+export function supervisorTempDirectory() {
+    return process.platform === "win32" ? tmpdir() : "/tmp";
+}
+//# sourceMappingURL=supervisor-temp.js.map

package/dist/core/sandbox/supervisor-temp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-temp.js","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor-temp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,GAAW;IACjD,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAAA,CACxD","sourcesContent":["import { tmpdir } from \"node:os\";\n\n/**\n * The directory the supervisor puts its own private state in.\n *\n * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code\n * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may\n * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an\n * unusually long `TMPDIR` exhausts.\n *\n * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows\n * session, because ADR 0005 leaves that platform unsupported and both backends report\n * `unavailable` before a launch gets this far. It still has to resolve to something real:\n * these helpers are called before the backend's platform check in one path, and off-platform\n * in the tests that exercise violation attribution without a macOS host. Returning\n * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate\n * \"OS sandbox is supported on macOS only.\"\n */\nexport function supervisorTempDirectory(): string {\n\treturn process.platform === \"win32\" ? tmpdir() : \"/tmp\";\n}\n"]}

package/dist/core/sandbox/supervisor.d.ts

@@ -3,6 +3,11 @@ export interface SandboxLaunch {
     readonly command: string;
     readonly args: readonly string[];
     readonly policy: SandboxPolicy;
+    /**
+     * A supervisor-owned private directory. Platform backends must never derive this
+     * from the workspace or fall back to it.
+     */
+    readonly supervisorStateDirectory: string;
     readonly environment?: NodeJS.ProcessEnv;
     /** Application/runtime directories needed by the child but never writable by it. */
     readonly readOnlyPaths?: readonly string[];
@@ -37,7 +42,13 @@ export interface SandboxBackend {
 }
 export interface SandboxSupervisor {
     readonly status: SandboxStatus;
-    launch(options: Omit<SandboxLaunch, "policy">): Promise<number>;
+    /**
+     * The supervisor may allocate this for low-level callers and tests. The backend
+     * still receives a required, private path on every launch.
+     */
+    launch(options: Omit<SandboxLaunch, "policy" | "supervisorStateDirectory"> & {
+        readonly supervisorStateDirectory?: string;
+    }): Promise<number>;
     close(): Promise<void>;
 }
 /**

package/dist/core/sandbox/supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhG,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjG;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;KACjC,CAAC;CACF;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAChD,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;CACtB,GAAG,iBAAiB,CAWpB","sourcesContent":["import { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n\t/**\n\t * Host executables projected read-only at an exact path inside the child. The\n\t * destination is chosen by the caller because only it knows where the child will\n\t * look; the backend just places the file there without write access.\n\t */\n\treadonly readOnlyBinaries?: readonly { readonly source: string; readonly destination: string }[];\n\t/**\n\t * The supervisor-owned credential write channel, when one was opened for this\n\t * launch. `hostSocketPath` is where the supervisor's writer listens; the backend\n\t * projects it to `childSocketPath`, which is also what the child is told through\n\t * `APEX_CREDENTIAL_PROXY_PATH`. Absent means the session has no credential write\n\t * path at all -- the mount stays read-only with no exception.\n\t */\n\treadonly credentialChannel?: {\n\t\treadonly hostSocketPath: string;\n\t\treadonly childSocketPath: string;\n\t};\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\tlaunch(options: Omit<SandboxLaunch, \"policy\">): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\treturn options.backend.launch({ ...launch, policy: options.policy });\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhG,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjG;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;KACjC,CAAC;CACF;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;OAGG;IACH,MAAM,CACL,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,0BAA0B,CAAC,GAAG;QACrE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;KAC3C,GACC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAChD,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;CACtB,GAAG,iBAAiB,CAoBpB","sourcesContent":["import { chmodSync, mkdtempSync, rmSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\t/**\n\t * A supervisor-owned private directory. Platform backends must never derive this\n\t * from the workspace or fall back to it.\n\t */\n\treadonly supervisorStateDirectory: string;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n\t/**\n\t * Host executables projected read-only at an exact path inside the child. The\n\t * destination is chosen by the caller because only it knows where the child will\n\t * look; the backend just places the file there without write access.\n\t */\n\treadonly readOnlyBinaries?: readonly { readonly source: string; readonly destination: string }[];\n\t/**\n\t * The supervisor-owned credential write channel, when one was opened for this\n\t * launch. `hostSocketPath` is where the supervisor's writer listens; the backend\n\t * projects it to `childSocketPath`, which is also what the child is told through\n\t * `APEX_CREDENTIAL_PROXY_PATH`. Absent means the session has no credential write\n\t * path at all -- the mount stays read-only with no exception.\n\t */\n\treadonly credentialChannel?: {\n\t\treadonly hostSocketPath: string;\n\t\treadonly childSocketPath: string;\n\t};\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\t/**\n\t * The supervisor may allocate this for low-level callers and tests. The backend\n\t * still receives a required, private path on every launch.\n\t */\n\tlaunch(\n\t\toptions: Omit<SandboxLaunch, \"policy\" | \"supervisorStateDirectory\"> & {\n\t\t\treadonly supervisorStateDirectory?: string;\n\t\t},\n\t): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\tconst ownsStateDirectory = launch.supervisorStateDirectory === undefined;\n\t\t\tconst supervisorStateDirectory =\n\t\t\t\tlaunch.supervisorStateDirectory ??\n\t\t\t\tmkdtempSync(join(tmpdir(), `apex-supervisor-${process.pid}-`), { encoding: \"utf8\" });\n\t\t\tif (ownsStateDirectory) chmodSync(supervisorStateDirectory, 0o700);\n\t\t\ttry {\n\t\t\t\treturn await options.backend.launch({ ...launch, supervisorStateDirectory, policy: options.policy });\n\t\t\t} finally {\n\t\t\t\tif (ownsStateDirectory) rmSync(supervisorStateDirectory, { force: true, recursive: true });\n\t\t\t}\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/supervisor.js

@@ -1,3 +1,6 @@
+import { chmodSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { requireSandboxEnforcement } from "./policy.js";
 /**
  * Owns fail-closed policy propagation and lifecycle; OS details remain behind the
@@ -8,7 +11,18 @@ export function createSandboxSupervisor(options) {
         status: options.backend.status,
         async launch(launch) {
             requireSandboxEnforcement(options.backend.status);
-            return options.backend.launch({ ...launch, policy: options.policy });
+            const ownsStateDirectory = launch.supervisorStateDirectory === undefined;
+            const supervisorStateDirectory = launch.supervisorStateDirectory ??
+                mkdtempSync(join(tmpdir(), `apex-supervisor-${process.pid}-`), { encoding: "utf8" });
+            if (ownsStateDirectory)
+                chmodSync(supervisorStateDirectory, 0o700);
+            try {
+                return await options.backend.launch({ ...launch, supervisorStateDirectory, policy: options.policy });
+            }
+            finally {
+                if (ownsStateDirectory)
+                    rmSync(supervisorStateDirectory, { force: true, recursive: true });
+            }
         },
         async close() {
             await options.backend.close();

package/dist/core/sandbox/supervisor.js.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAA0C,MAAM,aAAa,CAAC;AA2ChG;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAGvC,EAAqB;IACrB,OAAO;QACN,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM;QAC9B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;YACpB,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAAA,CACrE;QACD,KAAK,CAAC,KAAK,GAAG;YACb,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAAA,CAC9B;KACD,CAAC;AAAA,CACF","sourcesContent":["import { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n\t/**\n\t * Host executables projected read-only at an exact path inside the child. The\n\t * destination is chosen by the caller because only it knows where the child will\n\t * look; the backend just places the file there without write access.\n\t */\n\treadonly readOnlyBinaries?: readonly { readonly source: string; readonly destination: string }[];\n\t/**\n\t * The supervisor-owned credential write channel, when one was opened for this\n\t * launch. `hostSocketPath` is where the supervisor's writer listens; the backend\n\t * projects it to `childSocketPath`, which is also what the child is told through\n\t * `APEX_CREDENTIAL_PROXY_PATH`. Absent means the session has no credential write\n\t * path at all -- the mount stays read-only with no exception.\n\t */\n\treadonly credentialChannel?: {\n\t\treadonly hostSocketPath: string;\n\t\treadonly childSocketPath: string;\n\t};\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\tlaunch(options: Omit<SandboxLaunch, \"policy\">): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\treturn options.backend.launch({ ...launch, policy: options.policy });\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,yBAAyB,EAA0C,MAAM,aAAa,CAAC;AAwDhG;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAGvC,EAAqB;IACrB,OAAO;QACN,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM;QAC9B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;YACpB,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClD,MAAM,kBAAkB,GAAG,MAAM,CAAC,wBAAwB,KAAK,SAAS,CAAC;YACzE,MAAM,wBAAwB,GAC7B,MAAM,CAAC,wBAAwB;gBAC/B,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,mBAAmB,OAAO,CAAC,GAAG,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YACtF,IAAI,kBAAkB;gBAAE,SAAS,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;YACnE,IAAI,CAAC;gBACJ,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,wBAAwB,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YACtG,CAAC;oBAAS,CAAC;gBACV,IAAI,kBAAkB;oBAAE,MAAM,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5F,CAAC;QAAA,CACD;QACD,KAAK,CAAC,KAAK,GAAG;YACb,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAAA,CAC9B;KACD,CAAC;AAAA,CACF","sourcesContent":["import { chmodSync, mkdtempSync, rmSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\t/**\n\t * A supervisor-owned private directory. Platform backends must never derive this\n\t * from the workspace or fall back to it.\n\t */\n\treadonly supervisorStateDirectory: string;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n\t/**\n\t * Host executables projected read-only at an exact path inside the child. The\n\t * destination is chosen by the caller because only it knows where the child will\n\t * look; the backend just places the file there without write access.\n\t */\n\treadonly readOnlyBinaries?: readonly { readonly source: string; readonly destination: string }[];\n\t/**\n\t * The supervisor-owned credential write channel, when one was opened for this\n\t * launch. `hostSocketPath` is where the supervisor's writer listens; the backend\n\t * projects it to `childSocketPath`, which is also what the child is told through\n\t * `APEX_CREDENTIAL_PROXY_PATH`. Absent means the session has no credential write\n\t * path at all -- the mount stays read-only with no exception.\n\t */\n\treadonly credentialChannel?: {\n\t\treadonly hostSocketPath: string;\n\t\treadonly childSocketPath: string;\n\t};\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\t/**\n\t * The supervisor may allocate this for low-level callers and tests. The backend\n\t * still receives a required, private path on every launch.\n\t */\n\tlaunch(\n\t\toptions: Omit<SandboxLaunch, \"policy\" | \"supervisorStateDirectory\"> & {\n\t\t\treadonly supervisorStateDirectory?: string;\n\t\t},\n\t): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\tconst ownsStateDirectory = launch.supervisorStateDirectory === undefined;\n\t\t\tconst supervisorStateDirectory =\n\t\t\t\tlaunch.supervisorStateDirectory ??\n\t\t\t\tmkdtempSync(join(tmpdir(), `apex-supervisor-${process.pid}-`), { encoding: \"utf8\" });\n\t\t\tif (ownsStateDirectory) chmodSync(supervisorStateDirectory, 0o700);\n\t\t\ttry {\n\t\t\t\treturn await options.backend.launch({ ...launch, supervisorStateDirectory, policy: options.policy });\n\t\t\t} finally {\n\t\t\t\tif (ownsStateDirectory) rmSync(supervisorStateDirectory, { force: true, recursive: true });\n\t\t\t}\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/terminal-handoff.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Lends the terminal from the sandboxed child back to the supervisor for a prompt.
+ *
+ * The supervisor has to draw the escalation prompt itself. Per ADR 0023 an approval
+ * asserted from inside the boundary is indistinguishable from one forged by the code the
+ * boundary exists to contain, so the human's answer must be read by the side that owns the
+ * decision. The child cannot read it in any case: it runs under `bwrap --new-session` and
+ * has no controlling terminal, which `terminal-size.ts` documents for the same reason.
+ *
+ * The transport is the one `terminal-size.ts` already established -- a file in the
+ * workspace, which is bind-mounted into the child, watched on the other side. Signals are
+ * unavailable because bwrap sits between the processes as PID 1 and forwards nothing.
+ *
+ * Two files rather than one, because the supervisor must know the child has actually let
+ * go of stdin before it reads an answer. The child inherits stdin and its TUI holds it in
+ * raw mode; prompting while both sides read would lose keystrokes to whichever won.
+ *
+ * The child is asked, never obeyed. A child that never acknowledges delays the prompt by
+ * the timeout and no longer, because a contained process that could withhold
+ * acknowledgement indefinitely would be able to veto the human's decision -- which is the
+ * authority failure ADR 0023 forbids. An unread prompt is a legibility failure, and that
+ * is the direction this is allowed to fail in.
+ */
+/**
+ * Env var naming the directory holding the supervisor's command file.
+ *
+ * Supervisor-private where the platform backend allocates one (PS.3): the child reads the
+ * suspend/resume latch there and can never write it. The acknowledgement travels the other
+ * way and therefore has its own variable below.
+ */
+export declare const TERMINAL_HANDOFF_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_PATH";
+/**
+ * Env var naming the child-writable acknowledgement file.
+ *
+ * Absent means "the file next to the command file", which is the single-directory
+ * arrangement the macOS backend still uses. The two locations are kept explicit rather
+ * than derived because the platforms genuinely differ: Linux can put the command file on a
+ * host path the child sees read-only, and macOS has no `/home` tmpfs to separate them with.
+ */
+export declare const TERMINAL_HANDOFF_ACK_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_ACK_PATH";
+export interface TerminalHandoff {
+    /**
+     * Suspend the child, run `prompt` with the terminal to itself, then resume the child.
+     * Overlapping calls are serialised, so two prompts never share the terminal.
+     */
+    borrowTerminal<T>(prompt: () => Promise<T>): Promise<T>;
+    stop(): void;
+}
+export interface TerminalHandoffOptions {
+    acknowledgementTimeoutMs?: number;
+    /**
+     * Where the child writes its acknowledgement. Defaults to the file beside the command
+     * file. Split from it when the command file lives somewhere the child cannot write.
+     */
+    acknowledgementPath?: string;
+}
+/** Supervisor side. `directory` holds the command file; see the env vars above. */
+export declare function createTerminalHandoff(directory: string, options?: TerminalHandoffOptions): TerminalHandoff;
+/** Child side. Acknowledges a suspend once it has actually stopped drawing and reading. */
+export declare function observeTerminalHandoff(directory: string, hooks: {
+    suspend: () => void | Promise<void>;
+    resume: () => void | Promise<void>;
+}, options?: {
+    acknowledgementPath?: string;
+}): {
+    stop: () => void;
+};
+//# sourceMappingURL=terminal-handoff.d.ts.map

package/dist/core/sandbox/terminal-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-handoff.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/terminal-handoff.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,+BAA+B,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC,mCAAmC,CAAC;AA+CnF,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxD,IAAI,IAAI,IAAI,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACtC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAwF1G;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,EAClF,OAAO,CAAC,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAgDtB","sourcesContent":["import { closeSync, constants, type FSWatcher, openSync, readFileSync, rmSync, watch } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { writeWithoutFollowingLinks } from \"./terminal-size.ts\";\n\n/**\n * Lends the terminal from the sandboxed child back to the supervisor for a prompt.\n *\n * The supervisor has to draw the escalation prompt itself. Per ADR 0023 an approval\n * asserted from inside the boundary is indistinguishable from one forged by the code the\n * boundary exists to contain, so the human's answer must be read by the side that owns the\n * decision. The child cannot read it in any case: it runs under `bwrap --new-session` and\n * has no controlling terminal, which `terminal-size.ts` documents for the same reason.\n *\n * The transport is the one `terminal-size.ts` already established -- a file in the\n * workspace, which is bind-mounted into the child, watched on the other side. Signals are\n * unavailable because bwrap sits between the processes as PID 1 and forwards nothing.\n *\n * Two files rather than one, because the supervisor must know the child has actually let\n * go of stdin before it reads an answer. The child inherits stdin and its TUI holds it in\n * raw mode; prompting while both sides read would lose keystrokes to whichever won.\n *\n * The child is asked, never obeyed. A child that never acknowledges delays the prompt by\n * the timeout and no longer, because a contained process that could withhold\n * acknowledgement indefinitely would be able to veto the human's decision -- which is the\n * authority failure ADR 0023 forbids. An unread prompt is a legibility failure, and that\n * is the direction this is allowed to fail in.\n */\n\n/**\n * Env var naming the directory holding the supervisor's command file.\n *\n * Supervisor-private where the platform backend allocates one (PS.3): the child reads the\n * suspend/resume latch there and can never write it. The acknowledgement travels the other\n * way and therefore has its own variable below.\n */\nexport const TERMINAL_HANDOFF_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_PATH\";\n\n/**\n * Env var naming the child-writable acknowledgement file.\n *\n * Absent means \"the file next to the command file\", which is the single-directory\n * arrangement the macOS backend still uses. The two locations are kept explicit rather\n * than derived because the platforms genuinely differ: Linux can put the command file on a\n * host path the child sees read-only, and macOS has no `/home` tmpfs to separate them with.\n */\nexport const TERMINAL_HANDOFF_ACK_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_ACK_PATH\";\n\nconst STATE_FILE = \"terminal-handoff\";\nconst ACKNOWLEDGEMENT_FILE = \"terminal-handoff-ack\";\nconst DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS = 1_000;\n\n/**\n * Read without following a symlink at the final path component; undefined when refused.\n *\n * The acknowledgement is the one half of the handoff the contained side writes, so a link\n * planted at its path would otherwise let the child choose which host file the supervisor\n * reads. Its content is not authority (ADR 0023), but the read itself is the supervisor's.\n */\nfunction readWithoutFollowingLinks(path: string): string | undefined {\n\tlet descriptor: number;\n\ttry {\n\t\tdescriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);\n\t} catch {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn readFileSync(descriptor, \"utf8\");\n\t} catch {\n\t\treturn undefined;\n\t} finally {\n\t\tcloseSync(descriptor);\n\t}\n}\n\n/**\n * How often each side re-reads the state file, independently of the watcher.\n *\n * `fs.watch` is a thin wrapper over whatever the platform provides, and the platforms do\n * not agree. macOS CI delivered a resume more than a second after it was written, and\n * intermittently: the event arrives, late enough that a TUI would sit visibly frozen\n * after the human had already answered. The watcher still does the work in the common\n * case; this only bounds how wrong it can be.\n */\nconst POLL_INTERVAL_MS = 100;\n\ntype HandoffState = \"suspend\" | \"resume\";\n\nfunction parseState(contents: string): HandoffState | undefined {\n\tconst value = contents.trim();\n\treturn value === \"suspend\" || value === \"resume\" ? value : undefined;\n}\n\nexport interface TerminalHandoff {\n\t/**\n\t * Suspend the child, run `prompt` with the terminal to itself, then resume the child.\n\t * Overlapping calls are serialised, so two prompts never share the terminal.\n\t */\n\tborrowTerminal<T>(prompt: () => Promise<T>): Promise<T>;\n\tstop(): void;\n}\n\nexport interface TerminalHandoffOptions {\n\tacknowledgementTimeoutMs?: number;\n\t/**\n\t * Where the child writes its acknowledgement. Defaults to the file beside the command\n\t * file. Split from it when the command file lives somewhere the child cannot write.\n\t */\n\tacknowledgementPath?: string;\n}\n\n/** Supervisor side. `directory` holds the command file; see the env vars above. */\nexport function createTerminalHandoff(directory: string, options?: TerminalHandoffOptions): TerminalHandoff {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = options?.acknowledgementPath ?? join(directory, ACKNOWLEDGEMENT_FILE);\n\tconst acknowledgementDirectory = dirname(acknowledgementPath);\n\t// Floored at two poll intervals. The state file is a latch the child samples, so a\n\t// supervisor that gives up before the child can sample writes `resume` over its own\n\t// `suspend` and the child observes neither: it reads one value equal to what it\n\t// already held. Two intervals guarantee a sampling opportunity even when the\n\t// watcher never fires, which is the macOS case POLL_INTERVAL_MS exists for.\n\tconst timeout = Math.max(\n\t\toptions?.acknowledgementTimeoutMs ?? DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS,\n\t\tPOLL_INTERVAL_MS * 2,\n\t);\n\t// Every borrow chains onto the last, which is what keeps two escalations that arrive\n\t// together from drawing over each other.\n\tlet queue: Promise<unknown> = Promise.resolve();\n\n\tfunction write(state: HandoffState): void {\n\t\ttry {\n\t\t\twriteWithoutFollowingLinks(statePath, `${state}\\n`);\n\t\t} catch {\n\t\t\t// A handoff we cannot request still leaves the prompt readable often enough to\n\t\t\t// be worth attempting; it is never worth failing the escalation over.\n\t\t}\n\t}\n\n\tfunction waitForAcknowledgement(): Promise<void> {\n\t\treturn new Promise((resolve) => {\n\t\t\tlet watcher: FSWatcher | undefined;\n\t\t\tlet timer: NodeJS.Timeout | undefined;\n\t\t\tlet poll: NodeJS.Timeout | undefined;\n\t\t\tconst finish = () => {\n\t\t\t\tif (timer) clearTimeout(timer);\n\t\t\t\tif (poll) clearInterval(poll);\n\t\t\t\twatcher?.close();\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\t// No-follow: the acknowledgement path is the one half of the handoff the child\n\t\t\t\t// may write, so a link planted there would otherwise let it choose which host\n\t\t\t\t// file the supervisor reads.\n\t\t\t\tif (readWithoutFollowingLinks(acknowledgementPath)?.trim() === \"suspended\") finish();\n\t\t\t};\n\t\t\ttimer = setTimeout(finish, timeout);\n\t\t\ttry {\n\t\t\t\twatcher = watch(acknowledgementDirectory, check);\n\t\t\t} catch {\n\t\t\t\t// Without a watcher the poll below still delivers, just less promptly.\n\t\t\t}\n\t\t\tpoll = setInterval(check, POLL_INTERVAL_MS);\n\t\t\tpoll.unref();\n\t\t\tcheck();\n\t\t});\n\t}\n\n\tasync function run<T>(prompt: () => Promise<T>): Promise<T> {\n\t\ttry {\n\t\t\trmSync(acknowledgementPath, { force: true });\n\t\t} catch {\n\t\t\t// A stale acknowledgement is handled by the content check, not by its absence.\n\t\t}\n\t\twrite(\"suspend\");\n\t\tawait waitForAcknowledgement();\n\t\ttry {\n\t\t\treturn await prompt();\n\t\t} finally {\n\t\t\twrite(\"resume\");\n\t\t}\n\t}\n\n\treturn {\n\t\tborrowTerminal<T>(prompt: () => Promise<T>): Promise<T> {\n\t\t\tconst next = queue.then(\n\t\t\t\t() => run(prompt),\n\t\t\t\t() => run(prompt),\n\t\t\t);\n\t\t\t// Swallowed here only so one rejected borrow does not poison the queue for the\n\t\t\t// next; the caller still receives the rejection through `next`.\n\t\t\tqueue = next.then(\n\t\t\t\t() => undefined,\n\t\t\t\t() => undefined,\n\t\t\t);\n\t\t\treturn next;\n\t\t},\n\t\tstop(): void {\n\t\t\twrite(\"resume\");\n\t\t},\n\t};\n}\n\n/** Child side. Acknowledges a suspend once it has actually stopped drawing and reading. */\nexport function observeTerminalHandoff(\n\tdirectory: string,\n\thooks: { suspend: () => void | Promise<void>; resume: () => void | Promise<void> },\n\toptions?: { acknowledgementPath?: string },\n): { stop: () => void } {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = options?.acknowledgementPath ?? join(directory, ACKNOWLEDGEMENT_FILE);\n\tlet current: HandoffState = \"resume\";\n\tlet applying: Promise<void> = Promise.resolve();\n\n\tconst apply = () => {\n\t\tlet state: HandoffState | undefined;\n\t\ttry {\n\t\t\tstate = parseState(readFileSync(statePath, \"utf8\"));\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tif (!state || state === current) return;\n\t\tcurrent = state;\n\t\tapplying = applying.then(async () => {\n\t\t\tif (state === \"suspend\") {\n\t\t\t\tawait hooks.suspend();\n\t\t\t\ttry {\n\t\t\t\t\twriteWithoutFollowingLinks(acknowledgementPath, \"suspended\\n\");\n\t\t\t\t} catch {\n\t\t\t\t\t// The supervisor's timeout covers an acknowledgement we cannot write.\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tawait hooks.resume();\n\t\t\t}\n\t\t});\n\t};\n\n\tapply();\n\n\tlet watcher: FSWatcher | undefined;\n\ttry {\n\t\twatcher = watch(directory, apply);\n\t} catch {\n\t\t// Without a watcher the poll below still delivers, just less promptly.\n\t}\n\tconst poll = setInterval(apply, POLL_INTERVAL_MS);\n\t// Never hold the process open for this. The child exits on its own schedule and a\n\t// handoff that stops being observed at shutdown has nothing left to deliver.\n\tpoll.unref();\n\n\treturn {\n\t\tstop: () => {\n\t\t\twatcher?.close();\n\t\t\tclearInterval(poll);\n\t\t},\n\t};\n}\n"]}