@coo-quack/sensitive-canary 0.7.0 → 0.8.0

package/dist/lib/fail-closed.js

@@ -0,0 +1,31 @@
+// What both hooks do when the check itself goes wrong.
+//
+// A hook that crashes exits 1, and only exit 2 blocks, so an unforeseen error
+// is a silent pass — the failure this whole tool exists to prevent. What went
+// wrong is unknown at this point, and "unknown" is not "safe": the check did
+// not finish, so the call is stopped rather than let through. `[allow-all]`
+// gets past it, and the message says the check failed rather than claiming a
+// finding.
+//
+// One copy, because two would be two rules: the wording, the exit code and
+// which events are handled all have to be the same in both hooks, and a fix
+// applied to one of two copies is a hook that fails open on the other.
+export function failClosed(error) {
+    try {
+        process.stderr.write(`\n🐤 sensitive-canary: the check could not complete — ${error instanceof Error ? error.message : String(error)}\n\n` +
+            "  Nothing was scanned, so nothing can be vouched for. Stopping rather\n" +
+            "  than passing it through. Add [allow-all] to your prompt to proceed\n" +
+            "  anyway, and please report this.\n");
+    }
+    catch {
+        // A closed stderr must not turn the block back into a pass.
+    }
+    process.exit(2);
+}
+// Registered by both hooks as their first statement. A rejection that nothing
+// awaited reaches the process the same way an exception does, and either one
+// arriving unhandled is the pass this exists to stop.
+export function blockOnUnhandledError() {
+    process.on("uncaughtException", failClosed);
+    process.on("unhandledRejection", failClosed);
+}

package/dist/lib/rules.js

@@ -0,0 +1,399 @@
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import vm from "node:vm";
+import { entropy, isNotSecretShaped, isPlaceholder, keyDescribesRatherThanHolds, } from "./shapes.js";
+import { getValidator } from "./validators.js";
+const ALL_CATEGORIES = new Set(["secret", "pii"]);
+// Parse the SENSITIVE_CANARY_CATEGORIES env var: a comma-separated list of
+// "secret", "pii", or "all" (e.g. "secret" or "secret,pii"). Unset, empty, or
+// containing no valid token means all categories are enabled.
+export function parseCategories(value) {
+    const categories = new Set();
+    for (const token of (value ?? "").split(",")) {
+        const normalized = token.trim().toLowerCase();
+        if (normalized === "all")
+            return new Set(ALL_CATEGORIES);
+        if (normalized === "secret" || normalized === "pii")
+            categories.add(normalized);
+    }
+    return categories.size > 0 ? categories : new Set(ALL_CATEGORIES);
+}
+// Rule categories enabled for this process, from SENSITIVE_CANARY_CATEGORIES
+// ("secret", "pii", "secret,pii", or "all"; default: all).
+export function enabledCategoriesFromEnv() {
+    const { SENSITIVE_CANARY_CATEGORIES } = process.env;
+    return parseCategories(SENSITIVE_CANARY_CATEGORIES);
+}
+// ── Context enhancement ──────────────────────────────────────────────────────
+// Set from the default config during module initialisation (see buildRules).
+let effectiveContextWindow = 3;
+export function getDefaultContextWindow() {
+    return effectiveContextWindow;
+}
+// Words as they were written, with only the punctuation around them removed.
+// Splitting on punctuation made `extract-zip` supply "zip" and
+// `golang.org/x/mobile` supply "mobile", so a version number beside either read
+// as a postal code or a telephone number — which is to say lockfiles and
+// `go.sum` could not be read.
+function contextTokens(text) {
+    const out = new Set();
+    for (const raw of text.split(/\s+/)) {
+        const word = raw
+            .replace(/^[\p{P}\p{S}]+/gu, "")
+            .replace(/[\p{P}\p{S}]+$/gu, "")
+            .toLowerCase();
+        if (word)
+            out.add(word);
+    }
+    return out;
+}
+function hasNearbyContextWord(text, matchStart, matchEnd, contextWords, windowTokens) {
+    if (contextWords.length === 0)
+        return true;
+    const charWindow = windowTokens * 8;
+    const before = text.slice(Math.max(0, matchStart - charWindow), matchStart);
+    const after = text.slice(matchEnd, matchEnd + charWindow);
+    const window = `${before} ${after}`;
+    const nearby = contextTokens(window);
+    const lowered = window.toLowerCase();
+    return contextWords.some((raw) => {
+        const word = raw.toLowerCase();
+        // A label in a language that does not put spaces around its words is
+        // written against the number, so it is looked for as written.
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: the ASCII range is the test
+        if (!/^[\x00-\x7f]+$/.test(word))
+            return lowered.includes(word);
+        return nearby.has(word);
+    });
+}
+// ── Config loading ───────────────────────────────────────────────────────────
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG_PATH = join(MODULE_DIR, "default-config.json");
+const { SENSITIVE_CANARY_CONFIG: userConfigPath } = process.env;
+const USER_CONFIG_PATH = userConfigPath ??
+    join(homedir(), ".config", "sensitive-canary", "config.json");
+function readJsonFile(filePath) {
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+// Validate a raw JSON object against the RuleConfig schema. Throws with a
+// descriptive message when a required field is missing, a type is wrong, or a
+// cross-field constraint is violated.
+function validateRuleConfig(rc) {
+    if (typeof rc !== "object" || rc === null) {
+        throw new Error("rule must be an object");
+    }
+    const { id, description, regex: source, category, flags, secretGroup, entropyThreshold, validate: validateName, contextWords, excludeContext, requireContext, contextWindow, } = rc;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error('missing or empty "id" field');
+    }
+    if (typeof description !== "string" || description.length === 0) {
+        throw new Error('missing or empty "description" field');
+    }
+    if (typeof source !== "string" || source.length === 0) {
+        throw new Error('missing or empty "regex" field');
+    }
+    if (category !== "secret" && category !== "pii") {
+        throw new Error(`invalid "category" ${JSON.stringify(category)} (must be "secret" or "pii")`);
+    }
+    if (flags != null && typeof flags !== "string") {
+        throw new Error('"flags" must be a string');
+    }
+    if (secretGroup != null &&
+        (typeof secretGroup !== "number" ||
+            !Number.isInteger(secretGroup) ||
+            secretGroup < 0)) {
+        throw new Error('"secretGroup" must be a non-negative integer');
+    }
+    if (entropyThreshold != null &&
+        (typeof entropyThreshold !== "number" || entropyThreshold < 0)) {
+        throw new Error('"entropyThreshold" must be a non-negative number');
+    }
+    if (validateName != null && typeof validateName !== "string") {
+        throw new Error('"validate" must be a string');
+    }
+    if (excludeContext != null) {
+        if (!Array.isArray(excludeContext) ||
+            excludeContext.some((w) => typeof w !== "string" || w.length === 0)) {
+            throw new Error('"excludeContext" must be an array of non-empty strings');
+        }
+    }
+    if (contextWords != null) {
+        if (!Array.isArray(contextWords) ||
+            contextWords.some((w) => typeof w !== "string" || w.length === 0)) {
+            throw new Error('"contextWords" must be an array of non-empty strings');
+        }
+    }
+    if (requireContext != null && typeof requireContext !== "boolean") {
+        throw new Error('"requireContext" must be a boolean');
+    }
+    if (contextWindow != null &&
+        (typeof contextWindow !== "number" ||
+            !Number.isInteger(contextWindow) ||
+            contextWindow < 1)) {
+        throw new Error('"contextWindow" must be a positive integer');
+    }
+    // Cross-field: requireContext is meaningless without contextWords
+    if (requireContext === true &&
+        (!Array.isArray(contextWords) || contextWords.length === 0)) {
+        throw new Error('"requireContext" is true but "contextWords" is empty — context gating would be disabled and the rule would always fire');
+    }
+}
+// Compile a single RuleConfig (JSON) into a Rule (with compiled RegExp and
+// resolved validator function). Throws on invalid regex or missing required
+// fields so the caller (buildRules) can catch and warn per-rule.
+export function compileRule(rc) {
+    validateRuleConfig(rc);
+    const { regex: source, flags, validate: validateName, ...rest } = rc;
+    // matchAll requires the global flag; ensure it is always present.
+    const flagStr = flags ?? "g";
+    const withG = flagStr.includes("g") ? flagStr : `${flagStr}g`;
+    const rule = {
+        ...rest,
+        regex: new RegExp(source, withG),
+    };
+    if (validateName) {
+        const fn = getValidator(validateName);
+        if (fn) {
+            rule.validate = fn;
+        }
+        else {
+            process.stderr.write(`sensitive-canary: unknown validator "${validateName}" in rule "${rc.id}" — validation disabled\n`);
+        }
+    }
+    return rule;
+}
+// Load and compile the built-in default rules from default-config.json.
+function loadDefaultConfig() {
+    return readJsonFile(DEFAULT_CONFIG_PATH);
+}
+// Load user config if it exists. Returns null when the file is absent (the
+// common case). JSON parse errors and permission issues are reported on stderr
+// so that a broken config file is not silently ignored.
+function loadUserConfig() {
+    try {
+        // A FIFO or a device here would block the read until something wrote to
+        // it, and a hook that never returns is killed by the timeout, which does
+        // not block. The transcript reader and the file scanner both pay this stat
+        // already; this path was the one that did not.
+        if (!statSync(USER_CONFIG_PATH).isFile()) {
+            process.stderr.write(`sensitive-canary: user config "${USER_CONFIG_PATH}" is not a regular file, ignoring\n`);
+            return null;
+        }
+        return readJsonFile(USER_CONFIG_PATH);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT") {
+            process.stderr.write(`sensitive-canary: could not read user config "${USER_CONFIG_PATH}": ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+        return null;
+    }
+}
+// Build the final rule list: default rules first, then user rules. A user rule
+// with the same id as a built-in rule replaces it; new ids are appended.
+// Invalid user rules (bad regex, etc.) are skipped with a warning so that one
+// bad entry does not break the entire hook.
+function buildRules() {
+    const defaultConfig = loadDefaultConfig();
+    effectiveContextWindow = defaultConfig.contextWindow ?? 3;
+    const defaultRules = [];
+    for (const rc of defaultConfig.rules) {
+        try {
+            defaultRules.push(compileRule(rc));
+        }
+        catch (e) {
+            process.stderr.write(`sensitive-canary: failed to compile built-in rule "${rc?.id ?? "(unknown)"}": ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    const userConfig = loadUserConfig();
+    if (userConfig) {
+        if (typeof userConfig.contextWindow === "number" &&
+            Number.isInteger(userConfig.contextWindow) &&
+            userConfig.contextWindow >= 1) {
+            effectiveContextWindow = userConfig.contextWindow;
+        }
+        else if (userConfig.contextWindow != null) {
+            process.stderr.write(`sensitive-canary: invalid contextWindow in user config, ignoring\n`);
+        }
+        if (userConfig.rules != null && !Array.isArray(userConfig.rules)) {
+            process.stderr.write(`sensitive-canary: "rules" in user config must be an array, ignoring\n`);
+        }
+        if (Array.isArray(userConfig.rules) && userConfig.rules.length) {
+            const userRules = [];
+            for (const rc of userConfig.rules) {
+                try {
+                    userRules.push(compileRule(rc));
+                }
+                catch (e) {
+                    process.stderr.write(`sensitive-canary: skipping user rule "${rc?.id ?? "(unknown)"}": ${e instanceof Error ? e.message : String(e)}\n`);
+                }
+            }
+            // De-duplicate by id (last definition wins) so duplicate ids in the
+            // user config don't produce duplicate rules and duplicate findings.
+            const byId = new Map();
+            for (const rule of userRules) {
+                if (byId.has(rule.id)) {
+                    process.stderr.write(`sensitive-canary: duplicate user rule id "${rule.id}" — using the last definition\n`);
+                }
+                byId.set(rule.id, rule);
+            }
+            return defaultRules
+                .filter((r) => !byId.has(r.id))
+                .concat(Array.from(byId.values()));
+        }
+    }
+    return defaultRules;
+}
+export const RULES = buildRules();
+// Enough of a value to say which one was found, and no more.
+//
+// The block reason is written to stderr, which is where Claude reads it, so
+// whatever is shown here reaches the API that the block exists to keep it from.
+// Four characters at each end returned eight of a nine-character password.
+// A quarter of the value, capped at four per end.
+export function redact(str) {
+    // Code points, not code units. Slicing by unit cuts a surrogate pair in half
+    // and writes a lone surrogate to the terminal, which is neither the character
+    // nor a redaction of it.
+    const characters = [...str];
+    const shown = Math.min(4, Math.floor(characters.length / 8));
+    if (shown === 0)
+        return "****";
+    const head = characters.slice(0, shown).join("");
+    const tail = characters.slice(-shown).join("");
+    return `${head}****${tail}`;
+}
+// Longer than any honest scan and far shorter than the hook timeout. A rule
+// that backtracks badly takes minutes on a megabyte, and a hook killed by the
+// timeout does not block, so the damage is silent. The patterns that did that
+// are bounded; this catches the next one of that shape rather than letting it
+// repeat. The check sits between rules because a single `matchAll` cannot be
+// interrupted.
+export const SCAN_BUDGET_MS = 10_000;
+export class ScanBudgetExceeded extends Error {
+    constructor(ruleId, elapsed) {
+        super(`the scan passed ${SCAN_BUDGET_MS}ms (${elapsed}ms at rule "${ruleId}")`);
+        this.name = "ScanBudgetExceeded";
+    }
+}
+// The budget belongs to the hook invocation, not to one `scan()` call. A single
+// call is a small part of the work: `scanEnvironment` scans once per variable,
+// a file is scanned at both ends, and `Object.keys(process.env)` sets the
+// multiplier. Per call, each stays inside the budget while the total runs past
+// the hook timeout — and a hook killed by the timeout does not block.
+//
+// Set once by each hook entry point. Left unset, every call gets the full
+// budget, which is what the test suite needs.
+let deadline = null;
+// `null` clears it, which is the state a process starts in.
+export function beginScanBudget(totalMs = SCAN_BUDGET_MS) {
+    deadline = totalMs === null ? null : Date.now() + totalMs;
+}
+// What is left of the budget, or the whole of it when none was begun.
+function remainingBudget() {
+    return deadline === null ? SCAN_BUDGET_MS : deadline - Date.now();
+}
+// The between-rule check below cannot interrupt a single `matchAll`, and one
+// rule from a user config is enough to hang the hook — which is then killed by
+// the timeout, and a killed hook does not block. A V8-side timeout does
+// interrupt a running match. Measured at 0.06ms per call, against a scan that
+// costs hundreds of times that.
+const SCAN_SLOT = "__sensitiveCanaryScan";
+const HARD_LIMIT_SLACK_MS = 2_000;
+// `limitMs` bounds this call so it cannot overshoot what the invocation has
+// left. Without it a single call could run the full hard limit past a deadline
+// that was already spent.
+function runInterruptibly(work, limitMs) {
+    const slots = globalThis;
+    slots[SCAN_SLOT] = work;
+    try {
+        return vm.runInThisContext(`globalThis.${SCAN_SLOT}()`, {
+            timeout: limitMs,
+            displayErrors: false,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("timed out"))
+            throw new ScanBudgetExceeded("a single rule", limitMs);
+        throw error;
+    }
+    finally {
+        delete slots[SCAN_SLOT];
+    }
+}
+export function scan(text, categories = ALL_CATEGORIES) {
+    const remaining = remainingBudget();
+    if (remaining <= 0)
+        throw new ScanBudgetExceeded("this call's total", SCAN_BUDGET_MS);
+    return runInterruptibly(() => scanUninterrupted(text, categories, remaining), remaining + HARD_LIMIT_SLACK_MS);
+}
+function scanUninterrupted(text, categories, budgetMs) {
+    const findings = [];
+    const startedAt = Date.now();
+    for (const rule of RULES) {
+        if (!categories.has(rule.category))
+            continue;
+        const elapsed = Date.now() - startedAt;
+        // Thrown rather than returned: a partial result is indistinguishable from a
+        // clean one, and the hooks stop the call on an error they cannot explain.
+        if (elapsed > budgetMs)
+            throw new ScanBudgetExceeded(rule.id, elapsed);
+        for (const match of text.matchAll(rule.regex)) {
+            const secretValue = rule.secretGroup != null ? match[rule.secretGroup] : match[0];
+            if (!secretValue)
+                continue;
+            // Both the captured value and the whole match: a rule with a
+            // `secretGroup` captures only part of what it matched, and the
+            // connection-string rule stops at the `@`, so the host — the one thing
+            // that separates `user:password@localhost` from `user:password@` in front
+            // of real infrastructure — is outside the capture.
+            const matchStart = match.index ?? 0;
+            const matchEnd = matchStart + match[0].length;
+            const following = text.slice(matchEnd, matchEnd + 64);
+            // The shape test applies only where the rule captured a free-form value.
+            // A rule that matches a fixed prefix has already said what the thing is —
+            // a Slack webhook is a URL and a secret, and asking whether it looks like
+            // a URL is asking the wrong question.
+            const capturesAValue = rule.secretGroup != null;
+            if (rule.category === "secret" &&
+                (isPlaceholder(secretValue, following) ||
+                    (capturesAValue &&
+                        (isNotSecretShaped(secretValue) ||
+                            isPlaceholder(match[0], following) ||
+                            isNotSecretShaped(match[0]) ||
+                            keyDescribesRatherThanHolds(match[0])))))
+                continue;
+            if (rule.entropyThreshold != null &&
+                entropy(secretValue) < rule.entropyThreshold)
+                continue;
+            if (rule.validate != null && !rule.validate(secretValue))
+                continue;
+            const hasContext = !rule.contextWords || rule.contextWords.length === 0
+                ? true
+                : hasNearbyContextWord(text, matchStart, matchEnd, rule.contextWords, rule.contextWindow ?? effectiveContextWindow);
+            // Rules that require context (e.g. bare postal codes) are dropped when
+            // no context label is nearby, to avoid flagging every 5-digit number.
+            if (rule.requireContext && !hasContext)
+                continue;
+            // And the other way: a word nearby that says this is not what the rule is
+            // for. `git clone git@github.com:…` and `ssh deploy@host` are addresses by
+            // shape, and the command in front of them is what says they are not
+            // anyone's mail.
+            if (rule.excludeContext &&
+                rule.excludeContext.length > 0 &&
+                hasNearbyContextWord(text, matchStart, matchEnd, rule.excludeContext, rule.contextWindow ?? effectiveContextWindow)) {
+                continue;
+            }
+            findings.push({
+                ruleId: rule.id,
+                description: rule.description,
+                category: rule.category,
+                matchRedacted: redact(secretValue),
+                secretValue,
+                score: hasContext ? 1.0 : 0.4,
+            });
+        }
+    }
+    return findings;
+}

package/dist/lib/shapes.js

@@ -0,0 +1,161 @@
+// Whether a value that matched a rule is a credential after all.
+//
+// A rule finds a shape. These decide what the shape is standing for: a name
+// that points at a secret, a slot waiting to be filled, a reference to a value
+// in code. Each one waves a match through, so each is a way past every rule it
+// runs over, and each is written to be narrower than the shape it answers for.
+// A value whose shape says it is not a credential, whatever its name suggests.
+// `TOKEN_ENDPOINT`, `secret_name`, `VAULT_TOKEN_PATH` and `TOKEN_HEADER_NAME`
+// all assign something that points at a secret rather than being one, and
+// blocking them made Terraform, Kubernetes manifests and OAuth configuration
+// unreadable — fourteen of the twenty-six wrong blocks in a survey of six
+// hundred real files.
+export function isNotSecretShaped(value) {
+    const v = value.trim();
+    // A URL or a URN. Credentials embedded in one are the connection-string
+    // rule's business, and a URL carrying a token in its query is left alone
+    // here so the `?` case still reaches the other rules.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(v) &&
+        !v.includes("?") &&
+        !v.includes("@"))
+        return true;
+    if (/^urn:/i.test(v))
+        return true;
+    // A filesystem path.
+    if (/^[~.]?\/[^\s]*$/.test(v))
+        return true;
+    // The name of a variable rather than its value.
+    if (/^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(v))
+        return true;
+    // An HTTP header name.
+    if (/^[A-Z][A-Za-z0-9]*(?:-[A-Z][A-Za-z0-9]*)+$/.test(v))
+        return true;
+    // A number.
+    if (/^\d+$/.test(v))
+        return true;
+    // A dotted lower-case identifier, as a storage key or a setting name.
+    if (/^[a-z][a-z0-9]*(?:\.[a-z0-9]+)+$/.test(v))
+        return true;
+    // A reference to a value in code rather than the value: `process.env.API_KEY`,
+    // `user.password_digest`, `self.api_key`, `response.data.accessToken`. Of the
+    // distinct values `env-assignment` matched across thirty thousand real files,
+    // two in five were one of these.
+    if (/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(v) &&
+        v.split(".").every(readsAsWords))
+        return true;
+    return false;
+}
+// Whether a name is built out of words rather than out of random characters.
+//
+// Dotted credentials exist — a JWT, and the dotted forms several vendors issue —
+// so the shape alone cannot stand for "this is code". What separates them is
+// that a name is words: `connectionString` and `password_digest` run several
+// letters between one boundary and the next, where a random segment changes
+// case or slips in a digit every character or two.
+//
+// Measured over 147,643 dotted identifiers taken from the source on this
+// machine, 0.06% fall below the threshold below, and the ones that do are JWTs.
+export const MIN_MEAN_WORD_LENGTH = 2.5;
+// Short segments are words by default: `env`, `data`, `id`. The statistic needs
+// something to average over before it says anything.
+export const SHORTEST_MEASURABLE_SEGMENT = 8;
+export function readsAsWords(segment) {
+    if (segment.length < SHORTEST_MEASURABLE_SEGMENT)
+        return true;
+    // A leading capital belongs to the lowercase run after it, so `toLowerCase`
+    // is three words and not five runs of one case.
+    const words = segment.match(/[A-Z]+(?![a-z])|[A-Z]?[a-z]+|\d+/g);
+    if (words === null || words.length === 0)
+        return false;
+    return segment.length / words.length >= MIN_MEAN_WORD_LENGTH;
+}
+// A key that says where a secret lives, or what it is called, rather than what
+// it is. The rule fires on the keyword anywhere in the name, so
+// `SECRET_MANAGER_PROJECT` reads as a secret because of its first word, when its
+// last one says it holds a project.
+const DESCRIBES_A_SECRET = /\b[A-Za-z0-9_]*_(?:PROJECT|NAME|PATH|FILE|DIR|URL|URI|ENDPOINT|HOST|PORT|ID|TYPE|HEADER|PREFIX|SUFFIX|FIELD|COLUMN|TABLE|ENV|REGION|BUCKET|ARN|VERSION|TTL|TIMEOUT|LENGTH|COUNT|ENABLED|ALGORITHM|ISSUER|AUDIENCE|SCOPE|PROVIDER|BACKEND|SOURCE)\b[ \t]*[:=]/i;
+export function keyDescribesRatherThanHolds(matchText) {
+    return DESCRIBES_A_SECRET.test(matchText);
+}
+// A value written to be replaced. Half of a realistic `.env.example` was being
+// blocked on its contents, which is the block most likely to get the tool turned
+// off — the file is meant to be committed and read.
+//
+// Only secret rules consult this. "todo@company.com" is a real address, and
+// AWS's own documented key ends in EXAMPLE and is still a key, so `example` is
+// deliberately absent from the marker list where it would matter.
+// A word that only ever appears in a value nobody typed.
+const PLACEHOLDER_MARKERS = /^(?:changeme|change|me|replace|insert|set|with|real|this|your|my|here|todo|tbd|fixme|dummy|placeholder|insecure|sample|example|test|fake|redacted|value|x{3,})$/i;
+// A word that can make up the rest of such a value, but never marks one alone.
+const PLACEHOLDER_FILLER = /^(?:api|key|keys|token|tokens|secret|secrets|password|passwd|pwd|pass|base|url|uri|host|hostname|name|user|username|id|access|refresh|client|auth|sk|pk|in|production|development|staging|local|dev|the|a|of|for|and|[0-9]+)$/i;
+// The scheme is bounded: an unbounded `\w+` in front of a literal that usually
+// is not there makes the match quadratic in the length of the value, and a
+// value is as long as whoever wrote the text wants. A scheme is a word.
+const GENERIC_CREDENTIALS = /\w{1,32}:\/\/(?:your[_-]?)?(?:user|username)(?:name)?:(?:your[_-]?)?(?:password|passwd|pwd)@/i;
+const GENERIC_HOST = /^(?:localhost|127\.0\.0\.1|0\.0\.0\.0|host|hostname|db|database|example\.(?:com|org|net))\b/i;
+export function isPlaceholder(value, following = "") {
+    const v = value.trim();
+    if (!v)
+        return false;
+    // Filler on its own: `xxxxxxxxxxxx`.
+    if (/^[Xx]+$/.test(v))
+        return true;
+    // A slot rather than a value: `<your-token>`, `${TOKEN}`, `{{ token }}`.
+    if (/^[<{[]/.test(v) && /[>}\]]$/.test(v))
+        return true;
+    // A shell or template reference, which holds nothing at all.
+    if (/^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/.test(v))
+        return true;
+    // An unexpanded reference anywhere inside a connection string: no character
+    // of the credentials has been substituted yet.
+    if (/:\/\/[^@\s]*(?:\$\{[A-Za-z_][^}]*\}|\$[A-Za-z_][A-Za-z0-9_]*|\{\})[^@\s]*@/.test(v))
+        return true;
+    // A user and a password that are the same word, and that word names the
+    // service: `postgres:postgres@`, `root:root@`, `guest:guest@` are what a
+    // compose file and a quickstart ship with.
+    const samePair = v.match(/:\/\/([A-Za-z]{3,12}):([A-Za-z]{3,12})@/);
+    if (samePair &&
+        samePair[1]?.toLowerCase() === samePair[2]?.toLowerCase() &&
+        /^(?:postgres|postgresql|mysql|mariadb|mongo|mongodb|redis|root|guest|admin|user|test|rabbitmq)$/i.test(samePair[1] ?? ""))
+        return true;
+    // The default the django template generates, which ships in every new project.
+    if (/^django-insecure-/i.test(v))
+        return true;
+    // A connection string where the user, the password and the host are all the
+    // words for them. Each of the three matters: `root:secret@` is a password
+    // people set, and `user:password@prod.corp.internal` names real infrastructure.
+    // The rule that finds these stops at the `@`, so the host arrives as the text
+    // that follows rather than as part of the value.
+    //
+    // Matched once. Asking three times ran the same backtracking three times.
+    const credentials = GENERIC_CREDENTIALS.exec(v);
+    if (credentials !== null) {
+        const afterAt = v.slice(credentials.index + credentials[0].length);
+        if (GENERIC_HOST.test(afterAt || following))
+            return true;
+    }
+    // Otherwise every part of the value has to be one of these words, and at
+    // least one has to be a marker. Testing whether the value *contains* a marker
+    // was a way through: `changeme_` in front of a live key disabled the rule.
+    const parts = v.split(/[-_.\s]+/).filter(Boolean);
+    if (parts.length === 0)
+        return false;
+    if (!parts.some((part) => PLACEHOLDER_MARKERS.test(part)))
+        return false;
+    return parts.every((part) => PLACEHOLDER_MARKERS.test(part) || PLACEHOLDER_FILLER.test(part));
+}
+// Shannon entropy (bits per character; ≈0–8 for byte-sized alphabets)
+export function entropy(str) {
+    if (str.length === 0)
+        return 0;
+    const freq = {};
+    for (const ch of str)
+        freq[ch] = (freq[ch] ?? 0) + 1;
+    let h = 0;
+    const n = str.length;
+    for (const count of Object.values(freq)) {
+        const p = count / n;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}