@quickback-dev/cli 0.70.45 → 0.72.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 (232) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +10 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/deploy.d.ts.map +1 -1
  5. package/dist/commands/deploy.js +7 -1
  6. package/dist/commands/deploy.js.map +1 -1
  7. package/dist/commands/mcp.d.ts.map +1 -1
  8. package/dist/commands/mcp.js +6 -5
  9. package/dist/commands/mcp.js.map +1 -1
  10. package/dist/index.js +1 -1
  11. package/dist/index.js.map +1 -1
  12. package/dist/lib/access-manifest-diff.d.ts +6 -0
  13. package/dist/lib/access-manifest-diff.d.ts.map +1 -1
  14. package/dist/lib/access-manifest-diff.js +10 -0
  15. package/dist/lib/access-manifest-diff.js.map +1 -1
  16. package/dist/lib/action-harvest.d.ts.map +1 -1
  17. package/dist/lib/action-harvest.js +36 -0
  18. package/dist/lib/action-harvest.js.map +1 -1
  19. package/dist/lib/api-client.d.ts +8 -0
  20. package/dist/lib/api-client.d.ts.map +1 -1
  21. package/dist/lib/api-client.js.map +1 -1
  22. package/dist/lib/deployment-target.d.ts +13 -0
  23. package/dist/lib/deployment-target.d.ts.map +1 -1
  24. package/dist/lib/deployment-target.js +4 -0
  25. package/dist/lib/deployment-target.js.map +1 -1
  26. package/dist/lib/file-loader.d.ts +22 -0
  27. package/dist/lib/file-loader.d.ts.map +1 -1
  28. package/dist/lib/file-loader.js +80 -18
  29. package/dist/lib/file-loader.js.map +1 -1
  30. package/dist/lib/file-writer.js +9 -0
  31. package/dist/lib/file-writer.js.map +1 -1
  32. package/dist/lib/harness.d.ts +10 -0
  33. package/dist/lib/harness.d.ts.map +1 -1
  34. package/dist/lib/harness.js +31 -0
  35. package/dist/lib/harness.js.map +1 -1
  36. package/dist/lib/migrations/executor.js +5 -1
  37. package/dist/lib/migrations/executor.js.map +1 -1
  38. package/dist/lib/migrations/plan.js +3 -0
  39. package/dist/lib/migrations/plan.js.map +1 -1
  40. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  41. package/dist/lib/migrations/postprocessors/index.js +23 -2
  42. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  43. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
  44. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
  45. package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
  46. package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
  47. package/dist/lib/migrations/prior-state.d.ts +13 -1
  48. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  49. package/dist/lib/migrations/prior-state.js +33 -2
  50. package/dist/lib/migrations/prior-state.js.map +1 -1
  51. package/dist/lib/migrations/types.d.ts +2 -2
  52. package/dist/lib/migrations/types.d.ts.map +1 -1
  53. package/dist/lib/migrations/types.js +3 -0
  54. package/dist/lib/migrations/types.js.map +1 -1
  55. package/dist/lib/wrangler-resources.d.ts +14 -1
  56. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  57. package/dist/lib/wrangler-resources.js +29 -7
  58. package/dist/lib/wrangler-resources.js.map +1 -1
  59. package/dist/skill/SKILL.md +64 -0
  60. package/dist/skill/docs/api/actions.md +73 -2
  61. package/dist/skill/docs/api/batch-operations.md +2 -0
  62. package/dist/skill/docs/api/caching.md +2 -2
  63. package/dist/skill/docs/api/crud.md +13 -0
  64. package/dist/skill/docs/api/errors.md +111 -10
  65. package/dist/skill/docs/api/index.md +24 -0
  66. package/dist/skill/docs/api/openapi.md +8 -0
  67. package/dist/skill/docs/api/query-params.md +6 -0
  68. package/dist/skill/docs/configure/agents.md +73 -1
  69. package/dist/skill/docs/configure/auth.md +7 -1
  70. package/dist/skill/docs/configure/bindings.md +55 -0
  71. package/dist/skill/docs/configure/cloudflare-access.md +191 -0
  72. package/dist/skill/docs/configure/domains.md +1 -1
  73. package/dist/skill/docs/configure/index.md +4 -2
  74. package/dist/skill/docs/configure/providers.md +2 -1
  75. package/dist/skill/docs/configure/tenancy.md +3 -0
  76. package/dist/skill/docs/configure/tenant-databases.md +2407 -0
  77. package/dist/skill/docs/define/access.md +33 -1
  78. package/dist/skill/docs/define/actions/defining.md +118 -1
  79. package/dist/skill/docs/define/actions/scoped-db.md +32 -8
  80. package/dist/skill/docs/define/areas.md +145 -2
  81. package/dist/skill/docs/define/diagnostics.md +160 -21
  82. package/dist/skill/docs/define/encryption.md +13 -2
  83. package/dist/skill/docs/define/fga.md +320 -42
  84. package/dist/skill/docs/define/firewall.md +4 -0
  85. package/dist/skill/docs/define/index.md +1 -0
  86. package/dist/skill/docs/define/read.md +46 -5
  87. package/dist/skill/docs/define/relationships.md +30 -12
  88. package/dist/skill/docs/define/schema.md +2 -0
  89. package/dist/skill/docs/define/scopes.md +393 -9
  90. package/dist/skill/docs/define/sealed-protocol.md +67 -12
  91. package/dist/skill/docs/define/transitions.md +4 -1
  92. package/dist/skill/docs/define/triggers.md +55 -1
  93. package/dist/skill/docs/platform/api-contract/index.md +9 -3
  94. package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
  95. package/dist/skill/docs/platform/auth/using-auth.md +1 -1
  96. package/dist/skill/docs/platform/database/d1.md +112 -3
  97. package/dist/skill/docs/platform/database/data-migrations.md +3 -1
  98. package/dist/skill/docs/platform/database/neon.md +10 -2
  99. package/dist/skill/docs/platform/queues/handlers.md +48 -16
  100. package/dist/skill/docs/platform/queues/using-queues.md +16 -0
  101. package/dist/skill/docs/platform/realtime/durable-objects.md +294 -17
  102. package/dist/skill/docs/platform/realtime/index.md +9 -6
  103. package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
  104. package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
  105. package/dist/skill/docs/platform/schedules/index.md +1 -1
  106. package/dist/skill/docs/platform/storage/r2.md +10 -1
  107. package/dist/skill/docs/platform/storage/using-r2.md +42 -1
  108. package/dist/skill/docs/tooling/output.md +9 -2
  109. package/dist/skill/docs/ui/account/features/admin.md +5 -3
  110. package/dist/skill/docs/ui/account/hooks.md +9 -2
  111. package/dist/skill/docs/ui/admin/connecting.md +3 -3
  112. package/dist/skill/docs/ui/admin/index.md +1 -1
  113. package/package.json +1 -1
  114. package/src/skill/SKILL.md +64 -0
  115. package/src/skill/docs/api/actions.md +73 -2
  116. package/src/skill/docs/api/batch-operations.md +2 -0
  117. package/src/skill/docs/api/caching.md +2 -2
  118. package/src/skill/docs/api/crud.md +13 -0
  119. package/src/skill/docs/api/errors.md +111 -10
  120. package/src/skill/docs/api/index.md +24 -0
  121. package/src/skill/docs/api/openapi.md +8 -0
  122. package/src/skill/docs/api/query-params.md +6 -0
  123. package/src/skill/docs/configure/agents.md +73 -1
  124. package/src/skill/docs/configure/auth.md +7 -1
  125. package/src/skill/docs/configure/bindings.md +55 -0
  126. package/src/skill/docs/configure/cloudflare-access.md +191 -0
  127. package/src/skill/docs/configure/domains.md +1 -1
  128. package/src/skill/docs/configure/index.md +4 -2
  129. package/src/skill/docs/configure/providers.md +2 -1
  130. package/src/skill/docs/configure/tenancy.md +3 -0
  131. package/src/skill/docs/configure/tenant-databases.md +2407 -0
  132. package/src/skill/docs/define/access.md +33 -1
  133. package/src/skill/docs/define/actions/defining.md +118 -1
  134. package/src/skill/docs/define/actions/scoped-db.md +32 -8
  135. package/src/skill/docs/define/areas.md +145 -2
  136. package/src/skill/docs/define/diagnostics.md +160 -21
  137. package/src/skill/docs/define/encryption.md +13 -2
  138. package/src/skill/docs/define/fga.md +320 -42
  139. package/src/skill/docs/define/firewall.md +4 -0
  140. package/src/skill/docs/define/index.md +1 -0
  141. package/src/skill/docs/define/read.md +46 -5
  142. package/src/skill/docs/define/relationships.md +30 -12
  143. package/src/skill/docs/define/schema.md +2 -0
  144. package/src/skill/docs/define/scopes.md +393 -9
  145. package/src/skill/docs/define/sealed-protocol.md +67 -12
  146. package/src/skill/docs/define/transitions.md +4 -1
  147. package/src/skill/docs/define/triggers.md +55 -1
  148. package/src/skill/docs/platform/api-contract/index.md +9 -3
  149. package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
  150. package/src/skill/docs/platform/auth/using-auth.md +1 -1
  151. package/src/skill/docs/platform/database/d1.md +112 -3
  152. package/src/skill/docs/platform/database/data-migrations.md +3 -1
  153. package/src/skill/docs/platform/database/neon.md +10 -2
  154. package/src/skill/docs/platform/queues/handlers.md +48 -16
  155. package/src/skill/docs/platform/queues/using-queues.md +16 -0
  156. package/src/skill/docs/platform/realtime/durable-objects.md +294 -17
  157. package/src/skill/docs/platform/realtime/index.md +9 -6
  158. package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
  159. package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
  160. package/src/skill/docs/platform/schedules/index.md +1 -1
  161. package/src/skill/docs/platform/storage/r2.md +10 -1
  162. package/src/skill/docs/platform/storage/using-r2.md +42 -1
  163. package/src/skill/docs/tooling/output.md +9 -2
  164. package/src/skill/docs/ui/account/features/admin.md +5 -3
  165. package/src/skill/docs/ui/account/hooks.md +9 -2
  166. package/src/skill/docs/ui/admin/connecting.md +3 -3
  167. package/src/skill/docs/ui/admin/index.md +1 -1
  168. package/dist/codex/AGENTS.md +0 -290
  169. package/dist/commands/build.test.d.ts.map +0 -1
  170. package/dist/commands/codex.d.ts +0 -16
  171. package/dist/commands/codex.d.ts.map +0 -1
  172. package/dist/commands/codex.js +0 -159
  173. package/dist/commands/codex.js.map +0 -1
  174. package/dist/commands/compile.d.ts +0 -62
  175. package/dist/commands/compile.d.ts.map +0 -1
  176. package/dist/commands/compile.js +0 -830
  177. package/dist/commands/compile.js.map +0 -1
  178. package/dist/commands/compile.test.d.ts.map +0 -1
  179. package/dist/commands/init.d.ts +0 -6
  180. package/dist/commands/init.d.ts.map +0 -1
  181. package/dist/commands/init.js +0 -405
  182. package/dist/commands/init.js.map +0 -1
  183. package/dist/commands/migrate.test.d.ts.map +0 -1
  184. package/dist/commands/migrations.test.d.ts.map +0 -1
  185. package/dist/commands/push.test.d.ts.map +0 -1
  186. package/dist/commands/schema.test.d.ts.map +0 -1
  187. package/dist/docs/content.d.ts +0 -7
  188. package/dist/docs/content.d.ts.map +0 -1
  189. package/dist/docs/content.js +0 -672
  190. package/dist/docs/content.js.map +0 -1
  191. package/dist/docs/index.test.d.ts.map +0 -1
  192. package/dist/lib/action-harvest.test.d.ts.map +0 -1
  193. package/dist/lib/api-client.test.d.ts.map +0 -1
  194. package/dist/lib/artifact-routing.test.d.ts.map +0 -1
  195. package/dist/lib/auth.test.d.ts.map +0 -1
  196. package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
  197. package/dist/lib/compiler-floor.test.d.ts.map +0 -1
  198. package/dist/lib/config-id-splice.test.d.ts.map +0 -1
  199. package/dist/lib/config-sync.test.d.ts.map +0 -1
  200. package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
  201. package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
  202. package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
  203. package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
  204. package/dist/lib/file-loader.test.d.ts.map +0 -1
  205. package/dist/lib/file-writer.test.d.ts.map +0 -1
  206. package/dist/lib/helpers.d.ts +0 -39
  207. package/dist/lib/helpers.d.ts.map +0 -1
  208. package/dist/lib/helpers.js +0 -299
  209. package/dist/lib/helpers.js.map +0 -1
  210. package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
  211. package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
  212. package/dist/lib/migrations/executor.test.d.ts.map +0 -1
  213. package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
  214. package/dist/lib/migrations/lock.test.d.ts.map +0 -1
  215. package/dist/lib/migrations/paths.test.d.ts.map +0 -1
  216. package/dist/lib/migrations/plan.test.d.ts.map +0 -1
  217. package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
  218. package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
  219. package/dist/lib/migrations/staging.test.d.ts.map +0 -1
  220. package/dist/lib/neon-canary.test.d.ts.map +0 -1
  221. package/dist/lib/neon-target.test.d.ts.map +0 -1
  222. package/dist/lib/neon.test.d.ts.map +0 -1
  223. package/dist/lib/prepare-output.test.d.ts.map +0 -1
  224. package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
  225. package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
  226. package/dist/lib/shell.test.d.ts.map +0 -1
  227. package/dist/lib/sweep-stale.d.ts +0 -25
  228. package/dist/lib/sweep-stale.d.ts.map +0 -1
  229. package/dist/lib/sweep-stale.js +0 -179
  230. package/dist/lib/sweep-stale.js.map +0 -1
  231. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  232. package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
@@ -121,10 +121,22 @@ All routes are `POST`, JSON in/out, mounted at `/seal/v1`, and require an authen
121
121
 
122
122
  `enroll`, `grant`, `rotate`, and `revoke` are gated by **`hasKeyAdminForScope`**:
123
123
 
124
- - `userRole === "sysadmin"` always passes; **or**
125
- - a verified `ctx.scope.seal` claim **for the exact `scopeRef`** carrying a key-admin-tier scoped role (configurable via `encryption.seal.keyAdminRoles`; the literal `"key-admin"` scoped role always qualifies).
126
-
127
- Scoped roles live **only** on `ctx.scope.seal`, never `ctx.roles` — a forged `ctx.roles` entry can't satisfy the gate. There is **no automatic** role→grant: the server holds no key material, so it cannot wrap the scope key to a new reader itself. Instead a reader self-publishes their public key via [`/grant-request`](#10-grant-request--request-access-to-a-scope-any-member) and a key-admin fulfils it via [`/grant`](#7-grant--enroll-a-reader--store-their-wrapped-scope-key-key-admin) — see [role→grant](#rolegrant-readers-request-key-admins-fulfil). Minting the key-admin scope claim is done through the normal [scopes](/define/scopes) machinery — that policy (which role becomes key-admin for which scope) is yours to declare.
124
+ - a verified `ctx.scope.seal` claim with `kind: "admin"`, **for the exact
125
+ `scopeRef`**, carrying a key-admin-tier scoped role (configurable via
126
+ `encryption.seal.keyAdminRoles`; the literal `"key-admin"` scoped role always
127
+ qualifies).
128
+
129
+ There is deliberately **no platform-role bypass**: `sysadmin`, infrastructure
130
+ credentials, and an organization role do not become a seal administrator. The
131
+ application must explicitly decide who may mint the short-lived, exact-scope
132
+ admin claim. Scoped roles live **only** on `ctx.scope.seal`, never `ctx.roles` —
133
+ a forged `ctx.roles` entry can't satisfy the gate. There is **no automatic**
134
+ role→grant: the server holds no key material, so it cannot wrap the scope key to
135
+ a new reader itself. Instead a reader self-publishes their public key via
136
+ [`/grant-request`](#10-grant-request--request-access-to-a-scope-any-member) and
137
+ a key-admin fulfils it via
138
+ [`/grant`](#7-grant--enroll-a-reader--store-their-wrapped-scope-key-key-admin) —
139
+ see [role→grant](#rolegrant-readers-request-key-admins-fulfil).
128
140
 
129
141
  ---
130
142
 
@@ -150,13 +162,19 @@ Trust-on-first-use: **first write wins**, never overwrites. Persists `seal_keys`
150
162
 
151
163
  ### 3. `/challenge` — issue a step-up nonce (any member)
152
164
 
153
- A single-use, **(issuing-user, scopeRef, vaultItemId)-bound** nonce, stored in KV (`expirationTtl` **120 s**). Bound to the item's owning scopeRef so it can only answer a reveal for *that* item; bound to the issuing user so another user can't burn it.
165
+ A single-use, **(issuing-user, scopeRef, vaultItemId)-bound** nonce. The server
166
+ stores only its SHA-256 hash in the features database with a **120 s** expiry;
167
+ consumption is one conditional `DELETE … RETURNING`, so concurrent replays can
168
+ produce only one winner. It is bound to the item's owning scopeRef so it can
169
+ only answer a reveal for *that* item, and to the issuing user so another user
170
+ can't burn it.
154
171
 
155
172
  ```jsonc
156
173
  // → { vaultItemId }
157
174
  // ← { nonce: "<b64url 32B>", scopeRef, vaultItemId, expiresIn: 120 }
158
175
  ```
159
- 503 fail-closed if no KV binding (sealed deployments require it).
176
+ Sealed deployments still require KV for JWT revocation, but raw step-up nonces
177
+ are never stored there.
160
178
 
161
179
  ### 4. `/reveal` — prove step-up, mint a reveal token (reader)
162
180
 
@@ -177,11 +195,21 @@ Verifies the step-up proof, writes a **committed** append-only reveal-log row, t
177
195
  ```
178
196
  Each reveal-log row (`requested` here, `delivered` at `/key`) is also written to the separate security-audit database as an `audit_events` row with `event_kind = 'vault_reveal'`, `action_name = 'vault-reveal:<phase>'`, `resource = 'vault_items'`, `operation = 'reveal' | 'key'`, the actor, org, and `vaultItemId`, and `metadata = { scopeRef, reauthMethod, ip, userAgent }`. No key material and no before-image. The write is fail-closed: if the audit binding is missing or the insert throws, no token is minted and no key is returned. A sealed column therefore always provisions the security-audit pipeline (`AUDIT_DB` on D1, the `audit` schema on Postgres), even with no unsafe actions or hard deletes.
179
197
 
180
- Gates, all fail-closed and in order: **(a)** tenant load, **(b)** any presented `ctx.scope.seal` claim must match the item's scopeRef, **(c)** structural step-up (single-use nonce, bound message), **(d)** `assertGrantLive` (D1 read — owner reveal needs no grant; otherwise a live `seal_key_grant` for the scope, or an audience `vault_grant`).
198
+ Gates, all fail-closed and in order: **(a)** tenant load, **(b)** any presented
199
+ `ctx.scope.seal` claim must be `kind: "reveal"`, carry the `reveal` role, and
200
+ match the item's exact `scopeRef` and `vaultItemId`, **(c)** structural step-up
201
+ (single-use nonce, bound message), **(d)** `assertGrantLive` (a live,
202
+ current-enrollment `seal_key_grant` for the scope, or a version-bound audience
203
+ `vault_grant`). Direct owner access is not an implicit reveal grant.
181
204
 
182
205
  ### 5. `/key` — fetch the wrapped key (bearer the reveal token)
183
206
 
184
- The **separate** post-mint route (never folded into `/reveal`). Re-runs three independent gates — tenant, capability (`ctx.scope.seal` only), `assertGrantLive` (D1, **prior to and independent of** any KV revocation check, which fails *open*) — writes a committed `delivered` reveal-log row, and returns the still-wrapped material.
207
+ The **separate** post-mint route (never folded into `/reveal`). Re-runs three
208
+ independent gates — tenant, exact-item reveal capability (`ctx.scope.seal`
209
+ only), `assertGrantLive` (database read, **prior to and independent of** the KV
210
+ token-revocation check) — and also compares the capability's enrollment version
211
+ and random enrollment revision with the current live grant. It writes a
212
+ committed `delivered` reveal-log row and returns the still-wrapped material.
185
213
 
186
214
  ```jsonc
187
215
  // → { vaultItemId } (Authorization: Bearer <revealToken>)
@@ -196,22 +224,32 @@ For `wrapMethod: "scope"`, the client first unwraps the scope private key with i
196
224
 
197
225
  ```jsonc
198
226
  // → { scopeRef }
199
- // ← { wrappedPrivateKey: "<qbseal envelope>", wrapMethod: "scope" }
227
+ // ← { wrappedPrivateKey: "<qbseal envelope>", wrapMethod: "scope",
228
+ // enrollmentVersion, enrollmentRevision }
200
229
  ```
201
230
 
202
231
  ### 7. `/grant` — enroll a reader + store their wrapped scope key (key-admin)
203
232
 
204
- The combined **enrollment + grant** endpoint. The server **never wraps** — it persists the client-supplied opaque blob. Exactly one live grant per `(scopeRef, userId)` (it revokes any prior live grant first).
233
+ The grant endpoint. The server **never wraps** — it persists the client-supplied
234
+ opaque blob. The user must already have a current framework-owned enrollment;
235
+ the grant copies that enrollment's monotonic version and random revision.
236
+ Exactly one live grant per `(scopeRef, userId)` (it revokes any prior live grant
237
+ first). Replacing enrollment makes every older grant and capability stale even
238
+ if two replacement attempts race on the human-readable version counter.
205
239
 
206
240
  ```jsonc
207
- // → { scopeRef, userId, wrappedPrivateKey: "<qbseal envelope>", wrapMethod: "scope",
241
+ // → { scopeRef, userId, userPublicKey: "<b64url X25519>",
242
+ // wrappedPrivateKey: "<qbseal envelope>", wrapMethod: "scope",
208
243
  // wrapMeta?,
209
244
  // // OPTIONAL passphrase-reveal enrollment (the step-up verifier):
210
245
  // stepUp?: { kind: "passphrase", publicKey: "<b64url Ed25519>",
211
246
  // salt: "<b64url>", argon2: { memoryKiB, iterations, parallelism } } }
212
247
  // ← { granted: true, scopeRef, userId, stepUpEnrolled: boolean }
213
248
  ```
214
- `stepUp.argon2` is floor-checked **at enrollment** (a weak verifier is rejected here, not just at reveal). The `stepUpPublicKey` + params are stored zero-knowledge; the passphrase never leaves the client.
249
+ Legacy callers may still include `stepUp` for compatibility, but new clients
250
+ should use `/enrollment/replace` first. Argon2 parameters are floor-checked at
251
+ enrollment; the `stepUpPublicKey` and params are public verifier material, and
252
+ the passphrase never leaves the client.
215
253
 
216
254
  ### 8. `/revoke` — sever future access (key-admin)
217
255
 
@@ -246,6 +284,23 @@ A reader who has a role for a scope but no grant publishes their X25519 USER pub
246
284
  ```
247
285
  The key-admin wraps the scope key to each `userPublicKey` and calls [`/grant`](#7-grant--enroll-a-reader--store-their-wrapped-scope-key-key-admin), which **auto-resolves** the matching pending request.
248
286
 
287
+ ### Enrollment lifecycle — replace and inspect verifier material
288
+
289
+ `/enrollment/replace` is the single framework-owned mutation for changing a
290
+ reader's public enrollment material. In one database batch it:
291
+
292
+ 1. advances `enrollmentVersion` and generates a fresh random
293
+ `enrollmentRevision`;
294
+ 2. replaces the X25519 and Ed25519 public keys plus Argon2 parameters;
295
+ 3. revokes the previous live scope grant; and
296
+ 4. creates or refreshes the pending grant request for custodian approval.
297
+
298
+ The reader stays locked until a key-admin wraps and grants the scope key to the
299
+ new public key. `/enrollment/me` returns only the caller's current public
300
+ enrollment. `/enrollments` is key-admin-gated and returns public enrollment
301
+ material for the requested users. These routes never accept or return a
302
+ passphrase, USER private key, or unwrapped scope key.
303
+
249
304
  ### 12. `/recovery/enroll` — escrow the scope key under a recovery factor (key-admin)
250
305
 
251
306
  A key-admin (holding the scope private key) wraps it to a client-held recovery factor and escrows the blob. The server stores only the opaque recovery-wrapped material — the factor, held by the client, is what makes it usable; the server can never unwrap it.
@@ -216,7 +216,10 @@ export default defineTable(guests, {
216
216
  - **`onEnter` steps** run in the generated `execute`, *after* the
217
217
  compiler-applied primary write (parent row first). `update` steps go
218
218
  through the scoped db — cross-feature targets resolve automatically and
219
- inherit the firewall. `enqueue` steps ride the after-commit effects queue.
219
+ inherit the firewall. `enqueue` steps ride the after-commit effects queue
220
+ (`effects.enqueue(binding, message)`); in a [tenant
221
+ feature](/configure/tenant-databases#platform-queues) they go through the
222
+ object's outbox instead.
220
223
  Substitution values are a strict allowlist — `$record.<col>`,
221
224
  `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id` — always
222
225
  parameterized, never interpolated into SQL.
@@ -89,7 +89,11 @@ What is the same on every provider:
89
89
  - `OLD.column` / `NEW.column` references use **SQL column names**
90
90
  (`deleted_at`, not `deletedAt`) and are validated against the table at
91
91
  compile time.
92
- - Optional `when:` is a SQL expression guard (`WHEN` clause). On Postgres it
92
+ - Optional `when:` is a SQL expression guard (`WHEN` clause) and must be
93
+ exactly **one expression**: the compile fails on a `;`, a comment, an
94
+ unbalanced parenthesis, `BEGIN`, an `END` that closes no `CASE`, or a
95
+ statement keyword (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`,
96
+ `PRAGMA`, …) outside a string literal. On Postgres it
93
97
  cannot contain a subquery (`EXISTS (SELECT …)`, `IN (SELECT …)`, or a scalar
94
98
  `(SELECT …)`) — Postgres refuses that at `CREATE TRIGGER` time, so the
95
99
  compile fails instead. Keep the subquery-free conjuncts in `when:` and move
@@ -250,6 +254,49 @@ Drops never use `CASCADE` — an unexpected dependency fails loudly rather than
250
254
  being swept — and Postgres trigger drops are guarded on `to_regclass`, so a
251
255
  table the preceding schema migration removed does not break the cleanup.
252
256
 
257
+ ### Tenant databases
258
+
259
+ With [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases), a
260
+ tenant table's `sql:` triggers install **inside each tenant object**, not on
261
+ the features D1. They are reinstalled whenever the trigger set changes, after
262
+ every tenant migration, and after a dump restore.
263
+
264
+ Its `handler:` triggers run in the tenant Worker only: they are emitted into
265
+ `src/tenant/trigger-hooks.ts`, and the edge registry (`src/lib/trigger-hooks.ts`)
266
+ holds only platform tables' handlers. Tenant handlers get the same checks as
267
+ tenant actions (no `env` bindings, no edge-only modules).
268
+
269
+ A trigger runs inside one SQLite database, so every table its body or `when:`
270
+ names must live in the **same object** as the trigger's table — the same
271
+ tenant, or the same partition kind. The compiler reads every table position
272
+ (`FROM` / `JOIN` lists, `INSERT INTO`, `UPDATE`, `DELETE FROM`, `x IN table`,
273
+ subqueries), splitting the text the way SQLite does, and fails the compile
274
+ with `TENANCY_TRIGGER_CROSS_OBJECT`, listing each offender, when one names a
275
+ platform table, another partition kind, or a table no feature declares
276
+ (names are matched by their SQL name, not the export name). Shapes it does
277
+ not model are refused, not passed: a schema-qualified name, a CTE, a
278
+ string literal in a table position, a table-valued function other than
279
+ `json_each` / `json_tree`, a statement keyword such as `DROP` or `PRAGMA`,
280
+ or unbalanced parentheses. This is a conservative check, not a full SQL
281
+ parser — if it refuses a body you know is local, rewrite it with plain
282
+ table names. A platform
283
+ table's trigger may not name a tenant table either. Carry a cross-object
284
+ effect in application code (`tenantRuntime(env).send(...)`).
285
+
286
+ ```typescript
287
+ // features/tasks/tasks.ts — a tenant table: installs in every tenant object
288
+ beforeUpdate: [
289
+ {
290
+ name: 'lockDone',
291
+ when: `OLD.done = 1`,
292
+ sql: `SELECT RAISE(ABORT, 'QB_TRIGGER_REJECTED:TASK_DONE: done tasks are immutable');`,
293
+ },
294
+ ],
295
+ ```
296
+
297
+ `handler:` triggers on tenant tables are governed separately; see
298
+ [Tenant databases](/configure/tenant-databases#what-the-compiler-refuses).
299
+
253
300
  ## Handler triggers (`handler:`)
254
301
 
255
302
  Handlers run at the same write chokepoint that powers audit stamping and
@@ -419,6 +466,13 @@ execute: async ({ db, effects }) => {
419
466
  }
420
467
  ```
421
468
 
469
+ To send a queue message after commit, pass the binding and the message:
470
+ `effects.enqueue("COMMS_QUEUE", { type: "mail.send", … })` calls
471
+ `env.COMMS_QUEUE.send(message)` with the other effects. In a [tenant
472
+ feature](/configure/tenant-databases#platform-queues) the message goes through
473
+ the tenant object's outbox before the response instead, with `tenantId` and
474
+ `dedupeKey` stamped by the edge.
475
+
422
476
  Effects enqueued by an `execute` that later throws are dropped. The context
423
477
  also carries `now` — one ISO timestamp per invocation; prefer it over
424
478
  `new Date().toISOString()`. See [Column types](/define/schema#decimals-dates-64-bit-integers-and-arrays) for
@@ -81,8 +81,10 @@ caller-generated UUID, ≤ 255 chars) to make the write safe to retry:
81
81
  - A concurrent duplicate gets `409 IDEMPOTENCY_IN_PROGRESS`.
82
82
  - Reusing a key for a *different* request (method/path) is a
83
83
  `422 IDEMPOTENCY_KEY_REUSED`.
84
- - Keys expire after **24 hours** (Stripe semantics); 5xx and `Set-Cookie`
85
- responses release the lock instead of caching.
84
+ - Keys expire after **24 hours** (Stripe semantics); 5xx, `Set-Cookie` and
85
+ `Cache-Control: no-store` responses release the lock instead of caching. A
86
+ `no-store` response (a grant code, a token) is never stored for any caller,
87
+ so a retry re-runs the handler rather than replaying a secret.
86
88
 
87
89
  The key is per **request**. For "this client-side record exists exactly
88
90
  once" across sessions and devices, store a per-**row** token instead — see
@@ -97,7 +99,11 @@ before the stale-claim takeover, so a foreign caller can neither read nor
97
99
  overwrite your claim.
98
100
 
99
101
  **Unauthenticated requests carrying the header are rejected (400)** — an
100
- anonymous caller has no principal to bind the claim to. A PUBLIC standalone
102
+ anonymous caller has no principal to bind the claim to. Better Auth's own
103
+ routes (`/auth/v1/*` and `/cli/*`) are the exception: Better Auth
104
+ authenticates them itself, so the header is ignored there rather than
105
+ rejected, and a client can attach it to every write. The operator endpoints
106
+ mounted under the auth prefix still honor it. A PUBLIC standalone
101
107
  action may opt in explicitly:
102
108
 
103
109
  ```ts title="quickback/features/orders/actions/submitForm.ts"
@@ -71,9 +71,14 @@ Validation steps (in generated `src/middleware/auth.ts`):
71
71
  3. Verify the EdDSA signature with jose against the keyring's public JWKS — cached per isolate, refetched at most once when a token names an unknown `kid` (key rotation). Only `EdDSA` is accepted, so alg-confusion is rejected by construction, and `iss` / `aud` are pinned to the compile-time constants
72
72
  4. Check `exp` against the current time
73
73
  5. On success: hydrate `AppContext` from claims (`sub`, `sid`, `orgId`, `role`, `userRole`, `email`, `name`) — no DB query
74
- 6. On failure for a token **this project minted** (rotated key, expired, tampered, revoked — recognised by the pinned `iss`, or the legacy HS256 shape): **`401`** with `AUTH_INVALID_TOKEN` (`AUTH_EXPIRED` when `exp` has passed) and `WWW-Authenticate: Bearer error="invalid_token"`. No fall-through: a presented-and-bad credential is never treated as no credential, so clients can key "drop the cached token and re-mint" on 401 alone. A foreign JWT (an OAuth access token — same keyring, OAuth issuer) falls through to its own verifier — which is why [`auth.jwt.issuer`](/configure/auth#issuer-string--iss-claim) may never equal the OAuth issuer (compile error). A token that *verifies* but is not one this lane admits (a session user's scope token on a project without `auth.jwt`) is a good credential, not a bad one: it falls through to session auth
74
+ 6. On failure for a token **this project minted** (rotated key, expired, tampered, revoked — recognised by the pinned `iss`, through the same `isQuickbackJwt()` exported from `src/lib/jwt.ts`): **`401`** with `AUTH_INVALID_TOKEN` (`AUTH_EXPIRED` when `exp` has passed) and `WWW-Authenticate: Bearer error="invalid_token"`. No fall-through: a presented-and-bad credential is never treated as no credential, so clients can key "drop the cached token and re-mint" on 401 alone. A foreign JWT (an OAuth access token — same keyring, OAuth issuer) falls through to its own verifier — which is why [`auth.jwt.issuer`](/configure/auth#issuer-string--iss-claim) may never equal the OAuth issuer (compile error). A token that *verifies* but is not one this lane admits (a session user's scope token on a project without `auth.jwt`) is a good credential, not a bad one: it falls through to session auth
75
75
  7. With no JWT at all: fall back to Better Auth's session cookie auth; if that succeeds, mint a fresh JWT and return it in the `set-auth-token` response header
76
76
 
77
+ > **Removed: legacy HS256 token shape**
78
+ >
79
+ > Nothing has minted an HS256 Quickback JWT since the keyring (0.66, 2026-09-17), and an HS256 token never verified. Since 0.72 the middleware no longer recognises the shape: an HS256 bearer carries no pinned `iss`, so it falls through like any unrecognised token. An authenticated route answers `401` (`AUTH_MISSING`) and a public route serves the anonymous principal. No signed-in user is affected: a client still holding an HS256 token was already unable to authenticate.
80
+
81
+
77
82
  The Files worker (R2 uploads) runs the same verifier (`src/lib/jwt-verify.ts`) over the public keys it reads from the `jwks` table — no shared secret, no network round-trip to the auth API for file operations.
78
83
 
79
84
  ---
@@ -110,6 +115,8 @@ The fast-path is stateless by default: it verifies the signature and **trusts th
110
115
 
111
116
  **Lower the TTL.** `auth.jwt.expiresIn: 30` gives a hard 30-second ceiling. Browser SPAs auto-refresh via `set-auth-token` on every authed call, so a low TTL is invisible to logged-in users; only stale server-to-server bearer tokens feel it.
112
117
 
118
+ An `expiresIn` above one day (`86400`) without `revocationCheck: 'kv'` compiles with a **warning**: nothing can revoke such a token before it expires, so a ban or sign-out would take up to that long to reach it.
119
+
113
120
  **Or enable sub-TTL revocation.** Set `revocationCheck: 'kv'` (Cloudflare runtime only):
114
121
 
115
122
  ```ts title="quickback.config.ts"
@@ -133,6 +140,11 @@ Revocation stamps are written **automatically** on:
133
140
 
134
141
  The generated `src/lib/jwt-revocation.ts` exports `revokeUserTokens`, `revokeMemberTokens`, and `revokeScopeTokens` for explicit calls from your own action code.
135
142
 
143
+ > **Retiring: `qbrev:scope`**
144
+ >
145
+ > The scope markers (`qbrev:scope`, written by `revokeScopeTokens` and by relationship-row changes) only deny scope tokens from `POST /scope/v1/enter`, `ctx.mintScope`, and namespace `mintScope: true`. Those mints are [deprecated](/define/scopes#migrating-to-instance-bound-oauth-tokens) in favour of instance-bound OAuth tokens, which re-prove the relationship at every refresh and on every request. `qbrev:scope` keeps working while scope tokens do, and is removed with them in a later major. `qbrev:sid`, `qbrev:user`, and `qbrev:member` stay: they are the only sub-TTL revocation for Quickback-minted JWTs, bound OAuth tokens included.
146
+
147
+
136
148
  Independently of revocation, a JWT **never outlives the session it was minted from**: both the session-path mint (`set-auth-token`) and `GET /auth/v1/token` clamp `exp` to `min(now + expiresIn, session.expiresAt)`. A token minted in the last minutes of a session expires with it instead of running the full TTL.
137
149
 
138
150
  > **Honest limits**
@@ -107,7 +107,7 @@ export default defineConfig({
107
107
  });
108
108
  ```
109
109
 
110
- `GET /auth/v1/organization/roster` then returns `{ data: [{ id, name, email, image, role }] }` for `ctx.activeOrgId`:
110
+ `GET /api/v1/organization/roster` then returns `{ data: [{ id, name, email, image, role }] }` for `ctx.activeOrgId`:
111
111
 
112
112
  - **401** with no credentials, **403** `ACCESS_NO_ORG` with no active organization, **403** when the caller holds none of `access.roles`.
113
113
  - It reads on the service lane and filters to the active organization in the query, because Postgres RLS lets a caller-scoped handle read only their own `users` row.
@@ -261,8 +261,8 @@ complete as a hand-written one. The rules:
261
261
  `worker.vars` keeps production's other vars and overrides
262
262
  `BETTER_AUTH_URL`. `requiredSecrets`, `workersDev`, `previewUrls`,
263
263
  `placement` and the email binding are inherited unchanged.
264
- - **Identity and state are never inherited.** `name`, `domain` / `domains`,
265
- `filesWorker`, `branch`, `worker.env`, and the stateful bindings `d1`, `kv`,
264
+ - **Identity and state are never inherited.** `name`, `accountId`, `domain` /
265
+ `domains`, `filesWorker`, `tenantWorker`, `branch`, `worker.env`, and the stateful bindings `d1`, `kv`,
266
266
  `hyperdrive`, `queues`, `r2Buckets` and `rateLimits` must be restated. If
267
267
  any were inherited, a staging deploy would run on production's script,
268
268
  hostnames, or data. If one is missing, the usual per-target errors name it
@@ -272,6 +272,102 @@ complete as a hand-written one. The rules:
272
272
  - **Chains are allowed. A cycle or an unknown parent is a compile error** that
273
273
  names the chain (`staging → preview → staging`).
274
274
 
275
+ ### A target in another Cloudflare account (`accountId`)
276
+
277
+ Set `accountId` on a target to deploy it into a different Cloudflare account
278
+ than the rest of the project. It emits `account_id` inside that target's
279
+ `[env.<name>]` stanza:
280
+
281
+ {/* doc-compile: skip — excerpt of the `environments` block; the full target contract is shown above. */}
282
+ ```typescript title="quickback/quickback.config.ts"
283
+ providers: {
284
+ runtime: defineRuntime("cloudflare", { accountId: "0123456789abcdef0123456789abcdef" }),
285
+ // …
286
+ },
287
+ environments: {
288
+ dev: { name: "my-app-dev", worker: { /* … */ } }, // our account
289
+ acme: {
290
+ name: "my-app-acme",
291
+ accountId: "fedcba9876543210fedcba9876543210", // the client's account
292
+ worker: { /* … every binding id from the client's account … */ },
293
+ },
294
+ },
295
+ ```
296
+
297
+ ```toml title="wrangler.toml (generated)"
298
+ account_id = "0123456789abcdef0123456789abcdef"
299
+
300
+ [env.acme]
301
+ name = "my-app-acme"
302
+ account_id = "fedcba9876543210fedcba9876543210"
303
+ ```
304
+
305
+ Wrangler reads the `[env.*]` `account_id` before the top-level one and before
306
+ `CLOUDFLARE_ACCOUNT_ID`, so `npm run deploy:acme` and
307
+ `npm run db:migrate:acme:remote` (both pass `--env acme`) can only reach the
308
+ client's account. The managed files Worker's `wrangler.toml` gets the same
309
+ `account_id` per target.
310
+
311
+ The compile fails closed:
312
+
313
+ - `accountId` must be a Cloudflare account id: 32 lowercase hex characters.
314
+ The same rule applies to `providers.runtime.config.accountId`.
315
+ - Once any target sets `accountId`, every target must resolve an account —
316
+ its own, or `providers.runtime.config.accountId`. Without either, Wrangler
317
+ deploys into whichever account the credential selects.
318
+ - A target in an account other than the top-level one must declare every
319
+ account-scoped resource itself. A resource lives in exactly one account, so
320
+ the compile error lists everything missing at once:
321
+ *Environment acme deploys into Cloudflare account fedcba…, not the top-level
322
+ account, and a resource lives in exactly one account — so it must declare
323
+ its own: bindings.d1.auth.databaseId, bindings.d1.features.databaseId.*
324
+ - `extends` never copies `accountId`. A target extending a pinned target must
325
+ state its own `accountId` (the same id to stay in that account); omitting
326
+ it is a compile error, not a silent fallback to the top-level account.
327
+ - `quickback deploy --env <name>` refuses a `wrangler.toml` whose
328
+ `account_id` differs from the config (*Run quickback build before
329
+ deploying*), so a stale build cannot deploy into the previous account.
330
+ - `providers.runtime.config.accountId` must also be 32 lowercase hex. A value
331
+ in any other format, which Wrangler would reject at deploy, now fails the
332
+ compile.
333
+ - The brokered deploy (Quickback Start) refuses a project with a pinned
334
+ target (`environment-account-unsupported`). It deploys only into the
335
+ account you connected. Deploy pinned targets with `quickback deploy --env`
336
+ or Wrangler.
337
+
338
+ ### Private deployment in a client's account
339
+
340
+ To run a client on their own Cloudflare account, add one environment per
341
+ client account:
342
+
343
+ 1. Get a credential for their account: a scoped API token (Workers Scripts,
344
+ D1, R2, KV, and Workers Routes on their zone), or membership with a scoped
345
+ role.
346
+ 2. Create their D1 databases, KV namespace, R2 buckets, and queues **in their
347
+ account**.
348
+ 3. Add `environments.<client>` with `accountId`, its own `name`, `domains`,
349
+ and every resource id from step 2.
350
+ 4. Set secrets per target: `wrangler secret put BETTER_AUTH_SECRET --env <client>`.
351
+ 5. Deploy with that client's credential: `npm run db:migrate:<client>:remote`,
352
+ then `npm run deploy:<client>`.
353
+
354
+ Every client runs the same compiled bundle. Only the `[env.<client>]` stanza
355
+ differs.
356
+
357
+ Check one thing by hand: **a target without `accountId` deploys into
358
+ `providers.runtime.config.accountId`**. The compiler cannot tell a client
359
+ target from one of yours, so a client target that omits `accountId` compiles
360
+ cleanly and deploys into your account. Review every client target for it.
361
+
362
+ Hand-written Wrangler commands must pass `--env <client>` too —
363
+ `wrangler r2 bucket create … --env acme`, `wrangler secret put … --env acme`.
364
+ Without `--env`, Wrangler reads the top-level `account_id`.
365
+
366
+ The generated `drizzle.*.config.ts` files (`driver: "d1-http"`, used by
367
+ `drizzle-kit studio` / `push`) read `CLOUDFLARE_ACCOUNT_ID` from the shell and
368
+ the top-level D1 ids. They are not per-target. Do not loop them over client
369
+ targets; run D1 migrations with `npm run db:migrate:<client>:remote`.
370
+
275
371
  ### Queues and R2 buckets per target
276
372
 
277
373
  Queue names and R2 bucket names are stateful, so repeating the primary value
@@ -344,7 +440,16 @@ The contract fails closed:
344
440
  sharing a queue or bucket would hand a dev deploy production state.
345
441
  - `requiredSecrets` and `rateLimits` must match the generated runtime
346
442
  inventory exactly, so adding a feature tells you which override changed.
347
- - `workersDev: true` and `previewUrls: false` must be explicit on each target.
443
+ - `workersDev` (`true` or `false`) and `previewUrls: false` must be explicit on each target. `workersDev: false` turns the target's `<name>.<account>.workers.dev` hostname off (and its tenant Worker's, with `tenancy.isolation: 'durable-object'`); the target then needs a hostname of its own (`domain` / `domains`, or an MCP server's public URL for that environment), or the config is refused.
444
+ - The top-level `name` in `wrangler.toml` is an inert placeholder,
445
+ `<name>-unselected`, and no target may use it. A bare or positional
446
+ `wrangler deploy` without `--env` therefore creates an unbound Worker under
447
+ that name. It cannot replace a real target, such as the one that deploys as
448
+ the project `name`. The managed files Worker gets `<name>-files-unselected`
449
+ the same way. The top level keeps only settings that bind nothing (`[dev]`,
450
+ `observability`, `placement`). Assets and cron triggers are emitted per
451
+ target. Workers AI, Vectorize and a separate realtime service are refused
452
+ with named environments until they have per-target config.
348
453
  - Every custom domain the config generates must be claimed per target via
349
454
  `domains` (`{ api: "api-dev.example.com" }`, or the bare `domain` shorthand
350
455
  for a single-hostname project). Quickback emits no top-level `routes` block
@@ -352,6 +457,10 @@ The contract fails closed:
352
457
  hostname on a dev deploy. Each target names its own all-in-one host with
353
458
  `domains.primary`; none is inferred. See
354
459
  [Named Environments](/configure/domains#named-environments).
460
+ - With `tenancy.isolation: 'durable-object'`, each target also names its own
461
+ tenant Worker (`tenantWorker.name`, plus `backupBucketName` when
462
+ `tenancy.backup` is set). See
463
+ [Database per Tenant](/configure/tenant-databases#named-environments).
355
464
 
356
465
  Set secrets per target: `wrangler secret put BETTER_AUTH_SECRET --env dev`.
357
466
 
@@ -72,7 +72,9 @@ do in action files, so `../../db/schema` is the generated schema barrel.
72
72
  with a single conflict-free `INSERT`, so two concurrent applies cannot both
73
73
  run. An applied id answers `409 DATA_MIGRATION_ALREADY_APPLIED`.
74
74
  - **Failures are recorded and retryable.** A thrown error marks the row
75
- `failed`, with the message and log. The next `quickback migrate data` re-runs
75
+ `failed`, with the message and log. Recognizable bound database values are
76
+ redacted from failure messages and logged errors before storage or response;
77
+ SQL placeholders and diagnostic names remain. The next `quickback migrate data` re-runs
76
78
  it.
77
79
  - **No implied transaction.** D1 has no transactions across statements, so
78
80
  write migrations that are safe to re-run after a partial failure. Select
@@ -112,6 +112,10 @@ deploys through Wrangler as `attend-v2-dev` and `attend-v2-prod`:
112
112
  > error, because there would be no single source of truth.
113
113
 
114
114
 
115
+ To deploy one target into a different Cloudflare account, such as a client's,
116
+ set `environments.<name>.accountId`. The rules are the same on Neon and D1 —
117
+ see [A target in another Cloudflare account](/platform/database/d1#a-target-in-another-cloudflare-account-accountid).
118
+
115
119
  ```typescript title="quickback/quickback.config.ts"
116
120
  export default defineConfig({
117
121
  name: "attend-v2",
@@ -203,6 +207,9 @@ placeholder state.
203
207
  The environment contract is intentionally exact and fails closed:
204
208
 
205
209
  - `workersDev: true` and `previewUrls: false` must be explicit for each target.
210
+ - The top-level `name` in `wrangler.toml` is an inert placeholder,
211
+ `<name>-unselected`, so a `wrangler deploy` without `--env` cannot replace
212
+ a real target. No target may use it.
206
213
  - `worker.placement` (`{ mode }` or `{ region }`) sets that target's
207
214
  [placement](/configure/providers#runtime-options); without it, the top-level
208
215
  `providers.runtime.config.placement` is emitted for the target.
@@ -569,8 +576,9 @@ write it makes runs on the service lane. The predicate:
569
576
  Everything else is **service-only** — deny-anon plus the bootstrap lane is the
570
577
  entire policy set, and no caller-scoped handle can read a row either: `verification`,
571
578
  `jwks`, the Better Auth rate-limit counters, `device_code`, the
572
- `oauth_*` provider tables and the `agent_*` / `approval_request` agent-auth
573
- tables. Better Auth's own adapter always stamps the service marker, so its
579
+ `oauth_*` provider tables, the `agent_*` / `approval_request` agent-auth
580
+ tables, `two_factor` (the `twoFactor` plugin's TOTP secrets and backup codes),
581
+ and `wallet_address` (`siwe`). Better Auth's own adapter always stamps the service marker, so its
574
582
  reads and writes never consult any of this; the policies exist for the handles
575
583
  that are *not* Better Auth.
576
584
 
@@ -75,6 +75,10 @@ export default defineQueue<ProcessMaterialMessage>({
75
75
  | `name` | `string` | Yes | Handler identifier (used in logs) |
76
76
  | `messageType` | `string` | Yes | Message type to match (e.g., `'process_material'`) |
77
77
  | `description` | `string` | No | Human-readable description |
78
+ | `tenant` | `true` | No | Run inside the tenant object named by `message.tenantId` (`tenancy.isolation: 'durable-object'`). See [Tenant databases](/configure/tenant-databases#background-work). |
79
+ | `result` | `true` | No | A result job: called from edge code with `callTenantJob(env, tenantId, message, runId)`, which returns the handler's `result`. Needs `tenant: true` and `resultSchema`; never queued. See [Result jobs](/configure/tenant-databases#result-jobs). |
80
+ | `resultSchema` | `z.object(…)` | With `result` | Validates the returned `result` before it is recorded and returned (at most 256 KiB). `z.object` strips unknown keys; a strict object refuses them; passthrough / loose schemas fail the build. |
81
+ | `resultTtlSeconds` | number literal | No | Result jobs only: how long the object keeps a call's result so a repeated `runId` replays it. 60 to 604800 (7 days, the default); a short one suits read-only pulls such as exports. See [Result jobs](/configure/tenant-databases#result-jobs). |
78
82
  | `execute` | `function` | Yes | Handler function |
79
83
 
80
84
  ## Execute Function
@@ -122,7 +126,7 @@ payload (e.g. `message.body.organizationId`).
122
126
 
123
127
  ## Constants and Imports
124
128
 
125
- The compiler extracts top-level constants and imports from your handler file and includes them in the generated queue consumer:
129
+ The compiler extracts top-level declarations and imports from your handler file and includes them in the generated queue consumer:
126
130
 
127
131
  ```typescript
128
132
  // services/queues/ingest.ts
@@ -147,9 +151,24 @@ export default defineQueue({
147
151
 
148
152
  The compiler:
149
153
  1. Extracts all `import` statements
150
- 2. Extracts top-level `const` declarations (including multi-line template literals)
154
+ 2. Extracts top-level `const` / `let`, `function`, `class`, `enum`, type alias
155
+ and interface declarations, in source order, before or after `defineQueue`
151
156
  3. Inlines them in the generated queue consumer
152
157
 
158
+ Every handler file's declarations share one generated module, so names must be
159
+ unique across handler files (a clash fails the build). `var` is refused because
160
+ a repeated `var` would silently shadow another file's. Directives
161
+ (`'use strict'`) and ambient `declare global` / `declare module` blocks are
162
+ skipped. Any other top-level statement (a bare call, an `if` block) fails the
163
+ build with `Unsupported top-level statement in <file>:<line>`: move it into a
164
+ declaration or into `execute`. The same rules apply to schedule and inbound
165
+ email handlers.
166
+
167
+ `execute` must be written inline: an arrow function with a block body, an
168
+ expression body (`async ({ message }) => ({ success: true })`) or a method
169
+ (`async execute({ message }) { … }`). A shorthand `execute,` or a computed
170
+ `['execute']` key fails the build.
171
+
153
172
  Write static relative imports from your authored file's location. For example,
154
173
  from `quickback/services/queues/ingest.ts`, import a feature helper with
155
174
  `../../features/materials/lib/process`. The compiler relocates that import to
@@ -244,24 +263,37 @@ const ingestQueueHandler = async (batch, env) => {
244
263
  }
245
264
  };
246
265
 
247
- // Unified dispatcher
248
- export const queue = async (batch, env) => {
249
- const messageType = batch.messages[0]?.body?.type;
250
-
251
- switch (messageType) {
252
- case 'embedding':
253
- await embeddingQueueHandler(batch, env);
254
- break;
255
- case 'process_material':
256
- await ingestQueueHandler(batch, env);
257
- break;
258
- default:
259
- console.warn('[Queue] Unknown message type:', messageType);
260
- for (const msg of batch.messages) msg.ack();
266
+ // Unified dispatcher: groups the delivery by body.type, so each handler
267
+ // gets a batch of only its own messages (simplified).
268
+ export const queue = async (incoming, env) => {
269
+ for (const [messageType, messages] of groupByType(incoming.messages)) {
270
+ const batch = queueSubBatch(incoming, messages); // ackAll/retryAll: these messages only
271
+ switch (messageType) {
272
+ case 'embedding':
273
+ await embeddingQueueHandler(batch, env);
274
+ break;
275
+ case 'process_material':
276
+ await ingestQueueHandler(batch, env);
277
+ break;
278
+ default:
279
+ console.warn('[Queue] Unknown message type:', messageType);
280
+ for (const msg of batch.messages) msg.ack();
281
+ }
261
282
  }
262
283
  };
263
284
  ```
264
285
 
286
+ One queue can carry several producers' messages, so a single delivery may mix
287
+ types. The dispatcher routes **per message**: it groups the batch by
288
+ `body.type` and calls each type's handler with a batch of only that type's
289
+ messages (`ackAll()` / `retryAll()` on it touch only those). A handler that
290
+ throws does not stop the other types; the first error is rethrown afterwards,
291
+ so the runtime retries every message no handler acked. Ack (or retry) every
292
+ message explicitly: one left to the runtime's implicit ack is redelivered when
293
+ another type's handler in the same delivery throws. With webhooks, webhook
294
+ deliveries are handled one by one and the rest go to this dispatcher as their
295
+ own batch.
296
+
265
297
  ## wrangler.toml Configuration
266
298
 
267
299
  Configure your queues in wrangler.toml:
@@ -40,6 +40,22 @@ await ctx.env.EMBEDDINGS_QUEUE.send({
40
40
 
41
41
  **Webhooks** are enqueued via `emitWebhookEvent()` — see [Outbound Webhooks](/platform/webhooks/outbound).
42
42
 
43
+ ### From tenant code
44
+
45
+ With [database-per-tenant](/configure/tenant-databases) tenancy, tenant
46
+ actions and tenant jobs have no queue bindings. They send through the tenant
47
+ object's outbox instead, and the edge Worker delivers the message with
48
+ `tenantId` and a `dedupeKey` stamped:
49
+
50
+ {/* doc-compile: skip — tenant action body fragment */}
51
+ ```typescript
52
+ tenantRuntime(env).enqueue("PROCESSING_QUEUE", { type: "process_material", materialId: input.materialId });
53
+ ```
54
+
55
+ Delivery is at least once; dedupe on `message.dedupeKey`. Only the project's
56
+ declared queue bindings are accepted. See
57
+ [Platform queues](/configure/tenant-databases#platform-queues).
58
+
43
59
  ## Chaining Queues
44
60
 
45
61
  Queue handlers can publish to other queues for multi-stage pipelines: