@vouchington/utils 0.9.0 → 0.10.1

package/README.md

@@ -149,7 +149,15 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
   returned by identity. Callers provide `credentialHeaders`, an optional `redactUrl` hook (applied
   after query and fragment stripping, for path-borne credentials), and an opt-in `dropRequestBody`.
   URL-only and credential-only passes are exported separately, and `composeBeforeSend` accepts
-  either `ScrubOptions` or a final scrubber function. This package has no product defaults.
+  either `ScrubOptions` or a final scrubber function. `scrubEvent` also makes a recursive pass over
+  the whole event (`user`, `extra`, `contexts`, `tags`, `message`, exception values, breadcrumb
+  messages and data): values under sensitive keys (authorization, cookie, password, secret, token,
+  api/access key, email, dsn, credential) are replaced with `[Filtered]` (a plain object keeps its
+  keys), and every string has bearer/basic credentials, `token=` style assignments, and email
+  addresses redacted. `ScrubOptions` accepts additive `sensitiveKeyPatterns`, `textRedactors`, and
+  `maxDepth` (default 12, minimum `MIN_MAX_DEPTH` = 8; deeper containers become `[Filtered]`, cycles become `[Circular]`). Dates,
+  Errors, and other class instances are left as-is. `scrubDeep(value, options?)`, `redactText`, and
+  `scrubBreadcrumb(breadcrumb, options)` are exported for direct use.
 
 - `error-tree`: `formatErrorTree(error, { maxDepth?, maxNested? })` renders an error with its
   `errors[]` and `cause` chain, marks circular references, and reports how many nested errors the

package/dist/ai-moderation.d.mts

@@ -8,10 +8,10 @@ export type ModerationInputPart = {
         url: string;
     };
 };
-/** The fields of a moderation result this module reads. */
+/** The fields of a moderation result this module reads. A null category counts as not flagged. */
 export type ModerationResultLike = {
     flagged: boolean;
-    categories: Record<string, boolean>;
+    categories: Readonly<Record<string, boolean | null>>;
 };
 export type MessageSafetyViolation = {
     code: 'PROMPT_INJECTION';

package/dist/ai-moderation.mjs

@@ -7,7 +7,7 @@ export function buildModerationInput(texts, imageUrls = []) {
 }
 /** Names of the categories a result flagged. */
 export function getFlaggedCategories(result) {
-    return Object.entries(result.categories).flatMap(([category, flagged]) => flagged ? [category] : []);
+    return Object.entries(result.categories).flatMap(([category, flagged]) => flagged === true ? [category] : []);
 }
 /**
  * A violation naming every category flagged by any result, else null. Results line up with the

package/dist/observability-deep.d.mts

@@ -0,0 +1,26 @@
+export declare const EMAIL_REDACTED = "[Filtered email]";
+export declare const TOKEN_REDACTED = "[Filtered token]";
+export declare const CIRCULAR_VALUE = "[Circular]";
+export declare const DEFAULT_MAX_DEPTH = 12;
+/** Deep enough to keep `event.exception.values[].stacktrace.frames[]` objects intact. */
+export declare const MIN_MAX_DEPTH = 8;
+export interface DeepScrubOptions {
+    /** Extra key patterns, added to the defaults, whose values are replaced with the filtered marker. */
+    sensitiveKeyPatterns?: readonly RegExp[];
+    /** Extra text redactors, run after the defaults, applied to every string in the event. */
+    textRedactors?: ReadonlyArray<(text: string) => string>;
+    /**
+     * Containers nested deeper than this are replaced with the filtered marker. Default 12; at least
+     * `MIN_MAX_DEPTH` so event structure (fingerprint, exception frames) is never truncated.
+     */
+    maxDepth?: number;
+}
+/** Default text redactor: bearer/basic credentials, token assignments, then email addresses. */
+export declare function redactText(text: string): string;
+/**
+ * Recursively redact sensitive keys and free-text secrets. Plain objects and arrays are walked;
+ * Date, Error, and other class instances are returned as-is. Cycles become a marker, containers
+ * beyond `maxDepth` are replaced (fail closed), and unchanged input is returned by identity.
+ * Shared subtrees are scrubbed once per depth they are first reached at, not once per path.
+ */
+export declare function scrubDeep<T>(value: T, options?: DeepScrubOptions): T;

package/dist/observability-deep.mjs

@@ -0,0 +1,79 @@
+import { redactEmails } from './observability-email.mjs';
+import { SENSITIVE_VALUE, isRecord, transformRecord } from './observability-records.mjs';
+export const EMAIL_REDACTED = '[Filtered email]';
+export const TOKEN_REDACTED = '[Filtered token]';
+export const CIRCULAR_VALUE = '[Circular]';
+export const DEFAULT_MAX_DEPTH = 12;
+/** Deep enough to keep `event.exception.values[].stacktrace.frames[]` objects intact. */
+export const MIN_MAX_DEPTH = 8;
+const DEFAULT_KEY_PATTERN = /authorization|cookie|password|passwd|secret|token|api[_-]?key|access[_-]?key|email|dsn|credential/i;
+const AUTH_TOKEN_PATTERN = /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi;
+const TOKEN_ASSIGNMENT_PATTERN = /\b((?:access[_-]?token|refresh[_-]?token|id[_-]?token|token|secret|password|passwd|api[_-]?key)=)(?!\[Filtered token\])[^&\s]+/gi;
+/** Default text redactor: bearer/basic credentials, token assignments, then email addresses. */
+export function redactText(text) {
+    return redactEmails(text
+        .replace(AUTH_TOKEN_PATTERN, `$1 ${TOKEN_REDACTED}`)
+        .replace(TOKEN_ASSIGNMENT_PATTERN, `$1${TOKEN_REDACTED}`), EMAIL_REDACTED);
+}
+/** Stateless copy of a pattern, so `g` and `y` flags cannot make `test` order-dependent. */
+function stateless(pattern) {
+    return new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''));
+}
+/** Redact a sensitive value; a plain object keeps its keys with every value filtered. */
+function redactValue(value) {
+    return isRecord(value) && isPlain(value)
+        ? transformRecord(value, () => SENSITIVE_VALUE)
+        : SENSITIVE_VALUE;
+}
+function isPlain(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Recursively redact sensitive keys and free-text secrets. Plain objects and arrays are walked;
+ * Date, Error, and other class instances are returned as-is. Cycles become a marker, containers
+ * beyond `maxDepth` are replaced (fail closed), and unchanged input is returned by identity.
+ * Shared subtrees are scrubbed once per depth they are first reached at, not once per path.
+ */
+export function scrubDeep(value, options = {}) {
+    const keyPatterns = [DEFAULT_KEY_PATTERN, ...(options.sensitiveKeyPatterns ?? []).map(stateless)];
+    const redactors = [redactText, ...(options.textRedactors ?? [])];
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    if (!Number.isInteger(maxDepth) || maxDepth < MIN_MAX_DEPTH) {
+        throw new RangeError(`maxDepth must be an integer of at least ${MIN_MAX_DEPTH}`);
+    }
+    const ancestors = new WeakSet();
+    // A result computed at a shallower depth had more budget, so it is reusable at deeper depths.
+    const done = new WeakMap();
+    const isSensitiveKey = (key) => keyPatterns.some((pattern) => pattern.test(key));
+    function walkArray(input, depth) {
+        const mapped = input.map((child) => walk(child, depth + 1));
+        return mapped.some((child, index) => !Object.is(child, input[index])) ? mapped : input;
+    }
+    function walk(input, depth) {
+        if (typeof input === 'string')
+            return redactors.reduce((text, redact) => redact(text), input);
+        const isArray = Array.isArray(input);
+        if (!isArray && !(isRecord(input) && isPlain(input)))
+            return input;
+        if (ancestors.has(input))
+            return CIRCULAR_VALUE;
+        if (depth >= maxDepth)
+            return SENSITIVE_VALUE;
+        const cached = done.get(input);
+        if (cached && cached.depth <= depth)
+            return cached.result;
+        ancestors.add(input);
+        try {
+            const result = isArray
+                ? walkArray(input, depth)
+                : transformRecord(input, (key, child) => isSensitiveKey(key) ? redactValue(child) : walk(child, depth + 1));
+            done.set(input, { depth, result });
+            return result;
+        }
+        finally {
+            ancestors.delete(input);
+        }
+    }
+    return walk(value, 0);
+}

package/dist/observability-email.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Replace email addresses with `replacement` in linear time. Matching starts from each `@` and
+ * expands over local-part and domain characters, which never include `@`, so no character is
+ * scanned more than a constant number of times (unlike a backtracking regular expression).
+ */
+export declare function redactEmails(text: string, replacement: string): string;

package/dist/observability-email.mjs

@@ -0,0 +1,51 @@
+const LOCAL_CHAR = /[A-Za-z0-9._%+-]/;
+const DOMAIN_CHAR = /[A-Za-z0-9.-]/;
+const LETTER = /[A-Za-z]/;
+const WORD_CHAR = /\w/;
+/** End of the longest `label.tld` domain in `text[from, end)`, or -1; one forward pass. */
+function domainEnd(text, from, end) {
+    let best = -1;
+    let letterRunStart = from;
+    for (let index = from; index < end; index++) {
+        if (!LETTER.test(text[index])) {
+            letterRunStart = index + 1;
+            continue;
+        }
+        const after = index + 1;
+        if (after - letterRunStart >= 2 &&
+            letterRunStart - 1 > from &&
+            text[letterRunStart - 1] === '.' &&
+            !WORD_CHAR.test(text[after] ?? '')) {
+            best = after;
+        }
+    }
+    return best;
+}
+/**
+ * Replace email addresses with `replacement` in linear time. Matching starts from each `@` and
+ * expands over local-part and domain characters, which never include `@`, so no character is
+ * scanned more than a constant number of times (unlike a backtracking regular expression).
+ */
+export function redactEmails(text, replacement) {
+    let output = '';
+    let copied = 0;
+    let at = text.indexOf('@');
+    while (at !== -1) {
+        let start = at;
+        while (start > copied && LOCAL_CHAR.test(text[start - 1]))
+            start--;
+        let end = at + 1;
+        while (end < text.length && DOMAIN_CHAR.test(text[end]))
+            end++;
+        const domain = domainEnd(text, at + 1, end);
+        if (start < at && domain !== -1) {
+            output += text.slice(copied, start) + replacement;
+            copied = domain;
+            at = text.indexOf('@', domain);
+        }
+        else {
+            at = text.indexOf('@', at + 1);
+        }
+    }
+    return output + text.slice(copied);
+}

package/dist/observability-event.d.mts

@@ -1,5 +1,6 @@
+import { type DeepScrubOptions } from './observability-deep.mts';
 import { type UrlScrubOptions } from './observability-url.mts';
-export interface ScrubOptions extends UrlScrubOptions {
+export interface ScrubOptions extends UrlScrubOptions, DeepScrubOptions {
     /** Header names (case-insensitive) whose values are replaced with the filtered marker. */
     credentialHeaders: readonly string[];
     /** Also drop `request.data` and the `http.request.body.data` attribute. Defaults to false. */
@@ -20,7 +21,14 @@ export declare function scrubRequest<T extends object>(request: T | undefined, o
 export declare function scrubBreadcrumbs<T extends {
     data?: Record<string, unknown>;
 }>(breadcrumbs: T[] | undefined, options: ScrubOptions): T[] | undefined;
-/** Scrub an event's request and breadcrumbs; the input event is returned when nothing changed. */
+/** Scrub one breadcrumb: its `data` like span attributes, then every key and string recursively. */
+export declare function scrubBreadcrumb<T extends {
+    data?: Record<string, unknown>;
+}>(breadcrumb: T, options: ScrubOptions): T;
+/**
+ * Scrub an event: request and breadcrumb data first, then a recursive pass over the whole event
+ * (`user`, `extra`, `contexts`, `tags`, messages, exception values). Unchanged input is returned.
+ */
 export declare function scrubEvent<T extends ObservableEvent>(event: T, options: ScrubOptions): T;
 type BeforeSendResult<T> = T | null | PromiseLike<T | null>;
 /**

package/dist/observability-event.mjs

@@ -1,4 +1,5 @@
 import { dropRequestBody, dropSpanRequestBody } from './observability-body.mjs';
+import { scrubDeep } from './observability-deep.mjs';
 import { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mjs';
 import { scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, } from './observability-url.mjs';
 export function scrubHeaders(headers, credentialHeaders, redactUrl) {
@@ -27,17 +28,26 @@ export function scrubBreadcrumbs(breadcrumbs, options) {
         ? result
         : breadcrumbs;
 }
-/** Scrub an event's request and breadcrumbs; the input event is returned when nothing changed. */
+/** Scrub one breadcrumb: its `data` like span attributes, then every key and string recursively. */
+export function scrubBreadcrumb(breadcrumb, options) {
+    const [scrubbed] = scrubBreadcrumbs([breadcrumb], options);
+    return scrubDeep(scrubbed, options);
+}
+/**
+ * Scrub an event: request and breadcrumb data first, then a recursive pass over the whole event
+ * (`user`, `extra`, `contexts`, `tags`, messages, exception values). Unchanged input is returned.
+ */
 export function scrubEvent(event, options) {
     const request = scrubRequest(event.request, options);
     const breadcrumbs = scrubBreadcrumbs(event.breadcrumbs, options);
-    if (request === event.request && breadcrumbs === event.breadcrumbs)
-        return event;
-    return {
-        ...event,
-        ...(request === event.request ? {} : { request }),
-        ...(breadcrumbs === event.breadcrumbs ? {} : { breadcrumbs }),
-    };
+    const base = request === event.request && breadcrumbs === event.breadcrumbs
+        ? event
+        : {
+            ...event,
+            ...(request === event.request ? {} : { request }),
+            ...(breadcrumbs === event.breadcrumbs ? {} : { breadcrumbs }),
+        };
+    return scrubDeep(base, options);
 }
 function isPromiseLike(value) {
     if (value === null || (typeof value !== 'object' && typeof value !== 'function'))

package/dist/observability.d.mts

@@ -1,6 +1,7 @@
 export { SENSITIVE_VALUE } from './observability-records.mts';
 export { createSpikeWindowTracker, DEFAULT_MAX_SPIKE_FINGERPRINTS, type SpikeWindowTracker, } from './spike-window.mts';
-export { composeBeforeSend, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, type ObservableEvent, type ScrubOptions, } from './observability-event.mts';
+export { CIRCULAR_VALUE, DEFAULT_MAX_DEPTH, EMAIL_REDACTED, MIN_MAX_DEPTH, TOKEN_REDACTED, redactText, scrubDeep, type DeepScrubOptions, } from './observability-deep.mts';
+export { composeBeforeSend, scrubBreadcrumb, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, type ObservableEvent, type ScrubOptions, } from './observability-event.mts';
 export { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mts';
 export { SCRUBBED_URL_ATTRIBUTE_KEYS, URL_ATTRIBUTE_KEYS, URL_COMPONENT_ATTRIBUTE_KEYS, scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, scrubUrlValue, stripUrlQueryAndFragment, type UrlScrubOptions, } from './observability-url.mts';
 export { REQUEST_BODY_SPAN_ATTRIBUTE, dropRequestBody, dropSpanRequestBody, } from './observability-body.mts';

package/dist/observability.mjs

@@ -1,6 +1,7 @@
 export { SENSITIVE_VALUE } from './observability-records.mjs';
 export { createSpikeWindowTracker, DEFAULT_MAX_SPIKE_FINGERPRINTS, } from './spike-window.mjs';
-export { composeBeforeSend, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, } from './observability-event.mjs';
+export { CIRCULAR_VALUE, DEFAULT_MAX_DEPTH, EMAIL_REDACTED, MIN_MAX_DEPTH, TOKEN_REDACTED, redactText, scrubDeep, } from './observability-deep.mjs';
+export { composeBeforeSend, scrubBreadcrumb, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, } from './observability-event.mjs';
 export { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mjs';
 export { SCRUBBED_URL_ATTRIBUTE_KEYS, URL_ATTRIBUTE_KEYS, URL_COMPONENT_ATTRIBUTE_KEYS, scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, scrubUrlValue, stripUrlQueryAndFragment, } from './observability-url.mjs';
 export { REQUEST_BODY_SPAN_ATTRIBUTE, dropRequestBody, dropSpanRequestBody, } from './observability-body.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {