dsh-perm-gate 0.2.0

package/lib/rule.js

@@ -0,0 +1,220 @@
+/**
+ * Rule vocabulary for dsh-perm-gate: parsing a `permissions` YAML document into
+ * a validated config, compiling globs, and first-match evaluation. Every
+ * function is pure — no filesystem/clock/process state — so parsing, matching
+ * and the failure modes are unit-testable and replayable.
+ *
+ * The chain is split into `deny` / `allow` / `ask` lists. deny is evaluated
+ * first (blacklist priority); within each action list, first match wins. When
+ * nothing matches, `defaultAction` applies.
+ */
+import { parse } from 'yaml';
+import { compileGlob, hashText } from './compiler.js';
+const VALID_ACTIONS = ['allow', 'ask', 'deny'];
+const PATH_CANDIDATE_KEYS = [
+    'path', 'paths', 'file', 'files', 'file_path', 'dir', 'directory', 'directories',
+    'cwd', 'workspace', 'root', 'target', 'targets', 'output',
+];
+const URL_CANDIDATE_KEYS = ['url', 'urls', 'uri', 'endpoint', 'remote', 'repo', 'repository'];
+const COMMAND_CANDIDATE_KEYS = ['command', 'cmd', 'script', 'command_line', 'commandLine'];
+export class RuleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RuleError';
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function stringList(v, at) {
+    if (v === undefined)
+        return [];
+    const list = typeof v === 'string' ? [v] : v;
+    if (!Array.isArray(list))
+        throw new RuleError(`${at} must be a string or list of strings`);
+    return list.map((item, i) => {
+        if (typeof item !== 'string' || item.length === 0)
+            throw new RuleError(`${at}[${i}] must be a non-empty string`);
+        return item;
+    });
+}
+function actionOf(v, at) {
+    if (typeof v !== 'string' || !VALID_ACTIONS.includes(v)) {
+        throw new RuleError(`${at} action must be one of ${VALID_ACTIONS.join('|')}`);
+    }
+    return v;
+}
+/** Parse a raw YAML permissions document; malformed files fail loud at load. */
+export function parsePermissionsDocument(text) {
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch (error) {
+        throw new RuleError(`invalid YAML: ${String(error)}`);
+    }
+    if (raw === null || raw === undefined) {
+        return { defaultAction: 'ask', deny: [], allow: [], ask: [] };
+    }
+    if (!isRecord(raw))
+        throw new RuleError('permissions document must be a mapping');
+    const root = isRecord(raw.permissions) ? raw.permissions : raw;
+    const unknown = Object.keys(root).filter((k) => !VALID_ACTIONS.includes(k) && k !== 'defaultAction');
+    if (unknown.length > 0) {
+        throw new RuleError(`unknown permissions field${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => JSON.stringify(k)).join(', ')}`);
+    }
+    const defaultAction = root.defaultAction === undefined ? 'ask' : actionOf(root.defaultAction, 'defaultAction');
+    const parseList = (key, at) => {
+        const arr = root[key];
+        if (arr === undefined)
+            return [];
+        if (!Array.isArray(arr))
+            throw new RuleError(`${at}.${key} must be a list`);
+        return arr.map((item, i) => parseRuleEntry(item, key, `${at}.${key}[${i}]`));
+    };
+    return {
+        defaultAction,
+        deny: parseList('deny', 'permissions'),
+        allow: parseList('allow', 'permissions'),
+        ask: parseList('ask', 'permissions'),
+    };
+}
+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));
+    if (unknown.length > 0) {
+        throw new RuleError(`${at} unknown field${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => JSON.stringify(k)).join(', ')}`);
+    }
+    if (raw.action !== undefined && actionOf(raw.action, `${at}.action`) !== action) {
+        throw new RuleError(`${at} action conflicts with its list`);
+    }
+    const reason = raw.reason;
+    if (reason !== undefined && (typeof reason !== 'string' || reason.trim().length === 0)) {
+        throw new RuleError(`${at}.reason must be a non-empty string`);
+    }
+    return {
+        tools: stringList(raw.tools, `${at}.tools`),
+        command: stringList(raw.command, `${at}.command`),
+        args: stringList(raw.args, `${at}.args`),
+        paths: stringList(raw.paths, `${at}.paths`),
+        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`); })(),
+    };
+}
+function compilePatternList(patterns, at, opts) {
+    const stars = opts.maxGlobStars ?? 2;
+    const ci = opts.caseInsensitivePaths ?? false;
+    const desc = at.includes('paths');
+    const list = [];
+    for (const p of patterns) {
+        list.push(compileGlob(p, { segments: desc, maxStars: stars }));
+    }
+    // Case-insensitive path patterns: recompile with `i`.
+    if (ci && desc) {
+        return list.map((c) => ({ source: c.source, re: new RegExp(c.re.source, 'ui') }));
+    }
+    return list;
+}
+/** Compile one command entry (`word` or `word#flag`). */
+function compileCommand(entry, opts) {
+    const hash = entry.lastIndexOf('#');
+    let word;
+    let flag;
+    if (hash > 0 && hash < entry.length - 1) {
+        word = entry.slice(0, hash);
+        const f = entry.slice(hash + 1);
+        if (f === 'recursive' || f === 'force')
+            flag = f;
+    }
+    else {
+        word = entry;
+    }
+    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,
+        action,
+        reason: entry.reason,
+        enabled: entry.enabled,
+        tools: compilePatternList(entry.tools, 'tools', opts),
+        command: entry.command.map((c) => compileCommand(c, opts)),
+        args: compilePatternList(entry.args, 'args', opts),
+        paths: compilePatternList(entry.paths, 'paths', opts),
+        source: entry,
+    }));
+    return {
+        defaultAction: doc.defaultAction,
+        deny: comp(doc.deny, 'deny', 0),
+        allow: comp(doc.allow, 'allow', doc.deny.length),
+        ask: comp(doc.ask, 'ask', doc.deny.length + doc.allow.length),
+        caseInsensitivePaths: opts.caseInsensitivePaths ?? false,
+    };
+}
+/** SHA-256 hash of the raw document (compile-cache key without recompiling). */
+export function documentHash(text) {
+    return hashText(text);
+}
+// Candidate extraction (shared by evaluate + path rules).
+export function extractPathCandidates(args) {
+    const out = [];
+    const walk = (node, depth) => {
+        if (depth > 8)
+            return;
+        if (Array.isArray(node)) {
+            for (const e of node)
+                walk(e, depth + 1);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        for (const [k, v] of Object.entries(node)) {
+            if (PATH_CANDIDATE_KEYS.includes(k)) {
+                if (typeof v === 'string')
+                    out.push(v);
+                else if (Array.isArray(v))
+                    for (const e of v)
+                        if (typeof e === 'string')
+                            out.push(e);
+            }
+            walk(v, depth + 1);
+        }
+    };
+    walk(args, 0);
+    return out;
+}
+export function extractUrlCandidates(args) {
+    const out = [];
+    const urlRe = /https?:\/\/[^\s"'<>)\]\\]+/g;
+    const walk = (node, depth) => {
+        if (depth > 8)
+            return;
+        if (Array.isArray(node)) {
+            for (const e of node)
+                walk(e, depth + 1);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        for (const [k, v] of Object.entries(node)) {
+            if (URL_CANDIDATE_KEYS.includes(k)) {
+                if (typeof v === 'string')
+                    out.push(v);
+                else if (Array.isArray(v))
+                    for (const e of v)
+                        if (typeof e === 'string')
+                            out.push(e);
+            }
+            if (COMMAND_CANDIDATE_KEYS.includes(k) && typeof v === 'string') {
+                for (const m of v.matchAll(urlRe))
+                    out.push(m[0]);
+            }
+            walk(v, depth + 1);
+        }
+    };
+    walk(args, 0);
+    return out;
+}

package/lib/runtime.d.ts

@@ -0,0 +1,146 @@
+import { type AuditEntry } from './audit.js';
+import { type PermGateConfig, type PermissiveStrategies } 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 CompiledRuleset } from './rule.js';
+export interface PreToolDecisionLike {
+    kind: 'deny' | 'ask';
+    reason: string;
+}
+export interface ToolExecutionLike {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+    readonly commandText?: string;
+    readonly cwd?: string;
+    readonly sessionId?: string;
+    readonly parentAuthorized?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface PermGateRuntimeOptions extends PermGateConfig {
+    readonly onRulesChanged?: (ruleset: CompiledRuleset) => void;
+    readonly now?: () => number;
+    /**
+     * Test/direct-use injection replacing the HTTP risk grader. Return
+     * `unresolved` (or omit this hook) to stay on the human seam — fail-closed.
+     */
+    readonly riskHook?: (req: RiskRequest) => Promise<RiskVerdict>;
+    /** Optional live source of the Permissive tier (e.g. a DSH settings namespace). */
+    readonly readPermissive?: () => PermissiveState;
+    /** Optional live source of the llmAssist classifier setup. */
+    readonly readClassifyConfig?: () => ClassifierConfig;
+    /**
+     * Optional live source of the verdict-learning state. When unset, the static
+     * `riskLearning` / `riskThreshold` options apply.
+     */
+    readonly readRiskLearning?: () => RiskLearningState;
+    /** Persistence path for verdict learning; `undefined` keeps it in memory. */
+    readonly learningFile?: string;
+    /** Persistence path for the decision-event feed; `undefined` disables it. */
+    readonly eventsFile?: string;
+}
+export type CallDecision = 'allow' | 'deny' | 'ask';
+/** The effective Permissive tier state read per tool call. */
+export interface PermissiveState {
+    readonly enabled: boolean;
+    readonly strategies: PermissiveStrategies;
+}
+/** The effective verdict-learning state read per decision. */
+export interface RiskLearningState {
+    readonly enabled: boolean;
+    readonly threshold: number;
+}
+export declare class PermGateRuntime {
+    private readonly options;
+    private ruleset;
+    private readonly grants;
+    private readonly artifacts;
+    private readonly audit;
+    private readonly cache;
+    private readonly permissiveEnabled;
+    private readonly strategies;
+    private readonly learning;
+    private readonly events?;
+    /** Learning candidates awaiting human approval + execution (call fingerprint → candidate). */
+    private readonly pending;
+    constructor(options?: PermGateRuntimeOptions);
+    private compileInline;
+    /** Reload rules from disk (HMR); on failure keeps the previous rules. */
+    reload(): boolean;
+    get auditEntries(): readonly AuditEntry[];
+    grantCount(): number;
+    get defaultAction(): string;
+    ruleCount(): number;
+    /** Whether the independent Permissive tier is active (single front switch). */
+    get permissive(): boolean;
+    /** Backend approval strategy booleans active when Permissive is on. */
+    get permissiveStrategies(): Readonly<PermissiveStrategies>;
+    artifactCount(): number;
+    /** The decision-event feed (undefined when event recording is disabled). */
+    get eventLog(): EventLog | undefined;
+    /** Learning candidates currently awaiting settlement (diagnostics/tests). */
+    pendingCount(): number;
+    /** Deep read-only view of the learning state (diagnostics/tests). */
+    learningSnapshot(): ReturnType<RiskLearning['snapshot']>;
+    private ctxFor;
+    private liveRiskLearning;
+    private livePermissive;
+    private recordEvent;
+    /**
+     * Decide one tool call. Returns a decision to veto (`deny`/`ask`) or
+     * undefined to delegate via `next()` (allow / passthrough). Always records an
+     * audit entry and a decision event. Grant consumption happens inside
+     * {@link decide}; a call that targets a different fingerprint than any minted
+     * grant no-ops. An `ask` verdict may afterwards be refined by
+     * {@link refineAsk} (LLM risk grading + verdict learning) before it reaches
+     * the human seam.
+     */
+    decideExecution(exec: ToolExecutionLike): PreToolDecisionLike | undefined;
+    /**
+     * Apply the Permissive tier to a raw decision. Hard-deny and minted-grant
+     * outcomes are never touched (fail-closed). `alwaysConfirm` escalates a
+     * rule-allow to `ask` — which the caller may then refine via
+     * {@link refineAsk}. `trustAutoAllow` is the baseline middle-tier auto-allow
+     * and needs no modulation here; llmAssist refinement lives in
+     * {@link refineAsk} because it is asynchronous.
+     */
+    private applyPermissive;
+    /**
+     * Refine an `ask` decision with the configured LLM risk grader
+     * (`llmAssist` strategy). Returns `undefined` to allow (delegate via
+     * `next()`), or the decision to keep vetoing with. Every uncertainty path —
+     * strategy off, no classifier setup, transport failure, off-protocol output —
+     * keeps the original ask (fail-closed). Only a `neutral` risk under an
+     * enabled learning store registers a pending candidate; its confirmation is
+     * settled by {@link settleExecution} when the call actually executes.
+     */
+    refineAsk(exec: ToolExecutionLike, decision: PreToolDecisionLike): Promise<PreToolDecisionLike | undefined>;
+    /**
+     * Settle a learning candidate after the call finished (`tools/result`).
+     * A result arriving for a registered pending candidate means the human
+     * approved it and it actually executed — record one confirmation.
+     */
+    settleExecution(exec: ToolExecutionLike): void;
+    /** Mint a precise session grant bound to a canonical call fingerprint. */
+    grant(exec: ToolExecutionLike, maxUses: number, ttlMs: number): void;
+    /**
+     * Grant "repeat this call for the current session" (the always-confirm panel's
+     * first extended allow button): mint a bounded session grant for the exact
+     * call so an identical re-run this session passes without asking again.
+     */
+    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.
+     */
+    approveAllowEverywhere(commandWord: string, reason?: string): boolean;
+    /** Read-only view of the current allow-list command patterns (whitelist). */
+    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).
+     */
+    setAllowlist(patterns: readonly string[]): boolean;
+}