@beignet/core 0.0.2 → 0.0.3

package/src/uploads/index.ts

@@ -0,0 +1,1067 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { StorageMetadata, StorageObject, StoragePort } from "../ports";
+import type { ProviderInstrumentationTarget } from "../providers";
+import { createProviderInstrumentation } from "../providers";
+
+/**
+ * Any Standard Schema compatible validator.
+ */
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Value or promise of that value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Infer the parsed output type from a Standard Schema.
+ */
+export type InferSchemaOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+/**
+ * File metadata declared by a browser before an upload starts.
+ */
+export interface UploadFileIntent {
+  /**
+   * Original file name supplied by the client.
+   */
+  name: string;
+  /**
+   * MIME content type supplied by the client.
+   */
+  contentType: string;
+  /**
+   * File size in bytes.
+   */
+  size: number;
+}
+
+/**
+ * Constraints for files accepted by an upload definition.
+ */
+export interface UploadFileConstraints {
+  /**
+   * Accepted MIME content types. Omit to accept any content type.
+   */
+  contentTypes?: readonly string[];
+  /**
+   * Maximum accepted file size in bytes.
+   */
+  maxSizeBytes?: number;
+  /**
+   * Maximum files accepted by one request.
+   *
+   * @default 1
+   */
+  maxFiles?: number;
+  /**
+   * Object visibility written to storage.
+   *
+   * @default "private"
+   */
+  visibility?: "private" | "public";
+  /**
+   * Cache-Control value written to storage.
+   */
+  cacheControl?: string;
+}
+
+/**
+ * Parsed file intent with a generated upload id and storage key.
+ */
+export interface PreparedUploadFile extends UploadFileIntent {
+  /**
+   * Stable upload id used to correlate prepare, direct upload, and complete.
+   */
+  uploadId: string;
+  /**
+   * Storage key that should receive the file.
+   */
+  key: string;
+}
+
+/**
+ * Direct upload instruction returned by an upload signer.
+ */
+export interface DirectUploadInstruction {
+  method: "PUT";
+  url: string;
+  headers?: Record<string, string>;
+  expiresAt: string;
+}
+
+/**
+ * Arguments passed to an upload signer.
+ */
+export interface SignUploadArgs {
+  uploadName: string;
+  uploadId: string;
+  key: string;
+  file: UploadFileIntent;
+  metadata: unknown;
+  storage: {
+    visibility: "private" | "public";
+    cacheControl?: string;
+    metadata: StorageMetadata;
+  };
+}
+
+/**
+ * Port for providers that can create direct-upload instructions.
+ */
+export interface UploadSignerPort {
+  /**
+   * Create direct upload instructions for one prepared file.
+   */
+  sign(args: SignUploadArgs): MaybePromise<DirectUploadInstruction>;
+}
+
+/**
+ * Prepared upload file returned to clients.
+ */
+export interface PreparedUploadResultFile extends PreparedUploadFile {
+  /**
+   * Direct upload instruction when a signer is configured.
+   */
+  direct?: DirectUploadInstruction;
+}
+
+/**
+ * Result returned by `prepare(...)`.
+ */
+export interface PrepareUploadResult {
+  uploadName: string;
+  mode: "direct" | "server";
+  files: PreparedUploadResultFile[];
+}
+
+/**
+ * File object completed by direct upload or server upload.
+ */
+export interface CompletedUploadFile extends PreparedUploadFile {
+  object: StorageObject;
+}
+
+/**
+ * Result returned by upload completion.
+ */
+export interface CompleteUploadResult<Result = unknown> {
+  uploadName: string;
+  files: CompletedUploadFile[];
+  result: Result;
+}
+
+/**
+ * Input for `prepare(...)`.
+ */
+export interface PrepareUploadInput {
+  metadata: unknown;
+  files: readonly UploadFileIntent[];
+}
+
+/**
+ * Input for `complete(...)`.
+ */
+export interface CompleteUploadInput {
+  metadata: unknown;
+  files: readonly PreparedUploadFile[];
+}
+
+/**
+ * Input for server-handled multipart uploads.
+ */
+export interface ServerUploadInput {
+  formData: FormData;
+}
+
+/**
+ * Authorization result accepted by upload definitions.
+ */
+export type UploadAuthorizeResult =
+  | boolean
+  | undefined
+  | {
+      allowed: boolean;
+      reason?: string;
+    };
+
+/**
+ * Arguments passed to upload definition hooks.
+ */
+export interface UploadHookArgs<Metadata, Ctx> {
+  ctx: Ctx;
+  metadata: Metadata;
+}
+
+/**
+ * Arguments passed to file-specific upload hooks.
+ */
+export interface UploadFileHookArgs<Metadata, Ctx>
+  extends UploadHookArgs<Metadata, Ctx> {
+  file: UploadFileIntent;
+  uploadId: string;
+}
+
+/**
+ * Arguments passed to `onComplete(...)`.
+ */
+export interface UploadCompleteHookArgs<Metadata, Ctx>
+  extends UploadHookArgs<Metadata, Ctx> {
+  files: CompletedUploadFile[];
+}
+
+/**
+ * Upload definition options.
+ */
+export interface DefineUploadOptions<
+  MetadataSchema extends StandardSchema,
+  Ctx,
+  Result,
+> {
+  /**
+   * Metadata schema submitted with prepare, server upload, and complete calls.
+   */
+  metadata: MetadataSchema;
+  /**
+   * File constraints for this upload workflow.
+   */
+  file: UploadFileConstraints;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
+  description?: string;
+  /**
+   * Check whether the current actor may start this upload.
+   */
+  authorize?(
+    args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<UploadAuthorizeResult>;
+  /**
+   * Build the storage key for one file.
+   */
+  key(
+    args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<string>;
+  /**
+   * Add storage metadata for one file.
+   */
+  storageMetadata?(
+    args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<StorageMetadata>;
+  /**
+   * Run after files exist in storage.
+   */
+  onComplete?(
+    args: UploadCompleteHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<Result>;
+}
+
+/**
+ * Upload definition created by `defineUpload(...)`.
+ */
+export interface UploadDef<
+  Name extends string = string,
+  MetadataSchema extends StandardSchema = StandardSchema,
+  Ctx = unknown,
+  Result = unknown,
+> {
+  readonly kind: "upload";
+  readonly name: Name;
+  readonly metadata: MetadataSchema;
+  readonly file: UploadFileConstraints;
+  readonly description?: string;
+  authorize?(
+    args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<UploadAuthorizeResult>;
+  key(
+    args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<string>;
+  storageMetadata?(
+    args: UploadFileHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<StorageMetadata>;
+  onComplete?(
+    args: UploadCompleteHookArgs<InferSchemaOutput<MetadataSchema>, Ctx>,
+  ): MaybePromise<Result>;
+}
+
+/**
+ * Infer the parsed metadata type for an upload definition.
+ */
+export type InferUploadMetadata<U extends UploadDef> =
+  U["metadata"] extends StandardSchemaV1<unknown, infer Output>
+    ? Output
+    : never;
+
+/**
+ * Infer the result returned by an upload definition's completion hook.
+ */
+export type InferUploadResult<U extends UploadDef> =
+  U extends UploadDef<string, StandardSchema, unknown, infer Result>
+    ? Result
+    : unknown;
+
+/**
+ * Nested upload registry shape used by server registration and typed clients.
+ */
+export interface UploadRegistry {
+  /**
+   * Upload definition or nested upload registry.
+   */
+  readonly [key: string]: UploadDef | UploadRegistry;
+}
+
+/**
+ * Infer every upload definition contained in a nested upload registry.
+ */
+export type UploadFromRegistry<Registry> = Registry extends UploadDef
+  ? Registry
+  : Registry extends readonly (infer Upload)[]
+    ? Upload extends UploadDef
+      ? Upload
+      : never
+    : Registry extends object
+      ? {
+          [Key in keyof Registry]: UploadFromRegistry<Registry[Key]>;
+        }[keyof Registry]
+      : never;
+
+/**
+ * Client-safe upload metadata generated from server upload definitions.
+ */
+export interface UploadManifestEntry {
+  /**
+   * Upload route name.
+   */
+  name: string;
+  /**
+   * Optional human-readable upload description.
+   */
+  description?: string;
+  /**
+   * File constraints safe to expose to browser UI code.
+   */
+  file: UploadFileConstraints;
+}
+
+/**
+ * Options for `createUploadRouter(...)`.
+ */
+export interface CreateUploadRouterOptions<Ctx> {
+  /**
+   * Upload definitions registered with this router.
+   */
+  uploads: readonly UploadDef<string, StandardSchema, Ctx, unknown>[];
+  /**
+   * Request context value or lazy context factory.
+   */
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  /**
+   * Storage port used for server uploads and direct upload completion checks.
+   */
+  storage: StoragePort;
+  /**
+   * Optional signer used to prepare direct upload instructions.
+   */
+  signer?: UploadSignerPort;
+  /**
+   * Optional instrumentation target used by devtools/provider watchers.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+  /**
+   * Optional upload id generator for tests or custom id policies.
+   */
+  id?: () => string;
+}
+
+/**
+ * Framework-neutral upload router.
+ */
+export interface UploadRouter {
+  prepare(
+    uploadName: string,
+    input: PrepareUploadInput,
+  ): Promise<PrepareUploadResult>;
+  complete(
+    uploadName: string,
+    input: CompleteUploadInput,
+  ): Promise<CompleteUploadResult>;
+  upload(
+    uploadName: string,
+    input: ServerUploadInput,
+  ): Promise<CompleteUploadResult>;
+  handleRequest(
+    request: Request,
+    options: { uploadName: string; action: "prepare" | "complete" | "upload" },
+  ): Promise<Response>;
+}
+
+/**
+ * Machine-readable upload error codes.
+ */
+export type UploadErrorCode =
+  | "UPLOAD_NOT_FOUND"
+  | "INVALID_UPLOAD_ACTION"
+  | "INVALID_UPLOAD_METADATA"
+  | "INVALID_UPLOAD_FILE"
+  | "UNAUTHORIZED_UPLOAD"
+  | "UPLOAD_OBJECT_NOT_FOUND"
+  | "INVALID_UPLOAD_BODY";
+
+/**
+ * Error thrown for expected upload failures.
+ */
+export class UploadError extends Error {
+  readonly code: UploadErrorCode;
+  readonly status: number;
+  readonly details?: unknown;
+
+  constructor(args: {
+    code: UploadErrorCode;
+    message: string;
+    status?: number;
+    details?: unknown;
+  }) {
+    super(args.message);
+    this.name = "UploadError";
+    this.code = args.code;
+    this.status = args.status ?? 400;
+    this.details = args.details;
+  }
+}
+
+/**
+ * Define a typed upload workflow.
+ */
+export function defineUpload<
+  const Name extends string,
+  MetadataSchema extends StandardSchema,
+  Ctx = unknown,
+  Result = unknown,
+>(
+  name: Name,
+  options: DefineUploadOptions<MetadataSchema, Ctx, Result>,
+): UploadDef<Name, MetadataSchema, Ctx, Result> {
+  return {
+    kind: "upload",
+    name,
+    metadata: options.metadata,
+    file: {
+      ...options.file,
+      maxFiles: options.file.maxFiles ?? 1,
+      visibility: options.file.visibility ?? "private",
+    },
+    ...(options.description !== undefined
+      ? { description: options.description }
+      : {}),
+    ...(options.authorize ? { authorize: options.authorize } : {}),
+    key: options.key,
+    ...(options.storageMetadata
+      ? { storageMetadata: options.storageMetadata }
+      : {}),
+    ...(options.onComplete ? { onComplete: options.onComplete } : {}),
+  };
+}
+
+/**
+ * Define a nested upload registry while preserving upload names and metadata
+ * types for client code.
+ */
+export function defineUploads<const Uploads extends UploadRegistry>(
+  uploads: Uploads,
+): Uploads {
+  return uploads;
+}
+
+/**
+ * Flatten a nested upload registry into the list expected by
+ * `createUploadRouter(...)`.
+ */
+export function uploadsFromRegistry(
+  uploads: UploadRegistry | readonly UploadDef[],
+): UploadDef[] {
+  if (Array.isArray(uploads)) return [...uploads];
+
+  const result: UploadDef[] = [];
+  for (const value of Object.values(uploads)) {
+    if (isUploadDef(value)) {
+      result.push(value);
+    } else {
+      result.push(...uploadsFromRegistry(value));
+    }
+  }
+  return result;
+}
+
+/**
+ * Create client-safe upload metadata for browser helpers.
+ */
+export function createUploadManifest(
+  uploads: UploadRegistry | readonly UploadDef[],
+): UploadManifestEntry[] {
+  return uploadsFromRegistry(uploads).map((upload) => ({
+    name: upload.name,
+    ...(upload.description !== undefined
+      ? { description: upload.description }
+      : {}),
+    file: upload.file,
+  }));
+}
+
+/**
+ * Create deterministic direct upload instructions for tests.
+ */
+export function createMemoryUploadSigner(
+  options: { baseUrl?: string; expiresAt?: string } = {},
+): UploadSignerPort {
+  const baseUrl = options.baseUrl ?? "https://uploads.beignet.test";
+  const expiresAt = options.expiresAt ?? "2100-01-01T00:00:00.000Z";
+
+  return {
+    sign(args) {
+      return {
+        method: "PUT",
+        url: `${baseUrl}/${encodeURIComponent(args.key)}`,
+        headers: {
+          "content-type": args.file.contentType,
+        },
+        expiresAt,
+      };
+    },
+  };
+}
+
+/**
+ * Create a framework-neutral upload router.
+ */
+export function createUploadRouter<Ctx>(
+  options: CreateUploadRouterOptions<Ctx>,
+): UploadRouter {
+  const uploads = new Map(
+    options.uploads.map((upload) => [upload.name, upload]),
+  );
+  const id = options.id ?? randomUploadId;
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "uploads",
+      watcher: "uploads",
+    },
+  );
+
+  async function resolveCtx(): Promise<Ctx> {
+    return typeof options.ctx === "function"
+      ? (options.ctx as () => MaybePromise<Ctx>)()
+      : options.ctx;
+  }
+
+  function findUpload(name: string) {
+    const upload = uploads.get(name);
+    if (!upload) {
+      throw new UploadError({
+        code: "UPLOAD_NOT_FOUND",
+        status: 404,
+        message: `Upload "${name}" is not registered.`,
+      });
+    }
+    return upload;
+  }
+
+  async function prepare(uploadName: string, input: PrepareUploadInput) {
+    const startedAt = Date.now();
+    instrumentation.custom({
+      name: "upload.prepare.started",
+      label: "Upload prepare started",
+      summary: uploadName,
+    });
+
+    try {
+      const upload = findUpload(uploadName);
+      const ctx = await resolveCtx();
+      const metadata = await parseMetadata(upload, input.metadata);
+      assertFiles(upload, input.files);
+
+      const files: PreparedUploadResultFile[] = [];
+      for (const file of input.files) {
+        const uploadId = id();
+        await assertAuthorized(upload, { ctx, metadata, file, uploadId });
+        const key = await upload.key({ ctx, metadata, file, uploadId });
+        const storageMetadata =
+          (await upload.storageMetadata?.({ ctx, metadata, file, uploadId })) ??
+          {};
+        const prepared: PreparedUploadResultFile = {
+          ...file,
+          uploadId,
+          key,
+        };
+
+        if (options.signer) {
+          prepared.direct = await options.signer.sign({
+            uploadName,
+            uploadId,
+            key,
+            file,
+            metadata,
+            storage: {
+              visibility: upload.file.visibility ?? "private",
+              ...(upload.file.cacheControl !== undefined
+                ? { cacheControl: upload.file.cacheControl }
+                : {}),
+              metadata: storageMetadata,
+            },
+          });
+        }
+
+        files.push(prepared);
+      }
+
+      instrumentation.custom({
+        name: "upload.prepare.completed",
+        label: "Upload prepare completed",
+        summary: `${uploadName} (${files.length} file${files.length === 1 ? "" : "s"})`,
+        details: {
+          uploadName,
+          mode: options.signer ? "direct" : "server",
+          fileCount: files.length,
+          durationMs: Date.now() - startedAt,
+        },
+      });
+
+      return {
+        uploadName,
+        mode: options.signer ? "direct" : "server",
+        files,
+      } satisfies PrepareUploadResult;
+    } catch (error) {
+      recordFailure("upload.prepare.failed", uploadName, startedAt, error);
+      throw error;
+    }
+  }
+
+  async function complete(uploadName: string, input: CompleteUploadInput) {
+    const startedAt = Date.now();
+    instrumentation.custom({
+      name: "upload.complete.started",
+      label: "Upload complete started",
+      summary: uploadName,
+    });
+
+    try {
+      const upload = findUpload(uploadName);
+      const ctx = await resolveCtx();
+      const metadata = await parseMetadata(upload, input.metadata);
+      assertFiles(upload, input.files);
+
+      const files: CompletedUploadFile[] = [];
+      for (const file of input.files) {
+        await assertAuthorized(upload, {
+          ctx,
+          metadata,
+          file,
+          uploadId: file.uploadId,
+        });
+        const expectedKey = await upload.key({
+          ctx,
+          metadata,
+          file,
+          uploadId: file.uploadId,
+        });
+        if (file.key !== expectedKey) {
+          throw new UploadError({
+            code: "INVALID_UPLOAD_FILE",
+            status: 422,
+            message: `Uploaded object key does not match upload "${upload.name}".`,
+            details: {
+              expectedKey,
+              actualKey: file.key,
+            },
+          });
+        }
+        const object = await options.storage.stat(file.key);
+        if (!object) {
+          throw new UploadError({
+            code: "UPLOAD_OBJECT_NOT_FOUND",
+            status: 404,
+            message: `Uploaded object "${file.key}" was not found.`,
+          });
+        }
+        assertStoredObject(upload, file, object);
+        files.push({ ...file, object });
+      }
+
+      const result = await upload.onComplete?.({ ctx, metadata, files });
+      instrumentation.custom({
+        name: "upload.complete.completed",
+        label: "Upload complete completed",
+        summary: `${uploadName} (${files.length} file${files.length === 1 ? "" : "s"})`,
+        details: {
+          uploadName,
+          fileCount: files.length,
+          durationMs: Date.now() - startedAt,
+        },
+      });
+
+      return {
+        uploadName,
+        files,
+        result,
+      } satisfies CompleteUploadResult;
+    } catch (error) {
+      recordFailure("upload.complete.failed", uploadName, startedAt, error);
+      throw error;
+    }
+  }
+
+  async function upload(uploadName: string, input: ServerUploadInput) {
+    const startedAt = Date.now();
+    instrumentation.custom({
+      name: "upload.server.started",
+      label: "Server upload started",
+      summary: uploadName,
+    });
+
+    try {
+      const definition = findUpload(uploadName);
+      const ctx = await resolveCtx();
+      const metadata = await parseMetadata(
+        definition,
+        metadataFromFormData(input.formData),
+      );
+      const webFiles = filesFromFormData(input.formData);
+      const intents = webFiles.map(fileIntentFromFile);
+      assertFiles(definition, intents);
+
+      const completed: CompletedUploadFile[] = [];
+      for (const [index, file] of webFiles.entries()) {
+        const intent = intents[index];
+        if (!intent) continue;
+        const uploadId = id();
+        await assertAuthorized(definition, {
+          ctx,
+          metadata,
+          file: intent,
+          uploadId,
+        });
+        const key = await definition.key({
+          ctx,
+          metadata,
+          file: intent,
+          uploadId,
+        });
+        const storageMetadata =
+          (await definition.storageMetadata?.({
+            ctx,
+            metadata,
+            file: intent,
+            uploadId,
+          })) ?? {};
+        const object = await options.storage.put(key, file, {
+          contentType: intent.contentType,
+          ...(definition.file.cacheControl !== undefined
+            ? { cacheControl: definition.file.cacheControl }
+            : {}),
+          metadata: storageMetadata,
+          visibility: definition.file.visibility ?? "private",
+        });
+        completed.push({
+          ...intent,
+          uploadId,
+          key,
+          object,
+        });
+      }
+
+      const result = await definition.onComplete?.({
+        ctx,
+        metadata,
+        files: completed,
+      });
+      instrumentation.custom({
+        name: "upload.server.completed",
+        label: "Server upload completed",
+        summary: `${uploadName} (${completed.length} file${completed.length === 1 ? "" : "s"})`,
+        details: {
+          uploadName,
+          fileCount: completed.length,
+          durationMs: Date.now() - startedAt,
+        },
+      });
+
+      return {
+        uploadName,
+        files: completed,
+        result,
+      } satisfies CompleteUploadResult;
+    } catch (error) {
+      recordFailure("upload.server.failed", uploadName, startedAt, error);
+      throw error;
+    }
+  }
+
+  function recordFailure(
+    name: string,
+    uploadName: string,
+    startedAt: number,
+    error: unknown,
+  ) {
+    instrumentation.custom({
+      name,
+      label: "Upload failed",
+      summary: uploadName,
+      details: {
+        uploadName,
+        durationMs: Date.now() - startedAt,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+
+  return {
+    prepare,
+    complete,
+    upload,
+    async handleRequest(request, requestOptions) {
+      try {
+        if (requestOptions.action === "prepare") {
+          const input = (await request.json()) as PrepareUploadInput;
+          return jsonResponse(await prepare(requestOptions.uploadName, input));
+        }
+
+        if (requestOptions.action === "complete") {
+          const input = (await request.json()) as CompleteUploadInput;
+          return jsonResponse(await complete(requestOptions.uploadName, input));
+        }
+
+        const formData = await request.formData();
+        return jsonResponse(
+          await upload(requestOptions.uploadName, {
+            formData,
+          }),
+        );
+      } catch (error) {
+        return uploadErrorResponse(error);
+      }
+    },
+  };
+}
+
+async function parseMetadata<U extends UploadDef>(
+  upload: U,
+  input: unknown,
+): Promise<InferUploadMetadata<U>> {
+  const result = await upload.metadata["~standard"].validate(input);
+
+  if (result.issues?.length) {
+    throw new UploadError({
+      code: "INVALID_UPLOAD_METADATA",
+      status: 422,
+      message: `Invalid metadata for upload "${upload.name}".`,
+      details: { issues: result.issues },
+    });
+  }
+
+  if ("value" in result) {
+    return result.value as InferUploadMetadata<U>;
+  }
+
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+function assertFiles(
+  upload: UploadDef,
+  files: readonly UploadFileIntent[],
+): void {
+  const maxFiles = upload.file.maxFiles ?? 1;
+  if (files.length === 0 || files.length > maxFiles) {
+    throw new UploadError({
+      code: "INVALID_UPLOAD_FILE",
+      status: 422,
+      message: `Upload "${upload.name}" requires between 1 and ${maxFiles} file${maxFiles === 1 ? "" : "s"}.`,
+      details: { fileCount: files.length, maxFiles },
+    });
+  }
+
+  for (const file of files) {
+    if (!file.name || !file.contentType || !Number.isFinite(file.size)) {
+      throw new UploadError({
+        code: "INVALID_UPLOAD_FILE",
+        status: 422,
+        message: `Upload "${upload.name}" received invalid file metadata.`,
+        details: { file },
+      });
+    }
+
+    if (
+      upload.file.contentTypes?.length &&
+      !upload.file.contentTypes.includes(file.contentType)
+    ) {
+      throw new UploadError({
+        code: "INVALID_UPLOAD_FILE",
+        status: 415,
+        message: `Upload "${upload.name}" does not accept "${file.contentType}".`,
+        details: {
+          contentType: file.contentType,
+          acceptedContentTypes: upload.file.contentTypes,
+        },
+      });
+    }
+
+    if (
+      upload.file.maxSizeBytes !== undefined &&
+      file.size > upload.file.maxSizeBytes
+    ) {
+      throw new UploadError({
+        code: "INVALID_UPLOAD_FILE",
+        status: 413,
+        message: `Upload "${upload.name}" exceeds the maximum file size.`,
+        details: {
+          size: file.size,
+          maxSizeBytes: upload.file.maxSizeBytes,
+        },
+      });
+    }
+  }
+}
+
+async function assertAuthorized<Metadata, Ctx>(
+  upload: UploadDef<string, StandardSchema, Ctx>,
+  args: UploadFileHookArgs<Metadata, Ctx>,
+): Promise<void> {
+  const result = await upload.authorize?.(
+    args as UploadFileHookArgs<InferUploadMetadata<typeof upload>, Ctx>,
+  );
+  const denied =
+    result === false ||
+    (typeof result === "object" &&
+      result !== null &&
+      "allowed" in result &&
+      result.allowed === false);
+  if (!denied) return;
+
+  throw new UploadError({
+    code: "UNAUTHORIZED_UPLOAD",
+    status: 403,
+    message:
+      typeof result === "object" && result?.reason
+        ? result.reason
+        : `Upload "${upload.name}" is not authorized.`,
+  });
+}
+
+function assertStoredObject(
+  upload: UploadDef,
+  file: UploadFileIntent,
+  object: StorageObject,
+): void {
+  assertFiles(upload, [file]);
+
+  if (
+    object.contentType &&
+    file.contentType &&
+    object.contentType !== file.contentType
+  ) {
+    throw new UploadError({
+      code: "INVALID_UPLOAD_FILE",
+      status: 422,
+      message: `Uploaded object "${object.key}" content type does not match the prepared file.`,
+      details: {
+        expected: file.contentType,
+        actual: object.contentType,
+      },
+    });
+  }
+}
+
+function metadataFromFormData(formData: FormData): unknown {
+  const metadata = formData.get("metadata");
+  if (typeof metadata !== "string") return {};
+
+  try {
+    return JSON.parse(metadata);
+  } catch {
+    throw new UploadError({
+      code: "INVALID_UPLOAD_BODY",
+      status: 400,
+      message: "Upload metadata must be valid JSON.",
+    });
+  }
+}
+
+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,
+      message: 'Multipart upload must include at least one "file" field.',
+    });
+  }
+  return files;
+}
+
+function fileIntentFromFile(file: File): UploadFileIntent {
+  return {
+    name: file.name,
+    contentType: file.type || "application/octet-stream",
+    size: file.size,
+  };
+}
+
+function jsonResponse(body: unknown, init?: ResponseInit): Response {
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+  };
+  if (init?.headers) {
+    new Headers(init.headers).forEach((value, key) => {
+      headers[key] = value;
+    });
+  }
+
+  return new Response(JSON.stringify(body), {
+    status: init?.status ?? 200,
+    headers,
+  });
+}
+
+function uploadErrorResponse(error: unknown): Response {
+  if (error instanceof UploadError) {
+    return jsonResponse(
+      {
+        error: {
+          code: error.code,
+          message: error.message,
+          ...(error.details !== undefined ? { details: error.details } : {}),
+        },
+      },
+      { status: error.status },
+    );
+  }
+
+  return jsonResponse(
+    {
+      error: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Internal server error",
+      },
+    },
+    { status: 500 },
+  );
+}
+
+function randomUploadId(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID();
+  }
+
+  return `upload_${Math.random().toString(36).slice(2)}`;
+}
+
+function isUploadDef(value: UploadDef | UploadRegistry): value is UploadDef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "upload"
+  );
+}