@beignet/core 0.0.32 → 0.0.34

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>;
@@ -613,6 +698,7 @@ export function defineUpload<
     ...(options.storageMetadata
       ? { storageMetadata: options.storageMetadata }
       : {}),
+    ...(options.verifyFile ? { verifyFile: options.verifyFile } : {}),
     ...(options.onComplete ? { onComplete: options.onComplete } : {}),
   };
 }
@@ -783,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) {
@@ -855,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) {
@@ -880,14 +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 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 });
@@ -930,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?.({
@@ -1299,6 +1414,7 @@ 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) {
@@ -1316,9 +1432,13 @@ function assertFiles(
       });
     }
 
+    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 InvalidUploadFileError({
         status: 415,
@@ -1346,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>,
@@ -1411,7 +1933,8 @@ function assertStoredObject(
   if (
     object.contentType &&
     file.contentType &&
-    object.contentType !== file.contentType
+    normalizeContentType(object.contentType) !==
+      normalizeContentType(file.contentType)
   ) {
     throw new InvalidUploadFileError({
       message: `Uploaded object "${object.key}" content type does not match the prepared file.`,
@@ -1448,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,
   };
 }