Files
PaperClipAI/doc/cloud-browser-analytics.md
T
DottaandClaude Opus 5.5 fa8bc78d2a fix(posthog-proxy): forward the visitor IP behind a private proxy hop (#22052)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud sends browser analytics to PostHog through a
same-origin proxy at `/_ph`
> - On Cloud, the server runs behind Railway's private proxy hop and
`TRUST_PROXY` is not set
> - So the proxy forwarded the hop address (100.64.x.x) to PostHog
instead of the visitor's IP
> - PostHog could not resolve a location, and every visitor shared one
per-client in-flight bucket
> - This pull request makes the proxy use the first `X-Forwarded-For`
entry when the socket peer is private
> - The benefit is correct visitor location in PostHog web analytics and
per-visitor limits that work on Cloud

## Linked Issues or Issue Description

**What happened?**
On Paperclip Cloud staging, every browser event that reaches PostHog
through the `/_ph` proxy has `$ip` set to a Railway private address
(100.64.0.5 to 100.64.0.21). PostHog shows no country or city. All
visitors also share a few per-client in-flight buckets.

**Expected behavior**
PostHog receives the visitor's own IP, so web analytics shows visitor
location. Each visitor gets its own in-flight bucket.

**Steps to reproduce**
1. Turn on browser analytics on a Cloud stack
(`PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`) without `TRUST_PROXY`.
2. Load the board and navigate a few pages.
3. In PostHog, query `properties.$ip` for those `$pageview` events. The
value is a 100.64.x.x address and there is no geo data.

**Deployment mode**
Paperclip Cloud (authenticated, hosted on Railway).

## What Changed

- Add `posthogVisitorIp()` in `server/src/routes/posthog-proxy.ts`.
- Use it for the forwarded `X-Forwarded-For` header and for the
per-visitor in-flight limit.
- Add tests for the helper and for the forwarded header.

## Verification

- `npx vitest run src/__tests__/cloud-posthog-browser.test.ts` (server):
51 pass.
- Red check: with the old proxy code, the new tests fail (11 failures).
- Reproduced on paperclip.staging.paperclip.app: PostHog `$ip` values
were 100.64.0.5 to 100.64.0.21, with no location.

## Risks

- A client can set its own `X-Forwarded-For`. This only changes its own
analytics location and its per-visitor bucket. The global in-flight
limit still applies.
- The proxy is mounted only on Cloud with browser analytics on, so
self-hosted installs are not affected.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use.

## 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 14:18:45 -06:00

136 lines
7.4 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
Masking is deny by default. A surface that nobody marked stays masked.
- Session replay masks every input value and every text node.
`maskReplayText` in `ui/src/lib/analytics/privacy.ts` shows text only inside
elements with `ANALYTICS_UNMASK_PROPS`: sidebar items whose label is a fixed
string, and a shared `Button`, `Label`, `TabsTrigger` or `EmptyState` only
when its caller passes `analyticsChrome`. None of them opts in by default,
because they also render customer text such as agent names and titles.
- 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, even on unmasked chrome, so images record as empty boxes and
link targets (for example download links with file paths) never leave.
- `ANALYTICS_MASK_CLASS` keeps customer content masked even inside unmasked
chrome: rendered markdown (task bodies, comments, chat messages, documents),
task and issue chat threads, the comment timeline, the rich editor and the
file viewer. Text in a `contenteditable` editor is always masked.
- `ANALYTICS_NO_CAPTURE_CLASS` replaces secrets with a blank box in replays:
every password-type `Input`, environment variable values and new secret
values.
- 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 (Gmail bodies, Calendar events, Slack messages
in tasks, chat, tool results and previews) is Google user data or Slack
data. No human may read it in a replay (Google API Limited Use). It is never
inside the unmask allowlist, and autocapture records no element text at all.
`ui/src/lib/analytics/unmask-allowlist.test.ts` pins the allowlist: a new
unmask needs a reviewed entry there.
- The UI never captures an event that the server already sends
(`PAPERCLIP_EVENTS`); `product-analytics-events.test.ts` enforces this.