## 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>
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:
- The instance is cloud managed (
isCloudManagedInstance). PAPERCLIP_POSTHOG_PROJECT_TOKENandPAPERCLIP_CLOUD_STACK_IDare set.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.userIdis the authenticated actor's user id verbatim (req.actor.userId, for examplepaperclip-id:...), the same id server events use asdistinct_id. Email and name are person properties only, never event properties. group("workspace", stackId).- Every event carries
deployment_source: "cloud"andenvironment. WithoutPAPERCLIP_POSTHOG_ENVIRONMENT,environmentisstagingon a*.staging.paperclip.apphost andproductionotherwise. - Sign-out:
reset(), called byuseSignOutbefore 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.
maskReplayTextinui/src/lib/analytics/privacy.tsshows text only inside elements withANALYTICS_UNMASK_PROPS: sidebar items whose label is a fixed string, and a sharedButton,Label,TabsTriggerorEmptyStateonly when its caller passesanalyticsChrome. 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_CLASSkeeps 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 acontenteditableeditor is always masked.ANALYTICS_NO_CAPTURE_CLASSreplaces secrets with a blank box in replays: every password-typeInput, 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 secretkey=valuepairs redacted. - Events never carry the page title (
before_senddropstitle), 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.tspins 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.tsenforces this.