Skip to content
bucker

Session replay: what is captured, what is masked, and where scrubbing happens

Audit of the replay privacy pipeline, SDK capture through stored segment. The code of record: sdks/browser/src/replay/ (capture and client-side masking), sdks/browser/src/microdom.ts (selector construction), domain/src/modules/replay/ingest.ts (server-side scrub and storage), domain/src/modules/replay/transcript.ts + domain/src/modules/essence/trust.ts (agent-facing compilation and injection quarantine).

The recorder is not rrweb. It records the interaction layer — no DOM mutations, no screenshots, no text nodes except where explicitly noted below. Most of the privacy story is therefore structural: the bytes for a pixel-accurate replay of the user's screen are never collected in the first place.

That is a decision, not a gap waiting to be filled. A visual DOM-snapshot tier (SG-037) was declined by the owner on 2026-10-17, accepting the runbook's recommendation (docs/2026-10-17-dom-replay-decision.md, Option 2): the guarantee stays structural — there are no screen bytes for a misconfiguration to leak — rather than becoming a mask configuration that customer markup can defeat. The revisit trigger is a lost deal attributed to the missing visual replay; reopening means amending this document and the DPA (§5 of docs/legal/dpa.md) first, with the DPA owner's sign-off, before any code.

1. What the recorder captures, per event type

Event Captured User content?
nav route template (/orders/:id), previous template No — ids collapsed, query string dropped
click micro-DOM selector chain (form#pay > button#submit) Element label text only if maskAllText: false
input selector, masked/sensitive flags, value Value is <masked> unless maskAllText: false
net method, URL template, status, duration, error name No — query strings dropped, path ids collapsed
console console.error/console.warn arguments, stringified, ≤200 chars; info/log/debug only when consoleLevels asks (SG-043) Shape only under maskAllText (§4 F2 was fixed in the SDK)
scroll coalesced scrollY No
resize viewport width × height No
vital LCP / FCP / TTFB / CLS / INP as numbers (SG-043) No — no element, no URL

Two opt-ins widen net and click (SG-043):

  • Network detail is captured only for URLs the code allowlists (networkDetailAllowUrls), and only the header NAMES it lists. Credential headers are dropped even when named, JSON bodies have credential-shaped keys replaced, and every body is cut at 2048 characters. The stored-tier scrub and the org's rules run over it as over every other string. A project that enforces masking switches it off remotely, and ingest refuses a segment that carries a body anyway. Bodies never reach the agent transcript.
  • Dead clicks add one boolean to a click. They are computed from a MutationObserver that records only that the DOM changed, never what changed.

By default nothing leaves the page until an error is captured: the ring buffer (buffer.ts) holds at most the last 30 seconds / 200 events in memory, and an error-free session is never transmitted. The one exception is opt-in and off by default: sessionSampleRate (SG-039, session.ts) records that share of sessions whole, in segments flagged replay_type: session. Those segments carry exactly the event types above, under exactly the same masking. The tier changes when events are sent, never what is captured. The project's remote config can lower the rate and never raise it. Eviction is counted (evicted), so a short segment is explainable rather than suspicious.

Client-side masking (mask.ts)

  • Default is mask-everything. maskAllText defaults to true; input values arrive as the literal <masked> and click labels are omitted.
  • Credential-shaped fields are masked at every setting. isSensitiveField (type=password, autocomplete credential tokens, cc-*, one-time-code, name/id/aria-label matching password/token/cvv/ssn/… shapes, data-bucker-mask / data-private / data-sentry-mask attributes) is not reachable from any option, by construction — turning masking off is not consent to ship a password.
  • Selector lists only refine the default (SG-041). mask, block and ignore remove information. unmask is the one list that adds it, and it never reaches a credential-shaped field. maskFn runs only on values already leaving unmasked, so it can remove information and never add it.
  • The project's remote configuration only tightens. GET /api/:projectId/replay-config (replay/settings.ts) can force mask-all on, add selectors, revoke unmask and cap sample rates. Nothing in it can loosen a deployed recorder.
  • URLs are templated before capture. urlTemplate drops every query string and collapses numeric / UUID / long-hex / opaque path segments to :id, so a /reset-password/<token> never leaves the page as a live credential. Cross-origin hosts are kept (which third party failed is load-bearing).
  • Selectors are attribute skeletons. microdom.ts keeps tag, id, data-testid, role, name, type and one build-stable class; hashed class names are pruned. Element text is read into the micro-DOM node but only ever emitted on click.text, which is gated on maskAllText: false.

2. What reaches the server

One bulk-lane envelope per error (rate-limited to one segment per 5 s), carrying:

  • replay_event — segment metadata: replay/segment ids, time bounds, event count, starting URL template, masked flag, eviction count, stop reason, overhead.
  • replay_recording — the event array itself.

Both are re-validated on the server against schemas declared server-side (replay/schemas.ts): a replay payload is authored by a script running on the customer's page and is attacker-controllable in the strongest sense. Strings are bounded, events capped at 2000/segment, and an invalid item stores nothing.

3. Where scrubbing happens relative to storage

page ──mask (SDK, capture time)──▶ wire ──▶ accept (counted, not parsed)
  ──▶ worker ingest:  zod validation
                      ├─ SCRUB, stored tier  ──▶ blob write (payloadKey)
                      │                        ──▶ ReplaySegment row (url, meta)
                      └─ SCRUB, agent tier   ──▶ transcript compile
                                                  ├─ injection quarantine (Labeler)
                                                  └─ ReplayTranscript row
  • Stored tier before any byte persists (ingest.ts): the same rule set that guards the Event row — JWTs, Bearer/Basic values, vendor tokens (sk-…, ghp_…, xox…), AWS key ids, private-key blocks, card numbers (Luhn-checked), high-entropy secrets — runs over the event array and the metadata URL before the blob write and before the segment row. The redaction summary (e.g. 2x jwt) is stored inside the blob and served with the payload, so a [Filtered] value is explainable to whoever is looking at it.
  • Masking enforcement before anything else (SG-041). When the project's enforceMasking is on, ingest.ts refuses a segment before the scrub, the blob write and the row: one that declares masked: false, carries an unmasked input value, or carries a click label. The check reads the events themselves, not only the client's own masked claim (see F5), so an old, forked or hostile SDK cannot get an unmasked recording stored for that project.
  • Agent tier before the transcript: the transcript is agent context by definition, so it compiles from the strictly narrower agent projection — additionally redacting emails and public IPs that a human on-call engineer may legitimately see in the payload view. The same applies to …/replay/anchors labels, which ride RCA evidence: they are built from agent-tier-scrubbed events at read time.
  • Injection quarantine at compile and at anchor build: every page-derived string served to an agent goes through the essence Labeler; matches are replaced with [redacted:quarantined] and the document publishes a securityNotice. Quarantine is about instructions, the scrub about data — they are independent and both mandatory.

Storage split: the recording lives in the blob store under replays/<projectId>/<day>/… (retention = drop the day prefix); Postgres holds only metadata (ReplaySegment) and the compiled, already-redacted transcript (ReplayTranscript). Segments are bounded (≤2000 events, every string bounded), so a payload tops out at low single-digit MB and is served whole, JSON, sorted by the recorder clock — no chunking API is needed at these sizes.

Recording lifecycle (SG-042)

  • Delete one recording or a whole session. DELETE …/replay/:segmentId and DELETE …/replays/:replayId need write on the issue (or on the project while a segment is unlinked). They write an audit row before deleting, then delete through purgeReplaySegments: the blob first, then the row, because the row is the only thing that knows the key. The dashboard offers both from the player, behind a typed confirmation.
  • Per-project retention. ProjectRetentionSettings.replayRetentionDays (Settings › Projects › Session replay) can only shorten the organization's replayDays window. The compliance sweep purges past the smaller of the two, and a longer value has no effect.
  • Per-subject erasure (GDPR Art. 17). The telemetry erasure (compliance/telemetry-blob-erasure.ts) now also seeds a session from ReplaySegment.userHash, the scoped pseudonym of the scope user that SG-038 stores. A session-tier recording that never carried an error, and never typed the address, is still reached by the identifier the controller names. What remains out of reach is declared in TELEMETRY_NOT_REACHABLE.

4. Findings

F1 — fixed server-side: replay bypassed the pipeline's scrub stage. Error events pass through scrubEvent before storage (workers/src/pipeline/process.ts), but replay envelopes went from zod validation straight to the blob store: a Bearer token in a console.error, or a secret pasted into an unmasked input, was stored verbatim and could surface in the transcript (the injection scanner does not catch credentials). Fixed in ingest.ts: stored-tier scrub before the blob write, agent-tier scrub before transcript compilation, per §3.

F2 — SDK-side, flagged (out of scope to change here): maskAllText does not apply to console capture. recorder.ts records console.error/console.warn arguments verbatim (≤200 chars) regardless of the masking setting, while the segment's masked: true flag suggests otherwise. Applications routinely interpolate emails, names and order details into error logs, so a "masked" segment can still carry user text in console.message. The server-side scrub now removes credential-shaped content, and emails never reach the agent projection, but stored blobs retain what the page itself logged. Recommended SDK change: honor maskAllText for console messages (or add a dedicated maskConsole option) and reflect the residual exposure in the masked flag.

F3 — SDK-side, minor: selector attributes are captured unmasked. id, name and data-testid values ride into selectors and are not maskable. In practice these are developer-authored, but an app that writes user data into DOM ids would leak it into selectors. The server bounds them (≤512 chars) and scrubs credential shapes; no further action recommended beyond documenting the assumption.

F4 — accepted risk, mitigated: the metadata URL is client-asserted. Our SDK sends a template, but the schema cannot force a hostile or legacy client to template. Since the scrub now runs over meta.url too, a raw /reset/<jwt>?email=… is redacted before it reaches the ReplaySegment.url column; a raw email in a path segment, however, would persist at the stored tier (consistent with how event URLs are treated).

F5 — honest-flag note: masked is asserted by the client. The row's masked column reflects what the SDK claims, not what the server verified. It is surfaced as an honesty field for triage, not as a guarantee; the guarantees are the ones enforced server-side in §3.

5. What the read API serves

  • GET …/issues/:id/replay — segment metadata only (time range, duration, event count, size, masked, evicted, transcript availability). No payload bytes.

  • GET …/issues/:id/replay/transcript — the agent form: agent-tier scrubbed, quarantined, token-budgeted, provenance-labeled per line.

  • GET …/issues/:id/replay/anchors — notable moments (error, navigation, last-N interaction) as { timestampMs, offsetMs, label }; labels are built from agent-tier-scrubbed events and labeled/quarantined like transcript lines.

  • GET …/replay/:segmentId — the stored-tier payload (humans may see emails here; agents are never handed this route's output directly), served as JSON with its redactions summary and format descriptor (bucker.replay.interaction + version) so a player can refuse formats it does not know.

  • GET …/replays and GET …/replays/:replayId (SG-038) — the project's sessions and one session's segments, from facet columns ingest derived from the SCRUBBED events. The only identity column is userHash, deriveUserHash's scoped pseudonym (the one events.userHash holds). The SDK's user object is hashed on arrival and never stored, and the list serves only whether a session was identified. The browser is a family and major version, never the user agent string.

  • GET …/replay/:segmentId/traces (SG-040) — the traces the segment's requests carried (ids only, from traceparent/traceresponse), each with the backend errors on it. Those errors are drawn only from the projects the caller may read (reachableProjectIdsFor), because a trace crosses projects and reading a replay does not imply reading the API's issues. The same narrowing applies to the backend anchors on …/replay/anchors.

All these routes authorize as read on the issue, 403-not-404 for permission denials, with existence resolved tenant-scoped first (a foreign segment id 404s before any authorization question is asked about it).

6. Reading sessions over MCP (DX-01)

Two read tools reach the same stored facets the dashboard list reads, so an agent can find and read a session without an issue to start from. Nothing here widens what is stored; what changes is who can read it and what is written down when they do.

  • sessions_list (scope event:read) filters with the replay search grammar, sorts by newest, errors, rage clicks or duration, and pages with a cursor. It reads the last 30 days and the newest 10,000 sessions, and every answer states what it scanned and whether the cap cut it short. include: ["groups"] counts sessions by one dimension (url, browser, release, environment, replay type, issue, day).
  • session_get (scope event:read) returns one session as session_essence_v1, at most 400 tokens: when and how long, release, browser, whether the user was identified (a boolean, never who), how it was recorded (basis: replay type, the configured sample rate, and a consent field that stays null until the consent basis ships), the last five routes, counts, up to three issues and traces, five flag variants and six chapters. include: ["transcript"] adds the compiled action log, at most 800 tokens, newest window kept.

Four rules govern both:

  1. A person lookup is a human read. The user: search key matches a named person's sessions by their pseudonym; over MCP it is refused with a 403 naming the human-only pii:read scope, in any position in the query, and a view that would save it is refused too. has:user names no one and stays open.
  2. Small cohorts are folded. A group is shown only when at least five distinct users stand behind it; the rest are one other bucket whose own distinct-user count is exact, and which withholds its counts, the user count included, when even the total is under five (belowFloor). A session with no user hash counts as its own user, so an anonymous cohort cannot be shrunk to one person.
  3. An incident token reads only its own sessions. A project-wide list is refused to a token pinned to one incident, groups included. session_get reads a session only when one of its recordings was grouped into that incident's issue, and answers any other session, an unknown id included, with the same 403. The essence it reads names that one issue only: the session's other issues, and their error events' flag state, are siblings it neither lists nor counts.
  4. Every read is recorded, and never with content. Each call that returns session data writes one replay.session.read audit row: the token, how many sessions came back and which categories (metadata, route labels, issue links, trace links, flag variants, chapters, transcript), with the session id as the target for session_get. A route, a title or a transcript line is never in the row, and a read that cannot be recorded is refused. The dashboard list marks a session viewed when you, or an agent acting for you, have read it, and can hide those on request.

Every string that came from a customer's page or SDK (the session id itself, which the recorder chooses, routes, browser, release, environment, issue titles, flag keys, variants and versions, chapter routes, transcript lines) goes through the agent-tier scrub and the injection scan, is listed in the envelope's trust.untrustedFields with its untrusted class, and so counts as untrusted text served to that agent's session.

The list is also available as a file: GET …/replays/export?format=csv|jsonl, at most 10,000 rows, written from the same query as the list on screen. An export of 1,000 rows or more is audited as replays.export with its filter and count.

7. Session summaries (DX-13)

A summary is a model's short account of one session, and it is off for every project until a person turns it on. Nothing about a session goes to a model before that, and nothing here sends video, a DOM or a pixel: the recorder does not capture them, and the model never sees an event.

The switch. session_summary.widen is a human-only act for an organization owner, taken per project in the replay settings. An agent, a service credential and an OAuth client are refused it before the organization is read; it is refused during a change freeze; it is written to the audit log marked as a loosening and every owner is alerted. Turning it off (session_summary.narrow) is something an agent may do, because it can only take away. The same switch gates every other use of a model over session data: the element-role labeler of the friction detectors runs only where it is on.

What the model reads. Only the agent-tier action log Bucker already serves to agents, the anchors (with ids) and chapters derived from it, and counts Bucker computed, in at most 1,200 tokens. Routes are paths without query strings or fragments. Selectors are the leaf element only. Request lines carry the method, the path and the status, never a body or a header. Input values and element text are removed before the log is compiled, and console lines are not sent at all when the project masks all text. Every line goes through the injection scan (a hit becomes a placeholder) and the agent-tier scrub, and the whole input is declared to the AI egress ledger under the purpose session_summary: counts per data class and a digest, never text. The call is made from bucker-workers only, to Anthropic only, never inside an ingest request, and only while the organization's AI switch is on. A project may take the purpose away (ai_egress_policy.narrow), and the summary then stays unavailable.

What is shown. A fixed shape: an outcome, an intent, at most five key moments and chapter labels. Each claim cites an anchor, and the server checks every citation against a second read of the stored recordings before anything is shown: the anchor must exist and have been shown to the model, its kind must match the claim, an errored outcome needs an error in the stream, an abandoned one needs the abandon marker, a number the model writes must be one its citation carries (counts always come from Bucker), no text of a quarantined line may reappear, and the output must pass the same scrub and scan. A summary that fails any check is kept as rejected with the check that failed, and readers see the deterministic chapters instead. A summary is model text: it is labelled so, served as untrusted, never signed and never opens, closes or fires anything. At most 500 summaries are generated per project per day.

Retention. One row per session, replaced when the recordings, the prompt version or the model change, and removed with the session: deleting a session or letting it age out takes its summary with it, and a summary whose session is gone is not readable.