@beignet/core 0.0.31 → 0.0.33

package/src/uploads/index.ts

@@ -2,6 +2,7 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type {
   StorageMetadata,
   StorageObject,
+  StorageObjectBody,
   StoragePort,
 } from "../ports/index.js";
 import type { ProviderInstrumentationTarget } from "../providers/index.js";
@@ -39,6 +40,46 @@ export interface UploadFileIntent {
    * File size in bytes.
    */
   size: number;
+  /**
+   * Optional expected checksum for this file. Direct uploads use this to
+   * verify the object bytes during completion.
+   */
+  checksum?: UploadFileChecksum;
+}
+
+/**
+ * Checksum algorithms supported by Beignet upload verification.
+ */
+export type UploadChecksumAlgorithm = "sha256";
+
+/**
+ * Expected or computed file checksum.
+ */
+export interface UploadFileChecksum {
+  /**
+   * Hash algorithm used for the checksum.
+   */
+  algorithm: UploadChecksumAlgorithm;
+  /**
+   * Lowercase hex digest.
+   */
+  value: string;
+}
+
+/**
+ * Checksum verification requested by an upload definition.
+ */
+export interface UploadChecksumRequirement {
+  /**
+   * Hash algorithm to compute.
+   */
+  algorithm: UploadChecksumAlgorithm;
+  /**
+   * Whether direct upload preparation/completion must include a checksum.
+   *
+   * @default true
+   */
+  required?: boolean;
 }
 
 /**
@@ -69,6 +110,18 @@ export interface UploadFileConstraints {
    * Cache-Control value written to storage.
    */
   cacheControl?: string;
+  /**
+   * Verify supported MIME types against file signatures instead of trusting
+   * only the client-declared content type.
+   *
+   * @default "signature"
+   */
+  contentTypeVerification?: "signature" | false;
+  /**
+   * Request checksum verification for direct uploads and expose the requirement
+   * through the upload manifest so browser clients can send expected digests.
+   */
+  checksum?: UploadChecksumRequirement;
 }
 
 /**
@@ -223,6 +276,28 @@ export interface UploadCompleteHookArgs<Metadata, Ctx>
   files: CompletedUploadFile[];
 }
 
+/**
+ * Arguments passed to `verifyFile(...)` after a file exists in storage and
+ * before `onComplete(...)` runs.
+ */
+export interface UploadVerifyFileHookArgs<Metadata, Ctx>
+  extends UploadHookArgs<Metadata, Ctx> {
+  file: CompletedUploadFile;
+  storage: StoragePort;
+}
+
+/**
+ * Verification result accepted by `verifyFile(...)`.
+ */
+export type UploadFileVerificationResult =
+  | boolean
+  | undefined
+  | {
+      valid: boolean;
+      reason?: string;
+      details?: unknown;
+    };
+
 /**
  * Upload definition options.
  */
@@ -267,6 +342,13 @@ export interface DefineUploadOptions<
   storageMetadata?(
     args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
   ): MaybePromise<StorageMetadata>;
+  /**
+   * Run after a file exists in storage and before `onComplete(...)`. Use this
+   * for app-owned scanning, moderation, or quarantine decisions.
+   */
+  verifyFile?(
+    args: UploadVerifyFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<UploadFileVerificationResult>;
   /**
    * Run after files exist in storage.
    */
@@ -299,6 +381,9 @@ export interface UploadDef<
   storageMetadata?(
     args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
   ): MaybePromise<StorageMetadata>;
+  verifyFile?(
+    args: UploadVerifyFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<UploadFileVerificationResult>;
   onComplete?(
     args: UploadCompleteHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
   ): MaybePromise<Result>;
@@ -452,14 +537,19 @@ export type UploadErrorCode =
   | "INVALID_UPLOAD_BODY";
 
 /**
- * Error thrown for expected upload failures.
+ * Base error for expected upload failures.
+ *
+ * Upload workflows throw one of the specific subclasses, such as
+ * {@link UploadNotFoundError} or {@link UnauthorizedUploadError}. Catch this
+ * base class to handle any expected upload failure; the upload router maps it
+ * to an HTTP response using `code`, `status`, and `details`.
  */
 export class UploadError extends Error {
   readonly code: UploadErrorCode;
   readonly status: number;
   readonly details?: unknown;
 
-  constructor(args: {
+  protected constructor(args: {
     code: UploadErrorCode;
     message: string;
     status?: number;
@@ -473,6 +563,111 @@ export class UploadError extends Error {
   }
 }
 
+/**
+ * Error thrown when an upload name is not registered on the router.
+ */
+export class UploadNotFoundError extends UploadError {
+  declare readonly code: "UPLOAD_NOT_FOUND";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UPLOAD_NOT_FOUND", status: 404, ...args });
+    this.name = "UploadNotFoundError";
+  }
+}
+
+/**
+ * Error thrown when an upload request targets an unknown upload action.
+ */
+export class InvalidUploadActionError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_ACTION";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "INVALID_UPLOAD_ACTION", status: 400, ...args });
+    this.name = "InvalidUploadActionError";
+  }
+}
+
+/**
+ * Error thrown when upload metadata fails schema validation.
+ */
+export class InvalidUploadMetadataError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_METADATA";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "INVALID_UPLOAD_METADATA", status: 422, ...args });
+    this.name = "InvalidUploadMetadataError";
+  }
+}
+
+/**
+ * Error thrown when a file fails upload validation, such as file count,
+ * content type (415), size limits (413), or prepared-file mismatches.
+ */
+export class InvalidUploadFileError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_FILE";
+
+  constructor(args: { message: string; details?: unknown; status?: number }) {
+    super({
+      code: "INVALID_UPLOAD_FILE",
+      message: args.message,
+      status: args.status ?? 422,
+      details: args.details,
+    });
+    this.name = "InvalidUploadFileError";
+  }
+}
+
+/**
+ * Error thrown when an upload is denied by authorize(...) or lacks
+ * authorization configuration.
+ */
+export class UnauthorizedUploadError extends UploadError {
+  declare readonly code: "UNAUTHORIZED_UPLOAD";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UNAUTHORIZED_UPLOAD", status: 403, ...args });
+    this.name = "UnauthorizedUploadError";
+  }
+}
+
+/**
+ * Error thrown when a completed upload references a stored object that does
+ * not exist.
+ */
+export class UploadObjectNotFoundError extends UploadError {
+  declare readonly code: "UPLOAD_OBJECT_NOT_FOUND";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UPLOAD_OBJECT_NOT_FOUND", status: 404, ...args });
+    this.name = "UploadObjectNotFoundError";
+  }
+}
+
+/**
+ * Error thrown when an upload request body exceeds the configured size limit.
+ */
+export class UploadBodyTooLargeError extends UploadError {
+  declare readonly code: "UPLOAD_BODY_TOO_LARGE";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UPLOAD_BODY_TOO_LARGE", status: 413, ...args });
+    this.name = "UploadBodyTooLargeError";
+  }
+}
+
+/**
+ * Error thrown when an upload request body cannot be parsed or has an
+ * invalid shape.
+ */
+export class InvalidUploadBodyError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_BODY";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "INVALID_UPLOAD_BODY", status: 400, ...args });
+    this.name = "InvalidUploadBodyError";
+  }
+}
+
 /**
  * Define a typed upload workflow.
  */
@@ -503,10 +698,52 @@ export function defineUpload<
     ...(options.storageMetadata
       ? { storageMetadata: options.storageMetadata }
       : {}),
+    ...(options.verifyFile ? { verifyFile: options.verifyFile } : {}),
     ...(options.onComplete ? { onComplete: options.onComplete } : {}),
   };
 }
 
+/**
+ * Context-bound upload helper factory.
+ */
+export interface Uploads<Ctx> {
+  /**
+   * Define an upload workflow with the bound context type.
+   */
+  defineUpload<
+    const Name extends string,
+    MetadataSchema extends StandardSchema,
+    Result = unknown,
+  >(
+    name: Name,
+    options: DefineUploadOptions<MetadataSchema, Ctx, Result>,
+  ): UploadDef<Name, MetadataSchema, Ctx, Result>;
+}
+
+/**
+ * Create upload helper methods bound to an application context type.
+ *
+ * Call it once in `lib/uploads.ts`:
+ *
+ * ```ts
+ * export const { defineUpload } = createUploads<AppContext>();
+ * ```
+ */
+export function createUploads<Ctx>(): Uploads<Ctx> {
+  return {
+    defineUpload<
+      const Name extends string,
+      MetadataSchema extends StandardSchema,
+      Result = unknown,
+    >(
+      name: Name,
+      options: DefineUploadOptions<MetadataSchema, Ctx, Result>,
+    ): UploadDef<Name, MetadataSchema, Ctx, Result> {
+      return defineUpload(name, options);
+    },
+  };
+}
+
 /**
  * Define a nested upload registry while preserving upload names and metadata
  * types for client code.
@@ -612,9 +849,7 @@ export function createUploadRouter<Ctx>(
       const registered = [...uploads.keys()]
         .map((registeredName) => `"${registeredName}"`)
         .join(", ");
-      throw new UploadError({
-        code: "UPLOAD_NOT_FOUND",
-        status: 404,
+      throw new UploadNotFoundError({
         message: `Upload "${name}" is not registered. Registered uploads: ${registered || "none"}. Upload routes resolve the defineUpload(...) name, not the defineUploads({...}) registry key.`,
       });
     }
@@ -634,7 +869,9 @@ export function createUploadRouter<Ctx>(
       const parsed = parsePrepareInput(uploadName, input);
       const ctx = await resolveCtx();
       const metadata = await parseMetadata(upload, parsed.metadata);
-      assertFiles(upload, parsed.files);
+      assertFiles(upload, parsed.files, {
+        requireChecksum: Boolean(options.signer),
+      });
 
       const files: PreparedUploadResultFile[] = [];
       for (const file of parsed.files) {
@@ -706,7 +943,7 @@ export function createUploadRouter<Ctx>(
       const parsed = parseCompleteInput(uploadName, input);
       const ctx = await resolveCtx();
       const metadata = await parseMetadata(upload, parsed.metadata);
-      assertFiles(upload, parsed.files);
+      assertFiles(upload, parsed.files, { requireChecksum: true });
 
       const files: CompletedUploadFile[] = [];
       for (const file of parsed.files) {
@@ -723,9 +960,7 @@ export function createUploadRouter<Ctx>(
           uploadId: file.uploadId,
         });
         if (file.key !== expectedKey) {
-          throw new UploadError({
-            code: "INVALID_UPLOAD_FILE",
-            status: 422,
+          throw new InvalidUploadFileError({
             message: `Uploaded object key does not match upload "${upload.name}".`,
             details: {
               expectedKey,
@@ -733,16 +968,29 @@ export function createUploadRouter<Ctx>(
             },
           });
         }
-        const object = await options.storage.stat(file.key);
+        const object = needsUploadBodyVerification(upload, file)
+          ? await options.storage.get(file.key)
+          : await options.storage.stat(file.key);
         if (!object) {
-          throw new UploadError({
-            code: "UPLOAD_OBJECT_NOT_FOUND",
-            status: 404,
+          throw new UploadObjectNotFoundError({
             message: `Uploaded object "${file.key}" was not found.`,
           });
         }
         assertStoredObject(upload, file, object);
-        files.push({ ...file, object });
+        const verified = await verifyStoredUploadFile(upload, file, object);
+        const completedObject = storageObjectMetadata(object);
+        const completedFile = {
+          ...file,
+          ...(verified.checksum ? { checksum: verified.checksum } : {}),
+          object: completedObject,
+        };
+        await assertVerifiedFile(upload, {
+          ctx,
+          metadata,
+          file: completedFile,
+          storage: options.storage,
+        });
+        files.push(completedFile);
       }
 
       const result = await upload.onComplete?.({ ctx, metadata, files });
@@ -785,46 +1033,58 @@ export function createUploadRouter<Ctx>(
       );
       const webFiles = filesFromFormData(input.formData);
       const intents = webFiles.map(fileIntentFromFile);
-      assertFiles(definition, intents);
+      assertFiles(definition, intents, { requireChecksum: false });
 
       const completed: CompletedUploadFile[] = [];
       for (const [index, file] of webFiles.entries()) {
         const intent = intents[index];
         if (!intent) continue;
+        const verified = await verifyBlobUploadFile(definition, intent, file);
+        const verifiedIntent = {
+          ...intent,
+          ...(verified.checksum ? { checksum: verified.checksum } : {}),
+        };
         const uploadId = id();
         await assertAuthorized(definition, {
           ctx,
           metadata,
-          file: intent,
+          file: verifiedIntent,
           uploadId,
         });
         const key = await definition.key({
           ctx,
           metadata,
-          file: intent,
+          file: verifiedIntent,
           uploadId,
         });
         const storageMetadata =
           (await definition.storageMetadata?.({
             ctx,
             metadata,
-            file: intent,
+            file: verifiedIntent,
             uploadId,
           })) ?? {};
         const object = await options.storage.put(key, file, {
-          contentType: intent.contentType,
+          contentType: verifiedIntent.contentType,
           ...(definition.file.cacheControl !== undefined
             ? { cacheControl: definition.file.cacheControl }
             : {}),
           metadata: storageMetadata,
           visibility: definition.file.visibility ?? "private",
         });
-        completed.push({
-          ...intent,
+        const completedFile = {
+          ...verifiedIntent,
           uploadId,
           key,
           object,
+        };
+        await assertVerifiedFile(definition, {
+          ctx,
+          metadata,
+          file: completedFile,
+          storage: options.storage,
         });
+        completed.push(completedFile);
       }
 
       const result = await definition.onComplete?.({
@@ -970,9 +1230,7 @@ function assertUploadContentLengthWithinLimit(
   const actualBytes = Number(contentLength);
   if (!Number.isFinite(actualBytes) || actualBytes < 0) return;
   if (actualBytes > context.maxBytes) {
-    throw new UploadError({
-      code: "UPLOAD_BODY_TOO_LARGE",
-      status: 413,
+    throw new UploadBodyTooLargeError({
       message: `Upload "${context.uploadName}" ${context.action} body is too large.`,
       details: {
         maxBytes: context.maxBytes,
@@ -996,9 +1254,7 @@ async function readLimitedRequestText(
     const text = await request.text();
     const actualBytes = new TextEncoder().encode(text).byteLength;
     if (actualBytes > context.maxBytes) {
-      throw new UploadError({
-        code: "UPLOAD_BODY_TOO_LARGE",
-        status: 413,
+      throw new UploadBodyTooLargeError({
         message: `Upload "${context.uploadName}" ${context.action} body is too large.`,
         details: {
           maxBytes: context.maxBytes,
@@ -1020,9 +1276,7 @@ async function readLimitedRequestText(
       if (result.done) break;
       actualBytes += result.value.byteLength;
       if (actualBytes > context.maxBytes) {
-        throw new UploadError({
-          code: "UPLOAD_BODY_TOO_LARGE",
-          status: 413,
+        throw new UploadBodyTooLargeError({
           message: `Upload "${context.uploadName}" ${context.action} body is too large.`,
           details: {
             maxBytes: context.maxBytes,
@@ -1052,9 +1306,7 @@ async function readJsonBody(
     return JSON.parse(await readLimitedRequestText(request, context));
   } catch (error) {
     if (error instanceof UploadError) throw error;
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: `Upload "${context.uploadName}" ${context.action} body must be valid JSON.`,
     });
   }
@@ -1115,9 +1367,7 @@ function parsePrepareInput(
     requireCompletedFileFields: false,
   });
   if (issues.length > 0) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: `Upload "${uploadName}" prepare body is invalid.`,
       details: { issues },
     });
@@ -1133,9 +1383,7 @@ function parseCompleteInput(
     requireCompletedFileFields: true,
   });
   if (issues.length > 0) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: `Upload "${uploadName}" complete body is invalid.`,
       details: { issues },
     });
@@ -1150,9 +1398,7 @@ async function parseMetadata<U extends UploadDef>(
   const result = await upload.metadata["~standard"].validate(input);
 
   if (result.issues?.length) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_METADATA",
-      status: 422,
+    throw new InvalidUploadMetadataError({
       message: `Invalid metadata for upload "${upload.name}".`,
       details: { issues: result.issues },
     });
@@ -1168,12 +1414,11 @@ async function parseMetadata<U extends UploadDef>(
 function assertFiles(
   upload: UploadDef,
   files: readonly UploadFileIntent[],
+  options: { requireChecksum?: boolean } = {},
 ): void {
   const maxFiles = upload.file.maxFiles ?? 1;
   if (files.length === 0 || files.length > maxFiles) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
-      status: 422,
+    throw new InvalidUploadFileError({
       message: `Upload "${upload.name}" requires between 1 and ${maxFiles} file${maxFiles === 1 ? "" : "s"}.`,
       details: { fileCount: files.length, maxFiles },
     });
@@ -1181,20 +1426,21 @@ function assertFiles(
 
   for (const file of files) {
     if (!file.name || !file.contentType || !Number.isFinite(file.size)) {
-      throw new UploadError({
-        code: "INVALID_UPLOAD_FILE",
-        status: 422,
+      throw new InvalidUploadFileError({
         message: `Upload "${upload.name}" received invalid file metadata.`,
         details: { file },
       });
     }
 
+    assertFileChecksum(upload, file, options);
+
     if (
       upload.file.contentTypes?.length &&
-      !upload.file.contentTypes.includes(file.contentType)
+      !upload.file.contentTypes
+        .map(normalizeContentType)
+        .includes(normalizeContentType(file.contentType))
     ) {
-      throw new UploadError({
-        code: "INVALID_UPLOAD_FILE",
+      throw new InvalidUploadFileError({
         status: 415,
         message: `Upload "${upload.name}" does not accept "${file.contentType}".`,
         details: {
@@ -1208,8 +1454,7 @@ function assertFiles(
       upload.file.maxSizeBytes !== undefined &&
       file.size > upload.file.maxSizeBytes
     ) {
-      throw new UploadError({
-        code: "INVALID_UPLOAD_FILE",
+      throw new InvalidUploadFileError({
         status: 413,
         message: `Upload "${upload.name}" exceeds the maximum file size.`,
         details: {
@@ -1221,6 +1466,408 @@ function assertFiles(
   }
 }
 
+function assertFileChecksum(
+  upload: UploadDef,
+  file: UploadFileIntent,
+  options: { requireChecksum?: boolean },
+): void {
+  const requirement = upload.file.checksum;
+  if (!requirement && !file.checksum) return;
+
+  const configuredAlgorithm = requirement?.algorithm as string | undefined;
+  if (configuredAlgorithm && configuredAlgorithm !== "sha256") {
+    throw new InvalidUploadFileError({
+      message: `Upload "${upload.name}" uses an unsupported checksum algorithm.`,
+      details: {
+        algorithm: configuredAlgorithm,
+      },
+    });
+  }
+
+  const required = requirement
+    ? requirement.required !== false && options.requireChecksum === true
+    : false;
+  if (!file.checksum) {
+    if (!required) return;
+    throw new InvalidUploadFileError({
+      message: `Upload "${upload.name}" requires a sha256 checksum for "${file.name}".`,
+      details: {
+        fileName: file.name,
+        algorithm: "sha256",
+      },
+    });
+  }
+
+  if (
+    file.checksum.algorithm !== "sha256" ||
+    !isSha256Hex(file.checksum.value)
+  ) {
+    throw new InvalidUploadFileError({
+      message: `Upload "${upload.name}" received an invalid checksum for "${file.name}".`,
+      details: {
+        fileName: file.name,
+        checksum: file.checksum,
+      },
+    });
+  }
+}
+
+const UPLOAD_SIGNATURE_MAX_BYTES = 512;
+
+type UploadFileBodyVerification = {
+  checksum?: UploadFileChecksum;
+};
+
+function needsUploadBodyVerification(
+  upload: UploadDef,
+  file: UploadFileIntent,
+): boolean {
+  return (
+    needsUploadChecksumVerification(upload, file) ||
+    needsUploadContentTypeVerification(upload, file)
+  );
+}
+
+function needsUploadChecksumVerification(
+  upload: UploadDef,
+  file: UploadFileIntent,
+): boolean {
+  return Boolean(
+    file.checksum ||
+      (upload.file.checksum && upload.file.checksum.required !== false),
+  );
+}
+
+function needsUploadContentTypeVerification(
+  upload: UploadDef,
+  file: UploadFileIntent,
+): boolean {
+  if (upload.file.contentTypeVerification === false) return false;
+
+  if (hasContentTypeSignature(file.contentType)) return true;
+  return Boolean(
+    upload.file.contentTypes?.some((contentType) =>
+      hasContentTypeSignature(contentType),
+    ),
+  );
+}
+
+async function verifyBlobUploadFile(
+  upload: UploadDef,
+  file: UploadFileIntent,
+  blob: Blob,
+): Promise<UploadFileBodyVerification> {
+  if (!needsUploadBodyVerification(upload, file)) return {};
+
+  const needsChecksum = needsUploadChecksumVerification(upload, file);
+  const bytes = needsChecksum
+    ? new Uint8Array(await blob.arrayBuffer())
+    : new Uint8Array(
+        await blob.slice(0, UPLOAD_SIGNATURE_MAX_BYTES).arrayBuffer(),
+      );
+
+  assertUploadContentTypeSignature(upload, file, bytes);
+
+  if (!needsChecksum) return {};
+  const checksum = await createUploadChecksum(bytes);
+  assertUploadChecksum(upload, file, checksum);
+  return { checksum };
+}
+
+async function verifyStoredUploadFile(
+  upload: UploadDef,
+  file: UploadFileIntent,
+  object: StorageObject | StorageObjectBody,
+): Promise<UploadFileBodyVerification> {
+  if (!needsUploadBodyVerification(upload, file)) return {};
+
+  if (!("bytes" in object)) {
+    throw new InvalidUploadFileError({
+      message: `Uploaded object "${object.key}" must be readable for verification.`,
+      details: {
+        key: object.key,
+      },
+    });
+  }
+
+  const needsChecksum = needsUploadChecksumVerification(upload, file);
+  const bytes = needsChecksum
+    ? await object.bytes()
+    : await readObjectPrefix(object, UPLOAD_SIGNATURE_MAX_BYTES);
+
+  assertUploadContentTypeSignature(upload, file, bytes);
+
+  if (!needsChecksum) return {};
+  const checksum = await createUploadChecksum(bytes);
+  assertUploadChecksum(upload, file, checksum);
+  return { checksum };
+}
+
+function storageObjectMetadata(object: StorageObject): StorageObject {
+  return {
+    key: object.key,
+    size: object.size,
+    ...(object.contentType !== undefined
+      ? { contentType: object.contentType }
+      : {}),
+    ...(object.cacheControl !== undefined
+      ? { cacheControl: object.cacheControl }
+      : {}),
+    metadata: object.metadata,
+    visibility: object.visibility,
+    lastModified: object.lastModified,
+  };
+}
+
+function assertUploadContentTypeSignature(
+  upload: UploadDef,
+  file: UploadFileIntent,
+  bytes: Uint8Array,
+): void {
+  if (upload.file.contentTypeVerification === false) return;
+
+  const declaredContentType = normalizeContentType(file.contentType);
+  const acceptedContentTypes =
+    upload.file.contentTypes?.map(normalizeContentType) ?? [];
+  const detectedContentType = detectSupportedContentType(bytes);
+
+  if (
+    detectedContentType &&
+    acceptedContentTypes.length > 0 &&
+    !acceptedContentTypes.includes(detectedContentType)
+  ) {
+    throw new InvalidUploadFileError({
+      status: 415,
+      message: `Upload "${upload.name}" does not accept detected content type "${detectedContentType}".`,
+      details: {
+        fileName: file.name,
+        declaredContentType,
+        detectedContentType,
+        acceptedContentTypes,
+      },
+    });
+  }
+
+  if (
+    hasContentTypeSignature(declaredContentType) &&
+    !matchesContentTypeSignature(declaredContentType, bytes)
+  ) {
+    throw new InvalidUploadFileError({
+      status: 415,
+      message: `Upload "${upload.name}" content type "${declaredContentType}" does not match the file bytes.`,
+      details: {
+        fileName: file.name,
+        expectedContentType: declaredContentType,
+        detectedContentType: detectedContentType ?? "unknown",
+      },
+    });
+  }
+}
+
+function assertUploadChecksum(
+  upload: UploadDef,
+  file: UploadFileIntent,
+  actual: UploadFileChecksum,
+): void {
+  if (!file.checksum) return;
+
+  if (file.checksum.value.toLowerCase() === actual.value) return;
+
+  throw new InvalidUploadFileError({
+    message: `Upload "${upload.name}" checksum does not match "${file.name}".`,
+    details: {
+      fileName: file.name,
+      algorithm: "sha256",
+      expected: file.checksum.value.toLowerCase(),
+      actual: actual.value,
+    },
+  });
+}
+
+async function assertVerifiedFile<Metadata, Ctx>(
+  upload: UploadDef<string, StandardSchema, Ctx>,
+  args: UploadVerifyFileHookArgs<Metadata, Ctx>,
+): Promise<void> {
+  if (!upload.verifyFile) return;
+
+  const result = await upload.verifyFile(
+    args as UploadVerifyFileHookArgs<InferUploadMetadata<typeof upload>, Ctx>,
+  );
+  const invalid =
+    result === false ||
+    (typeof result === "object" &&
+      result !== null &&
+      "valid" in result &&
+      result.valid === false);
+  if (!invalid) return;
+
+  throw new InvalidUploadFileError({
+    message:
+      typeof result === "object" && result?.reason
+        ? result.reason
+        : `Upload "${upload.name}" file "${args.file.name}" did not pass verification.`,
+    details:
+      typeof result === "object" && "details" in result
+        ? result.details
+        : {
+            fileName: args.file.name,
+            key: args.file.key,
+          },
+  });
+}
+
+async function readObjectPrefix(
+  object: StorageObjectBody,
+  maxBytes: number,
+): Promise<Uint8Array> {
+  const reader = object.stream().getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  try {
+    while (total < maxBytes) {
+      const result = await reader.read();
+      if (result.done) break;
+      const remaining = maxBytes - total;
+      const chunk =
+        result.value.byteLength > remaining
+          ? result.value.slice(0, remaining)
+          : result.value;
+      chunks.push(chunk);
+      total += chunk.byteLength;
+      if (result.value.byteLength > remaining) break;
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+async function createUploadChecksum(
+  bytes: Uint8Array,
+): Promise<UploadFileChecksum> {
+  if (!globalThis.crypto?.subtle) {
+    throw new InvalidUploadFileError({
+      message: "Upload checksum verification requires Web Crypto.",
+    });
+  }
+
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", buffer);
+  return {
+    algorithm: "sha256",
+    value: bytesToHex(new Uint8Array(digest)),
+  };
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function isSha256Hex(value: string): boolean {
+  return /^[a-f0-9]{64}$/i.test(value);
+}
+
+function normalizeContentType(contentType: string): string {
+  return contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+}
+
+function hasContentTypeSignature(contentType: string): boolean {
+  return SIGNATURE_CONTENT_TYPES.has(normalizeContentType(contentType));
+}
+
+function matchesContentTypeSignature(
+  contentType: string,
+  bytes: Uint8Array,
+): boolean {
+  const normalized = normalizeContentType(contentType);
+  switch (normalized) {
+    case "application/pdf":
+      return startsWithBytes(bytes, [0x25, 0x50, 0x44, 0x46, 0x2d]);
+    case "application/zip":
+      return (
+        startsWithBytes(bytes, [0x50, 0x4b, 0x03, 0x04]) ||
+        startsWithBytes(bytes, [0x50, 0x4b, 0x05, 0x06]) ||
+        startsWithBytes(bytes, [0x50, 0x4b, 0x07, 0x08])
+      );
+    case "image/gif":
+      return (
+        startsWithAscii(bytes, "GIF87a") || startsWithAscii(bytes, "GIF89a")
+      );
+    case "image/jpeg":
+      return startsWithBytes(bytes, [0xff, 0xd8, 0xff]);
+    case "image/png":
+      return startsWithBytes(
+        bytes,
+        [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+      );
+    case "image/svg+xml":
+      return looksLikeSvg(bytes);
+    case "image/webp":
+      return (
+        startsWithAscii(bytes, "RIFF") &&
+        bytes.length >= 12 &&
+        asciiAt(bytes, 8, 4) === "WEBP"
+      );
+    default:
+      return false;
+  }
+}
+
+function detectSupportedContentType(bytes: Uint8Array): string | undefined {
+  for (const contentType of SIGNATURE_CONTENT_TYPES) {
+    if (matchesContentTypeSignature(contentType, bytes)) return contentType;
+  }
+  return undefined;
+}
+
+const SIGNATURE_CONTENT_TYPES = new Set([
+  "application/pdf",
+  "application/zip",
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/svg+xml",
+  "image/webp",
+]);
+
+function startsWithBytes(
+  bytes: Uint8Array,
+  prefix: readonly number[],
+): boolean {
+  if (bytes.length < prefix.length) return false;
+  return prefix.every((byte, index) => bytes[index] === byte);
+}
+
+function startsWithAscii(bytes: Uint8Array, prefix: string): boolean {
+  return asciiAt(bytes, 0, prefix.length) === prefix;
+}
+
+function asciiAt(bytes: Uint8Array, offset: number, length: number): string {
+  return String.fromCharCode(...bytes.slice(offset, offset + length));
+}
+
+function looksLikeSvg(bytes: Uint8Array): boolean {
+  const text = new TextDecoder()
+    .decode(bytes)
+    .replace(/^\uFEFF/, "")
+    .trimStart()
+    .toLowerCase();
+  return (
+    text.startsWith("<svg") ||
+    (text.startsWith("<?xml") && text.includes("<svg"))
+  );
+}
+
 async function assertAuthorized<Metadata, Ctx>(
   upload: UploadDef<string, StandardSchema, Ctx>,
   args: UploadFileHookArgs<Metadata, Ctx>,
@@ -1228,9 +1875,7 @@ async function assertAuthorized<Metadata, Ctx>(
   if (!upload.authorize) {
     if ((upload.access ?? "protected") === "public") return;
 
-    throw new UploadError({
-      code: "UNAUTHORIZED_UPLOAD",
-      status: 403,
+    throw new UnauthorizedUploadError({
       message: `Upload "${upload.name}" must declare authorize(...) or set access: "public".`,
     });
   }
@@ -1246,9 +1891,7 @@ async function assertAuthorized<Metadata, Ctx>(
       result.allowed === false);
   if (!denied) return;
 
-  throw new UploadError({
-    code: "UNAUTHORIZED_UPLOAD",
-    status: 403,
+  throw new UnauthorizedUploadError({
     message:
       typeof result === "object" && result?.reason
         ? result.reason
@@ -1267,8 +1910,7 @@ function assertStoredObject(
     upload.file.maxSizeBytes !== undefined &&
     object.size > upload.file.maxSizeBytes
   ) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
+    throw new InvalidUploadFileError({
       status: 413,
       message: `Uploaded object "${object.key}" exceeds the maximum file size.`,
       details: {
@@ -1279,9 +1921,7 @@ function assertStoredObject(
   }
 
   if (object.size !== file.size) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
-      status: 422,
+    throw new InvalidUploadFileError({
       message: `Uploaded object "${object.key}" size does not match the prepared file.`,
       details: {
         expected: file.size,
@@ -1293,11 +1933,10 @@ function assertStoredObject(
   if (
     object.contentType &&
     file.contentType &&
-    object.contentType !== file.contentType
+    normalizeContentType(object.contentType) !==
+      normalizeContentType(file.contentType)
   ) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
-      status: 422,
+    throw new InvalidUploadFileError({
       message: `Uploaded object "${object.key}" content type does not match the prepared file.`,
       details: {
         expected: file.contentType,
@@ -1314,9 +1953,7 @@ function metadataFromFormData(formData: FormData): unknown {
   try {
     return JSON.parse(metadata);
   } catch {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: "Upload metadata must be valid JSON.",
     });
   }
@@ -1326,9 +1963,7 @@ function filesFromFormData(formData: FormData): File[] {
   const values = [...formData.getAll("file"), ...formData.getAll("files")];
   const files = values.filter((value): value is File => value instanceof File);
   if (files.length === 0) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: 'Multipart upload must include at least one "file" field.',
     });
   }
@@ -1336,9 +1971,11 @@ function filesFromFormData(formData: FormData): File[] {
 }
 
 function fileIntentFromFile(file: File): UploadFileIntent {
+  const contentType =
+    normalizeContentType(file.type) || "application/octet-stream";
   return {
     name: file.name,
-    contentType: file.type || "application/octet-stream",
+    contentType,
     size: file.size,
   };
 }