mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## 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>
136 lines
7.4 KiB
Markdown
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.
|