@quickback-dev/cli 0.66.1 → 0.66.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) 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 +804 -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/skill/SKILL.md +6 -6
  55. package/dist/skill/docs/api/actions.md +27 -3
  56. package/dist/skill/docs/api/batch-operations.md +4 -0
  57. package/dist/skill/docs/api/crud.md +64 -0
  58. package/dist/skill/docs/api/index.md +1 -1
  59. package/dist/skill/docs/api/openapi.md +1 -1
  60. package/dist/skill/docs/api/query-params.md +19 -2
  61. package/dist/skill/docs/changelog/index.md +33 -1
  62. package/dist/skill/docs/configure/agents.md +1 -1
  63. package/dist/skill/docs/configure/index.md +8 -3
  64. package/dist/skill/docs/configure/providers.md +3 -0
  65. package/dist/skill/docs/configure/variables.md +3 -3
  66. package/dist/skill/docs/define/access.md +7 -0
  67. package/dist/skill/docs/define/actions/defining.md +39 -8
  68. package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
  69. package/dist/skill/docs/define/actions/scoped-db.md +46 -16
  70. package/dist/skill/docs/define/areas.md +1 -1
  71. package/dist/skill/docs/define/diagnostics.md +1 -0
  72. package/dist/skill/docs/define/encryption.md +1 -1
  73. package/dist/skill/docs/define/feature.md +14 -7
  74. package/dist/skill/docs/define/guards.md +34 -3
  75. package/dist/skill/docs/define/schema.md +29 -17
  76. package/dist/skill/docs/define/security.md +1 -1
  77. package/dist/skill/docs/define/transitions.md +35 -4
  78. package/dist/skill/docs/define/views.md +33 -0
  79. package/dist/skill/docs/index.md +2 -2
  80. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  81. package/dist/skill/docs/platform/auth/using-auth.md +37 -0
  82. package/dist/skill/docs/platform/database/d1.md +2 -2
  83. package/dist/skill/docs/platform/database/neon.md +4 -4
  84. package/dist/skill/docs/platform/email/index.md +1 -1
  85. package/dist/skill/docs/platform/queues/handlers.md +1 -1
  86. package/dist/skill/docs/platform/queues/using-queues.md +1 -1
  87. package/dist/skill/docs/platform/schedules/index.md +1 -1
  88. package/dist/skill/docs/platform/storage/index.md +3 -3
  89. package/dist/skill/docs/platform/storage/r2.md +87 -37
  90. package/dist/skill/docs/platform/storage/using-r2.md +99 -19
  91. package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
  92. package/dist/skill/docs/start/deploy-browser.md +39 -44
  93. package/dist/skill/docs/start/deploy-owner-access.md +28 -19
  94. package/dist/skill/docs/start/deploy.md +2 -2
  95. package/dist/skill/docs/start/first-api.md +1 -1
  96. package/dist/skill/docs/start/hand-crafted.md +3 -3
  97. package/dist/skill/docs/start/index.md +3 -3
  98. package/dist/skill/docs/start/quickstart.md +3 -3
  99. package/dist/skill/docs/start/template-blog.md +2 -2
  100. package/dist/skill/docs/start/template-cloudflare.md +2 -2
  101. package/dist/skill/docs/start/template-empty.md +1 -1
  102. package/dist/skill/docs/start/templates.md +1 -1
  103. package/dist/skill/docs/tooling/claude-skill.md +1 -1
  104. package/dist/skill/docs/tooling/cli.md +40 -19
  105. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  106. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  107. package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
  108. package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  109. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  110. package/dist/skill/docs/tooling/output.md +32 -2
  111. package/dist/skill/docs/tooling/troubleshooting.md +1 -1
  112. package/dist/skill/docs/ui/account/environment-variables.md +2 -2
  113. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  114. package/dist/skill/docs/ui/account/features/avatars.md +24 -8
  115. package/dist/skill/docs/ui/account/features/index.md +9 -5
  116. package/dist/skill/docs/ui/account/features/organizations.md +3 -2
  117. package/dist/skill/docs/ui/account/index.md +3 -1
  118. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  119. package/dist/skill/docs/ui/admin/actions.md +97 -3
  120. package/dist/skill/docs/ui/admin/components.md +4 -6
  121. package/dist/skill/docs/ui/admin/connecting.md +15 -3
  122. package/dist/skill/docs/ui/admin/index.md +71 -6
  123. package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
  124. package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
  125. package/dist/skill/docs/ui/admin/schema-format.md +39 -2
  126. package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
  127. package/dist/skill/docs/ui/admin/security.md +19 -4
  128. package/dist/skill/docs/ui/admin/table-views.md +59 -12
  129. package/package.json +1 -1
  130. package/src/cursor/quickback.mdc +1 -1
  131. package/src/skill/SKILL.md +6 -6
  132. package/src/skill/docs/api/actions.md +27 -3
  133. package/src/skill/docs/api/batch-operations.md +4 -0
  134. package/src/skill/docs/api/crud.md +64 -0
  135. package/src/skill/docs/api/index.md +1 -1
  136. package/src/skill/docs/api/openapi.md +1 -1
  137. package/src/skill/docs/api/query-params.md +19 -2
  138. package/src/skill/docs/changelog/index.md +33 -1
  139. package/src/skill/docs/configure/agents.md +1 -1
  140. package/src/skill/docs/configure/index.md +8 -3
  141. package/src/skill/docs/configure/providers.md +3 -0
  142. package/src/skill/docs/configure/variables.md +3 -3
  143. package/src/skill/docs/define/access.md +7 -0
  144. package/src/skill/docs/define/actions/defining.md +39 -8
  145. package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
  146. package/src/skill/docs/define/actions/scoped-db.md +46 -16
  147. package/src/skill/docs/define/areas.md +1 -1
  148. package/src/skill/docs/define/diagnostics.md +1 -0
  149. package/src/skill/docs/define/encryption.md +1 -1
  150. package/src/skill/docs/define/feature.md +14 -7
  151. package/src/skill/docs/define/guards.md +34 -3
  152. package/src/skill/docs/define/schema.md +29 -17
  153. package/src/skill/docs/define/security.md +1 -1
  154. package/src/skill/docs/define/transitions.md +35 -4
  155. package/src/skill/docs/define/views.md +33 -0
  156. package/src/skill/docs/index.md +2 -2
  157. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  158. package/src/skill/docs/platform/auth/using-auth.md +37 -0
  159. package/src/skill/docs/platform/database/d1.md +2 -2
  160. package/src/skill/docs/platform/database/neon.md +4 -4
  161. package/src/skill/docs/platform/email/index.md +1 -1
  162. package/src/skill/docs/platform/queues/handlers.md +1 -1
  163. package/src/skill/docs/platform/queues/using-queues.md +1 -1
  164. package/src/skill/docs/platform/schedules/index.md +1 -1
  165. package/src/skill/docs/platform/storage/index.md +3 -3
  166. package/src/skill/docs/platform/storage/r2.md +87 -37
  167. package/src/skill/docs/platform/storage/using-r2.md +99 -19
  168. package/src/skill/docs/platform/webhooks/inbound.md +40 -0
  169. package/src/skill/docs/start/deploy-browser.md +39 -44
  170. package/src/skill/docs/start/deploy-owner-access.md +28 -19
  171. package/src/skill/docs/start/deploy.md +2 -2
  172. package/src/skill/docs/start/first-api.md +1 -1
  173. package/src/skill/docs/start/hand-crafted.md +3 -3
  174. package/src/skill/docs/start/index.md +3 -3
  175. package/src/skill/docs/start/quickstart.md +3 -3
  176. package/src/skill/docs/start/template-blog.md +2 -2
  177. package/src/skill/docs/start/template-cloudflare.md +2 -2
  178. package/src/skill/docs/start/template-empty.md +1 -1
  179. package/src/skill/docs/start/templates.md +1 -1
  180. package/src/skill/docs/tooling/claude-skill.md +1 -1
  181. package/src/skill/docs/tooling/cli.md +40 -19
  182. package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  183. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  184. package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
  185. package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  186. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  187. package/src/skill/docs/tooling/output.md +32 -2
  188. package/src/skill/docs/tooling/troubleshooting.md +1 -1
  189. package/src/skill/docs/ui/account/environment-variables.md +2 -2
  190. package/src/skill/docs/ui/account/features/admin.md +1 -1
  191. package/src/skill/docs/ui/account/features/avatars.md +24 -8
  192. package/src/skill/docs/ui/account/features/index.md +9 -5
  193. package/src/skill/docs/ui/account/features/organizations.md +3 -2
  194. package/src/skill/docs/ui/account/index.md +3 -1
  195. package/src/skill/docs/ui/account/with-quickback.md +1 -1
  196. package/src/skill/docs/ui/admin/actions.md +97 -3
  197. package/src/skill/docs/ui/admin/components.md +4 -6
  198. package/src/skill/docs/ui/admin/connecting.md +15 -3
  199. package/src/skill/docs/ui/admin/index.md +71 -6
  200. package/src/skill/docs/ui/admin/inline-editing.md +38 -4
  201. package/src/skill/docs/ui/admin/record-layouts.md +22 -21
  202. package/src/skill/docs/ui/admin/schema-format.md +39 -2
  203. package/src/skill/docs/ui/admin/schema-registry.md +107 -7
  204. package/src/skill/docs/ui/admin/security.md +19 -4
  205. package/src/skill/docs/ui/admin/table-views.md +59 -12
@@ -290,7 +290,7 @@ After defining queue handlers:
290
290
 
291
291
  2. **Compile:**
292
292
  ```bash
293
- quickback compile
293
+ quickback build
294
294
  ```
295
295
 
296
296
  3. **Deploy:**
@@ -148,7 +148,7 @@ wrangler queues create my-app-processing-queue
148
148
  ### 2. Compile and Deploy
149
149
 
150
150
  ```bash
151
- quickback compile
151
+ quickback build
152
152
  wrangler deploy
153
153
  ```
154
154
 
@@ -41,7 +41,7 @@ Two `../` — up from `services/schedules/` to `quickback/`, then down into `fea
41
41
 
42
42
  1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
43
43
  2. **`[triggers] crons = [...]`** in `wrangler.toml` — one deduped, sorted list across all schedules.
44
- 3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback compile`, so there's nothing to hand-maintain.
44
+ 3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback build`, so there's nothing to hand-maintain.
45
45
 
46
46
  ## Execute context
47
47
 
@@ -7,11 +7,11 @@ The Quickback Stack uses Cloudflare's storage primitives for different use cases
7
7
  | Service | Use Case | Pages |
8
8
  |---------|----------|-------|
9
9
  | **KV** | Sessions, caching, rate limiting | [Setup](/platform/storage/kv) · [Usage](/platform/storage/using-kv) |
10
- | **R2** | File uploads, avatars, attachments | [Setup](/platform/storage/r2) · [Usage](/platform/storage/using-r2) |
10
+ | **R2** | Hosted file bytes (listing photos, avatars, attachments) | [Setup](/platform/storage/r2) · [Usage](/platform/storage/using-r2) |
11
11
 
12
12
  ## Getting Started
13
13
 
14
14
  - **[KV Setup](/platform/storage/kv)** — Namespace and bindings configuration
15
15
  - **[Using KV](/platform/storage/using-kv)** — Sessions, caching, rate limiting
16
- - **[R2 Setup](/platform/storage/r2)** — Bucket, bindings, CORS configuration
17
- - **[Using R2](/platform/storage/using-r2)** — Uploads, downloads, role-based access
16
+ - **[R2 Setup](/platform/storage/r2)** — Public vs signed reads, buckets, bindings
17
+ - **[Using R2](/platform/storage/using-r2)** — URL fields, public buckets, signed uploads
@@ -9,12 +9,12 @@ Quickback provides built-in file storage using Cloudflare R2.
9
9
  - **Presign-only (default)** — emits just the `ctx.storage` signer (presigned
10
10
  PUT/GET URLs straight to R2). **No new D1, no `/storage/v1/*` endpoints, no
11
11
  files worker.** You compute keys and store file references in your own table.
12
- 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.