From 4c89b129724c0285ca1439d3099d3a25830b4b1f Mon Sep 17 00:00:00 2001
From: Rogier Trimpe <rogiertrimpe@MacBook-Pro-2.local>
Date: Thu, 27 Aug 2026 09:39:51 +0200
Subject: [PATCH 1/4] =?UTF-8?q?feat(privacy):=20Privacy=20at=20Capture=20?=
 =?UTF-8?q?=E2=80=94=20recorded-DOM=20URL=20sanitization=20(experimental)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../privacy-at-capture-url-sanitization.md    | 22 ++++++
 guide.md                                      | 37 ++++++----
 packages/rrweb-snapshot/src/privacy.ts        | 72 ++++++++++++++++++-
 packages/rrweb-snapshot/src/types.ts          |  1 +
 .../test/privacy-integration.test.ts          | 51 ++++++++++---
 packages/rrweb-snapshot/test/privacy.test.ts  | 68 +++++++++++++++---
 packages/rrweb/src/index.ts                   |  1 +
 packages/rrweb/src/record/index.ts            |  5 +-
 packages/types/src/index.ts                   | 15 ++++
 9 files changed, 240 insertions(+), 32 deletions(-)
 create mode 100644 .changeset/privacy-at-capture-url-sanitization.md

diff --git a/.changeset/privacy-at-capture-url-sanitization.md b/.changeset/privacy-at-capture-url-sanitization.md
new file mode 100644
index 0000000000..d5f830ed25
--- /dev/null
+++ b/.changeset/privacy-at-capture-url-sanitization.md
@@ -0,0 +1,22 @@
+---
+"rrweb": minor
+"rrweb-snapshot": minor
+"@rrweb/types": minor
+---
+
+Privacy at Capture: recorded-DOM URL sanitization (**experimental** -- no
+vendor precedent, review this hardest).
+
+- Under `balanced`/`strict`, every URL-bearing attribute the serializer emits
+  and the Meta event's `href` go through `sanitizeUrl`: userinfo is
+  stripped, sensitive query parameter values are replaced with `*`
+  (`url.blockedQueryParameters` plus a default list), and the hash is
+  removed unless `url.removeHash: false`. `strict` blocks every parameter
+  value unless `url.allowedQueryParameters` names it.
+- An unparseable URL fails closed: the attribute is dropped (`null`) rather
+  than emptied, since an empty `src`/`href` re-resolves to the document URL
+  at replay.
+- The unmask escape cannot reopen a sanitized URL.
+- Rebased onto the renamed rule actions (`mask`/`block`/`unmask`) and the
+  opt-in `vendorCompat` flag; URL sanitization itself keys off the managed
+  presets and is unaffected by either.
diff --git a/guide.md b/guide.md
index 1e4880569c..cdd515d0fe 100644
--- a/guide.md
+++ b/guide.md
@@ -215,7 +215,7 @@ you get by default (the `minimal` preset, below):
 - `input[type="password"]` will be masked by default.
 - Mask options to mask the content in input elements.
 
-For a consistent policy across text, inputs, and attributes, pass a
+For a consistent policy across text, inputs, attributes, and URLs, pass a
 versioned `privacyPolicy`:
 
 ```js
@@ -240,17 +240,28 @@ record({
         action: 'block',
       },
     ],
+    url: {
+      blockedQueryParameters: ['token', 'session'],
+    },
   },
 });
 ```
 
 `preset` compiles to the following, on top of the `rules` above:
 
-| preset              | behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `minimal` (default) | Inert: only the existing masking options above apply. `rules` still work (below), but the `data-privacy` attribute and cross-vendor class recognition described below are off.                                                                                                                                                                                                                                                                                                                                  |
-| `balanced`          | Masks every input value (like `maskAllInputs: true`); masks the `title`, `placeholder`, and `aria-label` attributes on every element. Page text is untouched.                                                                                                                                                                                                                                                                                                                                                   |
-| `strict`            | Everything `balanced` does, plus: all page text is masked; media element sources (`<img>`, `<video>`, `<audio>`, `<iframe>`, `<embed>`, `<object>`, `<source>`) are dropped instead of captured, except that an `<img>` source or `<video>` poster on an element with declared integer `width`/`height` attributes is replaced by a neutral same-size placeholder image so the surrounding layout does not collapse; and canvas recording is disabled outright, even with a `canvasMasking` adapter configured. |
+| preset              | behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `minimal` (default) | Inert: only the existing masking options above apply. `rules` still work (below), but the `data-privacy` attribute and cross-vendor class recognition described below are off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `balanced`          | Masks every input value (like `maskAllInputs: true`); masks the `title`, `placeholder`, and `aria-label` attributes on every element; sanitizes URLs -- strips `username`/`password` (userinfo), removes the value of any query parameter in a default sensitive list (`access_token`, `auth`, `code`, `key`, `password`, `secret`, `session`, `token`) plus any configured `url.blockedQueryParameters`, and removes the hash unless `url.removeHash: false`. Query parameter names stay visible. Page text is untouched.                                                                                                                     |
+| `strict`            | Everything `balanced` does, plus: all page text is masked; media element sources (`<img>`, `<video>`, `<audio>`, `<iframe>`, `<embed>`, `<object>`, `<source>`) are dropped instead of captured, except that an `<img>` source or `<video>` poster on an element with declared integer `width`/`height` attributes is replaced by a neutral same-size placeholder image so the surrounding layout does not collapse; canvas recording is disabled outright, even with a `canvasMasking` adapter configured; and URL sanitization blocks _every_ query parameter's value unless you also set `url.allowedQueryParameters` to an explicit allow-list. |
+
+> **URL sanitization is experimental.** No session-replay vendor sanitizes
+> URLs inside the recorded DOM: PostHog, Highlight, Sentry, Amplitude and
+> Mixpanel all record `href`/`src` verbatim and scrub URLs in their ingestion
+> pipeline instead, if at all. rrweb's in-DOM `sanitizeUrl` is its own design,
+> not an established pattern, and it rewrites attribute values that the replay
+> then depends on. An unparseable URL is dropped entirely (the attribute is
+> removed) rather than emptied.
 
 `minimal` is a permanent tier, not a transitional one: it is masking you
 configure yourself, through the classic options above. Password and
@@ -503,8 +514,8 @@ covers text and the preset's masked attributes (`title`, `placeholder`,
 `aria-label`) on elements inside the matched subtree -- this option, a policy
 `unmask` rule and a recognized unmask class are merged into one
 selector and behave identically. It cannot unmask input
-values, and it cannot override a protected input, a dropped media source
-under `strict`, or a `block`.
+values or a sanitized URL, and it cannot override a protected input, a
+dropped media source under `strict`, or a `block`.
 
 An invalid `maskTextSelector`, `unmaskTextSelector` or `blockSelector` --
 either the `record()`-level string option or a policy rule's selector -- is
@@ -540,11 +551,11 @@ mutually exclusive: if both are supplied, `maskAllElementAttributes` wins and
 `maskAttributeFn` is ignored, with a one-time console warning. A throwing
 `maskAttributeFn` fails closed to stars rather than leaking the original
 value. Under `minimal`, `maskAttributeFn`'s return value is used as-is; under
-`balanced`/`strict` the compiled policy still runs on top of it
-(`title`/`placeholder`/`aria-label` masking, `strict`'s media-source drop)
-and can only
-narrow what the callback chose to keep, never restore something the policy
-would otherwise mask. `style`/`_cssText` are exempt from all of this.
+`balanced`/`strict` the compiled policy still runs on top of it (URL
+sanitization, `title`/`placeholder`/`aria-label` masking, `strict`'s
+media-source drop) and can only narrow what the callback chose to keep,
+never restore something the policy would otherwise mask. `style`/`_cssText`
+are exempt from all of this.
 Likewise, under `minimal`, `maskInputFn`'s return value is trusted verbatim;
 under `balanced`/`strict`, `maskInputFn` output is star-replaced -- the
 callback controls length, never content. Every callback fails closed the
diff --git a/packages/rrweb-snapshot/src/privacy.ts b/packages/rrweb-snapshot/src/privacy.ts
index a14c0ae076..cd7c2802c6 100644
--- a/packages/rrweb-snapshot/src/privacy.ts
+++ b/packages/rrweb-snapshot/src/privacy.ts
@@ -218,6 +218,18 @@ const RENDERING_METADATA_ATTRIBUTES = new Set([
 
 const OPERATIONAL_ATTRIBUTES = new Set(['data-privacy', 'data-rr-is-password']);
 
+const URL_ATTRIBUTES = new Set([
+  'action',
+  'background',
+  'data',
+  'formaction',
+  'href',
+  'poster',
+  'rr_src',
+  'src',
+  'xlink:href',
+]);
+
 /** Attributes that point at media bytes; dropped entirely under `strict`. */
 const MEDIA_SOURCE_ATTRIBUTES = new Set([
   'background',
@@ -252,6 +264,17 @@ export const FORM_VALUE_TAGS = new Set([
   'TEXTAREA',
 ]);
 
+const DEFAULT_BLOCKED_QUERY_PARAMETERS = [
+  'access_token',
+  'auth',
+  'code',
+  'key',
+  'password',
+  'secret',
+  'session',
+  'token',
+];
+
 /** Occludes text content, preserving whitespace so layout survives; contrast `stars`, which occludes to length. */
 function starText(value: string): string {
   return value.replace(/[\S]/g, '*');
@@ -416,6 +439,7 @@ export function compilePrivacyPolicy(
     );
   const maskedAttributes = new Set(managed ? MASKED_ATTRIBUTE_DEFAULTS : []);
   const blockMedia = preset === 'strict';
+  const sanitizeUrls = managed;
 
   const bySelector = {
     mask: [] as string[],
@@ -472,8 +496,22 @@ export function compilePrivacyPolicy(
       : null,
     maskAllInputs: managed,
     maskedAttributes,
-    attributePolicyInert: !blockMedia && maskedAttributes.size === 0,
+    attributePolicyInert:
+      !blockMedia && !sanitizeUrls && maskedAttributes.size === 0,
     blockMedia,
+    sanitizeUrls,
+    blockedQueryParameters: new Set(
+      [
+        ...DEFAULT_BLOCKED_QUERY_PARAMETERS,
+        ...(effective.url?.blockedQueryParameters || []),
+      ].map((n) => n.toLowerCase()),
+    ),
+    allowedQueryParameters: effective.url?.allowedQueryParameters
+      ? new Set(
+          effective.url.allowedQueryParameters.map((n) => n.toLowerCase()),
+        )
+      : null,
+    removeHash: effective.url?.removeHash !== false,
   };
 }
 
@@ -747,6 +785,7 @@ export function finalizeAttribute({
     if (MEDIA_TAGS.has(tagName))
       return blockedMediaValue(element, tagName, normalizedName);
   }
+  if (URL_ATTRIBUTES.has(normalizedName)) return sanitizeUrl(current, privacy);
   if (privacy.maskedAttributes.has(normalizedName)) {
     return isUnmasked(element, privacy, unmaskMemo) ? current : stars(current);
   }
@@ -794,3 +833,34 @@ export function finalizeAttributes(
     });
   }
 }
+
+/** EXPERIMENTAL: no session-replay vendor sanitizes URLs in the recorded DOM; see the changeset. */
+export function sanitizeUrl(
+  value: string,
+  privacy: CompiledPrivacyPolicy | undefined,
+): string | null {
+  if (!value) return value;
+  if (!privacy || !privacy.sanitizeUrls) return value;
+  try {
+    const url = new URL(value, 'https://rrweb.invalid');
+    url.username = '';
+    url.password = '';
+    for (const [name] of url.searchParams) {
+      const lower = name.toLowerCase();
+      if (
+        (privacy.preset === 'strict' && !privacy.allowedQueryParameters) ||
+        (privacy.allowedQueryParameters &&
+          !privacy.allowedQueryParameters.has(lower)) ||
+        privacy.blockedQueryParameters.has(lower)
+      ) {
+        url.searchParams.set(name, '*');
+      }
+    }
+    if (privacy.removeHash) url.hash = '';
+    if (url.origin === 'https://rrweb.invalid')
+      return `${url.pathname}${url.search}${url.hash}`;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/rrweb-snapshot/src/types.ts b/packages/rrweb-snapshot/src/types.ts
index 8267b105bb..cad290e922 100644
--- a/packages/rrweb-snapshot/src/types.ts
+++ b/packages/rrweb-snapshot/src/types.ts
@@ -82,6 +82,7 @@ export type {
   PrivacyRule,
   PrivacyTarget,
   VendorCompatId,
+  PrivacyUrlOptions,
   CompiledPrivacyPolicy,
 } from '@rrweb/types';
 
diff --git a/packages/rrweb-snapshot/test/privacy-integration.test.ts b/packages/rrweb-snapshot/test/privacy-integration.test.ts
index 452306d95f..ac4a4dc696 100644
--- a/packages/rrweb-snapshot/test/privacy-integration.test.ts
+++ b/packages/rrweb-snapshot/test/privacy-integration.test.ts
@@ -543,7 +543,7 @@ describe('finalizeAttribute', () => {
     ).toBe('Bob');
   });
 
-  it('strict nulls media sources, and only on media tags', () => {
+  it('strict nulls media sources; URLs sanitized elsewhere', () => {
     expect(
       finalizeAttribute({
         element: el(),
@@ -552,7 +552,15 @@ describe('finalizeAttribute', () => {
         privacy: strict,
       }),
     ).toBeNull();
-    // non-media element keeps its src under strict
+    expect(
+      finalizeAttribute({
+        element: el('<a href="#"></a>', 'a'),
+        name: 'href',
+        value: 'https://u:p@a.com/x?token=t',
+        privacy: balanced,
+      }),
+    ).toBe('https://a.com/x?token=*');
+    // non-media element keeps a sanitized src under strict
     expect(
       finalizeAttribute({
         element: el('<div></div>', 'div'),
@@ -560,7 +568,7 @@ describe('finalizeAttribute', () => {
         value: 'https://a.com/x?page=1',
         privacy: strict,
       }),
-    ).toBe('https://a.com/x?page=1');
+    ).toBe('https://a.com/x?page=*');
   });
 
   describe('dimension-preserving placeholders for blocked images', () => {
@@ -1054,7 +1062,15 @@ describe('finalizeAttribute', () => {
     expect(out).not.toContain('"Dave"'); // no escape -> still starred
   });
 
-  it('the unmask escape cannot reopen a blocked media source', () => {
+  it('the unmask escape cannot reopen a URL or a blocked media source', () => {
+    expect(
+      finalizeAttribute({
+        element: el('<img class="rr-unmask" src="https://a.com/?token=t">'),
+        name: 'src',
+        value: 'https://a.com/?token=t',
+        privacy: balanced,
+      }),
+    ).toBe('https://a.com/?token=*');
     expect(
       finalizeAttribute({
         element: el('<img class="rr-unmask" src="https://a.com/i.png">'),
@@ -1174,7 +1190,8 @@ describe('finalizeAttribute', () => {
         maskAttributeFn: () => '',
       }),
     ).toBeNull();
-    // On the branches that do not drop it, an emptied value stays empty.
+    // On the branches that do not drop it, an emptied value stays empty
+    // instead of being resolved into a path by sanitizeUrl.
     expect(
       finalizeAttribute({
         element: el('<a href="#"></a>', 'a'),
@@ -1216,7 +1233,7 @@ describe('finalizeAttribute', () => {
     ).toBe('*'.repeat('a longer value'.length));
   });
 
-  it('applies the strict media-source rule to the renamed rr_src', () => {
+  it('applies the strict media-source and URL rules to the renamed rr_src', () => {
     const iframe = () => el('<iframe src="https://x.com/"></iframe>', 'iframe');
     expect(
       finalizeAttribute({
@@ -1226,6 +1243,14 @@ describe('finalizeAttribute', () => {
         privacy: strict,
       }),
     ).toBeNull();
+    expect(
+      finalizeAttribute({
+        element: iframe(),
+        name: 'rr_src',
+        value: 'https://u:p@x.com/?token=t',
+        privacy: balanced,
+      }),
+    ).toBe('https://x.com/?token=*');
   });
 
   it('passes through null/empty values and untouched attributes', () => {
@@ -1252,8 +1277,8 @@ describe('attribute finalization through the serializer', () => {
   /**
    * A cross-origin `<iframe>` rrweb cannot see into has its `src` renamed to
    * `rr_src` *before* finalization runs, so the renamed name has to carry the
-   * same policy weight as `src` -- otherwise `strict`'s media-source drop
-   * would miss it and the frame URL would ride out of the recording verbatim.
+   * same policy weight as `src` -- otherwise userinfo and query tokens ride
+   * out of the recording verbatim.
    */
   function serializeOpaqueIframe(
     src: string,
@@ -1272,6 +1297,16 @@ describe('attribute finalization through the serializer', () => {
     return JSON.stringify(snapshot(document, { privacyPolicy }));
   }
 
+  it('sanitizes the renamed rr_src of a cross-origin iframe under balanced', () => {
+    const out = serializeOpaqueIframe('https://u:p@x.com/?token=t', {
+      version: 1,
+      preset: 'balanced',
+    });
+    expect(out).toContain('"rr_src":"https://x.com/?token=*"');
+    expect(out).not.toContain('u:p@x.com');
+    expect(out).not.toContain('token=t');
+  });
+
   it('drops the renamed rr_src of a cross-origin iframe under strict', () => {
     const out = serializeOpaqueIframe('https://u:p@x.com/?token=t', {
       version: 1,
diff --git a/packages/rrweb-snapshot/test/privacy.test.ts b/packages/rrweb-snapshot/test/privacy.test.ts
index bb58f97838..e2b2352a8f 100644
--- a/packages/rrweb-snapshot/test/privacy.test.ts
+++ b/packages/rrweb-snapshot/test/privacy.test.ts
@@ -7,6 +7,7 @@ import {
   validateSelector,
   mergeSelectors,
   resolvePrivacyContext,
+  sanitizeUrl,
   splitSelectorList,
   resolveTextValue,
   isEventIgnored,
@@ -48,8 +49,9 @@ describe('compilePrivacyPolicy v2', () => {
     expect(c.maskAllInputs).toBe(false);
     expect([...c.maskedAttributes]).toEqual([]);
     expect(c.attributePolicyInert).toBe(true);
+    expect(c.sanitizeUrls).toBe(false);
   });
-  it('balanced masks inputs and attributes but not text', () => {
+  it('balanced masks inputs, attributes and URLs but not text', () => {
     const c = compilePrivacyPolicy({ version: 1, preset: 'balanced' });
     expect(c.maskAllInputs).toBe(true);
     expect([...c.maskedAttributes]).toEqual([
@@ -57,6 +59,7 @@ describe('compilePrivacyPolicy v2', () => {
       'placeholder',
       'aria-label',
     ]);
+    expect(c.sanitizeUrls).toBe(true);
     expect(c.maskTextSelector).not.toContain('*');
     expect(c.maskTextSelector).toContain('[data-privacy]');
     expect(c.maskTextSelector).toContain('.rr-mask');
@@ -132,6 +135,15 @@ describe('compilePrivacyPolicy v2', () => {
       }),
     ).toThrow();
   });
+  it('precomputes lowercased query parameter sets', () => {
+    const c = compilePrivacyPolicy({
+      version: 1,
+      preset: 'strict',
+      url: { blockedQueryParameters: ['SessionID'] },
+    });
+    expect(c.blockedQueryParameters.has('sessionid')).toBe(true);
+    expect(c.blockedQueryParameters.has('token')).toBe(true); // default list
+  });
 });
 /**
  * `data-privacy` carries a fixed vocabulary. A value outside it is almost
@@ -1187,14 +1199,52 @@ describe('merge helpers validate the record()-level selector', () => {
     expect(warn).toHaveBeenCalled();
   });
 });
-/**
- * `needMaskingText` is exported from the package root and its third parameter
- * changed shape (raw selector string -> pre-split `{maskAll, selector}`). An
- * un-updated or untyped caller still passing the string used to destructure to
- * `{maskAll: undefined, selector: undefined}`, at which point every mask
- * selector silently stopped matching -- a fail-open on the masking path, which
- * is the one direction that must never happen quietly.
- */
+
+describe('sanitizeUrl v2', () => {
+  const strict = compilePrivacyPolicy({ version: 1, preset: 'strict' });
+  const balanced = compilePrivacyPolicy({ version: 1, preset: 'balanced' });
+  const manual = compilePrivacyPolicy(undefined);
+  it('strips userinfo credentials', () => {
+    expect(
+      sanitizeUrl('https://alice:hunter2@api.example.com/x', balanced),
+    ).toBe('https://api.example.com/x');
+  });
+  it('masks blocked query parameters, case-insensitively', () => {
+    expect(sanitizeUrl('https://a.com/?Token=abc&ok=1', balanced)).toBe(
+      'https://a.com/?Token=*&ok=1',
+    );
+  });
+  it('strict masks all params unless allowlisted', () => {
+    const allow = compilePrivacyPolicy({
+      version: 1,
+      preset: 'strict',
+      url: { allowedQueryParameters: ['page'] },
+    });
+    expect(sanitizeUrl('https://a.com/?page=2&q=x', strict)).toBe(
+      'https://a.com/?page=*&q=*',
+    );
+    expect(sanitizeUrl('https://a.com/?page=2&q=x', allow)).toBe(
+      'https://a.com/?page=2&q=*',
+    );
+  });
+  it('removes hash unless disabled; manual passes through untouched', () => {
+    expect(sanitizeUrl('https://a.com/x#frag', balanced)).toBe(
+      'https://a.com/x',
+    );
+    expect(sanitizeUrl('https://alice:pw@a.com/?token=x#f', manual)).toBe(
+      'https://alice:pw@a.com/?token=x#f',
+    );
+  });
+  it('unparseable value under non-manual fails closed by dropping the attribute', () => {
+    expect(sanitizeUrl('http://[broken', balanced)).toBeNull();
+  });
+  it('empty in, empty out -- never resolved into a path', () => {
+    expect(sanitizeUrl('', balanced)).toBe('');
+    expect(sanitizeUrl('', strict)).toBe('');
+    expect(sanitizeUrl('', manual)).toBe('');
+  });
+});
+
 describe('resolveTextValue: exemptScript', () => {
   const script = document.createElement('script');
   it('exempts SCRIPT text from masking when exemptScript is true (the snapshot path)', () => {
diff --git a/packages/rrweb/src/index.ts b/packages/rrweb/src/index.ts
index 18b8f20f14..de6a0ab964 100644
--- a/packages/rrweb/src/index.ts
+++ b/packages/rrweb/src/index.ts
@@ -29,6 +29,7 @@ export type {
   PrivacyPreset,
   PrivacyRule,
   PrivacyTarget,
+  PrivacyUrlOptions,
 } from 'rrweb-snapshot';
 
 const { addCustomEvent } = record;
diff --git a/packages/rrweb/src/record/index.ts b/packages/rrweb/src/record/index.ts
index c63b189433..3fee853a5c 100644
--- a/packages/rrweb/src/record/index.ts
+++ b/packages/rrweb/src/record/index.ts
@@ -4,6 +4,7 @@ import {
   type MaskInputOptions,
   createMirror,
   resolvePrivacyContext,
+  sanitizeUrl,
 } from 'rrweb-snapshot';
 import { initObservers, mutationBuffers } from './observer';
 import {
@@ -387,7 +388,9 @@ function record<T = eventWithTime>(
       {
         type: EventType.Meta,
         data: {
-          href: window.location.href,
+          // Meta's `href` is a required string; '' is the inert fallback for
+          // an unparseable URL, which `sanitizeUrl` otherwise drops (null).
+          href: sanitizeUrl(window.location.href, privacy) ?? '',
           width: getWindowWidth(),
           height: getWindowHeight(),
         },
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 73a419dc32..e25c8e5df9 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -318,6 +318,7 @@ export type PrivacyPolicy = {
   rules?: PrivacyRule[];
   /** Opt in to recognizing other session-replay tools' privacy classes/attributes; off by default. `true` recognizes every verified vendor; an array recognizes only the named ones. */
   vendorCompat?: boolean | VendorCompatId[];
+  url?: PrivacyUrlOptions;
 };
 
 /** A vendor whose mask/block conventions `vendorCompat` can recognize; see guide.md's "Vendor class recognition" table. */
@@ -363,6 +364,14 @@ export type PrivacyTarget = {
   selector: string;
 };
 
+export type PrivacyUrlOptions = {
+  /** Query parameter names whose values are always removed. */
+  blockedQueryParameters?: string[];
+  /** When supplied, all query parameter values except these are removed. */
+  allowedQueryParameters?: string[];
+  removeHash?: boolean;
+};
+
 /** Runtime form of a compiled policy, shared by snapshot and incremental observers. */
 export type CompiledPrivacyPolicy = {
   preset: PrivacyPreset;
@@ -384,6 +393,12 @@ export type CompiledPrivacyPolicy = {
   attributePolicyInert: boolean;
   /** true under strict; the `strict` preset alias every media gate reads */
   blockMedia: boolean;
+  /** true under balanced/strict */
+  sanitizeUrls: boolean;
+  /** precomputed, lowercased */
+  blockedQueryParameters: Set<string>;
+  allowedQueryParameters: Set<string> | null;
+  removeHash: boolean;
 };
 
 export type RecordPlugin<TOptions = unknown> = {

From c3ee3162d8bedb41a9210e0375791821820ab8a6 Mon Sep 17 00:00:00 2001
From: Rogier Trimpe <rogiertrimpe@MacBook-Pro-2.local>
Date: Sun, 30 Aug 2026 12:59:19 +0200
Subject: [PATCH 2/4] feat(privacy-url): scope the Meta event's own href
 differently under strict

Add sanitizeMetaUrl (blocked-list-only param masking) for the Meta event's
window.location.href call site in record/index.ts, so strict's
mask-every-param-unless-allowlisted rule applies only to DOM URL
attributes -- the Meta href is the recording's own address, not markup a
page author wrote, so masking every one of its params (most apps' own
routing state) would make strict useless for identifying which page a
session happened on. Implemented as an internal paramsMode option on
sanitizeUrl so the special case stays inside this layer; core has no
sanitizeUrl branch. Flagged in guide.md and the changeset as an open
design question for upstream.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../privacy-at-capture-url-sanitization.md    |  6 +++
 guide.md                                      |  9 ++++
 packages/rrweb-snapshot/src/privacy.ts        | 39 +++++++++++++++++-
 packages/rrweb-snapshot/test/privacy.test.ts  | 41 +++++++++++++++++++
 packages/rrweb/src/record/index.ts            |  9 ++--
 packages/rrweb/test/record/privacy.test.ts    | 39 ++++++++++++++++++
 6 files changed, 138 insertions(+), 5 deletions(-)

diff --git a/.changeset/privacy-at-capture-url-sanitization.md b/.changeset/privacy-at-capture-url-sanitization.md
index d5f830ed25..e1aecf5c6c 100644
--- a/.changeset/privacy-at-capture-url-sanitization.md
+++ b/.changeset/privacy-at-capture-url-sanitization.md
@@ -13,6 +13,12 @@ vendor precedent, review this hardest).
   (`url.blockedQueryParameters` plus a default list), and the hash is
   removed unless `url.removeHash: false`. `strict` blocks every parameter
   value unless `url.allowedQueryParameters` names it.
+- **EXPERIMENTAL, open design question for upstream:** the Meta event's
+  `href` (via the new `sanitizeMetaUrl`) is scoped like `balanced` even
+  under `strict` -- masking only blocked-list parameters -- because it is
+  the recording's own address, not page-author markup; every DOM URL
+  attribute keeps `strict`'s normal mask-everything-unless-allowlisted
+  treatment.
 - An unparseable URL fails closed: the attribute is dropped (`null`) rather
   than emptied, since an empty `src`/`href` re-resolves to the document URL
   at replay.
diff --git a/guide.md b/guide.md
index cdd515d0fe..650e39db37 100644
--- a/guide.md
+++ b/guide.md
@@ -262,6 +262,15 @@ record({
 > not an established pattern, and it rewrites attribute values that the replay
 > then depends on. An unparseable URL is dropped entirely (the attribute is
 > removed) rather than emptied.
+>
+> One deliberate asymmetry within that design, itself an open question for
+> upstream: the Meta event's own `href` -- the recording's address, not
+> markup a page author wrote -- is scoped like `balanced` (only the
+> blocked-list parameters are masked) even under `strict`, where every DOM
+> URL attribute masks every parameter unless explicitly allowlisted.
+> Treating the Meta href identically to an arbitrary `<a href>` would make
+> `strict` unable to say which page a session happened on, since most apps
+> put routing state in their own URL.
 
 `minimal` is a permanent tier, not a transitional one: it is masking you
 configure yourself, through the classic options above. Password and
diff --git a/packages/rrweb-snapshot/src/privacy.ts b/packages/rrweb-snapshot/src/privacy.ts
index cd7c2802c6..97b9154821 100644
--- a/packages/rrweb-snapshot/src/privacy.ts
+++ b/packages/rrweb-snapshot/src/privacy.ts
@@ -834,10 +834,22 @@ export function finalizeAttributes(
   }
 }
 
-/** EXPERIMENTAL: no session-replay vendor sanitizes URLs in the recorded DOM; see the changeset. */
+/**
+ * EXPERIMENTAL: no session-replay vendor sanitizes URLs in the recorded DOM;
+ * see the changeset.
+ *
+ * `paramsMode` is an internal knob, not part of the public policy surface:
+ * `'preset'` (the default) is `strict`'s normal mask-every-param-unless-
+ * allowlisted behavior; `'blocklist'` forces the `balanced` treatment
+ * (mask only `blockedQueryParameters`/non-`allowedQueryParameters`) even
+ * under `strict`. `sanitizeMetaUrl` is the one caller that needs it -- see
+ * its doc comment. This keeps the preset special-case inside the URL layer
+ * instead of leaking a `strict`-vs-Meta branch into core.
+ */
 export function sanitizeUrl(
   value: string,
   privacy: CompiledPrivacyPolicy | undefined,
+  { paramsMode = 'preset' }: { paramsMode?: 'preset' | 'blocklist' } = {},
 ): string | null {
   if (!value) return value;
   if (!privacy || !privacy.sanitizeUrls) return value;
@@ -845,10 +857,14 @@ export function sanitizeUrl(
     const url = new URL(value, 'https://rrweb.invalid');
     url.username = '';
     url.password = '';
+    const maskAllParams =
+      paramsMode === 'preset' &&
+      privacy.preset === 'strict' &&
+      !privacy.allowedQueryParameters;
     for (const [name] of url.searchParams) {
       const lower = name.toLowerCase();
       if (
-        (privacy.preset === 'strict' && !privacy.allowedQueryParameters) ||
+        maskAllParams ||
         (privacy.allowedQueryParameters &&
           !privacy.allowedQueryParameters.has(lower)) ||
         privacy.blockedQueryParameters.has(lower)
@@ -864,3 +880,22 @@ export function sanitizeUrl(
     return null;
   }
 }
+
+/**
+ * EXPERIMENTAL, open design question for upstream: sanitizes the Meta
+ * event's `window.location.href` with blocked-list-only parameter masking
+ * (the `balanced` treatment), even under `strict`, where every other URL in
+ * the recorded DOM masks every param unless explicitly allowlisted. The
+ * Meta event's URL is the recording's own address bar, not markup the page
+ * author wrote -- treating it identically to an arbitrary `<a href>` would
+ * make `strict` unusable for reconstructing which page a session happened
+ * on, since almost every app puts routing state in its own URL. Whether
+ * that asymmetry is the right default, versus a dedicated option, is not
+ * settled; see the changeset.
+ */
+export function sanitizeMetaUrl(
+  value: string,
+  privacy: CompiledPrivacyPolicy | undefined,
+): string | null {
+  return sanitizeUrl(value, privacy, { paramsMode: 'blocklist' });
+}
diff --git a/packages/rrweb-snapshot/test/privacy.test.ts b/packages/rrweb-snapshot/test/privacy.test.ts
index e2b2352a8f..04c4c23db3 100644
--- a/packages/rrweb-snapshot/test/privacy.test.ts
+++ b/packages/rrweb-snapshot/test/privacy.test.ts
@@ -8,6 +8,7 @@ import {
   mergeSelectors,
   resolvePrivacyContext,
   sanitizeUrl,
+  sanitizeMetaUrl,
   splitSelectorList,
   resolveTextValue,
   isEventIgnored,
@@ -1245,6 +1246,46 @@ describe('sanitizeUrl v2', () => {
   });
 });
 
+/**
+ * EXPERIMENTAL, open design question for upstream (see `sanitizeMetaUrl`'s
+ * doc comment): the Meta event's own `href` is scoped like `balanced`
+ * (blocked-list-only param masking) even under `strict`, while every DOM
+ * URL attribute keeps `strict`'s normal mask-everything-unless-allowlisted
+ * treatment. Without this, `strict` would star every query param on the
+ * page's own address, including ordinary routing state most apps put
+ * there.
+ */
+describe('sanitizeMetaUrl scopes the Meta href differently than DOM URL attributes', () => {
+  const strict = compilePrivacyPolicy({ version: 1, preset: 'strict' });
+
+  it('keeps a non-blocked param under strict', () => {
+    expect(sanitizeMetaUrl('https://a.com/?page=2', strict)).toBe(
+      'https://a.com/?page=2',
+    );
+  });
+
+  it('still masks a blocked-list param under strict', () => {
+    expect(sanitizeMetaUrl('https://a.com/?token=x', strict)).toBe(
+      'https://a.com/?token=*',
+    );
+  });
+
+  it('is strictly narrower than plain sanitizeUrl under strict, never broader', () => {
+    const metaOut = sanitizeMetaUrl('https://a.com/?page=2&token=x', strict);
+    const domOut = sanitizeUrl('https://a.com/?page=2&token=x', strict);
+    expect(metaOut).toBe('https://a.com/?page=2&token=*');
+    // The DOM path masks `page` too -- strict masks everything unless
+    // explicitly allowlisted, and no allowlist was configured here.
+    expect(domOut).toBe('https://a.com/?page=*&token=*');
+  });
+
+  it('a DOM URL attribute is unaffected: strict still masks every param', () => {
+    expect(sanitizeUrl('https://a.com/?page=2&q=x', strict)).toBe(
+      'https://a.com/?page=*&q=*',
+    );
+  });
+});
+
 describe('resolveTextValue: exemptScript', () => {
   const script = document.createElement('script');
   it('exempts SCRIPT text from masking when exemptScript is true (the snapshot path)', () => {
diff --git a/packages/rrweb/src/record/index.ts b/packages/rrweb/src/record/index.ts
index 3fee853a5c..d073c7f61d 100644
--- a/packages/rrweb/src/record/index.ts
+++ b/packages/rrweb/src/record/index.ts
@@ -4,7 +4,7 @@ import {
   type MaskInputOptions,
   createMirror,
   resolvePrivacyContext,
-  sanitizeUrl,
+  sanitizeMetaUrl,
 } from 'rrweb-snapshot';
 import { initObservers, mutationBuffers } from './observer';
 import {
@@ -389,8 +389,11 @@ function record<T = eventWithTime>(
         type: EventType.Meta,
         data: {
           // Meta's `href` is a required string; '' is the inert fallback for
-          // an unparseable URL, which `sanitizeUrl` otherwise drops (null).
-          href: sanitizeUrl(window.location.href, privacy) ?? '',
+          // an unparseable URL, which `sanitizeMetaUrl` otherwise drops
+          // (null). `sanitizeMetaUrl` masks only blocked-list params, even
+          // under `strict` -- see its doc comment for why the Meta event's
+          // own URL is scoped differently than a DOM URL attribute.
+          href: sanitizeMetaUrl(window.location.href, privacy) ?? '',
           width: getWindowWidth(),
           height: getWindowHeight(),
         },
diff --git a/packages/rrweb/test/record/privacy.test.ts b/packages/rrweb/test/record/privacy.test.ts
index 4eb48982e9..4c858aebd1 100644
--- a/packages/rrweb/test/record/privacy.test.ts
+++ b/packages/rrweb/test/record/privacy.test.ts
@@ -523,3 +523,42 @@ describe('record() input events under data-privacy="ignore"', () => {
     expect(texts).not.toContain('secret after');
   });
 });
+
+/**
+ * EXPERIMENTAL, open design question for upstream: the Meta event's own
+ * `href` is scoped like `balanced` (blocked-list-only param masking) even
+ * under `strict`, while a DOM URL attribute keeps `strict`'s normal
+ * mask-everything-unless-allowlisted treatment. See `sanitizeMetaUrl`'s doc
+ * comment in `rrweb-snapshot/src/privacy.ts`.
+ */
+describe('record() Meta event href under strict', () => {
+  function metaHref(events: eventWithTime[]): string | undefined {
+    const meta = events.find((event) => event.type === EventType.Meta);
+    return meta && meta.type === EventType.Meta ? meta.data.href : undefined;
+  }
+
+  it('keeps a non-blocked query param', () => {
+    const originalPushState = window.history.pushState.bind(window.history);
+    originalPushState(null, '', '/path?page=2');
+    const events: eventWithTime[] = [];
+    const stop = record({
+      emit: (event) => events.push(event),
+      privacyPolicy: { version: 1, preset: 'strict' },
+    });
+    stop?.();
+    expect(metaHref(events)).toContain('page=2');
+  });
+
+  it('still masks a blocked-list query param', () => {
+    const originalPushState = window.history.pushState.bind(window.history);
+    originalPushState(null, '', '/path?token=secret');
+    const events: eventWithTime[] = [];
+    const stop = record({
+      emit: (event) => events.push(event),
+      privacyPolicy: { version: 1, preset: 'strict' },
+    });
+    stop?.();
+    expect(metaHref(events)).toContain('token=*');
+    expect(metaHref(events)).not.toContain('secret');
+  });
+});

From 6448ea101ee7f7cb6ebbf1468cb4ab0698016756 Mon Sep 17 00:00:00 2001
From: Rogier Trimpe <rogiertrimpe@MacBook-Pro-2.local>
Date: Sun, 30 Aug 2026 13:57:17 +0200
Subject: [PATCH 3/4] docs(privacy-url): disclose that sanitization rewrites
 relative URLs root-relative

Sanitization parses against an internal base URL and re-serializes the path,
so a relative URL in an attribute rrweb does not already absolutify
(`<form action>`, `<video poster>`, ...) is recorded root-relative:
`pay/confirm` becomes `/pay/confirm`. Behavior unchanged; this was
undocumented.

refactor(privacy): rename the `manual` preset to `minimal` throughout the
url-sanitization layer's own additions -- the `sanitizeUrl` test fixtures
and test names. Clean rename, nothing released; the record()-level
"manual selector"/"manual half" test names are unrelated and untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/privacy-at-capture-url-sanitization.md |  5 ++++-
 guide.md                                          |  6 ++++++
 packages/rrweb-snapshot/test/privacy.test.ts      | 10 +++++-----
 3 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/.changeset/privacy-at-capture-url-sanitization.md b/.changeset/privacy-at-capture-url-sanitization.md
index e1aecf5c6c..6d6ca49d6f 100644
--- a/.changeset/privacy-at-capture-url-sanitization.md
+++ b/.changeset/privacy-at-capture-url-sanitization.md
@@ -21,7 +21,10 @@ vendor precedent, review this hardest).
   treatment.
 - An unparseable URL fails closed: the attribute is dropped (`null`) rather
   than emptied, since an empty `src`/`href` re-resolves to the document URL
-  at replay.
+  at replay. A _relative_ URL in an attribute rrweb does not already
+  absolutify (`<form action>`, `<video poster>`, ...) is rewritten
+  root-relative -- `pay/confirm` records as `/pay/confirm` -- because
+  sanitization parses against an internal base and re-serializes the path.
 - The unmask escape cannot reopen a sanitized URL.
 - Rebased onto the renamed rule actions (`mask`/`block`/`unmask`) and the
   opt-in `vendorCompat` flag; URL sanitization itself keys off the managed
diff --git a/guide.md b/guide.md
index 650e39db37..ee5284f2f5 100644
--- a/guide.md
+++ b/guide.md
@@ -670,6 +670,12 @@ Breaking changes versus pre-2.0 masking, for anyone upgrading:
   and **unstable**: exported for cross-package use and direct unit testing,
   not part of the supported API, and free to change or disappear without a
   major bump.
+- Under URL sanitization (`balanced`/`strict`), a **relative** URL in an
+  attribute rrweb does not already absolutify -- `<form action>`,
+  `<video poster>`, and similar -- is rewritten root-relative: `pay/confirm`
+  is recorded as `/pay/confirm`. Sanitization parses against an internal
+  base URL and re-serializes the path, which normalizes away the difference
+  between a document-relative and a root-relative reference.
 
 ##### For event consumers
 
diff --git a/packages/rrweb-snapshot/test/privacy.test.ts b/packages/rrweb-snapshot/test/privacy.test.ts
index 04c4c23db3..57e75e565a 100644
--- a/packages/rrweb-snapshot/test/privacy.test.ts
+++ b/packages/rrweb-snapshot/test/privacy.test.ts
@@ -1204,7 +1204,7 @@ describe('merge helpers validate the record()-level selector', () => {
 describe('sanitizeUrl v2', () => {
   const strict = compilePrivacyPolicy({ version: 1, preset: 'strict' });
   const balanced = compilePrivacyPolicy({ version: 1, preset: 'balanced' });
-  const manual = compilePrivacyPolicy(undefined);
+  const minimal = compilePrivacyPolicy(undefined);
   it('strips userinfo credentials', () => {
     expect(
       sanitizeUrl('https://alice:hunter2@api.example.com/x', balanced),
@@ -1228,21 +1228,21 @@ describe('sanitizeUrl v2', () => {
       'https://a.com/?page=2&q=*',
     );
   });
-  it('removes hash unless disabled; manual passes through untouched', () => {
+  it('removes hash unless disabled; minimal passes through untouched', () => {
     expect(sanitizeUrl('https://a.com/x#frag', balanced)).toBe(
       'https://a.com/x',
     );
-    expect(sanitizeUrl('https://alice:pw@a.com/?token=x#f', manual)).toBe(
+    expect(sanitizeUrl('https://alice:pw@a.com/?token=x#f', minimal)).toBe(
       'https://alice:pw@a.com/?token=x#f',
     );
   });
-  it('unparseable value under non-manual fails closed by dropping the attribute', () => {
+  it('unparseable value under non-minimal fails closed by dropping the attribute', () => {
     expect(sanitizeUrl('http://[broken', balanced)).toBeNull();
   });
   it('empty in, empty out -- never resolved into a path', () => {
     expect(sanitizeUrl('', balanced)).toBe('');
     expect(sanitizeUrl('', strict)).toBe('');
-    expect(sanitizeUrl('', manual)).toBe('');
+    expect(sanitizeUrl('', minimal)).toBe('');
   });
 });
 

From cd0539b5218ea14af92ea5fad74f03247806fe08 Mon Sep 17 00:00:00 2001
From: roggernaut <roggernaut@users.noreply.github.com>
Date: Mon, 31 Aug 2026 11:59:27 +0000
Subject: [PATCH 4/4] Apply formatting changes

---
 guide.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/guide.md b/guide.md
index ee5284f2f5..be21db6b6c 100644
--- a/guide.md
+++ b/guide.md
@@ -250,9 +250,9 @@ record({
 `preset` compiles to the following, on top of the `rules` above:
 
 | preset              | behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `minimal` (default) | Inert: only the existing masking options above apply. `rules` still work (below), but the `data-privacy` attribute and cross-vendor class recognition described below are off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `balanced`          | Masks every input value (like `maskAllInputs: true`); masks the `title`, `placeholder`, and `aria-label` attributes on every element; sanitizes URLs -- strips `username`/`password` (userinfo), removes the value of any query parameter in a default sensitive list (`access_token`, `auth`, `code`, `key`, `password`, `secret`, `session`, `token`) plus any configured `url.blockedQueryParameters`, and removes the hash unless `url.removeHash: false`. Query parameter names stay visible. Page text is untouched.                                                                                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `minimal` (default) | Inert: only the existing masking options above apply. `rules` still work (below), but the `data-privacy` attribute and cross-vendor class recognition described below are off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `balanced`          | Masks every input value (like `maskAllInputs: true`); masks the `title`, `placeholder`, and `aria-label` attributes on every element; sanitizes URLs -- strips `username`/`password` (userinfo), removes the value of any query parameter in a default sensitive list (`access_token`, `auth`, `code`, `key`, `password`, `secret`, `session`, `token`) plus any configured `url.blockedQueryParameters`, and removes the hash unless `url.removeHash: false`. Query parameter names stay visible. Page text is untouched.                                                                                                                          |
 | `strict`            | Everything `balanced` does, plus: all page text is masked; media element sources (`<img>`, `<video>`, `<audio>`, `<iframe>`, `<embed>`, `<object>`, `<source>`) are dropped instead of captured, except that an `<img>` source or `<video>` poster on an element with declared integer `width`/`height` attributes is replaced by a neutral same-size placeholder image so the surrounding layout does not collapse; canvas recording is disabled outright, even with a `canvasMasking` adapter configured; and URL sanitization blocks _every_ query parameter's value unless you also set `url.allowedQueryParameters` to an explicit allow-list. |
 
 > **URL sanitization is experimental.** No session-replay vendor sanitizes