feat(browser): mask sensitive request/response fields before export

Add a maskFields option to HyperDX.init in the Browser SDK. When
advancedNetworkCapture is enabled, matching headers and JSON body fields
are replaced with '***' before they are recorded as span attributes, so
sensitive data never leaves the client.

Header matches are case-insensitive. Body matches walk through nested JSON
objects and accept dotted paths (e.g. 'creditCard.number'). Non-JSON
request/response bodies are passed through unchanged.

Drive-by: switch headerCapture from for...of over a Map to Map.forEach so
the function is exercisable by the node-mocha test runner, which currently
resolves an ES5-targeted ts-node config and silently no-ops Map iterators
without downlevelIteration. Production behaviour is identical.

Refs HDX-4127

Author: wrn14897

.changeset/mask-network-fields.md

@@ -0,0 +1,10 @@
+---
+'@hyperdx/browser': minor
+'@hyperdx/otel-web': patch
+---
+
+Browser SDK: support masking sensitive fields in captured request/response
+headers and bodies before telemetry leaves the client. Add a `maskFields`
+option to `HyperDX.init`. Header matches are case-insensitive; body matches
+traverse nested JSON objects and accept dotted paths (e.g.
+`creditCard.number`). Matched values are replaced with `***`.

packages/browser/README.md

@@ -35,6 +35,24 @@ HyperDX.init({
 - `consoleCapture` - (Optional) Capture all console logs (default `false`).
 - `advancedNetworkCapture` - (Optional) Capture full request/response headers
   and bodies (default false).
+- `maskFields` - (Optional) Field names to mask in captured request/response
+  headers and bodies before telemetry leaves the browser. Only applies when
+  `advancedNetworkCapture` is enabled. Header matches are case-insensitive.
+  Body matches walk through nested JSON objects and accept dotted paths to
+  target nested properties (e.g. `creditCard.number`). Non-JSON request/
+  response bodies are passed through unchanged. Matched values are replaced
+  with `***`. Example:
+  ```js
+  HyperDX.init({
+    apiKey: '<YOUR_API_KEY_HERE>',
+    service: 'my-frontend-app',
+    advancedNetworkCapture: true,
+    maskFields: {
+      headers: ['authorization', 'x-api-key'],
+      body: ['password', 'creditCard.number'],
+    },
+  });
+  ```
 - `url` - (Optional) The OpenTelemetry collector URL, only needed for
   self-hosted instances.
 - `maskAllInputs` - (Optional) Whether to mask all input fields in session

packages/browser/src/index.ts

@@ -13,6 +13,17 @@ type ErrorBoundaryComponent = any; // TODO: Define ErrorBoundary type
 type Instrumentations = RumOtelWebConfig['instrumentations'];
 type IgnoreUrls = RumOtelWebConfig['ignoreUrls'];
 
+/**
+ * Sensitive field names to mask in captured network telemetry. Header field
+ * matches are case-insensitive. Body fields support dotted paths to address
+ * nested object properties (e.g. `creditCard.number`). Masking is applied
+ * before any data leaves the browser.
+ */
+export type MaskFields = {
+  headers?: string[];
+  body?: string[];
+};
+
 type BrowserSDKConfig = {
   advancedNetworkCapture?: boolean;
   apiKey: string;
@@ -28,6 +39,13 @@ type BrowserSDKConfig = {
   maskAllInputs?: boolean;
   maskAllText?: boolean;
   maskClass?: string;
+  /**
+   * Sensitive field names to mask in captured request/response headers and
+   * bodies before telemetry leaves the browser. Only applies when
+   * `advancedNetworkCapture` is enabled. Matched values are replaced with
+   * `'***'`.
+   */
+  maskFields?: MaskFields;
   recordCanvas?: boolean;
   sampling?: RumRecorderConfig['sampling'];
   service: string;
@@ -47,6 +65,7 @@ function hasWindow() {
 
 class Browser {
   private _advancedNetworkCapture = false;
+  private _maskFields: MaskFields | undefined;
 
   init({
     advancedNetworkCapture = false,
@@ -63,6 +82,7 @@ class Browser {
     maskAllInputs = true,
     maskAllText = false,
     maskClass,
+    maskFields,
     recordCanvas = false,
     sampling,
     service,
@@ -93,6 +113,7 @@ class Browser {
     const resolvedLogsUrl = logsUrl ?? `${urlBase}/v1/logs`;
 
     this._advancedNetworkCapture = advancedNetworkCapture;
+    this._maskFields = maskFields;
 
     Rum.init({
       debug,
@@ -112,6 +133,7 @@ class Browser {
               }
             : {}),
           advancedNetworkCapture: () => this._advancedNetworkCapture,
+          maskFields: () => this._maskFields,
         },
         xhr: {
           ...(tracePropagationTargets != null
@@ -120,6 +142,7 @@ class Browser {
               }
             : {}),
           advancedNetworkCapture: () => this._advancedNetworkCapture,
+          maskFields: () => this._maskFields,
         },
         ...instrumentations,
       },

packages/otel-web/src/HyperDXFetchInstrumentation.ts

@@ -4,10 +4,11 @@ import {
 } from '@opentelemetry/instrumentation-fetch';
 
 import { captureTraceParent } from './servertiming';
-import { headerCapture } from './utils';
+import { headerCapture, maskBody, MaskFieldsConfig } from './utils';
 
 export type HyperDXFetchInstrumentationConfig = FetchInstrumentationConfig & {
   advancedNetworkCapture?: () => boolean;
+  maskFields?: () => MaskFieldsConfig | undefined;
 };
 
 // not used yet
@@ -42,11 +43,12 @@ export class HyperDXFetchInstrumentation extends FetchInstrumentation {
       span.setAttribute('component', 'fetch');
 
       if (config.advancedNetworkCapture?.() && span) {
+        const maskFields = config.maskFields?.();
+
         if (request.headers) {
-          headerCapture('request', Object.keys(request.headers))(
-            span,
-            (header) => request.headers?.[header],
-          );
+          headerCapture('request', Object.keys(request.headers), {
+            maskFields: maskFields?.headers,
+          })(span, (header) => request.headers?.[header]);
         }
         if (request.body) {
           if (request.body instanceof ReadableStream) {
@@ -56,7 +58,10 @@ export class HyperDXFetchInstrumentation extends FetchInstrumentation {
             //   span.setAttribute('http.request.body', body);
             // });
           } else {
-            span.setAttribute('http.request.body', request.body.toString());
+            span.setAttribute(
+              'http.request.body',
+              maskBody(request.body, maskFields?.body),
+            );
           }
         }
 
@@ -66,16 +71,18 @@ export class HyperDXFetchInstrumentation extends FetchInstrumentation {
             response.headers.forEach((value, name) => {
               headerNames.push(name);
             });
-            headerCapture('response', headerNames)(
-              span,
-              (header) => response.headers.get(header) ?? '',
-            );
+            headerCapture('response', headerNames, {
+              maskFields: maskFields?.headers,
+            })(span, (header) => response.headers.get(header) ?? '');
           }
           response
             .clone()
             .text()
             .then((body) => {
-              span.setAttribute('http.response.body', body);
+              span.setAttribute(
+                'http.response.body',
+                maskBody(body, maskFields?.body),
+              );
             })
             .catch(() => {
               // Ignore

packages/otel-web/src/HyperDXXMLHttpRequestInstrumentation.ts

@@ -6,7 +6,7 @@ import {
 } from '@opentelemetry/instrumentation-xml-http-request';
 
 import { captureTraceParent } from './servertiming';
-import { headerCapture } from './utils';
+import { headerCapture, maskBody, MaskFieldsConfig } from './utils';
 
 type ExposedSuper = {
   _addResourceObserver: (xhr: XMLHttpRequest, spanUrl: string) => void;
@@ -20,6 +20,7 @@ type ExposedSuper = {
 export type HyperDXXMLHttpRequestInstrumentationConfig =
   XMLHttpRequestInstrumentationConfig & {
     advancedNetworkCapture?: () => boolean;
+    maskFields?: () => MaskFieldsConfig | undefined;
   };
 
 export class HyperDXXMLHttpRequestInstrumentation extends XMLHttpRequestInstrumentation {
@@ -36,17 +37,24 @@ export class HyperDXXMLHttpRequestInstrumentation extends XMLHttpRequestInstrume
       if (span) {
         if (config.advancedNetworkCapture?.()) {
           xhr.addEventListener('readystatechange', function () {
+            const maskFields = config.maskFields?.();
+
             if (xhr.readyState === xhr.OPENED) {
               shimmer.wrap(xhr, 'setRequestHeader', (original) => {
                 return function (header, value) {
-                  headerCapture('request', [header])(span, () => value);
+                  headerCapture('request', [header], {
+                    maskFields: maskFields?.headers,
+                  })(span, () => value);
                   return original.apply(this, arguments);
                 };
               });
               shimmer.wrap(xhr, 'send', (original) => {
                 return function (body) {
                   if (body) {
-                    span.setAttribute('http.request.body', body.toString());
+                    span.setAttribute(
+                      'http.request.body',
+                      maskBody(body, maskFields?.body),
+                    );
                   }
                   return original.apply(this, arguments);
                 };
@@ -62,12 +70,14 @@ export class HyperDXXMLHttpRequestInstrumentation extends XMLHttpRequestInstrume
                   }
                   return result;
                 }, {});
-              headerCapture('response', Object.keys(headers))(
-                span,
-                (header) => headers[header],
-              );
+              headerCapture('response', Object.keys(headers), {
+                maskFields: maskFields?.headers,
+              })(span, (header) => headers[header]);
               try {
-                span.setAttribute('http.response.body', xhr.responseText);
+                span.setAttribute(
+                  'http.response.body',
+                  maskBody(xhr.responseText, maskFields?.body),
+                );
               } catch (e) {
                 // ignore (DOMException if responseType is not the empty string or "text")
               }