ColeMurray
diff --git a/‎packages/control-plane/src/media.test.ts‎
Lines changed: 102 additions & 0 deletions b/‎packages/control-plane/src/media.test.ts‎
Lines changed: 102 additions & 0 deletions
diff --git a/‎packages/control-plane/src/media.ts‎
Lines changed: 200 additions & 0 deletions b/‎packages/control-plane/src/media.ts‎
Lines changed: 200 additions & 0 deletions
@@ -2,11 +2,19 @@ import { describe, expect, it } from "vitest";
 import {
   buildMediaObjectKey,
   detectScreenshotFileType,
+  detectVideoFileType,
   isSupportedScreenshotMimeType,
+  isSupportedVideoMimeType,
   parseOptionalBoolean,
   parseOptionalViewport,
+  parseVideoUploadMetadata,
 } from "./media";
 
+const MP4_SIGNATURE = Uint8Array.from([
+  0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70, 0x69, 0x73, 0x6f, 0x6d, 0x00, 0x00, 0x02, 0x00,
+  0x69, 0x73, 0x6f, 0x6d, 0x69, 0x73, 0x6f, 0x32,
+]);
+
 describe("media helpers", () => {
   it("builds session-scoped media object keys", () => {
     expect(buildMediaObjectKey("session-1", "artifact-1", "png")).toBe(
@@ -21,6 +29,100 @@ describe("media helpers", () => {
     expect(isSupportedScreenshotMimeType("image/gif")).toBe(false);
   });
 
+  it("accepts only supported video mime types", () => {
+    expect(isSupportedVideoMimeType("video/mp4")).toBe(true);
+    expect(isSupportedVideoMimeType("video/webm")).toBe(false);
+  });
+
+  it("detects MP4 videos by ISO BMFF file type bytes", () => {
+    expect(detectVideoFileType(MP4_SIGNATURE)).toEqual({
+      mimeType: "video/mp4",
+      extension: "mp4",
+    });
+  });
+
+  it("parses required video metadata", () => {
+    const formData = new FormData();
+    formData.set("caption", "Menu opens after clicking settings");
+    formData.set("durationMs", "2500");
+    formData.set("recordingStartedAt", "1000");
+    formData.set("recordingEndedAt", "3500");
+    formData.set("dimensions", '{"width":1280,"height":720}');
+    formData.set("truncated", "false");
+    formData.set("sourceUrl", "https://example.com/start");
+    formData.set("endUrl", "https://example.com/end");
+    formData.set("hasAudio", "false");
+
+    expect(parseVideoUploadMetadata(formData, 4000)).toEqual({
+      caption: "Menu opens after clicking settings",
+      durationMs: 2500,
+      createdAt: 4000,
+      recordingStartedAt: 1000,
+      recordingEndedAt: 3500,
+      dimensions: { width: 1280, height: 720 },
+      truncated: false,
+      sourceUrl: "https://example.com/start",
+      endUrl: "https://example.com/end",
+      hasAudio: false,
+      captureSurface: "browser",
+      source: "agent",
+    });
+  });
+
+  it.each([
+    ["missing caption", { caption: "" }, "caption is required"],
+    ["non-positive duration", { durationMs: "0" }, "durationMs must be a positive number"],
+    ["decimal duration", { durationMs: "2500.5" }, "durationMs must be a positive integer"],
+    ["exponent duration", { durationMs: "1e3" }, "durationMs must be a positive integer"],
+    [
+      "unsafe duration integer",
+      { durationMs: "9007199254740992" },
+      "durationMs must be a safe integer",
+    ],
+    [
+      "non-finite timestamp integer",
+      { recordingStartedAt: "1".padEnd(310, "0") },
+      "recordingStartedAt must be a safe integer",
+    ],
+    ["duration above maximum", { durationMs: "90001" }, "durationMs must be 90000 or less"],
+    [
+      "invalid dimensions",
+      { dimensions: '{"width":0,"height":720}' },
+      "dimensions must include positive integer width and height",
+    ],
+    [
+      "fractional dimensions",
+      { dimensions: '{"width":0.4,"height":720}' },
+      "dimensions must include positive integer width and height",
+    ],
+    ["invalid source URL", { sourceUrl: "not-a-url" }, "sourceUrl must be a valid URL"],
+    ["audio present", { hasAudio: "true" }, "hasAudio must be false"],
+    [
+      "timestamp span above maximum",
+      { recordingEndedAt: "93001" },
+      "recording timestamps must span 90000ms or less",
+    ],
+    [
+      "duration exceeds timestamp span",
+      { durationMs: "5000" },
+      "durationMs must not exceed the recording timestamp span",
+    ],
+  ])("rejects invalid video metadata: %s", (_label, overrides, message) => {
+    const formData = new FormData();
+    formData.set("caption", "Menu opens after clicking settings");
+    formData.set("durationMs", "2500");
+    formData.set("recordingStartedAt", "1000");
+    formData.set("recordingEndedAt", "3500");
+    formData.set("dimensions", '{"width":1280,"height":720}');
+    formData.set("truncated", "false");
+
+    for (const [name, value] of Object.entries(overrides)) {
+      formData.set(name, value);
+    }
+
+    expect(() => parseVideoUploadMetadata(formData, 4000)).toThrow(message);
+  });
+
   it.each([
     [
       "PNG",
 
@@ -1,31 +1,59 @@
+import type { VideoArtifactMetadata } from "@open-inspect/shared";
+
 export const SCREENSHOT_MAX_BYTES = 10 * 1024 * 1024;
 export const SCREENSHOT_UPLOAD_LIMIT_PER_SESSION = 100;
+export const VIDEO_MAX_BYTES = 100 * 1024 * 1024;
+export const VIDEO_UPLOAD_LIMIT_PER_SESSION = 20;
+export const VIDEO_MAX_DURATION_MS = 90_000;
+export const VIDEO_TIMESTAMP_TOLERANCE_MS = 1_000;
 
 const SCREENSHOT_EXTENSIONS = {
   "image/png": "png",
   "image/jpeg": "jpg",
   "image/webp": "webp",
 } as const;
 
+const VIDEO_EXTENSIONS = {
+  "video/mp4": "mp4",
+} as const;
+
 export type SupportedScreenshotMimeType = keyof typeof SCREENSHOT_EXTENSIONS;
+export type SupportedVideoMimeType = keyof typeof VIDEO_EXTENSIONS;
 
 export interface ScreenshotFileType {
   mimeType: SupportedScreenshotMimeType;
   extension: (typeof SCREENSHOT_EXTENSIONS)[SupportedScreenshotMimeType];
 }
 
+export interface VideoFileType {
+  mimeType: SupportedVideoMimeType;
+  extension: (typeof VIDEO_EXTENSIONS)[SupportedVideoMimeType];
+}
+
 export interface MultipartFileLike {
   size: number;
   type: string;
   arrayBuffer(): Promise<ArrayBuffer>;
 }
 
 export type MultipartFieldValue = string | MultipartFileLike;
+export type VideoUploadMetadata = Omit<
+  VideoArtifactMetadata,
+  "objectKey" | "mimeType" | "sizeBytes"
+>;
+
+export interface MultipartFieldsLike {
+  get(name: string): MultipartFieldValue | null;
+}
 
 export function isSupportedScreenshotMimeType(value: string): value is SupportedScreenshotMimeType {
   return value in SCREENSHOT_EXTENSIONS;
 }
 
+export function isSupportedVideoMimeType(value: string): value is SupportedVideoMimeType {
+  return value in VIDEO_EXTENSIONS;
+}
+
 export function detectScreenshotFileType(bytes: Uint8Array): ScreenshotFileType | null {
   if (bytes.length >= 8 && hasPrefix(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
     return { mimeType: "image/png", extension: "png" };
@@ -46,6 +74,18 @@ export function detectScreenshotFileType(bytes: Uint8Array): ScreenshotFileType
   return null;
 }
 
+export function detectVideoFileType(bytes: Uint8Array): VideoFileType | null {
+  if (
+    bytes.length >= 12 &&
+    hasPrefix(bytes.slice(4, 8), [0x66, 0x74, 0x79, 0x70]) &&
+    isMp4CompatibleBrand(bytes.slice(8, 12))
+  ) {
+    return { mimeType: "video/mp4", extension: "mp4" };
+  }
+
+  return null;
+}
+
 export function buildMediaObjectKey(
   sessionId: string,
   artifactId: string,
@@ -112,6 +152,166 @@ export function parseOptionalViewport(
   };
 }
 
+export function parseVideoUploadMetadata(
+  fields: MultipartFieldsLike,
+  createdAt = Date.now()
+): VideoUploadMetadata {
+  const caption = parseRequiredString(fields.get("caption"), "caption");
+  const durationMs = parseRequiredPositiveInteger(fields.get("durationMs"), "durationMs");
+  if (durationMs > VIDEO_MAX_DURATION_MS) {
+    throw new Error(`durationMs must be ${VIDEO_MAX_DURATION_MS} or less`);
+  }
+
+  const recordingStartedAt = parseRequiredPositiveInteger(
+    fields.get("recordingStartedAt"),
+    "recordingStartedAt"
+  );
+  const recordingEndedAt = parseRequiredPositiveInteger(
+    fields.get("recordingEndedAt"),
+    "recordingEndedAt"
+  );
+  if (recordingEndedAt < recordingStartedAt) {
+    throw new Error("recordingEndedAt must be greater than or equal to recordingStartedAt");
+  }
+  const elapsedMs = recordingEndedAt - recordingStartedAt;
+  if (elapsedMs > VIDEO_MAX_DURATION_MS + VIDEO_TIMESTAMP_TOLERANCE_MS) {
+    throw new Error(`recording timestamps must span ${VIDEO_MAX_DURATION_MS}ms or less`);
+  }
+  if (durationMs > elapsedMs + VIDEO_TIMESTAMP_TOLERANCE_MS) {
+    throw new Error("durationMs must not exceed the recording timestamp span");
+  }
+
+  const dimensions = parseRequiredDimensions(fields.get("dimensions"));
+  const truncated = parseRequiredBoolean(fields.get("truncated"), "truncated");
+  const sourceUrl = parseOptionalUrl(fields.get("sourceUrl"), "sourceUrl");
+  const endUrl = parseOptionalUrl(fields.get("endUrl"), "endUrl");
+  const hasAudio = parseOptionalBoolean(fields.get("hasAudio"));
+  if (hasAudio === true) {
+    throw new Error("hasAudio must be false");
+  }
+
+  return {
+    caption,
+    durationMs,
+    createdAt,
+    recordingStartedAt,
+    recordingEndedAt,
+    dimensions,
+    truncated,
+    ...(sourceUrl ? { sourceUrl } : {}),
+    ...(endUrl ? { endUrl } : {}),
+    ...(hasAudio === false ? { hasAudio: false } : {}),
+    captureSurface: "browser",
+    source: "agent",
+  };
+}
+
 function hasPrefix(bytes: Uint8Array, prefix: number[]): boolean {
   return prefix.every((value, index) => bytes[index] === value);
 }
+
+function isMp4CompatibleBrand(brand: Uint8Array): boolean {
+  if (brand.length < 4) return false;
+  const value = String.fromCharCode(...brand);
+  return (
+    value === "isom" ||
+    value === "iso2" ||
+    value === "mp41" ||
+    value === "mp42" ||
+    value === "avc1" ||
+    value === "M4V "
+  );
+}
+
+function parseRequiredString(value: MultipartFieldValue | null, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} is required`);
+  }
+
+  return value.trim();
+}
+
+function parseRequiredPositiveInteger(value: MultipartFieldValue | null, name: string): number {
+  const stringValue = parseRequiredString(value, name);
+  if (stringValue === "0") {
+    throw new Error(`${name} must be a positive number`);
+  }
+  if (!/^[1-9]\d*$/.test(stringValue)) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+
+  const parsed = Number(stringValue);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`${name} must be a safe integer`);
+  }
+
+  return parsed;
+}
+
+function parseRequiredBoolean(value: MultipartFieldValue | null, name: string): boolean {
+  if (value === null) {
+    throw new Error(`${name} is required`);
+  }
+
+  return parseOptionalBoolean(value) ?? false;
+}
+
+function parseRequiredDimensions(value: MultipartFieldValue | null): {
+  width: number;
+  height: number;
+} {
+  if (value === null) {
+    throw new Error("dimensions is required");
+  }
+
+  if (typeof value !== "string") {
+    throw new Error("dimensions must be a JSON string");
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("dimensions must be valid JSON");
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("dimensions must be an object");
+  }
+
+  const candidate = parsed as { width?: unknown; height?: unknown };
+  if (
+    typeof candidate.width !== "number" ||
+    !Number.isFinite(candidate.width) ||
+    !Number.isInteger(candidate.width) ||
+    candidate.width <= 0 ||
+    typeof candidate.height !== "number" ||
+    !Number.isFinite(candidate.height) ||
+    !Number.isInteger(candidate.height) ||
+    candidate.height <= 0
+  ) {
+    throw new Error("dimensions must include positive integer width and height");
+  }
+
+  return {
+    width: candidate.width,
+    height: candidate.height,
+  };
+}
+
+function parseOptionalUrl(value: MultipartFieldValue | null, name: string): string | undefined {
+  if (value === null) return undefined;
+  if (typeof value !== "string") {
+    throw new Error(`${name} must be a string`);
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  try {
+    new URL(trimmed);
+  } catch {
+    throw new Error(`${name} must be a valid URL`);
+  }
+
+  return trimmed;
+}