dsh-perm-gate 2.1.0 → 3.0.0

package/lib/events.d.ts

@@ -1,3 +1,4 @@
+import type { RulesView } from './rules-view.js';
 /** One gate decision event. `kind` drives the client notice strip styling. */
 export interface GateEvent {
     /** Monotonic id (resumed from the file across restarts). */
@@ -8,9 +9,11 @@ export interface GateEvent {
     /**
      * auto = allowed (rule/grant/llm), ask = routed to the human, deny = vetoed,
      * learned = confirmation settled, manual-* = the human's terminal answer to an
-     * ask (approved / rejected / cancelled).
+     * ask (approved / rejected / cancelled), stand-down = the gate itself is
+     * inactive in this session's permission preset and therefore decided nothing
+     * (see {@link GateEvent.verdict} `stand-down`).
      */
-    readonly kind: 'auto' | 'ask' | 'deny' | 'learned' | 'manual-approved' | 'manual-rejected' | 'manual-cancelled';
+    readonly kind: 'auto' | 'ask' | 'deny' | 'learned' | 'manual-approved' | 'manual-rejected' | 'manual-cancelled' | 'stand-down';
     /** Risk category when an LLM verdict contributed to the decision. */
     readonly risk?: string;
     /** Truncated decision reason. */
@@ -127,11 +130,14 @@ export interface WebServerLike {
 export declare const EVENTS_ROUTE = "/api/dsh-perm-gate/events";
 export declare const LEARNING_ROUTE = "/api/dsh-perm-gate/learning";
 export declare const HEALTH_ROUTE = "/api/dsh-perm-gate/health";
+export declare const NETWORK_ROUTE = "/api/dsh-perm-gate/network";
 export declare const RECEIVER_ROUTE = "/api/dsh-perm-gate/receiver";
 export declare const DIFF_ROUTE = "/api/dsh-perm-gate/diff";
 export declare const REVERT_ROUTE = "/api/dsh-perm-gate/revert";
 export declare const SNAPSHOTS_STATS_ROUTE = "/api/dsh-perm-gate/snapshots-stats";
 export declare const SNAPSHOTS_CLEAR_ROUTE = "/api/dsh-perm-gate/snapshots-clear";
+export declare const DRY_RUN_ROUTE = "/api/dsh-perm-gate/dry-run";
+export declare const RULES_ROUTE = "/api/dsh-perm-gate/rules";
 /**
  * Register `GET /api/dsh-perm-gate/events?sessionId=&since=` on the webServer
  * service. Returns whether the route was registered (false when the service is
@@ -177,12 +183,73 @@ export declare function registerHealthRoute(server: unknown, provider: {
         detail: string;
     }>;
 }): (() => void) | undefined;
+/** The network-state face the settings UI's network section needs. */
+export interface NetworkRouteProvider {
+    snapshot(): unknown;
+}
+/**
+ * Register the network diagnostics route: `GET /api/dsh-perm-gate/network`
+ * returns the live network state (mode, bind, port, proxy liveness, env
+ * injection, block counters, recent blocks). Read-only — a policy change goes
+ * through the settings namespace, never through HTTP.
+ * Returns whether the route was registered.
+ */
+export declare function registerNetworkRoute(server: unknown, provider: NetworkRouteProvider): (() => void) | undefined;
 /** The learning-store face the settings UI's sediment view needs. */
 export interface LearningRouteProvider {
     snapshot(): unknown;
     threshold(): number;
     reset(key: string, fp?: string): void;
 }
+/** One rule-test request: the call to evaluate, nothing else. */
+export interface DryRunRequest {
+    readonly tool: string;
+    readonly args: Record<string, unknown>;
+    readonly permissive?: boolean;
+}
+/**
+ * The rule-test face the settings card calls. `run` evaluates one call against
+ * the ruleset the gate currently has loaded and returns the report from
+ * `dryRunResult`. It must not change any state — see {@link registerDryRunRoute}.
+ */
+export interface DryRunRouteProvider {
+    run(request: DryRunRequest): unknown;
+}
+/**
+ * Register `POST /api/dsh-perm-gate/dry-run` — the rule-test panel's endpoint.
+ * Body `{ tool, args?, permissive? }`; the response carries the effective
+ * verdict plus the rule layer's own answer.
+ *
+ * **Read-only by construction.** Unlike `/learning` (GET reads, POST resets), this
+ * route has no write form: it never edits rules, grants, learning state or the
+ * settings namespace, and the provider it delegates to evaluates against a
+ * throwaway or live read path only. Testing a rule must not be able to change
+ * the ruleset — otherwise "test it first" would itself be the risky action.
+ *
+ * Returns whether the route was registered.
+ */
+export declare function registerDryRunRoute(server: unknown, provider: DryRunRouteProvider): (() => void) | undefined;
+/**
+ * The permissions-file face the settings card calls. `view` reads the rules file
+ * the gate is loading; it must never write it.
+ */
+export interface RulesRouteProvider {
+    view(): RulesView;
+}
+/**
+ * Register `GET /api/dsh-perm-gate/rules` — the panel's view of the permissions
+ * YAML the gate actually loads.
+ *
+ * **Read-only by construction**, like {@link registerDryRunRoute}: there is no
+ * write form. The card could already *edit* this file — the allowlist section
+ * appends and replaces patterns — but had no way to display it, so an operator
+ * changing rules through the panel could not see the document being changed.
+ * Reading must not be the risky act, and a viewer that could write would make
+ * "let me just look at the rules" a mutation.
+ *
+ * Returns whether the route was registered.
+ */
+export declare function registerRulesRoute(server: unknown, provider: RulesRouteProvider): (() => void) | undefined;
 /**
  * Register the learning-store routes on the webServer service:
  * `GET  /api/dsh-perm-gate/learning` → the store snapshot + live threshold,

package/lib/events.js

@@ -351,11 +351,14 @@ function readBody(req, limit = 1024 * 1024) {
 export const EVENTS_ROUTE = '/api/dsh-perm-gate/events';
 export const LEARNING_ROUTE = '/api/dsh-perm-gate/learning';
 export const HEALTH_ROUTE = '/api/dsh-perm-gate/health';
+export const NETWORK_ROUTE = '/api/dsh-perm-gate/network';
 export const RECEIVER_ROUTE = '/api/dsh-perm-gate/receiver';
 export const DIFF_ROUTE = '/api/dsh-perm-gate/diff';
 export const REVERT_ROUTE = '/api/dsh-perm-gate/revert';
 export const SNAPSHOTS_STATS_ROUTE = '/api/dsh-perm-gate/snapshots-stats';
 export const SNAPSHOTS_CLEAR_ROUTE = '/api/dsh-perm-gate/snapshots-clear';
+export const DRY_RUN_ROUTE = '/api/dsh-perm-gate/dry-run';
+export const RULES_ROUTE = '/api/dsh-perm-gate/rules';
 /**
  * Register `GET /api/dsh-perm-gate/events?sessionId=&since=` on the webServer
  * service. Returns whether the route was registered (false when the service is
@@ -651,6 +654,126 @@ export function registerHealthRoute(server, provider) {
         },
     });
 }
+/**
+ * Register the network diagnostics route: `GET /api/dsh-perm-gate/network`
+ * returns the live network state (mode, bind, port, proxy liveness, env
+ * injection, block counters, recent blocks). Read-only — a policy change goes
+ * through the settings namespace, never through HTTP.
+ * Returns whether the route was registered.
+ */
+export function registerNetworkRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: NETWORK_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET' && req.method !== 'HEAD') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            try {
+                json(res, 200, { ok: true, ...provider.snapshot() });
+            }
+            catch (e) {
+                json(res, 500, { ok: false, error: String(e?.message ?? e) });
+            }
+        },
+    });
+}
+/**
+ * Register `POST /api/dsh-perm-gate/dry-run` — the rule-test panel's endpoint.
+ * Body `{ tool, args?, permissive? }`; the response carries the effective
+ * verdict plus the rule layer's own answer.
+ *
+ * **Read-only by construction.** Unlike `/learning` (GET reads, POST resets), this
+ * route has no write form: it never edits rules, grants, learning state or the
+ * settings namespace, and the provider it delegates to evaluates against a
+ * throwaway or live read path only. Testing a rule must not be able to change
+ * the ruleset — otherwise "test it first" would itself be the risky action.
+ *
+ * Returns whether the route was registered.
+ */
+export function registerDryRunRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: DRY_RUN_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            void (async () => {
+                try {
+                    const parsed = await readBody(req);
+                    const tool = parsed.tool;
+                    if (typeof tool !== 'string' || tool === '') {
+                        json(res, 400, { ok: false, error: 'missing tool' });
+                        return;
+                    }
+                    const args = parsed.args;
+                    if (args !== undefined && (typeof args !== 'object' || args === null || Array.isArray(args))) {
+                        json(res, 400, { ok: false, error: 'args must be an object' });
+                        return;
+                    }
+                    const result = provider.run({
+                        tool,
+                        args: (args ?? {}),
+                        ...(typeof parsed.permissive === 'boolean' ? { permissive: parsed.permissive } : {}),
+                    });
+                    json(res, 200, { ok: true, result });
+                }
+                catch (e) {
+                    json(res, 500, { ok: false, error: String(e?.message ?? e) });
+                }
+            })();
+        },
+    });
+}
+/**
+ * Register `GET /api/dsh-perm-gate/rules` — the panel's view of the permissions
+ * YAML the gate actually loads.
+ *
+ * **Read-only by construction**, like {@link registerDryRunRoute}: there is no
+ * write form. The card could already *edit* this file — the allowlist section
+ * appends and replaces patterns — but had no way to display it, so an operator
+ * changing rules through the panel could not see the document being changed.
+ * Reading must not be the risky act, and a viewer that could write would make
+ * "let me just look at the rules" a mutation.
+ *
+ * Returns whether the route was registered.
+ */
+export function registerRulesRoute(server, provider) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: RULES_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET') {
+                json(res, 405, { ok: false, error: 'method not allowed' });
+                return;
+            }
+            try {
+                json(res, 200, { ok: true, result: provider.view() });
+            }
+            catch (e) {
+                json(res, 500, { ok: false, error: String(e?.message ?? e) });
+            }
+        },
+    });
+}
 /**
  * Register the learning-store routes on the webServer service:
  * `GET  /api/dsh-perm-gate/learning` → the store snapshot + live threshold,

package/lib/index.d.ts

@@ -53,5 +53,5 @@ export declare function makeApprovalAnswerer(runtime: Pick<PermGateRuntime, 'set
  * `riskTimeoutMs` (default 20 s), and a grader failure keeps the original ask
  * (fail-closed).
  */
-export declare function makePreExecuteListener(runtime: Pick<PermGateRuntime, 'decideExecution' | 'refineAsk'>): (exec: ToolExecutionLike, next: () => Promise<unknown>) => Promise<unknown>;
+export declare function makePreExecuteListener(runtime: Pick<PermGateRuntime, 'decideExecution' | 'refineAsk' | 'beginShellExecution'>): (exec: ToolExecutionLike, next: () => Promise<unknown>) => Promise<unknown>;
 export declare function apply(ctx: Context, config?: Record<string, unknown>): PermGateRuntime;