@peakflo/agent-harness 0.0.0-stage → 0.2.1-rc.3

package/dist/credential-store.d.ts

@@ -0,0 +1,110 @@
+/**
+ * DURABLE RUNNER CREDENTIAL STORAGE — the fix for "a crashed harness can never
+ * rejoin".
+ *
+ * THE PROBLEM. The enrolment token is single-use and burns on the first
+ * `register`. The runner credential it is exchanged for is long-lived
+ * (RUNNER_CREDENTIAL_TTL_SECONDS = 86400) but Track B held it IN MEMORY ONLY,
+ * inside `ControlPlaneClient`. So a harness that crashed — SIGKILL, OOM, a host
+ * reboot — lost the one credential it had and could not get another: `register`
+ * answers `401 enrolment_token_spent`, which the harness correctly treats as
+ * final and exits. On a Daytona sandbox that is harmless, because a fresh
+ * sandbox is minted with a fresh single-use token. On a SELF-HOSTED runner it
+ * bricks the host until a human issues a new token.
+ *
+ * "Long-lived credential" and "memory only" are in direct tension: a credential
+ * is long-lived precisely so it can outlive a process. So it is persisted here —
+ * but ONLY for the runtimes where that reasoning holds.
+ *
+ * WHICH RUNTIMES, AND WHY. The parent research says the sandbox token is "MEMORY
+ * ONLY, never on disk". That reasoning was written for the SANDBOX, where
+ * session users share a host and a credential on disk is a credential a session
+ * user might read. It does NOT extend to a self-hosted VM or the desktop, which
+ * are single-tenant machines the customer owns, and where every comparable
+ * runner installer (GitHub Actions, GitLab, Buildkite) persists exactly this.
+ *
+ *   - `sandbox`      -> NoCredentialStore. Memory only. A fresh token always
+ *                       exists, and the host is shared.
+ *   - `self-hosted`  -> FileCredentialStore at 0600 under the workspace root.
+ *   - `desktop`      -> FileCredentialStore. The user's own machine.
+ *
+ * The file is written 0600 so that even on a multi-user VM it is readable only
+ * by the harness user — matching how the sandbox already protects the bootstrap
+ * .npmrc.
+ */
+import { RunnerRuntime } from './types';
+/** The file name under the workspace root. */
+export declare const CREDENTIAL_FILE_NAME = "runner-credential.json";
+/**
+ * What is persisted. Deliberately the minimum a harness needs to re-authenticate
+ * without re-enrolling: the credential, who it belongs to, and when it expires.
+ * No enrolment token is ever stored — it is single-use and already spent by the
+ * time a credential exists.
+ */
+export interface StoredCredential {
+    runnerId: string;
+    tenantId: string | null;
+    credential: string;
+    /** ISO 8601, or null when the control plane returned no expiry. */
+    credentialExpiresAt: string | null;
+    /** ISO 8601. When this row was written, for operator diagnostics. */
+    savedAt: string;
+}
+export interface CredentialStore {
+    /** The stored credential, or null when there is none or it is unreadable. */
+    load(): StoredCredential | null;
+    /** Persist a credential, overwriting any previous one. */
+    save(credential: StoredCredential): void;
+    /** Remove the stored credential. Idempotent. */
+    clear(): void;
+}
+/**
+ * The sandbox implementation: hold nothing.
+ *
+ * This is a REAL decision, not a stub. A sandbox is ephemeral and its host is
+ * shared between session users, so persisting the credential would both be
+ * pointless (the disk goes away with the sandbox) and a small exposure (a
+ * session user could read it). Memory only is the correct security position
+ * there — the same one Track B shipped.
+ */
+export declare class NoCredentialStore implements CredentialStore {
+    load(): StoredCredential | null;
+    save(): void;
+    clear(): void;
+}
+/** One-process credential handoff from pf-bootstrap. Nothing is written. */
+export declare class MemoryCredentialStore implements CredentialStore {
+    private credential;
+    constructor(credential: StoredCredential | null);
+    load(): StoredCredential | null;
+    save(credential: StoredCredential): void;
+    clear(): void;
+}
+/**
+ * Take the private bootstrap handoff and remove every credential-bearing
+ * variable before an adapter can copy the process environment to a child.
+ */
+export declare function takeHandedOffCredential(env: NodeJS.ProcessEnv): StoredCredential | null;
+/**
+ * The durable implementation: a single JSON file at 0600.
+ *
+ * Synchronous fs on purpose. This is touched at most a handful of times per
+ * process — once on start, once per registration, once per rotation — and never
+ * on the hot path of a turn, so there is nothing to gain from async and a great
+ * deal of clarity to lose. A partial or corrupt file is treated as "no
+ * credential" rather than a crash: the fallback is enrolment, which is exactly
+ * what an absent credential should trigger.
+ */
+export declare class FileCredentialStore implements CredentialStore {
+    private readonly path;
+    constructor(workspaceRoot: string);
+    load(): StoredCredential | null;
+    save(credential: StoredCredential): void;
+    clear(): void;
+}
+/**
+ * Pick the store for a runtime. This is the ONE place that encodes the
+ * sandbox-vs-durable decision, so a future runtime has exactly one line to
+ * change and cannot silently inherit the wrong policy.
+ */
+export declare function createCredentialStore(runtime: RunnerRuntime, workspaceRoot: string): CredentialStore;

package/dist/credential-store.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * DURABLE RUNNER CREDENTIAL STORAGE — the fix for "a crashed harness can never
+ * rejoin".
+ *
+ * THE PROBLEM. The enrolment token is single-use and burns on the first
+ * `register`. The runner credential it is exchanged for is long-lived
+ * (RUNNER_CREDENTIAL_TTL_SECONDS = 86400) but Track B held it IN MEMORY ONLY,
+ * inside `ControlPlaneClient`. So a harness that crashed — SIGKILL, OOM, a host
+ * reboot — lost the one credential it had and could not get another: `register`
+ * answers `401 enrolment_token_spent`, which the harness correctly treats as
+ * final and exits. On a Daytona sandbox that is harmless, because a fresh
+ * sandbox is minted with a fresh single-use token. On a SELF-HOSTED runner it
+ * bricks the host until a human issues a new token.
+ *
+ * "Long-lived credential" and "memory only" are in direct tension: a credential
+ * is long-lived precisely so it can outlive a process. So it is persisted here —
+ * but ONLY for the runtimes where that reasoning holds.
+ *
+ * WHICH RUNTIMES, AND WHY. The parent research says the sandbox token is "MEMORY
+ * ONLY, never on disk". That reasoning was written for the SANDBOX, where
+ * session users share a host and a credential on disk is a credential a session
+ * user might read. It does NOT extend to a self-hosted VM or the desktop, which
+ * are single-tenant machines the customer owns, and where every comparable
+ * runner installer (GitHub Actions, GitLab, Buildkite) persists exactly this.
+ *
+ *   - `sandbox`      -> NoCredentialStore. Memory only. A fresh token always
+ *                       exists, and the host is shared.
+ *   - `self-hosted`  -> FileCredentialStore at 0600 under the workspace root.
+ *   - `desktop`      -> FileCredentialStore. The user's own machine.
+ *
+ * The file is written 0600 so that even on a multi-user VM it is readable only
+ * by the harness user — matching how the sandbox already protects the bootstrap
+ * .npmrc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileCredentialStore = exports.MemoryCredentialStore = exports.NoCredentialStore = exports.CREDENTIAL_FILE_NAME = void 0;
+exports.takeHandedOffCredential = takeHandedOffCredential;
+exports.createCredentialStore = createCredentialStore;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** The file name under the workspace root. */
+exports.CREDENTIAL_FILE_NAME = 'runner-credential.json';
+/**
+ * The sandbox implementation: hold nothing.
+ *
+ * This is a REAL decision, not a stub. A sandbox is ephemeral and its host is
+ * shared between session users, so persisting the credential would both be
+ * pointless (the disk goes away with the sandbox) and a small exposure (a
+ * session user could read it). Memory only is the correct security position
+ * there — the same one Track B shipped.
+ */
+class NoCredentialStore {
+    load() {
+        return null;
+    }
+    save() {
+        // Deliberately empty. See the class comment.
+    }
+    clear() {
+        // Deliberately empty.
+    }
+}
+exports.NoCredentialStore = NoCredentialStore;
+/** One-process credential handoff from pf-bootstrap. Nothing is written. */
+class MemoryCredentialStore {
+    credential;
+    constructor(credential) {
+        this.credential = credential;
+    }
+    load() {
+        return this.credential;
+    }
+    save(credential) {
+        this.credential = credential;
+    }
+    clear() {
+        this.credential = null;
+    }
+}
+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.
+ */
+function takeHandedOffCredential(env) {
+    const runnerId = env.PF_RUNNER_ID;
+    const credential = env.PF_RUNNER_CREDENTIAL;
+    const stored = runnerId && credential
+        ? {
+            runnerId,
+            tenantId: env.PF_RUNNER_TENANT_ID || null,
+            credential,
+            credentialExpiresAt: env.PF_RUNNER_CREDENTIAL_EXPIRES_AT || null,
+            savedAt: new Date().toISOString()
+        }
+        : null;
+    // 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;
+    return stored;
+}
+function isStoredCredential(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.runnerId === 'string' &&
+        v.runnerId.length > 0 &&
+        typeof v.credential === 'string' &&
+        v.credential.length > 0 &&
+        (v.tenantId === null || typeof v.tenantId === 'string') &&
+        (v.credentialExpiresAt === null ||
+            typeof v.credentialExpiresAt === 'string'));
+}
+/**
+ * The durable implementation: a single JSON file at 0600.
+ *
+ * Synchronous fs on purpose. This is touched at most a handful of times per
+ * process — once on start, once per registration, once per rotation — and never
+ * on the hot path of a turn, so there is nothing to gain from async and a great
+ * deal of clarity to lose. A partial or corrupt file is treated as "no
+ * credential" rather than a crash: the fallback is enrolment, which is exactly
+ * what an absent credential should trigger.
+ */
+class FileCredentialStore {
+    path;
+    constructor(workspaceRoot) {
+        this.path = (0, node_path_1.join)(workspaceRoot, exports.CREDENTIAL_FILE_NAME);
+    }
+    load() {
+        let raw;
+        try {
+            raw = (0, node_fs_1.readFileSync)(this.path, 'utf8');
+        }
+        catch {
+            // Missing file is the ordinary first-boot case, not an error.
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return isStoredCredential(parsed) ? parsed : null;
+        }
+        catch {
+            // A truncated write from a crash between open and flush. Treat it as
+            // absent so the harness re-enrols rather than dying on a parse error.
+            return null;
+        }
+    }
+    save(credential) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.path), { recursive: true, mode: 0o700 });
+        // Write with the restrictive mode up front, then chmod as well: `mode` on
+        // writeFileSync is masked by the process umask, so an unusual umask could
+        // otherwise leave the file group- or world-readable. The explicit chmod is
+        // not subject to the umask.
+        (0, node_fs_1.writeFileSync)(this.path, JSON.stringify(credential), {
+            encoding: 'utf8',
+            mode: 0o600
+        });
+        (0, node_fs_1.chmodSync)(this.path, 0o600);
+    }
+    clear() {
+        (0, node_fs_1.rmSync)(this.path, { force: true });
+    }
+}
+exports.FileCredentialStore = FileCredentialStore;
+/**
+ * Pick the store for a runtime. This is the ONE place that encodes the
+ * sandbox-vs-durable decision, so a future runtime has exactly one line to
+ * change and cannot silently inherit the wrong policy.
+ */
+function createCredentialStore(runtime, workspaceRoot) {
+    if (runtime === 'sandbox') {
+        return new NoCredentialStore();
+    }
+    return new FileCredentialStore(workspaceRoot);
+}

package/dist/enrol/browser-enrol.d.ts

@@ -0,0 +1,85 @@
+/**
+ * INTERACTIVE ENROLMENT — sign in in a browser, choose an org, done.
+ *
+ * Before this, starting a runner meant obtaining an enrolment token out of band
+ * (there is no UI for it — minting one is a `curl` against an admin route) and
+ * pasting it in. That is a fine mechanism for a MANAGED sandbox, where
+ * pf-bootstrap injects the token through the environment precisely so it never
+ * appears in /proc/<pid>/cmdline. It is a poor one for a human on a laptop.
+ *
+ * THIS IS A FAITHFUL PORT OF WHAT 20x ALREADY DOES, not a new design. 20x's
+ * `enterprise:signupInBrowser` starts a loopback HTTP server, opens
+ * `<app>/login?redirect_uri=<loopback>` in the real browser, and waits. The
+ * workflow-builder login page already understands `redirect_uri`: it routes
+ * through `/auth/desktop-callback`, which validates the target is localhost and
+ * then redirects with the Supabase tokens IN THE URL FRAGMENT.
+ *
+ * THE FRAGMENT IS THE WHOLE REASON THIS FILE SERVES AN HTML PAGE. A fragment is
+ * never sent to an HTTP server — that is what keeps the tokens out of server
+ * logs and out of `Referer` headers. So the callback path serves a tiny page
+ * whose script reads `location.hash` and POSTs it back to this same loopback
+ * server. Without that hop the tokens would be visible to the browser and
+ * invisible to us.
+ *
+ * NOTHING NEW IS NEEDED ON THE SERVER. Every endpoint used here already exists
+ * and is already used by 20x:
+ *   POST /api/20x/auth/verify         -> the user's companies
+ *   POST /api/20x/auth/select-tenant  -> a pf-workflo JWT for the chosen org
+ *   POST /api/coding-agents/runners/enrolment-tokens -> the token we then spend
+ *
+ * AND THE TOKEN IS STILL THE ONLY WAY IN. This flow does NOT mint a runner
+ * credential; it mints the same single-use enrolment token an administrator
+ * would have minted by hand, and hands it to the ordinary registration path.
+ * One enrolment path to reason about, one to secure.
+ *
+ * TWO DELIBERATE DEPARTURES FROM 20x's IMPLEMENTATION, both hardening:
+ *
+ *  1. A `state` NONCE. 20x's loopback accepts any POST to its receive route, so
+ *     anything able to reach 127.0.0.1 — including a page in the user's own
+ *     browser — can inject an attacker's tokens into the waiting app. Here the
+ *     nonce goes out in the redirect query, comes back with the tokens, and is
+ *     compared in constant time. A mismatch is refused.
+ *  2. NO `Access-Control-Allow-Origin: *`. 20x sets it; nothing needs it,
+ *     because the POST comes from the page this server itself served, which is
+ *     same-origin. Setting it invites exactly the injection the nonce blocks.
+ *
+ * ZERO RUNTIME DEPENDENCIES, like the rest of this package: node:http,
+ * node:crypto, node:readline and the global fetch. Adding a dependency here
+ * would break the sandbox install (see the package README).
+ */
+export interface BrowserEnrolOptions {
+    controlPlaneUrl: string;
+    runtime: string;
+    /** Overrides the origin derived from the control plane url. */
+    appUrl?: string;
+    /** Runner label; defaults to this machine's hostname. */
+    label?: string;
+    /** Injected in tests. */
+    fetchImpl?: typeof fetch;
+    /** Injected in tests; returns the chosen index. */
+    promptImpl?: (question: string) => Promise<string>;
+    /** Injected in tests, and skipped when a browser cannot be opened. */
+    openBrowser?: (url: string) => void;
+    log?: (message: string) => void;
+}
+export interface Company {
+    id: string;
+    name: string;
+    isPrimary?: boolean;
+}
+/**
+ * Where the browser-facing app lives, derived from the API url.
+ *
+ * THE SAME RULE 20x USES, and it must stay the same rule: loopback means the
+ * Next dev server on 4000, otherwise the `api` host maps to the `app` host.
+ * Getting this wrong sends the user to a page that cannot sign them in.
+ */
+export declare function deriveAppOrigin(controlPlaneUrl: string): string;
+/**
+ * Run the whole flow and return a single-use ENROLMENT TOKEN.
+ *
+ * The caller then enrols with it exactly as if it had been pasted in, so this
+ * function adds a way to OBTAIN the token and changes nothing about how a
+ * runner registers.
+ */
+export declare function enrolViaBrowser(options: BrowserEnrolOptions): Promise<string>;