cloudrop 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/server.md ADDED
@@ -0,0 +1,603 @@
1
+ # Server
2
+
3
+ This page is for developers setting up cloudrop on their server. It covers everything that runs there: creating the
4
+ server with `createCloudrop`, choosing a storage driver, defining routes and who may use them, what the upload token is
5
+ and what it allows, mounting the handler in your framework, which origins may call it, and the `cloudrop.api` file
6
+ operations. For the browser side, see [Client](client.md). To keep a row per upload in your database (`onComplete` once,
7
+ quotas, revocation, cleanup), see [Database store](store.md).
8
+
9
+ ## Create the server
10
+
11
+ ```ts
12
+ // lib/cloudrop.ts
13
+ import { createCloudrop, r2, route, unauthorized } from "cloudrop";
14
+
15
+ export const cloudrop = createCloudrop({
16
+ storage: r2({ bucket: "media" }),
17
+ routes: {
18
+ avatar: route(
19
+ {
20
+ accept: "image/*",
21
+ maxSize: "5MB",
22
+ authorize: async ({ request }) => {
23
+ const user = await getUser(request); // your app's session lookup
24
+ return user ? { userId: user.id } : unauthorized();
25
+ },
26
+ },
27
+ { prefix: ({ userId }) => `users/${userId}/avatars` },
28
+ ),
29
+ },
30
+ });
31
+ ```
32
+
33
+ `createCloudrop` checks every option when it is called and throws a `CloudropError` with code `INVALID_CONFIG` for the
34
+ first mistake it finds, checking the options in a fixed order. Its message names the option and the fix. A
35
+ misconfigured server fails when it starts, not on a user's first upload. Settings that come from the environment
36
+ (`CLOUDROP_SECRET` and the storage variables) are read on the first request instead, so a build needs no secrets; one
37
+ still missing then makes every request answer 500 and logs `INVALID_CONFIG` once. With `NODE_ENV=development` they are
38
+ checked when `createCloudrop` runs too, so a dev server fails as soon as the server module loads.
39
+
40
+ | Option | What it does | Default |
41
+ | --- | --- | --- |
42
+ | `storage` | Where files go: `r2({ ... })` or `s3({ ... })`. Required. | |
43
+ | `routes` | The upload routes, by name. At least one. A name uses letters, digits, `-` and `_`, at most 64. | |
44
+ | `secret` | The secret that signs upload tokens: text of at least 32 characters, or a list of them (see [Rotate the secret](#rotate-the-secret)). | env `CLOUDROP_SECRET` |
45
+ | `basePath` | Where the handler is mounted. A leading slash, no trailing slash, no query. | `"/api/cloudrop"` |
46
+ | `trustedOrigins` | Exact origins, such as `"https://app.example.com"`, that may call the handler from another origin (see [Origins](#origins)). Never `"*"`. | `[]` |
47
+ | `multipartThreshold` | Files larger than this go in parts. Bytes or a size such as `"64MB"`. | 64 MiB |
48
+ | `plugins` | Plugins with server hooks (see [Hooks](#hooks)). | `[]` |
49
+ | `logger` | Where failures inside the handler and configuration warnings go: any object with `error(message, error)` and `warn(message)`, such as `console` or a pino logger. | `console` |
50
+ | `store` | A database store, such as `sqlStore(...)` from `cloudrop/adapters/sql` (see [Database store](store.md)). | none: stateless |
51
+ | `quota` | With a store: each owner's limit in bytes, or `null` for none, asked once per `/upload`. | none |
52
+ | `completionLeaseMs` | With a store and no transaction: how long a `/complete` holds its file while `onComplete` runs. Longer than your slowest `onComplete`. | 300000 |
53
+
54
+ Generate a secret with `openssl rand -base64 32`. Use a different secret for every deployment: a token verifies
55
+ wherever its secret is configured.
56
+
57
+ Sizes such as `maxSize` and `multipartThreshold` take a number of bytes or a string with a unit: `"512KB"`, `"5MB"`,
58
+ `"1.5GB"`. `KB`, `MB`, `GB` and `TB` are binary units (1 KB = 1024 bytes), the same as `KiB`, `MiB`, `GiB` and `TiB`.
59
+
60
+ ### Rotate the secret
61
+
62
+ Pass a list. The first secret signs new tokens; every secret in the list verifies. Put the new secret first and keep the
63
+ old one until its tokens expire, 24 hours later:
64
+
65
+ ```ts
66
+ secret: [process.env.NEW_SECRET as string, process.env.OLD_SECRET as string],
67
+ ```
68
+
69
+ ### Settings from the environment
70
+
71
+ The library reads the environment only through `process.env`, and only when the runtime has one. On a runtime without
72
+ `process.env`, pass `secret` and the storage credentials explicitly.
73
+
74
+ ## Choose a storage driver
75
+
76
+ ### R2
77
+
78
+ ```ts
79
+ import { r2 } from "cloudrop";
80
+
81
+ const storage = r2({ bucket: "media" });
82
+ ```
83
+
84
+ | Option | Default |
85
+ | --- | --- |
86
+ | `bucket` | env `CLOUDROP_R2_BUCKET`. The exact bucket name. |
87
+ | `accountId` | env `CLOUDROP_R2_ACCOUNT_ID`. 32 hexadecimal characters, from the R2 overview page in the Cloudflare dashboard. |
88
+ | `accessKeyId` | env `CLOUDROP_R2_ACCESS_KEY_ID` |
89
+ | `secretAccessKey` | env `CLOUDROP_R2_SECRET_ACCESS_KEY` |
90
+ | `jurisdiction` | `"eu"` or `"fedramp"` for a bucket in that jurisdiction. Omit it for the default location. |
91
+ | `publicUrl` | Where the bucket is served publicly: a custom domain or `r2.dev` URL, a path allowed, such as `"https://cdn.example.com/files"`. |
92
+ | `fetch` | Replaces the global `fetch`. |
93
+
94
+ An option that is unset or empty falls back to its variable. One `INVALID_CONFIG` error lists everything missing at
95
+ once, on the first request (when the server is created, in development). An option you pass is checked when `r2()` is
96
+ called.
97
+
98
+ With every variable set, `r2()` needs no argument at all:
99
+
100
+ ```sh
101
+ CLOUDROP_R2_ACCOUNT_ID=<32 hexadecimal characters>
102
+ CLOUDROP_R2_ACCESS_KEY_ID=<access key id>
103
+ CLOUDROP_R2_SECRET_ACCESS_KEY=<secret access key>
104
+ CLOUDROP_R2_BUCKET=media
105
+ ```
106
+
107
+ ```ts
108
+ const storage = r2();
109
+ ```
110
+
111
+ ### Any S3-compatible service
112
+
113
+ ```ts
114
+ import { s3 } from "cloudrop";
115
+
116
+ // Reads CLOUDROP_S3_ENDPOINT, CLOUDROP_S3_REGION, CLOUDROP_S3_BUCKET, CLOUDROP_S3_ACCESS_KEY_ID and
117
+ // CLOUDROP_S3_SECRET_ACCESS_KEY for any setting not passed.
118
+ const storage = s3({ endpoint: "https://s3.us-east-1.amazonaws.com", region: "us-east-1" });
119
+ ```
120
+
121
+ `s3()` takes `endpoint`, `region`, `bucket`, `accessKeyId` and `secretAccessKey`, each from its option or its variable,
122
+ as `r2()` does, so with all five variables set `s3()` needs no argument. `endpoint` is an `http` or `https` URL with no
123
+ query or fragment; a path in it is kept as a prefix of every request, for a service behind a proxy path. `publicUrl` and
124
+ `fetch` work as for `r2()`.
125
+
126
+ Pass the driver to `createCloudrop` as `r2()` or `s3()` returns it. When a setting comes from the environment, the
127
+ server finds the driver's lazy check by the driver object itself, so a copy or a wrapper, such as `{ ...r2(), put }` for
128
+ logging, loses it. With a storage setting missing, every upload then fails with `STORAGE_ERROR`, and the log has
129
+ `cloudrop: a storage request failed.` with the `INVALID_CONFIG` on every request, instead of the single line saying
130
+ every request answers 500 until it is fixed. A wrapper is safe when every setting is passed as an option.
131
+
132
+ Which permissions the credentials need: [Bucket setup](bucket-setup.md#credentials-and-permissions).
133
+
134
+ ## Define routes
135
+
136
+ A route is one kind of upload: what files it accepts, how large, who may upload, and where the files go.
137
+
138
+ ```ts
139
+ import { route, unauthorized } from "cloudrop";
140
+ import { z } from "zod"; // any Standard Schema library: zod, valibot, arktype
141
+
142
+ const photo = route(
143
+ {
144
+ accept: ["image/png", "image/jpeg", "image/webp"],
145
+ maxSize: "10MB",
146
+ maxFiles: 20, // files per /upload call; the default is 10
147
+ metadata: z.object({ albumId: z.string() }),
148
+ authorize: async ({ request, metadata }) => {
149
+ const user = await getUser(request); // your app's session lookup
150
+ if (!user) return unauthorized();
151
+ return { userId: user.id };
152
+ },
153
+ },
154
+ {
155
+ prefix: ({ userId, metadata }) => `users/${userId}/albums/${metadata.albumId}`,
156
+ onComplete: async ({ file, userId }) => {
157
+ await savePhoto({ id: file.id, key: file.key, userId }); // your app's database write
158
+ return { key: file.key };
159
+ },
160
+ },
161
+ );
162
+ ```
163
+
164
+ | Option | What it does |
165
+ | --- | --- |
166
+ | `accept` | MIME types in lower case, such as `"image/png"`, `"image/*"` or `"*/*"`. One string or a list. The file name's extension must agree with its type: `photo.png` sent as `image/jpeg` is refused. |
167
+ | `maxSize` | The largest file, in bytes or a size such as `"5MB"`. At most what the storage allows for one object. |
168
+ | `maxFiles` | Files per `/upload` call, 1 to 100. Default 10. |
169
+ | `metadata` | Any [Standard Schema](https://standardschema.dev) (zod, valibot, arktype). The client sends metadata with the upload; the server validates it. Its output, as JSON, must fit in 2 KiB. A route without a schema refuses metadata. |
170
+ | `authorize` | Required. Decides who may upload (see [Authorize uploads](#authorize-uploads)). |
171
+ | `prefix` | The folder for generated keys. A key is `<prefix>/<ulid><ext>`, such as `users/42/avatars/01JD5Z3K7Q2X8M4N6P9R0S1T2V.png`. |
172
+ | `key` | The whole key instead of `<prefix>/<ulid><ext>`. Pass `prefix` or `key`, not both. A custom key must be unique (see below). |
173
+ | `visibility` | `"public"` or `"private"`. `"public"` needs the storage's `publicUrl`. Default: `"public"` when the storage has a `publicUrl`, otherwise `"private"`. |
174
+ | `replace` | With a store and `owner`: one file per owner, such as an avatar. A completed file deletes the owner's previous files on the route ([One file per owner](store.md#one-file-per-owner-replace)). |
175
+ | `onComplete` | Runs inside `/complete` once the file is verified. What it returns reaches the client as `data.data`, as JSON. |
176
+ | `owner` | With a store: who the file counts against for `quota` and `api.usage`, such as a user or team id, or `null`. |
177
+ | `afterComplete` | With a store: runs once the completion is recorded, at most once and best effort; the place for emails and webhooks. |
178
+
179
+ A route that takes any type of file says so with `accept: "*/*"`. The extension check still applies to the types
180
+ cloudrop knows, so `photo.png` sent as `image/jpeg` is still refused, and a file the browser gives no type is stored as
181
+ `application/octet-stream`:
182
+
183
+ ```ts
184
+ const attachment = route(
185
+ {
186
+ accept: "*/*",
187
+ maxSize: "100MB",
188
+ authorize: async ({ request }) => {
189
+ const user = await getUser(request); // your app's session lookup
190
+ return user ? { userId: user.id } : unauthorized();
191
+ },
192
+ },
193
+ { prefix: ({ userId }) => `users/${userId}/attachments` },
194
+ );
195
+ ```
196
+
197
+ `prefix`, `key` and `onComplete` receive what `authorize` returned, plus `request`, `metadata` and, for `prefix` and
198
+ `key`, the `file` (`id`, `name`, `size`, `type`, `ext`). `onComplete` receives the stored `file` (`id`, `key`, `name`,
199
+ `size`, `type`, and `url`, the public URL on a public route or `null`).
200
+
201
+ ### Keys
202
+
203
+ The server chooses every key; the client's file name never reaches it. The name appears only in the stored
204
+ `Content-Disposition` header. Keys from `prefix` and `key` are checked the same way: `.` and `..` segments, empty
205
+ segments, a leading `/`, control characters and keys over 1024 bytes are refused, and Unicode is normalized to NFC.
206
+ `prefix` must also return a string without a leading `/`.
207
+
208
+ A bad key is a bug in your route, not the user's mistake: the check throws, `/upload` answers `SERVER_ERROR` (HTTP 500)
209
+ and the server logs which route built the key and why it was refused.
210
+
211
+ A custom `key` must be unique. A rejected or aborted upload's object is deleted by key once a `HEAD`, or a create-only
212
+ completion, shows the object is this upload's. That delete is not conditional: another file stored under the same key
213
+ between the two requests would be deleted.
214
+
215
+ ### Private and public routes
216
+
217
+ A file on a public route gets a public URL in `file.url`. A private route needs a bucket without a public domain: when
218
+ the storage has a `publicUrl`, anyone who learns a key can read the file. `createCloudrop` logs a warning when a private
219
+ route uses storage with a `publicUrl`. Serve private files with `cloudrop.api.getUrl(key)`, which signs a short-lived
220
+ link.
221
+
222
+ ## Authorize uploads
223
+
224
+ Every route needs `authorize`. It receives `{ request, metadata }` and returns either a plain object with the facts
225
+ later steps need, or `unauthorized()` or `forbidden()`:
226
+
227
+ ```ts
228
+ authorize: async ({ request }) => {
229
+ const user = await getUser(request); // your app's session lookup
230
+ return user ? { userId: user.id } : unauthorized("Sign in to upload photos.");
231
+ },
232
+ ```
233
+
234
+ - `unauthorized()` refuses the upload with `UNAUTHORIZED`. Its message reaches the user; the default is "Sign in to
235
+ upload files here."
236
+ - `forbidden()` refuses a signed-in user who may not upload (a quota, a plan, a role) with `FORBIDDEN`. The default
237
+ message is "You are not allowed to upload files here. Ask the site owner for access if you think this is wrong."
238
+ - A public route must say so: `authorize: allowAnyone`. Public uploads are never a default.
239
+ - `prefix`, `key` and `onComplete` go in `route()`'s second argument. TypeScript types their context from what
240
+ `authorize` returns, in whatever order the options are written.
241
+ - What `authorize` returns is signed into the upload token, which the browser can read. Return ids, never secrets.
242
+ - The client sends cookies with every call to your server (`credentials: "include"`), so `authorize` can read the
243
+ session from `request`. A page on another site needs cookies set for that: see [Deployment](deployment.md).
244
+
245
+ Refuse a signed-out user with `unauthorized()` and a signed-in user who may not upload with `forbidden()`, so the user
246
+ is not told to sign in when they already have:
247
+
248
+ ```ts
249
+ authorize: async ({ request }) => {
250
+ const user = await getUser(request); // your app's session lookup
251
+ if (!user) return unauthorized();
252
+ if (user.plan === "free") return forbidden("Uploads need a paid plan. Upgrade in Settings, then try again.");
253
+ return { userId: user.id };
254
+ },
255
+ ```
256
+
257
+ ### Read the session
258
+
259
+ `request` is a standard `Request`, whatever framework mounts the handler. With
260
+ [better-auth](https://www.better-auth.com), pass its headers to `getSession`:
261
+
262
+ ```ts
263
+ import { route, unauthorized } from "cloudrop";
264
+ import { auth } from "./auth"; // your better-auth instance
265
+
266
+ const avatar = route(
267
+ {
268
+ accept: "image/*",
269
+ maxSize: "5MB",
270
+ authorize: async ({ request }) => {
271
+ const session = await auth.api.getSession({ headers: request.headers });
272
+ return session ? { userId: session.user.id } : unauthorized();
273
+ },
274
+ },
275
+ { prefix: ({ userId }) => `users/${userId}/avatars` },
276
+ );
277
+ ```
278
+
279
+ With your own session cookie, read it from the `Cookie` header:
280
+
281
+ ```ts
282
+ // Returns the value as sent: decodeURIComponent it if your cookie is encoded.
283
+ function readCookie(request: Request, name: string): string | undefined {
284
+ for (const pair of request.headers.get("cookie")?.split(";") ?? []) {
285
+ const [key, ...value] = pair.trim().split("=");
286
+ if (key === name) return value.join("=");
287
+ }
288
+ return undefined;
289
+ }
290
+
291
+ // In the route's policy:
292
+ authorize: async ({ request }) => {
293
+ const user = await findUserBySession(readCookie(request, "session")); // your app's session lookup
294
+ return user ? { userId: user.id } : unauthorized();
295
+ },
296
+ ```
297
+
298
+ An app that sends a bearer token instead of a cookie reads `request.headers.get("authorization")`; the client side is in
299
+ [Client](client.md#send-a-bearer-token).
300
+
301
+ ## The upload token and what it allows
302
+
303
+ `/upload` answers each accepted file with a **ticket**: the file's key, its upload URLs and an **upload token**. The
304
+ token carries everything later calls need: the route, the key, the size and type, what `authorize` returned and the
305
+ validated metadata. It is signed with your secret, so the server keeps no state and trusts nothing else a client sends.
306
+ It is signed, not encrypted: the browser can read it.
307
+
308
+ What happens in `/upload`:
309
+
310
+ 1. The handler checks the request: `POST`, an allowed origin, `Content-Type: application/json`, a body of at most
311
+ 64 KiB.
312
+ 2. The body is `{ route, files, metadata, idempotencyKey }`. The route must exist (`UNKNOWN_ROUTE`), the number of
313
+ files must be within `maxFiles` (`TOO_MANY_FILES`), and each file entry needs a name, size and type. File names are
314
+ normalized to NFC before they are counted (1 to 255 Unicode code points) and stored. `idempotencyKey` is optional:
315
+ 16 to 128 letters, digits, `-` or `_` (`INVALID_INPUT` otherwise). The client sends a new one for each ask and the
316
+ same one on every retry of it; without a store it is checked and ignored, with one a retry
317
+ [supersedes the attempt whose answer was lost](store.md#what-changes-for-the-client). Never reuse a key for a new
318
+ ask: a request with a key ends the pending uploads of earlier requests with the same key, route and owner. On a
319
+ route without `owner`, or when it answers null, the key does nothing.
320
+ 3. The route's metadata schema validates the metadata (`INVALID_METADATA`).
321
+ 4. `authorize` runs (`UNAUTHORIZED`, `FORBIDDEN`).
322
+ 5. Each file's type and size are checked against the route (`FILE_TYPE_NOT_ALLOWED`, `FILE_TOO_LARGE`), and its key is
323
+ built. A refused file does not stop the others.
324
+ 6. Plugins' `beforeUpload` hooks run.
325
+ 7. Only then is anything signed.
326
+
327
+ Then the rules that follow from a stateless token:
328
+
329
+ - **`authorize` runs only in `/upload`.** The token is the authority for that file for 24 hours. A session revoked
330
+ mid-upload can still finish the upload, so check the session again in `onComplete` when that matters: `request`
331
+ carries the caller's cookies and headers.
332
+ - **Upload URLs live 15 minutes.** The client renews them through `/sign`. Every URL ends at least 15 minutes before
333
+ its token, so a `PUT` started under the last one can still be completed; in a token's last 15 minutes `/sign`
334
+ answers `UPLOAD_EXPIRED`.
335
+ - **`/abort` is cleanup, not revocation.** Until the token expires, whoever holds it can get a new single-`PUT` URL,
336
+ upload and complete, and can delete its own completed file through `/abort`. An expired token still aborts an
337
+ unfinished upload, but never deletes a stored file.
338
+ - **`keep` narrows `/abort` without a store.** `/abort { token, keep: true }` never deletes an object that landed, even
339
+ with a live token: it only aborts an unfinished multipart upload, since the server cannot tell whether `onComplete`
340
+ ran. The client's `discard()` sends it, so discarding an upload whose `/complete` may have finished keeps the file.
341
+ With a [database store](store.md) the row decides as for any `/abort`, and `keep` changes nothing. `keep` must be a
342
+ boolean when sent (`INVALID_INPUT` otherwise).
343
+ - **A removed route.** `/abort` still cleans up, and runs `onAbort`, after a deploy removed or renamed the token's route.
344
+ `/sign` and `/complete` refuse such a token with `UNKNOWN_ROUTE`.
345
+
346
+ A [database store](store.md) changes the first and third rules: `api.revokeUploads` ends a user's unfinished uploads
347
+ at their next call, and `/abort` never deletes a completed file.
348
+
349
+ What `/complete` verifies, which is the real guarantee:
350
+
351
+ - **Single `PUT`:** a `HEAD` of the object. Its size, type and upload id must match the token.
352
+ - **Multipart:** the bucket's list of parts. Every part's size must match the plan; completion uses the server's part
353
+ list, never the client's. A missing or wrong-sized part answers `PARTS_MISSING` with its number, and the client sends
354
+ it again.
355
+ - For a single `PUT`, a wrong size or type deletes the object and answers `VERIFICATION_FAILED`. A multipart upload's
356
+ type is set by the server when it creates the upload, so only part sizes can be wrong, and those are sent again.
357
+ - An object another upload wrote under the same key is never deleted: it answers `VERIFICATION_FAILED` (single `PUT`)
358
+ or `ALREADY_EXISTS` (multipart).
359
+
360
+ What the server signs or sets, so the bucket itself refuses anything else:
361
+
362
+ - **A single `PUT` URL** signs the exact size and type, `If-None-Match: *` (a URL can never overwrite an object), the
363
+ upload id in `x-amz-meta-cloudrop-id`, and the `Content-Disposition`.
364
+ - **A multipart upload** gets its type, upload id and `Content-Disposition` from the server when it is created. Each
365
+ part URL signs only that part's exact size.
366
+
367
+ The `Content-Disposition` is `inline` for raster images, video and audio, and `attachment` for everything else,
368
+ including HTML, SVG and XML. That keeps an uploaded HTML or SVG file from running as a page on a public bucket domain.
369
+
370
+ Why it works this way: the M2 decisions in [docs/decisions](https://github.com/vcode-sh/cloudrop/blob/main/docs/decisions/README.md) and
371
+ [the design](https://github.com/vcode-sh/cloudrop/blob/main/docs/superpowers/specs/2026-11-15-cloudrop-design.md#7-security-and-verification).
372
+
373
+ ## Hooks
374
+
375
+ ### onComplete
376
+
377
+ `onComplete` is a route option. It runs inside `/complete`, after the file is verified, at least once per file. Its JSON
378
+ result reaches the client as `data.data`; without `onComplete`, `data.data` is `null`. With a [database store](store.md)
379
+ it runs once per file, and on a store built with `transaction: true` its writes through `tx` commit with the upload;
380
+ `owner` and `afterComplete` are store callbacks, described there.
381
+
382
+ ### Plugin hooks
383
+
384
+ Plugins add server hooks through `createCloudrop({ plugins })`. Each plugin is `{ id, server }`, and `server` takes any
385
+ of these functions:
386
+
387
+ | Hook | When it runs |
388
+ | --- | --- |
389
+ | `beforeUpload` | In `/upload`, after authorization and the size and type checks, before anything is signed. Return a `CloudropError` to refuse every file. |
390
+ | `afterVerify` | In `/complete`, after verification, before `onComplete`. Return a `CloudropError` to refuse the file: the object is deleted and the error reaches the client. |
391
+ | `onAbort` | When a file `beforeUpload` accepted is refused, cannot be started, is rejected at `/complete`, or is ended through `/abort`. Release a reservation here. |
392
+ | `extendRoute` | Once per route, in `createCloudrop`. Throw a `CloudropError` with `INVALID_CONFIG` to refuse the route. |
393
+
394
+ ```ts
395
+ import { type CloudropPlugin, CloudropError } from "cloudrop";
396
+
397
+ const quota: CloudropPlugin = {
398
+ id: "quota",
399
+ server: {
400
+ beforeUpload: async ({ files, auth }) => {
401
+ const ok = await reserveQuota(auth, files); // your app's quota check
402
+ return ok ? undefined : new CloudropError("FORBIDDEN", "You are out of storage. Delete some files first.");
403
+ },
404
+ onAbort: async ({ file }) => {
405
+ await releaseQuota(file.id); // your app's cleanup, idempotent by file.id
406
+ },
407
+ },
408
+ };
409
+ ```
410
+
411
+ A `beforeUpload` refusal refuses every file of the job with its code and message. `FORBIDDEN` says the user is signed
412
+ in but may not upload this; the message says what to do (see [Errors](errors.md#upload-endpoint-errors)).
413
+
414
+ Nothing runs when an abandoned upload's token expires, so a reservation also needs its own expiry. A database store's
415
+ `quota` reserves and releases bytes for you, with no plugin (see [Database store](store.md#owners-and-quota)).
416
+ cloudrop's own plugins (`contentChecks`, `limits`, `images`, `checksums`) arrive in M6.
417
+
418
+ ### Make hooks idempotent
419
+
420
+ Hooks can run more than once. A retried or replayed request repeats `afterVerify` and `onComplete` (on `/complete`) and
421
+ `onAbort` (on `/abort`), and a resumed upload runs `afterVerify` and `onComplete` again. Make their side effects
422
+ idempotent by the stable `file.id`: for example, insert with `file.id` as the primary key and ignore a duplicate. A
423
+ database store answers a finished upload's retries from its row instead (see
424
+ [what it guarantees](store.md#what-it-guarantees)).
425
+
426
+ The client also sends a slow call again. A `/complete` slower than 120 s, or an `/upload` slower than 30 s, counts as no
427
+ answer and is retried (see [Stalled requests](client.md#stalled-requests)), so keep `onComplete` and `authorize` well
428
+ under that, and `onComplete` idempotent. A retried `/upload` runs `authorize` and `beforeUpload` again: the
429
+ `idempotencyKey` it carries lets a store release what the lost attempt reserved, not plugins.
430
+
431
+ An app that must refuse a late upload after `/abort` (see [the token](#the-upload-token-and-what-it-allows)) checks its
432
+ own record in `afterVerify`, such as a released quota reservation, and refuses it there, which deletes the object.
433
+
434
+ ## Mounting the handler
435
+
436
+ `cloudrop.handler(request)` takes a `Request` and always resolves to a `Response`; it never throws. It serves `POST`,
437
+ and the CORS preflight `OPTIONS`, at `<basePath>/upload`, `/sign`, `/complete` and `/abort`. With the default
438
+ `basePath`, that is `/api/cloudrop/upload` and so on.
439
+
440
+ ### Next.js
441
+
442
+ ```ts
443
+ // app/api/cloudrop/[...all]/route.ts
444
+ import { toNextHandler } from "cloudrop/next";
445
+ import { cloudrop } from "../../../../lib/cloudrop";
446
+
447
+ export const { GET, POST, OPTIONS } = toNextHandler(cloudrop);
448
+ ```
449
+
450
+ `next build` loads `lib/cloudrop.ts`. Settings from the environment are read on the first request, so the build needs
451
+ no secrets.
452
+
453
+ ### Node http, http2 and Express
454
+
455
+ ```ts
456
+ import http from "node:http";
457
+ import { toNodeHandler } from "cloudrop/node";
458
+ import { cloudrop } from "./lib/cloudrop";
459
+
460
+ http.createServer(toNodeHandler(cloudrop)).listen(3000);
461
+ ```
462
+
463
+ With Express (installed separately), mount it at the path, before any body parser:
464
+
465
+ ```ts
466
+ import express from "express";
467
+ import { toNodeHandler } from "cloudrop/node";
468
+ import { cloudrop } from "./lib/cloudrop";
469
+
470
+ const app = express();
471
+ app.use("/api/cloudrop", toNodeHandler(cloudrop));
472
+ app.use(express.json()); // body parsers after cloudrop
473
+ app.listen(3000);
474
+ ```
475
+
476
+ A parser that reads the body first leaves nothing for cloudrop to read.
477
+
478
+ `toNodeHandler` takes the request's origin from `Host` (or HTTP/2's `:authority`) and the scheme from the connection,
479
+ never from `X-Forwarded-*` or `:scheme`, because that origin decides the same-origin check. Rather than guess an origin
480
+ such as `localhost`, it answers `400` when:
481
+
482
+ - the request has no `Host` (or `:authority`);
483
+ - `Host` is sent twice;
484
+ - the host is malformed: it carries userinfo, a path or an invalid port;
485
+ - `host` and `:authority` name different origins;
486
+ - the request target is not a path, such as the absolute form `POST http://host/api/cloudrop/upload`. Browsers send that
487
+ form only to proxies, and accepting it would let the target choose the origin.
488
+
489
+ A hand-built request without `rawHeaders` is read from `headers` alone.
490
+
491
+ ### Hono
492
+
493
+ ```ts
494
+ import { Hono } from "hono";
495
+ import { cloudrop } from "./lib/cloudrop";
496
+
497
+ const app = new Hono();
498
+ app.all("/api/cloudrop/*", (c) => cloudrop.handler(c.req.raw));
499
+
500
+ export default app;
501
+ ```
502
+
503
+ `c.req.raw` is the standard `Request`. The path is your `basePath` followed by `/*`.
504
+
505
+ - Use `app.all`, not `app.post`. The handler answers the CORS preflight (`OPTIONS`) itself, and answers any other
506
+ method with `METHOD_NOT_ALLOWED`.
507
+ - Keep that path out of CORS middleware such as `hono/cors`. The handler already answers preflights from
508
+ `trustedOrigins` and sets the CORS headers on its own answers. A middleware would apply its own rules instead: scope
509
+ it to your other routes, for example `app.use("/api/app/*", cors())`.
510
+
511
+ ### Bun
512
+
513
+ ```ts
514
+ import { cloudrop } from "./lib/cloudrop";
515
+
516
+ Bun.serve({
517
+ port: 3000,
518
+ routes: {
519
+ "/api/cloudrop/*": (request) => cloudrop.handler(request),
520
+ },
521
+ fetch: () => new Response("Not found", { status: 404 }), // your app's other requests
522
+ });
523
+ ```
524
+
525
+ ### Any runtime with Request and Response
526
+
527
+ Deno, Cloudflare Workers and frameworks that speak `Request` and `Response` call the handler directly:
528
+
529
+ ```ts
530
+ // Cloudflare Workers
531
+ export default {
532
+ fetch: (request: Request) => cloudrop.handler(request),
533
+ };
534
+ ```
535
+
536
+ On Workers, pass `secret` and the storage credentials explicitly unless your Worker exposes `process.env` (see
537
+ [Settings from the environment](#settings-from-the-environment)); creating the server from the Worker's `env`:
538
+ [Deployment](deployment.md#cloudflare-workers). How the server's parallel storage calls fit Workers' subrequest limits
539
+ has not been measured yet.
540
+
541
+ ## Origins
542
+
543
+ The handler accepts:
544
+
545
+ - requests from its own origin;
546
+ - requests from `trustedOrigins`, exact origins such as `"https://app.example.com"`, never `"*"`;
547
+ - requests without an `Origin` header, which come from servers and native apps, unless `Sec-Fetch-Site: cross-site`
548
+ shows a browser that dropped it. `Origin: null` is refused.
549
+
550
+ Everything else gets `ORIGIN_NOT_ALLOWED`. The handler also requires `Content-Type: application/json`, so a page on
551
+ another origin must pass a CORS preflight first.
552
+
553
+ The handler sees its own origin in the request URL and trusts no `X-Forwarded-*` header. **Behind a proxy that
554
+ terminates TLS or rewrites `Host`, your own pages look cross-origin:** list the app's public origin in
555
+ `trustedOrigins`. The first time the handler refuses a request from an origin, it logs a warning naming the refused
556
+ origin and the one it sees, for up to 16 origins.
557
+
558
+ Same-origin versus cross-origin setups, cookies across sites and which origin the bucket's CORS rule lists:
559
+ [Deployment](deployment.md).
560
+
561
+ ## File API
562
+
563
+ `cloudrop.api` works on the same storage from your server. Every call returns `{ data, error }`.
564
+
565
+ | Call | What it does |
566
+ | --- | --- |
567
+ | `getUrl(key, { expiresIn?, download? })` | A URL to read the object. With a `publicUrl` and no options: the plain public URL. Otherwise a presigned `GET`, valid for at least `expiresIn` seconds (default 3600). `download` names the saved file. |
568
+ | `head(key)` | The object's size, type, ETag, metadata and upload time, or `null` when it does not exist. |
569
+ | `put(key, body, options?)` | A small server-side upload, up to the storage's single-`PUT` limit. |
570
+ | `delete(key)` | Deletes one object. Deleting a missing key succeeds. |
571
+ | `deleteMany(keys)` | Deletes many objects; each key ends up in `deleted` or in `failed` with its own error. |
572
+ | `copy(from, to)` | Copies an object. |
573
+ | `deletePrefix(prefix)` | Empties a folder prefix ending in `/`, such as `"users/42/"`, then lists it again to prove it is empty. For erasure requests. |
574
+ | `checkBucket({ origins? })` | Reports the bucket's CORS rule, lifecycle rule and public-access conflicts (see below). |
575
+
576
+ With a store, `api` also has `file`, `files`, `usage`, `revokeUploads`, `deleteFile`, `eraseOwner`, `reconcile` and
577
+ `sweep` (see [Database store](store.md#file-operations)). For an erasure request, `eraseOwner` needs no key layout and
578
+ proves when nothing is left; `deletePrefix` empties a folder you name.
579
+
580
+ `getUrl` signs at the start of an `expiresIn` window and the URL stays valid for two windows, so every viewer in one
581
+ window gets the same, cacheable URL.
582
+
583
+ ### checkBucket
584
+
585
+ ```ts
586
+ const { data: report, error } = await cloudrop.api.checkBucket({ origins: ["https://app.example.com"] });
587
+ // report.cors, report.lifecycle, report.publicAccess: each { status: "ok" | "problem" | "unknown", message }
588
+ ```
589
+
590
+ It checks:
591
+
592
+ - **`cors`:** whether browsers on `origins` (default: `trustedOrigins`) may `PUT` with the headers cloudrop signs and
593
+ read `ETag`.
594
+ - **`lifecycle`:** whether an enabled rule aborts incomplete multipart uploads across the bucket.
595
+ - **`publicAccess`:** whether a private route stores files on a bucket with a public URL.
596
+
597
+ `cors` and `lifecycle` come back `unknown` when the credentials may not read that setting (an R2 object token cannot)
598
+ or the storage cannot report it (Wrangler's local R2 answers `501 NotImplemented`). `cors` is also `unknown` when no
599
+ origin was given; `lifecycle` does not depend on origins. With an R2
600
+ admin read token, R2's answers have not been measured yet. Any other storage failure fails the call.
601
+
602
+ In development (`NODE_ENV=development`, exactly), the handler's first request runs this check once in the background
603
+ and logs a warning for each problem. More on what it can and cannot see: [Bucket setup](bucket-setup.md#what-checkbucket-can-tell-you).