@loxel.dev/pharos-browser 0.6.0

package/dist/index.js

@@ -0,0 +1,504 @@
+import {
+  ACTIVATION_EVENT_TAG,
+  EXCLUDE_CLASS,
+  LOCAL_TTL_MS,
+  MASK_CLASS,
+  MASK_TOKEN,
+  MAX_BUFFER_BYTES,
+  MAX_WINDOW_BYTES,
+  RECORDER_DEFAULTS,
+  beginsWithSnapshot,
+  clearPersisted,
+  createDropLedger,
+  createUploadSink,
+  decide,
+  drainPersisted,
+  encodeWindow,
+  envelopeMetaFor,
+  isSensitiveField,
+  maskText,
+  masksValue,
+  persistWindow,
+  postEnvelope,
+  quotaDroppedWindows,
+  resetQuotaDroppedWindows,
+  resolveConfig,
+  scrubAttribute,
+  scrubUrl,
+  shouldExclude,
+  shouldMaskByMarker
+} from "./index-bc4bw3ba.js";
+import {
+  __require
+} from "./index-c3taa3cg.js";
+
+// src/stack.ts
+var MAX_FRAMES = 50;
+var V8_WITH_FN = /^at\s+(.+?)\s+\((.+):(\d+):(\d+)\)$/;
+var V8_NO_FN = /^at\s+(.+):(\d+):(\d+)$/;
+var FIREFOX = /^([^@]*)@(.+):(\d+):(\d+)$/;
+function parseLine(line) {
+  let m = V8_WITH_FN.exec(line);
+  if (m) {
+    return { fn: m[1], file: m[2], line: Number(m[3]), col: Number(m[4]) };
+  }
+  m = V8_NO_FN.exec(line);
+  if (m) {
+    return { file: m[1], line: Number(m[2]), col: Number(m[3]) };
+  }
+  m = FIREFOX.exec(line);
+  if (m) {
+    const frame = { file: m[2], line: Number(m[3]), col: Number(m[4]) };
+    if (m[1])
+      frame.fn = m[1];
+    return frame;
+  }
+  return null;
+}
+function parseStack(stack) {
+  const frames = [];
+  for (const rawLine of stack.split(`
+`)) {
+    if (frames.length >= MAX_FRAMES)
+      break;
+    const line = rawLine.trim();
+    if (!line)
+      continue;
+    const frame = parseLine(line);
+    if (frame)
+      frames.push(frame);
+  }
+  return frames;
+}
+// src/privacy/collect.ts
+var STRUCTURAL_ATTRS = new Set(["class", "type", "contenteditable"]);
+function pathOf(el, root) {
+  const parts = [];
+  let node = el;
+  while (node && node !== root) {
+    const parent = node.parentElement;
+    if (!parent)
+      break;
+    const index = Array.prototype.indexOf.call(parent.children, node) + 1;
+    parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
+    node = parent;
+  }
+  return parts.join(" > ");
+}
+function collectRecordedStrings(root) {
+  const out = [];
+  const visit = (el) => {
+    const decision = decide(el);
+    if (decision === "exclude")
+      return;
+    const path = pathOf(el, root);
+    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))
+          continue;
+        if (name === "value" && valueIsMasked)
+          continue;
+        const scrubbed = scrubAttribute(el, attr.name, attr.value);
+        if (scrubbed === null || scrubbed === MASK_TOKEN)
+          continue;
+        if (scrubbed === "")
+          continue;
+        out.push({ value: scrubbed, path, origin: "attribute", attribute: attr.name });
+      }
+      if (decision === "record" && !valueIsMasked) {
+        for (const child of Array.from(el.childNodes)) {
+          if (child.nodeType !== 3)
+            continue;
+          const text = (child.textContent ?? "").trim();
+          if (text)
+            out.push({ value: text, path, origin: "text" });
+        }
+      }
+    }
+    for (const child of Array.from(el.children))
+      visit(child);
+  };
+  visit(root);
+  return out;
+}
+
+// src/index.ts
+var MAX_MESSAGE_LEN = 8192;
+var MAX_KIND_SITE_LEN = 256;
+var MAX_FRAME_FIELD_LEN = 512;
+var MAX_FLAG_KEYS = 64;
+var MAX_ATTR_KEYS = 64;
+var MAX_ATTR_KEY_LEN = 128;
+function isScalar(v) {
+  return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max) : s;
+}
+function sanitizeMessage(err) {
+  let raw;
+  if (err && typeof err === "object" && typeof err.message === "string") {
+    raw = err.message;
+  } else {
+    raw = String(err);
+  }
+  return truncate(raw.length > 0 ? raw : "(no message)", MAX_MESSAGE_LEN);
+}
+function sanitizeKind(err) {
+  if (err && typeof err === "object") {
+    const name = err.name;
+    if (typeof name === "string" && name.length > 0)
+      return truncate(name, MAX_KIND_SITE_LEN);
+  }
+  return;
+}
+function triggerSourceFor(kind, err) {
+  const name = sanitizeKind(err);
+  return name !== undefined ? { kind, name } : { kind };
+}
+function sanitizeStack(err) {
+  if (!err || typeof err !== "object")
+    return [];
+  const stack = err.stack;
+  if (typeof stack !== "string")
+    return [];
+  return parseStack(stack).map((f) => {
+    const out = {};
+    if (f.fn !== undefined)
+      out.fn = truncate(f.fn, MAX_FRAME_FIELD_LEN);
+    if (f.file !== undefined)
+      out.file = truncate(f.file, MAX_FRAME_FIELD_LEN);
+    if (typeof f.line === "number")
+      out.line = f.line;
+    if (typeof f.col === "number")
+      out.col = f.col;
+    return out;
+  });
+}
+function sanitizeFlags(flags) {
+  const out = {};
+  for (const k of Object.keys(flags).slice(0, MAX_FLAG_KEYS)) {
+    const v = flags[k];
+    if (isScalar(v))
+      out[k] = v;
+  }
+  return out;
+}
+function sanitizeAttrs(attrs) {
+  const out = {};
+  for (const k of Object.keys(attrs).slice(0, MAX_ATTR_KEYS)) {
+    if (k.length > MAX_ATTR_KEY_LEN)
+      continue;
+    const v = attrs[k];
+    if (isScalar(v)) {
+      out[k] = v;
+    } else if (Array.isArray(v)) {
+      const scalars = v.filter(isScalar);
+      if (scalars.length > 0)
+        out[k] = scalars;
+    }
+  }
+  return out;
+}
+var RECONNECT_BACKOFF_MS = 1000;
+function buildBootstrapBody(context) {
+  const { contextKey, application, release, sessionId, attributes } = context;
+  const pharos = { contextKey };
+  if (application !== undefined)
+    pharos.application = application;
+  if (release !== undefined)
+    pharos.release = release;
+  if (sessionId !== undefined)
+    pharos.sessionId = sessionId;
+  return { pharos, attributes: attributes ?? {} };
+}
+
+class PharosBrowserClient {
+  baseUrl;
+  clientKey;
+  context;
+  eventSourceFactory;
+  flags = {};
+  version = -Infinity;
+  streamToken = null;
+  eventSource = null;
+  listeners = {
+    change: new Set,
+    error: new Set
+  };
+  closed = false;
+  reconnectTimer = null;
+  errorsEnabled;
+  errorTarget;
+  replayHandle = null;
+  replayTriggerKind = "exception";
+  replayErrorListeners = null;
+  onReplayError = (event) => {
+    const e = event;
+    this.replayHandle?.trigger(triggerSourceFor("exception", e?.error ?? e?.message));
+  };
+  onReplayRejection = (event) => {
+    const e = event;
+    this.replayHandle?.trigger(triggerSourceFor("unhandledrejection", e?.reason));
+  };
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.clientKey = config.clientKey;
+    this.context = config.context;
+    this.eventSourceFactory = config.eventSourceFactory ?? ((url) => new EventSource(url));
+    this.errorsEnabled = config.errors ?? true;
+    this.errorTarget = config.errorTarget ?? globalThis;
+  }
+  static async init(config) {
+    const client = new PharosBrowserClient(config);
+    await client.bootstrap();
+    client.connectStream();
+    if (client.errorsEnabled)
+      client.registerErrorListeners();
+    return client;
+  }
+  async bootstrap() {
+    const body = buildBootstrapBody(this.context);
+    const res = await fetch(`${this.baseUrl}/api/v1/client/bootstrap`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.clientKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      throw new Error(`pharos bootstrap failed: HTTP ${res.status}`);
+    }
+    const data = await res.json();
+    this.flags = data.flags ?? {};
+    this.version = data.version ?? 0;
+    this.streamToken = data.streamToken;
+  }
+  connectStream() {
+    if (!this.streamToken)
+      return;
+    const url = `${this.baseUrl}/api/v1/client/stream?token=${encodeURIComponent(this.streamToken)}`;
+    const es = this.eventSourceFactory(url);
+    es.addEventListener("flags", (event) => {
+      try {
+        const payload = JSON.parse(event.data);
+        if (typeof payload.version === "number" && payload.version < this.version) {
+          return;
+        }
+        this.flags = payload.flags ?? {};
+        this.version = payload.version;
+        this.emit("change", payload);
+      } catch (err) {
+        this.emit("error", err);
+      }
+    });
+    es.onerror = () => {
+      this.emit("error", { type: "stream-error" });
+      this.maybeReconnect(es);
+    };
+    this.eventSource = es;
+  }
+  maybeReconnect(es) {
+    if (this.closed || this.reconnectTimer)
+      return;
+    if (es.readyState !== 2)
+      return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.closed)
+        return;
+      this.identify(this.context).catch((err) => this.emit("error", err));
+    }, RECONNECT_BACKOFF_MS);
+  }
+  onWindowError = (event) => {
+    const e = event;
+    this.captureException(e?.error ?? e?.message);
+  };
+  onUnhandledRejection = (event) => {
+    const e = event;
+    this.replayTriggerKind = "unhandledrejection";
+    try {
+      this.captureException(e?.reason);
+    } finally {
+      this.replayTriggerKind = "exception";
+    }
+  };
+  registerErrorListeners() {
+    this.errorTarget.addEventListener("error", this.onWindowError);
+    this.errorTarget.addEventListener("unhandledrejection", this.onUnhandledRejection);
+  }
+  unregisterErrorListeners() {
+    this.errorTarget.removeEventListener("error", this.onWindowError);
+    this.errorTarget.removeEventListener("unhandledrejection", this.onUnhandledRejection);
+  }
+  captureException(err, opts) {
+    if (this.closed)
+      return;
+    const entry = { message: sanitizeMessage(err) };
+    const kind = sanitizeKind(err);
+    if (kind !== undefined)
+      entry.kind = kind;
+    this.replayHandle?.trigger(triggerSourceFor(this.replayTriggerKind, err));
+    if (opts?.site)
+      entry.site = truncate(opts.site, MAX_KIND_SITE_LEN);
+    const stack = sanitizeStack(err);
+    if (stack.length > 0)
+      entry.stack = stack;
+    const flags = sanitizeFlags(this.flags);
+    if (Object.keys(flags).length > 0)
+      entry.flags = flags;
+    if (opts?.attributes) {
+      const attrs = sanitizeAttrs(opts.attributes);
+      if (Object.keys(attrs).length > 0)
+        entry.attrs = attrs;
+    }
+    const pharos = { contextKey: this.context.contextKey };
+    if (this.context.application !== undefined)
+      pharos.application = this.context.application;
+    if (this.context.release !== undefined)
+      pharos.release = this.context.release;
+    if (this.context.sessionId !== undefined)
+      pharos.sessionId = this.context.sessionId;
+    fetch(`${this.baseUrl}/api/v1/errors`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.clientKey}`
+      },
+      body: JSON.stringify({ pharos, errors: [entry] })
+    }).catch((err2) => this.emit("error", err2));
+  }
+  attachReplay(handle) {
+    if (this.closed)
+      return;
+    if (this.replayHandle !== null && this.replayHandle !== handle) {
+      throw new Error("pharos: a session recorder is already attached — call detachReplay() " + "before attaching another. rrweb records into one process-wide " + "session, so a second startRecording() silently takes over the first.");
+    }
+    this.warnIfSessionIdsDisagree(handle);
+    this.replayHandle = handle;
+    if (this.errorsEnabled || this.replayErrorListeners)
+      return;
+    this.errorTarget.addEventListener("error", this.onReplayError);
+    this.errorTarget.addEventListener("unhandledrejection", this.onReplayRejection);
+    this.replayErrorListeners = () => {
+      this.errorTarget.removeEventListener("error", this.onReplayError);
+      this.errorTarget.removeEventListener("unhandledrejection", this.onReplayRejection);
+    };
+  }
+  warnIfSessionIdsDisagree(handle) {
+    const ctxId = this.context.sessionId;
+    if (ctxId === undefined)
+      return;
+    const replayId = handle.sessionId;
+    if (typeof replayId !== "string" || replayId === ctxId)
+      return;
+    console.warn("pharos: this recorder uploads under sessionId " + `"${replayId}" while errors are reported under "${ctxId}". ` + "Replay windows cannot be joined to errors. Pass " + "`sessionId: <PharosContext.sessionId>` to startReplayUpload(), or " + "use client.startReplay() which does it for you.");
+  }
+  async startReplay(options = {}) {
+    if (this.closed)
+      return null;
+    const { startReplayUpload } = await import("./wire-992wvzs1.js");
+    if (this.closed)
+      return null;
+    const handle = startReplayUpload({
+      ...options,
+      endpoint: `${this.baseUrl}/api/v1/client/replay`,
+      appKey: this.clientKey,
+      ...this.context.sessionId !== undefined ? { sessionId: this.context.sessionId } : {}
+    });
+    try {
+      this.attachReplay(handle);
+    } catch (e) {
+      handle.stop();
+      throw e;
+    }
+    return handle;
+  }
+  detachReplay() {
+    this.replayHandle = null;
+    this.replayErrorListeners?.();
+    this.replayErrorListeners = null;
+  }
+  flag(key, defaultValue) {
+    if (Object.prototype.hasOwnProperty.call(this.flags, key)) {
+      return this.flags[key];
+    }
+    return defaultValue;
+  }
+  on(event, cb) {
+    this.listeners[event].add(cb);
+    return () => {
+      this.listeners[event].delete(cb);
+    };
+  }
+  emit(event, payload) {
+    for (const cb of this.listeners[event]) {
+      cb(payload);
+    }
+  }
+  async identify(context) {
+    if (this.closed)
+      return;
+    this.context = context;
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    await this.bootstrap();
+    if (!this.closed) {
+      this.connectStream();
+    }
+  }
+  close() {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    if (this.errorsEnabled) {
+      this.unregisterErrorListeners();
+    }
+    this.replayHandle = null;
+    this.replayErrorListeners?.();
+    this.replayErrorListeners = null;
+  }
+}
+export {
+  ACTIVATION_EVENT_TAG,
+  EXCLUDE_CLASS,
+  LOCAL_TTL_MS,
+  MASK_CLASS,
+  MASK_TOKEN,
+  MAX_BUFFER_BYTES,
+  MAX_WINDOW_BYTES,
+  PharosBrowserClient,
+  RECORDER_DEFAULTS,
+  beginsWithSnapshot,
+  clearPersisted,
+  collectRecordedStrings,
+  createDropLedger,
+  createUploadSink,
+  decide,
+  drainPersisted,
+  encodeWindow,
+  envelopeMetaFor,
+  isSensitiveField,
+  maskText,
+  masksValue,
+  persistWindow,
+  postEnvelope,
+  quotaDroppedWindows,
+  resetQuotaDroppedWindows,
+  resolveConfig,
+  scrubAttribute,
+  scrubUrl,
+  shouldExclude,
+  shouldMaskByMarker
+};

package/dist/privacy/attributes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Keep scheme, host and path; drop `?query` and `#fragment`, which is where
+ * typed search text and record ids overwhelmingly live — the shape of the
+ * #792 leak. Non-http(s) schemes are masked entirely: a `mailto:` path IS an
+ * email address and a `data:` URL can embed the content itself. URL userinfo
+ * (`user:pw@host`) is dropped as a side effect of reconstructing the output
+ * from `protocol`/`host`/`pathname` rather than copying `url.href` verbatim —
+ * do not "simplify" this back to `url.href`, or credentials come back.
+ */
+export declare function scrubUrl(value: string): string;
+/** Returns the value to record, or `null` to omit the attribute entirely. */
+export declare function scrubAttribute(el: Element, name: string, value: string): string | null;

package/dist/privacy/collect.d.ts

@@ -0,0 +1,8 @@
+export interface RecordedString {
+    value: string;
+    path: string;
+    origin: 'text' | 'value' | 'attribute';
+    attribute?: string;
+}
+export declare const STRUCTURAL_ATTRS: Set<string>;
+export declare function collectRecordedStrings(root: Element): RecordedString[];

package/dist/privacy/markers.d.ts

@@ -0,0 +1,7 @@
+export declare const EXCLUDE_CLASS = "pharos-exclude";
+export declare const MASK_CLASS = "pharos-mask";
+export declare function hasMarkerAncestor(el: Element, cls: string): boolean;
+/** The subtree is recorded as an empty same-tag element: contents never leave. */
+export declare function shouldExclude(el: Element): boolean;
+/** Structure and attributes are recorded; text and values are masked. */
+export declare function shouldMaskByMarker(el: Element): boolean;

package/dist/privacy/mask.d.ts

@@ -0,0 +1,2 @@
+export declare const MASK_TOKEN = "\u2022\u2022\u2022\u2022";
+export declare function maskText(_text: string): string;

package/dist/privacy/policy.d.ts

@@ -0,0 +1,27 @@
+export type Decision = 'exclude' | 'mask' | 'record';
+export declare function decide(el: Element): Decision;
+/**
+ * Whether this element's VALUE must be masked — always true for anything the
+ * user types into, regardless of markers or detection (spec §3.3).
+ *
+ * CONTENTEDITABLE IS INHERITED, AND THAT IS THE WHOLE POINT OF THE ANCESTOR
+ * CHECK. A browser stores multi-line contenteditable content in CHILD
+ * elements — a `<div>`/`<p>` per line on Enter, a `<span>` per styled run —
+ * and those children carry no `contenteditable` attribute of their own.
+ * Reading only `el.getAttribute('contenteditable')` (as this did until
+ * 2026-09-02) therefore answered `false` for essentially every real
+ * contenteditable region, and the typed text in those children was recorded
+ * verbatim: the #792 leak shape, through the one input surface that has
+ * element children. Do NOT "simplify" this back to a self-only attribute
+ * read.
+ *
+ * CALLING CONTRACT: this does NOT consult `pharos-exclude`/`pharos-mask` or
+ * run field-sensitivity detection, by design — that is `decide()`'s job.
+ * Call this only AFTER `decide(el)` has returned `'record'` or `'mask'`, never
+ * on an element `decide()` said to exclude: an excluded element's subtree is
+ * replaced wholesale (see `markers.ts`), so asking this function about it is
+ * a category error, not a stricter check. A recorder that calls this
+ * standalone, without routing the element through `decide()` first, will
+ * record values `decide()` would have excluded outright.
+ */
+export declare function masksValue(el: Element): boolean;

package/dist/privacy/sensitivity.d.ts

@@ -0,0 +1 @@
+export declare function isSensitiveField(el: Element): boolean;

package/dist/replay/budget.d.ts

@@ -0,0 +1,49 @@
+import type { DegradationRecord, ResolvedRecorderConfig } from './config';
+/** The browser's own long-task threshold. A `PerformanceObserver` longtask entry is ≥ this by definition. */
+export declare const LONG_TASK_MS = 50;
+/** Minimum gap between escalations, so one janky second does not collapse straight to the floor. */
+export declare const ESCALATION_COOLDOWN_MS = 5000;
+/** Quiet period before stepping back up one level. */
+export declare const RECOVERY_AFTER_MS = 30000;
+export declare const MAX_DEGRADATION_LEVEL = 3;
+/** Rate limit on memory-ceiling records: a heavy page evicts constantly and must not emit thousands. */
+export declare const CEILING_RECORD_COOLDOWN_MS = 10000;
+export interface Budget {
+    level(): number;
+    checkpointIntervalMs(): number;
+    mousemoveWaitMs(): number;
+    /** Returns true when the level actually changed, so the caller can re-apply rates. */
+    noteLongTask(durationMs: number): boolean;
+    /**
+     * One segment dropped for the byte ceiling. Call this once per eviction —
+     * i.e. wire it straight to `ReplayBuffer`'s `onCeilingEviction`, which fires
+     * once per dropped segment and in lockstep with `evictedForBytes`. Bursts
+     * are collapsed HERE, with the count preserved; see the emission comment
+     * below for why the caller must not pre-aggregate.
+     */
+    noteCeilingEviction(): void;
+    /** Returns true when the level actually changed. */
+    maybeRecover(): boolean;
+    /** A snapshot. Callers may retain it; later coalescing never rewrites it. */
+    records(): DegradationRecord[];
+}
+export declare function createBudget(opts: {
+    config: ResolvedRecorderConfig;
+    now: () => number;
+}): Budget;
+/**
+ * Wires `PerformanceObserver` long-task entries into a budget. Returns a
+ * detach function.
+ *
+ * Long-task observation is optional: Safari ships the constructor but not the
+ * `longtask` entry type, and an engine asked for an entry type it does not
+ * support either throws or quietly observes nothing. BOTH ARE HANDLED — the
+ * throw by the `catch` below, the silence by simply never degrading — which is
+ * why this swallows the failure rather than reporting it.
+ *
+ * happy-dom DOES define `PerformanceObserver` and accepts the `observe` call,
+ * but never emits a `longtask` entry — so tests reach this function's success
+ * path and the escalation path below is unreachable without a stub. Do not
+ * assume the test environment lacks the constructor; it does not.
+ */
+export declare function observeLongTasks(budget: Budget, onEscalate: () => void): () => void;