@bli-cockpit/telemetry-core 0.1.41 → 0.1.43

package/dist/secret-guards-masking.js

@@ -0,0 +1,240 @@
+import { SECRET_ASSIGNMENT_SOURCE, SECRET_LIKE_CONTENT_PATTERNS, SECRET_NAME_MATCH_SOURCE, } from "./secret-guards-content-rules.js";
+import { RawEvidenceRedactionMetadataSchema } from "./secret-guards-metadata.js";
+// Same fence as the detector (BLI-3116) — the two must agree or a prefixed
+// name would be detected and then left unredacted, which costs whole sessions
+// (see findSecretRedactionMatches).
+const SECRET_ASSIGNMENT_REDACTION_PATTERN = new RegExp(`(${SECRET_NAME_MATCH_SOURCE}${SECRET_ASSIGNMENT_SOURCE})([A-Za-z0-9_./+=-]{12,})`, "gi");
+const SECRET_REDACTION_RULES = [
+    {
+        ruleId: "credential_assignment",
+        pattern: SECRET_ASSIGNMENT_REDACTION_PATTERN,
+        secretGroup: 2,
+    },
+    {
+        // The body stops at `{`, and excludes nothing else (BLI-4168).
+        //
+        // `[\s\S]*?` used to sit here, which gave the rule no notion of where one
+        // record ends. Transcripts are JSONL, so a key whose `-----END-----` never
+        // arrived — a truncated write, a killed session — paired with the next
+        // `-----END-----` many records later and collapsed everything between into
+        // one `[REDACTED:private_key_block]`. That over-masks: nothing leaked, but
+        // a session's worth of legitimate records was destroyed silently, because
+        // a redaction looks exactly like the guard working.
+        //
+        // `{` is the JSONL record boundary: it is what opens the next record, and a
+        // PEM body is base64, so it cannot appear inside a key. This is JSONL-record
+        // scoping specifically, and JSONL is the ONLY shape it fixes. The same
+        // function also receives plain text — a raw `.pem`, a git diff, a log tail,
+        // YAML, CSV, a markdown note — where `{` is not a boundary at all. There it
+        // splits two ways. Where a `{` does happen to fall between the markers it
+        // merely ends the match early, leaving a narrow residue; that residue is the
+        // price of the scope. Where NO `{` falls between an unterminated BEGIN and a
+        // later stray END — the ordinary case for every one of those formats — the
+        // match is still unbounded and the original over-masking is FULLY ALIVE.
+        // Measured on six shapes, each an unterminated key, then a bystander record,
+        // then a stray END: JSONL preserved the bystander and the other five
+        // destroyed it. This rule does not fix that case. BLI-4216 carries it.
+        //
+        // It MUST stay a DENYLIST of that one character. An allowlist of the PEM
+        // alphabet was tried here and reverted the same day: one character outside
+        // the class anywhere between BEGIN and END — a `.`, a `[info] ` log prefix,
+        // an `N | ` gutter, an ANSI reset, a diff hunk header — makes the whole
+        // rule fail to match, and the body is then left in PLAINTEXT while
+        // `private_key_header` masks only the BEGIN line and
+        // `containsSecretLikeContent` reports the residue clean, so
+        // `secret_redaction_failed` never fires. That is a leak, and a leak is
+        // strictly worse than the over-masking this rule exists to fix. The
+        // leak-direction tests in `secret-guards.test.ts` pin it.
+        ruleId: "private_key_block",
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[^{]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    },
+    {
+        ruleId: "private_key_header",
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
+    },
+    {
+        ruleId: "bearer_token",
+        pattern: /\b(Bearer\s+)([A-Za-z0-9._~+/=-]{16,})/gi,
+        secretGroup: 2,
+    },
+    {
+        ruleId: "jwt",
+        pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+    },
+    {
+        ruleId: "stripe_token",
+        pattern: /\b(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{16,}/g,
+    },
+    {
+        ruleId: "openai_token",
+        pattern: /\bsk-[A-Za-z0-9_-]{16,}/g,
+    },
+    {
+        ruleId: "github_token",
+        pattern: /\b(?:gh[pousr]_[A-Za-z0-9_]{16,}|github_pat_[A-Za-z0-9_]{20,})/g,
+    },
+    {
+        ruleId: "linear_token",
+        pattern: /\blin_api_[A-Za-z0-9]{16,}/g,
+    },
+    {
+        ruleId: "supabase_secret_token",
+        pattern: /\bsb_secret_[A-Za-z0-9_]{16,}/g,
+    },
+    {
+        ruleId: "slack_token",
+        pattern: /\bxox[baprs]-[A-Za-z0-9-]{16,}/g,
+    },
+    {
+        ruleId: "aws_access_key_id",
+        pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+    },
+    {
+        ruleId: "langfuse_token",
+        pattern: /\b(?:pk|sk)-lf-[A-Za-z0-9_-]{16,}\b/gi,
+    },
+    {
+        ruleId: "mem0_token",
+        pattern: /\bm0[-_][A-Za-z0-9_-]{16,}\b/gi,
+    },
+];
+/**
+ * Mask every secret-shaped span and keep the rest of the text, because a
+ * session is never dropped for carrying one: this returns the redacted bytes
+ * plus the receipt that says which rules fired, where, and how much was
+ * replaced.
+ */
+export function redactSecretLikeContent(value, options = {}) {
+    const matches = findSecretRedactionMatches(value);
+    if (matches.length === 0) {
+        return { redacted: false, text: value, metadata: null };
+    }
+    let text = "";
+    let cursor = 0;
+    const ruleCounts = new Map();
+    for (const match of matches) {
+        text += value.slice(cursor, match.start);
+        text += `[REDACTED:${match.ruleId}]`;
+        cursor = match.end;
+        const existing = ruleCounts.get(match.ruleId) ?? {
+            rule_id: match.ruleId,
+            match_count: 0,
+            redacted_char_count: 0,
+        };
+        existing.match_count += 1;
+        existing.redacted_char_count += match.end - match.start;
+        ruleCounts.set(match.ruleId, existing);
+    }
+    text += value.slice(cursor);
+    const metadata = RawEvidenceRedactionMetadataSchema.parse({
+        schema_version: "raw-evidence-redaction.v1",
+        status: "sanitized",
+        mode: "deterministic_text_replacement",
+        applied_by: [options.appliedBy ?? "local_collector"],
+        rule_counts: [...ruleCounts.values()].sort((a, b) => a.rule_id.localeCompare(b.rule_id)),
+        secret_like_match_count: matches.length,
+        redacted_fields: options.redactedFields ?? [],
+        redacted_ranges: matches.slice(0, 200).map((match) => ({
+            start: match.start,
+            end: match.end,
+            rule_id: match.ruleId,
+        })),
+    });
+    return { redacted: true, text, metadata };
+}
+/**
+ * Every region the detector considers a secret, redacted — precisely where a
+ * rule can pinpoint the value, coarsely where none can.
+ *
+ * `containsSecretLikeContent` and `SECRET_REDACTION_RULES` are two lists that
+ * have to agree, and nothing used to make them. When the detector matched and
+ * no rule produced a range, `redactSecretLikeContent` reported
+ * `redacted: false`, and the caller dropped the entire session file
+ * (`secret_like_content_guard`). Drift between the lists cost whole sessions:
+ * 78 fleet-wide as of 2026-08-14, 3 of Viet's 17 Claude sessions.
+ *
+ * The two lists can still drift — regexes are like that — but drift now costs
+ * precision instead of evidence. A detector hit with no matching rule redacts
+ * the whole matched span, so `redactSecretLikeContent` always reports the
+ * redaction it performed and the transcript survives with the value removed.
+ */
+function findSecretRedactionMatches(value) {
+    const accepted = acceptNonOverlapping(secretRuleCandidates(value));
+    const uncovered = detectorFallbackCandidates(value).filter((candidate) => !overlapsAny(candidate, accepted));
+    if (uncovered.length === 0)
+        return accepted;
+    return acceptNonOverlapping([...accepted, ...uncovered]);
+}
+function secretRuleCandidates(value) {
+    const candidates = [];
+    SECRET_REDACTION_RULES.forEach((rule, priority) => {
+        const pattern = cloneGlobalPattern(rule.pattern);
+        for (const match of value.matchAll(pattern)) {
+            const fullMatch = match[0];
+            const matchIndex = match.index;
+            if (!fullMatch || matchIndex === undefined)
+                continue;
+            const secret = rule.secretGroup ? match[rule.secretGroup] : fullMatch;
+            if (!secret)
+                continue;
+            const relativeStart = fullMatch.indexOf(secret);
+            if (relativeStart < 0)
+                continue;
+            candidates.push({
+                start: matchIndex + relativeStart,
+                end: matchIndex + relativeStart + secret.length,
+                ruleId: rule.ruleId,
+                priority,
+            });
+        }
+    });
+    return candidates;
+}
+/**
+ * Ranked below every real rule, so a rule that can name the credential always
+ * wins and the coarse span is only used where nothing else reached.
+ */
+function detectorFallbackCandidates(value) {
+    const candidates = [];
+    const basePriority = SECRET_REDACTION_RULES.length;
+    SECRET_LIKE_CONTENT_PATTERNS.forEach((pattern, offset) => {
+        for (const match of value.matchAll(cloneGlobalPattern(pattern))) {
+            const fullMatch = match[0];
+            const matchIndex = match.index;
+            if (!fullMatch || matchIndex === undefined)
+                continue;
+            candidates.push({
+                start: matchIndex,
+                end: matchIndex + fullMatch.length,
+                ruleId: "unnamed_secret_shape",
+                priority: basePriority + offset,
+            });
+        }
+    });
+    return candidates;
+}
+function overlapsAny(candidate, accepted) {
+    return accepted.some((other) => candidate.start < other.end && other.start < candidate.end);
+}
+function acceptNonOverlapping(candidates) {
+    const ordered = [...candidates].sort((a, b) => {
+        if (a.start !== b.start)
+            return a.start - b.start;
+        if (a.priority !== b.priority)
+            return a.priority - b.priority;
+        return b.end - b.start - (a.end - a.start);
+    });
+    const accepted = [];
+    let lastEnd = -1;
+    for (const candidate of ordered) {
+        if (candidate.start < lastEnd)
+            continue;
+        accepted.push(candidate);
+        lastEnd = candidate.end;
+    }
+    return accepted;
+}
+function cloneGlobalPattern(pattern) {
+    const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+    return new RegExp(pattern.source, flags);
+}

package/dist/secret-guards-metadata.d.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+/**
+ * What a secret scan RECORDS: the redaction receipt every uploaded object
+ * carries, and the one builder of the clean half of it.
+ *
+ * Owned by `secret-guards.ts` (BLI-3986); the rules that produce these records
+ * live in `secret-guards-content-rules.ts` and `secret-guards-masking.ts`.
+ * Nothing here decides what a secret IS — it decides what a reader downstream
+ * is told about a scan that already ran, which is why the per-status
+ * invariants below are the load-bearing part: a record that claims a
+ * sanitization that never happened is worse than a missing record.
+ */
+export declare const RawEvidenceRedactionSourceSchema: z.ZodEnum<{
+    local_collector: "local_collector";
+    server_commit: "server_commit";
+    legacy_upload: "legacy_upload";
+}>;
+export type RawEvidenceRedactionSource = z.infer<typeof RawEvidenceRedactionSourceSchema>;
+export declare const RawEvidenceRedactionRuleCountSchema: z.ZodObject<{
+    rule_id: z.ZodString;
+    match_count: z.ZodNumber;
+    redacted_char_count: z.ZodNumber;
+}, z.core.$strict>;
+export type RawEvidenceRedactionRuleCount = z.infer<typeof RawEvidenceRedactionRuleCountSchema>;
+export declare const RawEvidenceRedactionRangeSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    rule_id: z.ZodString;
+}, z.core.$strict>;
+export type RawEvidenceRedactionRange = z.infer<typeof RawEvidenceRedactionRangeSchema>;
+/**
+ * The verdict of a secret scan — NOT "did the bytes change" (BLI-3277).
+ *
+ * `sanitized` means the scan matched and the uploaded bytes differ from what was
+ * read. `scanned_clean` means the same scan ran over the same bytes and matched
+ * nothing, so the uploaded bytes are the original ones. The second value exists
+ * because every reader downstream asks "was this scanned?", and for 70% of
+ * transcripts — the ones with no secret in them — the honest answer used to be
+ * an absent record, which reads identically to "nobody ever looked".
+ */
+export declare const RawEvidenceRedactionStatusSchema: z.ZodEnum<{
+    sanitized: "sanitized";
+    scanned_clean: "scanned_clean";
+}>;
+export type RawEvidenceRedactionStatus = z.infer<typeof RawEvidenceRedactionStatusSchema>;
+export declare const RawEvidenceRedactionMetadataSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
+    status: z.ZodEnum<{
+        sanitized: "sanitized";
+        scanned_clean: "scanned_clean";
+    }>;
+    mode: z.ZodLiteral<"deterministic_text_replacement">;
+    applied_by: z.ZodArray<z.ZodEnum<{
+        local_collector: "local_collector";
+        server_commit: "server_commit";
+        legacy_upload: "legacy_upload";
+    }>>;
+    rule_counts: z.ZodArray<z.ZodObject<{
+        rule_id: z.ZodString;
+        match_count: z.ZodNumber;
+        redacted_char_count: z.ZodNumber;
+    }, z.core.$strict>>;
+    secret_like_match_count: z.ZodNumber;
+    redacted_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    redacted_ranges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        rule_id: z.ZodString;
+    }, z.core.$strict>>>;
+    original_content_hash_sha256: z.ZodOptional<z.ZodString>;
+    sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
+    original_byte_size: z.ZodOptional<z.ZodNumber>;
+    sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+    applied_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type RawEvidenceRedactionMetadata = z.infer<typeof RawEvidenceRedactionMetadataSchema>;
+/**
+ * The receipt for a file the scan cleared (BLI-3277, moved here by BLI-3280).
+ *
+ * Same schema, same `mode` — the deterministic ruleset is what ran — with the
+ * verdict `scanned_clean` and zero of everything else. The content fields are
+ * the point: an evidence ref is only readable downstream when its redaction
+ * record hashes the bytes that are actually in the bucket, and for a clean file
+ * those are the original bytes, so both halves carry the same digest and size.
+ *
+ * It lives in telemetry-core rather than in the collector because two callers
+ * now build this exact record and they must never drift: the collector writes
+ * it at upload time, and the BLI-3280 operator backfill writes it onto refs
+ * that were stored before the receipt existed. Both must satisfy the same
+ * `sanitized_content_hash_sha256 === content_hash_sha256` /
+ * `sanitized_byte_size === byte_size` equality the digest reader checks, and a
+ * second copy of this function is a second chance to get that wrong.
+ *
+ * `appliedBy` is who ran the scan, and it is not decoration: a backfill passes
+ * `legacy_upload` so a reader can tell "the collector scanned this before it
+ * uploaded" apart from "an operator scanned the stored bytes afterwards".
+ */
+export declare function scannedCleanRedactionMetadata(bytes: Uint8Array, options?: {
+    appliedBy?: RawEvidenceRedactionSource;
+    /** ISO-8601 with offset. Omitted entirely when absent (BLI-3290). */
+    appliedAt?: string;
+}): RawEvidenceRedactionMetadata;

package/dist/secret-guards-metadata.js

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { IsoDateTimeSchema } from "./common.js";
+/**
+ * What a secret scan RECORDS: the redaction receipt every uploaded object
+ * carries, and the one builder of the clean half of it.
+ *
+ * Owned by `secret-guards.ts` (BLI-3986); the rules that produce these records
+ * live in `secret-guards-content-rules.ts` and `secret-guards-masking.ts`.
+ * Nothing here decides what a secret IS — it decides what a reader downstream
+ * is told about a scan that already ran, which is why the per-status
+ * invariants below are the load-bearing part: a record that claims a
+ * sanitization that never happened is worse than a missing record.
+ */
+export const RawEvidenceRedactionSourceSchema = z.enum([
+    "local_collector",
+    "server_commit",
+    "legacy_upload",
+]);
+export const RawEvidenceRedactionRuleCountSchema = z
+    .object({
+    rule_id: z.string().trim().min(1).max(80),
+    match_count: z.number().int().nonnegative(),
+    redacted_char_count: z.number().int().nonnegative(),
+})
+    .strict();
+export const RawEvidenceRedactionRangeSchema = z
+    .object({
+    start: z.number().int().nonnegative(),
+    end: z.number().int().positive(),
+    rule_id: z.string().trim().min(1).max(80),
+})
+    .strict()
+    .superRefine((range, context) => {
+    if (range.end <= range.start) {
+        context.addIssue({
+            code: "custom",
+            message: "redaction range end must be greater than start",
+            path: ["end"],
+        });
+    }
+});
+/**
+ * The verdict of a secret scan — NOT "did the bytes change" (BLI-3277).
+ *
+ * `sanitized` means the scan matched and the uploaded bytes differ from what was
+ * read. `scanned_clean` means the same scan ran over the same bytes and matched
+ * nothing, so the uploaded bytes are the original ones. The second value exists
+ * because every reader downstream asks "was this scanned?", and for 70% of
+ * transcripts — the ones with no secret in them — the honest answer used to be
+ * an absent record, which reads identically to "nobody ever looked".
+ */
+export const RawEvidenceRedactionStatusSchema = z.enum([
+    "sanitized",
+    "scanned_clean",
+]);
+export const RawEvidenceRedactionMetadataSchema = z
+    .object({
+    schema_version: z.literal("raw-evidence-redaction.v1"),
+    status: RawEvidenceRedactionStatusSchema,
+    mode: z.literal("deterministic_text_replacement"),
+    applied_by: z.array(RawEvidenceRedactionSourceSchema).min(1),
+    rule_counts: z.array(RawEvidenceRedactionRuleCountSchema),
+    secret_like_match_count: z.number().int().nonnegative(),
+    redacted_fields: z.array(z.string().trim().min(1).max(160)).default([]),
+    redacted_ranges: z.array(RawEvidenceRedactionRangeSchema).max(200).default([]),
+    original_content_hash_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    sanitized_content_hash_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    original_byte_size: z.number().int().nonnegative().optional(),
+    sanitized_byte_size: z.number().int().nonnegative().optional(),
+    /**
+     * When the scan ran, ISO-8601 with an offset (BLI-3290).
+     *
+     * Optional, and it stays optional: every receipt written before this field
+     * existed is still valid, and the collector does not stamp it — at upload
+     * time the ref's own `received_at` already answers "when". It exists for
+     * receipts written over bytes that were stored long ago, where the ref's
+     * timestamps describe the ORIGINAL upload and nothing in the record would
+     * otherwise say when an operator re-scanned or re-masked the object.
+     */
+    applied_at: IsoDateTimeSchema.optional(),
+})
+    .strict()
+    // The per-status invariants the old `z.literal("sanitized")` + `.min(1)` +
+    // `.positive()` shape enforced structurally. They still hold for a sanitized
+    // record; a clean one has to prove the opposite — no rule fired, no range was
+    // replaced, no field was masked, and the bytes came out the way they went in.
+    .superRefine((metadata, context) => {
+    if (metadata.status === "sanitized") {
+        if (metadata.rule_counts.length === 0) {
+            context.addIssue({
+                code: "custom",
+                message: "a sanitized redaction must name at least one rule",
+                path: ["rule_counts"],
+            });
+        }
+        if (metadata.secret_like_match_count < 1) {
+            context.addIssue({
+                code: "custom",
+                message: "a sanitized redaction must count at least one match",
+                path: ["secret_like_match_count"],
+            });
+        }
+        return;
+    }
+    if (metadata.rule_counts.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot name a rule that fired",
+            path: ["rule_counts"],
+        });
+    }
+    if (metadata.secret_like_match_count !== 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot count a match",
+            path: ["secret_like_match_count"],
+        });
+    }
+    if (metadata.redacted_ranges.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot redact a range",
+            path: ["redacted_ranges"],
+        });
+    }
+    if (metadata.redacted_fields.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot redact a field",
+            path: ["redacted_fields"],
+        });
+    }
+    if (metadata.original_content_hash_sha256 !== undefined &&
+        metadata.sanitized_content_hash_sha256 !== undefined &&
+        metadata.original_content_hash_sha256 !==
+            metadata.sanitized_content_hash_sha256) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot change the content hash",
+            path: ["sanitized_content_hash_sha256"],
+        });
+    }
+    if (metadata.original_byte_size !== undefined &&
+        metadata.sanitized_byte_size !== undefined &&
+        metadata.original_byte_size !== metadata.sanitized_byte_size) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot change the byte size",
+            path: ["sanitized_byte_size"],
+        });
+    }
+});
+/**
+ * The receipt for a file the scan cleared (BLI-3277, moved here by BLI-3280).
+ *
+ * Same schema, same `mode` — the deterministic ruleset is what ran — with the
+ * verdict `scanned_clean` and zero of everything else. The content fields are
+ * the point: an evidence ref is only readable downstream when its redaction
+ * record hashes the bytes that are actually in the bucket, and for a clean file
+ * those are the original bytes, so both halves carry the same digest and size.
+ *
+ * It lives in telemetry-core rather than in the collector because two callers
+ * now build this exact record and they must never drift: the collector writes
+ * it at upload time, and the BLI-3280 operator backfill writes it onto refs
+ * that were stored before the receipt existed. Both must satisfy the same
+ * `sanitized_content_hash_sha256 === content_hash_sha256` /
+ * `sanitized_byte_size === byte_size` equality the digest reader checks, and a
+ * second copy of this function is a second chance to get that wrong.
+ *
+ * `appliedBy` is who ran the scan, and it is not decoration: a backfill passes
+ * `legacy_upload` so a reader can tell "the collector scanned this before it
+ * uploaded" apart from "an operator scanned the stored bytes afterwards".
+ */
+export function scannedCleanRedactionMetadata(bytes, options = {}) {
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    return {
+        schema_version: "raw-evidence-redaction.v1",
+        status: "scanned_clean",
+        mode: "deterministic_text_replacement",
+        applied_by: [options.appliedBy ?? "local_collector"],
+        rule_counts: [],
+        secret_like_match_count: 0,
+        redacted_fields: [],
+        redacted_ranges: [],
+        original_content_hash_sha256: digest,
+        sanitized_content_hash_sha256: digest,
+        original_byte_size: bytes.byteLength,
+        sanitized_byte_size: bytes.byteLength,
+        ...(options.appliedAt === undefined ? {} : { applied_at: options.appliedAt }),
+    };
+}

package/dist/secret-guards-path-rules.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Which file NAMES are never opened at all.
+ *
+ * Owned by `secret-guards.ts` (BLI-3986). This is the cheapest of the guard's
+ * questions and the only one answered without reading a byte of content, which
+ * is why it stays broad and why it is asked first: the collector's attribution
+ * pass, its collection pass and the path walk all share this one definition
+ * instead of re-declaring a pattern each.
+ */
+/**
+ * File-path / file-name segments that must never be read at all. This is a
+ * NAME matcher (it never reads file content), so it stays broad: a file called
+ * `service-role.json` or a dotenv file is skipped on its name alone. The
+ * collector imports this instead of re-declaring it, so attribution,
+ * collection, and the path walk share one definition.
+ */
+export declare const SECRET_FILE_SEGMENT_PATTERN: RegExp;
+/**
+ * Does this path segment name a file the collector must not open? One place
+ * asks the pattern so every caller skips the same names.
+ */
+export declare function isSecretLikePathSegment(value: string): boolean;

package/dist/secret-guards-path-rules.js

@@ -0,0 +1,24 @@
+/**
+ * Which file NAMES are never opened at all.
+ *
+ * Owned by `secret-guards.ts` (BLI-3986). This is the cheapest of the guard's
+ * questions and the only one answered without reading a byte of content, which
+ * is why it stays broad and why it is asked first: the collector's attribution
+ * pass, its collection pass and the path walk all share this one definition
+ * instead of re-declaring a pattern each.
+ */
+/**
+ * File-path / file-name segments that must never be read at all. This is a
+ * NAME matcher (it never reads file content), so it stays broad: a file called
+ * `service-role.json` or a dotenv file is skipped on its name alone. The
+ * collector imports this instead of re-declaring it, so attribution,
+ * collection, and the path walk share one definition.
+ */
+export const SECRET_FILE_SEGMENT_PATTERN = /(^|[/\\])(?:\.env(?:\..*)?|.*(?:secret|credential|private[_-]?key|service[_-]?role).*)$/i;
+/**
+ * Does this path segment name a file the collector must not open? One place
+ * asks the pattern so every caller skips the same names.
+ */
+export function isSecretLikePathSegment(value) {
+    return SECRET_FILE_SEGMENT_PATTERN.test(value);
+}