refactor(browser): drop maskPlaceholder, hardcode '***' default

No comparable browser RUM SDK (Sentry, Datadog) exposes a custom mask
placeholder, and the OpenTelemetry HTTP semantic conventions hardcode
'REDACTED' for sensitive query params. Removing maskPlaceholder simplifies
the API surface; the default '***' covers the realistic use cases. The
option can be reintroduced non-breakingly later if needed.

Author: wrn14897

.changeset/mask-network-fields.md

@@ -4,7 +4,7 @@
 ---
 
 Browser SDK: support masking sensitive fields in captured request/response
-headers and bodies before telemetry leaves the client. Add `maskFields` and
-`maskPlaceholder` options to `HyperDX.init`. Header matches are
-case-insensitive; body matches traverse nested JSON objects and accept dotted
-paths (e.g. `creditCard.number`).
+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

@@ -40,7 +40,8 @@ HyperDX.init({
   `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. Example:
+  response bodies are passed through unchanged. Matched values are replaced
+  with `***`. Example:
   ```js
   HyperDX.init({
     apiKey: '<YOUR_API_KEY_HERE>',
@@ -50,11 +51,8 @@ HyperDX.init({
       headers: ['authorization', 'x-api-key'],
       body: ['password', 'creditCard.number'],
     },
-    maskPlaceholder: '***',
   });
   ```
-- `maskPlaceholder` - (Optional) Replacement value used when a field matches
-  `maskFields`. Defaults to `'***'`.
 - `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

@@ -42,14 +42,10 @@ type BrowserSDKConfig = {
   /**
    * Sensitive field names to mask in captured request/response headers and
    * bodies before telemetry leaves the browser. Only applies when
-   * `advancedNetworkCapture` is enabled.
-   */
-  maskFields?: MaskFields;
-  /**
-   * Replacement value used when a field matches `maskFields`. Defaults to
+   * `advancedNetworkCapture` is enabled. Matched values are replaced with
    * `'***'`.
    */
-  maskPlaceholder?: string;
+  maskFields?: MaskFields;
   recordCanvas?: boolean;
   sampling?: RumRecorderConfig['sampling'];
   service: string;
@@ -70,7 +66,6 @@ function hasWindow() {
 class Browser {
   private _advancedNetworkCapture = false;
   private _maskFields: MaskFields | undefined;
-  private _maskPlaceholder: string | undefined;
 
   init({
     advancedNetworkCapture = false,
@@ -88,7 +83,6 @@ class Browser {
     maskAllText = false,
     maskClass,
     maskFields,
-    maskPlaceholder,
     recordCanvas = false,
     sampling,
     service,
@@ -120,7 +114,6 @@ class Browser {
 
     this._advancedNetworkCapture = advancedNetworkCapture;
     this._maskFields = maskFields;
-    this._maskPlaceholder = maskPlaceholder;
 
     Rum.init({
       debug,
@@ -141,7 +134,6 @@ class Browser {
             : {}),
           advancedNetworkCapture: () => this._advancedNetworkCapture,
           maskFields: () => this._maskFields,
-          maskPlaceholder: () => this._maskPlaceholder,
         },
         xhr: {
           ...(tracePropagationTargets != null
@@ -151,7 +143,6 @@ class Browser {
             : {}),
           advancedNetworkCapture: () => this._advancedNetworkCapture,
           maskFields: () => this._maskFields,
-          maskPlaceholder: () => this._maskPlaceholder,
         },
         ...instrumentations,
       },

packages/otel-web/src/HyperDXFetchInstrumentation.ts

@@ -9,7 +9,6 @@ import { headerCapture, maskBody, MaskFieldsConfig } from './utils';
 export type HyperDXFetchInstrumentationConfig = FetchInstrumentationConfig & {
   advancedNetworkCapture?: () => boolean;
   maskFields?: () => MaskFieldsConfig | undefined;
-  maskPlaceholder?: () => string | undefined;
 };
 
 // not used yet
@@ -45,12 +44,10 @@ export class HyperDXFetchInstrumentation extends FetchInstrumentation {
 
       if (config.advancedNetworkCapture?.() && span) {
         const maskFields = config.maskFields?.();
-        const maskPlaceholder = config.maskPlaceholder?.();
 
         if (request.headers) {
           headerCapture('request', Object.keys(request.headers), {
             maskFields: maskFields?.headers,
-            maskPlaceholder,
           })(span, (header) => request.headers?.[header]);
         }
         if (request.body) {
@@ -63,7 +60,7 @@ export class HyperDXFetchInstrumentation extends FetchInstrumentation {
           } else {
             span.setAttribute(
               'http.request.body',
-              maskBody(request.body, maskFields?.body, maskPlaceholder),
+              maskBody(request.body, maskFields?.body),
             );
           }
         }
@@ -76,7 +73,6 @@ export class HyperDXFetchInstrumentation extends FetchInstrumentation {
             });
             headerCapture('response', headerNames, {
               maskFields: maskFields?.headers,
-              maskPlaceholder,
             })(span, (header) => response.headers.get(header) ?? '');
           }
           response
@@ -85,7 +81,7 @@ export class HyperDXFetchInstrumentation extends FetchInstrumentation {
             .then((body) => {
               span.setAttribute(
                 'http.response.body',
-                maskBody(body, maskFields?.body, maskPlaceholder),
+                maskBody(body, maskFields?.body),
               );
             })
             .catch(() => {

packages/otel-web/src/HyperDXXMLHttpRequestInstrumentation.ts

@@ -21,7 +21,6 @@ export type HyperDXXMLHttpRequestInstrumentationConfig =
   XMLHttpRequestInstrumentationConfig & {
     advancedNetworkCapture?: () => boolean;
     maskFields?: () => MaskFieldsConfig | undefined;
-    maskPlaceholder?: () => string | undefined;
   };
 
 export class HyperDXXMLHttpRequestInstrumentation extends XMLHttpRequestInstrumentation {
@@ -39,14 +38,12 @@ export class HyperDXXMLHttpRequestInstrumentation extends XMLHttpRequestInstrume
         if (config.advancedNetworkCapture?.()) {
           xhr.addEventListener('readystatechange', function () {
             const maskFields = config.maskFields?.();
-            const maskPlaceholder = config.maskPlaceholder?.();
 
             if (xhr.readyState === xhr.OPENED) {
               shimmer.wrap(xhr, 'setRequestHeader', (original) => {
                 return function (header, value) {
                   headerCapture('request', [header], {
                     maskFields: maskFields?.headers,
-                    maskPlaceholder,
                   })(span, () => value);
                   return original.apply(this, arguments);
                 };
@@ -56,7 +53,7 @@ export class HyperDXXMLHttpRequestInstrumentation extends XMLHttpRequestInstrume
                   if (body) {
                     span.setAttribute(
                       'http.request.body',
-                      maskBody(body, maskFields?.body, maskPlaceholder),
+                      maskBody(body, maskFields?.body),
                     );
                   }
                   return original.apply(this, arguments);
@@ -75,12 +72,11 @@ export class HyperDXXMLHttpRequestInstrumentation extends XMLHttpRequestInstrume
                 }, {});
               headerCapture('response', Object.keys(headers), {
                 maskFields: maskFields?.headers,
-                maskPlaceholder,
               })(span, (header) => headers[header]);
               try {
                 span.setAttribute(
                   'http.response.body',
-                  maskBody(xhr.responseText, maskFields?.body, maskPlaceholder),
+                  maskBody(xhr.responseText, maskFields?.body),
                 );
               } catch (e) {
                 // ignore (DOMException if responseType is not the empty string or "text")

packages/otel-web/src/utils.ts

@@ -232,14 +232,14 @@ export function shouldMaskHeader(
 }
 
 /**
- * Mask matching fields inside a JSON-shaped request/response body. When the
- * body cannot be parsed as JSON the original string is returned unchanged.
- * Field paths support dotted notation (e.g. `creditCard.number`).
+ * Mask matching fields inside a JSON-shaped request/response body. Matched
+ * values are replaced with `DEFAULT_MASK_PLACEHOLDER`. When the body cannot
+ * be parsed as JSON the original string is returned unchanged. Field paths
+ * support dotted notation (e.g. `creditCard.number`).
  */
 export function maskBody(
   body: unknown,
   fieldsToMask: string[] | undefined,
-  placeholder: string = DEFAULT_MASK_PLACEHOLDER,
 ): string {
   const original = typeof body === 'string' ? body : jsonToString(body);
 
@@ -256,7 +256,7 @@ export function maskBody(
     return original;
   }
 
-  const masked = maskJsonValue(parsed, fieldsToMask, placeholder);
+  const masked = maskJsonValue(parsed, fieldsToMask);
 
   try {
     return JSON.stringify(masked);
@@ -267,18 +267,17 @@ export function maskBody(
 
 /**
  * Recursively walk a parsed JSON value and replace any property whose path
- * matches one of `fieldsToMask` with `placeholder`. Path comparison uses
- * dotted notation rooted at the top-level value.
+ * matches one of `fieldsToMask` with `DEFAULT_MASK_PLACEHOLDER`. Path
+ * comparison uses dotted notation rooted at the top-level value.
  */
 function maskJsonValue(
   value: unknown,
   fieldsToMask: string[],
-  placeholder: string,
   currentPath = '',
 ): unknown {
   if (Array.isArray(value)) {
     return value.map((item) =>
-      maskJsonValue(item, fieldsToMask, placeholder, currentPath),
+      maskJsonValue(item, fieldsToMask, currentPath),
     );
   }
 
@@ -287,12 +286,11 @@ function maskJsonValue(
     for (const key of Object.keys(value as Record<string, unknown>)) {
       const nextPath = currentPath ? `${currentPath}.${key}` : key;
       if (matchesField(key, nextPath, fieldsToMask)) {
-        result[key] = placeholder;
+        result[key] = DEFAULT_MASK_PLACEHOLDER;
       } else {
         result[key] = maskJsonValue(
           (value as Record<string, unknown>)[key],
           fieldsToMask,
-          placeholder,
           nextPath,
         );
       }
@@ -323,12 +321,11 @@ function matchesField(
 export function headerCapture(
   type: 'request' | 'response',
   headers: string[],
-  options: { maskFields?: string[]; maskPlaceholder?: string } = {},
+  options: { maskFields?: string[] } = {},
 ) {
   const normalizedHeaders = new Map(
     headers.map((header) => [header, header.toLowerCase().replace(/-/g, '_')]),
   );
-  const placeholder = options.maskPlaceholder ?? DEFAULT_MASK_PLACEHOLDER;
 
   return (
     span: Span,
@@ -347,9 +344,9 @@ export function headerCapture(
       let value: string | string[] | number = rawValue;
       if (masked) {
         if (Array.isArray(rawValue)) {
-          value = rawValue.map(() => placeholder);
+          value = rawValue.map(() => DEFAULT_MASK_PLACEHOLDER);
         } else {
-          value = placeholder;
+          value = DEFAULT_MASK_PLACEHOLDER;
         }
       }
 

packages/otel-web/test/masking.test.ts

@@ -93,12 +93,6 @@ describe('maskBody', () => {
     });
   });
 
-  it('uses a custom placeholder when provided', () => {
-    const body = JSON.stringify({ password: 'secret' });
-    const masked = JSON.parse(maskBody(body, ['password'], '[REDACTED]'));
-    assert.deepStrictEqual(masked, { password: '[REDACTED]' });
-  });
-
   it('returns the original body unchanged when it is not JSON', () => {
     const body = 'username=alice&password=secret';
     assert.strictEqual(maskBody(body, ['password']), body);
@@ -140,18 +134,6 @@ describe('headerCapture with masking', () => {
     ]);
   });
 
-  it('honors a custom mask placeholder', () => {
-    const span = makeFakeSpan();
-    headerCapture('request', ['x-api-key'], {
-      maskFields: ['x-api-key'],
-      maskPlaceholder: '[REDACTED]',
-    })(span as any, () => 'super-secret-token');
-
-    assert.deepStrictEqual(span.attributes['http.request.header.x_api_key'], [
-      '[REDACTED]',
-    ]);
-  });
-
   it('matches header names case-insensitively', () => {
     const span = makeFakeSpan();
     headerCapture('request', ['Authorization'], {