fullcourtdefense-cli 1.34.26 → 1.35.0

package/dist/commands/httpGateway.js

@@ -0,0 +1,273 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockedResponseBody = blockedResponseBody;
+exports.startHttpGateway = startHttpGateway;
+/**
+ * `fullcourtdefense http-gateway` — a LOCAL HTTP/HTTPS forward proxy that gates
+ * an AI agent's outbound API calls.
+ *
+ * The agent process is pointed at it with the standard HTTP_PROXY /
+ * HTTPS_PROXY variables (workload-protect writes them into the identity file),
+ * so its HTTP libraries route through here without code changes. For every
+ * request the gateway:
+ *
+ *   capture      plain-HTTP request (method + absolute URL) or CONNECT tunnel (host only)
+ *   canonicalize `httpEgress.ts` — host, method class, path template, agent name, flags
+ *   decide       `evaluateActionPolicies` over the delivered policy bundle (deterministic)
+ *   enforce      allow → forward / tunnel; block → 403 JSON (tunnel: 403 then close);
+ *                require_approval → hold, ask the org queue, block on timeout or when
+ *                nobody can answer; log → forward and record
+ *   record       minimized facts (agent, host, method, path template, verdict, rule)
+ *
+ * The gateway itself never sees inside an HTTPS tunnel: for CONNECT the only
+ * fact is the destination host (+ port), so host-level rules apply and method /
+ * endpoint rules cannot. The console says so ("HTTPS: host only").
+ *
+ * Nothing here branches on anything but the returned verdict.
+ */
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const net = __importStar(require("net"));
+const httpEgress_1 = require("../httpEgress");
+const HOP_BY_HOP = new Set(['proxy-connection', 'proxy-authorization', 'proxy-authenticate', 'connection', 'keep-alive', 'te', 'trailer', 'upgrade', httpEgress_1.AGENT_NAME_HEADER]);
+function blockedResponseBody(req, decision) {
+    return JSON.stringify({
+        blocked: true,
+        by: 'FullCourtDefense',
+        action: (0, httpEgress_1.describeHttpEgress)(req),
+        agent: req.agentName,
+        host: req.host,
+        method: req.method,
+        ...(req.pathTemplate ? { endpoint: req.pathTemplate } : {}),
+        reason: decision.reason || (decision.verdict === 'require_approval'
+            ? 'This call requires approval and nobody approved it in time.'
+            : 'Blocked by API destination policy.'),
+        ...(decision.policyName ? { policy: decision.policyName } : {}),
+        ...(decision.matchedRule ? { rule: decision.matchedRule } : {}),
+        ...(decision.approvalId ? { approvalId: decision.approvalId } : {}),
+        howToChange: 'Fleet console → this agent → API destinations.',
+    });
+}
+async function startHttpGateway(options) {
+    const bind = options.bind || '127.0.0.1';
+    const upstreamTimeoutMs = options.upstreamTimeoutMs ?? 15_000;
+    const log = options.log || (() => undefined);
+    const bypass = options.bypassHosts || new Set();
+    const stats = { requests: 0, blocked: 0, forwarded: 0, tunnelled: 0, errors: 0 };
+    const shouldBypass = (req) => bypass.has(req.host) || (0, httpEgress_1.isLoopbackHost)(req.host);
+    const upstreamFor = (req) => options.resolveUpstream?.(req.host, req.port) || { host: req.host, port: req.port };
+    const server = http.createServer(async (clientReq, clientRes) => {
+        const started = Date.now();
+        stats.requests += 1;
+        // Health / self endpoint: a request addressed to the proxy itself, not through it.
+        if (clientReq.url === '/__fcd/health' || clientReq.url === '/__fcd/health/') {
+            clientRes.writeHead(200, { 'content-type': 'application/json' });
+            clientRes.end(JSON.stringify({ ok: true, gateway: 'http', ...stats }));
+            return;
+        }
+        const canonical = (0, httpEgress_1.canonicalizeHttpEgress)({
+            method: clientReq.method || 'GET',
+            target: clientReq.url || '',
+            headers: clientReq.headers,
+            agent: options.agent,
+        });
+        if (!canonical) {
+            clientRes.writeHead(400, { 'content-type': 'application/json' });
+            clientRes.end(JSON.stringify({ error: 'FullCourtDefense http-gateway: cannot parse proxy target', target: clientReq.url }));
+            return;
+        }
+        if (shouldBypass(canonical)) {
+            forwardPlain(clientReq, clientRes, canonical, upstreamFor(canonical), upstreamTimeoutMs, () => { stats.forwarded += 1; }, () => { stats.errors += 1; });
+            return;
+        }
+        let decision;
+        try {
+            decision = await options.decide(canonical);
+        }
+        catch (error) {
+            // The decider is the only thing allowed to fail closed/open; an exception here is a bug — block and say so.
+            stats.errors += 1;
+            decision = { verdict: 'block', reason: `FullCourtDefense http-gateway could not evaluate policy: ${error.message}` };
+        }
+        if (decision.verdict === 'block' || decision.verdict === 'require_approval') {
+            stats.blocked += 1;
+            clientRes.writeHead(403, {
+                'content-type': 'application/json',
+                'x-fcd-verdict': decision.verdict,
+                ...(decision.policyName ? { 'x-fcd-policy': safeHeader(decision.policyName) } : {}),
+            });
+            clientRes.end(blockedResponseBody(canonical, decision));
+            options.record({ req: canonical, decision, enforced: 'blocked', durationMs: Date.now() - started, statusCode: 403 });
+            log(`blocked ${(0, httpEgress_1.describeHttpEgress)(canonical)} (${decision.policyName || decision.reason || decision.verdict})`);
+            return;
+        }
+        forwardPlain(clientReq, clientRes, canonical, upstreamFor(canonical), upstreamTimeoutMs, (statusCode) => {
+            stats.forwarded += 1;
+            options.record({ req: canonical, decision, enforced: 'forwarded', durationMs: Date.now() - started, statusCode });
+        }, (message) => {
+            stats.errors += 1;
+            options.record({ req: canonical, decision: { ...decision, reason: message }, enforced: 'error', durationMs: Date.now() - started, statusCode: 502 });
+        });
+    });
+    server.on('connect', async (clientReq, clientSocket, head) => {
+        const started = Date.now();
+        stats.requests += 1;
+        const canonical = (0, httpEgress_1.canonicalizeHttpEgress)({ method: 'CONNECT', target: clientReq.url || '', headers: clientReq.headers, agent: options.agent });
+        if (!canonical) {
+            clientSocket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
+            return;
+        }
+        let decision = { verdict: 'allow' };
+        if (!shouldBypass(canonical)) {
+            try {
+                decision = await options.decide(canonical);
+            }
+            catch (error) {
+                stats.errors += 1;
+                decision = { verdict: 'block', reason: `FullCourtDefense http-gateway could not evaluate policy: ${error.message}` };
+            }
+        }
+        if (decision.verdict === 'block' || decision.verdict === 'require_approval') {
+            stats.blocked += 1;
+            const body = blockedResponseBody(canonical, decision);
+            clientSocket.end(`HTTP/1.1 403 Forbidden\r\nContent-Type: application/json\r\nX-FCD-Verdict: ${decision.verdict}\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`);
+            options.record({ req: canonical, decision, enforced: 'blocked', durationMs: Date.now() - started, statusCode: 403 });
+            log(`blocked ${(0, httpEgress_1.describeHttpEgress)(canonical)} (${decision.policyName || decision.reason || decision.verdict})`);
+            return;
+        }
+        const target = upstreamFor(canonical);
+        const upstream = net.connect({ host: target.host, port: target.port });
+        let settled = false;
+        const fail = (message) => {
+            if (settled)
+                return;
+            settled = true;
+            stats.errors += 1;
+            if (!clientSocket.destroyed)
+                clientSocket.end(`HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n`);
+            upstream.destroy();
+            if (!shouldBypass(canonical))
+                options.record({ req: canonical, decision: { ...decision, reason: message }, enforced: 'error', durationMs: Date.now() - started, statusCode: 502 });
+        };
+        upstream.setTimeout(upstreamTimeoutMs, () => fail('upstream connect timeout'));
+        upstream.once('error', (error) => fail(error.message));
+        upstream.once('connect', () => {
+            settled = true;
+            upstream.setTimeout(0);
+            stats.tunnelled += 1;
+            clientSocket.write('HTTP/1.1 200 Connection Established\r\nProxy-Agent: FullCourtDefense\r\n\r\n');
+            if (head && head.length)
+                upstream.write(head);
+            upstream.pipe(clientSocket);
+            clientSocket.pipe(upstream);
+            if (!shouldBypass(canonical))
+                options.record({ req: canonical, decision, enforced: 'tunnelled', durationMs: Date.now() - started });
+        });
+        clientSocket.once('error', () => upstream.destroy());
+        clientSocket.once('close', () => upstream.destroy());
+        upstream.once('close', () => { if (!clientSocket.destroyed)
+            clientSocket.destroy(); });
+    });
+    server.on('clientError', (_error, socket) => {
+        if (!socket.destroyed)
+            socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port, bind, () => { server.off('error', reject); resolve(); });
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : options.port;
+    log(`listening on http://${bind}:${port} (agent: ${options.agent.configured || options.agent.workloadName || 'unknown-agent'})`);
+    return {
+        port,
+        address: bind,
+        stats,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections?.();
+            server.close(() => resolve());
+        }),
+    };
+}
+function safeHeader(value) {
+    return value.replace(/[^\x20-\x7e]/g, '').slice(0, 200);
+}
+function forwardPlain(clientReq, clientRes, canonical, target, timeoutMs, onDone, onError) {
+    const headers = {};
+    for (const [key, value] of Object.entries(clientReq.headers)) {
+        if (value === undefined || HOP_BY_HOP.has(key.toLowerCase()) || key.toLowerCase() === 'host')
+            continue;
+        headers[key] = value;
+    }
+    headers.connection = 'close';
+    // The verdict was decided on the absolute-URI host; the upstream must see
+    // THAT host. A client-supplied `Host:` that names a different virtual host
+    // on the same front (CDN, cloud LB, ingress) would otherwise reach a vhost
+    // the policy never evaluated.
+    const defaultPort = canonical.scheme === 'https' ? 443 : 80;
+    headers.host = canonical.port === defaultPort ? canonical.host : `${canonical.host}:${canonical.port}`;
+    // An absolute `https://` URI on the plain proxy path (rare: a client that does
+    // not use CONNECT) must be forwarded over TLS, never in cleartext to :443.
+    const request = canonical.scheme === 'https' ? https.request : http.request;
+    const upstreamReq = request({
+        host: target.host,
+        port: target.port,
+        method: canonical.method,
+        path: canonical.path || '/',
+        headers,
+        timeout: timeoutMs,
+        ...(canonical.scheme === 'https' ? { servername: canonical.host } : {}),
+    }, (upstreamRes) => {
+        const responseHeaders = {};
+        for (const [key, value] of Object.entries(upstreamRes.headers)) {
+            if (value === undefined || key.toLowerCase() === 'connection')
+                continue;
+            responseHeaders[key] = value;
+        }
+        clientRes.writeHead(upstreamRes.statusCode || 502, responseHeaders);
+        upstreamRes.pipe(clientRes);
+        upstreamRes.once('end', () => onDone(upstreamRes.statusCode || 0));
+    });
+    upstreamReq.once('timeout', () => { upstreamReq.destroy(new Error('upstream timeout')); });
+    upstreamReq.once('error', (error) => {
+        onError(error.message);
+        if (!clientRes.headersSent) {
+            clientRes.writeHead(502, { 'content-type': 'application/json' });
+        }
+        clientRes.end(JSON.stringify({ error: 'FullCourtDefense http-gateway: upstream unreachable', detail: error.message, host: canonical.host }));
+    });
+    clientReq.pipe(upstreamReq);
+}

package/dist/commands/httpGatewayCommand.d.ts

@@ -0,0 +1,87 @@
+import type { BotGuardConfig } from '../config';
+import { type EngineActionPolicy, type EngineCheckResult } from '../actionPolicyEngine';
+import { type HttpEgressRequest } from '../httpEgress';
+import { type GatewayConfig } from './mcpGateway';
+import { type HttpEgressDecision, type HttpEgressRecord, type RunningHttpGateway } from './httpGateway';
+/** Fact the compiled API-destination rules constrain on (`gateway equals http`). Mirrors backend API_EGRESS_GATEWAY_FACT. */
+export declare const HTTP_GATEWAY_FACT = "http";
+export declare const DEFAULT_HTTP_GATEWAY_PORT = 18790;
+export interface HttpGatewayArgs {
+    port?: string;
+    bind?: string;
+    agentName?: string;
+    shieldId?: string;
+    shieldKey?: string;
+    apiUrl?: string;
+    developerName?: string;
+    approvalTimeoutMs?: string;
+    approvalPollMs?: string;
+    failClosed?: string;
+    /** `host=addr:port[,host=addr:port]` — connect elsewhere for these hosts (demos / tests). */
+    resolve?: string;
+    /** Write a JSON line per decision here (in addition to the spool) — demos / tests. */
+    decisionLog?: string;
+    /** Write `{ port }` here once listening — the spawner (workload-protect) waits for it. */
+    readyFile?: string;
+    /** 'true' => print one line per request to stderr. */
+    verbose?: string;
+    /**
+     * 'true' => honour a per-request `x-fcd-agent` header (several agents behind ONE
+     * gateway). OFF by default: the agent process would otherwise be able to rename
+     * itself out of its own table. Also FCD_HTTP_GATEWAY_AGENT_HEADER=1.
+     */
+    agentHeader?: string;
+}
+export declare function parseResolveArg(value: string | undefined): Map<string, {
+    host: string;
+    port: number;
+}>;
+/**
+ * The engine-facing evaluation for one egress request. Pure given its inputs —
+ * exported so tests can drive it without sockets.
+ */
+export declare function evaluateHttpEgress(policies: EngineActionPolicy[], req: HttpEgressRequest, identity: {
+    developerName: string;
+    agentName: string;
+    agentClient: string;
+}): {
+    operation: string;
+    context: Record<string, string>;
+    result: EngineCheckResult;
+};
+export declare class HttpGatewayRuntime {
+    private readonly gatewayConfig;
+    private readonly options;
+    private apis;
+    private bundleMemo;
+    private folds;
+    private decisionLogPath?;
+    constructor(gatewayConfig: GatewayConfig, options: {
+        failClosed: boolean;
+        decisionLog?: string;
+        verbose?: boolean;
+    });
+    private apiFor;
+    bundle(force?: boolean): Promise<import("../runtimeConfig").EffectiveBundle>;
+    private identity;
+    /** The decider handed to the proxy: resolves every request to an enforceable verdict. */
+    decide: (req: HttpEgressRequest) => Promise<HttpEgressDecision>;
+    /** Local Safety snapshot for this machine (bundle-hash keyed, stale-cache-wins on Monitor). Never throws. */
+    private localSafety;
+    private spoolFinding;
+    /** Recorder handed to the proxy: folds allowed calls, spools blocks immediately. */
+    record: (record: HttpEgressRecord) => void;
+    private fold;
+    /** Flush pending folds now (shutdown / tests). */
+    flushFolds(): void;
+    private spool;
+}
+export interface StartedHttpGateway {
+    gateway: RunningHttpGateway;
+    runtime: HttpGatewayRuntime;
+    agentName: string;
+    stop: () => Promise<void>;
+}
+/** Start the gateway in-process (used by the command and by tests). */
+export declare function startHttpGatewayFromArgs(args: HttpGatewayArgs, config: BotGuardConfig): Promise<StartedHttpGateway>;
+export declare function httpGatewayCommand(args: HttpGatewayArgs, config: BotGuardConfig): Promise<void>;