@peakflo/agent-harness 0.2.12 → 0.2.13-rc.1

package/dist/bootstrap-handoff.d.ts

@@ -0,0 +1,73 @@
+/**
+ * PRIVATE CREDENTIAL HANDOFF FROM pf-bootstrap — never through the environment.
+ *
+ * THE PROBLEM. pf-bootstrap used to hand the enrolment token (cold boot) and
+ * the LIVE runner credential (warm in-place upgrade) to the harness in
+ * PF_ENROLMENT_TOKEN / PF_RUNNER_CREDENTIAL. Deleting them from `process.env`
+ * afterwards (see `scrubCredentialEnv`) keeps them out of child environments,
+ * but `/proc/<pid>/environ` is the execve SNAPSHOT and keeps them for the
+ * life of the process. Pi and every agent subprocess run as the same uid as
+ * the harness, and the kernel lets a same-uid process read another's environ.
+ * Confirmed on staging: an agent could read the live runner credential.
+ *
+ * THE FIX. pf-bootstrap already spawns the harness with a private IPC channel
+ * (`stdio: [..., 'ipc']`, a socketpair only the two processes hold). It now
+ * sets the NON-secret marker `PF_CREDENTIAL_HANDOFF=ipc` and puts no secret in
+ * the environment at all. At startup the harness sends ONE request on that
+ * channel and pf-bootstrap answers ONCE with the credentials. They live only
+ * in this process's heap from then on.
+ *
+ * Request/response rather than "bootstrap pushes on spawn": a message that
+ * arrives before a listener exists is dropped, and asking first also means
+ * pf-bootstrap never writes a secret to a channel nobody is reading.
+ *
+ * COMPATIBILITY. Without the marker (an older pf-bootstrap image, a
+ * self-hosted runner, the desktop) nothing here runs and the environment path
+ * works exactly as before, followed by the same scrub. pf-bootstrap only sets
+ * the marker for a harness whose package.json declares
+ * `peakflo.credentialHandoff: "ipc"` (see package.json), so an older harness
+ * installed by a newer image still gets its token the old way.
+ */
+/** The non-secret marker pf-bootstrap sets when it will answer over IPC. */
+export declare const CREDENTIAL_HANDOFF_ENV = "PF_CREDENTIAL_HANDOFF";
+export declare const CREDENTIAL_HANDOFF_IPC = "ipc";
+/** harness -> bootstrap. */
+export declare const CREDENTIAL_REQUEST_TYPE = "pf-harness-credentials-request";
+/** bootstrap -> harness. */
+export declare const CREDENTIAL_RESPONSE_TYPE = "pf-bootstrap-credentials";
+export declare const CREDENTIAL_HANDOFF_TIMEOUT_MS = 15000;
+/** The variables that may carry a credential. Never left in `process.env`. */
+export declare const CREDENTIAL_ENV_KEYS: readonly ["PF_ENROLMENT_TOKEN", "PF_RUNNER_CREDENTIAL", "PF_RUNNER_ID", "PF_RUNNER_TENANT_ID", "PF_RUNNER_CREDENTIAL_EXPIRES_AT"];
+export interface BootstrapCredentials {
+    /** Cold boot: the enrolment token. Warm upgrade: the live runner credential. */
+    enrolmentToken: string;
+    runnerId?: string;
+    runnerCredential?: string;
+    tenantId?: string | null;
+    credentialExpiresAt?: string | null;
+}
+/** The slice of `process` this needs, so tests can pass a fake. */
+export interface HandoffProcess {
+    send?: (message: unknown) => boolean;
+    on(event: 'message', listener: (message: unknown) => void): unknown;
+    off(event: 'message', listener: (message: unknown) => void): unknown;
+}
+export declare class CredentialHandoffError extends Error {
+    constructor(message: string);
+}
+/** Remove every credential-bearing variable. Idempotent. */
+export declare function scrubCredentialEnv(env: NodeJS.ProcessEnv): void;
+/**
+ * Ask pf-bootstrap for the credentials over the private IPC channel.
+ *
+ * Returns null — and does nothing — when the marker is absent: the caller then
+ * uses the environment exactly as before. The marker itself is removed either
+ * way, so agent subprocesses do not inherit it.
+ */
+export declare function receiveBootstrapCredentials(proc: HandoffProcess, env: NodeJS.ProcessEnv, timeoutMs?: number): Promise<BootstrapCredentials | null>;
+/**
+ * The credentials as the environment-shaped variables `parseOptions` and
+ * `takeHandedOffCredential` already understand. The result is merged into a
+ * PLAIN OBJECT copy of the environment, never into `process.env`.
+ */
+export declare function credentialsAsEnv(credentials: BootstrapCredentials): NodeJS.ProcessEnv;

package/dist/bootstrap-handoff.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * PRIVATE CREDENTIAL HANDOFF FROM pf-bootstrap — never through the environment.
+ *
+ * THE PROBLEM. pf-bootstrap used to hand the enrolment token (cold boot) and
+ * the LIVE runner credential (warm in-place upgrade) to the harness in
+ * PF_ENROLMENT_TOKEN / PF_RUNNER_CREDENTIAL. Deleting them from `process.env`
+ * afterwards (see `scrubCredentialEnv`) keeps them out of child environments,
+ * but `/proc/<pid>/environ` is the execve SNAPSHOT and keeps them for the
+ * life of the process. Pi and every agent subprocess run as the same uid as
+ * the harness, and the kernel lets a same-uid process read another's environ.
+ * Confirmed on staging: an agent could read the live runner credential.
+ *
+ * THE FIX. pf-bootstrap already spawns the harness with a private IPC channel
+ * (`stdio: [..., 'ipc']`, a socketpair only the two processes hold). It now
+ * sets the NON-secret marker `PF_CREDENTIAL_HANDOFF=ipc` and puts no secret in
+ * the environment at all. At startup the harness sends ONE request on that
+ * channel and pf-bootstrap answers ONCE with the credentials. They live only
+ * in this process's heap from then on.
+ *
+ * Request/response rather than "bootstrap pushes on spawn": a message that
+ * arrives before a listener exists is dropped, and asking first also means
+ * pf-bootstrap never writes a secret to a channel nobody is reading.
+ *
+ * COMPATIBILITY. Without the marker (an older pf-bootstrap image, a
+ * self-hosted runner, the desktop) nothing here runs and the environment path
+ * works exactly as before, followed by the same scrub. pf-bootstrap only sets
+ * the marker for a harness whose package.json declares
+ * `peakflo.credentialHandoff: "ipc"` (see package.json), so an older harness
+ * installed by a newer image still gets its token the old way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialHandoffError = exports.CREDENTIAL_ENV_KEYS = exports.CREDENTIAL_HANDOFF_TIMEOUT_MS = exports.CREDENTIAL_RESPONSE_TYPE = exports.CREDENTIAL_REQUEST_TYPE = exports.CREDENTIAL_HANDOFF_IPC = exports.CREDENTIAL_HANDOFF_ENV = void 0;
+exports.scrubCredentialEnv = scrubCredentialEnv;
+exports.receiveBootstrapCredentials = receiveBootstrapCredentials;
+exports.credentialsAsEnv = credentialsAsEnv;
+/** The non-secret marker pf-bootstrap sets when it will answer over IPC. */
+exports.CREDENTIAL_HANDOFF_ENV = 'PF_CREDENTIAL_HANDOFF';
+exports.CREDENTIAL_HANDOFF_IPC = 'ipc';
+/** harness -> bootstrap. */
+exports.CREDENTIAL_REQUEST_TYPE = 'pf-harness-credentials-request';
+/** bootstrap -> harness. */
+exports.CREDENTIAL_RESPONSE_TYPE = 'pf-bootstrap-credentials';
+exports.CREDENTIAL_HANDOFF_TIMEOUT_MS = 15_000;
+/** The variables that may carry a credential. Never left in `process.env`. */
+exports.CREDENTIAL_ENV_KEYS = [
+    'PF_ENROLMENT_TOKEN',
+    'PF_RUNNER_CREDENTIAL',
+    'PF_RUNNER_ID',
+    'PF_RUNNER_TENANT_ID',
+    'PF_RUNNER_CREDENTIAL_EXPIRES_AT'
+];
+class CredentialHandoffError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CredentialHandoffError';
+    }
+}
+exports.CredentialHandoffError = CredentialHandoffError;
+/** Remove every credential-bearing variable. Idempotent. */
+function scrubCredentialEnv(env) {
+    for (const key of exports.CREDENTIAL_ENV_KEYS) {
+        delete env[key];
+    }
+}
+const nonEmpty = (value) => typeof value === 'string' && value.length > 0;
+function parseResponse(message) {
+    if (typeof message !== 'object' || message === null)
+        return null;
+    const m = message;
+    if (m.type !== exports.CREDENTIAL_RESPONSE_TYPE || !nonEmpty(m.enrolmentToken)) {
+        return null;
+    }
+    const credentials = {
+        enrolmentToken: m.enrolmentToken
+    };
+    // A runner id without its credential (or the reverse) is not a handoff.
+    if (nonEmpty(m.runnerId) && nonEmpty(m.runnerCredential)) {
+        credentials.runnerId = m.runnerId;
+        credentials.runnerCredential = m.runnerCredential;
+        credentials.tenantId = nonEmpty(m.tenantId) ? m.tenantId : null;
+        credentials.credentialExpiresAt = nonEmpty(m.credentialExpiresAt)
+            ? m.credentialExpiresAt
+            : null;
+    }
+    return credentials;
+}
+/**
+ * Ask pf-bootstrap for the credentials over the private IPC channel.
+ *
+ * Returns null — and does nothing — when the marker is absent: the caller then
+ * uses the environment exactly as before. The marker itself is removed either
+ * way, so agent subprocesses do not inherit it.
+ */
+async function receiveBootstrapCredentials(proc, env, timeoutMs = exports.CREDENTIAL_HANDOFF_TIMEOUT_MS) {
+    const mode = env[exports.CREDENTIAL_HANDOFF_ENV];
+    delete env[exports.CREDENTIAL_HANDOFF_ENV];
+    if (mode === undefined || mode === '')
+        return null;
+    if (mode !== exports.CREDENTIAL_HANDOFF_IPC) {
+        throw new CredentialHandoffError(`Unsupported ${exports.CREDENTIAL_HANDOFF_ENV} '${mode}'. Expected '${exports.CREDENTIAL_HANDOFF_IPC}'.`);
+    }
+    const send = proc.send;
+    if (typeof send !== 'function') {
+        throw new CredentialHandoffError(`${exports.CREDENTIAL_HANDOFF_ENV}=ipc is set but this process has no IPC channel`);
+    }
+    return new Promise((resolve, reject) => {
+        let timer;
+        const finish = (error, value) => {
+            proc.off('message', onMessage);
+            if (timer)
+                clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const onMessage = (message) => {
+            const credentials = parseResponse(message);
+            if (credentials)
+                finish(null, credentials);
+        };
+        // Listen BEFORE asking, so the answer cannot arrive unheard.
+        proc.on('message', onMessage);
+        timer = setTimeout(() => finish(new CredentialHandoffError(`pf-bootstrap did not hand over the credentials within ${timeoutMs} ms`)), timeoutMs);
+        try {
+            send.call(proc, { type: exports.CREDENTIAL_REQUEST_TYPE });
+        }
+        catch (error) {
+            finish(new CredentialHandoffError(`Could not ask pf-bootstrap for the credentials: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    });
+}
+/**
+ * The credentials as the environment-shaped variables `parseOptions` and
+ * `takeHandedOffCredential` already understand. The result is merged into a
+ * PLAIN OBJECT copy of the environment, never into `process.env`.
+ */
+function credentialsAsEnv(credentials) {
+    const env = {
+        PF_ENROLMENT_TOKEN: credentials.enrolmentToken
+    };
+    if (credentials.runnerId && credentials.runnerCredential) {
+        env.PF_RUNNER_ID = credentials.runnerId;
+        env.PF_RUNNER_CREDENTIAL = credentials.runnerCredential;
+        if (credentials.tenantId)
+            env.PF_RUNNER_TENANT_ID = credentials.tenantId;
+        if (credentials.credentialExpiresAt) {
+            env.PF_RUNNER_CREDENTIAL_EXPIRES_AT = credentials.credentialExpiresAt;
+        }
+    }
+    return env;
+}

package/dist/cli.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const adapter_resolver_1 = require("./adapter-resolver");
+const bootstrap_handoff_1 = require("./bootstrap-handoff");
 const contract_1 = require("./contract");
 const credential_store_1 = require("./credential-store");
 const harness_1 = require("./harness");
@@ -97,8 +98,8 @@ Options:
 Needs Node.js 22.19 or newer; start stops with one line on an older one.
 PF_ALLOW_UNSUPPORTED_NODE=1 starts anyway, at your own risk.
 
-In a managed sandbox pf-bootstrap supplies these through the environment, so
-the enrolment token never appears in /proc/<pid>/cmdline.
+In a managed sandbox pf-bootstrap hands the token over a private IPC channel,
+so it never appears in /proc/<pid>/cmdline or /proc/<pid>/environ.
 `;
 const serviceStart = (0, service_1.isServiceStart)(process.argv.slice(2));
 function stopPermanentServiceFailure(reason, linuxCode) {
@@ -224,8 +225,22 @@ async function main() {
      */
     const startArgs = argv.slice(1);
     const wantsLogin = startArgs.includes('--login');
+    /*
+     * CREDENTIALS NEVER STAY IN process.env. A current pf-bootstrap hands them
+     * over its private IPC channel (bootstrap-handoff.ts); an older one, a
+     * self-hosted install or a developer still uses the environment. Either way
+     * they are merged into `startEnv`, a PLAIN OBJECT copy that lives only in
+     * this heap, and every credential variable is scrubbed from process.env
+     * before anything else runs, so no child can inherit one.
+     */
+    const handoff = await (0, bootstrap_handoff_1.receiveBootstrapCredentials)(process, process.env);
+    const startEnv = {
+        ...process.env,
+        ...(handoff ? (0, bootstrap_handoff_1.credentialsAsEnv)(handoff) : {})
+    };
+    (0, bootstrap_handoff_1.scrubCredentialEnv)(process.env);
     // `--token=x` counts as a token, hence readOptionValue rather than indexOf.
-    const hasToken = Boolean(readOptionValue(startArgs, 'token') ?? process.env.PF_ENROLMENT_TOKEN);
+    const hasToken = Boolean(readOptionValue(startArgs, 'token') ?? startEnv.PF_ENROLMENT_TOKEN);
     const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
     if (!serviceStart && !hasToken && (wantsLogin || interactive)) {
         const { enrolViaBrowser } = await Promise.resolve().then(() => __importStar(require('./enrol/browser-enrol')));
@@ -239,17 +254,17 @@ async function main() {
             appUrl: readOptionValue(startArgs, 'app-url') ?? process.env.PF_APP_URL,
             label: readOptionValue(startArgs, 'label') ?? process.env.PF_RUNNER_LABEL
         });
-        // Handed on through the environment rather than argv, for the same reason
-        // pf-bootstrap does: argv is world-readable via /proc/<pid>/cmdline.
-        process.env.PF_ENROLMENT_TOKEN = token;
+        // Handed on in memory rather than argv: argv is world-readable via
+        // /proc/<pid>/cmdline. Never written back to process.env.
+        startEnv.PF_ENROLMENT_TOKEN = token;
     }
-    const options = (0, options_1.parseOptions)(startArgs, process.env);
+    const options = (0, options_1.parseOptions)(startArgs, startEnv);
     new service_1.ServiceManager({
         nodePath: process.execPath,
         cliPath: __filename,
         env: process.env
     }).assertNoDuplicateRunner(options);
-    const handedOffCredential = (0, credential_store_1.takeHandedOffCredential)(process.env);
+    const handedOffCredential = (0, credential_store_1.takeHandedOffCredential)(startEnv);
     const resolveAdapter = (0, adapter_resolver_1.createAdapterResolver)(options.runtime, options.workspaceRoot);
     const harness = new harness_1.Harness(options, {
         getAdapter: (backend, ports) => resolveAdapter(backend, ports),

package/dist/credential-store.d.ts

@@ -81,8 +81,9 @@ export declare class MemoryCredentialStore implements CredentialStore {
     clear(): void;
 }
 /**
- * Take the private bootstrap handoff and remove every credential-bearing
- * variable before an adapter can copy the process environment to a child.
+ * Take the bootstrap handoff out of an environment-shaped object and remove
+ * every credential-bearing variable from it, before an adapter can copy the
+ * process environment to a child.
  */
 export declare function takeHandedOffCredential(env: NodeJS.ProcessEnv): StoredCredential | null;
 /**

package/dist/credential-store.js

@@ -39,6 +39,7 @@ exports.takeHandedOffCredential = takeHandedOffCredential;
 exports.createCredentialStore = createCredentialStore;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const bootstrap_handoff_1 = require("./bootstrap-handoff");
 /** The file name under the workspace root. */
 exports.CREDENTIAL_FILE_NAME = 'runner-credential.json';
 /**
@@ -80,8 +81,9 @@ class MemoryCredentialStore {
 }
 exports.MemoryCredentialStore = MemoryCredentialStore;
 /**
- * Take the private bootstrap handoff and remove every credential-bearing
- * variable before an adapter can copy the process environment to a child.
+ * Take the bootstrap handoff out of an environment-shaped object and remove
+ * every credential-bearing variable from it, before an adapter can copy the
+ * process environment to a child.
  */
 function takeHandedOffCredential(env) {
     const runnerId = env.PF_RUNNER_ID;
@@ -98,11 +100,9 @@ function takeHandedOffCredential(env) {
     // On warm upgrade PF_ENROLMENT_TOKEN contains the live runner credential.
     // On cold boot it contains a single-use enrolment token. Neither belongs in
     // an agent subprocess environment after parseOptions() has consumed it.
-    delete env.PF_ENROLMENT_TOKEN;
-    delete env.PF_RUNNER_CREDENTIAL;
-    delete env.PF_RUNNER_ID;
-    delete env.PF_RUNNER_TENANT_ID;
-    delete env.PF_RUNNER_CREDENTIAL_EXPIRES_AT;
+    // Scrubbing process.env does NOT clear /proc/<pid>/environ, which is why a
+    // current pf-bootstrap hands these over IPC instead (bootstrap-handoff.ts).
+    (0, bootstrap_handoff_1.scrubCredentialEnv)(env);
     return stored;
 }
 function isStoredCredential(value) {

package/dist/options.d.ts

@@ -7,9 +7,10 @@ export declare class OptionsError extends Error {
  *
  * NOTE ON THE ENROLMENT TOKEN: it is accepted on the command line for local
  * development and self-hosted installs, which is what the design calls for.
- * In a managed sandbox pf-bootstrap passes it through PF_ENROLMENT_TOKEN
- * instead, so it never appears in the process arguments — /proc/<pid>/cmdline
- * is world-readable, while /proc/<pid>/environ is readable only by the
- * process owner.
+ * In a managed sandbox pf-bootstrap hands it over its private IPC channel
+ * (bootstrap-handoff.ts) and cli.ts passes it here in a plain in-memory copy
+ * of the environment, so it never appears in /proc/<pid>/cmdline (world-
+ * readable) or /proc/<pid>/environ (readable by the same uid, which Pi
+ * shares). An older pf-bootstrap still sets PF_ENROLMENT_TOKEN itself.
  */
 export declare function parseOptions(argv: string[], env: NodeJS.ProcessEnv): HarnessOptions;

package/dist/options.js

@@ -182,10 +182,11 @@ function parseSwitch(raw, fallback, name) {
  *
  * NOTE ON THE ENROLMENT TOKEN: it is accepted on the command line for local
  * development and self-hosted installs, which is what the design calls for.
- * In a managed sandbox pf-bootstrap passes it through PF_ENROLMENT_TOKEN
- * instead, so it never appears in the process arguments — /proc/<pid>/cmdline
- * is world-readable, while /proc/<pid>/environ is readable only by the
- * process owner.
+ * In a managed sandbox pf-bootstrap hands it over its private IPC channel
+ * (bootstrap-handoff.ts) and cli.ts passes it here in a plain in-memory copy
+ * of the environment, so it never appears in /proc/<pid>/cmdline (world-
+ * readable) or /proc/<pid>/environ (readable by the same uid, which Pi
+ * shares). An older pf-bootstrap still sets PF_ENROLMENT_TOKEN itself.
  */
 function parseOptions(argv, env) {
     const controlPlaneUrl = readFlag(argv, 'control-plane') ?? env.PF_CONTROL_PLANE_URL;

package/dist/types.d.ts

@@ -27,11 +27,15 @@
  *    can use. `POST /api/coding-agents/sessions/:id/ingest` in particular is
  *    identical for all three; that is the whole payoff of the extraction.
  *
- * 4. TOKENS TRAVEL IN THE ENVIRONMENT OR IN HEADERS, NEVER IN ARGV.
- *    `/proc/<pid>/cmdline` is world-readable; `/proc/<pid>/environ` is readable
- *    only by the process owner. Every credential below is either an
- *    `Authorization: Bearer` header or an environment variable handed to a
- *    child process. Do not "improve" this by adding a `--token` flag.
+ * 4. TOKENS TRAVEL IN HEADERS OR IN MEMORY, NEVER IN ARGV.
+ *    `/proc/<pid>/cmdline` is world-readable. `/proc/<pid>/environ` is
+ *    readable by every process of the same uid — and in a sandbox Pi shares
+ *    the harness's uid — and keeps the execve snapshot even after
+ *    `delete process.env.X`. So the RUNNER's own credentials reach a managed
+ *    sandbox harness over pf-bootstrap's private IPC channel
+ *    (bootstrap-handoff.ts), not the environment; the environment remains
+ *    only for a self-hosted or desktop start and an older pf-bootstrap.
+ *    Do not "improve" this by adding a `--token` flag.
  */
 export interface HarnessOptions {
     /** workflow-api base url, e.g. https://stage-api.peakflo.ai */

package/dist/types.js

@@ -28,11 +28,15 @@
  *    can use. `POST /api/coding-agents/sessions/:id/ingest` in particular is
  *    identical for all three; that is the whole payoff of the extraction.
  *
- * 4. TOKENS TRAVEL IN THE ENVIRONMENT OR IN HEADERS, NEVER IN ARGV.
- *    `/proc/<pid>/cmdline` is world-readable; `/proc/<pid>/environ` is readable
- *    only by the process owner. Every credential below is either an
- *    `Authorization: Bearer` header or an environment variable handed to a
- *    child process. Do not "improve" this by adding a `--token` flag.
+ * 4. TOKENS TRAVEL IN HEADERS OR IN MEMORY, NEVER IN ARGV.
+ *    `/proc/<pid>/cmdline` is world-readable. `/proc/<pid>/environ` is
+ *    readable by every process of the same uid — and in a sandbox Pi shares
+ *    the harness's uid — and keeps the execve snapshot even after
+ *    `delete process.env.X`. So the RUNNER's own credentials reach a managed
+ *    sandbox harness over pf-bootstrap's private IPC channel
+ *    (bootstrap-handoff.ts), not the environment; the environment remains
+ *    only for a self-hosted or desktop start and an older pf-bootstrap.
+ *    Do not "improve" this by adding a `--token` flag.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 /* -------------------------------------------------------------------------- */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.12",
+  "version": "0.2.13-rc.1",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",
@@ -14,6 +14,9 @@
     "README.md",
     "LICENSE"
   ],
+  "peakflo": {
+    "credentialHandoff": "ipc"
+  },
   "engines": {
     "node": ">=22.19"
   },