dsh-perm-gate 2.0.0 → 2.1.2

package/lib/network.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure network-policy orchestration for dsh-perm-gate.
+ *
+ * Shared by the `tools/pre-execute` gate (URL candidate static check) and
+ * the local HTTP/CONNECT proxy (real subprocess traffic). Three policy modes
+ * mapped onto DSH sandbox presets, first-match evaluation over the loaded
+ * CompiledRuleset, and mode-default fallback decision. No I/O, no process
+ * state — unit-testable and replayable.
+ *
+ * Network is a **parallel execution surface** (NOT a P-layer): it shares the
+ * same CompiledRuleset / verdict vocabulary as the P0–P4 chain but does not
+ * enter the prefix numbering. The proxy layer has no session context, so
+ * `ask` decisions degrade to block + audit.
+ */
+import type { CompiledRuleEntry, CompiledRuleset } from './rule.js';
+/** The three network policy modes. */
+export type NetworkMode = 'deny-all' | 'whitelist' | 'allow-all';
+/** Closed mode list for runtime normalization. */
+export declare const NETWORK_MODES: readonly NetworkMode[];
+/** The official file-sandbox presets the mode maps onto. */
+export type SandboxModeName = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** How a whitelist-mode unlisted target is handled. */
+export type UnlistedAction = 'ask' | 'deny';
+/**
+ * How traffic with **no in-flight shell attribution** is handled.
+ *
+ * - `'allow'` (default) — pass through unreviewed. Such traffic is not a shell
+ *   subprocess: it is DSH's own client (a built-in network tool, the LLM
+ *   transport). The proxy is a *subprocess* policy surface, so reviewing the
+ *   host's own traffic risks the host blocking itself — a far worse failure
+ *   than a missed block. This is what keeps the built-in network tools working.
+ * - `'deny'` — review it like any other connection. Stricter, but if a
+ *   built-in client ever honors the proxy environment (e.g. Node 24+ with
+ *   `NODE_USE_ENV_PROXY=1`), DSH's own calls would be blocked and the harness
+ *   would stop working.
+ */
+export type UnattributedAction = 'allow' | 'deny';
+/** A parsed network target for one connection/URL. */
+export interface NetworkTarget {
+    readonly host: string;
+    readonly port?: number;
+    readonly scheme?: string;
+    /** Resolved IP addresses (populated after DNS lookup). */
+    readonly ips: readonly string[];
+}
+/** One network decision: a rule hit or the mode-default fallback. */
+export interface NetworkDecision {
+    readonly action: 'allow' | 'deny' | 'ask';
+    /** Whether a rule (true) or the mode default (false) produced the decision. */
+    readonly matched: boolean;
+    readonly mode: NetworkMode;
+    readonly ruleIndex?: number;
+    readonly rule?: CompiledRuleEntry;
+    /** Source file path for audit attribution. */
+    readonly source?: string;
+    /** True when the connection carried no shell attribution and was exempted. */
+    readonly unattributed?: true;
+}
+/** Proxy-layer evaluation options. */
+export interface NetworkDecisionOptions {
+    readonly mode: NetworkMode;
+    readonly unlisted: UnlistedAction;
+    /** `allow` short-circuits loopback targets before rules; `policy` evaluates them normally. */
+    readonly loopback: 'allow' | 'policy';
+    /**
+     * Whether an in-flight shell execution can be attributed to this
+     * connection. `false` means the connection did not come from a subprocess
+     * the gate is tracking. Omitted = treat as attributed (pre-change behavior).
+     */
+    readonly attributed?: boolean;
+    /** Handling for unattributed traffic. Default `'allow'`. */
+    readonly unattributed?: UnattributedAction;
+}
+/**
+ * Map one official sandbox preset onto its network mode.
+ * `read-only` → deny-all, `workspace-write` → whitelist,
+ * `danger-full-access` → allow-all. Unknown → fallback.
+ */
+export declare function networkModeForSandbox(sandbox: string | undefined, fallback: NetworkMode): NetworkMode;
+/** The default decision a mode yields for an unmatched target. */
+export declare function defaultDecision(mode: NetworkMode, unlisted: UnlistedAction): NetworkDecision;
+/**
+ * Evaluate the network policy for one target against a compiled ruleset.
+ * First-match wins across deny → allow → ask partitions (deny-first).
+ *
+ * Proxy-layer tool attribution: shell subprocess connections carry
+ * `bash`/`pwsh` identity; rules scoped to other tools never fire.
+ * Agent identity is unknown at the proxy → agent-scoped rules fail-closed.
+ *
+ * **Unattributed traffic is exempt by default.** A connection that cannot be
+ * tied to an in-flight shell execution did not come from a subprocess the gate
+ * manages — it is DSH's own client. Reviewing it would let the host block
+ * itself, so it passes through (see {@link UnattributedAction}).
+ */
+export declare function decideNetworkTarget(ruleset: CompiledRuleset, target: NetworkTarget, options: NetworkDecisionOptions): NetworkDecision;
+/** Whether a target addresses the loopback range. */
+export declare function isLoopbackTarget(target: NetworkTarget): boolean;
+/** Whether a string is an IP literal (v4 or v6). */
+export declare function isIpLiteral(host: string): boolean;
+/**
+ * Parse a URL string into a NetworkTarget.
+ * Returns undefined for malformed URLs.
+ */
+export declare function parseUrlTarget(url: string): NetworkTarget | undefined;
+/**
+ * The short structured message a blocked proxy connection receives.
+ * `ask` at proxy layer degrades to block + audit (no session context).
+ */
+export declare function blockMessage(decision: NetworkDecision): string;

package/lib/network.js

@@ -0,0 +1,196 @@
+import { compileCidr, compilePortSpec, compileDomainPattern } from './compiler.js';
+/** Closed mode list for runtime normalization. */
+export const NETWORK_MODES = ['deny-all', 'whitelist', 'allow-all'];
+// ─── Mode mapping ──────────────────────────────────────────────────────────
+/**
+ * Map one official sandbox preset onto its network mode.
+ * `read-only` → deny-all, `workspace-write` → whitelist,
+ * `danger-full-access` → allow-all. Unknown → fallback.
+ */
+export function networkModeForSandbox(sandbox, fallback) {
+    switch (sandbox) {
+        case 'read-only': return 'deny-all';
+        case 'workspace-write': return 'whitelist';
+        case 'danger-full-access': return 'allow-all';
+        default: return fallback;
+    }
+}
+/** The default decision a mode yields for an unmatched target. */
+export function defaultDecision(mode, unlisted) {
+    switch (mode) {
+        case 'deny-all':
+            return { action: 'deny', matched: false, mode };
+        case 'whitelist':
+            return { action: unlisted, matched: false, mode };
+        case 'allow-all':
+            return { action: 'allow', matched: false, mode };
+    }
+}
+// ─── Target matching ───────────────────────────────────────────────────────
+/**
+ * Evaluate the network policy for one target against a compiled ruleset.
+ * First-match wins across deny → allow → ask partitions (deny-first).
+ *
+ * Proxy-layer tool attribution: shell subprocess connections carry
+ * `bash`/`pwsh` identity; rules scoped to other tools never fire.
+ * Agent identity is unknown at the proxy → agent-scoped rules fail-closed.
+ *
+ * **Unattributed traffic is exempt by default.** A connection that cannot be
+ * tied to an in-flight shell execution did not come from a subprocess the gate
+ * manages — it is DSH's own client. Reviewing it would let the host block
+ * itself, so it passes through (see {@link UnattributedAction}).
+ */
+export function decideNetworkTarget(ruleset, target, options) {
+    if (options.loopback === 'allow' && isLoopbackTarget(target)) {
+        return { action: 'allow', matched: false, mode: options.mode };
+    }
+    // Not from a shell subprocess → not this surface's to police.
+    if (options.attributed === false && (options.unattributed ?? 'allow') === 'allow') {
+        return { action: 'allow', matched: false, mode: options.mode, unattributed: true };
+    }
+    // Scan deny → allow → ask (deny-first).
+    for (const partition of [ruleset.deny, ruleset.allow, ruleset.ask]) {
+        for (const rule of partition) {
+            if (!rule.enabled)
+                continue;
+            if (rule.network === undefined)
+                continue;
+            if (!matchToolsProxy(rule))
+                continue;
+            if (!targetMatchesNetwork(target, rule.network))
+                continue;
+            return {
+                action: rule.action,
+                matched: true,
+                mode: options.mode,
+                ruleIndex: rule.index,
+                rule,
+            };
+        }
+    }
+    return defaultDecision(options.mode, options.unlisted);
+}
+/**
+ * Tool-scope check for proxy traffic: shell subprocess connections carry
+ * `bash`/`pwsh` identity. Rules scoped to other tools never fire at proxy.
+ */
+function matchToolsProxy(rule) {
+    if (rule.tools.length === 0)
+        return true;
+    // Match if any tool pattern matches 'bash' or 'pwsh'.
+    return rule.tools.some((t) => t.re.test('bash') || t.re.test('pwsh'));
+}
+/**
+ * Check if a network target matches a rule's network dimension.
+ * All present sub-dimensions must match (AND); within a sub-dimension, entries are OR.
+ */
+function targetMatchesNetwork(target, network) {
+    // domains
+    if (network.domains !== undefined && network.domains.length > 0) {
+        const matchers = network.domains.map((d) => compileDomainPattern(d));
+        if (!matchers.some((m) => m.re.test(target.host)))
+            return false;
+    }
+    // ips
+    if (network.ips !== undefined && network.ips.length > 0) {
+        const allIps = [...target.ips];
+        if (target.host !== undefined)
+            allIps.push(target.host);
+        const cidrs = network.ips.filter((s) => s.includes('/'));
+        const literals = network.ips.filter((s) => !s.includes('/'));
+        const ipMatch = allIps.some((ip) => literals.includes(ip) || cidrs.some((c) => {
+            try {
+                return compileCidr(c)(ip);
+            }
+            catch {
+                return false;
+            }
+        }));
+        if (!ipMatch)
+            return false;
+    }
+    // ports
+    if (network.ports !== undefined && network.ports.length > 0) {
+        if (target.port === undefined)
+            return false;
+        const matchers = network.ports.map((p) => {
+            try {
+                return compilePortSpec(p);
+            }
+            catch {
+                return (_) => false;
+            }
+        });
+        if (!matchers.some((m) => m(target.port)))
+            return false;
+    }
+    // schemes
+    if (network.schemes !== undefined && network.schemes.length > 0) {
+        if (target.scheme === undefined)
+            return false;
+        if (!network.schemes.includes(target.scheme))
+            return false;
+    }
+    return true;
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+/** Whether a target addresses the loopback range. */
+export function isLoopbackTarget(target) {
+    const host = target.host;
+    if (host === 'localhost' || host === '::1' || host === '0:0:0:0:0:0:0:1')
+        return true;
+    const parts = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (parts === null)
+        return false;
+    return parts.slice(1).every((o) => Number(o) <= 255) && parts[1] === '127';
+}
+/** Whether a string is an IP literal (v4 or v6). */
+export function isIpLiteral(host) {
+    return /^[\d.:a-fA-F]+$/.test(host) && (host.includes(':') || /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host));
+}
+/**
+ * Parse a URL string into a NetworkTarget.
+ * Returns undefined for malformed URLs.
+ */
+export function parseUrlTarget(url) {
+    try {
+        const u = new URL(url);
+        const host = u.hostname.toLowerCase().replace(/\.+$/, '');
+        if (host.length === 0)
+            return undefined;
+        const port = u.port !== '' ? Number(u.port) : (u.protocol === 'https:' ? 443 : u.protocol === 'http:' ? 80 : undefined);
+        return {
+            host,
+            port: port !== undefined && Number.isFinite(port) ? port : undefined,
+            scheme: u.protocol.replace(/:$/, ''),
+            ips: isIpLiteral(host) ? [host] : [],
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The short structured message a blocked proxy connection receives.
+ * `ask` at proxy layer degrades to block + audit (no session context).
+ */
+export function blockMessage(decision) {
+    const reason = decision.rule?.reason ?? '';
+    if (decision.matched) {
+        const rulePart = decision.ruleIndex !== undefined ? ` by rule ${decision.ruleIndex + 1}` : '';
+        if (decision.action === 'ask') {
+            return `[network: blocked pending approval${rulePart}] ${reason}\n(subprocess connections cannot ride the interactive approval seam — ask your user or add an allow rule for this target)`;
+        }
+        return `[network: denied${rulePart}] ${reason}`;
+    }
+    switch (decision.mode) {
+        case 'deny-all':
+            return '[network: denied] network mode deny-all (read-only sandbox preset): only whitelisted targets are reachable';
+        case 'whitelist':
+            return decision.action === 'ask'
+                ? '[network: blocked pending approval] whitelist mode: the target is not matched by an allow rule'
+                : '[network: denied] whitelist mode: the target is not matched by an allow rule';
+        case 'allow-all':
+            return '[network: denied]';
+    }
+}

package/lib/proxy.d.ts

@@ -0,0 +1,160 @@
+import type { NetworkDecision, NetworkMode, NetworkTarget } from './network.js';
+/** Proxy env var names the injector sets/restores (upper + lower for mixed-ecosystem CLIs). */
+export declare const PROXY_ENV_NAMES: readonly string[];
+/** NO_PROXY env var names cleared by the injector. */
+export declare const NO_PROXY_ENV_NAMES: readonly string[];
+/** Default DNS lookup bound (ms). A black-holed resolver must not hang a CONNECT. */
+export declare const DNS_TIMEOUT_MS = 3000;
+/** Default connection-setup bound (ms) — slowloris guard. */
+export declare const HEADERS_TIMEOUT_MS = 60000;
+/** Default cap on concurrent accepted connections. */
+export declare const MAX_CONNECTIONS = 256;
+/** Bound on how long close() waits for a server to finish closing (ms). */
+export declare const CLOSE_TIMEOUT_MS = 2000;
+/** One recorded proxy-layer block. */
+export interface NetworkBlockRecord {
+    readonly time: number;
+    readonly tool: string;
+    readonly attributed: boolean;
+    readonly callId?: string;
+    readonly domain: string;
+    readonly scheme?: string;
+    readonly port?: number;
+    readonly action: 'deny' | 'ask';
+    readonly mode: NetworkMode;
+    readonly matched: boolean;
+    readonly source: string;
+    readonly ruleIndex?: number;
+    readonly reason?: string;
+}
+/** Cumulative proxy-layer block counters. */
+export interface NetworkStats {
+    denied: number;
+    askBlocked: number;
+}
+/** Attribution the runtime supplies for one connection. */
+export interface ProxyAttribution {
+    readonly tool: string;
+    readonly callId?: string;
+}
+/** Construction options for NetworkProxy. */
+export interface NetworkProxyOptions {
+    /** Bind address (loopback by config). */
+    readonly bind: string;
+    /** Requested port; `0` binds an ephemeral port. */
+    readonly port: number;
+    /** Cap on recent-block records kept in memory. */
+    readonly maxRecent: number;
+    /** Decision function supplied by the runtime. */
+    readonly decide: (target: NetworkTarget) => NetworkDecision | Promise<NetworkDecision>;
+    /**
+     * Escalate an `ask` decision to the interactive approval seam. Called ONLY
+     * when {@link decide} returns `ask` — a `deny` is never escalated, so the
+     * rule review cannot be bypassed by approving a connection.
+     *
+     * Absent, throwing, or timing out all mean "not allowed": the connection is
+     * blocked exactly as it would have been.
+     */
+    readonly escalate?: (target: NetworkTarget, decision: NetworkDecision) => Promise<'allow' | 'deny'>;
+    /** Current attribution (newest in-flight shell execution). */
+    readonly attribution?: () => ProxyAttribution | undefined;
+    /** Called for every blocked connection. */
+    readonly onBlock?: (record: NetworkBlockRecord, attribution: ProxyAttribution | undefined) => void;
+    /** Bind a DNS lookup with this timeout (ms). Default {@link DNS_TIMEOUT_MS}. */
+    readonly dnsTimeoutMs?: number;
+    /** Connection-setup bound (ms). Default {@link HEADERS_TIMEOUT_MS}. */
+    readonly headersTimeoutMs?: number;
+    /** Cap on concurrent connections. Default {@link MAX_CONNECTIONS}. */
+    readonly maxConnections?: number;
+    /** Logger sink (proxy failures must never crash the host). */
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * The local HTTP/CONNECT policy proxy. Binds on demand; every live tunnel
+ * socket is tracked and destroyed on close so updates and uninstalls leave
+ * no orphaned connections.
+ */
+export declare class NetworkProxy {
+    private readonly options;
+    private server;
+    private readonly sockets;
+    private readonly recent;
+    private readonly stats;
+    private actualPort;
+    /** In-flight start(); guards against a second concurrent bind. */
+    private starting;
+    /** Set by close(); a bind resolving afterwards tears itself down. */
+    private closed;
+    constructor(options: NetworkProxyOptions);
+    /**
+     * Logger sink that can never throw. The logger is called from inside
+     * 'error' handlers, so a throwing logger would itself become an
+     * unhandled error and defeat the whole point of the guard.
+     */
+    private safeWarn;
+    /** The bound port (valid after start resolves). */
+    get port(): number;
+    /** Deny/ask blocks recorded since mount, newest first. */
+    recentBlocks(): readonly NetworkBlockRecord[];
+    /** Cumulative block counters. */
+    blockStats(): NetworkStats;
+    /** Number of active sockets (tunnels + client connections). */
+    activeSocketCount(): number;
+    /**
+     * Bind the server and return the actual port.
+     * On bind failure: warns and returns -1 (degraded mode — no proxy).
+     * Concurrent calls share the single in-flight bind.
+     */
+    start(): Promise<number>;
+    private bind;
+    /**
+     * Stop the server and destroy every tunnel socket.
+     *
+     * Safe against a concurrent (in-flight) {@link start}: the `closed` flag
+     * makes a bind that resolves after this call tear itself down instead of
+     * leaving an orphaned listening server behind.
+     */
+    close(): Promise<void>;
+    private handleRequest;
+    private handleConnect;
+    private forwardOrBlock;
+    /**
+     * DNS-resolve a hostname so `ips`-scoped rules see real addresses, then
+     * decide. Resolution failure → decide on the literal name.
+     *
+     * The lookup is **time-bounded**: an unbounded `lookup()` on a black-holed
+     * resolver would hold the CONNECT socket open indefinitely, so a slow
+     * resolver degrades to literal-name evaluation instead of hanging the
+     * client. `ips`-scoped rules simply cannot fire in that case.
+     */
+    private decideWithResolution;
+    /**
+     * The final decision for one target: the rule/mode verdict, then — only for
+     * an `ask` — the interactive approval seam.
+     *
+     * Escalation is deliberately narrow:
+     * - A `deny` verdict is NEVER escalated. Approving a connection can widen
+     *   reach for a target no rule allows, but it can never override a rule that
+     *   says no. The rule review stays authoritative.
+     * - An escalation that throws, is absent, or returns anything but `allow`
+     *   leaves the verdict blocked.
+     */
+    private resolveDecision;
+    private recordBlock;
+}
+/**
+ * Inject proxy environment variables for subprocesses and return a disposer
+ * restoring every previous value exactly.
+ *
+ * The snapshot pass covers EVERY name BEFORE any write: on Windows
+ * `process.env` is case-insensitive, so writing `HTTP_PROXY` mid-loop
+ * would poison the later snapshot of `http_proxy`.
+ *
+ * @param port - the bound proxy port.
+ * @param noProxy - `'clear'` empties NO_PROXY so policy cannot be bypassed;
+ *                  `'preserve'` keeps ambient values.
+ * @returns the restore disposer.
+ */
+export declare function injectProxyEnv(port: number, noProxy: 'clear' | 'preserve'): () => void;