codegate-ai 0.16.2 → 1.0.0

package/dist/layer2-static/text/override-phrases.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Instruction-override phrases matched against normalized (NFKC, hidden
+ * characters stripped, confusable-folded, lowercased) text. This is the
+ * high-signal literal tier; semantic analysis belongs to the Layer 3
+ * meta-agent. Data-driven so the content feed can extend it.
+ */
+export interface OverridePhrase {
+    phrase: string;
+    language: string;
+}
+export declare const OVERRIDE_PHRASES: readonly OverridePhrase[];
+export declare function resetActiveOverridePhrasesCache(): void;
+/** Bundled phrases plus any extras delivered by the verified content feed. */
+export declare function activeOverridePhrases(): readonly OverridePhrase[];

package/dist/layer2-static/text/override-phrases.js

@@ -0,0 +1,49 @@
+import { loadActiveContentBundle } from "../../content/content-store.js";
+export const OVERRIDE_PHRASES = [
+    { phrase: "ignore previous instructions", language: "en" },
+    { phrase: "ignore all previous instructions", language: "en" },
+    { phrase: "disregard previous instructions", language: "en" },
+    { phrase: "disregard prior instructions", language: "en" },
+    { phrase: "skip permissions", language: "en" },
+    { phrase: "bypass permissions", language: "en" },
+    { phrase: "bypass safety", language: "en" },
+    { phrase: "disable guardrails", language: "en" },
+    { phrase: "ignora las instrucciones anteriores", language: "es" },
+    { phrase: "ignore las instrucciones anteriores", language: "es" },
+    { phrase: "ignore as instrucoes anteriores", language: "pt" },
+    { phrase: "ignore as instruções anteriores", language: "pt" },
+    { phrase: "ignore les instructions precedentes", language: "fr" },
+    { phrase: "ignore les instructions précédentes", language: "fr" },
+    { phrase: "ignorez les instructions précédentes", language: "fr" },
+    { phrase: "ignoriere alle vorherigen anweisungen", language: "de" },
+    { phrase: "ignoriere die vorherigen anweisungen", language: "de" },
+    { phrase: "игнорируй предыдущие инструкции", language: "ru" },
+    { phrase: "игнорируйте предыдущие инструкции", language: "ru" },
+    { phrase: "忽略之前的指令", language: "zh" },
+    { phrase: "忽略以上指令", language: "zh" },
+    { phrase: "忽略先前的指示", language: "zh" },
+    { phrase: "以前の指示を無視して", language: "ja" },
+    { phrase: "これまでの指示を無視", language: "ja" },
+];
+let cachedActivePhrases = null;
+export function resetActiveOverridePhrasesCache() {
+    cachedActivePhrases = null;
+}
+/** Bundled phrases plus any extras delivered by the verified content feed. */
+export function activeOverridePhrases() {
+    if (cachedActivePhrases) {
+        return cachedActivePhrases;
+    }
+    let feedPhrases;
+    try {
+        const bundle = loadActiveContentBundle();
+        feedPhrases = (bundle?.override_phrases ?? []).filter((entry) => typeof entry?.phrase === "string" &&
+            entry.phrase.length > 0 &&
+            typeof entry?.language === "string");
+    }
+    catch {
+        feedPhrases = [];
+    }
+    cachedActivePhrases = [...OVERRIDE_PHRASES, ...feedPhrases];
+    return cachedActivePhrases;
+}

package/dist/layer2-static/text/threat-patterns.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared threat patterns for instruction/rule-file text and MCP tool
+ * descriptions. Callers are expected to match against text run through
+ * normalizeForMatching() so hidden-character and homoglyph obfuscation
+ * cannot dodge these literals.
+ */
+export declare const NEGATION_PATTERN: RegExp;
+export declare const SENSITIVE_READ_PATTERN: RegExp;
+export declare const SENSITIVE_FILE_PATTERN: RegExp;
+export declare const OUTBOUND_TRANSFER_PATTERN: RegExp;
+export declare const EXFIL_PATTERN: RegExp;
+export declare const COMMAND_EXECUTION_PATTERN: RegExp;
+export declare const REMOTE_SHELL_PATTERN: RegExp;
+export declare const SUSPICIOUS_LONG_LINE_PATTERN: RegExp;
+export declare const HTML_COMMENT_PATTERN: RegExp;
+export declare const COMMENT_PAYLOAD_PATTERN: RegExp;
+export declare const COOKIE_EXPORT_PATTERN: RegExp;
+export declare const SESSION_SHARE_PATTERN: RegExp;
+export declare const PROFILE_SYNC_PATTERN: RegExp;
+export declare const BOOTSTRAP_INSTALL_PATTERN: RegExp;
+export declare const AGENT_CONTROL_POINT_PATTERN: RegExp;
+export declare const RESTART_LOAD_PATTERN: RegExp;
+export declare const REMOTE_INSTRUCTION_INDIRECTION_PATTERN: RegExp;
+export interface OverridePhraseMatch {
+    phrase: string;
+    index: number;
+}
+/**
+ * Find the first instruction-override phrase in a normalized line, skipping
+ * matches preceded by nearby negation ("never bypass permissions").
+ */
+export declare function findOverridePhrase(normalizedLine: string): OverridePhraseMatch | null;
+export declare function hasNegationBefore(normalizedLine: string, matchIndex: number): boolean;

package/dist/layer2-static/text/threat-patterns.js

@@ -0,0 +1,45 @@
+import { activeOverridePhrases } from "./override-phrases.js";
+/**
+ * Shared threat patterns for instruction/rule-file text and MCP tool
+ * descriptions. Callers are expected to match against text run through
+ * normalizeForMatching() so hidden-character and homoglyph obfuscation
+ * cannot dodge these literals.
+ */
+export const NEGATION_PATTERN = /\b(?:must not|should not|do not|don't|never)\b/iu;
+export const SENSITIVE_READ_PATTERN = /\b(?:read|cat)\s+(?:~\/\.ssh(?:\/[^\s]+)?|\.env\b|~\/\.[a-z0-9._-]+(?:\/[^\s]+)*)/iu;
+export const SENSITIVE_FILE_PATTERN = /(~\/\.ssh|~\/\.aws|id_rsa|\.env|credentials|\.git-credentials)/iu;
+export const OUTBOUND_TRANSFER_PATTERN = /\b(?:upload externally|send to (?:an |a )?(?:external )?(?:webhook|endpoint|server)|curl\b|wget\b|invoke-webrequest\b|post to\b|https?:\/\/|exfiltrat(?:e|ion|ing))\b/iu;
+export const EXFIL_PATTERN = /(send .*https?:\/\/|upload|webhook|post to|exfiltrat)/iu;
+export const COMMAND_EXECUTION_PATTERN = /(run command|execute shell|bash -c|sh -c|powershell)/iu;
+export const REMOTE_SHELL_PATTERN = /\b(?:curl|wget)\b[^\n|]{0,240}\|\s*(?:bash|sh)\b|\b(?:invoke-webrequest|iwr)\b[^\n|]{0,240}\|\s*(?:iex|invoke-expression)\b/iu;
+export const SUSPICIOUS_LONG_LINE_PATTERN = /\b(?:ignore previous instructions|skip permissions|bypass permissions|upload externally|curl\b|wget\b|https?:\/\/|bash\s+-lc|sh\s+-c|powershell\b|base64\b|~\/\.ssh|\.env\b)\b/iu;
+export const HTML_COMMENT_PATTERN = /<!--([\s\S]*?)-->/gu;
+export const COMMENT_PAYLOAD_PATTERN = /\b(?:secret instructions|ignore previous instructions|curl\b|wget\b|invoke-webrequest\b|bash\b|powershell\b|session share\b|profile sync\b)\b/iu;
+export const COOKIE_EXPORT_PATTERN = /\bcookies?\s+(?:export|import|get)\b/iu;
+export const SESSION_SHARE_PATTERN = /\bsession\s+share\b|\blive url\b/iu;
+export const PROFILE_SYNC_PATTERN = /\bprofile\s+sync\b|\breal chrome\b|\blogin sessions\b|\bsession tokens?\b|--profile\b/iu;
+export const BOOTSTRAP_INSTALL_PATTERN = /\b(?:npm|pnpm|yarn|bun)\s+install\s+-g\b|\bbrew\s+install\b|\bpipx\s+install\b|\bgo\s+install\b|\b(?:npx|pnpx|uvx)\b[^\n`]{0,160}@latest\b/iu;
+export const AGENT_CONTROL_POINT_PATTERN = /\.claude\/hooks\/|\.claude\/settings\.json|\.claude\/agents\/|\bclaude\.md\b|\bagents\.md\b|\bmcp configuration\b/iu;
+export const RESTART_LOAD_PATTERN = /\brestart\b.*\b(?:load|take effect|activate|reload|work)\b|\bonly load after restart\b|\bafter restarting\b/iu;
+export const REMOTE_INSTRUCTION_INDIRECTION_PATTERN = /\b(?:follow|read|fetch|apply|obey|execute)\b[^\n]{0,40}\b(?:instructions|steps|guide|rules|directives)\b[^\n]{0,40}https?:\/\//iu;
+function hasNearbyNegation(normalizedLine, matchIndex) {
+    const prefix = normalizedLine.slice(Math.max(0, matchIndex - 24), matchIndex);
+    return NEGATION_PATTERN.test(prefix);
+}
+/**
+ * Find the first instruction-override phrase in a normalized line, skipping
+ * matches preceded by nearby negation ("never bypass permissions").
+ */
+export function findOverridePhrase(normalizedLine) {
+    for (const { phrase } of activeOverridePhrases()) {
+        const matchIndex = normalizedLine.indexOf(phrase);
+        if (matchIndex < 0 || hasNearbyNegation(normalizedLine, matchIndex)) {
+            continue;
+        }
+        return { phrase, index: matchIndex };
+    }
+    return null;
+}
+export function hasNegationBefore(normalizedLine, matchIndex) {
+    return hasNearbyNegation(normalizedLine, matchIndex);
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Single source of truth for hidden/invisible Unicode classes used across
+ * detectors. Tag characters (U+E0000-U+E007F) are the primary real-world
+ * "ASCII smuggling" vector: they encode invisible ASCII that survives
+ * copy/paste and reaches models while remaining unseen by human reviewers.
+ *
+ * All patterns use escape sequences on purpose: this file must never
+ * contain literal hidden characters.
+ */
+export declare const HIDDEN_UNICODE_CLASS: {
+    readonly ZeroWidth: "zero-width";
+    readonly Bidi: "bidi";
+    readonly Tags: "tags";
+    readonly VariationSelector: "variation-selector";
+};
+export type HiddenUnicodeClass = (typeof HIDDEN_UNICODE_CLASS)[keyof typeof HIDDEN_UNICODE_CLASS];
+export declare const ZERO_WIDTH_PATTERN: RegExp;
+export declare const BIDI_CONTROL_PATTERN: RegExp;
+export declare const TAG_CHARACTER_PATTERN: RegExp;
+export declare const VARIATION_SELECTOR_PATTERN: RegExp;
+export interface HiddenUnicodeMatch {
+    index: number;
+    codePoint: number;
+    class: HiddenUnicodeClass;
+}
+/**
+ * Find hidden Unicode characters worth flagging. Variation selectors are
+ * reported only when clustered (two or more in a row).
+ */
+export declare function findHiddenUnicode(text: string): HiddenUnicodeMatch[];
+/** Remove every hidden character class so pattern matching sees the visible text. */
+export declare function stripHiddenCharacters(text: string): string;
+export declare function hasHiddenUnicodeClass(text: string, cls: HiddenUnicodeClass): boolean;

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

@@ -0,0 +1,83 @@
+/**
+ * Single source of truth for hidden/invisible Unicode classes used across
+ * detectors. Tag characters (U+E0000-U+E007F) are the primary real-world
+ * "ASCII smuggling" vector: they encode invisible ASCII that survives
+ * copy/paste and reaches models while remaining unseen by human reviewers.
+ *
+ * All patterns use escape sequences on purpose: this file must never
+ * contain literal hidden characters.
+ */
+export const HIDDEN_UNICODE_CLASS = {
+    ZeroWidth: "zero-width",
+    Bidi: "bidi",
+    Tags: "tags",
+    VariationSelector: "variation-selector",
+};
+export const ZERO_WIDTH_PATTERN = /[\u200B-\u200D\u2060\uFEFF]/u;
+export const BIDI_CONTROL_PATTERN = /[\u202A-\u202E\u2066-\u2069]/u;
+export const TAG_CHARACTER_PATTERN = /[\u{E0000}-\u{E007F}]/u;
+export const VARIATION_SELECTOR_PATTERN = /[\uFE00-\uFE0F\u{E0100}-\u{E01EF}]/u;
+// Variation selectors are only suspicious in clusters: payload encodings use
+// runs of them, while a single selector legitimately follows an emoji.
+const CLUSTERED_VARIATION_SELECTOR_PATTERN = /[\uFE00-\uFE0F\u{E0100}-\u{E01EF}]{2,}/u;
+/* eslint-disable no-misleading-character-class -- matching the combining/invisible characters themselves is the point */
+const STRIP_FOR_MATCHING_PATTERN = /[\u200B-\u200D\u2060\uFEFF\u202A-\u202E\u2066-\u2069\uFE00-\uFE0F\u{E0000}-\u{E007F}\u{E0100}-\u{E01EF}]/gu;
+function classifyCodePoint(codePoint) {
+    if ((codePoint >= 0x200b && codePoint <= 0x200d) ||
+        codePoint === 0x2060 ||
+        codePoint === 0xfeff) {
+        return HIDDEN_UNICODE_CLASS.ZeroWidth;
+    }
+    if ((codePoint >= 0x202a && codePoint <= 0x202e) ||
+        (codePoint >= 0x2066 && codePoint <= 0x2069)) {
+        return HIDDEN_UNICODE_CLASS.Bidi;
+    }
+    if (codePoint >= 0xe0000 && codePoint <= 0xe007f) {
+        return HIDDEN_UNICODE_CLASS.Tags;
+    }
+    if ((codePoint >= 0xfe00 && codePoint <= 0xfe0f) ||
+        (codePoint >= 0xe0100 && codePoint <= 0xe01ef)) {
+        return HIDDEN_UNICODE_CLASS.VariationSelector;
+    }
+    return null;
+}
+/**
+ * Find hidden Unicode characters worth flagging. Variation selectors are
+ * reported only when clustered (two or more in a row).
+ */
+export function findHiddenUnicode(text) {
+    const matches = [];
+    const clusteredVariationRanges = [];
+    const clusterRegex = new RegExp(CLUSTERED_VARIATION_SELECTOR_PATTERN, "gu");
+    let clusterMatch = clusterRegex.exec(text);
+    while (clusterMatch) {
+        clusteredVariationRanges.push({
+            start: clusterMatch.index,
+            end: clusterMatch.index + clusterMatch[0].length,
+        });
+        clusterMatch = clusterRegex.exec(text);
+    }
+    let index = 0;
+    for (const char of text) {
+        const codePoint = char.codePointAt(0) ?? 0;
+        const classified = classifyCodePoint(codePoint);
+        if (classified === HIDDEN_UNICODE_CLASS.VariationSelector) {
+            const clustered = clusteredVariationRanges.some((range) => index >= range.start && index < range.end);
+            if (clustered) {
+                matches.push({ index, codePoint, class: classified });
+            }
+        }
+        else if (classified) {
+            matches.push({ index, codePoint, class: classified });
+        }
+        index += char.length;
+    }
+    return matches;
+}
+/** Remove every hidden character class so pattern matching sees the visible text. */
+export function stripHiddenCharacters(text) {
+    return text.replace(STRIP_FOR_MATCHING_PATTERN, "");
+}
+export function hasHiddenUnicodeClass(text, cls) {
+    return findHiddenUnicode(text).some((match) => match.class === cls);
+}

package/dist/layer3-dynamic/deep-resource-executor.d.ts

@@ -0,0 +1,21 @@
+import type { RuntimeMode } from "../config.js";
+import type { DeepScanResource } from "../pipeline.js";
+import { type RegistryClientDeps } from "./registry-client.js";
+import type { ResourceFetchResult } from "./resource-fetcher.js";
+export interface DeepResourceExecutionContext {
+    runtimeMode?: RuntimeMode;
+}
+/**
+ * Default deep-resource executor.
+ *
+ * URL resources (http/sse) are never fetched: connecting to endpoints found
+ * in scanned config files is a security risk (crafted responses, SSRF, IP
+ * logging), so the URL is recorded as metadata for the agent to analyze.
+ *
+ * npm/pypi package resources are different: their metadata comes from
+ * pinned, well-known registry hosts, not from attacker-chosen endpoints.
+ * When the runtime mode is "online" (and the per-resource consent the
+ * caller already collected), the hardened registry client fetches a typed
+ * metadata subset. Offline (the default) stays record-only.
+ */
+export declare function createDeepResourceExecutor(deps?: RegistryClientDeps): (resource: DeepScanResource, context?: DeepResourceExecutionContext) => Promise<ResourceFetchResult>;

package/dist/layer3-dynamic/deep-resource-executor.js

@@ -0,0 +1,73 @@
+import { fetchRegistryMetadata, REGISTRY_KIND, } from "./registry-client.js";
+function registryKindFor(resource) {
+    if (resource.request.kind === "npm") {
+        return REGISTRY_KIND.Npm;
+    }
+    if (resource.request.kind === "pypi") {
+        return REGISTRY_KIND.Pypi;
+    }
+    return null;
+}
+function recordOnlyResult(resource) {
+    return {
+        status: "ok",
+        attempts: 0,
+        elapsedMs: 0,
+        metadata: {
+            resource_id: resource.id,
+            resource_kind: resource.request.kind,
+            resource_url: resource.request.locator,
+            note: "URL recorded for analysis without making outbound connections.",
+        },
+    };
+}
+function classifyError(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    if (message.includes("timeout") || message.includes("abort")) {
+        return "timeout";
+    }
+    return "network_error";
+}
+/**
+ * Default deep-resource executor.
+ *
+ * URL resources (http/sse) are never fetched: connecting to endpoints found
+ * in scanned config files is a security risk (crafted responses, SSRF, IP
+ * logging), so the URL is recorded as metadata for the agent to analyze.
+ *
+ * npm/pypi package resources are different: their metadata comes from
+ * pinned, well-known registry hosts, not from attacker-chosen endpoints.
+ * When the runtime mode is "online" (and the per-resource consent the
+ * caller already collected), the hardened registry client fetches a typed
+ * metadata subset. Offline (the default) stays record-only.
+ */
+export function createDeepResourceExecutor(deps = {}) {
+    return async (resource, context) => {
+        const registryKind = registryKindFor(resource);
+        if (!registryKind || context?.runtimeMode !== "online") {
+            return recordOnlyResult(resource);
+        }
+        const startedAt = Date.now();
+        try {
+            const registry = await fetchRegistryMetadata(registryKind, resource.request.locator, deps);
+            return {
+                status: "ok",
+                attempts: 1,
+                elapsedMs: Date.now() - startedAt,
+                metadata: {
+                    resource_id: resource.id,
+                    resource_kind: resource.request.kind,
+                    registry,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                status: classifyError(error),
+                attempts: 1,
+                elapsedMs: Date.now() - startedAt,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    };
+}

package/dist/layer3-dynamic/meta-agent.js

@@ -1,12 +1,13 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { stripHiddenCharacters } from "../layer2-static/text/unicode.js";
 const templatesRoot = join(dirname(fileURLToPath(import.meta.url)), "prompt-templates");
 function readTemplate(name) {
     return readFileSync(join(templatesRoot, name), "utf8");
 }
 function normalize(value) {
-    return value.replace(/[\u200B-\u200D\u2060\uFEFF]/gu, "").trim();
+    return stripHiddenCharacters(value).trim();
 }
 export function buildSecurityAnalysisPrompt(input) {
     return readTemplate("security-analysis.md")

package/dist/layer3-dynamic/registry-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hardened metadata client for package registries. Constraints, each tested:
+ * pinned HTTPS hosts only, redirects rejected, 5s timeout, 1 MiB streamed
+ * body cap, JSON only. Returns a typed subset — never the raw registry blob.
+ */
+export declare const REGISTRY_KIND: {
+    readonly Npm: "npm";
+    readonly Pypi: "pypi";
+};
+export type RegistryKind = (typeof REGISTRY_KIND)[keyof typeof REGISTRY_KIND];
+export interface RegistryPackageMetadata {
+    kind: RegistryKind;
+    name: string;
+    latestVersion: string | null;
+    firstPublishedAt: string | null;
+    latestPublishedAt: string | null;
+    maintainerCount: number | null;
+    deprecated: string | null;
+    /** npm lifecycle scripts that run code on install (preinstall/install/postinstall). */
+    installScripts: string[];
+    repositoryUrl: string | null;
+}
+export interface RegistryClientDeps {
+    fetchImpl?: typeof fetch;
+}
+export declare function fetchRegistryMetadata(kind: RegistryKind, name: string, deps?: RegistryClientDeps): Promise<RegistryPackageMetadata>;

package/dist/layer3-dynamic/registry-client.js

@@ -0,0 +1,138 @@
+/**
+ * Hardened metadata client for package registries. Constraints, each tested:
+ * pinned HTTPS hosts only, redirects rejected, 5s timeout, 1 MiB streamed
+ * body cap, JSON only. Returns a typed subset — never the raw registry blob.
+ */
+export const REGISTRY_KIND = {
+    Npm: "npm",
+    Pypi: "pypi",
+};
+const ALLOWED_HOSTS = {
+    npm: "registry.npmjs.org",
+    pypi: "pypi.org",
+};
+const TIMEOUT_MS = 5000;
+const MAX_BODY_BYTES = 1024 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function endpointFor(kind, name) {
+    if (kind === REGISTRY_KIND.Npm) {
+        const encoded = name.startsWith("@") ? name.replace(/\//gu, "%2f") : name;
+        return `https://${ALLOWED_HOSTS.npm}/${encoded}`;
+    }
+    return `https://${ALLOWED_HOSTS.pypi}/pypi/${name}/json`;
+}
+function assertAllowedEndpoint(kind, endpoint) {
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:") {
+        throw new Error(`Registry endpoint must use https: ${endpoint}`);
+    }
+    if (url.hostname !== ALLOWED_HOSTS[kind]) {
+        throw new Error(`Registry host not allowlisted: ${url.hostname}`);
+    }
+}
+async function readBodyCapped(response) {
+    const contentLength = response.headers.get("content-length");
+    if (contentLength && Number.parseInt(contentLength, 10) > MAX_BODY_BYTES) {
+        throw new Error(`Registry response exceeds ${MAX_BODY_BYTES} bytes`);
+    }
+    const body = response.body;
+    if (!body) {
+        const text = await response.text();
+        if (text.length > MAX_BODY_BYTES) {
+            throw new Error(`Registry response exceeds ${MAX_BODY_BYTES} bytes`);
+        }
+        return text;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        total += value.byteLength;
+        if (total > MAX_BODY_BYTES) {
+            await reader.cancel();
+            throw new Error(`Registry response exceeds ${MAX_BODY_BYTES} bytes`);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function fetchRegistryJson(kind, name, deps) {
+    const endpoint = endpointFor(kind, name);
+    assertAllowedEndpoint(kind, endpoint);
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(endpoint, {
+        redirect: "error",
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+        headers: { accept: "application/json" },
+    });
+    if (!response.ok) {
+        throw new Error(`Registry responded with HTTP ${response.status} for ${name}`);
+    }
+    const raw = await readBodyCapped(response);
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error(`Registry returned a non-object document for ${name}`);
+    }
+    return parsed;
+}
+const NPM_INSTALL_SCRIPT_KEYS = ["preinstall", "install", "postinstall"];
+function parseNpmMetadata(name, doc) {
+    const distTags = isRecord(doc["dist-tags"]) ? doc["dist-tags"] : {};
+    const latestVersion = typeof distTags.latest === "string" ? distTags.latest : null;
+    const time = isRecord(doc.time) ? doc.time : {};
+    const versions = isRecord(doc.versions) ? doc.versions : {};
+    const latestDoc = latestVersion && isRecord(versions[latestVersion]) ? versions[latestVersion] : null;
+    const scripts = latestDoc && isRecord(latestDoc.scripts) ? latestDoc.scripts : {};
+    const maintainers = Array.isArray(doc.maintainers) ? doc.maintainers : null;
+    const repository = latestDoc && isRecord(latestDoc.repository)
+        ? latestDoc.repository
+        : isRecord(doc.repository)
+            ? doc.repository
+            : null;
+    return {
+        kind: REGISTRY_KIND.Npm,
+        name,
+        latestVersion,
+        firstPublishedAt: typeof time.created === "string" ? time.created : null,
+        latestPublishedAt: latestVersion && typeof time[latestVersion] === "string"
+            ? time[latestVersion]
+            : null,
+        maintainerCount: maintainers ? maintainers.length : null,
+        deprecated: latestDoc && typeof latestDoc.deprecated === "string" ? latestDoc.deprecated : null,
+        installScripts: NPM_INSTALL_SCRIPT_KEYS.filter((key) => typeof scripts[key] === "string"),
+        repositoryUrl: repository && typeof repository.url === "string" ? repository.url : null,
+    };
+}
+function parsePypiMetadata(name, doc) {
+    const info = isRecord(doc.info) ? doc.info : {};
+    const urls = Array.isArray(doc.urls) ? doc.urls : [];
+    const firstUpload = urls.find((entry) => isRecord(entry));
+    const projectUrls = isRecord(info.project_urls) ? info.project_urls : {};
+    return {
+        kind: REGISTRY_KIND.Pypi,
+        name,
+        latestVersion: typeof info.version === "string" ? info.version : null,
+        firstPublishedAt: null,
+        latestPublishedAt: firstUpload && typeof firstUpload.upload_time_iso_8601 === "string"
+            ? firstUpload.upload_time_iso_8601
+            : null,
+        maintainerCount: null,
+        deprecated: info.yanked === true ? "yanked" : null,
+        installScripts: [],
+        repositoryUrl: typeof projectUrls.Source === "string"
+            ? projectUrls.Source
+            : typeof info.home_page === "string" && info.home_page.length > 0
+                ? info.home_page
+                : null,
+    };
+}
+export async function fetchRegistryMetadata(kind, name, deps = {}) {
+    const doc = await fetchRegistryJson(kind, name, deps);
+    return kind === REGISTRY_KIND.Npm ? parseNpmMetadata(name, doc) : parsePypiMetadata(name, doc);
+}

package/dist/layer3-dynamic/registry-findings.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from "../types/finding.js";
+export interface RegistryHeuristicsOptions {
+    recentPublishDays?: number;
+    now?: () => number;
+}
+/** Derive supply-chain findings from registry metadata fetched by the deep scan. */
+export declare function deriveRegistryFindings(resourceId: string, metadata: unknown, options?: RegistryHeuristicsOptions): Finding[];

package/dist/layer3-dynamic/registry-findings.js

@@ -0,0 +1,64 @@
+const DEFAULT_RECENT_PUBLISH_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function extractRegistryMetadata(metadata) {
+    if (!isRecord(metadata) || !isRecord(metadata.registry)) {
+        return null;
+    }
+    const registry = metadata.registry;
+    if (typeof registry.kind !== "string" || typeof registry.name !== "string") {
+        return null;
+    }
+    return registry;
+}
+function makeFinding(resourceId, registry, ruleId, severity, description) {
+    return {
+        rule_id: ruleId,
+        finding_id: `${ruleId.toUpperCase().replaceAll("-", "_")}-${resourceId}`,
+        severity,
+        category: "COMMAND_EXEC",
+        layer: "L3",
+        file_path: resourceId,
+        location: { field: `registry.${registry.name}` },
+        description,
+        affected_tools: [],
+        cve: null,
+        owasp: ["ASI05"],
+        cwe: "CWE-829",
+        confidence: "HIGH",
+        fixable: false,
+        remediation_actions: [],
+        metadata: {
+            sources: [resourceId],
+            risk_tags: ["registry", "supply-chain"],
+            origin: "registry-findings",
+        },
+        suppressed: false,
+    };
+}
+/** Derive supply-chain findings from registry metadata fetched by the deep scan. */
+export function deriveRegistryFindings(resourceId, metadata, options = {}) {
+    const registry = extractRegistryMetadata(metadata);
+    if (!registry) {
+        return [];
+    }
+    const findings = [];
+    if (registry.installScripts.length > 0) {
+        findings.push(makeFinding(resourceId, registry, "package-install-scripts", "HIGH", `Package "${registry.name}" declares npm lifecycle scripts (${registry.installScripts.join(", ")}) that execute code at install time.`));
+    }
+    if (registry.deprecated) {
+        findings.push(makeFinding(resourceId, registry, "package-deprecated", "MEDIUM", `Package "${registry.name}" is marked deprecated/yanked by its registry: ${registry.deprecated}`));
+    }
+    const recentDays = options.recentPublishDays ?? DEFAULT_RECENT_PUBLISH_DAYS;
+    if (registry.latestPublishedAt) {
+        const publishedAt = Date.parse(registry.latestPublishedAt);
+        const now = options.now ? options.now() : Date.now();
+        if (Number.isFinite(publishedAt) && now - publishedAt < recentDays * DAY_MS) {
+            findings.push(makeFinding(resourceId, registry, "package-recently-published", "MEDIUM", `Package "${registry.name}" version ${registry.latestVersion ?? "?"} was published within ` +
+                `the last ${recentDays} days. Fresh releases are the window for compromised-package attacks.`));
+        }
+    }
+    return findings;
+}