@rivi-software/workers-bundle-check 0.0.0-stage → 0.1.0

package/dist/secrets.d.ts

@@ -0,0 +1,48 @@
+import { type ModulePattern } from "./modules.js";
+/** The shape of a kind of secret, by the name reports give it. */
+export type SecretPattern = {
+    name: string;
+    pattern: RegExp;
+};
+/**
+ * The key formats the check looks for. Each has a prefix or a structure of its own, so text that
+ * merely looks random does not match. Public keys that apps ship to browsers on purpose, such as
+ * Stripe's `pk_` keys and Google's `AIza` API keys, are not in the list.
+ */
+export declare const SECRET_PATTERNS: readonly SecretPattern[];
+/**
+ * A finding known to be safe, such as a library's example key. It names the finding's
+ * fingerprint, the module the value came from, or both, and must match a finding: an entry that
+ * matches none is reported, so the list stays current.
+ */
+export type AllowedSecret = {
+    /** The fingerprint the report gives the finding. */
+    fingerprint?: string;
+    /** The module the value comes from, as the file's source map says: see {@link ModulePattern}. */
+    module?: ModulePattern;
+    /** Why it is safe, for whoever reads the configuration next. */
+    reason: string;
+};
+/** A value shaped like a secret in a built file. */
+export type SecretFinding = {
+    /** The pattern's name. */
+    name: string;
+    /** The first 16 hexadecimal digits of the value's SHA-256. The value itself is never reported. */
+    fingerprint: string;
+    /** The line it is on, from 1. */
+    line: number;
+    /** Its column on the line, from 0. */
+    column: number;
+};
+/** Every value in `text` that one of the patterns matches. */
+export declare function findSecrets(text: string, patterns: readonly SecretPattern[]): SecretFinding[];
+/** The fingerprint a finding of `value` gets. */
+export declare function fingerprint(value: string): string;
+/** Whether an allowed entry covers a finding, given the module the finding comes from. */
+export declare function allows(allowed: AllowedSecret, finding: SecretFinding, module?: string): boolean;
+/** Throws when an entry names neither a fingerprint nor a module, or has no reason. */
+export declare function validateAllowedSecrets(allowed: readonly AllowedSecret[]): void;
+/** Throws when a secret pattern has no name, or matches the empty string. */
+export declare function validateSecretPatterns(patterns: readonly SecretPattern[]): void;
+/** An allowed entry as reports name it. */
+export declare function describeAllowed(entry: AllowedSecret): string;

package/dist/secrets.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { describePattern, moduleMatcher } from "./modules.js";
+/**
+ * The key formats the check looks for. Each has a prefix or a structure of its own, so text that
+ * merely looks random does not match. Public keys that apps ship to browsers on purpose, such as
+ * Stripe's `pk_` keys and Google's `AIza` API keys, are not in the list.
+ */
+export const SECRET_PATTERNS = [
+    {
+        name: "private key",
+        pattern: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----(?:\\+[nr]|\s)+[A-Za-z0-9+/=]{40,}/,
+    },
+    // AWS's documentation and SDKs use IDs that end in EXAMPLE.
+    { name: "AWS access key ID", pattern: /\b(?:AKIA|ASIA)(?![A-Z2-7]{9}EXAMPLE)[A-Z2-7]{16}\b/ },
+    { name: "GitHub token", pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{36}|github_pat_\w{82})\b/ },
+    { name: "GitLab token", pattern: /\bglpat-[\w-]{20,}/ },
+    { name: "npm token", pattern: /\bnpm_[A-Za-z0-9]{36}\b/ },
+    { name: "Slack token", pattern: /\bxox[abeprs]-\d+-[A-Za-z0-9-]{10,}/ },
+    {
+        name: "Slack webhook URL",
+        pattern: /\bhooks\.slack\.com\/(?:services|workflows|triggers)\/[\w+/-]{30,}/,
+    },
+    { name: "Stripe secret key", pattern: /\b[rs]k_(?:live|test)_[A-Za-z0-9]{20,}/ },
+    { name: "webhook signing secret", pattern: /\bwhsec_[A-Za-z0-9+/=]{24,}/ },
+    { name: "OpenAI API key", pattern: /\bsk-[\w-]{20,}T3BlbkFJ[\w-]{20,}/ },
+    { name: "Anthropic API key", pattern: /\bsk-ant-(?:api|admin)\d\d-[\w-]{80,}/ },
+    { name: "PostHog personal API key", pattern: /\bphx_[A-Za-z0-9]{20,}/ },
+    { name: "PostHog project secret key", pattern: /\bphs_[A-Za-z0-9]{20,}/ },
+    { name: "Supabase secret key", pattern: /\bsb_secret_[\w-]{20,}/ },
+    { name: "SendGrid API key", pattern: /\bSG\.[\w-]{22}\.[\w-]{43}\b/ },
+    { name: "Shopify access token", pattern: /\bshp(?:at|ca|pa|ss)_[a-fA-F0-9]{32}\b/ },
+    { name: "Linear API key", pattern: /\blin_api_[A-Za-z0-9]{40}\b/ },
+    { name: "Hugging Face token", pattern: /\bhf_[A-Za-z0-9]{34,}\b/ },
+];
+/** Every value in `text` that one of the patterns matches. */
+export function findSecrets(text, patterns) {
+    const findings = [];
+    let lines;
+    for (const { name, pattern } of patterns) {
+        const global = new RegExp(pattern.source, `${pattern.flags.replace(/[gy]/g, "")}g`);
+        for (const match of text.matchAll(global)) {
+            if (!match[0])
+                continue;
+            lines ??= lineStarts(text);
+            const line = lineOf(lines, match.index);
+            findings.push({
+                name,
+                fingerprint: fingerprint(match[0]),
+                line: line + 1,
+                column: match.index - lines[line],
+            });
+        }
+    }
+    return findings.sort((a, b) => a.line - b.line || a.column - b.column);
+}
+/** The fingerprint a finding of `value` gets. */
+export function fingerprint(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+/** Whether an allowed entry covers a finding, given the module the finding comes from. */
+export function allows(allowed, finding, module) {
+    return ((allowed.fingerprint === undefined || allowed.fingerprint === finding.fingerprint) &&
+        (allowed.module === undefined ||
+            (module !== undefined && moduleMatcher(allowed.module)(module))));
+}
+/** Throws when an entry names neither a fingerprint nor a module, or has no reason. */
+export function validateAllowedSecrets(allowed) {
+    for (const entry of allowed) {
+        if (entry.fingerprint === undefined && entry.module === undefined)
+            throw new TypeError(`An allowed secret names neither a fingerprint nor a module (${entry.reason}).`);
+        if (!entry.reason?.trim())
+            throw new TypeError(`An allowed secret has no reason: ${describeAllowed(entry)}.`);
+    }
+}
+/** Throws when a secret pattern has no name, or matches the empty string. */
+export function validateSecretPatterns(patterns) {
+    for (const { name, pattern } of patterns) {
+        if (!name?.trim() || !(pattern instanceof RegExp))
+            throw new TypeError(`A secret pattern needs a name and a regular expression: ${name}.`);
+        if (new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, "")).test(""))
+            throw new TypeError(`The secret pattern ${name} matches an empty string.`);
+    }
+}
+/** An allowed entry as reports name it. */
+export function describeAllowed(entry) {
+    return [
+        entry.fingerprint === undefined ? undefined : `fingerprint ${entry.fingerprint}`,
+        entry.module === undefined ? undefined : `module ${describePattern(entry.module)}`,
+    ]
+        .filter(Boolean)
+        .join(" and ");
+}
+function lineStarts(text) {
+    const starts = [0];
+    for (let index = text.indexOf("\n"); index >= 0; index = text.indexOf("\n", index + 1))
+        starts.push(index + 1);
+    return starts;
+}
+/** The 0-based line that holds `index`. */
+function lineOf(starts, index) {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (starts[middle] <= index)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return low;
+}

package/dist/source-map.d.ts

@@ -0,0 +1,52 @@
+/** A version 3 source map, with the fields the check reads. */
+export type SourceMap = {
+    sources: (string | null)[];
+    mappings: string;
+    sourceRoot?: string;
+    /** An index map's parts. The check reads only plain maps. */
+    sections?: unknown;
+};
+/** A source map with the module path of each of its sources. */
+export type ResolvedSourceMap = {
+    /** The map file, or the built file itself when the map is inline. */
+    file: string;
+    map: SourceMap;
+    /** Each source's module path, by its index in `map.sources`: see {@link modulePath}. */
+    modules: string[];
+};
+/** A generated position's segment: its column and its source's index, or -1 when it has none. */
+export type Segment = [column: number, source: number];
+/** The segments of each generated line: its column and source index (Base64 VLQ, source map v3). */
+export declare function decodeMappings(mappings: string): Segment[][];
+/**
+ * The bytes of generated code each source renders, by source index. A source whose only code is
+ * the residue of a dropped module is left out.
+ */
+export declare function renderedSources(code: string, mappings: Segment[][]): Map<number, number>;
+/** The source index of the code at a generated line (0-based) and column, or -1. */
+export declare function sourceAt(mappings: Segment[][], line: number, column: number): number;
+/**
+ * The source map of a built file: the one its `sourceMappingURL` names, inline or in a file, or
+ * else `<file>.map` beside it, which is where a `hidden` map is. Undefined when it has none.
+ */
+export declare function readSourceMap(file: string, code: string, cwd: string): Promise<ResolvedSourceMap | undefined>;
+/**
+ * The module a source map's source names, as a path relative to `cwd` with `/` between segments,
+ * symlinks resolved: `src/server.ts`, `node_modules/.pnpm/msw@2.7.0/node_modules/msw/lib/core/index.mjs`,
+ * or `../../node_modules/…` for a module outside `cwd`. A source that names no file, such as a
+ * bundler's virtual module, is kept as it is.
+ *
+ * The source is resolved from the map's directory and `sourceRoot`, as the specification says.
+ * Wrangler writes a `sourceRoot` that its own sources do not use, so when no file is there, the
+ * source is looked for without it.
+ */
+export declare function modulePath(source: string, mapFile: string, sourceRoot: string | undefined, cwd: string): string;
+/** The real path of a file, or undefined when it does not exist. */
+export declare function realPath(file: string): string | undefined;
+/**
+ * A path as reports show it: relative to `cwd`, which is a real path, with `/` between segments.
+ * A file that exists is named by its real path.
+ */
+export declare function display(file: string, cwd: string): string;
+/** `file` relative to `dir`, with `/` between segments. */
+export declare function posixRelative(dir: string, file: string): string;

package/dist/source-map.js

@@ -0,0 +1,169 @@
+import { existsSync, realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const DIGIT = new Map([...BASE64].map((char, index) => [char, index]));
+/** The segments of each generated line: its column and source index (Base64 VLQ, source map v3). */
+export function decodeMappings(mappings) {
+    const lines = [];
+    let source = 0;
+    for (const line of mappings.split(";")) {
+        const segments = [];
+        let column = 0;
+        for (const segment of line.split(",")) {
+            if (!segment)
+                continue;
+            const fields = [];
+            let value = 0;
+            let shift = 0;
+            for (const char of segment) {
+                const digit = DIGIT.get(char);
+                if (digit === undefined)
+                    throw new Error(`The source map's mappings hold "${char}".`);
+                value += (digit & 31) * 2 ** shift;
+                if (digit & 32)
+                    shift += 5;
+                else {
+                    fields.push(value % 2 ? -Math.floor(value / 2) : value / 2);
+                    value = 0;
+                    shift = 0;
+                }
+            }
+            column += fields[0] ?? 0;
+            if (fields.length >= 4) {
+                source += fields[1];
+                segments.push([column, source]);
+            }
+            else
+                segments.push([column, -1]);
+        }
+        lines.push(segments);
+    }
+    return lines;
+}
+/**
+ * What Rolldown and esbuild leave of a module whose code was dropped: the call to its lazy
+ * initializer, `init_x(` and the `)` that closes it, kept where its importer was.
+ */
+const INIT_RESIDUE = /^(?:[\w$]+\(|\)[\s,;)}\]]*)$/;
+/**
+ * The bytes of generated code each source renders, by source index. A source whose only code is
+ * the residue of a dropped module is left out.
+ */
+export function renderedSources(code, mappings) {
+    const sizes = new Map();
+    const lines = code.split("\n");
+    mappings.forEach((segments, line) => {
+        const text = lines[line] ?? "";
+        segments.forEach(([column, source], position) => {
+            if (source < 0)
+                return;
+            const end = segments[position + 1]?.[0] ?? text.length;
+            const rendered = text.slice(column, end).trim();
+            if (!rendered || INIT_RESIDUE.test(rendered))
+                return;
+            sizes.set(source, (sizes.get(source) ?? 0) + rendered.length);
+        });
+    });
+    return sizes;
+}
+/** The source index of the code at a generated line (0-based) and column, or -1. */
+export function sourceAt(mappings, line, column) {
+    let found = -1;
+    for (const [start, source] of mappings[line] ?? []) {
+        if (start > column)
+            break;
+        found = source;
+    }
+    return found;
+}
+/** The `sourceMappingURL` comment at the end of a built file. */
+const SOURCE_MAPPING_URL = /\/[/*][#@] sourceMappingURL=([^\s'"*]+)[\s*/]*$/;
+/**
+ * The source map of a built file: the one its `sourceMappingURL` names, inline or in a file, or
+ * else `<file>.map` beside it, which is where a `hidden` map is. Undefined when it has none.
+ */
+export async function readSourceMap(file, code, cwd) {
+    // From the last comment, not the file's last few kB: an inline map can be megabytes long.
+    const at = code.lastIndexOf("sourceMappingURL=");
+    const url = at < 4 ? undefined : SOURCE_MAPPING_URL.exec(code.slice(at - 4))?.[1];
+    let found;
+    if (url?.startsWith("data:")) {
+        const comma = url.indexOf(",");
+        const data = url.slice(comma + 1);
+        found = {
+            file,
+            text: /;base64$/.test(url.slice(0, comma))
+                ? Buffer.from(data, "base64").toString("utf8")
+                : decodeURIComponent(data),
+        };
+    }
+    else {
+        const candidates = [`${file}.map`];
+        if (url && !/^[a-z][a-z\d+.-]*:/i.test(url))
+            candidates.unshift(path.resolve(path.dirname(file), decodeURIComponent(url)));
+        const mapFile = candidates.find((candidate) => existsSync(candidate));
+        if (mapFile)
+            found = { file: mapFile, text: await readFile(mapFile, "utf8") };
+    }
+    if (!found)
+        return undefined;
+    let map;
+    try {
+        map = JSON.parse(found.text);
+    }
+    catch {
+        throw new Error(`${display(found.file, cwd)} is not a source map: it is not JSON.`);
+    }
+    if (map.sections)
+        throw new Error(`${display(found.file, cwd)} is an index map (sections), which the check does not read.`);
+    if (!Array.isArray(map.sources) || typeof map.mappings !== "string")
+        throw new Error(`${display(found.file, cwd)} is not a source map: it lacks sources or mappings.`);
+    return {
+        file: found.file,
+        map,
+        modules: map.sources.map((source) => modulePath(source ?? "", found.file, map.sourceRoot, cwd)),
+    };
+}
+/**
+ * The module a source map's source names, as a path relative to `cwd` with `/` between segments,
+ * symlinks resolved: `src/server.ts`, `node_modules/.pnpm/msw@2.7.0/node_modules/msw/lib/core/index.mjs`,
+ * or `../../node_modules/…` for a module outside `cwd`. A source that names no file, such as a
+ * bundler's virtual module, is kept as it is.
+ *
+ * The source is resolved from the map's directory and `sourceRoot`, as the specification says.
+ * Wrangler writes a `sourceRoot` that its own sources do not use, so when no file is there, the
+ * source is looked for without it.
+ */
+export function modulePath(source, mapFile, sourceRoot, cwd) {
+    if (source.startsWith("file:"))
+        return display(fileURLToPath(source), cwd);
+    if (!source || /^[a-z][a-z\d+.-]*:/i.test(source) || source.startsWith("\0"))
+        return source.replace(/^\0/, "");
+    const base = path.dirname(mapFile);
+    const candidates = [path.resolve(base, sourceRoot ?? "", source)];
+    if (sourceRoot)
+        candidates.push(path.resolve(base, source));
+    return display(candidates.find((candidate) => existsSync(candidate)) ?? candidates[0], cwd);
+}
+/** The real path of a file, or undefined when it does not exist. */
+export function realPath(file) {
+    try {
+        return realpathSync(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A path as reports show it: relative to `cwd`, which is a real path, with `/` between segments.
+ * A file that exists is named by its real path.
+ */
+export function display(file, cwd) {
+    return posixRelative(cwd, realPath(file) ?? file);
+}
+/** `file` relative to `dir`, with `/` between segments. */
+export function posixRelative(dir, file) {
+    return (path.relative(dir, file) || ".").split(path.sep).join("/");
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@rivi-software/workers-bundle-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Fails CI on what a Cloudflare Worker's build should not contain: a forbidden module or marker in the Worker, a source map its static assets would serve, or a value shaped like a secret",
+  "keywords": [
+    "cloudflare",
+    "cloudflare-workers",
+    "wrangler",
+    "bundle",
+    "source-map",
+    "assetsignore",
+    "secrets",
+    "ci"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "workers-bundle-check": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "ignore": "^5.3.2",
+    "minimatch": "^10.2.5"
+  },
+  "devDependencies": {
+    "vite": "8.3.5",
+    "wrangler": "4.156.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rivi-software/tools.git",
+    "directory": "packages/workers-bundle-check"
+  },
+  "homepage": "https://github.com/rivi-software/tools/tree/main/packages/workers-bundle-check#readme",
+  "bugs": "https://github.com/rivi-software/tools/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }