codegate-ai 0.16.2 → 1.0.0

package/dist/layer2-static/detectors/skill-frontmatter.js

@@ -0,0 +1,130 @@
+import { load as parseYaml } from "js-yaml";
+import { normalizeForMatching } from "../text/normalize.js";
+import { REMOTE_INSTRUCTION_INDIRECTION_PATTERN, REMOTE_SHELL_PATTERN, findOverridePhrase, } from "../text/threat-patterns.js";
+const SKILL_FILE_NAME = "skill.md";
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u;
+// Tool grants that hand a skill unrestricted execution or wildcard access.
+const BROAD_TOOL_BASES = new Set(["bash", "shell", "terminal", "exec", "execute"]);
+const WILDCARD_GRANTS = new Set(["*", "all"]);
+function isSkillFile(filePath) {
+    const segments = filePath.replaceAll("\\", "/").split("/");
+    return (segments[segments.length - 1] ?? "").toLowerCase() === SKILL_FILE_NAME;
+}
+function skillDirectoryName(filePath) {
+    const segments = filePath.replaceAll("\\", "/").split("/");
+    return segments.length >= 2 ? (segments[segments.length - 2] ?? null) : null;
+}
+function makeFinding(input, ruleId, field, severity, category, description, cwe) {
+    return {
+        rule_id: ruleId,
+        finding_id: `SKILL_FRONTMATTER-${input.filePath}-${field}`,
+        severity,
+        category,
+        layer: "L2",
+        file_path: input.filePath,
+        location: { field: `frontmatter.${field}` },
+        description,
+        affected_tools: ["claude-code", "codex-cli", "opencode", "cursor"],
+        cve: null,
+        owasp: ["ASI02"],
+        cwe,
+        confidence: "HIGH",
+        fixable: true,
+        remediation_actions: ["remove_field", "quarantine_file"],
+        metadata: {
+            sources: [input.filePath, field],
+            risk_tags: ["skill", "frontmatter"],
+            origin: "skill-frontmatter",
+        },
+        suppressed: false,
+    };
+}
+function parseFrontmatter(textContent) {
+    const match = textContent.match(FRONTMATTER_PATTERN);
+    if (!match?.[1]) {
+        return null;
+    }
+    try {
+        const parsed = parseYaml(match[1]);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function collectToolGrants(value) {
+    if (typeof value === "string") {
+        return value
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+    }
+    if (Array.isArray(value)) {
+        return value
+            .filter((entry) => typeof entry === "string")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+    }
+    return [];
+}
+function parseToolGrant(raw) {
+    const match = raw.match(/^([^()]+)(?:\(([^)]*)\))?$/u);
+    const base = (match?.[1] ?? raw).trim().toLowerCase();
+    const qualifier = match?.[2] !== undefined ? match[2].trim() : null;
+    return { raw, base, qualifier };
+}
+function isBroadGrant(grant) {
+    if (WILDCARD_GRANTS.has(grant.base)) {
+        return true;
+    }
+    if (!BROAD_TOOL_BASES.has(grant.base)) {
+        return false;
+    }
+    return grant.qualifier === null || grant.qualifier === "" || grant.qualifier === "*";
+}
+function frontmatterTextFields(frontmatter) {
+    const texts = [];
+    for (const value of Object.values(frontmatter)) {
+        if (typeof value === "string") {
+            texts.push(value);
+        }
+    }
+    return texts;
+}
+export function detectSkillFrontmatterIssues(input) {
+    if (!isSkillFile(input.filePath)) {
+        return [];
+    }
+    const frontmatter = parseFrontmatter(input.textContent);
+    if (!frontmatter) {
+        return [];
+    }
+    const findings = [];
+    const grantsRaw = frontmatter["allowed-tools"] ?? frontmatter.allowed_tools;
+    const broadGrants = collectToolGrants(grantsRaw).map(parseToolGrant).filter(isBroadGrant);
+    if (broadGrants.length > 0) {
+        findings.push(makeFinding(input, "skill-allowed-tools-broad", "allowed-tools", "HIGH", "CONSENT_BYPASS", `Skill frontmatter requests unrestricted tool access: ${broadGrants
+            .map((grant) => grant.raw)
+            .join(", ")}. Unqualified shell or wildcard grants let the skill run arbitrary commands.`, "CWE-250"));
+    }
+    const hiddenInstructionTexts = frontmatterTextFields(frontmatter).filter((text) => {
+        const normalized = normalizeForMatching(text);
+        return (findOverridePhrase(normalized) !== null ||
+            REMOTE_SHELL_PATTERN.test(normalized) ||
+            REMOTE_INSTRUCTION_INDIRECTION_PATTERN.test(normalized));
+    });
+    if (hiddenInstructionTexts.length > 0) {
+        findings.push(makeFinding(input, "skill-frontmatter-hidden-instructions", "metadata", "HIGH", "RULE_INJECTION", "Skill frontmatter metadata contains override, remote-shell, or remote-instruction language " +
+            "outside the visible skill body.", "CWE-116"));
+    }
+    const declaredName = typeof frontmatter.name === "string" ? frontmatter.name.trim() : null;
+    const directoryName = skillDirectoryName(input.filePath);
+    if (declaredName && directoryName && declaredName.toLowerCase() !== directoryName.toLowerCase()) {
+        findings.push(makeFinding(input, "skill-frontmatter-mismatch", "name", "INFO", "CONFIG_PRESENT", `Skill frontmatter name "${declaredName}" does not match its directory "${directoryName}". ` +
+            "Name confusion is a common registry-squatting signal.", "CWE-1021"));
+    }
+    return findings;
+}

package/dist/layer2-static/engine.d.ts

@@ -3,6 +3,7 @@ import { type SymlinkEscapeEntry } from "./detectors/symlink.js";
 import type { AuditPersona, RuntimeMode } from "../config.js";
 import { type Finding } from "../types/finding.js";
 import type { DiscoveryFormat } from "../types/discovery.js";
+import type { ResolvedKnownBadIndicators } from "../content/known-bad.js";
 export interface StaticFileInput {
     filePath: string;
     format: DiscoveryFormat;
@@ -28,6 +29,7 @@ export interface StaticEngineConfig {
         disable?: boolean;
         config?: Record<string, unknown>;
     }>;
+    knownBadIndicators?: ResolvedKnownBadIndicators;
 }
 export interface StaticEngineInput {
     projectRoot: string;

package/dist/layer2-static/rule-pack-loader.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { loadActiveContentBundle } from "../content/content-store.js";
 const defaultRulesDir = resolve(dirname(fileURLToPath(import.meta.url)), "rules");
 const require = createRequire(import.meta.url);
 const Ajv = require("ajv");
@@ -179,9 +180,31 @@ function normalizeOptions(arg) {
         skipRules: normalizeRuleIds(options.skip_rules),
     };
 }
+function loadContentFeedRules() {
+    try {
+        const bundle = loadActiveContentBundle();
+        const rules = bundle?.rules ?? [];
+        const validated = [];
+        for (const candidate of rules) {
+            if (!ruleValidator(candidate)) {
+                // One invalid feed rule disqualifies the feed's rule set; bundled
+                // rules remain the safe baseline.
+                return [];
+            }
+            validated.push(candidate);
+        }
+        return validated;
+    }
+    catch {
+        return [];
+    }
+}
 export function loadRulePacks(arg) {
     const options = normalizeOptions(arg);
     const bundledRules = collectRulesFromPaths([options.baseDir]);
+    const feedRules = loadContentFeedRules();
     const externalRules = collectRulesFromPaths(options.rulePackPaths);
-    return filterRules(dedupeByRuleId([...bundledRules, ...externalRules]), options.allowedRules, options.skipRules);
+    // Later entries win in dedupe: user packs override feed rules, which
+    // override bundled rules.
+    return filterRules(dedupeByRuleId([...bundledRules, ...feedRules, ...externalRules]), options.allowedRules, options.skipRules);
 }

package/dist/layer2-static/state/scan-state.d.ts

@@ -5,6 +5,7 @@ export interface ScanStateServerEntry {
     first_seen: string;
     last_seen: string;
 }
+/** Scan state for a single project root (one slice of the state file). */
 export interface ScanState {
     servers: Record<string, ScanStateServerEntry>;
 }
@@ -19,14 +20,18 @@ export interface EvaluateScanStateSnapshotsInput {
     snapshots: McpServerSnapshot[];
     previousState: ScanState;
     nowIso?: string;
+    /** Trusted targets get INFO first-seen findings; untrusted get MEDIUM. */
+    trustedTarget?: boolean;
+    /** When false, first-seen findings are skipped (state is still recorded). */
+    firstScanReview?: boolean;
 }
 export interface EvaluateScanStateSnapshotsResult {
     findings: Finding[];
     nextState: ScanState;
 }
 export declare function getScanStatePath(customPath?: string): string;
-export declare function loadScanState(customPath?: string): ScanState;
-export declare function saveScanState(state: ScanState, customPath?: string): void;
+export declare function loadScanState(customPath?: string, projectRoot?: string): ScanState;
+export declare function saveScanState(state: ScanState, customPath?: string, projectRoot?: string): void;
 export declare function resetScanState(customPath?: string): void;
 export declare function evaluateScanStateSnapshots(input: EvaluateScanStateSnapshotsInput): EvaluateScanStateSnapshotsResult;
 export declare function extractMcpServerSnapshots(filePath: string, parsed: unknown): McpServerSnapshot[];

package/dist/layer2-static/state/scan-state.js

@@ -2,6 +2,9 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
+const SCAN_STATE_FILE_VERSION = 2;
+/** Bucket used when no project root is supplied (direct API use, tooling). */
+const SHARED_PROJECT_KEY = "*";
 const LAUNCHERS = new Set(["npx", "uvx", "node", "python", "python3", "deno", "bun"]);
 const MCP_SERVER_CONTAINER_KEYS = ["mcpServers", "mcp_servers", "context_servers"];
 const REMOTE_MCP_SERVER_ARRAY_KEYS = ["remoteMCPServers", "remote_mcp_servers"];
@@ -106,18 +109,29 @@ function normalizedUrlServerId(rawUrl) {
         return `url:${trimmed}`;
     }
 }
-function makeStateFinding(kind, snapshot, previousLastSeen) {
+const STATE_FINDING_KIND = {
+    NewServer: "NEW_SERVER",
+    ConfigChange: "CONFIG_CHANGE",
+};
+/** First-use of a server in an untrusted project deserves a visible review. */
+function firstSeenSeverity(trustedTarget) {
+    return trustedTarget ? "INFO" : "MEDIUM";
+}
+function makeStateFinding(kind, snapshot, previousLastSeen, trustedTarget) {
     const locationField = snapshot.serverPath ?? `mcpServers.${snapshot.serverName}`;
-    if (kind === "NEW_SERVER") {
+    if (kind === STATE_FINDING_KIND.NewServer) {
+        const reviewNote = trustedTarget
+            ? "Not previously scanned."
+            : "Not previously scanned in this untrusted project; review its configuration before use.";
         return {
             rule_id: "mcp-server-first-seen",
             finding_id: `NEW_SERVER-${snapshot.serverId}`,
-            severity: "INFO",
+            severity: firstSeenSeverity(trustedTarget),
             category: "NEW_SERVER",
             layer: "L2",
             file_path: snapshot.configPath,
             location: { field: locationField },
-            description: `MCP server "${snapshot.serverId}" first seen in this project. Not previously scanned.`,
+            description: `MCP server "${snapshot.serverId}" first seen in this project. ${reviewNote}`,
             affected_tools: ["claude-code", "cursor", "windsurf", "codex-cli", "opencode"],
             cve: null,
             owasp: ["ASI08"],
@@ -150,31 +164,22 @@ function makeStateFinding(kind, snapshot, previousLastSeen) {
 export function getScanStatePath(customPath) {
     return resolve(expandHomePath(customPath ?? defaultPath()));
 }
-export function loadScanState(customPath) {
-    const path = getScanStatePath(customPath);
-    if (!existsSync(path)) {
-        return { servers: {} };
-    }
-    let parsed;
-    try {
-        const raw = readFileSync(path, "utf8");
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return { servers: {} };
-    }
-    if (!isRecord(parsed) || !isRecord(parsed.servers)) {
-        return { servers: {} };
+function projectStateKey(projectRoot) {
+    return projectRoot === undefined ? SHARED_PROJECT_KEY : resolve(projectRoot);
+}
+function parseServerEntries(value) {
+    if (!isRecord(value)) {
+        return {};
     }
     const entries = {};
-    for (const [key, value] of Object.entries(parsed.servers)) {
-        if (!isRecord(value)) {
+    for (const [key, entry] of Object.entries(value)) {
+        if (!isRecord(entry)) {
             continue;
         }
-        const config_hash = typeof value.config_hash === "string" ? value.config_hash : "";
-        const config_path = typeof value.config_path === "string" ? value.config_path : "";
-        const first_seen = typeof value.first_seen === "string" ? value.first_seen : "";
-        const last_seen = typeof value.last_seen === "string" ? value.last_seen : "";
+        const config_hash = typeof entry.config_hash === "string" ? entry.config_hash : "";
+        const config_path = typeof entry.config_path === "string" ? entry.config_path : "";
+        const first_seen = typeof entry.first_seen === "string" ? entry.first_seen : "";
+        const last_seen = typeof entry.last_seen === "string" ? entry.last_seen : "";
         if (!config_hash || !config_path || !first_seen || !last_seen) {
             continue;
         }
@@ -185,12 +190,47 @@ export function loadScanState(customPath) {
             last_seen,
         };
     }
-    return { servers: entries };
+    return entries;
 }
-export function saveScanState(state, customPath) {
+function loadScanStateFile(customPath) {
+    const empty = { version: SCAN_STATE_FILE_VERSION, projects: {} };
     const path = getScanStatePath(customPath);
+    if (!existsSync(path)) {
+        return empty;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return empty;
+    }
+    // Legacy (unversioned, top-level `servers`) and malformed files both reset:
+    // legacy entries carry no project provenance, so trusting them would leak
+    // baselines across projects.
+    if (!isRecord(parsed) ||
+        parsed.version !== SCAN_STATE_FILE_VERSION ||
+        !isRecord(parsed.projects)) {
+        return empty;
+    }
+    const projects = {};
+    for (const [projectKey, slice] of Object.entries(parsed.projects)) {
+        if (isRecord(slice)) {
+            projects[projectKey] = { servers: parseServerEntries(slice.servers) };
+        }
+    }
+    return { version: SCAN_STATE_FILE_VERSION, projects };
+}
+export function loadScanState(customPath, projectRoot) {
+    const file = loadScanStateFile(customPath);
+    return file.projects[projectStateKey(projectRoot)] ?? { servers: {} };
+}
+export function saveScanState(state, customPath, projectRoot) {
+    const path = getScanStatePath(customPath);
+    const file = loadScanStateFile(customPath);
+    file.projects[projectStateKey(projectRoot)] = state;
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, "utf8");
 }
 export function resetScanState(customPath) {
     const path = getScanStatePath(customPath);
@@ -198,6 +238,8 @@ export function resetScanState(customPath) {
 }
 export function evaluateScanStateSnapshots(input) {
     const nowIso = input.nowIso ?? new Date().toISOString();
+    const trustedTarget = input.trustedTarget ?? false;
+    const firstScanReview = input.firstScanReview ?? true;
     const nextState = {
         servers: { ...input.previousState.servers },
     };
@@ -205,7 +247,9 @@ export function evaluateScanStateSnapshots(input) {
     for (const snapshot of input.snapshots) {
         const previous = nextState.servers[snapshot.serverId];
         if (!previous) {
-            findings.push(makeStateFinding("NEW_SERVER", snapshot, null));
+            if (firstScanReview) {
+                findings.push(makeStateFinding(STATE_FINDING_KIND.NewServer, snapshot, null, trustedTarget));
+            }
             nextState.servers[snapshot.serverId] = {
                 config_hash: snapshot.configHash,
                 config_path: snapshot.configPath,
@@ -215,7 +259,7 @@ export function evaluateScanStateSnapshots(input) {
             continue;
         }
         if (previous.config_hash !== snapshot.configHash) {
-            findings.push(makeStateFinding("CONFIG_CHANGE", snapshot, previous.last_seen));
+            findings.push(makeStateFinding(STATE_FINDING_KIND.ConfigChange, snapshot, previous.last_seen, trustedTarget));
             nextState.servers[snapshot.serverId] = {
                 config_hash: snapshot.configHash,
                 config_path: snapshot.configPath,

package/dist/layer2-static/text/confusables.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Minimal confusables map: non-Latin code points that render like Latin
+ * letters and are used to slip phrases past literal matching. NFKC already
+ * folds fullwidth/compatibility forms; this covers the Cyrillic and Greek
+ * lookalikes NFKC leaves alone. Data-driven so a content feed can extend it.
+ */
+export declare const CONFUSABLE_TO_LATIN: Readonly<Record<string, string>>;

package/dist/layer2-static/text/confusables.js

@@ -0,0 +1,70 @@
+/**
+ * Minimal confusables map: non-Latin code points that render like Latin
+ * letters and are used to slip phrases past literal matching. NFKC already
+ * folds fullwidth/compatibility forms; this covers the Cyrillic and Greek
+ * lookalikes NFKC leaves alone. Data-driven so a content feed can extend it.
+ */
+export const CONFUSABLE_TO_LATIN = {
+    // Cyrillic lowercase
+    а: "a",
+    в: "b",
+    е: "e",
+    ё: "e",
+    к: "k",
+    м: "m",
+    н: "h",
+    о: "o",
+    р: "p",
+    с: "c",
+    т: "t",
+    у: "y",
+    х: "x",
+    і: "i",
+    ѕ: "s",
+    ј: "j",
+    ԁ: "d",
+    ԛ: "q",
+    ѡ: "w",
+    // Cyrillic uppercase
+    А: "A",
+    В: "B",
+    Е: "E",
+    К: "K",
+    М: "M",
+    Н: "H",
+    О: "O",
+    Р: "P",
+    С: "C",
+    Т: "T",
+    У: "Y",
+    Х: "X",
+    І: "I",
+    Ѕ: "S",
+    Ј: "J",
+    // Greek lowercase
+    α: "a",
+    ε: "e",
+    η: "n",
+    ι: "i",
+    κ: "k",
+    ν: "v",
+    ο: "o",
+    ρ: "p",
+    τ: "t",
+    υ: "u",
+    // Greek uppercase
+    Α: "A",
+    Β: "B",
+    Ε: "E",
+    Ζ: "Z",
+    Η: "H",
+    Ι: "I",
+    Κ: "K",
+    Μ: "M",
+    Ν: "N",
+    Ο: "O",
+    Ρ: "P",
+    Τ: "T",
+    Υ: "Y",
+    Χ: "X",
+};

package/dist/layer2-static/text/edit-distance.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Damerau-Levenshtein distance (optimal string alignment variant):
+ * insertions, deletions, substitutions, and adjacent transpositions each
+ * cost 1. Small inputs only (package names), so the O(n*m) table is fine.
+ */
+export declare function damerauLevenshtein(left: string, right: string): number;

package/dist/layer2-static/text/edit-distance.js

@@ -0,0 +1,33 @@
+/**
+ * Damerau-Levenshtein distance (optimal string alignment variant):
+ * insertions, deletions, substitutions, and adjacent transpositions each
+ * cost 1. Small inputs only (package names), so the O(n*m) table is fine.
+ */
+export function damerauLevenshtein(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    const rows = left.length + 1;
+    const cols = right.length + 1;
+    const table = Array.from({ length: rows }, () => new Array(cols).fill(0));
+    for (let row = 0; row < rows; row += 1) {
+        table[row][0] = row;
+    }
+    for (let col = 0; col < cols; col += 1) {
+        table[0][col] = col;
+    }
+    for (let row = 1; row < rows; row += 1) {
+        for (let col = 1; col < cols; col += 1) {
+            const cost = left[row - 1] === right[col - 1] ? 0 : 1;
+            let value = Math.min(table[row - 1][col] + 1, table[row][col - 1] + 1, table[row - 1][col - 1] + cost);
+            if (row > 1 &&
+                col > 1 &&
+                left[row - 1] === right[col - 2] &&
+                left[row - 2] === right[col - 1]) {
+                value = Math.min(value, table[row - 2][col - 2] + 1);
+            }
+            table[row][col] = value;
+        }
+    }
+    return table[rows - 1][cols - 1];
+}

package/dist/layer2-static/text/encoded-payloads.d.ts

@@ -0,0 +1,16 @@
+export declare const ENCODED_PAYLOAD_KIND: {
+    readonly Base64: "base64";
+    readonly Hex: "hex";
+};
+export type EncodedPayloadKind = (typeof ENCODED_PAYLOAD_KIND)[keyof typeof ENCODED_PAYLOAD_KIND];
+export interface EncodedPayloadMatch {
+    kind: EncodedPayloadKind;
+    line: number;
+    decodedExcerpt: string;
+    matchesRemoteShell: boolean;
+    matchesOverridePhrase: boolean;
+    matchesSensitiveExfil: boolean;
+    matchesCommandExecution: boolean;
+}
+/** Scan text for encoded blobs whose decoded content matches threat patterns. */
+export declare function scanEncodedPayloads(text: string): EncodedPayloadMatch[];

package/dist/layer2-static/text/encoded-payloads.js

@@ -0,0 +1,116 @@
+import { normalizeForMatching } from "./normalize.js";
+import { COMMAND_EXECUTION_PATTERN, EXFIL_PATTERN, REMOTE_SHELL_PATTERN, SENSITIVE_FILE_PATTERN, findOverridePhrase, } from "./threat-patterns.js";
+/**
+ * Bounded decode-and-rescan for base64/hex blobs embedded in instruction
+ * files and tool descriptions. Hard limits keep this pass cheap and
+ * non-explosive: one nesting level, capped blob count and decoded size.
+ */
+const BASE64_RUN_PATTERN = /[A-Za-z0-9+/_-]{40,}={0,2}/gu;
+const HEX_RUN_PATTERN = /(?:[0-9a-fA-F]{2}){30,}/gu;
+const MAX_BLOBS_PER_TEXT = 20;
+const MAX_DECODED_BYTES = 64 * 1024;
+const MIN_PRINTABLE_RATIO = 0.3;
+const DECODED_EXCERPT_LENGTH = 160;
+export const ENCODED_PAYLOAD_KIND = {
+    Base64: "base64",
+    Hex: "hex",
+};
+function printableRatio(text) {
+    if (text.length === 0) {
+        return 0;
+    }
+    let printable = 0;
+    for (const char of text) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code === 0x09 || code === 0x0a || code === 0x0d || (code >= 0x20 && code < 0x7f)) {
+            printable += 1;
+        }
+    }
+    return printable / text.length;
+}
+function decodeBase64(blob) {
+    // Normalize base64url variants before decoding.
+    const normalized = blob.replace(/-/gu, "+").replace(/_/gu, "/");
+    try {
+        const decoded = Buffer.from(normalized, "base64");
+        if (decoded.length === 0 || decoded.length > MAX_DECODED_BYTES) {
+            return null;
+        }
+        return decoded.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function decodeHex(blob) {
+    try {
+        const decoded = Buffer.from(blob, "hex");
+        if (decoded.length === 0 || decoded.length > MAX_DECODED_BYTES) {
+            return null;
+        }
+        return decoded.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function lineNumberAt(text, index) {
+    return text.slice(0, index).split(/\r?\n/u).length;
+}
+function isDataImageUri(text, blobIndex) {
+    const prefixStart = Math.max(0, blobIndex - 40);
+    return /data:image\/[a-z+.-]+;base64,?$/iu.test(text.slice(prefixStart, blobIndex));
+}
+function analyzeDecoded(kind, line, decoded) {
+    if (printableRatio(decoded) < MIN_PRINTABLE_RATIO) {
+        return null;
+    }
+    const normalized = normalizeForMatching(decoded);
+    const matchesRemoteShell = REMOTE_SHELL_PATTERN.test(normalized);
+    const matchesOverridePhrase = findOverridePhrase(normalized) !== null;
+    const matchesSensitiveExfil = SENSITIVE_FILE_PATTERN.test(normalized) && EXFIL_PATTERN.test(normalized);
+    const matchesCommandExecution = COMMAND_EXECUTION_PATTERN.test(normalized);
+    if (!matchesRemoteShell &&
+        !matchesOverridePhrase &&
+        !matchesSensitiveExfil &&
+        !matchesCommandExecution) {
+        return null;
+    }
+    return {
+        kind,
+        line,
+        decodedExcerpt: decoded.slice(0, DECODED_EXCERPT_LENGTH),
+        matchesRemoteShell,
+        matchesOverridePhrase,
+        matchesSensitiveExfil,
+        matchesCommandExecution,
+    };
+}
+/** Scan text for encoded blobs whose decoded content matches threat patterns. */
+export function scanEncodedPayloads(text) {
+    const matches = [];
+    let blobsSeen = 0;
+    const scanRuns = (pattern, kind, decode) => {
+        pattern.lastIndex = 0;
+        let match = pattern.exec(text);
+        while (match && blobsSeen < MAX_BLOBS_PER_TEXT) {
+            blobsSeen += 1;
+            const blob = match[0];
+            if (kind === ENCODED_PAYLOAD_KIND.Base64 && isDataImageUri(text, match.index)) {
+                match = pattern.exec(text);
+                continue;
+            }
+            const decoded = decode(blob);
+            if (decoded) {
+                const analyzed = analyzeDecoded(kind, lineNumberAt(text, match.index), decoded);
+                if (analyzed) {
+                    matches.push(analyzed);
+                }
+            }
+            match = pattern.exec(text);
+        }
+    };
+    scanRuns(BASE64_RUN_PATTERN, ENCODED_PAYLOAD_KIND.Base64, decodeBase64);
+    scanRuns(HEX_RUN_PATTERN, ENCODED_PAYLOAD_KIND.Hex, decodeHex);
+    return matches;
+}

package/dist/layer2-static/text/normalize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalize text before threat-pattern matching so trivial obfuscation
+ * (zero-width splits, tag characters, homoglyphs, compatibility forms)
+ * cannot dodge literal patterns:
+ *
+ *   NFKC -> strip hidden characters -> fold confusables -> lowercase
+ *
+ * Normalize per line when line numbers matter: evidence must quote the
+ * original line while matching runs against the normalized one.
+ */
+export declare function normalizeForMatching(text: string): string;

package/dist/layer2-static/text/normalize.js

@@ -0,0 +1,19 @@
+import { CONFUSABLE_TO_LATIN } from "./confusables.js";
+import { stripHiddenCharacters } from "./unicode.js";
+const confusablePattern = new RegExp(`[${Object.keys(CONFUSABLE_TO_LATIN).join("")}]`, "gu");
+function foldConfusables(text) {
+    return text.replace(confusablePattern, (char) => CONFUSABLE_TO_LATIN[char] ?? char);
+}
+/**
+ * Normalize text before threat-pattern matching so trivial obfuscation
+ * (zero-width splits, tag characters, homoglyphs, compatibility forms)
+ * cannot dodge literal patterns:
+ *
+ *   NFKC -> strip hidden characters -> fold confusables -> lowercase
+ *
+ * Normalize per line when line numbers matter: evidence must quote the
+ * original line while matching runs against the normalized one.
+ */
+export function normalizeForMatching(text) {
+    return foldConfusables(stripHiddenCharacters(text.normalize("NFKC"))).toLowerCase();
+}