@loxel.dev/pharos-browser 0.6.0 → 0.7.0

package/README.md

@@ -318,6 +318,90 @@ you can verify what a recorder would send before turning one on.
 
 ## Version history
 
+- `0.7.0` — **a marker on a shadow host now protects its shadow root** (#821),
+  and the verification helper sees what the recorder sees (#822).
+
+  `hasMarkerAncestor` walked `parentElement`, which is `null` at a shadow
+  boundary, so `pharos-mask`/`pharos-exclude` on a web component's host
+  protected nothing inside it — while rrweb recorded that content regardless.
+  Established empirically before the fix: rrweb captures shadow-root text
+  unconditionally (no recorder option gates it), and `maskTextHook` *is*
+  invoked for those nodes, so the decision function was the sole failure
+  point. The walk now re-roots through `getRootNode()`/`.host`, bounded
+  against a malformed tree.
+
+  `collectRecordedStrings` did not traverse shadow DOM either. That was not a
+  compensating margin — **the auditor's blind spot lined up exactly with the
+  recorder's leak surface**, so an app could run the helper, get a clean
+  report, and be shipping shadow-root content. It now traverses, and
+  `pathOf()` renders a boundary crossing as `>>>` rather than truncating the
+  path to `''` (which was indistinguishable from a root-level row).
+
+  **Why MINOR, not PATCH:** two consumer-visible outputs change. Content
+  inside a marked shadow host is now masked where it previously shipped in
+  the clear, and `collectRecordedStrings` reports strings it previously
+  omitted — so a pinned audit snapshot will differ. Both changes are in the
+  safe direction, but a consumer sees different output either way.
+
+  `STRUCTURAL_ATTRS` is unchanged in membership and is now derived from a
+  justification map: each entry declares a `kind` — `closed-enumeration`
+  (which must name its finite vocabulary) or `cost-tradeoff` (which must
+  carry `meetsImpossibilityBar: false`). `class` is recorded honestly as the
+  second kind. The gate cannot verify a claim's truth; that stays human
+  review.
+
+  **The first round of that fix only reached the FULL SNAPSHOT.** rrweb
+  decides whether to consult `maskTextFn` in `needMaskingText`, which returns
+  "nothing to mask" for any node that is not an element and has no parent
+  *element* — and a text node whose parent is a `ShadowRoot` is exactly that.
+  So on the **incremental** streams (`characterData`, `childList` adds) the
+  decision function was never called at all and a **marked** host still
+  shipped `shadowRoot.textContent = user.name` in the clear once recording had
+  started. An element-wrapped `<p>` inside the same shadow root did not
+  reproduce it (rrweb takes its element branch there), which is how it
+  shipped. The recorder now post-processes both streams through the same
+  policy, and applies it over rrweb's answer in the snapshot too — in the
+  masking direction only, never unmasking.
+
+  **`pharos-exclude` across a shadow boundary shipped attributes.** rrweb's
+  `isBlocked` uses `closest()`, which does not cross a boundary, so an add
+  into an excluded host's shadow root was not dropped — and the scrub pass
+  judges a serialized node through a detached surrogate that by construction
+  has no host and no ancestry. Measured: `<p title="SECRET">TEXT</p>` appended
+  into an excluded host's shadow root shipped its `title` verbatim while its
+  text was masked. Such adds are now dropped, judged against the **live**
+  parent the mutation names by id.
+
+  **Snapshot noise to expect on your first re-run:** shadow roots almost
+  always contain a `<style>`, and `collectRecordedStrings` now reaches it and
+  reports its CSS text as an ordinary text row. That is not a leak — author
+  CSS is not user content — but a pinned audit snapshot will grow by more than
+  the app's own strings.
+
+  **Still not covered:**
+  - **Closed shadow roots**, which rrweb cannot reach either (`n.shadowRoot`
+    is `null`), so neither the recorder nor the helper sees them.
+  - **The full snapshot's own answer for a bare shadow text node is rrweb's,
+    not the policy's**, and it flips on the host's shape:
+    `needMaskingText` returns `false` for an element with no child nodes, so
+    whether a shadow subtree inherits masking depends on whether the host
+    happens to have light-DOM children. The policy is now applied over the
+    top, but only ever to mask MORE — so an **unmarked** host's bare shadow
+    text can be masked in the snapshot while `collectRecordedStrings` reports
+    it. The report is the truthful one: the recorder ships that string
+    verbatim on the incremental stream.
+  - **An excluded host's shadow subtree can still leave structural traces.**
+    Content is dropped, but rrweb's mirror holds nodes this SDK removed from
+    the `adds` stream, so a later `removes` entry can carry their ids. Ids and
+    tree shape, never text or attributes.
+  - Light-DOM content projected through a native `<slot>` is **no longer**
+    on this list: it was measured and is covered. A slotted node is an
+    ordinary light-DOM child of the host — rrweb serializes it under the host
+    and the helper reaches it via `el.children` — so the two agree with no
+    slot-specific handling, and a marker on the host governs it through
+    ordinary light-DOM ancestry. There is a test for it so it does not have to
+    be re-derived.
+
 - `0.6.0` — **first npm release, as `@loxel.dev/pharos-browser`.** Ships built
   output with an `exports` map, so it resolves as an ordinary package.
 

package/dist/{index-bc4bw3ba.js → index-yabengpp.js}

@@ -7,12 +7,23 @@ function maskText(_text) {
 // src/privacy/markers.ts
 var EXCLUDE_CLASS = "pharos-exclude";
 var MASK_CLASS = "pharos-mask";
+var MAX_HOPS = 1000;
 function hasMarkerAncestor(el, cls) {
   let node = el;
+  let hops = 0;
   while (node) {
     if (node.classList?.contains(cls))
       return true;
-    node = node.parentElement;
+    const parentEl = node.parentElement;
+    if (parentEl) {
+      node = parentEl;
+    } else {
+      const root = node.getRootNode();
+      node = typeof ShadowRoot !== "undefined" && root instanceof ShadowRoot ? root.host : null;
+    }
+    hops += 1;
+    if (hops > MAX_HOPS)
+      return true;
   }
   return false;
 }

package/dist/index.js

@@ -27,7 +27,7 @@ import {
   scrubUrl,
   shouldExclude,
   shouldMaskByMarker
-} from "./index-bc4bw3ba.js";
+} from "./index-yabengpp.js";
 import {
   __require
 } from "./index-c3taa3cg.js";
@@ -71,17 +71,74 @@ function parseStack(stack) {
   return frames;
 }
 // src/privacy/collect.ts
-var STRUCTURAL_ATTRS = new Set(["class", "type", "contenteditable"]);
+var STRUCTURAL_ATTR_JUSTIFICATIONS = {
+  type: {
+    kind: "closed-enumeration",
+    claim: "The `type` attribute's value space is a fixed, closed enumeration defined by the HTML Living Standard, scoped per element. No element accepts an application-supplied free-text value there — an out-of-vocabulary `type` is simply not a recognized state.",
+    vocabulary: [
+      "text",
+      "button",
+      "checkbox",
+      "color",
+      "date",
+      "datetime-local",
+      "email",
+      "file",
+      "hidden",
+      "image",
+      "month",
+      "number",
+      "password",
+      "radio",
+      "range",
+      "reset",
+      "search",
+      "submit",
+      "tel",
+      "time",
+      "url",
+      "week",
+      "1",
+      "a",
+      "A",
+      "i",
+      "I"
+    ]
+  },
+  contenteditable: {
+    kind: "closed-enumeration",
+    claim: "The `contenteditable` attribute's value space is a closed enumeration defined by the HTML Living Standard. Any other string is not a recognized keyword state, so this attribute cannot carry free text.",
+    vocabulary: ["true", "false", "plaintext-only", "inherit", ""]
+  },
+  class: {
+    kind: "cost-tradeoff",
+    claim: "class has no closed vocabulary and CAN carry templated content in principle, so it does not clear the content-impossibility bar the enumeration entries clear. It is kept anyway as a stated cost/benefit call: every element has a class attribute, and treating it as content would drown every snapshot in noise.",
+    meetsImpossibilityBar: false
+  }
+};
+var STRUCTURAL_ATTRS = new Set(Object.keys(STRUCTURAL_ATTR_JUSTIFICATIONS));
+var MAX_PATH_HOPS = 1000;
 function pathOf(el, root) {
   const parts = [];
   let node = el;
+  let hops = 0;
   while (node && node !== root) {
     const parent = node.parentElement;
-    if (!parent)
+    if (parent) {
+      const index = Array.prototype.indexOf.call(parent.children, node) + 1;
+      parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
+      node = parent;
+    } else {
+      const shadowRoot = node.getRootNode();
+      if (!(typeof ShadowRoot !== "undefined" && shadowRoot instanceof ShadowRoot))
+        break;
+      const index = Array.prototype.indexOf.call(shadowRoot.children, node) + 1;
+      parts.unshift(">>>", `${node.tagName.toLowerCase()}:nth-child(${index})`);
+      node = shadowRoot.host;
+    }
+    hops += 1;
+    if (hops > MAX_PATH_HOPS)
       break;
-    const index = Array.prototype.indexOf.call(parent.children, node) + 1;
-    parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
-    node = parent;
   }
   return parts.join(" > ");
 }
@@ -92,8 +149,8 @@ function collectRecordedStrings(root) {
     if (decision === "exclude")
       return;
     const path = pathOf(el, root);
+    const valueIsMasked = masksValue(el);
     if (decision === "record" || decision === "mask") {
-      const valueIsMasked = masksValue(el);
       for (const attr of Array.from(el.attributes)) {
         const name = attr.name.toLowerCase();
         if (STRUCTURAL_ATTRS.has(name))
@@ -119,6 +176,22 @@ function collectRecordedStrings(root) {
     }
     for (const child of Array.from(el.children))
       visit(child);
+    if (el.shadowRoot) {
+      const shadowPath = path ? `${path} > >>>` : ">>>";
+      for (const child of Array.from(el.shadowRoot.childNodes)) {
+        if (child.nodeType === 1) {
+          visit(child);
+          continue;
+        }
+        if (child.nodeType !== 3)
+          continue;
+        if (decision !== "record" || valueIsMasked)
+          continue;
+        const text = (child.textContent ?? "").trim();
+        if (text)
+          out.push({ value: text, path: shadowPath, origin: "text" });
+      }
+    }
   };
   visit(root);
   return out;
@@ -400,7 +473,7 @@ class PharosBrowserClient {
   async startReplay(options = {}) {
     if (this.closed)
       return null;
-    const { startReplayUpload } = await import("./wire-992wvzs1.js");
+    const { startReplayUpload } = await import("./wire-p2kvy6dd.js");
     if (this.closed)
       return null;
     const handle = startReplayUpload({

package/dist/privacy/collect.d.ts

@@ -4,5 +4,16 @@ export interface RecordedString {
     origin: 'text' | 'value' | 'attribute';
     attribute?: string;
 }
+type StructuralAttrJustification = {
+    readonly kind: 'closed-enumeration';
+    readonly claim: string;
+    readonly vocabulary: readonly string[];
+} | {
+    readonly kind: 'cost-tradeoff';
+    readonly claim: string;
+    readonly meetsImpossibilityBar: false;
+};
+export declare const STRUCTURAL_ATTR_JUSTIFICATIONS: Readonly<Record<string, StructuralAttrJustification>>;
 export declare const STRUCTURAL_ATTRS: Set<string>;
 export declare function collectRecordedStrings(root: Element): RecordedString[];
+export {};

package/dist/replay/privacy-hooks.d.ts

@@ -43,6 +43,8 @@ export interface SerializedNode {
     tagName?: string;
     attributes?: Record<string, unknown>;
     childNodes?: SerializedNode[];
+    /** rrweb-snapshot's text payload — present on `type === SERIALIZED_TEXT`. */
+    textContent?: string;
     id?: number;
     [key: string]: unknown;
 }

package/dist/{wire-992wvzs1.js → wire-p2kvy6dd.js}

@@ -26,7 +26,7 @@ import {
   resolveConfig,
   scrubAttribute,
   scrubUrl
-} from "./index-bc4bw3ba.js";
+} from "./index-yabengpp.js";
 import"./index-c3taa3cg.js";
 
 // src/replay/recorder.ts
@@ -146,8 +146,34 @@ function isStyleDiff(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var SERIALIZED_ELEMENT = 2;
+var SERIALIZED_TEXT = 3;
 var SOURCE_MUTATION = 0;
 var SOURCE_INPUT = 5;
+function shadowHostOf(node) {
+  if (node && typeof ShadowRoot !== "undefined" && node instanceof ShadowRoot)
+    return node.host;
+  return null;
+}
+function governingElementOfTextNode(node) {
+  if (!node)
+    return null;
+  return node.parentElement ?? shadowHostOf(node.parentNode);
+}
+function governingElementOfParent(parent) {
+  if (!parent)
+    return null;
+  if (parent.nodeType === 1)
+    return parent;
+  return shadowHostOf(parent);
+}
+function addLandsInExcludedSubtree(parent) {
+  if (!parent)
+    return true;
+  const el = governingElementOfParent(parent);
+  if (el)
+    return decide(el) === "exclude";
+  return false;
+}
 function shouldMaskTextOf(el) {
   if (!el)
     return true;
@@ -271,14 +297,33 @@ function scrubSerializedNode(node, doc) {
       scrubSerializedNode(child, doc);
   }
 }
+function maskUnjudgedShadowText(node, ctx) {
+  const children = node.childNodes;
+  if (!children)
+    return;
+  let host;
+  for (const child of children) {
+    if (child.type === SERIALIZED_TEXT && child.isShadow === true && typeof child.textContent === "string") {
+      if (host === undefined) {
+        const live = typeof node.id === "number" ? ctx.resolveNode(node.id) : null;
+        host = live && live.nodeType === 1 ? live : null;
+      }
+      if (shouldMaskTextOf(host))
+        child.textContent = maskText(child.textContent);
+    }
+    maskUnjudgedShadowText(child, ctx);
+  }
+}
 function scrubEventAttributes(event, ctx) {
   const e = event;
   const data = e.data;
   if (!data)
     return event;
   const node = data.node;
-  if (node && typeof node === "object")
+  if (node && typeof node === "object") {
     scrubSerializedNode(node, ctx.doc);
+    maskUnjudgedShadowText(node, ctx);
+  }
   if (data.source === SOURCE_INPUT && typeof data.text === "string") {
     const live = ctx.resolveNode(data.id);
     const el = live && live.nodeType === 1 ? live : null;
@@ -286,11 +331,34 @@ function scrubEventAttributes(event, ctx) {
   }
   if (data.source !== SOURCE_MUTATION)
     return event;
+  const texts = data.texts;
+  if (Array.isArray(texts)) {
+    for (const entry of texts) {
+      if (typeof entry?.value !== "string")
+        continue;
+      if (shouldMaskTextOf(governingElementOfTextNode(ctx.resolveNode(entry.id)))) {
+        entry.value = maskText(entry.value);
+      }
+    }
+  }
   const adds = data.adds;
   if (Array.isArray(adds)) {
-    for (const add of adds) {
-      if (add?.node)
-        scrubSerializedNode(add.node, ctx.doc);
+    for (let i = adds.length - 1;i >= 0; i--) {
+      const add = adds[i];
+      if (!add?.node)
+        continue;
+      const parent = typeof add.parentId === "number" ? ctx.resolveNode(add.parentId) : null;
+      if (addLandsInExcludedSubtree(parent)) {
+        adds.splice(i, 1);
+        continue;
+      }
+      if (add.node.type === SERIALIZED_TEXT && typeof add.node.textContent === "string") {
+        if (shouldMaskTextOf(governingElementOfParent(parent))) {
+          add.node.textContent = maskText(add.node.textContent);
+        }
+      }
+      scrubSerializedNode(add.node, ctx.doc);
+      maskUnjudgedShadowText(add.node, ctx);
     }
   }
   const attributes = data.attributes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxel.dev/pharos-browser",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Browser client for Pharos — server-evaluated feature flags, error capture, and session replay.",
   "license": "MIT",
   "type": "module",