@dimah-s3/server 1.0.2 → 1.1.1

package/dist/plugins.js

@@ -1,10 +1,28 @@
-import { S3_API_ROUTES, isAPIError, DimahS3Error, S3_ERROR_CODES, confirmBodySchema, deleteQuerySchema, downloadQuerySchema, multipartAbortBodySchema, multipartCompleteBodySchema, multipartInitBodySchema, multipartListPartsQuerySchema, multipartSignPartBodySchema, uploadBodySchema, parseFileName, S3_MAX_EXPIRES_IN, buildContentDisposition, S3_MAX_POST_OBJECT_BYTES, S3_DEFAULT_EXPIRES_IN } from '@dimah-s3/core';
-import { DeleteObjectCommand, GetObjectCommand, CreateMultipartUploadCommand, UploadPartCommand, PutObjectCommand, GetObjectAclCommand, ListPartsCommand, CompleteMultipartUploadCommand, HeadObjectCommand, AbortMultipartUploadCommand } from '@aws-sdk/client-s3';
+import { S3_API_ROUTES, isAPIError, DimahS3Error, S3_ERROR_CODES, confirmBodySchema, deleteQuerySchema, isDimahS3Error, deleteBatchBodySchema, downloadQuerySchema, fileQuerySchema, multipartAbortBodySchema, multipartCompleteBodySchema, multipartInitBodySchema, multipartListPartsQuerySchema, multipartSignPartBodySchema, uploadBodySchema, S3_MAX_EXPIRES_IN, buildContentDisposition, S3_MAX_POST_OBJECT_BYTES, resolveStoredFileName, S3_DEFAULT_EXPIRES_IN, matchesFileTypes, ROUTE_NAME_PATTERN, normalizeObjectKey, sanitizeFileName } from '@dimah-s3/core';
+import { DeleteObjectCommand, GetObjectCommand, CreateMultipartUploadCommand, UploadPartCommand, PutObjectCommand, ListPartsCommand, AbortMultipartUploadCommand, CompleteMultipartUploadCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
 import { createMiddleware, createEndpoint } from 'better-call';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { createPresignedPost } from '@aws-sdk/s3-presigned-post';
 
 // src/plugin/apply-plugins.ts
+async function deleteObjectBestEffort(client, bucket, key) {
+  try {
+    await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+  } catch {
+  }
+}
+async function abortMultipartBestEffort(client, bucket, key, uploadId) {
+  try {
+    await client.send(
+      new AbortMultipartUploadCommand({
+        Bucket: bucket,
+        Key: key,
+        UploadId: uploadId
+      })
+    );
+  } catch {
+  }
+}
 var errors = {
   notFound: () => DimahS3Error.from("NOT_FOUND", S3_ERROR_CODES.NOT_FOUND),
   unauthorized: () => DimahS3Error.from("UNAUTHORIZED", S3_ERROR_CODES.UNAUTHORIZED),
@@ -21,10 +39,18 @@ var errors = {
     params: { feature }
   }),
   invalidKey: () => DimahS3Error.from("BAD_REQUEST", S3_ERROR_CODES.INVALID_KEY),
-  invalidBucket: (bucket) => DimahS3Error.from("FORBIDDEN", {
-    code: S3_ERROR_CODES.INVALID_BUCKET.code,
-    message: S3_ERROR_CODES.INVALID_BUCKET.message,
-    params: { bucket }
+  unknownRoute: (route) => DimahS3Error.from("NOT_FOUND", {
+    code: S3_ERROR_CODES.UNKNOWN_ROUTE.code,
+    message: S3_ERROR_CODES.UNKNOWN_ROUTE.message,
+    params: { route }
+  }),
+  fileTypeNotAllowed: (fileName, contentType) => DimahS3Error.from("BAD_REQUEST", {
+    code: S3_ERROR_CODES.FILE_TYPE_NOT_ALLOWED.code,
+    message: S3_ERROR_CODES.FILE_TYPE_NOT_ALLOWED.message,
+    params: {
+      fileName,
+      ...contentType ? { contentType } : {}
+    }
   }),
   s3NetworkError: (code) => DimahS3Error.from("BAD_GATEWAY", {
     code: S3_ERROR_CODES.S3_NETWORK_ERROR.code,
@@ -34,11 +60,6 @@ var errors = {
     ),
     params: { code }
   }),
-  fileSizeRequiredUpload: () => DimahS3Error.from("BAD_REQUEST", S3_ERROR_CODES.FILE_SIZE_REQUIRED_UPLOAD),
-  fileSizeRequiredMultipart: () => DimahS3Error.from(
-    "BAD_REQUEST",
-    S3_ERROR_CODES.FILE_SIZE_REQUIRED_MULTIPART
-  ),
   multipartPartMissing: (partNumber) => DimahS3Error.from("BAD_REQUEST", {
     code: S3_ERROR_CODES.MULTIPART_PART_MISSING.code,
     message: S3_ERROR_CODES.MULTIPART_PART_MISSING.message.replaceAll(
@@ -51,6 +72,10 @@ var errors = {
     ...S3_ERROR_CODES.PAYLOAD_TOO_LARGE,
     message
   }),
+  quotaExceeded: (message = S3_ERROR_CODES.QUOTA_EXCEEDED.message) => DimahS3Error.from("PAYLOAD_TOO_LARGE", {
+    ...S3_ERROR_CODES.QUOTA_EXCEEDED,
+    message
+  }),
   validationError: (message) => DimahS3Error.from("BAD_REQUEST", {
     code: S3_ERROR_CODES.VALIDATION_ERROR.code,
     message
@@ -70,119 +95,366 @@ async function sendOrObjectNotFound(send) {
     throw err;
   }
 }
-var DEFAULT_ACL_LOOKUP_TIMEOUT_MS = 1500;
-async function resolveObjectAcl(s3, bucket, key, timeoutMs = DEFAULT_ACL_LOOKUP_TIMEOUT_MS) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const result = await s3.send(
-      new GetObjectAclCommand({ Bucket: bucket, Key: key }),
-      { abortSignal: controller.signal }
-    );
-    const isPublic = result.Grants?.some(
-      (g) => g.Grantee?.URI === "http://acs.amazonaws.com/groups/global/AllUsers" && (g.Permission === "READ" || g.Permission === "FULL_CONTROL")
-    );
-    return isPublic ? "public-read" : "private";
-  } catch {
-    return void 0;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-// src/helpers/resolve-request-acl.ts
-function resolveRequestAcl(policy, requested) {
-  if (policy?.acl) return policy.acl;
-  if (policy?.allowClientAcl && requested) return requested;
-  return "private";
-}
 function normalizeExpiresIn(value, maxExpiresIn = S3_MAX_EXPIRES_IN) {
   const n = Number(value);
   const expires = Number.isFinite(n) && n > 0 ? Math.floor(n) : S3_DEFAULT_EXPIRES_IN;
   const max = Number.isFinite(maxExpiresIn) && maxExpiresIn > 0 ? Math.floor(maxExpiresIn) : S3_MAX_EXPIRES_IN;
   return Math.min(expires, max);
 }
+
+// src/helpers/logger.ts
+var defaultLogger = {
+  error: (message, ...args) => {
+    console.error("[dimah-s3]", message, ...args);
+  },
+  warn: (message, ...args) => {
+    console.warn("[dimah-s3]", message, ...args);
+  }
+};
+function resolveLogger(logger) {
+  if (logger === false) return {};
+  if (!logger) return defaultLogger;
+  return logger;
+}
+
+// src/helpers/hooks.ts
+function mapGuardError(err) {
+  if (isAPIError(err)) throw err;
+  if (err instanceof Error && err.message.trim()) {
+    throw new DimahS3Error("FORBIDDEN", {
+      message: err.message,
+      cause: err
+    });
+  }
+  throw errors.forbidden();
+}
 async function runHook(hook, context) {
   if (!hook) return;
   try {
     await hook(context);
   } catch (err) {
-    if (isAPIError(err)) throw err;
-    if (err instanceof Error && err.message.trim()) {
-      throw new DimahS3Error("FORBIDDEN", {
-        message: err.message,
-        cause: err
-      });
-    }
-    throw errors.forbidden();
+    mapGuardError(err);
   }
 }
-async function runLifecycleHook(hook, context) {
+async function runObjectHook(hook, context) {
+  if (!hook) return;
+  try {
+    return await hook(context);
+  } catch (err) {
+    mapGuardError(err);
+  }
+}
+async function runLifecycleHook(hook, context, config) {
   if (!hook) return;
   try {
     await hook(context);
   } catch (err) {
     if (isAPIError(err)) throw err;
-    console.error("[S3 API] lifecycle hook failed", err);
+    resolveLogger(config?.logger).error?.("lifecycle hook failed", err);
+    config?.onError?.(err, { request: context.request });
     throw errors.internalError();
   }
 }
 
-// src/helpers/request.ts
-function requestFromHeaders(headers) {
-  return new Request("http://dimah-s3.local", { headers });
+// src/helpers/previous-key.ts
+var DIMAH_PREVIOUS_KEY_META = "dimah-previous-key";
+function stripPreviousKeyMeta(metadata) {
+  if (!metadata) return {};
+  const { [DIMAH_PREVIOUS_KEY_META]: _omit, ...rest } = metadata;
+  return rest;
+}
+function previousKeyFromMetadata(metadata) {
+  const value = metadata?.[DIMAH_PREVIOUS_KEY_META]?.trim();
+  return value || void 0;
 }
 
 // src/helpers/resolve-target.ts
 function assertSafeObjectKey(key) {
-  const trimmed = key.replace(/^\/+/u, "").replace(/\/+$/u, "");
-  if (!trimmed) {
-    throw errors.invalidKey();
-  }
-  if (trimmed.includes("\\") || trimmed.includes("\0")) {
-    throw errors.invalidKey();
-  }
-  const parts = trimmed.split("/");
-  if (parts.some((part) => part === "" || part === "." || part === "..")) {
-    throw errors.invalidKey();
-  }
-  return parts.join("/");
+  const normalized = normalizeObjectKey(key);
+  if (!normalized) throw errors.invalidKey();
+  return normalized;
 }
 function applyPrefix(prefix, key) {
   const p = assertSafeObjectKey(prefix);
   const k = assertSafeObjectKey(key);
-  if (k === p || k.startsWith(`${p}/`)) return k;
+  if (k.startsWith(`${p}/`)) return k;
+  if (k === p) throw errors.invalidKey();
   return `${p}/${k}`;
 }
-async function resolveObjectKey(policy, context) {
-  if (policy?.resolveKey) {
-    return assertSafeObjectKey(await policy.resolveKey(context));
+function nestKeyUnderPrefix(keyPrefix, key) {
+  const safe = assertSafeObjectKey(key);
+  if (keyPrefix === false) return safe;
+  return applyPrefix(keyPrefix, safe);
+}
+function assertStoredKey(key, keyPrefix) {
+  const safe = assertSafeObjectKey(key);
+  if (keyPrefix === false) return safe;
+  const root = assertSafeObjectKey(keyPrefix);
+  if (safe.startsWith(`${root}/`)) return safe;
+  throw errors.invalidKey();
+}
+function objectKeyFileName(fileName) {
+  const sanitized = sanitizeFileName(fileName);
+  const leaf = sanitized.split("/").filter((part) => part.length > 0).at(-1);
+  if (!leaf || leaf === "." || leaf === "..") return "file";
+  return leaf;
+}
+function generateObjectKey(folder, fileName) {
+  const leaf = `${crypto.randomUUID()}/${objectKeyFileName(fileName)}`;
+  if (folder === false) return assertSafeObjectKey(leaf);
+  return applyPrefix(folder, leaf);
+}
+function resolveAcl(info, route) {
+  return info?.acl ?? route.upload.acl ?? "private";
+}
+async function resolveUploadTarget(route, context) {
+  const bucket = route.bucket;
+  const objectContext = {
+    ...context,
+    bucket,
+    keyPrefix: route.keyPrefix
+  };
+  const info = await runObjectHook(route.upload.object, objectContext) ?? void 0;
+  const key = info?.key ? nestKeyUnderPrefix(route.keyPrefix, info.key) : generateObjectKey(
+    info?.folder != null && info.folder !== "" ? nestKeyUnderPrefix(route.keyPrefix, info.folder) : route.keyPrefix === false ? false : route.keyPrefix,
+    context.file.name
+  );
+  const metadata = { ...info?.metadata };
+  if (info?.previousKey) {
+    metadata[DIMAH_PREVIOUS_KEY_META] = nestKeyUnderPrefix(
+      route.keyPrefix,
+      info.previousKey
+    );
   }
-  const prefix = typeof policy?.prefix === "function" ? await policy.prefix(context) : policy?.prefix;
-  if (prefix) {
-    return applyPrefix(prefix, context.proposedKey);
+  return {
+    key,
+    bucket,
+    metadata: Object.keys(metadata).length > 0 ? metadata : info?.metadata,
+    acl: resolveAcl(info, route)
+  };
+}
+function resolveStoredTarget(route, key) {
+  return {
+    key: assertStoredKey(key, route.keyPrefix),
+    bucket: route.bucket
+  };
+}
+function assertRouteName(name) {
+  if (!ROUTE_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `dimahS3 route "${name}" is invalid. Use a letter followed by up to 63 letters, digits, underscores, or hyphens.`
+    );
   }
-  return assertSafeObjectKey(context.proposedKey);
 }
-function resolveBucket(config, requested) {
-  if (!requested) return config.bucket;
-  if (config.allowClientBucket) return requested;
-  if (config.buckets?.length) {
-    if (config.buckets.includes(requested)) return requested;
-    throw errors.invalidBucket(requested);
+
+// src/helpers/features.ts
+function isEnabled(feature) {
+  return feature.enabled;
+}
+function resolveKeyPrefix(name, value) {
+  if (value === false) return false;
+  const normalized = normalizeObjectKey(value ?? name);
+  if (!normalized) {
+    throw new Error(
+      `dimahS3 route "${name}": keyPrefix is not a valid object-key prefix.`
+    );
   }
-  return config.bucket;
+  return normalized;
 }
-async function resolveRequestTarget(config, policy, input) {
-  const bucket = resolveBucket(config, input.bucket);
-  const key = await resolveObjectKey(policy, {
-    request: input.request,
-    proposedKey: input.key,
-    fileName: input.fileName,
-    contentType: input.contentType,
-    bucket
+function isFeatureOn(value, defaultOn = false) {
+  if (value === false) return false;
+  if (value === void 0) return defaultOn;
+  if (value === true) return true;
+  if ("enabled" in value && typeof value.enabled === "boolean") {
+    return value.enabled;
+  }
+  return true;
+}
+function normalizeFeature(value, defaultOn = false) {
+  if (value === false) return { enabled: false };
+  if (value === void 0) {
+    if (!defaultOn) return { enabled: false };
+    return { enabled: true };
+  }
+  if (value === true) return { enabled: true };
+  return { ...value, enabled: true };
+}
+function skippedPluginIds(plugins) {
+  const ids = /* @__PURE__ */ new Set();
+  if (!plugins) return ids;
+  for (const [id, enabled] of Object.entries(plugins)) {
+    if (enabled === false) ids.add(id);
+  }
+  return ids;
+}
+function splitUpload(upload2) {
+  if (upload2 === void 0 || typeof upload2 === "boolean") {
+    return { upload: upload2, multipart: void 0 };
+  }
+  const { multipart, ...rest } = upload2;
+  return { upload: rest, multipart };
+}
+function normalizeRoute(name, route, instance) {
+  assertRouteName(name);
+  const client = route.client ?? instance.client;
+  const bucket = route.bucket ?? instance.bucket;
+  if (!client) {
+    throw new Error(
+      `dimahS3 route "${name}": set client on the route or on dimahS3().`
+    );
+  }
+  if (!bucket) {
+    throw new Error(
+      `dimahS3 route "${name}": set bucket on the route or on dimahS3().`
+    );
+  }
+  const { upload: uploadInput, multipart: multipartInput } = splitUpload(
+    route.upload
+  );
+  const upload2 = normalizeFeature(uploadInput);
+  const download2 = normalizeFeature(route.download);
+  const deleteFeature = normalizeFeature(route.delete);
+  const multipart = normalizeFeature(multipartInput);
+  if (!upload2.enabled && !download2.enabled && !deleteFeature.enabled) {
+    throw new Error(
+      `dimahS3 route "${name}": enable upload, download, or delete.`
+    );
+  }
+  const resolvedUpload = upload2.enabled ? { ...upload2, multipart } : { enabled: false, multipart: { enabled: false } };
+  if (resolvedUpload.enabled) {
+    const maxFileSize = resolvedUpload.maxFileSize;
+    if (maxFileSize != null && (!Number.isFinite(maxFileSize) || maxFileSize <= 0)) {
+      throw new Error(
+        `dimahS3 route "${name}": maxFileSize must be a positive number.`
+      );
+    }
+  }
+  return {
+    name,
+    client,
+    bucket,
+    keyPrefix: resolveKeyPrefix(name, route.keyPrefix),
+    guard: route.guard,
+    skippedPluginIds: skippedPluginIds(route.plugins),
+    upload: resolvedUpload,
+    download: download2,
+    delete: deleteFeature
+  };
+}
+function normalizeRoutes(config) {
+  const entries = Object.entries(config.routes);
+  if (entries.length === 0) {
+    throw new Error("dimahS3: at least one route is required.");
+  }
+  const routes = {};
+  for (const [name, route] of entries) {
+    routes[name] = normalizeRoute(name, route, config);
+  }
+  assertDistinctKeyPrefixes(routes);
+  return routes;
+}
+function prefixesOverlap(a, b) {
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+function assertDistinctKeyPrefixes(routes) {
+  const named = Object.entries(routes).filter(
+    (entry) => entry[1].keyPrefix !== false
+  );
+  for (let i = 0; i < named.length; i++) {
+    for (let j = i + 1; j < named.length; j++) {
+      const [nameA, routeA] = named[i];
+      const [nameB, routeB] = named[j];
+      if (prefixesOverlap(routeA.keyPrefix, routeB.keyPrefix)) {
+        throw new Error(
+          `dimahS3: routes "${nameA}" and "${nameB}" have overlapping keyPrefix values ("${routeA.keyPrefix}" and "${routeB.keyPrefix}").`
+        );
+      }
+    }
+  }
+}
+
+// src/helpers/request.ts
+function requestFromHeaders(headers) {
+  return new Request("http://dimah-s3.local", { headers });
+}
+function assertWithinMaxFileSize(maxFileSize, size) {
+  if (typeof maxFileSize === "number" && size > maxFileSize) {
+    throw errors.payloadTooLarge();
+  }
+}
+function assertDeclaredConstraints(constraints, input) {
+  if (constraints?.fileTypes?.length && !matchesFileTypes(input.fileName, input.contentType, constraints.fileTypes)) {
+    throw errors.fileTypeNotAllowed(input.fileName, input.contentType);
+  }
+  assertWithinMaxFileSize(constraints?.maxFileSize, input.fileSize);
+}
+function assertVerifiedConstraints(constraints, input) {
+  assertWithinMaxFileSize(constraints?.maxFileSize, input.contentLength);
+  const name = input.fileName ?? "";
+  if (constraints?.fileTypes?.length && !matchesFileTypes(name, input.contentType, constraints.fileTypes)) {
+    throw errors.fileTypeNotAllowed(name || "unknown", input.contentType);
+  }
+}
+
+// src/helpers/resolve-route.ts
+function getResolvedRoute(config, name) {
+  const route = config.routes[name];
+  if (!route) {
+    throw errors.unknownRoute(name);
+  }
+  return route;
+}
+function featureIsEnabled(route, feature) {
+  if (feature === "multipart") return route.upload.multipart.enabled;
+  return route[feature].enabled;
+}
+function assertFeatureEnabled(route, feature) {
+  if (!featureIsEnabled(route, feature)) {
+    throw errors.featureDisabled(feature);
+  }
+}
+async function openRoute(config, name, request, feature) {
+  const route = getResolvedRoute(config, name);
+  assertFeatureEnabled(route, feature);
+  await runHook(route.guard, { request, route: route.name });
+  return route;
+}
+function storedObjectContext(request, route, key) {
+  return { request, route: route.name, key, bucket: route.bucket };
+}
+async function openUploadTarget(config, input, request, feature) {
+  const route = await openRoute(config, input.route, request, feature);
+  const fileSize = Math.floor(input.fileSize);
+  const fileName = input.fileName;
+  assertDeclaredConstraints(route.upload, {
+    fileName,
+    fileSize,
+    contentType: input.contentType
+  });
+  const target = await resolveUploadTarget(route, {
+    request,
+    route: route.name,
+    file: {
+      name: fileName,
+      size: fileSize,
+      type: input.contentType
+    },
+    clientMetadata: input.metadata
   });
-  return { key, bucket };
+  return {
+    route,
+    ...target,
+    stored: storedObjectContext(request, route, target.key)
+  };
+}
+async function openStoredTarget(config, input, request, feature) {
+  const route = await openRoute(config, input.route, request, feature);
+  const target = resolveStoredTarget(route, input.key);
+  return {
+    route,
+    ...target,
+    stored: storedObjectContext(request, route, target.key)
+  };
 }
 async function headObjectOrNotFound(client, bucket, key) {
   return sendOrObjectNotFound(
@@ -194,7 +466,7 @@ async function headObjectAfterMultipartComplete(client, bucket, key) {
     () => client.send(new HeadObjectCommand({ Bucket: bucket, Key: key }))
   );
   let head = await send();
-  for (let attempt = 0; attempt < 4 && !head.ContentLength; attempt++) {
+  for (let attempt = 0; attempt < 4 && typeof head.ContentLength !== "number"; attempt++) {
     await new Promise((r) => setTimeout(r, 250 * 2 ** attempt));
     head = await send();
   }
@@ -227,61 +499,70 @@ async function listAllParts(client, input) {
   }
   return parts;
 }
-
-// src/helpers/features.ts
-function normalizeFeature(value) {
-  if (value === void 0) return void 0;
-  if (value === false) return { enabled: false };
-  if (value === true) return { enabled: true };
-  return { ...value, enabled: true };
-}
-function isFeatureEnabled(config, feature) {
-  return config[feature]?.enabled === true;
-}
-function applyMultipartDefault(config, multipartInput) {
-  let next = config;
-  if (multipartInput === void 0 && config.upload?.enabled) {
-    next = {
-      ...config,
-      multipart: { ...config.multipart, enabled: true }
-    };
-  }
-  if (next.multipart && next.upload) {
-    next = {
-      ...next,
-      multipart: {
-        ...next.multipart,
-        prefix: next.multipart.prefix ?? next.upload.prefix,
-        resolveKey: next.multipart.resolveKey ?? next.upload.resolveKey,
-        acl: next.multipart.acl ?? next.upload.acl,
-        allowClientAcl: next.multipart.allowClientAcl ?? next.upload.allowClientAcl,
-        requireFileSize: next.multipart.requireFileSize ?? next.upload.requireFileSize
-      }
-    };
+function listedPartsByteSize(parts, excludePartNumber) {
+  let total = 0;
+  for (const part of parts) {
+    if (excludePartNumber !== void 0 && part.PartNumber === excludePartNumber) {
+      continue;
+    }
+    total += part.Size ?? 0;
   }
-  return next;
+  return total;
 }
-function normalizeFeatures(config) {
-  return {
-    upload: normalizeFeature(config.upload),
-    download: normalizeFeature(config.download),
-    delete: normalizeFeature(config.delete),
-    multipart: normalizeFeature(config.multipart)
+async function finalizeConfirmedObject(client, bucket, key, input) {
+  const { config, route, stored, head, uploadId, acl } = input;
+  const contentLength = requireContentLength(head);
+  const fileName = resolveStoredFileName(head.ContentDisposition, key);
+  const rawMetadata = head.Metadata ?? {};
+  try {
+    assertVerifiedConstraints(route.upload, {
+      fileName,
+      contentType: head.ContentType,
+      contentLength
+    });
+  } catch (err) {
+    await deleteObjectBestEffort(client, bucket, key);
+    throw err;
+  }
+  const metadata = stripPreviousKeyMeta(rawMetadata);
+  const context = {
+    ...stored,
+    contentType: head.ContentType,
+    contentLength,
+    eTag: head.ETag?.replace(/"/g, ""),
+    metadata,
+    acl,
+    fileName,
+    versionId: head.VersionId,
+    lastModified: head.LastModified?.toISOString(),
+    uploadId
   };
-}
-function assertExclusiveBucketFlags(config) {
-  if (config.allowClientBucket && config.buckets?.length) {
-    throw new Error(
-      "dimahS3: set either allowClientBucket or buckets, not both. allowClientBucket honors any client-sent bucket; buckets is an allowlist."
-    );
+  try {
+    await runLifecycleHook(route.upload.onConfirmed, context, config);
+  } catch (err) {
+    await deleteObjectBestEffort(client, bucket, key);
+    throw err;
   }
-}
-
-// src/api/assert-feature-enabled.ts
-function assertFeatureEnabled(config, feature) {
-  if (!isFeatureEnabled(config, feature)) {
-    throw errors.featureDisabled(feature);
+  const previousKey = previousKeyFromMetadata(rawMetadata);
+  if (previousKey && previousKey !== key) {
+    try {
+      const safe = assertStoredKey(previousKey, route.keyPrefix);
+      await deleteObjectBestEffort(client, bucket, safe);
+    } catch {
+    }
   }
+  return {
+    key,
+    bucket,
+    contentType: context.contentType,
+    contentLength: context.contentLength,
+    eTag: context.eTag,
+    metadata: context.metadata ?? {},
+    acl,
+    fileName,
+    versionId: context.versionId,
+    lastModified: context.lastModified
+  };
 }
 var s3ContextMiddleware = createMiddleware(async (ctx) => {
   const injected = ctx.context;
@@ -329,138 +610,269 @@ var createS3Endpoint = ((pathOrOptions, optionsOrHandler, maybeHandler) => {
 
 // src/api/routes/confirm.ts
 async function handleConfirm(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.upload, {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key: input.key,
-    bucket: input.bucket
+    "upload"
+  );
+  await runHook(route.upload.confirmGuard, {
+    ...stored,
+    replace: route.upload.replace
   });
-  await runHook(config.upload?.confirmGuard, {
-    request,
-    key,
-    bucket
+  const head = await headObjectOrNotFound(route.client, bucket, key);
+  return finalizeConfirmedObject(route.client, bucket, key, {
+    config,
+    route,
+    stored,
+    head,
+    acl: route.upload.acl
   });
-  const head = await headObjectOrNotFound(config.client, bucket, key);
-  const acl = config.resolveObjectAcl ? await resolveObjectAcl(config.client, bucket, key) : void 0;
-  const fileName = parseFileName(head.ContentDisposition);
-  const context = {
-    request,
-    key,
-    bucket,
-    contentType: head.ContentType,
-    contentLength: requireContentLength(head),
-    eTag: head.ETag?.replace(/"/g, ""),
-    metadata: head.Metadata,
-    acl,
-    fileName,
-    versionId: head.VersionId,
-    lastModified: head.LastModified?.toISOString()
-  };
-  await runLifecycleHook(config.upload?.onConfirmed, context);
-  return {
-    key,
-    bucket,
-    contentType: context.contentType,
-    contentLength: context.contentLength,
-    eTag: context.eTag,
-    metadata: context.metadata ?? {},
-    acl,
-    fileName,
-    versionId: context.versionId,
-    lastModified: context.lastModified
-  };
 }
 var confirm = createS3Endpoint(
   S3_API_ROUTES.uploadConfirm,
   { method: "POST", body: confirmBodySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "upload");
     return handleConfirm(ctx.context.config, ctx.body, ctx.context.request);
   }
 );
 async function handleDelete(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.delete, {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key: input.key,
-    bucket: input.bucket
-  });
-  await runHook(config.delete?.guard, {
-    request,
-    key,
-    bucket
-  });
-  await headObjectOrNotFound(config.client, bucket, key);
-  await config.client.send(
+    "delete"
+  );
+  await runHook(route.delete.guard, stored);
+  await headObjectOrNotFound(route.client, bucket, key);
+  await route.client.send(
     new DeleteObjectCommand({ Bucket: bucket, Key: key })
   );
-  await runLifecycleHook(config.delete?.onDeleted, { request, key, bucket });
+  await runLifecycleHook(route.delete.onDeleted, stored, config);
   return { success: true, bucket, key };
 }
 var deleteObject = createS3Endpoint(
   S3_API_ROUTES.delete,
   { method: "DELETE", query: deleteQuerySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "delete");
     return handleDelete(ctx.context.config, ctx.query, ctx.context.request);
   }
 );
+async function deleteOne(config, routeName, key, request) {
+  const { route, bucket, stored } = await openStoredTarget(
+    config,
+    { route: routeName, key },
+    request,
+    "delete"
+  );
+  await runHook(route.delete.guard, stored);
+  await headObjectOrNotFound(route.client, bucket, stored.key);
+  await route.client.send(
+    new DeleteObjectCommand({ Bucket: bucket, Key: stored.key })
+  );
+  await runLifecycleHook(route.delete.onDeleted, stored, config);
+}
+var deleteBatch = createS3Endpoint(
+  S3_API_ROUTES.deleteBatch,
+  { method: "POST", body: deleteBatchBodySchema },
+  async (ctx) => {
+    const config = ctx.context.config;
+    const request = ctx.context.request;
+    const results = [];
+    for (const key of ctx.body.keys) {
+      try {
+        await deleteOne(config, ctx.body.route, key, request);
+        results.push({ key, success: true });
+      } catch (err) {
+        results.push({
+          key,
+          success: false,
+          error: isDimahS3Error(err) ? { code: err.code ?? "INTERNAL_ERROR", message: err.message } : { code: "INTERNAL_ERROR", message: "Internal server error" }
+        });
+      }
+    }
+    return { results };
+  }
+);
+function fileUrl(request, basePath, query) {
+  const url = new URL(request.url);
+  const prefix = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  url.pathname = `${prefix}${S3_API_ROUTES.file}`;
+  url.search = "";
+  url.searchParams.set("route", query.route);
+  url.searchParams.set("key", query.key);
+  if (query.fileName) url.searchParams.set("fileName", query.fileName);
+  if (query.disposition) url.searchParams.set("disposition", query.disposition);
+  return url.toString();
+}
 async function handleDownload(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.download, {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key: input.key,
-    bucket: input.bucket,
-    fileName: input.fileName
+    "download"
+  );
+  const resolved = await route.download.resolve?.({
+    ...stored,
+    fileName: input.fileName,
+    disposition: input.disposition ?? route.download.disposition
   });
-  const expiresIn = normalizeExpiresIn(input.expiresIn, config.maxExpiresIn);
-  const fileName = input.fileName;
-  await runHook(config.download?.guard, {
-    request,
-    key,
-    bucket,
-    fileName
+  const fileName = resolved?.fileName ?? input.fileName;
+  const disposition = resolved?.disposition ?? input.disposition ?? route.download.disposition ?? "attachment";
+  const expiresIn = normalizeExpiresIn(
+    resolved?.expiresIn ?? route.download.expiresIn,
+    config.maxExpiresIn
+  );
+  await runHook(route.download.guard, {
+    ...stored,
+    fileName,
+    disposition
   });
-  await headObjectOrNotFound(config.client, bucket, key);
-  const url = await getSignedUrl(
-    config.client,
+  await headObjectOrNotFound(route.client, bucket, key);
+  const mode = route.download.mode ?? "presign";
+  const contentDisposition = fileName ? buildContentDisposition(fileName, disposition) : disposition;
+  const url = mode === "proxy" ? fileUrl(request, config.basePath ?? "/api/s3", {
+    route: input.route,
+    key,
+    fileName,
+    disposition
+  }) : await getSignedUrl(
+    route.client,
     new GetObjectCommand({
       Bucket: bucket,
       Key: key,
-      ResponseContentDisposition: fileName ? buildContentDisposition(fileName) : "attachment"
+      ResponseContentDisposition: contentDisposition
     }),
     { expiresIn }
   );
-  await runLifecycleHook(config.download?.onPresigned, {
-    request,
-    key,
+  await runLifecycleHook(
+    route.download.onPresigned,
+    {
+      ...stored,
+      fileName,
+      url,
+      expiresIn: mode === "proxy" ? 0 : expiresIn
+    },
+    config
+  );
+  return {
     bucket,
-    fileName,
+    key,
     url,
-    expiresIn
-  });
-  return { bucket, key, url, expiresIn };
+    expiresIn: mode === "proxy" ? 0 : expiresIn,
+    mode,
+    disposition
+  };
 }
 var download = createS3Endpoint(
   S3_API_ROUTES.download,
   { method: "GET", query: downloadQuerySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "download");
     return handleDownload(ctx.context.config, ctx.query, ctx.context.request);
   }
 );
-async function handleAbort(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.multipart, {
+function catalogUpload(upload2) {
+  if (!isEnabled(upload2)) return { enabled: false };
+  return {
+    enabled: true,
+    fileTypes: upload2.fileTypes,
+    maxFileSize: upload2.maxFileSize,
+    multipart: isEnabled(upload2.multipart),
+    ...upload2.checksum ? { checksum: true } : {},
+    ...upload2.replace ? { replace: upload2.replace } : {}
+  };
+}
+function catalogDownload(download2) {
+  if (!isEnabled(download2)) return { enabled: false };
+  return {
+    enabled: true,
+    ...download2.disposition ? { disposition: download2.disposition } : {},
+    ...download2.mode ? { mode: download2.mode } : {}
+  };
+}
+function buildRouteCatalog(config) {
+  const routes = {};
+  for (const [name, route] of Object.entries(config.routes)) {
+    routes[name] = {
+      upload: catalogUpload(route.upload),
+      download: catalogDownload(route.download),
+      delete: isEnabled(route.delete) ? { enabled: true } : { enabled: false }
+    };
+  }
+  return { routes };
+}
+var catalog = createS3Endpoint(
+  S3_API_ROUTES.catalog,
+  { method: "GET" },
+  async (ctx) => {
+    return buildRouteCatalog(ctx.context.config);
+  }
+);
+async function handleFile(config, input, request) {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key: input.key,
-    bucket: input.bucket
+    "download"
+  );
+  const resolved = await route.download.resolve?.({
+    ...stored,
+    fileName: input.fileName,
+    disposition: input.disposition ?? route.download.disposition
   });
-  const uploadId = input.uploadId;
-  await runHook(config.multipart?.abortGuard, {
+  const fileName = resolved?.fileName ?? input.fileName;
+  const disposition = resolved?.disposition ?? input.disposition ?? route.download.disposition ?? "attachment";
+  await runHook(route.download.guard, {
+    ...stored,
+    fileName,
+    disposition
+  });
+  await headObjectOrNotFound(route.client, bucket, key);
+  const result = await sendOrObjectNotFound(
+    () => route.client.send(
+      new GetObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        ResponseContentDisposition: fileName ? buildContentDisposition(fileName, disposition) : `${disposition}`
+      })
+    )
+  );
+  const body = result.Body;
+  if (!body) throw errors.objectNotFound();
+  const stream = "transformToWebStream" in body && typeof body.transformToWebStream === "function" ? body.transformToWebStream() : body;
+  const headers = new Headers();
+  headers.set("Content-Type", result.ContentType ?? "application/octet-stream");
+  headers.set(
+    "Content-Disposition",
+    fileName ? buildContentDisposition(fileName, disposition) : `${disposition}`
+  );
+  if (typeof result.ContentLength === "number") {
+    headers.set("Content-Length", String(result.ContentLength));
+  }
+  return new Response(stream, { headers });
+}
+var file = createS3Endpoint(
+  S3_API_ROUTES.file,
+  { method: "GET", query: fileQuerySchema },
+  async (ctx) => {
+    return handleFile(ctx.context.config, ctx.query, ctx.context.request);
+  }
+);
+async function handleAbort(config, input, request) {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key,
-    bucket,
-    uploadId
+    "multipart"
+  );
+  const uploadId = input.uploadId;
+  await runHook(route.upload.multipart.guard, {
+    ...stored,
+    uploadId,
+    action: "abort"
   });
   await sendOrObjectNotFound(
-    () => config.client.send(
+    () => route.client.send(
       new AbortMultipartUploadCommand({
         Bucket: bucket,
         Key: key,
@@ -468,52 +880,68 @@ async function handleAbort(config, input, request) {
       })
     )
   );
-  await runLifecycleHook(config.multipart?.onAbort, {
-    request,
-    key,
-    bucket,
-    uploadId
-  });
+  await runLifecycleHook(
+    route.upload.multipart.onAbort,
+    {
+      ...stored,
+      uploadId
+    },
+    config
+  );
   return { bucket, key, uploadId, aborted: true };
 }
 var multipartAbort = createS3Endpoint(
   S3_API_ROUTES.multipartAbort,
   { method: "POST", body: multipartAbortBodySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "multipart");
     return handleAbort(ctx.context.config, ctx.body, ctx.context.request);
   }
 );
 async function handleComplete(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.multipart, {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key: input.key,
-    bucket: input.bucket
-  });
+    "multipart"
+  );
   const uploadId = input.uploadId;
-  const parts = input.parts.map(({ partNumber }) => partNumber).sort((a, b) => a - b);
+  const parts = [
+    ...new Set(input.parts.map(({ partNumber }) => partNumber))
+  ].sort((a, b) => a - b);
   const partRefs = parts.map((partNumber) => ({ partNumber }));
-  await runHook(config.multipart?.completeGuard, {
-    request,
-    key,
-    bucket,
+  await runHook(route.upload.multipart.guard, {
+    ...stored,
+    uploadId,
+    action: "complete"
+  });
+  await runHook(route.upload.confirmGuard, {
+    ...stored,
     uploadId,
-    parts: partRefs
+    parts: partRefs,
+    replace: route.upload.replace
   });
-  const listedParts = await listAllParts(config.client, {
+  const listedParts = await listAllParts(route.client, {
     bucket,
     key,
     uploadId
   });
+  let assembledBytes = 0;
   const completeParts = parts.map((partNumber) => {
     const found = listedParts.find((p) => p.PartNumber === partNumber);
     if (!found?.ETag) {
       throw errors.multipartPartMissing(partNumber);
     }
+    assembledBytes += found.Size ?? 0;
     return { PartNumber: partNumber, ETag: found.ETag };
   });
+  try {
+    assertWithinMaxFileSize(route.upload.maxFileSize, assembledBytes);
+  } catch (err) {
+    await abortMultipartBestEffort(route.client, bucket, key, uploadId);
+    throw err;
+  }
   const completeResult = await sendOrObjectNotFound(
-    () => config.client.send(
+    () => route.client.send(
       new CompleteMultipartUploadCommand({
         Bucket: bucket,
         Key: key,
@@ -523,273 +951,290 @@ async function handleComplete(config, input, request) {
     )
   );
   const head = await headObjectAfterMultipartComplete(
-    config.client,
+    route.client,
     bucket,
     key
   );
-  const contentLength = requireContentLength(head);
-  const contentType = head.ContentType;
-  const eTag = (head.ETag ?? completeResult.ETag ?? "").replace(/"/g, "");
-  const metadata = head.Metadata ?? {};
-  const versionId = head.VersionId;
-  const lastModified = head.LastModified?.toISOString();
-  const acl = config.resolveObjectAcl ? await resolveObjectAcl(config.client, bucket, key) : void 0;
-  const fileName = parseFileName(head.ContentDisposition);
-  await runLifecycleHook(config.multipart?.onComplete, {
-    request,
-    key,
-    bucket,
+  const confirmed = await finalizeConfirmedObject(route.client, bucket, key, {
+    config,
+    route,
+    stored,
+    head: {
+      ...head,
+      ETag: head.ETag ?? completeResult.ETag
+    },
     uploadId,
-    contentLength,
-    contentType,
-    eTag,
-    metadata,
-    acl,
-    fileName,
-    versionId,
-    lastModified
+    acl: route.upload.acl
   });
-  return {
-    bucket,
-    key,
-    uploadId,
-    contentLength,
-    contentType,
-    eTag,
-    metadata,
-    acl,
-    fileName,
-    versionId,
-    lastModified
-  };
+  return { ...confirmed, uploadId };
 }
 var multipartComplete = createS3Endpoint(
   S3_API_ROUTES.multipartComplete,
   { method: "POST", body: multipartCompleteBodySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "multipart");
     return handleComplete(ctx.context.config, ctx.body, ctx.context.request);
   }
 );
 async function handleMultipartInit(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.multipart, {
-    request,
-    key: input.key,
-    bucket: input.bucket,
-    fileName: input.fileName,
-    contentType: input.contentType
-  });
-  const acl = resolveRequestAcl(config.multipart, input.acl);
-  const fileSize = typeof input.fileSize === "number" && input.fileSize > 0 ? Math.floor(input.fileSize) : void 0;
-  if (config.multipart?.requireFileSize && fileSize === void 0) {
-    throw errors.fileSizeRequiredMultipart();
-  }
-  await runHook(config.multipart?.initGuard, {
+  const fileSize = Math.floor(input.fileSize);
+  const fileName = input.fileName;
+  const { route, key, bucket, metadata, acl, stored } = await openUploadTarget(
+    config,
+    {
+      route: input.route,
+      fileName,
+      fileSize,
+      contentType: input.contentType,
+      metadata: input.metadata
+    },
     request,
-    key,
-    bucket,
-    fileSize,
-    contentType: input.contentType,
-    metadata: input.metadata,
+    "multipart"
+  );
+  await runHook(route.upload.guard, {
+    ...stored,
+    file: {
+      name: fileName,
+      size: fileSize,
+      type: input.contentType
+    },
+    metadata,
+    clientMetadata: input.metadata,
     acl,
-    fileName: input.fileName
+    replace: route.upload.replace
   });
-  const { UploadId } = await config.client.send(
+  const { UploadId } = await route.client.send(
     new CreateMultipartUploadCommand({
       Bucket: bucket,
       Key: key,
       ContentType: input.contentType,
-      ContentDisposition: input.fileName ? buildContentDisposition(input.fileName) : void 0,
-      Metadata: input.metadata,
+      ContentDisposition: buildContentDisposition(fileName),
+      Metadata: metadata,
       ACL: acl
     })
   );
   if (!UploadId) {
     throw errors.internalError();
   }
-  await runLifecycleHook(config.multipart?.onInit, {
-    request,
-    key,
-    bucket,
-    uploadId: UploadId,
-    contentType: input.contentType,
-    fileSize,
-    metadata: input.metadata,
-    acl,
-    fileName: input.fileName
-  });
+  await runLifecycleHook(
+    route.upload.multipart.onInit,
+    {
+      ...stored,
+      uploadId: UploadId,
+      file: {
+        name: fileName,
+        size: fileSize,
+        type: input.contentType
+      },
+      metadata,
+      clientMetadata: input.metadata,
+      acl,
+      replace: route.upload.replace
+    },
+    config
+  );
   return { bucket, key, uploadId: UploadId };
 }
 var multipartInit = createS3Endpoint(
   S3_API_ROUTES.multipartInit,
   { method: "POST", body: multipartInitBodySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "multipart");
-    ctx.setStatus(201);
-    return handleMultipartInit(
+    const result = await handleMultipartInit(
       ctx.context.config,
       ctx.body,
       ctx.context.request
     );
+    ctx.setStatus(201);
+    return result;
   }
 );
 async function handleListParts(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.multipart, {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key: input.key,
-    bucket: input.bucket
-  });
+    "multipart"
+  );
   const uploadId = input.uploadId;
-  await runHook(config.multipart?.listGuard, {
-    request,
-    key,
-    bucket,
-    uploadId
-  });
-  const listed = await listAllParts(config.client, { bucket, key, uploadId });
-  const parts = listed.map((p) => ({
-    partNumber: p.PartNumber ?? 0,
-    size: p.Size ?? 0,
-    eTag: (p.ETag ?? "").replace(/"/g, "")
-  }));
-  await runLifecycleHook(config.multipart?.onList, {
-    request,
-    key,
-    bucket,
+  await runHook(route.upload.multipart.guard, {
+    ...stored,
     uploadId,
-    parts
+    action: "list"
+  });
+  const listed = await listAllParts(route.client, { bucket, key, uploadId });
+  const parts = listed.flatMap((p) => {
+    if (p.PartNumber == null || p.PartNumber < 1) return [];
+    return [
+      {
+        partNumber: p.PartNumber,
+        size: p.Size ?? 0,
+        eTag: (p.ETag ?? "").replace(/"/g, "")
+      }
+    ];
   });
+  await runLifecycleHook(
+    route.upload.multipart.onList,
+    {
+      ...stored,
+      uploadId,
+      parts
+    },
+    config
+  );
   return { parts };
 }
 var multipartListParts = createS3Endpoint(
   S3_API_ROUTES.multipartListParts,
   { method: "GET", query: multipartListPartsQuerySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "multipart");
     return handleListParts(ctx.context.config, ctx.query, ctx.context.request);
   }
 );
 async function handleSignPart(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.multipart, {
+  const { route, key, bucket, stored } = await openStoredTarget(
+    config,
+    input,
     request,
-    key: input.key,
-    bucket: input.bucket
-  });
+    "multipart"
+  );
   const uploadId = input.uploadId;
   const partNumber = input.partNumber;
-  const expiresIn = normalizeExpiresIn(input.expiresIn, config.maxExpiresIn);
-  const partSize = typeof input.partSize === "number" && input.partSize > 0 ? Math.floor(input.partSize) : null;
-  await runHook(config.multipart?.partGuard, {
-    request,
-    key,
-    bucket,
+  const expiresIn = normalizeExpiresIn(
+    route.upload.expiresIn,
+    config.maxExpiresIn
+  );
+  const partSize = Math.floor(input.partSize);
+  await runHook(route.upload.multipart.guard, {
+    ...stored,
     uploadId,
+    action: "part",
     partNumber,
-    partSize: partSize ?? void 0
+    partSize
   });
-  const presignedUrl = await getSignedUrl(
-    config.client,
+  const maxFileSize = route.upload.maxFileSize;
+  assertWithinMaxFileSize(maxFileSize, partSize);
+  if (typeof maxFileSize === "number") {
+    const listed = await listAllParts(route.client, { bucket, key, uploadId });
+    assertWithinMaxFileSize(
+      maxFileSize,
+      listedPartsByteSize(listed, partNumber) + partSize
+    );
+  }
+  const url = await getSignedUrl(
+    route.client,
     new UploadPartCommand({
       Bucket: bucket,
       Key: key,
       UploadId: uploadId,
       PartNumber: partNumber,
-      ...partSize !== null ? { ContentLength: partSize } : {}
+      ContentLength: partSize
     }),
     {
       expiresIn,
-      ...partSize !== null ? { signableHeaders: /* @__PURE__ */ new Set(["content-length"]) } : {}
+      signableHeaders: /* @__PURE__ */ new Set(["content-length"])
     }
   );
   return {
-    presignedUrl,
+    url,
     partNumber,
     uploadId,
     bucket,
     expiresIn,
-    ...partSize !== null ? { partSize } : {}
+    partSize
   };
 }
 var multipartPart = createS3Endpoint(
   S3_API_ROUTES.multipartPart,
   { method: "POST", body: multipartSignPartBodySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "multipart");
     return handleSignPart(ctx.context.config, ctx.body, ctx.context.request);
   }
 );
-function putMetadataHeaders(metadata) {
+function objectUserMetadata(metadata) {
   if (!metadata) return {};
-  const headers = {};
+  const fields = {};
   for (const [k, v] of Object.entries(metadata)) {
-    headers[`x-amz-meta-${k}`] = v;
+    fields[`x-amz-meta-${k}`] = v;
   }
-  return headers;
+  return fields;
 }
 async function handleUpload(config, input, request) {
-  const { key, bucket } = await resolveRequestTarget(config, config.upload, {
+  const fileSize = Math.floor(input.fileSize);
+  const fileName = input.fileName;
+  const { route, key, bucket, metadata, acl, stored } = await openUploadTarget(
+    config,
+    {
+      route: input.route,
+      fileName,
+      fileSize,
+      contentType: input.contentType,
+      metadata: input.metadata
+    },
     request,
-    key: input.key,
-    bucket: input.bucket,
-    fileName: input.fileName,
-    contentType: input.contentType
-  });
-  const expiresIn = normalizeExpiresIn(input.expiresIn, config.maxExpiresIn);
-  const acl = resolveRequestAcl(config.upload, input.acl);
-  const contentType = input.contentType ?? "application/octet-stream";
-  const fileSize = typeof input.fileSize === "number" && input.fileSize > 0 ? Math.floor(input.fileSize) : null;
-  if (config.upload?.requireFileSize && fileSize === null) {
-    throw errors.fileSizeRequiredUpload();
+    "upload"
+  );
+  const method = route.upload.method ?? "POST";
+  if (route.upload.checksum && !input.checksum) {
+    throw errors.validationError("Checksum is required for this route");
   }
-  await runHook(config.upload?.guard, {
-    request,
-    key,
-    bucket,
-    contentType: input.contentType,
-    fileSize: fileSize ?? void 0,
-    metadata: input.metadata,
+  if (method === "POST" && fileSize > S3_MAX_POST_OBJECT_BYTES) {
+    throw errors.payloadTooLarge(
+      `POST uploads cannot exceed ${S3_MAX_POST_OBJECT_BYTES} bytes. Enable upload.multipart or set upload.method to "PUT".`
+    );
+  }
+  const expiresIn = normalizeExpiresIn(
+    route.upload.expiresIn,
+    config.maxExpiresIn
+  );
+  const contentType = input.contentType ?? "application/octet-stream";
+  const hookCtx = {
+    ...stored,
+    file: {
+      name: fileName,
+      size: fileSize,
+      type: input.contentType
+    },
+    metadata,
+    clientMetadata: input.metadata,
     acl,
-    fileName: input.fileName
-  });
-  const method = config.upload?.method ?? "POST";
+    replace: route.upload.replace
+  };
+  await runHook(route.upload.guard, hookCtx);
   if (method === "PUT") {
     const putHeaders = {
       "Content-Type": contentType,
-      ...putMetadataHeaders(input.metadata)
+      ...objectUserMetadata(metadata),
+      "Content-Disposition": buildContentDisposition(fileName),
+      ...input.checksum ? { "x-amz-checksum-sha256": input.checksum } : {}
     };
-    if (input.fileName) {
-      putHeaders["Content-Disposition"] = buildContentDisposition(
-        input.fileName
-      );
-    }
     const url2 = await getSignedUrl(
-      config.client,
+      route.client,
       new PutObjectCommand({
         Bucket: bucket,
         Key: key,
         ContentType: contentType,
         ACL: acl,
-        Metadata: input.metadata,
-        ...input.fileName ? { ContentDisposition: buildContentDisposition(input.fileName) } : {},
-        ...fileSize !== null ? { ContentLength: fileSize } : {}
+        Metadata: metadata,
+        ContentDisposition: buildContentDisposition(fileName),
+        ContentLength: fileSize,
+        ...input.checksum ? { ChecksumSHA256: input.checksum, ChecksumAlgorithm: "SHA256" } : {}
       }),
       {
         expiresIn,
-        ...fileSize !== null ? { signableHeaders: /* @__PURE__ */ new Set(["content-length"]) } : {}
+        signableHeaders: /* @__PURE__ */ new Set([
+          "content-length",
+          ...input.checksum ? ["x-amz-checksum-sha256"] : []
+        ])
       }
     );
-    await runLifecycleHook(config.upload?.onPresigned, {
-      request,
-      key,
-      bucket,
-      contentType: input.contentType,
-      fileSize: fileSize ?? void 0,
-      metadata: input.metadata,
-      acl,
-      fileName: input.fileName,
-      url: url2,
-      expiresIn
-    });
+    await runLifecycleHook(
+      route.upload.onPresigned,
+      {
+        ...hookCtx,
+        url: url2,
+        expiresIn
+      },
+      config
+    );
     return {
       bucket,
       key,
@@ -799,39 +1244,32 @@ async function handleUpload(config, input, request) {
       method: "PUT"
     };
   }
-  const fields = { acl, "Content-Type": contentType };
-  if (input.fileName) {
-    fields["Content-Disposition"] = buildContentDisposition(input.fileName);
-  }
-  if (input.metadata) {
-    for (const [k, v] of Object.entries(input.metadata)) {
-      fields[`x-amz-meta-${k}`] = v;
-    }
-  }
-  const rangeMin = fileSize ?? 1;
-  const rangeMax = fileSize ?? void 0;
+  const fields = {
+    acl,
+    "Content-Type": contentType,
+    "Content-Disposition": buildContentDisposition(fileName),
+    ...objectUserMetadata(metadata),
+    ...input.checksum ? { "x-amz-checksum-sha256": input.checksum } : {}
+  };
   const { url, fields: signedFields } = await createPresignedPost(
-    config.client,
+    route.client,
     {
       Bucket: bucket,
       Key: key,
-      Conditions: rangeMax !== void 0 ? [["content-length-range", rangeMin, rangeMax]] : [["content-length-range", rangeMin, S3_MAX_POST_OBJECT_BYTES]],
+      Conditions: [["content-length-range", fileSize, fileSize]],
       Fields: fields,
       Expires: expiresIn
     }
   );
-  await runLifecycleHook(config.upload?.onPresigned, {
-    request,
-    key,
-    bucket,
-    contentType: input.contentType,
-    fileSize: fileSize ?? void 0,
-    metadata: input.metadata,
-    acl,
-    fileName: input.fileName,
-    url,
-    expiresIn
-  });
+  await runLifecycleHook(
+    route.upload.onPresigned,
+    {
+      ...hookCtx,
+      url,
+      expiresIn
+    },
+    config
+  );
   return {
     bucket,
     key,
@@ -845,7 +1283,6 @@ var upload = createS3Endpoint(
   S3_API_ROUTES.upload,
   { method: "POST", body: uploadBodySchema },
   async (ctx) => {
-    assertFeatureEnabled(ctx.context.config, "upload");
     return handleUpload(ctx.context.config, ctx.body, ctx.context.request);
   }
 );
@@ -855,7 +1292,10 @@ var coreEndpoints = {
   upload,
   confirm,
   download,
+  catalog,
+  file,
   delete: deleteObject,
+  deleteBatch,
   multipartInit,
   multipartPart,
   multipartListParts,
@@ -879,19 +1319,24 @@ function chainHooks(...hooks) {
 var FEATURE_HOOK_KEYS = {
   upload: ["guard", "onPresigned", "confirmGuard", "onConfirmed"],
   download: ["guard", "onPresigned"],
-  delete: ["guard", "onDeleted"],
-  multipart: [
-    "initGuard",
-    "partGuard",
-    "completeGuard",
-    "abortGuard",
-    "listGuard",
-    "onInit",
-    "onComplete",
-    "onAbort",
-    "onList"
-  ]
+  delete: ["guard", "onDeleted"]
 };
+var MULTIPART_HOOK_KEYS = [
+  "onInit",
+  "guard",
+  "onAbort",
+  "onList"
+];
+var LIFECYCLE_FEATURE_HOOK_KEYS = {
+  upload: ["onPresigned", "onConfirmed"],
+  download: ["onPresigned"],
+  delete: ["onDeleted"]
+};
+var LIFECYCLE_MULTIPART_HOOK_KEYS = [
+  "onInit",
+  "onAbort",
+  "onList"
+];
 
 // src/plugin/types.ts
 var RESERVED_PLUGIN_IDS = [
@@ -900,35 +1345,74 @@ var RESERVED_PLUGIN_IDS = [
   "context",
   "getPlugin",
   "$ERROR_CODES",
-  "$Infer"
+  "$Infer",
+  "upload",
+  "confirm",
+  "download",
+  "catalog",
+  "file",
+  "delete",
+  "deleteBatch",
+  "put",
+  "multipart"
 ];
 
 // src/plugin/apply-plugins.ts
-function mergeHookField(pluginHooks, userHook) {
-  const present = [...pluginHooks, userHook].filter(
-    (h) => h != null
-  );
+function mergeHookField(pluginHooks, userHook, order = "plugins-first") {
+  const present = (order === "user-first" ? [userHook, ...pluginHooks] : [...pluginHooks, userHook]).filter((h) => h != null);
   if (present.length === 0) return void 0;
   if (present.length === 1) return present[0];
   return chainHooks(...present);
 }
-function mergeFeatureHooks(feature, keys, plugins, userFeature) {
-  if (!userFeature && plugins.every((p) => !p.hooks?.[feature])) {
-    return userFeature;
-  }
-  const merged = { ...userFeature ?? {} };
+function mergeHooks(keys, plugins, userFeature, pick, lifecycleKeys = /* @__PURE__ */ new Set()) {
+  const merged = { ...userFeature };
   for (const key of keys) {
-    const fromPlugins = plugins.map(
-      (p) => p.hooks?.[feature]?.[key]
+    const next = mergeHookField(
+      plugins.map((plugin) => pick(plugin)?.[key]),
+      userFeature[key],
+      lifecycleKeys.has(key) ? "user-first" : "plugins-first"
     );
-    const userHook = userFeature?.[key];
-    const next = mergeHookField(fromPlugins, userHook);
-    if (next !== void 0) {
-      merged[key] = next;
-    }
+    if (next !== void 0) merged[key] = next;
   }
   return merged;
 }
+function applyHooksToRoute(route, plugins) {
+  const active = plugins.filter((p) => !route.skippedPluginIds.has(p.id));
+  const upload2 = isEnabled(route.upload) ? {
+    ...mergeHooks(
+      FEATURE_HOOK_KEYS.upload,
+      active,
+      route.upload,
+      (p) => p.hooks?.upload,
+      new Set(LIFECYCLE_FEATURE_HOOK_KEYS.upload)
+    ),
+    multipart: isEnabled(route.upload.multipart) ? mergeHooks(
+      MULTIPART_HOOK_KEYS,
+      active,
+      route.upload.multipart,
+      (p) => p.hooks?.upload?.multipart,
+      new Set(LIFECYCLE_MULTIPART_HOOK_KEYS)
+    ) : route.upload.multipart
+  } : route.upload;
+  return {
+    ...route,
+    upload: upload2,
+    download: isEnabled(route.download) ? mergeHooks(
+      FEATURE_HOOK_KEYS.download,
+      active,
+      route.download,
+      (p) => p.hooks?.download,
+      new Set(LIFECYCLE_FEATURE_HOOK_KEYS.download)
+    ) : route.download,
+    delete: isEnabled(route.delete) ? mergeHooks(
+      FEATURE_HOOK_KEYS.delete,
+      active,
+      route.delete,
+      (p) => p.hooks?.delete,
+      new Set(LIFECYCLE_FEATURE_HOOK_KEYS.delete)
+    ) : route.delete
+  };
+}
 function applyPlugins(config) {
   const plugins = config.plugins ?? [];
   const seen = /* @__PURE__ */ new Set();
@@ -1017,37 +1501,25 @@ function applyPlugins(config) {
     }
   }
   const { plugins: _omit, ...rest } = config;
-  assertExclusiveBucketFlags(rest);
+  const normalized = normalizeRoutes(rest);
   for (const plugin of plugins) {
     plugin.init?.({ config: rest, getPlugin });
   }
-  const features = normalizeFeatures(rest);
-  const {
-    upload: _upload,
-    download: _download,
-    delete: _delete,
-    multipart: _multipart,
-    ...base
-  } = rest;
+  const routes = {};
+  for (const [name, route] of Object.entries(normalized)) {
+    routes[name] = applyHooksToRoute(route, plugins);
+  }
   const guard = mergeHookField(
     plugins.map((p) => p.hooks?.guard),
     rest.guard
   );
   const merged = {
-    ...base,
-    ...features,
+    ...rest,
+    routes,
     ...guard !== void 0 ? { guard } : {}
   };
-  for (const feature of Object.keys(FEATURE_HOOK_KEYS)) {
-    merged[feature] = mergeFeatureHooks(
-      feature,
-      FEATURE_HOOK_KEYS[feature],
-      plugins,
-      merged[feature]
-    );
-  }
   return {
-    config: applyMultipartDefault(merged, rest.multipart),
+    config: merged,
     context,
     getPlugin,
     endpoints
@@ -1059,6 +1531,10 @@ function definePlugin(plugin) {
   return plugin;
 }
 
-export { CORE_ENDPOINT_NAMES, FEATURE_HOOK_KEYS, RESERVED_PLUGIN_IDS, applyPlugins, chainHooks, createS3Endpoint, createS3Middleware, definePlugin };
+// src/types/config.ts
+var ROUTE_FEATURES = ["upload", "download", "delete"];
+var ROUTE_OPERATIONS = [...ROUTE_FEATURES, "multipart"];
+
+export { CORE_ENDPOINT_NAMES, FEATURE_HOOK_KEYS, LIFECYCLE_FEATURE_HOOK_KEYS, LIFECYCLE_MULTIPART_HOOK_KEYS, MULTIPART_HOOK_KEYS, RESERVED_PLUGIN_IDS, ROUTE_FEATURES, ROUTE_OPERATIONS, applyPlugins, chainHooks, createS3Endpoint, createS3Middleware, definePlugin, isFeatureOn };
 //# sourceMappingURL=plugins.js.map
 //# sourceMappingURL=plugins.js.map