@better-s3/server 3.1049.0 → 3.1051.0

package/README.md

@@ -1,6 +1,8 @@
 # @better-s3/server
 
-Server-side presigned URL handlers for S3 — upload, download, delete, and multipart. Works with any `Request`/`Response` runtime (Next.js, Hono, Bun, Deno, Cloudflare Workers, etc).
+Presigned S3 route handlers and lifecycle hooks for upload, download, delete, and multipart.
+
+Full documentation: [better-s3-docs.vercel.app](https://better-s3-docs.vercel.app/docs/server)
 
 ## Install
 
@@ -8,10 +10,9 @@ Server-side presigned URL handlers for S3 — upload, download, delete, and mult
 pnpm add @better-s3/server @aws-sdk/client-s3
 ```
 
-## Quick Start
+## Minimal setup
 
 ```ts
-// app/api/s3/[...s3]/route.ts  (Next.js App Router)
 import { createRouteHandler } from "@better-s3/server/next";
 import { s3Config } from "@/lib/better-s3";
 
@@ -20,204 +21,19 @@ export { handler as GET, handler as POST, handler as DELETE };
 ```
 
 ```ts
-// lib/better-s3.ts
 import type { S3HandlerConfig } from "@better-s3/server";
 import { s3, defaultBucket } from "@/lib/s3";
 
 export const s3Config = {
-  s3: s3,
-  defaultBucket: defaultBucket,
-  // Optional: enable ACL inference only when you need it.
-  // resolveObjectAcl: true,
-
-  // guard: async ({ request }) => { ... },
-
-  upload: {
-    enabled: true,
-    onUploadConfirmed: async ({ key, contentLength }) => {
-      // await db.file.create({ data: { key, contentLength } });
-    },
-  },
-
-  download: { enabled: true },
-
-  delete: {
-    enabled: true,
-    onDeleted: async ({ key }) => {
-      // await db.file.delete({ where: { key } });
-    },
-  },
-
-  // multipart: { enabled: true },
+  s3,
+  defaultBucket,
+  upload: { enabled: true },
+  download: { enabled: false },
+  delete: { enabled: false },
+  multipart: { enabled: false },
 } satisfies S3HandlerConfig;
 ```
 
-Mount the catch-all route at `app/api/s3/[...s3]/route.ts` (default base path `/api/s3`). For a custom path, pass the same value to `createRouteHandler(config, basePath)` and `createS3Api(basePath)` from `@better-s3/core`.
-
-`resolveObjectAcl` is optional and defaults to `false`.
-When disabled, confirmation responses omit `acl` (unknown state).
-
-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
-```
-
-## Enabling endpoints
-
-All endpoints are **disabled by default** — set `enabled: true` inside each section to opt in. Disabled endpoints respond with `404`.
-
-```ts
-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}
-```
-
-| Upload mode | Enforcement                                                                                                     |
-| ----------- | --------------------------------------------------------------------------------------------------------------- |
-| Simple      | S3 enforces exact size via `content-length-range` in the signed POST policy — tamperproof                       |
-| Multipart   | `HeadObject` after complete verifies the final object size; no per-part enforcement at the S3 level (see below) |
-
-> 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).
-
-## 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.
-
-```
-Simple:    upload.presignGuard → upload.onPresigned → [S3] → upload.confirmGuard → upload.onUploadConfirmed
-Multipart: multipart.initGuard → multipart.onInit
-           multipart.partGuard → [S3]
-           multipart.completeGuard → HeadObject → multipart.onComplete
-           multipart.abortGuard → multipart.onAbort
-```
-
-### Authentication
-
-```ts
-guard: async ({ request }) => {
-  const session = await getSession(request);
-  if (!session) throw Object.assign(new Error("Unauthorized"), { status: 401 });
-},
-```
-
-### Quota check
-
-`fileSize` in `upload.presignGuard` and `multipart.initGuard` is **declared by the client** — use it for pre-checks. `contentLength` in `onUploadConfirmed` / `multipart.onComplete` is verified by S3.
-
-```ts
-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).
-
-**Mitigation: track uploads in a database + cron cleanup**
-
-```ts
-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" },
-    });
-  },
-
-    onComplete: async ({ key, contentLength, contentType, eTag }) => {
-      await db.upload.update({
-        where: { key },
-        data: { status: "complete", verifiedSize: contentLength, contentType, eTag },
-      });
-    },
-
-    onAbort: async ({ key }) => {
-      await db.upload.update({ where: { key }, data: { status: "aborted" } });
-    },
-  },
-}
-```
-
-**Cron job** — abort stale uploads and release S3 part storage:
-
-```ts
-// Runs every hour
-const stale = await db.upload.findMany({
-  where: {
-    status: "pending",
-    createdAt: { lt: new Date(Date.now() - 3_600_000) },
-  },
-});
-for (const upload of stale) {
-  await s3
-    .send(
-      new AbortMultipartUploadCommand({
-        Bucket: defaultBucket,
-        Key: upload.key,
-        UploadId: upload.uploadId,
-      }),
-    )
-    .catch(() => {});
-  await db.upload.update({
-    where: { key: upload.key },
-    data: { status: "expired" },
-  });
-}
-```
-
-**S3 lifecycle rule** — safety net for anything the cron misses (e.g. crash before `onInit`):
-
-```json
-{
-  "Rules": [
-    {
-      "ID": "abort-incomplete-multipart",
-      "Status": "Enabled",
-      "Filter": { "Prefix": "" },
-      "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 1 }
-    }
-  ]
-}
-```
-
-> Also rate-limit `/presign/multipart/part` per user/IP at the application layer.
-
-## API Routes
-
-| Method   | Path                          | Description                      |
-| -------- | ----------------------------- | -------------------------------- |
-| `POST`   | `/presign/upload`             | Presigned POST for direct upload |
-| `POST`   | `/presign/upload/confirm`     | Confirm upload via HeadObject    |
-| `GET`    | `/presign/download`           | Presigned download URL           |
-| `DELETE` | `/delete`                     | Delete object                    |
-| `POST`   | `/presign/multipart/init`     | Init multipart upload            |
-| `POST`   | `/presign/multipart/part`     | Sign a part URL                  |
-| `POST`   | `/presign/multipart/complete` | Complete + verify                |
-| `POST`   | `/presign/multipart/abort`    | Abort multipart                  |
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-s3/server",
-  "version": "3.1049.0",
+  "version": "3.1051.0",
   "description": "Framework-agnostic S3 server handlers — presigned uploads, downloads, deletes, and multipart operations",
   "keywords": [
     "s3",
@@ -42,15 +42,15 @@
     "dist"
   ],
   "dependencies": {
-    "@aws-sdk/s3-presigned-post": "^3.1063.0",
-    "@aws-sdk/s3-request-presigner": "^3.1063.0",
-    "@better-s3/core": "3.1049.0"
+    "@aws-sdk/s3-presigned-post": "^3.1068.0",
+    "@aws-sdk/s3-request-presigner": "^3.1068.0",
+    "@better-s3/core": "3.1051.0"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.1063.0",
+    "@aws-sdk/client-s3": "^3.1068.0",
     "tsc-alias": "^1.8.17",
     "tsup": "^8.5.1",
     "typescript": "6.0.3"