@better-s3/server 3.2.0 → 3.2.1

package/README.md

@@ -12,119 +12,66 @@ pnpm add @better-s3/server @aws-sdk/client-s3
 
 ```ts
 // app/api/s3/[...s3]/route.ts  (Next.js App Router)
-import { S3Client } from "@aws-sdk/client-s3";
 import { createRouteHandler } from "@better-s3/server/next";
+import { s3Config } from "@/lib/better-s3";
 
-const handler = createRouteHandler({
-  s3: new S3Client({ region: "us-east-1" }),
-  defaultBucket: "my-bucket",
-  basePath: "/api/s3",
-
-  // Enable only the features your app needs. All are disabled by default.
-  features: {
-    upload: true,
-    download: true,
-    delete: true,
-    // multipart: true, // enable only if you explicitly need multipart support
-  },
-});
-
+const handler = createRouteHandler(s3Config);
 export { handler as GET, handler as POST, handler as DELETE };
 ```
 
-Other frameworks via `createRouter` from `@better-s3/server`:
-
 ```ts
-const router = createRouter({
-  s3,
-  defaultBucket: "my-bucket",
+// lib/better-s3.ts
+import type { S3RouteHandlerConfig } from "@better-s3/server";
+import { s3, defaultBucket, resolvePublicUrl } from "@/lib/s3";
+
+export const s3Config = {
+  s3: s3,
+  defaultBucket: defaultBucket,
+  resolvePublicUrl: resolvePublicUrl,
   basePath: "/api/s3",
-  features: { upload: true, download: true, delete: true, multipart: true },
-  hooks: {
-    guard: async ({ request }) => {
-      console.log("[guard]", request.method, request.url);
-    },
 
-    upload: {
-      guard: async ({ key, bucket, contentType, fileSize }) => {
-        console.log("[upload.guard]", { key, bucket, contentType, fileSize });
-      },
-      onPresigned: async ({ key, url, expiresIn }) => {
-        console.log("[upload.onPresigned]", { key, url, expiresIn });
-      },
-      onUploaded: async ({ key, contentType, contentLength, eTag }) => {
-        console.log("[upload.onUploaded]", {
-          key,
-          contentType,
-          contentLength,
-          eTag,
-        });
-      },
-    },
+  // guard: async ({ request }) => { ... },
 
-    download: {
-      guard: async ({ key, bucket, fileName }) => {
-        console.log("[download.guard]", { key, bucket, fileName });
-      },
-      onPresigned: async ({ key, url, expiresIn }) => {
-        console.log("[download.onPresigned]", { key, url, expiresIn });
-      },
+  upload: {
+    enabled: true,
+    onUploaded: async ({ key, contentLength }) => {
+      // await db.file.create({ data: { key, contentLength } });
     },
+  },
 
-    delete: {
-      guard: async ({ key, bucket }) => {
-        console.log("[delete.guard]", { key, bucket });
-      },
-      onDeleted: async ({ key, bucket }) => {
-        console.log("[delete.onDeleted]", { key, bucket });
-      },
-    },
+  download: { enabled: true },
 
-    multipart: {
-      guard: async ({ key, bucket, fileSize }) => {
-        console.log("[multipart.guard]", { key, bucket, fileSize });
-      },
-      onInit: async ({ key, uploadId, contentType, fileSize }) => {
-        console.log("[multipart.onInit]", {
-          key,
-          uploadId,
-          contentType,
-          fileSize,
-        });
-      },
-      onComplete: async ({ key, uploadId, contentLength, eTag }) => {
-        console.log("[multipart.onComplete]", {
-          key,
-          uploadId,
-          contentLength,
-          eTag,
-        });
-      },
-      onAbort: async ({ key, uploadId }) => {
-        console.log("[multipart.onAbort]", { key, uploadId });
-      },
+  delete: {
+    enabled: true,
+    onDeleted: async ({ key }) => {
+      // await db.file.delete({ where: { key } });
     },
   },
-});
 
+  // multipart: { enabled: true },
+} satisfies S3RouteHandlerConfig;
+```
+
+Other frameworks via `createRouter`:
+
+```ts
+import { createRouter } from "@better-s3/server";
+
+const router = createRouter(s3Config);
 app.all("/api/s3/*", (c) => router(c.req.raw)); // Hono example
 ```
 
-## Features
+## Enabling endpoints
 
-All endpoints are **disabled by default**. You must explicitly opt in via the `features` config — this prevents unintended exposure of expensive or sensitive operations (especially multipart, which is vulnerable to [cost attacks](#multipart-cost-attacks)).
+All endpoints are **disabled by default** — set `enabled: true` inside each section to opt in. Disabled endpoints respond with `404`.
 
 ```ts
-features: {
-  upload: true,     // POST /presign/upload + POST /presign/upload/confirm
-  download: true,   // GET  /presign/download
-  delete: true,     // DELETE /delete
-  multipart: true,  // POST /presign/multipart/{init,part,complete,abort}
-}
+upload:    { enabled: true }  // POST /presign/upload + POST /presign/upload/confirm
+download:  { enabled: true }  // GET  /presign/download
+delete:    { enabled: true }  // DELETE /delete
+multipart: { enabled: true }  // POST /presign/multipart/{init,part,complete,abort}
 ```
 
-> Disabled endpoints respond with `404 Not Found`.
-
 | Upload mode | Enforcement                                                                                                     |
 | ----------- | --------------------------------------------------------------------------------------------------------------- |
 | Simple      | S3 enforces exact size via `content-length-range` in the signed POST policy — tamperproof                       |
@@ -132,7 +79,7 @@ features: {
 
 > Simple upload is inherently more secure — enforcement happens at the S3 storage layer. Multipart presigned `UploadPart` URLs cannot enforce per-part size; see [Multipart cost attacks](#multipart-cost-attacks).
 
-## Server Hooks
+## Hooks
 
 Run server-side logic at key points. Every hook receives the `Request` object. **Throw to reject** — returned as `{ message }` with status 403, or any status you set on the thrown error.
 
@@ -147,12 +94,10 @@ Multipart: multipart.guard(init) → multipart.onInit
 ### Authentication
 
 ```ts
-hooks: {
-  guard: async ({ request }) => {
-    const session = await getSession(request);
-    if (!session) throw Object.assign(new Error("Unauthorized"), { status: 401 });
-  },
-}
+guard: async ({ request }) => {
+  const session = await getSession(request);
+  if (!session) throw Object.assign(new Error("Unauthorized"), { status: 401 });
+},
 ```
 
 ### Quota check
@@ -160,18 +105,19 @@ hooks: {
 `fileSize` in `upload.guard` and `multipart.guard` (init only) is **declared by the client** — use it for pre-checks. `contentLength` in `onUploaded` / `multipart.onComplete` is verified by S3.
 
 ```ts
-hooks: {
-  upload: {
-    guard: async ({ request, fileSize }) => {
-      const { userId } = await getSession(request);
-      const used = await db.storage.getUsed(userId);
-      if (fileSize && used + fileSize > QUOTA)
-        throw Object.assign(new Error("Quota exceeded"), { status: 403 });
-    },
+upload: {
+  enabled: true,
+  guard: async ({ request, fileSize }) => {
+    const { userId } = await getSession(request);
+    const used = await db.storage.getUsed(userId);
+    if (fileSize && used + fileSize > QUOTA)
+      throw Object.assign(new Error("Quota exceeded"), { status: 403 });
   },
-}
+},
 ```
 
+````
+
 ## Multipart cost attacks
 
 S3 presigned `UploadPart` URLs cannot enforce per-part size. A malicious client can upload oversized parts — the post-complete `HeadObject` check will catch and delete the final object, but temporary part storage still accumulates cost. Without completion, orphaned parts stay on AWS S3 indefinitely (R2 cleans up after 7 days).
@@ -179,24 +125,24 @@ S3 presigned `UploadPart` URLs cannot enforce per-part size. A malicious client
 **Mitigation: track uploads in a database + cron cleanup**
 
 ```ts
-hooks: {
-  multipart: {
-    // Guard runs on init, part, complete, and abort.
-    // fileSize is only present during init — use it to limit open sessions.
-    guard: async ({ request, fileSize }) => {
-      if (!fileSize) return;
-      const { userId } = await getSession(request);
-      const pending = await db.upload.count({ where: { userId, status: "pending" } });
-      if (pending >= 3)
-        throw Object.assign(new Error("Too many pending uploads"), { status: 429 });
-    },
+multipart: {
+  enabled: true,
+  // Guard runs on init, part, complete, and abort.
+  // fileSize is only present during init — use it to limit open sessions.
+  guard: async ({ request, fileSize }) => {
+    if (!fileSize) return;
+    const { userId } = await getSession(request);
+    const pending = await db.upload.count({ where: { userId, status: "pending" } });
+    if (pending >= 3)
+      throw Object.assign(new Error("Too many pending uploads"), { status: 429 });
+  },
 
-    onInit: async ({ request, key, uploadId, contentType, fileSize }) => {
-      const { userId } = await getSession(request);
-      await db.upload.create({
-        data: { key, userId, uploadId, contentType, declaredSize: fileSize, status: "pending" },
-      });
-    },
+  onInit: async ({ request, key, uploadId, contentType, fileSize }) => {
+    const { userId } = await getSession(request);
+    await db.upload.create({
+      data: { key, userId, uploadId, contentType, declaredSize: fileSize, status: "pending" },
+    });
+  },
 
     onComplete: async ({ key, contentLength, contentType, eTag }) => {
       await db.upload.update({
@@ -210,7 +156,7 @@ hooks: {
     },
   },
 }
-```
+````
 
 **Cron job** — abort stale uploads and release S3 part storage:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-s3/server",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "Framework-agnostic S3 server handlers — presigned uploads, downloads, deletes, and multipart operations",
   "keywords": [
     "s3",