Files
PaperClipAI/doc/cloud-browser-analytics.md
T
DottaandClaude Opus 5.5 b56f240f45 feat(analytics): show session replay text by default, mask only customer content (#22057)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosted Paperclip Cloud records browser sessions with PostHog session
replay
> - Replay masked all text and showed only an allowlist of chrome, so
most replays showed only stars
> - The team cannot see how people use the board, and the allowlist
needed a review for each new label
> - The owner decided to show text by default and mask only marked
customer content, the way PostHog normally works
> - This pull request flips the default, removes the allowlist, and
marks every surface that can show connected-account content
> - The benefit is readable replays, while Google user data and Slack
data stay masked

## Linked Issues or Issue Description

**Subsystem affected**

Hosted Cloud browser analytics: PostHog session replay in the board UI
(`ui/src/lib/analytics/`).

**Problem or motivation**

Replay masked every text node. Only sidebar items and opt-in components
showed text. Replays were almost unreadable. Each new label needed an
`analyticsChrome` opt-in and an allowlist review.

**Proposed solution**

Record text as it is. Mask text only inside `ph-mask` (customer
content), `ph-no-capture` (secrets, blocked) and editable content. Add
`ANALYTICS_MASK_CLASS` to every surface that can show connected-account
content (Gmail, Calendar, Drive and Docs, Slack) or other free-form text
from agents or customers.

**Alternatives considered**

Keep "mask all" and grow the allowlist. This needs a review for each
label and still hides most of the board.

## What Changed

- `privacy.ts`: `ANALYTICS_MASK_TEXT_SELECTOR` is now `.ph-mask,
.ph-no-capture, [contenteditable]:not([contenteditable="false"])`. rrweb
masks a text node only when its parent or an ancestor matches the
selector. Removed `maskReplayText`, `isReplayTextRevealed`,
`ANALYTICS_UNMASK_ATTRIBUTE` and `ANALYTICS_UNMASK_PROPS`.
- `product-analytics.ts`: removed `maskTextFn`, so rrweb uses its
default star masking. `maskAllInputs`, `blockClass`, `maskAttributeFn`,
`mask_all_text` and `mask_all_element_attributes` do not change.
- Removed the `analyticsChrome` prop from `Button`, `Label`,
`TabsTrigger`, `EmptyState` and `SidebarNavItem`, and from all sidebar
call sites.
- Added `ANALYTICS_MASK_CLASS` to the content element (not the chrome)
of these surfaces:
- Link preview cards, task quicklook description, external object pills
and rows, related-work titles.
  - Email message cards and email send intents.
- Connected account names and email addresses (Browse, Connections, app
detail headers, app sidebar, connection choice list, connection access
and repair cards), GitHub login and repositories, Slack workspace names,
chat channel and linked user labels.
- Inbox and decision rows (subject and detail), obligation evidence,
Needs You notes and receipts, decision options and result summaries, and
the interaction card roots (questions, options, answers, tool action
requests, suggested tasks).
- Approval payloads, action card input and reason, recovery card
headline, evidence and options, run ledger retry detail, interrupt
handoff previews.
- Run transcripts, run failure details and run events on the agent page.
- Search result snippets, toast bodies, voice and call transcripts, case
summary, files and fields, attachment previews, artifact previews (text,
tables, patches and documents).
- Replaced `unmask-allowlist.test.ts` with `replay-masking.test.tsx`. It
checks that unmarked chrome records as it is, that each marker masks,
that a rendered voice transcript and run transcript mask, that each
surface above has the class, and that autocapture records no element
text. Updated `privacy.test.ts`, `shared-chrome.test.tsx` and
`product-analytics.test.ts`.
- Updated `doc/cloud-browser-analytics.md`: new default, marker classes,
masked surfaces, and residual risk.

## Verification

- `pnpm exec vitest run src/lib/analytics` in `ui/`: 83 tests pass.
- Vitest for the 48 test files next to the changed components: 994 tests
pass.
- `tsc --noEmit -p ui/tsconfig.json`: no new errors (only the existing
generated Storybook catalog errors).
- `pnpm verify` exits 2 because a doc is a global CI input. Required CI
supplies the broad coverage.
- Manual: I ran an isolated local instance with a Cloud-like browser
analytics config. `PAPERCLIP_POSTHOG_HOST` pointed to a local capture
server, not PostHog. I opened a task page in headless Chromium, hovered
a GitHub pull request link, and decoded the captured `/s/` replay
payloads:
- Clear text: sidebar (`New task`, `Chat`, `Tasks`, `Inbox`, `More`),
breadcrumb, task title `Quarterly launch checklist`, `REP-1`, the
Connectors promo heading and button.
- Masked (stars only): the markdown task body, the chat comment, the
link preview card (pull request title, author, URL, status), and the
company menu.
- Marker strings in the body, comment and preview never appeared in
clear text in any payload.
- The page `<title>` (task title and company name) is in the replay
head. This is accepted residual risk.

## Risks

- Text that is not marked is now recorded. Task titles, agent names,
project names, company names, routine names, artifact and document
titles, and activity rows are visible in replays. The owner accepted
this. An agent can copy email or Slack text into a task title.
- A new surface that shows connected-account content without
`ANALYTICS_MASK_CLASS` is recorded until somebody marks it.
`replay-masking.test.tsx` and the doc list the marked surfaces.
- The masking options in `posthog.init` take precedence over the PostHog
project masking settings (posthog-js 1.450), so a dashboard change
cannot unmask content. Keep the project settings empty to avoid a
console warning.
- Some masked areas also mask nearby fixed labels (for example the
interaction card buttons). This is safe.
- Analytics is off on self-hosted and local installs, so they see no
change.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (claude-opus-5-5), Anthropic, with tool use and code
execution in Claude Code.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 15:18:50 -06:00

210 lines
12 KiB
Markdown

# Cloud Browser Product Analytics
On Paperclip Cloud, the board UI can send page views, sessions, autocapture
clicks, heatmaps, Web Vitals and session replays to PostHog. Self-hosted
installs never do this: they do not download `posthog-js` and do not serve the
PostHog proxy.
## Who gets it
The server decides, in `server/src/services/cloud-posthog-browser.ts`. The
authenticated `GET /api/auth/get-session` response carries a
`browserAnalytics` object only when all of these hold:
1. The instance is cloud managed (`isCloudManagedInstance`).
2. `PAPERCLIP_POSTHOG_PROJECT_TOKEN` and `PAPERCLIP_CLOUD_STACK_ID` are set.
3. `PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`.
Otherwise the field is `null`, and the browser loads nothing. When it is set,
the browser loads PostHog's browser script (`/_ph/static/array.js`, through the
proxy) only after the page settles (first paint, page reads finished, browser
idle), so cold loads do not wait for it. posthog-js is not an npm dependency
of the board and is in no bundle chunk; PostHog serves it, as it serves the
extensions posthog-js loads at run time (recorder, web vitals).
## Configuration
| Variable | Default | Meaning |
| --- | --- | --- |
| `PAPERCLIP_POSTHOG_PROJECT_TOKEN` | — | PostHog project token. It is public by design: it can send events but cannot read data. |
| `PAPERCLIP_POSTHOG_HOST` | `https://us.i.posthog.com` | PostHog ingest host. The proxy forwards to it. |
| `PAPERCLIP_POSTHOG_ENVIRONMENT` | — | `staging` or `production`. Added to every event as `environment`. |
| `PAPERCLIP_POSTHOG_BROWSER_ENABLED` | off | `1` turns browser analytics on for this stack. Leave it unset to keep it off. |
| `PAPERCLIP_POSTHOG_REPLAY_ENABLED` | on (when browser analytics is on) | `0` turns session replay off for this stack and keeps the other browser analytics. |
### Per-stack opt-out
For a customer whose contract forbids recording, set
`PAPERCLIP_POSTHOG_REPLAY_ENABLED=0` on that stack. To turn off all browser
analytics for a stack, unset `PAPERCLIP_POSTHOG_BROWSER_ENABLED`. Both take
effect on the next server restart.
## Reverse proxy
The browser sends to `/_ph` on its own origin, so ad blockers do not drop
events. `server/src/routes/posthog-proxy.ts` is not a generic proxy. It
forwards only the requests posthog-js makes:
| Method | Path | Upstream |
| --- | --- | --- |
| `POST` | `/e/`, `/i/v0/e/`, `/batch/` | ingest host |
| `POST` | `/s/` (session replay) | ingest host |
| `POST` | `/flags/`, `/decide/` | ingest host |
| `GET` | `/array/<token>/config`, `/array/<token>/config.js` | assets host |
| `GET` | `/static/<name>.js` | assets host |
The ingest host is `PAPERCLIP_POSTHOG_HOST`. The assets host is derived from it
(`us.i.posthog.com` → `us-assets.i.posthog.com`). Every other method or path
answers 404 without contacting PostHog. The proxy streams bodies, builds a new
header set from an allowlist plus `X-Forwarded-For`, and never forwards the
inbound Host, Cookie or Authorization headers. It drops `Set-Cookie` from
responses. It refuses bodies over 64 MiB (413) and limits requests in
flight to 16 per client address and 256 in total (429). It is mounted only when
browser analytics is on. It does not require a session: posthog-js sends some
events while a page unloads, and the proxy can only reach the two PostHog hosts
with the public project token, like PostHog's own ingest endpoint.
### Visitor address behind the platform proxy
The per-client limit uses `req.ip`, which comes from the server's trusted proxy
settings (`TRUST_PROXY`). It never comes from a header the client controls. If
`TRUST_PROXY` is unset behind a platform proxy, `req.ip` is the proxy's private
hop, so every visitor behind that hop shares one 16-request limit. Set
`TRUST_PROXY` to the platform's proxy range so that `req.ip` is the visitor.
The `X-Forwarded-For` value that the proxy sends to PostHog carries the
visitor's location. When the socket peer is private, the proxy uses the
rightmost public `X-Forwarded-For` entry, which the platform edge appended.
This value is used only for location, never for limits.
## Identity
- After sign-in: `identify(session.userId, { email, name })`. `session.userId`
is the authenticated actor's user id verbatim (`req.actor.userId`, for
example `paperclip-id:...`), the same id server events use as `distinct_id`. Email and name are person
properties only, never event properties.
- `group("workspace", stackId)`.
- Every event carries `deployment_source: "cloud"` and `environment`. Without
`PAPERCLIP_POSTHOG_ENVIRONMENT`, `environment` is `staging` on a
`*.staging.paperclip.app` host and `production` otherwise.
- Sign-out: `reset()`, called by `useSignOut` before it leaves the page.
- API requests to our own host carry PostHog tracing headers, so server events
link to the browser session.
## Privacy
Session replay shows text by default, the way PostHog normally works. Text is
masked only inside marked customer content. Input values and attribute values
are always masked.
- Session replay masks every input value (`maskAllInputs`).
- Replay masks text only inside these markers (`ANALYTICS_MASK_TEXT_SELECTOR`
in `ui/src/lib/analytics/privacy.ts`, passed as rrweb `maskTextSelector`):
- `ANALYTICS_MASK_CLASS` (`ph-mask ph-sensitive`): customer content.
- `ANALYTICS_NO_CAPTURE_CLASS` (`ph-no-capture`): secrets. Replay blocks
these elements entirely.
- `contenteditable` editors (not `contenteditable="false"`).
rrweb masks a text node only when its parent matches the selector or has an
ancestor that matches it. All other text, for example navigation, headings,
buttons, task titles, agent names, project names and company names, is
recorded as it is.
- Replay also masks attribute values (`maskReplayAttribute`): only layout
attributes (`class`, `style`, `role`, `data-state`, SVG geometry and similar),
rrweb metadata and stylesheet links keep their values. `title`,
`aria-label`, `alt`, `placeholder`, `src`, `href`, `data-*` values and
element references (`id`, `for`, `aria-labelledby`) are always masked, so
images record as empty boxes and link targets (for example download links
with file paths) never leave.
- The masking options in `posthog.init` take precedence over the PostHog
project's "Privacy and masking" settings (posthog-js 1.450). posthog-js
ignores the project setting and logs a warning when the two differ. Keep the
project masking settings empty, and change masking only in `privacy.ts`. The
`ph-mask` class is also the posthog-js default `maskTextClass`.
- `ANALYTICS_NO_CAPTURE_CLASS` replaces secrets with a blank box in replays:
every password-type `Input`, environment variable values, new secret
values, and secrets shown as text: one-time sign-in and device codes,
pairing and setup prompts, identity confirmation links, newly issued API
keys and gateway tokens, gateway client snippets, webhook URLs and secrets,
invite claim secrets, raw provider frames and SSH fallback commands.
- Every event and replay meta event goes through `scrubCapturedEvent`
(`before_send`). Every URL keeps only its origin and path: query and hash
values never leave, because they can hold credentials, file paths or search
text. The token segment of `/board-claim/<token>` and `/invite/<token>` is
redacted (`redactAnalyticsUrl`). Other strings only have secret
`key=value` pairs redacted.
- Events never carry the page title (`before_send` drops `title`), because
Paperclip page titles name the task and the organization.
- Autocapture never records element text or attribute values
(`mask_all_text`, `mask_all_element_attributes`). It keeps the click, the
element tree and the page.
- Connected-account content is Google user data or Slack data. No human may
read it in a replay (privacy policy and Google API Limited Use). The
surfaces below, and other free-form text that agents or customers write,
carry `ANALYTICS_MASK_CLASS` on their content element (not on the chrome
around it):
- Rendered markdown (task bodies, comments, chat messages, documents), the
rich editor, task and issue chat threads (messages, tool calls, tool
results, interaction cards), the comment timeline and the file viewer.
- Link preview cards, task quicklook descriptions, external object pills and
rows, and related-work titles.
- Email message cards and email send intents.
- Connection names, connected account names, aliases and email addresses
(Browse rows and the remove dialog, Connections, app detail headers, the
app sidebar, connection choice lists and instructions, aggregator and
Composio account dialogs, Tailscale networks, agent tool and audit
tables, AI connection names, pickers, selects, account details and
controls, pool run details, subscription and quota panels, adapter
sign-in status, connection access and repair cards), GitHub logins
(identity rows, bot people, chat setup, run identity history) and
repositories, Slack workspace names (list and selected value), Slack
account pickers, chat channels, linked user labels, the external task
banner and chat identity pages.
- Connection and account management surfaces are masked by section, not
label by label: the Browse connector list, the App detail body below its
header, the Connections table, Tailscale networks, the chat connection
detail body and its account subtitle, GitHub chat setup, the AI
connection pool editor and the chat identity confirmation. Every dialog,
alert dialog, select (trigger and list), popover, dropdown, sheet and
tooltip under `pages/apps`, `features/connections` and
`components/ai-connections` carries its own mask, because portals escape
the page's masked container; `replay-masking.test.tsx` fails when one
does not.
- App action test results (parsed preview and raw response).
- Inbox and decision rows (subject and detail line), obligation evidence,
Needs You notes and receipts, decision cards and compact decisions,
decision records, and interaction cards (questions, options, answers,
tool action requests, suggested tasks) wherever they render.
- Approval payloads, action card input and reason, recovery card headline,
evidence and options, run ledger retry details and interrupt handoff
previews.
- Run transcripts, run failure details, run events, run stdout and stderr
excerpts (agent page and execution workspace operations), the run
invocation command, notes, prompt, context and environment, Runner
inspector frames, and every preformatted block that shows run output,
tool or webhook payloads, request or response bodies, instructions,
skills or package files.
- Saved connection instructions for agents.
- Document and case revision diffs.
- Search result snippets, toasts (title and body), voice and call
transcripts, case summaries, files and fields, attachment previews and
artifact previews (text, tables, patches and documents).
Component tests render these surfaces with distinctive fixture text and
assert, through `ui/src/lib/analytics/replay-recording.test-utils.ts`, that
the text is rendered but not recorded (or is blocked, for secrets),
including alternate branches, dialog portals and selected values in
closed pickers. `ui/src/lib/analytics/replay-masking.test.tsx` also pins
the remaining surfaces at source level. A new surface that shows
connected-account content needs the class and a test.
- Residual risk: text that the owner accepted as visible can still hold
customer words. Task titles, agent names, project names, company names,
routine names, artifact and document titles, and activity rows (which name
the task or entity) are recorded as they are. Paperclip member names and
email addresses on member, access and profile pages are recorded too. An
agent can copy email or Slack text into a task title. Masking is opt-in per
surface, so a new surface that renders connected-account content without
the class is recorded until somebody marks it.
- The UI never captures an event that the server already sends
(`PAPERCLIP_EVENTS`); `product-analytics-events.test.ts` enforces this.