diff --git a/changelog.d/features/11369-video-bridge-drilldown-isolation.md b/changelog.d/features/11369-video-bridge-drilldown-isolation.md new file mode 100644 index 0000000000..b0b499304d --- /dev/null +++ b/changelog.d/features/11369-video-bridge-drilldown-isolation.md @@ -0,0 +1 @@ +- **feat(video bridge):** harden the optional drill-down cache substrate with exact-path broker policy, canonical principal/session/media isolation, independent retained-byte quotas, cancellation-safe commits, rejection of excess or non-canonical Base64 padding and non-JPEG/truncated media, warning-sensitive full JPEG canonicalization that strips trailing polyglot bytes, server-derived dimensions, and auditable derivation metadata; production tenant binding and multi-resolution selection remain follow-up work ([#11369](https://github.com/diegosouzapw/OmniRoute/pull/11369)) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 9dae1d0150..9fae13e631 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -5719,17 +5719,28 @@ paths: x-loopback-only: true tags: [System] summary: Read a bounded Video Bridge drill-down slice - description: Internal loopback/token-authenticated lookup into a short-lived per-session frame cache. It never downloads media or starts a subprocess; start/end and frame count only select already materialized frames. + description: Internal loopback/token-authenticated lookup into a short-lived cache isolated by an opaque principal, session, and media reference. It never downloads media or starts a subprocess; start/end and frame count only select already materialized, canonicalized JPEG frames whose dimensions were derived from their bytes. This cache substrate is not yet wired to the transparent Video Bridge request path and does not yet expose multi-resolution selection. security: [] parameters: + - in: header + name: x-omniroute-video-bridge-principal + required: true + description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: "^[!-~]{1,256}$" - in: query name: sessionId required: true - schema: { type: string, maxLength: 128 } + description: Canonical opaque ID without surrounding whitespace + schema: { type: string, minLength: 1, maxLength: 128 } - in: query name: videoRef required: true - schema: { type: string, maxLength: 4096 } + description: Canonical opaque reference without surrounding whitespace + schema: { type: string, minLength: 1, maxLength: 4096 } - in: query name: start required: false @@ -5743,25 +5754,58 @@ paths: required: false schema: { type: integer, minimum: 1, maximum: 16 } responses: - "200": { description: Bounded cached frame slice } - "403": { description: Trusted loopback/token identity required } + "200": { description: Bounded cached frame slice with derivation audit metadata } + "403": { description: Trusted loopback/token identity and principal required } "404": { description: Drill-down session or media key was not found } post: x-loopback-only: true tags: [System] summary: Store a bounded Video Bridge drill-down result - description: Internal lifecycle operation for explicitly authorized callers. The short-lived session cache is isolated by session and media reference and does not alter the primary request cost. + description: Internal lifecycle operation for explicitly authorized callers. The short-lived cache is isolated by principal, session, and media reference; enforces independent per-principal and global retained-byte quotas; accepts canonical Base64 only after a warning-sensitive bounded full JPEG decode/re-encode; strips trailing polyglot bytes; retains and charges only the canonical JPEG output; derives resolution from decoded bytes; and does not alter the primary request cost. The JSON wire budget includes Base64 overhead for the 32 MiB decoded-input ceiling. security: [] + parameters: + - in: header + name: x-omniroute-video-bridge-principal + required: true + description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: "^[!-~]{1,256}$" requestBody: required: true content: application/json: schema: type: object - required: [sessionId, videoRef, durationSeconds, frames] + additionalProperties: false + required: [sessionId, videoRef, derivation, durationSeconds, frames] properties: - sessionId: { type: string, maxLength: 128 } - videoRef: { type: string, maxLength: 4096 } + sessionId: + type: string + minLength: 1 + maxLength: 128 + description: Canonical opaque ID without surrounding whitespace + videoRef: + type: string + minLength: 1 + maxLength: 4096 + description: Canonical opaque reference without surrounding whitespace + derivation: + type: object + additionalProperties: false + required: [parentContentHash, policy, version] + properties: + parentContentHash: + type: string + pattern: "^sha256:[a-f0-9]{64}$" + policy: + type: string + pattern: "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$" + version: + type: string + pattern: "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$" durationSeconds: { type: number, exclusiveMinimum: 0, maximum: 600 } frames: type: array @@ -5769,27 +5813,43 @@ paths: maxItems: 16 items: type: object + additionalProperties: false required: [timestampSeconds, dataUri] properties: timestampSeconds: { type: number, minimum: 0 } - dataUri: { type: string, pattern: "^data:image/jpeg;base64," } + dataUri: + type: string + minLength: 27 + maxLength: 5592431 + description: Canonical Base64 data URI whose decoded bytes pass a warning-sensitive bounded full JPEG decode/re-encode; trailing bytes are discarded and width and height are derived server-side responses: "201": { description: Drill-down result stored } - "403": { description: Trusted loopback/token identity required } + "403": { description: Trusted loopback/token identity and principal required } "413": { description: Payload exceeds the bounded session budget } + "499": { description: Caller cancelled before the derivation was committed } delete: x-loopback-only: true tags: [System] summary: Delete a Video Bridge drill-down session security: [] parameters: + - in: header + name: x-omniroute-video-bridge-principal + required: true + description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: "^[!-~]{1,256}$" - in: query name: sessionId required: true - schema: { type: string, maxLength: 128 } + description: Canonical opaque ID without surrounding whitespace + schema: { type: string, minLength: 1, maxLength: 128 } responses: "200": { description: Session entries removed } - "403": { description: Trusted loopback/token identity required } + "403": { description: Trusted loopback/token identity and principal required } /api/cache/stats: get: diff --git a/docs/security/GUARDRAILS.md b/docs/security/GUARDRAILS.md index 28cd0a4e38..bf6ce5d7f2 100644 --- a/docs/security/GUARDRAILS.md +++ b/docs/security/GUARDRAILS.md @@ -387,14 +387,39 @@ or download a second media copy; without that explicit track, it remains video-only. The internal `/api/modality-bridge/video/drilldown` lifecycle is a separate, -loopback/token-authenticated cache. It stores at most 16 JPEG frames per entry, -keeps entries isolated by session and video reference, expires them after ten -minutes, and supports bounded `start`/`end` reads or explicit session deletion. -Besides the per-entry limits, the cache enforces a global 256 MiB decoded-byte -budget: least-recently-used entries are evicted until new content fits, and an -entry larger than the whole budget is rejected outright. -It only slices materialized frames and cannot increase the cost of the primary -video request. +loopback/token-authenticated cache substrate. Every operation also requires a +canonical opaque principal ID. Before a production caller is enabled, it must +derive that ID from the authenticated tenant and must never forward a +client-selected value. Cache keys bind that principal to canonical session and +video-reference IDs, store only their SHA-256-derived keys, and scope both reads +and deletion to the same principal. The cache stores at most 16 derived JPEG +frames per entry, expires them after ten minutes, and supports bounded +`start`/`end` reads or explicit session deletion. + +Each principal is limited to 16 entries and 64 MiB of canonical JPEG data. Those +limits are independent from the global 64-entry/256 MiB ceiling: principal quota +pressure evicts only that principal's least-recently-used entries before global +LRU eviction is considered. Expired entries are swept from both principal and +global accounting on cache activity, while cancellation and validation failure do +not commit a partial replacement. + +The cache rejects non-canonical Base64, excess padding, non-JPEG media, malformed or +truncated JPEGs, and JPEGs that produce a warning during a bounded full-image `sharp` +decode. It re-encodes each accepted image as a canonical JPEG, derives width and height +from the decoded bytes instead of trusting caller fields, and discards any trailing +polyglot bytes rather than retaining them. Only the bounded canonical compressed buffer +is charged to both quotas. The JSON wire limit includes Base64 overhead for the 32 MiB +decoded-input ceiling. Every +stored derivation records its validated JPEG format/resolution, sampling policy, +derivation version, creation time, server-computed content hash, and hashed parent +reference plus the trusted caller's parent-content hash. Cancellation is checked +between asynchronous decode/hash phases before the atomic cache commit. + +This tranche does not yet connect a production producer to the route and does not +provide multi-resolution variant selection. The transparent Video Bridge request +path therefore incurs no added work, while tenant-bound principal derivation and +the full FU-08 multi-resolution lifecycle remain explicit follow-up work rather +than documented as complete behavior. Frames are captioned sequentially with the configured Video model. An empty Video override inherits the Vision setting; if both are empty, the Vision diff --git a/src/app/api/modality-bridge/video/drilldown/route.ts b/src/app/api/modality-bridge/video/drilldown/route.ts index ba89c3053d..81c1131841 100644 --- a/src/app/api/modality-bridge/video/drilldown/route.ts +++ b/src/app/api/modality-bridge/video/drilldown/route.ts @@ -1,22 +1,149 @@ +import { z } from "zod"; + +import { sanitizeErrorMessage } from "@omniroute/open-sse/utils/error"; import { createErrorResponse } from "@/lib/api/errorResponse"; import { - VIDEO_BRIDGE_BROKER_PATH, - isVideoBridgeBrokerInternalRequest, + resolveVideoBridgeDrilldownPrincipal, + VIDEO_BRIDGE_DRILLDOWN_PATH, } from "@/lib/guardrails/videoBridgeBrokerAuth"; import { + VideoDrilldownAbortedError, VideoDrilldownCache, - type VideoDrilldownFrame, + VideoDrilldownValidationError, + VIDEO_DRILLDOWN_MAX_ENTRY_BYTES, + VIDEO_DRILLDOWN_MAX_FRAME_DATA_URI_CHARS, } from "@/lib/guardrails/videoBridgeDrilldown"; import { resolveModelSyncInternalBaseUrl } from "@/shared/services/modelSyncScheduler"; +import { createLogger } from "@/shared/utils/logger"; + +const log = createLogger("video-bridge-drilldown"); export const dynamic = "force-dynamic"; export const revalidate = 0; -export const VIDEO_BRIDGE_DRILLDOWN_PATH = "/api/modality-bridge/video/drilldown"; -const MAX_BODY_BYTES = 34 * 1024 * 1024; +export { VIDEO_BRIDGE_DRILLDOWN_PATH }; +export const VIDEO_DRILLDOWN_MAX_BODY_BYTES = + Math.ceil(VIDEO_DRILLDOWN_MAX_ENTRY_BYTES / 3) * 4 + 64 * 1024; + +function isCanonicalOpaqueId(value: string): boolean { + return value === value.trim(); +} + +function isAsciiAlphaNumeric(code: number): boolean { + return ( + (code >= 0x30 && code <= 0x39) || + (code >= 0x41 && code <= 0x5a) || + (code >= 0x61 && code <= 0x7a) + ); +} + +function isDerivationToken(value: string): boolean { + if (value.length < 1 || value.length > 64 || !isAsciiAlphaNumeric(value.charCodeAt(0))) { + return false; + } + for (let index = 1; index < value.length; index += 1) { + const code = value.charCodeAt(index); + if ( + !isAsciiAlphaNumeric(code) && + code !== 0x2e && + code !== 0x5f && + code !== 0x2f && + code !== 0x2d + ) { + return false; + } + } + return true; +} + +function isSha256Id(value: string): boolean { + if (value.length !== 71 || !value.startsWith("sha256:")) return false; + for (let index = 7; index < value.length; index += 1) { + const code = value.charCodeAt(index); + if (!((code >= 0x30 && code <= 0x39) || (code >= 0x61 && code <= 0x66))) return false; + } + return true; +} + +function isCanonicalNonNegativeNumber(value: string): boolean { + if (value.length < 1 || value.length > 64 || value !== value.trim()) return false; + const parsed = Number(value); + return Number.isFinite(parsed) && parsed >= 0; +} + +function isCanonicalFrameCount(value: string): boolean { + if (value.length < 1 || value.length > 2) return false; + for (let index = 0; index < value.length; index += 1) { + const code = value.charCodeAt(index); + if (code < 0x30 || code > 0x39) return false; + } + const parsed = Number(value); + return parsed >= 1 && parsed <= 16; +} + +const SessionIdSchema = z + .string() + .min(1) + .max(128) + .refine(isCanonicalOpaqueId, "sessionId must not contain surrounding whitespace"); +const VideoRefSchema = z + .string() + .min(1) + .max(4096) + .refine(isCanonicalOpaqueId, "videoRef must not contain surrounding whitespace"); +const NonNegativeQueryNumberSchema = z + .string() + .refine(isCanonicalNonNegativeNumber) + .transform(Number); +const FrameCountQuerySchema = z.string().refine(isCanonicalFrameCount).transform(Number); +const DrilldownReadQuerySchema = z + .object({ + end: NonNegativeQueryNumberSchema.optional(), + frames: FrameCountQuerySchema.optional(), + sessionId: SessionIdSchema, + start: NonNegativeQueryNumberSchema.optional(), + videoRef: VideoRefSchema, + }) + .strict(); +const DrilldownDeleteQuerySchema = z.object({ sessionId: SessionIdSchema }).strict(); +const DrilldownDerivationSchema = z + .object({ + parentContentHash: z.string().refine(isSha256Id), + policy: z.string().refine(isDerivationToken), + version: z.string().refine(isDerivationToken), + }) + .strict(); +const DrilldownFrameSchema = z + .object({ + dataUri: z.string().min(1).max(VIDEO_DRILLDOWN_MAX_FRAME_DATA_URI_CHARS), + timestampSeconds: z.number().finite().nonnegative(), + }) + .strict(); +const DrilldownPostBodySchema = z + .object({ + derivation: DrilldownDerivationSchema, + durationSeconds: z.number().finite().positive().max(600), + frames: z.array(DrilldownFrameSchema).min(1).max(16), + sessionId: SessionIdSchema, + videoRef: VideoRefSchema, + }) + .strict() + .superRefine((value, context) => { + for (let index = 0; index < value.frames.length; index += 1) { + if (value.frames[index].timestampSeconds > value.durationSeconds) { + context.addIssue({ + code: "custom", + message: "frame timestamp exceeds duration", + path: ["frames", index, "timestampSeconds"], + }); + } + } + }); const drilldownCache = new VideoDrilldownCache({ maxEntries: 64, - // Global decoded-byte ceiling: without it, 64 entries × 32 MiB could pin ~2 GiB. + maxEntriesPerPrincipal: 16, + maxBytesPerPrincipal: 64 * 1024 * 1024, + // Global retained-JPEG ceiling: without it, 64 entries × 32 MiB could pin ~2 GiB. maxTotalBytes: 256 * 1024 * 1024, ttlMs: 10 * 60 * 1000, }); @@ -30,6 +157,47 @@ function invalid(message: string, status = 400): Response { return createErrorResponse({ status, message, type: "invalid_request" }); } +class VideoDrilldownRequestAbortedError extends Error {} + +function queryRecord(searchParams: URLSearchParams): Record { + const values: Record = {}; + for (const [key, value] of searchParams) { + const existing = values[key]; + values[key] = + existing === undefined + ? value + : Array.isArray(existing) + ? [...existing, value] + : [existing, value]; + } + return values; +} + +function yieldToEventLoop(): Promise { + return new Promise((resolve) => setImmediate(resolve)); +} + +async function readBodyWithAbort(request: Request): Promise { + if (request.signal.aborted) throw new VideoDrilldownRequestAbortedError(); + return new Promise((resolve, reject) => { + const onAbort = () => { + request.signal.removeEventListener("abort", onAbort); + reject(new VideoDrilldownRequestAbortedError()); + }; + request.signal.addEventListener("abort", onAbort, { once: true }); + request.arrayBuffer().then( + (bytes) => { + request.signal.removeEventListener("abort", onAbort); + resolve(bytes); + }, + (error: unknown) => { + request.signal.removeEventListener("abort", onAbort); + reject(error); + } + ); + }); +} + function parseQuery(url: URL): { endSeconds?: number; frameCount?: number; @@ -37,28 +205,15 @@ function parseQuery(url: URL): { startSeconds?: number; videoRef: string; } | null { - const allowed = new Set(["end", "frames", "sessionId", "start", "videoRef"]); - if ([...url.searchParams.keys()].some((key) => !allowed.has(key))) return null; - const sessionId = url.searchParams.get("sessionId")?.trim() ?? ""; - const videoRef = url.searchParams.get("videoRef")?.trim() ?? ""; - if (!sessionId || !videoRef) return null; - const parseNumber = (name: string): number | undefined | null => { - const value = url.searchParams.get(name); - if (value === null) return undefined; - const parsed = Number(value); - return Number.isFinite(parsed) && parsed >= 0 ? parsed : null; + const parsed = DrilldownReadQuerySchema.safeParse(queryRecord(url.searchParams)); + if (!parsed.success) return null; + return { + endSeconds: parsed.data.end, + frameCount: parsed.data.frames, + sessionId: parsed.data.sessionId, + startSeconds: parsed.data.start, + videoRef: parsed.data.videoRef, }; - const startSeconds = parseNumber("start"); - const endSeconds = parseNumber("end"); - const rawFrameCount = url.searchParams.get("frames"); - const frameCount = - rawFrameCount === null - ? undefined - : /^\d{1,2}$/.test(rawFrameCount) && Number(rawFrameCount) >= 1 && Number(rawFrameCount) <= 16 - ? Number(rawFrameCount) - : null; - if (startSeconds === null || endSeconds === null || frameCount === null) return null; - return { endSeconds, frameCount, sessionId, startSeconds, videoRef }; } interface VideoDrilldownRouteDependencies { @@ -71,60 +226,72 @@ export async function handleVideoDrilldownRequest( ): Promise { const url = new URL(request.url); if (url.pathname !== expectedPath()) return invalid("Invalid Video Bridge drill-down path", 404); - if (!isVideoBridgeBrokerInternalRequest(request, VIDEO_BRIDGE_BROKER_PATH)) { + const principalId = resolveVideoBridgeDrilldownPrincipal(request); + if (!principalId) { return invalid("This endpoint requires an authenticated internal loopback request", 403); } const cache = dependencies.cache ?? drilldownCache; if (request.method === "GET") { const query = parseQuery(url); if (!query) return invalid("Invalid Video Bridge drill-down query"); - const result = cache.get(query.sessionId, query.videoRef, query); + const result = cache.get(principalId, query.sessionId, query.videoRef, query); return result ? Response.json(result, { headers: { "Cache-Control": "no-store" } }) : invalid("Video Bridge drill-down result was not found", 404); } if (request.method === "DELETE") { - const sessionId = url.searchParams.get("sessionId")?.trim() ?? ""; - if (!sessionId || [...url.searchParams.keys()].some((key) => key !== "sessionId")) { - return invalid("A sessionId is required"); - } - return Response.json({ removed: cache.clearSession(sessionId) }); + const query = DrilldownDeleteQuerySchema.safeParse(queryRecord(url.searchParams)); + if (!query.success) return invalid("A canonical sessionId is required"); + return Response.json({ removed: cache.clearSession(principalId, query.data.sessionId) }); } if (request.method !== "POST") return invalid("Invalid Video Bridge drill-down method", 405); if (request.headers.get("content-type")?.toLowerCase() !== "application/json") { return invalid("Video Bridge drill-down requires application/json"); } const declaredLength = Number(request.headers.get("content-length")); - if (Number.isFinite(declaredLength) && declaredLength > MAX_BODY_BYTES) { + if (Number.isFinite(declaredLength) && declaredLength > VIDEO_DRILLDOWN_MAX_BODY_BYTES) { return invalid("Video Bridge drill-down payload is too large", 413); } let body: unknown; try { - const bytes = await request.arrayBuffer(); - if (bytes.byteLength > MAX_BODY_BYTES) + const bytes = await readBodyWithAbort(request); + if (bytes.byteLength > VIDEO_DRILLDOWN_MAX_BODY_BYTES) return invalid("Video Bridge drill-down payload is too large", 413); body = JSON.parse(Buffer.from(bytes).toString("utf8")); - } catch { + } catch (error: unknown) { + if (error instanceof VideoDrilldownRequestAbortedError) { + return invalid("Video Bridge drill-down request was cancelled", 499); + } return invalid("Video Bridge drill-down payload is invalid"); } - if (!body || typeof body !== "object") - return invalid("Video Bridge drill-down payload is invalid"); - const record = body as Record; - if ( - typeof record.sessionId !== "string" || - typeof record.videoRef !== "string" || - typeof record.durationSeconds !== "number" || - !Array.isArray(record.frames) - ) { - return invalid("Video Bridge drill-down payload is invalid"); + const parsed = DrilldownPostBodySchema.safeParse(body); + if (!parsed.success) return invalid("Video Bridge drill-down payload is invalid"); + await yieldToEventLoop(); + if (request.signal.aborted) { + return invalid("Video Bridge drill-down request was cancelled", 499); } try { - cache.put(record.sessionId, record.videoRef, { - durationSeconds: record.durationSeconds, - frames: record.frames as VideoDrilldownFrame[], + await cache.put(principalId, parsed.data.sessionId, parsed.data.videoRef, parsed.data, { + signal: request.signal, + }); + } catch (error: unknown) { + if (error instanceof VideoDrilldownValidationError) { + return invalid("Video Bridge drill-down payload is invalid"); + } + if (error instanceof VideoDrilldownAbortedError || request.signal.aborted) { + return invalid("Video Bridge drill-down request was cancelled", 499); + } + log.error( + { + errorName: error instanceof Error ? sanitizeErrorMessage(error.name) : "UnknownError", + }, + "Unexpected Video Bridge drill-down cache failure" + ); + return createErrorResponse({ + status: 500, + message: "Video Bridge drill-down could not be stored", + type: "server_error", }); - } catch { - return invalid("Video Bridge drill-down payload is invalid"); } return Response.json({ stored: true }, { status: 201, headers: { "Cache-Control": "no-store" } }); } diff --git a/src/lib/guardrails/videoBridgeBrokerAuth.ts b/src/lib/guardrails/videoBridgeBrokerAuth.ts index d4bdb8489e..c1096d2dde 100644 --- a/src/lib/guardrails/videoBridgeBrokerAuth.ts +++ b/src/lib/guardrails/videoBridgeBrokerAuth.ts @@ -3,7 +3,9 @@ import { randomUUID, timingSafeEqual } from "node:crypto"; import { AUTHZ_HEADER_PEER_LOCALITY } from "@/server/authz/headers"; export const VIDEO_BRIDGE_BROKER_PATH = "/api/modality-bridge/video/extract"; +export const VIDEO_BRIDGE_DRILLDOWN_PATH = "/api/modality-bridge/video/drilldown"; export const VIDEO_BRIDGE_BROKER_AUTH_HEADER = "x-omniroute-video-bridge-broker"; +export const VIDEO_BRIDGE_DRILLDOWN_PRINCIPAL_HEADER = "x-omniroute-video-bridge-principal"; const globalState = globalThis as typeof globalThis & { __omnirouteVideoBridgeBrokerToken?: string; @@ -20,8 +22,26 @@ export function buildVideoBridgeBrokerHeaders(): Record { return { [VIDEO_BRIDGE_BROKER_AUTH_HEADER]: brokerToken() }; } +function normalizeVideoBridgePrincipalId(value: string | null): string | null { + if (!value || value.length > 256) return null; + for (let index = 0; index < value.length; index += 1) { + const code = value.charCodeAt(index); + if (code < 0x21 || code > 0x7e) return null; + } + return value; +} + +export function buildVideoBridgeDrilldownHeaders(principalId: string): Record { + const normalized = normalizeVideoBridgePrincipalId(principalId); + if (!normalized) throw new Error("Video Bridge drill-down principal is invalid"); + return { + ...buildVideoBridgeBrokerHeaders(), + [VIDEO_BRIDGE_DRILLDOWN_PRINCIPAL_HEADER]: normalized, + }; +} + export function isVideoBridgeBrokerTokenRequest(request: Request, path: string): boolean { - if (path !== VIDEO_BRIDGE_BROKER_PATH) return false; + if (path !== VIDEO_BRIDGE_BROKER_PATH && path !== VIDEO_BRIDGE_DRILLDOWN_PATH) return false; const expected = brokerToken(); const provided = request.headers.get(VIDEO_BRIDGE_BROKER_AUTH_HEADER)?.trim() ?? ""; if (!provided || provided.length !== expected.length) return false; @@ -34,3 +54,10 @@ export function isVideoBridgeBrokerInternalRequest(request: Request, path: strin isVideoBridgeBrokerTokenRequest(request, path) ); } + +export function resolveVideoBridgeDrilldownPrincipal(request: Request): string | null { + if (!isVideoBridgeBrokerInternalRequest(request, VIDEO_BRIDGE_DRILLDOWN_PATH)) return null; + return normalizeVideoBridgePrincipalId( + request.headers.get(VIDEO_BRIDGE_DRILLDOWN_PRINCIPAL_HEADER) + ); +} diff --git a/src/lib/guardrails/videoBridgeDrilldown.ts b/src/lib/guardrails/videoBridgeDrilldown.ts index 330da73a46..e39eaf4a57 100644 --- a/src/lib/guardrails/videoBridgeDrilldown.ts +++ b/src/lib/guardrails/videoBridgeDrilldown.ts @@ -1,18 +1,49 @@ import { createHash } from "node:crypto"; +import sharp from "sharp"; + import { resolveVideoFocusWindow, type VideoFocusWindow } from "./videoBridgeRuntime"; -export interface VideoDrilldownFrame { +export interface VideoDrilldownFrameInput { dataUri: string; timestampSeconds: number; } +export interface VideoDrilldownFrame extends VideoDrilldownFrameInput { + height: number; + width: number; +} + +export interface VideoDrilldownDerivationInput { + parentContentHash: string; + policy: string; + version: string; +} + +export interface VideoDrilldownDerivationMetadata { + contentHash: string; + createdAt: number; + format: "image/jpeg"; + parent: { + contentHash: string; + referenceHash: string; + }; + policy: string; + resolution: { + height: number; + width: number; + }; + version: string; +} + export interface VideoDrilldownPutValue { + derivation: VideoDrilldownDerivationInput; durationSeconds: number; - frames: readonly VideoDrilldownFrame[]; + frames: readonly VideoDrilldownFrameInput[]; } export interface VideoDrilldownResult { + derivation: VideoDrilldownDerivationMetadata; durationSeconds: number; focusWindow?: VideoFocusWindow; frames: VideoDrilldownFrame[]; @@ -20,30 +51,273 @@ export interface VideoDrilldownResult { export interface VideoDrilldownCacheOptions { maxEntries: number; - /** Aggregate decoded-byte budget across every entry; oldest entries are evicted (LRU) to fit. */ + /** Per-principal entry quota, enforced before the global LRU ceiling. */ + maxEntriesPerPrincipal?: number; + /** Per-principal retained-JPEG-byte quota, independent from the global budget. */ + maxBytesPerPrincipal?: number; + /** Aggregate retained-JPEG-byte budget; oldest entries are evicted (LRU) to fit. */ maxTotalBytes?: number; now?: () => number; ttlMs: number; + normalizeJpeg?: VideoDrilldownJpegNormalizer; } -interface StoredDrilldown extends VideoDrilldownPutValue { +export type VideoDrilldownJpegNormalizer = ( + data: Buffer +) => Promise<{ data: Buffer; height: number; width: number }>; + +export class VideoDrilldownValidationError extends Error { + constructor(message: string) { + super(message); + this.name = "VideoDrilldownValidationError"; + } +} + +export class VideoDrilldownAbortedError extends Error { + constructor() { + super("Video Bridge drill-down was aborted"); + this.name = "VideoDrilldownAbortedError"; + } +} + +interface StoredDrilldown { bytes: number; + derivation: VideoDrilldownDerivationMetadata; + durationSeconds: number; expiresAt: number; - sessionId: string; + frames: StoredDrilldownFrame[]; + principalKey: string; + sessionKey: string; } -const MAX_FRAME_BYTES = 4 * 1024 * 1024; -const MAX_TOTAL_BYTES = 32 * 1024 * 1024; +interface StoredDrilldownFrame { + data: Buffer; + height: number; + timestampSeconds: number; + width: number; +} + +export const VIDEO_DRILLDOWN_MAX_FRAME_BYTES = 4 * 1024 * 1024; +export const VIDEO_DRILLDOWN_MAX_ENTRY_BYTES = 32 * 1024 * 1024; const MAX_DURATION_SECONDS = 600; +const MAX_FRAME_DIMENSION = 8192; +const JPEG_DATA_URI_PREFIX = "data:image/jpeg;base64,"; +export const VIDEO_DRILLDOWN_MAX_FRAME_DATA_URI_CHARS = + JPEG_DATA_URI_PREFIX.length + Math.ceil(VIDEO_DRILLDOWN_MAX_FRAME_BYTES / 3) * 4; -function cacheKey(sessionId: string, videoRef: string): string { - return createHash("sha256").update(`${sessionId}\0${videoRef}`).digest("hex"); +function validationFailure(message: string): never { + throw new VideoDrilldownValidationError(message); } -function validateFrames(value: VideoDrilldownPutValue): { - frames: VideoDrilldownFrame[]; +function throwIfAborted(signal?: AbortSignal): void { + if (signal?.aborted) throw new VideoDrilldownAbortedError(); +} + +function yieldToEventLoop(): Promise { + return new Promise((resolve) => setImmediate(resolve)); +} + +function isAsciiAlphaNumeric(code: number): boolean { + return ( + (code >= 0x30 && code <= 0x39) || + (code >= 0x41 && code <= 0x5a) || + (code >= 0x61 && code <= 0x7a) + ); +} + +function isDerivationToken(value: string): boolean { + if (value.length < 1 || value.length > 64 || !isAsciiAlphaNumeric(value.charCodeAt(0))) { + return false; + } + for (let index = 1; index < value.length; index += 1) { + const code = value.charCodeAt(index); + if ( + !isAsciiAlphaNumeric(code) && + code !== 0x2e && + code !== 0x5f && + code !== 0x2f && + code !== 0x2d + ) { + return false; + } + } + return true; +} + +function isSha256Id(value: string): boolean { + if (value.length !== 71 || !value.startsWith("sha256:")) return false; + for (let index = 7; index < value.length; index += 1) { + const code = value.charCodeAt(index); + if (!((code >= 0x30 && code <= 0x39) || (code >= 0x61 && code <= 0x66))) return false; + } + return true; +} + +function isCanonicalBase64Alphabet(value: string): boolean { + if (value.length < 4 || value.length % 4 !== 0) return false; + const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0; + const contentLength = value.length - padding; + for (let index = 0; index < contentLength; index += 1) { + const code = value.charCodeAt(index); + if (!isAsciiAlphaNumeric(code) && code !== 0x2b && code !== 0x2f) return false; + } + for (let index = contentLength; index < value.length; index += 1) { + if (value.charCodeAt(index) !== 0x3d) return false; + } + return true; +} + +function digestKey(...parts: readonly string[]): string { + const hash = createHash("sha256"); + for (const part of parts) { + hash + .update(String(Buffer.byteLength(part, "utf8"))) + .update(":") + .update(part); + } + return hash.digest("hex"); +} + +function contentDigest(value: string | Buffer): string { + return `sha256:${createHash("sha256").update(value).digest("hex")}`; +} + +function updateHashPart(hash: ReturnType, value: string | Buffer): void { + const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : value; + hash.update(String(bytes.byteLength)).update(":").update(bytes); +} + +function validIdentity(principalId: string, sessionId: string, videoRef?: string): boolean { + return ( + validPrincipal(principalId) && + validOpaqueId(sessionId, 128) && + (videoRef === undefined || validOpaqueId(videoRef, 4096)) + ); +} + +function validPrincipal(principalId: string): boolean { + if (principalId.length < 1 || principalId.length > 256) return false; + for (let index = 0; index < principalId.length; index += 1) { + const code = principalId.charCodeAt(index); + if (code < 0x21 || code > 0x7e) return false; + } + return true; +} + +function validOpaqueId(value: string, maxLength: number): boolean { + return value.length >= 1 && value.length <= maxLength && value === value.trim(); +} + +async function normalizeJpegWithSharp( + data: Buffer +): Promise<{ data: Buffer; height: number; width: number }> { + if ( + data.byteLength < 4 || + data[0] !== 0xff || + data[1] !== 0xd8 || + data[data.byteLength - 2] !== 0xff || + data[data.byteLength - 1] !== 0xd9 + ) { + validationFailure("Invalid drill-down JPEG frame signature"); + } + try { + const image = sharp(data, { + failOn: "warning", + limitInputPixels: MAX_FRAME_DIMENSION * MAX_FRAME_DIMENSION, + sequentialRead: true, + }); + const metadata = await image.metadata(); + const height = metadata.height; + const width = metadata.width; + if ( + metadata.format !== "jpeg" || + !Number.isInteger(width) || + !Number.isInteger(height) || + !width || + !height || + width > MAX_FRAME_DIMENSION || + height > MAX_FRAME_DIMENSION + ) { + validationFailure("Invalid drill-down JPEG frame dimensions"); + } + // A thumbnail decode can stop before the complete entropy scan. Re-encoding the + // full image makes libvips surface scan warnings and strips any bytes trailing the + // source JPEG. Only this canonical compressed output is retained and charged. + const normalized = await image.clone().jpeg({ progressive: false }).toBuffer(); + if ( + normalized.byteLength < 4 || + normalized.byteLength > VIDEO_DRILLDOWN_MAX_FRAME_BYTES || + normalized[0] !== 0xff || + normalized[1] !== 0xd8 || + normalized[normalized.byteLength - 2] !== 0xff || + normalized[normalized.byteLength - 1] !== 0xd9 + ) { + validationFailure("Invalid canonical drill-down JPEG frame"); + } + return { data: normalized, height, width }; + } catch (error: unknown) { + if (error instanceof VideoDrilldownValidationError) throw error; + validationFailure("Invalid drill-down JPEG frame structure"); + } +} + +async function decodeCanonicalJpeg( + dataUri: string, + normalizeJpeg: VideoDrilldownJpegNormalizer, + signal?: AbortSignal +): Promise<{ + data: Buffer; + resolution: { height: number; width: number }; +}> { + throwIfAborted(signal); + if (!dataUri.startsWith(JPEG_DATA_URI_PREFIX)) { + validationFailure("Invalid drill-down JPEG frame"); + } + const encoded = dataUri.slice(JPEG_DATA_URI_PREFIX.length); + if (dataUri.length > VIDEO_DRILLDOWN_MAX_FRAME_DATA_URI_CHARS) { + validationFailure("Drill-down frame byte limit exceeded"); + } + if (!isCanonicalBase64Alphabet(encoded)) { + validationFailure("Drill-down JPEG must use canonical Base64"); + } + const data = Buffer.from(encoded, "base64"); + if (data.toString("base64") !== encoded) { + validationFailure("Drill-down JPEG must use canonical Base64"); + } + if (data.byteLength < 1 || data.byteLength > VIDEO_DRILLDOWN_MAX_FRAME_BYTES) { + validationFailure("Drill-down frame byte limit exceeded"); + } + throwIfAborted(signal); + const normalized = await normalizeJpeg(data); + throwIfAborted(signal); + if ( + !Buffer.isBuffer(normalized.data) || + normalized.data.byteLength < 1 || + normalized.data.byteLength > VIDEO_DRILLDOWN_MAX_FRAME_BYTES || + !Number.isInteger(normalized.width) || + !Number.isInteger(normalized.height) || + normalized.width < 1 || + normalized.height < 1 || + normalized.width > MAX_FRAME_DIMENSION || + normalized.height > MAX_FRAME_DIMENSION + ) { + validationFailure("Invalid canonical drill-down JPEG frame"); + } + return { + data: normalized.data, + resolution: { height: normalized.height, width: normalized.width }, + }; +} + +async function validateFrames( + value: VideoDrilldownPutValue, + normalizeJpeg: VideoDrilldownJpegNormalizer, + signal?: AbortSignal +): Promise<{ + frames: StoredDrilldownFrame[]; + resolution: { height: number; width: number }; totalBytes: number; -} { +}> { if ( !Number.isFinite(value.durationSeconds) || value.durationSeconds <= 0 || @@ -52,36 +326,112 @@ function validateFrames(value: VideoDrilldownPutValue): { value.frames.length < 1 || value.frames.length > 16 ) { - throw new Error("Invalid drill-down duration or frame count"); + validationFailure("Invalid drill-down duration or frame count"); } let totalBytes = 0; - const frames = value.frames.map((frame) => { + let resolution: { height: number; width: number } | undefined; + const frames: StoredDrilldownFrame[] = []; + for (const frame of value.frames) { + throwIfAborted(signal); if ( !frame || !Number.isFinite(frame.timestampSeconds) || frame.timestampSeconds < 0 || frame.timestampSeconds > value.durationSeconds || - !/^data:image\/jpeg;base64,[A-Za-z0-9+/=]+$/i.test(frame.dataUri) + typeof frame.dataUri !== "string" ) { - throw new Error("Invalid drill-down JPEG frame"); + validationFailure("Invalid drill-down JPEG frame"); } - const encoded = frame.dataUri.slice(frame.dataUri.indexOf(",") + 1); - const bytes = Math.floor((encoded.length * 3) / 4); - if (bytes < 1 || bytes > MAX_FRAME_BYTES) - throw new Error("Drill-down frame byte limit exceeded"); + const decoded = await decodeCanonicalJpeg(frame.dataUri, normalizeJpeg, signal); + if ( + resolution && + (resolution.height !== decoded.resolution.height || + resolution.width !== decoded.resolution.width) + ) { + validationFailure("Drill-down frames must use one auditable resolution"); + } + resolution ??= decoded.resolution; + const bytes = decoded.data.byteLength; totalBytes += bytes; - if (totalBytes > MAX_TOTAL_BYTES) throw new Error("Drill-down response byte limit exceeded"); - return { dataUri: frame.dataUri, timestampSeconds: frame.timestampSeconds }; - }); + if (totalBytes > VIDEO_DRILLDOWN_MAX_ENTRY_BYTES) { + validationFailure("Drill-down response byte limit exceeded"); + } + frames.push({ + data: decoded.data, + height: decoded.resolution.height, + timestampSeconds: frame.timestampSeconds, + width: decoded.resolution.width, + }); + } + const sortedFrames = frames.sort((left, right) => left.timestampSeconds - right.timestampSeconds); + if (!resolution) validationFailure("Invalid drill-down frame resolution"); return { - frames: frames.sort((left, right) => left.timestampSeconds - right.timestampSeconds), + frames: sortedFrames, + resolution, totalBytes, }; } +async function buildDerivationMetadata( + videoRef: string, + value: VideoDrilldownPutValue, + frames: readonly StoredDrilldownFrame[], + resolution: { height: number; width: number }, + createdAt: number, + signal?: AbortSignal +): Promise { + const derivation = value.derivation; + const parentContentHash = derivation?.parentContentHash; + const policy = derivation?.policy; + const version = derivation?.version; + if ( + typeof parentContentHash !== "string" || + !isSha256Id(parentContentHash) || + typeof policy !== "string" || + !isDerivationToken(policy) || + typeof version !== "string" || + !isDerivationToken(version) + ) { + validationFailure("Invalid drill-down derivation metadata"); + } + throwIfAborted(signal); + const hash = createHash("sha256"); + for (const part of [ + "video-drilldown/v1", + parentContentHash, + policy, + version, + String(value.durationSeconds), + ]) { + updateHashPart(hash, part); + } + for (const frame of frames) { + throwIfAborted(signal); + updateHashPart(hash, String(frame.timestampSeconds)); + updateHashPart(hash, `${frame.width}x${frame.height}`); + updateHashPart(hash, frame.data); + await yieldToEventLoop(); + } + throwIfAborted(signal); + return { + contentHash: `sha256:${hash.digest("hex")}`, + createdAt, + format: "image/jpeg", + parent: { + contentHash: parentContentHash, + referenceHash: contentDigest(videoRef), + }, + policy, + resolution: { ...resolution }, + version, + }; +} + export class VideoDrilldownCache { private readonly entries = new Map(); private readonly now: () => number; + private readonly principalUsage = new Map(); + private readonly normalizeJpeg: VideoDrilldownJpegNormalizer; private totalBytes = 0; constructor(private readonly options: VideoDrilldownCacheOptions) { @@ -91,6 +441,18 @@ export class VideoDrilldownCache { if (!Number.isInteger(options.maxEntries) || options.maxEntries < 1) { throw new Error("Drill-down cache entry limit is invalid"); } + if ( + options.maxEntriesPerPrincipal !== undefined && + (!Number.isInteger(options.maxEntriesPerPrincipal) || options.maxEntriesPerPrincipal < 1) + ) { + throw new Error("Drill-down cache principal entry quota is invalid"); + } + if ( + options.maxBytesPerPrincipal !== undefined && + (!Number.isInteger(options.maxBytesPerPrincipal) || options.maxBytesPerPrincipal < 1) + ) { + throw new Error("Drill-down cache principal byte quota is invalid"); + } if ( options.maxTotalBytes !== undefined && (!Number.isInteger(options.maxTotalBytes) || options.maxTotalBytes < 1) @@ -98,6 +460,7 @@ export class VideoDrilldownCache { throw new Error("Drill-down cache byte budget is invalid"); } this.now = options.now ?? Date.now; + this.normalizeJpeg = options.normalizeJpeg ?? normalizeJpegWithSharp; } private drop(key: string): void { @@ -105,26 +468,103 @@ export class VideoDrilldownCache { if (!stored) return; this.entries.delete(key); this.totalBytes -= stored.bytes; + const usage = this.principalUsage.get(stored.principalKey); + if (!usage) return; + usage.bytes -= stored.bytes; + usage.entries -= 1; + if (usage.entries === 0) this.principalUsage.delete(stored.principalKey); } - put(sessionId: string, videoRef: string, value: VideoDrilldownPutValue): void { - if (!sessionId || sessionId.length > 128 || !videoRef || videoRef.length > 4096) { - throw new Error("Drill-down cache key is invalid"); + private addUsage(principalKey: string, bytes: number): void { + const usage = this.principalUsage.get(principalKey) ?? { bytes: 0, entries: 0 }; + usage.bytes += bytes; + usage.entries += 1; + this.principalUsage.set(principalKey, usage); + } + + private sweepExpired(): void { + const now = this.now(); + for (const [key, stored] of this.entries) { + if (stored.expiresAt <= now) this.drop(key); } - const { frames, totalBytes } = validateFrames(value); + } + + private principalExceedsQuota(principalKey: string): boolean { + const usage = this.principalUsage.get(principalKey); + return Boolean( + usage && + ((this.options.maxEntriesPerPrincipal !== undefined && + usage.entries > this.options.maxEntriesPerPrincipal) || + (this.options.maxBytesPerPrincipal !== undefined && + usage.bytes > this.options.maxBytesPerPrincipal)) + ); + } + + private evictOldestForPrincipal(principalKey: string, protectedKey: string): void { + for (const [key, stored] of this.entries) { + if (stored.principalKey === principalKey && key !== protectedKey) { + this.drop(key); + return; + } + } + } + + async put( + principalId: string, + sessionId: string, + videoRef: string, + value: VideoDrilldownPutValue, + requestOptions: { signal?: AbortSignal } = {} + ): Promise { + if (!validIdentity(principalId, sessionId, videoRef)) { + validationFailure("Drill-down cache key is invalid"); + } + this.sweepExpired(); + const signal = requestOptions.signal; + const { frames, resolution, totalBytes } = await validateFrames( + value, + this.normalizeJpeg, + signal + ); if (this.options.maxTotalBytes !== undefined && totalBytes > this.options.maxTotalBytes) { - throw new Error("Drill-down entry exceeds the cache byte budget"); + validationFailure("Drill-down entry exceeds the cache byte budget"); } - const key = cacheKey(sessionId, videoRef); + if ( + this.options.maxBytesPerPrincipal !== undefined && + totalBytes > this.options.maxBytesPerPrincipal + ) { + validationFailure("Drill-down entry exceeds the principal byte quota"); + } + const principalKey = digestKey(principalId); + const sessionKey = digestKey(principalId, sessionId); + const key = digestKey(principalId, sessionId, videoRef); + const createdAt = this.now(); + const derivation = await buildDerivationMetadata( + videoRef, + value, + frames, + resolution, + createdAt, + signal + ); + throwIfAborted(signal); this.drop(key); this.entries.set(key, { bytes: totalBytes, + derivation, durationSeconds: value.durationSeconds, - expiresAt: this.now() + this.options.ttlMs, + expiresAt: createdAt + this.options.ttlMs, frames, - sessionId, + principalKey, + sessionKey, }); this.totalBytes += totalBytes; + this.addUsage(principalKey, totalBytes); + while (this.principalExceedsQuota(principalKey)) { + const previousSize = this.entries.size; + this.evictOldestForPrincipal(principalKey, key); + if (this.entries.size === previousSize) break; + } while ( this.entries.size > this.options.maxEntries || (this.options.maxTotalBytes !== undefined && this.totalBytes > this.options.maxTotalBytes) @@ -136,11 +576,14 @@ export class VideoDrilldownCache { } get( + principalId: string, sessionId: string, videoRef: string, options: { endSeconds?: number; frameCount?: number; startSeconds?: number } = {} ): VideoDrilldownResult | null { - const key = cacheKey(sessionId, videoRef); + if (!validIdentity(principalId, sessionId, videoRef)) return null; + this.sweepExpired(); + const key = digestKey(principalId, sessionId, videoRef); const stored = this.entries.get(key); if (!stored) return null; if (stored.expiresAt <= this.now()) { @@ -178,19 +621,33 @@ export class VideoDrilldownCache { frame.timestampSeconds <= focusWindow.endSeconds) ) .slice(0, frameCount) - .map((frame) => ({ ...frame })); + .map((frame) => ({ + dataUri: `${JPEG_DATA_URI_PREFIX}${frame.data.toString("base64")}`, + height: frame.height, + timestampSeconds: frame.timestampSeconds, + width: frame.width, + })); if (frames.length === 0) return null; return { + derivation: { + ...stored.derivation, + parent: { ...stored.derivation.parent }, + resolution: { ...stored.derivation.resolution }, + }, durationSeconds: stored.durationSeconds, ...(focusWindow ? { focusWindow } : {}), frames, }; } - clearSession(sessionId: string): number { + clearSession(principalId: string, sessionId: string): number { + if (!validIdentity(principalId, sessionId)) return 0; + this.sweepExpired(); + const principalKey = digestKey(principalId); + const sessionKey = digestKey(principalId, sessionId); let removed = 0; for (const [key, entry] of this.entries.entries()) { - if (entry.sessionId === sessionId) { + if (entry.principalKey === principalKey && entry.sessionKey === sessionKey) { this.drop(key); removed += 1; } @@ -198,8 +655,27 @@ export class VideoDrilldownCache { return removed; } + getUsage(principalId: string): { + bytes: number; + entries: number; + totalBytes: number; + totalEntries: number; + } { + this.sweepExpired(); + const usage = validPrincipal(principalId) + ? this.principalUsage.get(digestKey(principalId)) + : undefined; + return { + bytes: usage?.bytes ?? 0, + entries: usage?.entries ?? 0, + totalBytes: this.totalBytes, + totalEntries: this.entries.size, + }; + } + clearAll(): void { this.entries.clear(); + this.principalUsage.clear(); this.totalBytes = 0; } } diff --git a/src/server/authz/policies/management.ts b/src/server/authz/policies/management.ts index 772c801247..0ab352b84a 100644 --- a/src/server/authz/policies/management.ts +++ b/src/server/authz/policies/management.ts @@ -15,6 +15,7 @@ import { evaluateAccessTokenAuth } from "../accessTokenAuth"; import { isInternalServiceRequest } from "../../../lib/api/internalServiceAuth"; import { VIDEO_BRIDGE_BROKER_PATH, + VIDEO_BRIDGE_DRILLDOWN_PATH, isVideoBridgeBrokerTokenRequest, } from "../../../lib/guardrails/videoBridgeBrokerAuth"; import { CLI_TOKEN_HEADER, PEER_IP_HEADER, VIA_PROXY_HEADER } from "../headers"; @@ -246,19 +247,20 @@ export const managementPolicy: RoutePolicy = { return allow({ kind: "management_key", id: "model-sync", label: "internal-model-sync" }); } - // Exact-path, per-process authenticated self-hop used by the public Video - // Bridge guardrail. The unconditional LOCAL_ONLY gate above has already - // rejected remote peers; this carve-out is deliberately not valid for the - // adjacent runtime-status route or any future child path. + // Exact-path, per-process authenticated self-hops used by the public Video + // Bridge guardrail and its isolated drill-down lifecycle. The unconditional + // LOCAL_ONLY gate above has already rejected remote peers; this carve-out is + // deliberately not valid for runtime status or any future adjacent path. if ( - path === VIDEO_BRIDGE_BROKER_PATH && + (path === VIDEO_BRIDGE_BROKER_PATH || path === VIDEO_BRIDGE_DRILLDOWN_PATH) && isLoopbackRequest(ctx) && isVideoBridgeBrokerTokenRequest(ctx.request as unknown as Request, path) ) { + const drilldown = path === VIDEO_BRIDGE_DRILLDOWN_PATH; return allow({ kind: "management_key", - id: "video-bridge-broker", - label: "internal-video-bridge-broker", + id: drilldown ? "video-bridge-drilldown" : "video-bridge-broker", + label: drilldown ? "internal-video-bridge-drilldown" : "internal-video-bridge-broker", }); } diff --git a/tests/unit/guardrails/videoBridgeDrilldown.test.ts b/tests/unit/guardrails/videoBridgeDrilldown.test.ts index 054447d9cb..d0ffa931a5 100644 --- a/tests/unit/guardrails/videoBridgeDrilldown.test.ts +++ b/tests/unit/guardrails/videoBridgeDrilldown.test.ts @@ -1,34 +1,120 @@ import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; import test from "node:test"; +import sharp from "sharp"; + import { + VideoDrilldownAbortedError, VideoDrilldownCache, type VideoDrilldownFrame, } from "../../../src/lib/guardrails/videoBridgeDrilldown"; -const frames: VideoDrilldownFrame[] = [ - { dataUri: "data:image/jpeg;base64,QQ==", timestampSeconds: 1 }, - { dataUri: "data:image/jpeg;base64,Qg==", timestampSeconds: 5 }, - { dataUri: "data:image/jpeg;base64,Qw==", timestampSeconds: 9 }, -]; - -test("drill-down cache isolates sessions and returns bounded focus slices", () => { - const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); - cache.put("session-a", "video-a", { durationSeconds: 10, frames }); - cache.put("session-b", "video-a", { durationSeconds: 10, frames: [frames[0]] }); - - assert.deepEqual( - cache.get("session-a", "video-a", { endSeconds: 6, frameCount: 2 })?.frames, - frames.slice(0, 2) +const validJpegs = new Map(); +for (const [width, height] of [ + [320, 180], + [640, 360], +] as const) { + validJpegs.set( + `${width}x${height}`, + await sharp({ + create: { width, height, channels: 3, background: { r: 1, g: 1, b: 1 } }, + }) + .jpeg({ progressive: false }) + .toBuffer() ); - assert.equal(cache.get("session-a", "video-b"), null); - assert.equal(cache.get("session-b", "video-a")?.frames.length, 1); +} +const noisyPixels = Buffer.alloc(128 * 128 * 3); +let noiseState = 1; +for (let index = 0; index < noisyPixels.length; index += 1) { + noiseState = (noiseState * 1_664_525 + 1_013_904_223) >>> 0; + noisyPixels[index] = noiseState >>> 24; +} +const noisyJpeg = await sharp(noisyPixels, { + raw: { width: 128, height: 128, channels: 3 }, +}) + .jpeg({ progressive: false, quality: 90 }) + .toBuffer(); + +const frames: VideoDrilldownFrame[] = [ + { dataUri: jpegDataUri(320, 180, 0, 1), height: 180, timestampSeconds: 1, width: 320 }, + { dataUri: jpegDataUri(320, 180, 0, 2), height: 180, timestampSeconds: 5, width: 320 }, + { dataUri: jpegDataUri(320, 180, 0, 3), height: 180, timestampSeconds: 9, width: 320 }, +]; +const derivation = { + parentContentHash: `sha256:${"a".repeat(64)}`, + policy: "focused-window", + version: "video-drilldown/v1", +} as const; + +function jpegDataUri(width: number, height: number, payloadBytes = 0, fill = 0): string { + const base = validJpegs.get(`${width}x${height}`); + if (!base) throw new Error(`Missing valid JPEG fixture for ${width}x${height}`); + if (payloadBytes > 65_531) throw new Error("JPEG fixture comment is too large"); + const bytes = + payloadBytes === 0 + ? base + : Buffer.concat([ + base.subarray(0, -2), + Buffer.from([0xff, 0xfe, (payloadBytes + 2) >> 8, (payloadBytes + 2) & 0xff]), + Buffer.alloc(payloadBytes, fill), + base.subarray(-2), + ]); + return `data:image/jpeg;base64,${bytes.toString("base64")}`; +} + +function retainedBytes(dataUri: string): number { + return Buffer.from(dataUri.slice(dataUri.indexOf(",") + 1), "base64").byteLength; +} + +function retainFixtureJpeg(data: Buffer): Promise<{ data: Buffer; height: number; width: number }> { + return Promise.resolve({ data: Buffer.from(data), height: 180, width: 320 }); +} + +function drilldownValue(inputFrames: readonly VideoDrilldownFrame[]) { + return { derivation, durationSeconds: 10, frames: inputFrames }; +} + +test("drill-down cache denies cross-principal reads and deletes", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + await cache.put("principal-a", "session", "video", drilldownValue(frames)); + + assert.equal(cache.get("principal-b", "session", "video"), null); + assert.equal(cache.clearSession("principal-b", "session"), 0); + assert.equal(cache.get("principal-a", "session", "video")?.frames.length, 3); + assert.equal(cache.clearSession("principal-a", "session"), 1); + assert.equal(cache.get("principal-a", "session", "video"), null); }); -test("drill-down cache clamps a valid focus and preserves timeline metadata", () => { +test("drill-down cache isolates sessions and returns bounded focus slices", async () => { const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); - cache.put("session", "video", { durationSeconds: 10, frames }); - const result = cache.get("session", "video", { + await cache.put("principal", "session-a", "video-a", drilldownValue(frames)); + await cache.put("principal", "session-b", "video-a", drilldownValue([frames[0]])); + + const slice = cache.get("principal", "session-a", "video-a", { + endSeconds: 6, + frameCount: 2, + }); + assert.deepEqual( + slice?.frames.map(({ height, timestampSeconds, width }) => ({ + height, + timestampSeconds, + width, + })), + frames.slice(0, 2).map(({ height, timestampSeconds, width }) => ({ + height, + timestampSeconds, + width, + })) + ); + assert.equal(cache.get("principal", "session-a", "video-b"), null); + assert.equal(cache.get("principal", "session-b", "video-a")?.frames.length, 1); +}); + +test("drill-down cache clamps a valid focus and preserves timeline metadata", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + await cache.put("principal", "session", "video", drilldownValue(frames)); + const result = cache.get("principal", "session", "video", { endSeconds: 100, startSeconds: -4, frameCount: 16, @@ -38,72 +124,419 @@ test("drill-down cache clamps a valid focus and preserves timeline metadata", () assert.equal(result?.frames.length, 3); }); -test("drill-down cache rejects invalid and oversized frame payloads", () => { +test("drill-down cache rejects invalid and oversized frame payloads", async () => { const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); - assert.throws(() => cache.put("session", "video", { durationSeconds: 10, frames: [] }), /frame/i); - assert.throws( - () => - cache.put("session", "video", { - durationSeconds: 10, - frames: [{ dataUri: "data:image/png;base64,QQ==", timestampSeconds: 1 }], - }), + await assert.rejects(cache.put("principal", "session", "video", drilldownValue([])), /frame/i); + await assert.rejects( + cache.put( + "principal", + "session", + "video", + drilldownValue([ + { + dataUri: "data:image/png;base64,QQ==", + height: 180, + timestampSeconds: 1, + width: 320, + }, + ]) + ), /JPEG/i ); }); -test("drill-down cache expires entries and evicts the least recently used key", () => { - let now = 1000; - const cache = new VideoDrilldownCache({ now: () => now, ttlMs: 5000, maxEntries: 1 }); - cache.put("session-a", "video", { durationSeconds: 10, frames }); - cache.put("session-b", "video", { durationSeconds: 10, frames }); - assert.equal(cache.get("session-a", "video"), null); - now = 7000; - assert.equal(cache.get("session-b", "video"), null); +test("drill-down cache rejects non-canonical Base64 before quota accounting", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + const padded = `${jpegDataUri(320, 180)}${"=".repeat(1024 * 1024)}`; + + await assert.rejects( + cache.put( + "principal", + "session", + "video", + drilldownValue([{ dataUri: padded, height: 180, timestampSeconds: 1, width: 320 }]) + ), + /canonical Base64/i + ); + assert.deepEqual(cache.getUsage("principal"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); }); -test("drill-down cache enforces a global byte budget with LRU eviction", () => { - const bigFrame = (fill: string): VideoDrilldownFrame => ({ - dataUri: `data:image/jpeg;base64,${fill.repeat(4000)}`, - timestampSeconds: 1, +test("drill-down cache rejects non-JPEG bytes disguised by a JPEG data URI", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + const mp4 = Buffer.concat([ + Buffer.from([0, 0, 0, 24]), + Buffer.from("ftypisom", "ascii"), + ]).toString("base64"); + + await assert.rejects( + cache.put( + "principal", + "session", + "video", + drilldownValue([ + { + dataUri: `data:image/jpeg;base64,${mp4}`, + height: 180, + timestampSeconds: 1, + width: 320, + }, + ]) + ), + /JPEG/i + ); +}); + +test("drill-down cache canonicalizes JPEG bytes without retaining a disguised media tail", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + const jpeg = validJpegs.get("320x180"); + if (!jpeg) throw new Error("Missing valid JPEG fixture for 320x180"); + const marker = Buffer.from("ftypisom", "ascii"); + const tainted = Buffer.concat([ + jpeg, + Buffer.from([0, 0, 1, 16]), + marker, + Buffer.alloc(256, 0x41), + Buffer.from([0xff, 0xd9]), + ]); + + await cache.put( + "principal", + "session", + "video", + drilldownValue([ + { + dataUri: `data:image/jpeg;base64,${tainted.toString("base64")}`, + height: 180, + timestampSeconds: 1, + width: 320, + }, + ]) + ); + + const result = cache.get("principal", "session", "video"); + assert.equal(result?.frames.length, 1); + const retained = Buffer.from(result?.frames[0].dataUri.split(",", 2)[1] ?? "", "base64"); + assert.equal(retained.includes(marker), false); + assert.ok(retained.byteLength < tainted.byteLength); + assert.equal(retained.subarray(-2).toString("hex"), "ffd9"); + assert.deepEqual( + await sharp(retained) + .metadata() + .then(({ height, width }) => ({ height, width })), + { + height: 180, + width: 320, + } + ); + assert.deepEqual(cache.getUsage("principal"), { + bytes: retained.byteLength, + entries: 1, + totalBytes: retained.byteLength, + totalEntries: 1, }); - // Each entry is ~3000 decoded bytes; the budget fits two entries. +}); + +test("drill-down cache rejects a forged SOI/SOF header without a valid scan and EOI", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + const forged = "data:image/jpeg;base64,/9hBQkP/wAAHCAABAAE="; + + await assert.rejects( + cache.put( + "principal", + "session", + "video", + drilldownValue([{ dataUri: forged, height: 1, timestampSeconds: 1, width: 1 }]) + ), + /JPEG/i + ); + assert.deepEqual(cache.getUsage("principal"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); +}); + +test("drill-down cache rejects a truncated entropy scan even when EOI is reattached", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + const truncated = Buffer.concat([ + noisyJpeg.subarray(0, noisyJpeg.byteLength - 34), + Buffer.from([0xff, 0xd9]), + ]); + + await assert.rejects( + cache.put( + "principal", + "session", + "video", + drilldownValue([ + { + dataUri: `data:image/jpeg;base64,${truncated.toString("base64")}`, + height: 128, + timestampSeconds: 1, + width: 128, + }, + ]) + ), + /JPEG/i + ); + assert.deepEqual(cache.getUsage("principal"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); +}); + +test("drill-down cache derives resolution from JPEG bytes instead of caller metadata", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + await cache.put( + "principal", + "session", + "video", + drilldownValue([{ dataUri: jpegDataUri(640, 360), height: 1, timestampSeconds: 1, width: 1 }]) + ); + + const result = cache.get("principal", "session", "video"); + assert.deepEqual(result?.derivation.resolution, { height: 360, width: 640 }); + assert.deepEqual( + result?.frames.map(({ height, width }) => ({ height, width })), + [{ height: 360, width: 640 }] + ); +}); + +test("drill-down cache expires entries and evicts the least recently used key", async () => { + let now = 1000; + const cache = new VideoDrilldownCache({ now: () => now, ttlMs: 5000, maxEntries: 1 }); + await cache.put("principal", "session-a", "video", drilldownValue(frames)); + await cache.put("principal", "session-b", "video", drilldownValue(frames)); + assert.equal(cache.get("principal", "session-a", "video"), null); + now = 7000; + assert.equal(cache.get("principal", "session-b", "video"), null); +}); + +test("drill-down cache sweeps all expired entries from principal and global usage", async () => { + let now = 1000; + const cache = new VideoDrilldownCache({ now: () => now, ttlMs: 5000, maxEntries: 4 }); + await cache.put("principal-a", "session", "video", drilldownValue(frames)); + await cache.put("principal-b", "session", "video", drilldownValue([frames[0]])); + const principalABytes = + cache + .get("principal-a", "session", "video") + ?.frames.reduce((total, frame) => total + retainedBytes(frame.dataUri), 0) ?? 0; + const principalBBytes = + cache + .get("principal-b", "session", "video") + ?.frames.reduce((total, frame) => total + retainedBytes(frame.dataUri), 0) ?? 0; + assert.deepEqual(cache.getUsage("principal-a"), { + bytes: principalABytes, + entries: 1, + totalBytes: principalABytes + principalBBytes, + totalEntries: 2, + }); + + now = 7000; + + assert.deepEqual(cache.getUsage("principal-a"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); + assert.equal(cache.clearSession("principal-b", "session"), 0); +}); + +test("drill-down cache enforces a global byte budget with LRU eviction", async () => { + const bigFrame = (fill: string): VideoDrilldownFrame => ({ + dataUri: jpegDataUri(320, 180, 3000, fill.charCodeAt(0)), + height: 180, + timestampSeconds: 1, + width: 320, + }); + const bigFrameBytes = retainedBytes(bigFrame("A").dataUri); const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 10, - maxTotalBytes: 7000, + maxTotalBytes: bigFrameBytes * 2, + normalizeJpeg: retainFixtureJpeg, }); - cache.put("s", "v1", { durationSeconds: 10, frames: [bigFrame("A")] }); - cache.put("s", "v2", { durationSeconds: 10, frames: [bigFrame("B")] }); - assert.ok(cache.get("s", "v1")); - assert.ok(cache.get("s", "v2")); - cache.put("s", "v3", { durationSeconds: 10, frames: [bigFrame("C")] }); - assert.equal(cache.get("s", "v1"), null, "the least recently used entry must be evicted"); - assert.ok(cache.get("s", "v2")); - assert.ok(cache.get("s", "v3")); - assert.ok(cache.get("s", "v2")); - cache.put("s", "v4", { durationSeconds: 10, frames: [bigFrame("D")] }); - assert.equal(cache.get("s", "v3"), null, "eviction must follow recency, not insertion order"); - assert.ok(cache.get("s", "v2")); - assert.ok(cache.get("s", "v4")); + await cache.put("principal", "s", "v1", drilldownValue([bigFrame("A")])); + await cache.put("principal", "s", "v2", drilldownValue([bigFrame("B")])); + assert.ok(cache.get("principal", "s", "v1")); + assert.ok(cache.get("principal", "s", "v2")); + await cache.put("principal", "s", "v3", drilldownValue([bigFrame("C")])); + assert.equal( + cache.get("principal", "s", "v1"), + null, + "the least recently used entry must be evicted" + ); + assert.ok(cache.get("principal", "s", "v2")); + assert.ok(cache.get("principal", "s", "v3")); + assert.ok(cache.get("principal", "s", "v2")); + await cache.put("principal", "s", "v4", drilldownValue([bigFrame("D")])); + assert.equal( + cache.get("principal", "s", "v3"), + null, + "eviction must follow recency, not insertion order" + ); + assert.ok(cache.get("principal", "s", "v2")); + assert.ok(cache.get("principal", "s", "v4")); }); -test("drill-down cache rejects an entry larger than the whole byte budget", () => { +test("drill-down cache enforces each principal quota without charging another principal", async () => { + const bigFrame = (fill: string): VideoDrilldownFrame => ({ + dataUri: jpegDataUri(320, 180, 3000, fill.charCodeAt(0)), + height: 180, + timestampSeconds: 1, + width: 320, + }); + const bigFrameBytes = retainedBytes(bigFrame("A").dataUri); + const cache = new VideoDrilldownCache({ + now: () => 1000, + ttlMs: 5000, + maxEntries: 10, + maxTotalBytes: bigFrameBytes * 6, + maxBytesPerPrincipal: bigFrameBytes * 2, + maxEntriesPerPrincipal: 2, + normalizeJpeg: retainFixtureJpeg, + }); + await cache.put("principal-a", "s", "v1", drilldownValue([bigFrame("A")])); + await cache.put("principal-a", "s", "v2", drilldownValue([bigFrame("B")])); + await cache.put("principal-b", "s", "v1", drilldownValue([bigFrame("C")])); + await cache.put("principal-b", "s", "v2", drilldownValue([bigFrame("D")])); + assert.ok(cache.get("principal-a", "s", "v1")); + + await cache.put("principal-a", "s", "v3", drilldownValue([bigFrame("E")])); + + assert.equal(cache.get("principal-a", "s", "v2"), null, "principal A must evict its own LRU"); + assert.ok(cache.get("principal-a", "s", "v1")); + assert.ok(cache.get("principal-a", "s", "v3")); + assert.ok(cache.get("principal-b", "s", "v1"), "principal B must keep its independent quota"); + assert.ok(cache.get("principal-b", "s", "v2")); +}); + +test("drill-down cache returns server-derived audit metadata without retaining the raw parent", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + const parentContentHash = `sha256:${"a".repeat(64)}`; + await cache.put("principal", "session", "sensitive-parent-ref", { + derivation: { + parentContentHash, + policy: "focused-window", + version: "video-drilldown/v1", + }, + durationSeconds: 10, + frames: [{ ...frames[0], height: 180, width: 320 }], + }); + + const result = cache.get("principal", "session", "sensitive-parent-ref"); + assert.deepEqual(result?.derivation, { + contentHash: result?.derivation.contentHash, + createdAt: 1000, + format: "image/jpeg", + parent: { + contentHash: parentContentHash, + referenceHash: `sha256:${createHash("sha256").update("sensitive-parent-ref").digest("hex")}`, + }, + policy: "focused-window", + resolution: { height: 180, width: 320 }, + version: "video-drilldown/v1", + }); + assert.match(result?.derivation.contentHash ?? "", /^sha256:[a-f0-9]{64}$/); + assert.equal(JSON.stringify(result).includes("sensitive-parent-ref"), false); +}); + +test("drill-down cache preserves the prior derivation when a replacement fails validation", async () => { + const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4 }); + await cache.put("principal", "session", "video", drilldownValue(frames)); + const before = cache.get("principal", "session", "video"); + const beforeBytes = + before?.frames.reduce((total, frame) => total + retainedBytes(frame.dataUri), 0) ?? 0; + + await assert.rejects( + cache.put("principal", "session", "video", { + derivation: { ...derivation, parentContentHash: "not-a-content-hash" }, + durationSeconds: 10, + frames, + }), + /derivation metadata/i + ); + + assert.deepEqual(cache.get("principal", "session", "video"), before); + assert.deepEqual(cache.getUsage("principal"), { + bytes: beforeBytes, + entries: 1, + totalBytes: beforeBytes, + totalEntries: 1, + }); +}); + +test("drill-down cache aborts during JPEG validation without committing quota", async () => { + let markValidationStarted: () => void = () => {}; + let releaseValidation: () => void = () => {}; + const validationStarted = new Promise((resolve) => { + markValidationStarted = resolve; + }); + const validationRelease = new Promise((resolve) => { + releaseValidation = resolve; + }); + const cache = new VideoDrilldownCache({ + maxEntries: 4, + now: () => 1000, + ttlMs: 5000, + normalizeJpeg: async (data) => { + markValidationStarted(); + await validationRelease; + return { data, height: 180, width: 320 }; + }, + }); + const controller = new AbortController(); + const pending = cache.put("principal", "session", "video", drilldownValue([frames[0]]), { + signal: controller.signal, + }); + + await validationStarted; + controller.abort(); + releaseValidation(); + + await assert.rejects(pending, VideoDrilldownAbortedError); + assert.deepEqual(cache.getUsage("principal"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); +}); + +test("drill-down cache rejects an entry larger than the whole byte budget", async () => { const cache = new VideoDrilldownCache({ now: () => 1000, ttlMs: 5000, maxEntries: 4, maxTotalBytes: 1000, + normalizeJpeg: retainFixtureJpeg, }); - assert.throws( - () => - cache.put("s", "v1", { - durationSeconds: 10, - frames: [{ dataUri: `data:image/jpeg;base64,${"A".repeat(4000)}`, timestampSeconds: 1 }], - }), + await assert.rejects( + cache.put("principal", "s", "v1", { + derivation, + durationSeconds: 10, + frames: [ + { + dataUri: jpegDataUri(320, 180, 4000, 65), + height: 180, + timestampSeconds: 1, + width: 320, + }, + ], + }), /byte budget/i ); - assert.equal(cache.get("s", "v1"), null); + assert.equal(cache.get("principal", "s", "v1"), null); assert.throws( () => new VideoDrilldownCache({ now: () => 0, ttlMs: 1, maxEntries: 1, maxTotalBytes: 0 }), /byte budget/i diff --git a/tests/unit/video-bridge-drilldown-authz.test.ts b/tests/unit/video-bridge-drilldown-authz.test.ts new file mode 100644 index 0000000000..59d4c20204 --- /dev/null +++ b/tests/unit/video-bridge-drilldown-authz.test.ts @@ -0,0 +1,57 @@ +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + buildVideoBridgeDrilldownHeaders, + VIDEO_BRIDGE_DRILLDOWN_PATH, +} from "../../src/lib/guardrails/videoBridgeBrokerAuth.ts"; +import { managementPolicy } from "../../src/server/authz/policies/management.ts"; + +function policyContext(path: string, ip = "127.0.0.1") { + return { + request: { + method: "GET", + headers: new Headers(buildVideoBridgeDrilldownHeaders("principal-a")), + ip, + url: `http://localhost${path}`, + nextUrl: { pathname: path }, + }, + classification: { + routeClass: "MANAGEMENT" as const, + normalizedPath: path, + reason: "management_api", + }, + requestId: "req_video_drilldown_authz", + }; +} + +test("drill-down principal is canonical visible ASCII and is never silently trimmed", () => { + assert.throws(() => buildVideoBridgeDrilldownHeaders(" principal-a "), /principal/i); + assert.throws(() => buildVideoBridgeDrilldownHeaders("principal-á"), /principal/i); + assert.doesNotThrow(() => buildVideoBridgeDrilldownHeaders("tenant:principal-a")); +}); + +test("management policy carries the token-bound drill-down self-hop to the route", async () => { + const outcome = await managementPolicy.evaluate(policyContext(VIDEO_BRIDGE_DRILLDOWN_PATH)); + + assert.equal(outcome.allow, true); + if (outcome.allow) { + assert.equal(outcome.subject.id, "video-bridge-drilldown"); + assert.equal(outcome.subject.label, "internal-video-bridge-drilldown"); + } + + const adjacent = await managementPolicy.evaluate( + policyContext("/api/modality-bridge/video/runtime") + ); + assert.notEqual( + adjacent.allow ? adjacent.subject.label : "rejected", + "internal-video-bridge-drilldown", + "the broker token must not authenticate an adjacent Video Bridge path" + ); + + const remote = await managementPolicy.evaluate( + policyContext(VIDEO_BRIDGE_DRILLDOWN_PATH, "203.0.113.10") + ); + assert.equal(remote.allow, false); + if (!remote.allow) assert.equal(remote.code, "LOCAL_ONLY"); +}); diff --git a/tests/unit/video-bridge-drilldown-route.test.ts b/tests/unit/video-bridge-drilldown-route.test.ts index 6ee9372752..1e92c94abc 100644 --- a/tests/unit/video-bridge-drilldown-route.test.ts +++ b/tests/unit/video-bridge-drilldown-route.test.ts @@ -1,26 +1,92 @@ import assert from "node:assert/strict"; import test from "node:test"; -import { handleVideoDrilldownRequest } from "../../src/app/api/modality-bridge/video/drilldown/route"; -import { buildVideoBridgeBrokerHeaders } from "../../src/lib/guardrails/videoBridgeBrokerAuth"; -import { VideoDrilldownCache } from "../../src/lib/guardrails/videoBridgeDrilldown"; +import sharp from "sharp"; + +import { + handleVideoDrilldownRequest, + VIDEO_DRILLDOWN_MAX_BODY_BYTES, +} from "../../src/app/api/modality-bridge/video/drilldown/route"; +import { + buildVideoBridgeBrokerHeaders, + buildVideoBridgeDrilldownHeaders, + VIDEO_BRIDGE_DRILLDOWN_PRINCIPAL_HEADER, +} from "../../src/lib/guardrails/videoBridgeBrokerAuth"; +import { + VideoDrilldownCache, + VIDEO_DRILLDOWN_MAX_ENTRY_BYTES, +} from "../../src/lib/guardrails/videoBridgeDrilldown"; import { AUTHZ_HEADER_PEER_LOCALITY } from "../../src/server/authz/headers"; import { isLocalOnlyPath } from "../../src/server/authz/routeGuard"; -function headers(contentType?: string): Headers { +const derivation = { + parentContentHash: `sha256:${"a".repeat(64)}`, + policy: "focused-window", + version: "video-drilldown/v1", +}; + +const validJpegs = new Map(); +for (const [width, height] of [ + [320, 180], + [640, 360], +] as const) { + validJpegs.set( + `${width}x${height}`, + await sharp({ + create: { width, height, channels: 3, background: { r: 1, g: 1, b: 1 } }, + }) + .jpeg({ progressive: false }) + .toBuffer() + ); +} + +function jpegDataUri(width: number, height: number, payloadBytes = 0, fill = 0): string { + const base = validJpegs.get(`${width}x${height}`); + if (!base) throw new Error(`Missing valid JPEG fixture for ${width}x${height}`); + if (payloadBytes > 65_531) throw new Error("JPEG fixture comment is too large"); + const bytes = + payloadBytes === 0 + ? base + : Buffer.concat([ + base.subarray(0, -2), + Buffer.from([0xff, 0xfe, (payloadBytes + 2) >> 8, (payloadBytes + 2) & 0xff]), + Buffer.alloc(payloadBytes, fill), + base.subarray(-2), + ]); + return `data:image/jpeg;base64,${bytes.toString("base64")}`; +} + +function headers(principalId: string, contentType?: string): Headers { return new Headers({ - ...buildVideoBridgeBrokerHeaders(), + ...buildVideoBridgeDrilldownHeaders(principalId), [AUTHZ_HEADER_PEER_LOCALITY]: "loopback", ...(contentType ? { "Content-Type": contentType } : {}), }); } +test("drill-down JSON body budget can carry the documented decoded entry ceiling", () => { + const encodedEntryBytes = Math.ceil(VIDEO_DRILLDOWN_MAX_ENTRY_BYTES / 3) * 4; + assert.ok(VIDEO_DRILLDOWN_MAX_BODY_BYTES >= encodedEntryBytes + 64 * 1024); +}); + test("drill-down route is loopback/token protected and has no public fallback", async () => { assert.equal(isLocalOnlyPath("/api/modality-bridge/video/drilldown", "GET"), true); const response = await handleVideoDrilldownRequest( new Request("http://localhost/api/modality-bridge/video/drilldown?sessionId=s&videoRef=v") ); assert.equal(response.status, 403); + + const missingPrincipal = new Headers({ + ...buildVideoBridgeBrokerHeaders(), + [AUTHZ_HEADER_PEER_LOCALITY]: "loopback", + }); + assert.equal(missingPrincipal.has(VIDEO_BRIDGE_DRILLDOWN_PRINCIPAL_HEADER), false); + const missingPrincipalResponse = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown?sessionId=s&videoRef=v", { + headers: missingPrincipal, + }) + ); + assert.equal(missingPrincipalResponse.status, 403); }); test("drill-down route stores, slices, and deletes an isolated session result", async () => { @@ -28,15 +94,22 @@ test("drill-down route stores, slices, and deletes an isolated session result", const post = await handleVideoDrilldownRequest( new Request("http://localhost/api/modality-bridge/video/drilldown", { body: JSON.stringify({ + derivation, durationSeconds: 10, frames: [ - { dataUri: "data:image/jpeg;base64,QQ==", timestampSeconds: 1 }, - { dataUri: "data:image/jpeg;base64,Qg==", timestampSeconds: 5 }, + { + dataUri: jpegDataUri(320, 180, 1, 1), + timestampSeconds: 1, + }, + { + dataUri: jpegDataUri(320, 180, 1, 2), + timestampSeconds: 5, + }, ], sessionId: "session-a", videoRef: "video-a", }), - headers: headers("application/json"), + headers: headers("principal-a", "application/json"), method: "POST", }), { cache } @@ -46,21 +119,318 @@ test("drill-down route stores, slices, and deletes an isolated session result", const get = await handleVideoDrilldownRequest( new Request( "http://localhost/api/modality-bridge/video/drilldown?sessionId=session-a&videoRef=video-a&start=2&end=6&frames=1", - { headers: headers() } + { headers: headers("principal-a") } ), { cache } ); assert.equal(get.status, 200); - assert.deepEqual((await get.json()).frames, [ - { dataUri: "data:image/jpeg;base64,Qg==", timestampSeconds: 5 }, - ]); + const getBody = await get.json(); + assert.equal(getBody.frames.length, 1); + assert.deepEqual( + getBody.frames.map( + ({ + height, + timestampSeconds, + width, + }: { + height: number; + timestampSeconds: number; + width: number; + }) => ({ + height, + timestampSeconds, + width, + }) + ), + [{ height: 180, timestampSeconds: 5, width: 320 }] + ); + assert.match(getBody.frames[0].dataUri, /^data:image\/jpeg;base64,/); + const returnedJpeg = Buffer.from(getBody.frames[0].dataUri.split(",", 2)[1], "base64"); + assert.deepEqual( + await sharp(returnedJpeg) + .metadata() + .then(({ height, width }) => ({ height, width })), + { height: 180, width: 320 } + ); + assert.equal(getBody.derivation.createdAt, 1000); + assert.equal(getBody.derivation.format, "image/jpeg"); + assert.equal(getBody.derivation.parent.contentHash, derivation.parentContentHash); + assert.deepEqual(getBody.derivation.resolution, { height: 180, width: 320 }); + assert.match(getBody.derivation.contentHash, /^sha256:[a-f0-9]{64}$/); const deleted = await handleVideoDrilldownRequest( new Request("http://localhost/api/modality-bridge/video/drilldown?sessionId=session-a", { - headers: headers(), + headers: headers("principal-a"), method: "DELETE", }), { cache } ); assert.deepEqual(await deleted.json(), { removed: 1 }); }); + +test("drill-down route denies cross-principal reads and deletes without enumerating", async () => { + const cache = new VideoDrilldownCache({ maxEntries: 4, now: () => 1000, ttlMs: 5000 }); + const body = JSON.stringify({ + derivation, + durationSeconds: 10, + frames: [ + { + dataUri: jpegDataUri(320, 180), + timestampSeconds: 1, + }, + ], + sessionId: "shared-session", + videoRef: "shared-video", + }); + const stored = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown", { + body, + headers: headers("principal-a", "application/json"), + method: "POST", + }), + { cache } + ); + assert.equal(stored.status, 201); + + const deniedRead = await handleVideoDrilldownRequest( + new Request( + "http://localhost/api/modality-bridge/video/drilldown?sessionId=shared-session&videoRef=shared-video", + { headers: headers("principal-b") } + ), + { cache } + ); + assert.equal(deniedRead.status, 404); + + const deniedDelete = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown?sessionId=shared-session", { + headers: headers("principal-b"), + method: "DELETE", + }), + { cache } + ); + assert.deepEqual(await deniedDelete.json(), { removed: 0 }); + + const ownerRead = await handleVideoDrilldownRequest( + new Request( + "http://localhost/api/modality-bridge/video/drilldown?sessionId=shared-session&videoRef=shared-video", + { headers: headers("principal-a") } + ), + { cache } + ); + assert.equal(ownerRead.status, 200); +}); + +test("drill-down route does not retain a cancelled derivation", async () => { + const cache = new VideoDrilldownCache({ maxEntries: 4, now: () => 1000, ttlMs: 5000 }); + const controller = new AbortController(); + controller.abort(); + const response = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown", { + body: JSON.stringify({ + derivation, + durationSeconds: 10, + frames: [ + { + dataUri: jpegDataUri(320, 180), + timestampSeconds: 1, + }, + ], + sessionId: "cancelled-session", + videoRef: "cancelled-video", + }), + headers: headers("principal-a", "application/json"), + method: "POST", + signal: controller.signal, + }), + { cache } + ); + + assert.equal(response.status, 499); + assert.deepEqual(cache.getUsage("principal-a"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); +}); + +test("drill-down route cancels an in-flight JPEG validation before cache commit", async () => { + let markValidationStarted: () => void = () => {}; + let releaseValidation: () => void = () => {}; + const validationStarted = new Promise((resolve) => { + markValidationStarted = resolve; + }); + const validationRelease = new Promise((resolve) => { + releaseValidation = resolve; + }); + const cache = new VideoDrilldownCache({ + maxEntries: 4, + now: () => 1000, + ttlMs: 5000, + normalizeJpeg: async (data) => { + markValidationStarted(); + await validationRelease; + return { data, height: 180, width: 320 }; + }, + }); + const controller = new AbortController(); + const pending = handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown", { + body: JSON.stringify({ + derivation, + durationSeconds: 10, + frames: [{ dataUri: jpegDataUri(320, 180), timestampSeconds: 1 }], + sessionId: "cancelled-session", + videoRef: "cancelled-video", + }), + headers: headers("principal-a", "application/json"), + method: "POST", + signal: controller.signal, + }), + { cache } + ); + + await validationStarted; + controller.abort(); + releaseValidation(); + + const response = await pending; + assert.equal(response.status, 499); + assert.deepEqual(cache.getUsage("principal-a"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); +}); + +test("drill-down route rejects raw media instead of silently retaining it", async () => { + const cache = new VideoDrilldownCache({ maxEntries: 4, now: () => 1000, ttlMs: 5000 }); + const response = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown", { + body: JSON.stringify({ + derivation, + durationSeconds: 10, + frames: [ + { + dataUri: jpegDataUri(320, 180), + timestampSeconds: 1, + }, + ], + rawMedia: "data:video/mp4;base64,AAAA", + sessionId: "raw-session", + videoRef: "raw-video", + }), + headers: headers("principal-a", "application/json"), + method: "POST", + }), + { cache } + ); + + assert.equal(response.status, 400); + assert.equal(cache.getUsage("principal-a").entries, 0); +}); + +test("drill-down route rejects padded Base64, disguised media, and caller dimensions", async () => { + const cache = new VideoDrilldownCache({ maxEntries: 4, now: () => 1000, ttlMs: 5000 }); + const mp4 = Buffer.concat([ + Buffer.from([0, 0, 0, 24]), + Buffer.from("ftypisom", "ascii"), + ]).toString("base64"); + const invalidFrames: Array> = [ + { dataUri: `${jpegDataUri(320, 180)}${"=".repeat(1024 * 1024)}`, timestampSeconds: 1 }, + { dataUri: `data:image/jpeg;base64,${mp4}`, timestampSeconds: 1 }, + { dataUri: "data:image/jpeg;base64,/9hBQkP/wAAHCAABAAE=", timestampSeconds: 1 }, + { dataUri: jpegDataUri(320, 180), height: 1, timestampSeconds: 1, width: 1 }, + ]; + + for (const [index, frame] of invalidFrames.entries()) { + const response = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown", { + body: JSON.stringify({ + derivation, + durationSeconds: 10, + frames: [frame], + sessionId: `invalid-session-${index}`, + videoRef: `invalid-video-${index}`, + }), + headers: headers("principal-a", "application/json"), + method: "POST", + }), + { cache } + ); + assert.equal(response.status, 400); + } + + assert.equal(cache.getUsage("principal-a").entries, 0); +}); + +test("drill-down route rejects non-canonical session and video identifiers consistently", async () => { + const cache = new VideoDrilldownCache({ maxEntries: 4, now: () => 1000, ttlMs: 5000 }); + const post = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown", { + body: JSON.stringify({ + derivation, + durationSeconds: 10, + frames: [{ dataUri: jpegDataUri(320, 180), timestampSeconds: 1 }], + sessionId: " session-a ", + videoRef: " video-a ", + }), + headers: headers("principal-a", "application/json"), + method: "POST", + }), + { cache } + ); + assert.equal(post.status, 400); + + const get = await handleVideoDrilldownRequest( + new Request( + "http://localhost/api/modality-bridge/video/drilldown?sessionId=%20session-a%20&videoRef=%20video-a%20", + { headers: headers("principal-a") } + ), + { cache } + ); + assert.equal(get.status, 400); + + const deleted = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown?sessionId=%20session-a%20", { + headers: headers("principal-a"), + method: "DELETE", + }), + { cache } + ); + assert.equal(deleted.status, 400); + assert.deepEqual(cache.getUsage("principal-a"), { + bytes: 0, + entries: 0, + totalBytes: 0, + totalEntries: 0, + }); +}); + +test("drill-down route maps unexpected cache failures to a sanitized 500", async () => { + class FailingCache extends VideoDrilldownCache { + override async put(..._args: Parameters): Promise { + throw new Error("secret failure at /tmp/internal/drilldown.ts:42"); + } + } + const cache = new FailingCache({ maxEntries: 4, now: () => 1000, ttlMs: 5000 }); + const response = await handleVideoDrilldownRequest( + new Request("http://localhost/api/modality-bridge/video/drilldown", { + body: JSON.stringify({ + derivation, + durationSeconds: 10, + frames: [{ dataUri: jpegDataUri(320, 180), timestampSeconds: 1 }], + sessionId: "session-a", + videoRef: "video-a", + }), + headers: headers("principal-a", "application/json"), + method: "POST", + }), + { cache } + ); + + assert.equal(response.status, 500); + const text = await response.text(); + assert.doesNotMatch(text, /secret failure|\/tmp\/internal|drilldown\.ts/i); +});