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/CHANGELOG.md +55 -0
- package/README.md +29 -1
- package/dist/adapters/sql.d.ts +3 -0
- package/dist/adapters/sql.js +7 -0
- package/dist/adapters/sql.js.map +1 -1
- package/dist/cli.js +2045 -0
- package/dist/{client-ePVHwvMv.js → client-DxP3uv8V.js} +47 -5
- package/dist/client-DxP3uv8V.js.map +1 -0
- package/dist/client.js +1 -1
- package/dist/index.d.ts +25 -1
- package/dist/index.js +86 -45
- package/dist/index.js.map +1 -1
- package/dist/react.js +1 -1
- package/dist/testing.d.ts +81 -0
- package/dist/testing.js +1243 -0
- package/dist/testing.js.map +1 -0
- package/docs/README.md +30 -0
- package/docs/bucket-setup.md +226 -0
- package/docs/client.md +386 -0
- package/docs/command.md +129 -0
- package/docs/deployment.md +169 -0
- package/docs/errors.md +150 -0
- package/docs/hono.md +276 -0
- package/docs/react.md +508 -0
- package/docs/resume.md +253 -0
- package/docs/server.md +603 -0
- package/docs/store.md +804 -0
- package/docs/testing-your-app.md +328 -0
- package/docs/troubleshooting.md +176 -0
- package/package.json +10 -2
- package/dist/client-ePVHwvMv.js.map +0 -1
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).
|