evershield 0.0.0-stage → 0.2.0

package/dist/report/sarif.js

@@ -0,0 +1,129 @@
+/**
+ * SARIF 2.1.0 output, the format GitHub code scanning and most security
+ * dashboards ingest. One run per scan; one rule entry per distinct ruleId;
+ * one result per finding with its first evidence as the primary location.
+ *
+ * File paths are relative to the scanned directory, not the repository
+ * root, because build output is usually not committed. Response evidence
+ * has no file, so it is reported as a logical location (endpoint, identity
+ * and JSON path); DOM evidence likewise (page, identity and selector).
+ */
+import { RESPONSE_RULES } from "../audit/rules.js";
+import { VERSION } from "../index.js";
+import { ARTIFACT_RULES } from "../rules/index.js";
+import { SURFACE_RULES } from "../surface/rules.js";
+import { helpUri } from "../rules/types.js";
+import { isBlocking } from "./index.js";
+function levelFor(severity) {
+    switch (severity) {
+        case "critical":
+        case "high":
+            return "error";
+        case "medium":
+            return "warning";
+        default:
+            return "note";
+    }
+}
+function locations(finding) {
+    const first = finding.evidence[0];
+    if (first === undefined)
+        return [];
+    if (first.kind === "file") {
+        const region = first.line === undefined ? {} : { region: { startLine: first.line, startColumn: first.column ?? 1 } };
+        return [{ physicalLocation: { artifactLocation: { uri: first.path }, ...region } }];
+    }
+    if (first.kind === "response") {
+        return [
+            {
+                logicalLocations: [
+                    { name: first.jsonPath, fullyQualifiedName: `${first.endpoint} as ${first.identity} → ${first.jsonPath}`, kind: "member" },
+                ],
+            },
+        ];
+    }
+    const as = first.identity === undefined ? "" : ` as ${first.identity}`;
+    return [{ logicalLocations: [{ name: first.selector, fullyQualifiedName: `${first.url}${as} → ${first.selector}`, kind: "element" }] }];
+}
+const KNOWN_RULES = new Map([
+    ...ARTIFACT_RULES.map((rule) => [rule.id, rule]),
+    ...RESPONSE_RULES.map((rule) => [rule.id, rule]),
+    ...SURFACE_RULES.map((rule) => [rule.id, rule]),
+]);
+function invocationProperties(result, gate) {
+    if (result.layer === "artifact") {
+        return { layer: result.layer, adapter: result.adapter, filesScanned: result.filesScanned, ignored: result.ignored, gate };
+    }
+    if (result.layer === "surface") {
+        return {
+            layer: result.layer,
+            identities: result.identities,
+            pagesAudited: result.pagesAudited,
+            snapshotsEvaluated: result.snapshotsEvaluated,
+            warnings: result.warnings,
+            ignored: result.ignored,
+            gate,
+        };
+    }
+    return {
+        layer: result.layer,
+        identities: result.identities,
+        endpointsAudited: result.endpointsAudited,
+        responsesEvaluated: result.responsesEvaluated,
+        warnings: result.warnings,
+        ignored: result.ignored,
+        gate,
+    };
+}
+export function renderSarif(result, gate) {
+    const ruleIds = [...new Set(result.findings.map((finding) => finding.ruleId))].sort();
+    const rules = ruleIds.map((id) => {
+        const meta = KNOWN_RULES.get(id);
+        return {
+            id,
+            name: id.split("/").pop() ?? id,
+            shortDescription: { text: id },
+            helpUri: helpUri(id),
+            defaultConfiguration: { level: meta === undefined ? "warning" : levelFor(meta.defaultSeverity) },
+            properties: meta === undefined ? {} : { defaultSeverity: meta.defaultSeverity, defaultConfidence: meta.defaultConfidence },
+        };
+    });
+    const results = result.findings.map((finding) => ({
+        ruleId: finding.ruleId,
+        ruleIndex: ruleIds.indexOf(finding.ruleId),
+        level: levelFor(finding.severity),
+        message: { text: finding.remediation === undefined ? finding.message : `${finding.message}. ${finding.remediation}` },
+        locations: locations(finding),
+        properties: {
+            severity: finding.severity,
+            confidence: finding.confidence,
+            blocking: isBlocking(finding, gate),
+        },
+    }));
+    const sarif = {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "evershield",
+                        version: VERSION,
+                        informationUri: "https://github.com/inviy/evershield",
+                        rules,
+                    },
+                },
+                invocations: [
+                    {
+                        executionSuccessful: true,
+                        startTimeUtc: result.startedAt,
+                        endTimeUtc: result.finishedAt,
+                        properties: invocationProperties(result, gate),
+                    },
+                ],
+                results,
+            },
+        ],
+    };
+    return `${JSON.stringify(sarif, null, 2)}\n`;
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "./types.ts";
+/** Layer 1 rules, in report order. */
+export declare const ARTIFACT_RULES: readonly Rule[];
+export type { Rule, RuleContext } from "./types.ts";

package/dist/rules/index.js

@@ -0,0 +1,11 @@
+import { internalEndpoint } from "./internal-endpoint.js";
+import { secretLikeString } from "./secret-like-string.js";
+import { sensitiveEnvName } from "./sensitive-env-name.js";
+import { sourceMapPublished } from "./source-map-published.js";
+/** Layer 1 rules, in report order. */
+export const ARTIFACT_RULES = [
+    secretLikeString,
+    sourceMapPublished,
+    sensitiveEnvName,
+    internalEndpoint,
+];

package/dist/rules/internal-endpoint.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const internalEndpoint: Rule;

package/dist/rules/internal-endpoint.js

@@ -0,0 +1,61 @@
+import { lineColumn } from "../scan/text.js";
+import { helpUri, MAX_FINDINGS_PER_FILE } from "./types.js";
+const PATTERNS = [
+    {
+        name: "Private IP address",
+        pattern: /\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3})\b/g,
+        severity: "medium",
+        confidence: "medium",
+        remediation: "Replace with a public hostname resolved server-side, or remove the reference.",
+    },
+    {
+        name: "Internal hostname",
+        pattern: /\bhttps?:\/\/[a-z0-9.-]+\.(?:internal|local|corp|lan|intranet)(?::\d+)?\b/gi,
+        severity: "medium",
+        confidence: "high",
+        remediation: "Internal names map your infrastructure for an attacker. Proxy the call through a public endpoint.",
+    },
+    {
+        name: "localhost URL",
+        pattern: /\bhttps?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?\b/gi,
+        severity: "low",
+        confidence: "low",
+        remediation: "Usually a development fallback that leaked into production config. Confirm it is unreachable in production.",
+    },
+    {
+        name: "Staging or admin hostname",
+        pattern: /\bhttps?:\/\/(?:[a-z0-9-]+\.)*(?:staging|stage|dev|admin|preprod|uat)\.[a-z0-9.-]+\b/gi,
+        severity: "low",
+        confidence: "low",
+        remediation: "Confirm the environment is meant to be reachable from the public bundle.",
+    },
+];
+export const internalEndpoint = {
+    id: "artifact/internal-endpoint",
+    defaultSeverity: "medium",
+    defaultConfidence: "medium",
+    check(file) {
+        const findings = [];
+        const seen = new Set();
+        for (const entry of PATTERNS) {
+            for (const match of file.text.matchAll(entry.pattern)) {
+                const value = match[0];
+                if (seen.has(value) || findings.length >= MAX_FINDINGS_PER_FILE)
+                    continue;
+                seen.add(value);
+                const { line, column } = lineColumn(file.text, match.index);
+                findings.push({
+                    ruleId: internalEndpoint.id,
+                    layer: "artifact",
+                    severity: entry.severity,
+                    confidence: entry.confidence,
+                    message: `${entry.name} in ${file.relativePath}: ${value}`,
+                    evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: value }],
+                    remediation: entry.remediation,
+                    helpUri: helpUri(internalEndpoint.id),
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/rules/secret-like-string.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const secretLikeString: Rule;

package/dist/rules/secret-like-string.js

@@ -0,0 +1,128 @@
+import { decodeJwtPayload, lineColumn, looksLikePlaceholder, redact, shannonEntropy } from "../scan/text.js";
+import { helpUri, MAX_FINDINGS_PER_FILE } from "./types.js";
+const ROTATE = "Rotate the credential now; treat it as compromised. Move its use behind a server endpoint.";
+const PROVIDERS = [
+    { name: "AWS access key ID", pattern: /\bAKIA[0-9A-Z]{16}\b/g, severity: "critical", confidence: "high", remediation: ROTATE },
+    { name: "GitHub token", pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{80,}\b/g, severity: "critical", confidence: "high", remediation: ROTATE },
+    { name: "Stripe secret key", pattern: /\b(?:sk|rk)_live_[0-9A-Za-z]{24,}\b/g, severity: "critical", confidence: "high", remediation: ROTATE },
+    { name: "Stripe test secret key", pattern: /\b(?:sk|rk)_test_[0-9A-Za-z]{24,}\b/g, severity: "medium", confidence: "high", remediation: "Test keys should not ship either; remove and keep them server-side." },
+    { name: "Slack token", pattern: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/g, severity: "critical", confidence: "high", remediation: ROTATE },
+    { name: "Anthropic API key", pattern: /\bsk-ant-[A-Za-z0-9_-]{32,}\b/g, severity: "critical", confidence: "high", remediation: ROTATE },
+    { name: "OpenAI API key", pattern: /\bsk-(?!ant-)(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{32,}\b/g, severity: "critical", confidence: "high", remediation: ROTATE },
+    { name: "Private key block", pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY(?: BLOCK)?-----/g, severity: "critical", confidence: "high", remediation: "Remove the key from the build and rotate it." },
+    {
+        name: "Google API key",
+        pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+        severity: "medium",
+        confidence: "medium",
+        remediation: "Browser keys are expected to ship; confirm this one is restricted to your origins and to the APIs it needs.",
+    },
+];
+const JWT = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g;
+const NAMED_VALUE = /\b((?:[A-Za-z_][A-Za-z0-9_]*?)?(?:secret|token|api[_-]?key|apikey|password|passwd|private[_-]?key|auth[_-]?key)[A-Za-z0-9_]*)["']?\s*[:=]\s*["']([A-Za-z0-9_\-./+=]{16,})["']/gi;
+const MIN_NAMED_ENTROPY = 3.5;
+function isPublicName(name, context) {
+    const upper = name.toUpperCase();
+    return context.adapter.publicEnvPrefixes.some((prefix) => upper.startsWith(prefix));
+}
+/**
+ * Entropy alone passes CSS custom properties (`--brand-color-hover`) and
+ * dotted paths (`spacing.large.default`): long, varied, and not secrets.
+ * Real credentials mix letters with digits or case and do not look like
+ * identifiers or paths.
+ */
+function looksLikeCredentialValue(value) {
+    if (value.startsWith("--") || value.startsWith("./") || value.startsWith("/"))
+        return false;
+    if (/^[a-z0-9]+(?:[.\-_/][a-z0-9]+)+$/i.test(value) && !/[0-9]/.test(value))
+        return false;
+    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/].filter((re) => re.test(value)).length;
+    return classes >= 2 && shannonEntropy(value) >= MIN_NAMED_ENTROPY;
+}
+export const secretLikeString = {
+    id: "artifact/secret-like-string",
+    defaultSeverity: "high",
+    defaultConfidence: "low",
+    check(file, context) {
+        const findings = [];
+        const seen = new Set();
+        const push = (finding, key) => {
+            if (seen.has(key) || findings.length >= MAX_FINDINGS_PER_FILE)
+                return;
+            seen.add(key);
+            findings.push(finding);
+        };
+        for (const provider of PROVIDERS) {
+            for (const match of file.text.matchAll(provider.pattern)) {
+                const value = match[0];
+                const { line, column } = lineColumn(file.text, match.index);
+                push({
+                    ruleId: secretLikeString.id,
+                    layer: "artifact",
+                    severity: provider.severity,
+                    confidence: provider.confidence,
+                    message: `${provider.name} shipped in ${file.relativePath}`,
+                    evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: redact(value) }],
+                    remediation: provider.remediation,
+                    helpUri: helpUri(secretLikeString.id),
+                }, `${provider.name}:${value}`);
+            }
+        }
+        for (const match of file.text.matchAll(JWT)) {
+            const token = match[0];
+            const payload = decodeJwtPayload(token);
+            if (payload === null)
+                continue;
+            const role = typeof payload.role === "string" ? payload.role : null;
+            const { line, column } = lineColumn(file.text, match.index);
+            if (role === "service_role") {
+                push({
+                    ruleId: secretLikeString.id,
+                    layer: "artifact",
+                    severity: "critical",
+                    confidence: "high",
+                    message: `Supabase service_role JWT shipped in ${file.relativePath}; it bypasses row-level security`,
+                    evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: redact(token) }],
+                    remediation: "Rotate the service role key in Supabase and use the anon key in the browser.",
+                    helpUri: helpUri(secretLikeString.id),
+                }, `jwt:${token}`);
+            }
+            else if (role === null) {
+                // Not a Supabase anon/authenticated token; unknown JWTs in a bundle
+                // deserve a look but are often harmless fixtures.
+                push({
+                    ruleId: secretLikeString.id,
+                    layer: "artifact",
+                    severity: "low",
+                    confidence: "medium",
+                    message: `JWT embedded in ${file.relativePath}`,
+                    evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: redact(token) }],
+                    remediation: "Confirm the token is not a live credential. Tokens belong in responses, not bundles.",
+                    helpUri: helpUri(secretLikeString.id),
+                }, `jwt:${token}`);
+            }
+        }
+        for (const match of file.text.matchAll(NAMED_VALUE)) {
+            const name = match[1];
+            const value = match[2];
+            if (name === undefined || value === undefined)
+                continue;
+            if (isPublicName(name, context) || looksLikePlaceholder(value))
+                continue;
+            if (!looksLikeCredentialValue(value))
+                continue;
+            const { line, column } = lineColumn(file.text, match.index);
+            push({
+                ruleId: secretLikeString.id,
+                layer: "artifact",
+                severity: "high",
+                confidence: "low",
+                message: `"${name}" is assigned a high-entropy value in ${file.relativePath}`,
+                evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: `${name} = ${redact(value)}` }],
+                remediation: "If this is a real credential, rotate it and move the call server-side. If it is public by design, rename it with your framework's public prefix.",
+                helpUri: helpUri(secretLikeString.id),
+            }, `named:${name}:${value}`);
+        }
+        return findings;
+    },
+};

package/dist/rules/sensitive-env-name.d.ts

@@ -0,0 +1,4 @@
+import { type Rule } from "./types.ts";
+/** Secrets are long and mix letters with digits or case; enum values and words are not. */
+export declare function looksLikeSecretValue(value: string): boolean;
+export declare const sensitiveEnvName: Rule;

package/dist/rules/sensitive-env-name.js

@@ -0,0 +1,76 @@
+import { lineColumn, redact } from "../scan/text.js";
+import { helpUri, MAX_FINDINGS_PER_FILE } from "./types.js";
+const KEYWORDS = [
+    "SERVICE_ROLE", "SECRET", "PRIVATE_KEY", "DATABASE_URL", "CONNECTION_STRING",
+    "SIGNING_KEY", "MASTER_KEY", "PASSWORD", "ACCESS_TOKEN", "REFRESH_TOKEN",
+];
+/** Keywords strong enough that even a bare mention deserves a look. */
+const BARE_NAME_KEYWORDS = new Set([
+    "SERVICE_ROLE", "SECRET", "PRIVATE_KEY", "DATABASE_URL", "CONNECTION_STRING", "SIGNING_KEY", "MASTER_KEY",
+]);
+const SENSITIVE_NAME = new RegExp(`\\b((?:[A-Z][A-Z0-9]*_)*(${KEYWORDS.join("|")})(?:_[A-Z0-9]+)*)\\b(?:["']?\\s*[:=]\\s*["']([^"'\\s]{8,})["'])?`, "g");
+function isPublicName(name, context) {
+    return context.adapter.publicEnvPrefixes.some((prefix) => name.startsWith(prefix));
+}
+/** Secrets are long and mix letters with digits or case; enum values and words are not. */
+export function looksLikeSecretValue(value) {
+    if (value.length < 12)
+        return false;
+    if (/^[A-Z0-9_]+$/.test(value))
+        return false;
+    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/].filter((re) => re.test(value)).length;
+    return classes >= 2;
+}
+export const sensitiveEnvName = {
+    id: "artifact/sensitive-env-name",
+    defaultSeverity: "low",
+    defaultConfidence: "low",
+    check(file, context) {
+        const findings = [];
+        const seen = new Set();
+        for (const match of file.text.matchAll(SENSITIVE_NAME)) {
+            const name = match[1];
+            const keyword = match[2];
+            const value = match[3];
+            if (name === undefined || keyword === undefined || isPublicName(name, context))
+                continue;
+            if (findings.length >= MAX_FINDINGS_PER_FILE)
+                break;
+            const { line, column } = lineColumn(file.text, match.index);
+            if (value !== undefined && looksLikeSecretValue(value)) {
+                const key = `${name}:${value}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                findings.push({
+                    ruleId: sensitiveEnvName.id,
+                    layer: "artifact",
+                    severity: "high",
+                    confidence: "medium",
+                    message: `${name} is assigned a literal value in ${file.relativePath}`,
+                    evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: `${name} = ${redact(value)}` }],
+                    remediation: "Server-only configuration must not be bundled. Read it on the server and expose only what the client needs.",
+                    helpUri: helpUri(sensitiveEnvName.id),
+                });
+                continue;
+            }
+            if (!BARE_NAME_KEYWORDS.has(keyword))
+                continue;
+            const key = `${name}:`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            findings.push({
+                ruleId: sensitiveEnvName.id,
+                layer: "artifact",
+                severity: "low",
+                confidence: "low",
+                message: `Server-only variable name ${name} appears in ${file.relativePath}`,
+                evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: name }],
+                remediation: "Check why client code references this name. If it is read at runtime, the value may be inlined elsewhere.",
+                helpUri: helpUri(sensitiveEnvName.id),
+            });
+        }
+        return findings;
+    },
+};

package/dist/rules/source-map-published.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const sourceMapPublished: Rule;

package/dist/rules/source-map-published.js

@@ -0,0 +1,39 @@
+import { lineColumn } from "../scan/text.js";
+import { helpUri } from "./types.js";
+const INLINE_MAP = /\/\/[#@]\s*sourceMappingURL=data:application\/json[^\n]*/g;
+export const sourceMapPublished = {
+    id: "artifact/source-map-published",
+    defaultSeverity: "high",
+    defaultConfidence: "high",
+    check(file) {
+        const findings = [];
+        if (file.relativePath.endsWith(".map")) {
+            findings.push({
+                ruleId: sourceMapPublished.id,
+                layer: "artifact",
+                severity: "high",
+                confidence: "high",
+                message: `Source map shipped: ${file.relativePath}`,
+                evidence: [{ kind: "file", path: file.relativePath }],
+                remediation: "Disable production browser source maps, or upload them to your error tracker and delete them from the deploy.",
+                helpUri: helpUri(sourceMapPublished.id),
+            });
+            return findings;
+        }
+        for (const match of file.text.matchAll(INLINE_MAP)) {
+            const { line, column } = lineColumn(file.text, match.index);
+            findings.push({
+                ruleId: sourceMapPublished.id,
+                layer: "artifact",
+                severity: "high",
+                confidence: "high",
+                message: `Inline source map embedded in ${file.relativePath}`,
+                // Only the scheme prefix travels; the base64 payload is the whole source.
+                evidence: [{ kind: "file", path: file.relativePath, line, column, excerpt: `${match[0].slice(0, 44)}…` }],
+                remediation: "Build with source maps off, or emit them as separate files that are not deployed.",
+                helpUri: helpUri(sourceMapPublished.id),
+            });
+        }
+        return findings;
+    },
+};

package/dist/rules/types.d.ts

@@ -0,0 +1,23 @@
+import type { Confidence, Finding, Severity } from "../index.ts";
+import type { Adapter } from "../scan/adapters.ts";
+import type { ScannedFile } from "../scan/files.ts";
+export interface RuleContext {
+    adapter: Adapter;
+    /** Every shipped file's relative path, for cross-file checks such as source map references. */
+    shippedPaths: ReadonlySet<string>;
+}
+/**
+ * A rule inspects one file and returns findings with evidence. The doc
+ * comment on each rule module must state why its default severity and
+ * confidence are what they are (see CONTRIBUTING.md).
+ */
+export interface Rule {
+    id: string;
+    defaultSeverity: Severity;
+    defaultConfidence: Confidence;
+    check(file: ScannedFile, context: RuleContext): Finding[];
+}
+export declare const RULES_DOC = "https://github.com/inviy/evershield/blob/main/docs/rules.md";
+/** Rules cap findings per file so one generated bundle cannot flood a report. */
+export declare const MAX_FINDINGS_PER_FILE = 25;
+export declare function helpUri(ruleId: string): string;

package/dist/rules/types.js

@@ -0,0 +1,6 @@
+export const RULES_DOC = "https://github.com/inviy/evershield/blob/main/docs/rules.md";
+/** Rules cap findings per file so one generated bundle cannot flood a report. */
+export const MAX_FINDINGS_PER_FILE = 25;
+export function helpUri(ruleId) {
+    return `${RULES_DOC}#${ruleId.replace("/", "")}`;
+}

package/dist/scan/adapters.d.ts

@@ -0,0 +1,24 @@
+/**
+ * An adapter knows which files in a build directory the browser actually
+ * receives, and which environment variable prefixes the framework treats as
+ * public by design. Every rule must still work with the plain adapter.
+ */
+export interface Adapter {
+    name: "nextjs" | "plain";
+    /** Whether a root-relative POSIX path is shipped to the browser. */
+    includes(relativePath: string): boolean;
+    /** Env var prefixes that are public by framework contract (never a finding by name). */
+    publicEnvPrefixes: readonly string[];
+}
+/** Any directory of built files: everything text-like is assumed shipped. */
+export declare const plainAdapter: Adapter;
+/**
+ * Next.js `.next/` output. Only `static/` reaches the browser as-is;
+ * `server/` holds server bundles that never leave the host, except the
+ * prerendered documents (`.html`, `.rsc`, `.body`) that are served verbatim.
+ * `cache/`, traces and manifests are build-time only.
+ */
+export declare const nextjsAdapter: Adapter;
+/** Pick the adapter from the directory's shape. */
+export declare function detectAdapter(root: string): Promise<Adapter>;
+export declare const ADAPTERS: Record<Adapter["name"], Adapter>;

package/dist/scan/adapters.js

@@ -0,0 +1,65 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+const COMMON_PUBLIC_PREFIXES = [
+    "NEXT_PUBLIC_",
+    "VITE_",
+    "PUBLIC_",
+    "REACT_APP_",
+    "NUXT_PUBLIC_",
+    "EXPO_PUBLIC_",
+    "GATSBY_",
+    "VUE_APP_",
+];
+const TEXT_EXTENSIONS = new Set([
+    ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx",
+    ".map", ".html", ".htm", ".css", ".json", ".txt", ".xml", ".svg",
+    ".rsc", ".body", ".webmanifest",
+]);
+function hasTextExtension(relativePath) {
+    return TEXT_EXTENSIONS.has(path.posix.extname(relativePath).toLowerCase());
+}
+/** Any directory of built files: everything text-like is assumed shipped. */
+export const plainAdapter = {
+    name: "plain",
+    includes: hasTextExtension,
+    publicEnvPrefixes: COMMON_PUBLIC_PREFIXES,
+};
+/**
+ * Next.js `.next/` output. Only `static/` reaches the browser as-is;
+ * `server/` holds server bundles that never leave the host, except the
+ * prerendered documents (`.html`, `.rsc`, `.body`) that are served verbatim.
+ * `cache/`, traces and manifests are build-time only.
+ */
+export const nextjsAdapter = {
+    name: "nextjs",
+    includes(relativePath) {
+        if (!hasTextExtension(relativePath))
+            return false;
+        if (relativePath.startsWith("static/"))
+            return true;
+        if (relativePath.startsWith("server/")) {
+            const ext = path.posix.extname(relativePath).toLowerCase();
+            return ext === ".html" || ext === ".rsc" || ext === ".body";
+        }
+        return false;
+    },
+    publicEnvPrefixes: COMMON_PUBLIC_PREFIXES,
+};
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Pick the adapter from the directory's shape. */
+export async function detectAdapter(root) {
+    const isNext = (await exists(path.join(root, "BUILD_ID"))) && (await exists(path.join(root, "static")));
+    return isNext ? nextjsAdapter : plainAdapter;
+}
+export const ADAPTERS = {
+    nextjs: nextjsAdapter,
+    plain: plainAdapter,
+};

package/dist/scan/artifact.d.ts

@@ -0,0 +1,18 @@
+import { type Finding, type ScanSummary } from "../index.ts";
+import { type Adapter } from "./adapters.ts";
+export interface ArtifactScanOptions {
+    /** Force an adapter instead of detecting one from the directory. */
+    adapter?: Adapter["name"];
+}
+export interface ArtifactScanResult extends ScanSummary {
+    layer: "artifact";
+    target: string;
+    adapter: Adapter["name"];
+    filesScanned: number;
+    /** Findings removed by config ignore rules; they are not in `findings`. */
+    ignored: number;
+}
+/** Worst first, then surest first, then by location so output is stable. */
+export declare function sortFindings(findings: Finding[]): Finding[];
+/** Layer 1: scan a directory of built files for what should not ship. */
+export declare function scanArtifact(target: string, options?: ArtifactScanOptions): Promise<ArtifactScanResult>;