shieldcortex 4.9.0 → 4.10.0

package/dist/environment/fetcher.js

@@ -0,0 +1,137 @@
+const MAX_REDIRECTS = 10;
+const MAX_BYTES = 2 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 15000;
+const USER_AGENT = 'ShieldCortex-EnvScanner/1.0 (+https://shieldcortex.ai)';
+export async function fetchWithProvenance(rawUrl) {
+    const started = Date.now();
+    const redirectChain = [];
+    let current;
+    try {
+        current = new URL(rawUrl);
+    }
+    catch {
+        return {
+            finalUrl: rawUrl,
+            redirectChain: [],
+            statusCode: null,
+            contentType: null,
+            body: '',
+            bytesReceived: 0,
+            durationMs: Date.now() - started,
+            error: 'Invalid URL',
+        };
+    }
+    if (current.protocol !== 'http:' && current.protocol !== 'https:') {
+        return {
+            finalUrl: current.toString(),
+            redirectChain: [],
+            statusCode: null,
+            contentType: null,
+            body: '',
+            bytesReceived: 0,
+            durationMs: Date.now() - started,
+            error: `Unsupported protocol: ${current.protocol}`,
+        };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        for (let i = 0; i <= MAX_REDIRECTS; i++) {
+            const res = await fetch(current.toString(), {
+                method: 'GET',
+                redirect: 'manual',
+                signal: controller.signal,
+                headers: {
+                    'User-Agent': USER_AGENT,
+                    Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                },
+            });
+            if (res.status >= 300 && res.status < 400) {
+                const loc = res.headers.get('location');
+                if (!loc)
+                    break;
+                redirectChain.push(current.toString());
+                current = new URL(loc, current);
+                if (i === MAX_REDIRECTS) {
+                    return {
+                        finalUrl: current.toString(),
+                        redirectChain,
+                        statusCode: res.status,
+                        contentType: res.headers.get('content-type'),
+                        body: '',
+                        bytesReceived: 0,
+                        durationMs: Date.now() - started,
+                        error: 'Too many redirects',
+                    };
+                }
+                continue;
+            }
+            const reader = res.body?.getReader();
+            let received = 0;
+            const chunks = [];
+            if (reader) {
+                while (received < MAX_BYTES) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    if (value) {
+                        received += value.length;
+                        chunks.push(value);
+                        if (received >= MAX_BYTES)
+                            break;
+                    }
+                }
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            const buffer = new Uint8Array(received);
+            let offset = 0;
+            for (const chunk of chunks) {
+                buffer.set(chunk.subarray(0, Math.min(chunk.length, MAX_BYTES - offset)), offset);
+                offset += chunk.length;
+                if (offset >= MAX_BYTES)
+                    break;
+            }
+            const body = new TextDecoder('utf-8', { fatal: false }).decode(buffer);
+            return {
+                finalUrl: res.url || current.toString(),
+                redirectChain,
+                statusCode: res.status,
+                contentType: res.headers.get('content-type'),
+                body,
+                bytesReceived: received,
+                durationMs: Date.now() - started,
+                error: null,
+            };
+        }
+        return {
+            finalUrl: current.toString(),
+            redirectChain,
+            statusCode: null,
+            contentType: null,
+            body: '',
+            bytesReceived: 0,
+            durationMs: Date.now() - started,
+            error: 'Redirect loop without body',
+        };
+    }
+    catch (error) {
+        return {
+            finalUrl: current.toString(),
+            redirectChain,
+            statusCode: null,
+            contentType: null,
+            body: '',
+            bytesReceived: 0,
+            durationMs: Date.now() - started,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/environment/hidden-detector.d.ts

@@ -0,0 +1,2 @@
+import type { HiddenAnalysis } from './types.js';
+export declare function analyseHidden(rawHtml: string): HiddenAnalysis;

package/dist/environment/hidden-detector.js

@@ -0,0 +1,134 @@
+const HIDDEN_SAMPLE_CHARS = 120;
+function stripTagContent(html, tagNames) {
+    let out = html;
+    for (const tag of tagNames) {
+        const re = new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?</${tag}>`, 'gi');
+        out = out.replace(re, ' ');
+    }
+    return out;
+}
+function decodeHtmlEntities(input) {
+    return input
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/gi, "'")
+        .replace(/&apos;/gi, "'")
+        .replace(/&amp;/gi, '&')
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&#(\d+);/g, (_, n) => {
+        const code = parseInt(n, 10);
+        return Number.isFinite(code) && code < 0x10ffff ? String.fromCodePoint(code) : '';
+    });
+}
+function innerText(rawHtml) {
+    const withoutComments = rawHtml.replace(/<!--[\s\S]*?-->/g, ' ');
+    const withoutScripts = stripTagContent(withoutComments, ['script', 'style', 'noscript', 'template']);
+    const withoutTags = withoutScripts.replace(/<[^>]+>/g, ' ');
+    return decodeHtmlEntities(withoutTags).replace(/\s+/g, ' ').trim();
+}
+function collectHiddenSpans(html) {
+    const results = [];
+    const patterns = [
+        ['display_none', /<([a-z][\w-]*)\b[^>]*style=["'][^"']*display\s*:\s*none[^"']*["'][^>]*>([\s\S]*?)<\/\1>/gi],
+        ['visibility_hidden', /<([a-z][\w-]*)\b[^>]*style=["'][^"']*visibility\s*:\s*hidden[^"']*["'][^>]*>([\s\S]*?)<\/\1>/gi],
+        ['zero_font_size', /<([a-z][\w-]*)\b[^>]*style=["'][^"']*font-size\s*:\s*0(?:px|em|rem)?[^"']*["'][^>]*>([\s\S]*?)<\/\1>/gi],
+        ['offscreen_position', /<([a-z][\w-]*)\b[^>]*style=["'][^"']*(?:position\s*:\s*absolute[^"']*(?:left|top)\s*:\s*-\d{3,}|text-indent\s*:\s*-\d{4,})[^"']*["'][^>]*>([\s\S]*?)<\/\1>/gi],
+        ['aria_hidden', /<([a-z][\w-]*)\b[^>]*aria-hidden=["']true["'][^>]*>([\s\S]*?)<\/\1>/gi],
+    ];
+    for (const [technique, re] of patterns) {
+        let match;
+        re.lastIndex = 0;
+        while ((match = re.exec(html)) !== null) {
+            const body = match[2];
+            if (!body)
+                continue;
+            const text = innerText(body);
+            if (text.length > 0)
+                results.push({ technique, text });
+        }
+    }
+    return results;
+}
+function detectSameColourText(html) {
+    const hits = [];
+    const re = /<([a-z][\w-]*)\b[^>]*style=["'][^"']*color\s*:\s*(#fff(?:fff)?|white)[^"']*["'][^>]*>([\s\S]*?)<\/\1>/gi;
+    let match;
+    while ((match = re.exec(html)) !== null) {
+        const text = innerText(match[3] || '');
+        if (text.length > 0)
+            hits.push(text);
+    }
+    return hits;
+}
+function detectComments(html) {
+    const hits = [];
+    const re = /<!--([\s\S]*?)-->/g;
+    let match;
+    while ((match = re.exec(html)) !== null) {
+        const text = match[1].trim();
+        if (text.length > 40)
+            hits.push(text);
+    }
+    return hits;
+}
+function detectScriptTags(html) {
+    const hits = [];
+    const re = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
+    let match;
+    while ((match = re.exec(html)) !== null) {
+        const body = match[1].trim();
+        if (body.length > 0)
+            hits.push(body);
+    }
+    return hits;
+}
+function detectBidiOverride(html) {
+    return /[\u202A-\u202E\u2066-\u2069]/.test(html);
+}
+function detectZeroWidth(html) {
+    return /[\u200B\u200C\u200D\uFEFF]/.test(html);
+}
+function detectMetaRefresh(html) {
+    const match = html.match(/<meta\b[^>]*http-equiv=["']refresh["'][^>]*content=["']([^"']+)["']/i);
+    return match ? match[1] : null;
+}
+function clip(text, max = HIDDEN_SAMPLE_CHARS) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+export function analyseHidden(rawHtml) {
+    const hits = [];
+    for (const { technique, text } of collectHiddenSpans(rawHtml)) {
+        hits.push({ technique, sample: clip(text), charCount: text.length });
+    }
+    for (const text of detectSameColourText(rawHtml)) {
+        hits.push({ technique: 'same_colour_text', sample: clip(text), charCount: text.length });
+    }
+    for (const text of detectComments(rawHtml)) {
+        hits.push({ technique: 'html_comment', sample: clip(text), charCount: text.length });
+    }
+    for (const text of detectScriptTags(rawHtml)) {
+        hits.push({ technique: 'script_tag', sample: clip(text), charCount: text.length });
+    }
+    if (detectBidiOverride(rawHtml)) {
+        hits.push({ technique: 'bidi_override', sample: 'Unicode bidi override characters present', charCount: 0 });
+    }
+    if (detectZeroWidth(rawHtml)) {
+        hits.push({ technique: 'zero_width_text', sample: 'Zero-width characters present in document', charCount: 0 });
+    }
+    const metaRefresh = detectMetaRefresh(rawHtml);
+    if (metaRefresh) {
+        hits.push({ technique: 'meta_refresh', sample: clip(metaRefresh), charCount: metaRefresh.length });
+    }
+    const visible = innerText(rawHtml);
+    const hiddenText = hits
+        .filter((h) => h.technique !== 'script_tag' && h.technique !== 'html_comment' && h.charCount > 0)
+        .map((h) => h.sample)
+        .join(' ');
+    return {
+        hits,
+        hiddenCharCount: hits.reduce((acc, h) => acc + h.charCount, 0),
+        visibleText: visible,
+        hiddenText,
+    };
+}

package/dist/environment/index.d.ts

@@ -0,0 +1,6 @@
+export { scanUrl } from './scanner.js';
+export { scoreProvenance } from './provenance.js';
+export { analyseHidden } from './hidden-detector.js';
+export { deriveTaint } from './taint.js';
+export { formatEnvScanReport, formatEnvScanMarkdown } from './report.js';
+export type { EnvironmentScanResult, ProvenanceResult, ProvenanceSignals, HiddenAnalysis, HiddenInstructionHit, InjectionHit, TaintLabel, } from './types.js';

package/dist/environment/index.js

@@ -0,0 +1,5 @@
+export { scanUrl } from './scanner.js';
+export { scoreProvenance } from './provenance.js';
+export { analyseHidden } from './hidden-detector.js';
+export { deriveTaint } from './taint.js';
+export { formatEnvScanReport, formatEnvScanMarkdown } from './report.js';

package/dist/environment/provenance.d.ts

@@ -0,0 +1,6 @@
+import type { ProvenanceResult } from './types.js';
+export declare function scoreProvenance(args: {
+    originalUrl: string;
+    finalUrl: string;
+    redirectChain: string[];
+}): ProvenanceResult;

package/dist/environment/provenance.js

@@ -0,0 +1,127 @@
+const SUSPICIOUS_TLDS = new Set([
+    'zip', 'mov', 'top', 'xyz', 'click', 'country', 'link', 'gq', 'ml', 'tk', 'cf', 'ga',
+    'quest', 'sbs', 'rest', 'cyou', 'bond', 'cam', 'cfd', 'trade', 'download', 'racing',
+]);
+const KNOWN_GOOD_DOMAINS = new Set([
+    'github.com', 'raw.githubusercontent.com', 'gitlab.com', 'bitbucket.org',
+    'npmjs.com', 'registry.npmjs.org', 'pypi.org', 'rubygems.org', 'crates.io',
+    'anthropic.com', 'openai.com', 'google.com', 'cloudflare.com',
+    'stripe.com', 'mozilla.org', 'w3.org', 'ietf.org', 'python.org',
+    'rust-lang.org', 'golang.org', 'nodejs.org', 'typescriptlang.org',
+    'arxiv.org', 'wikipedia.org', 'wikimedia.org',
+    'shieldcortex.ai', 'drakonsystems.com',
+]);
+const KNOWN_BAD_DOMAINS = new Set([
+// intentionally empty — populated from threat feeds in later phases
+]);
+function extractRegistrableDomain(hostname) {
+    const parts = hostname.toLowerCase().split('.');
+    if (parts.length <= 2)
+        return hostname.toLowerCase();
+    return parts.slice(-2).join('.');
+}
+function isIpAddress(hostname) {
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || /:/.test(hostname);
+}
+function hasPunycode(hostname) {
+    return /xn--/i.test(hostname);
+}
+export function scoreProvenance(args) {
+    const reasons = [];
+    let score = 0.5;
+    let finalParsed;
+    try {
+        finalParsed = new URL(args.finalUrl);
+    }
+    catch {
+        return {
+            score: 0,
+            signals: {
+                tls: false,
+                redirectCount: args.redirectChain.length,
+                redirectChain: args.redirectChain,
+                finalDomain: '',
+                suspiciousTld: false,
+                allowlisted: false,
+                denylisted: false,
+                isIpAddress: false,
+                hasUserInfo: false,
+                hasPunycode: false,
+            },
+            reasons: ['Unparseable final URL'],
+        };
+    }
+    const tls = finalParsed.protocol === 'https:';
+    const finalDomain = extractRegistrableDomain(finalParsed.hostname);
+    const tld = finalDomain.split('.').pop() || '';
+    const suspiciousTld = SUSPICIOUS_TLDS.has(tld);
+    const allowlisted = KNOWN_GOOD_DOMAINS.has(finalDomain) || KNOWN_GOOD_DOMAINS.has(finalParsed.hostname);
+    const denylisted = KNOWN_BAD_DOMAINS.has(finalDomain) || KNOWN_BAD_DOMAINS.has(finalParsed.hostname);
+    const ipHost = isIpAddress(finalParsed.hostname);
+    const userInfo = Boolean(finalParsed.username || finalParsed.password);
+    const punycode = hasPunycode(finalParsed.hostname);
+    if (tls) {
+        score += 0.1;
+        reasons.push('TLS connection');
+    }
+    else {
+        score -= 0.25;
+        reasons.push('Plain HTTP (no TLS)');
+    }
+    if (allowlisted) {
+        score += 0.3;
+        reasons.push(`Allowlisted domain: ${finalDomain}`);
+    }
+    if (denylisted) {
+        score -= 0.8;
+        reasons.push(`Denylisted domain: ${finalDomain}`);
+    }
+    if (suspiciousTld) {
+        score -= 0.2;
+        reasons.push(`Suspicious TLD: .${tld}`);
+    }
+    if (ipHost) {
+        score -= 0.15;
+        reasons.push('Host is raw IP address');
+    }
+    if (userInfo) {
+        score -= 0.3;
+        reasons.push('URL contains embedded credentials');
+    }
+    if (punycode) {
+        score -= 0.1;
+        reasons.push('Host uses Punycode (possible homograph attack)');
+    }
+    if (args.redirectChain.length > 0) {
+        const originalDomain = (() => {
+            try {
+                return extractRegistrableDomain(new URL(args.originalUrl).hostname);
+            }
+            catch {
+                return '';
+            }
+        })();
+        if (originalDomain && originalDomain !== finalDomain) {
+            score -= 0.1;
+            reasons.push(`Cross-domain redirect: ${originalDomain} → ${finalDomain}`);
+        }
+        if (args.redirectChain.length >= 3) {
+            score -= 0.1;
+            reasons.push(`${args.redirectChain.length} redirects before final response`);
+        }
+    }
+    score = Math.max(0, Math.min(1, score));
+    const signals = {
+        tls,
+        redirectCount: args.redirectChain.length,
+        redirectChain: args.redirectChain,
+        finalDomain,
+        suspiciousTld,
+        allowlisted,
+        denylisted,
+        isIpAddress: ipHost,
+        hasUserInfo: userInfo,
+        hasPunycode: punycode,
+    };
+    return { score, signals, reasons };
+}

package/dist/environment/report.d.ts

@@ -0,0 +1,3 @@
+import type { EnvironmentScanResult } from './types.js';
+export declare function formatEnvScanReport(result: EnvironmentScanResult): string;
+export declare function formatEnvScanMarkdown(result: EnvironmentScanResult): string;

package/dist/environment/report.js

@@ -0,0 +1,89 @@
+const TAINT_COLOURS = {
+    trusted: '\x1b[32m',
+    untrusted: '\x1b[33m',
+    suspicious: '\x1b[91m',
+    hostile: '\x1b[31m',
+};
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+export function formatEnvScanReport(result) {
+    const lines = [];
+    const colour = TAINT_COLOURS[result.taint.label];
+    lines.push('');
+    lines.push(`${BOLD}Environment Firewall Report${RESET}`);
+    lines.push('─'.repeat(60));
+    lines.push(`  URL:          ${result.url}`);
+    if (result.finalUrl !== result.url)
+        lines.push(`  Final URL:    ${result.finalUrl}`);
+    lines.push(`  Status:       ${result.statusCode ?? 'n/a'} (${result.bytesReceived} bytes, ${result.fetchDurationMs}ms)`);
+    lines.push(`  Taint:        ${colour}${result.taint.label.toUpperCase()}${RESET} — ${result.taint.reason}`);
+    lines.push(`  Provenance:   ${result.provenance.score.toFixed(2)} (${result.provenance.signals.finalDomain})`);
+    if (result.provenance.reasons.length > 0) {
+        lines.push(`\n${BOLD}Provenance signals:${RESET}`);
+        for (const r of result.provenance.reasons)
+            lines.push(`  - ${r}`);
+    }
+    if (result.hidden.hits.length > 0) {
+        lines.push(`\n${BOLD}Hidden content (${result.hidden.hits.length}):${RESET}`);
+        const grouped = new Map();
+        for (const h of result.hidden.hits)
+            grouped.set(h.technique, (grouped.get(h.technique) ?? 0) + 1);
+        for (const [technique, count] of grouped)
+            lines.push(`  - ${technique}: ${count}`);
+    }
+    if (result.injection.visibleHits.length > 0 || result.injection.hiddenHits.length > 0) {
+        lines.push(`\n${BOLD}Injection patterns:${RESET}`);
+        for (const hit of [...result.injection.hiddenHits, ...result.injection.visibleHits]) {
+            const surfaceTag = hit.surface === 'hidden' ? `${TAINT_COLOURS.hostile}[HIDDEN]${RESET}` : `${DIM}[visible]${RESET}`;
+            lines.push(`  ${surfaceTag} ${hit.pattern}: "${hit.snippet.slice(0, 80)}"`);
+        }
+    }
+    if (result.risks.length > 0) {
+        lines.push(`\n${BOLD}Risks:${RESET}`);
+        for (const r of result.risks)
+            lines.push(`  - ${r}`);
+    }
+    lines.push('');
+    lines.push(result.summary);
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatEnvScanMarkdown(result) {
+    const lines = [];
+    lines.push(`# Environment Firewall Report`);
+    lines.push('');
+    lines.push(`- **URL**: ${result.url}`);
+    if (result.finalUrl !== result.url)
+        lines.push(`- **Final URL**: ${result.finalUrl}`);
+    lines.push(`- **Status**: ${result.statusCode ?? 'n/a'} (${result.bytesReceived} bytes, ${result.fetchDurationMs}ms)`);
+    lines.push(`- **Taint**: \`${result.taint.label.toUpperCase()}\` — ${result.taint.reason}`);
+    lines.push(`- **Provenance score**: ${result.provenance.score.toFixed(2)} (${result.provenance.signals.finalDomain})`);
+    if (result.provenance.reasons.length > 0) {
+        lines.push('');
+        lines.push('## Provenance signals');
+        for (const r of result.provenance.reasons)
+            lines.push(`- ${r}`);
+    }
+    if (result.hidden.hits.length > 0) {
+        lines.push('');
+        lines.push('## Hidden content');
+        for (const h of result.hidden.hits) {
+            lines.push(`- \`${h.technique}\` (${h.charCount} chars): ${h.sample}`);
+        }
+    }
+    if (result.injection.visibleHits.length > 0 || result.injection.hiddenHits.length > 0) {
+        lines.push('');
+        lines.push('## Injection patterns');
+        for (const hit of [...result.injection.hiddenHits, ...result.injection.visibleHits]) {
+            lines.push(`- **[${hit.surface}]** \`${hit.pattern}\`: "${hit.snippet.slice(0, 120)}"`);
+        }
+    }
+    if (result.risks.length > 0) {
+        lines.push('');
+        lines.push('## Risks');
+        for (const r of result.risks)
+            lines.push(`- ${r}`);
+    }
+    return lines.join('\n');
+}

package/dist/environment/scanner.d.ts

@@ -0,0 +1,2 @@
+import type { EnvironmentScanResult } from './types.js';
+export declare function scanUrl(url: string): Promise<EnvironmentScanResult>;

package/dist/environment/scanner.js

@@ -0,0 +1,119 @@
+import { scanForInjection } from '../defence/iron-dome/injection-scanner.js';
+import { fetchWithProvenance } from './fetcher.js';
+import { scoreProvenance } from './provenance.js';
+import { analyseHidden } from './hidden-detector.js';
+import { deriveTaint } from './taint.js';
+function toHits(detections, surface) {
+    return detections.map((d) => ({
+        surface,
+        pattern: `${d.category}/${d.pattern}`,
+        snippet: d.match,
+    }));
+}
+function buildRisks(args) {
+    const risks = [];
+    if (args.hiddenHits.length > 0) {
+        risks.push(`${args.hiddenHits.length} injection pattern${args.hiddenHits.length === 1 ? '' : 's'} found in HIDDEN content — humans will never see this.`);
+    }
+    if (args.visibleHits.length > 0) {
+        risks.push(`${args.visibleHits.length} injection pattern${args.visibleHits.length === 1 ? '' : 's'} found in visible content.`);
+    }
+    const htmlComments = args.hidden.hits.filter((h) => h.technique === 'html_comment');
+    if (htmlComments.length > 0) {
+        risks.push(`${htmlComments.length} substantial HTML comment${htmlComments.length === 1 ? '' : 's'} — review for hidden agent instructions.`);
+    }
+    const layoutHides = args.hidden.hits.filter((h) => ['display_none', 'visibility_hidden', 'zero_font_size', 'offscreen_position', 'same_colour_text'].includes(h.technique));
+    if (layoutHides.length > 0) {
+        risks.push(`${layoutHides.length} CSS-hidden text region${layoutHides.length === 1 ? '' : 's'} — content visible to an agent parser but not a human reader.`);
+    }
+    if (args.hidden.hits.some((h) => h.technique === 'bidi_override')) {
+        risks.push('Unicode bidi override characters found — possible rendering-vs-parsing deception.');
+    }
+    if (args.hidden.hits.some((h) => h.technique === 'meta_refresh')) {
+        risks.push('Meta refresh redirect in document — agent may be steered to a different page.');
+    }
+    if (args.hidden.hits.some((h) => h.technique === 'zero_width_text')) {
+        risks.push('Zero-width characters in document — possible obfuscation or watermark.');
+    }
+    if (!args.provenance.signals.tls)
+        risks.push('Fetched over plain HTTP — content integrity not verified.');
+    if (args.provenance.signals.denylisted)
+        risks.push(`Final domain is denylisted: ${args.provenance.signals.finalDomain}.`);
+    if (args.provenance.signals.suspiciousTld)
+        risks.push(`Final domain uses a suspicious TLD (.${args.provenance.signals.finalDomain.split('.').pop()}).`);
+    if (args.provenance.signals.hasPunycode)
+        risks.push('Domain uses Punycode — possible homograph attack against a known brand.');
+    if (args.provenance.signals.isIpAddress)
+        risks.push('Request went to a raw IP address rather than a domain name.');
+    if (args.statusCode && args.statusCode >= 400)
+        risks.push(`HTTP ${args.statusCode} — response may be an error page rather than the intended content.`);
+    return risks;
+}
+function buildSummary(result) {
+    const lines = [];
+    lines.push(`Taint: ${result.taint.label.toUpperCase()} — ${result.taint.reason}`);
+    lines.push(`Provenance score: ${result.provenance.score.toFixed(2)} (${result.provenance.signals.finalDomain})`);
+    lines.push(`Visible injection hits: ${result.injection.visibleHits.length}`);
+    lines.push(`Hidden injection hits: ${result.injection.hiddenHits.length}`);
+    lines.push(`Hidden content techniques: ${result.hidden.hits.length > 0 ? Array.from(new Set(result.hidden.hits.map((h) => h.technique))).join(', ') : 'none'}`);
+    return lines.join('\n');
+}
+export async function scanUrl(url) {
+    const fetched = await fetchWithProvenance(url);
+    const provenance = scoreProvenance({
+        originalUrl: url,
+        finalUrl: fetched.finalUrl,
+        redirectChain: fetched.redirectChain,
+    });
+    if (fetched.error || !fetched.body) {
+        const hidden = { hits: [], hiddenCharCount: 0, visibleText: '', hiddenText: '' };
+        const injection = { visibleHits: [], hiddenHits: [] };
+        const taint = deriveTaint({ provenance, hidden, visibleHits: [], hiddenHits: [] });
+        const risks = buildRisks({ provenance, hidden, visibleHits: [], hiddenHits: [], statusCode: fetched.statusCode });
+        if (fetched.error)
+            risks.unshift(`Fetch failed: ${fetched.error}`);
+        const partial = { taint, provenance, injection, hidden, finalUrl: fetched.finalUrl };
+        return {
+            url,
+            finalUrl: fetched.finalUrl,
+            statusCode: fetched.statusCode,
+            contentType: fetched.contentType,
+            fetchedAt: new Date().toISOString(),
+            fetchDurationMs: fetched.durationMs,
+            bytesReceived: fetched.bytesReceived,
+            error: fetched.error,
+            provenance,
+            hidden,
+            injection,
+            taint,
+            risks,
+            summary: buildSummary(partial),
+        };
+    }
+    const hidden = analyseHidden(fetched.body);
+    const visibleScan = scanForInjection(hidden.visibleText);
+    const hiddenScan = scanForInjection(hidden.hiddenText);
+    const injection = {
+        visibleHits: toHits(visibleScan.detections, 'visible'),
+        hiddenHits: toHits(hiddenScan.detections, 'hidden'),
+    };
+    const taint = deriveTaint({ provenance, hidden, visibleHits: injection.visibleHits, hiddenHits: injection.hiddenHits });
+    const risks = buildRisks({ provenance, hidden, visibleHits: injection.visibleHits, hiddenHits: injection.hiddenHits, statusCode: fetched.statusCode });
+    const partial = { taint, provenance, injection, hidden, finalUrl: fetched.finalUrl };
+    return {
+        url,
+        finalUrl: fetched.finalUrl,
+        statusCode: fetched.statusCode,
+        contentType: fetched.contentType,
+        fetchedAt: new Date().toISOString(),
+        fetchDurationMs: fetched.durationMs,
+        bytesReceived: fetched.bytesReceived,
+        error: null,
+        provenance,
+        hidden,
+        injection,
+        taint,
+        risks,
+        summary: buildSummary(partial),
+    };
+}

package/dist/environment/taint.d.ts

@@ -0,0 +1,10 @@
+import type { HiddenAnalysis, InjectionHit, ProvenanceResult, TaintLabel } from './types.js';
+export declare function deriveTaint(args: {
+    provenance: ProvenanceResult;
+    hidden: HiddenAnalysis;
+    visibleHits: InjectionHit[];
+    hiddenHits: InjectionHit[];
+}): {
+    label: TaintLabel;
+    reason: string;
+};