:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { createHmac } from 'crypto'
import { LRUCache } from 'lru-cache'
import { EncryptedFields } from '~/cdp/utils/encryption-utils'
import { DEVICE_SUBSCRIPTION_PREFIX, deviceSubscriptionKey } from '~/cdp/utils/push-subscription-utils'
import { PostgresRouter, PostgresUse } from '~/common/utils/db/postgres'
import { verifyPushIdentityToken } from './identity-token'
import { ProjectTokenLookup } from './project-token-lookup'
import { CaptureBillingLimitError, PushCaptureService } from './push-capture'
import { InflatedBodyTooLargeError, RawRequest, decodeRequest } from './request-decoding'
export type PushRejectionCode =
| 'method_not_allowed'
| 'request_too_large'
| 'invalid_json'
| 'missing_api_key'
| 'invalid_api_key'
| 'missing_fields'
| 'identity_verification_failed'
| 'capture_failed'
| 'capture_billing_limited'
export type PushErrorType = 'validation_error' | 'authentication_error' | 'throttled_error' | 'server_error'
/** The body shape Django's `generate_exception_response` produces, which SDKs already parse. */
export type PushErrorBody = {
type: PushErrorType
code: PushRejectionCode
detail: string
attr: null
}
export type PushSuccessBody = {
distinct_id: string
stored?: false
push_enabled?: false
reason?: string
detail?: string
}
export type PushHandlerResult = {
status: number
body: PushErrorBody | PushSuccessBody
headers?: Record<string, string>
/** Set on a rejection so the caller can log and count it with the same fields Django uses. */
rejection?: {
code: PushRejectionCode
teamId?: number
appId?: string | null
detail?: string
apiKeyFingerprint?: string
error?: unknown
}
discarded?: { teamId: number; appId: string; reason: 'no_integration' }
identityVerification?: {
mode: 'optional' | 'required'
operation: 'register' | 'unregister'
outcome: 'verified' | 'unverified'
}
}
export const MAX_BODY_BYTES = 16 * 1024
const BILLING_LIMITED_RETRY_AFTER_SECONDS = 3600
const VERIFICATION_MODE_PRECEDENCE: Record<string, number> = { disabled: 0, optional: 1, required: 2 }
type PushIntegration = { config: Record<string, any> }
/** In-process rather than Redis: the token is request-controlled and the endpoint is public, so a
* shared key per submitted value would let anyone evict real entries. */
const INVALID_TOKEN_CACHE_TTL_MS = 60_000
const INVALID_TOKEN_CACHE_SIZE = 2048
/** Keyed on the team alone: keying on the request's app_id would let one public project token mint
* unbounded entries. */
const CONFIGURED_APP_IDS_CACHE_TTL_MS = 60_000
const CONFIGURED_APP_IDS_CACHE_SIZE = 10_000
const PUSH_INTEGRATION_KINDS = ['firebase', 'apns']
export class PushSubscriptionsService {
private invalidTokens: LRUCache<string, true>
private configuredAppIdsCache: LRUCache<number, string[]>
constructor(
private projectTokens: Pick<ProjectTokenLookup, 'getTeamByToken'>,
private postgres: PostgresRouter,
private encryptedFields: EncryptedFields,
private capture: Pick<PushCaptureService, 'capture'>,
private secretKey: string,
private mirroredCapture: Pick<PushCaptureService, 'capture'> = capture
) {
this.invalidTokens = new LRUCache({ max: INVALID_TOKEN_CACHE_SIZE, ttl: INVALID_TOKEN_CACHE_TTL_MS })
this.configuredAppIdsCache = new LRUCache({
max: CONFIGURED_APP_IDS_CACHE_SIZE,
ttl: CONFIGURED_APP_IDS_CACHE_TTL_MS,
})
}
private apiKeyFingerprint(apiKey: string): string {
// Keyed with the server secret so a fingerprint cannot be precomputed for a guessed token.
return createHmac('sha256', this.secretKey).update(apiKey).digest('hex').slice(0, 16)
}
public async handle(request: RawRequest): Promise<PushHandlerResult> {
if (request.method !== 'POST' && request.method !== 'DELETE') {
return reject('method_not_allowed', 405, 'validation_error', 'Only POST and DELETE requests are supported.')
}
if (request.body.length > MAX_BODY_BYTES) {
return reject('request_too_large', 413, 'validation_error', 'Request body too large.')
}
let data: Record<string, any>
let form: URLSearchParams | undefined
try {
const decoded = decodeRequest(request)
form = decoded.form
if (typeof decoded.data !== 'object' || decoded.data === null || Array.isArray(decoded.data)) {
return reject('invalid_json', 400, 'validation_error', 'Invalid JSON body.')
}
data = decoded.data as Record<string, any>
} catch (error) {
if (error instanceof InflatedBodyTooLargeError) {
return reject('request_too_large', 413, 'validation_error', 'Request body too large.')
}
return reject('invalid_json', 400, 'validation_error', 'Invalid JSON body.')
}
const apiKey = getToken(data, form)
if (!apiKey) {
return reject(
'missing_api_key',
401,
'authentication_error',
'Project token not provided. You can find your project token in your PostHog project settings.'
)
}
const fingerprint = this.apiKeyFingerprint(apiKey)
const appIdField = typeof data.app_id === 'string' ? data.app_id : null
if (this.invalidTokens.has(fingerprint)) {
return reject('invalid_api_key', 401, 'authentication_error', 'Invalid project token.', {
appId: appIdField,
apiKeyFingerprint: fingerprint,
})
}
const team = await this.projectTokens.getTeamByToken(apiKey)
if (!team || team.api_token !== apiKey) {
this.invalidTokens.set(fingerprint, true)
return reject('invalid_api_key', 401, 'authentication_error', 'Invalid project token.', {
appId: appIdField,
apiKeyFingerprint: fingerprint,
})
}
const missingFields = (['distinct_id', 'device_token', 'app_id'] as const).filter(
(field) => !data[field] || typeof data[field] !== 'string'
)
if (missingFields.length > 0) {
// absent vs empty vs invalid separates contract drift from a client passing a bad value.
const detail = missingFields
.map((field) => {
const state = !hasOwn(data, field) ? 'absent' : data[field] === '' ? 'empty' : 'invalid'
return `${field}:${state}`
})
.join(',')
return reject(
'missing_fields',
400,
'validation_error',
`Missing required fields: ${missingFields.join(', ')}.`,
{ teamId: team.id, detail }
)
}
const distinctId = data.distinct_id as string
const deviceToken = data.device_token as string
const appId = data.app_id as string
const integrations = await this.findIntegrations(team.id, appId)
// SDKs auto-register on every app open, so a 4xx here turns the whole fleet into an error
// firehose. DELETE falls through: logout must clear a subscription stored earlier.
if (integrations.length === 0 && request.method === 'POST') {
return {
status: 200,
body: {
distinct_id: distinctId,
stored: false,
push_enabled: false,
// Without this a developer whose token goes nowhere cannot tell the difference
// from a working registration.
reason: 'no_push_channel_for_app_id',
detail:
`This project has no push channel for app_id '${appId}'. The device token was ` +
'not stored. Add a push channel whose Firebase project id or APNs bundle id ' +
'matches this app_id, and check the project the SDK is sending to.',
},
discarded: { teamId: team.id, appId, reason: 'no_integration' },
}
}
const operation = request.method === 'POST' ? 'register' : 'unregister'
const verificationMode = strictestVerificationMode(integrations)
let identityVerification: PushHandlerResult['identityVerification']
if (verificationMode === 'optional' || verificationMode === 'required') {
const identityToken = data.identity_token
const publicKeys = integrations.flatMap(
(integration) => (integration.config.push_identity_public_keys as string[] | undefined) ?? []
)
const verified =
typeof identityToken === 'string' &&
verifyPushIdentityToken({
token: identityToken,
distinctId,
appId,
publicKeys,
})
identityVerification = {
mode: verificationMode,
operation,
outcome: verified ? 'verified' : 'unverified',
}
if (!verified && verificationMode === 'required') {
return {
...reject(
'identity_verification_failed',
401,
'authentication_error',
'A valid identity token is required for this device. Your backend must sign a ' +
'short-lived token for the signed-in user with the key configured for this ' +
"channel's identity verification.",
{ teamId: team.id, appId }
),
identityVerification,
}
}
}
const propertyKey = deviceSubscriptionKey(appId, deviceToken)
// $unset of an absent property is a no-op, so DELETE is idempotent. Logout also clears the
// app-wide key: a device cannot tell whether that key holds its own token, and leaving it
// would keep a logged-out device receiving notifications.
const properties =
request.method === 'POST'
? { $set: { [propertyKey]: this.encryptedFields.encrypt(deviceToken) } }
: { $unset: [propertyKey, `${DEVICE_SUBSCRIPTION_PREFIX}${appId}`] }
try {
// An SDK told the registration was stored stops re-sending it, so a capture that did
// not happen has to surface here.
const capture = request.mirrored ? this.mirroredCapture : this.capture
await capture.capture({
token: team.api_token,
event: '$set',
distinctId,
properties: { ...properties, $process_person_profile: true },
})
} catch (error) {
const detail =
request.method === 'POST' ? 'Failed to store push subscription.' : 'Failed to remove push subscription.'
if (error instanceof CaptureBillingLimitError) {
// SDKs keep the registration or the logout for a later retry on a 429 and a 5xx, and drop it
// on any other 4xx. Retry-After holds the retries back for the rest of the session, because
// the billing limit does not lift in minutes.
return {
...reject('capture_billing_limited', 429, 'throttled_error', detail, { teamId: team.id, appId }),
headers: { 'Retry-After': String(BILLING_LIMITED_RETRY_AFTER_SECONDS) },
identityVerification,
}
}
return {
...reject('capture_failed', 500, 'server_error', detail, { teamId: team.id, appId, error }),
identityVerification,
}
}
return { status: 200, body: { distinct_id: distinctId }, identityVerification }
}
private async findIntegrations(teamId: number, appId: string): Promise<PushIntegration[]> {
// null means "don't know", so a failed lookup falls through to the real query rather than
// discarding a registration the team is entitled to.
const configured = await this.configuredAppIds(teamId)
if (configured !== null && !configured.includes(appId)) {
return []
}
return await this.fetchIntegrations(teamId, appId)
}
private async configuredAppIds(teamId: number): Promise<string[] | null> {
const cached = this.configuredAppIdsCache.get(teamId)
if (cached) {
return cached
}
try {
const { rows } = await this.postgres.query<{ kind: string; config: Record<string, any> }>(
PostgresUse.COMMON_READ,
`SELECT kind, config FROM posthog_integration WHERE team_id = $1 AND kind = ANY($2)`,
[teamId, PUSH_INTEGRATION_KINDS],
'fetchConfiguredPushAppIds'
)
const appIds = rows
.map((row) => (row.kind === 'firebase' ? row.config?.project_id : row.config?.bundle_id))
.filter((appId): appId is string => typeof appId === 'string')
this.configuredAppIdsCache.set(teamId, appIds)
return appIds
} catch {
return null
}
}
// Resolved from the app_id alone, not the device platform, so a device can register with either
// provider. Read per request: the row carries the verification policy, and a cached copy would
// keep answering `disabled` after an admin turns verification on.
private async fetchIntegrations(teamId: number, appId: string): Promise<PushIntegration[]> {
const { rows } = await this.postgres.query<{ config: Record<string, any> }>(
PostgresUse.COMMON_READ,
`SELECT config FROM posthog_integration
WHERE team_id = $1
AND ((kind = 'firebase' AND config->>'project_id' = $2)
OR (kind = 'apns' AND config->>'bundle_id' = $2))`,
[teamId, appId],
'fetchPushIntegrations'
)
return rows.map((row) => ({ config: row.config ?? {} }))
}
}
function hasOwn(data: Record<string, any>, field: string): boolean {
return Object.prototype.hasOwnProperty.call(data, field)
}
function strictestVerificationMode(integrations: PushIntegration[]): string {
let mode = 'disabled'
for (const integration of integrations) {
const candidate = (integration.config.push_identity_verification as string | undefined) ?? 'disabled'
if ((VERIFICATION_MODE_PRECEDENCE[candidate] ?? 0) > (VERIFICATION_MODE_PRECEDENCE[mode] ?? 0)) {
mode = candidate
}
}
return mode
}
/** The order Django's `get_token` uses for a body-carrying request. Query parameters are not read:
* Django only looks at those for GET, and this endpoint takes POST and DELETE. */
function getToken(data: Record<string, any>, form?: URLSearchParams): string | null {
for (const value of [form?.get('api_key'), form?.get('token')]) {
if (value) {
return value
}
}
// Django reads `properties.token` with `.get`, which raises when properties is not a mapping and
// answers the request with a 500. Treating it as absent answers 401 instead, which is what the
// client should have been told.
const properties = typeof data.properties === 'object' && data.properties !== null ? data.properties : {}
for (const value of [data.$token, data.token, data.api_key, properties.token]) {
if (typeof value === 'string' && value) {
return value
}
}
return null
}
function reject(
code: PushRejectionCode,
status: number,
type: PushErrorType,
detail: string,
extra: {
teamId?: number
appId?: string | null
detail?: string
apiKeyFingerprint?: string
error?: unknown
} = {}
): PushHandlerResult {
return {
status,
body: { type, code, detail, attr: null },
rejection: { code, ...extra },
}
}