apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/sandbox/rpc/framing.js

@@ -0,0 +1,114 @@
+/**
+ * The framing both supervisor-owned RPC channels share.
+ *
+ * Extracted from `credential-proxy.ts` when the git credential channel needed the same
+ * reader. A second hand-written copy of a byte-bounded parser sitting on a socket that
+ * every process inside the sandbox can reach is exactly the divergence ADR 0010 exists to
+ * prevent for tool contracts: a hardening applied to one copy and not the other is
+ * invisible until it matters. One implementation, named per channel only in its messages.
+ */
+export const MAX_FRAME_BYTES = 64 * 1024;
+export function writeFrame(socket, response) {
+    if (socket.destroyed)
+        return;
+    const frame = Buffer.from(`${JSON.stringify(response)}\n`, "utf8");
+    if (frame.length > MAX_FRAME_BYTES) {
+        throw new Error("Channel response exceeded its byte limit.");
+    }
+    socket.write(frame);
+}
+export function isRequestObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * One request frame at a time, newline-delimited JSON, bounded in bytes.
+ *
+ * Pipelining is refused rather than queued: a channel that answers a second request before
+ * the first is served makes the audit tail ambiguous about which frame a refusal belonged
+ * to, and neither channel has a caller that needs it.
+ */
+export class FrameReader {
+    socket;
+    channelName;
+    onProtocolRefusal;
+    buffer = Buffer.alloc(0);
+    queued = [];
+    waiting = [];
+    terminalError;
+    constructor(socket, channelName, onProtocolRefusal) {
+        this.socket = socket;
+        this.channelName = channelName;
+        this.onProtocolRefusal = onProtocolRefusal;
+        socket.on("data", (chunk) => this.push(chunk));
+        socket.on("close", () => this.fail(new Error(`${channelName} client disconnected.`)));
+        socket.on("error", (error) => this.fail(error));
+    }
+    next() {
+        const queued = this.queued.shift();
+        if (queued !== undefined)
+            return Promise.resolve(queued);
+        if (this.terminalError)
+            return Promise.reject(this.terminalError);
+        return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
+    }
+    push(chunk) {
+        if (this.terminalError)
+            return;
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        while (true) {
+            const newline = this.buffer.indexOf(0x0a);
+            if (newline < 0) {
+                if (this.buffer.length > MAX_FRAME_BYTES)
+                    this.rejectOversizedFrame();
+                return;
+            }
+            if (newline > MAX_FRAME_BYTES) {
+                this.rejectOversizedFrame();
+                return;
+            }
+            const frame = this.buffer.subarray(0, newline);
+            this.buffer = this.buffer.subarray(newline + 1);
+            if (frame.length === 0)
+                continue;
+            let value;
+            try {
+                value = JSON.parse(frame.toString("utf8"));
+            }
+            catch {
+                this.onProtocolRefusal("Invalid request frame: not JSON.");
+                writeFrame(this.socket, { ok: false, error: "Invalid request frame: not JSON." });
+                this.fail(new Error(`${this.channelName} received an invalid JSON frame.`));
+                this.socket.end();
+                return;
+            }
+            const waiter = this.waiting.shift();
+            if (waiter) {
+                waiter.resolve(value);
+            }
+            else if (this.queued.length === 0) {
+                this.queued.push(value);
+            }
+            else {
+                this.onProtocolRefusal("Unexpected pipelined request frame.");
+                writeFrame(this.socket, { ok: false, error: "Unexpected pipelined request frame." });
+                this.fail(new Error(`${this.channelName} received an unexpected pipelined frame.`));
+                this.socket.end();
+                return;
+            }
+        }
+    }
+    rejectOversizedFrame() {
+        this.onProtocolRefusal("Request frame exceeded the 64 KiB byte limit.");
+        writeFrame(this.socket, { ok: false, error: "Request frame is too large." });
+        this.fail(new Error(`${this.channelName} frame exceeded its byte limit.`));
+        this.socket.end();
+    }
+    fail(error) {
+        if (this.terminalError)
+            return;
+        this.terminalError = error;
+        for (const waiter of this.waiting.splice(0))
+            waiter.reject(error);
+    }
+}
+//# sourceMappingURL=framing.js.map

package/dist/core/sandbox/rpc/framing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framing.js","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/framing.ts"],"names":[],"mappings":"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","sourcesContent":["import type * as net from \"node:net\";\n\n/**\n * The framing both supervisor-owned RPC channels share.\n *\n * Extracted from `credential-proxy.ts` when the git credential channel needed the same\n * reader. A second hand-written copy of a byte-bounded parser sitting on a socket that\n * every process inside the sandbox can reach is exactly the divergence ADR 0010 exists to\n * prevent for tool contracts: a hardening applied to one copy and not the other is\n * invisible until it matters. One implementation, named per channel only in its messages.\n */\n\nexport const MAX_FRAME_BYTES = 64 * 1024;\n\nexport function writeFrame(socket: net.Socket, response: object): void {\n\tif (socket.destroyed) return;\n\tconst frame = Buffer.from(`${JSON.stringify(response)}\\n`, \"utf8\");\n\tif (frame.length > MAX_FRAME_BYTES) {\n\t\tthrow new Error(\"Channel response exceeded its byte limit.\");\n\t}\n\tsocket.write(frame);\n}\n\nexport function isRequestObject(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * One request frame at a time, newline-delimited JSON, bounded in bytes.\n *\n * Pipelining is refused rather than queued: a channel that answers a second request before\n * the first is served makes the audit tail ambiguous about which frame a refusal belonged\n * to, and neither channel has a caller that needs it.\n */\nexport class FrameReader {\n\tprivate readonly socket: net.Socket;\n\tprivate readonly channelName: string;\n\tprivate readonly onProtocolRefusal: (detail: string) => void;\n\tprivate buffer = Buffer.alloc(0);\n\tprivate readonly queued: unknown[] = [];\n\tprivate readonly waiting: Array<{ resolve(value: unknown): void; reject(error: Error): void }> = [];\n\tprivate terminalError: Error | undefined;\n\n\tconstructor(socket: net.Socket, channelName: string, onProtocolRefusal: (detail: string) => void) {\n\t\tthis.socket = socket;\n\t\tthis.channelName = channelName;\n\t\tthis.onProtocolRefusal = onProtocolRefusal;\n\t\tsocket.on(\"data\", (chunk: Buffer) => this.push(chunk));\n\t\tsocket.on(\"close\", () => this.fail(new Error(`${channelName} client disconnected.`)));\n\t\tsocket.on(\"error\", (error) => this.fail(error));\n\t}\n\n\tnext(): Promise<unknown> {\n\t\tconst queued = this.queued.shift();\n\t\tif (queued !== undefined) return Promise.resolve(queued);\n\t\tif (this.terminalError) return Promise.reject(this.terminalError);\n\t\treturn new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));\n\t}\n\n\tprivate push(chunk: Buffer): void {\n\t\tif (this.terminalError) return;\n\t\tthis.buffer = Buffer.concat([this.buffer, chunk]);\n\t\twhile (true) {\n\t\t\tconst newline = this.buffer.indexOf(0x0a);\n\t\t\tif (newline < 0) {\n\t\t\t\tif (this.buffer.length > MAX_FRAME_BYTES) this.rejectOversizedFrame();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (newline > MAX_FRAME_BYTES) {\n\t\t\t\tthis.rejectOversizedFrame();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst frame = this.buffer.subarray(0, newline);\n\t\t\tthis.buffer = this.buffer.subarray(newline + 1);\n\t\t\tif (frame.length === 0) continue;\n\t\t\tlet value: unknown;\n\t\t\ttry {\n\t\t\t\tvalue = JSON.parse(frame.toString(\"utf8\")) as unknown;\n\t\t\t} catch {\n\t\t\t\tthis.onProtocolRefusal(\"Invalid request frame: not JSON.\");\n\t\t\t\twriteFrame(this.socket, { ok: false, error: \"Invalid request frame: not JSON.\" });\n\t\t\t\tthis.fail(new Error(`${this.channelName} received an invalid JSON frame.`));\n\t\t\t\tthis.socket.end();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst waiter = this.waiting.shift();\n\t\t\tif (waiter) {\n\t\t\t\twaiter.resolve(value);\n\t\t\t} else if (this.queued.length === 0) {\n\t\t\t\tthis.queued.push(value);\n\t\t\t} else {\n\t\t\t\tthis.onProtocolRefusal(\"Unexpected pipelined request frame.\");\n\t\t\t\twriteFrame(this.socket, { ok: false, error: \"Unexpected pipelined request frame.\" });\n\t\t\t\tthis.fail(new Error(`${this.channelName} received an unexpected pipelined frame.`));\n\t\t\t\tthis.socket.end();\n\t\t\t\treturn;\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate rejectOversizedFrame(): void {\n\t\tthis.onProtocolRefusal(\"Request frame exceeded the 64 KiB byte limit.\");\n\t\twriteFrame(this.socket, { ok: false, error: \"Request frame is too large.\" });\n\t\tthis.fail(new Error(`${this.channelName} frame exceeded its byte limit.`));\n\t\tthis.socket.end();\n\t}\n\n\tprivate fail(error: Error): void {\n\t\tif (this.terminalError) return;\n\t\tthis.terminalError = error;\n\t\tfor (const waiter of this.waiting.splice(0)) waiter.reject(error);\n\t}\n}\n"]}

package/dist/core/sandbox/rpc/git-credential-helper.d.ts

@@ -0,0 +1,47 @@
+import { type GitCredential, type GitCredentialRequest } from "./git-credential-proxy.ts";
+/** Env var naming the child-side socket the helper talks to. */
+export declare const GIT_CREDENTIAL_SOCKET_VARIABLE = "APEX_GIT_CREDENTIAL_PATH";
+export interface GitCredentialChannelPaths {
+    readonly hostSocketDirectory: string;
+    readonly hostSocketPath: string;
+    readonly childSocketPath: string;
+}
+/**
+ * Where the git credential socket lives on each side, mirroring the credential channel's
+ * own resolution. TMPDIR is deliberately not honoured: it can point inside the workspace
+ * on macOS, which the sandbox may write. The child-side path sits under `/home` on Linux
+ * because the `--tmpfs /home` is the only writable mount when bwrap creates the mountpoint.
+ */
+export declare function resolveGitCredentialChannelPaths(): GitCredentialChannelPaths;
+/**
+ * Where the helper lives, derived rather than passed.
+ *
+ * The supervisor writes `credential.helper` into the projected git config before the
+ * platform backend exists, and the backend writes the file itself. Deriving both from the
+ * state directory is what keeps the config from naming a path nothing ever created.
+ */
+export declare function gitCredentialHelperPath(stateDirectory: string): string;
+/** The `credential.helper` value naming that helper, run under the supervisor's own node. */
+export declare function gitCredentialHelperCommand(stateDirectory: string, nodePath?: string): string;
+/** Write the helper into a directory the child can read, returning its path. */
+export declare function writeGitCredentialHelper(directory: string): string;
+/**
+ * Resolve a credential on the host, through the host's own git configuration.
+ *
+ * `git credential fill` rather than reading any particular store, because the answer may
+ * come from `gh`'s helper, libsecret, the macOS keychain, or a plain file, and only git
+ * knows which of those this host is configured to ask. Reimplementing that resolution
+ * would be a second, quietly diverging copy of it.
+ *
+ * Two things about *where* it runs are part of the boundary rather than housekeeping. It
+ * runs in a private empty directory, never in whatever directory the supervisor happened to
+ * be started from, because a repository's own `credential.helper` is a command git would
+ * otherwise execute on the host. And it runs without the four variables that would point it
+ * back at such a repository. The request is re-parsed here too: this function serializes
+ * into git's line protocol, so it refuses anything that could rewrite the identity it was
+ * asked for, whether or not the proxy already checked.
+ */
+export declare function fillHostGitCredential(request: GitCredentialRequest, options?: {
+    environment?: NodeJS.ProcessEnv;
+}): Promise<GitCredential | undefined>;
+//# sourceMappingURL=git-credential-helper.d.ts.map

package/dist/core/sandbox/rpc/git-credential-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-credential-helper.d.ts","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/git-credential-helper.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAA6B,MAAM,2BAA2B,CAAC;AAErH,gEAAgE;AAChE,eAAO,MAAM,8BAA8B,6BAA6B,CAAC;AAwEzE,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,IAAI,yBAAyB,CAW5E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,6FAA6F;AAC7F,wBAAgB,0BAA0B,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,SAAmB,GAAG,MAAM,CAEtG;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIlE;AAqDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GAC3C,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CA+CpC","sourcesContent":["import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { supervisorTempDirectory } from \"../supervisor-temp.ts\";\nimport { type GitCredential, type GitCredentialRequest, parseGitCredentialRequest } from \"./git-credential-proxy.ts\";\n\n/** Env var naming the child-side socket the helper talks to. */\nexport const GIT_CREDENTIAL_SOCKET_VARIABLE = \"APEX_GIT_CREDENTIAL_PATH\";\n\n/**\n * The credential helper git runs inside the sandbox.\n *\n * `.cjs` for the same reason the network relay is: a plain `.js` under a workspace whose\n * package.json declares `\"type\": \"module\"` is parsed as ESM and dies on `require`.\n *\n * It answers `get` and nothing else. `store` and `erase` exit silently and successfully,\n * which is what tells git the credential was handled and stops it falling through to\n * another helper. Writing is deliberately not served: ADR 0015 keeps credential mutation\n * an explicit host operation, and a channel that let the child rewrite the host's store\n * would be a way out of the boundary rather than a way to work inside it.\n *\n * Any failure exits 0 having printed nothing, which git reads as \"this helper has no\n * credential\" and handles normally. Exiting non-zero would surface as a git error that\n * looks like a repository problem rather than a refused release.\n */\nconst HELPER_SOURCE = `\nconst net = require(\"node:net\");\n\nconst operation = process.argv[2];\nif (operation !== \"get\") process.exit(0);\n\nlet input = \"\";\nprocess.stdin.setEncoding(\"utf8\");\nprocess.stdin.on(\"data\", (chunk) => {\n\tinput += chunk;\n});\nprocess.stdin.on(\"end\", () => {\n\tconst request = {};\n\tfor (const line of input.split(\"\\\\n\")) {\n\t\tconst separator = line.indexOf(\"=\");\n\t\tif (separator > 0) request[line.slice(0, separator)] = line.slice(separator + 1).trim();\n\t}\n\tconst socketPath = process.env.${GIT_CREDENTIAL_SOCKET_VARIABLE};\n\tif (!socketPath || !request.host) process.exit(0);\n\n\tconst socket = net.connect(socketPath);\n\tlet buffer = \"\";\n\tconst giveUp = () => {\n\t\tsocket.destroy();\n\t\tprocess.exit(0);\n\t};\n\tsocket.on(\"connect\", () => {\n\t\tsocket.write(JSON.stringify({ op: \"get\", protocol: request.protocol || \"https\", host: request.host }) + \"\\\\n\");\n\t});\n\tsocket.on(\"data\", (chunk) => {\n\t\tbuffer += chunk.toString();\n\t\tconst newline = buffer.indexOf(\"\\\\n\");\n\t\tif (newline < 0) return;\n\t\tlet response;\n\t\ttry {\n\t\t\tresponse = JSON.parse(buffer.slice(0, newline));\n\t\t} catch {\n\t\t\tgiveUp();\n\t\t\treturn;\n\t\t}\n\t\tif (response && response.ok) {\n\t\t\tprocess.stdout.write(\"username=\" + response.username + \"\\\\n\");\n\t\t\tprocess.stdout.write(\"password=\" + response.password + \"\\\\n\");\n\t\t}\n\t\tsocket.destroy();\n\t\tprocess.exit(0);\n\t});\n\tsocket.on(\"error\", giveUp);\n});\n`.trim();\n\n/** AF_UNIX `sun_path` is 108 bytes on Linux, including the terminating NUL. */\nconst SUN_PATH_LIMIT = 108;\n\nexport interface GitCredentialChannelPaths {\n\treadonly hostSocketDirectory: string;\n\treadonly hostSocketPath: string;\n\treadonly childSocketPath: string;\n}\n\n/**\n * Where the git credential socket lives on each side, mirroring the credential channel's\n * own resolution. TMPDIR is deliberately not honoured: it can point inside the workspace\n * on macOS, which the sandbox may write. The child-side path sits under `/home` on Linux\n * because the `--tmpfs /home` is the only writable mount when bwrap creates the mountpoint.\n */\nexport function resolveGitCredentialChannelPaths(): GitCredentialChannelPaths {\n\tconst hostSocketDirectory = mkdtempSync(join(supervisorTempDirectory(), `apex-gitcred-${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(\"Git credential channel path exceeds the Unix socket path limit.\");\n\t}\n\tconst childSocketPath = process.platform === \"linux\" ? \"/home/apex-git-credential-channel.sock\" : hostSocketPath;\n\treturn { hostSocketDirectory, hostSocketPath, childSocketPath };\n}\n\n/**\n * Where the helper lives, derived rather than passed.\n *\n * The supervisor writes `credential.helper` into the projected git config before the\n * platform backend exists, and the backend writes the file itself. Deriving both from the\n * state directory is what keeps the config from naming a path nothing ever created.\n */\nexport function gitCredentialHelperPath(stateDirectory: string): string {\n\treturn join(stateDirectory, \"git-credential-apex.cjs\");\n}\n\n/** The `credential.helper` value naming that helper, run under the supervisor's own node. */\nexport function gitCredentialHelperCommand(stateDirectory: string, nodePath = process.execPath): string {\n\treturn `!\"${nodePath}\" \"${gitCredentialHelperPath(stateDirectory)}\"`;\n}\n\n/** Write the helper into a directory the child can read, returning its path. */\nexport function writeGitCredentialHelper(directory: string): string {\n\tconst path = gitCredentialHelperPath(directory);\n\twriteFileSync(path, HELPER_SOURCE);\n\treturn path;\n}\n\n/**\n * The environment variables that decide which repository git is standing in, and which\n * config it reads.\n *\n * `credential.helper` is a shell command git runs on whichever machine resolves the\n * credential -- the host, here. Any of these four lets a repository the agent cloned choose\n * that command, so a credential fill that inherits them is a host execution primitive with\n * a socket in front of it.\n *\n * `HOME` and the global and system config are deliberately kept. They are how `gh`,\n * libsecret, the macOS keychain and a plain `credential.helper` in `--global` are found,\n * and they belong to the human running the supervisor rather than to any repository.\n */\nconst REPOSITORY_DISCOVERY_VARIABLES = [\"GIT_DIR\", \"GIT_WORK_TREE\", \"GIT_INDEX_FILE\", \"GIT_CONFIG\"] as const;\n\ninterface PrivateFillDirectory {\n\t/** Where git runs: empty, 0700, and inside no repository. */\n\treadonly cwd: string;\n\t/** Its parent, so git's upward search for a repository stops before leaving it. */\n\treadonly ceiling: string;\n\treadonly dispose: () => void;\n}\n\nfunction createPrivateFillDirectory(): PrivateFillDirectory {\n\tconst base = mkdtempSync(join(supervisorTempDirectory(), `apex-gitcred-fill-${process.pid}-`), { encoding: \"utf8\" });\n\tchmodSync(base, 0o700);\n\tconst cwd = join(base, \"empty\");\n\tmkdirSync(cwd, { mode: 0o700 });\n\t// Resolved, because git ignores a ceiling entry that would need symlink resolution and\n\t// `/tmp` is a symlink on macOS.\n\tlet ceiling = base;\n\ttry {\n\t\tceiling = realpathSync(base);\n\t} catch {\n\t\t// A ceiling that does not resolve is a weaker second guard, not a broken fill; the\n\t\t// empty cwd is what does the work.\n\t}\n\treturn {\n\t\tcwd,\n\t\tceiling,\n\t\tdispose: () => {\n\t\t\ttry {\n\t\t\t\trmSync(base, { force: true, recursive: true });\n\t\t\t} catch {\n\t\t\t\t// A leftover empty directory under the supervisor's own temp root is not worth\n\t\t\t\t// failing a credential fill over.\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Resolve a credential on the host, through the host's own git configuration.\n *\n * `git credential fill` rather than reading any particular store, because the answer may\n * come from `gh`'s helper, libsecret, the macOS keychain, or a plain file, and only git\n * knows which of those this host is configured to ask. Reimplementing that resolution\n * would be a second, quietly diverging copy of it.\n *\n * Two things about *where* it runs are part of the boundary rather than housekeeping. It\n * runs in a private empty directory, never in whatever directory the supervisor happened to\n * be started from, because a repository's own `credential.helper` is a command git would\n * otherwise execute on the host. And it runs without the four variables that would point it\n * back at such a repository. The request is re-parsed here too: this function serializes\n * into git's line protocol, so it refuses anything that could rewrite the identity it was\n * asked for, whether or not the proxy already checked.\n */\nexport async function fillHostGitCredential(\n\trequest: GitCredentialRequest,\n\toptions?: { environment?: NodeJS.ProcessEnv },\n): Promise<GitCredential | undefined> {\n\tconst parsed = parseGitCredentialRequest({ protocol: request.protocol, host: request.host });\n\tif (!parsed.ok) return undefined;\n\tconst identity = parsed.request;\n\n\tconst { spawn } = await import(\"node:child_process\");\n\tconst directory = createPrivateFillDirectory();\n\tconst environment: NodeJS.ProcessEnv = { ...(options?.environment ?? process.env) };\n\tfor (const variable of REPOSITORY_DISCOVERY_VARIABLES) delete environment[variable];\n\tenvironment.GIT_CEILING_DIRECTORIES = directory.ceiling;\n\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = (credential: GitCredential | undefined): void => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tdirectory.dispose();\n\t\t\tresolve(credential);\n\t\t};\n\t\tconst child = spawn(\"git\", [\"credential\", \"fill\"], {\n\t\t\tcwd: directory.cwd,\n\t\t\tenv: environment,\n\t\t\tstdio: [\"pipe\", \"pipe\", \"ignore\"],\n\t\t});\n\t\tlet stdout = \"\";\n\t\tchild.stdout.setEncoding(\"utf8\");\n\t\tchild.stdout.on(\"data\", (chunk: string) => {\n\t\t\tstdout += chunk;\n\t\t});\n\t\tchild.on(\"error\", () => finish(undefined));\n\t\tchild.on(\"close\", (code) => {\n\t\t\tif (code !== 0) {\n\t\t\t\tfinish(undefined);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst fields = new Map<string, string>();\n\t\t\tfor (const line of stdout.split(\"\\n\")) {\n\t\t\t\tconst separator = line.indexOf(\"=\");\n\t\t\t\tif (separator > 0) fields.set(line.slice(0, separator), line.slice(separator + 1).trim());\n\t\t\t}\n\t\t\tconst username = fields.get(\"username\");\n\t\t\tconst password = fields.get(\"password\");\n\t\t\tfinish(username && password ? { username, password } : undefined);\n\t\t});\n\t\tchild.stdin.on(\"error\", () => finish(undefined));\n\t\tchild.stdin.end(`protocol=${identity.protocol}\\nhost=${identity.host}\\n\\n`);\n\t});\n}\n"]}

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

@@ -0,0 +1,222 @@
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { supervisorTempDirectory } from "../supervisor-temp.js";
+import { parseGitCredentialRequest } from "./git-credential-proxy.js";
+/** Env var naming the child-side socket the helper talks to. */
+export const GIT_CREDENTIAL_SOCKET_VARIABLE = "APEX_GIT_CREDENTIAL_PATH";
+/**
+ * The credential helper git runs inside the sandbox.
+ *
+ * `.cjs` for the same reason the network relay is: a plain `.js` under a workspace whose
+ * package.json declares `"type": "module"` is parsed as ESM and dies on `require`.
+ *
+ * It answers `get` and nothing else. `store` and `erase` exit silently and successfully,
+ * which is what tells git the credential was handled and stops it falling through to
+ * another helper. Writing is deliberately not served: ADR 0015 keeps credential mutation
+ * an explicit host operation, and a channel that let the child rewrite the host's store
+ * would be a way out of the boundary rather than a way to work inside it.
+ *
+ * Any failure exits 0 having printed nothing, which git reads as "this helper has no
+ * credential" and handles normally. Exiting non-zero would surface as a git error that
+ * looks like a repository problem rather than a refused release.
+ */
+const HELPER_SOURCE = `
+const net = require("node:net");
+
+const operation = process.argv[2];
+if (operation !== "get") process.exit(0);
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+	input += chunk;
+});
+process.stdin.on("end", () => {
+	const request = {};
+	for (const line of input.split("\\n")) {
+		const separator = line.indexOf("=");
+		if (separator > 0) request[line.slice(0, separator)] = line.slice(separator + 1).trim();
+	}
+	const socketPath = process.env.${GIT_CREDENTIAL_SOCKET_VARIABLE};
+	if (!socketPath || !request.host) process.exit(0);
+
+	const socket = net.connect(socketPath);
+	let buffer = "";
+	const giveUp = () => {
+		socket.destroy();
+		process.exit(0);
+	};
+	socket.on("connect", () => {
+		socket.write(JSON.stringify({ op: "get", protocol: request.protocol || "https", host: request.host }) + "\\n");
+	});
+	socket.on("data", (chunk) => {
+		buffer += chunk.toString();
+		const newline = buffer.indexOf("\\n");
+		if (newline < 0) return;
+		let response;
+		try {
+			response = JSON.parse(buffer.slice(0, newline));
+		} catch {
+			giveUp();
+			return;
+		}
+		if (response && response.ok) {
+			process.stdout.write("username=" + response.username + "\\n");
+			process.stdout.write("password=" + response.password + "\\n");
+		}
+		socket.destroy();
+		process.exit(0);
+	});
+	socket.on("error", giveUp);
+});
+`.trim();
+/** AF_UNIX `sun_path` is 108 bytes on Linux, including the terminating NUL. */
+const SUN_PATH_LIMIT = 108;
+/**
+ * Where the git credential socket lives on each side, mirroring the credential channel's
+ * own resolution. TMPDIR is deliberately not honoured: it can point inside the workspace
+ * on macOS, which the sandbox may write. The child-side path sits under `/home` on Linux
+ * because the `--tmpfs /home` is the only writable mount when bwrap creates the mountpoint.
+ */
+export function resolveGitCredentialChannelPaths() {
+    const hostSocketDirectory = mkdtempSync(join(supervisorTempDirectory(), `apex-gitcred-${process.pid}-`), {
+        encoding: "utf8",
+    });
+    chmodSync(hostSocketDirectory, 0o700);
+    const hostSocketPath = join(hostSocketDirectory, "channel.sock");
+    if (Buffer.byteLength(hostSocketPath) + 1 > SUN_PATH_LIMIT) {
+        throw new Error("Git credential channel path exceeds the Unix socket path limit.");
+    }
+    const childSocketPath = process.platform === "linux" ? "/home/apex-git-credential-channel.sock" : hostSocketPath;
+    return { hostSocketDirectory, hostSocketPath, childSocketPath };
+}
+/**
+ * Where the helper lives, derived rather than passed.
+ *
+ * The supervisor writes `credential.helper` into the projected git config before the
+ * platform backend exists, and the backend writes the file itself. Deriving both from the
+ * state directory is what keeps the config from naming a path nothing ever created.
+ */
+export function gitCredentialHelperPath(stateDirectory) {
+    return join(stateDirectory, "git-credential-apex.cjs");
+}
+/** The `credential.helper` value naming that helper, run under the supervisor's own node. */
+export function gitCredentialHelperCommand(stateDirectory, nodePath = process.execPath) {
+    return `!"${nodePath}" "${gitCredentialHelperPath(stateDirectory)}"`;
+}
+/** Write the helper into a directory the child can read, returning its path. */
+export function writeGitCredentialHelper(directory) {
+    const path = gitCredentialHelperPath(directory);
+    writeFileSync(path, HELPER_SOURCE);
+    return path;
+}
+/**
+ * The environment variables that decide which repository git is standing in, and which
+ * config it reads.
+ *
+ * `credential.helper` is a shell command git runs on whichever machine resolves the
+ * credential -- the host, here. Any of these four lets a repository the agent cloned choose
+ * that command, so a credential fill that inherits them is a host execution primitive with
+ * a socket in front of it.
+ *
+ * `HOME` and the global and system config are deliberately kept. They are how `gh`,
+ * libsecret, the macOS keychain and a plain `credential.helper` in `--global` are found,
+ * and they belong to the human running the supervisor rather than to any repository.
+ */
+const REPOSITORY_DISCOVERY_VARIABLES = ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_CONFIG"];
+function createPrivateFillDirectory() {
+    const base = mkdtempSync(join(supervisorTempDirectory(), `apex-gitcred-fill-${process.pid}-`), { encoding: "utf8" });
+    chmodSync(base, 0o700);
+    const cwd = join(base, "empty");
+    mkdirSync(cwd, { mode: 0o700 });
+    // Resolved, because git ignores a ceiling entry that would need symlink resolution and
+    // `/tmp` is a symlink on macOS.
+    let ceiling = base;
+    try {
+        ceiling = realpathSync(base);
+    }
+    catch {
+        // A ceiling that does not resolve is a weaker second guard, not a broken fill; the
+        // empty cwd is what does the work.
+    }
+    return {
+        cwd,
+        ceiling,
+        dispose: () => {
+            try {
+                rmSync(base, { force: true, recursive: true });
+            }
+            catch {
+                // A leftover empty directory under the supervisor's own temp root is not worth
+                // failing a credential fill over.
+            }
+        },
+    };
+}
+/**
+ * Resolve a credential on the host, through the host's own git configuration.
+ *
+ * `git credential fill` rather than reading any particular store, because the answer may
+ * come from `gh`'s helper, libsecret, the macOS keychain, or a plain file, and only git
+ * knows which of those this host is configured to ask. Reimplementing that resolution
+ * would be a second, quietly diverging copy of it.
+ *
+ * Two things about *where* it runs are part of the boundary rather than housekeeping. It
+ * runs in a private empty directory, never in whatever directory the supervisor happened to
+ * be started from, because a repository's own `credential.helper` is a command git would
+ * otherwise execute on the host. And it runs without the four variables that would point it
+ * back at such a repository. The request is re-parsed here too: this function serializes
+ * into git's line protocol, so it refuses anything that could rewrite the identity it was
+ * asked for, whether or not the proxy already checked.
+ */
+export async function fillHostGitCredential(request, options) {
+    const parsed = parseGitCredentialRequest({ protocol: request.protocol, host: request.host });
+    if (!parsed.ok)
+        return undefined;
+    const identity = parsed.request;
+    const { spawn } = await import("node:child_process");
+    const directory = createPrivateFillDirectory();
+    const environment = { ...(options?.environment ?? process.env) };
+    for (const variable of REPOSITORY_DISCOVERY_VARIABLES)
+        delete environment[variable];
+    environment.GIT_CEILING_DIRECTORIES = directory.ceiling;
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (credential) => {
+            if (settled)
+                return;
+            settled = true;
+            directory.dispose();
+            resolve(credential);
+        };
+        const child = spawn("git", ["credential", "fill"], {
+            cwd: directory.cwd,
+            env: environment,
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        let stdout = "";
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.on("error", () => finish(undefined));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                finish(undefined);
+                return;
+            }
+            const fields = new Map();
+            for (const line of stdout.split("\n")) {
+                const separator = line.indexOf("=");
+                if (separator > 0)
+                    fields.set(line.slice(0, separator), line.slice(separator + 1).trim());
+            }
+            const username = fields.get("username");
+            const password = fields.get("password");
+            finish(username && password ? { username, password } : undefined);
+        });
+        child.stdin.on("error", () => finish(undefined));
+        child.stdin.end(`protocol=${identity.protocol}\nhost=${identity.host}\n\n`);
+    });
+}
+//# sourceMappingURL=git-credential-helper.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git-credential-helper.js","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/git-credential-helper.ts"],"names":[],"mappings":"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","sourcesContent":["import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { supervisorTempDirectory } from \"../supervisor-temp.ts\";\nimport { type GitCredential, type GitCredentialRequest, parseGitCredentialRequest } from \"./git-credential-proxy.ts\";\n\n/** Env var naming the child-side socket the helper talks to. */\nexport const GIT_CREDENTIAL_SOCKET_VARIABLE = \"APEX_GIT_CREDENTIAL_PATH\";\n\n/**\n * The credential helper git runs inside the sandbox.\n *\n * `.cjs` for the same reason the network relay is: a plain `.js` under a workspace whose\n * package.json declares `\"type\": \"module\"` is parsed as ESM and dies on `require`.\n *\n * It answers `get` and nothing else. `store` and `erase` exit silently and successfully,\n * which is what tells git the credential was handled and stops it falling through to\n * another helper. Writing is deliberately not served: ADR 0015 keeps credential mutation\n * an explicit host operation, and a channel that let the child rewrite the host's store\n * would be a way out of the boundary rather than a way to work inside it.\n *\n * Any failure exits 0 having printed nothing, which git reads as \"this helper has no\n * credential\" and handles normally. Exiting non-zero would surface as a git error that\n * looks like a repository problem rather than a refused release.\n */\nconst HELPER_SOURCE = `\nconst net = require(\"node:net\");\n\nconst operation = process.argv[2];\nif (operation !== \"get\") process.exit(0);\n\nlet input = \"\";\nprocess.stdin.setEncoding(\"utf8\");\nprocess.stdin.on(\"data\", (chunk) => {\n\tinput += chunk;\n});\nprocess.stdin.on(\"end\", () => {\n\tconst request = {};\n\tfor (const line of input.split(\"\\\\n\")) {\n\t\tconst separator = line.indexOf(\"=\");\n\t\tif (separator > 0) request[line.slice(0, separator)] = line.slice(separator + 1).trim();\n\t}\n\tconst socketPath = process.env.${GIT_CREDENTIAL_SOCKET_VARIABLE};\n\tif (!socketPath || !request.host) process.exit(0);\n\n\tconst socket = net.connect(socketPath);\n\tlet buffer = \"\";\n\tconst giveUp = () => {\n\t\tsocket.destroy();\n\t\tprocess.exit(0);\n\t};\n\tsocket.on(\"connect\", () => {\n\t\tsocket.write(JSON.stringify({ op: \"get\", protocol: request.protocol || \"https\", host: request.host }) + \"\\\\n\");\n\t});\n\tsocket.on(\"data\", (chunk) => {\n\t\tbuffer += chunk.toString();\n\t\tconst newline = buffer.indexOf(\"\\\\n\");\n\t\tif (newline < 0) return;\n\t\tlet response;\n\t\ttry {\n\t\t\tresponse = JSON.parse(buffer.slice(0, newline));\n\t\t} catch {\n\t\t\tgiveUp();\n\t\t\treturn;\n\t\t}\n\t\tif (response && response.ok) {\n\t\t\tprocess.stdout.write(\"username=\" + response.username + \"\\\\n\");\n\t\t\tprocess.stdout.write(\"password=\" + response.password + \"\\\\n\");\n\t\t}\n\t\tsocket.destroy();\n\t\tprocess.exit(0);\n\t});\n\tsocket.on(\"error\", giveUp);\n});\n`.trim();\n\n/** AF_UNIX `sun_path` is 108 bytes on Linux, including the terminating NUL. */\nconst SUN_PATH_LIMIT = 108;\n\nexport interface GitCredentialChannelPaths {\n\treadonly hostSocketDirectory: string;\n\treadonly hostSocketPath: string;\n\treadonly childSocketPath: string;\n}\n\n/**\n * Where the git credential socket lives on each side, mirroring the credential channel's\n * own resolution. TMPDIR is deliberately not honoured: it can point inside the workspace\n * on macOS, which the sandbox may write. The child-side path sits under `/home` on Linux\n * because the `--tmpfs /home` is the only writable mount when bwrap creates the mountpoint.\n */\nexport function resolveGitCredentialChannelPaths(): GitCredentialChannelPaths {\n\tconst hostSocketDirectory = mkdtempSync(join(supervisorTempDirectory(), `apex-gitcred-${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(\"Git credential channel path exceeds the Unix socket path limit.\");\n\t}\n\tconst childSocketPath = process.platform === \"linux\" ? \"/home/apex-git-credential-channel.sock\" : hostSocketPath;\n\treturn { hostSocketDirectory, hostSocketPath, childSocketPath };\n}\n\n/**\n * Where the helper lives, derived rather than passed.\n *\n * The supervisor writes `credential.helper` into the projected git config before the\n * platform backend exists, and the backend writes the file itself. Deriving both from the\n * state directory is what keeps the config from naming a path nothing ever created.\n */\nexport function gitCredentialHelperPath(stateDirectory: string): string {\n\treturn join(stateDirectory, \"git-credential-apex.cjs\");\n}\n\n/** The `credential.helper` value naming that helper, run under the supervisor's own node. */\nexport function gitCredentialHelperCommand(stateDirectory: string, nodePath = process.execPath): string {\n\treturn `!\"${nodePath}\" \"${gitCredentialHelperPath(stateDirectory)}\"`;\n}\n\n/** Write the helper into a directory the child can read, returning its path. */\nexport function writeGitCredentialHelper(directory: string): string {\n\tconst path = gitCredentialHelperPath(directory);\n\twriteFileSync(path, HELPER_SOURCE);\n\treturn path;\n}\n\n/**\n * The environment variables that decide which repository git is standing in, and which\n * config it reads.\n *\n * `credential.helper` is a shell command git runs on whichever machine resolves the\n * credential -- the host, here. Any of these four lets a repository the agent cloned choose\n * that command, so a credential fill that inherits them is a host execution primitive with\n * a socket in front of it.\n *\n * `HOME` and the global and system config are deliberately kept. They are how `gh`,\n * libsecret, the macOS keychain and a plain `credential.helper` in `--global` are found,\n * and they belong to the human running the supervisor rather than to any repository.\n */\nconst REPOSITORY_DISCOVERY_VARIABLES = [\"GIT_DIR\", \"GIT_WORK_TREE\", \"GIT_INDEX_FILE\", \"GIT_CONFIG\"] as const;\n\ninterface PrivateFillDirectory {\n\t/** Where git runs: empty, 0700, and inside no repository. */\n\treadonly cwd: string;\n\t/** Its parent, so git's upward search for a repository stops before leaving it. */\n\treadonly ceiling: string;\n\treadonly dispose: () => void;\n}\n\nfunction createPrivateFillDirectory(): PrivateFillDirectory {\n\tconst base = mkdtempSync(join(supervisorTempDirectory(), `apex-gitcred-fill-${process.pid}-`), { encoding: \"utf8\" });\n\tchmodSync(base, 0o700);\n\tconst cwd = join(base, \"empty\");\n\tmkdirSync(cwd, { mode: 0o700 });\n\t// Resolved, because git ignores a ceiling entry that would need symlink resolution and\n\t// `/tmp` is a symlink on macOS.\n\tlet ceiling = base;\n\ttry {\n\t\tceiling = realpathSync(base);\n\t} catch {\n\t\t// A ceiling that does not resolve is a weaker second guard, not a broken fill; the\n\t\t// empty cwd is what does the work.\n\t}\n\treturn {\n\t\tcwd,\n\t\tceiling,\n\t\tdispose: () => {\n\t\t\ttry {\n\t\t\t\trmSync(base, { force: true, recursive: true });\n\t\t\t} catch {\n\t\t\t\t// A leftover empty directory under the supervisor's own temp root is not worth\n\t\t\t\t// failing a credential fill over.\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Resolve a credential on the host, through the host's own git configuration.\n *\n * `git credential fill` rather than reading any particular store, because the answer may\n * come from `gh`'s helper, libsecret, the macOS keychain, or a plain file, and only git\n * knows which of those this host is configured to ask. Reimplementing that resolution\n * would be a second, quietly diverging copy of it.\n *\n * Two things about *where* it runs are part of the boundary rather than housekeeping. It\n * runs in a private empty directory, never in whatever directory the supervisor happened to\n * be started from, because a repository's own `credential.helper` is a command git would\n * otherwise execute on the host. And it runs without the four variables that would point it\n * back at such a repository. The request is re-parsed here too: this function serializes\n * into git's line protocol, so it refuses anything that could rewrite the identity it was\n * asked for, whether or not the proxy already checked.\n */\nexport async function fillHostGitCredential(\n\trequest: GitCredentialRequest,\n\toptions?: { environment?: NodeJS.ProcessEnv },\n): Promise<GitCredential | undefined> {\n\tconst parsed = parseGitCredentialRequest({ protocol: request.protocol, host: request.host });\n\tif (!parsed.ok) return undefined;\n\tconst identity = parsed.request;\n\n\tconst { spawn } = await import(\"node:child_process\");\n\tconst directory = createPrivateFillDirectory();\n\tconst environment: NodeJS.ProcessEnv = { ...(options?.environment ?? process.env) };\n\tfor (const variable of REPOSITORY_DISCOVERY_VARIABLES) delete environment[variable];\n\tenvironment.GIT_CEILING_DIRECTORIES = directory.ceiling;\n\n\treturn new Promise((resolve) => {\n\t\tlet settled = false;\n\t\tconst finish = (credential: GitCredential | undefined): void => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tdirectory.dispose();\n\t\t\tresolve(credential);\n\t\t};\n\t\tconst child = spawn(\"git\", [\"credential\", \"fill\"], {\n\t\t\tcwd: directory.cwd,\n\t\t\tenv: environment,\n\t\t\tstdio: [\"pipe\", \"pipe\", \"ignore\"],\n\t\t});\n\t\tlet stdout = \"\";\n\t\tchild.stdout.setEncoding(\"utf8\");\n\t\tchild.stdout.on(\"data\", (chunk: string) => {\n\t\t\tstdout += chunk;\n\t\t});\n\t\tchild.on(\"error\", () => finish(undefined));\n\t\tchild.on(\"close\", (code) => {\n\t\t\tif (code !== 0) {\n\t\t\t\tfinish(undefined);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst fields = new Map<string, string>();\n\t\t\tfor (const line of stdout.split(\"\\n\")) {\n\t\t\t\tconst separator = line.indexOf(\"=\");\n\t\t\t\tif (separator > 0) fields.set(line.slice(0, separator), line.slice(separator + 1).trim());\n\t\t\t}\n\t\t\tconst username = fields.get(\"username\");\n\t\t\tconst password = fields.get(\"password\");\n\t\t\tfinish(username && password ? { username, password } : undefined);\n\t\t});\n\t\tchild.stdin.on(\"error\", () => finish(undefined));\n\t\tchild.stdin.end(`protocol=${identity.protocol}\\nhost=${identity.host}\\n\\n`);\n\t});\n}\n"]}

package/dist/core/sandbox/rpc/git-credential-proxy.d.ts

@@ -0,0 +1,66 @@
+import type { SandboxViolationStore } from "../violations.ts";
+export interface GitCredentialRequest {
+    readonly protocol: string;
+    readonly host: string;
+}
+export interface GitCredential {
+    readonly username: string;
+    readonly password: string;
+}
+export interface GitCredentialProxy {
+    close(): Promise<void>;
+}
+/** A request that survived validation, or the reason it did not. */
+export type GitCredentialRequestParse = {
+    readonly ok: true;
+    readonly request: GitCredentialRequest;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly audit: string;
+};
+/**
+ * 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 declare function parseGitCredentialRequest(request: Record<string, unknown>): GitCredentialRequestParse;
+/**
+ * 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 declare function createGitCredentialProxy(options: {
+    socketPath: string;
+    /** Whether this session may reach the host at all. */
+    isHostAllowed: (host: string) => boolean;
+    /** Ask a human to release the host's credential. Absent means refuse without asking. */
+    requestRelease?: (host: string) => Promise<boolean>;
+    /** Resolve the credential on the host, using the host's own configuration. */
+    fillCredential: (request: GitCredentialRequest) => Promise<GitCredential | undefined>;
+    violationStore?: SandboxViolationStore;
+}): Promise<GitCredentialProxy>;
+//# sourceMappingURL=git-credential-proxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git-credential-proxy.d.ts","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/git-credential-proxy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAK9D,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,oEAAoE;AACpE,MAAM,MAAM,yBAAyB,GAClC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAsB1E;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,yBAAyB,CAoCrG;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,wFAAwF;IACxF,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,8EAA8E;IAC9E,cAAc,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACtF,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACvC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkH9B","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"]}