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

package/dist/github-proxy.js

@@ -0,0 +1,476 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubTlsProxy = void 0;
+exports.parseReceivePackCommands = parseReceivePackCommands;
+exports.receivePackRefusal = receivePackRefusal;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const node_net_1 = require("node:net");
+const node_tls_1 = require("node:tls");
+const child_stream_guards_1 = require("./runtime/child-stream-guards");
+const INTERCEPTED_HOSTS = new Set(['github.com', 'api.github.com']);
+const PASS_THROUGH_HOSTS = new Set([
+    'objects.githubusercontent.com',
+    'codeload.github.com'
+]);
+const ALLOWED_HOSTS = new Set([...INTERCEPTED_HOSTS, ...PASS_THROUGH_HOSTS]);
+const GRAPHQL_REFUSED_MUTATIONS = [
+    'mergePullRequest',
+    'enablePullRequestAutoMerge',
+    'deleteRepository',
+    'updateBranchProtectionRule',
+    'createBranchProtectionRule'
+];
+const ZERO_OID = /^0+$/;
+const MAX_INSPECTED_BODY_BYTES = 16 * 1024 * 1024;
+const MAX_RECEIVE_PACK_COMMAND_BYTES = 64 * 1024;
+function receivePackCommandLength(body) {
+    let offset = 0;
+    while (offset + 4 <= body.length) {
+        const lengthText = body.subarray(offset, offset + 4).toString('ascii');
+        if (!/^[0-9a-f]{4}$/i.test(lengthText)) {
+            throw new Error('Invalid git receive-pack pkt-line length.');
+        }
+        const length = Number.parseInt(lengthText, 16);
+        if (length === 0)
+            return offset + 4;
+        if (length < 4)
+            throw new Error('Invalid git receive-pack pkt-line length.');
+        if (offset + length > body.length)
+            return null;
+        offset += length;
+    }
+    return null;
+}
+function safeEquals(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+function parseReceivePackCommands(body) {
+    const commands = [];
+    let offset = 0;
+    while (offset + 4 <= body.length) {
+        const lengthText = body.subarray(offset, offset + 4).toString('ascii');
+        if (!/^[0-9a-f]{4}$/i.test(lengthText)) {
+            throw new Error('Invalid git receive-pack pkt-line length.');
+        }
+        const length = Number.parseInt(lengthText, 16);
+        if (length === 0)
+            return commands;
+        if (length < 4 || offset + length > body.length) {
+            throw new Error('Incomplete git receive-pack pkt-line.');
+        }
+        const payload = body
+            .subarray(offset + 4, offset + length)
+            .toString('utf8')
+            .replace(/\n$/, '');
+        const command = payload.split('\0', 1)[0];
+        const match = command.match(/^([0-9a-f]+) ([0-9a-f]+) ([^\s]+)$/i);
+        if (!match)
+            throw new Error('Invalid git receive-pack ref update.');
+        commands.push({ oldOid: match[1], newOid: match[2], ref: match[3] });
+        offset += length;
+    }
+    throw new Error('Incomplete git receive-pack command list.');
+}
+function receivePackRefusal(body, sessionId) {
+    let commands;
+    try {
+        commands = parseReceivePackCommands(body);
+    }
+    catch {
+        return 'Git push refused: the receive-pack command list is malformed.';
+    }
+    if (commands.length === 0) {
+        return 'Git push refused: the receive-pack command list is empty.';
+    }
+    const allowed = `refs/heads/agent/${sessionId}`;
+    for (const command of commands) {
+        if (ZERO_OID.test(command.newOid)) {
+            return `Git push refused: deleting ${command.ref} is not permitted.`;
+        }
+        if (command.ref !== allowed) {
+            return `Git push refused: this session may update only ${allowed}.`;
+        }
+    }
+    return null;
+}
+function decodedPath(request) {
+    try {
+        return decodeURIComponent(new URL(request.url ?? '/', 'https://x').pathname);
+    }
+    catch {
+        return null;
+    }
+}
+function repositoryFromPath(hostname, path) {
+    const match = hostname === 'api.github.com'
+        ? path.match(/^\/repos\/([^/]+)\/([^/]+)(?:\/|$)/)
+        : path.match(/^\/([^/]+)\/([^/]+?)\.git(?:\/|$)/);
+    return match ? `${match[1]}/${match[2]}` : null;
+}
+function restRefusal(method, path) {
+    if (/^\/repos\/[^/]+\/[^/]+\/pulls\/[^/]+\/merge\/?$/i.test(path))
+        return 'GitHub request refused: pull requests must be merged by a human.';
+    if (/^\/repos\/[^/]+\/[^/]+\/merges\/?$/i.test(path))
+        return 'GitHub request refused: merge commits are not permitted.';
+    if (method === 'DELETE' && /^\/repos\/[^/]+\/[^/]+\/?$/i.test(path))
+        return 'GitHub request refused: repository deletion is not permitted.';
+    const forbidden = [
+        /\/actions\/secrets(?:\/|$)/i,
+        /\/actions\/workflows\/[^/]+\/dispatches\/?$/i,
+        /\/rulesets(?:\/|$)/i,
+        /\/branches\/[^/]+\/protection(?:\/|$)/i,
+        /\/hooks(?:\/|$)/i,
+        /\/keys(?:\/|$)/i,
+        /\/collaborators(?:\/|$)/i,
+        /\/deployments(?:\/|$)/i,
+        /\/codespaces(?:\/|$)/i
+    ];
+    return forbidden.some((pattern) => pattern.test(path))
+        ? 'GitHub request refused: this administrative operation is not permitted.'
+        : null;
+}
+function bearerSentinel(header) {
+    const value = Array.isArray(header) ? header[0] : header;
+    return (value?.match(/^\s*(?:token|Bearer)\s+(pfgh_[A-Za-z0-9_-]+)\s*$/i)?.[1] ??
+        null);
+}
+function basicSentinel(header) {
+    const value = Array.isArray(header) ? header[0] : header;
+    const encoded = value?.match(/^\s*Basic\s+([^\s]+)\s*$/i)?.[1];
+    if (!encoded)
+        return null;
+    try {
+        const decoded = Buffer.from(encoded, 'base64').toString('utf8');
+        const separator = decoded.indexOf(':');
+        return decoded.slice(0, separator) === 'x-access-token'
+            ? decoded.slice(separator + 1)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function graphQLPolicyText(body) {
+    const raw = body.toString('utf8');
+    const forms = [raw];
+    try {
+        forms.push(JSON.stringify(JSON.parse(raw)));
+    }
+    catch {
+        /* gh uses JSON; retain the raw form for other valid GitHub clients. */
+    }
+    try {
+        forms.push(decodeURIComponent(raw.replace(/\+/g, ' ')));
+    }
+    catch {
+        /* A malformed percent escape remains visible in the raw form. */
+    }
+    return forms.join('\n');
+}
+function forwardedHeaders(headers) {
+    const copy = { ...headers };
+    for (const name of [
+        'authorization',
+        'proxy-authorization',
+        'proxy-connection',
+        'connection',
+        'keep-alive',
+        'transfer-encoding',
+        'upgrade'
+    ]) {
+        delete copy[name];
+    }
+    return copy;
+}
+async function readBody(request) {
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        length += buffer.length;
+        if (length > MAX_INSPECTED_BODY_BYTES) {
+            throw new Error('GitHub request body is too large for policy inspection.');
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+async function readReceivePackPrefix(request) {
+    return new Promise((resolvePromise, reject) => {
+        let buffered = Buffer.alloc(0);
+        function cleanup() {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            request.off('data', onData);
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            request.off('end', onEnd);
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            request.off('error', onError);
+        }
+        function onError(error) {
+            cleanup();
+            reject(error);
+        }
+        function onEnd() {
+            cleanup();
+            reject(new Error('Incomplete git receive-pack command list.'));
+        }
+        function onData(chunk) {
+            request.pause();
+            buffered = Buffer.concat([buffered, Buffer.from(chunk)]);
+            if (buffered.length > MAX_RECEIVE_PACK_COMMAND_BYTES) {
+                cleanup();
+                reject(new Error('Git receive-pack command list is too large.'));
+                return;
+            }
+            try {
+                const length = receivePackCommandLength(buffered);
+                if (length === null) {
+                    request.resume();
+                    return;
+                }
+                cleanup();
+                const remainder = buffered.subarray(length);
+                if (remainder.length > 0)
+                    request.unshift(remainder);
+                resolvePromise(buffered.subarray(0, length));
+            }
+            catch (error) {
+                cleanup();
+                reject(error);
+            }
+        }
+        request.on('data', onData);
+        request.once('end', onEnd);
+        request.once('error', onError);
+        request.resume();
+    });
+}
+function reply(response, status, message, basicChallenge = false) {
+    response.writeHead(status, {
+        'content-type': 'text/plain; charset=utf-8',
+        'cache-control': 'no-store',
+        ...(basicChallenge ? { 'www-authenticate': 'Basic realm="GitHub"' } : {})
+    });
+    response.end(`${message}\n`);
+}
+class GitHubTlsProxy {
+    listener;
+    options;
+    tunneled = (0, node_http_1.createServer)((request, response) => {
+        void this.handle(request, response);
+    });
+    constructor(listener, options) {
+        this.listener = listener;
+        this.options = options;
+        listener.on('connect', (request, socket, head) => {
+            // A refused CONNECT commonly makes the client reset the TCP connection
+            // after it receives our 403. Without an error listener Node promotes that
+            // routine ECONNRESET into an uncaught exception and kills the whole
+            // harness. Install the guard before the first await/write in connect(),
+            // including for targets outside the GitHub allowlist.
+            (0, child_stream_guards_1.guardStream)(socket, 'GitHubProxy/connect');
+            void this.connect(request, socket, head);
+        });
+    }
+    refused(sessionId, kind, path, response, reason) {
+        this.logRefusal(sessionId, kind, path);
+        reply(response, 403, reason);
+    }
+    logRefusal(sessionId, kind, path) {
+        (this.options.logger ?? console).warn(`[coding-agents] github-proxy-refused sessionId=${sessionId} kind=${kind} path=${JSON.stringify(path)}`);
+    }
+    async connect(request, socket, head) {
+        const target = request.url ?? '';
+        const match = target.match(/^([^:]+):(\d+)$/);
+        const hostname = match?.[1]?.toLowerCase() ?? '';
+        if (match?.[2] === '443' && this.options.isDirectHostAllowed?.(hostname)) {
+            this.connectDirect(hostname, 443, socket, head);
+            return;
+        }
+        if (!match || match[2] !== '443' || !ALLOWED_HOSTS.has(hostname)) {
+            this.logRefusal('unknown', 'connect-target', target);
+            socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+            return;
+        }
+        try {
+            const leaf = await this.options.certificates.leaf(hostname);
+            const tlsServer = (0, node_tls_1.createServer)({
+                key: leaf.privateKey,
+                cert: leaf.certificate
+            });
+            tlsServer.once('secureConnection', (tlsSocket) => {
+                tlsSocket.pfGithubHost =
+                    hostname;
+                this.tunneled.emit('connection', tlsSocket);
+            });
+            tlsServer.once('tlsClientError', () => socket.destroy());
+            socket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+            if (head.length > 0)
+                socket.unshift(head);
+            tlsServer.emit('connection', socket);
+        }
+        catch {
+            socket.end('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n');
+        }
+    }
+    connectDirect(hostname, port, socket, head) {
+        // Some clients do not consistently honor NO_PROXY. Tunnel only the exact
+        // server-configured direct hosts so their public TLS certificate remains
+        // end-to-end, while GitHub traffic continues through policy inspection.
+        const upstream = (this.options.connectDirect ??
+            ((host, targetPort) => (0, node_net_1.connect)(targetPort, host)))(hostname, port);
+        (0, child_stream_guards_1.guardStream)(upstream, 'GitHubProxy/direct-upstream');
+        let connected = false;
+        upstream.once('connect', () => {
+            connected = true;
+            socket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+            if (head.length > 0)
+                upstream.write(head);
+            socket.pipe(upstream);
+            upstream.pipe(socket);
+        });
+        upstream.once('error', () => {
+            if (!connected) {
+                socket.end('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n');
+            }
+            else {
+                socket.destroy();
+            }
+        });
+        socket.once('close', () => upstream.destroy());
+        upstream.once('close', () => socket.destroy());
+    }
+    async handle(request, response) {
+        const hostname = request.socket
+            .pfGithubHost;
+        if (!hostname || !ALLOWED_HOSTS.has(hostname)) {
+            this.logRefusal('unknown', 'tunnel-target', hostname ?? 'unknown');
+            reply(response, 403, 'GitHub proxy target is not permitted.');
+            return;
+        }
+        const path = decodedPath(request);
+        if (!path) {
+            reply(response, 400, 'Malformed GitHub request path.');
+            return;
+        }
+        if (PASS_THROUGH_HOSTS.has(hostname)) {
+            this.forward(hostname, request, response, Buffer.alloc(0), undefined);
+            return;
+        }
+        const gitRequest = hostname === 'github.com' &&
+            /\.git\/(?:info\/refs|git-upload-pack|git-receive-pack)$/i.test(path);
+        const sentinel = gitRequest
+            ? basicSentinel(request.headers.authorization)
+            : bearerSentinel(request.headers.authorization);
+        if (!sentinel) {
+            this.logRefusal('unknown', 'missing-sentinel', path);
+            reply(response, 401, 'GitHub session sentinel is required.', gitRequest);
+            return;
+        }
+        const session = this.options.findSession(sentinel);
+        if (!session || !safeEquals(session.sentinel, sentinel)) {
+            this.logRefusal('unknown', 'invalid-sentinel', path);
+            reply(response, 403, 'GitHub session sentinel is invalid.');
+            return;
+        }
+        if (hostname === 'github.com' && !gitRequest) {
+            this.refused(session.sessionId, 'github-path', path, response, 'GitHub request refused: github.com is limited to Git smart HTTP.');
+            return;
+        }
+        const repository = repositoryFromPath(hostname, path);
+        if (repository &&
+            !session.credential.repositories.some((item) => item.fullName.toLowerCase() === repository.toLowerCase())) {
+            this.refused(session.sessionId, 'repository-grant', path, response, 'Repository is outside this agent grant.');
+            return;
+        }
+        if (hostname === 'api.github.com' && path !== '/graphql' && !repository) {
+            this.refused(session.sessionId, 'repository-grant', path, response, 'GitHub API request is not scoped to a granted repository.');
+            return;
+        }
+        const restReason = hostname === 'api.github.com'
+            ? restRefusal(request.method ?? 'GET', path)
+            : null;
+        if (restReason) {
+            this.refused(session.sessionId, 'rest-policy', path, response, restReason);
+            return;
+        }
+        const receivePack = /\.git\/git-receive-pack$/i.test(path);
+        let body;
+        try {
+            body = receivePack
+                ? await readReceivePackPrefix(request)
+                : await readBody(request);
+        }
+        catch (error) {
+            reply(response, 413, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        if (path === '/graphql') {
+            if (request.method !== 'POST' ||
+                ![undefined, 'identity'].includes(request.headers['content-encoding'])) {
+                this.refused(session.sessionId, 'graphql-policy', path, response, 'GitHub GraphQL request refused: the body cannot be inspected.');
+                return;
+            }
+            const text = graphQLPolicyText(body);
+            const mutation = GRAPHQL_REFUSED_MUTATIONS.find((name) => new RegExp(`\\b${name}\\b`).test(text));
+            if (mutation) {
+                this.refused(session.sessionId, 'graphql-policy', path, response, `GitHub GraphQL mutation refused: ${mutation} is not permitted.`);
+                return;
+            }
+        }
+        if (receivePack) {
+            const reason = receivePackRefusal(body, session.sessionId);
+            if (reason) {
+                this.refused(session.sessionId, 'git-receive-pack', path, response, reason);
+                return;
+            }
+        }
+        const authorization = gitRequest
+            ? `Basic ${Buffer.from(`x-access-token:${session.credential.token}`).toString('base64')}`
+            : `Bearer ${session.credential.token}`;
+        this.forward(hostname, request, response, body, authorization, receivePack);
+    }
+    forward(hostname, request, response, body, authorization, pipeRemainder = false) {
+        const headers = forwardedHeaders(request.headers);
+        headers.host = hostname;
+        if (authorization)
+            headers.authorization = authorization;
+        if (body.length > 0 && !pipeRemainder) {
+            headers['content-length'] = String(body.length);
+        }
+        const upstream = (0, node_https_1.request)({
+            hostname,
+            port: 443,
+            method: request.method,
+            path: request.url,
+            headers,
+            ...this.options.resolveUpstream?.(hostname)
+        }, (upstreamResponse) => {
+            const responseHeaders = forwardedHeaders(upstreamResponse.headers);
+            responseHeaders['cache-control'] = 'no-store';
+            response.writeHead(upstreamResponse.statusCode ?? 502, responseHeaders);
+            upstreamResponse.pipe(response);
+        });
+        upstream.once('error', (error) => {
+            if (!response.headersSent)
+                response.writeHead(502);
+            response.end(error.message);
+        });
+        if (pipeRemainder) {
+            if (body.length > 0)
+                upstream.write(body);
+            request.pipe(upstream);
+        }
+        else if (body.length > 0)
+            upstream.end(body);
+        else if (request.readableEnded)
+            upstream.end();
+        else
+            request.pipe(upstream);
+    }
+}
+exports.GitHubTlsProxy = GitHubTlsProxy;

package/dist/github-workspace.d.ts

@@ -0,0 +1,55 @@
+import { type RequestListener, type Server } from 'node:http';
+import type { WorkspaceProvider, WorkspaceRequest } from './ports';
+import type { LeasedGitHubCredential } from './types';
+export interface GitHubWorkspaceOptions {
+    root: string;
+    port?: number;
+    createServer?: (handler: RequestListener) => Server;
+    logger?: Pick<Console, 'warn'>;
+    directUrls?: string[];
+}
+/** Bare clone plus one worktree per session, adapted from 20x. */
+export declare class GitHubWorkspaceProvider implements WorkspaceProvider {
+    private readonly options;
+    private readonly sessions;
+    private readonly gitEnvironment;
+    private server;
+    private port;
+    private serverStart;
+    private linkSecret;
+    private caCertificatePath;
+    private readonly restartNotedSessions;
+    private readonly restoredWorktreeNotes;
+    private readonly preparedWorktrees;
+    private readonly directHosts;
+    constructor(options: GitHubWorkspaceOptions);
+    private rememberDirectUrls;
+    private runGit;
+    /**
+     * A harness crash must not erase or recreate a session checkout. Accept an
+     * existing path only when Git proves that it is the exact worktree this
+     * provider would have created: same canonical root, same bare repository,
+     * and same per-session branch. Anything else fails closed.
+     */
+    private canReuseWorktree;
+    private dirtyFileCount;
+    private worktreesForSession;
+    private failedPushMarker;
+    private readFailedPushes;
+    private writeFailedPushes;
+    setCredential(sessionId: string, credential: LeasedGitHubCredential): void;
+    private loadOrCreateLinkSecret;
+    private sentinelFor;
+    clearCredential(sessionId: string): void;
+    private sessionPath;
+    private ensureServer;
+    private startServer;
+    prepare(request: WorkspaceRequest): Promise<string>;
+    getEnvironment(sessionId: string, directUrls?: string[]): Record<string, string>;
+    takeTurnNote(sessionId: string): string | null;
+    preserveAtTurnEnd(sessionId: string): Promise<boolean>;
+    release(sessionId: string, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    stop(): Promise<void>;
+}