@debugbundle/sdk-react-native 1.3.0 → 3.0.0

package/src/client.ts

@@ -1,6 +1,7 @@
 import { getNativeModule, degradedNativeState, safeNativeCall } from "./native.js";
 import { applyBeforeSend } from "./before-send.js";
 import { defaultRedactFields, DEFAULT_HEADER_ALLOWLIST, sanitizeHeaders, sanitizeValue } from "./redaction.js";
+import { sanitizeTelemetry } from "./privacy-telemetry.js";
 import type {
   DebugBundleCaptureContext,
   DebugBundleClient,
@@ -18,7 +19,14 @@ import type {
 } from "./types.js";
 
 const SDK_NAME = "@debugbundle/sdk-react-native" as const;
-const DEFAULT_SDK_VERSION = "1.3.0";
+const DEFAULT_SDK_VERSION = "3.0.0";
+const MAX_PENDING_NATIVE_CALLS = 256;
+const MAX_PENDING_LOW_PRIORITY_CALLS = 224;
+const MAX_PENDING_NATIVE_BYTES = 4 * 1024 * 1024;
+const MAX_PENDING_LOW_PRIORITY_BYTES = 3 * 1024 * 1024;
+const MAX_NATIVE_EVENT_BYTES = 64 * 1024;
+const MAX_CONTEXT_FIELDS = 50;
+const MAX_CONTEXT_KEY_LENGTH = 128;
 const LOG_LEVELS: Record<DebugBundleLogLevel, number> = {
   debug: 10,
   info: 20,
@@ -27,6 +35,39 @@ const LOG_LEVELS: Record<DebugBundleLogLevel, number> = {
   critical: 50
 };
 
+function protectEventFields(
+  event: DebugBundleEventEnvelope,
+  additionalKeys: string[]
+): DebugBundleEventEnvelope | null {
+  // Preserve typed identities only when their scalar values pass the mandatory policy.
+  for (const value of [event.schema_version, event.sdk_name, event.sdk_version,
+    ...Object.values(event.correlation ?? {})]) {
+    if (typeof value !== "string") continue;
+    const checked = sanitizeTelemetry(value, { additionalKeys });
+    if (!checked.ok || checked.value !== value) return null;
+  }
+  const result = sanitizeTelemetry({
+    service: event.service,
+    payload: event.payload,
+    ...(event.context ? { context: event.context } : {})
+  }, { additionalKeys });
+  if (!result.ok || !result.value || typeof result.value !== "object" || Array.isArray(result.value)) {
+    return null;
+  }
+  const safeFields = result.value as Record<string, unknown>;
+  if (!safeFields.service || !safeFields.payload ||
+      typeof safeFields.service !== "object" || Array.isArray(safeFields.service) ||
+      typeof safeFields.payload !== "object" || Array.isArray(safeFields.payload)) {
+    return null;
+  }
+  return {
+    ...event,
+    service: safeFields.service as DebugBundleEventEnvelope["service"],
+    payload: safeFields.payload as Record<string, unknown>,
+    ...(event.context ? { context: safeFields.context as Record<string, unknown> } : {})
+  };
+}
+
 export class DebugBundleReactNativeClient implements DebugBundleClient {
   private config: ResolvedDebugBundleConfig;
   private nativeModule: NativeDebugBundleModule | null = null;
@@ -35,6 +76,8 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
   private breadcrumbs: Array<Record<string, unknown>> = [];
   private probeBuffers = new Map<string, Array<Record<string, unknown>>>();
   private jsProbeActivationExpiresAt = 0;
+  private pendingNativeCalls = 0;
+  private pendingNativeBytes = 0;
 
   constructor(config: DebugBundleConfig = {}) {
     this.config = resolveConfig(config);
@@ -82,6 +125,8 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
   }
 
   captureException(error: unknown, context: DebugBundleCaptureContext = {}): void {
+    if (!this.config.captureErrors || !this.canCapture("frontend_exception", false) ||
+        !this.hasNativeCapacity(true)) return;
     const mergedContext = this.mergeContext(context);
     const sanitizedError = asRecord(sanitizeValue(error, { redactFields: this.config.redactFields }));
     this.enqueue("frontend_exception", {
@@ -100,15 +145,22 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
   }
 
   captureLog(message: string, level: DebugBundleLogLevel = "warning", context: DebugBundleCaptureContext = {}): void {
+    if (!this.isLogEnabled(level)) return;
+    const mergedContext = this.mergeContext(context);
     this.enqueue("log_event", {
       level,
       message: sanitizeValue(message, { redactFields: this.config.redactFields }),
       attributes: {
-        ...asRecord(sanitizeValue(this.mergeContext(context), { redactFields: this.config.redactFields })),
+        ...asRecord(sanitizeValue(mergedContext, { redactFields: this.config.redactFields })),
         source: "javascript"
       }
-    }, stringValue(context.trace_id), true, undefined,
-    this.config.captureLogs && LOG_LEVELS[level] >= LOG_LEVELS[this.config.logLevel]);
+    }, stringValue(mergedContext.trace_id), true);
+  }
+
+  isLogEnabled(level: DebugBundleLogLevel): boolean {
+    const rank = LOG_LEVELS[level];
+    return rank !== undefined && this.config.captureLogs && rank >= LOG_LEVELS[this.config.logLevel] &&
+      this.canCapture("log_event", true) && this.hasNativeCapacity(rank >= LOG_LEVELS.error);
   }
 
   captureRequest(
@@ -116,6 +168,7 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
     response: DebugBundleResponseInfo,
     context: DebugBundleCaptureContext = {}
   ): void {
+    if (!this.config.captureNetwork || !this.canCapture("request_event", true) || !this.hasNativeCapacity(false)) return;
     const mergedContext = this.mergeContext(context);
     const traceId = request.traceId ?? stringValue(mergedContext.trace_id);
     const parsedUrl = parseRequestUrl(request.url);
@@ -133,16 +186,13 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
       }),
       duration_ms: response.durationMillis ?? 0
     };
-    if (this.config.captureNetwork) {
-      this.recordBreadcrumb("network_request", payload);
-    }
+    this.recordBreadcrumb("network_request", payload);
     this.enqueue(
       "request_event",
       payload,
       traceId,
       true,
-      asRecord(sanitizeValue(mergedContext, { redactFields: this.config.redactFields })),
-      this.config.captureNetwork
+      asRecord(sanitizeValue(mergedContext, { redactFields: this.config.redactFields }))
     );
   }
 
@@ -155,43 +205,61 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
   }
 
   setContext(key: string, value: unknown): void {
-    this.context[key] = sanitizeValue(value, { redactFields: this.config.redactFields });
-    if (this.nativeModule?.setContextValue) {
-      void safeNativeCall(() => this.nativeModule!.setContextValue!(key, { value: this.context[key] }), undefined);
-    } else if (this.nativeModule?.setContext) {
-      void safeNativeCall(() => this.nativeModule!.setContext!(key, this.context[key]), undefined);
+    if (typeof key !== "string" || !key || key.length > MAX_CONTEXT_KEY_LENGTH ||
+        !this.hasNativeCapacity(false) ||
+        !Object.hasOwn(this.context, key) && Object.keys(this.context).length >= MAX_CONTEXT_FIELDS) return;
+    try {
+      // Include the field name in mandatory privacy before local or native ownership.
+      const fields = asRecord(sanitizeValue({ [key]: value }, { redactFields: this.config.redactFields }));
+      if (!Object.hasOwn(fields, key)) return;
+      const entry = { value: fields[key] };
+      this.context = { ...this.context, [key]: entry.value };
+      const nativeModule = this.nativeModule;
+      if (nativeModule?.setContextValue) {
+        this.enqueueNativeAuxiliary({ key, entry }, () => nativeModule.setContextValue!(key, entry));
+      } else if (nativeModule?.setContext) {
+        this.enqueueNativeAuxiliary({ key, entry }, () => nativeModule.setContext!(key, entry.value));
+      }
+    } catch {
+      // Context accessors and optional native integrations cannot escape into the host.
     }
   }
 
   probe(label: string, data: unknown | (() => unknown), options: DebugBundleProbeOptions = {}): void {
-    if (!label || this.probeBuffers.size >= this.config.maxProbeLabels && !this.probeBuffers.has(label)) {
-      return;
-    }
-    const nativeProbeActive = this.nativeModule?.isProbeActive?.(label) ?? false;
-    if (options.heavy && !nativeProbeActive && !this.hasActiveJsProbeActivation()) {
-      return;
-    }
-    const value = typeof data === "function" ? safeInvoke(data as () => unknown) : data;
-    const sanitizedData = objectWrap(sanitizeValue(value, { redactFields: this.config.redactFields }));
-    const occurredAt = new Date().toISOString();
-    const entry = {
-      label,
-      data: sanitizedData,
-      timestamp: occurredAt,
-      activation_id: null
-    };
-    const entries = this.probeBuffers.get(label) ?? [];
-    entries.push(entry);
-    this.probeBuffers.set(label, entries.slice(-this.config.maxProbeEntriesPerLabel));
-    if (this.nativeModule?.captureProbe) {
-      void safeNativeCall(
-        () => this.nativeModule!.captureProbe!(label, sanitizedData, occurredAt),
-        false
-      );
+    if (!label || label.length > MAX_CONTEXT_KEY_LENGTH || !this.hasNativeCapacity(false) ||
+        this.probeBuffers.size >= this.config.maxProbeLabels && !this.probeBuffers.has(label)) return;
+    try {
+      const nativeModule = this.nativeModule;
+      const nativeProbeActive = nativeModule?.isProbeActive?.(label) ?? false;
+      if (options.heavy && !nativeProbeActive && !this.hasActiveJsProbeActivation()) return;
+      const value = typeof data === "function" ? safeInvoke(data as () => unknown) : data;
+      const sanitizedData = objectWrap(sanitizeValue(value, { redactFields: this.config.redactFields }));
+      const occurredAt = new Date().toISOString();
+      const entry = { label, data: sanitizedData, timestamp: occurredAt, activation_id: null };
+      const entries = this.probeBuffers.get(label) ?? [];
+      entries.push(entry);
+      this.probeBuffers.set(label, entries.slice(-this.config.maxProbeEntriesPerLabel));
+      if (nativeModule?.captureProbe) {
+        this.enqueueNativeAuxiliary({ label, data: sanitizedData, occurredAt },
+          () => nativeModule.captureProbe!(label, sanitizedData, occurredAt));
+      }
+    } catch {
+      // Probe options, native activation readers and data access cannot throw into the host.
     }
   }
 
+  private enqueueNativeAuxiliary(payload: unknown, operation: () => unknown): void {
+    if (!this.hasNativeCapacity(false)) return;
+    const bytes = utf8ByteLength(JSON.stringify(payload));
+    if (bytes > MAX_NATIVE_EVENT_BYTES || this.pendingNativeBytes + bytes > MAX_PENDING_LOW_PRIORITY_BYTES) return;
+    this.pendingNativeCalls += 1;
+    this.pendingNativeBytes += bytes;
+    void safeNativeCall(operation, undefined).finally(() => this.releaseNativeCapacity(bytes));
+  }
+
   async flush(): Promise<void> {
+    // Hook preparation queued by earlier capture calls must reach the bridge first.
+    await Promise.resolve();
     if (!this.nativeModule) {
       return;
     }
@@ -246,43 +314,111 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
     context?: Record<string, unknown>,
     localPolicyAllows = true
   ): void {
+    if (!localPolicyAllows) return;
     if (!this.canCapture(eventType, countTowardSession)) {
       return;
     }
-    const authoredEvent: DebugBundleEventEnvelope = {
-      schema_version: "2026-03-01",
-      event_id: generateId(),
-      event_type: eventType,
-      sdk_name: SDK_NAME,
-      sdk_version: this.config.sdkVersion,
-      service: {
-        name: this.config.service,
-        environment: this.config.environment,
-        runtime: "react-native",
-        framework: "react-native"
-      },
-      occurred_at: new Date().toISOString(),
-      ...(traceId ? { correlation: { trace_id: traceId } } : {}),
-      ...(context && Object.keys(context).length > 0 ? { context } : {}),
-      payload: this.nativeState.device
-        ? { ...payload, device: canonicalDevice(this.nativeState.device, this.config) }
-        : payload
-    };
-    const event = applyBeforeSend(authoredEvent, this.config.beforeSend);
-    if (!event || !localPolicyAllows) {
-      return;
-    }
-    if (!this.nativeModule) {
-      this.nativeState = degradedNativeState("native_module_unavailable");
-      return;
-    }
-    if (this.nativeModule.enqueueCanonicalEvent) {
-      void safeNativeCall(() => this.nativeModule!.enqueueCanonicalEvent!(event), undefined);
-    } else {
-      void safeNativeCall(() => this.nativeModule!.enqueueEvent(toLegacyNativeEvent(event)), undefined);
+    const highPriority = eventType === "frontend_exception" ||
+      eventType === "log_event" && (payload.level === "error" || payload.level === "critical");
+    if (!this.hasNativeCapacity(highPriority)) return;
+    this.pendingNativeCalls += 1;
+    let handedOff = false;
+    let reservedBytes = 0;
+    try {
+      const authoredEvent: DebugBundleEventEnvelope = {
+        schema_version: "2026-03-01",
+        event_id: generateId(),
+        event_type: eventType,
+        sdk_name: SDK_NAME,
+        sdk_version: this.config.sdkVersion,
+        service: {
+          name: this.config.service,
+          environment: this.config.environment,
+          runtime: "react-native",
+          framework: "react-native"
+        },
+        occurred_at: new Date().toISOString(),
+        ...(traceId ? { correlation: { trace_id: traceId } } : {}),
+        ...(context && Object.keys(context).length > 0 ? { context } : {}),
+        payload: this.nativeState.device
+          ? { ...payload, device: canonicalDevice(this.nativeState.device, this.config) }
+          : payload
+      };
+      const initial = protectEventFields(authoredEvent, this.config.redactFields);
+      if (!initial) return;
+      const config = this.config;
+      const nativeModule = this.nativeModule;
+      const initialBytes = utf8ByteLength(JSON.stringify(initial));
+      const byteLimit = highPriority ? MAX_PENDING_NATIVE_BYTES : MAX_PENDING_LOW_PRIORITY_BYTES;
+      if (initialBytes > MAX_NATIVE_EVENT_BYTES || this.pendingNativeBytes + initialBytes > byteLimit) return;
+      this.pendingNativeBytes += initialBytes;
+      reservedBytes = initialBytes;
+      if (!nativeModule) {
+        this.nativeState = degradedNativeState("native_module_unavailable");
+        return;
+      }
+      handedOff = true;
+      this.sendAdmittedEvent(initial, config, nativeModule, reservedBytes);
+    } catch {
+      this.nativeState = degradedNativeState("event_preparation_failed");
+    } finally {
+      if (!handedOff) this.releaseNativeCapacity(reservedBytes);
     }
   }
 
+  private sendAdmittedEvent(
+    initial: DebugBundleEventEnvelope,
+    config: ResolvedDebugBundleConfig,
+    nativeModule: NativeDebugBundleModule,
+    reservedBytes: number
+  ): void {
+    // This activation receives only a protected snapshot: deferred closures must
+    // not retain the raw capture payload/context through their lexical scope.
+      const prepareAndSend = async (): Promise<void> => {
+        if (this.config !== config) return;
+        const safeEvent = this.prepareAdmittedEvent(initial, config, nativeModule.enqueueCanonicalEvent !== undefined);
+        if (safeEvent === null) return;
+        const finalPriority = safeEvent.event_type === "frontend_exception" ||
+          safeEvent.event_type === "log_event" && ["error", "critical"].includes(String(safeEvent.payload.level));
+        const eventBytes = utf8ByteLength(JSON.stringify(safeEvent));
+        const finalLimit = finalPriority ? MAX_PENDING_NATIVE_BYTES : MAX_PENDING_LOW_PRIORITY_BYTES;
+        // The callback closure can retain the protected original until the bridge
+        // settles. Charge both it and the final snapshot instead of forgetting it.
+        if (eventBytes > MAX_NATIVE_EVENT_BYTES || this.pendingNativeBytes + eventBytes > finalLimit) return;
+        this.pendingNativeBytes += eventBytes;
+        reservedBytes += eventBytes;
+        if (nativeModule.enqueueCanonicalEvent) await nativeModule.enqueueCanonicalEvent(safeEvent);
+        else await nativeModule.enqueueEvent(safeEvent);
+      };
+      const operation = config.beforeSend === null
+        ? safeNativeCall(prepareAndSend, undefined)
+        : Promise.resolve().then(() => safeNativeCall(prepareAndSend, undefined));
+      void operation.finally(() => { this.releaseNativeCapacity(reservedBytes); });
+  }
+
+  private prepareAdmittedEvent(initial: DebugBundleEventEnvelope, config: ResolvedDebugBundleConfig, canonical: boolean): DebugBundleEventEnvelope | null {
+    // Exit this synchronous activation before awaiting the bridge. An application
+    // replacement may be huge before projection and must not survive suspension.
+    const event = applyBeforeSend(initial, config.beforeSend);
+    if (!event || this.config !== config) return null;
+    const safeEvent = protectEventFields(event, config.redactFields);
+    if (!safeEvent) return null;
+    if (safeEvent.event_type === "log_event" &&
+        (!config.captureLogs || !(LOG_LEVELS[safeEvent.payload.level as DebugBundleLogLevel] >= LOG_LEVELS[config.logLevel]))) return null;
+    if (safeEvent.event_type === "frontend_exception" && !config.captureErrors) return null;
+    return canonical ? safeEvent : toLegacyNativeEvent(safeEvent);
+  }
+
+  private hasNativeCapacity(highPriority: boolean): boolean {
+    return this.pendingNativeCalls < (highPriority ? MAX_PENDING_NATIVE_CALLS : MAX_PENDING_LOW_PRIORITY_CALLS) &&
+      this.pendingNativeBytes < (highPriority ? MAX_PENDING_NATIVE_BYTES : MAX_PENDING_LOW_PRIORITY_BYTES);
+  }
+
+  private releaseNativeCapacity(bytes: number): void {
+    this.pendingNativeCalls -= 1;
+    this.pendingNativeBytes -= bytes;
+  }
+
   private canCapture(eventType: DebugBundleEventEnvelope["event_type"], countTowardSession: boolean): boolean {
     if (!this.config.enabled || !this.config.projectToken) {
       return false;
@@ -293,7 +429,12 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
   }
 
   private mergeContext(context: DebugBundleCaptureContext): Record<string, unknown> {
-    return { ...this.context, ...context };
+    try {
+      return { ...this.context, ...context };
+    } catch {
+      // A hostile caller accessor cannot interrupt error reporting or application work.
+      return { ...this.context };
+    }
   }
 
   private snapshotProbeData(): Record<string, unknown> {
@@ -312,6 +453,21 @@ export class DebugBundleReactNativeClient implements DebugBundleClient {
 
 }
 
+function utf8ByteLength(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length &&
+             value.charCodeAt(index + 1) >= 0xdc00 && value.charCodeAt(index + 1) <= 0xdfff) {
+      bytes += 4;
+      index += 1;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
 export function createDebugBundleClient(config: DebugBundleConfig = {}): DebugBundleReactNativeClient {
   return new DebugBundleReactNativeClient(config);
 }

package/src/console.ts

@@ -2,7 +2,9 @@ import type { DebugBundleClient, DebugBundleLogLevel } from "./types.js";
 
 let restoreConsole: (() => void) | null = null;
 
-export function captureDebugBundleConsole(client: Pick<DebugBundleClient, "captureLog">): () => void {
+export function captureDebugBundleConsole(client: Pick<DebugBundleClient, "captureLog"> & {
+  isLogEnabled?: (level: DebugBundleLogLevel) => boolean;
+}): () => void {
   if (restoreConsole) {
     return restoreConsole;
   }
@@ -30,7 +32,10 @@ export function captureDebugBundleConsole(client: Pick<DebugBundleClient, "captu
     }
     inCapture = true;
     try {
+      if (client.isLogEnabled?.(level) === false) return;
       client.captureLog(args.map(String).join(" "), level, { source: "console" });
+    } catch {
+      // Console instrumentation must not change host logging behavior.
     } finally {
       inCapture = false;
     }

package/src/privacy-keys.ts

@@ -0,0 +1,39 @@
+export const DEFAULT_SENSITIVE_KEYS = [
+  "password", "secret", "token", "api_key", "apikey", "access_token", "refresh_token",
+  "private_key", "authorization", "bearer", "cookie", "session_id", "passwd", "ssn",
+  "credit_card", "card_number", "cvv", "cvc", "pin", "expiry", "phone", "otp",
+  "verification_code"
+] as const;
+
+function canonicalizeSensitiveKey(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function splitKeyIntoSegments(key: string): string[] {
+  return key
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((segment) => segment.length > 0);
+}
+
+export function isSensitiveKey(key: string, sensitiveKeys: readonly string[]): boolean {
+  const normalized = key.trim().toLowerCase();
+  if (sensitiveKeys.includes(normalized)) {
+    return true;
+  }
+
+  const canonicalSensitiveKeys = new Set(sensitiveKeys.map(canonicalizeSensitiveKey));
+  const segments = splitKeyIntoSegments(key);
+  for (let start = 0; start < segments.length; start += 1) {
+    let combined = "";
+    for (let end = start; end < segments.length; end += 1) {
+      combined += segments[end];
+      if (canonicalSensitiveKeys.has(combined)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}

package/src/privacy-telemetry.ts

@@ -0,0 +1,168 @@
+type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+import { DEFAULT_SENSITIVE_KEYS, isSensitiveKey } from "./privacy-keys.js";
+import { scrubCredentialText } from "./privacy-text.js";
+
+const REDACTED = "[REDACTED]";
+const MAX_DEPTH = 16;
+const MAX_NODES = 4096;
+const MAX_ENTRIES = 256;
+const MAX_STRING_BYTES = 16 * 1024;
+const MAX_TOTAL_BYTES = 256 * 1024;
+
+export interface TelemetrySanitizationOptions {
+  additionalKeys?: readonly string[];
+  maxTotalBytes?: number;
+}
+
+export type TelemetrySanitizationResult =
+  | { ok: true; value: JsonValue; redactionCount: number }
+  | { ok: false; reason: "unsafe_input" | "budget_exceeded" };
+
+interface WorkState {
+  nodes: number;
+  textBytes: number;
+  redactionCount: number;
+  seen: WeakSet<object>;
+  keys: string[];
+  extra: readonly string[];
+  maxTotalBytes: number;
+}
+
+class BudgetExceeded extends Error {}
+
+function byteLength(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length &&
+             value.charCodeAt(index + 1) >= 0xdc00 && value.charCodeAt(index + 1) <= 0xdfff) {
+      bytes += 4;
+      index += 1;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+function mask(state: WorkState): string {
+  state.redactionCount += 1;
+  return REDACTED;
+}
+
+function sanitizeString(value: string, state: WorkState, allowStructured: boolean): JsonValue {
+  if (value.length > MAX_STRING_BYTES) return mask(state);
+  const length = byteLength(value);
+  if (length > MAX_STRING_BYTES) return mask(state);
+  state.textBytes += length;
+  if (state.textBytes > state.maxTotalBytes) throw new BudgetExceeded();
+
+  if (allowStructured && (value.startsWith("{") || value.startsWith("["))) {
+    try {
+      const parsed: unknown = JSON.parse(value);
+      if (typeof parsed === "object" && parsed !== null) {
+        const nested = sanitizeValue(parsed, state, 0, false);
+        const encoded = JSON.stringify(nested);
+        if (encoded !== value) state.redactionCount += 1;
+        return encoded;
+      }
+    } catch (error) {
+      if (error instanceof BudgetExceeded) throw error;
+      // Malformed structured content with a recognizable sensitive label is withheld below.
+    }
+  }
+
+  const result = scrubCredentialText(value, state.extra);
+  if (result !== value) state.redactionCount += 1;
+  if ((value.startsWith("{") || value.startsWith("[")) && result === value &&
+      /(?:password|token|secret|authorization|cookie)["']?\s*[:=]/i.test(value)) {
+    return mask(state);
+  }
+  return result;
+}
+
+function sanitizeValue(value: unknown, state: WorkState, depth: number, allowStructured: boolean): JsonValue {
+  state.nodes += 1;
+  if (state.nodes > MAX_NODES) throw new BudgetExceeded();
+  if (depth > MAX_DEPTH) return mask(state);
+  if (typeof value === "string") return sanitizeString(value, state, allowStructured);
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "object") throw new TypeError("unsafe_input");
+
+  if (state.seen.has(value)) return "[Circular]";
+  state.seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (value.length > MAX_ENTRIES) return mask(state);
+      return Array.from({ length: value.length }, (_, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor === undefined || !("value" in descriptor)) throw new TypeError("unsafe_input");
+        return sanitizeValue(descriptor.value, state, depth + 1, allowStructured);
+      });
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+      throw new TypeError("unsafe_input");
+    }
+    const keys = Object.keys(value);
+    if (keys.length > MAX_ENTRIES) return mask(state);
+    const result: Record<string, JsonValue> = {};
+    for (const key of keys) {
+      if (key.length > 128) {
+        state.redactionCount += 1;
+        continue;
+      }
+      state.textBytes += byteLength(key);
+      if (state.textBytes > state.maxTotalBytes) throw new BudgetExceeded();
+      const safeKey = scrubCredentialText(key, state.extra);
+      if (safeKey !== key) {
+        state.redactionCount += 1;
+        continue;
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor === undefined || !("value" in descriptor)) throw new TypeError("unsafe_input");
+      const safeValue = isSensitiveKey(key, state.keys)
+        ? mask(state)
+        : sanitizeValue(descriptor.value, state, depth + 1, allowStructured);
+      Object.defineProperty(result, key, {
+        value: safeValue,
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+    }
+    return result;
+  } finally {
+    state.seen.delete(value);
+  }
+}
+
+/** Mandatory telemetry policy; unlike the legacy `redact` helper, custom keys are additive. */
+export function sanitizeTelemetry(value: unknown, options: TelemetrySanitizationOptions = {}): TelemetrySanitizationResult {
+  try {
+    const extra = options.additionalKeys ?? [];
+    if (extra.length > 128 || extra.some((key) => typeof key !== "string" || key.length > 64 || !key.trim())) {
+      return { ok: false, reason: "unsafe_input" };
+    }
+    const maxTotalBytes = options.maxTotalBytes ?? MAX_TOTAL_BYTES;
+    if (!Number.isInteger(maxTotalBytes) || maxTotalBytes < 1 || maxTotalBytes > 512 * 1024) {
+      return { ok: false, reason: "unsafe_input" };
+    }
+    const state: WorkState = {
+      nodes: 0,
+      textBytes: 0,
+      redactionCount: 0,
+      seen: new WeakSet<object>(),
+      keys: [...DEFAULT_SENSITIVE_KEYS, ...extra],
+      extra,
+      maxTotalBytes
+    };
+    const sanitized = sanitizeValue(value, state, 0, true);
+    if (byteLength(JSON.stringify(sanitized)) > maxTotalBytes) {
+      return { ok: false, reason: "budget_exceeded" };
+    }
+    return { ok: true, value: sanitized, redactionCount: state.redactionCount };
+  } catch (error) {
+    return { ok: false, reason: error instanceof BudgetExceeded ? "budget_exceeded" : "unsafe_input" };
+  }
+}