dsh-perm-gate 2.1.0 → 2.6.1

package/lib/rule.d.ts

@@ -1,4 +1,5 @@
 import { type CompiledPattern } from './compiler.js';
+import { type ParamsDimension, type AbsentDimension, type AgentsDimension, type WhenDimension, type ArgvDimension, type NetworkDimension, type BranchDimension } from './rule-dims.js';
 export type RuleAction = 'allow' | 'ask' | 'deny';
 /** A parsed, shape-validated permissions document (patterns not yet compiled). */
 export interface PermissionsDoc {
@@ -20,6 +21,20 @@ export interface RuleEntryDoc {
     readonly args: string[];
     /** Workspace-relative path globs; empty = no constraint. */
     readonly paths: string[];
+    /** Parameter key→value matching (AND over keys, `!` prefix negates). */
+    readonly params: ParamsDimension;
+    /** Parameter keys that must NOT be present. */
+    readonly absent: AbsentDimension;
+    /** Agent identity candidates (main / subagent / preset:<name>). */
+    readonly agents: AgentsDimension;
+    /** Environment / platform conditions. */
+    readonly when: WhenDimension | undefined;
+    /** Extra argv patterns (pipeline etc.). */
+    readonly argv: ArgvDimension | undefined;
+    /** Network dimension (domain / IP / port / scheme). */
+    readonly network: NetworkDimension | undefined;
+    /** Git branch / remote / protected-branch dimension. */
+    readonly branch: BranchDimension | undefined;
     readonly action: RuleAction;
     readonly reason: string;
     readonly enabled: boolean;
@@ -34,8 +49,28 @@ export interface CompiledRuleEntry {
     readonly command: readonly CommandSpec[];
     readonly args: readonly CompiledPattern[];
     readonly paths: readonly CompiledPattern[];
+    /** Parsed params dimension (raw patterns; compiled on match). */
+    readonly params: ParamsDimension;
+    /** Parsed absent dimension (raw key names). */
+    readonly absent: AbsentDimension;
+    /** Parsed agents dimension (raw patterns). */
+    readonly agents: AgentsDimension;
+    /** Parsed when dimension (raw conditions). */
+    readonly when: WhenDimension | undefined;
+    /** Parsed argv dimension (raw patterns). */
+    readonly argv: ArgvDimension | undefined;
+    /** Parsed network dimension (raw patterns). */
+    readonly network: NetworkDimension | undefined;
+    /** Compiled branch dimension (patterns compiled; absent = no constraint). */
+    readonly branch: CompiledBranchDimension | undefined;
     readonly source: RuleEntryDoc;
 }
+/** Compiled `branch` dimension: `target`/`remote` globs, raw `shared` flag. */
+export interface CompiledBranchDimension {
+    readonly target: readonly CompiledPattern[];
+    readonly remote: readonly CompiledPattern[];
+    readonly shared: boolean;
+}
 export interface CommandSpec {
     readonly word: CompiledPattern;
     readonly flag?: 'recursive' | 'force';
@@ -56,8 +91,33 @@ export declare class RuleError extends Error {
 }
 /** Parse a raw YAML permissions document; malformed files fail loud at load. */
 export declare function parsePermissionsDocument(text: string): PermissionsDoc;
+/**
+ * Parse a permissions document given as an already-parsed object — the shape
+ * the DSH settings namespace stores (the JSON twin of the YAML file). Accepts
+ * both the bare `{ defaultAction, deny, allow, ask }` form and the file's
+ * `permissions:`-wrapped form. Malformed input fails loud, exactly like the
+ * YAML path, so a settings doc that cannot compile is a state the operator
+ * sees, never a silent ruleset change.
+ */
+export declare function parsePermissionsObject(raw: unknown): PermissionsDoc;
+/**
+ * Compile one parsed entry into a hot-path rule.
+ *
+ * Exported because the multi-file rule chain (`rule-chain.ts`) merges entries
+ * from several documents into one ruleset and must produce the SAME shape here
+ * — an entry built by hand would silently drop every compiled dimension, and an
+ * empty dimension means "no constraint", i.e. "matches everything".
+ */
+export declare function compileRuleEntry(entry: RuleEntryDoc, action: RuleAction, index: number, opts?: CompileOptions): CompiledRuleEntry;
 /** Compile a validated document into hot-path rules. */
 export declare function compileDocument(doc: PermissionsDoc, opts?: CompileOptions): CompiledRuleset;
+/**
+ * Compile rules given as a structured settings object (already parsed — no
+ * YAML in the loop). The settings-first half of the dual-source read path:
+ * `parsePermissionsObject` validates the JSON form exactly as strictly as the
+ * YAML path, then the standard `compileDocument` runs.
+ */
+export declare function compileRulesObject(root: unknown, opts?: CompileOptions): CompiledRuleset;
 /** SHA-256 hash of the raw document (compile-cache key without recompiling). */
 export declare function documentHash(text: string): string;
 export declare function extractPathCandidates(args: Record<string, unknown>): string[];

package/lib/rule.js

@@ -9,7 +9,8 @@
  * nothing matches, `defaultAction` applies.
  */
 import { parse } from 'yaml';
-import { compileGlob, hashText } from './compiler.js';
+import { compileGlob, compileBranchPattern, hashText } from './compiler.js';
+import { parseParamsDimension, parseAbsentDimension, parseAgentsDimension, parseWhenDimension, parseArgvDimension, parseNetworkDimension, parseBranchDimension, } from './rule-dims.js';
 const VALID_ACTIONS = ['allow', 'ask', 'deny'];
 const PATH_CANDIDATE_KEYS = [
     'path', 'paths', 'file', 'files', 'file_path', 'dir', 'directory', 'directories',
@@ -53,6 +54,17 @@ export function parsePermissionsDocument(text) {
     catch (error) {
         throw new RuleError(`invalid YAML: ${String(error)}`);
     }
+    return parsePermissionsObject(raw);
+}
+/**
+ * Parse a permissions document given as an already-parsed object — the shape
+ * the DSH settings namespace stores (the JSON twin of the YAML file). Accepts
+ * both the bare `{ defaultAction, deny, allow, ask }` form and the file's
+ * `permissions:`-wrapped form. Malformed input fails loud, exactly like the
+ * YAML path, so a settings doc that cannot compile is a state the operator
+ * sees, never a silent ruleset change.
+ */
+export function parsePermissionsObject(raw) {
     if (raw === null || raw === undefined) {
         return { defaultAction: 'ask', deny: [], allow: [], ask: [] };
     }
@@ -82,7 +94,8 @@ export function parsePermissionsDocument(text) {
 function parseRuleEntry(raw, action, at) {
     if (!isRecord(raw))
         throw new RuleError(`${at} must be a mapping`);
-    const unknown = Object.keys(raw).filter((k) => !['tools', 'command', 'args', 'paths', 'action', 'reason', 'enabled'].includes(k));
+    const VALID_KEYS = ['tools', 'command', 'args', 'paths', 'params', 'absent', 'agents', 'when', 'argv', 'network', 'branch', 'action', 'reason', 'enabled'];
+    const unknown = Object.keys(raw).filter((k) => !VALID_KEYS.includes(k));
     if (unknown.length > 0) {
         throw new RuleError(`${at} unknown field${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => JSON.stringify(k)).join(', ')}`);
     }
@@ -98,6 +111,13 @@ function parseRuleEntry(raw, action, at) {
         command: stringList(raw.command, `${at}.command`),
         args: stringList(raw.args, `${at}.args`),
         paths: stringList(raw.paths, `${at}.paths`),
+        params: parseParamsDimension(raw.params, `${at}.params`),
+        absent: parseAbsentDimension(raw.absent, `${at}.absent`),
+        agents: parseAgentsDimension(raw.agents, `${at}.agents`),
+        when: parseWhenDimension(raw.when, `${at}.when`),
+        argv: parseArgvDimension(raw.argv, `${at}.argv`),
+        network: parseNetworkDimension(raw.network, `${at}.network`),
+        branch: parseBranchDimension(raw.branch, `${at}.branch`),
         action,
         reason: reason === undefined ? `${action}` : reason,
         enabled: raw.enabled === undefined ? true : typeof raw.enabled === 'boolean' ? raw.enabled : (() => { throw new RuleError(`${at}.enabled must be a boolean`); })(),
@@ -133,10 +153,32 @@ function compileCommand(entry, opts) {
     }
     return { word: compileGlob(word, { segments: false, maxStars: opts.maxGlobStars ?? 2 }), flag };
 }
-/** Compile a validated document into hot-path rules. */
-export function compileDocument(doc, opts = {}) {
-    const comp = (list, action, offset) => list.map((entry, i) => ({
-        index: offset + i,
+/**
+ * Compile the `branch` dimension (undefined = the rule does not constrain on it).
+ *
+ * Glob degree is bounded inside `compileBranchPattern` (DEFAULT_MAX_STARS), so
+ * this takes no options: branch patterns are never path-segmented.
+ */
+function compileBranchDimension(dim) {
+    if (dim === undefined)
+        return undefined;
+    return {
+        target: (dim.target ?? []).map((p) => compileBranchPattern(p)),
+        remote: (dim.remote ?? []).map((p) => compileBranchPattern(p)),
+        shared: dim.shared === true,
+    };
+}
+/**
+ * Compile one parsed entry into a hot-path rule.
+ *
+ * Exported because the multi-file rule chain (`rule-chain.ts`) merges entries
+ * from several documents into one ruleset and must produce the SAME shape here
+ * — an entry built by hand would silently drop every compiled dimension, and an
+ * empty dimension means "no constraint", i.e. "matches everything".
+ */
+export function compileRuleEntry(entry, action, index, opts = {}) {
+    return {
+        index,
         action,
         reason: entry.reason,
         enabled: entry.enabled,
@@ -144,8 +186,19 @@ export function compileDocument(doc, opts = {}) {
         command: entry.command.map((c) => compileCommand(c, opts)),
         args: compilePatternList(entry.args, 'args', opts),
         paths: compilePatternList(entry.paths, 'paths', opts),
+        params: entry.params,
+        absent: entry.absent,
+        agents: entry.agents,
+        when: entry.when,
+        argv: entry.argv,
+        network: entry.network,
+        branch: compileBranchDimension(entry.branch),
         source: entry,
-    }));
+    };
+}
+/** Compile a validated document into hot-path rules. */
+export function compileDocument(doc, opts = {}) {
+    const comp = (list, action, offset) => list.map((entry, i) => compileRuleEntry(entry, action, offset + i, opts));
     return {
         defaultAction: doc.defaultAction,
         deny: comp(doc.deny, 'deny', 0),
@@ -154,6 +207,15 @@ export function compileDocument(doc, opts = {}) {
         caseInsensitivePaths: opts.caseInsensitivePaths ?? false,
     };
 }
+/**
+ * Compile rules given as a structured settings object (already parsed — no
+ * YAML in the loop). The settings-first half of the dual-source read path:
+ * `parsePermissionsObject` validates the JSON form exactly as strictly as the
+ * YAML path, then the standard `compileDocument` runs.
+ */
+export function compileRulesObject(root, opts = {}) {
+    return compileDocument(parsePermissionsObject(root), opts);
+}
 /** SHA-256 hash of the raw document (compile-cache key without recompiling). */
 export function documentHash(text) {
     return hashText(text);

package/lib/rules-view.d.ts

@@ -0,0 +1,52 @@
+import { type RuleAction } from './rule.js';
+/** Rules per action, so the panel can say "3 deny / 7 allow / 1 ask" at a glance. */
+export interface RulesViewCounts {
+    readonly allow: number;
+    readonly deny: number;
+    readonly ask: number;
+}
+/** The whole read-only face of one permissions document. */
+export interface RulesView {
+    /** Absolute path, or `''` when the gate has no rules file configured. */
+    readonly path: string;
+    readonly exists: boolean;
+    /** File size on disk, not the length of `raw` — a truncated view still reports the truth. */
+    readonly bytes: number;
+    /** Content hash of the text the gate would load, for correlating with a reload. */
+    readonly hash: string;
+    readonly lines: number;
+    /** The document itself. Empty when absent, unreadable, or truncated away. */
+    readonly raw: string;
+    readonly truncated: boolean;
+    /** Parsed only when the document compiled; absent when it did not. */
+    readonly defaultAction?: RuleAction;
+    readonly counts: RulesViewCounts;
+    /** Why the document could not be shown or parsed. Absent when all is well. */
+    readonly error?: string;
+    /** Where the rules were read from. Absent on views produced before the settings migration. */
+    readonly source?: 'file' | 'settings';
+    /** The structured rules object the settings namespace stores (settings source only). */
+    readonly rules?: unknown;
+}
+/**
+ * Read one permissions document for display.
+ *
+ * Never throws: a missing, unreadable or malformed file is a state the panel has
+ * to render, not an error that should blank the section. Every failure mode is
+ * reported in the returned value instead.
+ */
+export declare function readRulesView(rulesFile: string): RulesView;
+/** The pseudo-path a settings view reports (there is no file to name). */
+export declare const SETTINGS_RULES_VIEW_PATH = "settings:dsh-perm-gate-rules";
+/**
+ * Render the settings-sourced rules for display — the read-only face of the
+ * `dsh-perm-gate-rules` namespace, the twin of {@link readRulesView}.
+ *
+ * The YAML rendering of the structured object fills `raw`, so the settings card
+ * shows the document in the same format the file view used; `rules` carries the
+ * structured object itself and `source: 'settings'` states the provenance.
+ *
+ * Never throws: a doc that fails `compileRulesObject` is a state the panel has
+ * to render (the `error` field), not an error that should blank the section.
+ */
+export declare function readRulesViewFromSettings(rules: unknown): RulesView;

package/lib/rules-view.js

@@ -0,0 +1,126 @@
+/**
+ * Reading the permissions YAML, for the panel that shows it.
+ *
+ * The card could already WRITE the rules file — the allowlist section appends
+ * and replaces patterns, and `index.ts` mirrors those edits back into the
+ * document. Nothing could read it back, so an operator editing patterns through
+ * the panel had no way to see the document they were editing: the file the gate
+ * actually loads was invisible from the UI.
+ *
+ * This is the missing read half. It is deliberately **read-only** — a view must
+ * never be able to change the ruleset it is describing, or "let me look at the
+ * rules" becomes a risky action. Writing stays where it already lives
+ * (`allowlist.ts`, the settings namespace).
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { stringify } from 'yaml';
+import { RuleError, compileDocument, compileRulesObject, documentHash, parsePermissionsDocument } from './rule.js';
+/** Beyond this the panel would be rendering a log, not a rules file. */
+const MAX_VIEW_BYTES = 512 * 1024;
+const NO_COUNTS = { allow: 0, deny: 0, ask: 0 };
+/**
+ * Read one permissions document for display.
+ *
+ * Never throws: a missing, unreadable or malformed file is a state the panel has
+ * to render, not an error that should blank the section. Every failure mode is
+ * reported in the returned value instead.
+ */
+export function readRulesView(rulesFile) {
+    if (rulesFile === '') {
+        return {
+            path: '', exists: false, bytes: 0, hash: '', lines: 0, raw: '', truncated: false,
+            counts: NO_COUNTS, error: 'no rules file is configured',
+        };
+    }
+    let bytes = 0;
+    let exists = true;
+    try {
+        bytes = statSync(rulesFile).size;
+    }
+    catch {
+        exists = false;
+    }
+    let raw = '';
+    try {
+        raw = readFileSync(rulesFile, 'utf8');
+    }
+    catch (e) {
+        return {
+            path: rulesFile, exists, bytes, hash: '', lines: 0, raw: '', truncated: false,
+            counts: NO_COUNTS,
+            error: exists ? `unreadable: ${String(e?.message ?? e)}` : 'file does not exist',
+        };
+    }
+    const lines = raw === '' ? 0 : raw.split('\n').length;
+    const truncated = raw.length > MAX_VIEW_BYTES;
+    const shown = truncated ? raw.slice(0, MAX_VIEW_BYTES) : raw;
+    // Parsing is what makes the view worth having: a YAML file that loads as text
+    // but not as rules is exactly the failure the panel exists to expose.
+    try {
+        const doc = parsePermissionsDocument(raw);
+        const ruleset = compileDocument(doc);
+        return {
+            path: rulesFile, exists: true, bytes, hash: documentHash(raw), lines,
+            raw: shown, truncated,
+            defaultAction: ruleset.defaultAction,
+            counts: { allow: ruleset.allow.length, deny: ruleset.deny.length, ask: ruleset.ask.length },
+            source: 'file',
+        };
+    }
+    catch (e) {
+        const detail = e instanceof RuleError ? e.message : String(e?.message ?? e);
+        return {
+            path: rulesFile, exists: true, bytes, hash: documentHash(raw), lines,
+            raw: shown, truncated,
+            counts: NO_COUNTS,
+            error: `does not compile: ${detail}`,
+            source: 'file',
+        };
+    }
+}
+/** The pseudo-path a settings view reports (there is no file to name). */
+export const SETTINGS_RULES_VIEW_PATH = 'settings:dsh-perm-gate-rules';
+/**
+ * Render the settings-sourced rules for display — the read-only face of the
+ * `dsh-perm-gate-rules` namespace, the twin of {@link readRulesView}.
+ *
+ * The YAML rendering of the structured object fills `raw`, so the settings card
+ * shows the document in the same format the file view used; `rules` carries the
+ * structured object itself and `source: 'settings'` states the provenance.
+ *
+ * Never throws: a doc that fails `compileRulesObject` is a state the panel has
+ * to render (the `error` field), not an error that should blank the section.
+ */
+export function readRulesViewFromSettings(rules) {
+    let raw = '';
+    try {
+        raw = stringify(rules ?? {});
+    }
+    catch {
+        raw = '';
+    }
+    const lines = raw === '' ? 0 : raw.split('\n').length;
+    const hash = documentHash(JSON.stringify(rules ?? {}));
+    try {
+        const ruleset = compileRulesObject(rules);
+        return {
+            path: SETTINGS_RULES_VIEW_PATH, exists: true, bytes: raw.length, hash, lines,
+            raw, truncated: false,
+            defaultAction: ruleset.defaultAction,
+            counts: { allow: ruleset.allow.length, deny: ruleset.deny.length, ask: ruleset.ask.length },
+            source: 'settings',
+            rules,
+        };
+    }
+    catch (e) {
+        const detail = e instanceof RuleError ? e.message : String(e?.message ?? e);
+        return {
+            path: SETTINGS_RULES_VIEW_PATH, exists: true, bytes: raw.length, hash, lines,
+            raw, truncated: false,
+            counts: NO_COUNTS,
+            error: `does not compile: ${detail}`,
+            source: 'settings',
+            rules,
+        };
+    }
+}