@bookedsolid/rea 0.2.1 → 0.4.0

package/dist/gateway/middleware/injection.d.ts

@@ -1,11 +1,43 @@
+import { z } from 'zod';
 import type { Middleware } from './chain.js';
+import { Tier } from '../../policy/types.js';
 import { type SafeRegex } from '../redact-safe/match-timeout.js';
 /**
  * Known prompt injection phrases (lowercase for case-insensitive matching).
  * These patterns are commonly used to override system instructions in tool
  * descriptions or resource content returned by downstream MCP servers.
+ *
+ * SECURITY (G9 follow-up): inputs are NFKC-normalized, whitespace-collapsed,
+ * and zero-width-stripped before matching (see `normalizeForMatch`). That
+ * means the phrases below can safely be written with plain ASCII spaces —
+ * the normalizer will fold NBSP, en-space, em-space, zero-width joiners,
+ * etc. into the same form so crafted Unicode variants cannot bypass.
+ *
+ * The pattern library is intentionally terse. Extending it is follow-up
+ * work (G9.1): pattern-set extensibility via policy is out of scope for
+ * this patch. Phrases added here must be short, lowercase, and tolerate
+ * the normalization pipeline (no Unicode, no non-ASCII punctuation).
  */
 export declare const INJECTION_PHRASES: readonly string[];
+/**
+ * G9 follow-up — normalize an input string to a canonical form for literal
+ * phrase matching.
+ *
+ *   1. NFKC Unicode normalization — folds compatibility forms (fullwidth
+ *      letters, mathematical alphanumerics) into ASCII equivalents.
+ *   2. Strip all Default_Ignorable_Code_Point characters — invisible codepoints
+ *      that have no rendering and are used only to visually split or obscure
+ *      injection keywords (soft hyphen, zero-width joiners/non-joiners/spaces,
+ *      BIDI isolation controls, variation selectors, BOM, etc.).
+ *   3. Collapse any run of Unicode whitespace (including NBSP, en/em space)
+ *      to a single ASCII space.
+ *   4. Lowercase — matches the case-insensitive contract of INJECTION_PHRASES.
+ *
+ * NEVER logs or exports the normalized text; it is used only for match-time
+ * comparison. The audit record still surfaces the PHRASE that matched, not
+ * the normalized input.
+ */
+export declare function normalizeForMatch(input: string): string;
 /**
  * Base64-token scanner regex. The only regex the injection middleware runs
  * against untrusted payloads; wrapped in `SafeRegex` at middleware creation
@@ -24,6 +56,11 @@ export declare const INJECTION_BASE64_SHAPE: RegExp;
  * one invocation append to an array under this key.
  */
 export declare const INJECTION_TIMEOUT_METADATA_KEY = "injection.regex_timeout";
+/**
+ * Audit metadata key for the classifier verdict. The value is an
+ * `InjectionClassifierMetadata` object.
+ */
+export declare const INJECTION_METADATA_KEY = "injection";
 export interface InjectionTimeoutEvent {
     event: 'injection.regex_timeout';
     pattern_source: 'default';
@@ -31,10 +68,103 @@ export interface InjectionTimeoutEvent {
     input_bytes: number;
     timeout_ms: number;
 }
+/**
+ * G9 — classifier verdict written under `ctx.metadata.injection`. The audit
+ * middleware exports `ctx.metadata` verbatim, so this object becomes the
+ * permanent record of why a call was allowed, warned, or denied.
+ *
+ * `verdict` —
+ *   `clean`: no match, no metadata is written (this type exists only to
+ *     describe the internal return of `classifyInjection`).
+ *   `suspicious`: exactly one literal match at write/destructive tier, no
+ *     base64 escalation. Warn-only by default; deny when
+ *     `policy.injection.suspicious_blocks_writes === true`.
+ *   `likely_injection`: always deny. Triggered by any of:
+ *     - ≥2 distinct literal pattern matches
+ *     - any match found after base64 decoding
+ *     - any match at read tier (read-tier is permissive by design — a hit
+ *       there is anomalous)
+ *     - an unknown/missing tier (fail-closed)
+ *   `error` (G9 follow-up): scanner failure — at least one regex call
+ *     exceeded its worker-bounded timeout. Treated as inconclusive; the
+ *     call is NOT denied on this signal alone, but the metadata record
+ *     carries a stable `verdict` field so downstream audit consumers do
+ *     not receive a timeout event without a verdict shape.
+ *
+ * `matched_patterns` — the distinct phrase strings from `INJECTION_PHRASES`
+ * that matched. Sorted for audit-log determinism. NEVER includes the input
+ * text itself (no payload leakage). On `verdict: 'error'` this array may be
+ * empty (the scan was abandoned).
+ *
+ * `base64_decoded` — true iff at least one match was found in content that
+ * was base64-decoded before matching. On `verdict: 'error'` this field
+ * reports whether any base64-decoded match was observed BEFORE the timeout.
+ */
+export interface InjectionClassifierMetadata {
+    verdict: 'suspicious' | 'likely_injection' | 'error';
+    matched_patterns: string[];
+    base64_decoded: boolean;
+}
+/**
+ * G9 follow-up — zod schema for the `ctx.metadata.injection` record the
+ * middleware emits. Every emitted record has a `verdict` field; the schema
+ * exists so internal test code (and a follow-up public surface, once we
+ * decide how to expose audit-record types) can catch shape regressions —
+ * notably the pre-fix behavior where a regex-timeout emitted timing
+ * metadata under a different key without ever writing a verdict.
+ *
+ * INTERNAL today. Not reachable via the published package `exports` map
+ * (only `.`, `./policy`, `./middleware`, and `./audit` are public). If
+ * downstream consumers (e.g. Helix) need to validate audit records they
+ * read off `.rea/audit.jsonl`, we will promote this to a public entrypoint
+ * in a follow-up (filed as G9.2). Do not rely on this symbol from outside
+ * the rea repo yet.
+ */
+export declare const InjectionMetadataSchema: z.ZodObject<{
+    verdict: z.ZodEnum<["suspicious", "likely_injection", "error"]>;
+    matched_patterns: z.ZodArray<z.ZodString, "many">;
+    base64_decoded: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    verdict: "error" | "suspicious" | "likely_injection";
+    matched_patterns: string[];
+    base64_decoded: boolean;
+}, {
+    verdict: "error" | "suspicious" | "likely_injection";
+    matched_patterns: string[];
+    base64_decoded: boolean;
+}>;
 interface CompiledInjectionPatterns {
     base64Token: SafeRegex;
     base64Shape: SafeRegex;
 }
+/**
+ * G9 — scan result split by match origin so the classifier can distinguish
+ * a single-literal hit (potentially `suspicious`) from a base64-decoded hit
+ * (always `likely_injection`). The Sets deduplicate by phrase; same phrase
+ * matched twice counts as one distinct pattern.
+ */
+export interface InjectionScanResult {
+    literalMatches: Set<string>;
+    base64DecodedMatches: Set<string>;
+}
+/**
+ * G9 — pure helper that walks an arbitrary `unknown` value and returns every
+ * successfully decoded base64-looking string. Decoding is attempted only for
+ * strings that:
+ *   - are ≥ `MIN_BASE64_PROBE_LENGTH` (24) chars
+ *   - have length divisible by 4 (base64 framing)
+ *   - match the `INJECTION_BASE64_SHAPE` (`^[A-Za-z0-9+/]+=*$`)
+ *   - decode to a UTF-8 string that is ≥95% printable and contains no null bytes
+ *
+ * NOTE: This function is NOT called from the middleware body. The inline base64
+ * probe in `scanStringForInjection` (via `INJECTION_BASE64_PATTERN`) already
+ * covers embedded base64 token detection. Calling `decodeBase64Strings` as a
+ * second full-tree pass would duplicate that work and add an avoidable DoS
+ * amplification surface (full tree traversal + decoded-string allocation for
+ * every base64-shaped leaf). This function is exported for testing and external
+ * use only.
+ */
+export declare function decodeBase64Strings(input: unknown): string[];
 export interface ScanForInjectionOptions {
     onTimeout?: (patternId: string, input: string) => void;
 }
@@ -44,36 +174,111 @@ export interface ScanForInjectionOptions {
  */
 export declare function compileInjectionPatterns(timeoutMs: number, onTimeout?: (patternId: string, input: string) => void): CompiledInjectionPatterns;
 /**
- * Scan a string for known prompt injection phrases.
- * Also decodes base64 tokens and checks the decoded content.
- * Returns an array of matched phrase descriptions, empty if clean.
+ * Scan a single string and record hits into the provided `InjectionScanResult`
+ * buckets. Exported for test surface and for callers who want to scan a known
+ * string without walking a tree.
  *
- * The `safe` parameter carries precompiled SafeRegex wrappers; callers build
- * it once via `compileInjectionPatterns`.
+ * - Literal matches (case-insensitive substring) go into `literalMatches`.
+ * - Base64-decoded matches (tokens extracted via `INJECTION_BASE64_PATTERN`,
+ *   decoded, then re-scanned for literals) go into `base64DecodedMatches`.
+ *
+ * Set semantics dedupe by phrase: the same phrase matched five times in one
+ * string counts as one distinct pattern, which is intentional for the
+ * classifier's "≥2 distinct patterns → likely" rule.
+ */
+export declare function scanStringForInjection(input: string, result: InjectionScanResult, safe: CompiledInjectionPatterns): void;
+/**
+ * Back-compat wrapper: legacy callers (and the old audit-metadata consumer)
+ * received a flat `string[]` of "literal: …" / "base64-encoded: …" descriptions.
+ * Kept as an exported helper so `scripts/lint-safe-regex.mjs` and any external
+ * consumer that imported it continue to work. New code should call
+ * `scanStringForInjection` directly.
  */
 export declare function scanForInjection(input: string, safe: CompiledInjectionPatterns): string[];
+/**
+ * Recursively scan an unknown value (string, array, or plain object) and
+ * accumulate matches into the supplied `InjectionScanResult` buckets.
+ */
+export declare function scanValueForInjection(value: unknown, result: InjectionScanResult, safe: CompiledInjectionPatterns): void;
+/**
+ * G9 — classify a scan result into `clean` / `suspicious` / `likely_injection`
+ * using the tier and the distinctness of literal matches.
+ *
+ * Decision table (first match wins):
+ *
+ *   1. No literal AND no base64-decoded matches
+ *      → { verdict: 'clean' }
+ *   2. Any base64-decoded match (regardless of count/tier)
+ *      → { verdict: 'likely_injection', base64_decoded: true }
+ *   3. ≥2 distinct literal matches
+ *      → { verdict: 'likely_injection' }
+ *   4. Tier is Read (or undefined — fail closed)
+ *      → { verdict: 'likely_injection' }
+ *   5. Exactly 1 literal match at Write/Destructive
+ *      → { verdict: 'suspicious' }
+ *
+ * Extension point: a future "deny-tag" per-pattern metadata layer can force
+ * any match to `likely_injection`. Not wired in this PR — TODO below.
+ */
+export type InjectionClassification = {
+    verdict: 'clean';
+} | InjectionClassifierMetadata;
+export declare function classifyInjection(scan: InjectionScanResult, tier: Tier | undefined): InjectionClassification;
 export type InjectionAction = 'block' | 'warn';
 export interface InjectionMiddlewareOptions {
     /** Timeout budget for each regex call. Default 100ms. */
     matchTimeoutMs?: number;
+    /**
+     * G9 — governs whether `suspicious` classifications at write/destructive
+     * tier deny. `likely_injection` is ALWAYS deny regardless of this flag.
+     *
+     * Interpreted by `createInjectionMiddleware` with the `action` parameter:
+     *
+     *   - `action: 'warn'` (legacy `injection_detection: warn`): this flag is
+     *     IGNORED. Suspicious stays warn-only, 0.2.x parity. Operators who
+     *     pinned warn mode never get a suspicious-deny, even if a profile
+     *     layer flipped the flag to `true`.
+     *   - `action: 'block'` + flag `true`: suspicious denies.
+     *   - `action: 'block'` + flag `false`: suspicious warns only.
+     *   - `action: 'block'` + flag `undefined` (UNSET): defaults to `false`
+     *     to preserve 0.3.x behavior. Consumers who omit the `injection:`
+     *     policy block will NOT be silently tightened on upgrade. To enable
+     *     the stricter posture, set `injection.suspicious_blocks_writes: true`
+     *     explicitly in policy (or use the bst-internal profile, which
+     *     already sets it).
+     *
+     * Wired from `policy.injection.suspicious_blocks_writes` by the gateway.
+     * When the policy omits the `injection:` block, the field is `undefined`
+     * (the loader schema no longer applies a default) so this middleware can
+     * distinguish "not configured" from "explicitly false".
+     */
+    suspiciousBlocksWrites?: boolean;
 }
 /**
- * PostToolUse middleware: scans tool results for prompt injection patterns.
+ * PostToolUse middleware: classifies tool results for prompt injection.
+ *
+ * G9 tiered classifier:
+ *   - `clean` → allow, no log
+ *   - `suspicious` → warn (stderr + audit metadata `injection.suspicious`).
+ *     Denies only when `suspiciousBlocksWrites: true`.
+ *   - `likely_injection` → always deny, always log.
  *
  * Operates on tool output (ctx.result) returned from downstream MCP servers.
- * On detection:
- *   - Always logs to audit metadata and emits a warning to stderr.
- *   - If action is 'block' (default), sets ctx.status to Denied and blocks the result.
- *   - If action is 'warn', allows the result through with a warning only.
  *
- * SECURITY: Checking PostToolUse (after downstream execution, before the result
- * reaches the LLM) is the correct place to catch injection in tool descriptions
- * and resource content coming from potentially untrusted downstream servers.
+ * SECURITY: Checking PostToolUse (after downstream execution, before the
+ * result reaches the LLM) is the correct place to catch injection in tool
+ * descriptions and resource content coming from potentially untrusted
+ * downstream servers.
  *
  * SECURITY (G3): The only regexes this middleware runs are wrapped in
  * `SafeRegex` with a 100ms default per-call timeout. On timeout the scanner
  * records an audit event and proceeds — blocking is governed by the literal
  * substring checks (which have no ReDoS surface).
+ *
+ * The legacy `action` parameter (`'block' | 'warn'`) selects the fallback
+ * behavior for `suspicious` verdicts when the G9 flag is unset — preserving
+ * 0.2.x `injection_detection: 'warn'` semantics for operators who pinned it.
+ * `likely_injection` ignores this parameter.
  */
 export declare function createInjectionMiddleware(action?: InjectionAction, opts?: InjectionMiddlewareOptions): Middleware;
 export {};