dsh-perm-gate 2.1.2 → 3.0.1

package/lib/rule.js

@@ -9,8 +9,8 @@
  * nothing matches, `defaultAction` applies.
  */
 import { parse } from 'yaml';
-import { compileGlob, hashText } from './compiler.js';
-import { parseParamsDimension, parseAbsentDimension, parseAgentsDimension, parseWhenDimension, parseArgvDimension, parseNetworkDimension, } from './rule-dims.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',
@@ -54,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: [] };
     }
@@ -83,7 +94,7 @@ export function parsePermissionsDocument(text) {
 function parseRuleEntry(raw, action, at) {
     if (!isRecord(raw))
         throw new RuleError(`${at} must be a mapping`);
-    const VALID_KEYS = ['tools', 'command', 'args', 'paths', 'params', 'absent', 'agents', 'when', 'argv', 'network', 'action', 'reason', 'enabled'];
+    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(', ')}`);
@@ -106,6 +117,7 @@ function parseRuleEntry(raw, action, at) {
         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`); })(),
@@ -141,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,
@@ -158,8 +192,13 @@ export function compileDocument(doc, opts = {}) {
         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),
@@ -168,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,
+        };
+    }
+}

package/lib/runtime.d.ts

@@ -1,17 +1,42 @@
-import { type AuditEntry } from './audit.js';
-import { type PermGateConfig, type PermissiveStrategies } from './config.js';
+import { type AuditEntry, type DecisionSource } from './audit.js';
+import { type PermGateConfig, type PermissiveStrategies, type RulesConfig } from './config.js';
 import type { ClassifierConfig } from './classifier.js';
 import { EventLog } from './events.js';
 import { RiskLearning } from './learning.js';
 import { type RiskRequest, type RiskVerdict } from './risk.js';
 import { type HostLlmLike, type HostModelSelection } from './host-llm.js';
-import { type CompiledRuleset } from './rule.js';
+import { type CompiledRuleEntry, type CompiledRuleset, type RuleAction } from './rule.js';
 import type { NetworkTarget } from './network.js';
 import { type SessionEventLike } from './preset.js';
 export interface PreToolDecisionLike {
     kind: 'deny' | 'ask';
     reason: string;
 }
+/**
+ * The P2 rule chain's own verdict for one call, as reported by
+ * {@link PermGateRuntime.explainRules}. Distinct from the gate's effective
+ * verdict: a P0 hard-deny or a preset deny-keyword fires *before* this layer and
+ * never leaves a rule index behind, so a differing pair is information rather
+ * than a contradiction.
+ */
+export interface RuleExplanation {
+    readonly action: RuleAction;
+    readonly reason: string;
+    readonly ruleIndex: number | undefined;
+    readonly rule: CompiledRuleEntry | undefined;
+    readonly defaultAction: RuleAction;
+}
+/**
+ * The pure policy outcome for one call, as reported by
+ * {@link PermGateRuntime.explainCall}. Same chain as the host-facing decision,
+ * minus every side effect and minus the session-state layers.
+ */
+export interface CallExplanation {
+    readonly action: RuleAction;
+    readonly reason: string;
+    readonly source: DecisionSource | 'deny-keyword' | 'cleanup-safe';
+    readonly ruleIndex?: number;
+}
 export interface ToolExecutionLike {
     readonly name: string;
     readonly arguments: Record<string, unknown>;
@@ -153,6 +178,24 @@ export interface PermGateRuntimeOptions extends PermGateConfig {
      * Default 30 minutes.
      */
     readonly networkGrantTtlMs?: number;
+    /**
+     * Live settings-sourced rules document (the `dsh-perm-gate-rules` namespace),
+     * read on every (re)compile. When it carries a real configuration — entries or
+     * a non-default `defaultAction` — it takes precedence over `rulesFile` and the
+     * rule chain (settings first, file fallback); `undefined` means "namespace
+     * still at bare defaults", and the file paths run unchanged.
+     */
+    readonly readRulesDocument?: () => RulesConfig | undefined;
+    /**
+     * Settings-backed allowlist writer. When wired (the settings service is
+     * available), {@link approveAllowEverywhere} / {@link setAllowlist} go through
+     * it instead of rewriting the rules file; a falsy verdict (no scope, rejected
+     * write) falls back to the file path.
+     */
+    readonly allowlistWriter?: {
+        readonly append: (pattern: string, reason: string) => boolean;
+        readonly replace: (patterns: readonly string[], reason: string) => boolean;
+    };
 }
 export type CallDecision = 'allow' | 'deny' | 'ask';
 /** The effective Permissive tier state read per tool call. */
@@ -227,6 +270,12 @@ export declare class PermGateRuntime {
      * frozen events, which would otherwise re-fold on every tool call.
      */
     private presetCache;
+    /**
+     * Last stand-down announced per session (sessionId → the out-of-scope preset
+     * name, `''` when the session records none). Bounded by the session count and
+     * only read on the stand-down path — the in-scope path never touches it.
+     */
+    private readonly standDownAnnounced;
     private readonly learning;
     private readonly events?;
     /** Learning candidates awaiting human approval + execution (call fingerprint → candidate). */
@@ -325,8 +374,26 @@ export declare class PermGateRuntime {
      * `danger-full-access` means "full access without approval prompts", where a
      * forwarded ask can only fail (the approval seam rejects before any answerer
      * runs) and a hard-deny would silently overrule the tier the user chose.
+     *
+     * P0 is therefore monotonic only WITHIN the gate's scope, not across every
+     * preset. {@link announceStandDown} makes that visible instead of silent.
      */
     private gateActive;
+    /**
+     * Record one `stand-down` event the first time a session is observed with a
+     * preset outside {@link gatePresets}, and again whenever that preset changes.
+     *
+     * Per-call silence is what makes a stand-down dangerous: the tool call looks
+     * exactly like a call the gate inspected and allowed. One event per
+     * transition is enough to say otherwise, and keeps the feed (and the
+     * `events.jsonl` append) proportional to preset changes rather than to call
+     * volume.
+     *
+     * The event is a NOTICE, not a decision: it carries no allow/deny meaning,
+     * and the call it was observed on is still settled entirely by the selected
+     * tier. `verdict: 'stand-down'` labels it for the history view.
+     */
+    private announceStandDown;
     /**
      * Whether an `ask` produced while the gate is active can actually reach a
      * human. Under `approval: never` the DSH approval seam returns `rejected`
@@ -405,6 +472,45 @@ export declare class PermGateRuntime {
      * the human seam.
      */
     decideExecution(exec: ToolExecutionLike): PreToolDecisionLike | undefined;
+    /**
+     * The **pure policy** outcome for one call: the same chain
+     * {@link decideExecution} runs, with every side effect and every session-state
+     * layer removed.
+     *
+     * Side effects removed — no audit entry, no event, no ask tracking, no call
+     * clearance, no learning. A rule-test panel must be able to run on every
+     * keystroke without writing to the live decision feed.
+     *
+     * Session-state layers removed — the preset stand-down and the
+     * `approval: never` ask degradation both describe a session a session-less
+     * caller does not have. Including them is not harmless: the degradation turns
+     * every "the rules would ask a human" into a reported **allow**, which is the
+     * opposite of the truth for exactly the rules someone opens the panel to
+     * review (measured on the live host: `shell ls -la` reported `allow` while the
+     * rule layer said `ask`).
+     *
+     * `reason` is never collapsed: "allow" has causes worth naming (a rule, a
+     * grant, cleanup-safety, the permissive default).
+     */
+    explainCall(exec: ToolExecutionLike): CallExplanation;
+    /**
+     * P0 hard-deny → P1 session grant → P2 rules → P4 ask, as a value. Shared by
+     * the host-facing decision and {@link explainCall} so the two cannot drift.
+     */
+    private rawPolicy;
+    /**
+     * Rule-layer explanation for one would-be call: what the `permissions` chain
+     * decides on its own, before P0 hard-deny, P1 session grants, the P3
+     * classifier and the P4 ask ever get a say.
+     *
+     * This is the read-only half of a dry-run. It appends nothing to the audit
+     * mirror, records no event, mints no grant and touches no learning store, so a
+     * "rule test" panel may call it on every keystroke without leaving a trace in
+     * the decision feed. It answers a narrower question than
+     * {@link decideExecution} and says so: `ruleIndex` identifies a rule in the
+     * chain, which only this layer can attribute.
+     */
+    explainRules(exec: ToolExecutionLike): RuleExplanation;
     /**
      * Apply the Permissive tier to a raw decision. Hard-deny and minted-grant
      * outcomes are never touched (fail-closed). `alwaysConfirm` escalates a
@@ -484,15 +590,23 @@ export declare class PermGateRuntime {
     approveRepeat(exec: ToolExecutionLike, maxUses?: number, ttlMs?: number): void;
     /**
      * Grant "allow every occurrence of this command" (the always-confirm panel's
-     * second extended allow button): persist the command into the rules file's
-     * `allow` whitelist and reload. Returns the reload result.
+     * second extended allow button): persist the command into the rules' `allow`
+     * whitelist and reload. Prefers the settings-backed writer (the namespace's
+     * watch triggers the reload once the write lands); falls back to the rules
+     * file when no settings scope is wired. Returns the write verdict.
      */
     approveAllowEverywhere(commandWord: string, reason?: string): boolean;
-    /** Read-only view of the current allow-list command patterns (whitelist). */
+    /**
+     * Read-only view of the current allow-list command patterns (whitelist).
+     * Reads the settings document when the namespace is configured, else the
+     * rules file.
+     */
     allowlist(): readonly string[];
     /**
      * Replace the whitelist with exactly the given command patterns and reload.
-     * Returns the reload result (false when no rulesFile or the write failed).
+     * Prefers the settings-backed writer; falls back to the rules file when no
+     * settings scope is wired. Returns the write verdict (false when neither
+     * sink is available or the write failed).
      */
     setAllowlist(patterns: readonly string[]): boolean;
 }