session-replay: PII defaults (#257)

* session-replay: pass privacy options and set defaults

* browser example: add input to demonstrate session replay PII

* session-replay: update default block/mask/ignore classes to bt-*

* session-replay: add additional options to text masking

* browser example: add example of unmasked text

---------

Co-authored-by: Sebastian Alex <[email protected]>

Author: perf2711

examples/sdk/browser/index.html

@@ -24,6 +24,8 @@
                 <h1 class="card-header" style="text-align: center">Welcome to the Backtrace demo</h1>
                 <p style="text-align: center">Please pick one of the available options:</p>
                 <br />
+                <p style="text-align: center" class="bt-unmask">This text has class rr-unmask, and will be unmasked on Session Replay.</p>
+                <input class="center" type="text" placeholder="Test Session Replay Input!">
                 <div class="action-container center">
                     <div class="action-button center">
                         <a class="text" id="send-error" target="_blank"> Send an error</a>

package-lock.json

@@ -0,0 +1,5 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'jsdom',
+};

packages/session-replay/jest.config.js

@@ -9,7 +9,8 @@
         "clean": "tsc -b --clean && rimraf \"lib\"",
         "format": "prettier --write '**/*.ts'",
         "lint": "eslint . --ext .ts",
-        "watch": "tsc -w"
+        "watch": "tsc -w",
+        "test": "cross-env NODE_ENV=test jest"
     },
     "repository": {
         "type": "git",
@@ -29,5 +30,8 @@
     },
     "dependencies": {
         "rrweb": "^2.0.0-alpha.15"
+    },
+    "devDependencies": {
+        "jest-environment-jsdom": "^29.7.0"
     }
 }

packages/session-replay/package.json

@@ -2,6 +2,7 @@ import { BacktraceAttachment, OverwritingArray } from '@backtrace/sdk-core';
 import { eventWithTime } from '@rrweb/types';
 import { record } from 'rrweb';
 import { BacktraceSessionRecorderOptions } from './options';
+import { maskTextFn } from './privacy/maskTextFn';
 
 export class BacktraceSessionRecorder implements BacktraceAttachment {
     public readonly name = 'bt-session-replay-0';
@@ -22,17 +23,35 @@ export class BacktraceSessionRecorder implements BacktraceAttachment {
 
     public start() {
         this._stop = record({
+            blockClass: this._options.privacy?.blockClass ?? 'bt-block',
+            blockSelector: this._options.privacy?.blockSelector,
+            ignoreClass: this._options.privacy?.ignoreClass ?? 'bt-ignore',
+            ignoreSelector: this._options.privacy?.ignoreSelector,
+            ignoreCSSAttributes: new Set(this._options.privacy?.ignoreCSSAttributes),
+            maskTextSelector: '*', // Pass all text to maskTextFn
+            maskAllInputs: this._options.privacy?.maskAllInputs ?? true,
+            maskInputFn: this._options.privacy?.maskInputFn,
+            maskTextFn: maskTextFn({
+                maskAllText: this._options.privacy?.maskAllText ?? true,
+                maskTextClass: this._options.privacy?.maskTextClass ?? 'bt-mask',
+                unmaskTextClass: this._options.privacy?.unmaskTextClass ?? 'bt-unmask',
+                maskTextSelector: this._options.privacy?.maskTextSelector,
+                unmaskTextSelector: this._options.privacy?.unmaskTextSelector,
+                maskTextFn: this._options.privacy?.maskTextFn,
+            }),
             ...this._options.advancedOptions,
             sampling: {
                 mousemove: this._options.sampling?.mousemove,
                 mouseInteraction: this._options.sampling?.mouseInteraction,
                 input: this._options.sampling?.input,
                 media: this._options.sampling?.media,
                 scroll: this._options.sampling?.scroll,
-                ...this._options.advancedOptions,
+                ...this._options.advancedOptions?.sampling,
             },
             emit: (event, isCheckout) => this.onEmit(event, isCheckout),
-            checkoutEveryNth: this._maxEventCount && Math.ceil(this._maxEventCount / 2),
+            checkoutEveryNth:
+                this._options.advancedOptions?.checkoutEveryNth ??
+                (this._maxEventCount && Math.ceil(this._maxEventCount / 2)),
         });
     }
 

packages/session-replay/src/BacktraceSessionRecorder.ts

@@ -72,8 +72,8 @@ export interface BacktraceSessionRecorderSamplingOptions {
 
 export interface BacktraceSessionReplayPrivacyOptions {
     /**
-     * Use a `string` or `RegExp` to configure which elements should be blocked.
-     * @default "rr-block"
+     * Blocks elements with this class.
+     * @default "bt-block"
      */
     readonly blockClass?: string | RegExp;
 
@@ -84,8 +84,8 @@ export interface BacktraceSessionReplayPrivacyOptions {
     readonly blockSelector?: string;
 
     /**
-     * Use a `string` or `RegExp` to configure which elements should be ignored.
-     * @default "rr-ignore"
+     * Ignores elements with this class.
+     * @default "bt-ignore"
      */
     readonly ignoreClass?: string;
 
@@ -98,33 +98,51 @@ export interface BacktraceSessionReplayPrivacyOptions {
     /**
      * Array of CSS attributes that should be ignored.
      */
-    readonly ignoreCSSAttributes?: string;
+    readonly ignoreCSSAttributes?: Set<string>;
 
     /**
-     * Use a `string` or `RegExp` to configure which elements should be masked.
-     * @default "rr-mask"
+     * Masks elements with this class.
+     * @default "bt-mask"
      */
     readonly maskTextClass?: string;
 
     /**
-     * Use a `string` to configure which selector should be masked.
+     * Unmasks elements with this class.
+     * @default "bt-unmask"
+     */
+    readonly unmaskTextClass?: string | RegExp;
+
+    /**
+     * Masks elements matching this selector.
      * @default undefined
      */
     readonly maskTextSelector?: string;
 
+    /**
+     * Unmasks elements matching this selector.
+     * @default undefined
+     */
+    readonly unmaskTextSelector?: string;
+
     /**
      * If `true`, will mask all inputs.
-     * @default false
+     * @default true
      */
     readonly maskAllInputs?: boolean;
 
     /**
-     * Mask specific kinds of input.
+     * If `true`, will mask all text.
+     * @default true
+     */
+    readonly maskAllText?: boolean;
+
+    /**
+     * Mask specific kinds of inputs.
      *
      * Can be an object with the following keys:
      * * `color`
      * * `date`
-     * * `'datetime-local'`
+     * * `datetime-local`
      * * `email`
      * * `month`
      * * `number`

packages/session-replay/src/options.ts

@@ -0,0 +1,88 @@
+import { MaskTextFn } from 'rrweb-snapshot';
+
+export interface MaskTextFnOptions {
+    readonly maskAllText: boolean;
+    readonly maskTextSelector?: string;
+    readonly unmaskTextSelector?: string;
+    readonly maskTextClass?: string | RegExp;
+    readonly unmaskTextClass?: string | RegExp;
+    readonly maskTextFn?: MaskTextFn;
+}
+
+function maskCharacters(text: string) {
+    return text.replace(/[\S]/g, '*');
+}
+
+function testSelector(element: HTMLElement, selector?: string) {
+    if (!selector) {
+        return false;
+    }
+
+    return element.matches(selector);
+}
+
+function testClass(element: HTMLElement, expr?: string | RegExp) {
+    if (!expr) {
+        return false;
+    }
+
+    const test = typeof expr === 'string' ? (v: string) => v === expr : (v: string) => expr.test(v);
+    for (const c of element.classList) {
+        if (test(c)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Tests if element should be masked or not.
+ *
+ * Prefers masking elements, i.e. to be unmasked, the element cannot be matched by mask
+ * and has to be matched by unmask.
+ */
+function testElementPreferMask(element: HTMLElement, options: MaskTextFnOptions) {
+    if (testSelector(element, options.maskTextSelector) || testClass(element, options.maskTextClass)) {
+        return true;
+    }
+
+    if (testSelector(element, options.unmaskTextSelector) || testClass(element, options.unmaskTextClass)) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Tests if element should be masked or not.
+ *
+ * Prefers unmasking elements, i.e. to be masked, the element cannot be matched by unmask
+ * and has to be matched by mask.
+ */
+function testElementPreferUnmask(element: HTMLElement, options: MaskTextFnOptions) {
+    if (testSelector(element, options.unmaskTextSelector) || testClass(element, options.unmaskTextClass)) {
+        return false;
+    }
+
+    if (testSelector(element, options.maskTextSelector) || testClass(element, options.maskTextClass)) {
+        return true;
+    }
+
+    return false;
+}
+
+export function maskTextFn(options: MaskTextFnOptions): MaskTextFn {
+    const maskText = options.maskTextFn ? options.maskTextFn : maskCharacters;
+
+    return function maskTextFn(text, element) {
+        if (!element) {
+            return options.maskAllText ? maskText(text, element) : text;
+        }
+
+        const shouldBeMasked = options.maskAllText
+            ? testElementPreferMask(element, options)
+            : testElementPreferUnmask(element, options);
+
+        return shouldBeMasked ? maskText(text, element) : text;
+    };
+}