dsh-perm-gate 2.1.0 → 2.6.1

package/lib/parsers/shell-cmds.js

@@ -0,0 +1,293 @@
+/**
+ * Shell dangerous commands parser - rm, mv, cp, chmod, dd, diskpart, etc.
+ * P1 priority - detects destructive filesystem operations.
+ *
+ * Handles:
+ * - rm -rf / recursive deletion
+ * - mv overwriting existing files
+ * - cp -r with destructive patterns
+ * - chmod/chown with system directories
+ * - dd writing to disk
+ * - diskpart on Windows
+ * - format disk operations
+ * - PowerShell Remove-Item with dangerous patterns
+ */
+/** Commands that are inherently destructive (only dangerous ones trigger canParse) */
+const DESTRUCTIVE_COMMANDS = {
+    // Level 5: Extreme (system-wide, data loss)
+    'dd': 5,
+    'diskpart': 5,
+    'format': 5,
+    'fdisk': 5,
+    'mkfs': 5,
+    'rm-sudo': 5,
+    // Level 4: High (significant file deletion/modification)
+    'rm': 4,
+    'rmdir': 4,
+    'shred': 4,
+    'wipefs': 4,
+    // Level 3: Medium (file operations with potential data loss)
+    'mv': 3,
+    // Level 2: Low (potentially risky)
+    'cp': 2,
+    'chmod': 2,
+    'chown': 2,
+    'chgrp': 2,
+    'install': 2,
+    'rsync': 2,
+    'tar': 2,
+};
+/** System directories that shouldn't be modified */
+const SYSTEM_DIRS = /^(\/bin|\/sbin|\/usr|\/lib|\/etc|\/boot|\/dev|\/proc|\/sys|\/var|C:\\Windows|C:\\Program Files)/i;
+/** Patterns that indicate destructive operations */
+const DESTRUCTIVE_PATTERNS = [
+    /rm\s+(-\w*\s+)*[^-\w]*\//i, // rm with /
+    /rm\s+(-\w*\s+)*\*/i, // rm with *
+    /rm\s+(-\w*\s+)*~/i, // rm with ~
+    /rm\s+(-\w*\s+)*\/[a-z]/i, // rm /anything
+    /rmdir\s+/i,
+    /mv\s+.*\//i, // mv to absolute path
+    /chmod\s+[0-7]*\s*\//i, // chmod on root paths
+    /chown\s+.*\//i, // chown on root paths
+    /dd\s+.*of=/i, // dd writing
+    /mkfs\./i, // format filesystem
+    />\s*\//i, // redirect to /
+    />>\s*\//i, // append to /
+];
+export class ShellDangerousParser {
+    name = 'shell-dangerous';
+    priority = 20;
+    canParse(command) {
+        const cmd = command.trim().toLowerCase();
+        const baseName = this.extractBaseName(cmd);
+        // Check if it's a known destructive command
+        if (DESTRUCTIVE_COMMANDS[baseName] !== undefined) {
+            return true;
+        }
+        // Check for PowerShell equivalents
+        if (cmd.startsWith('remove-item') || cmd.startsWith('ri ')) {
+            return true;
+        }
+        // Check for destructive patterns
+        return DESTRUCTIVE_PATTERNS.some(p => p.test(command));
+    }
+    parse(command) {
+        const trimmed = command.trim();
+        const cmd = trimmed.toLowerCase();
+        const baseName = this.extractBaseName(cmd);
+        let destructiveness = DESTRUCTIVE_COMMANDS[baseName] || 1;
+        let operation = baseName;
+        let targets = [];
+        let destructiveFlags = false;
+        // Parse based on command type
+        if (baseName === 'rm' || baseName === 'rmdir') {
+            const parsed = this.parseRm(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.recursive || parsed.force;
+            if (parsed.recursive && parsed.force) {
+                destructiveness = 5;
+                operation = 'recursive-force-delete';
+            }
+            else if (parsed.recursive) {
+                destructiveness = 4;
+                operation = 'recursive-delete';
+            }
+            else if (parsed.force) {
+                destructiveness = 3;
+                operation = 'force-delete';
+            }
+            // Check if targeting system directories
+            if (targets.some(t => SYSTEM_DIRS.test(t))) {
+                destructiveness = 5;
+            }
+        }
+        else if (baseName === 'mv') {
+            const parsed = this.parseMv(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.force;
+            if (parsed.force) {
+                destructiveness = 4;
+                operation = 'force-move';
+            }
+            // Check if overwriting system files
+            if (targets.some(t => SYSTEM_DIRS.test(t))) {
+                destructiveness = 4;
+            }
+        }
+        else if (baseName === 'chmod' || baseName === 'chown' || baseName === 'chgrp') {
+            const parsed = this.parseChmod(trimmed);
+            targets = parsed.targets;
+            if (targets.some(t => SYSTEM_DIRS.test(t))) {
+                destructiveness = 4;
+            }
+        }
+        else if (baseName === 'dd') {
+            const parsed = this.parseDd(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.force;
+        }
+        else if (baseName === 'diskpart' || baseName === 'format') {
+            const parsed = this.parseDiskpart(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = true;
+        }
+        else if (baseName.startsWith('remove-item') || baseName.startsWith('ri ')) {
+            const parsed = this.parsePowerShellRemove(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.recursive || parsed.force;
+            if (parsed.recursive && parsed.force) {
+                destructiveness = 5;
+                operation = 'recursive-force-delete';
+            }
+            else if (parsed.recursive) {
+                destructiveness = 4;
+                operation = 'recursive-delete';
+            }
+        }
+        else if (baseName === 'cp') {
+            const parsed = this.parseCp(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.force;
+            if (parsed.recursive) {
+                operation = 'recursive-copy';
+                destructiveness = 3;
+            }
+        }
+        else if (baseName === 'tar' || baseName === 'rsync') {
+            const parsed = this.parseArchive(trimmed);
+            targets = parsed.targets;
+            destructiveFlags = parsed.delete;
+            if (parsed.delete) {
+                destructiveness = 4;
+                operation = 'archive-delete-target';
+            }
+        }
+        const flags = this.extractFlags(trimmed);
+        return {
+            family: 'shell-dangerous',
+            subcommand: baseName,
+            operation,
+            destructiveness: destructiveness,
+            destructiveFlags,
+            targets,
+            flags,
+            requiresConfirmation: destructiveness >= 4,
+            compound: false,
+            gitOperation: false,
+            targetsSharedBranch: false,
+            rawCommand: trimmed,
+        };
+    }
+    extractBaseName(command) {
+        // Handle sh -c "..." patterns
+        const shMatch = command.match(/(?:sh|bash|pwsh)(?:\s+-c\s+['"]?)(.+?)(?:['"]?)$/);
+        const actual = shMatch ? shMatch[1] : command;
+        // Extract first word
+        const parts = actual.trim().split(/\s+/);
+        return parts[0]?.toLowerCase() || '';
+    }
+    parseRm(command) {
+        const args = this.extractArgs(command);
+        const recursive = args.some(a => a === '-r' || a === '-rf' || a === '-fr' || a === '--recursive');
+        const force = args.some(a => a === '-f' || a === '-rf' || a === '-fr' || a === '--force');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, recursive, force };
+    }
+    parseMv(command) {
+        const args = this.extractArgs(command);
+        const force = args.some(a => a === '-f' || a === '--force');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, force };
+    }
+    parseCp(command) {
+        const args = this.extractArgs(command);
+        const recursive = args.some(a => a === '-r' || a === '-R' || a === '--recursive');
+        const force = args.some(a => a === '-f' || a === '--force');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, recursive, force };
+    }
+    parseChmod(command) {
+        const args = this.extractArgs(command);
+        const targets = args.filter(a => !a.startsWith('-') && !/^[0-7]+$/.test(a));
+        return { targets };
+    }
+    parseDd(command) {
+        const args = this.extractArgs(command);
+        const targets = [];
+        for (const arg of args) {
+            if (arg.startsWith('of=')) {
+                targets.push(arg.slice(3));
+            }
+            if (arg.startsWith('if=')) {
+                targets.push(arg.slice(3));
+            }
+        }
+        const force = command.includes('conv=') || command.includes('oflag=');
+        return { targets, force };
+    }
+    parseDiskpart(command) {
+        // Diskpart commands are always dangerous
+        const args = this.extractArgs(command);
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets };
+    }
+    parsePowerShellRemove(command) {
+        const args = this.extractArgs(command);
+        const recursive = args.some(a => a === '-Recurse' || a === '-r');
+        const force = args.some(a => a === '-Force' || a === '-f');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, recursive, force };
+    }
+    parseArchive(command) {
+        const args = this.extractArgs(command);
+        const deleteFlag = args.some(a => a === '--delete' || a === '-d');
+        const targets = args.filter(a => !a.startsWith('-'));
+        return { targets, delete: deleteFlag };
+    }
+    extractArgs(command) {
+        const args = [];
+        let current = '';
+        let inQuote = false;
+        let quoteChar = '';
+        let escape = false;
+        for (const char of command) {
+            if (escape) {
+                current += char;
+                escape = false;
+                continue;
+            }
+            if (char === '\\') {
+                escape = true;
+                continue;
+            }
+            if (inQuote) {
+                if (char === quoteChar) {
+                    inQuote = false;
+                    continue;
+                }
+                current += char;
+                continue;
+            }
+            if (char === '"' || char === "'") {
+                inQuote = true;
+                quoteChar = char;
+                continue;
+            }
+            if (/\s/.test(char)) {
+                if (current) {
+                    args.push(current);
+                    current = '';
+                }
+                continue;
+            }
+            current += char;
+        }
+        if (current)
+            args.push(current);
+        return args;
+    }
+    extractFlags(command) {
+        const args = this.extractArgs(command);
+        return args.filter(a => a.startsWith('-'));
+    }
+}

package/lib/preset.d.ts

@@ -28,3 +28,16 @@ export interface SessionEventLike {
 export declare function permissionPresetOf(events: readonly SessionEventLike[] | undefined): string | undefined;
 /** Whether one preset name is covered by a configured scope list. */
 export declare function presetInScope(preset: string | undefined, scope: readonly string[]): boolean;
+/**
+ * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
+ * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
+ * same approval behaviour) — so a user can have the gate without inheriting a
+ * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
+ * preset, including the hard-deny layer).
+ *
+ * Lives in this dependency-free module (not `config.ts`) so the browser half can
+ * render the scope without pulling schemastery into the client bundle.
+ */
+export declare const DEFAULT_GATE_PRESETS: readonly string[];
+/** Normalize the gate scope: an unset/empty list means the default. */
+export declare function resolveGatePresets(configured?: readonly string[]): readonly string[];

package/lib/preset.js

@@ -39,3 +39,20 @@ export function presetInScope(preset, scope) {
         return false;
     return scope.includes(preset);
 }
+/**
+ * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
+ * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
+ * same approval behaviour) — so a user can have the gate without inheriting a
+ * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
+ * preset, including the hard-deny layer).
+ *
+ * Lives in this dependency-free module (not `config.ts`) so the browser half can
+ * render the scope without pulling schemastery into the client bundle.
+ */
+export const DEFAULT_GATE_PRESETS = ['permissive', 'permissive-full'];
+/** Normalize the gate scope: an unset/empty list means the default. */
+export function resolveGatePresets(configured) {
+    if (configured === undefined || configured.length === 0)
+        return DEFAULT_GATE_PRESETS;
+    return configured.filter((name) => typeof name === 'string' && name !== '');
+}

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;