@peakflo/agent-harness 0.2.11-rc.3 → 0.2.11-rc.4

package/dist/runtime/loopback-peer.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Who is on the other end of a loopback TCP connection?
+ *
+ * Inside the sandbox every chat's Chromium runs as its own Unix user, and the
+ * uids are drawn from this range — keep it in step with UID_MIN / UID_MAX in
+ * packages/agentSandbox/browser-broker/os-users.mjs. Chromium runs with
+ * --no-sandbox and uses the sandbox network directly (no egress proxy, no
+ * firewall), so a page — or a COMPROMISED renderer — can open a socket to
+ * 127.0.0.1. The harness loopback services therefore refuse browser uids: a
+ * loopback server that should say nothing to a browser asks `peerUid()` and
+ * refuses uids in this range.
+ */
+export declare const BROWSER_UID_MIN = 20000;
+export declare const BROWSER_UID_MAX = 29999;
+export declare function isBrowserUid(uid: number | null): boolean;
+/** The parts of a `net.Socket` the lookup needs (server side of the connection). */
+export interface LoopbackSocket {
+    remoteAddress?: string;
+    remotePort?: number;
+    localPort?: number;
+}
+export interface PeerUidOptions {
+    /** Defaults to `process.platform`; anything but 'linux' answers null. */
+    platform?: NodeJS.Platform;
+    /** Defaults to a sync read; injected by tests with fake /proc content. */
+    readFile?: (path: string) => string;
+    /** Byte order of the /proc address words. Defaults to `os.endianness()`. */
+    endianness?: 'LE' | 'BE';
+}
+export interface ProcNetTcpEntry {
+    localAddress: string;
+    localPort: number;
+    remoteAddress: string;
+    remotePort: number;
+    uid: number;
+}
+/**
+ * One spelling per address: dotted IPv4 for IPv4 and IPv4-mapped IPv6
+ * ('::ffff:127.0.0.1' -> '127.0.0.1'), 32 lowercase hex digits otherwise.
+ * Null for anything unparseable.
+ */
+export declare function canonicalAddress(address: string): string | null;
+/**
+ * Parse /proc/net/tcp or /proc/net/tcp6. Addresses come back canonical (see
+ * `canonicalAddress`), so an IPv4-mapped IPv6 row compares equal to its IPv4
+ * form. Malformed rows are skipped.
+ */
+export declare function parseProcNetTcp(text: string, ipv6: boolean, order?: 'LE' | 'BE'): ProcNetTcpEntry[];
+/**
+ * The owner uid of the CLIENT socket of an accepted loopback connection, or
+ * null when it cannot be told (not Linux, /proc unreadable, no matching row).
+ *
+ * Both ends of a loopback connection live in the same network namespace, so
+ * /proc/net/tcp{,6} lists the client's socket too: the row whose LOCAL
+ * address:port is our peer's address:port and whose REMOTE port is our own
+ * port. Its `uid` column is the uid that created that socket. The server's own
+ * accepted socket is the mirror row (local port = our port) and never matches.
+ *
+ * Synchronous and cheap enough for low-rate endpoints: two small file reads.
+ */
+export declare function peerUid(socket: LoopbackSocket, options?: PeerUidOptions): number | null;
+/** Resolves a connection's peer uid; null when unknown. Injected by tests. */
+export type PeerUidResolver = (socket: LoopbackSocket) => number | null;
+/** The body every guarded server sends a browser peer: nothing else. */
+export declare const FORBIDDEN_BODY: string;
+/** The minimum a `BrowserPeerGuard` needs from an http/net server. */
+interface ConnectionEmitter {
+    on(event: 'connection', listener: (socket: LoopbackSocket) => void): unknown;
+}
+/** The minimum a `BrowserPeerGuard` needs from an http response. */
+interface ForbiddableResponse {
+    writeHead(status: number, headers: Record<string, string>): unknown;
+    end(body: string): unknown;
+}
+/**
+ * Per-CONNECTION browser-uid guard for a busier loopback server (the MCP auth
+ * proxy, the knowledge host): the /proc lookup runs once when a connection is
+ * accepted and is cached on that socket, so keep-alive and streaming traffic
+ * pays nothing per request. A confirmed browser uid gets a bare 403 on every
+ * request of the connection; an unknown uid (non-Linux, /proc unreadable, a
+ * resolver that throws) is let through, for the same reason as the health
+ * check: the legitimate callers run as pfharness or root, and failing closed
+ * would turn a /proc hiccup into broken MCP tools.
+ */
+export declare class BrowserPeerGuard {
+    private readonly resolve;
+    private readonly uids;
+    constructor(resolve?: PeerUidResolver);
+    /** Look up every new connection's peer uid as it is accepted. */
+    attach(server: ConnectionEmitter): void;
+    /** True for a CONFIRMED browser peer. Looks up lazily if `attach` missed it. */
+    isBrowser(socket: LoopbackSocket): boolean;
+    /** Answer a browser peer with 403 and return true; otherwise return false. */
+    refuse(socket: LoopbackSocket, res: ForbiddableResponse): boolean;
+    private lookup;
+}
+export {};

package/dist/runtime/loopback-peer.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserPeerGuard = exports.FORBIDDEN_BODY = exports.BROWSER_UID_MAX = exports.BROWSER_UID_MIN = void 0;
+exports.isBrowserUid = isBrowserUid;
+exports.canonicalAddress = canonicalAddress;
+exports.parseProcNetTcp = parseProcNetTcp;
+exports.peerUid = peerUid;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+/**
+ * Who is on the other end of a loopback TCP connection?
+ *
+ * Inside the sandbox every chat's Chromium runs as its own Unix user, and the
+ * uids are drawn from this range — keep it in step with UID_MIN / UID_MAX in
+ * packages/agentSandbox/browser-broker/os-users.mjs. Chromium runs with
+ * --no-sandbox and uses the sandbox network directly (no egress proxy, no
+ * firewall), so a page — or a COMPROMISED renderer — can open a socket to
+ * 127.0.0.1. The harness loopback services therefore refuse browser uids: a
+ * loopback server that should say nothing to a browser asks `peerUid()` and
+ * refuses uids in this range.
+ */
+exports.BROWSER_UID_MIN = 20000;
+exports.BROWSER_UID_MAX = 29999;
+function isBrowserUid(uid) {
+    return uid !== null && uid >= exports.BROWSER_UID_MIN && uid <= exports.BROWSER_UID_MAX;
+}
+const PROC_FILES = [
+    { path: '/proc/net/tcp', ipv6: false },
+    { path: '/proc/net/tcp6', ipv6: true }
+];
+function parseIpv4(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4) {
+        return null;
+    }
+    const bytes = parts.map((p) => (/^\d{1,3}$/.test(p) ? Number(p) : NaN));
+    return bytes.every((b) => b >= 0 && b <= 255) ? bytes : null;
+}
+function parseIpv6(address) {
+    let text = address.split('%')[0]; // drop a zone id
+    const groups = [];
+    // A trailing dotted quad ('::ffff:1.2.3.4') is two 16-bit groups.
+    const lastColon = text.lastIndexOf(':');
+    const tail = parseIpv4(text.slice(lastColon + 1));
+    if (tail) {
+        text = `${text.slice(0, lastColon + 1)}${((tail[0] << 8) | tail[1]).toString(16)}:${((tail[2] << 8) | tail[3]).toString(16)}`;
+    }
+    const halves = text.split('::');
+    if (halves.length > 2) {
+        return null;
+    }
+    const parse = (part) => {
+        if (part === '') {
+            return [];
+        }
+        const out = [];
+        for (const g of part.split(':')) {
+            if (!/^[0-9A-Fa-f]{1,4}$/.test(g)) {
+                return null;
+            }
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    const head = parse(halves[0]);
+    const rest = halves.length === 2 ? parse(halves[1]) : [];
+    if (!head || !rest) {
+        return null;
+    }
+    const missing = 8 - head.length - rest.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0) {
+        return null;
+    }
+    groups.push(...head, ...new Array(missing).fill(0), ...rest);
+    const bytes = Buffer.alloc(16);
+    groups.forEach((g, i) => bytes.writeUInt16BE(g, i * 2));
+    return bytes;
+}
+function canonicalBytes(bytes) {
+    if (bytes.length === 4) {
+        return Array.from(bytes).join('.');
+    }
+    const mapped = bytes.subarray(0, 10).every((b) => b === 0) &&
+        bytes[10] === 0xff &&
+        bytes[11] === 0xff;
+    return mapped
+        ? Array.from(bytes.subarray(12)).join('.')
+        : bytes.toString('hex');
+}
+/**
+ * One spelling per address: dotted IPv4 for IPv4 and IPv4-mapped IPv6
+ * ('::ffff:127.0.0.1' -> '127.0.0.1'), 32 lowercase hex digits otherwise.
+ * Null for anything unparseable.
+ */
+function canonicalAddress(address) {
+    const v4 = parseIpv4(address);
+    if (v4) {
+        return v4.join('.');
+    }
+    const v6 = parseIpv6(address);
+    return v6 ? canonicalBytes(v6) : null;
+}
+/** "0100007F:1E61" -> { address: '127.0.0.1', port: 7777 } on little-endian. */
+function parseProcEndpoint(value, ipv6, order) {
+    const [hex, portHex] = value.split(':');
+    const width = ipv6 ? 32 : 8;
+    if (!hex ||
+        !portHex ||
+        hex.length !== width ||
+        !/^[0-9A-Fa-f]+$/.test(hex) ||
+        !/^[0-9A-Fa-f]{4}$/.test(portHex)) {
+        return null;
+    }
+    // The kernel prints each 32-bit word of the address in host byte order.
+    const bytes = Buffer.from(hex, 'hex');
+    if (order === 'LE') {
+        for (let i = 0; i < bytes.length; i += 4) {
+            bytes.subarray(i, i + 4).reverse();
+        }
+    }
+    return { address: canonicalBytes(bytes), port: parseInt(portHex, 16) };
+}
+/**
+ * Parse /proc/net/tcp or /proc/net/tcp6. Addresses come back canonical (see
+ * `canonicalAddress`), so an IPv4-mapped IPv6 row compares equal to its IPv4
+ * form. Malformed rows are skipped.
+ */
+function parseProcNetTcp(text, ipv6, order = (0, node_os_1.endianness)()) {
+    const entries = [];
+    for (const line of text.split('\n').slice(1)) {
+        // sl local_address rem_address st tx:rx tr:when retrnsmt uid ...
+        const cols = line.trim().split(/\s+/);
+        if (cols.length < 8) {
+            continue;
+        }
+        const local = parseProcEndpoint(cols[1], ipv6, order);
+        const remote = parseProcEndpoint(cols[2], ipv6, order);
+        const uid = Number(cols[7]);
+        if (!local || !remote || !Number.isInteger(uid)) {
+            continue;
+        }
+        entries.push({
+            localAddress: local.address,
+            localPort: local.port,
+            remoteAddress: remote.address,
+            remotePort: remote.port,
+            uid
+        });
+    }
+    return entries;
+}
+/**
+ * The owner uid of the CLIENT socket of an accepted loopback connection, or
+ * null when it cannot be told (not Linux, /proc unreadable, no matching row).
+ *
+ * Both ends of a loopback connection live in the same network namespace, so
+ * /proc/net/tcp{,6} lists the client's socket too: the row whose LOCAL
+ * address:port is our peer's address:port and whose REMOTE port is our own
+ * port. Its `uid` column is the uid that created that socket. The server's own
+ * accepted socket is the mirror row (local port = our port) and never matches.
+ *
+ * Synchronous and cheap enough for low-rate endpoints: two small file reads.
+ */
+function peerUid(socket, options = {}) {
+    if ((options.platform ?? process.platform) !== 'linux') {
+        return null;
+    }
+    const { remoteAddress, remotePort, localPort } = socket;
+    if (!remoteAddress || !remotePort || !localPort) {
+        return null;
+    }
+    const peer = canonicalAddress(remoteAddress);
+    if (!peer) {
+        return null;
+    }
+    const read = options.readFile ?? ((path) => (0, node_fs_1.readFileSync)(path, 'utf8'));
+    const order = options.endianness ?? (0, node_os_1.endianness)();
+    for (const file of PROC_FILES) {
+        let text;
+        try {
+            text = read(file.path);
+        }
+        catch {
+            continue; // e.g. no IPv6 in the kernel: the other file may still match
+        }
+        for (const entry of parseProcNetTcp(text, file.ipv6, order)) {
+            if (entry.localPort === remotePort &&
+                entry.remotePort === localPort &&
+                entry.localAddress === peer) {
+                return entry.uid;
+            }
+        }
+    }
+    return null;
+}
+/** The body every guarded server sends a browser peer: nothing else. */
+exports.FORBIDDEN_BODY = JSON.stringify({ error: 'forbidden' });
+/**
+ * Per-CONNECTION browser-uid guard for a busier loopback server (the MCP auth
+ * proxy, the knowledge host): the /proc lookup runs once when a connection is
+ * accepted and is cached on that socket, so keep-alive and streaming traffic
+ * pays nothing per request. A confirmed browser uid gets a bare 403 on every
+ * request of the connection; an unknown uid (non-Linux, /proc unreadable, a
+ * resolver that throws) is let through, for the same reason as the health
+ * check: the legitimate callers run as pfharness or root, and failing closed
+ * would turn a /proc hiccup into broken MCP tools.
+ */
+class BrowserPeerGuard {
+    resolve;
+    uids = new WeakMap();
+    constructor(resolve = (socket) => peerUid(socket)) {
+        this.resolve = resolve;
+    }
+    /** Look up every new connection's peer uid as it is accepted. */
+    attach(server) {
+        server.on('connection', (socket) => {
+            this.uids.set(socket, this.lookup(socket));
+        });
+    }
+    /** True for a CONFIRMED browser peer. Looks up lazily if `attach` missed it. */
+    isBrowser(socket) {
+        if (!this.uids.has(socket)) {
+            this.uids.set(socket, this.lookup(socket));
+        }
+        return isBrowserUid(this.uids.get(socket) ?? null);
+    }
+    /** Answer a browser peer with 403 and return true; otherwise return false. */
+    refuse(socket, res) {
+        if (!this.isBrowser(socket)) {
+            return false;
+        }
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(exports.FORBIDDEN_BODY);
+        return true;
+    }
+    lookup(socket) {
+        try {
+            return this.resolve(socket);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.BrowserPeerGuard = BrowserPeerGuard;

package/dist/runtime/mcp-auth-proxy.d.ts

@@ -35,13 +35,78 @@
  * from the network and does not weaken it. Binding 0.0.0.0 here WOULD, and the
  * test suite asserts the bind address.
  */
+import { type Server as HttpServer } from 'node:http';
 import { Notifier, TokenInjector } from '../ports';
+import { type PeerUidResolver } from './loopback-peer';
+/** Largest agent request body the browser hold buffers to re-send. */
+export declare const BROWSER_HOLD_MAX_BODY_BYTES: number;
+/** Consecutive upstream failures (network/5xx) a hold tolerates. */
+export declare const BROWSER_HOLD_MAX_FAILURES = 10;
+/**
+ * Longest a held re-send may wait for response headers before it counts as a
+ * transient upstream failure. The gateway holds one await-handback request
+ * for 20 s; after a handback it runs the call (a broker command is at most
+ * ~65 s), so this only fires for a gateway that has silently gone away — a
+ * hung socket would otherwise park Pi until its 24 h MCP timeout.
+ */
+export declare const BROWSER_HOLD_ATTEMPT_TIMEOUT_MS = 180000;
+export type BrowserPauseEndReason = 
+/** The gateway answered something other than a takeover 409. */
+'resolved'
+/** Pi closed the request. */
+ | 'client_closed'
+/** `cancelBrowserHolds`, `stop()`, or the start hook refused the hold. */
+ | 'cancelled'
+/** Too many consecutive upstream failures; Pi got a JSON-RPC error. */
+ | 'failed';
+export type BrowserPauseEvent = 
+/** `body` is the gateway's `BrowserTakeoverBody` (parsed JSON, or text). */
+{
+    state: 'start';
+    body: unknown;
+} | {
+    state: 'end';
+    reason: BrowserPauseEndReason;
+};
+/**
+ * Called once when a browser call starts being held and once when the hold
+ * ends. Returning `false` from the `start` event refuses the hold (no live
+ * turn for that session): the call is answered with a JSON-RPC error instead.
+ */
+export type BrowserPauseHook = (targetUrl: string, event: BrowserPauseEvent) => boolean | void;
 export interface McpAuthProxyOptions {
     tokens: TokenInjector;
     notifier?: Notifier;
     /** Injected in tests. Defaults to console. */
     logger?: Pick<Console, 'warn' | 'error' | 'log'>;
+    /** Browser takeover hold start/end. See `handleBrowserRequest`. */
+    onBrowserPause?: BrowserPauseHook;
+    /** Injected in tests: delay between hold attempts. Defaults to jittered. */
+    browserHoldBackoffMs?: (attempt: number, failures: number) => number;
+    /** Injected in tests. Defaults to `BROWSER_HOLD_ATTEMPT_TIMEOUT_MS`. */
+    browserHoldAttemptTimeoutMs?: number;
+    /**
+     * Injected in tests. Defaults to the /proc/net/tcp lookup; a chat browser
+     * uid gets 403 on every request of its connection. See `BrowserPeerGuard`.
+     */
+    peerUid?: PeerUidResolver;
+    /**
+     * Loopback port to listen on. 0 (the default, desktop) is ephemeral. A
+     * sandbox pins it (PF_MCP_PROXY_PORT) so the chat browser's Landlock rule
+     * can deny it by number. See `listenLoopback`.
+     */
+    port?: number;
 }
+/**
+ * Listen on 127.0.0.1:`port` (0 = ephemeral). When a FIXED port is taken the
+ * listener falls back to an ephemeral one and says so loudly, rather than
+ * failing the harness start: the per-uid `BrowserPeerGuard` still refuses a
+ * chat browser on any port, and the fixed number only feeds a defence-in-depth
+ * deny rule. Resolves with the bound port.
+ */
+export declare function listenLoopback(server: HttpServer, port: number, logger: Pick<Console, 'warn'>, label: string): Promise<number>;
+/** A fixed loopback port from the environment, or 0 (ephemeral) when unset or invalid. */
+export declare function loopbackPortFromEnv(value: string | undefined): number;
 export declare class McpAuthProxy {
     private readonly options;
     private server;
@@ -52,6 +117,10 @@ export declare class McpAuthProxy {
     /** One notification per integration per process, not one per failed call. */
     private readonly notifiedFailures;
     private readonly logger;
+    /** Browser calls held during a takeover. Cancelled on `stop()`. */
+    private readonly browserHolds;
+    /** Chat browsers run as their own uids; they get nothing from this proxy. */
+    private readonly peerGuard;
     constructor(options: McpAuthProxyOptions);
     getPort(): number | null;
     /**
@@ -67,8 +136,40 @@ export declare class McpAuthProxy {
     registerTarget(targetUrl: string, label?: string): string | null;
     unregisterTarget(proxyUrl: string): void;
     start(): Promise<number>;
+    /**
+     * Cancel every held browser call whose gateway URL starts with
+     * `targetUrlPrefix` (a full target URL, or `.../api/mcp/agent/<sessionId>/`
+     * for a whole session). Held calls are answered with a JSON-RPC error and
+     * the hook gets `end` / `cancelled`. Returns how many were cancelled.
+     */
+    cancelBrowserHolds(targetUrlPrefix: string): number;
+    /** Number of browser calls currently held. For tests and diagnostics. */
+    activeBrowserHolds(): number;
     stop(): Promise<void>;
     private handleRequest;
+    /**
+     * THE BROWSER TAKEOVER HOLD (sandbox browser). Only for the built-in
+     * `pf-browser` gateway server; every other target takes the plain streaming
+     * path above, unchanged.
+     *
+     * While a person controls the chat browser, the gateway answers a waiting
+     * browser tool with 409 + `x-pf-browser-takeover`. That answer is NOT handed
+     * to Pi: the agent's call stays open (Pi's timeout for this server is 24 h)
+     * and the SAME body is re-sent with `x-pf-browser-await-handback: 1` — each
+     * with a fresh token — until the gateway answers anything else (it holds
+     * each such request up to 20 s and, after a handback, rewrites the call into
+     * a fresh snapshot). That answer is streamed back to Pi unchanged. The turn
+     * is never aborted; the SessionRunner counts the time as an intentional
+     * pause through `onBrowserPause`.
+     */
+    private handleBrowserRequest;
+    private holdBackoffMs;
+    private callBrowserHook;
+    /**
+     * One upstream request with a buffered body and a fresh token. With
+     * `headersTimeoutMs`, no response headers by then is an error outcome.
+     */
+    private sendBuffered;
     /**
      * One notification per TARGET per process — keyed on the target id, not on
      * the human-readable label.