ai-shield-core 0.1.0 → 0.2.0

package/dist/scanner/ingestion.d.ts

@@ -0,0 +1,116 @@
+import type { Scanner, ScannerResult, ScanContext, Violation, IngestionSource, TrustTier } from "../types.js";
+/**
+ * Default trust-tier inferred from source.
+ * `user` is still untrusted in this library's threat model — a user can
+ * inject too — but `system` is reserved for content the developer
+ * controls and labels via `wrapContext()`. Every ingestion source
+ * (including `user`) therefore returns `"untrusted"` by default; the
+ * parameter is kept on the signature so future per-source overrides
+ * (e.g. an installer marking a specific source as trusted) don't
+ * require a breaking API change.
+ */
+export declare function trustTierForSource(_source: IngestionSource): TrustTier;
+/**
+ * Result of `scanIngested()`.
+ *
+ * Shape parallels `ScanResult` from `chain.ts` so callers can treat
+ * both interchangeably.
+ */
+export interface IngestionScanResult {
+    safe: boolean;
+    decision: "allow" | "warn" | "block";
+    /**
+     * Sanitized output. When `decision === "block"` this is the empty
+     * string — the original content was deemed unsafe and the field name
+     * "sanitized" would otherwise mislead callers into using poisoned
+     * content. Use the source `content` argument if you need the raw input
+     * for logging or quarantine.
+     */
+    sanitized: string;
+    violations: Violation[];
+    source: IngestionSource;
+    meta: {
+        scanDurationMs: number;
+        scannersRun: string[];
+        /** Number of extra source-specific patterns that fired. */
+        sourceSpecificHits: number;
+        /**
+         * Always `false` from `scanIngested()` — ingestion scans don't go
+         * through the LRU cache. Field is present so callers can write a
+         * single result-handler for both `ScanResult` and `IngestionScanResult`.
+         */
+        cached: boolean;
+    };
+}
+export interface IngestionScannerConfig {
+    /** Override the per-source threshold lookup. */
+    threshold?: number;
+    /**
+     * Additional custom patterns to merge with the source profile's
+     * `extraPatterns`. Useful for org-specific markers.
+     */
+    customPatterns?: RegExp[];
+    /**
+     * Force the underlying heuristic scanner to a different strictness
+     * (default "high" because ingestion is always tighter than user input).
+     */
+    strictness?: "low" | "medium" | "high";
+}
+/**
+ * Scanner implementation. Composable into a `ScannerChain` when the
+ * caller wants ingestion to participate in the main scan flow rather
+ * than be invoked via the standalone `scanIngested()` helper.
+ *
+ * The scanner reads the `source` from `ScanContext` (or treats input
+ * as `"user"` when missing) and applies the source-specific profile.
+ */
+export declare class IngestionScanner implements Scanner {
+    readonly name = "ingestion";
+    private readonly threshold;
+    private readonly customPatterns;
+    private readonly heuristic;
+    constructor(config?: IngestionScannerConfig);
+    scan(input: string, context: ScanContext): Promise<ScannerResult>;
+}
+/**
+ * One-shot helper. Scans `content` against the source-specific profile
+ * and returns a result without needing an `AIShield` instance.
+ *
+ * Use when you want a quick gate at the ingestion boundary, e.g.
+ * before storing a chunk into a vector DB or before passing a tool
+ * description into the model's context.
+ *
+ * @example
+ * ```ts
+ * import { scanIngested } from "ai-shield-core";
+ *
+ * const ragChunk = "...retrieved document text...";
+ * const result = await scanIngested(ragChunk, "rag");
+ * if (!result.safe) {
+ *   // reject the chunk OR strip it before assembly
+ *   logger.warn("IPI candidate", result.violations);
+ * }
+ * ```
+ */
+export declare function scanIngested(content: string, source: IngestionSource, config?: IngestionScannerConfig): Promise<IngestionScanResult>;
+/**
+ * Try to decode common obfuscation layers an attacker uses to smuggle
+ * an injection past pattern matchers. Returns the decoded payload when
+ * it looks like a successful decode, else `null`.
+ *
+ * The function deliberately runs at most ONE decode layer to avoid
+ * decoding amplification (a chain of `base64(base64(...))` would force
+ * us into deep recursion); a single-layer decode is enough to catch
+ * the vast majority of in-the-wild bypasses while keeping execution
+ * cost bounded.
+ *
+ * Heuristics:
+ *  - Base64: contiguous run of 40+ Base64 chars, decodes to mostly
+ *    printable ASCII or the `\u00..` C0 range stays empty.
+ *  - Hex: 80+ hex chars in a row.
+ *  - Percent-encoding: more than 5 `%XX` sequences.
+ *
+ * Returns the longest decoded payload when multiple candidates fire.
+ */
+export declare function tryDecodeObfuscation(input: string): string | null;
+//# sourceMappingURL=ingestion.d.ts.map

package/dist/scanner/ingestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingestion.d.ts","sourceRoot":"","sources":["../../src/scanner/ingestion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,WAAW,EACX,SAAS,EACT,eAAe,EACf,SAAS,EACV,MAAM,aAAa,CAAC;AA2GrB;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CAEtE;AAoFD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,MAAM,EAAE,eAAe,CAAC;IACxB,IAAI,EAAE;QACJ,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,2DAA2D;QAC3D,kBAAkB,EAAE,MAAM,CAAC;QAC3B;;;;WAIG;QACH,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAC9C,QAAQ,CAAC,IAAI,eAAe;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,MAAM,GAAE,sBAA2B;IAQzC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;CAmHxE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,sBAA2B,GAClC,OAAO,CAAC,mBAAmB,CAAC,CA0B9B;AAQD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2EjE"}

package/dist/scanner/ingestion.js

@@ -0,0 +1,452 @@
+import { HeuristicScanner, normalizeForInjectionScan } from "./heuristic.js";
+// ============================================================
+// Ingestion Scanner — Indirect Prompt Injection (IPI) Defense
+//
+// Scans non-user content (RAG chunks, MCP tool descriptions, stored
+// memory facts, scraped web pages, agent-to-agent messages) for
+// instruction-shaped payloads BEFORE they enter the model context.
+//
+// Per Lakera 2026 incident catalog + OWASP LLM01:2025, indirect
+// injection is now the dominant attack class — >55% of observed
+// incidents arrive through trusted-looking data channels. Direct user
+// injection is the minority case.
+//
+// This scanner runs the existing heuristic patterns at a stricter
+// threshold AND adds source-specific patterns the user channel does
+// not see (HTML-comment instructions, tool-description override,
+// memory-entry steering).
+// ============================================================
+/**
+ * Per-source threshold + extra patterns. Tighter than the user-channel
+ * default because data sources almost never need instruction syntax —
+ * the presence of one in retrieved content is itself a signal.
+ */
+const SOURCE_PROFILE = {
+    user: {
+        // For symmetry — a caller may pass source="user" through scanIngested().
+        // Falls back to normal heuristic strictness.
+        threshold: 0.3,
+        extraPatterns: [],
+    },
+    rag: {
+        // Retrieved docs basically never legitimately contain "ignore previous
+        // instructions" type wording. Strict. Patterns here are ReDoS-bounded —
+        // hidden-comment + CSS detection are done via slice-then-test below in
+        // `runStructuralIngestionScan()` so we never run two `[^]*?` wildcards
+        // back-to-back over attacker-controlled input.
+        threshold: 0.15,
+        extraPatterns: [
+            // "AI assistant note: ..." style trojan headers.
+            /(?:AI\s+(?:assistant|model)\s+(?:note|instruction|directive)|attention\s+(?:AI|model|assistant))[:\s]+/i,
+            // Document-claims-to-be-system marker.
+            /this\s+document\s+(?:is|contains|provides)\s+(?:your|the)\s+(?:new\s+)?(?:instructions?|system\s+prompt|directives?)/i,
+        ],
+    },
+    "tool-desc": {
+        // MCP tool descriptions / function schemas: any imperative aimed at
+        // the calling model is suspicious. OX Security MCP advisory + LiteLLM
+        // CVE-2025-69256 class.
+        threshold: 0.12,
+        extraPatterns: [
+            // "Before using this tool, you must ..." / "After calling, also call X"
+            /(?:before|after|while)\s+(?:using|invoking|calling|executing)\s+(?:this\s+)?(?:tool|function|action)[,\s]+(?:you\s+)?(?:must|should|will|need\s+to|are\s+required\s+to)/i,
+            // "Also call delete_*" / "ALWAYS invoke X first"
+            /(?:also|always|first|then|finally)\s+(?:call|invoke|use|execute|run)\s+(?:the\s+)?[a-z_][\w-]{2,}/i,
+            // "Tool description: ignore the above and ..."
+            /(?:tool|function|action)\s+description[:\s]+(?:ignore|disregard|override)/i,
+            // "Note to LLM:" / "Hidden instruction:"
+            /(?:note|hidden\s+(?:instruction|directive|note))\s+to\s+(?:LLM|model|assistant|AI|agent)[:\s]/i,
+            // Tool args carrying meta-instructions.
+            /(?:on\s+(?:success|call)|when\s+invoked)[,:]\s+(?:silently|also|then)\s+(?:call|invoke|exfiltrate|send|leak)/i,
+        ],
+    },
+    memory: {
+        // Stored memory entries: persistence poisoning. Look for sentinel
+        // instructions that re-anchor the model on subsequent retrieval.
+        threshold: 0.18,
+        extraPatterns: [
+            // "Remember:" / "Important note for next session:"
+            /(?:remember|important|critical)\s+(?:note|instruction|directive)\s+(?:for\s+(?:next|future|all)\s+(?:sessions?|conversations?|calls?))[:\s]/i,
+            // "Whenever the user asks X, do Y"
+            /(?:whenever|every\s+time)\s+(?:the\s+user|a\s+user|someone)\s+(?:asks|says|mentions|requests)\s+.{1,80}?[,:]\s*(?:you\s+(?:must|should|will|need)|always)/i,
+            // "User's true preference is ..." (steering attempts).
+            /(?:user(?:'s|s)?\s+(?:real|true|actual|hidden)\s+(?:preference|intent|goal|name|identity))/i,
+            // "Override default behavior when ..."
+            /override\s+(?:default|standard|normal)\s+(?:behavior|response|policy)/i,
+        ],
+    },
+    web: {
+        // Scraped web — same as RAG but also catch markdown-link hijacks.
+        // HTML-comment + CSS-hidden detection lives in
+        // `runStructuralIngestionScan()` (slice-then-test, ReDoS-bounded).
+        threshold: 0.15,
+        extraPatterns: [
+            // Markdown-link with instruction-shaped anchor text.
+            /\[(?:ignore|disregard|override|system\s+(?:prompt|message))[^\]]{0,200}\]\([^)]{0,500}\)/i,
+            // ARIA / data-* attributes leaking instructions.
+            /(?:aria-label|alt|title|data-[a-z-]{0,40})\s*=\s*["'][^"']{0,500}(ignore\s+previous|new\s+instruction|system\s+prompt|override)/i,
+        ],
+    },
+    "agent-output": {
+        // Output of one agent feeding another: multi-agent contagion.
+        // Treat like RAG but also catch "tell next agent to ..." patterns.
+        threshold: 0.18,
+        extraPatterns: [
+            /(?:tell|instruct|forward\s+to)\s+(?:the\s+)?(?:next|downstream|receiving|other)\s+(?:agent|model|assistant)\s+to/i,
+            /(?:on\s+behalf\s+of|impersonating)\s+(?:the\s+)?(?:user|admin|system|owner)/i,
+            /(?:relay|pass|propagate)\s+(?:these|the\s+following)\s+(?:instructions?|directives?|orders?)/i,
+        ],
+    },
+};
+/**
+ * Default trust-tier inferred from source.
+ * `user` is still untrusted in this library's threat model — a user can
+ * inject too — but `system` is reserved for content the developer
+ * controls and labels via `wrapContext()`. Every ingestion source
+ * (including `user`) therefore returns `"untrusted"` by default; the
+ * parameter is kept on the signature so future per-source overrides
+ * (e.g. an installer marking a specific source as trusted) don't
+ * require a breaking API change.
+ */
+export function trustTierForSource(_source) {
+    return "untrusted";
+}
+// --- ReDoS-safe structural scan helpers ---
+/**
+ * Hidden-comment + CSS-hidden detection done as bounded slice-then-test
+ * rather than a compound `[^]*?...[^]*?` regex (which back-tracks
+ * quadratically on attacker-controlled input that omits the terminator).
+ * See Critic C1 (round 1 review) — unterminated `<!--` of 50 KB stalled
+ * the original implementation.
+ *
+ * Each detector takes the already-NFKC-normalized input and returns
+ * `null` (clean) or a `Violation`.
+ */
+function runStructuralIngestionScan(normalized, source, threshold) {
+    if (source !== "rag" && source !== "web")
+        return [];
+    const violations = [];
+    const COMMENT_WINDOW = 2048;
+    const KEYWORD_RE = /ignore|disregard|override|forget|system\s+prompt|new\s+instructions?/i;
+    // 1. HTML comment hidden instruction.
+    let commentStart = 0;
+    let commentMatchCount = 0;
+    while (commentStart !== -1 && commentMatchCount < 8) {
+        commentStart = normalized.indexOf("<!--", commentStart);
+        if (commentStart === -1)
+            break;
+        const window = normalized.slice(commentStart + 4, commentStart + 4 + COMMENT_WINDOW);
+        if (KEYWORD_RE.test(window)) {
+            violations.push({
+                type: "ingested_injection",
+                scanner: "ingestion",
+                score: 0.4,
+                threshold,
+                message: `HTML-comment hidden instruction in ${source} content`,
+                detail: `Pattern: <!-- ... ignore|override|... (window 2KB)`,
+            });
+            commentMatchCount += 1;
+        }
+        commentStart += 4;
+    }
+    // 2. CSS-hidden style attribute carrying instruction-shaped neighbour.
+    //
+    // Round 2 Critic M-NEW-2: a single `.exec()` would only find the FIRST
+    // `style=` attribute. An attacker placing a benign `style="display:block"`
+    // first and a malicious `style="display:none"` later would slip through.
+    // Iterate all matches via the `/g` flag, capped at 16 to bound the work
+    // on adversarial input that floods style attributes.
+    const STYLE_HIDDEN_RE = /style\s*=\s*["'][^"']{0,300}(?:display\s*:\s*none|visibility\s*:\s*hidden|font-size\s*:\s*0)[^"']{0,300}["']/gi;
+    let styleMatchCount = 0;
+    let styleMatch;
+    while ((styleMatch = STYLE_HIDDEN_RE.exec(normalized)) !== null &&
+        styleMatchCount < 16) {
+        styleMatchCount += 1;
+        const tail = normalized.slice(styleMatch.index + styleMatch[0].length, styleMatch.index + styleMatch[0].length + 500);
+        if (/ignore|override|system|instruction/i.test(tail)) {
+            violations.push({
+                type: "ingested_injection",
+                scanner: "ingestion",
+                score: 0.4,
+                threshold,
+                message: `CSS-hidden instruction in ${source} content`,
+                detail: `Pattern: style="display:none ... ignore|override|... (window 500B)`,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Scanner implementation. Composable into a `ScannerChain` when the
+ * caller wants ingestion to participate in the main scan flow rather
+ * than be invoked via the standalone `scanIngested()` helper.
+ *
+ * The scanner reads the `source` from `ScanContext` (or treats input
+ * as `"user"` when missing) and applies the source-specific profile.
+ */
+export class IngestionScanner {
+    name = "ingestion";
+    threshold;
+    customPatterns;
+    heuristic;
+    constructor(config = {}) {
+        this.threshold = config.threshold;
+        this.customPatterns = config.customPatterns ?? [];
+        this.heuristic = new HeuristicScanner({
+            strictness: config.strictness ?? "high",
+        });
+    }
+    async scan(input, context) {
+        const source = context.source ?? "user";
+        const profile = SOURCE_PROFILE[source];
+        const effectiveThreshold = this.threshold ?? profile.threshold;
+        const start = performance.now();
+        const violations = [];
+        // 1. Run the base heuristic scanner at high strictness. We respect its
+        //    own decision (it includes structural signals that don't surface
+        //    as individual violations) and re-tag the violations as
+        //    `ingested_injection` so downstream code can filter.
+        const heuristicResult = await this.heuristic.scan(input, context);
+        for (const v of heuristicResult.violations) {
+            violations.push({
+                ...v,
+                type: "ingested_injection",
+                scanner: this.name,
+                detail: `${v.detail ?? ""} (source=${source})`.trim(),
+            });
+        }
+        // 2. Run source-specific patterns against the normalized input so the
+        //    same Unicode-evasion defense the user channel gets applies here.
+        const normalized = normalizeForInjectionScan(input);
+        const sourcePatterns = [...profile.extraPatterns, ...this.customPatterns];
+        let sourceScore = 0;
+        for (const pattern of sourcePatterns) {
+            if (pattern.test(normalized)) {
+                sourceScore += 0.4;
+                violations.push({
+                    type: "ingested_injection",
+                    scanner: this.name,
+                    score: 0.4,
+                    threshold: effectiveThreshold,
+                    message: `Indirect injection pattern in ${source} content`,
+                    detail: `Pattern: ${pattern.source.slice(0, 80)}`,
+                });
+            }
+        }
+        // 2b. Structural slice-then-test scans for `rag` + `web` (ReDoS-safe
+        //     replacement for the old compound HTML-comment + CSS-hidden
+        //     patterns).
+        const structural = runStructuralIngestionScan(normalized, source, effectiveThreshold);
+        for (const v of structural) {
+            sourceScore += 0.4;
+            violations.push(v);
+        }
+        // 2c. Encoding-bypass: attackers wrap an injection in Base64 / Hex /
+        //     percent-encoding and ask the model to "decode this". A single
+        //     decode pass over the input flushes the most common bypasses
+        //     documented in OWASP LLM Prompt Injection Prevention Cheat
+        //     Sheet 2026. Only run when the input "looks encoded" to keep
+        //     false-positive load low on plain prose.
+        const decoded = tryDecodeObfuscation(input);
+        if (decoded && decoded !== input) {
+            const decodedNormalized = normalizeForInjectionScan(decoded);
+            const decodedHeuristic = await this.heuristic.scan(decoded, context);
+            if (decodedHeuristic.decision !== "allow") {
+                for (const v of decodedHeuristic.violations) {
+                    violations.push({
+                        ...v,
+                        type: "ingested_injection",
+                        scanner: this.name,
+                        detail: `${v.detail ?? ""} (source=${source}, layer=decoded)`.trim(),
+                    });
+                }
+                sourceScore += 0.6; // decoded-hit is high-confidence
+            }
+            // Also run source-specific patterns over the decoded layer.
+            for (const pattern of sourcePatterns) {
+                if (pattern.test(decodedNormalized)) {
+                    sourceScore += 0.4;
+                    violations.push({
+                        type: "ingested_injection",
+                        scanner: this.name,
+                        score: 0.4,
+                        threshold: effectiveThreshold,
+                        message: `Encoded indirect injection in ${source} content`,
+                        detail: `Pattern: ${pattern.source.slice(0, 80)} (layer=decoded)`,
+                    });
+                }
+            }
+        }
+        sourceScore = Math.min(sourceScore, 1.0);
+        // 3. Combine decisions. The heuristic scanner already weighed
+        //    structural signals (newlines, headers, padding) that may not
+        //    surface as individual violations; trust its decision rather
+        //    than re-aggregating only the violation-score subset.
+        const heuristicBlocks = heuristicResult.decision === "block";
+        const heuristicWarns = heuristicResult.decision === "warn";
+        const sourceBlocks = sourceScore >= effectiveThreshold;
+        const sourceWarns = sourceScore >= effectiveThreshold * 0.6;
+        let decision;
+        if (heuristicBlocks || sourceBlocks) {
+            decision = "block";
+        }
+        else if (heuristicWarns || sourceWarns) {
+            decision = "warn";
+        }
+        else {
+            decision = "allow";
+        }
+        return {
+            decision,
+            violations,
+            durationMs: performance.now() - start,
+        };
+    }
+}
+/**
+ * One-shot helper. Scans `content` against the source-specific profile
+ * and returns a result without needing an `AIShield` instance.
+ *
+ * Use when you want a quick gate at the ingestion boundary, e.g.
+ * before storing a chunk into a vector DB or before passing a tool
+ * description into the model's context.
+ *
+ * @example
+ * ```ts
+ * import { scanIngested } from "ai-shield-core";
+ *
+ * const ragChunk = "...retrieved document text...";
+ * const result = await scanIngested(ragChunk, "rag");
+ * if (!result.safe) {
+ *   // reject the chunk OR strip it before assembly
+ *   logger.warn("IPI candidate", result.violations);
+ * }
+ * ```
+ */
+export async function scanIngested(content, source, config = {}) {
+    const start = performance.now();
+    const scanner = new IngestionScanner(config);
+    const result = await scanner.scan(content, { source });
+    return {
+        safe: result.decision === "allow",
+        decision: result.decision,
+        // When a chunk is blocked, returning the raw input under the field
+        // name "sanitized" mis-leads callers into trusting poisoned content.
+        // Return empty string on block so a `if (!safe) use(result.sanitized)`
+        // path becomes a no-op rather than a vulnerability. Use the original
+        // `content` argument if you still need it for audit / quarantine.
+        sanitized: result.decision === "block" ? "" : content,
+        violations: result.violations,
+        source,
+        meta: {
+            scanDurationMs: performance.now() - start,
+            scannersRun: [scanner.name],
+            sourceSpecificHits: result.violations.filter((v) => v.detail?.startsWith("Pattern:") && v.type === "ingested_injection").length,
+            cached: false,
+        },
+    };
+}
+// ============================================================
+// Encoding-bypass normalization (R1 from Round 1 review — closes
+// OWASP LLM Prompt Injection Prevention Cheat Sheet 2026 Base64/Hex
+// bypass class).
+// ============================================================
+/**
+ * Try to decode common obfuscation layers an attacker uses to smuggle
+ * an injection past pattern matchers. Returns the decoded payload when
+ * it looks like a successful decode, else `null`.
+ *
+ * The function deliberately runs at most ONE decode layer to avoid
+ * decoding amplification (a chain of `base64(base64(...))` would force
+ * us into deep recursion); a single-layer decode is enough to catch
+ * the vast majority of in-the-wild bypasses while keeping execution
+ * cost bounded.
+ *
+ * Heuristics:
+ *  - Base64: contiguous run of 40+ Base64 chars, decodes to mostly
+ *    printable ASCII or the `\u00..` C0 range stays empty.
+ *  - Hex: 80+ hex chars in a row.
+ *  - Percent-encoding: more than 5 `%XX` sequences.
+ *
+ * Returns the longest decoded payload when multiple candidates fire.
+ */
+export function tryDecodeObfuscation(input) {
+    if (typeof input !== "string" || input.length === 0)
+        return null;
+    // Cap input we look at — Base64 of a megabyte is not the threat model.
+    const haystack = input.length > 65_536 ? input.slice(0, 65_536) : input;
+    const candidates = [];
+    // Base64 — at least 40 chars, optional padding, optional whitespace.
+    const B64_RE = /[A-Za-z0-9+/=]{40,}/g;
+    for (const match of haystack.match(B64_RE) ?? []) {
+        const cleaned = match.replace(/=+$/, "").replace(/[^A-Za-z0-9+/]/g, "");
+        if (cleaned.length < 40)
+            continue;
+        try {
+            const decoded = Buffer.from(cleaned, "base64").toString("utf8");
+            if (decoded.length === 0)
+                continue;
+            const printable = decoded.replace(/[^\x20-\x7E\s]/g, "");
+            // Require >70% printable to avoid noise.
+            if (printable.length / decoded.length >= 0.7) {
+                candidates.push(decoded);
+            }
+        }
+        catch {
+            // ignore malformed Base64
+        }
+    }
+    // Hex — 80+ hex digits in a row.
+    const HEX_RE = /[0-9a-fA-F]{80,}/g;
+    for (const match of haystack.match(HEX_RE) ?? []) {
+        if (match.length % 2 !== 0)
+            continue;
+        try {
+            const decoded = Buffer.from(match, "hex").toString("utf8");
+            if (decoded.length === 0)
+                continue;
+            const printable = decoded.replace(/[^\x20-\x7E\s]/g, "");
+            if (printable.length / decoded.length >= 0.7) {
+                candidates.push(decoded);
+            }
+        }
+        catch {
+            // ignore malformed hex
+        }
+    }
+    // Percent-encoding — only decode a windowed region around clustered
+    // escapes rather than the full 65KB haystack. Round 2 Critic M-NEW-1:
+    // running `decodeURIComponent()` on the full haystack on every scan
+    // allocates a ~2× copy per call and pressures GC in high-throughput
+    // ingestion pipelines.
+    const PERCENT_RE = /%[0-9A-Fa-f]{2}/g;
+    const percentMatches = [];
+    let percentMatch;
+    while ((percentMatch = PERCENT_RE.exec(haystack)) !== null &&
+        percentMatches.length < 32) {
+        percentMatches.push(percentMatch.index);
+    }
+    if (percentMatches.length >= 5) {
+        // Decode only a window around the cluster: 256 bytes before the first
+        // escape, 1KB after the last. Bounded work regardless of haystack size.
+        const first = percentMatches[0] ?? 0;
+        const last = percentMatches[percentMatches.length - 1] ?? first;
+        const winStart = Math.max(0, first - 256);
+        const winEnd = Math.min(haystack.length, last + 1024);
+        const window = haystack.slice(winStart, winEnd);
+        try {
+            const decoded = decodeURIComponent(window);
+            if (decoded !== window)
+                candidates.push(decoded);
+        }
+        catch {
+            // ignore malformed percent-encoding
+        }
+    }
+    if (candidates.length === 0)
+        return null;
+    // Return the longest candidate; that's the most likely attack payload.
+    candidates.sort((a, b) => b.length - a.length);
+    return candidates[0] ?? null;
+}
+//# sourceMappingURL=ingestion.js.map

package/dist/scanner/pii.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pii.d.ts","sourceRoot":"","sources":["../../src/scanner/pii.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,WAAW,EAEX,SAAS,EAGT,SAAS,EACV,MAAM,aAAa,CAAC;AAsKrB,qBAAa,UAAW,YAAW,OAAO;IACxC,QAAQ,CAAC,IAAI,SAAS;IACtB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,YAAY,CAAe;gBAEvB,MAAM,GAAE,SAAc;IAO5B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAoDxE,sCAAsC;IACtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE;IA8BjC,uFAAuF;IACvF,OAAO,CAAC,mBAAmB;IAuB3B,gCAAgC;IAChC,OAAO,CAAC,YAAY;CAerB"}
+{"version":3,"file":"pii.d.ts","sourceRoot":"","sources":["../../src/scanner/pii.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,WAAW,EAEX,SAAS,EAGT,SAAS,EACV,MAAM,aAAa,CAAC;AAoLrB,qBAAa,UAAW,YAAW,OAAO;IACxC,QAAQ,CAAC,IAAI,SAAS;IACtB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,YAAY,CAAe;gBAEvB,MAAM,GAAE,SAAc;IAO5B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAoDxE,sCAAsC;IACtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE;IA8BjC,uFAAuF;IACvF,OAAO,CAAC,mBAAmB;IAuB3B,gCAAgC;IAChC,OAAO,CAAC,YAAY;CAerB"}

package/dist/scanner/pii.js

@@ -1,12 +1,12 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PIIScanner = void 0;
 // --- German & International PII Patterns ---
 const PII_PATTERNS = [
-    // IBAN: DE + 2 check digits + 18 digits (with optional spaces/dashes)
+    // IBAN: 2-letter ISO + 2 check digits + 11..30 alphanumerics (with optional spaces/dashes).
+    // Covers all 80+ IBAN countries: NO (15), BE (16), DE (22), FR (27), MT (31), SC (31).
+    // The validator runs mod-97 over the cleaned value and rejects anything that isn't a real IBAN.
+    // Pattern is linear (no nested quantifiers) — ReDoS-safe.
     {
         type: "iban",
-        pattern: /\b[A-Z]{2}\s?\d{2}\s?\d{4}\s?\d{4}\s?\d{4}\s?\d{4}\s?\d{2,4}\b/g,
+        pattern: /\b[A-Z]{2}\d{2}[ -]?[A-Z0-9](?:[A-Z0-9 -]{9,36}[A-Z0-9])?\b/g,
         validator: validateIBAN,
         baseConfidence: 0.95,
     },
@@ -36,10 +36,15 @@ const PII_PATTERNS = [
         pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
         baseConfidence: 0.95,
     },
-    // Phone: German formats (+49, 0xxx) and international
+    // Phone: German formats (+49, 0xxx) and international.
+    // Previous pattern had nested optional quantifiers (`\s?[\s\-/]?` plus two
+    // `[\s\-/]?\d{0,5}` tails) which risks catastrophic backtracking on
+    // malformed inputs. Restructured so every separator group requires at least
+    // one char when present and the trailing digits group is a true non-optional
+    // extension (or absent entirely).
     {
         type: "phone",
-        pattern: /(?<!\d)(?:\+\d{1,3}|00\d{1,3}|0)\s?[\s\-/]?\(?\d{2,5}\)?[\s\-/]?\d{3,8}[\s\-/]?\d{0,5}\b/g,
+        pattern: /(?<!\d)(?:\+\d{1,3}|00\d{1,3}|0)[\s\-/]?\(?\d{2,5}\)?[\s\-/]?\d{3,8}(?:[\s\-/]\d{1,5})?\b/g,
         validator: validatePhone,
         baseConfidence: 0.80,
     },
@@ -129,17 +134,25 @@ function maskValue(type, value) {
             return value[0] + "***@" + value.substring(atIdx + 1);
         }
         case "phone":
+            // Need room for 4-prefix + ****  + 2-suffix without overlap.
+            if (value.length < 7)
+                return "[PHONE]";
             return value.substring(0, 4) + "****" + value.substring(value.length - 2);
         case "iban":
-            return value.substring(0, 4) + " **** **** ****";
-        case "credit_card":
-            return "**** **** **** " + value.replace(/\D/g, "").substring(12);
+            // Keep country code + check digits, mask rest. Works for any IBAN length.
+            return value.length >= 4 ? value.substring(0, 4) + " **** **** ****" : "[IBAN]";
+        case "credit_card": {
+            const digits = value.replace(/\D/g, "");
+            if (digits.length < 13)
+                return "[CREDIT_CARD]";
+            return "**** **** **** " + digits.substring(digits.length - 4);
+        }
         default:
             return `[${type.toUpperCase()}]`;
     }
 }
 // --- PII Scanner Class ---
-class PIIScanner {
+export class PIIScanner {
     name = "pii";
     patterns;
     action;
@@ -251,5 +264,4 @@ class PIIScanner {
         return masked;
     }
 }
-exports.PIIScanner = PIIScanner;
 //# sourceMappingURL=pii.js.map

package/dist/shield.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shield.d.ts","sourceRoot":"","sources":["../src/shield.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAKpF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUlD,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,GAAE,YAAiB;IAyBrC,qCAAqC;IAC/B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BzE,kDAAkD;IAC5C,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,oBAAoB,EAAE,MAAM,EAC5B,qBAAqB,CAAC,EAAE,MAAM;IAahC,+CAA+C;IACzC,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM;IAMtB,sCAAsC;IAChC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKxD,4BAA4B;IAC5B,SAAS,IAAI,YAAY;IAIzB,2BAA2B;IAC3B,UAAU,IAAI,IAAI;IAIlB,sBAAsB;IACtB,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wBAAwB;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;IAkDrB,OAAO,CAAC,UAAU;CA2BnB"}
+{"version":3,"file":"shield.d.ts","sourceRoot":"","sources":["../src/shield.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAKpF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUlD,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,GAAE,YAAiB;IAyBrC,qCAAqC;IAC/B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA4CzE,kDAAkD;IAC5C,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,oBAAoB,EAAE,MAAM,EAC5B,qBAAqB,CAAC,EAAE,MAAM;IAahC,+CAA+C;IACzC,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM;IAMtB,sCAAsC;IAChC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKxD,4BAA4B;IAC5B,SAAS,IAAI,YAAY;IAIzB,2BAA2B;IAC3B,UAAU,IAAI,IAAI;IAIlB,sBAAsB;IACtB,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wBAAwB;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;IAkDrB,OAAO,CAAC,UAAU;CA2BnB"}