@quickback-dev/cli 0.70.45 → 0.72.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/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/docs/api/actions.md +73 -2
  60. package/dist/skill/docs/api/batch-operations.md +2 -0
  61. package/dist/skill/docs/api/caching.md +2 -2
  62. package/dist/skill/docs/api/crud.md +13 -0
  63. package/dist/skill/docs/api/errors.md +111 -10
  64. package/dist/skill/docs/api/index.md +24 -0
  65. package/dist/skill/docs/api/openapi.md +8 -0
  66. package/dist/skill/docs/api/query-params.md +6 -0
  67. package/dist/skill/docs/configure/agents.md +73 -1
  68. package/dist/skill/docs/configure/auth.md +7 -1
  69. package/dist/skill/docs/configure/bindings.md +55 -0
  70. package/dist/skill/docs/configure/cloudflare-access.md +191 -0
  71. package/dist/skill/docs/configure/domains.md +1 -1
  72. package/dist/skill/docs/configure/index.md +4 -2
  73. package/dist/skill/docs/configure/providers.md +2 -1
  74. package/dist/skill/docs/configure/tenancy.md +3 -0
  75. package/dist/skill/docs/configure/tenant-databases.md +2407 -0
  76. package/dist/skill/docs/define/access.md +33 -1
  77. package/dist/skill/docs/define/actions/defining.md +118 -1
  78. package/dist/skill/docs/define/actions/scoped-db.md +32 -8
  79. package/dist/skill/docs/define/areas.md +145 -2
  80. package/dist/skill/docs/define/diagnostics.md +160 -21
  81. package/dist/skill/docs/define/encryption.md +13 -2
  82. package/dist/skill/docs/define/fga.md +320 -42
  83. package/dist/skill/docs/define/firewall.md +4 -0
  84. package/dist/skill/docs/define/index.md +1 -0
  85. package/dist/skill/docs/define/read.md +39 -0
  86. package/dist/skill/docs/define/relationships.md +30 -12
  87. package/dist/skill/docs/define/schema.md +2 -0
  88. package/dist/skill/docs/define/scopes.md +393 -9
  89. package/dist/skill/docs/define/sealed-protocol.md +67 -12
  90. package/dist/skill/docs/define/transitions.md +4 -1
  91. package/dist/skill/docs/define/triggers.md +55 -1
  92. package/dist/skill/docs/platform/api-contract/index.md +4 -2
  93. package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
  94. package/dist/skill/docs/platform/auth/using-auth.md +1 -1
  95. package/dist/skill/docs/platform/database/d1.md +112 -3
  96. package/dist/skill/docs/platform/database/data-migrations.md +3 -1
  97. package/dist/skill/docs/platform/database/neon.md +10 -2
  98. package/dist/skill/docs/platform/queues/handlers.md +48 -16
  99. package/dist/skill/docs/platform/queues/using-queues.md +16 -0
  100. package/dist/skill/docs/platform/realtime/durable-objects.md +285 -17
  101. package/dist/skill/docs/platform/realtime/index.md +9 -6
  102. package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
  103. package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
  104. package/dist/skill/docs/platform/schedules/index.md +1 -1
  105. package/dist/skill/docs/platform/storage/r2.md +10 -1
  106. package/dist/skill/docs/platform/storage/using-r2.md +42 -1
  107. package/dist/skill/docs/tooling/output.md +9 -2
  108. package/dist/skill/docs/ui/account/features/admin.md +5 -3
  109. package/dist/skill/docs/ui/account/hooks.md +9 -2
  110. package/dist/skill/docs/ui/admin/index.md +1 -1
  111. package/package.json +1 -1
  112. package/src/skill/docs/api/actions.md +73 -2
  113. package/src/skill/docs/api/batch-operations.md +2 -0
  114. package/src/skill/docs/api/caching.md +2 -2
  115. package/src/skill/docs/api/crud.md +13 -0
  116. package/src/skill/docs/api/errors.md +111 -10
  117. package/src/skill/docs/api/index.md +24 -0
  118. package/src/skill/docs/api/openapi.md +8 -0
  119. package/src/skill/docs/api/query-params.md +6 -0
  120. package/src/skill/docs/configure/agents.md +73 -1
  121. package/src/skill/docs/configure/auth.md +7 -1
  122. package/src/skill/docs/configure/bindings.md +55 -0
  123. package/src/skill/docs/configure/cloudflare-access.md +191 -0
  124. package/src/skill/docs/configure/domains.md +1 -1
  125. package/src/skill/docs/configure/index.md +4 -2
  126. package/src/skill/docs/configure/providers.md +2 -1
  127. package/src/skill/docs/configure/tenancy.md +3 -0
  128. package/src/skill/docs/configure/tenant-databases.md +2407 -0
  129. package/src/skill/docs/define/access.md +33 -1
  130. package/src/skill/docs/define/actions/defining.md +118 -1
  131. package/src/skill/docs/define/actions/scoped-db.md +32 -8
  132. package/src/skill/docs/define/areas.md +145 -2
  133. package/src/skill/docs/define/diagnostics.md +160 -21
  134. package/src/skill/docs/define/encryption.md +13 -2
  135. package/src/skill/docs/define/fga.md +320 -42
  136. package/src/skill/docs/define/firewall.md +4 -0
  137. package/src/skill/docs/define/index.md +1 -0
  138. package/src/skill/docs/define/read.md +39 -0
  139. package/src/skill/docs/define/relationships.md +30 -12
  140. package/src/skill/docs/define/schema.md +2 -0
  141. package/src/skill/docs/define/scopes.md +393 -9
  142. package/src/skill/docs/define/sealed-protocol.md +67 -12
  143. package/src/skill/docs/define/transitions.md +4 -1
  144. package/src/skill/docs/define/triggers.md +55 -1
  145. package/src/skill/docs/platform/api-contract/index.md +4 -2
  146. package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
  147. package/src/skill/docs/platform/auth/using-auth.md +1 -1
  148. package/src/skill/docs/platform/database/d1.md +112 -3
  149. package/src/skill/docs/platform/database/data-migrations.md +3 -1
  150. package/src/skill/docs/platform/database/neon.md +10 -2
  151. package/src/skill/docs/platform/queues/handlers.md +48 -16
  152. package/src/skill/docs/platform/queues/using-queues.md +16 -0
  153. package/src/skill/docs/platform/realtime/durable-objects.md +285 -17
  154. package/src/skill/docs/platform/realtime/index.md +9 -6
  155. package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
  156. package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
  157. package/src/skill/docs/platform/schedules/index.md +1 -1
  158. package/src/skill/docs/platform/storage/r2.md +10 -1
  159. package/src/skill/docs/platform/storage/using-r2.md +42 -1
  160. package/src/skill/docs/tooling/output.md +9 -2
  161. package/src/skill/docs/ui/account/features/admin.md +5 -3
  162. package/src/skill/docs/ui/account/hooks.md +9 -2
  163. package/src/skill/docs/ui/admin/index.md +1 -1
  164. package/dist/codex/AGENTS.md +0 -290
  165. package/dist/commands/build.test.d.ts.map +0 -1
  166. package/dist/commands/codex.d.ts +0 -16
  167. package/dist/commands/codex.d.ts.map +0 -1
  168. package/dist/commands/codex.js +0 -159
  169. package/dist/commands/codex.js.map +0 -1
  170. package/dist/commands/compile.d.ts +0 -62
  171. package/dist/commands/compile.d.ts.map +0 -1
  172. package/dist/commands/compile.js +0 -830
  173. package/dist/commands/compile.js.map +0 -1
  174. package/dist/commands/compile.test.d.ts.map +0 -1
  175. package/dist/commands/init.d.ts +0 -6
  176. package/dist/commands/init.d.ts.map +0 -1
  177. package/dist/commands/init.js +0 -405
  178. package/dist/commands/init.js.map +0 -1
  179. package/dist/commands/migrate.test.d.ts.map +0 -1
  180. package/dist/commands/migrations.test.d.ts.map +0 -1
  181. package/dist/commands/push.test.d.ts.map +0 -1
  182. package/dist/commands/schema.test.d.ts.map +0 -1
  183. package/dist/docs/content.d.ts +0 -7
  184. package/dist/docs/content.d.ts.map +0 -1
  185. package/dist/docs/content.js +0 -672
  186. package/dist/docs/content.js.map +0 -1
  187. package/dist/docs/index.test.d.ts.map +0 -1
  188. package/dist/lib/action-harvest.test.d.ts.map +0 -1
  189. package/dist/lib/api-client.test.d.ts.map +0 -1
  190. package/dist/lib/artifact-routing.test.d.ts.map +0 -1
  191. package/dist/lib/auth.test.d.ts.map +0 -1
  192. package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
  193. package/dist/lib/compiler-floor.test.d.ts.map +0 -1
  194. package/dist/lib/config-id-splice.test.d.ts.map +0 -1
  195. package/dist/lib/config-sync.test.d.ts.map +0 -1
  196. package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
  197. package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
  198. package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
  199. package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
  200. package/dist/lib/file-loader.test.d.ts.map +0 -1
  201. package/dist/lib/file-writer.test.d.ts.map +0 -1
  202. package/dist/lib/helpers.d.ts +0 -39
  203. package/dist/lib/helpers.d.ts.map +0 -1
  204. package/dist/lib/helpers.js +0 -299
  205. package/dist/lib/helpers.js.map +0 -1
  206. package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
  207. package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
  208. package/dist/lib/migrations/executor.test.d.ts.map +0 -1
  209. package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
  210. package/dist/lib/migrations/lock.test.d.ts.map +0 -1
  211. package/dist/lib/migrations/paths.test.d.ts.map +0 -1
  212. package/dist/lib/migrations/plan.test.d.ts.map +0 -1
  213. package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
  214. package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
  215. package/dist/lib/migrations/staging.test.d.ts.map +0 -1
  216. package/dist/lib/neon-canary.test.d.ts.map +0 -1
  217. package/dist/lib/neon-target.test.d.ts.map +0 -1
  218. package/dist/lib/neon.test.d.ts.map +0 -1
  219. package/dist/lib/prepare-output.test.d.ts.map +0 -1
  220. package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
  221. package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
  222. package/dist/lib/shell.test.d.ts.map +0 -1
  223. package/dist/lib/sweep-stale.d.ts +0 -25
  224. package/dist/lib/sweep-stale.d.ts.map +0 -1
  225. package/dist/lib/sweep-stale.js +0 -179
  226. package/dist/lib/sweep-stale.js.map +0 -1
  227. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  228. package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
@@ -175,8 +175,63 @@ Each entry accepts:
175
175
  | `renamedClasses` | `[{ from, to }]` — class rename without losing storage. |
176
176
  | `transferredClasses` | `[{ from, from_script, to }]` — move a class across workers. |
177
177
 
178
+ With named environments, every `[[env.<name>.migrations]]` list in the existing `wrangler.toml` must hold the same tags in the same order — all environments share one generated chain. Divergent lists fail the compile, naming the environments and the differing tags. Deploy the missing steps where they are missing, make the lists identical, then recompile.
179
+
178
180
  **When you remove a DO from `bindings.durableObjects`**, declare the teardown here. Don't hand-edit `wrangler.toml` — those edits get wiped on the next compile.
179
181
 
182
+ ### `durableObjectLifecycle`
183
+
184
+ Set `durableObjectLifecycle: "exports"` to declare Durable Object classes with Cloudflare's [`exports` map](https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/) instead of `[[migrations]]`. The default, `"migrations"`, keeps the tagged chain.
185
+
186
+ ```ts
187
+ bindings: {
188
+ durableObjectLifecycle: "exports",
189
+ durableObjects: [
190
+ { name: "NOTEPAD", className: "Notepad", from: "lib/Notepad" },
191
+ ],
192
+ // Keep historical entries: they are the input the exports map is derived from.
193
+ durableObjectMigrations: [
194
+ { tag: "qb-do-deleted-legacy-notes-2026-05-09", deletedClasses: ["LegacyNotes"] },
195
+ ],
196
+ }
197
+ ```
198
+
199
+ ```toml
200
+ [exports.Notepad]
201
+ type = "durable-object"
202
+ storage = "sqlite"
203
+
204
+ [exports.LegacyNotes]
205
+ type = "durable-object"
206
+ state = "deleted"
207
+ ```
208
+
209
+ The compiler replays the full migration history — `durableObjectMigrations`, the `[[migrations]]` in the existing `wrangler.toml`, and an `exports` map from a previous compile — so Cloudflare sees the same namespaces with no lifecycle change:
210
+
211
+ | History | `exports` entry |
212
+ |---------|-----------------|
213
+ | `new_sqlite_classes` / auto-emitted class | `storage = "sqlite"` |
214
+ | `new_classes` | `storage = "legacy-kv"` (storage is immutable — a `v1` KV Broadcaster stays KV) |
215
+ | `deleted_classes` | `state = "deleted"` |
216
+ | `renamed_classes` | `state = "renamed"` + `renamed_to`, and the new name inherits the storage |
217
+ | `transferred_classes` (deployed) | live class; storage from the binding's `useSqlite` |
218
+
219
+ The compile fails instead of emitting a map that would lose data or that Cloudflare rejects:
220
+
221
+ - A deletion whose tag is not in the existing `wrangler.toml` (not deployed yet) — a `deleted` tombstone destroys the namespace and its data. List the class in `confirmDurableObjectDeletes: ["LegacyNotes"]` to proceed.
222
+ - A tombstone for a class still in `durableObjects`.
223
+ - A class live in the history but no longer in `durableObjects` — keep the binding, or declare its deletion.
224
+ - A transfer that is not deployed yet. Run it under `"migrations"` first.
225
+ - `"migrations"` when the existing `wrangler.toml` already has an `exports` map — Cloudflare does not let a Worker return.
226
+
227
+ Switching an existing project:
228
+
229
+ 1. Run `quickback build` with the current `wrangler.toml` in place. The CLI sends it to the compiler; without it the history of auto-emitted classes is lost and a legacy KV class would be declared `sqlite` (the deploy then fails with `storage_type_mismatch`).
230
+ 2. Review the `[exports.*]` tables against the classes you have deployed.
231
+ 3. Deploy with `wrangler deploy` (Wrangler 4.107+; the generated project pins `^4.129.0`).
232
+
233
+ The switch is one-way. A version that changes the `exports` map must deploy at 100% — `wrangler deploy` or `wrangler versions deploy <id>@100%`; a percentage split with it fails (`100405`). Versions that leave the map unchanged upload and split normally. Rollback cannot cross a version that changed the map. The brokered deploy does not support `exports` yet and refuses the manifest (`durable-object-exports-unsupported`).
234
+
180
235
  ### `vars`
181
236
 
182
237
  Merged into the compiler's own `[vars]` table — emitting a second `[vars]` block would be invalid TOML. Values must be `string`, `number`, or `boolean`.
@@ -0,0 +1,191 @@
1
+ # Cloudflare Access
2
+
3
+ Set `auth.cloudflareAccess` to put [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/access-controls/) in front of operator or staff routes. Inside an application's scope, the generated Worker authenticates the request **only** from the `Cf-Access-Jwt-Assertion` header, and verifies it on every request. It never trusts the header just because it is present.
4
+
5
+ ```ts title="quickback.config.ts"
6
+ export default defineConfig({
7
+ // ...
8
+ auth: {
9
+ cloudflareAccess: {
10
+ teamDomain: 'acme.cloudflareaccess.com',
11
+ aud: { env: 'CF_ACCESS_AUD' },
12
+ hosts: ['ops.example.com'],
13
+ roles: ['sysadmin'],
14
+ serviceTokens: { '88bf3b6d86161464f6509f7219099e57.access': 'deploy-bot@example.com' },
15
+ },
16
+ },
17
+ });
18
+ ```
19
+
20
+ Requires the `cloudflare` runtime, the `better-auth` auth provider, and the `cloudflare-d1` database. Anything else is a compile error. Postgres is refused for now: the lane's user lookup carries no RLS claims, so under RLS it would find no user.
21
+
22
+ Every Access setting comes from `quickback.config.ts` or, for `teamDomain` and `aud`, from a Worker var named with `{ env }`. None can come from the database or anything an admin can edit at runtime: whoever could change them could point the Worker at their own Access team. Both `teamDomain` and `aud` are required on every application, so the config can never be half-configured; an `{ env }` var that is unset, or set without its partner, gives **500 `CF_ACCESS_MISCONFIGURED`** on every request in scope, never a pass.
23
+
24
+ ## What the Worker verifies
25
+
26
+ For a request inside an application's scope:
27
+
28
+ 1. `Cf-Access-Jwt-Assertion` is present. Otherwise **401 `CF_ACCESS_REQUIRED`**.
29
+ 2. The token is an application token (`type: "app"`), RS256-signed by a key in `https://<teamDomain>/cdn-cgi/access/certs`. `iss` equals `https://<teamDomain>`, `aud` contains the configured AUD tag, and `exp` is present and in the future. Otherwise **401 `CF_ACCESS_INVALID`**.
30
+ 3. The identity maps to an existing Better Auth user, as described in [Identity mapping](#identity-mapping). Otherwise **403 `CF_ACCESS_UNMAPPED`**.
31
+ 4. The resulting `userRole` is in `roles`. Otherwise **403 `CF_ACCESS_ROLE_NOT_ADMITTED`**.
32
+
33
+ `aud` is the application's AUD tag: 64 lowercase hex characters. A literal `aud` in any other format fails the compile. An `{ env }` value is checked at request time: a value in any other format gives **500 `CF_ACCESS_MISCONFIGURED`**.
34
+
35
+ The Worker caches the JWKS per isolate. It refetches on an unknown `kid` (at most once per 30 seconds) and once the cached set is 10 minutes old. Both cover Access key rotation.
36
+
37
+ Inside the scope, the Access assertion is the only credential:
38
+
39
+ - A session cookie, a bearer JWT, or an API key does not authenticate the request. A refused assertion never falls back to them.
40
+ - Better Auth's own routes, `/auth/v1` and everything under it, get **403 `CF_ACCESS_AUTH_ROUTE_REFUSED`**, whatever the assertion. They authenticate with Better Auth's session cookie, so they would be a second credential. This covers sign-in, `get-session`, and `GET /auth/v1/token`. Better Auth's admin-plugin routes (`/auth/v1/admin/ban-user` and the rest) are refused too. Quickback's own operator and roster routes are not under `/auth/v1` since 0.72 (they are under `/api/v1/operator` and `/api/v1/organization/roster`), so they are ordinary routes here. Until 0.73.0, the deprecated aliases this project actually emits (`/auth/v1/admin/list-organizations` and siblings with `cms.sysadmin` or `account.auth.admin`, `/auth/v1/organization/roster` with `auth.organizationRoster`) are served to Access callers too.
41
+ - The CMS and Account SPAs sign in through those Better Auth routes. Do not put their hostnames, or `/auth/v1`, inside an Access scope.
42
+
43
+ On success, `ctx` has `authMethod: 'cloudflare-access'`, the user's `userId`, `userRole`, and `user`, plus `ctx.cloudflareAccess`: `{ type: 'user' | 'service-token', email?, commonName?, groups? }`. An action can require it: `access: { userRole: ['sysadmin'], authMethod: ['cloudflare-access'] }` refuses the same sysadmin on a session cookie ([`authMethod`](/define/access#authmethod)).
44
+
45
+ ## The operator plane
46
+
47
+ The operator control plane (`cms.sysadmin` or `account.auth.admin`) lives under one prefix, `/api/v1/operator` (`/api/v2/operator` on contract v2). One `paths` application gates all of it:
48
+
49
+ ```ts
50
+ cloudflareAccess: {
51
+ teamDomain: 'acme.cloudflareaccess.com',
52
+ aud: { env: 'CF_ACCESS_AUD' },
53
+ paths: ['/api/v1/operator'],
54
+ roles: ['appmanager', 'sysadmin'],
55
+ }
56
+ ```
57
+
58
+ During the compatibility window, each known Quickback operation must satisfy the most specific Access application on **both** its legacy path and its canonical path, whichever entry point the caller uses. A rule on `/auth/v1/admin` keeps protecting old callers; a rule on `/api/v1/operator/organizations/<id>/members` also protects legacy member mutations for that organization. Neither policy replaces the other. Counterparts are operation-specific: `GET` list and `POST` create are distinct, as are `PUT` set-member and `DELETE` remove-member. `HEAD` follows the matching `GET` operation. The roster and email-readiness aliases are mapped too; unrelated routes do not inherit a whole old or new prefix. The same application selected on both paths is checked once; distinct applications are checked separately even if they share an AUD.
59
+
60
+ The Worker receives one assertion header. If the two applications have different AUDs, that assertion must satisfy both; different teams cannot share one valid issuer. Identity and effective role mappings must also agree, or the request returns `403 CF_ACCESS_POLICY_CONFLICT`. Use one application covering both prefixes with consistent mappings, or reconcile the policies before migrating callers. Moving to the canonical route does not bypass a policy on its legacy counterpart.
61
+
62
+ Legacy member mutations trim `organizationId` and `userId` through the same helper used for policy targeting. GET aliases use the same Hono query accessor as their redirect, including duplicate query parameters. Canonical route IDs retain whitespace. Policy paths and request paths compare equivalent percent-encoded segments once; an encoded slash stays within its ID segment, and double encoding remains distinct. Invalid percent encoding in a configured path is a compile error, as are overlapping applications that become equally specific after this canonicalization.
63
+
64
+ When `auth.cloudflareAccess` is configured and the operator routes are emitted, the compile **warns** unless an application covers that prefix on every hostname (a `paths` application or a whole-Worker one). A `hosts`-only application leaves the routes reachable on the other hostnames.
65
+
66
+ The Account SPA's admin screens call these routes from the browser. Behind Access, the browser needs Access's `CF_Authorization` cookie for that path, so the Access application at the edge must cover the same path on the API hostname.
67
+
68
+ ## Scope
69
+
70
+ | Keys set | The application covers |
71
+ | --- | --- |
72
+ | neither `hosts` nor `paths` | every request the Worker serves |
73
+ | `hosts` | requests whose hostname is in the list (exact, case-insensitive; one trailing `.` on the request's `Host` is ignored) |
74
+ | `paths` | requests whose path equals a prefix or sits below it (`/api/v1/ops` covers `/api/v1/ops/*`, not `/api/v1/opsx`) |
75
+ | both | requests matching a host **and** a path |
76
+
77
+ Pass an array to declare several applications. When more than one covers a request, the most specific wins, as Access resolves it at the edge. Declaration order does not matter.
78
+
79
+ 1. `hosts` **and** `paths`, longest matching path prefix first
80
+ 2. `paths` only, longest matching path prefix first
81
+ 3. `hosts` only
82
+ 4. neither (the whole Worker)
83
+
84
+ A `paths`-only application covers its paths on every hostname, including a `hosts` application's hostname. Two applications that cover the same host and path prefix at the same tier fail the compile.
85
+
86
+ The tier decides before prefix length: a `hosts` + `paths` application beats a `paths`-only one on its host even when the `paths`-only prefix is longer (`h.acme.com` + `/a` wins over `/a/b/c` on `h.acme.com`). Cloudflare's edge may resolve overlapping applications differently, so do not rely on this ordering: give overlapping applications distinct paths, or keep the edge and the config to one application per route.
87
+
88
+ > A `hosts`-scoped application covers only those hostnames. The same routes on the Worker's other hostnames stay reachable through the normal cookie, bearer, and API-key lanes. If a route must never be reachable without Access, scope it by `paths`, or cover the whole Worker.
89
+
90
+
91
+ A host in `hosts` that the config does not claim never reaches the Access check. The [host allowlist](/configure/domains#host-allowlist) 404s it first.
92
+
93
+ ## Identity mapping
94
+
95
+ Access identities map to **existing** Better Auth users. Nothing is provisioned. Create the user first, and set `user.role` (admin plugin) unless `groups` supplies the role.
96
+
97
+ ### People
98
+
99
+ Access puts the IdP email in the `email` claim. The Worker looks up the user with that email (lowercased). The claim is only as trustworthy as the identity provider behind the Access policy: an IdP that lets users set their own email can sign in as any account. Allow only IdPs that verify email ownership. It refuses the user if the account's email is not verified (`emailVerified`), or if the user is banned. Without the verification check, anyone who pre-registers an unverified account with a colleague's address would inherit that colleague's Access identity. `userRole` is the user's `user.role` (default `'user'`), and it must be in `roles`.
100
+
101
+ ### Groups
102
+
103
+ Set `groups` to take the role from the IdP instead of `user.role`:
104
+
105
+ ```ts
106
+ cloudflareAccess: {
107
+ teamDomain: 'acme.cloudflareaccess.com',
108
+ aud: 'd8a1f0c7e2b3a4958677d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3',
109
+ paths: ['/api/v1/staff'],
110
+ roles: ['admin', 'sysadmin'],
111
+ groups: { 'it-admins': 'sysadmin', 'event-staff': 'admin' },
112
+ }
113
+ ```
114
+
115
+ The Worker reads groups from the token's `custom.groups` claim. Access includes it only when you add `groups` as a custom OIDC claim or SAML attribute on the identity provider. The first `groups` entry the caller holds, in declaration order, sets `userRole`. A group key that is all digits (`'42'`) fails the compile, because JavaScript enumerates integer-like keys first and would reorder the priority. Every `groups` value must also be in `roles`, or the compile fails. When `groups` is set, a caller who holds none of the listed groups, or whose token lacks the claim, is refused with **403**. Access trims `custom` claims to about 1 KB, so keep group names short.
116
+
117
+ > With `groups`, whoever administers groups in your identity provider controls these roles. The `custom` claim is best-effort, and Access may trim it. Use `groups` only with an IdP where users cannot edit their own group membership or attributes.
118
+
119
+
120
+ ### Service tokens
121
+
122
+ A request with `CF-Access-Client-Id` and `CF-Access-Client-Secret` reaches the Worker with a token that has no `email`. Its `common_name` is the Client ID (`<id>.access`) and its `sub` is empty. Map each Client ID to the email of the Better Auth user it acts as:
123
+
124
+ ```ts
125
+ serviceTokens: { '88bf3b6d86161464f6509f7219099e57.access': 'deploy-bot@example.com' },
126
+ ```
127
+
128
+ The token then authenticates as that user, and the user's `user.role` must be in `roles`. Unlisted Client IDs, and a `common_name` that does not end in `.access`, are refused. Keys in `serviceTokens` must have that form, or the compile fails. The email-verification check does not apply, because the mapping is your own config. `groups` does not apply to service tokens.
129
+
130
+ ### Organizations
131
+
132
+ Access carries no active-organization selection. With `features.pinnedOrganizationId`, an Access caller who is a member of the pinned org gets `activeOrgId` and the member role (expanded through `auth.roleHierarchy`). Without a pinned org, an Access caller has no active org. `userRole` gates and the sysadmin bypass still apply.
133
+
134
+ ## Per-environment values
135
+
136
+ `teamDomain` and `aud` each accept `{ env: 'VAR_NAME' }`. The Worker reads the var at request time, so every [named environment](/configure/domains#named-environments) can point at its own Access team from one bundle. This is how a client's own Access fronts their private deployment:
137
+
138
+ ```ts title="quickback.config.ts"
139
+ export default defineConfig({
140
+ // ...
141
+ auth: {
142
+ cloudflareAccess: {
143
+ teamDomain: { env: 'CF_ACCESS_TEAM' },
144
+ aud: { env: 'CF_ACCESS_AUD' },
145
+ paths: ['/api/v1/staff'],
146
+ roles: ['admin'],
147
+ },
148
+ },
149
+ environments: {
150
+ 'client-a': {
151
+ domains: { api: 'api.client-a.example' },
152
+ worker: {
153
+ vars: {
154
+ CF_ACCESS_TEAM: 'client-a.cloudflareaccess.com',
155
+ CF_ACCESS_AUD: '4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2',
156
+ },
157
+ },
158
+ },
159
+ },
160
+ });
161
+ ```
162
+
163
+ An unset var, or a team domain that is not `<team>.cloudflareaccess.com`, gives **500 `CF_ACCESS_MISCONFIGURED`**. It never gives a pass.
164
+
165
+ ## Browser requests and CSRF
166
+
167
+ Access adds the assertion to every browser request that carries its `CF_Authorization` cookie, so the credential is ambient. A request from a person passes this check:
168
+
169
+ | Request carries | Accepted when |
170
+ | --- | --- |
171
+ | `Origin` (any method, reads included) | it equals the request's own origin, or is an exact `https://` origin listed in `BETTER_AUTH_URL` or the `CF_ACCESS_TRUSTED_ORIGINS` Worker var |
172
+ | no `Origin`, `Sec-Fetch-Site` (mutations only) | `Sec-Fetch-Site` is `same-origin` or `none` |
173
+ | neither header | always: a non-browser caller such as `cloudflared access curl` |
174
+
175
+ Anything else gets **403 `CSRF_ORIGIN_REJECTED`**. Service-token requests skip this check. Refusing reads too means a page on another origin cannot read Access-gated data with the user's credential, whatever CORS headers the response would have carried.
176
+
177
+ - `CF_ACCESS_TRUSTED_ORIGINS` is a comma-separated list of exact `https://` origins, set per environment. It is empty by default, which fails closed. Use it for a browser app on another host that calls the API inside the Access scope, such as an Access-fronted console Worker that proxies the API. Its pages run with the user's Access credential, so list only origins Access itself fronts.
178
+ - The compile-time `trustedOrigins` (and the derived domains) are **not** trusted here: the bundle is shared by every environment. `EXTRA_APP_HOSTS` is not trusted either, although Better Auth and CORS trust it.
179
+ - An untrusted sibling subdomain is refused, even though the browser reports it `same-site`. It carries `CF_Authorization` too.
180
+ - `http://` origins never pass, and neither do loopback hosts (`localhost`, `127.x`, `[::1]`, `[::]`, IPv4-mapped loopback), even as `https://`. An empty or `null` `Origin` is refused.
181
+
182
+ ## Operator MFA
183
+
184
+ `auth.operatorMfa` downgrades operator sessions that lack a second factor. It does not apply to the Access lane. Enforce MFA in the Access policy instead.
185
+
186
+ ## Setting up the Access application
187
+
188
+ 1. In Zero Trust, create a self-hosted application for the hostname (and path) you scoped.
189
+ 2. Copy its **Application Audience (AUD) tag** into `aud`.
190
+ 3. Set `teamDomain` to your team domain, `<team>.cloudflareaccess.com`.
191
+ 4. For machines, create a service token and add a **Service Auth** policy. Then map its Client ID in `serviceTokens`.
@@ -280,7 +280,7 @@ Each target's `BETTER_AUTH_URL` also defaults to the hostname it claims (unified
280
280
 
281
281
  ## Host allowlist
282
282
 
283
- A Worker is also reachable at `<name>.<account>.workers.dev` (each environment must set `workersDev: true`), which would put the whole API on an origin the config never named — outside your custom-domain TLS policy, WAF rules, and CSP origins. So the generated worker answers only on hostnames the config claims: every generated route (`domain`, `api.domain`, `auth.domain`, `cms.domain`, `account.domain`, `account.adminDomain`, `apps.*` domains and aliases, explicit `providers.runtime.config.routes`) plus every hostname a named environment claims under `environments.<name>.domains`. Any other host gets `404 NOT_FOUND` before routing:
283
+ A Worker is also reachable at `<name>.<account>.workers.dev` unless its environment sets `workersDev: false` (each environment sets `workersDev` explicitly; `false` needs a custom domain or route), which would put the whole API on an origin the config never named — outside your custom-domain TLS policy, WAF rules, and CSP origins. So the generated worker answers only on hostnames the config claims: every generated route (`domain`, `api.domain`, `auth.domain`, `cms.domain`, `account.domain`, `account.adminDomain`, `apps.*` domains and aliases, explicit `providers.runtime.config.routes`) plus every hostname a named environment claims under `environments.<name>.domains`. Any other host gets `404 NOT_FOUND` before routing:
284
284
 
285
285
  ```bash
286
286
  curl https://my-api.my-account.workers.dev/health # → 404 {"code":"NOT_FOUND","layer":"route","host":"…"}
@@ -663,7 +663,7 @@ Quickback's default model assumes every CMS user belongs to at least one organiz
663
663
 
664
664
  - **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"appmanager"` — appmanagers keep platform control-plane access (Better Auth admin surfaces, organization and user management, support tooling — but NOT the CMS), while sysadmins get true cross-tenant data access. `ADMIN` is now a rejected legacy pseudo-role; use `userRole: ["appmanager"]` for control-plane gates and `roles: ["SYSADMIN"]` for cross-tenant access.
665
665
  - **Firewall**: every `buildFirewallConditions()` emits an `if (ctx.userRole === "sysadmin") return undefined` (or just the soft-delete predicate when present) at the top, so sysadmins see every tenant's rows. See [Firewall escape hatch](/define/firewall#sysadmin-escape-hatch).
666
- - **Org listing**: a `GET /auth/v1/admin/list-organizations` endpoint selects directly from the auth-schema `organization` table — every row, every tenant. Sits under Better Auth's admin URL namespace (sibling of `/auth/v1/admin/list-users`) so the URL shape matches BA convention; the handler is Quickback-emitted and gated to `user.role === "sysadmin"` only. For the membership-bound caller's-orgs listing, use BA's own `/auth/v1/organization/list`.
666
+ - **Org listing**: `GET /api/v1/operator/organizations` selects directly from the auth-schema `organization` table — every row, every tenant. Quickback-emitted and gated to `user.role` `appmanager` or `sysadmin`. It sat at `/auth/v1/admin/list-organizations` before 0.72 ([Moved routes](/api#moved-routes-072)). For the membership-bound caller's-orgs listing, use BA's own `/auth/v1/organization/list`.
667
667
  - **CMS SPA**: when the user is a sysadmin, the header switcher loads from the cross-tenant endpoint, defaults to "All organizations" (which omits `?organizationId=` and reaches the firewall escape), and pins selected tenants via `?organizationId=` on every API call. Org admins keep the existing membership-based switcher.
668
668
  - **CMS gate**: `cms.access: "sysadmin"` (the default) admits the `sysadmin` tier only; `cms.access: "member"` also admits any caller with an organization membership. `appmanager` opens the CMS in neither mode — see [Access gate](/ui/admin#access-gate).
669
669
 
@@ -814,7 +814,9 @@ For the Cloudflare provider (the default), the compiler automatically:
814
814
 
815
815
  …whenever any auth surface needs to send mail — `emailAndPassword.enabled`, the `emailOtp` / `magicLink` / `organization` plugins — or you set the top-level `email: {…}` config. You don't need to add `bindings.sendEmail` by hand for the standard cases.
816
816
 
817
- > **Cloudflare Email Routing setup is required.** The binding alone does not deliver mail. Enable Email Routing on the sending zone and add at least one verified destination address ([Cloudflare docs](https://developers.cloudflare.com/email-routing/get-started/)). Otherwise sends fail at runtime even with the binding present and the `/auth/v1/ses/status` check passing locally.
817
+ The public SES plugin readiness endpoint returns only `emailConfigured` and `provider`; sender addresses and region are not disclosed. Use `/api/v1/auth/email-status` for the provider-independent readiness check.
818
+
819
+ > **Cloudflare Email Routing setup is required.** The binding alone does not deliver mail. Enable Email Routing on the sending zone and add at least one verified destination address ([Cloudflare docs](https://developers.cloudflare.com/email-routing/get-started/)). Otherwise sends fail at runtime even with the binding present and the `/api/v1/auth/email-status` check passing locally.
818
820
 
819
821
  ## Multi-Domain Example
820
822
 
@@ -18,6 +18,7 @@ providers: {
18
18
 
19
19
  | Option | Type | Description |
20
20
  |--------|------|-------------|
21
+ | `accountId` | `string` | Emits top-level `account_id` in `wrangler.toml`. 32 lowercase hex characters, or the compile fails. A named target in another account sets `environments.<name>.accountId` — see [A target in another Cloudflare account](/platform/database/d1#a-target-in-another-cloudflare-account-accountid). |
21
22
  | `compatibilityDate` | `string` | Emits Cloudflare `compatibility_date` in `wrangler.toml`. |
22
23
  | `placement.mode` | `"smart" \| "standard"` | Emits Cloudflare's `[placement]` block. Mutually exclusive with `placement.region`. |
23
24
  | `placement.region` | `string` | Placement hint, `"<cloud>:<region>"` (e.g. `"aws:us-east-2"`): runs the Worker next to a single-region database instead of next to the user. Set it to your Postgres region. Any other `placement` key is a compile error. Named environments emit it per target; override with `environments.<name>.worker.placement`. |
@@ -368,7 +369,7 @@ When `features: ["organizations"]` is set in your config, the compiler automatic
368
369
  | `admin` | Admin panel access |
369
370
  | `apiKey` | API key authentication |
370
371
  | `anonymous` | Anonymous sessions |
371
- | `upgradeAnonymous` | Convert anonymous to full accounts |
372
+ | `upgradeAnonymous` | **Deprecated.** Convert anonymous to full accounts. Lets an anonymous user claim an email, so it is refused with invite-only or allowed-domain signup. Sign guests in with `emailOtp`, `magicLink`, or `passkey` instead |
372
373
  | `twoFactor` | Two-factor authentication |
373
374
  | `passkey` | WebAuthn passkey login |
374
375
  | `magicLink` | Email magic link login |
@@ -115,3 +115,6 @@ table an organization column if a tenant's purge should cover it.
115
115
 
116
116
  The purge writes no security-audit row of its own. Log the call from your
117
117
  action if you need one.
118
+
119
+ `tenancy.purge` is refused with [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases)
120
+ (`TENANCY_PURGE_DO`): there a tenant is one object, and deleting it ships with backups.