Skip to content

: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.

feat(replay): add a recording-api route that encrypts blocks for a new session (#120180)

Tue Haulund17f77e6d1cb4
diff --git a/nodejs/src/session-replay/recording-api/auth.test.ts b/nodejs/src/session-replay/recording-api/auth.test.ts
index db105dca2b83..311b69ef3572 100644
--- a/nodejs/src/session-replay/recording-api/auth.test.ts
+++ b/nodejs/src/session-replay/recording-api/auth.test.ts
@@ -201,6 +201,33 @@ describe('createRecordingApiAuthMiddleware', () => {
})
})
+ describe('routes that require a JWT', () => {
+ it.each([
+ ['the legacy secret', { jwtSecret: JWT_SECRET }, { 'x-internal-api-secret': LEGACY_SECRET }],
+ [
+ 'any request when no JWT key is configured',
+ { jwtSecret: '' },
+ { 'x-internal-api-secret': LEGACY_SECRET },
+ ],
+ ])('reject %s', (_, opts, headers) => {
+ const { res, next } = run(
+ { ...opts, op: 'write', allowLegacySecret: true, requireJwt: true },
+ mockRequest('123', headers)
+ )
+ expect(next).not.toHaveBeenCalled()
+ expect(res.status).toHaveBeenCalledWith(401)
+ })
+
+ it('accept a scoped write token', () => {
+ const { res, next } = run(
+ { op: 'write', allowLegacySecret: true, requireJwt: true },
+ mockRequest('123', bearer(mintToken({ team_id: 123, op: 'write' })))
+ )
+ expect(next).toHaveBeenCalled()
+ expect(res.status).not.toHaveBeenCalled()
+ })
+ })
+
describe('progressive rollout (legacy secret before JWT is enabled)', () => {
it('requires the legacy secret when no JWT secret is configured', () => {
const req = mockRequest('123', { 'x-internal-api-secret': LEGACY_SECRET })
diff --git a/nodejs/src/session-replay/recording-api/auth.ts b/nodejs/src/session-replay/recording-api/auth.ts
index 95ba814f013c..c8f1e1f007e9 100644
--- a/nodejs/src/session-replay/recording-api/auth.ts
+++ b/nodejs/src/session-replay/recording-api/auth.ts
@@ -10,11 +10,11 @@ import { logger } from '~/common/utils/logger'
*
* 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 vs delete). During migration the legacy `X-Internal-Api-Secret` is
+ * must match the route (read, delete or write). During migration the legacy `X-Internal-Api-Secret` is
* accepted as a fallback while `allowLegacySecret` is true; the final cutover flips that flag off.
*/
-export type RecordingApiOp = 'read' | 'delete'
+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
@@ -25,6 +25,8 @@ export interface RecordingApiAuthOptions {
legacySecret: string
allowLegacySecret: boolean
op: RecordingApiOp
+ // Accept only a scoped JWT, and refuse every request when no JWT key is configured.
+ requireJwt?: boolean
}
function getHeader(req: Request, name: string): string | undefined {
@@ -80,14 +82,19 @@ export function assertRecordingApiAuthConfigured(opts: {
}
export function createRecordingApiAuthMiddleware(options: RecordingApiAuthOptions) {
- const { jwtSecret, legacySecret, allowLegacySecret, op } = options
+ const { jwtSecret, legacySecret, allowLegacySecret, op, requireJwt = false } = 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 || '')
- const legacyEnabled = allowLegacySecret && !!legacySecret
+ const legacyEnabled = allowLegacySecret && !!legacySecret && !requireJwt
return (req: Request, res: Response, next: NextFunction): void => {
+ if (requireJwt && !jwt) {
+ res.status(401).json({ error: 'Unauthorized' })
+ return
+ }
+
// Nothing configured at all (local dev): allow. In every other case some auth is required —
// before the JWT scheme is enabled in an environment, the legacy secret still protects it.
if (!jwt && !legacyEnabled) {
diff --git a/nodejs/src/session-replay/recording-api/recording-api.test.ts b/nodejs/src/session-replay/recording-api/recording-api.test.ts
index 84ee7b07cbab..7a8c21505785 100644
--- a/nodejs/src/session-replay/recording-api/recording-api.test.ts
+++ b/nodejs/src/session-replay/recording-api/recording-api.test.ts
@@ -3,9 +3,10 @@ import { Server } from 'http'
import supertest from 'supertest'
import express from 'ultimate-express'
+import { JWT, PosthogJwtAudience } from '~/cdp/utils/jwt-utils'
import { IngestionOutputs } from '~/common/outputs/ingestion-outputs'
import { PostgresRouter } from '~/common/utils/db/postgres'
-import { getBlockDecryptor } from '~/ingestion/pipelines/sessionreplay/shared/crypto'
+import { getBlockDecryptor, getBlockEncryptor } from '~/ingestion/pipelines/sessionreplay/shared/crypto'
import { getKeyStore } from '~/ingestion/pipelines/sessionreplay/shared/keystore'
import { ReplayEventsOutput, SessionFeaturesOutput } from '~/ingestion/pipelines/sessionreplay/shared/outputs'
@@ -44,6 +45,7 @@ jest.mock('~/ingestion/pipelines/sessionreplay/shared/keystore/cache', () => ({
jest.mock('~/ingestion/pipelines/sessionreplay/shared/crypto', () => ({
getBlockDecryptor: jest.fn(),
+ getBlockEncryptor: jest.fn(),
}))
jest.mock('~/common/utils/db/redis', () => ({
@@ -102,9 +104,11 @@ describe('RecordingApi', () => {
getBlock: jest.fn(),
listBlocks: jest.fn(),
deleteRecordings: jest.fn(),
+ encryptBlocks: jest.fn(),
} as unknown as jest.Mocked<RecordingService>
;(getKeyStore as jest.Mock).mockReturnValue(mockKeyStore)
;(getBlockDecryptor as jest.Mock).mockReturnValue(mockDecryptor)
+ ;(getBlockEncryptor as jest.Mock).mockReturnValue({ start: jest.fn().mockResolvedValue(undefined) })
;(RecordingService as unknown as jest.Mock).mockImplementation(() => mockService)
})
@@ -614,4 +618,79 @@ describe('RecordingApi', () => {
})
})
})
+
+ describe('encryptBlocks endpoint', () => {
+ const JWT_SECRET = 'recording-api-test-secret'
+ let app: express.Application
+ let server: Server
+
+ const bearer = (op: string, teamId = 1): string =>
+ `Bearer ${new JWT(JWT_SECRET).sign({ team_id: teamId, op }, PosthogJwtAudience.RECORDING_API, { expiresIn: '5m' })}`
+ const body = { blocks: [Buffer.from('block').toString('base64')], retention_days: 365 }
+
+ beforeEach(async () => {
+ const recordingApi = new RecordingApi(
+ {
+ RECORDING_API_JWT_SECRET: JWT_SECRET,
+ RECORDING_API_ALLOW_LEGACY_SECRET: false,
+ } as RecordingApiConfig,
+ mockPostgres,
+ mockOutputs
+ )
+ await recordingApi.start(mockService)
+ app = express()
+ app.use(express.json())
+ app.use('/', recordingApi.router())
+ server = app.listen(0, () => {})
+ mockService.encryptBlocks.mockResolvedValue({ ok: true, blocks: [Buffer.from('sealed')] })
+ mockService.deleteRecordings.mockResolvedValue([])
+ })
+
+ afterEach(() => {
+ server.close()
+ })
+
+ it.each([
+ ['encrypt', 'write', 200],
+ ['encrypt', 'delete', 403],
+ ['encrypt', 'read', 403],
+ ['delete', 'write', 403],
+ ])('%s route with a %s token returns %s', async (route, op, expectedStatus) => {
+ const req =
+ route === 'encrypt'
+ ? supertest(app).post('/api/projects/1/recordings/session-1/encrypt').send(body)
+ : supertest(app)
+ .post('/api/projects/1/recordings/delete')
+ .send({ session_ids: ['session-1'], deleted_by: '[email protected]' })
+
+ const res = await req.set('Authorization', bearer(op))
+
+ expect(res.status).toBe(expectedStatus)
+ })
+
+ it.each([
+ [
+ { ok: true, blocks: [Buffer.from('sealed')] },
+ 200,
+ { blocks: [Buffer.from('sealed').toString('base64')] },
+ ],
+ [{ ok: false, error: 'recording_exists' }, 409, { error: 'recording_exists' }],
+ [
+ { ok: false, error: 'deleted', deletedAt: 1700000000, deletedBy: '[email protected]' },
+ 410,
+ { error: 'recording_deleted', deleted_at: 1700000000, deleted_by: '[email protected]' },
+ ],
+ ])('maps service result %j to %s', async (result, expectedStatus, expectedBody) => {
+ mockService.encryptBlocks.mockResolvedValue(result as any)
+
+ const res = await supertest(app)
+ .post('/api/projects/1/recordings/session-1/encrypt')
+ .set('Authorization', bearer('write'))
+ .send(body)
+
+ expect(res.status).toBe(expectedStatus)
+ expect(res.body).toEqual(expectedBody)
+ expect(mockService.encryptBlocks).toHaveBeenCalledWith('session-1', 1, [Buffer.from('block')], 365)
+ })
+ })
})
diff --git a/nodejs/src/session-replay/recording-api/recording-api.ts b/nodejs/src/session-replay/recording-api/recording-api.ts
index 69ee72c7ee87..af0548204774 100644
--- a/nodejs/src/session-replay/recording-api/recording-api.ts
+++ b/nodejs/src/session-replay/recording-api/recording-api.ts
@@ -8,7 +8,7 @@ import { PostgresRouter } from '~/common/utils/db/postgres'
import { createRedisPoolFromConfig } from '~/common/utils/db/redis'
import { logger, serializeError } from '~/common/utils/logger'
import { captureException } from '~/common/utils/posthog'
-import { getBlockDecryptor } from '~/ingestion/pipelines/sessionreplay/shared/crypto'
+import { getBlockDecryptor, getBlockEncryptor } from '~/ingestion/pipelines/sessionreplay/shared/crypto'
import { SessionFeatureStore } from '~/ingestion/pipelines/sessionreplay/shared/features/session-feature-store'
import { getKeyStore } from '~/ingestion/pipelines/sessionreplay/shared/keystore'
import { RedisCachedKeyStore } from '~/ingestion/pipelines/sessionreplay/shared/keystore/cache'
@@ -16,11 +16,17 @@ import { SessionMetadataStore } from '~/ingestion/pipelines/sessionreplay/shared
import { ReplayEventsOutput, SessionFeaturesOutput } from '~/ingestion/pipelines/sessionreplay/shared/outputs'
import { HealthCheckResult, HealthCheckResultError, HealthCheckResultOk, PluginServerService, RedisPool } from '~/types'
-import { createRecordingApiAuthMiddleware } from './auth'
+import { RecordingApiOp, createRecordingApiAuthMiddleware } from './auth'
import { ClickHouseCredential } from './clickhouse-credential'
import { RecordingService } from './recording-service'
-import { DeleteRecordingsBodySchema, GetBlockQuerySchema, RecordingParamsSchema, TeamParamsSchema } from './schemas'
-import { KeyStore, RecordingApiConfig, RecordingDecryptor } from './types'
+import {
+ DeleteRecordingsBodySchema,
+ EncryptBlocksBodySchema,
+ GetBlockQuerySchema,
+ RecordingParamsSchema,
+ TeamParamsSchema,
+} from './schemas'
+import { KeyStore, RecordingApiConfig, RecordingDecryptor, RecordingEncryptor } from './types'
export class RecordingApi {
private s3Client: S3Client | null = null
@@ -28,6 +34,7 @@ export class RecordingApi {
private s3Prefix: string | null = null
private keyStore: KeyStore | null = null
private decryptor: RecordingDecryptor | null = null
+ private encryptor: RecordingEncryptor | null = null
private redisPool: RedisPool | null = null
private clickhouseClient: ClickHouseClient | null = null
private recordingService: RecordingService | null = null
@@ -107,6 +114,9 @@ export class RecordingApi {
this.decryptor = getBlockDecryptor(this.keyStore)
await this.decryptor.start()
+ this.encryptor = getBlockEncryptor(this.keyStore)
+ await this.encryptor.start()
+
const metadataStore = new SessionMetadataStore(this.outputs)
const featureStore = new SessionFeatureStore(this.outputs)
@@ -136,7 +146,8 @@ export class RecordingApi {
metadataStore,
featureStore,
this.postgres,
- { client: this.clickhouseClient, credential: ClickHouseCredential.fromConfig(this.config) }
+ { client: this.clickhouseClient, credential: ClickHouseCredential.fromConfig(this.config) },
+ this.encryptor
)
logger.info('[RecordingApi] Started successfully')
@@ -166,6 +177,9 @@ export class RecordingApi {
if (!this.decryptor) {
uninitializedComponents.push('decryptor')
}
+ if (!this.encryptor) {
+ uninitializedComponents.push('encryptor')
+ }
if (uninitializedComponents.length > 0) {
return new HealthCheckResultError('Components not initialized', {
@@ -188,15 +202,23 @@ export class RecordingApi {
const blocksPath = '/api/projects/:team_id/recordings/:session_id/blocks'
- const auth = (op: 'read' | 'delete') =>
+ const encryptPath = '/api/projects/:team_id/recordings/:session_id/encrypt'
+
+ const auth = (op: RecordingApiOp) =>
createRecordingApiAuthMiddleware({
jwtSecret: this.config.RECORDING_API_JWT_SECRET,
legacySecret: this.config.INTERNAL_API_SECRET,
allowLegacySecret: this.config.RECORDING_API_ALLOW_LEGACY_SECRET,
op,
+ // Key minting is new, so it never inherits the fleet-wide legacy secret.
+ requireJwt: op === 'write',
})
const readAuth = auth('read')
const deleteAuth = auth('delete')
+ const writeAuth = auth('write')
+
+ // Registered before the prefix middleware so its own write scope applies instead of the delete scope.
+ router.post(encryptPath, writeAuth, asyncHandler(this.encryptBlocks))
// Mounted on the whole '/api/projects' prefix, matching what the shared-secret middleware
// exempts, rather than on the recording routes alone. Anything under the prefix that this
@@ -313,6 +335,62 @@ export class RecordingApi {
}
}
+ private encryptBlocks = async (req: express.Request, res: express.Response): Promise<void> => {
+ const paramsResult = RecordingParamsSchema.safeParse(req.params)
+ if (!paramsResult.success) {
+ res.status(400).json({ error: paramsResult.error.issues[0].message })
+ return
+ }
+
+ const bodyResult = EncryptBlocksBodySchema.safeParse(req.body)
+ if (!bodyResult.success) {
+ res.status(400).json({ error: bodyResult.error.issues[0].message })
+ return
+ }
+
+ if (!this.recordingService) {
+ res.status(503).json({ error: 'Service not initialized' })
+ return
+ }
+
+ const { team_id: teamId, session_id: sessionId } = paramsResult.data
+ const { blocks, retention_days: retentionDays } = bodyResult.data
+
+ try {
+ const result = await this.recordingService.encryptBlocks(
+ sessionId,
+ teamId,
+ blocks.map((b) => Buffer.from(b, 'base64')),
+ retentionDays
+ )
+ if (!result.ok) {
+ if (result.error === 'recording_exists') {
+ res.status(409).json({ error: 'recording_exists' })
+ return
+ }
+ if (result.error === 'key_unavailable') {
+ res.status(503).json({ error: 'key_unavailable' })
+ return
+ }
+ res.status(410).json({
+ error: 'recording_deleted',
+ deleted_at: result.deletedAt,
+ deleted_by: result.deletedBy,
+ })
+ return
+ }
+ res.json({ blocks: result.blocks.map((b) => b.toString('base64')) })
+ } catch (error) {
+ logger.error('[RecordingApi] Error encrypting blocks', {
+ error: serializeError(error),
+ teamId,
+ sessionId,
+ })
+ captureException(error)
+ res.status(500).json({ error: 'Failed to encrypt blocks' })
+ }
+ }
+
private deleteRecordings = async (req: express.Request, res: express.Response): Promise<void> => {
const paramsResult = TeamParamsSchema.safeParse(req.params)
if (!paramsResult.success) {
diff --git a/nodejs/src/session-replay/recording-api/recording-service.test.ts b/nodejs/src/session-replay/recording-api/recording-service.test.ts
index a28b5ff73b25..6638fb937255 100644
--- a/nodejs/src/session-replay/recording-api/recording-service.test.ts
+++ b/nodejs/src/session-replay/recording-api/recording-service.test.ts
@@ -1,11 +1,14 @@
import { NoSuchKey, S3Client } from '@aws-sdk/client-s3'
import { ClickHouseClient } from '@clickhouse/client'
+import sodium from 'libsodium-wrappers'
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import snappy from 'snappy'
import { PostgresRouter } from '~/common/utils/db/postgres'
+import * as envUtils from '~/common/utils/env-utils'
+import { SodiumRecordingDecryptor, SodiumRecordingEncryptor } from '~/ingestion/pipelines/sessionreplay/shared/crypto'
import { SessionFeatureStore } from '~/ingestion/pipelines/sessionreplay/shared/features/session-feature-store'
import { SessionMetadataStore } from '~/ingestion/pipelines/sessionreplay/shared/metadata/session-metadata-store'
@@ -70,7 +73,8 @@ describe('RecordingService', () => {
mockMetadataStore,
mockFeatureStore,
mockPostgres,
- { client: mockClickhouse, credential: new ClickHouseCredential('recording_api', 'static', '') }
+ { client: mockClickhouse, credential: new ClickHouseCredential('recording_api', 'static', '') },
+ new SodiumRecordingEncryptor(mockKeyStore)
)
})
@@ -746,4 +750,94 @@ describe('RecordingService', () => {
expect(mockPostgres.query).toHaveBeenCalled()
})
})
+
+ describe('encryptBlocks', () => {
+ const plaintextKey = Buffer.alloc(32, 7)
+ const ciphertextKey = {
+ plaintextKey,
+ encryptedKey: Buffer.from('wrapped'),
+ sessionState: 'ciphertext' as const,
+ }
+ const cleartextKey = {
+ plaintextKey: Buffer.alloc(0),
+ encryptedKey: Buffer.alloc(0),
+ sessionState: 'cleartext' as const,
+ }
+
+ beforeAll(async () => {
+ await sodium.ready
+ })
+
+ beforeEach(() => {
+ mockKeyStore.generateKey.mockResolvedValue(ciphertextKey)
+ })
+
+ const mockRecordingExists = (exists: boolean): void => {
+ mockClickhouse.query.mockResolvedValue({
+ json: jest.fn().mockResolvedValue(exists ? [{ '1': 1 }] : []),
+ } as any)
+ }
+
+ it.each([
+ ['an existing key', ciphertextKey, 0],
+ ['no key and no recording yet', cleartextKey, 1],
+ ])('encrypts with %s so the decryptor can read it back', async (_, existingKey, expectedKeyMints) => {
+ mockKeyStore.getKey.mockResolvedValue(existingKey)
+ mockRecordingExists(false)
+
+ const result = await service.encryptBlocks('session-1', 1, [Buffer.from('block-a'), Buffer.from('b')], 365)
+
+ expect(result.ok).toBe(true)
+ const decryptor = new SodiumRecordingDecryptor(mockKeyStore)
+ const decrypted = (result as { blocks: Buffer[] }).blocks.map(
+ (b) => decryptor.decryptBlockWithKey('session-1', 1, b, ciphertextKey).data
+ )
+ expect(decrypted).toEqual([Buffer.from('block-a'), Buffer.from('b')])
+ expect(mockKeyStore.generateKey).toHaveBeenCalledTimes(expectedKeyMints)
+ })
+
+ it.each([
+ ['a recording that predates encryption', cleartextKey],
+ ['an ingested encrypted recording', ciphertextKey],
+ ])('refuses to encrypt into %s', async (_, existingKey) => {
+ mockKeyStore.getKey.mockResolvedValue(existingKey)
+ mockRecordingExists(true)
+
+ const result = await service.encryptBlocks('session-1', 1, [Buffer.from('block')], 365)
+
+ expect(result).toEqual({ ok: false, error: 'recording_exists' })
+ expect(mockKeyStore.generateKey).not.toHaveBeenCalled()
+ })
+
+ it('refuses to return plaintext when a cloud key mint reads back no key', async () => {
+ const isCloud = jest.spyOn(envUtils, 'isCloud').mockReturnValue(true)
+ mockRecordingExists(false)
+ mockKeyStore.getKey.mockResolvedValue(cleartextKey)
+ mockKeyStore.generateKey.mockResolvedValue(cleartextKey)
+
+ const result = await service.encryptBlocks('session-1', 1, [Buffer.from('block')], 365)
+
+ expect(result).toEqual({ ok: false, error: 'key_unavailable' })
+ isCloud.mockRestore()
+ })
+
+ it('returns deleted when the session key was shredded', async () => {
+ mockRecordingExists(false)
+ mockKeyStore.getKey.mockResolvedValue({
+ ...cleartextKey,
+ sessionState: 'deleted',
+ deletedAt: 1700000000,
+ deletedBy: '[email protected]',
+ })
+
+ const result = await service.encryptBlocks('session-1', 1, [Buffer.from('block')], 365)
+
+ expect(result).toEqual({
+ ok: false,
+ error: 'deleted',
+ deletedAt: 1700000000,
+ deletedBy: '[email protected]',
+ })
+ })
+ })
})
diff --git a/nodejs/src/session-replay/recording-api/recording-service.ts b/nodejs/src/session-replay/recording-api/recording-service.ts
index a801afa0c51e..e8970e118490 100644
--- a/nodejs/src/session-replay/recording-api/recording-service.ts
+++ b/nodejs/src/session-replay/recording-api/recording-service.ts
@@ -3,6 +3,7 @@ import { ClickHouseClient } from '@clickhouse/client'
import snappy from 'snappy'
import { PostgresRouter, PostgresUse } from '~/common/utils/db/postgres'
+import { isCloud } from '~/common/utils/env-utils'
import { logger, serializeError } from '~/common/utils/logger'
import { ValidRetentionPeriods } from '~/ingestion/pipelines/sessionreplay/shared/constants'
import { SessionFeatureStore } from '~/ingestion/pipelines/sessionreplay/shared/features/session-feature-store'
@@ -11,7 +12,7 @@ import { SessionMetadataStore } from '~/ingestion/pipelines/sessionreplay/shared
import { ClickHouseCredential } from './clickhouse-credential'
import { RecordingApiMetrics } from './metrics'
-import { KeyStore, RecordingBlock, RecordingDecryptor, SessionKeyDeletedError } from './types'
+import { KeyStore, RecordingBlock, RecordingDecryptor, RecordingEncryptor, SessionKeyDeletedError } from './types'
export interface GetBlockParams {
sessionId: string
@@ -22,10 +23,15 @@ export interface GetBlockParams {
decompress?: boolean
}
-export type GetBlockResult =
- | { ok: true; data: Buffer }
- | { ok: false; error: 'not_found' }
- | { ok: false; error: 'deleted'; deletedAt?: number; deletedBy: string }
+export type RecordingDeletedResult = { ok: false; error: 'deleted'; deletedAt?: number; deletedBy: string }
+
+export type GetBlockResult = { ok: true; data: Buffer } | { ok: false; error: 'not_found' } | RecordingDeletedResult
+
+export type EncryptBlocksResult =
+ | { ok: true; blocks: Buffer[] }
+ | { ok: false; error: 'recording_exists' }
+ | { ok: false; error: 'key_unavailable' }
+ | RecordingDeletedResult
export type DeleteRecordingResult =
| { sessionId: string; ok: true; status: 'deleted'; deletedAt: number; deletedBy: string }
@@ -49,9 +55,48 @@ export class RecordingService {
private metadataStore?: SessionMetadataStore,
private featureStore?: SessionFeatureStore,
private postgres?: PostgresRouter,
- private clickhouse?: { client: ClickHouseClient; credential: ClickHouseCredential }
+ private clickhouse?: { client: ClickHouseClient; credential: ClickHouseCredential },
+ private encryptor?: RecordingEncryptor
) {}
+ // Lets a caller write a copied recording without its own access to KMS or the key table.
+ async encryptBlocks(
+ sessionId: string,
+ teamId: number,
+ blocks: Buffer[],
+ retentionDays: number
+ ): Promise<EncryptBlocksResult> {
+ const encryptor = this.encryptor
+ if (!encryptor) {
+ throw new Error('Encryptor not initialized')
+ }
+ // Encrypting only for sessions with no stored recording keeps this route from touching ingested data,
+ // and stops a new key from breaking the plaintext blocks of a pre-encryption recording.
+ if (await this.recordingExists(sessionId, teamId)) {
+ return { ok: false, error: 'recording_exists' }
+ }
+ let sessionKey = await this.keyStore.getKey(sessionId, teamId)
+ if (sessionKey.sessionState === 'cleartext') {
+ sessionKey = await this.keyStore.generateKey(sessionId, teamId, retentionDays)
+ }
+ // A lost race on the conditional key write can read back no key, and encrypting with it returns plaintext.
+ if (sessionKey.sessionState === 'cleartext' && isCloud()) {
+ return { ok: false, error: 'key_unavailable' }
+ }
+ if (sessionKey.sessionState === 'deleted') {
+ return {
+ ok: false,
+ error: 'deleted',
+ deletedAt: sessionKey.deletedAt,
+ deletedBy: sessionKey.deletedBy ?? '',
+ }
+ }
+ return {
+ ok: true,
+ blocks: blocks.map((block) => encryptor.encryptBlockWithKey(sessionId, teamId, block, sessionKey).data),
+ }
+ }
+
validateS3Key(key: string): boolean {
const pattern = `^${this.s3Prefix}/(${ValidRetentionPeriods.join('|')})/\\d+-[0-9a-f]{16}$`
return new RegExp(pattern).test(key)
@@ -164,6 +209,40 @@ export class RecordingService {
}
}
+ private async recordingExists(sessionId: string, teamId: number): Promise<boolean> {
+ if (!this.clickhouse) {
+ throw new Error('ClickHouse client not initialized')
+ }
+ const { client, credential } = this.clickhouse
+ // No retention or is_deleted filter: an expired or deleted recording still has blocks a new key would break.
+ const result = await client.query({
+ query: `/* team_id:${teamId} query_type:recording_api_recording_exists */ SELECT 1
+ FROM session_replay_events
+ PREWHERE team_id = {team_id:Int32} AND session_id = {session_id:String}
+ LIMIT 1
+ `,
+ query_params: { team_id: teamId, session_id: sessionId },
+ format: 'JSONEachRow',
+ auth: await credential.auth(),
+ clickhouse_settings: {
+ log_comment: JSON.stringify({
+ team_id: teamId,
+ product: 'replay',
+ kind: 'node',
+ query_type: 'recording_api_recording_exists',
+ service_name: 'recording-api',
+ container_hostname: process.env.HOSTNAME || 'unknown',
+ }),
+ max_execution_time: 30,
+ // The lookup has no date bound, so cap it to keep it from starving playback listings on the shared pool.
+ max_threads: 4,
+ max_bytes_to_read: '10000000000',
+ },
+ })
+ const rows = await result.json()
+ return rows.length > 0
+ }
+
async listBlocks(sessionId: string, teamId: number): Promise<RecordingBlock[]> {
if (!this.clickhouse) {
throw new Error('ClickHouse client not initialized')
diff --git a/nodejs/src/session-replay/recording-api/schemas.ts b/nodejs/src/session-replay/recording-api/schemas.ts
index 910df3e413aa..c26a959ee458 100644
--- a/nodejs/src/session-replay/recording-api/schemas.ts
+++ b/nodejs/src/session-replay/recording-api/schemas.ts
@@ -1,5 +1,7 @@
import { z } from 'zod'
+import { RetentionPeriodToDaysMap } from '~/ingestion/pipelines/sessionreplay/shared/constants'
+
// Schema for positive integer string (e.g., "123" -> 123)
const positiveIntString = (fieldName: string) =>
z
@@ -39,6 +41,18 @@ export const DeleteRecordingsBodySchema = z.object({
deleted_by: z.string().min(1, 'Missing deleted_by').max(254),
})
+const MAX_ENCRYPT_BLOCKS = 100
+const VALID_RETENTION_DAYS = new Set(Object.values(RetentionPeriodToDaysMap))
+
+export const EncryptBlocksBodySchema = z.object({
+ // Base64 of each compressed plaintext block, encrypted in order.
+ blocks: z
+ .array(z.base64('Invalid block encoding'))
+ .min(1, 'blocks must not be empty')
+ .max(MAX_ENCRYPT_BLOCKS, `Too many blocks (max ${MAX_ENCRYPT_BLOCKS})`),
+ retention_days: z.number().refine((d) => VALID_RETENTION_DAYS.has(d), 'Invalid retention_days'),
+})
+
// Static schema for getBlock query params (validates structure only)
export const GetBlockQuerySchema = z
.object({