@wrongstack/core 0.306.4 → 0.307.0

package/dist/security/permission-explain.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from '../core/context.js';
+import type { PermissionTrace, TrustPolicy } from '../types/permission.js';
+import type { Tool } from '../types/tool.js';
+export interface PermissionExplainContext {
+    policy: TrustPolicy;
+    policyInvalid: boolean;
+    wildcardEntries: {
+        pattern: string;
+        value: TrustPolicy[string];
+    }[];
+    sessionDenied: Map<string, boolean>;
+    sessionAllowed: Map<string, boolean>;
+    yolo: boolean;
+    promptDelegatePresent: boolean;
+    isSensitiveReadCall(tool: Tool, input: unknown): boolean;
+    yoloBlockedAsDestructive(tool: Tool, input: unknown, ctx: Context): boolean;
+}
+export declare function explainPermissionTrace(state: PermissionExplainContext, tool: Tool, input: unknown, ctx: Context): PermissionTrace;
+//# sourceMappingURL=permission-explain.d.ts.map

package/dist/security/permission-policy.d.ts

@@ -8,11 +8,6 @@ export { alwaysAllowUnavailableReason, matchesTrust, matchesCommandTrust, hasShe
 export interface PermissionPolicyOptions {
     trustFile: string;
     yolo?: boolean | undefined;
-    /**
-     * Let YOLO auto-approve destructive shell commands too. Off by default: with
-     * YOLO on, `rm -rf`, git history rewrites and external publishes still ask
-     * (WS-008).
-     */
     yoloDestructive?: boolean | undefined;
     promptDelegate?: (tool: Tool, input: unknown, suggestedPattern: string) => Promise<'yes' | 'no' | 'always' | 'deny'>;
     inputReader?: InputReader | undefined;
@@ -22,110 +17,22 @@ export declare class DefaultPermissionPolicy implements PermissionPolicy {
     private loaded;
     private readonly trustFile;
     private yolo;
-    /**
-     * Session-scoped "soft deny" map. When the user presses 'n' (block once),
-     * the tool+pattern is added here. If the LLM retries in the same session,
-     * we return deny directly without asking again.
-     *
-     * Cleared on reload() since reload = fresh trust file snapshot.
-     */
     private sessionDenied;
-    /**
-     * Session-scoped one-shot "soft trust" map. When the user presses 'y', the
-     * tool+pattern is added here so the immediate confirm re-run can proceed.
-     * The entry is consumed on first use; future calls must ask again unless the
-     * user chose persistent trust.
-     *
-     * Cleared on reload().
-     */
     private sessionAllowed;
-    /**
-     * Interactive prompt delegate. When set, `evaluate()` calls it to get a
-     * user decision synchronously (CLI REPL path). When cleared (TUI / WebUI),
-     * `evaluate()` returns `confirm` so the caller can emit
-     * `tool.confirm_needed` for the UI layer to handle.
-     *
-     * Mutable so the host can switch from CLI-prompt to event-driven
-     * confirmation at runtime (e.g. when `--goal` forces TUI mode after
-     * the agent was already constructed).
-     */
     private promptDelegate?;
-    /** Pre-compiled wildcard patterns — rebuilt on reload for O(1) lookup. */
     private wildcardEntries;
-    /**
-     * Evaluate-result cache. Keyed by `tool.name::subject::permissionFingerprint`
-     * so repeated calls with the same tool+input skip namespace matching,
-     * subject computation, and pattern matching (matchAny). The fingerprint
-     * suffix covers the `Tool` fields `evaluate()` reads (`permission`,
-     * `riskTier`, `mutating`, `capabilities`), so a tool redefined via
-     * `ToolRegistry.wrap()` misses the cache instead of inheriting a stale
-     * verdict.
-     *
-     * Cleared on any state change (reload, trust, deny, yolo toggle) because
-     * the result depends on the full policy state. The write-tool smart-bypass
-     * (step 7 in `evaluate()`) is not cached since `ctx.hasRead()` changes
-     * dynamically within a session.
-     *
-     * P3 #17 (before-release.md): capped at 500 entries via LRU eviction. An
-     * iteration that evaluates thousands of unique tool+subject combinations
-     * (e.g. repeated `tool-help` or `bash` with different commands) can grow
-     * the cache without bound. 500 is far more than any single iteration needs;
-     * the LRU evicts the least-recently-used entries first.
-     */
     private _evalCache;
     private policyDiagnostics;
     private policyInvalid;
-    /**
-     * When true, YOLO also auto-approves clearly destructive shell commands.
-     *
-     * WS-008: `isClearlyDestructiveBashCommand` was exported and heavily tested
-     * but called from zero production modules, so YOLO returned `auto` for
-     * everything — including `rm -rf`, git history rewrites, and external
-     * publishes. The `'yolo_destructive'` decision source, the getter/setter on
-     * PermissionPolicy, and the TUI branch that reads it all existed; only the
-     * gate itself was missing. Defaults to false: destructive commands still ask,
-     * even in YOLO.
-     */
     private yoloDestructive;
     constructor(opts: PermissionPolicyOptions);
-    /** Allow YOLO to cover destructive shell commands too (off by default). */
     setYoloDestructive(enabled: boolean): void;
-    /** Whether YOLO currently extends to destructive shell commands. */
     getYoloDestructive(): boolean;
-    /**
-     * True when this call is an FS_WRITE whose target lands inside WrongStack's
-     * own state root.
-     *
-     * FS_WRITE tools disagree on where the target path lives: write/edit use
-     * `path`, replace/format/git `files` (string OR array), patch `directory`,
-     * design `out`, scaffold writes under `cwd`/`template`. Checking only
-     * `path`/`file_path` let a state-root write merely switch tools, so every
-     * path-bearing key is inspected.
-     *
-     * Shared by the YOLO carve-out and the eval-cache guard so the two cannot
-     * drift: the carve-out scans all path keys while the cache key fingerprints
-     * only the subject key, so the cache must consult the same predicate or a
-     * secondary state-root key can be replayed a cached `auto`.
-     */
     private hasAgentStateWriteTarget;
-    /**
-     * True when YOLO is on but this specific call is a destructive shell command
-     * the user has not opted to auto-approve. Shared by `evaluate()` and the
-     * explain/trace path so the two cannot drift.
-     */
     private yoloBlockedAsDestructive;
-    /**
-     * Replace (or clear) the interactive prompt delegate at runtime.
-     * Used by the CLI to switch from inline prompts (REPL) to event-driven
-     * confirmation (TUI) when the run mode is determined after the policy
-     * was constructed (e.g. `--goal` auto-flipping to TUI).
-     */
     setPromptDelegate(delegate: PermissionPolicyOptions['promptDelegate']): void;
-    /** Toggle YOLO (auto-approve) mode at runtime. */
     setYolo(enabled: boolean): void;
-    /** Check whether YOLO mode is currently active. */
     getYolo(): boolean;
-    /** Read-only diagnostics for policy inspector/editor surfaces. */
     getPolicyDiagnostics(): readonly TrustPolicyDiagnostic[];
     reload(): Promise<void>;
     private _logDeny;
@@ -135,26 +42,18 @@ export declare class DefaultPermissionPolicy implements PermissionPolicy {
         tool: string;
         pattern: string;
     }): Promise<void>;
-    /** Persist a deny rule — this tool+pattern pair is permanently blocked. */
     deny(rule: {
         tool: string;
         pattern: string;
     }): Promise<void>;
-    /** Block this tool+pattern for the rest of this session (no trust file). */
     denyOnce(rule: {
         tool: string;
         pattern: string;
     }): void;
-    /** Auto-approve this tool+pattern once (no trust file). */
     allowOnce(rule: {
         tool: string;
         pattern: string;
     }): void;
-    /**
-     * Side-effect-free permission evaluation trace. Mirrors `evaluate()`
-     * step-by-step without prompting the user, writing to trust files, or
-     * mutating session state. Returns the full ordered trace and winner.
-     */
     explain(tool: Tool, input: unknown, ctx: Context): Promise<PermissionTrace>;
     private findNamespaceEntry;
 }

package/dist/security/yolo-risk.d.ts

@@ -2,10 +2,11 @@ export declare function getInputString(input: unknown, key: string): string | un
 export declare function pathLooksInsideProject(rawPath: string, projectRoot: string | undefined): boolean;
 /**
  * Best-effort detection of a *catastrophic* shell command — system-/disk-/
- * home-wide, effectively irreversible destruction. `projectRoot` is accepted
- * for signature stability but is intentionally unused: catastrophic targets are
- * absolute (filesystem root, a drive root, the home directory, a system
- * directory) and so are independent of where the project lives.
+ * home-wide, effectively irreversible destruction, OR a write to WrongStack's
+ * own trusted state files that could disable security boundaries.
+ * `projectRoot` is accepted for signature stability but is intentionally
+ * unused for catastrophic targets (they are absolute). It is not used for
+ * state-root detection either (those paths are resolved absolutely).
  */
 export declare function isClearlyDestructiveBashCommand(command: string, projectRoot: string | undefined): boolean;
 //# sourceMappingURL=yolo-risk.d.ts.map