dsh-perm-gate 0.2.0

package/lib/learning.js

@@ -0,0 +1,181 @@
+/**
+ * Verdict learning for dsh-perm-gate's `llmAssist` strategy.
+ *
+ * When the risk grader reports a `neutral` risk and the call goes to the human
+ * seam, a confirmation is learned once the call actually executes (observed via
+ * the host's `tools/result` settlement). After `threshold` confirmations of the
+ * same `tool|category` key AND a fingerprint match against a previously
+ * confirmed sample, the gate may auto-allow the same operation — and only that
+ * operation, never a wider class.
+ *
+ * State persists as a plugin-owned JSON file. The user's YAML rules file is the
+ * deterministic, human-owned layer and is never written here; all I/O errors
+ * degrade to in-memory state so learning can never break gating (worst case
+ * the gate simply keeps asking — still fail-closed).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const DEFAULT_THRESHOLD = 3;
+const DEFAULT_MAX_SAMPLES = 10;
+/** Shell tool names whose first argument word is the operation handle. */
+const SHELL_TOOLS = new Set(['bash', 'pwsh', 'sh', 'cmd', 'powershell']);
+/** Structured arg keys carrying the operation target. */
+const TARGET_KEYS = ['file_path', 'filePath', 'path', 'file', 'filename', 'target', 'url'];
+function basename(p) {
+    const s = p.replaceAll('\\', '/');
+    const base = s.slice(s.lastIndexOf('/') + 1).trim();
+    return base;
+}
+/**
+ * Derive a stable, precise operation fingerprint from structured arguments:
+ * shell calls → `word|target-basename`; file-arg tools → the target basename;
+ * everything else → the tool name alone. Two calls share a fingerprint only
+ * when they perform the same kind of write against the same-named target.
+ */
+export function operationFingerprint(tool, args, commandText) {
+    const command = typeof args.command === 'string'
+        ? args.command
+        : (SHELL_TOOLS.has(tool) && typeof commandText === 'string' ? commandText : undefined);
+    if (command !== undefined) {
+        const word = command.trim().split(/\s+/)[0] ?? '';
+        // Target position convention: the last non-flag token (`npm install foo`,
+        // `rm -rf dist`, `git push origin main` → main). Nothing target-like → word only.
+        let target = '';
+        const tokens = command.split(/\s+/);
+        for (let i = tokens.length - 1; i >= 1; i -= 1) {
+            const token = tokens[i];
+            if (token.startsWith('-') || token.length < 2)
+                continue;
+            target = basename(token);
+            if (target !== '')
+                break;
+        }
+        return target !== '' ? `${word}|${target}` : word;
+    }
+    for (const key of TARGET_KEYS) {
+        const v = args[key];
+        if (typeof v === 'string' && v.trim() !== '') {
+            const base = basename(v);
+            if (base !== '')
+                return base;
+        }
+    }
+    return tool;
+}
+/** The learning key for one call: `tool|category` (only neutral learns today). */
+export function learnKey(tool, category) {
+    return `${tool}|${category}`;
+}
+function emptyDoc() {
+    return { version: 1, confirmed: {}, samples: {} };
+}
+function sanitizeDoc(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return emptyDoc();
+    const doc = emptyDoc();
+    const confirmed = raw['confirmed'];
+    if (typeof confirmed === 'object' && confirmed !== null) {
+        for (const [k, v] of Object.entries(confirmed)) {
+            if (typeof v === 'number' && Number.isFinite(v) && v > 0)
+                doc.confirmed[k] = Math.floor(v);
+        }
+    }
+    const samples = raw['samples'];
+    if (typeof samples === 'object' && samples !== null) {
+        for (const [k, v] of Object.entries(samples)) {
+            if (!Array.isArray(v))
+                continue;
+            const list = [];
+            for (const s of v) {
+                if (typeof s !== 'object' || s === null)
+                    continue;
+                const fp = s['fp'];
+                if (typeof fp !== 'string' || fp === '')
+                    continue;
+                const ctx = typeof s['ctx'] === 'string' ? s['ctx'] : '';
+                const at = typeof s['at'] === 'number' ? s['at'] : 0;
+                list.push({ fp, ctx: ctx.slice(0, 200), at });
+            }
+            if (list.length > 0)
+                doc.samples[k] = list;
+        }
+    }
+    return doc;
+}
+export class RiskLearning {
+    filePath;
+    options;
+    doc = emptyDoc();
+    loaded = false;
+    constructor(
+    /** Persistence path; `undefined` keeps state in memory only. */
+    filePath, options = {}) {
+        this.filePath = filePath;
+        this.options = options;
+    }
+    get threshold() {
+        const t = this.options.threshold;
+        return (typeof t === 'function' ? t() : t) ?? DEFAULT_THRESHOLD;
+    }
+    load() {
+        if (!this.loaded) {
+            this.loaded = true;
+            if (this.filePath !== undefined) {
+                try {
+                    this.doc = sanitizeDoc(JSON.parse(readFileSync(this.filePath, 'utf8')));
+                }
+                catch {
+                    this.doc = emptyDoc(); // missing/corrupt file: start clean, never throw
+                }
+            }
+        }
+        return this.doc;
+    }
+    persist() {
+        if (this.filePath === undefined)
+            return;
+        try {
+            mkdirSync(dirname(this.filePath), { recursive: true });
+            writeFileSync(this.filePath, JSON.stringify(this.doc, null, 2) + '\n', 'utf8');
+        }
+        catch {
+            // Unwritable location: keep the in-memory state; learning silently degrades.
+        }
+    }
+    /** Human confirmations recorded so far for one key. */
+    count(key) {
+        return this.load().confirmed[key] ?? 0;
+    }
+    /** Whether one key already holds a confirmed sample with this fingerprint. */
+    hasSample(key, fp) {
+        return this.load().samples[key]?.some((s) => s.fp === fp) ?? false;
+    }
+    /**
+     * The learning gate: auto-allow only when the key reached the threshold AND
+     * this exact fingerprint was among the human-confirmed samples.
+     */
+    shouldAutoAllow(key, fp) {
+        return this.count(key) >= this.threshold && this.hasSample(key, fp);
+    }
+    /** Record one human confirmation: bump the count and store the sample (bounded). */
+    confirm(key, fp, ctx) {
+        const doc = this.load();
+        doc.confirmed[key] = (doc.confirmed[key] ?? 0) + 1;
+        const max = this.options.maxSamples ?? DEFAULT_MAX_SAMPLES;
+        const list = (doc.samples[key] ?? []).filter((s) => s.fp !== fp);
+        list.push({ fp, ctx: ctx.slice(0, 200), at: (this.options.now ?? Date.now)() });
+        doc.samples[key] = list.slice(-max);
+        this.persist();
+    }
+    /** Drop all learning state (counts and samples) and persist the empty doc. */
+    reset() {
+        this.doc = emptyDoc();
+        this.loaded = true;
+        this.persist();
+    }
+    /** Read-only deep view (for tests and diagnostics). */
+    snapshot() {
+        const doc = this.load();
+        return JSON.parse(JSON.stringify(doc));
+    }
+}

package/lib/path.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Path containment and normalization for dsh-perm-gate, plus a session-scoped
+ * artifact registry that tracks files a session created so deletion of
+ * same-session artifacts can be cleaned up without widening authority.
+ *
+ * Containment helpers are pure string operators (testable); the registry is
+ * the one stateful piece and stays in-process for a session.
+ */
+export declare function toPosix(p: string): string;
+/**
+ * Normalize one candidate path against the workspace root to a
+ * workspace-relative posix path. Candidates OUTSIDE the root yield `''`.
+ * `caseInsensitive` (Windows default) compares drive/root prefixes case-insensitively.
+ */
+export declare function normalizeWorkspacePath(cwd: string, candidate: string, caseInsensitive?: boolean): string;
+export declare function isWithin(base: string, target: string): boolean;
+/** Sensitive credential-ish path roots that reads/writes should route to review. */
+export declare function isSensitivePath(p: string): boolean;
+/** Root-level / DSH_HOME / home/system paths that must never be mutated. */
+export declare function isProtectedDestructiveTarget(p: string, dshHome?: string): boolean;
+export interface ArtifactRecord {
+    readonly device: string;
+    readonly inode: string;
+    readonly birthMs: number;
+    readonly kind: 'file' | 'dir';
+    readonly cwd: string;
+}
+export interface ArtifactRead {
+    /** device:inode for files; '' when unknown. */
+    readonly id: string;
+    readonly kind: 'file' | 'dir';
+    readonly tracked: boolean;
+}
+/**
+ * Tracks files a session created so their exact cleanup can be authorized
+ * without widening authority to pre-existing data. Keyed by `device:inode`.
+ */
+export declare class ArtifactRegistry {
+    private readonly byId;
+    register(id: string, kind: 'file' | 'dir', cwd: string): void;
+    /** Whether a known id was created during this session. */
+    known(id: string): ArtifactRead | undefined;
+    unregister(id: string): void;
+    snapshot(): number;
+    /** Build a stable identity string for a file system entry when given device+inode. */
+    static identity(device: number | string, inode: number | string): string;
+}

package/lib/path.js

@@ -0,0 +1,94 @@
+/**
+ * Path containment and normalization for dsh-perm-gate, plus a session-scoped
+ * artifact registry that tracks files a session created so deletion of
+ * same-session artifacts can be cleaned up without widening authority.
+ *
+ * Containment helpers are pure string operators (testable); the registry is
+ * the one stateful piece and stays in-process for a session.
+ */
+// --- Pure path helpers -------------------------------------------------------
+export function toPosix(p) {
+    return p.replaceAll('\\', '/');
+}
+/**
+ * Normalize one candidate path against the workspace root to a
+ * workspace-relative posix path. Candidates OUTSIDE the root yield `''`.
+ * `caseInsensitive` (Windows default) compares drive/root prefixes case-insensitively.
+ */
+export function normalizeWorkspacePath(cwd, candidate, caseInsensitive = false) {
+    const root = toPosix(cwd).replace(/\/+$/, '');
+    const raw = toPosix(candidate);
+    if (raw.length === 0)
+        return '';
+    let path = raw;
+    while (path.startsWith('./'))
+        path = path.slice(2);
+    if (/^[A-Za-z]:\//.test(path)) {
+        if (!/^[A-Za-z]:\//.test(root))
+            return '';
+        if (path.slice(0, 2).toLowerCase() !== root.slice(0, 2).toLowerCase())
+            return '';
+        return relFromRoot(root, path, path.slice(2), root.slice(2), caseInsensitive);
+    }
+    if (path.startsWith('/')) {
+        return relFromRoot(root, path, path, root, caseInsensitive);
+    }
+    return path;
+}
+function relFromRoot(root, path, rest, rootRest, ci) {
+    const eq = (a, b) => (ci ? a.toLowerCase() === b.toLowerCase() : a === b);
+    if (rootRest.length === 0)
+        return rest.slice(1);
+    if (eq(path, root))
+        return '';
+    return (ci ? rest.toLowerCase() : rest).startsWith((ci ? rootRest.toLowerCase() + '/' : rootRest + '/'))
+        ? rest.slice(rootRest.length + 1)
+        : '';
+}
+export function isWithin(base, target) {
+    const b = toPosix(base).replace(/\/+$/, '');
+    const t = toPosix(target);
+    return t === b || t.startsWith(b + '/');
+}
+/** Sensitive credential-ish path roots that reads/writes should route to review. */
+export function isSensitivePath(p) {
+    return /(?:^|[\\/])(?:\.ssh|\.gnupg|\.aws|\.azure|\.kube|\.config[\\/]gh|\.docker)(?:[\\/]|$)|(?:^|[\\/])(?:id_rsa|id_ed25519|credentials\.yaml|config\.json|\.env)(?:$|[.\\/])/i.test(p);
+}
+/** Root-level / DSH_HOME / home/system paths that must never be mutated. */
+export function isProtectedDestructiveTarget(p, dshHome) {
+    const posix = toPosix(p).toLowerCase();
+    const guards = ['/', '/home', '/root', '/usr', '/etc', '/bin', '/sbin', '/boot', '/var'];
+    for (const g of guards) {
+        if (posix === g || posix.startsWith(g + '/'))
+            return true;
+    }
+    if (dshHome !== undefined && (posix === toPosix(dshHome).toLowerCase() || posix.startsWith(toPosix(dshHome).toLowerCase() + '/')))
+        return true;
+    return false;
+}
+/**
+ * Tracks files a session created so their exact cleanup can be authorized
+ * without widening authority to pre-existing data. Keyed by `device:inode`.
+ */
+export class ArtifactRegistry {
+    byId = new Map();
+    register(id, kind, cwd) {
+        if (id !== '')
+            this.byId.set(id, { cwd, kind });
+    }
+    /** Whether a known id was created during this session. */
+    known(id) {
+        const r = this.byId.get(id);
+        return r === undefined ? undefined : { id, kind: r.kind, tracked: true };
+    }
+    unregister(id) {
+        this.byId.delete(id);
+    }
+    snapshot() {
+        return this.byId.size;
+    }
+    /** Build a stable identity string for a file system entry when given device+inode. */
+    static identity(device, inode) {
+        return `${String(device)}:${String(inode)}`;
+    }
+}

package/lib/risk.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Risk-category verdict protocol for dsh-perm-gate's `llmAssist` strategy.
+ *
+ * Layers on the same custom OpenAI-compatible endpoint as `classifier.ts` and
+ * asks the LLM to grade ONE tool call as either safe or risky with a category:
+ *
+ *   safe                      → the gate may auto-allow the ask
+ *   risky:<hard category>     → deletion / credential / remote / system / bulk —
+ *                               ALWAYS routed to the human, never auto-allowed
+ *   risky:neutral             → no hard-risk signal but not clearly safe; the
+ *                               verdict-learning path may auto-allow after
+ *                               enough human confirmations
+ *   unresolved                → transport failure, timeout, or a protocol
+ *                               violation — the caller must keep the ask
+ *                               (fail-closed) and must NOT learn from it
+ *
+ * The protocol, prompt wording, and parser are this repo's own; the design
+ * (hard categories vs. a neutral confirm-count zone) follows the approach
+ * demonstrated by dsh-approval-gate.
+ */
+import { type ClassifierConfig } from './classifier.js';
+/** Risk categories the LLM may report for a risky verdict. */
+export type RiskCategory = 'deletion' | 'credential' | 'remote' | 'system' | 'bulk' | 'neutral';
+/**
+ * Categories that always route to the human seam regardless of learning state
+ * or any later LLM opinion. Order-stable for prompts and event payloads.
+ */
+export declare const HARD_RISK_CATEGORIES: readonly RiskCategory[];
+/** Whether a category must never be auto-allowed. Unknown categories are hard too (fail-closed). */
+export declare function isHardRisk(category: string): boolean;
+/**
+ * A graded verdict for one tool call. `unresolved` covers every failure mode —
+ * the caller must treat it exactly like "no classifier": keep the ask, learn nothing.
+ */
+export type RiskVerdict = {
+    kind: 'safe';
+    reason?: string;
+} | {
+    kind: 'risky';
+    category: RiskCategory;
+    reason?: string;
+} | {
+    kind: 'unresolved';
+};
+/** The bounded call graded by {@link classifyRisk}. */
+export interface RiskRequest {
+    readonly tool: string;
+    readonly args: unknown;
+    /** The deterministic reason the call reached the LLM-assist seam. */
+    readonly reason: string;
+}
+/** Parse one assistant message into a verdict; anything off-protocol → undefined (caller retries/fails). */
+export declare function parseRiskVerdict(content: string): RiskVerdict | undefined;
+/**
+ * Grade one tool call with the configured LLM. Up to two attempts (one retry);
+ * any failure, timeout, or protocol violation resolves `unresolved` — never throws.
+ */
+export declare function classifyRisk(cfg: ClassifierConfig, req: RiskRequest, nowFetch?: typeof fetch): Promise<RiskVerdict>;

package/lib/risk.js

@@ -0,0 +1,100 @@
+/**
+ * Risk-category verdict protocol for dsh-perm-gate's `llmAssist` strategy.
+ *
+ * Layers on the same custom OpenAI-compatible endpoint as `classifier.ts` and
+ * asks the LLM to grade ONE tool call as either safe or risky with a category:
+ *
+ *   safe                      → the gate may auto-allow the ask
+ *   risky:<hard category>     → deletion / credential / remote / system / bulk —
+ *                               ALWAYS routed to the human, never auto-allowed
+ *   risky:neutral             → no hard-risk signal but not clearly safe; the
+ *                               verdict-learning path may auto-allow after
+ *                               enough human confirmations
+ *   unresolved                → transport failure, timeout, or a protocol
+ *                               violation — the caller must keep the ask
+ *                               (fail-closed) and must NOT learn from it
+ *
+ * The protocol, prompt wording, and parser are this repo's own; the design
+ * (hard categories vs. a neutral confirm-count zone) follows the approach
+ * demonstrated by dsh-approval-gate.
+ */
+import { chatCompletion, withLlmRetry } from './classifier.js';
+/**
+ * Categories that always route to the human seam regardless of learning state
+ * or any later LLM opinion. Order-stable for prompts and event payloads.
+ */
+export const HARD_RISK_CATEGORIES = ['deletion', 'credential', 'remote', 'system', 'bulk'];
+const RISK_CATEGORIES = [...HARD_RISK_CATEGORIES, 'neutral'];
+/** Whether a category must never be auto-allowed. Unknown categories are hard too (fail-closed). */
+export function isHardRisk(category) {
+    if (HARD_RISK_CATEGORIES.includes(category))
+        return true;
+    // An unknown category means the verdict is unreliable — treat it as hard.
+    return !RISK_CATEGORIES.includes(category);
+}
+const RISK_SYSTEM_PROMPT = [
+    'You are the risk grader inside a permission gate for a coding agent.',
+    'You receive one tool call (tool name, arguments, and the deterministic reason it needs human-grade review).',
+    'Grade whether executing it could cause irreversible damage or touch sensitive resources.',
+    '',
+    'Reply with ONLY one JSON object and nothing else:',
+    '  {"risk":"safe","reason":"short"}',
+    '  {"risk":"risky","category":"<category>","reason":"short"}',
+    '',
+    'category must be exactly one of:',
+    '  deletion  — deletes or overwrites data that cannot be regenerated',
+    '  credential — creates/modifies/exposes credentials, keys, tokens, auth config',
+    '  remote    — affects remote systems, production, databases, messaging, billing, publishing',
+    '  system    — system-level paths or configuration (/etc, /usr, boot items), shutdown/reboot',
+    '  bulk      — mass overwrite of many files, formatting, dd-style irreversible writes',
+    '  neutral   — none of the above clearly applies (ordinary edits outside the obvious scope, or you are unsure but see no hard-risk sign)',
+    '',
+    'Rules:',
+    '- safe is only for reversible, in-scope operations that touch no sensitive resource.',
+    '- When unsure between safe and neutral, answer neutral; never guess safe.',
+    '- Judge the operation content, not merely its location.',
+].join('\n');
+/** Parse one assistant message into a verdict; anything off-protocol → undefined (caller retries/fails). */
+export function parseRiskVerdict(content) {
+    const trimmed = content.trim();
+    try {
+        const parsed = JSON.parse(trimmed);
+        const reason = typeof parsed.reason === 'string' ? parsed.reason.slice(0, 200) : undefined;
+        if (parsed.risk === 'safe')
+            return { kind: 'safe', reason };
+        if (parsed.risk === 'risky') {
+            const category = typeof parsed.category === 'string' ? parsed.category.toLowerCase() : '';
+            if (RISK_CATEGORIES.includes(category)) {
+                return { kind: 'risky', category: category, reason };
+            }
+            return undefined; // off-protocol category: unreliable, do not decide on it
+        }
+        return undefined;
+    }
+    catch {
+        // Lenient fallback for models that ignore response_format: bare keyword scan.
+        // A bare "risky" carries no trustworthy category, so it stays unresolved —
+        // the caller keeps the human ask rather than guessing a category.
+        if (/\brisky\b/i.test(trimmed))
+            return undefined;
+        if (/\bsafe\b/i.test(trimmed))
+            return { kind: 'safe' };
+        return undefined;
+    }
+}
+/**
+ * Grade one tool call with the configured LLM. Up to two attempts (one retry);
+ * any failure, timeout, or protocol violation resolves `unresolved` — never throws.
+ */
+export async function classifyRisk(cfg, req, nowFetch = fetch) {
+    const user = JSON.stringify({
+        tool: req.tool,
+        args: req.args ?? {},
+        reason: req.reason,
+        instruction: 'Reply strictly as one JSON object: {"risk":"safe"} or {"risk":"risky","category":"..."} plus a short "reason".',
+    });
+    const content = await withLlmRetry(() => chatCompletion(cfg, RISK_SYSTEM_PROMPT, user, nowFetch).then((r) => (r.ok ? r.content : undefined)));
+    if (content === undefined)
+        return { kind: 'unresolved' };
+    return parseRiskVerdict(content) ?? { kind: 'unresolved' };
+}

package/lib/rule.d.ts

@@ -0,0 +1,64 @@
+import { type CompiledPattern } from './compiler.js';
+export type RuleAction = 'allow' | 'ask' | 'deny';
+/** A parsed, shape-validated permissions document (patterns not yet compiled). */
+export interface PermissionsDoc {
+    readonly defaultAction: RuleAction;
+    readonly deny: RuleEntryDoc[];
+    readonly allow: RuleEntryDoc[];
+    readonly ask: RuleEntryDoc[];
+}
+/** One parsed rule: match dimensions plus the action, reason, and metadata. */
+export interface RuleEntryDoc {
+    /** Tool-name globs; empty = every tool. */
+    readonly tools: string[];
+    /**
+     * Shell command-word patterns. An entry `word` or `word#flag` where flag is
+     * `recursive`/`force`. Empty = this rule does not constrain on command.
+     */
+    readonly command: string[];
+    /** Argument/value token globs (file paths, urls, command args); empty = no constraint. */
+    readonly args: string[];
+    /** Workspace-relative path globs; empty = no constraint. */
+    readonly paths: string[];
+    readonly action: RuleAction;
+    readonly reason: string;
+    readonly enabled: boolean;
+}
+export interface CompiledRuleEntry {
+    readonly index: number;
+    readonly action: RuleAction;
+    readonly reason: string;
+    readonly enabled: boolean;
+    readonly tools: readonly CompiledPattern[];
+    /** Command specs: { word glob, flag? }. */
+    readonly command: readonly CommandSpec[];
+    readonly args: readonly CompiledPattern[];
+    readonly paths: readonly CompiledPattern[];
+    readonly source: RuleEntryDoc;
+}
+export interface CommandSpec {
+    readonly word: CompiledPattern;
+    readonly flag?: 'recursive' | 'force';
+}
+export interface CompiledRuleset {
+    readonly defaultAction: RuleAction;
+    readonly deny: readonly CompiledRuleEntry[];
+    readonly allow: readonly CompiledRuleEntry[];
+    readonly ask: readonly CompiledRuleEntry[];
+    readonly caseInsensitivePaths: boolean;
+}
+export interface CompileOptions {
+    readonly maxGlobStars?: number;
+    readonly caseInsensitivePaths?: boolean;
+}
+export declare class RuleError extends Error {
+    constructor(message: string);
+}
+/** Parse a raw YAML permissions document; malformed files fail loud at load. */
+export declare function parsePermissionsDocument(text: string): PermissionsDoc;
+/** Compile a validated document into hot-path rules. */
+export declare function compileDocument(doc: PermissionsDoc, 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[];
+export declare function extractUrlCandidates(args: Record<string, unknown>): string[];