Files
PaperClipAI/packages/shared/src/validators/access.ts
T
DottaandClaude Opus 5.5 3c460f20cc feat(analytics): ask EU, UK and Swiss visitors before Cloud browser analytics (#22186)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud can send browser product analytics and session
replays to PostHog. Self-hosted installs never do this.
> - Today, browser analytics starts for every Cloud visitor after the
page settles.
> - Visitors in the EU, the EEA, the UK and Switzerland must agree
before analytics cookies and session recordings start.
> - This pull request adds a consent step for these visitors and a
switch in the user's profile settings.
> - The benefit is that Cloud analytics follows the owner decision: ask
in Europe, keep the current behavior elsewhere, and let every user
change the choice.

## Linked Issues or Issue Description

**Subsystem affected**
Paperclip Cloud browser product analytics (`ui/src/lib/analytics`,
`ProductAnalyticsGate`, the session route, and Profile settings).

**Problem or motivation**
Browser analytics and session replay start for every Cloud visitor
without a choice. EU, EEA, UK and Swiss visitors must consent first. The
privacy policy draft also says that users can change the choice in
settings. No such setting exists.

**Proposed solution**
Ask visitors in the EU, the EEA, the UK and Switzerland with a small
bottom banner (Accept or Decline). Do not load posthog-js before they
accept. Treat Do Not Track and Global Privacy Control as a decline for
these visitors. Keep the choice in `localStorage`. Add a "Product
analytics" switch to Profile settings for every user when browser
analytics is on.

**Alternatives considered**
A server-side country from a trusted edge header. Paperclip Cloud has no
such header today: Cloudflare records are DNS-only, so no `CF-IPCountry`
arrives, and the Railway edge adds no country header. This PR supports
an optional header (`PAPERCLIP_POSTHOG_COUNTRY_HEADER`) for a future
edge, and uses the browser time zone until then.

## What Changed

- `packages/shared`: `browserAnalytics` has a new optional
`consentRequired: boolean | null`.
- `packages/shared/src/analytics-consent.ts` (new): the one region
policy. `countryRequiresAnalyticsConsent` (EU and EEA with outermost
regions and Svalbard, GB with the Crown Dependencies and Gibraltar, CH)
and `timeZoneRequiresAnalyticsConsent` (`Europe/*`, EU, EEA and UK zones
outside Europe, and unknown zones such as `UTC` or `Etc/*`). The server
and the UI both use it.
- `server`: `resolveBrowserAnalyticsConfig` sets `consentRequired` from
the header that `PAPERCLIP_POSTHOG_COUNTRY_HEADER` names. No header or
an unknown code (`XX`) gives `null`.
- `ui/src/lib/analytics/consent.ts` (new): decides `granted`, `denied`
or `ask`. Order: for a visitor who must consent, Do Not Track or Global
Privacy Control gives `denied` (also over a stored Accept); then the
choice made on this page; then the stored choice; then the region
(server value, else browser time zone). The choice is in `localStorage`
key `paperclip.analyticsConsent`. All storage access is in `try/catch`.
A cross-tab `storage` event updates the page.
- `ProductAnalyticsGate`: one effect calls `syncProductAnalytics(config,
consent)`. Shows `AnalyticsConsentBanner` when consent is `ask`. Accept
loads posthog-js at once, without a reload.
- `product-analytics.ts`: new `syncProductAnalytics`. It starts, opts
in, opts out (`opt_out_capturing()` and `stopSessionRecording()`) or
cancels a pending load. Any consent other than `granted` stops
analytics. If consent is withdrawn while the script downloads, `init()`
does not run until a later opt-in.
- `AnalyticsConsentBanner` (new): a labelled bottom region with plain
copy, a privacy policy link, and Decline and Accept buttons (shared
`Button`). The copy says that recordings hide what you type and your
messages, documents and connected accounts, but may show page names like
task titles. It does not block the page. On mobile it sits above the
bottom navigation.
- `ProductAnalyticsSetting` (new) in Profile settings: a "Product
analytics" switch (shared `ToggleSwitch`). It shows only when browser
analytics is on for the instance. When GPC or DNT blocks analytics, it
is off and disabled and says why.
- `doc/cloud-browser-analytics.md`: new Consent section (signal,
behavior table, storage key, how to reset) and the new variable.
- `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed for the
changed shared validator.

## Verification

- Red/green: the 7 new `ProductAnalyticsGate` consent tests fail against
the master gate (7 failed, 3 passed). The 5 review-fix tests (failed
write with working read, cross-tab change, decline during script
download, granted -> ask from another tab, granted -> ask from a session
refresh) fail on the first commit (5 failed, 16 passed). All pass now.
- `cd ui && npx vitest run src/lib/analytics
src/components/ProductAnalyticsGate.test.tsx
src/components/AnalyticsConsentBanner.test.tsx
src/components/ProductAnalyticsSetting.test.tsx
src/pages/ProfileSettings.test.tsx`: 267 tests pass.
- `cd server && npx vitest run
src/__tests__/cloud-posthog-browser.test.ts
src/__tests__/auth-routes.test.ts
src/__tests__/auth-session-route.test.ts`: 87 tests pass.
`packages/shared` `analytics-consent.test.ts` passes. `tsc --noEmit` for
`ui`, `server` and `packages/shared` shows no new errors.
- `pnpm verify` exits 2 (a doc is a global CI input). Required CI gives
the broad coverage.
- Real check in headless Chromium. I ran a local Cloud-managed instance
(external local PostgreSQL, `PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN`,
`PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`). `PAPERCLIP_POSTHOG_HOST` pointed
at a local capture server, not PostHog. The capture server served a
small stand-in for `array.js` that sets a `ph_*` cookie and
`localStorage` key and posts `/e/` events. I set the visitor region with
the browser time zone:

| Visitor | Result |
| --- | --- |
| `Europe/Berlin`, no choice, 18 s wait | Banner shows. 0 `/_ph`
requests. No `ph_*` cookie or storage key. |
| Then Accept (keyboard Enter) | Banner closes. `GET
/_ph/static/array.js` and `POST /_ph/e/` in 3 s. Key is `granted`. After
reload: no banner, events continue. |
| `Europe/London`, Decline, wait, reload, wait | No banner. 0 `/_ph`
requests. No `ph_*` cookie or storage key. Key is `denied`. |
| `Europe/Zurich` with Global Privacy Control | No banner. 0 `/_ph`
requests. No `ph_*` cookie or storage key. |
| `America/New_York` | No banner. posthog-js loads after the page
settles, as before. |
| Profile settings switch (US) | Shows on. Off: client is opted out at
once. On: opt-in, events continue. |

- I ran the browser check again after the review fixes, with the same
results.
- Screenshots (banner light, banner dark, mobile 375 px light and dark,
settings switch): see the PR comment.
- Cold load (local dev server, fresh browser context per run, median of
7, ms):

| Build | Time zone | FCP | DOMContentLoaded | load |
| --- | --- | --- | --- | --- |
| master | New York | 728 / 724 | 687 / 684 | 689 / 686 |
| this PR | New York | 748 / 724 | 708 / 684 | 710 / 686 |
| master | Berlin | 740 | 694 | 697 |
| this PR | Berlin | 756 / 724 | 716 / 684 | 718 / 686 |

The second round gives the same medians for master and this PR. The
first-round difference is noise. The consent code adds no request and no
load-time wait.

## Risks

- Region by time zone is approximate. It asks some visitors outside the
EU (for example `Europe/Istanbul`, or `UTC` browsers). This is the safe
direction.
- A forged country header (only when `PAPERCLIP_POSTHOG_COUNTRY_HEADER`
is set) changes only the default for that visitor's own browser.
- The choice is per browser. A user on a new browser sees the banner
again (in consent regions).
- Visitors in consent regions now send no browser analytics until they
accept. Expect fewer EU/UK sessions in PostHog.
- Self-hosted installs: no change. They get no `browserAnalytics`
config, so no banner, no switch and no load.

## Model Used

- Claude Opus 5.5 (claude-opus-5-5), Anthropic, used through Claude Code
with tool use (shell, file edits, headless browser).

## 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-18 10:52:20 -06:00

275 lines
10 KiB
TypeScript

import { z } from "zod";
import {
AGENT_ADAPTER_TYPES,
HUMAN_COMPANY_MEMBERSHIP_ROLES,
INVITE_JOIN_TYPES,
JOIN_REQUEST_STATUSES,
JOIN_REQUEST_TYPES,
PERMISSION_KEYS,
} from "../constants.js";
import { optionalAgentAdapterTypeSchema } from "../adapter-type.js";
export const createCompanyInviteSchema = z.object({
allowedJoinTypes: z.enum(INVITE_JOIN_TYPES).default("both"),
humanRole: z.enum(HUMAN_COMPANY_MEMBERSHIP_ROLES).optional().nullable(),
defaultsPayload: z.record(z.string(), z.unknown()).optional().nullable(),
agentMessage: z.string().max(4000).optional().nullable(),
});
export type CreateCompanyInvite = z.infer<typeof createCompanyInviteSchema>;
export const createOpenClawInvitePromptSchema = z.object({
agentMessage: z.string().max(4000).optional().nullable(),
});
export type CreateOpenClawInvitePrompt = z.infer<
typeof createOpenClawInvitePromptSchema
>;
export const acceptInviteSchema = z.object({
requestType: z.enum(JOIN_REQUEST_TYPES),
agentName: z.string().min(1).max(120).optional(),
adapterType: optionalAgentAdapterTypeSchema,
capabilities: z.string().max(4000).optional().nullable(),
agentDefaultsPayload: z.record(z.string(), z.unknown()).optional().nullable(),
// OpenClaw join compatibility fields accepted at top level.
responsesWebhookUrl: z.string().max(4000).optional().nullable(),
responsesWebhookMethod: z.string().max(32).optional().nullable(),
responsesWebhookHeaders: z.record(z.string(), z.unknown()).optional().nullable(),
paperclipApiUrl: z.string().max(4000).optional().nullable(),
webhookAuthHeader: z.string().max(4000).optional().nullable(),
});
export type AcceptInvite = z.infer<typeof acceptInviteSchema>;
export const listJoinRequestsQuerySchema = z.object({
status: z.enum(JOIN_REQUEST_STATUSES).optional(),
requestType: z.enum(JOIN_REQUEST_TYPES).optional(),
});
export type ListJoinRequestsQuery = z.infer<typeof listJoinRequestsQuerySchema>;
export const listCompanyInvitesQuerySchema = z.object({
state: z.enum(["active", "revoked", "accepted", "expired"]).optional(),
limit: z.coerce.number().int().min(1).max(100).optional().default(20),
offset: z.coerce.number().int().min(0).optional().default(0),
});
export type ListCompanyInvitesQuery = z.infer<typeof listCompanyInvitesQuerySchema>;
export const claimJoinRequestApiKeySchema = z.object({
claimSecret: z.string().min(16).max(256),
});
export type ClaimJoinRequestApiKey = z.infer<typeof claimJoinRequestApiKeySchema>;
export const boardCliAuthAccessLevelSchema = z.enum([
"board",
"instance_admin_required",
]);
export type BoardCliAuthAccessLevel = z.infer<typeof boardCliAuthAccessLevelSchema>;
export const createCliAuthChallengeSchema = z.object({
command: z.string().min(1).max(240),
clientName: z.string().max(120).optional().nullable(),
requestedAccess: boardCliAuthAccessLevelSchema.default("board"),
requestedCompanyId: z.string().guid().optional().nullable(),
});
export type CreateCliAuthChallenge = z.infer<typeof createCliAuthChallengeSchema>;
export const resolveCliAuthChallengeSchema = z.object({
token: z.string().min(16).max(256),
});
export type ResolveCliAuthChallenge = z.infer<typeof resolveCliAuthChallengeSchema>;
export const createBoardApiKeySchema = z.object({
name: z.string().trim().min(1).max(120).default("paperclipai cli"),
expiresAt: z.coerce.date().optional().nullable(),
requestedCompanyId: z.string().guid().optional().nullable(),
});
export type CreateBoardApiKey = z.infer<typeof createBoardApiKeySchema>;
export const updateMemberPermissionsSchema = z.object({
grants: z.array(
z.object({
permissionKey: z.enum(PERMISSION_KEYS),
scope: z.record(z.string(), z.unknown()).optional().nullable(),
}),
),
});
export type UpdateMemberPermissions = z.infer<typeof updateMemberPermissionsSchema>;
export const updateAgentPermissionGrantSchema = z.object({
permissionKey: z.enum(PERMISSION_KEYS),
enabled: z.boolean(),
}).strict();
export type UpdateAgentPermissionGrant = z.infer<typeof updateAgentPermissionGrantSchema>;
const editableMembershipStatuses = ["pending", "active", "suspended"] as const;
export const updateCompanyMemberSchema = z.object({
membershipRole: z.enum(HUMAN_COMPANY_MEMBERSHIP_ROLES).optional().nullable(),
status: z.enum(editableMembershipStatuses).optional(),
}).refine((value) => value.membershipRole !== undefined || value.status !== undefined, {
message: "membershipRole or status is required",
});
export type UpdateCompanyMember = z.infer<typeof updateCompanyMemberSchema>;
export const updateCompanyMemberWithPermissionsSchema = z.object({
membershipRole: z.enum(HUMAN_COMPANY_MEMBERSHIP_ROLES).optional().nullable(),
status: z.enum(editableMembershipStatuses).optional(),
grants: updateMemberPermissionsSchema.shape.grants.default([]),
}).refine((value) => value.membershipRole !== undefined || value.status !== undefined, {
message: "membershipRole or status is required",
});
export type UpdateCompanyMemberWithPermissions = z.infer<typeof updateCompanyMemberWithPermissionsSchema>;
export const archiveCompanyMemberSchema = z.object({
reassignment: z
.object({
assigneeAgentId: z.string().guid().optional().nullable(),
assigneeUserId: z.string().guid().optional().nullable(),
})
.optional()
.nullable(),
}).superRefine((value, ctx) => {
if (value.reassignment?.assigneeAgentId && value.reassignment.assigneeUserId) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Choose either an agent or user reassignment target",
path: ["reassignment"],
});
}
});
export type ArchiveCompanyMember = z.infer<typeof archiveCompanyMemberSchema>;
export const updateUserCompanyAccessSchema = z.object({
companyIds: z.array(z.string().guid()).default([]),
});
export type UpdateUserCompanyAccess = z.infer<typeof updateUserCompanyAccessSchema>;
export const searchAdminUsersQuerySchema = z.object({
query: z.string().trim().max(120).optional().default(""),
});
export type SearchAdminUsersQuery = z.infer<typeof searchAdminUsersQuerySchema>;
const profileImageAssetPathPattern = /^\/api\/assets\/[^/?#]+\/content(?:\?[^#]*)?(?:#.*)?$/;
function isValidProfileImage(value: string): boolean {
if (profileImageAssetPathPattern.test(value)) return true;
try {
const url = new URL(value);
return url.protocol === "https:" || url.protocol === "http:";
} catch {
return false;
}
}
const profileImageSchema = z
.string()
.trim()
.min(1)
.max(4000)
.refine(isValidProfileImage, { message: "Invalid profile image URL" });
export const currentUserProfileSchema = z.object({
id: z.string().min(1),
email: z.preprocess(
(v) => (typeof v === "string" && v.trim() === "" ? null : v),
z.string().email().nullable(),
),
name: z.preprocess(
(v) => (typeof v === "string" && v.trim() === "" ? null : v),
z.string().min(1).max(120).nullable(),
),
image: profileImageSchema.nullable(),
});
export type CurrentUserProfile = z.infer<typeof currentUserProfileSchema>;
/**
* Browser performance tracing settings for a hosted Paperclip Cloud instance.
* The server sends a value only when the instance is cloud managed and an
* operator configured an endpoint; see `doc/browser-performance-tracing.md`.
* `ingestKey` is a Honeycomb ingest-only key (or null for a collector that
* needs no key); it is never a configuration key.
*/
export const browserTracingConfigSchema = z.object({
tracesUrl: z.string().url(),
ingestKey: z.string().min(1).nullable(),
serviceName: z.string().min(1),
environment: z.string().min(1).nullable(),
sampleRate: z.number().gt(0).max(1),
});
export type BrowserTracingConfig = z.infer<typeof browserTracingConfigSchema>;
/**
* Browser product analytics (PostHog) settings for a hosted Paperclip Cloud
* instance. The server sends a value only when the instance is cloud managed,
* `PAPERCLIP_POSTHOG_PROJECT_TOKEN` and `PAPERCLIP_CLOUD_STACK_ID` are set, and
* `PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`. `token` is a PostHog project token,
* which is public by design (it can only send events). `apiHost` is the
* same-origin reverse proxy path, and `uiHost` is the PostHog app host for
* links, or null when it is not a PostHog Cloud host. `environment` is
* always set, so every browser event carries it.
*/
export const browserAnalyticsConfigSchema = z.object({
token: z.string().min(1),
apiHost: z.string().min(1),
uiHost: z.string().url().nullable(),
environment: z.string().min(1),
stackId: z.string().min(1),
replayEnabled: z.boolean(),
consentRequired: z.boolean().nullable().optional(),
});
export type BrowserAnalyticsConfig = z.infer<typeof browserAnalyticsConfigSchema>;
export const authSessionSchema = z.object({
session: z.object({
id: z.string().min(1),
userId: z.string().min(1),
}),
user: currentUserProfileSchema,
// The front-end Sentry DSN for the current instance, or `null` when the
// operator has set neither `SENTRY_DSN_FRONTEND` nor the legacy
// `SENTRY_DSN`. Required, not optional: a missing value must fail the
// response schema instead of silently disabling browser error
// monitoring. The browser reads this value to open its own Sentry gate —
// see `ui/src/lib/sentry.ts`.
sentryDsn: z.string().min(1).nullable(),
// Optional for browser/server version skew; null leaves the SDK default.
sentryEnvironment: z.string().nullable().optional(),
// Null or absent leaves browser performance tracing off. Optional for
// browser/server version skew.
browserTracing: browserTracingConfigSchema.nullable().optional(),
// Null or absent leaves browser product analytics off; the browser then never
// downloads posthog-js. Optional for browser/server version skew.
browserAnalytics: browserAnalyticsConfigSchema.nullable().optional(),
});
export type AuthSession = z.infer<typeof authSessionSchema>;
export const updateCurrentUserProfileSchema = z.object({
name: z.string().trim().min(1).max(120),
image: z
.union([profileImageSchema, z.literal(""), z.null()])
.optional()
.transform((value) => value === "" ? null : value),
});
export type UpdateCurrentUserProfile = z.infer<typeof updateCurrentUserProfileSchema>;