feat(workflows): verify caller identity on push registration

[dmarchuk]

Problem

Follow-up to #65807, closing the one security finding we left open there: "High: untrusted callers can rebind push subscriptions."

A push device token (FCM registration token / APNs device token) is a delivery address, not a credential. FCM/APNs hand a token to any app instance, and an attacker owns their own token legitimately, so possession proves "deliver to this device" and never "this device belongs to user X". Today POST /api/push_subscriptions authenticates with the public project token, which is embedded in the app and world-readable. It identifies the project, not the person. So anyone with it can register their own device under a victim's distinct_id and receive that user's workflow push notifications (notification takeover).

This is a hard blocker before push goes GA. It doesn't affect the merged PR while push stays gated (no delivery yet), but it has to close before we turn delivery on.

Note

This is a draft of what the fix should ideally look like. The backend half is here and testable. The mobile SDK half (attaching and refreshing the token) is a separate piece owned by the SDK team, and the SDK is still in development, so we can shape its contract now.

Changes

I researched how the leading messaging platforms solve this. Braze's "SDK Authentication" is the reference design and the only one of the three I looked at that actually defends against the attack: the customer's backend (the only party that authenticated the end user) mints a short-lived signed token whose subject is the user id, and the platform verifies it. Customer.io and Brevo/WonderPush both "trust the client" - the client asserts the identity with no signature - which is exactly the hole we have now.

This PR adapts that pattern to PostHog's primitives:

• Signed identity token (push_identity_tokens.py). A short-lived JWT (HS256) signed with the project's secret API key (Team.secret_api_token), minted by the customer's backend, asserting sub = distinct_id and app_id. PostHog re-verifies it at registration. An attacker with only the public token can't forge it. Verification accepts the current or backup secret, so a key rotation doesn't reject in-flight tokens.
• Graduated per-integration enforcement on the endpoint (push_identity_verification in the Firebase/APNs integration config), mirroring Braze's staged rollout so it can be turned on without breaking existing traffic:

Mode	Behavior
disabled (default)	token ignored - current behavior, nothing breaks
optional	token verified and outcome recorded (push_subscription_identity_verification metric), but registration still succeeds - lets a customer confirm their backend mints valid tokens before enforcing
required	a registration without a valid token is rejected (401)

• A short integration doc (push_identity_tokens.md) describing the token, claims, flow, and rollout for the SDK/backend teams.

I chose symmetric HMAC over an asymmetric key pair (Braze uses RS256) because PostHog verifies its own ingestion - there's no third-party verifier that needs a public key - and the secret already ships with rotation. I also considered gating the endpoint behind a Project Secret API Key (PSAK), but PSAK auth is wired for team-scoped DRF viewsets, and this is a capture-style function view on /api/push_subscriptions. Signing keeps the SDK as the direct caller (good DX) while still requiring server-side proof.

Before - any holder of the public token can bind a victim's distinct_id:

flowchart LR
    App[App: public project token]:::phRed -->|"distinct_id + device_token"| EP["/api/push_subscriptions"]:::phYellow
    EP --> Store[(store token on person)]:::phGray
    classDef phRed fill:#f54e00,stroke:#f54e00,color:#fff;
    classDef phYellow fill:#f9bd2b,stroke:#f9bd2b,color:#000;
    classDef phGray fill:#e5e7eb,stroke:#c7ccd1,color:#000;

Loading

After (required mode) - only a backend-signed assertion can bind a distinct_id:

flowchart LR
    BE[Customer backend: authenticated user + secret key]:::phBlue -->|"mint signed identity_token"| App[App: public token]:::phRed
    App -->|"distinct_id + device_token + identity_token"| EP["/api/push_subscriptions"]:::phYellow
    EP -->|"verify sig, exp, sub==distinct_id"| Store[(store token on person)]:::phGray
    EP -->|"missing / invalid / wrong sub"| Reject[401]:::phRed
    classDef phBlue fill:#1d4aff,stroke:#1d4aff,color:#fff;
    classDef phRed fill:#f54e00,stroke:#f54e00,color:#fff;
    classDef phYellow fill:#f9bd2b,stroke:#f9bd2b,color:#000;
    classDef phGray fill:#e5e7eb,stroke:#c7ccd1,color:#000;

Loading

How did you test this code?

I (Claude) could not run the suite in this environment - no Django install available - so these tests have not run locally yet and I'm relying on CI to execute them. They are:

• test_push_identity_tokens.py (pure SimpleTestCase, no DB): the signature/claim matrix on verify_push_identity_token - valid current-secret and backup-secret tokens pass; wrong sub, wrong app_id, wrong secret, expired, malformed, and no-secret-configured all fail. Catches any regression that would let a token authorize a (distinct_id, app_id) it wasn't minted for (the core rebind guard) or wrongly reject a valid one.
• test_push_subscriptions.py (endpoint wiring guards): required mode accepts a valid token (200) and rejects both a missing token and a token minted for a different distinct_id (401, capture never called - the actual attack); optional mode stores even without a token (monitor mode must not block). These prove the mode wiring end to end, which the pure tests can't.

Invoked /writing-tests before writing them and pushed the claim matrix down to the pure SimpleTestCase per its guidance, keeping the endpoint tests as thin wiring guards.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

Included an in-repo integration doc (push_identity_tokens.md). No user-facing posthog.com docs yet - the customer-facing setup doc should land with the SDK support and the Channels UI toggle.

🤖 Agent context

Autonomy: Human-driven (agent-assisted) - directed by @dmarchuk, who should be the DRI/assignee (the create-PR tool couldn't set the assignee, so please assign yourself).

Authored by Claude (session). Skills invoked: /adding-project-secret-api-key-auth (to understand PostHog's secret-credential primitives), /writing-tests, and I followed the /improving-drf-endpoints rule for the endpoint. A research subagent gathered how Customer.io, Braze, and Brevo handle device-token-to-user binding (official docs), which is what pointed to the Braze signed-assertion pattern as the one that actually defends against this.

Decisions along the way: considered PSAK-gating the endpoint (rejected - it's a function-view capture route, not a team-scoped viewset) and an asymmetric RS256 JWT like Braze (rejected - no third-party verifier here, and HMAC off the existing secret reuses its rotation). Landed on HMAC-signed short-lived tokens with a per-integration disabled -> optional -> required rollout so it's safe to enable incrementally.

Known follow-ups, called out in the doc: SDK support for attaching/refreshing the token, a Channels UI control for the per-integration mode (today it's a config value), and clearing the binding on logout.

🤖 Generated with Claude Code

---

Generated by Claude Code

[dmarchuk]

Closing for now as per #65807 (comment)