@edgehero/pi-dispatch 1.0.0 → 1.2.0

package/src/config.mjs

@@ -7,6 +7,7 @@
 
 import { existsSync } from "node:fs";
 import { delimiter } from "node:path";
+import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
 import { MINTED_TOKEN_VARS } from "./forges.mjs";
 
 export function configError(message) {
@@ -89,7 +90,35 @@ function commaList(raw) {
 // token under that name into every container of every forge, with nothing failing and nothing logged.
 // `forges.mjs` derives both from one row, and `env-allowlist.test.mjs` binds them.
 
-function forwardEnvList(raw) {
+/**
+ * Names the WORKER holds that must never reach a job container, for a different reason than the minted
+ * ones above: nothing overrides them, they simply do not belong in there.
+ *
+ * `GITHUB_APP_PRIVATE_KEY` is the App's signing key. It mints installation tokens for every repository
+ * the App is installed on, with no expiry of its own -- so forwarding it hands an agent that is reading
+ * adversarial issue text something strictly worse than the per-job token the whole of
+ * `CONST-TOKEN-SCOPED-PER-JOB` exists to bound. This became reachable the moment the key could be an
+ * environment value at all (issue #208); before that, `PI_FORWARD_ENV` could only have carried the PATH.
+ *
+ * `GITHUB_APP_PRIVATE_KEY_PATH` is deliberately NOT here: a path string with no mount behind it is inert
+ * inside a container, and refusing harmless things is how a refusal stops being read.
+ *
+ * Kept separate from `MINTED_TOKEN_VARS`, which is defined as "every name any forge's mint can write"
+ * and derived from the forge table. This is not that, and folding it in would make that definition a lie.
+ */
+export const WORKER_ONLY_SECRET_VARS = new Set(["GITHUB_APP_PRIVATE_KEY"]);
+
+/**
+ * The proxy variables the egress policy writes into the closed container env (REQ-EGRESS-ALLOWLIST).
+ * Refused in `PI_FORWARD_ENV` only WHILE THE POLICY IS ARMED, and the conditionality is the point: with
+ * no policy these are an ordinary operator escape hatch, and `docs/egress.md` still documents the manual
+ * form that uses them. With a policy, a forwarded value would point every job at an operator's own proxy
+ * instead of the one the worker attached to the network -- and it would read exactly like the control
+ * working, which is the failure class this file already refuses for the minted token.
+ */
+export const EGRESS_ENV_VARS = new Set(["HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "NODE_USE_ENV_PROXY"]);
+
+function forwardEnvList(raw, egressArmed = false) {
 	const names = commaList(raw);
 	const minted = names.filter((n) => MINTED_TOKEN_VARS.has(n));
 	if (minted.length > 0) {
@@ -97,9 +126,35 @@ function forwardEnvList(raw) {
 			`PI_FORWARD_ENV must not forward ${minted.join(", ")} -- the worker mints a per-job token (CONST-TOKEN-SCOPED-PER-JOB) and a forwarded operator token would silently override it`,
 		);
 	}
+	const workerOnly = names.filter((n) => WORKER_ONLY_SECRET_VARS.has(n));
+	if (workerOnly.length > 0) {
+		throw configError(
+			`PI_FORWARD_ENV must not forward ${workerOnly.join(", ")} -- the App's signing key mints tokens for every repository the App is installed on, and a job container is the last place it belongs (CONST-TOKEN-SCOPED-PER-JOB)`,
+		);
+	}
+	const egress = egressArmed ? names.filter((n) => EGRESS_ENV_VARS.has(n)) : [];
+	if (egress.length > 0) {
+		throw configError(
+			`PI_FORWARD_ENV must not forward ${egress.join(", ")} while the egress policy is armed -- it sets them itself, pointing at the proxy on this job's network, and a forwarded value would silently redirect every job while looking like the control working (REQ-EGRESS-ALLOWLIST). Set PI_EGRESS=0 to use your own proxy: docs/egress.md`,
+		);
+	}
 	return names;
 }
 
+/**
+ * PI_EGRESS (REQ-EGRESS-ALLOWLIST). The parse itself lives in egress.mjs, because `doctor` and `up` read
+ * the environment directly and three copies of one default is two chances to flip it in the wrong number
+ * of places. Here it only gains the `piDispatchConfig` tag, so a bad value prints as a config error and
+ * the worker refuses to boot rather than guessing a security posture.
+ */
+function egressEnabled(env) {
+	try {
+		return egressArmed(env);
+	} catch (error) {
+		throw configError(error.message);
+	}
+}
+
 // The operator's global pi overlay dir (REQ-GLOBAL-PI-OVERLAY). Unset/empty = feature off. When set it
 // must EXIST at boot -- a typo pointing at nothing would silently drop the operator's whole setup on
 // every job, so fail loud like every other config error rather than degrade to nothing.
@@ -168,7 +223,12 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		jobImage: env.PI_JOB_IMAGE || "pi-job:latest", // || (not ??) so an empty string falls back; "" is falsy and would throw inside buildDockerRunArgs AFTER a budget slot was reserved
 		globalPiDir: resolveGlobalPiDir(env, fileExists), // REQ-GLOBAL-PI-OVERLAY: operator's ~/.pi/agent subset, :ro-mounted; null = off
 		allowGlobalExtensions: globalExtensionsEnabled(env), // REQ-GLOBAL-PI-OVERLAY: ON unless PI_GLOBAL_ALLOW_EXTENSIONS=0
-		forwardEnv: forwardEnvList(env.PI_FORWARD_ENV), // extra host var NAMES to forward (e.g. a custom provider's key); explicit allowlist, GitHub token names refused
+		// REQ-EGRESS-ALLOWLIST. `egress` gates the whole feature; `egressProxy` names the component the
+		// per-job network is built around. Read BEFORE forwardEnv below, because the forward list's refusal
+		// of the proxy variables is conditional on it.
+		egress: egressEnabled(env),
+		egressProxy: env.PI_EGRESS_PROXY || DEFAULT_EGRESS_PROXY, // || (not ??) so an empty string falls back
+		forwardEnv: forwardEnvList(env.PI_FORWARD_ENV, egressEnabled(env)), // extra host var NAMES to forward (e.g. a custom provider's key); explicit allowlist, GitHub token names refused
 		authFromPi: env.PI_AUTH_FROM_PI !== "0", // ON by default: use the key in ~/.pi/agent/auth.json when the env has none (api-key only). PI_AUTH_FROM_PI=0 forces env-only.
 		jobsDir: env.PI_JOBS_DIR ?? defaultJobsDir(),
 		// REQ-RESURRECTABLE-SANDBOX. `||` (not `??`) so an empty string falls back, matching logsDir.
@@ -198,6 +258,22 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// A bound on how large a transcript may be before it stops being resumed. Not disk hygiene: an
 		// oversized transcript is a prefill an operator never sized PI_MAX_TOKENS for.
 		sessionMaxBytes: nonNegativeInt(env, "PI_SESSION_MAX_BYTES", 8 * 1024 * 1024), // 0 = no cap
+		// How old the CONVERSATION may be, which is a different clock from sessionsTtlDays above and not a
+		// finer setting of it: the TTL reads the transcript's mtime, which the PROMOTE rename refreshes (the
+		// resolve copy does not, measured -- copyFileSync stamps the destination), so it measures time since
+		// the last COMPLETED run on this key. A key whose runs keep completing never expires however old its
+		// first turn is. This one reads the session header's own timestamp.
+		// OFF by default (0) rather than defaulted to a number: an age an operator did not choose is an
+		// opinion about their lineages that this project has no basis for.
+		sessionMaxAgeDays: nonNegativeInt(env, "PI_SESSION_MAX_AGE_DAYS", 0), // 0 = no age bound
+		// How many times in a row one key may be resumed before the next job starts fresh. The bound a long
+		// lineage actually needs: age and size both grow slowly while a chain grows once per run.
+		sessionMaxResumeChain: nonNegativeInt(env, "PI_SESSION_MAX_RESUME_CHAIN", 0), // 0 = no chain bound
+		// How full the saved context may be before a resume is refused, as a percentage of the model's own
+		// window. A PERCENTAGE, so `optionalBoundedInt` on softHoldPct's precedent rather than the 0 = off
+		// sentinel its two neighbours use: 0% would mean "never resume anything", which is a different
+		// request from "no bound", and 101 is a typo rather than a ceiling.
+		sessionMaxContextPct: optionalBoundedInt(env, "PI_SESSION_MAX_CONTEXT_PCT", 1, 100), // null = no context bound
 		chainDepthMax: nonNegativeInt(env, "PI_CHAIN_DEPTH_MAX", CHAIN_DEPTH_MAX_DEFAULT), // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
 		chainMaxPerJob: nonNegativeInt(env, "PI_CHAIN_MAX_PER_JOB", CHAIN_MAX_PER_JOB_DEFAULT), // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
 		dispatchRunPerHour: nonNegativeInt(env, "PI_DISPATCH_RUN_PER_HOUR", 3), // DES-ADMIN-VIA-PI-EXTENSION; 0 = disable dispatch_run
@@ -209,10 +285,43 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 	};
 }
 
+/**
+ * Normalise an inline App private key, or refuse it. Returns `null` for absent/blank (an empty
+ * `GITHUB_APP_PRIVATE_KEY=` line in a scaffolded .env means "unset", never "a key that is empty").
+ *
+ * ONE normalisation rule, and it is unambiguous rather than lenient: a PEM contains no backslash, so a
+ * value carrying literal `\n` escapes and no real newline can only be a flattened key -- which is what a
+ * .env line and most secrets-manager UIs produce, since neither can hold a multi-line value. Anything
+ * else is passed through untouched.
+ *
+ * Then the shape is CHECKED, because the alternative is a deployment that boots clean and dies at its
+ * first mint with a crypto error naming nothing. A truncated paste fails here instead.
+ *
+ * The value NEVER appears in a refusal message. That is the whole reason this is a function rather than
+ * three lines inline: one place to get that right, and one place to test it.
+ */
+export function normalizeAppPrivateKey(raw) {
+	const value = typeof raw === "string" ? raw.trim() : "";
+	if (value === "") return null;
+	const pem = value.includes("\\n") && !value.includes("\n") ? value.replace(/\\n/g, "\n") : value;
+	const begins = /^-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/.test(pem);
+	const ends = /-----END [A-Z0-9 ]*PRIVATE KEY-----$/.test(pem.trimEnd());
+	if (!begins || !ends) {
+		throw configError(
+			"GITHUB_APP_PRIVATE_KEY is not a PEM private key -- expected it to begin `-----BEGIN ... PRIVATE KEY-----` and end `-----END ... PRIVATE KEY-----` (the value itself is deliberately not shown; check for a truncated paste, or use GITHUB_APP_PRIVATE_KEY_PATH)",
+		);
+	}
+	return pem;
+}
+
 /**
  * Parse and validate the GitHub auth block consumed verbatim by `makeGitHubAuth(cfg)` in
- * get-token.mjs. Shape is fixed: `{ source, patVar, appId, installationId, privateKeyPath }`.
+ * get-token.mjs. Shape is fixed: `{ source, patVar, appId, installationId, privateKeyPath, privateKey }`.
  * Fails loud at load time so a misconfigured worker refuses to boot rather than failing per-job.
+ *
+ * `privateKey` carries KEY MATERIAL when the operator supplied it inline, so nothing may serialise this
+ * block: its three consumers (start.mjs, cli.mjs, sandbox-cli.mjs) pass it along and never print it, and
+ * that is a property to keep rather than a coincidence to rely on.
  */
 export function loadGitHubAuth(env, fileExists) {
 	const source = env.GITHUB_AUTH_SOURCE ?? "gh";
@@ -224,6 +333,11 @@ export function loadGitHubAuth(env, fileExists) {
 	const appId = env.GITHUB_APP_ID;
 	const installationId = env.GITHUB_APP_INSTALLATION_ID;
 	const privateKeyPath = env.GITHUB_APP_PRIVATE_KEY_PATH;
+	// Blank counts as unset on BOTH, so a scaffolded `.env` full of empty keys never shadows the one an
+	// operator actually set.
+	const inlineKey = (env.GITHUB_APP_PRIVATE_KEY ?? "").trim();
+	const keyPathSet = (privateKeyPath ?? "").trim() !== "";
+	let privateKey = null;
 
 	if (source === "pat") {
 		const pat = (env[patVar] ?? "").trim();
@@ -233,19 +347,32 @@ export function loadGitHubAuth(env, fileExists) {
 	}
 
 	if (source === "app") {
+		// Both set is a REFUSAL, not a precedence rule. A precedence rule means two places hold the App's
+		// signing key, they disagree eventually, and the deployment keeps working with whichever one this
+		// function happened to prefer -- which is exactly the class of surprise every other credential
+		// decision in this file forecloses.
+		if (inlineKey !== "" && keyPathSet) {
+			throw configError(
+				"GITHUB_APP_PRIVATE_KEY and GITHUB_APP_PRIVATE_KEY_PATH are both set -- supply the App key exactly once (the inline value for a secrets manager, the path for a key on disk)",
+			);
+		}
 		const missing = [];
 		if (!appId) missing.push("GITHUB_APP_ID");
 		if (!installationId) missing.push("GITHUB_APP_INSTALLATION_ID");
-		if (!privateKeyPath) missing.push("GITHUB_APP_PRIVATE_KEY_PATH");
+		if (inlineKey === "" && !keyPathSet) missing.push("GITHUB_APP_PRIVATE_KEY_PATH (or GITHUB_APP_PRIVATE_KEY)");
 		if (missing.length > 0) {
 			throw configError(`GITHUB_AUTH_SOURCE=app requires ${missing.join(", ")}`);
 		}
-		if (!fileExists(privateKeyPath)) {
+		if (inlineKey !== "") {
+			privateKey = normalizeAppPrivateKey(inlineKey);
+		} else if (!fileExists(privateKeyPath)) {
+			// Only when the PATH is the chosen source: an inline deployment has no key file to check, which
+			// is the entire point of the variable (docs/secrets.md).
 			throw configError(`GITHUB_APP_PRIVATE_KEY_PATH does not exist: ${privateKeyPath}`);
 		}
 	}
 
-	return { source, patVar, appId, installationId, privateKeyPath };
+	return { source, patVar, appId, installationId, privateKeyPath, privateKey };
 }
 
 function defaultJobsDir() {

package/src/docker-run.mjs

@@ -62,6 +62,8 @@ export const ISOLATION_FLAGS = [
  * @param globalPiDir host path to the operator's global pi overlay (REQ-GLOBAL-PI-OVERLAY); mounted /opt/pi-global:ro
  * @param name       container name (for `docker stop` at the timeout)
  * @param memory     e.g. "4g"; cpus e.g. "2"
+ * @param network    the per-job egress network this container joins (REQ-EGRESS-ALLOWLIST); null = the
+ *                   docker default bridge, which is what every job did before that requirement existed
  * @param extraFlags escape hatch for a Linux-only --user uid:gid on a bind-mounted local folder
  */
 export function buildDockerRunArgs({
@@ -75,13 +77,26 @@ export function buildDockerRunArgs({
 	name,
 	memory = "4g",
 	cpus = "2",
+	network = null,
 	extraFlags = [],
 }) {
 	if (!image) throw new Error("docker run: image is required");
 	if (!name) throw new Error("docker run: container name is required");
 	if (!workspace) throw new Error("docker run: workspace mount is required");
 
-	const args = ["run", `--name=${name}`, ...ISOLATION_FLAGS, `--memory=${memory}`, `--cpus=${cpus}`, ...extraFlags];
+	// `--network` sits HERE, beside --memory and --cpus, and deliberately NOT inside ISOLATION_FLAGS.
+	// That array is the LITERAL, value-free, unconditional set, and two separate places assert every member
+	// of it reaches the sandbox argv *against the imported array, not a copy* (CONST-ISOLATION-CONTAINER-PER-JOB
+	// and INT-SANDBOX-CONTRACT). A conditional member makes "every member" false on any deployment running
+	// without an egress policy, so the assertion would have to be weakened to "every member except this one"
+	// -- which does not weaken a constraint so much as retire the assertion that was enforcing it. There is
+	// no literal to put there anyway: the name carries a job id.
+	//
+	// null => the flag is ABSENT, so a job argv without an egress policy is byte-identical to one built
+	// before this feature existed. Same shape as the sessionDir/outboxDir/globalPiDir mounts below.
+	const args = ["run", `--name=${name}`, ...ISOLATION_FLAGS, `--memory=${memory}`, `--cpus=${cpus}`];
+	if (network) args.push(`--network=${network}`);
+	args.push(...extraFlags);
 
 	// Explicit env allowlist. Each entry is `-e NAME=VALUE`, built from the closed map -- so a
 	// stray host variable cannot ride along (no bare `-e NAME` inheriting from the host, no