@crewhaus/tool-secure 0.7.0

package/dist/lib/secrets.js

@@ -0,0 +1,329 @@
+/**
+ * Credential detection.
+ *
+ * ## The one hard rule
+ *
+ * A finding never carries the secret. Every value that reaches a result goes
+ * through `maskValue` first, and the tests assert that the serialized result
+ * of scanning a known credential does not contain that credential. A scanner
+ * that prints what it found has moved the secret from a file into a
+ * transcript, a log and a model's context window — three more places it has
+ * to be rotated out of.
+ *
+ * ## What the rules are
+ *
+ * Two kinds. VENDOR rules key on a published, distinctive prefix
+ * (`AKIA…`, `ghp_…`, `sk-ant-…`); they are precise and they go stale — a
+ * provider that changes its key format silently stops being covered here.
+ * STRUCTURAL rules key on shape: a PEM block, a JWT, a URL with a password
+ * in the authority, an assignment to something called `password`.
+ *
+ * ## What it cannot do
+ *
+ * It cannot tell a live key from a revoked one, a real key from an example
+ * in documentation, or a missing rule from a clean file. `SecretScan`
+ * reports the rule list it ran precisely so that "no findings" reads as
+ * "none of THESE matched", which is the only claim it can support.
+ *
+ * The high-entropy rule is deliberately context-gated by default: commit
+ * hashes, UUIDs, base64 images and minified code are all high entropy, and a
+ * scanner that cries wolf on them gets switched off.
+ */
+import { classifyCharset, looksHighEntropy, roundBits, shannonEntropy, } from "./entropy";
+import { groupSpan, maskValue, matchAll, sortFindings, withPositions } from "./text";
+/**
+ * The rule table, in scan order. Ids are stable: an operator's allow-list of
+ * accepted findings keys on them.
+ */
+export const SECRET_RULES = [
+    {
+        id: "aws.access-key-id",
+        kind: "vendor",
+        description: "AWS access key id (AKIA/ASIA/… followed by 16 upper-case base32 characters)",
+        severity: "high",
+        pattern: /\b(?:AKIA|ASIA|AIDA|AROA|AIPA|ANPA|ANVA|ABIA|ACCA)[0-9A-Z]{16}\b/g,
+    },
+    {
+        id: "aws.secret-access-key",
+        kind: "vendor",
+        description: "AWS secret access key assigned to an aws_secret_access_key-style name",
+        severity: "critical",
+        pattern: /aws_?secret_?access_?key["']?\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})/gi,
+        group: 1,
+    },
+    {
+        id: "github.token",
+        kind: "vendor",
+        description: "GitHub personal access, OAuth, user, server or refresh token (gh[pousr]_…)",
+        severity: "critical",
+        pattern: /\bgh[pousr]_[A-Za-z0-9]{36,255}\b/g,
+    },
+    {
+        id: "github.fine-grained-pat",
+        kind: "vendor",
+        description: "GitHub fine-grained personal access token (github_pat_…)",
+        severity: "critical",
+        pattern: /\bgithub_pat_[A-Za-z0-9_]{60,}\b/g,
+    },
+    {
+        id: "gitlab.token",
+        kind: "vendor",
+        description: "GitLab personal or project access token (glpat-…)",
+        severity: "critical",
+        pattern: /\bglpat-[A-Za-z0-9_-]{20,}\b/g,
+    },
+    {
+        id: "slack.token",
+        kind: "vendor",
+        description: "Slack bot, user, app or refresh token (xox[abposr]-…)",
+        severity: "critical",
+        pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}\b/g,
+    },
+    {
+        id: "slack.webhook",
+        kind: "vendor",
+        description: "Slack incoming-webhook URL, which is itself the credential",
+        severity: "high",
+        pattern: /https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9/+_-]{20,}/g,
+    },
+    {
+        id: "stripe.secret-key",
+        kind: "vendor",
+        description: "Stripe secret or restricted key (sk_live/sk_test/rk_…)",
+        severity: "critical",
+        pattern: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
+    },
+    {
+        id: "stripe.publishable-key",
+        kind: "vendor",
+        description: "Stripe publishable key — public by design, reported so it is not mistaken for a secret",
+        severity: "low",
+        pattern: /\bpk_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
+    },
+    {
+        id: "anthropic.api-key",
+        kind: "vendor",
+        description: "Anthropic API key (sk-ant-…)",
+        severity: "critical",
+        pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+    },
+    {
+        id: "openai.api-key",
+        kind: "vendor",
+        description: "OpenAI API key (sk-… / sk-proj-…)",
+        severity: "critical",
+        pattern: /\bsk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}\b/g,
+    },
+    {
+        id: "google.api-key",
+        kind: "vendor",
+        description: "Google API key (AIza followed by 35 characters)",
+        severity: "high",
+        pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+    },
+    {
+        id: "sendgrid.api-key",
+        kind: "vendor",
+        description: "SendGrid API key (SG.<id>.<secret>)",
+        severity: "critical",
+        pattern: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/g,
+    },
+    {
+        id: "twilio.api-key",
+        kind: "vendor",
+        description: "Twilio API key SID (SK followed by 32 hex characters)",
+        severity: "high",
+        pattern: /\bSK[0-9a-fA-F]{32}\b/g,
+    },
+    {
+        id: "npm.token",
+        kind: "vendor",
+        description: "npm access token (npm_…)",
+        severity: "critical",
+        pattern: /\bnpm_[A-Za-z0-9]{36}\b/g,
+    },
+    {
+        id: "pypi.token",
+        kind: "vendor",
+        description: "PyPI upload token (pypi-…)",
+        severity: "critical",
+        pattern: /\bpypi-[A-Za-z0-9_-]{50,}\b/g,
+    },
+    {
+        id: "private-key.pem-block",
+        kind: "structural",
+        description: "PEM private-key header; the key body follows it",
+        severity: "critical",
+        pattern: /-----BEGIN (?:RSA |DSA |EC |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g,
+    },
+    {
+        id: "jwt.compact",
+        kind: "structural",
+        description: "JWT in compact serialization; a bearer token unless it is a public id token",
+        severity: "medium",
+        pattern: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+    },
+    {
+        id: "url.credentials",
+        kind: "structural",
+        description: "Connection string or URL carrying a password in the authority (scheme://user:pass@host)",
+        severity: "high",
+        pattern: /\b[a-z][a-z0-9+.-]{1,20}:\/\/[^\s:@/]{1,64}:([^\s@/]{1,128})@[^\s/]{1,255}/gi,
+        group: 1,
+    },
+    {
+        id: "http.basic-auth-header",
+        kind: "structural",
+        description: "HTTP Basic Authorization header; the base64 decodes to user:password",
+        severity: "high",
+        pattern: /authorization\s*:\s*basic\s+([A-Za-z0-9+/=]{8,})/gi,
+        group: 1,
+    },
+    {
+        id: "generic.assignment",
+        kind: "structural",
+        description: "A value assigned to a password/secret/token/api-key-shaped name",
+        severity: "medium",
+        pattern: /\b(?:password|passwd|pwd|secret|client_secret|token|access_token|auth_token|api[_-]?key|apikey|private[_-]?key|credential)["']?\s*[:=]\s*["']([^"'\n]{8,200})["']/gi,
+        group: 1,
+    },
+];
+const RULES_BY_ID = new Map(SECRET_RULES.map((r) => [r.id, r]));
+/**
+ * Values that match a rule but are placeholders, not credentials. Kept short
+ * and literal; anything cleverer would start guessing.
+ */
+const PLACEHOLDER = /^(?:x{3,}|\*{3,}|\.{3,}|<[^>]*>|\$\{[^}]*\}|\{\{[^}]*\}\}|(?:your|my|the|some|example|sample|dummy|fake|test|placeholder|redacted|changeme|insert)[_a-z0-9-]*)$/i;
+/** Context that makes a high-entropy string worth reporting. */
+const CREDENTIAL_CONTEXT = /(?:pass(?:word|wd)?|secret|token|api[_-]?key|apikey|auth|bearer|credential|private[_-]?key|access[_-]?key|session|signature)/i;
+const HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9+/=_-]{20,120}/g;
+export class SecretRuleError extends Error {
+    name = "SecretRuleError";
+}
+/** The id the context-gated entropy heuristic reports under. */
+export const HIGH_ENTROPY_RULE = "generic.high-entropy";
+/**
+ * Every rule id a given options object will report under, including the
+ * entropy heuristic when it is enabled. `SecretScan` prints this so an empty
+ * result reads as a scope rather than a verdict, and `secretFindings` below
+ * runs exactly this set — the list and the scan cannot drift apart.
+ */
+export function rulesRunFor(options = {}) {
+    const ids = selectRules(options).map((r) => r.id);
+    return options.highEntropy === false ? ids : [...ids, HIGH_ENTROPY_RULE];
+}
+/** The rules a given options object will actually run, in scan order. */
+export function selectRules(options = {}) {
+    if (options.rules === undefined)
+        return [...SECRET_RULES];
+    const unknown = options.rules.filter((id) => !RULES_BY_ID.has(id));
+    if (unknown.length > 0) {
+        throw new SecretRuleError(`unknown secret rule id(s): ${unknown.join(", ")} — known ids are ${SECRET_RULES.map((r) => r.id).join(", ")}`);
+    }
+    return SECRET_RULES.filter((r) => options.rules?.includes(r.id));
+}
+/**
+ * Every located secret in the text, values included, in document order.
+ *
+ * This is the ONE implementation. `scanSecrets` masks it for a result and
+ * `secretSpans` hands it to a redactor unmasked; there is no second copy of
+ * the rule loop to fall out of step with this one, which is exactly what let
+ * `RedactForExport` report a high-entropy finding and then not remove it.
+ */
+export function secretFindings(text, options = {}) {
+    const rules = selectRules(options);
+    const raw = [];
+    for (const rule of rules) {
+        for (const { match } of matchAll(text, rule.pattern)) {
+            const group = rule.group ?? 0;
+            const value = match[group];
+            if (value === undefined || value.length === 0)
+                continue;
+            if (PLACEHOLDER.test(value))
+                continue;
+            // The group's REAL offset. Searching the match for the group's own text
+            // finds the wrong copy when the value also appears earlier in the match,
+            // which puts the span on a username and leaves the password in place.
+            const span = groupSpan(match, group);
+            if (span === undefined)
+                continue;
+            raw.push({
+                type: rule.id,
+                rule: rule.id,
+                confidence: rule.kind === "vendor" ? "likely" : "possible",
+                start: span.start,
+                end: span.end,
+                value,
+                detail: { severity: rule.severity },
+            });
+        }
+    }
+    if (options.highEntropy !== false) {
+        const requireContext = options.requireContext !== false;
+        for (const { index, match } of matchAll(text, HIGH_ENTROPY_CANDIDATE)) {
+            const value = match[0];
+            if (PLACEHOLDER.test(value))
+                continue;
+            const { high } = looksHighEntropy(value, options.minEntropy);
+            if (!high)
+                continue;
+            if (requireContext) {
+                const before = text.slice(Math.max(0, index - 60), index);
+                if (!CREDENTIAL_CONTEXT.test(before))
+                    continue;
+            }
+            // A vendor rule already covering this span is the better finding.
+            if (raw.some((f) => index < f.end && f.start < index + value.length))
+                continue;
+            raw.push({
+                type: HIGH_ENTROPY_RULE,
+                rule: HIGH_ENTROPY_RULE,
+                confidence: "possible",
+                start: index,
+                end: index + value.length,
+                value,
+                detail: { severity: "low" },
+            });
+        }
+    }
+    return sortFindings(withPositions(text, raw));
+}
+/** Scan text. The returned hits are already masked. */
+export function scanSecrets(text, options = {}) {
+    return secretFindings(text, options).map((f) => {
+        const rule = RULES_BY_ID.get(f.rule);
+        const { bits } = shannonEntropy(f.value);
+        return {
+            rule: f.rule,
+            kind: rule?.kind ?? "structural",
+            severity: (rule?.severity ?? "low"),
+            description: rule?.description ??
+                "opaque high-entropy string near a credential-shaped word (heuristic, not a vendor rule)",
+            line: f.line,
+            column: f.column,
+            start: f.start,
+            length: f.value.length,
+            masked: maskValue(f.value),
+            entropyBits: roundBits(bits),
+            charset: classifyCharset(f.value),
+        };
+    });
+}
+/**
+ * The spans a redactor should replace. Same rules, same options, same spans
+ * as `scanSecrets` — including the entropy heuristic, so a document cannot be
+ * reported as holding a secret and handed back with that secret still in it.
+ *
+ * `Finding`s carry their value because the caller is about to remove them; it
+ * is the scanner's OUTPUT that must never carry one.
+ */
+export function secretSpans(text, options = {}) {
+    return secretFindings(text, options);
+}
+/** Summarize hits by severity, highest first, for a one-line verdict. */
+export function severityCounts(hits) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const hit of hits)
+        counts[hit.severity] += 1;
+    return counts;
+}

package/dist/lib/text.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The shared spine of this package: located spans, the size caps every
+ * entry point applies, and the masking helper that keeps a finding from
+ * becoming a leak.
+ *
+ * Nothing here is a detector. Detectors live next door and all of them
+ * speak in `Finding`s, so one renderer, one de-duplicator and one redactor
+ * serve every scan.
+ */
+/** A located, classified hit. `value` is NEVER put in a tool result verbatim. */
+export type Finding = {
+    /** What kind of thing this is, e.g. `email`, `aws.access-key-id`. */
+    readonly type: string;
+    /** The named rule that matched, so a reviewer can look it up. */
+    readonly rule: string;
+    /** How much the rule proves. See `Confidence`. */
+    readonly confidence: Confidence;
+    /** UTF-16 code-unit offset of the first character. */
+    readonly start: number;
+    /** UTF-16 code-unit offset one past the last character. */
+    readonly end: number;
+    /** 1-based line of `start`. */
+    readonly line: number;
+    /** 1-based column of `start`, counted in code units. */
+    readonly column: number;
+    /** The matched text. Internal only — mask or drop it before returning. */
+    readonly value: string;
+    /** Optional rule-specific detail (brand, country, entropy, …). */
+    readonly detail?: Readonly<Record<string, string | number | boolean>>;
+};
+/**
+ * What a match is worth.
+ *
+ * - `verified` — a check digit passed (Luhn, ISO 7064 mod-97). The string is
+ *   a structurally valid instance of the format. It still says nothing about
+ *   whether the number was ever issued, or to whom.
+ * - `likely` — a distinctive shape plus corroborating context (a labelled
+ *   field, a vendor-specific prefix).
+ * - `possible` — shape alone. Expect false positives.
+ *
+ * No level means "this is personal data" or "this is a live credential".
+ * Those are judgements about the world; these rules only see bytes.
+ */
+export type Confidence = "verified" | "likely" | "possible";
+/**
+ * The ceiling on any text a tool in this package will examine.
+ *
+ * Every scanner is linear in the input, but a caller that hands over a
+ * 200 MB string has already lost: the string, the findings and the redacted
+ * copy all sit in memory at once. Refusing is the honest answer.
+ */
+export declare const MAX_TEXT_CHARS = 2000000;
+/** Raised for a caller mistake. Tools catch it and return the message. */
+export declare class SecureInputError extends Error {
+    readonly name = "SecureInputError";
+}
+/** Refuse an over-large string before any scanning work begins. */
+export declare function assertTextSize(text: string, field: string, limit?: number): void;
+/** Offsets at which each line starts; `[0]` is always 0. */
+export declare function lineStarts(text: string): number[];
+/** 1-based line and column for an offset, against a prepared `lineStarts`. */
+export declare function locate(starts: ReadonlyArray<number>, offset: number): {
+    line: number;
+    column: number;
+};
+/** Locale-independent ordering. `localeCompare` would make results host-dependent. */
+export declare function compareStrings(a: string, b: string): number;
+/**
+ * Mask a value so a finding can be reviewed without the value leaking.
+ *
+ * The rule: at most `keep` leading and `keep` trailing characters survive,
+ * and only when the value is long enough that those characters are a small
+ * fraction of it. Anything shorter is masked whole. The length is reported
+ * separately, because length is useful and is not the secret.
+ *
+ * This is the one function standing between `SecretScan` and a tool result
+ * that contains a live credential. It is tested directly.
+ */
+export declare function maskValue(value: string, keep?: number): string;
+/**
+ * Drop findings swallowed by a stronger one.
+ *
+ * Overlap is common and mostly noise: the digit run inside an IBAN also
+ * looks like a phone number, and a JWT is three high-entropy blobs. The
+ * survivor is chosen by confidence, then by length, then by earliest start,
+ * then by rule name — a total order, so the same input always yields the
+ * same set.
+ */
+export declare function dedupeOverlaps(findings: ReadonlyArray<Finding>): Finding[];
+/** Reading order, with a deterministic tiebreak. */
+export declare function sortFindings(findings: ReadonlyArray<Finding>): Finding[];
+/** Attach line/column to raw offsets in one pass over the text. */
+export declare function withPositions(text: string, raw: ReadonlyArray<Omit<Finding, "line" | "column">>): Finding[];
+/**
+ * Replace each span with the string `replace` returns for it.
+ *
+ * Spans must not overlap (`dedupeOverlaps` guarantees that); they are
+ * applied right to left so earlier offsets stay valid.
+ */
+export declare function applySpans(text: string, findings: ReadonlyArray<Finding>, replace: (finding: Finding) => string): string;
+/** Tally findings by `type`, sorted by type so the record is stable. */
+export declare function countByType(findings: ReadonlyArray<Finding>): Record<string, number>;
+/**
+ * Run a global regex over text, yielding matches with their offsets.
+ *
+ * The pattern is cloned so a caller's `lastIndex` cannot leak between calls,
+ * and a zero-length match advances the cursor rather than spinning forever.
+ *
+ * The clone always carries `g` and `d`. `d` matters: a rule that captures the
+ * secret in a group needs the group's REAL offset, and searching the match
+ * text for the group's own text finds the wrong copy whenever the value also
+ * appears earlier in the match — `scheme://admin_hunter2:hunter2@host` is the
+ * shape that does it. `groupSpan` below is how a caller gets that offset.
+ */
+export declare function matchAll(text: string, pattern: RegExp): Generator<{
+    index: number;
+    match: RegExpExecArray;
+}>;
+/**
+ * The absolute `[start, end)` of one capture group of a match produced by
+ * `matchAll`, or `undefined` when the group did not participate.
+ *
+ * Group 0 is the whole match. Any other group's offsets come from the `d`
+ * flag's indices, never from searching for the group's text inside the match.
+ */
+export declare function groupSpan(match: RegExpExecArray, group: number): {
+    start: number;
+    end: number;
+} | undefined;

package/dist/lib/text.js

@@ -0,0 +1,191 @@
+/**
+ * The shared spine of this package: located spans, the size caps every
+ * entry point applies, and the masking helper that keeps a finding from
+ * becoming a leak.
+ *
+ * Nothing here is a detector. Detectors live next door and all of them
+ * speak in `Finding`s, so one renderer, one de-duplicator and one redactor
+ * serve every scan.
+ */
+const CONFIDENCE_RANK = {
+    verified: 3,
+    likely: 2,
+    possible: 1,
+};
+/**
+ * The ceiling on any text a tool in this package will examine.
+ *
+ * Every scanner is linear in the input, but a caller that hands over a
+ * 200 MB string has already lost: the string, the findings and the redacted
+ * copy all sit in memory at once. Refusing is the honest answer.
+ */
+export const MAX_TEXT_CHARS = 2_000_000;
+/** Raised for a caller mistake. Tools catch it and return the message. */
+export class SecureInputError extends Error {
+    name = "SecureInputError";
+}
+/** Refuse an over-large string before any scanning work begins. */
+export function assertTextSize(text, field, limit = MAX_TEXT_CHARS) {
+    if (text.length > limit) {
+        throw new SecureInputError(`${field} is ${text.length} characters, over this package's ${limit} limit — split the input and scan the pieces`);
+    }
+}
+/** Offsets at which each line starts; `[0]` is always 0. */
+export function lineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** 1-based line and column for an offset, against a prepared `lineStarts`. */
+export function locate(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if ((starts[mid] ?? 0) <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo + 1, column: offset - (starts[lo] ?? 0) + 1 };
+}
+/** Locale-independent ordering. `localeCompare` would make results host-dependent. */
+export function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Mask a value so a finding can be reviewed without the value leaking.
+ *
+ * The rule: at most `keep` leading and `keep` trailing characters survive,
+ * and only when the value is long enough that those characters are a small
+ * fraction of it. Anything shorter is masked whole. The length is reported
+ * separately, because length is useful and is not the secret.
+ *
+ * This is the one function standing between `SecretScan` and a tool result
+ * that contains a live credential. It is tested directly.
+ */
+export function maskValue(value, keep = 2) {
+    const n = value.length;
+    if (n === 0)
+        return "";
+    // Below this a prefix+suffix would expose too much of the value: at n = 12
+    // and keep = 2, four of twelve characters survive, and that is the floor.
+    if (keep <= 0 || n < 4 * keep + 4)
+        return "*".repeat(Math.min(n, 12));
+    const head = value.slice(0, keep);
+    const tail = value.slice(n - keep);
+    return `${head}${"*".repeat(Math.min(n - 2 * keep, 12))}${tail}`;
+}
+/**
+ * Drop findings swallowed by a stronger one.
+ *
+ * Overlap is common and mostly noise: the digit run inside an IBAN also
+ * looks like a phone number, and a JWT is three high-entropy blobs. The
+ * survivor is chosen by confidence, then by length, then by earliest start,
+ * then by rule name — a total order, so the same input always yields the
+ * same set.
+ */
+export function dedupeOverlaps(findings) {
+    const ranked = [...findings].sort((a, b) => {
+        const byConfidence = CONFIDENCE_RANK[b.confidence] - CONFIDENCE_RANK[a.confidence];
+        if (byConfidence !== 0)
+            return byConfidence;
+        const byLength = b.end - b.start - (a.end - a.start);
+        if (byLength !== 0)
+            return byLength;
+        if (a.start !== b.start)
+            return a.start - b.start;
+        return compareStrings(a.rule, b.rule);
+    });
+    const kept = [];
+    for (const candidate of ranked) {
+        const clashes = kept.some((k) => candidate.start < k.end && k.start < candidate.end);
+        if (!clashes)
+            kept.push(candidate);
+    }
+    return sortFindings(kept);
+}
+/** Reading order, with a deterministic tiebreak. */
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => a.start - b.start ||
+        a.end - b.end ||
+        compareStrings(a.type, b.type) ||
+        compareStrings(a.rule, b.rule));
+}
+/** Attach line/column to raw offsets in one pass over the text. */
+export function withPositions(text, raw) {
+    const starts = lineStarts(text);
+    return raw.map((f) => ({ ...f, ...locate(starts, f.start) }));
+}
+/**
+ * Replace each span with the string `replace` returns for it.
+ *
+ * Spans must not overlap (`dedupeOverlaps` guarantees that); they are
+ * applied right to left so earlier offsets stay valid.
+ */
+export function applySpans(text, findings, replace) {
+    const ordered = sortFindings(findings);
+    let out = text;
+    for (let i = ordered.length - 1; i >= 0; i--) {
+        const f = ordered[i];
+        if (!f)
+            continue;
+        out = out.slice(0, f.start) + replace(f) + out.slice(f.end);
+    }
+    return out;
+}
+/** Tally findings by `type`, sorted by type so the record is stable. */
+export function countByType(findings) {
+    const counts = new Map();
+    for (const f of findings)
+        counts.set(f.type, (counts.get(f.type) ?? 0) + 1);
+    const out = {};
+    for (const key of [...counts.keys()].sort(compareStrings))
+        out[key] = counts.get(key) ?? 0;
+    return out;
+}
+/**
+ * Run a global regex over text, yielding matches with their offsets.
+ *
+ * The pattern is cloned so a caller's `lastIndex` cannot leak between calls,
+ * and a zero-length match advances the cursor rather than spinning forever.
+ *
+ * The clone always carries `g` and `d`. `d` matters: a rule that captures the
+ * secret in a group needs the group's REAL offset, and searching the match
+ * text for the group's own text finds the wrong copy whenever the value also
+ * appears earlier in the match — `scheme://admin_hunter2:hunter2@host` is the
+ * shape that does it. `groupSpan` below is how a caller gets that offset.
+ */
+export function* matchAll(text, pattern) {
+    let flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+    if (!flags.includes("d"))
+        flags = `${flags}d`;
+    const re = new RegExp(pattern.source, flags);
+    for (;;) {
+        const m = re.exec(text);
+        if (m === null)
+            return;
+        yield { index: m.index, match: m };
+        if (m[0].length === 0)
+            re.lastIndex += 1;
+    }
+}
+/**
+ * The absolute `[start, end)` of one capture group of a match produced by
+ * `matchAll`, or `undefined` when the group did not participate.
+ *
+ * Group 0 is the whole match. Any other group's offsets come from the `d`
+ * flag's indices, never from searching for the group's text inside the match.
+ */
+export function groupSpan(match, group) {
+    const whole = match[0];
+    if (group === 0)
+        return { start: match.index, end: match.index + whole.length };
+    const span = match.indices?.[group];
+    if (!span)
+        return undefined;
+    return { start: span[0], end: span[1] };
+}