shield360 1.1.0 → 1.2.0

package/dist/ai-security/mcp.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * MCP and tool pinning (OWASP LLM03 supply chain): which MCP servers and
+ * tools an app may use, and what each tool said about itself when it was
+ * approved.
+ *
+ * A tool is pinned by the SHA-256 of its description and of its input
+ * schema (canonical JSON). When a server lists its tools the SDK compares
+ * them with the pins from the platform:
+ *
+ *   mcp_unknown_server  a server not on the allow-list (by name, and by
+ *                       publisher and version when the pin names them)
+ *   mcp_unknown_tool    a tool with no pin
+ *   mcp_tool_changed    a pinned tool whose description or schema changed
+ *                       since approval: the "rug pull"
+ *   mcp_tool_poisoned   a description that reads like tool poisoning
+ *                       (scanned when first seen and on every change)
+ *
+ * Every tool seen is reported to the platform (name, hashes and the
+ * description itself, which is the tool author's text, not user data) so an
+ * operator can approve it or its change; approval adds the pin. With mode
+ * enforce and blockUnknown, unknown, changed and poisoned tools are removed
+ * from the list the model sees and calls to them are refused.
+ *
+ * The description scan is the shared injection detector (source
+ * tool_description) plus tool-rules.json, rules adapted from Cisco AI
+ * Defense's mcp-scanner (Apache-2.0), plus a cross-tool shadowing check: a
+ * description that names another tool of the session with a directive.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/ai_security/_mcp.py
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INJECTION_RULES_VERSION = exports.schemaHash = exports.descriptionHash = exports.TOOL_RULES_VERSION = void 0;
+exports.sha256 = sha256;
+exports.canonicalJson = canonicalJson;
+exports.scanToolDescription = scanToolDescription;
+exports.checkServerTools = checkServerTools;
+const crypto_1 = require("crypto");
+const tool_rules_json_1 = __importDefault(require("./tool-rules.json"));
+const injection_1 = require("./injection");
+Object.defineProperty(exports, "INJECTION_RULES_VERSION", { enumerable: true, get: function () { return injection_1.INJECTION_RULES_VERSION; } });
+const RULES = tool_rules_json_1.default.rules.map((r) => ({ ...r, compiled: r.patterns.map((p) => new RegExp(p, 'iu')) }));
+exports.TOOL_RULES_VERSION = tool_rules_json_1.default.version;
+const TOOL_THRESHOLD = tool_rules_json_1.default.threshold;
+function sha256(text) {
+    return (0, crypto_1.createHash)('sha256').update(text, 'utf8').digest('hex');
+}
+/** JSON with object keys sorted, so the same schema always hashes the same. */
+function canonicalJson(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.filter((k) => value[k] !== undefined).map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+const descriptionHash = (description) => sha256((description || '').trim());
+exports.descriptionHash = descriptionHash;
+const schemaHash = (schema) => sha256(canonicalJson(schema ?? null));
+exports.schemaHash = schemaHash;
+/**
+ * How much a tool description reads like tool poisoning: the injection
+ * detector's rules for tool descriptions, the tool rules, and cross-tool
+ * shadowing (another tool of the session named with a directive).
+ */
+function scanToolDescription(description, otherTools = []) {
+    const text = (description || '').slice(0, 20000);
+    if (!text)
+        return { score: 0, detected: false, rules: [] };
+    const inj = (0, injection_1.scanForInjection)(text, { source: 'tool_description' });
+    let keep = 1 - inj.score;
+    const rules = inj.matches.map((m) => m.rule);
+    for (const rule of RULES) {
+        if (rule.compiled.some((re) => re.test(text))) {
+            rules.push(rule.id);
+            keep *= 1 - rule.weight;
+        }
+    }
+    const lower = text.toLowerCase();
+    const shadowed = otherTools.find((name) => {
+        const n = name.toLowerCase();
+        if (n.length < 3)
+            return false;
+        const at = lower.indexOf(n);
+        if (at < 0)
+            return false;
+        const around = lower.slice(Math.max(0, at - 120), at + n.length + 120);
+        return /\b(?:always|must|instead|never|before|whenever|override|replace|redirect)\b/.test(around);
+    });
+    if (shadowed) {
+        rules.push('tool.cross_tool_shadowing');
+        keep *= 1 - 0.6;
+    }
+    const score = Math.round((1 - keep) * 1000) / 1000;
+    return { score, detected: score >= Math.min(TOOL_THRESHOLD, inj.threshold), rules: Array.from(new Set(rules)).sort() };
+}
+/** Compares a server's tools with the pins. Pure: no events, no network. */
+function checkServerTools(policy, server, tools) {
+    const enforce = policy.mode === 'enforce';
+    const pin = policy.servers.find((s) => s.name === server.name);
+    let allowed = true;
+    let reason;
+    if (!pin) {
+        allowed = false;
+        reason = 'unknown';
+    }
+    else if (pin.publisher && pin.publisher !== server.publisher) {
+        allowed = false;
+        reason = 'publisher';
+    }
+    else if (pin.version && pin.version !== server.version) {
+        allowed = false;
+        reason = 'version';
+    }
+    // An unpinned server is refused only with blockUnknown; a pinned one that changed publisher or version always is.
+    const refuseServer = enforce && !allowed && (reason !== 'unknown' || policy.blockUnknown);
+    const pins = new Map();
+    for (const t of policy.tools)
+        if (t.server === server.name)
+            pins.set(t.name, t);
+    const names = tools.map((t) => t.name);
+    const verdicts = tools.map((tool) => {
+        const dh = (0, exports.descriptionHash)(tool.description);
+        const sh = (0, exports.schemaHash)(tool.inputSchema);
+        const p = pins.get(tool.name);
+        let status = 'pinned';
+        const changed = [];
+        if (!p)
+            status = 'unknown';
+        else {
+            if (p.descriptionHash !== dh)
+                changed.push('description');
+            if (p.schemaHash !== sh)
+                changed.push('schema');
+            if (changed.length)
+                status = 'changed';
+        }
+        // Scanned when first seen and when changed; a pinned, unchanged tool was scanned at approval.
+        const poisoning = status === 'pinned' ? { score: 0, detected: false, rules: [] } : scanToolDescription(tool.description || '', names.filter((n) => n !== tool.name));
+        const refuse = refuseServer || (enforce && (poisoning.detected || status === 'changed' || (status === 'unknown' && policy.blockUnknown)));
+        return { tool: tool.name, descriptionHash: dh, schemaHash: sh, status, ...(changed.length ? { changed } : {}), poisoning, refuse };
+    });
+    return { server: server.name, allowed, ...(reason ? { reason } : {}), tools: verdicts };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/ai-security/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/ai-security/mcp.ts"],"names":[],"mappings":"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"}

package/dist/ai-security/output.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Output scanning (OWASP LLM02 sensitive information disclosure, LLM05
+ * improper output handling, LLM07 system prompt leakage): what a model
+ * answered, checked before the app returns it.
+ *
+ *   pii / secret     built-in kinds (e-mail, SSN, payment card, phone; API
+ *                    keys, tokens, private keys, connection strings)
+ *   custom_kind      the organisation's own kinds of data
+ *   cross_tenant     identifiers of another tenant that reached this
+ *                    request's context (RAG tenant check, tagContext)
+ *   exfil_link       markdown/HTML images to domains not on the allow-list
+ *                    (renderers fetch them unasked), and links or images
+ *                    carrying data in their query string or path
+ *   system_prompt_leak  runs of the request's own system prompt (distinctive
+ *                    6-word shingles) appearing in the answer
+ *   canary_leak      the configured canary marker appearing in the answer
+ *
+ * Findings carry a masked token and a keyed fingerprint, never the value.
+ * redact replaces each finding's span with its token (or "[link removed]");
+ * block withholds the answer. A leaked system prompt is withheld in enforce
+ * mode whatever the action: a redacted prompt still leaks its structure.
+ *
+ * OutputStreamScanner checks a streamed answer as it arrives with bounded
+ * memory: it holds back the last HOLDBACK characters so a value split across
+ * chunks can still be redacted, and scans a sliding window.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/ai_security/_output.py
+ */
+import type { AiSecurityPolicy, CustomDataKindDef } from './policy';
+export type OutputFindingKind = 'pii' | 'secret' | 'custom_kind' | 'cross_tenant' | 'exfil_link' | 'system_prompt_leak' | 'canary_leak';
+export type OutputFinding = {
+    kind: OutputFindingKind;
+    /** The label: email, payment_card, api_key, a custom kind's id, image, query_data... */
+    label: string;
+    start: number;
+    end: number;
+    masked: string;
+    fingerprint?: string;
+};
+export type OutputScanOptions = {
+    policy: AiSecurityPolicy['output'];
+    customKinds?: readonly CustomDataKindDef[];
+    /** The request's system prompt, for the leakage check. */
+    systemPrompt?: string | null;
+    /** Lower-cased identifier -> other tenant. */
+    foreign?: ReadonlyMap<string, string>;
+};
+export type OutputScanResult = {
+    findings: OutputFinding[];
+    /** The text with every finding replaced by its token. */
+    redacted: string;
+    /** Whether enforce mode must withhold the answer whatever the action. */
+    mustBlock: boolean;
+};
+export declare function hostAllowed(host: string, allowed: readonly string[]): boolean;
+/** Whether a URL carries data: a long query value or path segment that looks encoded, or a sensitive value. */
+export declare function urlCarriesData(url: string): boolean;
+/** The distinctive 6-word shingles of a system prompt: those with at least two words that are not stop words. */
+export declare function promptShingles(prompt: string, max?: number): Set<string>;
+/** A leak: at least 3 shingles and at least a tenth of the prompt's (or 25, whichever is less). */
+export declare function isLeak(matched: number, total: number): boolean;
+export declare function scanOutput(text: string, opts: OutputScanOptions): OutputScanResult;
+/** Replaces finding spans with their tokens; overlapping spans merge, the earliest finding's token wins. */
+export declare function redact(text: string, findings: readonly OutputFinding[]): string;
+/** Characters held back before release, so a value split across chunks is still caught whole. */
+export declare const HOLDBACK = 256;
+/** Characters of already-released text kept for context (prompt shingles, links that started earlier). */
+export declare const WINDOW = 2048;
+/** Pending characters beyond the holdback before a scan runs: fewer scans of the window, at most this much more delay. */
+export declare const RELEASE_STEP = 128;
+export type StreamVerdict = {
+    text: string;
+    findings: OutputFinding[];
+    blocked: boolean;
+};
+/**
+ * Scans a streamed answer incrementally. push() returns what may be released
+ * now (redacted when asked); end() returns the rest. Memory is bounded by
+ * WINDOW + HOLDBACK + one chunk; the prompt-leak count needs only the
+ * shingles already seen. When blocking, nothing more is released once a
+ * finding that blocks appears.
+ */
+export declare class OutputStreamScanner {
+    private readonly opts;
+    private readonly enforce;
+    private pending;
+    private released;
+    /** Characters released so far, for stable finding ids. */
+    private offset;
+    private readonly shingles;
+    private readonly leaked;
+    private tailWords;
+    /** A word cut by the chunk boundary, completed by the next chunk. */
+    private partial;
+    private reported;
+    blocked: boolean;
+    readonly findings: OutputFinding[];
+    constructor(opts: OutputScanOptions, enforce: {
+        redact: boolean;
+        block: boolean;
+    });
+    push(chunk: string): StreamVerdict;
+    end(): StreamVerdict;
+    private countShingles;
+    private release;
+    private verdict;
+}

package/dist/ai-security/output.js

@@ -0,0 +1,390 @@
+"use strict";
+/**
+ * Output scanning (OWASP LLM02 sensitive information disclosure, LLM05
+ * improper output handling, LLM07 system prompt leakage): what a model
+ * answered, checked before the app returns it.
+ *
+ *   pii / secret     built-in kinds (e-mail, SSN, payment card, phone; API
+ *                    keys, tokens, private keys, connection strings)
+ *   custom_kind      the organisation's own kinds of data
+ *   cross_tenant     identifiers of another tenant that reached this
+ *                    request's context (RAG tenant check, tagContext)
+ *   exfil_link       markdown/HTML images to domains not on the allow-list
+ *                    (renderers fetch them unasked), and links or images
+ *                    carrying data in their query string or path
+ *   system_prompt_leak  runs of the request's own system prompt (distinctive
+ *                    6-word shingles) appearing in the answer
+ *   canary_leak      the configured canary marker appearing in the answer
+ *
+ * Findings carry a masked token and a keyed fingerprint, never the value.
+ * redact replaces each finding's span with its token (or "[link removed]");
+ * block withholds the answer. A leaked system prompt is withheld in enforce
+ * mode whatever the action: a redacted prompt still leaks its structure.
+ *
+ * OutputStreamScanner checks a streamed answer as it arrives with bounded
+ * memory: it holds back the last HOLDBACK characters so a value split across
+ * chunks can still be redacted, and scans a sliding window.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/ai_security/_output.py
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputStreamScanner = exports.RELEASE_STEP = exports.WINDOW = exports.HOLDBACK = void 0;
+exports.hostAllowed = hostAllowed;
+exports.urlCarriesData = urlCarriesData;
+exports.promptShingles = promptShingles;
+exports.isLeak = isLeak;
+exports.scanOutput = scanOutput;
+exports.redact = redact;
+const findings_1 = require("../guard/findings");
+const custom_kinds_1 = require("./custom-kinds");
+const luhn = (v) => {
+    const d = v.replace(/\D/g, '');
+    if (d.length < 13 || d.length > 19)
+        return false;
+    let sum = 0;
+    for (let i = 0; i < d.length; i++) {
+        let n = d.charCodeAt(d.length - 1 - i) - 48;
+        if (i % 2 === 1) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+    }
+    return sum % 10 === 0;
+};
+const issuableSsn = (v) => {
+    const [a, b, c] = v.split('-');
+    return a !== '000' && a !== '666' && a[0] !== '9' && b !== '00' && c !== '0000';
+};
+// High-precision shapes only: an output check that flags every hex string is switched off by the people it annoys.
+const PATTERNS = [
+    { label: 'openai-api-key', kind: 'secret', re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}/g },
+    { label: 'anthropic-api-key', kind: 'secret', re: /\bsk-ant-[A-Za-z0-9_-]{20,}/g },
+    { label: 'aws-access-key', kind: 'secret', re: /(?<![A-Za-z0-9/+=])(?:AKIA|ASIA)[0-9A-Z]{16}(?![A-Za-z0-9/+=])/g },
+    { label: 'gcp-api-key', kind: 'secret', re: /\bAIza[0-9A-Za-z_-]{35}/g },
+    { label: 'github-token', kind: 'secret', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{36,}/g },
+    { label: 'github-fine-grained', kind: 'secret', re: /\bgithub_pat_[A-Za-z0-9_]{22,}/g },
+    { label: 'stripe-key', kind: 'secret', re: /\b(?:sk|rk)_live_[A-Za-z0-9]{24,}/g },
+    { label: 'slack-token', kind: 'secret', re: /\bxox[bpoas]-[A-Za-z0-9-]{10,}/g },
+    { label: 'private-key', kind: 'secret', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----/g },
+    { label: 'connection-string', kind: 'secret', re: /\b(?:mongodb(?:\+srv)?|postgres(?:ql)?|mysql|redis|amqps?):\/\/[^\s:@/]+:[^\s@/]+@[^\s]+/g },
+    { label: 'jwt', kind: 'secret', re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g },
+    { label: 'email', kind: 'pii', re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}\b/g },
+    { label: 'ssn', kind: 'pii', re: /(?<![0-9-])[0-9]{3}-[0-9]{2}-[0-9]{4}(?![0-9-])/g, check: issuableSsn },
+    { label: 'credit-card', kind: 'pii', re: /(?<![0-9])(?:4[0-9]{3}|5[1-5][0-9]{2}|3[47][0-9]{2}|6(?:011|5[0-9]{2}))(?:[ -]?[0-9]{4}){2}[ -]?[0-9]{3,4}(?![0-9])/g, check: luhn },
+    { label: 'phone-us', kind: 'pii', re: /(?<![0-9])(?:\+1[ .-]?)?\(?[2-9][0-9]{2}\)?[ .-][0-9]{3}[ .-][0-9]{4}(?![0-9])/g },
+];
+// ---------------------------------------------------------------------------
+// Links.
+const MD_IMAGE = /!\[[^\]\n]{0,200}\]\(\s*<?(https?:\/\/[^\s)>]+)>?[^)\n]{0,200}\)/gi;
+const HTML_IMAGE = /<img\b[^>\n]{0,300}?\bsrc\s*=\s*["']?(https?:\/\/[^\s"'>]+)/gi;
+const ANY_URL = /\bhttps?:\/\/[^\s<>"'()\]]+/gi;
+function hostAllowed(host, allowed) {
+    const h = host.toLowerCase().replace(/\.$/, '');
+    return allowed.some((d) => (d.startsWith('*.') ? h === d.slice(2) || h.endsWith(d.slice(1)) : h === d));
+}
+/** Whether a URL carries data: a long query value or path segment that looks encoded, or a sensitive value. */
+function urlCarriesData(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    const values = [];
+    parsed.searchParams.forEach((v) => values.push(v));
+    if (parsed.hash.length > 1)
+        values.push(decodeSafe(parsed.hash.slice(1)));
+    for (const seg of parsed.pathname.split('/'))
+        values.push(decodeSafe(seg));
+    return values.some((v) => {
+        if (v.length >= 40 && /^[A-Za-z0-9+/=_-]+$/.test(v))
+            return true; // base64 / hex blob
+        if (v.length >= 24 && /\s/.test(v) && /[a-z]{3,}/i.test(v))
+            return true; // prose in a URL
+        return PATTERNS.some((p) => {
+            p.re.lastIndex = 0;
+            const m = p.re.exec(v);
+            return !!m && (!p.check || p.check(m[0]));
+        });
+    });
+}
+function decodeSafe(s) {
+    try {
+        return decodeURIComponent(s.replace(/\+/g, ' '));
+    }
+    catch {
+        return s;
+    }
+}
+// ---------------------------------------------------------------------------
+// System prompt shingles.
+const SHINGLE = 6;
+const STOP = new Set('a an and are as at be by for from has have i if in into is it its of on or that the their them then there these they this to was were will with you your we our us not no do does can should must may'.split(' '));
+const words = (text) => text.toLowerCase().match(/[\p{L}\p{N}]+/gu) || [];
+/** The distinctive 6-word shingles of a system prompt: those with at least two words that are not stop words. */
+function promptShingles(prompt, max = 5000) {
+    const w = words(prompt);
+    const out = new Set();
+    for (let i = 0; i + SHINGLE <= w.length && out.size < max; i++) {
+        const s = w.slice(i, i + SHINGLE);
+        if (s.filter((x) => !STOP.has(x)).length >= 2)
+            out.add(s.join(' '));
+    }
+    return out;
+}
+/** How many of the prompt's shingles appear in a text (each counted once). */
+function leakedShingles(text, shingles) {
+    if (!shingles.size)
+        return 0;
+    const w = words(text);
+    const seen = new Set();
+    for (let i = 0; i + SHINGLE <= w.length; i++) {
+        const s = w.slice(i, i + SHINGLE).join(' ');
+        if (shingles.has(s))
+            seen.add(s);
+    }
+    return seen.size;
+}
+/** A leak: at least 3 shingles and at least a tenth of the prompt's (or 25, whichever is less). */
+function isLeak(matched, total) {
+    if (total === 0 || matched < 3)
+        return false;
+    return matched >= Math.min(25, Math.max(3, Math.ceil(total * 0.1)));
+}
+// ---------------------------------------------------------------------------
+// The scan.
+function finding(kind, label, start, end, value) {
+    if (kind === 'exfil_link')
+        return { kind, label, start, end, masked: '[link removed]' };
+    const f = (0, findings_1.makeFinding)(kind === 'custom_kind' ? `custom_${label}` : kind === 'cross_tenant' ? 'cross_tenant' : label, value);
+    return { kind, label, start, end, masked: f.masked, ...(f.fingerprint ? { fingerprint: f.fingerprint } : {}) };
+}
+const MAX_SCAN = 200000;
+function scanOutput(text, opts) {
+    const p = opts.policy;
+    const t = typeof text === 'string' ? (text.length > MAX_SCAN ? text.slice(0, MAX_SCAN) : text) : '';
+    const out = [];
+    let mustBlock = false;
+    if (!t)
+        return { findings: out, redacted: typeof text === 'string' ? text : '', mustBlock };
+    for (const pat of PATTERNS) {
+        if ((pat.kind === 'pii' && !p.pii) || (pat.kind === 'secret' && !p.secrets))
+            continue;
+        pat.re.lastIndex = 0;
+        let m;
+        while ((m = pat.re.exec(t)) && out.length < 200) {
+            if (pat.check && !pat.check(m[0]))
+                continue;
+            out.push(finding(pat.kind, pat.label, m.index, m.index + m[0].length, m[0]));
+        }
+    }
+    if (p.customKinds && opts.customKinds?.length) {
+        for (const f of (0, custom_kinds_1.findCustomKinds)(t, opts.customKinds).slice(0, 100))
+            out.push(finding('custom_kind', f.id, f.start, f.end, t.slice(f.start, f.end)));
+    }
+    if (p.crossTenant && opts.foreign?.size) {
+        const lower = t.toLowerCase();
+        opts.foreign.forEach((_tenant, id) => {
+            let at = lower.indexOf(id);
+            while (at >= 0 && out.length < 300) {
+                out.push(finding('cross_tenant', 'identifier', at, at + id.length, t.slice(at, at + id.length)));
+                at = lower.indexOf(id, at + id.length);
+            }
+        });
+    }
+    if (p.exfilLinks) {
+        const images = new Set();
+        for (const re of [MD_IMAGE, HTML_IMAGE]) {
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(t))) {
+                const url = m[1];
+                const start = m.index + m[0].indexOf(url);
+                images.add(start);
+                let host = '';
+                try {
+                    host = new URL(url).hostname;
+                }
+                catch {
+                    continue;
+                }
+                const allowed = p.allowedDomains.length > 0 && hostAllowed(host, p.allowedDomains);
+                if (allowed)
+                    continue;
+                if (p.allowedDomains.length > 0 || urlCarriesData(url))
+                    out.push(finding('exfil_link', 'image', start, start + url.length, url));
+            }
+        }
+        ANY_URL.lastIndex = 0;
+        let m;
+        while ((m = ANY_URL.exec(t))) {
+            if (images.has(m.index))
+                continue;
+            const url = m[0].replace(/[.,;:!?]+$/, '');
+            let host = '';
+            try {
+                host = new URL(url).hostname;
+            }
+            catch {
+                continue;
+            }
+            if (p.allowedDomains.length > 0 && hostAllowed(host, p.allowedDomains))
+                continue;
+            if (urlCarriesData(url))
+                out.push(finding('exfil_link', 'query_data', m.index, m.index + url.length, url));
+        }
+    }
+    if (p.canary) {
+        const at = t.indexOf(p.canary);
+        if (at >= 0) {
+            out.push({ kind: 'canary_leak', label: 'canary', start: at, end: at + p.canary.length, masked: '[canary]' });
+            mustBlock = true;
+        }
+    }
+    if (p.systemPromptLeak && opts.systemPrompt) {
+        const shingles = promptShingles(opts.systemPrompt);
+        const n = leakedShingles(t, shingles);
+        if (isLeak(n, shingles.size)) {
+            out.push({ kind: 'system_prompt_leak', label: `${n}/${shingles.size}`, start: 0, end: 0, masked: '[system prompt]' });
+            mustBlock = true;
+        }
+    }
+    return { findings: out, redacted: redact(text, out), mustBlock };
+}
+/** Replaces finding spans with their tokens; overlapping spans merge, the earliest finding's token wins. */
+function redact(text, findings) {
+    const spans = findings
+        .filter((f) => f.end > f.start)
+        .slice()
+        .sort((a, b) => a.start - b.start || b.end - a.end);
+    const merged = [];
+    for (const f of spans) {
+        const last = merged[merged.length - 1];
+        if (last && f.start < last.end)
+            last.end = Math.max(last.end, f.end);
+        else
+            merged.push({ start: f.start, end: f.end, masked: f.masked });
+    }
+    let s = text;
+    for (let i = merged.length - 1; i >= 0; i--)
+        s = s.slice(0, merged[i].start) + merged[i].masked + s.slice(merged[i].end);
+    return s;
+}
+// ---------------------------------------------------------------------------
+// Streaming.
+/** Characters held back before release, so a value split across chunks is still caught whole. */
+exports.HOLDBACK = 256;
+/** Characters of already-released text kept for context (prompt shingles, links that started earlier). */
+exports.WINDOW = 2048;
+/** Pending characters beyond the holdback before a scan runs: fewer scans of the window, at most this much more delay. */
+exports.RELEASE_STEP = 128;
+/**
+ * Scans a streamed answer incrementally. push() returns what may be released
+ * now (redacted when asked); end() returns the rest. Memory is bounded by
+ * WINDOW + HOLDBACK + one chunk; the prompt-leak count needs only the
+ * shingles already seen. When blocking, nothing more is released once a
+ * finding that blocks appears.
+ */
+class OutputStreamScanner {
+    constructor(opts, enforce) {
+        this.opts = opts;
+        this.enforce = enforce;
+        this.pending = '';
+        this.released = '';
+        /** Characters released so far, for stable finding ids. */
+        this.offset = 0;
+        this.leaked = new Set();
+        this.tailWords = [];
+        /** A word cut by the chunk boundary, completed by the next chunk. */
+        this.partial = '';
+        this.reported = new Set();
+        this.blocked = false;
+        this.findings = [];
+        this.shingles = opts.policy.systemPromptLeak && opts.systemPrompt ? promptShingles(opts.systemPrompt) : new Set();
+    }
+    push(chunk) {
+        if (this.blocked)
+            return { text: '', findings: [], blocked: true };
+        this.pending += chunk || '';
+        this.countShingles(chunk || '');
+        if (this.pending.length <= exports.HOLDBACK + exports.RELEASE_STEP)
+            return this.verdict('', []);
+        return this.release(this.pending.length - exports.HOLDBACK);
+    }
+    end() {
+        if (this.blocked)
+            return { text: '', findings: [], blocked: true };
+        this.countShingles(' ');
+        return this.release(this.pending.length);
+    }
+    countShingles(chunk) {
+        if (!this.shingles.size)
+            return;
+        const text = this.partial + chunk;
+        const cut = text.match(/[\p{L}\p{N}]+$/u);
+        this.partial = cut ? cut[0].slice(-64) : '';
+        const w = this.tailWords.concat(words(cut ? text.slice(0, text.length - cut[0].length) : text));
+        for (let i = 0; i + SHINGLE <= w.length; i++) {
+            const s = w.slice(i, i + SHINGLE).join(' ');
+            if (this.shingles.has(s))
+                this.leaked.add(s);
+        }
+        this.tailWords = w.slice(-(SHINGLE - 1));
+    }
+    release(upTo) {
+        // Scan the released tail plus everything pending, so a match straddling the cut is seen whole.
+        const ctx = this.released.slice(-exports.WINDOW);
+        const scanText = ctx + this.pending;
+        const { findings } = scanOutput(scanText, { ...this.opts, systemPrompt: null });
+        const fresh = [];
+        for (const f of findings) {
+            // Only findings that end in the part being released are judged now; later ones wait for more text.
+            const start = f.start - ctx.length;
+            const end = f.end - ctx.length;
+            if (end <= 0)
+                continue; // seen and handled in an earlier window
+            if (start >= upTo && upTo < this.pending.length)
+                continue;
+            const id = `${f.kind}:${f.label}:${f.masked}:${start + this.offset}`;
+            if (this.reported.has(id))
+                continue;
+            this.reported.add(id);
+            fresh.push({ ...f, start, end });
+        }
+        if (isLeak(this.leaked.size, this.shingles.size) && !this.reported.has('leak')) {
+            this.reported.add('leak');
+            fresh.push({ kind: 'system_prompt_leak', label: `${this.leaked.size}/${this.shingles.size}`, start: 0, end: 0, masked: '[system prompt]' });
+        }
+        const blocks = fresh.some((f) => f.kind === 'system_prompt_leak' || f.kind === 'canary_leak');
+        if (fresh.length && this.enforce.block)
+            this.blocked = true;
+        if (blocks && (this.enforce.block || this.enforce.redact))
+            this.blocked = true;
+        if (this.blocked) {
+            this.findings.push(...fresh);
+            this.pending = '';
+            return { text: '', findings: fresh, blocked: true };
+        }
+        // Extend the cut so no finding is split: a value that crosses it is released whole (redacted) now.
+        let cut = upTo;
+        for (const f of fresh)
+            if (f.start < cut && f.end > cut)
+                cut = Math.min(this.pending.length, f.end);
+        const part = this.pending.slice(0, cut);
+        const inPart = fresh.filter((f) => f.start >= 0 && f.end <= cut);
+        const text = this.enforce.redact ? redact(part, inPart) : part;
+        this.pending = this.pending.slice(cut);
+        this.released = (this.released + part).slice(-exports.WINDOW);
+        this.offset += part.length;
+        this.findings.push(...fresh);
+        return this.verdict(text, fresh);
+    }
+    verdict(text, findings) {
+        return { text, findings, blocked: this.blocked };
+    }
+}
+exports.OutputStreamScanner = OutputStreamScanner;
+//# sourceMappingURL=output.js.map