dsh-perm-gate 2.1.0 → 3.0.0

package/lib/agent-identity.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Agent identity extraction for the `agents` rule dimension.
+ *
+ * Given a tool execution context, produces zero or more identity candidates
+ * that the `agents` dimension can match against. Candidates are produced
+ * in priority order: most-specific first.
+ *
+ * Identity model:
+ *   - `main`          — the primary (top-level) agent session
+ *   - `subagent`      — a delegated child agent (parentAuthorized present)
+ *   - `preset:<name>` — running under a named permission preset
+ *
+ * When no identity can be determined, an empty array is returned and the
+ * `agents` dimension in rules fail-closes (no match → rule skipped).
+ */
+/**
+ * The subset of ToolExecutionLike we need. Defined as a permissive interface
+ * to avoid a circular import with runtime.ts. Uses `unknown` for event types
+ * since we only need to read `.type`/`.kind` and `.preset`/`.tier` properties.
+ */
+export interface ExecutionLike {
+    readonly parentAuthorized?: boolean;
+    readonly agent?: {
+        readonly sessionId?: string;
+        readonly session?: {
+            readonly id?: string;
+            readonly events?: readonly unknown[];
+            readonly snapshotEvents?: () => readonly unknown[];
+            readonly ownEvents?: () => readonly unknown[];
+        };
+    };
+}
+/**
+ * Extract agent identity candidates from a tool execution context.
+ *
+ * Returns a deduplicated list of identity strings. The `agents` rule
+ * dimension matches if ANY candidate matches ANY entry in the rule's
+ * `agents` list.
+ *
+ * @returns candidates in priority order, e.g. `['preset:permissive', 'subagent']`
+ *          or `['main']`. Empty array = undecidable → agents rules fail-close.
+ */
+export declare function extractAgentCandidates(exec: ExecutionLike): string[];

package/lib/agent-identity.js

@@ -0,0 +1,95 @@
+/**
+ * Agent identity extraction for the `agents` rule dimension.
+ *
+ * Given a tool execution context, produces zero or more identity candidates
+ * that the `agents` dimension can match against. Candidates are produced
+ * in priority order: most-specific first.
+ *
+ * Identity model:
+ *   - `main`          — the primary (top-level) agent session
+ *   - `subagent`      — a delegated child agent (parentAuthorized present)
+ *   - `preset:<name>` — running under a named permission preset
+ *
+ * When no identity can be determined, an empty array is returned and the
+ * `agents` dimension in rules fail-closes (no match → rule skipped).
+ */
+/**
+ * Extract agent identity candidates from a tool execution context.
+ *
+ * Returns a deduplicated list of identity strings. The `agents` rule
+ * dimension matches if ANY candidate matches ANY entry in the rule's
+ * `agents` list.
+ *
+ * @returns candidates in priority order, e.g. `['preset:permissive', 'subagent']`
+ *          or `['main']`. Empty array = undecidable → agents rules fail-close.
+ */
+export function extractAgentCandidates(exec) {
+    const candidates = [];
+    // 1. Preset name — most specific identity.
+    const preset = presetFromEvents(exec);
+    if (preset !== undefined) {
+        candidates.push(`preset:${preset}`);
+    }
+    // 2. Main vs subagent — determined by parentAuthorized presence.
+    if (exec.parentAuthorized !== undefined) {
+        // parentAuthorized is present → this is a child/subagent.
+        candidates.push('subagent');
+    }
+    else {
+        // parentAuthorized absent → assume main agent.
+        candidates.push('main');
+    }
+    return candidates;
+}
+/**
+ * Derive the current permission preset name from the session event log.
+ *
+ * The event log is append-only; the last `preset-switch` or `tier-select`
+ * event carries the current preset. Returns undefined when the log is
+ * unavailable or no preset event exists.
+ */
+function presetFromEvents(exec) {
+    const events = eventsOf(exec);
+    if (events === undefined)
+        return undefined;
+    // Walk backwards to find the most recent preset/tier event.
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (typeof ev !== 'object' || ev === null)
+            continue;
+        const rec = ev;
+        const type = rec.type ?? rec.kind;
+        if (typeof type !== 'string')
+            continue;
+        if (type === 'preset-switch' || type === 'tier-select') {
+            const value = rec.preset ?? rec.tier ?? rec.value;
+            if (typeof value === 'string' && value !== '')
+                return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Read the session event log from a ToolExecutionLike, handling both
+ * DSH 0.1.1 (plain array) and 0.1.2+ (function accessors) shapes.
+ */
+function eventsOf(exec) {
+    const session = exec.agent?.session;
+    if (session === undefined)
+        return undefined;
+    if (typeof session.snapshotEvents === 'function') {
+        try {
+            return session.snapshotEvents();
+        }
+        catch { /* ignore */ }
+    }
+    if (typeof session.ownEvents === 'function') {
+        try {
+            return session.ownEvents();
+        }
+        catch { /* ignore */ }
+    }
+    if (Array.isArray(session.events))
+        return session.events;
+    return undefined;
+}

package/lib/allowlist.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Minimal face of the DSH settings scope the rules namespace is bound to
+ * (`scope.get()` / `scope.update(patch)`; the host merges a patch into the
+ * user layer, replacing arrays wholesale).
+ */
+export interface SettingsRulesScope {
+    get(): unknown;
+    update(patch: object): Promise<unknown> | unknown;
+}
+/** The allow-list command patterns currently in the settings rules document (read-only). */
+export declare function listAllowFromRulesDoc(doc: unknown): string[];
+/**
+ * Append one command pattern as a new `allow` entry in the settings rules
+ * namespace. When the namespace is still unconfigured (bare defaults) and a
+ * file document is supplied, the namespace is seeded from it first — the
+ * implicit migration — so the first settings write cannot shadow file-defined
+ * deny/ask rules. Returns false when the scope rejects the write.
+ */
+export declare function appendAllowToSettings(scope: SettingsRulesScope, pattern: string, reason?: string, seed?: unknown): Promise<boolean>;
+/**
+ * Replace the settings rules namespace's `allow` whitelist with exactly the
+ * given command patterns (one allow entry per pattern); empty clears it.
+ * Other sections (deny / ask / defaultAction) are preserved — seeded from the
+ * file document on the namespace's first write. Returns false when the scope
+ * rejects the write.
+ */
+export declare function replaceAllowInSettings(scope: SettingsRulesScope, patterns: readonly string[], reason?: string, seed?: unknown): Promise<boolean>;
 /**
  * Append one command pattern as a new `allow` entry in the rules file.
  * Returns false (leaving the file untouched) on any I/O or shape error.

package/lib/allowlist.js

@@ -2,11 +2,113 @@
  * Durable allowlist (whitelist) writes for dsh-perm-gate.
  *
  * The "allow everywhere" approval action appends a matched command pattern to
- * the rules file's `allow` list and reloads, so a human-approved command is
+ * the rules' `allow` list and reloads, so a human-approved command is
  * persistently whitelisted across sessions — not just granted once.
+ *
+ * Two storage backs, per the dual-source migration:
+ * - **settings** (`appendAllowToSettings` / `replaceAllowInSettings`) — the
+ *   `dsh-perm-gate-rules` namespace; the primary write path once the settings
+ *   service is available.
+ * - **rules file** (`appendAllowCommand` / `replaceAllowCommands`) — the legacy
+ *   path, kept as the fallback when no settings scope is wired (and as the
+ *   migration seed: the first settings write carries the file document along so
+ *   file-defined deny/ask rules are not shadowed).
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { parse, stringify } from 'yaml';
+import { isRulesConfigured } from './config.js';
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Accept both the bare rules form and the file's `permissions:`-wrapped form. */
+function unwrapPermissions(seed) {
+    if (!isRecord(seed))
+        return {};
+    return isRecord(seed['permissions']) ? seed['permissions'] : seed;
+}
+/** The file document a first write should migrate into the namespace, or bare defaults. */
+function seedOrDefaults(seed) {
+    const root = unwrapPermissions(seed);
+    return {
+        defaultAction: typeof root['defaultAction'] === 'string' ? root['defaultAction'] : 'ask',
+        deny: Array.isArray(root['deny']) ? root['deny'] : [],
+        allow: Array.isArray(root['allow']) ? root['allow'] : [],
+        ask: Array.isArray(root['ask']) ? root['ask'] : [],
+    };
+}
+function allowEntriesOf(section) {
+    const allow = section['allow'];
+    return Array.isArray(allow) ? allow : [];
+}
+function commandEntries(patterns, reason) {
+    return patterns.map((pattern) => ({ command: [pattern], reason }));
+}
+/** The allow-list command patterns currently in the settings rules document (read-only). */
+export function listAllowFromRulesDoc(doc) {
+    const section = unwrapPermissions(doc);
+    const out = [];
+    for (const entry of allowEntriesOf(section)) {
+        if (!isRecord(entry))
+            continue;
+        const command = entry['command'];
+        if (typeof command === 'string') {
+            out.push(command);
+            continue;
+        }
+        if (!Array.isArray(command))
+            continue;
+        for (const c of command)
+            if (typeof c === 'string')
+                out.push(c);
+    }
+    return out;
+}
+/**
+ * Append one command pattern as a new `allow` entry in the settings rules
+ * namespace. When the namespace is still unconfigured (bare defaults) and a
+ * file document is supplied, the namespace is seeded from it first — the
+ * implicit migration — so the first settings write cannot shadow file-defined
+ * deny/ask rules. Returns false when the scope rejects the write.
+ */
+export async function appendAllowToSettings(scope, pattern, reason = 'permissive allow-everywhere', seed) {
+    try {
+        const current = scope.get();
+        const section = isRulesConfigured(current) && isRecord(current)
+            ? { ...current }
+            : seedOrDefaults(seed);
+        const allow = allowEntriesOf(section);
+        allow.push({ command: [pattern], reason });
+        section['allow'] = allow;
+        await scope.update(section);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Replace the settings rules namespace's `allow` whitelist with exactly the
+ * given command patterns (one allow entry per pattern); empty clears it.
+ * Other sections (deny / ask / defaultAction) are preserved — seeded from the
+ * file document on the namespace's first write. Returns false when the scope
+ * rejects the write.
+ */
+export async function replaceAllowInSettings(scope, patterns, reason = 'permissive allowlist', seed) {
+    try {
+        if (patterns === undefined)
+            return false;
+        const current = scope.get();
+        const section = isRulesConfigured(current) && isRecord(current)
+            ? { ...current }
+            : seedOrDefaults(seed);
+        section['allow'] = commandEntries(patterns, reason);
+        await scope.update(section);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Append one command pattern as a new `allow` entry in the rules file.
  * Returns false (leaving the file untouched) on any I/O or shape error.

package/lib/cli.js

@@ -10,7 +10,7 @@
  */
 import { parseArgs } from 'node:util';
 import { resolve } from 'node:path';
-import { PermGateRuntime } from './runtime.js';
+import { createDryRunRuntime, runDryRun } from './dry-run.js';
 function main() {
     const { values } = parseArgs({
         options: {
@@ -23,11 +23,7 @@ function main() {
         },
     });
     const rulesFile = values.rules ? resolve(values.rules) : undefined;
-    const runtime = new PermGateRuntime({
-        rulesFile,
-        caseInsensitivePaths: true,
-        permissive: values.permissive || undefined,
-    });
+    const runtime = createDryRunRuntime({ rulesFile, permissive: values.permissive });
     if (values.list) {
         process.stdout.write(JSON.stringify({
             rulesFile,
@@ -53,15 +49,16 @@ function main() {
         process.exitCode = 2;
         return;
     }
-    const decision = runtime.decideExecution({
-        name: tool,
-        arguments: args,
-        cwd: values.cwd ? resolve(values.cwd) : process.cwd(),
-    });
+    // `hostView` reproduces this command's historic output exactly: it reports the
+    // host-facing decision path (whose `allow` is a bare passthrough with no
+    // reason) and its audit count. The panel reports the pure policy verdict
+    // instead, because a session-less caller must not inherit the session layers.
+    const result = runDryRun({ tool, args, rulesFile, cwd: values.cwd, hostView: true }, runtime);
+    const host = result.host;
     process.stdout.write(JSON.stringify({
-        decision: decision === undefined ? 'allow' : decision.kind,
-        reason: decision?.reason ?? '(default/passthrough)',
-        audited: runtime.auditEntries.length,
+        decision: host?.verdict ?? result.verdict,
+        reason: host?.reason ?? result.reason,
+        audited: host?.audited ?? 0,
     }, null, 2) + '\n');
 }
 main();