dsh-perm-gate 2.1.0 → 3.0.0

package/lib/network-lifecycle.js

@@ -0,0 +1,180 @@
+/**
+ * Network proxy lifecycle for dsh-perm-gate.
+ *
+ * Owns the proxy + the subprocess environment injection and exposes the
+ * three operations the host needs:
+ *
+ *   attach()   — mount per the current config (called once at apply)
+ *   rebind()   — re-read the config and re-mount (called on a settings change)
+ *   detach()   — close the proxy and restore the environment
+ *
+ * Keeping this out of `index.ts` matters: the proxy has a real lifecycle
+ * (bind, env rewrite, teardown) and every step must be owned by exactly one
+ * disposer. `index.ts` only wires it.
+ *
+ * Robustness contract:
+ * - One persistent teardown effect is registered at construction, so a
+ *   dispose that races an in-flight bind still closes the proxy and restores
+ *   the environment.
+ * - Mutating operations are serialized: rapid settings toggles cannot
+ *   interleave attach/detach and leave an orphaned listener or a rewritten
+ *   `process.env`.
+ * - Nothing here throws into the host: failures degrade to "no proxy" and
+ *   surface through the optional logger.
+ */
+import { NetworkProxy, injectProxyEnv } from './proxy.js';
+/**
+ * Owns the proxy and the environment injection across (re)binds.
+ */
+export class NetworkLifecycle {
+    options;
+    proxy;
+    envRestore;
+    disposed = false;
+    /** Serializes mutations so rapid toggles cannot interleave. */
+    queue = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        // Registered ONCE, before any bind: a dispose that races the first bind
+        // still tears the proxy down and restores the environment. `effect`
+        // expects a factory returning the disposer, so the disposer is returned.
+        options.effect(() => () => {
+            this.disposed = true;
+            void this.run(() => this.detachLocked());
+        }, 'dsh-perm-gate: network proxy');
+    }
+    /** Mount the proxy per the current config. No-op when disabled or live. */
+    attach() {
+        return this.run(() => this.attachLocked());
+    }
+    /** Close the proxy and restore the environment. */
+    detach() {
+        return this.run(() => this.detachLocked());
+    }
+    /**
+     * Re-read the config and re-mount: the old proxy is closed and the old
+     * environment restored before the new one is installed. This is what makes
+     * the settings-card switches take effect without a plugin reload.
+     */
+    rebind() {
+        return this.run(async () => {
+            await this.detachLocked();
+            await this.attachLocked();
+        });
+    }
+    /** The diagnostics snapshot (safe to call at any time). */
+    snapshot() {
+        const cfg = this.options.readConfig();
+        const proxy = this.proxy;
+        const stats = proxy?.blockStats() ?? { denied: 0, askBlocked: 0 };
+        const port = proxy?.port ?? 0;
+        return {
+            enabled: cfg.enabled,
+            mode: cfg.mode,
+            bind: cfg.bind,
+            port,
+            proxyActive: proxy !== undefined && port > 0,
+            envInjected: this.envRestore !== undefined,
+            denied: stats.denied,
+            askBlocked: stats.askBlocked,
+            recent: proxy?.recentBlocks() ?? [],
+        };
+    }
+    // ─── Internals (always called through the queue) ─────────────────────
+    run(work) {
+        const next = this.queue.then(() => work());
+        // Keep the chain alive through a rejected step; the step itself is
+        // responsible for degrading rather than throwing.
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async attachLocked() {
+        if (this.disposed)
+            return;
+        const cfg = this.options.readConfig();
+        if (!cfg.enabled)
+            return;
+        // Already live: leave it alone (a rebind detaches first).
+        if (this.proxy !== undefined && this.proxy.port > 0)
+            return;
+        // A previous attempt may have left a proxy that failed to bind; drop it
+        // so the retry starts clean.
+        await this.closeProxyLocked();
+        this.restoreEnvLocked();
+        const proxy = new NetworkProxy({
+            bind: cfg.bind,
+            port: cfg.port,
+            maxRecent: 100,
+            decide: this.options.decide,
+            ...(this.options.escalate !== undefined ? { escalate: this.options.escalate } : {}),
+            attribution: this.options.attribution,
+            ...(this.options.onBlock !== undefined ? { onBlock: this.options.onBlock } : {}),
+            logger: this.options.logger,
+        });
+        this.proxy = proxy;
+        const port = await proxy.start();
+        // A dispose landed while binding: the effect already ran detach, but the
+        // proxy was created after it, so close it here.
+        if (this.disposed) {
+            await this.closeProxyLocked();
+            return;
+        }
+        if (port <= 0) {
+            // Bind failed (already logged by the proxy). Keep the handle so the
+            // snapshot can report `proxyActive: false`.
+            return;
+        }
+        if (cfg.injectEnv) {
+            try {
+                this.envRestore = injectProxyEnv(port, cfg.noProxy);
+            }
+            catch (error) {
+                this.safeWarn(`[dsh-perm-gate] proxy env injection failed: ${String(error)} — the proxy is live but subprocesses are not routed through it`);
+            }
+        }
+        this.safeInfo(`[dsh-perm-gate] network proxy listening on ${cfg.bind}:${port} (mode ${cfg.mode}${cfg.injectEnv ? ', env injected' : ', env not injected'})`);
+    }
+    async detachLocked() {
+        this.restoreEnvLocked();
+        await this.closeProxyLocked();
+    }
+    async closeProxyLocked() {
+        const proxy = this.proxy;
+        this.proxy = undefined;
+        if (proxy === undefined)
+            return;
+        try {
+            await proxy.close();
+        }
+        catch (error) {
+            this.safeWarn(`[dsh-perm-gate] proxy close failed: ${String(error)}`);
+        }
+    }
+    restoreEnvLocked() {
+        const restore = this.envRestore;
+        this.envRestore = undefined;
+        if (restore === undefined)
+            return;
+        try {
+            restore();
+        }
+        catch (error) {
+            this.safeWarn(`[dsh-perm-gate] proxy env restore failed: ${String(error)}`);
+        }
+    }
+    safeWarn(message) {
+        try {
+            this.options.logger.warn(message);
+        }
+        catch { /* never escalate */ }
+    }
+    safeInfo(message) {
+        const info = this.options.logger.info;
+        if (info === undefined)
+            return;
+        try {
+            info.call(this.options.logger, message);
+        }
+        catch { /* never escalate */ }
+    }
+}

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/parsers/git.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Git command parser - extracts subcommand, branch, remote, flags, destructiveness.
+ * P0 priority - most critical for branch permissions.
+ *
+ * Handles:
+ * - git push/force push detection
+ * - git branch operations (delete, rename)
+ * - git checkout/switch with branch names
+ * - git merge/rebase
+ * - git reset (soft/hard/mixed)
+ * - git clean (destructive file deletion)
+ * - git stash operations
+ * - git refspec parsing (HEAD:main)
+ * - Remote vs branch name disambiguation
+ */
+import type { CommandParser, CommandSemantics } from '../command-semantics.js';
+export declare class GitParser implements CommandParser {
+    readonly name = "git";
+    readonly priority = 10;
+    canParse(command: string): boolean;
+    parse(command: string): CommandSemantics | null;
+    private analyzeSubcommand;
+    private parseGitArgs;
+    private extractFlags;
+    private extractRemote;
+    private extractBranch;
+    private extractBranchName;
+    private extractRefs;
+    /**
+     * 目标是否落在保护分支上。
+     *
+     * **只剥已知的 ref 前缀，不对任意 `/` 取末段。** 早先的写法是
+     * `branch.split('/').pop()`，于是：
+     *   - `refs/heads/main` → `main`  ✅ 期望如此
+     *   - `backup/main`     → `main`  ❌ **误判**（它是含斜杠的普通分支名）
+     *   - `feat/release`    → `release` ❌ **误判**
+     *
+     * 误判方向不是"更安全"。这条判据喂给 P0 硬拒——而 P0 是**不可配置撤销**的
+     * （见 engine.ts 顶部："deterministic, monotonic, never negotiated"）。
+     * 漏判还有关键词层与 LLM 层兜底，误判则是"合法工作流被永久挡住且无出口"。
+     */
+    private isProtectedBranch;
+}