dsh-perm-gate 2.1.0 → 2.6.1

package/lib/rule-chain.js

@@ -0,0 +1,213 @@
+/**
+ * Multi-file rule chain for dsh-perm-gate.
+ *
+ * Resolves and merges multiple YAML permissions documents into a single
+ * `CompiledRuleset`. The chain follows a search-up strategy: starting from
+ * the workspace cwd, walk up directory ancestors looking for the rules file,
+ * then fall back to a configured path, then to an empty ruleset.
+ *
+ * Each file in the chain is independently compiled and cached by content hash.
+ * Chain-level merge preserves the deny-first partitioned structure: all deny
+ * entries from all files are concatenated (with source file tracking), then
+ * all allow entries, then all ask entries.
+ *
+ * Error policy: `fail` (default) throws on any malformed file; `warn` logs
+ * and skips the bad file, keeping the rest of the chain.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { parsePermissionsDocument, compileDocument, compileRuleEntry, documentHash } from './rule.js';
+import { hashText } from './compiler.js';
+/** Compile-cache entry: hash → compiled ruleset. */
+const compileCache = new Map();
+// ─── Chain resolution ──────────────────────────────────────────────────────
+/**
+ * Resolve the rule chain: find all applicable rules files and merge them.
+ *
+ * @param cwd - The workspace root directory.
+ * @param config - Chain configuration.
+ * @param opts - Compile options forwarded to each file's compiler.
+ * @returns The merged compiled ruleset.
+ */
+export function resolveRuleChain(cwd, config, opts = {}) {
+    const { rulesFile, searchUp = false, fallbackPath, badFilePolicy = 'fail', maxChainLength = 10, } = config;
+    const entries = findChainEntries(cwd, rulesFile, searchUp, fallbackPath, maxChainLength);
+    if (entries.length === 0) {
+        // Empty chain: return a ruleset with no rules (defaultAction only).
+        return {
+            defaultAction: 'ask',
+            deny: [],
+            allow: [],
+            ask: [],
+            caseInsensitivePaths: opts.caseInsensitivePaths ?? false,
+        };
+    }
+    // Merge all entries into a single ruleset.
+    return mergeChain(entries, badFilePolicy, opts);
+}
+/**
+ * Walk the chain and collect valid rules file entries.
+ */
+function findChainEntries(cwd, rulesFile, searchUp, fallbackPath, maxChainLength) {
+    const entries = [];
+    const seen = new Set();
+    // 1. Start from cwd and optionally search up.
+    const candidates = [];
+    let dir = resolve(cwd);
+    // Always check cwd first.
+    candidates.push(join(dir, rulesFile));
+    if (searchUp) {
+        // Walk up ancestors until root.
+        let prev = '';
+        while (dir !== prev && candidates.length < maxChainLength) {
+            candidates.push(join(dir, rulesFile));
+            prev = dir;
+            dir = dirname(dir);
+        }
+    }
+    for (const candidate of candidates) {
+        if (entries.length >= maxChainLength)
+            break;
+        const resolved = resolve(candidate);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        if (!existsSafe(resolved))
+            continue;
+        const stat = statSafe(resolved);
+        if (stat === undefined || !stat.isFile())
+            continue;
+        const entry = readEntry(resolved);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    // 2. Fallback path.
+    if (fallbackPath !== undefined && entries.length === 0) {
+        const resolved = resolve(fallbackPath);
+        if (!seen.has(resolved) && existsSafe(resolved)) {
+            const entry = readEntry(resolved);
+            if (entry !== undefined)
+                entries.push(entry);
+        }
+    }
+    return entries;
+}
+/**
+ * Read and parse a single rules file into a ChainEntry.
+ */
+function readEntry(filePath) {
+    try {
+        const text = readFileSync(filePath, 'utf8');
+        const hash = documentHash(text);
+        const doc = parsePermissionsDocument(text);
+        return { path: filePath, hash, doc };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Merge a chain of entries into a single CompiledRuleset.
+ * Each file's entries are sorted into deny/allow/ask partitions.
+ * Chain-level order: deny (all files, in chain order) → allow → ask.
+ */
+function mergeChain(entries, badFilePolicy, opts) {
+    // Collect entries per action, preserving chain order.
+    const denyDocs = [];
+    const allowDocs = [];
+    const askDocs = [];
+    for (const entry of entries) {
+        try {
+            // Compile to validate patterns (throws on malformed input).
+            compileDocument(entry.doc, opts);
+            // We use the raw doc lists for the merge (CompiledRuleset structure
+            // expects flat lists with source tracking).
+            denyDocs.push(entry.doc);
+            allowDocs.push(entry.doc);
+            askDocs.push(entry.doc);
+        }
+        catch (err) {
+            if (badFilePolicy === 'fail')
+                throw err;
+            // warn: skip this file silently.
+        }
+    }
+    // Flatten: deny entries from all files, then allow, then ask.
+    // Index numbering is sequential across the entire chain.
+    let index = 0;
+    const deny = flattenEntries(denyDocs, 'deny', index, opts);
+    index += deny.length;
+    const allow = flattenEntries(allowDocs, 'allow', index, opts);
+    index += allow.length;
+    const ask = flattenEntries(askDocs, 'ask', index, opts);
+    return {
+        defaultAction: entries.length > 0 ? entries[0].doc.defaultAction : 'ask',
+        deny,
+        allow,
+        ask,
+        caseInsensitivePaths: opts.caseInsensitivePaths ?? false,
+    };
+}
+/**
+ * Flatten a list of PermissionDocs into a single list of CompiledRuleEntry
+ * for a specific action partition.
+ *
+ * Every entry goes through `compileRuleEntry` — the exact compiler the
+ * single-file path uses. Building entries by hand here previously left
+ * `tools`/`command`/`args`/`paths` as empty arrays, and an empty dimension
+ * means "no constraint", so EVERY entry matched EVERY call: the first deny
+ * entry denied everything in its partition and the first allow entry allowed
+ * everything before the `ask` partition was ever consulted.
+ */
+function flattenEntries(docs, action, startIndex, opts) {
+    const result = [];
+    let idx = startIndex;
+    for (const doc of docs) {
+        const list = action === 'deny' ? doc.deny : action === 'allow' ? doc.allow : doc.ask;
+        for (const entry of list) {
+            result.push(compileRuleEntry(entry, action, idx++, opts));
+        }
+    }
+    return result;
+}
+// ─── Cache management ──────────────────────────────────────────────────────
+/**
+ * Get or create a compiled ruleset from the cache.
+ * Returns the cached version if the hash matches; otherwise compiles fresh.
+ */
+export function cachedCompile(text, opts = {}) {
+    const hash = hashText(text);
+    const cached = compileCache.get(hash);
+    if (cached !== undefined)
+        return cached;
+    const doc = parsePermissionsDocument(text);
+    const compiled = compileDocument(doc, opts);
+    compileCache.set(hash, compiled);
+    return compiled;
+}
+/** Clear the compile cache (used in tests and on reload). */
+export function clearCompileCache() {
+    compileCache.clear();
+}
+/** Current compile cache size (diagnostics). */
+export function compileCacheSize() {
+    return compileCache.size;
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function existsSafe(path) {
+    try {
+        return existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}
+function statSafe(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/rule-dims.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Extended rule dimensions for dsh-perm-gate.
+ *
+ * These 6 dimensions extend the existing 4 (tools/command/args/paths) and are
+ * parsed from each rule entry in the YAML permissions document. All types are
+ * pure — no I/O — so parsing and validation are unit-testable.
+ *
+ * Dimensions:
+ *   1. params   — key→value glob matching (AND over keys, `!` prefix negates)
+ *   2. absent   — parameter keys that must NOT be present
+ *   3. agents   — agent identity candidates (main/subagent/preset:<name>)
+ *   4. when     — environment / platform conditions
+ *   5. argv     — extra argv patterns (pipeline, etc.) not covered by command/args
+ *   6. network  — domain / IP / port / scheme matching
+ */
+/**
+ * One parameter match condition: a key name mapped to a list of value glob
+ * patterns. The key's actual value must match at least one pattern (OR within
+ * the list). All keys must match (AND across keys).
+ *
+ * A pattern prefixed with `!` is negated: the value must NOT match the
+ * remainder of the pattern.
+ */
+export interface ParamCondition {
+    /** The parameter key name (e.g. `command`, `flags.mode`). */
+    readonly key: string;
+    /** Value glob patterns; `!` prefix = negation. Empty list = key must exist (any value). */
+    readonly patterns: readonly string[];
+    /** Whether this condition is a negation (derived from `!` prefix on the sole pattern). */
+    readonly negated: boolean;
+}
+/**
+ * Parsed `params` dimension: a list of key→value conditions evaluated as AND.
+ */
+export type ParamsDimension = readonly ParamCondition[];
+/**
+ * Parse the `params` field from a rule entry.
+ *
+ * Format:
+ * ```yaml
+ * params:
+ *   command: ["*--force*", "!*--dry-run*"]
+ *   flags.mode: ["production"]
+ * ```
+ *
+ * Each key maps to a string-or-list of value glob patterns.
+ * A single `!`-prefixed pattern sets `negated: true`.
+ */
+export declare function parseParamsDimension(raw: unknown, at: string): ParamsDimension;
+/**
+ * Parsed `absent` dimension: parameter keys that must NOT be present
+ * in the tool call arguments. AND semantics — all listed keys must be absent.
+ */
+export type AbsentDimension = readonly string[];
+/**
+ * Parse the `absent` field: a list of parameter key names that must be absent.
+ */
+export declare function parseAbsentDimension(raw: unknown, at: string): AbsentDimension;
+/**
+ * Parsed `agents` dimension: identity candidates the rule applies to.
+ * Supported values: `main`, `subagent`, `preset:<name>`.
+ * Empty = this rule does not constrain on agent identity.
+ */
+export type AgentsDimension = readonly string[];
+/**
+ * Parse the `agents` field: a list of agent identity patterns.
+ */
+export declare function parseAgentsDimension(raw: unknown, at: string): AgentsDimension;
+/**
+ * Parsed `when` dimension: environment and platform conditions.
+ * All conditions are AND — every listed condition must be satisfied.
+ */
+export interface WhenDimension {
+    /** Required environment variable values. Key = env var name, value = allowed values (OR). */
+    readonly env?: Readonly<Record<string, readonly string[]>>;
+    /** Required platform(s). Values are Node.js `process.platform` strings. */
+    readonly platform?: readonly string[];
+    /** Required Node.js version range (semver-like). Reserved for future use. */
+    readonly nodeVersion?: string;
+}
+/**
+ * Parse the `when` field: environment and platform conditions.
+ *
+ * Format:
+ * ```yaml
+ * when:
+ *   env:
+ *     NODE_ENV: ["production"]
+ *     CI: ["true", "1"]
+ *   platform: [linux, win32]
+ * ```
+ */
+export declare function parseWhenDimension(raw: unknown, at: string): WhenDimension | undefined;
+/**
+ * Parsed `argv` dimension: extra argv patterns not covered by command/args.
+ * Currently supports `pipeline` patterns (pipe chains like `curl|sh`).
+ */
+export interface ArgvDimension {
+    /** Pipeline patterns: match the full command pipeline string. */
+    readonly pipeline?: readonly string[];
+}
+/**
+ * Parse the `argv` field: extra argv patterns.
+ *
+ * Format:
+ * ```yaml
+ * argv:
+ *   pipeline: ["curl|sh", "wget|bash"]
+ * ```
+ */
+export declare function parseArgvDimension(raw: unknown, at: string): ArgvDimension | undefined;
+/**
+ * Parsed `network` dimension: domain / IP / port / scheme matching.
+ * All sub-dimensions are AND — every listed sub-dimension must match.
+ * Within a sub-dimension, entries are OR.
+ */
+export interface NetworkDimension {
+    /** Domain patterns (glob-capable, e.g. `*.internal.corp`). */
+    readonly domains?: readonly string[];
+    /** IP/CIDR patterns (e.g. `10.0.0.0/8`, `192.168.1.1`). */
+    readonly ips?: readonly string[];
+    /** Port patterns (e.g. `443`, `8000-9000`). */
+    readonly ports?: readonly string[];
+    /** URL schemes (e.g. `https`, `http`). */
+    readonly schemes?: readonly string[];
+}
+/**
+ * Parse the `network` field: domain / IP / port / scheme matching.
+ *
+ * Format:
+ * ```yaml
+ * network:
+ *   domains: ["*.internal.corp", "github.com"]
+ *   ips: ["10.0.0.0/8"]
+ *   ports: ["443", "8000-9000"]
+ *   schemes: [https]
+ * ```
+ */
+export declare function parseNetworkDimension(raw: unknown, at: string): NetworkDimension | undefined;
+/**
+ * Parsed `branch` dimension: git branch / remote / shared-branch matching.
+ *
+ * Sub-dimensions are AND — every present sub-dimension must match. Within a
+ * sub-dimension, entries are OR.
+ *
+ * The candidates come from `dispatchCommand` (see `src/command-dispatcher.ts`)
+ * over each decomposed simple command, so `refspec` forms (`HEAD:main`) are
+ * already split and a remote name is never mistaken for a branch name.
+ *
+ * `shared` is **static**: it reflects the parser's protected-branch rule
+ * (`PROTECTED_BRANCHES` in `src/parsers/git.ts`: main / master / production /
+ * release / stable). It does **not** run git to discover whether a branch is
+ * genuinely shared — that would put a subprocess on the decision path.
+ */
+export interface BranchDimension {
+    /** Branch-name globs (e.g. `main`, `release*`). */
+    readonly target?: readonly string[];
+    /** Remote-name globs (e.g. `origin`, `upstream`). */
+    readonly remote?: readonly string[];
+    /** Require the command to target a protected branch. */
+    readonly shared?: boolean;
+}
+/**
+ * Parse the `branch` field: branch / remote / protected-branch matching.
+ *
+ * Format:
+ * ```yaml
+ * branch:
+ *   target: [main, "release*"]
+ *   remote: [origin]
+ *   shared: true
+ * ```
+ */
+export declare function parseBranchDimension(raw: unknown, at: string): BranchDimension | undefined;

package/lib/rule-dims.js

@@ -0,0 +1,230 @@
+/**
+ * Extended rule dimensions for dsh-perm-gate.
+ *
+ * These 6 dimensions extend the existing 4 (tools/command/args/paths) and are
+ * parsed from each rule entry in the YAML permissions document. All types are
+ * pure — no I/O — so parsing and validation are unit-testable.
+ *
+ * Dimensions:
+ *   1. params   — key→value glob matching (AND over keys, `!` prefix negates)
+ *   2. absent   — parameter keys that must NOT be present
+ *   3. agents   — agent identity candidates (main/subagent/preset:<name>)
+ *   4. when     — environment / platform conditions
+ *   5. argv     — extra argv patterns (pipeline, etc.) not covered by command/args
+ *   6. network  — domain / IP / port / scheme matching
+ */
+import { RuleError } from './rule.js';
+/**
+ * Parse the `params` field from a rule entry.
+ *
+ * Format:
+ * ```yaml
+ * params:
+ *   command: ["*--force*", "!*--dry-run*"]
+ *   flags.mode: ["production"]
+ * ```
+ *
+ * Each key maps to a string-or-list of value glob patterns.
+ * A single `!`-prefixed pattern sets `negated: true`.
+ */
+export function parseParamsDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new RuleError(`${at}.params must be a mapping`);
+    }
+    const result = [];
+    for (const [key, val] of Object.entries(raw)) {
+        if (key.length === 0)
+            throw new RuleError(`${at}.params has empty key`);
+        const patterns = toStringList(val, `${at}.params.${key}`);
+        const negated = patterns.length === 1 && patterns[0].startsWith('!');
+        result.push({ key, patterns, negated });
+    }
+    return result;
+}
+/**
+ * Parse the `absent` field: a list of parameter key names that must be absent.
+ */
+export function parseAbsentDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return [];
+    const list = toStringList(raw, `${at}.absent`);
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].length === 0)
+            throw new RuleError(`${at}.absent[${i}] must be a non-empty string`);
+    }
+    return list;
+}
+const VALID_AGENT_PATTERNS = /^(?:main|subagent|preset:.+)$/i;
+/**
+ * Parse the `agents` field: a list of agent identity patterns.
+ */
+export function parseAgentsDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return [];
+    const list = toStringList(raw, `${at}.agents`);
+    for (let i = 0; i < list.length; i++) {
+        const v = list[i];
+        if (v.length === 0)
+            throw new RuleError(`${at}.agents[${i}] must be a non-empty string`);
+        if (!VALID_AGENT_PATTERNS.test(v)) {
+            throw new RuleError(`${at}.agents[${i}] must be "main", "subagent", or "preset:<name>"`);
+        }
+    }
+    return list;
+}
+/**
+ * Parse the `when` field: environment and platform conditions.
+ *
+ * Format:
+ * ```yaml
+ * when:
+ *   env:
+ *     NODE_ENV: ["production"]
+ *     CI: ["true", "1"]
+ *   platform: [linux, win32]
+ * ```
+ */
+export function parseWhenDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new RuleError(`${at}.when must be a mapping`);
+    }
+    const obj = raw;
+    const env_ = (() => {
+        if (obj.env === undefined)
+            return undefined;
+        if (typeof obj.env !== 'object' || Array.isArray(obj.env)) {
+            throw new RuleError(`${at}.when.env must be a mapping`);
+        }
+        const e = {};
+        for (const [k, v] of Object.entries(obj.env)) {
+            e[k] = toStringList(v, `${at}.when.env.${k}`);
+        }
+        return e;
+    })();
+    const platform_ = obj.platform !== undefined ? toStringList(obj.platform, `${at}.when.platform`) : undefined;
+    const nodeVersion_ = obj.nodeVersion !== undefined
+        ? (typeof obj.nodeVersion === 'string' && obj.nodeVersion.length > 0
+            ? obj.nodeVersion
+            : (() => { throw new RuleError(`${at}.when.nodeVersion must be a non-empty string`); })())
+        : undefined;
+    if (env_ === undefined && platform_ === undefined && nodeVersion_ === undefined)
+        return undefined;
+    const result = {
+        ...(env_ !== undefined && { env: env_ }),
+        ...(platform_ !== undefined && { platform: platform_ }),
+        ...(nodeVersion_ !== undefined && { nodeVersion: nodeVersion_ }),
+    };
+    return result;
+}
+/**
+ * Parse the `argv` field: extra argv patterns.
+ *
+ * Format:
+ * ```yaml
+ * argv:
+ *   pipeline: ["curl|sh", "wget|bash"]
+ * ```
+ */
+export function parseArgvDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new RuleError(`${at}.argv must be a mapping`);
+    }
+    const obj = raw;
+    const pipeline_ = obj.pipeline !== undefined ? toStringList(obj.pipeline, `${at}.argv.pipeline`) : undefined;
+    if (pipeline_ === undefined)
+        return undefined;
+    return { pipeline: pipeline_ };
+}
+/**
+ * Parse the `network` field: domain / IP / port / scheme matching.
+ *
+ * Format:
+ * ```yaml
+ * network:
+ *   domains: ["*.internal.corp", "github.com"]
+ *   ips: ["10.0.0.0/8"]
+ *   ports: ["443", "8000-9000"]
+ *   schemes: [https]
+ * ```
+ */
+export function parseNetworkDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new RuleError(`${at}.network must be a mapping`);
+    }
+    const obj = raw;
+    const domains_ = obj.domains !== undefined ? toStringList(obj.domains, `${at}.network.domains`) : undefined;
+    const ips_ = obj.ips !== undefined ? toStringList(obj.ips, `${at}.network.ips`) : undefined;
+    const ports_ = obj.ports !== undefined ? toStringList(obj.ports, `${at}.network.ports`) : undefined;
+    const schemes_ = obj.schemes !== undefined ? toStringList(obj.schemes, `${at}.network.schemes`) : undefined;
+    if (domains_ === undefined && ips_ === undefined && ports_ === undefined && schemes_ === undefined)
+        return undefined;
+    const result = {
+        ...(domains_ !== undefined && { domains: domains_ }),
+        ...(ips_ !== undefined && { ips: ips_ }),
+        ...(ports_ !== undefined && { ports: ports_ }),
+        ...(schemes_ !== undefined && { schemes: schemes_ }),
+    };
+    return result;
+}
+/**
+ * Parse the `branch` field: branch / remote / protected-branch matching.
+ *
+ * Format:
+ * ```yaml
+ * branch:
+ *   target: [main, "release*"]
+ *   remote: [origin]
+ *   shared: true
+ * ```
+ */
+export function parseBranchDimension(raw, at) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new RuleError(`${at}.branch must be a mapping`);
+    }
+    const obj = raw;
+    const unknownKeys = Object.keys(obj).filter((k) => k !== 'target' && k !== 'remote' && k !== 'shared');
+    if (unknownKeys.length > 0) {
+        throw new RuleError(`${at}.branch unknown field${unknownKeys.length > 1 ? 's' : ''} ${unknownKeys.map((k) => JSON.stringify(k)).join(', ')} (expected target / remote / shared)`);
+    }
+    const target_ = obj.target !== undefined ? toStringList(obj.target, `${at}.branch.target`) : undefined;
+    const remote_ = obj.remote !== undefined ? toStringList(obj.remote, `${at}.branch.remote`) : undefined;
+    if (obj.shared !== undefined && typeof obj.shared !== 'boolean') {
+        throw new RuleError(`${at}.branch.shared must be a boolean`);
+    }
+    const shared_ = obj.shared;
+    if (target_ === undefined && remote_ === undefined && shared_ === undefined)
+        return undefined;
+    return {
+        ...(target_ !== undefined && { target: target_ }),
+        ...(remote_ !== undefined && { remote: remote_ }),
+        ...(shared_ !== undefined && { shared: shared_ }),
+    };
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+/** Convert an unknown value to a string list (string → [string], array → filtered). */
+function toStringList(value, at) {
+    if (value === undefined || value === null)
+        return [];
+    const list = typeof value === 'string' ? [value] : value;
+    if (!Array.isArray(list))
+        throw new RuleError(`${at} must be a string or list of strings`);
+    const result = [];
+    for (let i = 0; i < list.length; i++) {
+        const item = list[i];
+        if (typeof item !== 'string' || item.length === 0) {
+            throw new RuleError(`${at}[${i}] must be a non-empty string`);
+        }
+        result.push(item);
+    }
+    return result;
+}