dsh-perm-gate 2.0.0 → 2.1.2

package/lib/session-sweep.js

@@ -0,0 +1,153 @@
+/**
+ * Session-lifecycle sweep for dsh-perm-gate: DSH's workspace store
+ * (`<dshHome>/storages/workspace.json`) is the authority on which sessions are
+ * live and which were archived. On plugin start and hourly, the gate classifies
+ * every session id it holds gate data for — live (in a workspace), archived
+ * (in `global.archivedSessionIds`), or gone (neither) — and drops the
+ * authorization-chain data of archived/gone sessions: their decision events in
+ * `events.jsonl` and their pre-change snapshots in `snapshots/`.
+ *
+ * Fail-open like every other side effect in this plugin: any I/O or parse
+ * error is swallowed with a single warn and the round is skipped — the sweep
+ * must never influence gating. The workspace store is read-only here (DSH owns
+ * it and rewrites it continuously); a torn read simply defers to the next round.
+ */
+import { readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Strip the `session-` prefix so ids from different sources compare equal. */
+export function normalizeSessionId(id) {
+    const s = String(id ?? '');
+    return s.startsWith('session-') ? s.slice('session-'.length) : s;
+}
+/**
+ * Classify sessions from the raw text of the workspace store. Returns `null`
+ * on unparsable or structurally unexpected content (torn write, format bump) —
+ * the caller skips the round. Missing `global`/`tables` sections degrade to
+ * empty sets rather than failing: a fresh install has neither.
+ */
+export function classifySessions(raw) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc))
+        return null;
+    const root = doc;
+    const live = new Set();
+    const workspaces = root.tables?.workspaces;
+    if (typeof workspaces === 'object' && workspaces !== null) {
+        for (const record of Object.values(workspaces)) {
+            const ids = record?.sessionIds;
+            if (!Array.isArray(ids))
+                continue;
+            for (const id of ids)
+                live.add(normalizeSessionId(id));
+        }
+    }
+    const archived = new Set();
+    if (Array.isArray(root.global?.archivedSessionIds)) {
+        for (const id of root.global.archivedSessionIds)
+            archived.add(normalizeSessionId(id));
+    }
+    return { live, archived };
+}
+/**
+ * Whether a gate-side session id belongs to an archived or deleted session.
+ * An empty id (unattributable legacy row) never matches — the same semantics
+ * `snapshotMatchesSession` uses for snapshots, so unattributable data is kept.
+ */
+export function isStaleSession(id, cls) {
+    const norm = normalizeSessionId(id);
+    return norm !== '' && !cls.live.has(norm);
+}
+/**
+ * Drop archived/dead sessions' rows from `events.jsonl` (atomic tmp+rename
+ * rewrite, only when something is actually removed) and delete their snapshot
+ * files. Both halves are independent: a failure in one still lets the other
+ * run. I/O errors are swallowed with a warn — best-effort cleanup, never a
+ * gating concern.
+ */
+export function sweepSessionData(opts) {
+    const eventsRemoved = sweepEvents(opts);
+    const snapshotsRemoved = sweepSnapshots(opts);
+    return { eventsRemoved, snapshotsRemoved };
+}
+function sweepEvents({ classification, eventsFile }) {
+    let raw;
+    try {
+        raw = readFileSync(eventsFile, 'utf8');
+    }
+    catch {
+        return 0; // no feed yet (or unreadable) — nothing to sweep
+    }
+    const lines = raw.split('\n');
+    const kept = [];
+    let removed = 0;
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        let stale = false;
+        try {
+            const ev = JSON.parse(line);
+            stale = isStaleSession(String(ev.sessionId ?? ''), classification);
+        }
+        catch {
+            // An unparsable line is unattributable — keep it (never destroy evidence).
+        }
+        if (stale)
+            removed += 1;
+        else
+            kept.push(line);
+    }
+    if (removed === 0)
+        return 0;
+    try {
+        const tmp = `${eventsFile}.sweep-tmp`;
+        writeFileSync(tmp, kept.length > 0 ? kept.join('\n') + '\n' : '', 'utf8');
+        renameSync(tmp, eventsFile);
+        return removed;
+    }
+    catch (e) {
+        warn('events rewrite failed', e);
+        return 0;
+    }
+}
+function sweepSnapshots({ classification, snapshotsDir }) {
+    let entries;
+    try {
+        entries = readdirSync(snapshotsDir);
+    }
+    catch {
+        return 0; // no snapshot dir yet
+    }
+    let removed = 0;
+    for (const name of entries) {
+        if (!/^\d+\.json$/.test(name))
+            continue;
+        const abs = join(snapshotsDir, name);
+        let stale = false;
+        try {
+            const doc = JSON.parse(readFileSync(abs, 'utf8'));
+            stale = isStaleSession(String(doc.sessionId ?? ''), classification);
+        }
+        catch {
+            // Unparsable snapshot (torn write) has no attributable session — keep it.
+        }
+        if (!stale)
+            continue;
+        try {
+            rmSync(abs);
+            removed += 1;
+        }
+        catch (e) {
+            warn(`snapshot ${name} delete failed`, e);
+        }
+    }
+    return removed;
+}
+function warn(what, e) {
+    console.warn(`[dsh-perm-gate] session sweep: ${what}:`, e instanceof Error ? e.message : e);
+}

package/lib/shadow.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shadow detection for dsh-perm-gate rule chains.
+ *
+ * A rule is "shadowed" when an earlier rule in the same action partition
+ * always matches the same (or a superset of) tool calls, making the later
+ * rule unreachable. Shadowed rules are dead weight — they can never fire
+ * and may confuse users who think they are effective.
+ *
+ * This module performs a structural (conservative) shadow check. It does NOT
+ * do full semantic analysis — it flags potential shadows based on pattern
+ * structure, not on actual runtime argument values.
+ */
+import type { CompiledRuleset } from './rule.js';
+export interface ShadowReport {
+    /** Rule indices that are shadowed (unreachable). */
+    readonly shadowed: readonly number[];
+    /** Human-readable reasons per shadowed rule. */
+    readonly reasons: ReadonlyMap<number, string>;
+}
+/**
+ * Detect shadowed rules within a compiled ruleset.
+ *
+ * For each action partition (deny, allow, ask), check if any rule is
+ * dominated by an earlier rule in the same partition. A rule is dominated
+ * when:
+ *   1. Its tools pattern is a subset (or equal) of an earlier rule's tools
+ *   2. Its command pattern is a subset (or equal)
+ *   3. Its args/paths dimensions are subsets
+ *   4. Its new dimensions (params/absent/agents/when/network) are subsets
+ *
+ * This is conservative: it only flags rules that are DEFINITELY unreachable,
+ * not rules that MIGHT be unreachable under certain argument combinations.
+ */
+export declare function detectShadows(ruleset: CompiledRuleset): ShadowReport;

package/lib/shadow.js

@@ -0,0 +1,143 @@
+/**
+ * Detect shadowed rules within a compiled ruleset.
+ *
+ * For each action partition (deny, allow, ask), check if any rule is
+ * dominated by an earlier rule in the same partition. A rule is dominated
+ * when:
+ *   1. Its tools pattern is a subset (or equal) of an earlier rule's tools
+ *   2. Its command pattern is a subset (or equal)
+ *   3. Its args/paths dimensions are subsets
+ *   4. Its new dimensions (params/absent/agents/when/network) are subsets
+ *
+ * This is conservative: it only flags rules that are DEFINITELY unreachable,
+ * not rules that MIGHT be unreachable under certain argument combinations.
+ */
+export function detectShadows(ruleset) {
+    const shadowed = [];
+    const reasons = new Map();
+    for (const partition of [ruleset.deny, ruleset.allow, ruleset.ask]) {
+        for (let i = 0; i < partition.length; i++) {
+            const rule = partition[i];
+            if (!rule.enabled)
+                continue;
+            for (let j = 0; j < i; j++) {
+                const earlier = partition[j];
+                if (!earlier.enabled)
+                    continue;
+                const dominatedBy = isDominated(earlier, rule);
+                if (dominatedBy !== undefined) {
+                    shadowed.push(rule.index);
+                    reasons.set(rule.index, `shadowed by rule #${earlier.index}: ${dominatedBy}`);
+                    break; // already flagged by earliest dominator
+                }
+            }
+        }
+    }
+    return { shadowed, reasons };
+}
+/**
+ * Check if `candidate` is dominated by `dominator` (dominator always
+ * matches a superset of what candidate matches).
+ *
+ * Returns a reason string if dominated, undefined otherwise.
+ */
+function isDominated(dominator, candidate) {
+    // tools: dominator's tools must be a superset (fewer or equal patterns = wider match).
+    // If dominator has no tools constraint (empty = every tool), it's a superset.
+    if (dominator.tools.length > 0 && candidate.tools.length > 0) {
+        // Both have tools: conservatively check if dominator's patterns are broader.
+        // Simple heuristic: if dominator has fewer patterns, it's likely broader.
+        // Full subset analysis would require pattern comparison — too expensive for hot path.
+        // We only flag when dominator has NO tools constraint (empty = every tool).
+        // For non-empty/non-empty, we conservatively don't flag.
+        if (dominator.tools.length <= candidate.tools.length) {
+            // Could be broader — but we need actual pattern comparison.
+            // Conservative: don't flag unless we can prove subset.
+            // Skip this dimension for now.
+        }
+        else {
+            return undefined; // dominator is stricter on tools
+        }
+    }
+    // If dominator has no tools and candidate has tools → dominator is broader ✓
+    // command: same logic — dominator with no command constraint is broader.
+    if (dominator.command.length > 0 && candidate.command.length > 0) {
+        if (dominator.command.length > candidate.command.length)
+            return undefined;
+    }
+    // args: same logic.
+    if (dominator.args.length > 0 && candidate.args.length > 0) {
+        if (dominator.args.length > candidate.args.length)
+            return undefined;
+    }
+    // paths: same logic.
+    if (dominator.paths.length > 0 && candidate.paths.length > 0) {
+        if (dominator.paths.length > candidate.paths.length)
+            return undefined;
+    }
+    // New dimensions: if dominator has fewer constraints, it's broader.
+    // params
+    if (dominator.params.length > 0 && candidate.params.length > 0) {
+        if (dominator.params.length > candidate.params.length)
+            return undefined;
+    }
+    // absent
+    if (dominator.absent.length > 0 && candidate.absent.length > 0) {
+        if (dominator.absent.length > candidate.absent.length)
+            return undefined;
+    }
+    // agents
+    if (dominator.agents.length > 0 && candidate.agents.length > 0) {
+        if (dominator.agents.length > candidate.agents.length)
+            return undefined;
+    }
+    // when: dominator with no when = broader
+    if (dominator.when !== undefined && candidate.when === undefined) {
+        return undefined; // dominator is stricter
+    }
+    // network: dominator with no network = broader
+    if (dominator.network !== undefined && candidate.network === undefined) {
+        return undefined; // dominator is stricter
+    }
+    // If we get here, dominator has no constraints that candidate doesn't also
+    // have (or has fewer/equal constraints). This is a potential shadow.
+    // Only flag if dominator is strictly broader on at least one dimension.
+    const dominatorBroad = isStrictlyBroader(dominator, candidate);
+    if (dominatorBroad !== undefined)
+        return dominatorBroad;
+    return undefined;
+}
+/**
+ * Check if dominator is strictly broader than candidate on at least one dimension.
+ */
+function isStrictlyBroader(dominator, candidate) {
+    // tools: empty = every tool (broader)
+    if (dominator.tools.length === 0 && candidate.tools.length > 0) {
+        return `dominator has no tools constraint (matches all tools)`;
+    }
+    // command: empty = no command constraint (broader)
+    if (dominator.command.length === 0 && candidate.command.length > 0) {
+        return `dominator has no command constraint`;
+    }
+    // args: empty = no args constraint (broader)
+    if (dominator.args.length === 0 && candidate.args.length > 0) {
+        return `dominator has no args constraint`;
+    }
+    // paths: empty = no paths constraint (broader)
+    if (dominator.paths.length === 0 && candidate.paths.length > 0) {
+        return `dominator has no paths constraint`;
+    }
+    // params: empty = no params constraint (broader)
+    if (dominator.params.length === 0 && candidate.params.length > 0) {
+        return `dominator has no params constraint`;
+    }
+    // absent: empty = no absent constraint (broader)
+    if (dominator.absent.length === 0 && candidate.absent.length > 0) {
+        return `dominator has no absent constraint`;
+    }
+    // agents: empty = no agents constraint (broader)
+    if (dominator.agents.length === 0 && candidate.agents.length > 0) {
+        return `dominator has no agents constraint`;
+    }
+    return undefined;
+}

package/lib/watch.d.ts

@@ -0,0 +1,42 @@
+export interface WatcherOptions {
+    /** Debounce interval in ms. Default 300. */
+    readonly debounceMs?: number;
+    /** Maximum number of workspace watchers to keep. Default 10. */
+    readonly maxWatchers?: number;
+    /** Logger sink. */
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * Manages file watchers for rule files across workspaces.
+ * Each workspace gets its own watcher set; LRU eviction caps total count.
+ */
+export declare class RuleWatcher {
+    private readonly watchers;
+    private readonly debounceMs;
+    private readonly maxWatchers;
+    private readonly logger;
+    constructor(options?: WatcherOptions);
+    /**
+     * Start watching rule files for a workspace.
+     *
+     * @param cwd - The workspace root.
+     * @param ruleFiles - Absolute paths to the effective rule files (chain).
+     * @param reload - Callback to invoke (debounced) on any change.
+     */
+    watch(cwd: string, ruleFiles: readonly string[], reload: () => void): void;
+    /**
+     * Stop watching a specific workspace.
+     */
+    unwatch(cwd: string): void;
+    /**
+     * Stop all watchers and clear state.
+     */
+    closeAll(): void;
+    /** Number of active workspace watchers. */
+    activeWatcherCount(): number;
+    /** Number of pending (debounced) reloads. */
+    pendingReloadCount(): number;
+    private evictIfNeeded;
+}

package/lib/watch.js

@@ -0,0 +1,170 @@
+/**
+ * File watching for dsh-perm-gate rule hot-reload.
+ *
+ * Watches the effective rules files (the chain resolved for each workspace)
+ * and triggers a debounced `runtime.reload()` when any file changes. Also
+ * monitors candidate files (expected-but-absent files) through their deepest
+ * existing ancestor directory, so mid-session file creation is adopted.
+ *
+ * Design:
+ * - Chokidar for cross-platform reliability (PerryLink-validated).
+ * - Debounce window: multiple rapid writes within `debounceMs` merge into
+ *   one reload.
+ * - Chain-level: any file change triggers a full chain recompilation.
+ * - LRU eviction: workspace watchers are capped; least-recently-used are
+ *   closed when the cap is exceeded.
+ * - All registrations go through `ctx.effect()` for clean teardown.
+ */
+import { watch as chokidarWatch } from 'chokidar';
+import { dirname, resolve } from 'node:path';
+import { statSync } from 'node:fs';
+// ─── RuleWatcher ───────────────────────────────────────────────────────────
+/**
+ * Manages file watchers for rule files across workspaces.
+ * Each workspace gets its own watcher set; LRU eviction caps total count.
+ */
+export class RuleWatcher {
+    watchers = new Map();
+    debounceMs;
+    maxWatchers;
+    logger;
+    constructor(options = { logger: console }) {
+        this.debounceMs = options.debounceMs ?? 300;
+        this.maxWatchers = options.maxWatchers ?? 10;
+        this.logger = options.logger;
+    }
+    /**
+     * Start watching rule files for a workspace.
+     *
+     * @param cwd - The workspace root.
+     * @param ruleFiles - Absolute paths to the effective rule files (chain).
+     * @param reload - Callback to invoke (debounced) on any change.
+     */
+    watch(cwd, ruleFiles, reload) {
+        const key = resolve(cwd).toLowerCase();
+        // If already watching this workspace, just update the access time.
+        const existing = this.watchers.get(key);
+        if (existing !== undefined) {
+            existing.lastAccess = Date.now();
+            return;
+        }
+        // Evict LRU if at capacity.
+        this.evictIfNeeded();
+        // Collect all paths to watch: effective files + candidate file ancestors.
+        const paths = new Set();
+        for (const file of ruleFiles) {
+            paths.add(file);
+            // T3.3: Watch deepest existing ancestor for candidate files.
+            const ancestor = deepestExistingAncestor(file);
+            if (ancestor !== undefined)
+                paths.add(ancestor);
+        }
+        const watcher = chokidarWatch([...paths], {
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+        });
+        let timer = null;
+        const debouncedReload = () => {
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                timer = null;
+                try {
+                    reload();
+                }
+                catch (error) {
+                    this.logger.warn(`[dsh-perm-gate] rule reload failed: ${String(error)}`);
+                }
+            }, this.debounceMs);
+        };
+        watcher.on('change', debouncedReload);
+        watcher.on('add', debouncedReload);
+        watcher.on('unlink', debouncedReload);
+        watcher.on('error', (error) => {
+            this.logger.warn(`[dsh-perm-gate] watcher error: ${String(error)}`);
+        });
+        const entry = { cwd, watcher, timer, lastAccess: Date.now() };
+        this.watchers.set(key, entry);
+    }
+    /**
+     * Stop watching a specific workspace.
+     */
+    unwatch(cwd) {
+        const key = resolve(cwd).toLowerCase();
+        const entry = this.watchers.get(key);
+        if (entry === undefined)
+            return;
+        if (entry.timer !== null)
+            clearTimeout(entry.timer);
+        void entry.watcher.close();
+        this.watchers.delete(key);
+    }
+    /**
+     * Stop all watchers and clear state.
+     */
+    closeAll() {
+        for (const entry of this.watchers.values()) {
+            if (entry.timer !== null)
+                clearTimeout(entry.timer);
+            void entry.watcher.close();
+        }
+        this.watchers.clear();
+    }
+    /** Number of active workspace watchers. */
+    activeWatcherCount() {
+        return this.watchers.size;
+    }
+    /** Number of pending (debounced) reloads. */
+    pendingReloadCount() {
+        let count = 0;
+        for (const entry of this.watchers.values()) {
+            if (entry.timer !== null)
+                count++;
+        }
+        return count;
+    }
+    // ─── LRU eviction ──────────────────────────────────────────────────
+    evictIfNeeded() {
+        if (this.watchers.size < this.maxWatchers)
+            return;
+        // Find the least-recently-used entry.
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.watchers) {
+            if (entry.lastAccess < oldestTime) {
+                oldestTime = entry.lastAccess;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey !== undefined) {
+            this.unwatch(oldestKey);
+        }
+    }
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+/**
+ * Find the deepest existing ancestor directory of a file path.
+ * Used to watch for candidate files (expected-but-absent) through their
+ * closest existing parent.
+ */
+function deepestExistingAncestor(filePath) {
+    let dir = dirname(resolve(filePath));
+    let prev = '';
+    while (dir !== prev) {
+        if (existsSafe(dir))
+            return dir;
+        prev = dir;
+        dir = dirname(dir);
+    }
+    return undefined;
+}
+function existsSafe(path) {
+    try {
+        const stat = statSync(path);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "dsh-perm-gate",
-  "version": "2.0.0",
+  "version": "2.1.2",
   "description": "DSH permission-gate for the DeepSeek Harness 0.1.2+ line: a single self-sufficient, deterministic-first, fail-closed gate covering P0 hard-deny -> P1 session grant -> P2 static rule (allow/deny) chain -> P3 optional LLM semantic classifier -> P4 ask, with command whitelist/blacklist.",
   "type": "module",
   "files": [
     "lib",
+    "scripts/patch-permission-glyph.mjs",
     "cordis.patch.yml",
+    "dsh.plugin.json",
     "assets",
     "examples",
     "README.md",
@@ -54,7 +56,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "dsh-perm-gate": "./lib/cli.js"
+    "dsh-perm-gate": "./lib/cli.js",
+    "dsh-perm-gate-patch-glyph": "./scripts/patch-permission-glyph.mjs"
   },
   "engines": {
     "node": ">=20",
@@ -65,6 +68,7 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.0",
+    "chokidar": "^5.0.0",
     "yaml": "^2.5.0"
   },
   "devDependencies": {
@@ -89,6 +93,8 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit",
     "lint": "eslint src test scripts tsdown.config.ts eslint.config.mjs",
     "test": "vitest run",
+    "patch:glyph": "node scripts/patch-permission-glyph.mjs",
+    "patch:glyph:check": "node scripts/patch-permission-glyph.mjs --check",
     "verify:line": "node scripts/verify-line.mjs new",
     "verify:lines": "node scripts/verify-line.mjs both",
     "release:latest": "npm publish --tag latest",