@quickback-dev/cli 0.66.1 → 0.66.3
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/README.md +7 -4
- package/dist/commands/build.d.ts +51 -0
- package/dist/commands/build.d.ts.map +1 -0
- package/dist/commands/build.js +804 -0
- package/dist/commands/build.js.map +1 -0
- package/dist/commands/build.test.d.ts +2 -0
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/build.test.js +150 -0
- package/dist/commands/build.test.js.map +1 -0
- package/dist/commands/check.d.ts +2 -2
- package/dist/commands/check.js +4 -4
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.d.ts +1 -1
- package/dist/commands/create.js +7 -7
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/deploy.d.ts +6 -6
- package/dist/commands/deploy.js +23 -23
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/example.js +1 -1
- package/dist/commands/example.js.map +1 -1
- package/dist/commands/mcp.js +1 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/commands/migrate.d.ts +1 -1
- package/dist/commands/migrate.js +3 -3
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrations.js +2 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/push.js +1 -1
- package/dist/commands/push.js.map +1 -1
- package/dist/commands/start.js +1 -1
- package/dist/commands/start.js.map +1 -1
- package/dist/cursor/quickback.mdc +1 -1
- package/dist/index.js +18 -15
- package/dist/index.js.map +1 -1
- package/dist/lib/auth.js +1 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/compiler-floor.d.ts +1 -1
- package/dist/lib/compiler-floor.js +1 -1
- package/dist/lib/file-loader.js +2 -2
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +16 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.js +16 -0
- package/dist/lib/file-writer.test.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +3 -3
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/prepare-output.test.js +1 -1
- package/dist/lib/prepare-output.test.js.map +1 -1
- package/dist/lib/schema-sync/index.js +1 -1
- package/dist/lib/schema-sync/index.test.js +1 -1
- package/dist/lib/schema-sync/index.test.js.map +1 -1
- package/dist/skill/SKILL.md +6 -6
- package/dist/skill/docs/api/actions.md +27 -3
- package/dist/skill/docs/api/batch-operations.md +4 -0
- package/dist/skill/docs/api/crud.md +64 -0
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +19 -2
- package/dist/skill/docs/changelog/index.md +33 -1
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/index.md +8 -3
- package/dist/skill/docs/configure/providers.md +3 -0
- package/dist/skill/docs/configure/variables.md +3 -3
- package/dist/skill/docs/define/access.md +7 -0
- package/dist/skill/docs/define/actions/defining.md +39 -8
- package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/dist/skill/docs/define/actions/scoped-db.md +46 -16
- package/dist/skill/docs/define/areas.md +1 -1
- package/dist/skill/docs/define/diagnostics.md +1 -0
- package/dist/skill/docs/define/encryption.md +1 -1
- package/dist/skill/docs/define/feature.md +14 -7
- package/dist/skill/docs/define/guards.md +34 -3
- package/dist/skill/docs/define/schema.md +29 -17
- package/dist/skill/docs/define/security.md +1 -1
- package/dist/skill/docs/define/transitions.md +35 -4
- package/dist/skill/docs/define/views.md +33 -0
- package/dist/skill/docs/index.md +2 -2
- package/dist/skill/docs/platform/auth/api-keys.md +1 -1
- package/dist/skill/docs/platform/auth/using-auth.md +37 -0
- package/dist/skill/docs/platform/database/d1.md +2 -2
- package/dist/skill/docs/platform/database/neon.md +4 -4
- package/dist/skill/docs/platform/email/index.md +1 -1
- package/dist/skill/docs/platform/queues/handlers.md +1 -1
- package/dist/skill/docs/platform/queues/using-queues.md +1 -1
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/index.md +3 -3
- package/dist/skill/docs/platform/storage/r2.md +87 -37
- package/dist/skill/docs/platform/storage/using-r2.md +99 -19
- package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
- package/dist/skill/docs/start/deploy-browser.md +39 -44
- package/dist/skill/docs/start/deploy-owner-access.md +28 -19
- package/dist/skill/docs/start/deploy.md +2 -2
- package/dist/skill/docs/start/first-api.md +1 -1
- package/dist/skill/docs/start/hand-crafted.md +3 -3
- package/dist/skill/docs/start/index.md +3 -3
- package/dist/skill/docs/start/quickstart.md +3 -3
- package/dist/skill/docs/start/template-blog.md +2 -2
- package/dist/skill/docs/start/template-cloudflare.md +2 -2
- package/dist/skill/docs/start/template-empty.md +1 -1
- package/dist/skill/docs/start/templates.md +1 -1
- package/dist/skill/docs/tooling/claude-skill.md +1 -1
- package/dist/skill/docs/tooling/cli.md +40 -19
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
- package/dist/skill/docs/tooling/output.md +32 -2
- package/dist/skill/docs/tooling/troubleshooting.md +1 -1
- package/dist/skill/docs/ui/account/environment-variables.md +2 -2
- package/dist/skill/docs/ui/account/features/admin.md +1 -1
- package/dist/skill/docs/ui/account/features/avatars.md +24 -8
- package/dist/skill/docs/ui/account/features/index.md +9 -5
- package/dist/skill/docs/ui/account/features/organizations.md +3 -2
- package/dist/skill/docs/ui/account/index.md +3 -1
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/dist/skill/docs/ui/admin/actions.md +97 -3
- package/dist/skill/docs/ui/admin/components.md +4 -6
- package/dist/skill/docs/ui/admin/connecting.md +15 -3
- package/dist/skill/docs/ui/admin/index.md +71 -6
- package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
- package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
- package/dist/skill/docs/ui/admin/schema-format.md +39 -2
- package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
- package/dist/skill/docs/ui/admin/security.md +19 -4
- package/dist/skill/docs/ui/admin/table-views.md +59 -12
- package/package.json +1 -1
- package/src/cursor/quickback.mdc +1 -1
- package/src/skill/SKILL.md +6 -6
- package/src/skill/docs/api/actions.md +27 -3
- package/src/skill/docs/api/batch-operations.md +4 -0
- package/src/skill/docs/api/crud.md +64 -0
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +19 -2
- package/src/skill/docs/changelog/index.md +33 -1
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/index.md +8 -3
- package/src/skill/docs/configure/providers.md +3 -0
- package/src/skill/docs/configure/variables.md +3 -3
- package/src/skill/docs/define/access.md +7 -0
- package/src/skill/docs/define/actions/defining.md +39 -8
- package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/src/skill/docs/define/actions/scoped-db.md +46 -16
- package/src/skill/docs/define/areas.md +1 -1
- package/src/skill/docs/define/diagnostics.md +1 -0
- package/src/skill/docs/define/encryption.md +1 -1
- package/src/skill/docs/define/feature.md +14 -7
- package/src/skill/docs/define/guards.md +34 -3
- package/src/skill/docs/define/schema.md +29 -17
- package/src/skill/docs/define/security.md +1 -1
- package/src/skill/docs/define/transitions.md +35 -4
- package/src/skill/docs/define/views.md +33 -0
- package/src/skill/docs/index.md +2 -2
- package/src/skill/docs/platform/auth/api-keys.md +1 -1
- package/src/skill/docs/platform/auth/using-auth.md +37 -0
- package/src/skill/docs/platform/database/d1.md +2 -2
- package/src/skill/docs/platform/database/neon.md +4 -4
- package/src/skill/docs/platform/email/index.md +1 -1
- package/src/skill/docs/platform/queues/handlers.md +1 -1
- package/src/skill/docs/platform/queues/using-queues.md +1 -1
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/index.md +3 -3
- package/src/skill/docs/platform/storage/r2.md +87 -37
- package/src/skill/docs/platform/storage/using-r2.md +99 -19
- package/src/skill/docs/platform/webhooks/inbound.md +40 -0
- package/src/skill/docs/start/deploy-browser.md +39 -44
- package/src/skill/docs/start/deploy-owner-access.md +28 -19
- package/src/skill/docs/start/deploy.md +2 -2
- package/src/skill/docs/start/first-api.md +1 -1
- package/src/skill/docs/start/hand-crafted.md +3 -3
- package/src/skill/docs/start/index.md +3 -3
- package/src/skill/docs/start/quickstart.md +3 -3
- package/src/skill/docs/start/template-blog.md +2 -2
- package/src/skill/docs/start/template-cloudflare.md +2 -2
- package/src/skill/docs/start/template-empty.md +1 -1
- package/src/skill/docs/start/templates.md +1 -1
- package/src/skill/docs/tooling/claude-skill.md +1 -1
- package/src/skill/docs/tooling/cli.md +40 -19
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
- package/src/skill/docs/tooling/output.md +32 -2
- package/src/skill/docs/tooling/troubleshooting.md +1 -1
- package/src/skill/docs/ui/account/environment-variables.md +2 -2
- package/src/skill/docs/ui/account/features/admin.md +1 -1
- package/src/skill/docs/ui/account/features/avatars.md +24 -8
- package/src/skill/docs/ui/account/features/index.md +9 -5
- package/src/skill/docs/ui/account/features/organizations.md +3 -2
- package/src/skill/docs/ui/account/index.md +3 -1
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
- package/src/skill/docs/ui/admin/actions.md +97 -3
- package/src/skill/docs/ui/admin/components.md +4 -6
- package/src/skill/docs/ui/admin/connecting.md +15 -3
- package/src/skill/docs/ui/admin/index.md +71 -6
- package/src/skill/docs/ui/admin/inline-editing.md +38 -4
- package/src/skill/docs/ui/admin/record-layouts.md +22 -21
- package/src/skill/docs/ui/admin/schema-format.md +39 -2
- package/src/skill/docs/ui/admin/schema-registry.md +107 -7
- package/src/skill/docs/ui/admin/security.md +19 -4
- package/src/skill/docs/ui/admin/table-views.md +59 -12
|
@@ -41,7 +41,7 @@ Two `../` — up from `services/schedules/` to `quickback/`, then down into `fea
|
|
|
41
41
|
|
|
42
42
|
1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
|
|
43
43
|
2. **`[triggers] crons = [...]`** in `wrangler.toml` — one deduped, sorted list across all schedules.
|
|
44
|
-
3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback
|
|
44
|
+
3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback build`, so there's nothing to hand-maintain.
|
|
45
45
|
|
|
46
46
|
## Execute context
|
|
47
47
|
|
|
@@ -7,11 +7,11 @@ The Quickback Stack uses Cloudflare's storage primitives for different use cases
|
|
|
7
7
|
| Service | Use Case | Pages |
|
|
8
8
|
|---------|----------|-------|
|
|
9
9
|
| **KV** | Sessions, caching, rate limiting | [Setup](/platform/storage/kv) · [Usage](/platform/storage/using-kv) |
|
|
10
|
-
| **R2** |
|
|
10
|
+
| **R2** | Hosted file bytes (listing photos, avatars, attachments) | [Setup](/platform/storage/r2) · [Usage](/platform/storage/using-r2) |
|
|
11
11
|
|
|
12
12
|
## Getting Started
|
|
13
13
|
|
|
14
14
|
- **[KV Setup](/platform/storage/kv)** — Namespace and bindings configuration
|
|
15
15
|
- **[Using KV](/platform/storage/using-kv)** — Sessions, caching, rate limiting
|
|
16
|
-
- **[R2 Setup](/platform/storage/r2)** —
|
|
17
|
-
- **[Using R2](/platform/storage/using-r2)** —
|
|
16
|
+
- **[R2 Setup](/platform/storage/r2)** — Public vs signed reads, buckets, bindings
|
|
17
|
+
- **[Using R2](/platform/storage/using-r2)** — URL fields, public buckets, signed uploads
|
|
@@ -9,12 +9,12 @@ Quickback provides built-in file storage using Cloudflare R2.
|
|
|
9
9
|
- **Presign-only (default)** — emits just the `ctx.storage` signer (presigned
|
|
10
10
|
PUT/GET URLs straight to R2). **No new D1, no `/storage/v1/*` endpoints, no
|
|
11
11
|
files worker.** You compute keys and store file references in your own table.
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
Use this when you already have a media table and only need to sign large or
|
|
13
|
+
confidential transfers — see [Presigned uploads](#presigned-uploads).
|
|
14
14
|
- **Managed (`managed: true`)** — adds the turnkey subsystem on top: a FILES_DB
|
|
15
15
|
metadata database (buckets + objects), the `/storage/v1/*` upload/download/
|
|
16
|
-
manage endpoints, and a
|
|
17
|
-
|
|
16
|
+
manage endpoints, and a files worker for serving. Use this for listing photos,
|
|
17
|
+
avatars, and other files that should be **public-if-you-have-the-link**.
|
|
18
18
|
|
|
19
19
|
```ts
|
|
20
20
|
// Presign-only (default) — ctx.storage against a bucket, nothing else
|
|
@@ -24,12 +24,50 @@ defineFileStorage("cloudflare-r2", { bucketName: "my-app-media" })
|
|
|
24
24
|
defineFileStorage("cloudflare-r2", { managed: true, bucketName: "my-app-files" })
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
New projects can omit `bucketName` — it defaults to `<project>-media
|
|
28
|
-
|
|
29
|
-
|
|
27
|
+
New projects can omit `bucketName` — it defaults to `<project>-media`. Existing
|
|
28
|
+
projects set `bucketName` to a bucket they already have. A browser deploy
|
|
29
|
+
creates the bucket; it cannot mint the R2 API-token secrets that presigning
|
|
30
|
+
needs.
|
|
30
31
|
|
|
31
|
-
The sections below document the **managed** subsystem
|
|
32
|
-
|
|
32
|
+
The sections below document the **managed** subsystem. For signed PUT/GET only,
|
|
33
|
+
jump to [Presigned uploads](#presigned-uploads).
|
|
34
|
+
|
|
35
|
+
## Read models
|
|
36
|
+
|
|
37
|
+
Most files should be **semi-private**: anyone who has the exact URL can GET
|
|
38
|
+
them; anyone who does not, cannot. That is a public bucket
|
|
39
|
+
(`readScope: "public"`) plus a UUID in the object path. Signed URLs are the
|
|
40
|
+
smaller case — confidential files that must stay unreadable even if the URL
|
|
41
|
+
leaks.
|
|
42
|
+
|
|
43
|
+
| Read model | Who can GET | Use for |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| **Public bucket** (`readScope: "public"`) | Anyone with the exact URL | Listing photos, avatars, public media, shareable attachments |
|
|
46
|
+
| **Session-gated** (`organization` / `user`) | Signed-in caller who passes RBAC | Org-internal docs the CMS should still gate |
|
|
47
|
+
| **Signed GET** (`storage.signGetUrl`) | Holder of a short-lived URL | IDs, payroll, medical, anything that must expire |
|
|
48
|
+
|
|
49
|
+
Public is not a directory listing. The files worker serves `/public/...` with
|
|
50
|
+
no auth. Put a UUID in the key so `/public/org/listings/hero.jpg` is not
|
|
51
|
+
guessable:
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
public/{orgId}/listings/{uuid}-hero.jpg
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Do **not** enable Cloudflare's `r2.dev` public-bucket domain for this. That
|
|
58
|
+
publishes every object in the bucket. Quickback's `readScope: "public"` keeps
|
|
59
|
+
the R2 bucket private and only the `public/` prefix anonymous — so a later
|
|
60
|
+
private object is not world-readable.
|
|
61
|
+
|
|
62
|
+
A Cloudflare-public bucket (`PUT …/domains/managed { enabled: true }`) is OK
|
|
63
|
+
only when that bucket will **only ever** hold public objects. PUTs stay
|
|
64
|
+
authenticated either way. Presign still needs
|
|
65
|
+
`R2_ACCOUNT_ID` / `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY`; through-Worker
|
|
66
|
+
uploads (`POST /object`) do not.
|
|
67
|
+
|
|
68
|
+
If the file already lives on the internet, store a URL instead of R2 —
|
|
69
|
+
`photoUrl: q.url()`. No bucket, no secrets, no files worker. See
|
|
70
|
+
[Using R2](/platform/storage/using-r2#store-a-url-instead).
|
|
33
71
|
|
|
34
72
|
## Architecture
|
|
35
73
|
|
|
@@ -118,10 +156,11 @@ export default {
|
|
|
118
156
|
| GET | `/object` | List objects |
|
|
119
157
|
| POST | `/url` | Get file URL for serving |
|
|
120
158
|
|
|
121
|
-
> For anything larger than a small image — video, audio, big PDFs —
|
|
122
|
-
> **presigned
|
|
123
|
-
> request-body cap
|
|
124
|
-
>
|
|
159
|
+
> For anything larger than a small image — video, audio, big PDFs — upload with a
|
|
160
|
+
> **presigned PUT**. The bytes go straight to R2, so you skip the Worker's
|
|
161
|
+
> request-body cap. Serving those files can still be a public URL; presign is the
|
|
162
|
+
> upload path, not the default read model. See
|
|
163
|
+
> [Presigned uploads](#presigned-uploads).
|
|
125
164
|
|
|
126
165
|
|
|
127
166
|
### Files Worker (files.yourdomain.com)
|
|
@@ -140,20 +179,21 @@ Buckets organize files and define access control policies.
|
|
|
140
179
|
```bash
|
|
141
180
|
POST /storage/v1/bucket
|
|
142
181
|
{
|
|
143
|
-
"name": "
|
|
144
|
-
"readScope": "
|
|
182
|
+
"name": "listings",
|
|
183
|
+
"readScope": "public",
|
|
145
184
|
"writeScope": "organization",
|
|
146
|
-
"
|
|
147
|
-
"writeRoles": ["admin"],
|
|
148
|
-
"deleteRoles": ["admin"]
|
|
185
|
+
"writeRoles": ["admin", "member"]
|
|
149
186
|
}
|
|
150
187
|
```
|
|
151
188
|
|
|
189
|
+
`readScope: "public"` is the default for listing photos and avatars. Switch to
|
|
190
|
+
`organization` or `user` only when a signed-in session must gate the GET.
|
|
191
|
+
|
|
152
192
|
### Scope Options
|
|
153
193
|
|
|
154
194
|
| Scope | Read Behavior | Write Behavior |
|
|
155
195
|
|-------|---------------|----------------|
|
|
156
|
-
| `public` | Anyone
|
|
196
|
+
| `public` | Anyone with the exact URL (no auth) | N/A |
|
|
157
197
|
| `organization` | Org members only | Org members only |
|
|
158
198
|
| `user` | Owner only | Owner only |
|
|
159
199
|
|
|
@@ -222,18 +262,20 @@ Response:
|
|
|
222
262
|
"name": "profile.jpg",
|
|
223
263
|
"size": 12345,
|
|
224
264
|
"mimeType": "image/jpeg",
|
|
225
|
-
"readScope": "
|
|
265
|
+
"readScope": "public"
|
|
226
266
|
}
|
|
227
267
|
```
|
|
228
268
|
|
|
229
|
-
## Presigned uploads
|
|
269
|
+
## Presigned uploads
|
|
270
|
+
|
|
271
|
+
Streaming bytes through the Worker (`POST /object`) is fine for listing photos
|
|
272
|
+
and other small files. It needs no R2 API token — the bucket binding is enough.
|
|
230
273
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
Worker.
|
|
274
|
+
Use a **presigned PUT** for large media (video, audio, big PDFs) or when the
|
|
275
|
+
object itself is confidential. The Worker runs the access checks and hands back
|
|
276
|
+
a short-lived URL the client uploads to **directly**. The bytes never touch your
|
|
277
|
+
Worker. Presigned **GET** (`storage.signGetUrl`) is the matching read model for
|
|
278
|
+
those confidential files — not for listing photos.
|
|
237
279
|
|
|
238
280
|
```bash
|
|
239
281
|
# 1. Ask the API to sign an upload URL (auth + bucket + role checks run here)
|
|
@@ -321,17 +363,20 @@ action — the JSON body parser and its ~1 MiB cap stay on for every other route
|
|
|
321
363
|
|
|
322
364
|
## Serving Files
|
|
323
365
|
|
|
324
|
-
### Public
|
|
366
|
+
### Public (semi-private) files — the usual case
|
|
325
367
|
|
|
326
|
-
Files in buckets with `readScope: "public"` are stored with a `public/` prefix
|
|
368
|
+
Files in buckets with `readScope: "public"` are stored with a `public/` prefix
|
|
369
|
+
and served with **no authentication**. Anyone who has the exact URL can open
|
|
370
|
+
the file. Put a UUID in the path so the URL is not guessable:
|
|
327
371
|
|
|
328
372
|
```
|
|
329
|
-
https://files.yourdomain.com/public/org_abc/
|
|
373
|
+
https://files.yourdomain.com/public/org_abc/listings/3f2a…-hero.jpg
|
|
330
374
|
```
|
|
331
375
|
|
|
332
|
-
|
|
376
|
+
Store that URL on the listing row. Send it to the public listing page. This is
|
|
377
|
+
the right model for property photos, avatars, and shareable media.
|
|
333
378
|
|
|
334
|
-
###
|
|
379
|
+
### Session-gated private files
|
|
335
380
|
|
|
336
381
|
Private files require a valid Better Auth session cookie:
|
|
337
382
|
|
|
@@ -367,7 +412,9 @@ When file storage is configured, the compiler generates:
|
|
|
367
412
|
|
|
368
413
|
The compiler also adds [`aws4fetch`](https://github.com/mhart/aws4fetch) to your
|
|
369
414
|
`package.json` (used by the presigner) and the R2 presign secrets to your
|
|
370
|
-
generated `CloudflareBindings` type.
|
|
415
|
+
generated `CloudflareBindings` type. Package-mode compiles (Start browser
|
|
416
|
+
deploys) resolve it from the compiler image's `/deps/node_modules`, not from
|
|
417
|
+
an `npm install` of that generated `package.json`.
|
|
371
418
|
|
|
372
419
|
## Deployment
|
|
373
420
|
|
|
@@ -400,8 +447,9 @@ After compiling:
|
|
|
400
447
|
wrangler deploy
|
|
401
448
|
```
|
|
402
449
|
|
|
403
|
-
6. **Set the R2 presign secrets**
|
|
404
|
-
|
|
450
|
+
6. **Set the R2 presign secrets** only if you use signed PUT/GET. Public-bucket
|
|
451
|
+
uploads through `POST /object` do not need them. See
|
|
452
|
+
[Presigned uploads](#presigned-uploads):
|
|
405
453
|
```bash
|
|
406
454
|
wrangler secret put R2_ACCOUNT_ID
|
|
407
455
|
wrangler secret put R2_ACCESS_KEY_ID
|
|
@@ -442,7 +490,9 @@ Both paths answer `413` with the actual and permitted byte counts.
|
|
|
442
490
|
|
|
443
491
|
## Security Model
|
|
444
492
|
|
|
445
|
-
- **Upload security**: Enforced by API worker (auth
|
|
446
|
-
|
|
493
|
+
- **Upload security**: Enforced by the API worker (auth, org, role). A public
|
|
494
|
+
read scope never implies a public write.
|
|
495
|
+
- **Serve security**: Public prefix = URL is the capability. Session-gated
|
|
496
|
+
paths re-check membership on every GET. Signed GET expires.
|
|
447
497
|
- **Soft deletes**: Files are marked deleted in metadata but retained in R2
|
|
448
498
|
- **Tenant isolation**: All files are prefixed with organization ID
|
|
@@ -1,15 +1,87 @@
|
|
|
1
1
|
# Using R2
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Most "files" on a listing, profile, or gallery are **a URL**. Host the bytes in
|
|
4
|
+
R2 only when this app must own the upload.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
Pick the first row that fits:
|
|
7
|
+
|
|
8
|
+
| What you need | What to build |
|
|
9
|
+
|---|---|
|
|
10
|
+
| Photo already on the web, or the user pastes a link | `photoUrl: q.url()` — no R2, no secrets |
|
|
11
|
+
| This app hosts the bytes; anyone with the link may view | Managed public bucket (`readScope: "public"`) + UUID in the key |
|
|
12
|
+
| Large or confidential bytes; the URL itself must expire | Signed PUT/GET — needs an R2 API token |
|
|
13
|
+
|
|
14
|
+
Public-if-you-have-the-link is the usual read model (listing photos, avatars).
|
|
15
|
+
Signed URLs are the smaller case. Details:
|
|
16
|
+
[R2 Setup → Read models](/platform/storage/r2#read-models).
|
|
17
|
+
|
|
18
|
+
By default `defineFileStorage("cloudflare-r2")` is **presign-only**: you get
|
|
19
|
+
the `ctx.storage` signer and nothing else. The `/storage/v1/*` endpoints
|
|
20
|
+
further down exist only in the [managed subsystem](/platform/storage/r2#two-modes)
|
|
8
21
|
(`managed: true`).
|
|
9
22
|
|
|
10
|
-
##
|
|
23
|
+
## Store a URL instead
|
|
24
|
+
|
|
25
|
+
A property listing, avatar, or hero image that is already a link does not need
|
|
26
|
+
R2. Store the URL on the row. The CMS gets a URL input; the public listing page
|
|
27
|
+
renders it. A browser deploy does not ask for R2 secrets.
|
|
28
|
+
|
|
29
|
+
```ts title="quickback/features/listings/listings.ts"
|
|
30
|
+
import { q, defineTable } from "@quickback/compiler";
|
|
31
|
+
|
|
32
|
+
export const listings = q.table("listings", {
|
|
33
|
+
id: q.id(),
|
|
34
|
+
title: q.text().required(),
|
|
35
|
+
photoUrl: q.url(),
|
|
36
|
+
organizationId: q.scope("organization"),
|
|
37
|
+
...q.audit(),
|
|
38
|
+
...q.softDelete(),
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
export default defineTable(listings, {
|
|
42
|
+
read: { access: { roles: ["member+"] } },
|
|
43
|
+
crud: {
|
|
44
|
+
create: { access: { roles: ["member+"] } },
|
|
45
|
+
update: { access: { roles: ["admin+"] } },
|
|
46
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
47
|
+
},
|
|
48
|
+
guards: { createable: ["title", "photoUrl"], updatable: ["title", "photoUrl"] },
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`q.url()` rejects `javascript:` / `data:` URIs at the validation edge. Use
|
|
53
|
+
`q.text()` only when you must store a non-http value.
|
|
54
|
+
|
|
55
|
+
## Upload into a public bucket (managed)
|
|
56
|
+
|
|
57
|
+
With `managed: true`, create a bucket with `readScope: "public"` and PUT bytes
|
|
58
|
+
through the Worker. No R2 API token. The files worker serves the object at
|
|
59
|
+
`/public/...` with no auth. Put a UUID in the path so the URL is not guessable.
|
|
11
60
|
|
|
12
|
-
|
|
61
|
+
```bash
|
|
62
|
+
# 1. Create the bucket once (write stays org-gated)
|
|
63
|
+
curl -X POST https://api.example.com/storage/v1/bucket \
|
|
64
|
+
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
|
|
65
|
+
-d '{ "name": "listings", "readScope": "public", "writeScope": "organization", "writeRoles": ["admin", "member"] }'
|
|
66
|
+
|
|
67
|
+
# 2. Upload — bytes go through the Worker, binding only
|
|
68
|
+
curl -X POST https://api.example.com/storage/v1/object/listings/3f2a9c…-hero.jpg \
|
|
69
|
+
-H "Authorization: Bearer <token>" -H "Content-Type: image/jpeg" \
|
|
70
|
+
--data-binary @hero.jpg
|
|
71
|
+
# → { "key": "public/org_abc/listings/3f2a9c…-hero.jpg", "readScope": "public", … }
|
|
72
|
+
|
|
73
|
+
# 3. Store that URL on the listing (or POST /storage/v1/url to resolve it)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Serve:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
https://files.yourdomain.com/public/org_abc/listings/3f2a9c…-hero.jpg
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Signed upload (large or confidential files)
|
|
83
|
+
|
|
84
|
+
Write a `defineAction` that signs a presigned URL and stores the key in
|
|
13
85
|
**your own table**. Bytes go directly to R2 — the Worker only signs.
|
|
14
86
|
|
|
15
87
|
```ts title="quickback/features/media/actions/signUpload.ts"
|
|
@@ -38,7 +110,7 @@ curl -X POST https://api.example.com/api/v1/media/sign-upload \
|
|
|
38
110
|
-d '{ "filename": "report.pdf", "contentType": "application/pdf" }'
|
|
39
111
|
# → { "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...", "key": "...", "headers": { "Content-Type": "application/pdf" } }
|
|
40
112
|
|
|
41
|
-
# 2. Upload the bytes straight to R2 (replay the returned headers)
|
|
113
|
+
# 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
|
|
42
114
|
curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
|
|
43
115
|
```
|
|
44
116
|
|
|
@@ -48,12 +120,16 @@ returns a presigned GET URL. Pass `bucket` to target a bucket other than the
|
|
|
48
120
|
configured default.
|
|
49
121
|
|
|
50
122
|
Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
|
|
51
|
-
and `R2_SECRET_ACCESS_KEY` secrets.
|
|
123
|
+
and `R2_SECRET_ACCESS_KEY` secrets. A [browser deploy](/start/deploy-browser)
|
|
124
|
+
refuses the project until those exist; it cannot mint them. Create the token in
|
|
125
|
+
the Cloudflare dashboard (R2 → Manage API Tokens, Object Read & Write) and set
|
|
126
|
+
the secrets with `wrangler secret put` / `quickback deploy`. See
|
|
127
|
+
[R2 Setup → Presigned uploads](/platform/storage/r2#presigned-uploads).
|
|
52
128
|
|
|
53
|
-
|
|
129
|
+
### Managed presign endpoints
|
|
54
130
|
|
|
55
131
|
With `managed: true`, the generated API also exposes turnkey presigned
|
|
56
|
-
endpoints backed by
|
|
132
|
+
endpoints backed by FILES_DB:
|
|
57
133
|
|
|
58
134
|
```bash
|
|
59
135
|
# 1. Request a presigned upload URL
|
|
@@ -72,12 +148,12 @@ curl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \
|
|
|
72
148
|
|
|
73
149
|
## Download Flow
|
|
74
150
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
151
|
+
**Public bucket / URL field** — GET the stored URL. No session, no signature.
|
|
152
|
+
|
|
153
|
+
**Presign-only, confidential files** — mint a short-lived download URL with
|
|
154
|
+
`storage.signGetUrl(key, { downloadFilename })` from your action.
|
|
78
155
|
|
|
79
|
-
|
|
80
|
-
checks applied:
|
|
156
|
+
**Managed, session-gated buckets** — the files worker re-checks membership:
|
|
81
157
|
|
|
82
158
|
```bash
|
|
83
159
|
# Download a file (auth + firewall enforced)
|
|
@@ -93,12 +169,16 @@ The download endpoint:
|
|
|
93
169
|
|
|
94
170
|
## Role-Based Access
|
|
95
171
|
|
|
96
|
-
File
|
|
172
|
+
File **writes** always respect the same security layers as your API:
|
|
173
|
+
|
|
174
|
+
- **Firewall** — Users can only upload files belonging to their organization
|
|
175
|
+
- **Access** — Role-based upload / delete permissions
|
|
97
176
|
|
|
98
|
-
|
|
99
|
-
|
|
177
|
+
File **reads** follow the bucket's `readScope`. `public` does not run those
|
|
178
|
+
checks on GET — the URL is the capability.
|
|
100
179
|
|
|
101
180
|
## See Also
|
|
102
181
|
|
|
103
|
-
- [R2 Setup](/platform/storage/r2) —
|
|
182
|
+
- [R2 Setup](/platform/storage/r2) — Read models, bucket creation, wrangler bindings
|
|
104
183
|
- [Avatars](/ui/account/features/avatars) — Avatar upload UI integration
|
|
184
|
+
- [Deploy from your browser](/start/deploy-browser) — R2 secrets block Start deploys
|
|
@@ -338,3 +338,43 @@ which re-send the original signed envelope.
|
|
|
338
338
|
**Fail-closed runtime posture for every scheme:** an unset secret env is a
|
|
339
339
|
500 rejection — never a verify-skip; any signature failure is a 401 Problem
|
|
340
340
|
before the body is ever parsed.
|
|
341
|
+
|
|
342
|
+
### Per-organization secrets: verify in the action
|
|
343
|
+
|
|
344
|
+
`webhook:` resolves its secret from **env** — one secret per deployment. When
|
|
345
|
+
each organization connects its own provider account (a per-org Resend or
|
|
346
|
+
Svix signing secret in an `.encrypted()` column), declare `rawBody: true`
|
|
347
|
+
instead and verify inside `execute`. The route reads the body once (bounded,
|
|
348
|
+
pre-auth, exactly like the `webhook:` gate), parses `input` from those bytes,
|
|
349
|
+
and hands the same bytes to your handler — so the MAC runs over what the
|
|
350
|
+
provider signed, never over re-serialised JSON.
|
|
351
|
+
|
|
352
|
+
{/* doc-compile: skip — excerpt: `decryptValue` and the `connections` table live in the generated project; the fence shows the shape only. */}
|
|
353
|
+
```ts title="quickback/features/comms/actions/resendEvents.ts"
|
|
354
|
+
import { z } from "zod";
|
|
355
|
+
import { defineAction } from "../.quickback/define-action";
|
|
356
|
+
import { decryptValue } from "../../../../src/lib/encryption";
|
|
357
|
+
|
|
358
|
+
export default defineAction({
|
|
359
|
+
description: "Per-org Resend events — secret lives on the connection row",
|
|
360
|
+
path: "/resend/events/:orgId",
|
|
361
|
+
method: "POST",
|
|
362
|
+
access: { roles: ["PUBLIC"] },
|
|
363
|
+
rawBody: true,
|
|
364
|
+
input: z.object({ type: z.string(), data: z.record(z.unknown()) }),
|
|
365
|
+
execute: async ({ c, env, db, rawBody, input }) => {
|
|
366
|
+
const orgId = c.req.param("orgId");
|
|
367
|
+
const row = await db.query.connections.findFirst({ where: (t, { eq }) => eq(t.organizationId, orgId) });
|
|
368
|
+
// ctx.crypto is hydrated for authenticated requests only — a PUBLIC
|
|
369
|
+
// action reads an .encrypted() column through decryptValue directly.
|
|
370
|
+
const secret = await decryptValue(env, db, orgId, row.signingSecret);
|
|
371
|
+
// verify `rawBody` + the provider's signature headers with `secret`; throw a 401 ActionError on failure
|
|
372
|
+
return { ok: true, type: input.type };
|
|
373
|
+
},
|
|
374
|
+
});
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
`rawBody` is only ever populated on standalone, non-GET actions; a `GET`
|
|
378
|
+
declaring it is a compile error. Actions with `webhook:` get `rawBody` too —
|
|
379
|
+
useful when a provider signs the body and *also* nests a second signed
|
|
380
|
+
payload inside it.
|