mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 07:42:38 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - On Paperclip Cloud, the board UI sends browser analytics to PostHog through a same-origin proxy at `/_ph` > - The proxy limits requests in flight: 16 per client address and 256 in total > - Each open tab runs posthog-js, and one tab can have a few requests in flight at once > - On Railway without `TRUST_PROXY`, `req.ip` is the private edge hop, so all visitors share one 16-request limit > - This pull request raises the limits, makes them configurable, and stops the per-client limit when `req.ip` is a shared private hop > - The benefit is that busy stacks with many users and many tabs do not lose analytics to 429 answers, and ops can see when a limit is hit ## Linked Issues or Issue Description **Subsystem affected** Server: the PostHog reverse proxy for Cloud browser analytics (`server/src/routes/posthog-proxy.ts`). **Problem or motivation** The proxy limits are too low for busy Cloud stacks. One user with many tabs can use 16 requests in flight. Behind the Railway edge without `TRUST_PROXY`, `req.ip` is a private `100.64.x.x` hop, so all visitors share one 16-request limit. The proxy then answers 429 and posthog-js drops or delays events and replay uploads. Ops cannot change the limits and cannot see when the proxy refuses requests. **Proposed solution** Raise the defaults to 128 per public client address and 1024 in total. Read both limits from two environment variables with a strict parse and a ceiling. When `req.ip` is not a public address, apply only the total limit. Give each request a 60 second deadline. Log a warning at most once a minute when the proxy refuses requests at a limit. **Alternatives considered** Find the visitor for the per-client limit from `X-Forwarded-For`. A client can write that header, and an earlier security review asked the proxy to keep `req.ip` as the key, so this change does not do that. Scale the per-client limit for a shared hop. All visitors share the hop, so a scaled limit is only a second total limit. The proxy applies the total limit alone instead. **Additional context** Fleet operators can set the variables with an `env_config` campaign. `doc/cloud-browser-analytics.md` tells how. Refs #22012 (the proxy) and #22052 (visitor address behind a private hop). ## What Changed - Raised `DEFAULT_POSTHOG_PROXY_LIMITS` to 128 requests in flight per client address and 1024 in total. The 64 MiB body limit did not change. - Added `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` and `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT`. `resolvePostHogProxyLimits` reads them where `resolvePostHogProxyMount` builds the proxy. A value must be a whole number from 1 to 65536. An invalid value logs a warning and uses the default. The server does not stop. - Added `posthogProxyClientKey`. It returns `req.ip` only when it is a public address. For a private, carrier-grade NAT, loopback, link-local or other reserved address, or no address, the proxy applies only the total limit. The key never comes from a client header. - Added `createPostHogProxyLimitReporter`. When the proxy answers 429, it logs `PostHog proxy refused requests at its in-flight limit` at most once a minute. The fields are the refusal counts per limit since the last warning, the requests in flight, the limits and the time since the last warning. The warning has no addresses. It uses no timer: it checks the time when a refusal occurs. - Added a request deadline of 60 seconds from the time the proxy accepts a request. At the deadline, the proxy stops the request to PostHog and closes the browser response, also when PostHog already finished and the browser does not read the response. The slot is then free again. Before, the 30 second upstream timeout was an idle timeout, so a slow body that sent a byte at a time could hold a slot until the server request timeout (300 seconds). - The mount object now also returns the limits in use. - Updated `doc/cloud-browser-analytics.md`: the limits, why these defaults, the variables, the shared-hop behavior, the warning fields and how to tune a fleet with an `env_config` campaign. Why these defaults: - 128 per address covers about 10 people behind one office network, each with 4 tabs and 3 requests in flight per tab, with space left over. - 1024 in total keeps memory bounded. The proxy streams bodies, so a request holds two sockets and the stream buffers between them, not the full body. In a local test on this branch, 1024 held requests added about 96 MiB of resident memory with 4 KiB bodies and about 173 MiB with 256 KiB bodies (256 held requests with 4 KiB bodies: about 40 MiB). These numbers include the test client and the test upstream in the same process, so the proxy share is smaller. Operators can lower the limit for small stacks. ## Verification - `cd server && npx vitest run src/__tests__/cloud-posthog-browser.test.ts`: 87 tests pass (5 runs in a row). - New tests: - Defaults, values from the environment, an empty value, and invalid values (`0`, `-5`, `1.5`, `1e3`, `12abc`, `abc`, `0x10`, `+8`, `65537`, `1024000`, a value larger than a safe integer). `65536` is accepted. Each invalid value keeps the default and warns once per variable. - The mount passes the configured limits to the proxy. - Per-client limit for a public address (with `trust proxy` set): a second request from the same address gets 429, a request from another address gets 200. - Shared private hop (no trusted proxy, peer is loopback): the per-client limit does not apply, and the total limit still answers 429. - A forged `X-Forwarded-For` does not select the bucket when no proxy is trusted: three held requests with the same forged public address and a per-client limit of 1 all get 200. - Request deadline: an upstream that does not answer gives 502 at the deadline and frees the slot, a body that trickles in is cut off at the deadline, and a 16 MiB response that the browser does not read is closed at the deadline. - The tests wait until the held upstream receives each request, not for a fixed time. - Total limit across public addresses, and the reported reason (`total` or `per_client`) for each 429. - The warning rate limit: one warning for the first refusal, none in the next 60 seconds, then one warning with the counts of the refusals in between, and no addresses in any warning. - Red/green: with the shared-hop rule removed (`posthogProxyClientKey` returns `req.ip`), 9 of the new tests fail. With the deadline removed, the 2 deadline tests fail. With both, all pass. - `cd server && npx tsc --noEmit -p tsconfig.json`: passes. - `pnpm verify`: exit 2, because `doc/cloud-browser-analytics.md` is a global CI input. Required CI supplies the broad coverage. - Memory numbers come from a local script that held 1024 requests through the proxy against a local upstream (Node 26, macOS). ## Risks - Higher limits let more requests use memory and sockets at once. The worst case is bounded by the total limit, and operators can lower it with `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT`. - Behind a shared private hop, one client can use all of the total limit, and other visitors then get 429. The request deadline frees each slot after at most 60 seconds, but a client that sends again can keep the limit full. Before this change, the same visitors shared a limit of 16, which one client could also fill. A separate limit for the hop would not help the visitors behind it, because one client that fills it blocks all of them. Setting `TRUST_PROXY` brings back the per-client limit. - A PostHog request that takes longer than 60 seconds now fails with 502. posthog-js bodies are small and PostHog answers in well under a second, so this does not affect normal traffic. - If an operator sets `TRUST_PROXY` to trust every hop, `req.ip` comes from the client's `X-Forwarded-For`. This was already true before this change. The total limit still applies. - The proxy is mounted only on Cloud with browser analytics on. Self-hosted installs do not 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, used through Claude Code with tool use (shell, file edits, test runs). ## 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>
352 lines
20 KiB
Markdown
352 lines
20 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. |
|
|
| `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` | `1024` | Proxy requests in flight for the whole server. See [Proxy limits](#proxy-limits). |
|
|
| `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT` | `128` | Proxy requests in flight from one public client address. See [Proxy limits](#proxy-limits). |
|
|
| `PAPERCLIP_POSTHOG_COUNTRY_HEADER` | — | Name of a request header that the platform edge sets to the visitor's two-letter country code (for example `CF-IPCountry` behind a proxied Cloudflare zone). Leave it unset unless the edge sets the header and drops a value from the client. See [Consent](#consent). |
|
|
|
|
### 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.
|
|
|
|
## Consent
|
|
|
|
Visitors in the EU, the EEA, the UK and Switzerland must agree before browser
|
|
analytics and session replay start. Everyone else keeps analytics on by
|
|
default. Both can change the choice later. Server events are not affected:
|
|
they set no cookies.
|
|
|
|
### Who must agree
|
|
|
|
1. The server decides when it knows the visitor's country. If
|
|
`PAPERCLIP_POSTHOG_COUNTRY_HEADER` names a header and the request carries a
|
|
valid two-letter code in it, `browserAnalytics.consentRequired` is `true`
|
|
for the EU and EEA countries (and their outermost regions and Svalbard), the
|
|
UK (and the Crown Dependencies and Gibraltar) and Switzerland, and `false`
|
|
for every other ISO 3166-1 alpha-2 country. The aliases `UK` and `EL` count
|
|
as `GB` and `GR`, and `EU` and `EZ` count as consent required. Any other
|
|
value (for example `XX`, `UN`, `XK` or `T1`) gives `null`.
|
|
2. Otherwise `consentRequired` is `null`, and the browser decides from its time
|
|
zone. It asks when the zone starts with
|
|
`Europe/`, is an EU, EEA or UK zone outside Europe (for example
|
|
`Atlantic/Canary`, `Atlantic/Reykjavik`, `Asia/Nicosia`, `Indian/Reunion`),
|
|
or is unknown (`UTC`, `Etc/*`, empty, or `Intl` fails). When unsure, it asks.
|
|
|
|
Both lists live in one place, `packages/shared/src/analytics-consent.ts`
|
|
(`countryRequiresAnalyticsConsent`, `timeZoneRequiresAnalyticsConsent`). The
|
|
browser's choice logic is in `ui/src/lib/analytics/consent.ts`.
|
|
|
|
Paperclip Cloud uses the time zone today. Requests reach Railway through
|
|
DNS-only Cloudflare records, so no Cloudflare country header arrives, and the
|
|
Railway edge adds no country header. Set `PAPERCLIP_POSTHOG_COUNTRY_HEADER`
|
|
only when an edge that sets and overwrites a country header is in front of
|
|
the stack. A visitor who forges the header can only change the default for
|
|
their own browser.
|
|
|
|
### What happens
|
|
|
|
| Visitor | Before a choice | Accept / switch on | Decline / switch off |
|
|
| --- | --- | --- | --- |
|
|
| Must agree, no Do Not Track or Global Privacy Control | Banner. posthog-js does not load: no `/_ph` requests, no PostHog cookies or storage. | posthog-js loads at once, without a reload. | Nothing loads. |
|
|
| Must agree, `navigator.doNotTrack === "1"` or `navigator.globalPrivacyControl === true` | No banner. Counts as Decline, also over a stored Accept. | Not possible: the settings switch is off and disabled, and says why. | Nothing loads. A running client opts out. |
|
|
| Everyone else | Loads after the page settles, as before. | — | `opt_out_capturing()` and `stopSessionRecording()` run at once. After the next load, posthog-js does not load. |
|
|
|
|
The gate calls one function, `syncProductAnalytics(config, consent)` in
|
|
`ui/src/lib/analytics/product-analytics.ts`. It starts, opts in, opts out or
|
|
cancels. Analytics stops whenever the choice is not `granted`, also when it goes back
|
|
to "ask" (another tab removes the stored choice, or a session refresh changes
|
|
`consentRequired` to `true`). If the choice changes while posthog-js is still
|
|
downloading, `init()` does not run until the choice is `granted` again.
|
|
|
|
The banner sits at the bottom of the page and does not block the board. It
|
|
says that recordings hide what the visitor types and their messages,
|
|
documents and connected accounts, but can show page names such as task
|
|
titles. It links to the privacy policy (https://paperclip.ing/privacy/).
|
|
|
|
### Where the choice is kept
|
|
|
|
The choice is per browser, in `localStorage` under
|
|
`paperclip.analyticsConsent` (`granted` or `denied`). The latest choice on
|
|
the page wins, also when storage rejects the write; it then lasts for the open
|
|
page only. Each user can change it in
|
|
**Settings → Profile → Product analytics**. The switch shows only when browser
|
|
analytics is on for the instance. Turning it on after an earlier opt-out also
|
|
clears the PostHog opt-out (`opt_in_capturing()`).
|
|
|
|
To reset the choice and see the banner again, remove the key in the browser
|
|
console: `localStorage.removeItem("paperclip.analyticsConsent")`, then reload.
|
|
|
|
## 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 the requests in
|
|
flight (429, see [Proxy limits](#proxy-limits)). 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.
|
|
|
|
### Proxy limits
|
|
|
|
Each open tab runs posthog-js. One tab sends event batches, session replay
|
|
uploads and remote settings requests, so it can have a few requests in flight
|
|
at once, and more when PostHog is slow (the proxy waits up to 30 seconds for
|
|
an answer). The proxy has two limits. When a request is over a limit, the proxy
|
|
answers 429 with `Retry-After: 1`, and posthog-js sends it again later.
|
|
|
|
| Limit | Default | Variable |
|
|
| --- | --- | --- |
|
|
| Requests in flight for the whole server | 1024 | `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` |
|
|
| Requests in flight from one public client address | 128 | `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT` |
|
|
|
|
Why these values:
|
|
|
|
- 128 per address covers about 10 people behind one office network, each with
|
|
4 tabs and 3 requests in flight per tab, with space left over.
|
|
- 1024 in total keeps memory use bounded. The proxy streams bodies, so a
|
|
request holds two sockets and the stream buffers between them, not the full
|
|
body. In a local test, 1024 held requests added about 96 MiB of resident
|
|
memory with 4 KiB bodies and about 173 MiB with 256 KiB bodies. These
|
|
numbers include the test client and the test upstream, which ran in the same
|
|
process. Most PostHog bodies are a few KiB.
|
|
|
|
A value must be a whole number from 1 to 65536 (for example `2048`). The
|
|
server reads the values at start. If a value is not valid, the server logs a
|
|
warning, uses the default, and starts as usual.
|
|
|
|
Each request has a deadline of 60 seconds from the time the proxy accepts it,
|
|
whether or not data still moves. At the deadline, the proxy stops the request
|
|
to PostHog and closes the browser request, so a slow body or a slow answer
|
|
cannot hold a slot for longer. This deadline is not configurable. The proxy
|
|
also stops a request to PostHog that has no data for 30 seconds.
|
|
|
|
#### Shared platform hop
|
|
|
|
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 (for example `100.64.x.x` on Railway). All visitors come from that one
|
|
address, so a per-client limit would hold back all of them together.
|
|
|
|
When `req.ip` is not a public address (private, carrier-grade NAT, loopback,
|
|
link-local or another reserved range, or no address), the proxy applies only
|
|
the total limit. A separate limit for the shared hop would not protect the
|
|
visitors behind it: one client that fills it blocks all of them, the same as
|
|
with the total limit. The total limit and the request deadline bound the
|
|
memory and sockets that clients can use. It does not read `X-Forwarded-For` to find the visitor for a
|
|
limit, because a client can write that header. Set `TRUST_PROXY` to the
|
|
platform's proxy range so that `req.ip` is the visitor, and the per-client
|
|
limit applies again.
|
|
|
|
#### When the limits are hit
|
|
|
|
When the proxy refuses a request at a limit, it logs the warning
|
|
`PostHog proxy refused requests at its in-flight limit` at most once a minute.
|
|
The warning has these fields, and no addresses or other visitor data:
|
|
|
|
- `refusedAtTotalLimit` and `refusedAtPerClientLimit`: the requests refused
|
|
at each limit since the last warning (the first warning counts only one).
|
|
- `inFlight`: the requests in flight when the warning was written.
|
|
- `maxInFlight` and `maxInFlightPerClient`: the limits in use.
|
|
- `sinceMs`: the time since the last warning, or `null` for the first one.
|
|
|
|
#### Tuning a fleet
|
|
|
|
Set the variables with a fleet `env_config` campaign, the same way as the
|
|
other `PAPERCLIP_POSTHOG_*` variables. Start with a canary stack. The server
|
|
reads the values at start, so a campaign that drains and restarts the stacks
|
|
applies them at once, and a campaign with `"applyOnNextDeploy": true` applies
|
|
them on the next deploy. To go back to the defaults, remove the variables.
|
|
|
|
Raise `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` when the warning shows refusals
|
|
at the total limit and the stack has memory to spare. Raise
|
|
`PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT` when it shows refusals at
|
|
the per-client limit, for example for a customer with many people behind one
|
|
address.
|
|
|
|
### Visitor location
|
|
|
|
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.
|