@agent-native/core-corpus 0.214.0 → 0.217.0

package/corpus/templates/slides-2/server/handlers/uploads-chunked.ts

@@ -0,0 +1,1066 @@
+import {
+  ATTACHMENT_ERROR_CODES,
+  attachmentFailureToError,
+  attachmentFailureDetails,
+  deletePrivateBlob,
+  describeAttachmentFailure,
+  isAttachmentError,
+  isPrivateBlobError,
+  putPrivateBlob,
+  readPrivateBlob,
+  type AttachmentFailure,
+  type PrivateBlobHandle,
+  type StorageUnavailable,
+} from "@agent-native/core/private-blob";
+import {
+  defineEventHandler,
+  getHeader,
+  getQuery,
+  getRouterParam,
+  readBody,
+  readRawBody,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+import { nanoid } from "nanoid";
+
+import {
+  compareAndSetChunkedUploadSession,
+  createChunkedUploadSession,
+  deleteOrphanedChunkCleanup,
+  deleteChunkedUploadSession,
+  getChunkedUploadSession,
+  listOrphanedChunkCleanups,
+  listChunkedUploadSessions,
+  recordOrphanedChunkCleanup,
+  type ChunkedUploadSession,
+} from "../lib/chunked-upload-session.js";
+import { assertDeckAssetUploadScope } from "../lib/deck-asset-scope.js";
+import { isHostedSlidesRuntime } from "../lib/tenant-files.js";
+import {
+  findUploadedVideoAssetForSession,
+  MAX_VIDEO_ASSET_FILE_SIZE,
+  uploadVideoAsset,
+  videoUploadFailureResponse,
+} from "./assets.js";
+import {
+  resolveSlidesRequestAuth,
+  withSlidesRequestContext,
+} from "./request-auth-context.js";
+import { maxReferenceFileBytes, saveUploadedReferenceFile } from "./uploads.js";
+
+const STORAGE_NOT_CONNECTED: StorageUnavailable = {
+  status: "storageUnavailable",
+  reason: "not_configured",
+  whoCanFix: "workspace_admin",
+};
+
+const MAX_CHUNK_BYTES = 4 * 1024 * 1024;
+const MAX_CHUNKS = 128;
+const SESSION_TTL_MS = 60 * 60 * 1000;
+const FINALIZATION_LEASE_MS = 60 * 60 * 1000;
+const FINALIZATION_HEARTBEAT_MS = 60 * 1000;
+
+function referenceChunkReadFailure(error: unknown): AttachmentFailure {
+  if (!isPrivateBlobError(error)) {
+    return {
+      status: "storageUnavailable",
+      reason: "provider_unavailable",
+      whoCanFix: "self_resolving",
+    };
+  }
+
+  switch (error.kind) {
+    case "not_found":
+      return { status: "notFound", reason: "blob_missing" };
+    case "gone":
+      return { status: "expired", reason: "retention" };
+    case "corrupt":
+      return { status: "expired", reason: "undecryptable" };
+    case "not_configured":
+      return {
+        status: "storageUnavailable",
+        reason: "misconfigured",
+        whoCanFix: "operator",
+      };
+    case "unavailable":
+      return {
+        status: "storageUnavailable",
+        reason: "provider_unavailable",
+        whoCanFix: "self_resolving",
+      };
+    default:
+      return {
+        status: "storageUnavailable",
+        reason: "provider_unavailable",
+        whoCanFix: "self_resolving",
+      };
+  }
+}
+
+class UploadSessionFinalizingError extends Error {}
+
+interface StartBody {
+  filename?: unknown;
+  mimetype?: unknown;
+  declaredSize?: unknown;
+  uploadType?: unknown;
+  deckId?: unknown;
+}
+
+async function deleteChunk(handle: ChunkedUploadSession["chunks"][string]) {
+  return (await deletePrivateBlob(handle)).deleted;
+}
+
+async function cleanupConflictedChunk(args: {
+  sessionId: string;
+  chunkIndex: number;
+  ownerEmail: string;
+  orgId: string | undefined;
+  handle: PrivateBlobHandle;
+  uncertain?: boolean;
+}): Promise<boolean> {
+  let cleanupKey: string | undefined;
+  try {
+    cleanupKey = await recordOrphanedChunkCleanup({
+      version: 1,
+      ownerEmail: args.ownerEmail,
+      orgId: args.orgId ?? null,
+      uploadSessionId: args.sessionId,
+      chunkIndex: args.chunkIndex,
+      handle: args.handle,
+      createdAt: new Date().toISOString(),
+      ...(args.uncertain ? { uncertain: true } : {}),
+    });
+  } catch (error) {
+    console.error("[slides-upload] could not record orphaned chunk", {
+      sessionId: args.sessionId,
+      chunkIndex: args.chunkIndex,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  if (args.uncertain) return cleanupKey !== undefined;
+
+  try {
+    if (await deleteChunk(args.handle)) {
+      if (cleanupKey) {
+        try {
+          await deleteOrphanedChunkCleanup(cleanupKey);
+        } catch (error) {
+          console.warn("[slides-upload] orphaned chunk record cleanup failed", {
+            sessionId: args.sessionId,
+            chunkIndex: args.chunkIndex,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+      return true;
+    }
+  } catch (error) {
+    console.warn("[slides-upload] chunk cleanup after conflict failed", {
+      sessionId: args.sessionId,
+      chunkIndex: args.chunkIndex,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  return cleanupKey !== undefined;
+}
+
+async function reapOrphanedChunkBlobs(
+  ownerEmail: string,
+  orgId: string | undefined,
+): Promise<void> {
+  const cleanups = await listOrphanedChunkCleanups();
+  await Promise.all(
+    cleanups.map(async ({ key, cleanup }) => {
+      if (
+        cleanup.version !== 1 ||
+        cleanup.ownerEmail !== ownerEmail ||
+        (cleanup.orgId ?? null) !== (orgId ?? null) ||
+        !cleanup.handle ||
+        typeof cleanup.handle.id !== "string" ||
+        typeof cleanup.handle.provider !== "string" ||
+        cleanup.handle.opaque !== true
+      ) {
+        return;
+      }
+      try {
+        if (cleanup.uncertain) {
+          const session = await getChunkedUploadSession(
+            cleanup.uploadSessionId,
+          );
+          const current = session?.chunks[String(cleanup.chunkIndex)];
+          if (
+            current?.id === cleanup.handle.id &&
+            current.provider === cleanup.handle.provider
+          ) {
+            await deleteOrphanedChunkCleanup(key);
+            return;
+          }
+        }
+        if (await deleteChunk(cleanup.handle)) {
+          await deleteOrphanedChunkCleanup(key);
+        }
+      } catch (error) {
+        console.warn("[slides-upload] orphaned chunk retry failed", {
+          sessionId: cleanup.uploadSessionId,
+          chunkIndex: cleanup.chunkIndex,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }),
+  );
+}
+
+async function cleanupChunks(session: ChunkedUploadSession): Promise<boolean> {
+  const results = await Promise.all(
+    Object.values(session.chunks).map(deleteChunk),
+  );
+  return results.every(Boolean);
+}
+
+function sessionBelongsToRequest(
+  session: ChunkedUploadSession,
+  email: string,
+  orgId: string | undefined,
+): boolean {
+  return (
+    (!session.ownerEmail ||
+      (session.ownerEmail === email &&
+        (session.orgId ?? null) === (orgId ?? null))) &&
+    (session.uploadType !== "video" || Boolean(session.ownerEmail))
+  );
+}
+
+async function markSessionForCleanup(
+  sessionId: string,
+  initialSession: ChunkedUploadSession,
+  allowFinalizing = false,
+): Promise<ChunkedUploadSession | null> {
+  let session = initialSession;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    if (session.cleanupState === "aborting") return session;
+    if (session.finalizingAt && !allowFinalizing) {
+      throw new UploadSessionFinalizingError();
+    }
+    const cleanupSession = { ...session, cleanupState: "aborting" as const };
+    if (
+      await compareAndSetChunkedUploadSession(
+        sessionId,
+        session,
+        cleanupSession,
+      )
+    ) {
+      return cleanupSession;
+    }
+    const latest = await getChunkedUploadSession(sessionId);
+    if (!latest) return null;
+    session = latest;
+  }
+  throw new Error("Could not claim the upload session for cleanup");
+}
+
+async function discardSession(
+  sessionId: string,
+  session: ChunkedUploadSession,
+  { allowFinalizing = false }: { allowFinalizing?: boolean } = {},
+): Promise<boolean> {
+  const cleanupSession = await markSessionForCleanup(
+    sessionId,
+    session,
+    allowFinalizing,
+  );
+  if (!cleanupSession) return true;
+  const cleaned = await cleanupChunks(cleanupSession);
+  if (cleaned) await deleteChunkedUploadSession(sessionId);
+  return cleaned;
+}
+
+async function reapExpiredChunkedUploads(
+  ownerEmail: string,
+  orgId: string | undefined,
+): Promise<void> {
+  await reapOrphanedChunkBlobs(ownerEmail, orgId);
+  const now = Date.now();
+  const sessions = await listChunkedUploadSessions();
+  await Promise.all(
+    sessions.map(async ({ sessionId, session }) => {
+      if (
+        session.ownerEmail !== ownerEmail ||
+        (session.orgId ?? null) !== (orgId ?? null)
+      ) {
+        return;
+      }
+      const expiresAt = Date.parse(session.expiresAt);
+      const finalizationExpiresAt = session.finalizingAt
+        ? Date.parse(session.finalizationLeaseExpiresAt ?? "")
+        : Number.NaN;
+      const finalizationExpired =
+        session.finalizingAt !== undefined &&
+        (!Number.isFinite(finalizationExpiresAt) ||
+          finalizationExpiresAt <= now);
+      if (session.finalizingAt && session.cleanupState !== "aborting") {
+        if (!finalizationExpired) return;
+        try {
+          await discardExpiredFinalization(sessionId, session);
+        } catch (error) {
+          console.warn("[slides-upload] expired finalization cleanup failed", {
+            sessionId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+        return;
+      }
+      if (
+        session.cleanupState !== "aborting" &&
+        Number.isFinite(expiresAt) &&
+        expiresAt > now
+      ) {
+        return;
+      }
+      try {
+        const cleaned = await discardSession(sessionId, session);
+        if (!cleaned) {
+          console.warn("[slides-upload] expired session cleanup incomplete", {
+            sessionId,
+          });
+        }
+      } catch (error) {
+        console.warn("[slides-upload] expired session cleanup failed", {
+          sessionId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }),
+  );
+}
+
+async function cleanupCommittedSession(
+  sessionId: string,
+  session: ChunkedUploadSession,
+): Promise<void> {
+  try {
+    const cleaned = await discardSession(sessionId, session, {
+      allowFinalizing: true,
+    });
+    if (!cleaned) {
+      console.warn("[slides-upload] committed session cleanup incomplete", {
+        sessionId,
+      });
+    }
+  } catch (error) {
+    console.warn("[slides-upload] committed session cleanup failed", {
+      sessionId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function startFinalizationLease(
+  sessionId: string,
+  initialSession: ChunkedUploadSession,
+) {
+  let session = initialSession;
+  let failure: Error | undefined;
+  let renewal = Promise.resolve();
+  const timer = setInterval(() => {
+    renewal = renewal
+      .then(async () => {
+        if (failure) return;
+        const nextSession = {
+          ...session,
+          finalizationLeaseExpiresAt: new Date(
+            Date.now() + FINALIZATION_LEASE_MS,
+          ).toISOString(),
+        };
+        if (
+          !(await compareAndSetChunkedUploadSession(
+            sessionId,
+            session,
+            nextSession,
+          ))
+        ) {
+          throw new Error("Upload session finalization lease was lost");
+        }
+        session = nextSession;
+      })
+      .catch((error) => {
+        failure = error instanceof Error ? error : new Error(String(error));
+      });
+  }, FINALIZATION_HEARTBEAT_MS);
+  timer.unref?.();
+
+  return {
+    async assertActive() {
+      await renewal;
+      if (failure) throw failure;
+    },
+    async stop() {
+      clearInterval(timer);
+      await renewal;
+      return failure;
+    },
+  };
+}
+
+async function discardExpiredFinalization(
+  sessionId: string,
+  session: ChunkedUploadSession,
+): Promise<boolean> {
+  const cleanupSession = { ...session, cleanupState: "aborting" as const };
+  if (
+    !(await compareAndSetChunkedUploadSession(
+      sessionId,
+      session,
+      cleanupSession,
+    ))
+  ) {
+    return true;
+  }
+  const cleaned = await cleanupChunks(cleanupSession);
+  if (cleaned) await deleteChunkedUploadSession(sessionId);
+  return cleaned;
+}
+
+export const startChunkedUpload = defineEventHandler(async (event) => {
+  const auth = await resolveSlidesRequestAuth(event);
+  if (!auth.ok) {
+    setResponseStatus(event, auth.statusCode);
+    return { error: auth.error };
+  }
+  const authContext = auth.context;
+  const userEmail = authContext.email;
+  if (!userEmail) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  return withSlidesRequestContext(
+    event,
+    async ({ orgId }) => {
+      if (!isHostedSlidesRuntime()) {
+        return { uploadMode: "multipart" as const };
+      }
+      const body = (await readBody(event).catch(
+        () => null,
+      )) as StartBody | null;
+      const filename =
+        typeof body?.filename === "string" ? body.filename.trim() : "";
+      const mimetype =
+        typeof body?.mimetype === "string" && body.mimetype.trim()
+          ? body.mimetype.trim()
+          : "application/octet-stream";
+      const declaredSize = Number(body?.declaredSize);
+      const uploadType = body?.uploadType ?? "reference";
+      let deckId: string | undefined;
+      if (body?.deckId !== undefined) {
+        deckId = typeof body.deckId === "string" ? body.deckId.trim() : "";
+        if (!deckId || deckId.length > 200) {
+          setResponseStatus(event, 400);
+          return {
+            error: "deckId must be a non-empty string up to 200 characters",
+          };
+        }
+      }
+      if (!filename) {
+        setResponseStatus(event, 400);
+        return { error: "filename is required" };
+      }
+      if (!Number.isSafeInteger(declaredSize) || declaredSize <= 0) {
+        setResponseStatus(event, 400);
+        return { error: "declaredSize must be a positive integer" };
+      }
+      if (uploadType !== "reference" && uploadType !== "video") {
+        setResponseStatus(event, 400);
+        return { error: "Unsupported upload type" };
+      }
+      if (uploadType === "video" && !/\.(mp4|webm)$/i.test(filename)) {
+        setResponseStatus(event, 400);
+        return { error: "Only MP4 and WebM videos are allowed" };
+      }
+      const limit =
+        uploadType === "video"
+          ? MAX_VIDEO_ASSET_FILE_SIZE
+          : maxReferenceFileBytes(filename);
+      if (declaredSize > limit) {
+        setResponseStatus(event, 413);
+        return {
+          error:
+            uploadType === "video"
+              ? "Video too large (max 50 MB)"
+              : `File too large (max ${Math.round(limit / 1024 / 1024)} MB)`,
+        };
+      }
+
+      await assertDeckAssetUploadScope({
+        deckId,
+        email: userEmail,
+        orgId,
+      });
+      await reapExpiredChunkedUploads(userEmail, orgId);
+
+      const sessionId = nanoid();
+      const now = Date.now();
+      await createChunkedUploadSession(sessionId, {
+        uploadType,
+        ownerEmail: userEmail,
+        orgId: orgId ?? null,
+        ...(deckId ? { deckId } : {}),
+        filename,
+        mimeType: mimetype,
+        declaredSize,
+        chunks: {},
+        chunkSizes: {},
+        createdAt: new Date(now).toISOString(),
+        expiresAt: new Date(now + SESSION_TTL_MS).toISOString(),
+      });
+      return { sessionId, maxChunkBytes: MAX_CHUNK_BYTES };
+    },
+    authContext,
+  );
+});
+
+export const uploadChunkedChunk = defineEventHandler(async (event) => {
+  const auth = await resolveSlidesRequestAuth(event);
+  if (!auth.ok) {
+    setResponseStatus(event, auth.statusCode);
+    return { error: auth.error };
+  }
+  const authContext = auth.context;
+  const email = authContext.email;
+  if (!email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  return withSlidesRequestContext(
+    event,
+    async ({ orgId }) => {
+      const sessionId = getRouterParam(event, "sessionId");
+      if (!sessionId) {
+        setResponseStatus(event, 400);
+        return { error: "Missing sessionId" };
+      }
+      let session = await getChunkedUploadSession(sessionId);
+      if (session && !sessionBelongsToRequest(session, email, orgId)) {
+        setResponseStatus(event, 403);
+        return { error: "Upload session belongs to another user" };
+      }
+      if (
+        !session ||
+        session.cleanupState === "aborting" ||
+        session.finalizingAt
+      ) {
+        const completedVideo = await findUploadedVideoAssetForSession(
+          email,
+          sessionId,
+          orgId ?? null,
+        );
+        if (completedVideo) return completedVideo;
+      }
+      if (!session) {
+        setResponseStatus(event, 404);
+        return { error: "Upload session not found or expired" };
+      }
+      if (session.cleanupState === "aborting") {
+        setResponseStatus(event, 410);
+        return { error: "Upload session was cancelled" };
+      }
+      if (session.finalizingAt) {
+        setResponseStatus(event, 409);
+        return { error: "Upload session is already finalizing" };
+      }
+      if (Date.parse(session.expiresAt) <= Date.now()) {
+        try {
+          await discardSession(sessionId, session);
+        } catch (error) {
+          if (error instanceof UploadSessionFinalizingError) {
+            setResponseStatus(event, 409);
+            return { error: "Upload session is already finalizing" };
+          }
+          throw error;
+        }
+        setResponseStatus(event, 410);
+        return { error: "Upload session expired" };
+      }
+
+      let activeSession = session;
+      const query = getQuery(event);
+      const index = Number(query.index ?? 0);
+      const isFinal = query.isFinal === "1" || query.isFinal === "true";
+      if (!Number.isInteger(index) || index < 0 || index >= MAX_CHUNKS) {
+        setResponseStatus(event, 400);
+        return { error: "Invalid chunk index" };
+      }
+
+      const contentLengthHeader = getHeader(event, "content-length");
+      if (!contentLengthHeader || !/^\d+$/.test(contentLengthHeader)) {
+        setResponseStatus(event, 411);
+        return { error: "Valid Content-Length header required" };
+      }
+      const contentLength = Number(contentLengthHeader);
+      if (contentLength <= 0) {
+        setResponseStatus(event, 400);
+        return { error: "Empty chunk body" };
+      }
+      if (contentLength > MAX_CHUNK_BYTES) {
+        setResponseStatus(event, 413);
+        return { error: "Chunk too large" };
+      }
+
+      const chunkKey = String(index);
+      const previousSize = activeSession.chunkSizes[chunkKey] ?? 0;
+      const receivedBefore = Object.values(activeSession.chunkSizes).reduce(
+        (total, size) => total + size,
+        0,
+      );
+      const nextSize = receivedBefore - previousSize + contentLength;
+      const fileLimit =
+        activeSession.uploadType === "video"
+          ? MAX_VIDEO_ASSET_FILE_SIZE
+          : maxReferenceFileBytes(activeSession.filename);
+      if (nextSize > activeSession.declaredSize || nextSize > fileLimit) {
+        try {
+          await discardSession(sessionId, activeSession);
+        } catch (error) {
+          if (error instanceof UploadSessionFinalizingError) {
+            setResponseStatus(event, 409);
+            return { error: "Upload session is already finalizing" };
+          }
+          throw error;
+        }
+        setResponseStatus(event, 413);
+        return { error: "Uploaded bytes exceed the declared file size" };
+      }
+
+      const raw = await readRawBody(event, false);
+      const bytes = raw ?? new Uint8Array(0);
+      if (bytes.byteLength !== contentLength) {
+        setResponseStatus(event, 400);
+        return { error: "Chunk size does not match Content-Length" };
+      }
+
+      const previousHandle = activeSession.chunks[chunkKey];
+      let handle: PrivateBlobHandle | null;
+      try {
+        handle = await putPrivateBlob({
+          data: bytes,
+          filename: `${sessionId}-${index}`,
+          mimeType: "application/octet-stream",
+          ownerEmail: email,
+        });
+      } catch {
+        if (activeSession.uploadType === "video") {
+          return videoUploadFailureResponse(event, {
+            errorCode: "video_upload_storage_failed",
+          });
+        }
+        throw new Error("File storage could not save this upload chunk.");
+      }
+      if (!handle) {
+        setResponseStatus(event, 503);
+        return {
+          error: describeAttachmentFailure(STORAGE_NOT_CONNECTED, "save")
+            .message,
+          errorCode: ATTACHMENT_ERROR_CODES.storageUnavailable,
+          details: attachmentFailureDetails(STORAGE_NOT_CONNECTED),
+        };
+      }
+      const nextSession = {
+        ...activeSession,
+        chunks: { ...activeSession.chunks, [chunkKey]: handle },
+        chunkSizes: {
+          ...activeSession.chunkSizes,
+          [chunkKey]: bytes.byteLength,
+        },
+        ...(isFinal
+          ? {
+              finalizingAt: new Date().toISOString(),
+              finalizationLeaseExpiresAt: new Date(
+                Date.now() + FINALIZATION_LEASE_MS,
+              ).toISOString(),
+            }
+          : {}),
+      };
+      let sessionUpdated = false;
+      let recoveredCommittedCas = false;
+      try {
+        sessionUpdated = await compareAndSetChunkedUploadSession(
+          sessionId,
+          activeSession,
+          nextSession,
+        );
+      } catch (casError) {
+        let latest: ChunkedUploadSession | null;
+        try {
+          latest = await getChunkedUploadSession(sessionId);
+        } catch {
+          await cleanupConflictedChunk({
+            sessionId,
+            chunkIndex: index,
+            ownerEmail: email,
+            orgId,
+            handle,
+            uncertain: true,
+          });
+          throw casError;
+        }
+
+        const currentHandle = latest?.chunks[chunkKey];
+        if (
+          latest &&
+          currentHandle?.id === handle.id &&
+          currentHandle.provider === handle.provider
+        ) {
+          if (latest.cleanupState === "aborting") {
+            setResponseStatus(event, 410);
+            return { error: "Upload session was cancelled" };
+          }
+          activeSession = latest;
+          sessionUpdated = true;
+          recoveredCommittedCas = true;
+        } else {
+          if (!latest && activeSession.uploadType === "video") {
+            const completedVideo = await findUploadedVideoAssetForSession(
+              email,
+              sessionId,
+              orgId ?? null,
+            );
+            if (completedVideo) return completedVideo;
+          }
+          await cleanupConflictedChunk({
+            sessionId,
+            chunkIndex: index,
+            ownerEmail: email,
+            orgId,
+            handle,
+          });
+          throw casError;
+        }
+      }
+
+      if (!sessionUpdated) {
+        const cleanupTracked = await cleanupConflictedChunk({
+          sessionId,
+          chunkIndex: index,
+          ownerEmail: email,
+          orgId,
+          handle,
+        });
+        if (!cleanupTracked) {
+          setResponseStatus(event, 503);
+          return {
+            error: "Conflicted upload chunk cleanup could not be recorded",
+          };
+        }
+        setResponseStatus(event, 409);
+        return { error: "Upload session changed while saving the chunk" };
+      }
+      if (!recoveredCommittedCas) activeSession = nextSession;
+
+      if (previousHandle) {
+        try {
+          if (!(await deleteChunk(previousHandle))) {
+            const cleanupTracked = await cleanupConflictedChunk({
+              sessionId,
+              chunkIndex: index,
+              ownerEmail: email,
+              orgId,
+              handle: previousHandle,
+            });
+            if (!cleanupTracked) {
+              console.error(
+                "[slides-upload] replaced chunk cleanup is untracked",
+                { sessionId, chunkIndex: index },
+              );
+            }
+          }
+        } catch (error) {
+          await cleanupConflictedChunk({
+            sessionId,
+            chunkIndex: index,
+            ownerEmail: email,
+            orgId,
+            handle: previousHandle,
+          });
+          console.warn("[slides-upload] replaced chunk cleanup failed", {
+            sessionId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      if (!isFinal) return { ok: true };
+
+      const orderedIndices = Object.keys(activeSession.chunks)
+        .map(Number)
+        .sort((a, b) => a - b);
+      const missing = orderedIndices.some((value, i) => value !== i);
+      const receivedSize = Object.values(activeSession.chunkSizes).reduce(
+        (total, size) => total + size,
+        0,
+      );
+      if (
+        missing ||
+        orderedIndices.length === 0 ||
+        receivedSize !== activeSession.declaredSize
+      ) {
+        await discardSession(sessionId, activeSession, {
+          allowFinalizing: true,
+        });
+        setResponseStatus(event, 400);
+        return { error: "Upload is incomplete or has an invalid size" };
+      }
+
+      const finalizationLease = startFinalizationLease(
+        sessionId,
+        activeSession,
+      );
+      let result;
+      try {
+        const parts = await Promise.all(
+          orderedIndices.map(async (chunkIndex) => {
+            const chunkHandle = activeSession.chunks[String(chunkIndex)];
+            let read;
+            try {
+              read = await readPrivateBlob(chunkHandle);
+            } catch (error) {
+              if (activeSession.uploadType === "video") throw error;
+              throw attachmentFailureToError(
+                referenceChunkReadFailure(error),
+                "open",
+              );
+            }
+            return Buffer.from(read.data);
+          }),
+        );
+        const combined = Buffer.concat(parts);
+        if (combined.byteLength !== activeSession.declaredSize) {
+          throw new Error("Assembled upload size does not match declaredSize");
+        }
+        await finalizationLease.assertActive();
+        result =
+          activeSession.uploadType === "video"
+            ? await uploadVideoAsset({
+                email,
+                orgId,
+                deckId: activeSession.deckId,
+                originalName: activeSession.filename,
+                data: combined,
+                uploadSessionId: sessionId,
+              })
+            : await saveUploadedReferenceFile({
+                email,
+                orgId,
+                deckId: activeSession.deckId,
+                originalName: activeSession.filename,
+                data: combined,
+                type: activeSession.mimeType,
+              });
+      } catch (err) {
+        await finalizationLease.stop();
+        try {
+          const cleaned = await discardSession(sessionId, activeSession, {
+            allowFinalizing: true,
+          });
+          if (!cleaned) {
+            console.warn(
+              "[slides-upload] failed finalization cleanup incomplete",
+              {
+                sessionId,
+                error: err instanceof Error ? err.message : String(err),
+              },
+            );
+          }
+        } catch (cleanupError) {
+          console.error("[slides-upload] failed finalization cleanup failed", {
+            sessionId,
+            error: err instanceof Error ? err.message : String(err),
+            cleanupError:
+              cleanupError instanceof Error
+                ? cleanupError.message
+                : String(cleanupError),
+          });
+        }
+        if (activeSession.uploadType === "video") {
+          return videoUploadFailureResponse(event, err);
+        }
+        const statusCode =
+          typeof (err as { statusCode?: unknown })?.statusCode === "number"
+            ? (err as { statusCode: number }).statusCode
+            : 500;
+        const errorCode = (err as { errorCode?: unknown })?.errorCode;
+        const details = isAttachmentError(err) ? err.details : undefined;
+        setResponseStatus(event, statusCode);
+        return {
+          error: err instanceof Error ? err.message : "Invalid upload",
+          ...(typeof errorCode === "string" ? { errorCode } : {}),
+          ...(details ? { details } : {}),
+        };
+      }
+
+      const leaseFailure = await finalizationLease.stop();
+      if (leaseFailure) {
+        console.warn("[slides-upload] finalization lease ended during commit", {
+          sessionId,
+          error: leaseFailure.message,
+        });
+      }
+      await cleanupCommittedSession(sessionId, activeSession);
+      return activeSession.uploadType === "video" ? result : [result];
+    },
+    authContext,
+  );
+});
+
+export const getChunkedUploadStatus = defineEventHandler(async (event) => {
+  setResponseHeader(event, "Cache-Control", "private, no-store");
+  const auth = await resolveSlidesRequestAuth(event);
+  if (!auth.ok) {
+    setResponseStatus(event, auth.statusCode);
+    return { error: auth.error };
+  }
+  const authContext = auth.context;
+  const email = authContext.email;
+  if (!email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  return withSlidesRequestContext(
+    event,
+    async ({ orgId }) => {
+      const sessionId = getRouterParam(event, "sessionId");
+      if (!sessionId) {
+        setResponseStatus(event, 400);
+        return { error: "Missing sessionId" };
+      }
+
+      const session = await getChunkedUploadSession(sessionId);
+      if (session && !sessionBelongsToRequest(session, email, orgId)) {
+        setResponseStatus(event, 403);
+        return { error: "Upload session belongs to another user" };
+      }
+
+      const completedVideo = await findUploadedVideoAssetForSession(
+        email,
+        sessionId,
+        orgId ?? null,
+      );
+      if (completedVideo) {
+        return { status: "complete" as const, video: completedVideo };
+      }
+      if (!session || session.uploadType !== "video") {
+        return { status: "expired" as const };
+      }
+      if (session.cleanupState === "aborting") {
+        const cleaned = await discardSession(sessionId, session, {
+          allowFinalizing: true,
+        });
+        if (!cleaned) {
+          return { status: "processing" as const, retryAfterMs: 1500 };
+        }
+        const completedAfterCleanup = await findUploadedVideoAssetForSession(
+          email,
+          sessionId,
+          orgId ?? null,
+        );
+        return completedAfterCleanup
+          ? { status: "complete" as const, video: completedAfterCleanup }
+          : { status: "expired" as const };
+      }
+      if (session.finalizingAt) {
+        const leaseExpiresAt = Date.parse(
+          session.finalizationLeaseExpiresAt ?? "",
+        );
+        if (!Number.isFinite(leaseExpiresAt) || leaseExpiresAt <= Date.now()) {
+          await discardExpiredFinalization(sessionId, session);
+          const latest = await getChunkedUploadSession(sessionId);
+          if (!latest) {
+            const completedAfterCleanup =
+              await findUploadedVideoAssetForSession(
+                email,
+                sessionId,
+                orgId ?? null,
+              );
+            return completedAfterCleanup
+              ? { status: "complete" as const, video: completedAfterCleanup }
+              : { status: "expired" as const };
+          }
+          if (!sessionBelongsToRequest(latest, email, orgId)) {
+            setResponseStatus(event, 403);
+            return { error: "Upload session belongs to another user" };
+          }
+          const completedAfterCleanup = await findUploadedVideoAssetForSession(
+            email,
+            sessionId,
+            orgId ?? null,
+          );
+          if (completedAfterCleanup) {
+            return {
+              status: "complete" as const,
+              video: completedAfterCleanup,
+            };
+          }
+          if (latest.finalizingAt || latest.cleanupState === "aborting") {
+            return { status: "processing" as const, retryAfterMs: 1500 };
+          }
+          return { status: "uploading" as const };
+        }
+        return { status: "processing" as const, retryAfterMs: 1500 };
+      }
+      return { status: "uploading" as const };
+    },
+    authContext,
+  );
+});
+
+export const abortChunkedUpload = defineEventHandler(async (event) => {
+  const auth = await resolveSlidesRequestAuth(event);
+  if (!auth.ok) {
+    setResponseStatus(event, auth.statusCode);
+    return { error: auth.error };
+  }
+  const authContext = auth.context;
+  const email = authContext.email;
+  if (!email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  return withSlidesRequestContext(
+    event,
+    async ({ orgId }) => {
+      const sessionId = getRouterParam(event, "sessionId");
+      if (!sessionId) {
+        setResponseStatus(event, 400);
+        return { error: "Missing sessionId" };
+      }
+      const session = await getChunkedUploadSession(sessionId);
+      if (!session) return { ok: true };
+      if (!sessionBelongsToRequest(session, email, orgId)) {
+        setResponseStatus(event, 403);
+        return { error: "Upload session belongs to another user" };
+      }
+
+      try {
+        const cleaned = await discardSession(sessionId, session);
+        if (cleaned) return { ok: true };
+      } catch (error) {
+        if (error instanceof UploadSessionFinalizingError) {
+          setResponseStatus(event, 409);
+          return { error: "Upload session is already finalizing" };
+        }
+        console.warn("[slides-upload] aborted session cleanup failed", {
+          sessionId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      setResponseStatus(event, 503);
+      return { error: "Could not clean up upload session" };
+    },
+    authContext,
+  );
+});