@bli-cockpit/telemetry-core 0.1.41 → 0.1.42

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);
+}

package/dist/secret-guards.d.ts

@@ -1,4 +1,3 @@
-import { z } from "zod";
 /**
  * Secret-like content + file-name guards shared by the local collector
  * (attribution, collection) and the dashboard commit-time guard. Keeping a
@@ -14,113 +13,30 @@ import { z } from "zod";
  * harvest cares most about). Value-shaped tokens (JWT, sk-, ghp_, PEM blocks,
  * AWS key ids, Slack/Linear/Langfuse tokens) are self-identifying and stay
  * blocked regardless of surrounding context.
- */
-/**
- * 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;
-export declare function isSecretLikePathSegment(value: string): boolean;
-export declare function containsSecretLikeContent(value: string): boolean;
-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.
+ * This file is the table of contents (BLI-3986). It is the rulebook's four
+ * questions in the order a scan asks them, one sibling each, and every public
+ * name is still importable from `./secret-guards.js` and from the package's
+ * entry:
  *
- * 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.
+ * - `secret-guards-path-rules.ts` — which file NAMES are never opened.
+ * - `secret-guards-content-rules.ts` — which CONTENT looks like a secret: the
+ *   credential-name fence, the assignment operator, the self-identifying value
+ *   shapes, in the order the detector tries them.
+ * - `secret-guards-masking.ts` — how a match is MASKED and which rule gets to
+ *   name it; the rule table's INDEX is the priority, and masking never drops a
+ *   file.
+ * - `secret-guards-metadata.ts` — what the scan RECORDS: the redaction receipt,
+ *   its per-status invariants, and the clean-scan builder.
  *
- * `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".
+ * Two things this family may not do quietly, both locked by
+ * `secret-guards-lock.test.ts`: change a rule's ORDER (the reason label a
+ * dashboard reads is the rule that won) and change a regex's source or flags
+ * (a false negative on somebody's laptop, invisible to a type checker).
  */
-export declare function scannedCleanRedactionMetadata(bytes: Uint8Array, options?: {
-    appliedBy?: RawEvidenceRedactionSource;
-    /** ISO-8601 with offset. Omitted entirely when absent (BLI-3290). */
-    appliedAt?: string;
-}): RawEvidenceRedactionMetadata;
-export interface SecretRedactionResult {
-    redacted: boolean;
-    text: string;
-    metadata: RawEvidenceRedactionMetadata | null;
-}
-export declare function redactSecretLikeContent(value: string, options?: {
-    appliedBy?: RawEvidenceRedactionSource;
-    redactedFields?: string[];
-}): SecretRedactionResult;
+export { SECRET_FILE_SEGMENT_PATTERN, isSecretLikePathSegment, } from "./secret-guards-path-rules.js";
+export { containsSecretLikeContent } from "./secret-guards-content-rules.js";
+export { redactSecretLikeContent } from "./secret-guards-masking.js";
+export type { SecretRedactionResult } from "./secret-guards-masking.js";
+export { RawEvidenceRedactionSourceSchema, RawEvidenceRedactionRuleCountSchema, RawEvidenceRedactionRangeSchema, RawEvidenceRedactionStatusSchema, RawEvidenceRedactionMetadataSchema, scannedCleanRedactionMetadata, } from "./secret-guards-metadata.js";
+export type { RawEvidenceRedactionSource, RawEvidenceRedactionRuleCount, RawEvidenceRedactionRange, RawEvidenceRedactionStatus, RawEvidenceRedactionMetadata, } from "./secret-guards-metadata.js";