@quickback-dev/cli 0.66.0 → 0.66.2
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 +793 -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/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +5 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/lib/wrangler-resources.test.js +6 -0
- package/dist/lib/wrangler-resources.test.js.map +1 -1
- package/dist/skill/SKILL.md +24 -9
- package/dist/skill/docs/api/crud.md +7 -0
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/changelog/index.md +27 -1
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +11 -5
- package/dist/skill/docs/configure/providers.md +6 -3
- package/dist/skill/docs/configure/single-tenant.md +7 -3
- package/dist/skill/docs/configure/variables.md +3 -3
- package/dist/skill/docs/define/access.md +10 -0
- package/dist/skill/docs/define/actions/defining.md +35 -7
- package/dist/skill/docs/define/actions/index.md +1 -1
- package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/dist/skill/docs/define/actions/scoped-db.md +68 -21
- 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 +17 -8
- package/dist/skill/docs/define/firewall.md +2 -0
- package/dist/skill/docs/define/guards.md +27 -3
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/relationships.md +7 -0
- package/dist/skill/docs/define/schema.md +44 -14
- package/dist/skill/docs/define/security.md +1 -1
- package/dist/skill/docs/define/transitions.md +35 -4
- package/dist/skill/docs/define/triggers.md +14 -3
- 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 +2 -2
- package/dist/skill/docs/platform/auth/using-auth.md +37 -0
- package/dist/skill/docs/platform/database/d1.md +15 -3
- 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/realtime/using-realtime.md +6 -4
- 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 +40 -45
- package/dist/skill/docs/start/deploy-owner-access.md +60 -52
- package/dist/skill/docs/start/deploy.md +4 -4
- package/dist/skill/docs/start/first-api.md +2 -2
- package/dist/skill/docs/start/hand-crafted.md +3 -3
- package/dist/skill/docs/start/index.md +3 -3
- package/dist/skill/docs/start/patterns.md +17 -2
- 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 +3 -3
- 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 +21 -16
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
- 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 +74 -1
- package/dist/skill/docs/tooling/output.md +23 -2
- package/dist/skill/docs/tooling/troubleshooting.md +1 -1
- package/dist/skill/docs/ui/account/customization.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/api-keys.md +10 -8
- package/dist/skill/docs/ui/account/features/avatars.md +24 -8
- package/dist/skill/docs/ui/account/features/index.md +16 -11
- package/dist/skill/docs/ui/account/features/organizations.md +3 -2
- package/dist/skill/docs/ui/account/hooks.md +2 -0
- package/dist/skill/docs/ui/account/index.md +10 -5
- package/dist/skill/docs/ui/account/with-quickback.md +2 -2
- 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 +24 -9
- package/src/skill/docs/api/crud.md +7 -0
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/changelog/index.md +27 -1
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +11 -5
- package/src/skill/docs/configure/providers.md +6 -3
- package/src/skill/docs/configure/single-tenant.md +7 -3
- package/src/skill/docs/configure/variables.md +3 -3
- package/src/skill/docs/define/access.md +10 -0
- package/src/skill/docs/define/actions/defining.md +35 -7
- package/src/skill/docs/define/actions/index.md +1 -1
- package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/src/skill/docs/define/actions/scoped-db.md +68 -21
- 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 +17 -8
- package/src/skill/docs/define/firewall.md +2 -0
- package/src/skill/docs/define/guards.md +27 -3
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/relationships.md +7 -0
- package/src/skill/docs/define/schema.md +44 -14
- package/src/skill/docs/define/security.md +1 -1
- package/src/skill/docs/define/transitions.md +35 -4
- package/src/skill/docs/define/triggers.md +14 -3
- 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 +2 -2
- package/src/skill/docs/platform/auth/using-auth.md +37 -0
- package/src/skill/docs/platform/database/d1.md +15 -3
- 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/realtime/using-realtime.md +6 -4
- 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 +40 -45
- package/src/skill/docs/start/deploy-owner-access.md +60 -52
- package/src/skill/docs/start/deploy.md +4 -4
- package/src/skill/docs/start/first-api.md +2 -2
- package/src/skill/docs/start/hand-crafted.md +3 -3
- package/src/skill/docs/start/index.md +3 -3
- package/src/skill/docs/start/patterns.md +17 -2
- 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 +3 -3
- 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 +21 -16
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
- 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 +74 -1
- package/src/skill/docs/tooling/output.md +23 -2
- package/src/skill/docs/tooling/troubleshooting.md +1 -1
- package/src/skill/docs/ui/account/customization.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/api-keys.md +10 -8
- package/src/skill/docs/ui/account/features/avatars.md +24 -8
- package/src/skill/docs/ui/account/features/index.md +16 -11
- package/src/skill/docs/ui/account/features/organizations.md +3 -2
- package/src/skill/docs/ui/account/hooks.md +2 -0
- package/src/skill/docs/ui/account/index.md +10 -5
- package/src/skill/docs/ui/account/with-quickback.md +2 -2
- 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
|
@@ -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.
|
|
@@ -1,12 +1,22 @@
|
|
|
1
1
|
# Deploy from your browser
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Author and validate a backend in [Quickback Start](https://start.quickback.dev), build its complete generated output, and optionally ship that exact revision to **your own Cloudflare account** — databases created, migrations applied, secrets minted, Worker live on a `workers.dev` URL. No local tooling required.
|
|
4
4
|
|
|
5
5
|
This page covers the browser flow. For local projects, or anything the browser flow doesn't support yet, use [`quickback deploy`](/start/deploy) — the CLI covers every resource type and is always available.
|
|
6
6
|
|
|
7
7
|
> Browser deployment is new. The hosted deploy service sits behind a kill switch, and provisioning is rate-limited to 5 deploys per minute per user — enough to stop a runaway retry loop, not something a normal deploy will ever hit. `quickback deploy` works for everyone today.
|
|
8
8
|
|
|
9
9
|
|
|
10
|
+
## The three-stage workspace
|
|
11
|
+
|
|
12
|
+
Start keeps authoring, building, and deployment separate:
|
|
13
|
+
|
|
14
|
+
1. **Quickback Definitions** contains the files authored through chat: `quickback.config.ts`, features, schemas, access rules, actions, and other source definitions. Start validates these anonymously as they change. **Definitions valid** means the authored files pass this feedback loop; it is not a complete, downloadable backend build.
|
|
15
|
+
2. **Generated Backend** runs the hosted complete build. Sign in to your Quickback account here, click **Build generated backend**, then inspect or download the complete compiled backend preview artifact. After a successful build, **Rebuild** remains available in this tab so you can rerun the complete build even when the definitions have not changed. Each successful build approves the exact source revision and build identity for deployment. It also runs Wrangler's bundle check, so a missing export fails here — use **Send to agent** on the error — instead of later at Deploy. Quickback login authorizes this hosted build; it does not grant Cloudflare access and it is not the login for the app you generate.
|
|
16
|
+
3. **Cloudflare Infrastructure** is optional and comes last. Once a complete build is approved, connect Cloudflare, choose the account, and deploy from this tab. This stage reuses the approved revision and build identity, **not the bytes of the step-2 preview artifact**. It compiles the stored source once to prepare the deployment plan, provisions the real Cloudflare resources, then compiles it again with those resource ids to build and upload the Cloudflare package. All connection state, resources, progress, live URLs, and generated-app administrator credentials stay here.
|
|
17
|
+
|
|
18
|
+
All three tabs remain selectable before a build, so the later stages can explain what they need. Editing a definition after a successful build marks Generated Backend **stale** and blocks Cloudflare deployment until you rebuild. This guarantees that the source being deployed matches the revision you inspected.
|
|
19
|
+
|
|
10
20
|
## Browser vs CLI
|
|
11
21
|
|
|
12
22
|
| | Deploy from Start | `quickback deploy` |
|
|
@@ -19,24 +29,26 @@ This page covers the browser flow. For local projects, or anything the browser f
|
|
|
19
29
|
|
|
20
30
|
## How a deploy runs
|
|
21
31
|
|
|
22
|
-
|
|
32
|
+
After Generated Backend has a current complete build, open **Cloudflare Infrastructure** and click **Deploy this app**. The deployment pipeline runs four phases and reports each one:
|
|
23
33
|
|
|
24
|
-
1. **
|
|
34
|
+
1. **Preparing deployment plan** — Start performs the first deployment compile from the stored source for the exact revision approved in Generated Backend. It emits a *deployment manifest*: the exact set of resources, migrations, and secrets the deploy will touch. A changed or stale source hash is rejected before this begins. Anything the browser flow can't deploy fails **here**, with a named reason — never as a half-deployed app.
|
|
25
35
|
2. **Provision** — each D1 database, KV namespace, and R2 bucket is created in your account, or **adopted** if a resource with the same name already exists. Retries and redeploys never create duplicates. Nothing is ever deleted automatically.
|
|
26
|
-
3. **
|
|
36
|
+
3. **Building Cloudflare package** — Start performs the second deployment compile from the same approved source, now with the real resource ids folded into its deployment configuration. The result is the upload package: Worker modules plus your CMS/Account SPA assets, when enabled. It does not upload the step-2 preview artifact. Every byte is hash-verified against the manifest before anything is uploaded.
|
|
27
37
|
4. **Finalize** — migrations apply, the Worker uploads with its bindings, secrets are set, and the `workers.dev` route is enabled. Start probes the URL and only shows **Live** once it actually answers.
|
|
28
38
|
|
|
29
39
|
Provision hands back a one-time approval that finalize must present, so the upload can only ever be the one that was approved — being signed in is deliberately not enough on its own. The approval is good for an hour, which no normal deploy comes close to.
|
|
30
40
|
|
|
31
|
-
A typical deploy takes one to two minutes, most of it
|
|
41
|
+
A typical deploy takes one to two minutes, most of it the two deployment compiles and provisioning.
|
|
32
42
|
|
|
33
43
|
## Naming the Worker
|
|
34
44
|
|
|
35
|
-
The
|
|
45
|
+
The project `name` in `quickback/quickback.config.ts` decides what the deploy is called. That definition drives the Worker **and** every derived resource — `<name>-auth`, `<name>-features`, and any audit, webhook, or file-metadata databases your features pull in.
|
|
46
|
+
|
|
47
|
+
Cloudflare Infrastructure displays the derived Worker name read-only. To change it, edit the definition in chat or Quickback Definitions, validate again, and rebuild. The old complete build remains inspectable but becomes stale and cannot be deployed. This prevents a Cloudflare setting from silently changing the artifact you just reviewed.
|
|
36
48
|
|
|
37
|
-
|
|
49
|
+
Redeploying the same name updates the same app in place. Changing it deploys a **separate copy**: a new Worker, on new databases, at a new URL. The previous app keeps running untouched — nothing is renamed or deleted in your Cloudflare account, so a name you've finished with is yours to clean up in the dashboard.
|
|
38
50
|
|
|
39
|
-
Names follow Cloudflare's rule — lowercase letters, digits, hyphens, and underscores, starting with a letter or digit, up to 64 characters.
|
|
51
|
+
Names follow Cloudflare's rule — lowercase letters, digits, hyphens, and underscores, starting with a letter or digit, up to 64 characters.
|
|
40
52
|
|
|
41
53
|
## What deploys
|
|
42
54
|
|
|
@@ -46,7 +58,7 @@ Supported today, end to end:
|
|
|
46
58
|
|---|---|
|
|
47
59
|
| D1 databases | All of a project's databases — auth, features, and (when your features pull them in) audit, webhooks, and file-metadata |
|
|
48
60
|
| KV namespace | The `KV` binding for rate limiting and session overflow |
|
|
49
|
-
| R2 bucket | Managed file storage (`managed: true`) |
|
|
61
|
+
| R2 bucket | Managed file storage (`managed: true`). The bucket is created; the R2 API-token secrets (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`) are **not**. Profile-picture and org-logo upload stay off unless those secrets are set — see [Avatars](/ui/account/features/avatars) |
|
|
50
62
|
| Realtime | The inline Broadcaster Durable Object, including its class registration |
|
|
51
63
|
| Email binding | The Cloudflare Email Service binding is attached (see the delivery caveat below) |
|
|
52
64
|
| CMS / Account UI | The bundled SPAs upload as static assets on the same Worker, with your app's real URL baked in |
|
|
@@ -61,7 +73,7 @@ Blocked, fail-closed at the compile phase — the deploy stops with the reason,
|
|
|
61
73
|
| Separate-worker realtime | Needs a second Worker + service binding |
|
|
62
74
|
| Custom `apps:` mounts | Typically need custom domains |
|
|
63
75
|
| Custom `bindings:` (Durable Objects, queues, services, extra R2 buckets) | Not represented by the deploy contract yet |
|
|
64
|
-
| Secrets you supply (third-party API keys, etc.) | The browser flow has no way to collect them yet — a project that *requires* one is refused rather than deployed broken |
|
|
76
|
+
| Secrets you supply (R2 API tokens, third-party API keys, etc.) | The browser flow has no way to collect them yet — a project that *requires* one is refused rather than deployed broken. For listing photos, store `q.url()` instead of enabling `fileStorage`, or download and `wrangler secret put` the three `R2_*` secrets |
|
|
65
77
|
| Hyperdrive, public R2 buckets, containers, workflows | Out of MVP scope |
|
|
66
78
|
|
|
67
79
|
> **Email delivery**: the email *binding* is attached so your app boots and auth works, but actually sending mail requires Email Sending to be configured on your Cloudflare account with a verified sending domain — which a fresh `workers.dev` app doesn't have. Start's builder defaults new apps to email + password **without** email verification for exactly this reason; enable verification, OTP, or magic links after you've configured a sending domain.
|
|
@@ -69,12 +81,12 @@ Blocked, fail-closed at the compile phase — the deploy stops with the reason,
|
|
|
69
81
|
|
|
70
82
|
## Connecting your Cloudflare account
|
|
71
83
|
|
|
72
|
-
|
|
84
|
+
Building and deploying use two deliberately separate identities:
|
|
73
85
|
|
|
74
|
-
- **
|
|
75
|
-
- **Grant deploy access** gives Quickback permission to deploy into your Cloudflare account
|
|
86
|
+
- **Sign in to Quickback** lives in Generated Backend and authorizes the hosted complete build. The account login page may offer several providers, but Start does not force Cloudflare as the login method.
|
|
87
|
+
- **Grant deploy access** lives in Cloudflare Infrastructure and gives Quickback permission to deploy into your Cloudflare account. It is a standard OAuth consent against Cloudflare's own dashboard, shown by the **Quickback** OAuth client. You pick the account, see exactly which permissions are requested, and can revoke at any time from Cloudflare under **My Profile → Access Management → Connected Applications** (or disconnect from Start).
|
|
76
88
|
|
|
77
|
-
|
|
89
|
+
The generated app's login is a third identity boundary. Its first administrator is created only during deployment and signs in to the app's own Account UI; see [Owner access](/start/deploy-owner-access).
|
|
78
90
|
|
|
79
91
|
What's requested, and why:
|
|
80
92
|
|
|
@@ -90,15 +102,15 @@ What's requested, and why:
|
|
|
90
102
|
|
|
91
103
|
Nothing broader is requested — no zone, DNS, billing, or account-management access.
|
|
92
104
|
|
|
93
|
-
If you cancel at Cloudflare's consent screen — or Cloudflare ends the attempt for any other reason — you land back in Start with
|
|
105
|
+
If you cancel at Cloudflare's consent screen — or Cloudflare ends the attempt for any other reason — you land back in Start with Cloudflare Infrastructure explaining what happened and a **Try again** button. Nothing is stored on a cancelled attempt, and a connection you already had is left untouched.
|
|
94
106
|
|
|
95
107
|
## Connection states and recovery
|
|
96
108
|
|
|
97
|
-
|
|
109
|
+
Cloudflare Infrastructure is the whole connection UI: it reports the state of your Cloudflare connection and offers exactly one thing to do about it.
|
|
98
110
|
|
|
99
111
|
| What you see | What happened | What to do |
|
|
100
112
|
|---|---|---|
|
|
101
|
-
| "Grant Quickback permission to deploy…" |
|
|
113
|
+
| "Grant Quickback permission to deploy…" | The complete build is ready, but no deploy permission is stored yet | **Grant deploy access** |
|
|
102
114
|
| Masked email badge, green | Connected and healthy | Deploy |
|
|
103
115
|
| Badge turns amber, "· reconnect" | Grant revoked in Cloudflare, or the connection was deleted (plain expiry never surfaces — tokens refresh server-side) | **Reconnect Cloudflare** — one consent, same connection record |
|
|
104
116
|
| "…also linked to a different Quickback login" | This Cloudflare account is connected under another Quickback account too — apps deployed there are listed there, not here | Nothing, unless an app you expected is missing: sign in with the Quickback account you deployed it from |
|
|
@@ -113,20 +125,20 @@ Deploy is disabled while a reconnect is pending, so a deploy never starts on a c
|
|
|
113
125
|
|
|
114
126
|
### Reconnecting
|
|
115
127
|
|
|
116
|
-
**Reconnect** re-runs the same consent and lands on the **same connection record** — your account picker, deploys, and
|
|
128
|
+
**Reconnect** re-runs the same consent and lands on the **same connection record** — your account picker, deploys, and admin password reset all keep working. Reconnecting is also how you widen a grant that's missing a permission.
|
|
117
129
|
|
|
118
130
|
### Connecting more than one Cloudflare account
|
|
119
131
|
|
|
120
|
-
Connect a second Cloudflare login with **Connect another** and
|
|
132
|
+
Connect a second Cloudflare login with **Connect another** and Cloudflare Infrastructure adds a login picker above the account picker. Start remembers which one you deployed with last and preselects it.
|
|
121
133
|
|
|
122
|
-
|
|
134
|
+
Cloudflare connections are owned by the Quickback account used for the complete build. If an app you expect is missing, return to Generated Backend and confirm that you are signed into the Quickback account that deployed it.
|
|
123
135
|
|
|
124
136
|
### Disconnecting vs. revoking
|
|
125
137
|
|
|
126
138
|
Two different things, and you usually want both:
|
|
127
139
|
|
|
128
|
-
- **Disconnect** (in
|
|
129
|
-
- **Revoke** (Cloudflare dashboard → **My Profile → Access Management → Connected Applications**, linked from
|
|
140
|
+
- **Disconnect** (in Cloudflare Infrastructure) makes Quickback forget the connection and its stored token. It doesn't touch anything in your Cloudflare account, and it never touches deployed apps — they're plain Workers in your account and keep running.
|
|
141
|
+
- **Revoke** (Cloudflare dashboard → **My Profile → Access Management → Connected Applications**, linked from Cloudflare Infrastructure) withdraws the grant itself. The stored ciphertext becomes useless immediately; the next thing Start tries turns into a reconnect prompt.
|
|
130
142
|
|
|
131
143
|
## Where your token lives
|
|
132
144
|
|
|
@@ -138,11 +150,12 @@ The OAuth token never reaches your browser, the chat model, or the compiler. It
|
|
|
138
150
|
|
|
139
151
|
The grant is standing permission carried by short-lived credentials. The token that can actually touch your account expires every hour; the deploy service refreshes it server-side, so expiry never reaches you as a prompt — a leaked working token goes stale within the hour either way. What persists is the sealed refresh token, which can only mint the next short-lived token.
|
|
140
152
|
|
|
141
|
-
Revoking in Cloudflare (**My Profile → Access Management → Connected Applications**) kills the whole chain immediately — the stored ciphertext becomes useless, and
|
|
153
|
+
Revoking in Cloudflare (**My Profile → Access Management → Connected Applications**) kills the whole chain immediately — the stored ciphertext becomes useless, and Cloudflare Infrastructure turns the next failed call into a reconnect prompt. See [Connection states and recovery](#connection-states-and-recovery) for the full set.
|
|
142
154
|
|
|
143
155
|
## Secrets on the deployed app
|
|
144
156
|
|
|
145
157
|
- `BETTER_AUTH_SECRET` is minted by the deploy service — 256 bits of fresh entropy per app — and set on the Worker directly. It's never shown to the browser or stored in your project.
|
|
158
|
+
- **R2 presign secrets are not minted.** `defineFileStorage("cloudflare-r2")` requires `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, and `R2_SECRET_ACCESS_KEY`. Cloudflare Infrastructure creates the bucket; it cannot create an R2 API token (Cloudflare OAuth has no API-Tokens-Write scope). Finalize stops with `user-secret-missing` until those exist. Store a `q.url()` on the listing instead, or download the project and `wrangler secret put` after creating a token at **R2 → Manage API Tokens**.
|
|
146
159
|
- **Existing Worker secrets are always preserved.** Cloudflare's upload API replaces a Worker's bindings wholesale; the deploy explicitly carries every existing secret across, so a redeploy can never silently delete a secret you set by hand.
|
|
147
160
|
|
|
148
161
|
## Redeploys are safe by construction
|
|
@@ -172,35 +185,17 @@ Click Deploy as often as you like:
|
|
|
172
185
|
|
|
173
186
|
## After it's live
|
|
174
187
|
|
|
175
|
-
|
|
188
|
+
Cloudflare Infrastructure keeps the deployed target for this chat, with links straight into its CMS, Account UI, and API. It is read from local storage rather than transient deployment progress, so it survives a reload — refreshing no longer loses the way back to your app.
|
|
176
189
|
|
|
177
190
|
Your app answers at `https://<app-name>.<your-subdomain>.workers.dev`:
|
|
178
191
|
|
|
179
192
|
- **API-only apps** serve a small landing page at `/` (browsers) and a JSON service descriptor (everything else), linking `/api/v1`, `/openapi.json`, and `/health` — never a bare 404 on first visit.
|
|
180
|
-
- **Apps with the Account UI or CMS** redirect `/` to the login page or CMS. Both ship by default from Start, at `/cms/` and `/account/`. The CMS
|
|
193
|
+
- **Apps with the Account UI or CMS** redirect `/` to the login page or CMS. Both ship by default from Start, at `/cms/` and `/account/`. The CMS admits organization members (`cms.access: "member"`) — your first deploy seeds you as `owner` of the first organization (and `user.role === "sysadmin"`) — see [Owner access](/start/deploy-owner-access).
|
|
181
194
|
- `/health` reports status and whether email is configured.
|
|
182
195
|
|
|
183
|
-
The deployed app is a normal Worker in *your* account: logs, metrics, and settings live in your Cloudflare dashboard
|
|
184
|
-
|
|
185
|
-
That handover works because a successful deploy writes the real Cloudflare resource ids back into your `quickback.config.ts`:
|
|
186
|
-
|
|
187
|
-
```ts title="quickback/quickback.config.ts"
|
|
188
|
-
database: {
|
|
189
|
-
name: "cloudflare-d1",
|
|
190
|
-
config: {
|
|
191
|
-
splitDatabases: true,
|
|
192
|
-
authBinding: "AUTH_DB",
|
|
193
|
-
featuresBinding: "DB",
|
|
194
|
-
authDatabaseId: "8f2c…", // written by the deploy
|
|
195
|
-
featuresDatabaseId: "b91e…", // written by the deploy
|
|
196
|
-
},
|
|
197
|
-
},
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
Those ids identify the exact databases serving your app, so the download, the file tree, and any copy you hand to another tool all carry them. Without them `quickback deploy` can only match your resources by *name* — which silently creates a second, empty set if you deploy from a different Cloudflare login or rename the app.
|
|
201
|
-
|
|
202
|
-
> Keep those id keys when you edit the config. Deleting them points your next deploy at fresh, empty databases rather than the ones holding your data. If they do go missing, redeploying from Start writes them back.
|
|
196
|
+
The deployed app is a normal Worker in *your* account: logs, metrics, and settings live in your Cloudflare dashboard. Click **Download complete .zip** in Generated Backend when you want a local copy. The reviewed definitions and build are immutable after deployment, so Cloudflare resource ids are not written back into them.
|
|
203
197
|
|
|
198
|
+
For ongoing CLI management, keep the same project name and deploy through the same Cloudflare account so `quickback deploy` can match the named resources. Renaming the project intentionally creates a separate app and resource set.
|
|
204
199
|
|
|
205
200
|
## Not yet available
|
|
206
201
|
|