apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/sandbox/network-proxy.js

@@ -2,6 +2,57 @@ import { existsSync, unlinkSync } from "node:fs";
 import * as http from "node:http";
 import * as net from "node:net";
 export function createSandboxNetworkProxy(options) {
+    /** Hosts a human permitted this session. Never persisted; a durable entry is a settings edit. */
+    const granted = new Set();
+    /**
+     * Approvals currently awaiting an answer, keyed the same way a grant is.
+     *
+     * A real prompt takes as long as a human takes to read it, and a refused host usually
+     * arrives as several near-simultaneous connections. Without this, each one raises its
+     * own prompt for the same question.
+     */
+    const pending = new Map();
+    function isHostReachable(hostname) {
+        if (options.allowedHosts.some((entry) => entry === hostname || entry.startsWith(`${hostname}:`)))
+            return true;
+        for (const grant of granted) {
+            if (grant === hostname || grant.startsWith(`${hostname}:`))
+                return true;
+        }
+        return false;
+    }
+    function isAllowed(hostname, port) {
+        return (options.allowedHosts.includes(hostname) ||
+            options.allowedHosts.includes(`${hostname}:${port}`) ||
+            granted.has(`${hostname}:${port}`));
+    }
+    async function approve(hostname, port) {
+        const key = `${hostname}:${port}`;
+        if (granted.has(key))
+            return true;
+        const inFlight = pending.get(key);
+        if (inFlight)
+            return inFlight;
+        // Declining is deliberately not remembered. A second attempt asks again, because a
+        // cached "no" would be indistinguishable to the user from the boundary having
+        // silently stopped asking.
+        const question = (async () => {
+            try {
+                const approved = await options.requestApproval(hostname, port);
+                if (approved)
+                    granted.add(key);
+                return approved;
+            }
+            catch {
+                return false;
+            }
+            finally {
+                pending.delete(key);
+            }
+        })();
+        pending.set(key, question);
+        return question;
+    }
     return new Promise((resolve, reject) => {
         const server = http.createServer((_req, res) => {
             res.writeHead(405, { "Content-Type": "text/plain" });
@@ -15,33 +66,54 @@ export function createSandboxNetworkProxy(options) {
             }
             const hostname = match[1];
             const port = Number.parseInt(match[2], 10);
-            const isAllowed = options.allowedHosts.includes(hostname) || options.allowedHosts.includes(`${hostname}:${port}`);
-            if (!isAllowed) {
-                clientSocket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
-                clientSocket.destroy();
+            function refuse() {
+                if (!clientSocket.destroyed) {
+                    clientSocket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+                    clientSocket.destroy();
+                }
                 options.violationStore?.add({
                     kind: "network",
                     command: `CONNECT ${hostname}:${port}`,
                     detail: `Host ${hostname} refused by allowlist policy.`,
                     timestamp: new Date(),
                 });
-                return;
             }
-            const serverSocket = net.connect(Number(port) || 443, hostname, () => {
-                clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
-                serverSocket.write(head);
-                serverSocket.pipe(clientSocket);
-                clientSocket.pipe(serverSocket);
-            });
-            serverSocket.on("error", () => {
-                if (!clientSocket.destroyed) {
-                    clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\n\r\n`);
-                    clientSocket.destroy();
+            if (!isAllowed(hostname, port)) {
+                if (!options.requestApproval) {
+                    refuse();
+                    return;
                 }
-            });
-            clientSocket.on("error", () => {
-                serverSocket.destroy();
-            });
+                // The client is left waiting on its CONNECT while the human reads the
+                // prompt, which is what makes an approved host resume the original request
+                // instead of surfacing as a failure the caller has to retry.
+                void approve(hostname, port).then((approved) => {
+                    if (approved)
+                        tunnel();
+                    else
+                        refuse();
+                });
+                return;
+            }
+            tunnel();
+            function tunnel() {
+                if (clientSocket.destroyed)
+                    return;
+                const serverSocket = net.connect(Number(port) || 443, hostname, () => {
+                    clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+                    serverSocket.write(head);
+                    serverSocket.pipe(clientSocket);
+                    clientSocket.pipe(serverSocket);
+                });
+                serverSocket.on("error", () => {
+                    if (!clientSocket.destroyed) {
+                        clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\n\r\n`);
+                        clientSocket.destroy();
+                    }
+                });
+                clientSocket.on("error", () => {
+                    serverSocket.destroy();
+                });
+            }
         });
         server.on("error", reject);
         if (options.tcpHost !== undefined) {
@@ -56,6 +128,7 @@ export function createSandboxNetworkProxy(options) {
                 resolve({
                     server,
                     port,
+                    isHostReachable,
                     close: () => new Promise((r) => server.close(() => r())),
                 });
             });
@@ -71,6 +144,7 @@ export function createSandboxNetworkProxy(options) {
             server.off("error", reject);
             resolve({
                 server,
+                isHostReachable,
                 close: () => new Promise((r) => server.close(() => r())),
             });
         });

package/dist/core/sandbox/network-proxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"network-proxy.js","sourceRoot":"","sources":["../../../src/core/sandbox/network-proxy.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, unlinkSync } from \"node:fs\";\nimport * as http from \"node:http\";\nimport * as net from \"node:net\";\nimport type { SandboxViolationStore } from \"./violations.ts\";\n\nexport interface SandboxNetworkProxy {\n\treadonly server: http.Server;\n\t/** Set only in TCP-listen mode (`tcpHost`); the ephemeral port the proxy bound. */\n\treadonly port?: number;\n\tclose(): Promise<void>;\n}\n\nexport function createSandboxNetworkProxy(\n\toptions: {\n\t\tallowedHosts: readonly string[];\n\t\tviolationStore?: SandboxViolationStore;\n\t} & ({ socketPath: string; tcpHost?: undefined } | { socketPath?: undefined; tcpHost: string }),\n): Promise<SandboxNetworkProxy> {\n\treturn new Promise((resolve, reject) => {\n\t\tconst server = http.createServer((_req, res) => {\n\t\t\tres.writeHead(405, { \"Content-Type\": \"text/plain\" });\n\t\t\tres.end(\"Method Not Allowed\\n\");\n\t\t});\n\n\t\tserver.on(\"connect\", (req, clientSocket, head) => {\n\t\t\tconst match = req.url?.match(/^([^:]+):(\\d+)$/);\n\t\t\tif (!match) {\n\t\t\t\tclientSocket.destroy();\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst hostname = match[1];\n\t\t\tconst port = Number.parseInt(match[2], 10);\n\n\t\t\tconst isAllowed =\n\t\t\t\toptions.allowedHosts.includes(hostname) || options.allowedHosts.includes(`${hostname}:${port}`);\n\t\t\tif (!isAllowed) {\n\t\t\t\tclientSocket.write(\"HTTP/1.1 403 Forbidden\\r\\n\\r\\n\");\n\t\t\t\tclientSocket.destroy();\n\t\t\t\toptions.violationStore?.add({\n\t\t\t\t\tkind: \"network\",\n\t\t\t\t\tcommand: `CONNECT ${hostname}:${port}`,\n\t\t\t\t\tdetail: `Host ${hostname} refused by allowlist policy.`,\n\t\t\t\t\ttimestamp: new Date(),\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst serverSocket = net.connect(Number(port) || 443, hostname, () => {\n\t\t\t\tclientSocket.write(\"HTTP/1.1 200 Connection Established\\r\\n\\r\\n\");\n\t\t\t\tserverSocket.write(head);\n\t\t\t\tserverSocket.pipe(clientSocket);\n\t\t\t\tclientSocket.pipe(serverSocket);\n\t\t\t});\n\n\t\t\tserverSocket.on(\"error\", () => {\n\t\t\t\tif (!clientSocket.destroyed) {\n\t\t\t\t\tclientSocket.write(`HTTP/1.1 502 Bad Gateway\\r\\n\\r\\n`);\n\t\t\t\t\tclientSocket.destroy();\n\t\t\t\t}\n\t\t\t});\n\n\t\t\tclientSocket.on(\"error\", () => {\n\t\t\t\tserverSocket.destroy();\n\t\t\t});\n\t\t});\n\n\t\tserver.on(\"error\", reject);\n\n\t\tif (options.tcpHost !== undefined) {\n\t\t\t// macOS's Seatbelt can permit a specific localhost port directly, so the\n\t\t\t// proxy listens on loopback TCP there instead of a Unix domain socket --\n\t\t\t// no in-child relay process is needed the way Linux's `--unshare-net`\n\t\t\t// requires one.\n\t\t\tserver.listen(0, options.tcpHost, () => {\n\t\t\t\tserver.off(\"error\", reject);\n\t\t\t\tconst address = server.address();\n\t\t\t\tconst port = typeof address === \"object\" && address !== null ? address.port : undefined;\n\t\t\t\tresolve({\n\t\t\t\t\tserver,\n\t\t\t\t\tport,\n\t\t\t\t\tclose: () => new Promise((r) => server.close(() => r())),\n\t\t\t\t});\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\n\t\t// A prior sandboxed launch that never called close() (a crash, a SIGKILL)\n\t\t// leaves a stale socket file behind; Node's listen() refuses to bind over\n\t\t// one even though nothing is listening on it.\n\t\tif (existsSync(options.socketPath)) {\n\t\t\tunlinkSync(options.socketPath);\n\t\t}\n\n\t\tserver.listen(options.socketPath, () => {\n\t\t\tserver.off(\"error\", reject);\n\t\t\tresolve({\n\t\t\t\tserver,\n\t\t\t\tclose: () => new Promise((r) => server.close(() => r())),\n\t\t\t});\n\t\t});\n\t});\n}\n"]}
+{"version":3,"file":"network-proxy.js","sourceRoot":"","sources":["../../../src/core/sandbox/network-proxy.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, unlinkSync } from \"node:fs\";\nimport * as http from \"node:http\";\nimport * as net from \"node:net\";\nimport type { SandboxViolationStore } from \"./violations.ts\";\n\nexport interface SandboxNetworkProxy {\n\treadonly server: http.Server;\n\t/** Set only in TCP-listen mode (`tcpHost`); the ephemeral port the proxy bound. */\n\treadonly port?: number;\n\t/**\n\t * Whether this session may reach `hostname` on any port, by configuration or by a\n\t * grant the human made this session.\n\t *\n\t * Exposed so the git credential channel can ask the one component that actually knows,\n\t * rather than keeping a second copy of the allowlist that would drift from this one the\n\t * first time a host is approved at runtime.\n\t */\n\tisHostReachable(hostname: string): boolean;\n\tclose(): Promise<void>;\n}\n\nexport function createSandboxNetworkProxy(\n\toptions: {\n\t\tallowedHosts: readonly string[];\n\t\tviolationStore?: SandboxViolationStore;\n\t\t/**\n\t\t * Ask a human whether to permit one refused host for the rest of this session.\n\t\t *\n\t\t * Supplied by the supervisor and never by the child: per ADR 0023, an approval\n\t\t * asserted from inside the boundary would be indistinguishable from one forged by\n\t\t * the code the boundary exists to contain. Absent means deny without asking, which\n\t\t * is exactly today's behaviour and what ADR 0005 requires of headless, print,\n\t\t * JSON, and RPC modes.\n\t\t */\n\t\trequestApproval?: (hostname: string, port: number) => Promise<boolean>;\n\t} & ({ socketPath: string; tcpHost?: undefined } | { socketPath?: undefined; tcpHost: string }),\n): Promise<SandboxNetworkProxy> {\n\t/** Hosts a human permitted this session. Never persisted; a durable entry is a settings edit. */\n\tconst granted = new Set<string>();\n\t/**\n\t * Approvals currently awaiting an answer, keyed the same way a grant is.\n\t *\n\t * A real prompt takes as long as a human takes to read it, and a refused host usually\n\t * arrives as several near-simultaneous connections. Without this, each one raises its\n\t * own prompt for the same question.\n\t */\n\tconst pending = new Map<string, Promise<boolean>>();\n\n\tfunction isHostReachable(hostname: string): boolean {\n\t\tif (options.allowedHosts.some((entry) => entry === hostname || entry.startsWith(`${hostname}:`))) return true;\n\t\tfor (const grant of granted) {\n\t\t\tif (grant === hostname || grant.startsWith(`${hostname}:`)) return true;\n\t\t}\n\t\treturn false;\n\t}\n\n\tfunction isAllowed(hostname: string, port: number): boolean {\n\t\treturn (\n\t\t\toptions.allowedHosts.includes(hostname) ||\n\t\t\toptions.allowedHosts.includes(`${hostname}:${port}`) ||\n\t\t\tgranted.has(`${hostname}:${port}`)\n\t\t);\n\t}\n\n\tasync function approve(hostname: string, port: number): Promise<boolean> {\n\t\tconst key = `${hostname}:${port}`;\n\t\tif (granted.has(key)) return true;\n\t\tconst inFlight = pending.get(key);\n\t\tif (inFlight) return inFlight;\n\t\t// Declining is deliberately not remembered. A second attempt asks again, because a\n\t\t// cached \"no\" would be indistinguishable to the user from the boundary having\n\t\t// silently stopped asking.\n\t\tconst question = (async () => {\n\t\t\ttry {\n\t\t\t\tconst approved = await (options.requestApproval as (h: string, p: number) => Promise<boolean>)(\n\t\t\t\t\thostname,\n\t\t\t\t\tport,\n\t\t\t\t);\n\t\t\t\tif (approved) granted.add(key);\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(key);\n\t\t\t}\n\t\t})();\n\t\tpending.set(key, question);\n\t\treturn question;\n\t}\n\n\treturn new Promise((resolve, reject) => {\n\t\tconst server = http.createServer((_req, res) => {\n\t\t\tres.writeHead(405, { \"Content-Type\": \"text/plain\" });\n\t\t\tres.end(\"Method Not Allowed\\n\");\n\t\t});\n\n\t\tserver.on(\"connect\", (req, clientSocket, head) => {\n\t\t\tconst match = req.url?.match(/^([^:]+):(\\d+)$/);\n\t\t\tif (!match) {\n\t\t\t\tclientSocket.destroy();\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst hostname = match[1];\n\t\t\tconst port = Number.parseInt(match[2], 10);\n\n\t\t\tfunction refuse(): void {\n\t\t\t\tif (!clientSocket.destroyed) {\n\t\t\t\t\tclientSocket.write(\"HTTP/1.1 403 Forbidden\\r\\n\\r\\n\");\n\t\t\t\t\tclientSocket.destroy();\n\t\t\t\t}\n\t\t\t\toptions.violationStore?.add({\n\t\t\t\t\tkind: \"network\",\n\t\t\t\t\tcommand: `CONNECT ${hostname}:${port}`,\n\t\t\t\t\tdetail: `Host ${hostname} refused by allowlist policy.`,\n\t\t\t\t\ttimestamp: new Date(),\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (!isAllowed(hostname, port)) {\n\t\t\t\tif (!options.requestApproval) {\n\t\t\t\t\trefuse();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// The client is left waiting on its CONNECT while the human reads the\n\t\t\t\t// prompt, which is what makes an approved host resume the original request\n\t\t\t\t// instead of surfacing as a failure the caller has to retry.\n\t\t\t\tvoid approve(hostname, port).then((approved) => {\n\t\t\t\t\tif (approved) tunnel();\n\t\t\t\t\telse refuse();\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\ttunnel();\n\n\t\t\tfunction tunnel(): void {\n\t\t\t\tif (clientSocket.destroyed) return;\n\t\t\t\tconst serverSocket = net.connect(Number(port) || 443, hostname, () => {\n\t\t\t\t\tclientSocket.write(\"HTTP/1.1 200 Connection Established\\r\\n\\r\\n\");\n\t\t\t\t\tserverSocket.write(head);\n\t\t\t\t\tserverSocket.pipe(clientSocket);\n\t\t\t\t\tclientSocket.pipe(serverSocket);\n\t\t\t\t});\n\n\t\t\t\tserverSocket.on(\"error\", () => {\n\t\t\t\t\tif (!clientSocket.destroyed) {\n\t\t\t\t\t\tclientSocket.write(`HTTP/1.1 502 Bad Gateway\\r\\n\\r\\n`);\n\t\t\t\t\t\tclientSocket.destroy();\n\t\t\t\t\t}\n\t\t\t\t});\n\n\t\t\t\tclientSocket.on(\"error\", () => {\n\t\t\t\t\tserverSocket.destroy();\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\n\t\tserver.on(\"error\", reject);\n\n\t\tif (options.tcpHost !== undefined) {\n\t\t\t// macOS's Seatbelt can permit a specific localhost port directly, so the\n\t\t\t// proxy listens on loopback TCP there instead of a Unix domain socket --\n\t\t\t// no in-child relay process is needed the way Linux's `--unshare-net`\n\t\t\t// requires one.\n\t\t\tserver.listen(0, options.tcpHost, () => {\n\t\t\t\tserver.off(\"error\", reject);\n\t\t\t\tconst address = server.address();\n\t\t\t\tconst port = typeof address === \"object\" && address !== null ? address.port : undefined;\n\t\t\t\tresolve({\n\t\t\t\t\tserver,\n\t\t\t\t\tport,\n\t\t\t\t\tisHostReachable,\n\t\t\t\t\tclose: () => new Promise((r) => server.close(() => r())),\n\t\t\t\t});\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\n\t\t// A prior sandboxed launch that never called close() (a crash, a SIGKILL)\n\t\t// leaves a stale socket file behind; Node's listen() refuses to bind over\n\t\t// one even though nothing is listening on it.\n\t\tif (existsSync(options.socketPath)) {\n\t\t\tunlinkSync(options.socketPath);\n\t\t}\n\n\t\tserver.listen(options.socketPath, () => {\n\t\t\tserver.off(\"error\", reject);\n\t\t\tresolve({\n\t\t\t\tserver,\n\t\t\t\tisHostReachable,\n\t\t\t\tclose: () => new Promise((r) => server.close(() => r())),\n\t\t\t});\n\t\t});\n\t});\n}\n"]}

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

@@ -1,6 +1,13 @@
 export interface SandboxPolicy {
+    /**
+     * The one directory the session is anchored to. State, sessions, and the concurrency
+     * lease all live under it, and the child starts here, so it stays singular even when
+     * more roots are writable.
+     */
     readonly workspace: string;
     readonly allowedHosts: readonly string[];
+    /** Further writable directories, named on the command line and validated the same way. */
+    readonly additionalWritableRoots: readonly string[];
 }
 export type SandboxPolicyResult = {
     readonly kind: "valid";
@@ -26,6 +33,7 @@ export declare class SandboxUnavailableError extends Error {
 export declare function createSandboxPolicy(options: {
     workspace: string;
     allowedHosts?: readonly string[];
+    additionalWritableRoots?: readonly string[];
 }): SandboxPolicyResult;
 /** Throws rather than returning an executable fallback when OS enforcement is absent. */
 export declare function requireSandboxEnforcement(status: SandboxStatus): void;

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

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAM,EAAE,MAAM,EAGzB;CACD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,GAAG,mBAAmB,CAiBtB;AAED,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAGrE","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n}): SandboxPolicyResult {\n\tif (!isAbsolute(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: \"Sandbox workspace must be an absolute path.\" };\n\t}\n\tif (!existsSync(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace does not exist: ${options.workspace}` };\n\t}\n\tif (!statSync(options.workspace).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace is not a directory: ${options.workspace}` };\n\t}\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: {\n\t\t\tworkspace: realpathSync(options.workspace),\n\t\t\tallowedHosts: options.allowedHosts ?? [],\n\t\t},\n\t};\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAM,EAAE,MAAM,EAGzB;CACD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C,GAAG,mBAAmB,CAetB;AAsBD,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAGrE","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\t/**\n\t * The one directory the session is anchored to. State, sessions, and the concurrency\n\t * lease all live under it, and the child starts here, so it stays singular even when\n\t * more roots are writable.\n\t */\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n\t/** Further writable directories, named on the command line and validated the same way. */\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n\tadditionalWritableRoots?: readonly string[];\n}): SandboxPolicyResult {\n\tconst workspace = validateRoot(options.workspace, \"workspace\");\n\tif (typeof workspace !== \"string\") return workspace;\n\n\tconst additionalWritableRoots: string[] = [];\n\tfor (const candidate of options.additionalWritableRoots ?? []) {\n\t\tconst resolved = validateRoot(candidate, \"writable root\");\n\t\tif (typeof resolved !== \"string\") return resolved;\n\t\tadditionalWritableRoots.push(resolved);\n\t}\n\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: { workspace, allowedHosts: options.allowedHosts ?? [], additionalWritableRoots },\n\t};\n}\n\n/**\n * Resolve one writable root, or explain why it cannot be one.\n *\n * Every root goes through the same check for the same reason the workspace always did: a\n * backend must never silently broaden an ambiguous path into host authority, and an extra\n * root named on the command line is no less capable of doing that than the first one.\n */\nfunction validateRoot(candidate: string, label: string): string | { kind: \"invalid\"; reason: string } {\n\tif (!isAbsolute(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} must be an absolute path: ${candidate}` };\n\t}\n\tif (!existsSync(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} does not exist: ${candidate}` };\n\t}\n\tif (!statSync(candidate).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} is not a directory: ${candidate}` };\n\t}\n\treturn realpathSync(candidate);\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}

package/dist/core/sandbox/policy.js

@@ -12,23 +12,40 @@ export class SandboxUnavailableError extends Error {
  * silently broaden an ambiguous path into host authority.
  */
 export function createSandboxPolicy(options) {
-    if (!isAbsolute(options.workspace)) {
-        return { kind: "invalid", reason: "Sandbox workspace must be an absolute path." };
-    }
-    if (!existsSync(options.workspace)) {
-        return { kind: "invalid", reason: `Sandbox workspace does not exist: ${options.workspace}` };
-    }
-    if (!statSync(options.workspace).isDirectory()) {
-        return { kind: "invalid", reason: `Sandbox workspace is not a directory: ${options.workspace}` };
+    const workspace = validateRoot(options.workspace, "workspace");
+    if (typeof workspace !== "string")
+        return workspace;
+    const additionalWritableRoots = [];
+    for (const candidate of options.additionalWritableRoots ?? []) {
+        const resolved = validateRoot(candidate, "writable root");
+        if (typeof resolved !== "string")
+            return resolved;
+        additionalWritableRoots.push(resolved);
     }
     return {
         kind: "valid",
-        policy: {
-            workspace: realpathSync(options.workspace),
-            allowedHosts: options.allowedHosts ?? [],
-        },
+        policy: { workspace, allowedHosts: options.allowedHosts ?? [], additionalWritableRoots },
     };
 }
+/**
+ * Resolve one writable root, or explain why it cannot be one.
+ *
+ * Every root goes through the same check for the same reason the workspace always did: a
+ * backend must never silently broaden an ambiguous path into host authority, and an extra
+ * root named on the command line is no less capable of doing that than the first one.
+ */
+function validateRoot(candidate, label) {
+    if (!isAbsolute(candidate)) {
+        return { kind: "invalid", reason: `Sandbox ${label} must be an absolute path: ${candidate}` };
+    }
+    if (!existsSync(candidate)) {
+        return { kind: "invalid", reason: `Sandbox ${label} does not exist: ${candidate}` };
+    }
+    if (!statSync(candidate).isDirectory()) {
+        return { kind: "invalid", reason: `Sandbox ${label} is not a directory: ${candidate}` };
+    }
+    return realpathSync(candidate);
+}
 /** Throws rather than returning an executable fallback when OS enforcement is absent. */
 export function requireSandboxEnforcement(status) {
     if (status.kind === "enforced")

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

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAavC,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAc,EAAE;QAC3B,KAAK,CAAC,mDAAmD,MAAM,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAAA,CACtC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAGnC,EAAuB;IACvB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,6CAA6C,EAAE,CAAC;IACnF,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,qCAAqC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,yCAAyC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;IAClG,CAAC;IACD,OAAO;QACN,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACP,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC;YAC1C,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;SACxC;KACD,CAAC;AAAA,CACF;AAED,yFAAyF;AACzF,MAAM,UAAU,yBAAyB,CAAC,MAAqB,EAAQ;IACtE,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO;IACvC,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAAA,CACjD","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n}): SandboxPolicyResult {\n\tif (!isAbsolute(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: \"Sandbox workspace must be an absolute path.\" };\n\t}\n\tif (!existsSync(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace does not exist: ${options.workspace}` };\n\t}\n\tif (!statSync(options.workspace).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace is not a directory: ${options.workspace}` };\n\t}\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: {\n\t\t\tworkspace: realpathSync(options.workspace),\n\t\t\tallowedHosts: options.allowedHosts ?? [],\n\t\t},\n\t};\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAoBvC,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAc,EAAE;QAC3B,KAAK,CAAC,mDAAmD,MAAM,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAAA,CACtC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAInC,EAAuB;IACvB,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC/D,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAEpD,MAAM,uBAAuB,GAAa,EAAE,CAAC;IAC7C,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,uBAAuB,IAAI,EAAE,EAAE,CAAC;QAC/D,MAAM,QAAQ,GAAG,YAAY,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;QAC1D,IAAI,OAAO,QAAQ,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAClD,uBAAuB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,OAAO;QACN,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE,EAAE,uBAAuB,EAAE;KACxF,CAAC;AAAA,CACF;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,SAAiB,EAAE,KAAa,EAAgD;IACrG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,KAAK,8BAA8B,SAAS,EAAE,EAAE,CAAC;IAC/F,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,KAAK,oBAAoB,SAAS,EAAE,EAAE,CAAC;IACrF,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,KAAK,wBAAwB,SAAS,EAAE,EAAE,CAAC;IACzF,CAAC;IACD,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;AAAA,CAC/B;AAED,yFAAyF;AACzF,MAAM,UAAU,yBAAyB,CAAC,MAAqB,EAAQ;IACtE,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO;IACvC,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAAA,CACjD","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\t/**\n\t * The one directory the session is anchored to. State, sessions, and the concurrency\n\t * lease all live under it, and the child starts here, so it stays singular even when\n\t * more roots are writable.\n\t */\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n\t/** Further writable directories, named on the command line and validated the same way. */\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n\tadditionalWritableRoots?: readonly string[];\n}): SandboxPolicyResult {\n\tconst workspace = validateRoot(options.workspace, \"workspace\");\n\tif (typeof workspace !== \"string\") return workspace;\n\n\tconst additionalWritableRoots: string[] = [];\n\tfor (const candidate of options.additionalWritableRoots ?? []) {\n\t\tconst resolved = validateRoot(candidate, \"writable root\");\n\t\tif (typeof resolved !== \"string\") return resolved;\n\t\tadditionalWritableRoots.push(resolved);\n\t}\n\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: { workspace, allowedHosts: options.allowedHosts ?? [], additionalWritableRoots },\n\t};\n}\n\n/**\n * Resolve one writable root, or explain why it cannot be one.\n *\n * Every root goes through the same check for the same reason the workspace always did: a\n * backend must never silently broaden an ambiguous path into host authority, and an extra\n * root named on the command line is no less capable of doing that than the first one.\n */\nfunction validateRoot(candidate: string, label: string): string | { kind: \"invalid\"; reason: string } {\n\tif (!isAbsolute(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} must be an absolute path: ${candidate}` };\n\t}\n\tif (!existsSync(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} does not exist: ${candidate}` };\n\t}\n\tif (!statSync(candidate).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} is not a directory: ${candidate}` };\n\t}\n\treturn realpathSync(candidate);\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}

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

@@ -0,0 +1,25 @@
+/**
+ * A named, saved combination of what the OS boundary permits.
+ *
+ * Apex already has a permission rule model with five modes and eight-source precedence
+ * (ADR 0004). That governs the tool gate at `beforeToolCall`, inside the child. This
+ * governs the supervisor's launch contract, outside it. They are deliberately separate
+ * surfaces, and conflating them is exactly the misreading that makes `bypassPermissions`
+ * look like a sandbox escape -- so a profile here carries only boundary inputs and has no
+ * way to express a tool-gate mode.
+ *
+ * It also has no way to express "no boundary". That decision stays on the command line
+ * where a human has to type it, per ADR 0005's 2026-08-28 amendment; a profile can widen
+ * what is reachable and writable, never remove the boundary that constrains them.
+ *
+ * Resolved from global settings only, with `projectTrusted: false`, for the reason ADR
+ * 0016 gives for every supervisor policy input: a repository that could define the
+ * boundary it runs under would be granting itself authority.
+ */
+export interface SandboxProfile {
+    readonly allowedHosts: readonly string[];
+    readonly additionalWritableRoots: readonly string[];
+}
+/** Resolve one named profile, or undefined when the name is absent or was never given. */
+export declare function resolveSandboxProfile(name: string | undefined, cwd: string, agentDir: string): SandboxProfile | undefined;
+//# sourceMappingURL=profiles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/profiles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAMD,0FAA0F;AAC1F,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACd,cAAc,GAAG,SAAS,CAc5B","sourcesContent":["import { SettingsManager } from \"../settings-manager.ts\";\n\n/**\n * A named, saved combination of what the OS boundary permits.\n *\n * Apex already has a permission rule model with five modes and eight-source precedence\n * (ADR 0004). That governs the tool gate at `beforeToolCall`, inside the child. This\n * governs the supervisor's launch contract, outside it. They are deliberately separate\n * surfaces, and conflating them is exactly the misreading that makes `bypassPermissions`\n * look like a sandbox escape -- so a profile here carries only boundary inputs and has no\n * way to express a tool-gate mode.\n *\n * It also has no way to express \"no boundary\". That decision stays on the command line\n * where a human has to type it, per ADR 0005's 2026-08-28 amendment; a profile can widen\n * what is reachable and writable, never remove the boundary that constrains them.\n *\n * Resolved from global settings only, with `projectTrusted: false`, for the reason ADR\n * 0016 gives for every supervisor policy input: a repository that could define the\n * boundary it runs under would be granting itself authority.\n */\nexport interface SandboxProfile {\n\treadonly allowedHosts: readonly string[];\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nfunction stringArray(value: unknown): string[] {\n\treturn Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === \"string\") : [];\n}\n\n/** Resolve one named profile, or undefined when the name is absent or was never given. */\nexport function resolveSandboxProfile(\n\tname: string | undefined,\n\tcwd: string,\n\tagentDir: string,\n): SandboxProfile | undefined {\n\tif (!name) return undefined;\n\tconst settings = SettingsManager.create(cwd, agentDir, { projectTrusted: false });\n\tconst profiles = settings.getSandboxProfiles();\n\tconst profile = profiles?.[name];\n\tif (!profile || typeof profile !== \"object\") return undefined;\n\tconst record = profile as Record<string, unknown>;\n\t// Only these two keys are read. An unknown key in a profile is ignored rather than\n\t// rejected, so a profile written for a later version does not break this one, and a\n\t// key this version does not understand can never take effect by accident.\n\treturn {\n\t\tallowedHosts: stringArray(record.allowedHosts),\n\t\tadditionalWritableRoots: stringArray(record.additionalWritableRoots),\n\t};\n}\n"]}

package/dist/core/sandbox/profiles.js

@@ -0,0 +1,23 @@
+import { SettingsManager } from "../settings-manager.js";
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+/** Resolve one named profile, or undefined when the name is absent or was never given. */
+export function resolveSandboxProfile(name, cwd, agentDir) {
+    if (!name)
+        return undefined;
+    const settings = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+    const profiles = settings.getSandboxProfiles();
+    const profile = profiles?.[name];
+    if (!profile || typeof profile !== "object")
+        return undefined;
+    const record = profile;
+    // Only these two keys are read. An unknown key in a profile is ignored rather than
+    // rejected, so a profile written for a later version does not break this one, and a
+    // key this version does not understand can never take effect by accident.
+    return {
+        allowedHosts: stringArray(record.allowedHosts),
+        additionalWritableRoots: stringArray(record.additionalWritableRoots),
+    };
+}
+//# sourceMappingURL=profiles.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../../src/core/sandbox/profiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAyBzD,SAAS,WAAW,CAAC,KAAc,EAAY;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAAA,CACvG;AAED,0FAA0F;AAC1F,MAAM,UAAU,qBAAqB,CACpC,IAAwB,EACxB,GAAW,EACX,QAAgB,EACa;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,QAAQ,CAAC,kBAAkB,EAAE,CAAC;IAC/C,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,MAAM,GAAG,OAAkC,CAAC;IAClD,mFAAmF;IACnF,oFAAoF;IACpF,0EAA0E;IAC1E,OAAO;QACN,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,YAAY,CAAC;QAC9C,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAAC,uBAAuB,CAAC;KACpE,CAAC;AAAA,CACF","sourcesContent":["import { SettingsManager } from \"../settings-manager.ts\";\n\n/**\n * A named, saved combination of what the OS boundary permits.\n *\n * Apex already has a permission rule model with five modes and eight-source precedence\n * (ADR 0004). That governs the tool gate at `beforeToolCall`, inside the child. This\n * governs the supervisor's launch contract, outside it. They are deliberately separate\n * surfaces, and conflating them is exactly the misreading that makes `bypassPermissions`\n * look like a sandbox escape -- so a profile here carries only boundary inputs and has no\n * way to express a tool-gate mode.\n *\n * It also has no way to express \"no boundary\". That decision stays on the command line\n * where a human has to type it, per ADR 0005's 2026-08-28 amendment; a profile can widen\n * what is reachable and writable, never remove the boundary that constrains them.\n *\n * Resolved from global settings only, with `projectTrusted: false`, for the reason ADR\n * 0016 gives for every supervisor policy input: a repository that could define the\n * boundary it runs under would be granting itself authority.\n */\nexport interface SandboxProfile {\n\treadonly allowedHosts: readonly string[];\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nfunction stringArray(value: unknown): string[] {\n\treturn Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === \"string\") : [];\n}\n\n/** Resolve one named profile, or undefined when the name is absent or was never given. */\nexport function resolveSandboxProfile(\n\tname: string | undefined,\n\tcwd: string,\n\tagentDir: string,\n): SandboxProfile | undefined {\n\tif (!name) return undefined;\n\tconst settings = SettingsManager.create(cwd, agentDir, { projectTrusted: false });\n\tconst profiles = settings.getSandboxProfiles();\n\tconst profile = profiles?.[name];\n\tif (!profile || typeof profile !== \"object\") return undefined;\n\tconst record = profile as Record<string, unknown>;\n\t// Only these two keys are read. An unknown key in a profile is ignored rather than\n\t// rejected, so a profile written for a later version does not break this one, and a\n\t// key this version does not understand can never take effect by accident.\n\treturn {\n\t\tallowedHosts: stringArray(record.allowedHosts),\n\t\tadditionalWritableRoots: stringArray(record.additionalWritableRoots),\n\t};\n}\n"]}

package/dist/core/sandbox/rpc/command-client.d.ts

@@ -0,0 +1,28 @@
+/** The absolute path a sandbox filesystem refusal named, if the output named one. */
+export declare function extractRefusedPath(output: string): string | undefined;
+/** True when the output looks like the boundary refused a write rather than the command failing. */
+export declare function looksLikeSandboxRefusal(output: string): boolean;
+/**
+ * The directory an escalation should make writable for a refused path.
+ *
+ * The parent, not the file: the command was creating something that does not exist, and a
+ * bind of a non-existent path is not a mount bwrap can make.
+ */
+export declare function escalationRootFor(refusedPath: string): string;
+export interface EscalationOutcome {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Ask the supervisor to run one command with one extra writable root.
+ *
+ * Resolves undefined for every refusal and every failure alike, because the caller's
+ * behaviour is identical in both cases: report the original error. Only a command that
+ * actually ran returns anything.
+ */
+export declare function requestCommandEscalation(request: {
+    command: string;
+    writableRoot: string;
+}, socketPath?: string | undefined): Promise<EscalationOutcome | undefined>;
+//# sourceMappingURL=command-client.d.ts.map

package/dist/core/sandbox/rpc/command-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-client.d.ts","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/command-client.ts"],"names":[],"mappings":"AAsBA,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOrE;AAED,oGAAoG;AACpG,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAClD,UAAU,qBAAkD,GAC1D,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAgCxC","sourcesContent":["import * as net from \"node:net\";\nimport { dirname, isAbsolute } from \"node:path\";\nimport { COMMAND_ESCALATION_SOCKET_VARIABLE } from \"./command-proxy.ts\";\n\n/**\n * The child's side of per-command escalation.\n *\n * The path this extracts is a guess, and it is allowed to be, because nothing safe rests\n * on it. The supervisor shows the human the exact command and the exact root before\n * anything runs, so a bad guess is refused by someone reading it rather than silently\n * granted. What the guess buys is not having to make the user work out which directory to\n * name; when it finds nothing, no escalation is offered and the command fails as it did\n * before.\n */\n\n/** The wordings the kernel and the shell actually produce for a mount refusal. */\nconst REFUSAL_PATTERNS: readonly RegExp[] = [\n\t/cannot (?:create|touch|remove|open) ['\"]?([^'\":]+)['\"]?: (?:Read-only file system|Permission denied)/i,\n\t/^[^:]*: ?([/][^\\s:]+): (?:Operation not permitted|Permission denied|Read-only file system)/im,\n\t/(?:EROFS|EACCES|EPERM)[^'\"]*['\"]([/][^'\"]+)['\"]/,\n];\n\n/** The absolute path a sandbox filesystem refusal named, if the output named one. */\nexport function extractRefusedPath(output: string): string | undefined {\n\tfor (const pattern of REFUSAL_PATTERNS) {\n\t\tconst match = pattern.exec(output);\n\t\tconst candidate = match?.[1]?.trim();\n\t\tif (candidate && isAbsolute(candidate)) return candidate;\n\t}\n\treturn undefined;\n}\n\n/** True when the output looks like the boundary refused a write rather than the command failing. */\nexport function looksLikeSandboxRefusal(output: string): boolean {\n\treturn /Read-only file system|Operation not permitted|Permission denied/i.test(output);\n}\n\n/**\n * The directory an escalation should make writable for a refused path.\n *\n * The parent, not the file: the command was creating something that does not exist, and a\n * bind of a non-existent path is not a mount bwrap can make.\n */\nexport function escalationRootFor(refusedPath: string): string {\n\treturn dirname(refusedPath);\n}\n\nexport interface EscalationOutcome {\n\treadonly code: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\n/**\n * Ask the supervisor to run one command with one extra writable root.\n *\n * Resolves undefined for every refusal and every failure alike, because the caller's\n * behaviour is identical in both cases: report the original error. Only a command that\n * actually ran returns anything.\n */\nexport function requestCommandEscalation(\n\trequest: { command: string; writableRoot: string },\n\tsocketPath = process.env[COMMAND_ESCALATION_SOCKET_VARIABLE],\n): Promise<EscalationOutcome | undefined> {\n\tif (!socketPath) return Promise.resolve(undefined);\n\treturn new Promise((resolve) => {\n\t\tconst socket = net.connect(socketPath);\n\t\tlet buffer = \"\";\n\t\tconst giveUp = () => {\n\t\t\tsocket.destroy();\n\t\t\tresolve(undefined);\n\t\t};\n\t\tsocket.on(\"connect\", () => socket.write(`${JSON.stringify({ op: \"run\", ...request })}\\n`));\n\t\tsocket.on(\"data\", (chunk) => {\n\t\t\tbuffer += chunk.toString();\n\t\t\tconst newline = buffer.indexOf(\"\\n\");\n\t\t\tif (newline < 0) return;\n\t\t\tsocket.destroy();\n\t\t\ttry {\n\t\t\t\tconst response = JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>;\n\t\t\t\tif (response.ok === true && typeof response.code === \"number\") {\n\t\t\t\t\tresolve({\n\t\t\t\t\t\tcode: response.code,\n\t\t\t\t\t\tstdout: typeof response.stdout === \"string\" ? response.stdout : \"\",\n\t\t\t\t\t\tstderr: typeof response.stderr === \"string\" ? response.stderr : \"\",\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Fall through to the same undefined a refusal produces.\n\t\t\t}\n\t\t\tresolve(undefined);\n\t\t});\n\t\tsocket.on(\"error\", giveUp);\n\t});\n}\n"]}

package/dist/core/sandbox/rpc/command-client.js

@@ -0,0 +1,86 @@
+import * as net from "node:net";
+import { dirname, isAbsolute } from "node:path";
+import { COMMAND_ESCALATION_SOCKET_VARIABLE } from "./command-proxy.js";
+/**
+ * The child's side of per-command escalation.
+ *
+ * The path this extracts is a guess, and it is allowed to be, because nothing safe rests
+ * on it. The supervisor shows the human the exact command and the exact root before
+ * anything runs, so a bad guess is refused by someone reading it rather than silently
+ * granted. What the guess buys is not having to make the user work out which directory to
+ * name; when it finds nothing, no escalation is offered and the command fails as it did
+ * before.
+ */
+/** The wordings the kernel and the shell actually produce for a mount refusal. */
+const REFUSAL_PATTERNS = [
+    /cannot (?:create|touch|remove|open) ['"]?([^'":]+)['"]?: (?:Read-only file system|Permission denied)/i,
+    /^[^:]*: ?([/][^\s:]+): (?:Operation not permitted|Permission denied|Read-only file system)/im,
+    /(?:EROFS|EACCES|EPERM)[^'"]*['"]([/][^'"]+)['"]/,
+];
+/** The absolute path a sandbox filesystem refusal named, if the output named one. */
+export function extractRefusedPath(output) {
+    for (const pattern of REFUSAL_PATTERNS) {
+        const match = pattern.exec(output);
+        const candidate = match?.[1]?.trim();
+        if (candidate && isAbsolute(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** True when the output looks like the boundary refused a write rather than the command failing. */
+export function looksLikeSandboxRefusal(output) {
+    return /Read-only file system|Operation not permitted|Permission denied/i.test(output);
+}
+/**
+ * The directory an escalation should make writable for a refused path.
+ *
+ * The parent, not the file: the command was creating something that does not exist, and a
+ * bind of a non-existent path is not a mount bwrap can make.
+ */
+export function escalationRootFor(refusedPath) {
+    return dirname(refusedPath);
+}
+/**
+ * Ask the supervisor to run one command with one extra writable root.
+ *
+ * Resolves undefined for every refusal and every failure alike, because the caller's
+ * behaviour is identical in both cases: report the original error. Only a command that
+ * actually ran returns anything.
+ */
+export function requestCommandEscalation(request, socketPath = process.env[COMMAND_ESCALATION_SOCKET_VARIABLE]) {
+    if (!socketPath)
+        return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        const socket = net.connect(socketPath);
+        let buffer = "";
+        const giveUp = () => {
+            socket.destroy();
+            resolve(undefined);
+        };
+        socket.on("connect", () => socket.write(`${JSON.stringify({ op: "run", ...request })}\n`));
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString();
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            socket.destroy();
+            try {
+                const response = JSON.parse(buffer.slice(0, newline));
+                if (response.ok === true && typeof response.code === "number") {
+                    resolve({
+                        code: response.code,
+                        stdout: typeof response.stdout === "string" ? response.stdout : "",
+                        stderr: typeof response.stderr === "string" ? response.stderr : "",
+                    });
+                    return;
+                }
+            }
+            catch {
+                // Fall through to the same undefined a refusal produces.
+            }
+            resolve(undefined);
+        });
+        socket.on("error", giveUp);
+    });
+}
+//# sourceMappingURL=command-client.js.map

package/dist/core/sandbox/rpc/command-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-client.js","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/command-client.ts"],"names":[],"mappings":"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","sourcesContent":["import * as net from \"node:net\";\nimport { dirname, isAbsolute } from \"node:path\";\nimport { COMMAND_ESCALATION_SOCKET_VARIABLE } from \"./command-proxy.ts\";\n\n/**\n * The child's side of per-command escalation.\n *\n * The path this extracts is a guess, and it is allowed to be, because nothing safe rests\n * on it. The supervisor shows the human the exact command and the exact root before\n * anything runs, so a bad guess is refused by someone reading it rather than silently\n * granted. What the guess buys is not having to make the user work out which directory to\n * name; when it finds nothing, no escalation is offered and the command fails as it did\n * before.\n */\n\n/** The wordings the kernel and the shell actually produce for a mount refusal. */\nconst REFUSAL_PATTERNS: readonly RegExp[] = [\n\t/cannot (?:create|touch|remove|open) ['\"]?([^'\":]+)['\"]?: (?:Read-only file system|Permission denied)/i,\n\t/^[^:]*: ?([/][^\\s:]+): (?:Operation not permitted|Permission denied|Read-only file system)/im,\n\t/(?:EROFS|EACCES|EPERM)[^'\"]*['\"]([/][^'\"]+)['\"]/,\n];\n\n/** The absolute path a sandbox filesystem refusal named, if the output named one. */\nexport function extractRefusedPath(output: string): string | undefined {\n\tfor (const pattern of REFUSAL_PATTERNS) {\n\t\tconst match = pattern.exec(output);\n\t\tconst candidate = match?.[1]?.trim();\n\t\tif (candidate && isAbsolute(candidate)) return candidate;\n\t}\n\treturn undefined;\n}\n\n/** True when the output looks like the boundary refused a write rather than the command failing. */\nexport function looksLikeSandboxRefusal(output: string): boolean {\n\treturn /Read-only file system|Operation not permitted|Permission denied/i.test(output);\n}\n\n/**\n * The directory an escalation should make writable for a refused path.\n *\n * The parent, not the file: the command was creating something that does not exist, and a\n * bind of a non-existent path is not a mount bwrap can make.\n */\nexport function escalationRootFor(refusedPath: string): string {\n\treturn dirname(refusedPath);\n}\n\nexport interface EscalationOutcome {\n\treadonly code: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\n/**\n * Ask the supervisor to run one command with one extra writable root.\n *\n * Resolves undefined for every refusal and every failure alike, because the caller's\n * behaviour is identical in both cases: report the original error. Only a command that\n * actually ran returns anything.\n */\nexport function requestCommandEscalation(\n\trequest: { command: string; writableRoot: string },\n\tsocketPath = process.env[COMMAND_ESCALATION_SOCKET_VARIABLE],\n): Promise<EscalationOutcome | undefined> {\n\tif (!socketPath) return Promise.resolve(undefined);\n\treturn new Promise((resolve) => {\n\t\tconst socket = net.connect(socketPath);\n\t\tlet buffer = \"\";\n\t\tconst giveUp = () => {\n\t\t\tsocket.destroy();\n\t\t\tresolve(undefined);\n\t\t};\n\t\tsocket.on(\"connect\", () => socket.write(`${JSON.stringify({ op: \"run\", ...request })}\\n`));\n\t\tsocket.on(\"data\", (chunk) => {\n\t\t\tbuffer += chunk.toString();\n\t\t\tconst newline = buffer.indexOf(\"\\n\");\n\t\t\tif (newline < 0) return;\n\t\t\tsocket.destroy();\n\t\t\ttry {\n\t\t\t\tconst response = JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>;\n\t\t\t\tif (response.ok === true && typeof response.code === \"number\") {\n\t\t\t\t\tresolve({\n\t\t\t\t\t\tcode: response.code,\n\t\t\t\t\t\tstdout: typeof response.stdout === \"string\" ? response.stdout : \"\",\n\t\t\t\t\t\tstderr: typeof response.stderr === \"string\" ? response.stderr : \"\",\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Fall through to the same undefined a refusal produces.\n\t\t\t}\n\t\t\tresolve(undefined);\n\t\t});\n\t\tsocket.on(\"error\", giveUp);\n\t});\n}\n"]}

package/dist/core/sandbox/rpc/command-proxy.d.ts

@@ -0,0 +1,48 @@
+import type { SandboxViolationStore } from "../violations.ts";
+/** Env var naming the child-side socket. */
+export declare const COMMAND_ESCALATION_SOCKET_VARIABLE = "APEX_COMMAND_ESCALATION_PATH";
+export interface CommandEscalationRequest {
+    readonly command: string;
+    /** The one directory the command needs writable that it does not already have. */
+    readonly writableRoot: string;
+}
+export interface CommandEscalationResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandEscalationChannelPaths {
+    readonly hostSocketDirectory: string;
+    readonly hostSocketPath: string;
+    readonly childSocketPath: string;
+}
+export declare function resolveCommandEscalationChannelPaths(): CommandEscalationChannelPaths;
+/**
+ * Run one approved command in a second, differently-mounted child.
+ *
+ * A refused write is refused by the kernel inside a namespace whose mounts are fixed for
+ * its lifetime. There is no in-place equivalent of holding a CONNECT open while a human
+ * decides: the syscall has already failed, and nothing inside the namespace can widen it.
+ * So the escalation happens where the authority is, outside the boundary, by starting a
+ * separate child for that one command.
+ *
+ * The original child's namespace is never modified, which is what makes this sound rather
+ * than a hole. Approving one command grants nothing to the session it came from; the
+ * session's own next attempt at the same operation is refused exactly as before.
+ *
+ * Approval is the supervisor's, per ADR 0023, for the reason that ADR gives: this socket
+ * has no peer authentication, so a request arriving on it may have come from anything
+ * inside the boundary. Without an approver the channel refuses, which is what keeps
+ * headless, print, JSON, and RPC modes at ADR 0005's deny.
+ */
+export declare function createCommandEscalationProxy(options: {
+    socketPath: string;
+    /** Ask a human. Absent means refuse without asking. */
+    requestApproval?: (request: CommandEscalationRequest) => Promise<boolean>;
+    /** Start the second child. Supplied by the platform backend, which owns mount shape. */
+    runEscalated: (request: CommandEscalationRequest) => Promise<CommandEscalationResult>;
+    violationStore?: SandboxViolationStore;
+}): Promise<{
+    close(): Promise<void>;
+}>;
+//# sourceMappingURL=command-proxy.d.ts.map

package/dist/core/sandbox/rpc/command-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-proxy.d.ts","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/command-proxy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAO9D,4CAA4C;AAC5C,eAAO,MAAM,kCAAkC,iCAAiC,CAAC;AAEjF,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,oCAAoC,IAAI,6BAA6B,CAWpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,wFAAwF;IACxF,YAAY,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACtF,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACvC,GAAG,OAAO,CAAC;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CA2EtC","sourcesContent":["import { chmodSync, existsSync, mkdtempSync, unlinkSync } from \"node:fs\";\nimport * as net from \"node:net\";\nimport { join } from \"node:path\";\nimport { supervisorTempDirectory } from \"../supervisor-temp.ts\";\nimport type { SandboxViolationStore } from \"../violations.ts\";\nimport { FrameReader, isRequestObject, writeFrame } from \"./framing.ts\";\n\n/** AF_UNIX `sun_path` is 108 bytes on Linux, including the terminating NUL. */\nconst SUN_PATH_LIMIT = 108;\nconst MAX_CONNECTIONS = 8;\n\n/** Env var naming the child-side socket. */\nexport const COMMAND_ESCALATION_SOCKET_VARIABLE = \"APEX_COMMAND_ESCALATION_PATH\";\n\nexport interface CommandEscalationRequest {\n\treadonly command: string;\n\t/** The one directory the command needs writable that it does not already have. */\n\treadonly writableRoot: string;\n}\n\nexport interface CommandEscalationResult {\n\treadonly code: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\nexport interface CommandEscalationChannelPaths {\n\treadonly hostSocketDirectory: string;\n\treadonly hostSocketPath: string;\n\treadonly childSocketPath: string;\n}\n\nexport function resolveCommandEscalationChannelPaths(): CommandEscalationChannelPaths {\n\tconst hostSocketDirectory = mkdtempSync(join(supervisorTempDirectory(), `apex-escalate-${process.pid}-`), {\n\t\tencoding: \"utf8\",\n\t});\n\tchmodSync(hostSocketDirectory, 0o700);\n\tconst hostSocketPath = join(hostSocketDirectory, \"channel.sock\");\n\tif (Buffer.byteLength(hostSocketPath) + 1 > SUN_PATH_LIMIT) {\n\t\tthrow new Error(\"Command escalation channel path exceeds the Unix socket path limit.\");\n\t}\n\tconst childSocketPath = process.platform === \"linux\" ? \"/home/apex-command-escalation.sock\" : hostSocketPath;\n\treturn { hostSocketDirectory, hostSocketPath, childSocketPath };\n}\n\n/**\n * Run one approved command in a second, differently-mounted child.\n *\n * A refused write is refused by the kernel inside a namespace whose mounts are fixed for\n * its lifetime. There is no in-place equivalent of holding a CONNECT open while a human\n * decides: the syscall has already failed, and nothing inside the namespace can widen it.\n * So the escalation happens where the authority is, outside the boundary, by starting a\n * separate child for that one command.\n *\n * The original child's namespace is never modified, which is what makes this sound rather\n * than a hole. Approving one command grants nothing to the session it came from; the\n * session's own next attempt at the same operation is refused exactly as before.\n *\n * Approval is the supervisor's, per ADR 0023, for the reason that ADR gives: this socket\n * has no peer authentication, so a request arriving on it may have come from anything\n * inside the boundary. Without an approver the channel refuses, which is what keeps\n * headless, print, JSON, and RPC modes at ADR 0005's deny.\n */\nexport function createCommandEscalationProxy(options: {\n\tsocketPath: string;\n\t/** Ask a human. Absent means refuse without asking. */\n\trequestApproval?: (request: CommandEscalationRequest) => Promise<boolean>;\n\t/** Start the second child. Supplied by the platform backend, which owns mount shape. */\n\trunEscalated: (request: CommandEscalationRequest) => Promise<CommandEscalationResult>;\n\tviolationStore?: SandboxViolationStore;\n}): Promise<{ close(): Promise<void> }> {\n\tfunction audit(detail: string, command: string): void {\n\t\toptions.violationStore?.add({ kind: \"filesystem\", command, detail, timestamp: new Date() });\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 !== \"run\") return { ok: false, error: \"Only command escalation is served here.\" };\n\t\tconst command = typeof request.command === \"string\" ? request.command : \"\";\n\t\tconst writableRoot = typeof request.writableRoot === \"string\" ? request.writableRoot : \"\";\n\t\tif (!command || !writableRoot) return { ok: false, error: \"Request named no command or no root.\" };\n\n\t\t// Every request is asked about individually. There is no session-scoped grant here,\n\t\t// unlike a host or a credential: a command is not a stable subject to remember, and\n\t\t// remembering one would silently cover the next command that named the same root.\n\t\tif (!options.requestApproval) {\n\t\t\taudit(`Refused an escalation with no way to ask: ${command}`, command);\n\t\t\treturn { ok: false, error: \"Escalation is unavailable without a terminal.\" };\n\t\t}\n\t\tlet approved = false;\n\t\ttry {\n\t\t\tapproved = await options.requestApproval({ command, writableRoot });\n\t\t} catch {\n\t\t\tapproved = false;\n\t\t}\n\t\tif (!approved) {\n\t\t\taudit(`Escalation refused for ${writableRoot}`, command);\n\t\t\treturn { ok: false, error: \"Escalation was refused.\" };\n\t\t}\n\t\tconst result = await options.runEscalated({ command, writableRoot });\n\t\taudit(`Escalated with ${writableRoot} writable, exit ${result.code}`, command);\n\t\treturn { ok: true, code: result.code, stdout: result.stdout, stderr: result.stderr };\n\t}\n\n\treturn new Promise((resolve, reject) => {\n\t\tif (existsSync(options.socketPath)) unlinkSync(options.socketPath);\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, \"Command escalation channel\", (detail) =>\n\t\t\t\taudit(`Refused: ${detail}`, \"(protocol)\"),\n\t\t\t);\n\t\t\tvoid (async () => {\n\t\t\t\ttry {\n\t\t\t\t\twriteFrame(socket, await answer(await reader.next()));\n\t\t\t\t} catch {\n\t\t\t\t\t// A disconnected or malformed client is the reader's business.\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\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; this 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"]}