dsh-perm-gate 2.1.0 → 3.0.0

package/lib/runtime.d.ts

@@ -1,16 +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>;
@@ -73,6 +99,8 @@ interface PendingAsk {
     readonly learningKey?: string;
 }
 export interface PermGateRuntimeOptions extends PermGateConfig {
+    /** Workspace root for chain resolution. Defaults to process.cwd(). */
+    readonly cwd?: string;
     readonly onRulesChanged?: (ruleset: CompiledRuleset) => void;
     readonly now?: () => number;
     /**
@@ -132,6 +160,42 @@ export interface PermGateRuntimeOptions extends PermGateConfig {
      * review page's diff/revert data plane (events are still recorded).
      */
     readonly snapshotsDir?: string;
+    /**
+     * Raise one interactive approval request on behalf of a subprocess network
+     * connection. Wired by `apply` to the DSH `approval` service
+     * (`approval.request`), which routes the prompt to the agent, appends the
+     * `approval/asked` + `approval/decided` audit pair, and applies the session
+     * policy before any answerer runs.
+     *
+     * Absent (or throwing) means the connection cannot ride the seam and the
+     * gate fails closed to `deny`. Only `'allowed-once'` is treated as an allow.
+     */
+    readonly requestApproval?: (req: NetworkApprovalRequest) => Promise<ApprovalOutcomeLike>;
+    /**
+     * How long one approved network target stays approved for the session (ms).
+     * A single shell command routinely opens many connections to the same host;
+     * without this the human would be prompted once per connection.
+     * 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. */
@@ -152,6 +216,30 @@ export interface ApprovalRequestLike {
 }
 /** A closed approval outcome, structurally the DSH seam's `ApprovalOutcome`. */
 export type ApprovalOutcomeLike = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+/**
+ * One approval ask the gate raises on behalf of a subprocess network
+ * connection. Structurally the subset of the DSH `ApprovalRequest` the gate
+ * supplies — the host service adds the borrowed session/log handling.
+ */
+export interface NetworkApprovalRequest {
+    /** The host agent the question is asked on behalf of (routes the prompt). */
+    readonly agent: unknown;
+    /** The tool whose subprocess opened the connection. */
+    readonly toolName: string;
+    /** The exact tool call, when the host gave one — lets the UI attach the prompt. */
+    readonly callId?: string;
+    readonly reason: string;
+    readonly signal?: AbortSignal;
+}
+/** The attribution the proxy layer receives for one connection. */
+export interface ShellAttribution {
+    readonly tool: string;
+    readonly callId?: string;
+    /** The host agent, needed to route an approval request. */
+    readonly agent?: unknown;
+    readonly sessionId: string;
+    readonly signal?: AbortSignal;
+}
 export declare class PermGateRuntime {
     private readonly options;
     private ruleset;
@@ -165,6 +253,14 @@ export declare class PermGateRuntime {
     private readonly gatePresets;
     /** Extra tool names the user classified as safe (config `autoAllowTools`). */
     private readonly autoAllowExtra;
+    /** In-flight shell executions, for proxy-layer network attribution. */
+    private readonly inFlightShells;
+    /** Stable key per execution object (the host call id is not always present). */
+    private readonly shellKeys;
+    private shellSeq;
+    /** Session-scoped network grants: grantKey -> expiry epoch ms. */
+    private readonly networkGrants;
+    private readonly networkGrantTtlMs;
     /**
      * Cache of the permission-preset fold. The key is the log's length plus the
      * identity of its LAST event: a session's log only appends, so "same length
@@ -174,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). */
@@ -213,6 +315,40 @@ export declare class PermGateRuntime {
     /** Deep read-only view of the learning state (diagnostics/tests). */
     learningSnapshot(): ReturnType<RiskLearning['snapshot']>;
     private ctxFor;
+    /**
+     * Register a shell execution as in-flight so a proxy-layer block made by its
+     * child process can be attributed back to the session — and therefore ride
+     * the interactive approval seam. Called when the gate lets a shell call run;
+     * {@link endShellExecution} removes it.
+     */
+    beginShellExecution(exec: ToolExecutionLike): void;
+    /** Remove a shell execution from the in-flight table (its tool call settled). */
+    endShellExecution(exec: ToolExecutionLike): void;
+    /** Drop every in-flight entry (dispose / session teardown). */
+    clearShellExecutions(): void;
+    /**
+     * The newest live in-flight shell execution, for proxy-layer attribution.
+     * Stale entries (a shell that never reported a result) are expired here so a
+     * long-dead call can never authorize a later connection.
+     */
+    currentAttribution(): ShellAttribution | undefined;
+    /** A stable per-execution key: the host call id, else an object-keyed fallback. */
+    private shellKeyOf;
+    /**
+     * Ask the human to allow one network target, on behalf of the attributed
+     * shell execution. Returns `'allow'` only for an explicit `allowed-once`;
+     * every other outcome (rejection, cancellation, timeout, no answerer)
+     * fails closed to `'deny'`.
+     *
+     * The approval seam requires an open turn — the durable audit pair must be
+     * enclosed by the log's commit boundary — which holds here because the ask
+     * happens *while* the shell tool call is executing.
+     */
+    askNetwork(target: NetworkTarget, reason: string, timeoutMs: number): Promise<'allow' | 'deny'>;
+    /** Record one network escalation outcome in the audit mirror + event feed. */
+    private auditNetworkAsk;
+    /** The compiled ruleset (read-only view for network module). */
+    get compiledRuleset(): CompiledRuleset;
     private liveRiskLearning;
     private liveRiskSediment;
     private liveClassifySource;
@@ -238,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`
@@ -318,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
@@ -397,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;
 }