@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.
Files changed (228) hide show
  1. package/README.md +7 -4
  2. package/dist/commands/build.d.ts +51 -0
  3. package/dist/commands/build.d.ts.map +1 -0
  4. package/dist/commands/build.js +793 -0
  5. package/dist/commands/build.js.map +1 -0
  6. package/dist/commands/build.test.d.ts +2 -0
  7. package/dist/commands/build.test.d.ts.map +1 -0
  8. package/dist/commands/build.test.js +150 -0
  9. package/dist/commands/build.test.js.map +1 -0
  10. package/dist/commands/check.d.ts +2 -2
  11. package/dist/commands/check.js +4 -4
  12. package/dist/commands/check.js.map +1 -1
  13. package/dist/commands/create.d.ts +1 -1
  14. package/dist/commands/create.js +7 -7
  15. package/dist/commands/create.js.map +1 -1
  16. package/dist/commands/deploy.d.ts +6 -6
  17. package/dist/commands/deploy.js +23 -23
  18. package/dist/commands/deploy.js.map +1 -1
  19. package/dist/commands/example.js +1 -1
  20. package/dist/commands/example.js.map +1 -1
  21. package/dist/commands/mcp.js +1 -1
  22. package/dist/commands/mcp.js.map +1 -1
  23. package/dist/commands/migrate.d.ts +1 -1
  24. package/dist/commands/migrate.js +3 -3
  25. package/dist/commands/migrate.js.map +1 -1
  26. package/dist/commands/migrations.js +2 -2
  27. package/dist/commands/migrations.js.map +1 -1
  28. package/dist/commands/push.js +1 -1
  29. package/dist/commands/push.js.map +1 -1
  30. package/dist/commands/start.js +1 -1
  31. package/dist/commands/start.js.map +1 -1
  32. package/dist/cursor/quickback.mdc +1 -1
  33. package/dist/index.js +18 -15
  34. package/dist/index.js.map +1 -1
  35. package/dist/lib/auth.js +1 -1
  36. package/dist/lib/auth.js.map +1 -1
  37. package/dist/lib/compiler-floor.d.ts +1 -1
  38. package/dist/lib/compiler-floor.js +1 -1
  39. package/dist/lib/file-loader.js +2 -2
  40. package/dist/lib/file-loader.js.map +1 -1
  41. package/dist/lib/file-writer.d.ts +2 -0
  42. package/dist/lib/file-writer.d.ts.map +1 -1
  43. package/dist/lib/file-writer.js +16 -0
  44. package/dist/lib/file-writer.js.map +1 -1
  45. package/dist/lib/file-writer.test.js +16 -0
  46. package/dist/lib/file-writer.test.js.map +1 -1
  47. package/dist/lib/migrations/file-envelopes.js +3 -3
  48. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  49. package/dist/lib/prepare-output.test.js +1 -1
  50. package/dist/lib/prepare-output.test.js.map +1 -1
  51. package/dist/lib/schema-sync/index.js +1 -1
  52. package/dist/lib/schema-sync/index.test.js +1 -1
  53. package/dist/lib/schema-sync/index.test.js.map +1 -1
  54. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  55. package/dist/lib/wrangler-resources.js +5 -2
  56. package/dist/lib/wrangler-resources.js.map +1 -1
  57. package/dist/lib/wrangler-resources.test.js +6 -0
  58. package/dist/lib/wrangler-resources.test.js.map +1 -1
  59. package/dist/skill/SKILL.md +24 -9
  60. package/dist/skill/docs/api/crud.md +7 -0
  61. package/dist/skill/docs/api/index.md +1 -1
  62. package/dist/skill/docs/api/openapi.md +1 -1
  63. package/dist/skill/docs/changelog/index.md +27 -1
  64. package/dist/skill/docs/configure/agents.md +1 -1
  65. package/dist/skill/docs/configure/domains.md +1 -1
  66. package/dist/skill/docs/configure/index.md +11 -5
  67. package/dist/skill/docs/configure/providers.md +6 -3
  68. package/dist/skill/docs/configure/single-tenant.md +7 -3
  69. package/dist/skill/docs/configure/variables.md +3 -3
  70. package/dist/skill/docs/define/access.md +10 -0
  71. package/dist/skill/docs/define/actions/defining.md +35 -7
  72. package/dist/skill/docs/define/actions/index.md +1 -1
  73. package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
  74. package/dist/skill/docs/define/actions/scoped-db.md +68 -21
  75. package/dist/skill/docs/define/areas.md +1 -1
  76. package/dist/skill/docs/define/diagnostics.md +1 -0
  77. package/dist/skill/docs/define/encryption.md +1 -1
  78. package/dist/skill/docs/define/feature.md +17 -8
  79. package/dist/skill/docs/define/firewall.md +2 -0
  80. package/dist/skill/docs/define/guards.md +27 -3
  81. package/dist/skill/docs/define/index.md +1 -1
  82. package/dist/skill/docs/define/relationships.md +7 -0
  83. package/dist/skill/docs/define/schema.md +44 -14
  84. package/dist/skill/docs/define/security.md +1 -1
  85. package/dist/skill/docs/define/transitions.md +35 -4
  86. package/dist/skill/docs/define/triggers.md +14 -3
  87. package/dist/skill/docs/define/views.md +33 -0
  88. package/dist/skill/docs/index.md +2 -2
  89. package/dist/skill/docs/platform/auth/api-keys.md +2 -2
  90. package/dist/skill/docs/platform/auth/using-auth.md +37 -0
  91. package/dist/skill/docs/platform/database/d1.md +15 -3
  92. package/dist/skill/docs/platform/database/neon.md +4 -4
  93. package/dist/skill/docs/platform/email/index.md +1 -1
  94. package/dist/skill/docs/platform/queues/handlers.md +1 -1
  95. package/dist/skill/docs/platform/queues/using-queues.md +1 -1
  96. package/dist/skill/docs/platform/realtime/using-realtime.md +6 -4
  97. package/dist/skill/docs/platform/schedules/index.md +1 -1
  98. package/dist/skill/docs/platform/storage/index.md +3 -3
  99. package/dist/skill/docs/platform/storage/r2.md +87 -37
  100. package/dist/skill/docs/platform/storage/using-r2.md +99 -19
  101. package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
  102. package/dist/skill/docs/start/deploy-browser.md +40 -45
  103. package/dist/skill/docs/start/deploy-owner-access.md +60 -52
  104. package/dist/skill/docs/start/deploy.md +4 -4
  105. package/dist/skill/docs/start/first-api.md +2 -2
  106. package/dist/skill/docs/start/hand-crafted.md +3 -3
  107. package/dist/skill/docs/start/index.md +3 -3
  108. package/dist/skill/docs/start/patterns.md +17 -2
  109. package/dist/skill/docs/start/quickstart.md +3 -3
  110. package/dist/skill/docs/start/template-blog.md +2 -2
  111. package/dist/skill/docs/start/template-cloudflare.md +3 -3
  112. package/dist/skill/docs/start/template-empty.md +1 -1
  113. package/dist/skill/docs/start/templates.md +1 -1
  114. package/dist/skill/docs/tooling/claude-skill.md +1 -1
  115. package/dist/skill/docs/tooling/cli.md +21 -16
  116. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
  117. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  118. package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
  119. package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  120. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
  121. package/dist/skill/docs/tooling/output.md +23 -2
  122. package/dist/skill/docs/tooling/troubleshooting.md +1 -1
  123. package/dist/skill/docs/ui/account/customization.md +1 -1
  124. package/dist/skill/docs/ui/account/environment-variables.md +2 -2
  125. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  126. package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
  127. package/dist/skill/docs/ui/account/features/avatars.md +24 -8
  128. package/dist/skill/docs/ui/account/features/index.md +16 -11
  129. package/dist/skill/docs/ui/account/features/organizations.md +3 -2
  130. package/dist/skill/docs/ui/account/hooks.md +2 -0
  131. package/dist/skill/docs/ui/account/index.md +10 -5
  132. package/dist/skill/docs/ui/account/with-quickback.md +2 -2
  133. package/dist/skill/docs/ui/admin/actions.md +97 -3
  134. package/dist/skill/docs/ui/admin/components.md +4 -6
  135. package/dist/skill/docs/ui/admin/connecting.md +15 -3
  136. package/dist/skill/docs/ui/admin/index.md +71 -6
  137. package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
  138. package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
  139. package/dist/skill/docs/ui/admin/schema-format.md +39 -2
  140. package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
  141. package/dist/skill/docs/ui/admin/security.md +19 -4
  142. package/dist/skill/docs/ui/admin/table-views.md +59 -12
  143. package/package.json +1 -1
  144. package/src/cursor/quickback.mdc +1 -1
  145. package/src/skill/SKILL.md +24 -9
  146. package/src/skill/docs/api/crud.md +7 -0
  147. package/src/skill/docs/api/index.md +1 -1
  148. package/src/skill/docs/api/openapi.md +1 -1
  149. package/src/skill/docs/changelog/index.md +27 -1
  150. package/src/skill/docs/configure/agents.md +1 -1
  151. package/src/skill/docs/configure/domains.md +1 -1
  152. package/src/skill/docs/configure/index.md +11 -5
  153. package/src/skill/docs/configure/providers.md +6 -3
  154. package/src/skill/docs/configure/single-tenant.md +7 -3
  155. package/src/skill/docs/configure/variables.md +3 -3
  156. package/src/skill/docs/define/access.md +10 -0
  157. package/src/skill/docs/define/actions/defining.md +35 -7
  158. package/src/skill/docs/define/actions/index.md +1 -1
  159. package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
  160. package/src/skill/docs/define/actions/scoped-db.md +68 -21
  161. package/src/skill/docs/define/areas.md +1 -1
  162. package/src/skill/docs/define/diagnostics.md +1 -0
  163. package/src/skill/docs/define/encryption.md +1 -1
  164. package/src/skill/docs/define/feature.md +17 -8
  165. package/src/skill/docs/define/firewall.md +2 -0
  166. package/src/skill/docs/define/guards.md +27 -3
  167. package/src/skill/docs/define/index.md +1 -1
  168. package/src/skill/docs/define/relationships.md +7 -0
  169. package/src/skill/docs/define/schema.md +44 -14
  170. package/src/skill/docs/define/security.md +1 -1
  171. package/src/skill/docs/define/transitions.md +35 -4
  172. package/src/skill/docs/define/triggers.md +14 -3
  173. package/src/skill/docs/define/views.md +33 -0
  174. package/src/skill/docs/index.md +2 -2
  175. package/src/skill/docs/platform/auth/api-keys.md +2 -2
  176. package/src/skill/docs/platform/auth/using-auth.md +37 -0
  177. package/src/skill/docs/platform/database/d1.md +15 -3
  178. package/src/skill/docs/platform/database/neon.md +4 -4
  179. package/src/skill/docs/platform/email/index.md +1 -1
  180. package/src/skill/docs/platform/queues/handlers.md +1 -1
  181. package/src/skill/docs/platform/queues/using-queues.md +1 -1
  182. package/src/skill/docs/platform/realtime/using-realtime.md +6 -4
  183. package/src/skill/docs/platform/schedules/index.md +1 -1
  184. package/src/skill/docs/platform/storage/index.md +3 -3
  185. package/src/skill/docs/platform/storage/r2.md +87 -37
  186. package/src/skill/docs/platform/storage/using-r2.md +99 -19
  187. package/src/skill/docs/platform/webhooks/inbound.md +40 -0
  188. package/src/skill/docs/start/deploy-browser.md +40 -45
  189. package/src/skill/docs/start/deploy-owner-access.md +60 -52
  190. package/src/skill/docs/start/deploy.md +4 -4
  191. package/src/skill/docs/start/first-api.md +2 -2
  192. package/src/skill/docs/start/hand-crafted.md +3 -3
  193. package/src/skill/docs/start/index.md +3 -3
  194. package/src/skill/docs/start/patterns.md +17 -2
  195. package/src/skill/docs/start/quickstart.md +3 -3
  196. package/src/skill/docs/start/template-blog.md +2 -2
  197. package/src/skill/docs/start/template-cloudflare.md +3 -3
  198. package/src/skill/docs/start/template-empty.md +1 -1
  199. package/src/skill/docs/start/templates.md +1 -1
  200. package/src/skill/docs/tooling/claude-skill.md +1 -1
  201. package/src/skill/docs/tooling/cli.md +21 -16
  202. package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
  203. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  204. package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
  205. package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  206. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
  207. package/src/skill/docs/tooling/output.md +23 -2
  208. package/src/skill/docs/tooling/troubleshooting.md +1 -1
  209. package/src/skill/docs/ui/account/customization.md +1 -1
  210. package/src/skill/docs/ui/account/environment-variables.md +2 -2
  211. package/src/skill/docs/ui/account/features/admin.md +1 -1
  212. package/src/skill/docs/ui/account/features/api-keys.md +10 -8
  213. package/src/skill/docs/ui/account/features/avatars.md +24 -8
  214. package/src/skill/docs/ui/account/features/index.md +16 -11
  215. package/src/skill/docs/ui/account/features/organizations.md +3 -2
  216. package/src/skill/docs/ui/account/hooks.md +2 -0
  217. package/src/skill/docs/ui/account/index.md +10 -5
  218. package/src/skill/docs/ui/account/with-quickback.md +2 -2
  219. package/src/skill/docs/ui/admin/actions.md +97 -3
  220. package/src/skill/docs/ui/admin/components.md +4 -6
  221. package/src/skill/docs/ui/admin/connecting.md +15 -3
  222. package/src/skill/docs/ui/admin/index.md +71 -6
  223. package/src/skill/docs/ui/admin/inline-editing.md +38 -4
  224. package/src/skill/docs/ui/admin/record-layouts.md +22 -21
  225. package/src/skill/docs/ui/admin/schema-format.md +39 -2
  226. package/src/skill/docs/ui/admin/schema-registry.md +107 -7
  227. package/src/skill/docs/ui/admin/security.md +19 -4
  228. 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
- This is the recommended path for most apps and the lightest way to add
13
- uploads — see [Presigned uploads](#presigned-uploads-recommended).
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 public files worker for serving. Opt in only when you
17
- want buckets/objects handled for you instead of bringing your own media table.
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`, so the
28
- only setup is `wrangler r2 bucket create <name>` once plus the R2 API-token
29
- secrets. Existing projects set `bucketName` to a bucket they already have.
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; for the default
32
- presign-only path jump to [Presigned uploads](#presigned-uploads-recommended).
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 — prefer the
122
- > **presigned** path. The bytes go straight to R2, so you skip the Worker's
123
- > request-body cap and don't burn Worker CPU streaming the upload. See
124
- > [Presigned uploads](#presigned-uploads-recommended) below.
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": "avatars",
144
- "readScope": "organization",
182
+ "name": "listings",
183
+ "readScope": "public",
145
184
  "writeScope": "organization",
146
- "readRoles": ["admin", "member"],
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 can read | N/A |
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": "organization"
265
+ "readScope": "public"
226
266
  }
227
267
  ```
228
268
 
229
- ## Presigned uploads (recommended)
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
- Streaming bytes through the Worker (`POST /object`) is fine for small files, but
232
- it puts every byte on the Worker's request path — subject to the body-size cap,
233
- and billed as Worker CPU/duration. For media (video, audio, large PDFs), use a
234
- **presigned URL**: the Worker runs all the access checks and hands back a
235
- short-lived URL the client uploads to **directly**. The bytes never touch your
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 Files
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/avatars/logo.png
373
+ https://files.yourdomain.com/public/org_abc/listings/3f2a…-hero.jpg
330
374
  ```
331
375
 
332
- No authentication required.
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
- ### Private Files
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** (only if you use presigned uploads — see
404
- [Presigned uploads](#presigned-uploads-recommended)):
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 middleware, org check, role check)
446
- - **Serve security**: Enforced by files worker (session validation, metadata RBAC)
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
- Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.
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
- By default `defineFileStorage("cloudflare-r2")` is **presign-only**: you get the
6
- `ctx.storage` signer and nothing else. The `/storage/v1/*` endpoints shown
7
- further down only exist in the [managed subsystem](/platform/storage/r2#two-modes)
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
- ## Upload Flow (default — `ctx.storage`)
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
- Write a normal `defineAction` that signs a presigned URL and stores the key in
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. See [R2 Setup → Presigned uploads](/platform/storage/r2#presigned-uploads-recommended).
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
- ## Upload Flow (managed mode — `/storage/v1/*`)
129
+ ### Managed presign endpoints
54
130
 
55
131
  With `managed: true`, the generated API also exposes turnkey presigned
56
- endpoints backed by the FILES_DB metadata system:
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
- In **presign-only** mode, mint a short-lived download URL with
76
- `storage.signGetUrl(key, { downloadFilename })` from your action and hand it to
77
- the client — the bytes come straight from R2.
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
- In **managed** mode, files are also served through the worker with security
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 access respects the same security layers as your API:
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
- - **Firewall** — Users can only access files belonging to their organization
99
- - **Access** — Role-based download permissions
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) — Bucket creation, wrangler bindings, and configuration
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
- Build a backend in [Quickback Start](https://start.quickback.dev), get a green compile, and ship it to **your own Cloudflare account** with one click — databases created, migrations applied, secrets minted, Worker live on a `workers.dev` URL. No local tooling required.
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
- When you click **Deploy this app**, the pipeline runs four phases and reports each one:
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. **Compile** — your project compiles on the hosted compiler and emits a *deployment manifest*: the exact set of resources, migrations, and secrets the deploy will touch. Anything the browser flow can't deploy fails **here**, with a named reason — never as a half-deployed app.
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. **Package** — the project recompiles with the real resource ids folded in and is bundled into Worker modules (plus your CMS/Account SPA assets, when enabled). Every byte is hash-verified against the manifest before anything is uploaded.
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 compilation.
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 card's **Worker name** field seeds itself from your project's `name` and decides what the deploy is called. It appears as soon as your project compiles green — before you connect Cloudflare — so naming the app isn't gated behind an OAuth round trip. That single name drives the Worker **and** every resource derived from it — `<name>-auth`, `<name>-features`, and any audit, webhook, or file-metadata databases your features pull in.
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
- Start remembers the name per chat, so redeploying the same conversation updates the same app in place. Editing 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.
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. The field normalizes as you type and blocks the deploy rather than letting the broker reject the name a minute in.
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
- Deploying takes two distinct grants, and the card labels them differently on purpose:
84
+ Building and deploying use two deliberately separate identities:
73
85
 
74
- - **Continue with Cloudflare** signs you in to Quickback. Identity only — none of the deploy permissions below.
75
- - **Grant deploy access** gives Quickback permission to deploy into your Cloudflare account — 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).
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
- One click covers both: if you weren't signed in yet, sign-in chains straight into the deploy consent. First-time users see two Cloudflare screens back to back; after that, Cloudflare skips consent screens it has already approved, so re-authenticating is a ribbon of silent redirects.
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 the card explaining what happened and a **Try again** button. Nothing is stored on a cancelled attempt, and a connection you already had is left untouched.
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
- The deploy card is the whole connection UI: it reports the state of your Cloudflare connection and offers exactly one thing to do about it.
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…" | Signed in, but no deploy permission stored yet | **Grant deploy access** |
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 claim links all keep working. Reconnecting is also how you widen a grant that's missing a permission.
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 the card grows a login picker above the account picker. Start remembers which one you deployed with last and preselects it.
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
- To make every Cloudflare login land on the **same** Quickback account (rather than each minting its own), link them under **Connected accounts** in the [Account UI](/ui/account) — after that, "Continue with Cloudflare" signs you in to that one account no matter which Cloudflare identity your dashboard is holding.
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 the card) 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.
129
- - **Revoke** (Cloudflare dashboard → **My Profile → Access Management → Connected Applications**, linked from the card) withdraws the grant itself. The stored ciphertext becomes useless immediately; the next thing Start tries turns into a reconnect prompt.
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 the card turns the next failed call into a reconnect prompt. See [Connection states and recovery](#connection-states-and-recovery) for the full set.
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
- Start keeps a chip above the composer naming the app this chat deployed, with links straight into its CMS, Account UI, and API. It is read from local storage rather than the deploy card's live state, so it survives a reload — refreshing no longer loses the way back to your app.
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 needs `user.role === "appmanager"`, which your first deploy seeds for you — see [Owner access](/start/deploy-owner-access).
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, and you can take over management with the CLI at any time — download the project from Start and `quickback deploy` picks up the same resources.
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