: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 { NextFunction, Request, Response } from 'ultimate-express'
import { JWT, PosthogJwtAudience, hasJwtKeys, makeOptionalJwt } from '~/cdp/utils/jwt-utils'
import { logger } from '~/common/utils/logger'
import { RecordingApiRole } from './types'
/**
* Authorization for recording-api routes.
*
* Each route requires a team + operation scoped JWT (audience `posthog:recording_api`) minted by
* an authorized service: the token's `team_id` must match the `:team_id` in the path and its `op`
* must match the route (read, delete or write).
*/
export type RecordingApiOp = 'read' | 'delete' | 'write'
// jsonwebtoken tolerates up to this many seconds of clock skew between minter and verifier.
const CLOCK_TOLERANCE_SECONDS = 30
export interface RecordingApiAuthOptions {
// Comma-separated keys (newest first) for zero-downtime rotation. Empty disables JWT auth (dev only).
jwtSecret: string
op: RecordingApiOp
}
function getHeader(req: Request, name: string): string | undefined {
// Node lowercases all incoming header field names, so a single lowercased lookup is sufficient.
const value = req.headers[name.toLowerCase()]
return typeof value === 'string' ? value : undefined
}
function getBearerToken(req: Request): string | undefined {
const header = getHeader(req, 'authorization')
return header && /^Bearer /i.test(header) ? header.slice('Bearer '.length) : undefined
}
// The team_id from the request URL. This middleware is mounted on a path prefix, where
// ultimate-express does not surface req.params, so the segment is read from the URL directly;
// originalUrl preserves the full path across the mount. Only canonical digits are accepted, so a
// segment like '0123', '1e3' or '0x10' yields NaN and fails the team check instead of depending on
// the route handler coercing it to the same number this does. Leading zeros are rejected too, so
// there is exactly one URL spelling of any given team.
function pathTeamId(req: Request): number {
const match = /\/api\/projects\/([^/?]+)/.exec(req.originalUrl ?? req.path ?? '')
return match && /^(0|[1-9]\d*)$/.test(match[1]) ? parseInt(match[1], 10) : NaN
}
// Pinned to HS256 to match the Python minter, and logged by failure class only, never the token.
function verifyBearer(
jwt: JWT,
token: string,
audience: PosthogJwtAudience,
options: { maxAge?: string } = {}
): Record<string, unknown> | undefined {
try {
const payload = jwt.verify(token, audience, {
algorithms: ['HS256'],
clockTolerance: CLOCK_TOLERANCE_SECONDS,
...options,
})
return payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : undefined
} catch (err) {
logger.warn('Recording API JWT verification failed', {
audience,
reason: err instanceof Error ? err.name : 'unknown',
})
return undefined
}
}
/**
* Fail closed in production: recording routes must have a JWT secret, because without one the
* middleware below lets every request through. Uses the same key parsing as the verifier so a
* malformed-but-truthy value (e.g. ',') counts as "no JWT configured".
*/
export function assertRecordingApiAuthConfigured(opts: { isProd: boolean; jwtSecret: string }): void {
if (hasJwtKeys(opts.jwtSecret || '')) {
return
}
if (opts.isProd) {
throw new Error(
'recording-api has no auth configured in production: set RECORDING_API_JWT_SECRET ' +
'(hobby installs: run bin/upgrade-hobby)'
)
}
logger.warn('recording-api has no RECORDING_API_JWT_SECRET: recording routes accept every request')
}
/**
* Each role must hold exactly the auth it serves. A process serving the browser route needs the blocks secret in
* production, since no other secret is accepted there. A public process holds no service secret, so it skips the
* internal check that would otherwise demand one.
*/
export function assertRecordingApiRoleAuthConfigured(opts: {
role: RecordingApiRole
isProd: boolean
blocksJwtSecret: string
jwtSecret: string
}): void {
if (opts.role !== 'internal' && opts.isProd && !hasJwtKeys(opts.blocksJwtSecret || '')) {
throw new Error('recording-api serving browser blocks needs RECORDING_API_BLOCKS_JWT_SECRET in production')
}
if (opts.role !== 'public') {
assertRecordingApiAuthConfigured(opts)
}
}
// The browser block route checks its own browser token, so only a process serving it exempts it from the shared secret.
export function internalApiAuthExcludedPathPrefixes(role: RecordingApiRole): string[] {
return ['/api/projects/', ...(role === 'internal' ? [] : ['/replay-blocks/'])]
}
export function createRecordingApiAuthMiddleware(options: RecordingApiAuthOptions) {
const { jwtSecret, op } = options
// Build the verifier once. Comma-separated keys give zero-downtime rotation (verify against all);
// a malformed/empty value yields no keys and disables JWT (null) rather than throwing. `|| ''`
// guards against a partial runtime config where the field is absent.
const jwt = makeOptionalJwt(jwtSecret || '')
return (req: Request, res: Response, next: NextFunction): void => {
// No JWT secret configured (local dev): allow. Production refuses to boot in this state, see
// assertRecordingApiAuthConfigured.
if (!jwt) {
next()
return
}
const bearer = getBearerToken(req)
if (bearer) {
const claims = verifyBearer(jwt, bearer, PosthogJwtAudience.RECORDING_API)
if (claims) {
const tokenTeamId = Number(claims.team_id)
const requestTeamId = pathTeamId(req)
if (!Number.isInteger(tokenTeamId) || tokenTeamId !== requestTeamId) {
logger.warn('Recording API token team mismatch', { path: req.path })
res.status(403).json({ error: 'Forbidden: token not scoped to this team' })
return
}
if (claims.op !== op) {
logger.warn('Recording API token operation mismatch', { path: req.path, expected: op })
res.status(403).json({ error: 'Forbidden: token not valid for this operation' })
return
}
next()
return
}
}
res.status(401).json({ error: 'Unauthorized' })
}
}
// A browser block token older than this is refused whatever its exp, so a leaked one stops working soon.
const REPLAY_BLOCKS_TOKEN_MAX_AGE = '2h'
// The browser block route accepts only browser tokens, a separate audience from the service tokens above.
// There is no dev bypass: without a secret, every request is refused.
export function createReplayBlocksAuthMiddleware(jwtSecret: string) {
const jwt = makeOptionalJwt(jwtSecret)
return (req: Request, res: Response, next: NextFunction): void => {
// Only a served block may be cached, so every other answer on this route says no-store.
res.set('Cache-Control', 'no-store')
const bearer = getBearerToken(req)
const claims =
jwt && bearer
? verifyBearer(jwt, bearer, PosthogJwtAudience.REPLAY_BLOCKS, { maxAge: REPLAY_BLOCKS_TOKEN_MAX_AGE })
: undefined
if (!claims || typeof claims.exp !== 'number') {
res.status(401).json({ error: 'Unauthorized' })
return
}
// String equality also requires the canonical path spelling, so /01/ never shares a cache entry with /1/.
if (
!Number.isInteger(claims.team_id) ||
String(claims.team_id) !== req.params.team_id ||
claims.session_id !== req.params.session_id ||
// The viewer is in the URL so each viewer's blocks are separate browser cache entries: after an account
// switch the new viewer's URLs never match the previous viewer's cached blocks.
typeof claims.sub !== 'string' ||
!claims.sub ||
claims.sub !== req.params.viewer
) {
res.status(403).json({ error: 'Forbidden: token not scoped to this recording' })
return
}
res.locals.replayBlocksCaller = claims.sub
res.locals.replayBlocksTier = claims.tier
next()
}
}