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

7.4 KiB

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.