@agent-native/core 0.109.0 → 0.109.2

package/corpus/templates/clips/server/routes/api/thumbnail/[recordingId].get.ts

@@ -0,0 +1,340 @@
+/**
+ * Serve a recording thumbnail from the same origin as the public player.
+ *
+ * Thumbnail providers may return expiring or hotlink-protected URLs. Public
+ * share pages already proxy video through `/api/video/:recordingId`; using the
+ * same contract here keeps embeds and crawler previews reliable.
+ */
+
+import {
+  createSsrfSafeDispatcher,
+  isBlockedExtensionUrlWithDns,
+} from "@agent-native/core/extensions/url-safety";
+import { getOrgContext } from "@agent-native/core/org";
+import {
+  captureRouteError,
+  getSession,
+  runWithRequestContext,
+  signShortLivedToken,
+  verifyShortLivedToken,
+} from "@agent-native/core/server";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import {
+  defineEventHandler,
+  getCookie,
+  getQuery,
+  getRequestURL,
+  getRouterParam,
+  setCookie,
+  setResponseStatus,
+  type H3Event,
+} from "h3";
+
+import { getDb, schema } from "../../../db/index.js";
+import { getOrganizationRoleForEmail } from "../../../lib/recordings.js";
+import { verifySharePassword } from "../../../lib/share-password.js";
+
+const FETCH_TIMEOUT_MS = 30_000;
+const PROTECTED_MEDIA_ACCESS_TTL_SECONDS = 6 * 60 * 60;
+const PROTECTED_MEDIA_COOKIE_PREFIX = "clips_media_";
+const SAFE_RASTER_IMAGE_TYPES = new Set([
+  "image/avif",
+  "image/bmp",
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/x-icon",
+]);
+
+type ThumbnailRecording = {
+  id: string;
+  thumbnailUrl?: string | null;
+  animatedThumbnailUrl?: string | null;
+  expiresAt?: string | null;
+  organizationId?: string | null;
+  password?: string | null;
+  visibility?: string | null;
+};
+
+function appPath(path: string): string {
+  if (!path.startsWith("/")) return path;
+  const raw = process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH || "";
+  const base = raw.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+  return base ? `/${base}${path}` : path;
+}
+
+function cookieName(recordingId: string): string {
+  return `${PROTECTED_MEDIA_COOKIE_PREFIX}${recordingId.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+}
+
+function cookiePath(recordingId: string): string {
+  return appPath(`/api/thumbnail/${encodeURIComponent(recordingId)}`);
+}
+
+function isHttpsRequest(event: H3Event): boolean {
+  const requestUrl = getRequestURL(event);
+  return (
+    requestUrl.protocol === "https:" ||
+    process.env.APP_URL?.startsWith("https://") === true
+  );
+}
+
+function renewProtectedMediaCookie(event: H3Event, recordingId: string): void {
+  const token = signShortLivedToken({
+    resourceId: recordingId,
+    ttlSeconds: PROTECTED_MEDIA_ACCESS_TTL_SECONDS,
+  });
+  const secure = isHttpsRequest(event);
+  setCookie(event, cookieName(recordingId), token, {
+    httpOnly: true,
+    sameSite: secure ? "none" : "lax",
+    secure,
+    ...(secure ? { partitioned: true } : {}),
+    path: cookiePath(recordingId),
+    maxAge: PROTECTED_MEDIA_ACCESS_TTL_SECONDS,
+  });
+}
+
+function isRecursiveThumbnailUrl(value: string, recordingId: string): boolean {
+  try {
+    const parsed = new URL(value, "http://local.test");
+    const expected = `/api/thumbnail/${encodeURIComponent(recordingId)}`;
+    return parsed.pathname === expected || parsed.pathname.endsWith(expected);
+  } catch {
+    return false;
+  }
+}
+
+function dataUrlResponse(sourceUrl: string): Response | null {
+  const match = sourceUrl.match(/^data:(image\/[\w.+-]+)(;base64)?,(.*)$/s);
+  if (!match) return null;
+
+  const [, rawMimeType, encoding, payload] = match;
+  const mimeType = rawMimeType.toLowerCase();
+  if (!SAFE_RASTER_IMAGE_TYPES.has(mimeType)) return null;
+  try {
+    const bytes = encoding
+      ? decodeBase64(payload)
+      : new TextEncoder().encode(decodeURIComponent(payload));
+    return imageResponse(bytes, mimeType);
+  } catch {
+    return null;
+  }
+}
+
+function decodeBase64(value: string): Uint8Array<ArrayBuffer> {
+  const binary = globalThis.atob(value);
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let index = 0; index < binary.length; index++) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+function imageResponse(
+  body: BodyInit | null,
+  mimeType: string,
+  status = 200,
+): Response {
+  const headers = new Headers({
+    "Content-Type": mimeType,
+    "Cache-Control": "private, max-age=0, no-store",
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+  });
+  return new Response(body, { status, headers });
+}
+
+async function fetchThumbnail(sourceUrl: string): Promise<Response> {
+  let currentUrl = sourceUrl;
+  const dispatcher = (await createSsrfSafeDispatcher()) ?? undefined;
+
+  for (let redirects = 0; redirects <= 4; redirects++) {
+    if (await isBlockedExtensionUrlWithDns(currentUrl)) {
+      return imageResponse(null, "text/plain", 403);
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    let upstream: Response;
+    try {
+      const fetchOptions: RequestInit & { dispatcher?: unknown } = {
+        redirect: "manual",
+        signal: controller.signal,
+      };
+      if (dispatcher) fetchOptions.dispatcher = dispatcher;
+      upstream = await fetch(currentUrl, fetchOptions);
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    if (upstream.status < 300 || upstream.status >= 400) {
+      const contentType =
+        upstream.headers
+          .get("content-type")
+          ?.split(";", 1)[0]
+          ?.trim()
+          .toLowerCase() ?? "";
+      if (!SAFE_RASTER_IMAGE_TYPES.has(contentType)) {
+        await upstream.body?.cancel().catch(() => {});
+        return imageResponse(
+          null,
+          "text/plain; charset=utf-8",
+          upstream.ok ? 415 : upstream.status,
+        );
+      }
+      return imageResponse(upstream.body, contentType, upstream.status);
+    }
+
+    const location = upstream.headers.get("location");
+    await upstream.body?.cancel().catch(() => {});
+    if (!location) return imageResponse(null, "text/plain", upstream.status);
+    currentUrl = new URL(location, currentUrl).href;
+  }
+
+  return imageResponse(null, "text/plain", 508);
+}
+
+async function loadRecording(recordingId: string, event: H3Event) {
+  const access = await resolveAccess("recording", recordingId);
+  let recording = (access?.resource as ThumbnailRecording | undefined) ?? null;
+  const role = access?.role ?? null;
+  const session = await getSession(event).catch(() => null);
+
+  if (!recording) {
+    const [row] = await getDb()
+      .select({
+        id: schema.recordings.id,
+        thumbnailUrl: schema.recordings.thumbnailUrl,
+        animatedThumbnailUrl: schema.recordings.animatedThumbnailUrl,
+        expiresAt: schema.recordings.expiresAt,
+        organizationId: schema.recordings.organizationId,
+        password: schema.recordings.password,
+        visibility: schema.recordings.visibility,
+      })
+      .from(schema.recordings)
+      .where(eq(schema.recordings.id, recordingId))
+      .limit(1);
+
+    if (!row) return { error: "Not found", status: 404 } as const;
+
+    let viewerIsOrgMember = false;
+    if (session?.email && row.visibility === "org" && row.organizationId) {
+      const orgRole = await getOrganizationRoleForEmail(
+        row.organizationId,
+        session.email,
+      ).catch(() => null);
+      viewerIsOrgMember = Boolean(orgRole);
+    }
+    if (row.visibility !== "public" && !viewerIsOrgMember) {
+      return { error: "Not found", status: 404 } as const;
+    }
+
+    recording = row;
+  }
+
+  return { recording, role } as const;
+}
+
+export default defineEventHandler(async (event: H3Event) => {
+  const recordingId = getRouterParam(event, "recordingId");
+  if (!recordingId) {
+    setResponseStatus(event, 400);
+    return { error: "Missing recordingId" };
+  }
+
+  const session = await getSession(event).catch(() => null);
+  const orgCtx = await getOrgContext(event).catch(() => null);
+
+  return runWithRequestContext(
+    { userEmail: session?.email, orgId: orgCtx?.orgId ?? session?.orgId },
+    async () => {
+      const loaded = await loadRecording(recordingId, event);
+      if ("error" in loaded) {
+        setResponseStatus(event, loaded.status);
+        return { error: loaded.error };
+      }
+
+      const { recording } = loaded;
+      if (recording.expiresAt) {
+        const expires = new Date(recording.expiresAt).getTime();
+        if (Number.isFinite(expires) && expires < Date.now()) {
+          setResponseStatus(event, 410);
+          return { error: "Recording has expired" };
+        }
+      }
+
+      const query = getQuery(event) as {
+        password?: unknown;
+        t?: unknown;
+      };
+      if (recording.password && loaded.role !== "owner") {
+        const queryToken = typeof query.t === "string" ? query.t : "";
+        const cookieToken = getCookie(event, cookieName(recordingId)) ?? "";
+        const password =
+          typeof query.password === "string" ? query.password : "";
+        const allowed =
+          (queryToken && verifyShortLivedToken(queryToken, recordingId).ok) ||
+          (cookieToken && verifyShortLivedToken(cookieToken, recordingId).ok) ||
+          (password && verifySharePassword(password, recording.password));
+        if (!allowed) {
+          setResponseStatus(event, 401);
+          return { error: "Password required", passwordRequired: true };
+        }
+        renewProtectedMediaCookie(event, recordingId);
+      }
+
+      const sourceUrl =
+        recording.thumbnailUrl || recording.animatedThumbnailUrl;
+      if (!sourceUrl) {
+        setResponseStatus(event, 404);
+        return { error: "Thumbnail not found" };
+      }
+
+      if (sourceUrl.startsWith("data:")) {
+        return (
+          dataUrlResponse(sourceUrl) ??
+          imageResponse(null, "text/plain; charset=utf-8", 415)
+        );
+      }
+      if (isRecursiveThumbnailUrl(sourceUrl, recordingId)) {
+        setResponseStatus(event, 404);
+        return { error: "Thumbnail not found" };
+      }
+
+      let resolvedSourceUrl = sourceUrl;
+      if (sourceUrl.startsWith("/")) {
+        resolvedSourceUrl = new URL(sourceUrl, getRequestURL(event).origin)
+          .href;
+      }
+
+      try {
+        const response = await fetchThumbnail(resolvedSourceUrl);
+        if (response.status >= 500) {
+          captureRouteError(
+            new Error(
+              `Storage provider returned ${response.status} for thumbnail`,
+            ),
+            {
+              route: "api/thumbnail",
+              tags: { upstreamStatus: String(response.status) },
+              extra: { recordingId },
+            },
+          );
+          setResponseStatus(event, 502);
+          return { error: "The recording thumbnail could not be loaded." };
+        }
+        return response;
+      } catch (error) {
+        captureRouteError(error, {
+          route: "api/thumbnail",
+          extra: { recordingId },
+        });
+        setResponseStatus(event, 502);
+        return { error: "The recording thumbnail could not be loaded." };
+      }
+    },
+  );
+});

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/abort.post.ts

@@ -6,6 +6,7 @@
  */
 
 import {
+  deleteAppState,
   readAppState,
   writeAppState,
   deleteAppStateByPrefix,
@@ -22,6 +23,7 @@ import {
 } from "h3";
 
 import { getDb, schema } from "../../../../db/index.js";
+import { mediaVerificationStateKey } from "../../../../lib/media-verification-state.js";
 import {
   getEventOwnerContext,
   ownerEmailMatches,
@@ -75,6 +77,25 @@ export default defineEventHandler(async (event: H3Event) => {
       return { ok: true, recordingId, alreadyReady: true, chunksCleared: 0 };
     }
 
+    const existingUploadStateRaw = await readAppState(
+      `recording-upload-${recordingId}`,
+    ).catch(() => null);
+    const existingUploadState =
+      existingUploadStateRaw && typeof existingUploadStateRaw === "object"
+        ? (existingUploadStateRaw as Record<string, unknown>)
+        : {};
+    if (
+      existing.status === "processing" &&
+      existingUploadState.pendingMediaVerification === true
+    ) {
+      return {
+        ok: true,
+        recordingId,
+        verificationPending: true,
+        chunksCleared: 0,
+      };
+    }
+
     const preserveRecoveryState =
       isStoredButUnservableFinalizeError(failureReason) ||
       isStoredButUnservableFinalizeError(existing.failureReason);
@@ -104,13 +125,6 @@ export default defineEventHandler(async (event: H3Event) => {
       })
       .where(eq(schema.recordings.id, recordingId));
 
-    const existingUploadStateRaw = await readAppState(
-      `recording-upload-${recordingId}`,
-    ).catch(() => null);
-    const existingUploadState =
-      existingUploadStateRaw && typeof existingUploadStateRaw === "object"
-        ? (existingUploadStateRaw as Record<string, unknown>)
-        : {};
     await writeAppState(`recording-upload-${recordingId}`, {
       ...existingUploadState,
       recordingId,
@@ -118,6 +132,9 @@ export default defineEventHandler(async (event: H3Event) => {
       failureReason,
       updatedAt: now,
     });
+    await deleteAppState(mediaVerificationStateKey(recordingId)).catch(
+      () => {},
+    );
 
     const cleared = preserveRecoveryState
       ? 0

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/chunk.post.ts

@@ -101,6 +101,37 @@ function stateNumber(
   return typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
 }
 
+function pendingMediaVerificationState(
+  value: unknown,
+): Record<string, unknown> | null {
+  if (!value || typeof value !== "object") return null;
+  const state = value as Record<string, unknown>;
+  return state.status === "processing" &&
+    state.pendingMediaVerification === true
+    ? state
+    : null;
+}
+
+function acceptedProcessingResponse(
+  event: H3Event,
+  recordingId: string,
+  state: Record<string, unknown>,
+) {
+  setResponseStatus(event, 202);
+  return {
+    ok: true,
+    finalized: false,
+    verificationPending: true,
+    status: "processing" as const,
+    retryAfterMs: 3_000,
+    id: recordingId,
+    videoUrl: typeof state.videoUrl === "string" ? state.videoUrl : undefined,
+    videoSizeBytes: stateNumber(state, "videoSizeBytes"),
+    sourceSizeBytes: stateNumber(state, "sourceSizeBytes"),
+    durationMs: stateNumber(state, "durationMs"),
+  };
+}
+
 function expectedDataChunksForFinalPost(
   index: number,
   bodySize: number,
@@ -216,6 +247,15 @@ export default defineEventHandler(async (event: H3Event) => {
       throw createError({ statusCode: 404, message: "Recording not found" });
     }
 
+    if (isFinal && existing.status === "processing") {
+      const pendingState = pendingMediaVerificationState(
+        await readAppState(`recording-upload-${recordingId}`).catch(() => null),
+      );
+      if (pendingState) {
+        return acceptedProcessingResponse(event, recordingId, pendingState);
+      }
+    }
+
     // Resumable streaming path — forward chunks directly to the provider.
     const resumableSession = await getResumableSession(recordingId);
     if (resumableSession && isStreamingUploadDisabled()) {
@@ -567,13 +607,17 @@ export default defineEventHandler(async (event: H3Event) => {
         const waitingForStorage =
           (result as any)?.status === "waiting_storage" ||
           (result as any)?.storageSetupRequired === true;
-        if (waitingForStorage) {
+        const verificationPending =
+          (result as any)?.status === "processing" &&
+          (result as any)?.verificationPending === true;
+        if (waitingForStorage || verificationPending) {
           setResponseStatus(event, 202);
         }
         return {
           ok: true,
-          finalized: !waitingForStorage,
+          finalized: !waitingForStorage && !verificationPending,
           waitingForStorage,
+          ...(verificationPending ? { retryAfterMs: 3_000 } : {}),
           ...result,
         };
       } catch (err) {
@@ -650,6 +694,16 @@ export default defineEventHandler(async (event: H3Event) => {
             hasCamera: committed.hasCamera,
           };
         }
+        if (committed?.status === "processing" && committed.videoUrl) {
+          const pendingState = pendingMediaVerificationState(
+            await readAppState(`recording-upload-${recordingId}`).catch(
+              () => null,
+            ),
+          );
+          if (pendingState) {
+            return acceptedProcessingResponse(event, recordingId, pendingState);
+          }
+        }
         trackUploadBlockingFailure(ownerEmail, {
           stage: "finalize_recording",
           failureKind: "finalize_error",
@@ -657,7 +711,7 @@ export default defineEventHandler(async (event: H3Event) => {
           uploadMode: "buffered",
           errorMessage: err instanceof Error ? err.message : String(err),
         });
-        await db
+        const failed = await db
           .update(schema.recordings)
           .set({
             status: "failed",
@@ -665,7 +719,17 @@ export default defineEventHandler(async (event: H3Event) => {
               err instanceof Error ? err.message : "Finalize failed",
             updatedAt: new Date().toISOString(),
           })
-          .where(eq(schema.recordings.id, recordingId));
+          .where(
+            and(
+              eq(schema.recordings.id, recordingId),
+              ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+              eq(schema.recordings.status, "processing"),
+            ),
+          )
+          .returning({ id: schema.recordings.id });
+        if (failed.length !== 1) {
+          throw err;
+        }
         const failedUploadStateRaw = await readAppState(
           `recording-upload-${recordingId}`,
         ).catch(() => null);
@@ -862,7 +926,16 @@ async function handleResumableChunk(
         error: "Recording was cancelled before it finished saving.",
       };
     }
-    return { ok: true, finalized: true, ...result };
+    const verificationPending =
+      (result as any)?.status === "processing" &&
+      (result as any)?.verificationPending === true;
+    if (verificationPending) setResponseStatus(event, 202);
+    return {
+      ok: true,
+      finalized: !verificationPending,
+      ...(verificationPending ? { retryAfterMs: 3_000 } : {}),
+      ...result,
+    };
   } catch (err) {
     console.error(`[resumable-chunk-${recordingId}] finalize failed:`, err);
     const db = getDb();
@@ -932,6 +1005,14 @@ async function handleResumableChunk(
         hasCamera: committed.hasCamera,
       };
     }
+    if (committed?.status === "processing" && committed.videoUrl) {
+      const pendingState = pendingMediaVerificationState(
+        await readAppState(`recording-upload-${recordingId}`).catch(() => null),
+      );
+      if (pendingState) {
+        return acceptedProcessingResponse(event, recordingId, pendingState);
+      }
+    }
 
     trackUploadBlockingFailure(ownerEmail, {
       stage: "finalize_recording",
@@ -943,7 +1024,7 @@ async function handleResumableChunk(
     const failureReason =
       err instanceof Error ? err.message : "Finalize failed";
     const failedAt = new Date().toISOString();
-    await db
+    const failed = await db
       .update(schema.recordings)
       .set({
         status: "failed",
@@ -954,8 +1035,11 @@ async function handleResumableChunk(
         and(
           eq(schema.recordings.id, recordingId),
           ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+          eq(schema.recordings.status, "processing"),
         ),
-      );
+      )
+      .returning({ id: schema.recordings.id });
+    if (failed.length !== 1) throw err;
     const failedUploadStateRaw = await readAppState(
       `recording-upload-${recordingId}`,
     ).catch(() => null);

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/reset-chunks.post.ts

@@ -42,6 +42,7 @@ import {
 } from "h3";
 
 import { getDb, schema } from "../../../../db/index.js";
+import { isMediaVerificationPending } from "../../../../lib/media-verification-state.js";
 import {
   getEventOwnerContext,
   ownerEmailMatches,
@@ -115,7 +116,11 @@ export default defineEventHandler(async (event: H3Event) => {
     const db = getDb();
 
     const [existing] = await db
-      .select({ id: schema.recordings.id })
+      .select({
+        id: schema.recordings.id,
+        status: schema.recordings.status,
+        videoUrl: schema.recordings.videoUrl,
+      })
       .from(schema.recordings)
       .where(
         and(
@@ -129,6 +134,22 @@ export default defineEventHandler(async (event: H3Event) => {
       return { error: "Recording not found" };
     }
 
+    if (existing.status === "ready" && existing.videoUrl) {
+      setResponseStatus(event, 409);
+      return { error: "Recording is already ready" };
+    }
+
+    if (
+      await isMediaVerificationPending({
+        ownerEmail,
+        recordingId,
+        recordingStatus: existing.status,
+      })
+    ) {
+      setResponseStatus(event, 409);
+      return { error: "Recording is still being verified" };
+    }
+
     const cleared = await deleteAppStateByPrefix(
       `recording-chunks-${recordingId}-`,
     );

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/status.get.ts

@@ -1,9 +1,11 @@
+import { readAppState } from "@agent-native/core/application-state";
 import { runWithRequestContext } from "@agent-native/core/server";
 import { and, eq } from "drizzle-orm";
 import {
   createError,
   defineEventHandler,
   getRouterParam,
+  setResponseHeader,
   setResponseStatus,
   type H3Event,
 } from "h3";
@@ -23,6 +25,7 @@ function appPath(path: string): string {
 }
 
 export default defineEventHandler(async (event: H3Event) => {
+  setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
   const recordingId = getRouterParam(event, "recordingId");
   if (!recordingId) {
     throw createError({ statusCode: 400, message: "Missing recordingId" });
@@ -55,10 +58,21 @@ export default defineEventHandler(async (event: H3Event) => {
       return { error: "Not found" };
     }
 
+    const uploadState = await readAppState(
+      `recording-upload-${recordingId}`,
+    ).catch(() => null);
+    const verificationPending = Boolean(
+      uploadState &&
+      typeof uploadState === "object" &&
+      (uploadState as Record<string, unknown>).pendingMediaVerification ===
+        true,
+    );
+
     return {
       recording: {
         id: recording.id,
         status: recording.status,
+        verificationPending,
         videoUrl: resolvePlayerVideoUrl(recording, {
           appPath,
           proxyRemoteMedia: true,