cyborg-hunter 0.7.4 → 0.8.0

package/src/replay/redaction.js

@@ -0,0 +1,165 @@
+// src/replay/redaction.js
+// Redaction predicates, shared by every capture path.
+//
+// Spec §8 makes redaction a property of the FILE, not of one capture channel:
+// a redacted subtree's content must not appear in `initial_dom`, in
+// `initial_state.form`, in `dom.text`/`dom.attr`, in key identities, in
+// clipboard payloads, or in anchor identity. A single predicate is what makes
+// that claim checkable — v1 had two implementations (capture-trace's
+// `inRedactedSubtree`, capture-dom's `isInRedactedSubtree`) with different
+// signatures and quietly different password detection, so "is this node
+// redacted" could be answered two ways in one recording.
+//
+// The unified definition takes the SELECTOR (the actual configuration datum),
+// not an options bag, so both capture modules call it the same way:
+//   capture-trace: isInRedactedSubtree(el, config.redactSelector)
+//   snapshot/dom:  isInRedactedSubtree(node, opts.redactSelector)
+//
+// Adoption: complete. Every capture path — the snapshot walk, the mutation
+// mapper, the keyframe seed and event capture — asks this module, and the v1
+// duplicates it replaced are gone. The password check is the union of what the
+// two of them used to do separately (property OR attribute), which is why the
+// predicate is broader than either was.
+
+var ELEMENT_NODE = 1;
+
+// Nodes whose content this recording has ever withheld. Redaction is a
+// property of the FILE (spec §8), and the DOM only knows the present: a node
+// that spent the trial inside a redacted container and is then moved OUT of
+// it would serialize its accumulated content into the very next `dom.add`,
+// putting in the file exactly the text the keyframe refused. Membership is
+// therefore permanent for the life of the page, not scoped to a keyframe
+// span: a whole-file leak scan reads every segment.
+//
+// A module-level WeakSet, so the protection is on by default and no wiring
+// step can forget it. It holds no node alive, and it is keyed by node
+// IDENTITY, so two recorders on one page (or two tests in one process) can
+// only ever over-redact each other's nodes, never under-redact. Callers that
+// want their own scope may pass one in.
+var defaultTaint = new WeakSet();
+
+// How many nodes the SHARED set has ever withheld. A WeakSet has no `size`, so
+// a counter is the only way to answer the one question a later recording needs
+// to ask: did this page withhold anything before I started? Its answer travels
+// as `extensions["cyborg-hunter"].inherited_redaction_taint`, because an empty
+// field in a second recording otherwise means two things the file cannot
+// distinguish — the participant typed nothing, or an earlier recording on this
+// page withheld it.
+//
+// Monotonic on purpose. GC can drop entries from the WeakSet, but a node that
+// became unreachable can never be encountered again, so "has ever withheld" is
+// the question with a stable answer.
+var defaultTaintMarks = 0;
+
+function taintSet(taint) {
+  return taint && typeof taint.has === 'function' ? taint : defaultTaint;
+}
+
+/**
+ * Record that this node's content was withheld, so every later channel keeps
+ * withholding it. Called wherever the withholding happens: the snapshot walk
+ * stripping a subtree, a suppressed `dom.text`, a withheld `value` patch.
+ */
+export function markRedacted(node, taint) {
+  if (node) {
+    var set = taintSet(taint);
+    if (set === defaultTaint) defaultTaintMarks++;
+    set.add(node);
+  }
+  return node;
+}
+
+/**
+ * True when the page's shared taint set has withheld something already. Read
+ * once, at `startSession`, so a recording can state whether it inherited
+ * withholding from an earlier one on the same page (see the counter above).
+ */
+export function hasInheritedRedactionTaint() {
+  return defaultTaintMarks > 0;
+}
+
+/** True when this node's content has ever been withheld (see markRedacted). */
+export function isRedactionTainted(node, taint) {
+  return !!node && taintSet(taint).has(node);
+}
+
+/**
+ * True when this node OR ANY ANCESTOR has ever been withheld.
+ *
+ * The subtree reading is the one every channel has to use, and it exists
+ * because the node-only reading disagreed with itself across channels (T3
+ * final review, F-1). The snapshot walk always inherited a tainted ancestor's
+ * verdict downward — it descends the tree, so it carries the answer with it —
+ * while the mutation mapper and the trace capture asked about the queried node
+ * alone. New content created inside a container that had been moved OUT of a
+ * redacted subtree therefore shipped in full through `dom.add`, `dom.text` and
+ * `input.value`, and was then withheld by the next keyframe describing the same
+ * nodes: one file, two verdicts, the weaker one first.
+ *
+ * A fresh child of a withheld container is withheld. That is the only reading
+ * under which the taint set's stated property — it can only ever over-redact —
+ * is true of the FILE rather than of one channel at a time.
+ */
+export function isInTaintedSubtree(node, taint) {
+  var set = taintSet(taint);
+  var cur = node;
+  while (cur) {
+    if (set.has(cur)) return true;
+    cur = cur.parentNode;
+  }
+  return false;
+}
+
+function hasTypePasswordAttr(el) {
+  var attrs = el.attributes || [];
+  for (var i = 0; i < attrs.length; i++) {
+    if (attrs[i].name === 'type') return attrs[i].value === 'password';
+  }
+  return false;
+}
+
+/**
+ * The spec §8 floor: `<input type="password">` values are never recorded, in
+ * any channel, and no configuration can turn that off.
+ *
+ * Property OR attribute: the `type` IDL property is the browser's answer, but
+ * it is absent on duck-typed fixture nodes and reads "text" for an unknown
+ * type — so a field the page author wrote as `type="password"` must be caught
+ * by the attribute too. Detection stays declarative (spec §8): a name or
+ * placeholder that merely looks password-ish is not a password field.
+ */
+export function isPasswordField(el) {
+  if (!el || el.tagName !== 'INPUT') return false;
+  return el.type === 'password' || hasTypePasswordAttr(el);
+}
+
+/**
+ * True when this element is itself redacted: a password field (always) or a
+ * match for the researcher-configured redaction selector.
+ *
+ * A selector that throws (invalid syntax) redacts nothing rather than
+ * everything — the alternative is a typo silently emptying a whole recording.
+ */
+export function isRedacted(el, selector) {
+  if (isPasswordField(el)) return true;
+  if (!selector || !el || typeof el.matches !== 'function') return false;
+  try { return el.matches(selector); } catch (e) { return false; }
+}
+
+/**
+ * True when the node is a redacted element or lives inside one.
+ *
+ * The ancestor walk is what makes redaction a subtree property: text nodes and
+ * comments have no `matches()` of their own, so typed content under a redacted
+ * container (a contenteditable, a wrapper div matched by the selector) is only
+ * caught by asking about its ancestors. Elements above the observed root count
+ * too — the walk follows `parentNode` as far as it goes.
+ */
+export function isInRedactedSubtree(node, selector) {
+  var cur = node;
+  while (cur) {
+    if (cur.nodeType === ELEMENT_NODE && isRedacted(cur, selector)) return true;
+    cur = cur.parentNode;
+  }
+  return false;
+}

package/src/replay/serializer.js

@@ -1,22 +1,53 @@
 // src/replay/serializer.js
-// In-memory recorder state → SessionRecording v1 (jsPsych PR #3661 wire
-// format) with a ch_extensions namespace for CH-only data.
+// In-memory recorder state → SessionRecording v2 (spec §2/§3).
 //
-// This is one of exactly two places in the system that convert time bases
-// (the other is the CLI ingest): in-memory events carry absolute
-// performance.now() values; the wire carries ms-since-session-start.
+// This is one of exactly two places in the system that convert time bases (the
+// other is the CLI ingest): in-memory events carry absolute performance.now()
+// values; the wire carries ms since the recording started (spec §7), which is
+// why the file also states that origin as `recording_started_at_perf` — the two
+// halves of one claim, and a reader can put an event back on the capture clock
+// by adding them.
+//
+// What v2 moved, and where it went (spec §14's CH list):
+//   - `metadata` dissolves into the top level; `recorder` becomes a
+//     {name, version} pair rather than a string.
+//   - `trials` → `segments`, `trial_index` → positional `index` (+ `label`),
+//     `trial_data` → `host_data`, `view_state` → `initial_state`.
+//   - the initial DOM is a DomNode tree (snapshot.js), not an HTML string.
+//   - `stylesheets: {initial, events}` → one id-bearing array plus
+//     `stylesheet_events` (empty: CH captures no stylesheet mutations yet — a
+//     recorded gap, not a claim that none happened).
+//   - `ch_extensions` → `extensions["cyborg-hunter"]`, same content minus
+//     `marker_attr` (integer node ids retired the nonce markers), plus the
+//     `tier`/`keys` config echo that v1 kept in metadata.
+//   - `capture_stopped` gains a standard mirror: top-level `truncated` (§5.7).
+//
+// Everything CH-specific that the format has no field for goes into the vendor
+// namespace rather than riding as an unknown top-level key: an unknown key is
+// indistinguishable from a producer bug, and §9 exists precisely so a player
+// can ignore it knowingly.
 
 import { VERSION } from '../shared/constants.js';
 
+/**
+ * The wire format this module emits. Exported because it is not only the
+ * serializer's business: the meta pointer that rides in the host's data
+ * (persistence.js, and index.js's no-session degradation) states the schema
+ * version of the recording it points at, and a hard-coded literal there is how
+ * a v1 pointer survived into a v2 recorder.
+ */
+export var SCHEMA_VERSION = 2;
+
 // Convert an absolute performance.now() value to wire time (ms since
-// session start), rounded to 1 decimal to keep JSON compact.
+// recording start), rounded to 1 decimal to keep JSON compact (spec §7 permits
+// producer rounding and names CH's 0.1 ms).
 function wireT(t, sessionStart) {
   if (t == null) return null;
   return Math.round((t - sessionStart) * 10) / 10;
 }
 
 // Session-scoped CH arrays whose entries carry absolute `t` — converted to
-// session-relative on the way into ch_extensions.
+// session-relative on the way into the vendor namespace.
 function convertTimes(entries, sessionStart) {
   return (entries || []).map(function (e) {
     var out = Object.assign({}, e);
@@ -26,11 +57,38 @@ function convertTimes(entries, sessionStart) {
   });
 }
 
+// Time-sorted copy. Stable by construction (Array.prototype.sort is stable in
+// every engine CH supports), so events that share a `t` keep the order the
+// buffer received them in — which spec §7 makes authoritative within an array.
+function byTime(entries) {
+  return entries.slice().sort(function (a, b) { return a.t - b.t; });
+}
+
+// Spec §2 types every ViewportState field as a number, and a recorder started
+// without a window (node harness, a test) has no geometry to report. The
+// format has no way to say "unknown", so zeros keep the file loadable where
+// nulls would fail every consumer's type check.
+var VIEWPORT_UNKNOWN = { w: 0, h: 0, dpr: 1, scale: 1, offset_x: 0, offset_y: 0 };
+
+function viewportState(v) {
+  return v ? {
+    w: num(v.w), h: num(v.h), dpr: num(v.dpr, 1),
+    scale: num(v.scale, 1), offset_x: num(v.offset_x), offset_y: num(v.offset_y),
+  } : Object.assign({}, VIEWPORT_UNKNOWN);
+}
+
+function num(v, fallback) {
+  return typeof v === 'number' && isFinite(v) ? v : (fallback == null ? 0 : fallback);
+}
+
 /**
  * @param {Object} state - recorder.getState() output
- * @param {Object} opts - { chSessionReport } — pull-model CH merge; the
- *   caller (jsPsych adapter or researcher) provides CH's session report,
- *   the serializer never reaches into CH itself.
+ * @param {Object} opts
+ *   `chSessionReport` — pull-model CH merge: the caller (jsPsych adapter or
+ *                       researcher) provides CH's session report, so the
+ *                       serializer never reaches into CH itself.
+ *   `host`            — the runtime the recorder was embedded in (spec §2),
+ *                       `{name, version}`; null/absent for standalone use.
  */
 export function serialize(state, opts) {
   opts = opts || {};
@@ -40,42 +98,57 @@ export function serialize(state, opts) {
   }
   var ch = opts.chSessionReport || null;
 
+  // The last moment the recording observed, on the capture clock. Kept
+  // absolute so it sits in the same frame as `recording_started_at_perf`;
+  // their difference is the recording's duration in wire time.
   var lastT = s0;
-  var trials = state.trials.map(function (trial) {
-    var events = trial.events.slice().sort(function (a, b) { return a.t - b.t; });
+  var segments = state.trials.map(function (trial, i) {
+    var events = byTime(trial.events);
     var lastEventT = events.length > 0 ? events[events.length - 1].t : trial.tLoad;
     if (lastEventT > lastT) lastT = lastEventT;
+    if (trial.tEnd != null && trial.tEnd > lastT) lastT = trial.tEnd;
     return {
-      trial_index: trial.trialIndex,
-      trial_id: trial.trialId,
-      plugin: trial.plugin,
-      // t_load is the trial time origin (design §10). t_start/t_dom_ready are
-      // #3661-parity fields, null when the host has no pre-render hook.
+      // Positional, not the recorder's counter: spec §7 makes the array
+      // position authoritative and strict validation rejects disagreement.
+      index: i,
+      label: trial.trialId != null ? trial.trialId : null,
+      plugin: trial.plugin != null ? trial.plugin : null,
+      // t_load is the segment time origin (spec §3). t_start/t_dom_ready are
+      // null when the host has no pre-render hook.
       t_start: wireT(trial.tStart, s0),
       t_dom_ready: wireT(trial.tDomReady, s0),
       t_load: wireT(trial.tLoad, s0),
-      // A trial still open at serialization time (tab closed, mid-session
+      // A segment still open at serialization time (tab closed, mid-session
       // getRecording) ends at its last observed event.
       t_end: wireT(trial.tEnd != null ? trial.tEnd : lastEventT, s0),
-      // Scroll/viewport state at trial start — the viewer's camera seed.
-      // Times inside are absolute-free (plain state), so no conversion.
-      view_state: trial.viewState || null,
-      initial_dom: trial.initialDom || '',
+      // Keyframe (a DomNode tree) vs continuation (null) — spec §3. Absent on
+      // trace tier, where no segment ever carries one.
+      initial_dom: trial.initialDom || null,
+      // The replay-state seed the tree cannot carry (initial-state.js); null
+      // when every field was at its default, which is the spec's omit rule.
+      initial_state: trial.initialState || null,
       events: events.map(function (e) {
         var out = Object.assign({}, e);
         out.t = wireT(e.t, s0);
         return out;
       }),
-      trial_data: {}
+      host_data: trial.hostData != null ? trial.hostData : null,
+      // An implicitly opened segment (events arrived before any startTrial) is
+      // a CH-side fact about bracketing, not a standard field.
+      extensions: trial.implicit ? { 'cyborg-hunter': { implicit: true } } : null,
     };
   });
 
   var chExtensions = {
     replay_version: VERSION,
-    // Serialization-marker attribute name (per-recording nonce); the viewer
-    // harvests these markers out of the reconstructed DOM for stable
-    // mutation/anchor resolution. Null on trace-tier or legacy recordings.
-    marker_attr: state.markerAttr || null,
+    // v1 kept these in `metadata`; spec §14 routes the config echo here.
+    tier: state.tier,
+    keys: state.keys,
+    // documentElement's client box at session start. Spec §2's ViewportState
+    // has no room for it and the per-event camera block (§6) only carries it
+    // where an interaction happened, but it is the box the page was laid out
+    // against — what a viewer should size its reconstruction by.
+    viewport_client: state.viewportClient || null,
     ch_version: ch ? (ch.libraryVersion || null) : null,
     preset: ch && ch.config ? ch.config.preset : null,
     scoring: ch ? {
@@ -94,26 +167,58 @@ export function serialize(state, opts) {
       zoom_changes: convertTimes(ch.zoomChanges, s0),
       extension_injections: convertTimes(ch.extensionInjections, s0)
     } : null,
+    // Guard-friction violations are CH events with no standard type (§5.8
+    // forbids vendor events in the stream), so they live here with their
+    // times converted like every other session-scoped CH array.
     guard_violations: convertTimes(state.guardViolations, s0),
     capture_failures: convertTimes(state.captureFailures, s0),
-    capture_stopped: !!state.captureStopped
+    capture_stopped: !!state.captureStopped,
+    // Spec §8 redaction is a property of the file, but the mechanism enforcing
+    // it (redaction.js's taint set) has PAGE lifetime — so a recording that is
+    // not the page's first can inherit withholding it never configured. Without
+    // this flag an empty field means two things the file cannot distinguish:
+    // the participant typed nothing, or an earlier recording withheld it.
+    // Always present, like every other key here, so its absence means an old
+    // file rather than a clean page.
+    inherited_redaction_taint: !!state.inheritedRedactionTaint
   };
 
   return {
-    schema_version: 1,
-    metadata: {
-      start_time: new Date(state.sessionStartEpoch).toISOString(),
-      end_time: new Date(state.sessionStartEpoch + Math.max(0, Math.round(lastT - s0))).toISOString(),
-      end_reason: state.endReason || 'aborted',
-      participant_id: state.participantId,
-      recorder: 'cyborg-hunter-replay@' + VERSION,
-      tier: state.tier,
-      keys: state.keys
-    },
-    viewport: state.viewport,
-    stylesheets: { initial: state.stylesheets || [], events: [] },
-    rng_calls: [],   // shape parity with #3661; CH never re-executes code
-    trials: trials,
-    ch_extensions: chExtensions
+    schema_version: SCHEMA_VERSION,
+    recorder: { name: 'cyborg-hunter-replay', version: VERSION },
+    host: opts.host || null,
+    participant_id: state.participantId != null ? state.participantId : null,
+    recording_started_at: new Date(state.sessionStartEpoch).toISOString(),
+    recording_started_at_perf: s0,
+    user_agent: state.userAgent || '',
+    viewport: viewportState(state.viewport),
+    observed_root: state.observedRoot || null,
+    stylesheets: state.stylesheets || [],
+    // Known gap: CH captures the initial sheets only. Stylesheet mutations
+    // (spec §2 StylesheetEvent) need a CSSOM observer CH does not have, so the
+    // array is empty rather than absent — the format's way of saying "capture
+    // was on and nothing is recorded here".
+    stylesheet_events: [],
+    // Time-sorted on the way out (spec §7): the capture side coalesces both
+    // viewport channels through RAF callbacks, and this is the last place that
+    // can guarantee the property for the file.
+    viewport_changes: byTime(state.viewportChanges || []).map(function (c) {
+      var out = Object.assign({}, c);
+      out.t = wireT(c.t, s0);
+      return out;
+    }),
+    // CH never patches Math.random and never re-executes experiment code, so
+    // RNG capture was off — which §7 spells as both fields null.
+    rng: null,
+    rng_calls: null,
+    ended_at_perf: lastT,
+    end_reason: state.endReason || 'aborted',
+    // Spec §5.7: the standard mirror of the capture-stopped signal, so a
+    // player can surface truncation without reading a vendor namespace.
+    truncated: !!state.captureStopped,
+    extensions: { 'cyborg-hunter': chExtensions },
+    // Last, matching the canonical fixture's reading order: the bulk of the
+    // file after everything a reader needs to interpret it.
+    segments: segments,
   };
 }