@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/enrol/browser-enrol.js

@@ -0,0 +1,387 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveAppOrigin = deriveAppOrigin;
+exports.enrolViaBrowser = enrolViaBrowser;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const node_os_1 = require("node:os");
+const node_readline_1 = require("node:readline");
+/** Ports to try, deliberately NOT 20x's 48620-48640 so both can run at once. */
+const PORT_RANGE_START = 48660;
+const PORT_RANGE_END = 48680;
+/** How long a human gets to finish signing in. 20x uses ten minutes. */
+const LOGIN_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * 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.
+ */
+function deriveAppOrigin(controlPlaneUrl) {
+    const parsed = new URL(controlPlaneUrl);
+    if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
+        parsed.port = '4000';
+        return parsed.origin;
+    }
+    parsed.hostname = parsed.hostname
+        .replace('-api.', '-app.')
+        .replace(/^api\./, 'app.');
+    return parsed.origin;
+}
+/** Constant-time compare that cannot throw on a length mismatch. */
+function nonceMatches(expected, actual) {
+    if (typeof actual !== 'string')
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(actual);
+    if (a.length !== b.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * The page served at the callback. Reads the fragment, posts it back, and says
+ * something truthful to the human either way.
+ */
+const CALLBACK_PAGE = `<!doctype html>
+<html><head><meta charset="utf-8"><title>Peakflo runner</title>
+<style>
+ body{font:14px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+      display:flex;align-items:center;justify-content:center;height:100vh;margin:0;
+      background:#0b0b0c;color:#e6e6e6}
+ .card{text-align:center;max-width:28rem;padding:2rem}
+ h1{font-size:1.1rem;margin:0 0 .5rem}
+ p{color:#9a9a9a;margin:0}
+</style></head>
+<body><div class="card" id="c">
+  <h1>Connecting…</h1><p>One moment.</p>
+</div>
+<script>
+(function () {
+  var card = document.getElementById('c');
+  function show(title, detail) {
+    card.innerHTML = '<h1>' + title + '</h1><p>' + detail + '</p>';
+  }
+  var hash = new URLSearchParams((location.hash || '').replace(/^#/, ''));
+  var qs = new URLSearchParams(location.search);
+  var body = {
+    access_token: hash.get('access_token'),
+    refresh_token: hash.get('refresh_token'),
+    state: qs.get('state')
+  };
+  if (!body.access_token) {
+    show('No sign-in tokens found', 'Try starting the runner again.');
+    return;
+  }
+  fetch('/auth/receive-tokens', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body)
+  }).then(function (r) {
+    if (r.ok) {
+      show('Runner authorised', 'You can close this tab and return to the terminal.');
+    } else {
+      show('Authorisation refused', 'The terminal has the details.');
+    }
+    // Do not leave the tokens sitting in the address bar.
+    history.replaceState(null, '', location.pathname);
+  }).catch(function () {
+    show('Could not reach the runner', 'Is it still running?');
+  });
+})();
+</script></body></html>`;
+/**
+ * The loopback server. Serves the fragment-reading page, then receives the
+ * tokens that page POSTs back.
+ */
+class CallbackServer {
+    server = null;
+    port = 0;
+    state = (0, node_crypto_1.randomBytes)(24).toString('hex');
+    resolve = null;
+    reject = null;
+    async start() {
+        for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port += 1) {
+            try {
+                await this.listenOn(port);
+                this.port = port;
+                // The nonce rides in the QUERY, which `/auth/desktop-callback`
+                // preserves — it only ever replaces the fragment.
+                return `http://127.0.0.1:${port}/auth/callback?state=${this.state}`;
+            }
+            catch {
+                continue;
+            }
+        }
+        throw new Error(`No free port for the login callback in ${PORT_RANGE_START}-${PORT_RANGE_END}.`);
+    }
+    listenOn(port) {
+        return new Promise((resolve, reject) => {
+            const server = (0, node_http_1.createServer)((req, res) => {
+                this.handle(req.url ?? '/', req, res);
+            });
+            server.on('error', reject);
+            // 127.0.0.1, not 0.0.0.0: this must never be reachable off the machine.
+            server.listen(port, '127.0.0.1', () => {
+                this.server = server;
+                resolve();
+            });
+        });
+    }
+    handle(url, req, res) {
+        const parsed = new URL(url, `http://127.0.0.1:${this.port}`);
+        if (parsed.pathname === '/auth/callback') {
+            // The tokens are in the FRAGMENT, which never reached us. Serve a page
+            // that reads it and posts it back.
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(CALLBACK_PAGE);
+            return;
+        }
+        if (parsed.pathname === '/auth/receive-tokens' && req.method === 'POST') {
+            let body = '';
+            req.on('data', (chunk) => {
+                body += String(chunk);
+                // A runaway body must not exhaust memory on the user's laptop.
+                if (body.length > 64_000)
+                    req.destroy();
+            });
+            req.on('end', () => {
+                try {
+                    const payload = JSON.parse(body);
+                    if (!nonceMatches(this.state, payload.state)) {
+                        res.writeHead(403, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'state mismatch' }));
+                        return;
+                    }
+                    const accessToken = payload.access_token;
+                    const refreshToken = payload.refresh_token;
+                    if (typeof accessToken !== 'string' || accessToken.length === 0) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'no access token' }));
+                        return;
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true }));
+                    this.resolve?.({
+                        accessToken,
+                        refreshToken: typeof refreshToken === 'string' ? refreshToken : ''
+                    });
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'bad json' }));
+                }
+            });
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    }
+    wait(timeoutMs = LOGIN_TIMEOUT_MS) {
+        return new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+            const timer = setTimeout(() => {
+                reject(new Error('Timed out waiting for the browser sign-in. Run the command again, ' +
+                    'or pass --token if this machine has no browser.'));
+            }, timeoutMs);
+            // Never hold the process open on this timer alone.
+            timer.unref?.();
+        });
+    }
+    stop() {
+        this.server?.close();
+        this.server = null;
+        this.reject = null;
+    }
+}
+/** Best-effort browser open. A failure is not fatal: the url is printed too. */
+function defaultOpenBrowser(url) {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'cmd'
+            : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        const child = (0, node_child_process_1.spawn)(command, args, { stdio: 'ignore', detached: true });
+        // An ENOENT here must not take the process down; the printed url is the
+        // real contract and opening the browser is only a convenience.
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        /* printed url is the fallback */
+    }
+}
+function defaultPrompt(question) {
+    const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+async function postJson(fetchImpl, url, token, body) {
+    const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify(body ?? {})
+    });
+    const text = await response.text();
+    let json = {};
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        json = { raw: text };
+    }
+    // 2xx, NOT an exact code. The mint route answers 201 Created, and demanding
+    // 200 turned a SUCCESSFUL enrolment into "unknown error" after the user had
+    // already signed in and chosen an organisation.
+    return { status: response.status, ok: response.ok, json };
+}
+/**
+ * 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.
+ */
+async function enrolViaBrowser(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const log = options.log ?? ((m) => process.stdout.write(`${m}\n`));
+    const prompt = options.promptImpl ?? defaultPrompt;
+    const open = options.openBrowser ?? defaultOpenBrowser;
+    const appOrigin = options.appUrl
+        ? new URL(options.appUrl).origin
+        : deriveAppOrigin(options.controlPlaneUrl);
+    const server = new CallbackServer();
+    try {
+        const redirectUri = await server.start();
+        const loginUrl = `${appOrigin}/login?redirect_uri=${encodeURIComponent(redirectUri)}`;
+        log('');
+        log('  Authorise this runner by signing in:');
+        log(`      ${loginUrl}`);
+        log('');
+        log('  Waiting for the browser… (Ctrl-C to cancel)');
+        const waiting = server.wait();
+        open(loginUrl);
+        const tokens = await waiting;
+        log('  Signed in. Fetching your organisations…');
+        /* ---- Which organisations may this user use? ---------------------- */
+        const verify = await postJson(fetchImpl, `${options.controlPlaneUrl}/api/20x/auth/verify`, tokens.accessToken, {});
+        if (!verify.ok) {
+            throw new Error(`Could not read your account (${verify.status}): ${verify.json.message ??
+                verify.json.error ??
+                'unknown error'}`);
+        }
+        const companies = verify.json.companies ?? [];
+        if (companies.length === 0) {
+            throw new Error('Your account belongs to no organisation, so there is nothing to ' +
+                'enrol this runner into.');
+        }
+        /* ---- Choose one. Auto-select a sole org, exactly as 20x does. ----- */
+        let chosen;
+        if (companies.length === 1) {
+            chosen = companies[0];
+            log(`  Organisation: ${chosen.name}`);
+        }
+        else {
+            log('');
+            log('  Choose an organisation for this runner:');
+            companies.forEach((c, i) => {
+                log(`    ${i + 1}) ${c.name}${c.isPrimary ? '  (primary)' : ''}`);
+            });
+            log('');
+            const answer = (await prompt(`  Number [1-${companies.length}]: `)).trim();
+            const index = Number.parseInt(answer, 10) - 1;
+            if (!Number.isInteger(index) || index < 0 || index >= companies.length) {
+                throw new Error(`Not a valid choice: "${answer}"`);
+            }
+            chosen = companies[index];
+            log(`  Organisation: ${chosen.name}`);
+        }
+        /* ---- Exchange for a pf-workflo JWT scoped to that org ------------- */
+        const selected = await postJson(fetchImpl, `${options.controlPlaneUrl}/api/20x/auth/select-tenant`, tokens.accessToken, { tenantId: chosen.id });
+        if (!selected.ok || typeof selected.json.token !== 'string') {
+            throw new Error(`Could not select "${chosen.name}" (${selected.status}): ${selected.json.message ??
+                selected.json.error ??
+                'unknown error'}`);
+        }
+        /* ---- Mint the ordinary single-use enrolment token ----------------- */
+        const minted = await postJson(fetchImpl, `${options.controlPlaneUrl}/api/coding-agents/runners/enrolment-tokens`, selected.json.token, { runtime: options.runtime, label: options.label ?? (0, node_os_1.hostname)() });
+        if (minted.status === 403) {
+            // Worth naming precisely: this is the SAME permission that gates minting
+            // a token by hand, and the flow deliberately does not lower it.
+            throw new Error(`You do not have permission to add a runner to "${chosen.name}". ` +
+                'Adding one needs the coding-agents:manage permission — ask an ' +
+                'administrator, or have them mint a token and pass --token.');
+        }
+        if (!minted.ok || typeof minted.json.enrolmentToken !== 'string') {
+            throw new Error(`Could not mint an enrolment token (${minted.status}): ${minted.json.message ??
+                minted.json.error ??
+                'unknown error'}`);
+        }
+        log('  Authorised.');
+        log('');
+        return minted.json.enrolmentToken;
+    }
+    finally {
+        server.stop();
+    }
+}

package/dist/github-command-guards.d.ts

@@ -0,0 +1,20 @@
+export declare const MERGE_REFUSAL = "GitHub merge refused: agents may open pull requests but must not merge them.";
+interface GuardPathLease {
+    bin: string;
+    release(): void;
+}
+/**
+ * Install friendly command-line refusals before backend processes start.
+ * These launchers are UX only. The TLS proxy is the security boundary and
+ * applies the same policy even when an agent calls the real binary directly.
+ */
+export declare function installGhGuard(root: string): Promise<string>;
+/**
+ * Lease one session-neutral guard directory for the whole process. Generated
+ * launchers read policy from the target worktree, so sharing the launcher is
+ * safe; stacking per-Harness directories in global PATH is not.
+ */
+export declare function acquireGhGuardPath(root: string): Promise<GuardPathLease>;
+/** Git supplies resolved destination refs, covering force, wildcard and implicit pushes. */
+export declare function installPushGuard(directory: string, sessionId: string, defaultBranch: string, remoteUrl: string): Promise<void>;
+export {};