@provide-io/telemetry 0.2.2

package/src/otel-logs.ts

@@ -0,0 +1,161 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Stryker disable all -- dynamic import('...' as string) prevents Stryker's V8 perTest
+   coverage from attributing any coverage to specific tests; all mutations in this file
+   show covered:0 even though integration tests exercise every branch. */
+
+/**
+ * Optional OTEL SDK log wiring — activated when registerOtelProviders() runs.
+ *
+ * Peer deps required:
+ *   @opentelemetry/sdk-logs                  — LoggerProvider, BatchLogRecordProcessor
+ *   @opentelemetry/exporter-logs-otlp-http   — OTLPLogExporter
+ *   @opentelemetry/api-logs                  — logs global, SeverityNumber
+ *
+ * Mirrors Python provide.telemetry.logger.core OTLPLogExporter wiring.
+ */
+
+import type { TelemetryConfig } from './config';
+import { getConfig } from './config';
+import type { ShutdownableProvider } from './runtime';
+
+/** Pino level number → OTel SeverityNumber (from @opentelemetry/api-logs). */
+const SEVERITY_MAP: Record<number, number> = {
+  10: 1, // TRACE
+  20: 5, // DEBUG
+  30: 9, // INFO
+  40: 13, // WARN
+  50: 17, // ERROR
+  60: 21, // FATAL
+};
+const SEVERITY_TEXT: Record<number, string> = {
+  10: 'TRACE',
+  20: 'DEBUG',
+  30: 'INFO',
+  40: 'WARN',
+  50: 'ERROR',
+  60: 'FATAL',
+};
+const DEFAULT_SEVERITY = 9; // INFO
+
+/** Internal singleton — set by setupOtelLogProvider, read by emitLogRecord. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _loggerProvider: any = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _otelLogger: any = null;
+
+/**
+ * Construct an OTLPLogExporter + LoggerProvider and register it globally.
+ * Returns a ShutdownableProvider so the caller can flush/shutdown it.
+ * Throws if any peer dep is missing (caught by the caller in otel.ts).
+ */
+export async function setupOtelLogProvider(cfg: TelemetryConfig): Promise<ShutdownableProvider> {
+  const headers = cfg.otlpHeaders ?? {};
+  const endpoint = cfg.otlpEndpoint ?? 'http://localhost:4318';
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const sdkLogs: any = await import('@opentelemetry/sdk-logs' as string);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const otlpLogs: any = await import('@opentelemetry/exporter-logs-otlp-http' as string);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const apiLogs: any = await import('@opentelemetry/api-logs' as string);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const res: any = await import('@opentelemetry/resources' as string);
+
+  const { LoggerProvider, BatchLogRecordProcessor } = sdkLogs;
+  const { OTLPLogExporter } = otlpLogs;
+  const { logs } = apiLogs;
+  const { resourceFromAttributes } = res;
+
+  const logExporter = new OTLPLogExporter({ url: `${endpoint}/v1/logs`, headers });
+  const processor = new BatchLogRecordProcessor(logExporter);
+  const provider = new LoggerProvider({
+    resource: resourceFromAttributes({
+      'service.name': cfg.serviceName,
+      'deployment.environment': cfg.environment,
+      'service.version': cfg.version,
+    }),
+    processors: [processor],
+  });
+
+  logs.setGlobalLoggerProvider(provider);
+  _loggerProvider = provider;
+  _otelLogger = logs.getLogger('@provide-io/telemetry');
+
+  return provider as ShutdownableProvider;
+}
+
+/**
+ * Emit a pino log record to the OTel LoggerProvider.
+ * Called from makeWriteHook() on every log line after enrichment and sanitization.
+ * No-op when no provider is registered (graceful degradation).
+ */
+export function emitLogRecord(o: Record<string, unknown>): void {
+  if (!_otelLogger) return;
+
+  const level = (o['level'] as number) ?? 30;
+  const body = String(o['msg'] ?? o['event'] ?? '');
+  const severityNumber = SEVERITY_MAP[level] ?? DEFAULT_SEVERITY;
+  const severityText = SEVERITY_TEXT[level] ?? 'INFO';
+
+  // Build attributes: everything except the pino-internal fields already
+  // represented by body / severity / timestamp.
+  const SKIP = new Set(['msg', 'level', 'time', 'v']);
+  const attributes: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(o)) {
+    if (!SKIP.has(k) && v !== undefined) attributes[k] = v;
+  }
+
+  // — Security: truncate long attribute values —
+  const cfg = getConfig();
+  const maxLen = cfg.securityMaxAttrValueLength;
+  for (const [k, v] of Object.entries(attributes)) {
+    if (typeof v === 'string' && v.length > maxLen) {
+      attributes[k] = v.slice(0, maxLen) + '...';
+    }
+  }
+
+  // — Security: limit attribute count —
+  const maxCount = cfg.securityMaxAttrCount;
+  const keys = Object.keys(attributes);
+  if (keys.length > maxCount) {
+    for (const k of keys.slice(maxCount)) {
+      delete attributes[k];
+    }
+  }
+
+  // — Code attributes: map provide-telemetry fields to OTel semantic conventions —
+  if (cfg.logCodeAttributes) {
+    if (attributes['caller_file']) {
+      attributes['code.filepath'] = attributes['caller_file'];
+    }
+    if (attributes['caller_line']) {
+      attributes['code.lineno'] = attributes['caller_line'];
+    }
+    if (attributes['name']) {
+      attributes['code.namespace'] = attributes['name'];
+    }
+  }
+
+  _otelLogger.emit({
+    body,
+    severityNumber,
+    severityText,
+    attributes,
+    timestamp: typeof o['time'] === 'number' ? o['time'] : Date.now(),
+  });
+}
+
+/** Exposed for tests and resetTelemetryState(). */
+export function _resetOtelLogProviderForTests(): void {
+  _loggerProvider = null;
+  _otelLogger = null;
+}
+
+/** Exposed for integration tests to inspect state. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function _getOtelLogProvider(): any {
+  return _loggerProvider;
+}

package/src/otel-noop.ts

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * No-op OTEL provider registration for browser environments.
+ *
+ * In browser builds, the Node.js OTel SDKs are not available. This stub
+ * prevents bundlers from pulling in the heavy SDK dependencies while still
+ * allowing registerOtelProviders() to be called without error.
+ *
+ * Note: Cloudflare Workers and Vercel Edge have their own OTel support and
+ * should use the default export, not this stub.
+ */
+
+import type { TelemetryConfig } from './config';
+
+export async function registerOtelProviders(_cfg: TelemetryConfig): Promise<void> {
+  // No-op in browser/edge environments.
+}

package/src/otel.ts

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/* Stryker disable all -- dynamic import('...' as string) prevents Stryker's V8 perTest
+   coverage from attributing any coverage to specific tests; all mutations in this file
+   show covered:0 even though integration tests exercise every branch. */
+
+/**
+ * Optional OTEL SDK wiring — only activated when setupTelemetry({ otelEnabled: true }) is called.
+ *
+ * All imports are dynamic so this module adds zero bundle overhead when OTEL is unused.
+ * Peer deps required:
+ *   @opentelemetry/sdk-trace-base   — BasicTracerProvider, span processors/exporters
+ *   @opentelemetry/sdk-metrics      — MeterProvider, metric readers
+ *   @opentelemetry/resources        — resourceFromAttributes
+ *   @opentelemetry/exporter-trace-otlp-http   — OTLPTraceExporter
+ *   @opentelemetry/exporter-metrics-otlp-http — OTLPMetricExporter
+ *
+ * Mirrors Python provide.telemetry _otel.py lazy-load approach.
+ */
+
+import type { TelemetryConfig } from './config';
+import { setupOtelLogProvider } from './otel-logs';
+
+const DEFAULT_OTLP_ENDPOINT = 'http://localhost:4318';
+import {
+  type ShutdownableProvider,
+  _areProvidersRegistered,
+  _markProvidersRegistered,
+  _storeRegisteredProviders,
+} from './runtime';
+
+/**
+ * Register OTEL TracerProvider and MeterProvider using OTLP HTTP exporters.
+ * Safe to call multiple times — subsequent calls are no-ops if already registered.
+ */
+export async function registerOtelProviders(cfg: TelemetryConfig): Promise<void> {
+  if (!cfg.otelEnabled) return;
+  if (_areProvidersRegistered()) return;
+
+  const headers = cfg.otlpHeaders ?? {};
+  const endpoint = cfg.otlpEndpoint ?? DEFAULT_OTLP_ENDPOINT;
+  const registered: ShutdownableProvider[] = [];
+
+  // ── Tracing ──────────────────────────────────────────────────────────────────
+  try {
+    // These are optional peer deps — TypeScript checks are suppressed intentionally.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const traceBase: any = await import('@opentelemetry/sdk-trace-base' as string);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const otlpTrace: any = await import('@opentelemetry/exporter-trace-otlp-http' as string);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const res: any = await import('@opentelemetry/resources' as string);
+    const { trace } = await import('@opentelemetry/api');
+
+    const { BasicTracerProvider, BatchSpanProcessor } = traceBase;
+    const { OTLPTraceExporter } = otlpTrace;
+    const { resourceFromAttributes } = res;
+
+    const traceExporter = new OTLPTraceExporter({
+      url: `${endpoint}/v1/traces`,
+      headers,
+    });
+
+    const provider = new BasicTracerProvider({
+      resource: resourceFromAttributes({
+        'service.name': cfg.serviceName,
+        'deployment.environment': cfg.environment,
+        'service.version': cfg.version,
+      }),
+      spanProcessors: [new BatchSpanProcessor(traceExporter)],
+    });
+    trace.setGlobalTracerProvider(provider);
+    registered.push(provider as ShutdownableProvider);
+  } catch (err) {
+    console.warn('[provide/telemetry] OTEL trace setup failed (missing peer deps?):', err);
+  }
+
+  // ── Metrics ──────────────────────────────────────────────────────────────────
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sdkMetrics: any = await import('@opentelemetry/sdk-metrics' as string);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const otlpMetrics: any = await import('@opentelemetry/exporter-metrics-otlp-http' as string);
+    const { metrics } = await import('@opentelemetry/api');
+    const { MeterProvider, PeriodicExportingMetricReader } = sdkMetrics;
+    const { OTLPMetricExporter } = otlpMetrics;
+
+    const metricExporter = new OTLPMetricExporter({
+      url: `${endpoint}/v1/metrics`,
+      headers,
+    });
+
+    const meterProvider = new MeterProvider({
+      readers: [new PeriodicExportingMetricReader({ exporter: metricExporter })],
+    });
+    metrics.setGlobalMeterProvider(meterProvider);
+    registered.push(meterProvider as ShutdownableProvider);
+  } catch (err) {
+    console.warn('[provide/telemetry] OTEL metrics setup failed (missing peer deps?):', err);
+  }
+
+  // ── Logs ─────────────────────────────────────────────────────────────────────
+  try {
+    registered.push(await setupOtelLogProvider(cfg));
+  } catch (err) {
+    console.warn('[provide/telemetry] OTEL logs setup failed (missing peer deps?):', err);
+  }
+
+  _storeRegisteredProviders(registered);
+  _markProvidersRegistered();
+}

package/src/pii.ts

@@ -0,0 +1,358 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * PII policy engine with rule-based masking and nested traversal.
+ * Mirrors Python provide.telemetry.pii.
+ *
+ * Also serves as the canonical home for sanitize() / DEFAULT_SANITIZE_FIELDS;
+ * sanitize.ts re-exports these for backwards compatibility.
+ */
+
+import { shortHash12 } from './hash';
+
+/**
+ * Default fields redacted from log records. Canonical 17-key list shared across
+ * Python, TypeScript, and Go implementations.
+ * Note: 'email' is intentionally excluded — it is commonly used for user identification
+ * in logs. Users who want email redaction should register a custom PII rule.
+ */
+export const DEFAULT_SANITIZE_FIELDS: readonly string[] = [
+  'password',
+  'passwd',
+  'secret',
+  'token',
+  'api_key',
+  'apikey',
+  'auth',
+  'authorization',
+  'credential',
+  'private_key',
+  'ssn',
+  'credit_card',
+  'creditcard',
+  'cvv',
+  'pin',
+  'account_number',
+  'cookie',
+];
+
+const REDACTED = '***';
+
+/** Default maximum recursion depth for PII sanitization. */
+const _DEFAULT_MAX_DEPTH = 8;
+
+const _MIN_SECRET_LENGTH = 20;
+/* Stryker disable all: regex quantifier mutations produce patterns that still match test values */
+export const _SECRET_PATTERNS: RegExp[] = [
+  /(?:AKIA|ASIA)[A-Z0-9]{16}/, // AWS access key
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, // JWT
+  /gh[pos]_[A-Za-z0-9_]{36,}/, // GitHub token
+  /[0-9a-fA-F]{40,}/, // Long hex string
+  /[A-Za-z0-9+/]{40,}={0,2}/, // Long base64 string
+];
+/* Stryker restore all */
+
+export function _detectSecretInValue(value: string): boolean {
+  // Stryker disable next-line ConditionalExpression: removing length check makes patterns match short strings — equivalent when all test secrets are ≥20 chars
+  if (value.length < _MIN_SECRET_LENGTH) return false;
+  return _SECRET_PATTERNS.some((p) => p.test(value));
+}
+
+/**
+ * Redact PII fields in a log object in place.
+ * Checks DEFAULT_SANITIZE_FIELDS plus any additional fields from config.
+ * Case-insensitive key matching.
+ */
+// Stryker disable next-line ArrayDeclaration
+export function sanitize(obj: Record<string, unknown>, extraFields: string[] = []): void {
+  const blocked = new Set([
+    ...DEFAULT_SANITIZE_FIELDS.map((f) => f.toLowerCase()),
+    ...extraFields.map((f) => f.toLowerCase()),
+  ]);
+  for (const key of Object.keys(obj)) {
+    // Stryker disable next-line ConditionalExpression: mutating to true redacts all keys — equivalent because tests use blocked keys
+    if (blocked.has(key.toLowerCase())) {
+      obj[key] = REDACTED;
+    } else if (
+      // Stryker disable next-line all: V8 perTest coverage doesn't attribute else-if branches; tested in pii.test.ts secret detection suite
+      typeof obj[key] === 'string' &&
+      _detectSecretInValue(obj[key] as string)
+    ) {
+      obj[key] = REDACTED;
+    }
+  }
+}
+
+// ── Dynamic PII rule engine ───────────────────────────────────────────────────
+
+export type MaskMode = 'redact' | 'drop' | 'hash' | 'truncate';
+
+export interface PIIRule {
+  /** Dot-separated field path (e.g. "user.email"). Python uses tuple paths instead. */
+  path: string;
+  mode: MaskMode;
+  /** For 'truncate' mode: max characters before '...' is appended. */
+  truncateTo?: number;
+}
+
+// Stryker disable next-line ArrayDeclaration
+const _rules: PIIRule[] = [];
+
+// Governance hooks — set by classification / receipts modules if present.
+// null = feature not loaded (zero overhead).
+export let _classificationHook: ((key: string, value: unknown) => string | null) | null = null;
+export let _receiptHook:
+  | ((fieldPath: string, action: string, originalValue: unknown) => void)
+  | null = null;
+
+export function setClassificationHook(
+  fn: ((key: string, value: unknown) => string | null) | null,
+): void {
+  _classificationHook = fn;
+}
+
+export function setReceiptHook(
+  fn: ((fieldPath: string, action: string, originalValue: unknown) => void) | null,
+): void {
+  _receiptHook = fn;
+}
+
+// Overridable hash function — allows tests to exercise the fallback path.
+let _hashFnOverride: ((val: string) => string) | null = null;
+
+export function _setHashFnForTest(fn: ((val: string) => string) | null): void {
+  _hashFnOverride = fn;
+}
+
+function _hashValue(val: string): string {
+  try {
+    if (_hashFnOverride !== null) return _hashFnOverride(val);
+    return shortHash12(val);
+  } catch {
+    return REDACTED;
+  }
+}
+
+function _applyMode(value: unknown, rule: PIIRule): { keep: boolean; value: unknown } {
+  switch (rule.mode) {
+    case 'drop':
+      // Stryker disable next-line ObjectLiteral
+      return { keep: false, value: undefined };
+    case 'hash':
+      return { keep: true, value: _hashValue(String(value)) };
+    case 'truncate': {
+      const limit = Math.max(0, rule.truncateTo ?? 8);
+      const text = String(value);
+      return { keep: true, value: text.length > limit ? text.slice(0, limit) + '...' : text };
+    }
+    default:
+      return { keep: true, value: REDACTED };
+  }
+}
+
+function _pathSegments(path: string): string[] {
+  return path.split('.');
+}
+
+function _matches(ruleSegs: string[], valueSegs: string[]): boolean {
+  // Stryker disable next-line ConditionalExpression
+  if (ruleSegs.length !== valueSegs.length) return false;
+  return ruleSegs.every((seg, i) => seg === '*' || seg === valueSegs[i]);
+}
+
+function _applyRuleFull(
+  node: unknown,
+  rule: PIIRule,
+  currentPath: string[],
+  maxDepth: number = _DEFAULT_MAX_DEPTH,
+  depth: number = 0,
+  receiptHook: ((fieldPath: string, action: string, originalValue: unknown) => void) | null = null,
+): unknown {
+  if (typeof node !== 'object' || node === null) return node;
+  if (depth >= maxDepth) return node;
+  // Stryker disable next-line ConditionalExpression,BlockStatement: when array is treated as object, numeric string indices still match wildcard '*' rule segments — equivalent
+  if (Array.isArray(node)) {
+    // Stryker disable next-line StringLiteral: '*' wildcard in VALUE path is irrelevant because _matches checks RULE segment, not value segment, for wildcards
+    return node.map((item) =>
+      _applyRuleFull(item, rule, [...currentPath, '*'], maxDepth, depth + 1, receiptHook),
+    );
+  }
+  const obj = node as Record<string, unknown>;
+  const ruleSegs = _pathSegments(rule.path);
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(obj)) {
+    const childPath = [...currentPath, key];
+    if (_matches(ruleSegs, childPath)) {
+      if (receiptHook !== null) receiptHook(childPath.join('.'), rule.mode, val);
+      const { keep, value } = _applyMode(val, rule);
+      if (keep) result[key] = value;
+    } else {
+      result[key] = _applyRuleFull(val, rule, childPath, maxDepth, depth + 1, receiptHook);
+    }
+  }
+  return result;
+}
+
+/**
+ * Recursively redact keys matching blocked field names and secret patterns,
+ * respecting depth limits. Mirrors Python _apply_default_sensitive_key_redaction.
+ */
+function _applyDefaultSensitiveKeyRedaction(
+  node: unknown,
+  original: unknown,
+  blocked: Set<string>,
+  ruleTargets: Set<string | undefined>,
+  maxDepth: number,
+  receiptHook: ((fieldPath: string, action: string, originalValue: unknown) => void) | null,
+  depth: number = 0,
+): unknown {
+  if (depth >= maxDepth) return node;
+  if (typeof node !== 'object' || node === null) return node;
+  if (Array.isArray(node)) {
+    /* v8 ignore next: [] fallback — original always matches node's array type through recursive calls */
+    const origArr = Array.isArray(original) ? original : [];
+    return node.map((item, i) =>
+      _applyDefaultSensitiveKeyRedaction(
+        item,
+        origArr[i],
+        blocked,
+        ruleTargets,
+        maxDepth,
+        receiptHook,
+        depth + 1,
+      ),
+    );
+  }
+  const obj = node as Record<string, unknown>;
+  /* v8 ignore start: original always mirrors node's object structure through recursive calls — : obj fallback is defensive */
+  const orig =
+    typeof original === 'object' && original !== null && !Array.isArray(original)
+      ? (original as Record<string, unknown>)
+      : obj;
+  /* v8 ignore stop */
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(obj)) {
+    const lk = key.toLowerCase();
+    const origVal = orig[key];
+    if (blocked.has(lk) && !ruleTargets.has(lk)) {
+      // If a custom rule already changed the value, keep the rule's result.
+      /* v8 ignore next 2: defensive guard for value modified before sanitizePayload — not reachable via normal API */
+      if (val !== origVal) {
+        result[key] = val;
+      } else {
+        result[key] = REDACTED;
+        if (receiptHook !== null) receiptHook(key, 'redact', origVal);
+      }
+    } else if (typeof val === 'string' && _detectSecretInValue(val)) {
+      result[key] = REDACTED;
+      if (receiptHook !== null) receiptHook(key, 'redact', val);
+    } else {
+      result[key] = _applyDefaultSensitiveKeyRedaction(
+        val,
+        origVal,
+        blocked,
+        ruleTargets,
+        maxDepth,
+        receiptHook,
+        depth + 1,
+      );
+    }
+  }
+  return result;
+}
+
+export function registerPiiRule(rule: PIIRule): void {
+  _rules.push(rule);
+}
+
+export function getPiiRules(): PIIRule[] {
+  return [..._rules];
+}
+
+export function replacePiiRules(rules: PIIRule[]): void {
+  _rules.length = 0;
+  _rules.push(...rules);
+}
+
+export function resetPiiRulesForTests(): void {
+  _rules.length = 0;
+  _hashFnOverride = null;
+  _classificationHook = null;
+  _receiptHook = null;
+}
+
+/** Options for sanitizePayload. */
+export interface SanitizePayloadOptions {
+  /** Maximum recursion depth for nested traversal. Default 8. */
+  maxDepth?: number;
+}
+
+/**
+ * Apply all registered PII rules to a payload object recursively.
+ * Also redacts top-level keys that match DEFAULT_SANITIZE_FIELDS unless a rule already handled them.
+ */
+export function sanitizePayload(
+  obj: Record<string, unknown>,
+  // Stryker disable next-line ArrayDeclaration
+  extraFields: string[] = [],
+  options?: SanitizePayloadOptions,
+): void {
+  const maxDepth = options?.maxDepth ?? _DEFAULT_MAX_DEPTH;
+  // Capture hooks once at call time to avoid repeated reads.
+  const receiptHook = _receiptHook;
+  const classHook = _classificationHook;
+  let current: unknown = obj;
+
+  // Apply registered rules first.
+  for (const rule of _rules) {
+    current = _applyRuleFull(current, rule, [], maxDepth, 0, receiptHook);
+  }
+
+  // Apply default field-name redaction + secret detection recursively with depth limit.
+  // v8 ignore: current is always a non-null object here; null/array branches are defensive.
+  // Stryker disable next-line LogicalOperator,ConditionalExpression
+  /* v8 ignore next */
+  if (typeof current === 'object' && current !== null && !Array.isArray(current)) {
+    // Stryker disable next-line OptionalChaining: _pathSegments always returns a non-empty array (split returns at least one element)
+    const ruleTargets = new Set(_rules.map((r) => _pathSegments(r.path).pop()?.toLowerCase()));
+    const blocked = new Set([
+      ...DEFAULT_SANITIZE_FIELDS.map((f) => f.toLowerCase()),
+      ...extraFields.map((f) => f.toLowerCase()),
+    ]);
+    const c = _applyDefaultSensitiveKeyRedaction(
+      current,
+      obj,
+      blocked,
+      ruleTargets,
+      maxDepth,
+      receiptHook,
+    ) as Record<string, unknown>;
+    // Update the original object in-place.
+    for (const key of Object.keys(obj)) {
+      /* Stryker disable ConditionalExpression: false mutation deletes all keys — equivalent when no 'drop' rules are active */
+      if (key in c) {
+        obj[key] = c[key];
+      } else {
+        delete obj[key]; /* Stryker restore ConditionalExpression */
+      }
+    }
+    // Add any new keys from nested rule transformations.
+    // Stryker disable all
+    for (const key of Object.keys(c)) {
+      /* v8 ignore next */
+      if (!(key in obj)) obj[key] = c[key];
+    }
+    // Stryker enable all
+
+    // Apply classification tags for top-level keys if hook is registered.
+    if (classHook !== null) {
+      for (const key of Object.keys(obj)) {
+        const label = classHook(key, obj[key]);
+        if (label !== null) {
+          obj[`__${key}__class`] = label;
+        }
+      }
+    }
+  }
+}