@themoltnet/pi-runtime 0.16.0 → 0.18.0

package/dist/testing.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The policy each shape resolves to. The E2E suite creates real runtime
+ * policies from these same values, so a live REST-resolved policy and the unit
+ * fixture cannot drift apart.
+ */
+export declare const ESCAPE_POLICY_FIXTURES: Record<EscapePolicyShape, EscapePolicyFixture>;
+
+export declare interface EscapePolicyFixture {
+    /** Runtime/MCP tool names the policy allows. */
+    tools: string[];
+    /** Shell argv-prefix rules, the only authority for shell invocations. */
+    shellCommands: Array<{
+        argvPrefix: [string, ...string[]];
+    }>;
+}
+
+/**
+ * Deterministic escape-technique corpus for the tool-policy gate (issue #2275
+ * §5). No LLM, no VM: every case is a `bash` command run through the real shell
+ * analyzer and the real gate, with the decision asserted.
+ *
+ * The corpus has two jobs:
+ *
+ * 1. **Regression fence.** A change that widens the gate turns a `block` case
+ *    into a failing test rather than a quiet policy hole.
+ * 2. **Honest documentation of grant semantics.** Some cases are allowed *by
+ *    design* because the operator asked for a broad grant. Those carry
+ *    `documentsGrantBreadth: true` so a reader can tell "this is what you bought"
+ *    from "this is contained".
+ *
+ * Adding a case: pick the fixture whose shape you are testing, run the command
+ * through the gate, and record the decision you observe **only if it is the
+ * decision you want**. A case whose observed decision is wrong does not belong
+ * here with its observed value — see the note on unfixed gaps at the bottom.
+ */
+/** The policy shapes a case can be evaluated against. */
+export declare type EscapePolicyShape = 
+/** Structured tools only, no shell grants at all. */
+'no-shell'
+/** Tool grants that happen to share a name with a shell program. */
+| 'tool-grant-only'
+/** A multi-token argv-prefix rule: `ls -la`. */
+| 'narrow-shell'
+/** A three-token argv-prefix rule on a subcommand: `gh pr view`. */
+| 'multi-token-shell'
+/** One-token rules on programs whose flags can name another command. */
+| 'one-token-escape-flags'
+/** A one-token rule: `git`, i.e. "any git invocation". */
+| 'one-token-shell'
+/** A one-token rule on a GTFOBins-escapable program: `find`. */
+| 'one-token-escapable';
+
+export declare const TOOL_POLICY_ESCAPE_CASES: ToolPolicyEscapeCase[];
+
+/** The smaller subset the live-policy E2E replays against real runtime policies. */
+export declare const TOOL_POLICY_ESCAPE_E2E_CASES: ToolPolicyEscapeCase[];
+
+/**
+ * The gate's verdict:
+ * - `{ allow: true }` — let the tool run.
+ * - `{ allow: false, reason }` — block it (enforce mode).
+ * - `{ audit, ... }` — would-block, but proceed and record it (watch mode).
+ */
+declare type ToolPolicyDecisionReason = 'policy_off' | 'executor_protocol_tool' | 'policy_allowed' | 'shell_command_prefix_allowed' | 'shell_command_unresolvable' | 'arbitrary_code_interpreter' | 'shell_output_redirection_not_permitted' | 'unsafe_environment_assignment' | 'tool_not_permitted';
+
+export declare interface ToolPolicyEscapeCase {
+    name: string;
+    policyShape: EscapePolicyShape;
+    command: string;
+    expectedAllow: boolean;
+    reasonCode: ToolPolicyDecisionReason;
+    /** Executable names the decision must report, when it reports any. */
+    missing?: string[];
+    /** Short technique family, for grouping failures in test output. */
+    technique: string;
+    /**
+     * Set when the case is allowed because the operator granted it broadly, not
+     * because the gate contained anything. These are the cost of a broad rule,
+     * stated out loud.
+     */
+    documentsGrantBreadth?: true;
+    /** Included in the smaller live-policy E2E subset. */
+    e2e?: true;
+    source: string;
+}
+
+export { }