@guilz-dev/belay 0.1.0

package/dist/core/control-plane-isolation.d.ts

@@ -0,0 +1,10 @@
+import type { BelayControlPlaneIsolationConfig } from './config.js';
+export interface ControlPlaneIsolationReport {
+    ok: boolean;
+    mode: BelayControlPlaneIsolationConfig['mode'];
+    controlPlaneDir: string;
+    issues: string[];
+    agentWritable: boolean;
+    observedOwnerUid: number | null;
+}
+export declare function verifyControlPlaneIsolation(controlPlaneDir: string, isolation: BelayControlPlaneIsolationConfig): ControlPlaneIsolationReport;

package/dist/core/control-plane-isolation.js

@@ -0,0 +1,83 @@
+import { accessSync, constants, existsSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+function currentUid() {
+    if (typeof process.getuid === 'function') {
+        return process.getuid();
+    }
+    return null;
+}
+export function verifyControlPlaneIsolation(controlPlaneDir, isolation) {
+    const issues = [];
+    let agentWritable = false;
+    let observedOwnerUid = null;
+    if (isolation.mode === 'none') {
+        return {
+            ok: true,
+            mode: isolation.mode,
+            controlPlaneDir,
+            issues,
+            agentWritable: false,
+            observedOwnerUid: null,
+        };
+    }
+    if (!existsSync(controlPlaneDir)) {
+        issues.push(`control plane directory does not exist: ${controlPlaneDir}`);
+        return {
+            ok: false,
+            mode: isolation.mode,
+            controlPlaneDir,
+            issues,
+            agentWritable: false,
+            observedOwnerUid: null,
+        };
+    }
+    try {
+        const stats = statSync(controlPlaneDir);
+        observedOwnerUid = stats.uid;
+        const uid = currentUid();
+        if (isolation.mode === 'separate-user' && uid !== null && stats.uid === uid) {
+            issues.push('control plane directory is owned by the current agent uid');
+        }
+        if (isolation.expectedOwnerUid !== undefined && stats.uid !== isolation.expectedOwnerUid) {
+            issues.push(`control plane owner uid ${stats.uid} does not match expected ${isolation.expectedOwnerUid}`);
+        }
+    }
+    catch (error) {
+        issues.push(error instanceof Error ? error.message : 'failed to stat control plane directory');
+    }
+    if (isolation.verifyAgentWritable) {
+        const probePath = path.join(controlPlaneDir, '.belay-isolation-probe');
+        try {
+            mkdir(controlPlaneDir, { recursive: true });
+            writeFileSync(probePath, 'probe\n', 'utf8');
+            agentWritable = true;
+            try {
+                unlinkSync(probePath);
+            }
+            catch {
+                // best effort
+            }
+            issues.push('agent process can write to the control plane directory');
+        }
+        catch {
+            agentWritable = false;
+            try {
+                accessSync(controlPlaneDir, constants.W_OK);
+                agentWritable = true;
+                issues.push('agent process has write access to the control plane directory');
+            }
+            catch {
+                agentWritable = false;
+            }
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        mode: isolation.mode,
+        controlPlaneDir,
+        issues,
+        agentWritable,
+        observedOwnerUid,
+    };
+}

package/dist/core/custom-command-match.d.ts

@@ -0,0 +1,2 @@
+/** Match config allow/deny patterns against a normalized command or segment key (exact only). */
+export declare function matchesCustomCommand(normalizedCommand: string, key: string, pattern: string): boolean;

package/dist/core/custom-command-match.js

@@ -0,0 +1,8 @@
+/** Match config allow/deny patterns against a normalized command or segment key (exact only). */
+export function matchesCustomCommand(normalizedCommand, key, pattern) {
+    const trimmed = pattern.trim();
+    if (!trimmed) {
+        return false;
+    }
+    return normalizedCommand === trimmed || key === trimmed;
+}

package/dist/core/egress/allowlist.d.ts

@@ -0,0 +1,7 @@
+import type { BelayConfigV3 } from '../config.js';
+import type { EgressAllowlistEntry, EgressAllowlistFile } from './types.js';
+export declare function egressAllowlistPath(config: BelayConfigV3, repoLocalStateDir: string): string;
+export declare function loadEgressAllowlist(filePath: string): Promise<EgressAllowlistFile>;
+export declare function saveEgressAllowlist(filePath: string, state: EgressAllowlistFile): Promise<void>;
+export declare function isHostAllowlisted(host: string, allowlist: EgressAllowlistFile): boolean;
+export declare function addDomainToAllowlist(allowlist: EgressAllowlistFile, entry: EgressAllowlistEntry): EgressAllowlistFile;

package/dist/core/egress/allowlist.js

@@ -0,0 +1,33 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { belayStateDir } from '../config.js';
+export function egressAllowlistPath(config, repoLocalStateDir) {
+    return path.join(belayStateDir(config, repoLocalStateDir), 'egress-allowlist.json');
+}
+export async function loadEgressAllowlist(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, domains: [] };
+    }
+    const raw = JSON.parse(await readFile(filePath, 'utf8'));
+    return {
+        version: 1,
+        domains: Array.isArray(raw.domains) ? raw.domains : [],
+    };
+}
+export async function saveEgressAllowlist(filePath, state) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export function isHostAllowlisted(host, allowlist) {
+    const normalized = host.toLowerCase();
+    return allowlist.domains.some((entry) => entry.host.toLowerCase() === normalized);
+}
+export function addDomainToAllowlist(allowlist, entry) {
+    const normalized = entry.host.toLowerCase();
+    const filtered = allowlist.domains.filter((domain) => domain.host.toLowerCase() !== normalized);
+    return {
+        version: 1,
+        domains: [...filtered, { ...entry, host: normalized }],
+    };
+}

package/dist/core/egress/env.d.ts

@@ -0,0 +1,3 @@
+import type { BelayEgressConfig } from '../config.js';
+export declare function recommendedProxyEnv(egress: BelayEgressConfig): Record<string, string>;
+export declare function formatProxyEnv(egress: BelayEgressConfig): string;

package/dist/core/egress/env.js

@@ -0,0 +1,17 @@
+export function recommendedProxyEnv(egress) {
+    const proxyUrl = `http://${egress.listenHost}:${egress.listenPort}`;
+    return {
+        HTTP_PROXY: proxyUrl,
+        HTTPS_PROXY: proxyUrl,
+        http_proxy: proxyUrl,
+        https_proxy: proxyUrl,
+        NO_PROXY: '127.0.0.1,localhost',
+        no_proxy: '127.0.0.1,localhost',
+    };
+}
+export function formatProxyEnv(egress) {
+    const vars = recommendedProxyEnv(egress);
+    return Object.entries(vars)
+        .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
+        .join('\n');
+}

package/dist/core/egress/fingerprint.d.ts

@@ -0,0 +1,3 @@
+export declare function egressFingerprint(repoRoot: string, host: string, port: number, method: string, hasPayload?: boolean): string;
+export declare function egressSummary(host: string, port: number, method?: string, hasPayload?: boolean): string;
+export declare function parseHostFromSummary(summary: string): string | null;

package/dist/core/egress/fingerprint.js

@@ -0,0 +1,35 @@
+import { hashValue } from '../fingerprint.js';
+export function egressFingerprint(repoRoot, host, port, method, hasPayload = false) {
+    const payloadTag = hasPayload ? ':payload' : '';
+    return hashValue(`egress:${repoRoot}:${host.toLowerCase()}:${port}:${method.toUpperCase()}${payloadTag}`);
+}
+function formatHostPort(host, port) {
+    const normalized = host.toLowerCase();
+    const hostLabel = normalized.includes(':') ? `[${normalized}]` : normalized;
+    return `${hostLabel}:${port}`;
+}
+export function egressSummary(host, port, method = 'CONNECT', hasPayload = false) {
+    return `${method} ${formatHostPort(host, port)}${hasPayload ? ' (payload)' : ''}`;
+}
+export function parseHostFromSummary(summary) {
+    const trimmed = summary.trim();
+    const methodMatch = trimmed.match(/^(CONNECT|GET|POST|PUT|DELETE|HEAD|PATCH|OPTIONS)\s+(.+?)(?:\s+\(payload\))?$/i);
+    if (!methodMatch?.[2]) {
+        try {
+            return new URL(trimmed).hostname.toLowerCase();
+        }
+        catch {
+            return null;
+        }
+    }
+    const target = methodMatch[2].trim();
+    const bracketMatch = target.match(/^\[([^\]]+)\]:(\d+)$/);
+    if (bracketMatch?.[1]) {
+        return bracketMatch[1].toLowerCase();
+    }
+    const colonIndex = target.lastIndexOf(':');
+    if (colonIndex > 0) {
+        return target.slice(0, colonIndex).toLowerCase();
+    }
+    return target.toLowerCase();
+}

package/dist/core/egress/policy.d.ts

@@ -0,0 +1,8 @@
+import type { ApprovalStateFile } from '../types.js';
+import type { EgressAllowlistFile, EgressConnectRequest, EgressPolicyResult } from './types.js';
+export declare function evaluateEgressConnect(params: {
+    request: EgressConnectRequest;
+    allowlist: EgressAllowlistFile;
+    approved: ApprovalStateFile;
+    pendingApprovalId?: string;
+}): EgressPolicyResult;

package/dist/core/egress/policy.js

@@ -0,0 +1,47 @@
+import { isHostAllowlisted } from './allowlist.js';
+import { egressFingerprint, egressSummary } from './fingerprint.js';
+const SAFE_READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+export function evaluateEgressConnect(params) {
+    const { request, allowlist, approved } = params;
+    const host = request.host.toLowerCase();
+    const fingerprint = egressFingerprint(request.repoRoot, host, request.port, request.method, request.hasPayload === true);
+    const summary = egressSummary(host, request.port, request.method, request.hasPayload === true);
+    if (SAFE_READ_METHODS.has(request.method) && request.hasPayload !== true) {
+        return {
+            decision: 'allow',
+            fingerprint,
+            summary,
+            reason: 'egress_read',
+        };
+    }
+    if (isHostAllowlisted(host, allowlist)) {
+        return {
+            decision: 'allow',
+            fingerprint,
+            summary,
+            reason: 'egress_allowlist',
+        };
+    }
+    const approvedMatch = approved.approvals.find((approval) => approval.kind === 'egress' &&
+        approval.fingerprint === fingerprint &&
+        approval.repoRoot === request.repoRoot);
+    if (approvedMatch) {
+        return {
+            decision: 'allow',
+            fingerprint,
+            summary,
+            reason: 'approved_once',
+        };
+    }
+    return {
+        decision: 'deny_pending',
+        fingerprint,
+        summary,
+        reason: request.method === 'CONNECT'
+            ? 'egress_connect_requires_approval'
+            : SAFE_READ_METHODS.has(request.method) && request.hasPayload === true
+                ? 'egress_read_with_payload_requires_approval'
+                : 'egress_requires_approval',
+        approvalId: params.pendingApprovalId,
+    };
+}

package/dist/core/egress/proxy-server.d.ts

@@ -0,0 +1,21 @@
+import http from 'node:http';
+import type { BelayConfigV3 } from '../config.js';
+import { type EgressApprovalStore } from '../egress-approval.js';
+import type { ApprovalStateFile } from '../types.js';
+export interface EgressProxyContext {
+    config: BelayConfigV3;
+    repoRoot: string;
+    store: EgressApprovalStore;
+    onAudit?: (event: Record<string, unknown>) => Promise<void>;
+    loadApproved: () => Promise<ApprovalStateFile>;
+}
+export declare function parseConnectTarget(url: string): {
+    host: string;
+    port: number;
+} | null;
+export declare function createEgressProxy(ctx: EgressProxyContext): http.Server;
+export declare function startEgressProxy(ctx: EgressProxyContext): Promise<{
+    server: http.Server;
+    port: number;
+    host: string;
+}>;

package/dist/core/egress/proxy-server.js

@@ -0,0 +1,263 @@
+import http from 'node:http';
+import net from 'node:net';
+import { URL } from 'node:url';
+import { consumeApprovedEgress, ensurePendingEgressApproval, notifyEgressDeny, } from '../egress-approval.js';
+import { loadEgressAllowlist } from './allowlist.js';
+import { evaluateEgressConnect } from './policy.js';
+function parseHttpTarget(req) {
+    if (!req.url) {
+        return null;
+    }
+    try {
+        const url = new URL(req.url);
+        return {
+            host: url.hostname,
+            port: url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80,
+            url,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function parseConnectTarget(url) {
+    if (!url) {
+        return null;
+    }
+    const bracketMatch = url.match(/^\[([^\]]+)\]:(\d+)$/);
+    if (bracketMatch?.[1]) {
+        const port = parseConnectPort(bracketMatch[2]);
+        return port ? { host: bracketMatch[1], port } : null;
+    }
+    const colonIndex = url.lastIndexOf(':');
+    if (colonIndex === -1) {
+        return { host: url, port: 443 };
+    }
+    const host = url.slice(0, colonIndex);
+    const portValue = url.slice(colonIndex + 1);
+    if (!host) {
+        return null;
+    }
+    const port = portValue ? parseConnectPort(portValue) : 443;
+    return port ? { host, port } : null;
+}
+function parseConnectPort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return null;
+    }
+    return port;
+}
+function headerValue(headers, name) {
+    const value = headers[name];
+    if (Array.isArray(value)) {
+        return value[0];
+    }
+    return value;
+}
+function requestHasPayload(req) {
+    const contentLength = headerValue(req.headers, 'content-length');
+    if (contentLength) {
+        const parsed = Number(contentLength);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return true;
+        }
+    }
+    const transferEncoding = headerValue(req.headers, 'transfer-encoding');
+    return typeof transferEncoding === 'string' && transferEncoding.trim().length > 0;
+}
+async function evaluateRequest(ctx, request) {
+    const allowlist = await loadEgressAllowlist(ctx.store.allowlistPath);
+    const approved = await ctx.loadApproved();
+    const result = evaluateEgressConnect({ request, allowlist, approved });
+    if (result.decision === 'allow') {
+        if (result.reason === 'approved_once') {
+            const consumed = await consumeApprovedEgress({
+                repoRoot: ctx.repoRoot,
+                fingerprint: result.fingerprint,
+                store: ctx.store,
+            });
+            if (!consumed) {
+                const freshApproved = await ctx.loadApproved();
+                const retry = evaluateEgressConnect({ request, allowlist, approved: freshApproved });
+                if (retry.decision !== 'allow') {
+                    return denyEgressRequest(ctx, request, allowlist);
+                }
+                await ctx.onAudit?.({
+                    event: 'egressConnect',
+                    kind: 'egress',
+                    verdict: 'allow',
+                    reason: retry.reason,
+                    fingerprint: retry.fingerprint,
+                    summary: retry.summary,
+                    repoRoot: ctx.repoRoot,
+                    permission: 'allow',
+                    wouldBlock: false,
+                });
+                return { allowed: true, result: retry };
+            }
+            await ctx.onAudit?.({
+                event: 'egressConnect',
+                kind: 'egress',
+                verdict: 'allow',
+                reason: 'approved_once',
+                fingerprint: result.fingerprint,
+                summary: result.summary,
+                repoRoot: ctx.repoRoot,
+                approvalId: consumed.approvalId,
+                permission: 'allow',
+                wouldBlock: false,
+            });
+            return { allowed: true, result };
+        }
+        await ctx.onAudit?.({
+            event: 'egressConnect',
+            kind: 'egress',
+            verdict: 'allow',
+            reason: result.reason,
+            fingerprint: result.fingerprint,
+            summary: result.summary,
+            repoRoot: ctx.repoRoot,
+            permission: 'allow',
+            wouldBlock: false,
+        });
+        return { allowed: true, result };
+    }
+    return denyEgressRequest(ctx, request, allowlist, result);
+}
+async function denyEgressRequest(ctx, request, allowlist, result) {
+    const approved = await ctx.loadApproved();
+    const policyResult = result ??
+        evaluateEgressConnect({
+            request,
+            allowlist,
+            approved,
+        });
+    const { approvalId, approval, created } = await ensurePendingEgressApproval({
+        config: ctx.config,
+        repoRoot: ctx.repoRoot,
+        policyResult,
+        store: ctx.store,
+    });
+    if (created) {
+        await notifyEgressDeny({
+            config: ctx.config,
+            repoRoot: ctx.repoRoot,
+            policyResult,
+            approval,
+        });
+    }
+    await ctx.onAudit?.({
+        event: 'egressConnect',
+        kind: 'egress',
+        verdict: 'deny_pending_approval',
+        reason: policyResult.reason,
+        fingerprint: policyResult.fingerprint,
+        summary: policyResult.summary,
+        repoRoot: ctx.repoRoot,
+        approvalId,
+        permission: 'deny',
+        wouldBlock: true,
+    });
+    return { allowed: false, approvalId, result: policyResult };
+}
+function denyResponse(res, approvalId, summary) {
+    const body = JSON.stringify({
+        error: 'egress_requires_approval',
+        message: `Belay blocked egress to ${summary}. Approval ID: ${approvalId}.`,
+        approvalId,
+    });
+    res.writeHead(403, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+function forwardHttp(req, res, target) {
+    const upstreamPath = `${target.url.pathname}${target.url.search}`;
+    const headers = { ...req.headers, host: `${target.host}:${target.port}` };
+    const proxyReq = http.request({
+        host: target.host,
+        port: target.port,
+        method: req.method,
+        path: upstreamPath,
+        headers,
+    }, (proxyRes) => {
+        res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+        proxyRes.pipe(res);
+    });
+    proxyReq.on('error', () => {
+        res.writeHead(502);
+        res.end('Bad gateway');
+    });
+    req.pipe(proxyReq);
+}
+export function createEgressProxy(ctx) {
+    const server = http.createServer(async (req, res) => {
+        const target = parseHttpTarget(req);
+        if (!target) {
+            res.writeHead(400);
+            res.end('Bad request');
+            return;
+        }
+        const evaluation = await evaluateRequest(ctx, {
+            host: target.host,
+            port: target.port,
+            method: (req.method ?? 'GET'),
+            hasPayload: requestHasPayload(req),
+            repoRoot: ctx.repoRoot,
+        });
+        if (!evaluation.allowed) {
+            denyResponse(res, evaluation.approvalId ?? '', evaluation.result.summary);
+            return;
+        }
+        forwardHttp(req, res, target);
+    });
+    server.on('connect', (req, clientSocket, head) => {
+        void (async () => {
+            const target = parseConnectTarget(req.url ?? '');
+            if (!target) {
+                clientSocket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+                clientSocket.destroy();
+                return;
+            }
+            const evaluation = await evaluateRequest(ctx, {
+                host: target.host,
+                port: target.port,
+                method: 'CONNECT',
+                repoRoot: ctx.repoRoot,
+            });
+            if (!evaluation.allowed) {
+                const body = `Belay blocked egress. Approval ID: ${evaluation.approvalId ?? 'unknown'}`;
+                clientSocket.write(`HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+                clientSocket.destroy();
+                return;
+            }
+            const serverSocket = net.connect(target.port, target.host, () => {
+                clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+                if (head.length > 0) {
+                    serverSocket.write(head);
+                }
+                serverSocket.pipe(clientSocket);
+                clientSocket.pipe(serverSocket);
+            });
+            serverSocket.on('error', () => {
+                clientSocket.destroy();
+            });
+            clientSocket.on('error', () => {
+                serverSocket.destroy();
+            });
+        })();
+    });
+    return server;
+}
+export async function startEgressProxy(ctx) {
+    const server = createEgressProxy(ctx);
+    const host = ctx.config.egress.listenHost;
+    const port = ctx.config.egress.listenPort;
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => resolve());
+    });
+    return { server, port, host };
+}

package/dist/core/egress/types.d.ts

@@ -0,0 +1,25 @@
+export interface EgressConnectRequest {
+    host: string;
+    port: number;
+    method: 'CONNECT' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'PATCH' | 'OPTIONS';
+    hasPayload?: boolean;
+    repoRoot: string;
+}
+export type EgressDecision = 'allow' | 'deny_pending';
+export interface EgressPolicyResult {
+    decision: EgressDecision;
+    fingerprint: string;
+    summary: string;
+    reason: string;
+    approvalId?: string;
+}
+export interface EgressAllowlistEntry {
+    host: string;
+    approvedAt: string;
+    approvalId?: string;
+}
+export interface EgressAllowlistFile {
+    version: 1;
+    domains: EgressAllowlistEntry[];
+}
+export type EgressApprovalScope = 'once' | 'domain';

package/dist/core/egress/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/egress-approval.d.ts

@@ -0,0 +1,48 @@
+import type { BelayConfigV3 } from './config.js';
+import type { EgressApprovalScope, EgressPolicyResult } from './egress/types.js';
+import type { ApprovalRecord, ApprovalStateFile } from './types.js';
+export interface EgressApprovalStore {
+    loadPending: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    loadApproved: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    writePending: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    writeApproved: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    allowlistPath: string;
+}
+export declare function ensurePendingEgressApproval(params: {
+    config: BelayConfigV3;
+    repoRoot: string;
+    policyResult: EgressPolicyResult;
+    store: EgressApprovalStore;
+}): Promise<{
+    approvalId: string;
+    approval: ApprovalRecord;
+    created: boolean;
+}>;
+export declare function consumeApprovedEgress(params: {
+    repoRoot: string;
+    fingerprint: string;
+    store: EgressApprovalStore;
+}): Promise<ApprovalRecord | null>;
+export declare function notifyEgressDeny(params: {
+    config: BelayConfigV3;
+    repoRoot: string;
+    policyResult: EgressPolicyResult;
+    approval: ApprovalRecord;
+}): Promise<void>;
+export declare function recordEgressApproval(params: {
+    approvalId: string;
+    config: BelayConfigV3;
+    store: EgressApprovalStore;
+    scope?: EgressApprovalScope;
+    token?: string;
+    requireSignedToken?: boolean;
+}): Promise<{
+    ok: boolean;
+    message: string;
+}>;