@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
@@ -29,7 +29,8 @@ src/
29
29
  │ └── .quickback/
30
30
  │ └── define-action.ts # Typed per-feature `defineAction` helper
31
31
  ├── routes/
32
- │ └── {feature}.ts # Mount re-export consumed by src/index.ts
32
+ │ ├── {feature}.ts # Mount re-export consumed by src/index.ts
33
+ │ └── __legacy-{feature}.routes.ts # Legacy forwards of namespace-claimed tables/actions (when `legacy` is set)
33
34
  ├── lib/
34
35
  │ ├── auth.ts # Better Auth instance & config
35
36
  │ ├── auth.schema-gen.ts # Copy of auth.ts with hooks/email templates stubbed — what `better-auth generate` reads
@@ -41,6 +42,7 @@ src/
41
42
  │ ├── services.ts # Service layer
42
43
  │ ├── q.ts # Generated Drizzle query-operator namespace for actions
43
44
  │ ├── audit-wrapper.ts # Stamps the managed audit columns on write
45
+ │ ├── legacy-forward.ts # Legacy-forward runtime: org-only check, instance pre-check, in-process dispatch, deprecation headers (when `legacy` is set)
44
46
  │ └── security-audit.ts # Unsafe cross-tenant audit logger (when needed)
45
47
  └── middleware/
46
48
  ├── auth.ts # Auth context middleware
@@ -193,6 +195,8 @@ than replaced:
193
195
  compile; scripts and fields the compiler does not emit are kept. Because owned
194
196
  scripts converge, a hand-deleted `db:migrate:auth:*` step comes back — declare
195
197
  [`authMigrations: 'external'`](/configure/providers#cloudflare-d1) instead.
198
+ A package the compiler owns in `dependencies` or `devDependencies` is removed
199
+ from the other field, so a stale pin cannot shadow the compiler's version.
196
200
  - **`.gitignore`** — a union: your entries stay, missing compiler entries are
197
201
  appended.
198
202
  - **`README.md`** — written once; an existing README is never touched.
@@ -391,7 +395,10 @@ environments: {
391
395
  ```
392
396
 
393
397
  Omitting `filesWorker.domain` emits `routes = []` for that target — the explicit
394
- workers.dev-only opt-out, so it cannot inherit a sibling's hostname.
398
+ workers.dev-only opt-out, so it cannot inherit a sibling's hostname. The files
399
+ Worker's top-level `name` is an inert placeholder, `<name>-files-unselected`,
400
+ which no target may use. Without it, Wrangler would name a bare deploy from
401
+ `package.json`, which is the production edge.
395
402
 
396
403
  ### Webhooks
397
404
 
@@ -36,7 +36,7 @@ When `auth.admin` is `false` (the default), the admin surface does not exist for
36
36
  - **Create an organization** — you name the **owner**; the operator creating it is deliberately not seated (see below)
37
37
  - **Seat, re-role and remove members** — manage a tenant's roster without joining it
38
38
 
39
- These run on `/auth/v1/admin/*`, emitted by Quickback because Better Auth's organization plugin cannot serve them: every one of its endpoints resolves through the *caller's* membership, and an operator administers organizations it does not belong to.
39
+ These run on `/api/v1/operator/organizations` (under `/auth/v1/admin/*` before 0.72; see [Moved routes](/api#moved-routes-072)), emitted by Quickback because Better Auth's organization plugin cannot serve them: every one of its endpoints resolves through the *caller's* membership, and an operator administers organizations it does not belong to. Put them behind [Cloudflare Access](/configure/cloudflare-access#the-operator-plane) with one path rule.
40
40
 
41
41
  > **Users sign themselves up.** Self-serve signup stays on — a new account simply has no organization, and lands on a screen saying so until someone invites or seats them. What operators control is *organizations*, not accounts.
42
42
 
@@ -56,7 +56,7 @@ The admin panel is restricted to platform roles on the Better Auth user record:
56
56
  >
57
57
  > Equal tier is allowed, so an appmanager can still make another appmanager (the example below). Only a `sysadmin` can grant `sysadmin`.
58
58
  >
59
- > `set-organization-member` refuses to seat its caller with `403 OPERATOR_SELF_SEAT`: operators are never seated by their own control-plane calls.
59
+ > Seating a member (`PUT /api/v1/operator/organizations/:id/members/:userId`) refuses to seat its caller with `403 OPERATOR_SELF_SEAT`: operators are never seated by their own control-plane calls.
60
60
 
61
61
 
62
62
  To grant operator access to a user:
@@ -89,7 +89,7 @@ providers: {
89
89
  },
90
90
  ```
91
91
 
92
- With it on, an `appmanager` or `sysadmin` whose session was **not** established by a passkey assertion or a two-factor verification is treated as a plain `user` for that request. Every operator surface refuses with `403 MFA_REQUIRED`: the CMS and `/api/v1/schema`, the `/auth/v1/admin/*` operator routes, Better Auth's own admin endpoints (`list-users`, `set-role`, `ban-user`), and the sysadmin cross-tenant bypass. The Account UI keeps working, so the enrolment path is short:
92
+ With it on, an `appmanager` or `sysadmin` whose session was **not** established by a passkey assertion or a two-factor verification is treated as a plain `user` for that request. Every operator surface refuses with `403 MFA_REQUIRED`: the CMS and `/api/v1/schema`, the `/api/v1/operator/*` routes, Better Auth's own admin endpoints (`list-users`, `set-role`, `ban-user`), and the sysadmin cross-tenant bypass. The Account UI keeps working, so the enrolment path is short:
93
93
 
94
94
  1. Sign in with a password (or magic link / OTP) as usual.
95
95
  2. Register a passkey at `/account/passkeys/setup`.
@@ -97,6 +97,8 @@ With it on, an `appmanager` or `sysadmin` whose session was **not** established
97
97
 
98
98
  How it works: the compiler adds a `session.amr` column (RFC 8176, *Authentication Methods Reference*) and a `session.create.before` hook that stamps `passkey` when the session comes from `/passkey/verify-authentication` and `mfa` when it comes from `/two-factor/verify-*`. Nothing else sets it, and it is not client-settable. The auth middleware reads it on the session lane and copies it into the JWT fast-path claims, so bearer callers are gated identically.
99
99
 
100
+ Cloudflare Access is recommended additionally for `/api/v1/operator`. It does not replace `operatorMfa`: Better Auth admin endpoints and the other operator powers still need the application second factor. Configuring Access with `operatorMfa` off emits a compile warning.
101
+
100
102
  Things to know:
101
103
 
102
104
  - **Requires `passkey` or `twoFactor`.** The compile fails otherwise: without a second factor to enrol, every operator would be locked out.
@@ -142,6 +142,10 @@ before calling `quickback/hooks/resolve-oauth-context.ts`. Use this trusted
142
142
  server hook when tenant selection cannot be derived solely from the session's
143
143
  active organization.
144
144
 
145
+ It never runs for an [instance-bound token](/define/scopes#instance-bound-oauth-tokens)
146
+ (audience = a scope kind's resource): that principal is confined to one
147
+ instance and gets no tenant context.
148
+
145
149
  ```ts title="quickback/hooks/resolve-oauth-context.ts"
146
150
  import type { OAuthContextResolver } from '@quickback/compiler';
147
151
 
@@ -328,7 +332,7 @@ type HookCtx = {
328
332
  };
329
333
  ```
330
334
 
331
- `authDb` is the load-bearing piece: hooks must write to the auth DB via Drizzle directly. See the [CSRF caveat](#csrf-caveat-server-side-org-create) below. `authSchema` is the namespace export of the generated auth schema module; destructure the tables you need.
335
+ `authDb` is the Drizzle connection to the auth DB. Read through it freely; for writes, prefer Better Auth's API (`auth.api.*`; `ctx.auth` in actions), which runs Better Auth's own hooks and revokes sessions. A direct insert, update, or delete on a Better Auth table is flagged [`ACTION_AUTH_DB_WRITE`](/define/diagnostics#action_auth_db_write) — in `hooks/` as a **warning**, never a compile error. Where no endpoint fits, such as the server-side org create below (see the [CSRF caveat](#csrf-caveat-server-side-org-create)), keep the write and mark it with `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>`. `authSchema` is the namespace export of the generated auth schema module; destructure the tables you need.
332
336
 
333
337
  This injection is unique to account hooks. Actions reach AUTH_DB via `c.get("authDb")` ([Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb)). Trigger handlers on a table file get neither — use `ctx` for the acting user, and do not import `../../auth/schema` from the table file.
334
338
 
@@ -393,6 +397,7 @@ export default async (user, { authDb, authSchema }) => {
393
397
  .where(eq(organization.id, orgId));
394
398
  if (existing.length > 0) return;
395
399
 
400
+ // quickback-allow ACTION_AUTH_DB_WRITE: server-side org create has no Origin for auth.api.createOrganization
396
401
  await authDb.insert(organization).values({
397
402
  id: orgId,
398
403
  name: `${user.name ?? 'Personal'} Workspace`,
@@ -400,6 +405,7 @@ export default async (user, { authDb, authSchema }) => {
400
405
  createdAt: new Date(),
401
406
  });
402
407
 
408
+ // quickback-allow ACTION_AUTH_DB_WRITE: membership for the org created above, same reason
403
409
  await authDb.insert(member).values({
404
410
  id: crypto.randomUUID(),
405
411
  userId: user.id,
@@ -430,6 +436,7 @@ export default async (newSession, { authDb, authSchema }) => {
430
436
 
431
437
  if (memberships.length === 0) return;
432
438
 
439
+ // quickback-allow ACTION_AUTH_DB_WRITE: setActiveOrganization needs a request; this hook has none
433
440
  await authDb
434
441
  .update(session)
435
442
  .set({ activeOrganizationId: memberships[0].organizationId })
@@ -458,7 +465,7 @@ The compiler-generated wrapper merges your `data` onto the original entity, so y
458
465
 
459
466
  `POST /auth/v1/organization/create` (and Better Auth's `auth.api.createOrganization(...)` server helper) require an `Origin` header. A hook running inside `databaseHooks.user.create.after` is server-side — there is no incoming request, so no `Origin`. Calling those APIs from a hook may also validate `Origin` internally and reject.
460
467
 
461
- **The only safe path is direct Drizzle writes via `authDb`.** Treat the org/member tables as your source of truth and let the SPA call the BA API for user-initiated org creation.
468
+ **Here, direct Drizzle writes via `authDb` are the working path.** Mark each with `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>` so the warning records why. Treat the org/member tables as your source of truth and let the SPA call the BA API for user-initiated org creation.
462
469
 
463
470
  ## Generated output
464
471
 
@@ -120,7 +120,7 @@ export default defineConfig({
120
120
  ```
121
121
 
122
122
  When you run `quickback build`, the CLI:
123
- 1. Builds the CMS SPA from source and places assets in `src/apps/cms/`
123
+ 1. Copies the prebuilt CMS SPA into `src/apps/cms/` (the compiler ships one generic bundle; per-project settings reach it at serve time)
124
124
  2. Adds `[assets]` config to `wrangler.toml` with `run_worker_first = true`
125
125
  3. Generates Worker routing to serve the CMS SPA
126
126
 
@@ -139,8 +139,8 @@ This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `
139
139
  CMS access defaults to `access: "sysadmin"` — only `user.role === "sysadmin"` (the cross-tenant data-plane tier) can use `/cms/*`. Set `access: "member"` to also admit anyone holding an organization membership. `user.role === "appmanager"` opens the CMS in neither mode: it is the control-plane tier and belongs at `/account/admin`. The gate is enforced at multiple layers:
140
140
 
141
141
  - **Account UI** hides the "Go to CMS" button for callers outside those roles.
142
- - **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-operator. A non-operator who types the CMS URL directly cannot load the app.
143
- - **`/api/v1/schema`** returns `403 Platform operator access required` to callers outside those roles, so schema metadata can't be scraped by hitting the API directly.
142
+ - **CMS SPA shell** — the Worker redirects unauthenticated requests to login. Sign-in is the only shell-level gate; the app itself is a generic bundle. For a caller `/api/v1/schema` would admit, the Worker also inlines the schema registry in the shell as a non-executing `<script type="application/json" id="__qb-cms-bootstrap">` block, so the CMS starts without fetching it. The block uses the same admission check as `/api/v1/schema`, so it never carries anything that route would refuse. With [Cloudflare Access](/configure/cloudflare-access), it is inlined only when `/api/v1/schema` needs no Access application or the same one the shell request passed. The CMS shell is served `Cache-Control: private, no-store`.
143
+ - **`/api/v1/schema`** returns `401 AUTH_MISSING` to anonymous callers `403 CMS_ACCESS_DENIED` (naming the role required) to signed-in callers outside those roles, and `403 MFA_REQUIRED` to an operator whose session lacks the second factor `auth.operatorMfa` demands, so schema metadata can't be scraped by hitting the API directly.
144
144
  - **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
145
145
  - **In-SPA screen** — a signed-in caller who isn't admitted is served the shell and shown a screen naming what they'd need. There is no wrong-role redirect.
146
146
 
@@ -217,7 +217,7 @@ The shell is served to any signed-in caller, and the SPA resolves one of six sta
217
217
  | State | Screen |
218
218
  |-------|--------|
219
219
  | Not signed in | Redirect to sign-in (the one redirect that remains — it is where you were going anyway) |
220
- | `sysadmin`, no tenant chosen | Tenant picker, filterable, with **All organizations** as a first-class choice |
220
+ | `sysadmin`, no tenant chosen | Tenant picker (from `GET /api/v1/operator/organizations`), filterable, with **All organizations** as a first-class choice |
221
221
  | `sysadmin`, tenant chosen | The CMS, scoped to that tenant |
222
222
  | `appmanager`, `access: "sysadmin"` | *"The CMS shows organization data"* → **Go to admin** |
223
223
  | Anyone else, `access: "sysadmin"` | *"This CMS is restricted"* — names the config value that would admit them |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.70.45",
3
+ "version": "0.72.3",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -303,6 +303,70 @@ throw new ActionError("Not enough balance", "INSUFFICIENT_FUNDS", 400, { availab
303
303
 
304
304
  Constructor: `(message, code, statusCode = 400, details?)`. Do **NOT** throw Hono's `HTTPException` — it isn't unwrapped and surfaces as a 500 `ACTION_EXECUTION_FAILED`. Returning `c.json({...}, 400)` directly also works (the executor receives `c`).
305
305
 
306
+ ## Custom CMS pages (`definePage`)
307
+
308
+ Reach for a custom page before building a separate admin app. The CMS gives every table a list and record view. When the job is *working across two tables* (reconciling, matching, assigning, triaging), one `definePage()` file gives the operator a split-panel screen with drag-and-drop, scored match suggestions, and a button that runs a real action. You write no UI code.
309
+
310
+ Good fits: bank transactions ↔ ledger entries, applicants ↔ open roles, support tickets ↔ agents, imported rows ↔ existing records, invoices ↔ payments.
311
+
312
+ ```ts
313
+ // quickback/features/banking/pages/bank-reconciliation.ts
314
+ import { definePage } from "@quickback/compiler";
315
+
316
+ export default definePage({
317
+ slug: "bank-reconciliation", // lowercase, digits, hyphens
318
+ title: "Bank Reconciliation",
319
+ feature: "banking",
320
+ access: { roles: ["owner", "admin"] },
321
+ dataSources: {
322
+ bank: { table: "bankTransaction", defaultFilters: { status: "pending" }, displayColumns: ["date", "description", "amount"] },
323
+ ledger: { table: "ledgerEntry", defaultSort: { field: "date", order: "desc" }, displayColumns: ["date", "memo", "amount"] },
324
+ },
325
+ layout: {
326
+ type: "split-panel",
327
+ panels: [
328
+ { id: "bank", title: "Bank", dataSource: "bank", position: "left", features: ["drag-source"] },
329
+ { id: "ledger", title: "Ledger", dataSource: "ledger", position: "right", features: ["drop-target"] },
330
+ ],
331
+ },
332
+ matching: {
333
+ enabled: true,
334
+ confidenceThreshold: 0.5,
335
+ rules: [
336
+ { name: "Amount", weight: 0.5, condition: { left: "bank.amount", right: "ledger.amount", operator: "abs-equals" } },
337
+ { name: "Date", weight: 0.3, condition: { left: "bank.date", right: "ledger.date", operator: "within-days", value: 7 } },
338
+ { name: "Memo", weight: 0.2, condition: { left: "bank.description", right: "ledger.memo", operator: "fuzzy-match" } },
339
+ ],
340
+ },
341
+ pageActions: {
342
+ reconcile: {
343
+ table: "bankTransaction", action: "reconcile", label: "Reconcile",
344
+ confirm: "Match this transaction to the selected entry?",
345
+ inputMapping: { transactionId: "bank.$id", ledgerEntryId: "ledger.$id" },
346
+ },
347
+ },
348
+ });
349
+ ```
350
+
351
+ How to craft one:
352
+
353
+ 1. **Write the action first.** A page only *calls* actions; it never writes data itself. Define `actions/reconcile.ts` on the target table, with its own `access`, guards, and input schema, then map page fields into its input with `inputMapping` (`"<dataSource>.$<field>"`; `$id` is the record id). Dropping a row from the drag-source panel onto a row in the drop-target panel opens the first page action's dialog, with both records as context.
354
+ 2. **Narrow each panel.** `defaultFilters` (e.g. `status: "pending"`) keeps the panels to the work still to do, and `displayColumns` keeps them readable (the default is just `id`).
355
+ 3. **Weight the match rules to sum to 1.** Each weight and `confidenceThreshold` must be within 0–1. Operators: `abs-equals` (amounts with opposite signs), `within-days` (`value` = max days, default 7), `fuzzy-match` (word overlap). The score is the weighted average; suggestions below the threshold are hidden.
356
+ 4. **`access.roles` on a page only controls who sees it** (it's checked in the browser). Panels read through each table's normal list endpoint, and buttons call each action's endpoint, so the tables' Firewall/Access/Masking rules still decide what data comes back and what can change. Never rely on page `access` to hide data.
357
+
358
+ One page per file in `features/<feature>/pages/`; the compiler validates slugs, data-source references and weights at compile time. Only `split-panel` exists as a layout today. Details: `quickback docs ui/admin/pages`.
359
+
360
+ ## Clients that stay fast on slow networks
361
+
362
+ Each round trip costs ~150 ms on a slow phone connection. When you build or change the client that calls the API, count the requests it makes before the first useful paint:
363
+
364
+ - **One request per screen.** A screen that needs more than two lists gets a `defineBundle`, not several list calls (`quickback docs define/bundles`). Never fetch records one at a time in a loop from the client. Use `?include=` for parents, and a filtered list for children.
365
+ - **Start fetches in the route, not the component.** Fetch in the router's `loader` (TanStack Router: `loader: () => queryClient.ensureQueryData(...)`), so the request starts during navigation instead of after the component mounts. Set `defaultPreload: 'intent'` so hovering or focusing a link starts its code and data early.
366
+ - **Run independent awaits in parallel.** In actions and hooks, start unrelated lookups together with `Promise.all([...])`. Two sequential `await`s that don't depend on each other add a full round trip each time.
367
+ - **Link previews read only the HTML.** iMessage, Slack, and similar bots never run JavaScript. A prebuilt `apps.<name>` SPA must put its `<title>` and `og:*` meta tags in `index.html` itself.
368
+ - **Don't trust the User-Agent for routing.** Anyone can fake it, and it also matches Lighthouse. If bots really must get a different response, use Cloudflare's verified-bot signal: `request.cf.botManagement.verifiedBot` on Bot Management plans, or the `cf.client.bot` field in a WAF rule.
369
+
306
370
  ## Reaching auth tables (org members, users)
307
371
 
308
372
  The scoped feature `db` never includes Better Auth tables — that is by design.
@@ -327,6 +327,77 @@ When validation fails you get an RFC 9457 Problem Details document
327
327
  Malformed JSON returns `INVALID_JSON` (400); a body over the 1 MiB cap returns
328
328
  `PAYLOAD_TOO_LARGE` (413).
329
329
 
330
+ ## Paginated actions
331
+
332
+ An action that declares [`pagination`](/define/actions/defining#paginated-actions-pagination)
333
+ reads the collection-read parameter names and answers the collection-read
334
+ envelope. Forward only; one base table.
335
+
336
+ ### Request
337
+
338
+ | Parameter | Default | Description |
339
+ |-----------|---------|-------------|
340
+ | `limit` | the declared default (`50`) | Page size, clamped to `[1, max]` (`100` unless declared) |
341
+ | `starting_after` | — | `pagination.nextCursor` of the previous page. Omit for the first page |
342
+ | `sort` | the declared default | One of the action's named sorts |
343
+
344
+ A GET action reads them from the query string; any other method from the
345
+ JSON body (declare them with `pageInput()` so the body schema keeps them).
346
+ The action's own fields travel beside them and are part of the cursor's
347
+ context.
348
+
349
+ ```bash
350
+ GET /api/v1/messages/list?conversationId=c_123&limit=50
351
+ GET /api/v1/messages/list?conversationId=c_123&limit=50&starting_after=eyJ2IjoyLCJjIjoi…
352
+ ```
353
+
354
+ ### Response
355
+
356
+ ```json
357
+ {
358
+ "data": [ /* rows, masked for the caller */ ],
359
+ "pagination": {
360
+ "count": 50,
361
+ "pageSize": 50,
362
+ "hasMore": true,
363
+ "nextCursor": "eyJ2IjoyLCJjIjoi…",
364
+ "sort": "recent"
365
+ }
366
+ }
367
+ ```
368
+
369
+ - `count` — rows on this page; `pageSize` — the resolved limit
370
+ - `hasMore` — from a `limit + 1` probe, so a final page that exactly fills
371
+ the limit reports `false`
372
+ - `nextCursor` — pass back as `starting_after`; `null` on the final page
373
+ - `sort` — the named sort the page was produced under
374
+
375
+ An action may return domain fields beside `data` and `pagination`; a
376
+ non-paginated action's response is unchanged.
377
+
378
+ ### Cursors
379
+
380
+ A cursor is opaque and versioned. It carries the boundary row's sort-key
381
+ values and a hash of the action, table, sort and input it was minted for —
382
+ it is encoded, not encrypted, and it never authorizes: every page re-runs
383
+ access, the table firewall, soft-delete filtering and masking, so a cursor
384
+ from another caller or tenant yields that caller's own rows, nothing more.
385
+ A sort over a masked column is only offered to callers who may see it.
386
+
387
+ Validation failures are RFC 9457 problems, never a silent restart at page one:
388
+
389
+ | Status | `code` | When |
390
+ |--------|--------|------|
391
+ | `400` | `PAGINATION_INVALID_CURSOR` | Malformed, truncated, over 2048 characters, wrong version, wrong number of values, or a value of the wrong type |
392
+ | `400` | `PAGINATION_CURSOR_MISMATCH` | A cursor minted for another action, table, sort or input |
393
+ | `400` | `PAGINATION_INVALID_SORT` | `sort` is not one of the action's named sorts |
394
+ | `403` | `PAGINATION_SORT_NOT_VISIBLE` | A sort key is masked for this caller |
395
+
396
+ Pages are not a snapshot. A row inserted, updated or deleted between two
397
+ requests can shift the boundary: under a mutable sort a row may appear twice
398
+ or be missed. Reconnect checkpoints and change history are a
399
+ [realtime](/platform/realtime) concern, not a pagination one.
400
+
330
401
  ## Response Types
331
402
 
332
403
  Actions support three response types:
@@ -466,9 +537,9 @@ await db.update(applications).set({ deletedAt: now, modifiedAt: now })
466
537
 
467
538
  | Status | Description |
468
539
  |--------|-------------|
469
- | `400` | Invalid input / validation error (also `GUARD_FIELD_PROTECTED` for direct protected-field writes) |
540
+ | `400` | Invalid input / validation error (also `GUARD_FIELD_PROTECTED` for direct protected-field writes; `PAGINATION_INVALID_CURSOR`, `PAGINATION_CURSOR_MISMATCH`, `PAGINATION_INVALID_SORT` on [paginated actions](#paginated-actions)) |
470
541
  | `401` | Not authenticated |
471
- | `403` | Access role check failed (`ACCESS_ROLE_REQUIRED`) |
542
+ | `403` | Access role check failed (`ACCESS_ROLE_REQUIRED`); a masked sort key on a paginated action (`PAGINATION_SORT_NOT_VISIBLE`) |
472
543
  | `404` | Record not found (record-based actions) |
473
544
  | `409` | Record is in the wrong state for this action — `access.record` predicate or `transition` policy failed (`ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`) |
474
545
  | `500` | Handler execution error |
@@ -314,9 +314,11 @@ transport with Neon's hyperdrive mode.
314
314
  | Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
315
315
  |----------|----------|-----------|----------------------|----------|
316
316
  | `PATCH /batch` (update) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
317
+ | `PATCH /batch` (update) | [tenant table](/configure/tenant-databases) (`tenancy.isolation: 'durable-object'`) | `true` | `true` | `ctx.storage.transaction()` in the organization's Durable Object wraps the loop. Any failure rolls back ALL writes in the batch. |
317
318
  | `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
318
319
  | `PATCH /batch` (update) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Fail-fast loop without rollback — the driver has no `db.transaction`. Records before the failure stay committed. |
319
320
  | `PUT /batch` (upsert) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
321
+ | `PUT /batch` (upsert) | [tenant table](/configure/tenant-databases) | `true` | `true` | Bulk insert + per-record update share one Durable Object transaction. |
320
322
  | `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
321
323
  | `POST /batch` (create) | (any) | (any) | `true` | One bulk `INSERT` — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
322
324
  | `DELETE /batch` | (any) | (any) | `true` | One bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
@@ -47,12 +47,12 @@ When ETags are enabled, GET responses include:
47
47
  Content-Type: application/json
48
48
  ETag: W/"a1b2c3d4e5f60718"
49
49
  Cache-Control: private, no-cache
50
- Vary: Authorization, Cookie
50
+ Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion
51
51
  ```
52
52
 
53
53
  `Cache-Control: private, no-cache` means the browser **must revalidate** on every request, but can use its cached copy if the ETag matches, and no shared cache may store the response. This is the correct behavior for authenticated APIs — data is always fresh, but unchanged responses avoid re-transfer.
54
54
 
55
- Every other JSON response produced under a cookie or bearer token (writes, actions, auth, admin) is sent with `Cache-Control: private, no-store` unless the route sets its own policy, and always carries `Vary: Authorization, Cookie`, so a proxy can never serve one user's body to another.
55
+ Every other JSON response produced under a cookie, bearer token, or [Cloudflare Access](/configure/cloudflare-access) assertion (writes, actions, auth, admin) is sent with `Cache-Control: private, no-store` unless the route sets its own policy, and always carries `Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion`, so a proxy can never serve one user's body to another.
56
56
 
57
57
  ## Client usage
58
58
 
@@ -55,6 +55,13 @@ For a resource named `jobs`, Quickback generates:
55
55
  | `PUT` | `/jobs/:id` | Upsert a record (requires config) |
56
56
  | `PUT` | `/jobs/batch` | Batch upsert multiple records (requires config) |
57
57
 
58
+ A table a namespace claims mounts these under the namespace prefix
59
+ (`/event/:eventId/jobs`), and every row they read or write is confined to the instance in the URL
60
+ (see [Claimed tables are pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance)). With [`legacy`](/define/areas#keeping-the-old-url-legacy) it also keeps
61
+ each one at its pre-claim base (`/jobs`, `/jobs/:id`, …) as a deprecated forward: same method, same
62
+ body, one instance per request, org members only, with `Deprecation`, `Sunset` and `Link` response
63
+ headers.
64
+
58
65
  ## Replace a generated verb with an action
59
66
 
60
67
  Map `create`, `update`, or `delete` to a named action when the public URL
@@ -225,6 +232,11 @@ columns may be omitted or sent as `null`. An empty string is **not** a blank —
225
232
  `""` is validated like any other value (so it fails `q.url()`, `q.enum()`, and
226
233
  `q.int()`).
227
234
 
235
+ On a table a namespace claims, the instance column (`eventId` under
236
+ `/event/:eventId/jobs`) is stamped from the URL. Omit it; a body value must
237
+ equal the URL instance or the create answers `400 INSTANCE_MISMATCH`. The same
238
+ rule applies to each `POST /batch` record and to the insert branch of `PUT`.
239
+
228
240
  ### Client-supplied IDs (optimistic updates)
229
241
 
230
242
  Set `allowClientIds: true` on the database config to let `POST /` and
@@ -373,6 +385,7 @@ wrapper:
373
385
  | Status | Description |
374
386
  |--------|-------------|
375
387
  | `400` | Invalid field or missing required field |
388
+ | `400` | `INSTANCE_MISMATCH` — on a claimed table, the body's instance column names another instance than the URL |
376
389
  | `403` | User lacks permission to create records |
377
390
  | `409` | Client-supplied `id` (with `allowClientIds: true`) already exists |
378
391
  | `409` | `IDEMPOTENCY_ROW_CONFLICT` — a [row token](#row-token-idempotency) or client id already belongs to a different record |
@@ -198,6 +198,7 @@ Access violations return **403 Forbidden** when the user's role doesn't match th
198
198
  | `ACCESS_OWNERSHIP_REQUIRED` | User must own the record |
199
199
  | `ACCESS_NO_ORG` | No active organization set |
200
200
  | `ACCESS_KEY_SCOPE_REQUIRED` | A [scoped API key](/platform/auth/api-keys#scopes) does not cover this route and method. `details.required` lists the scope that would admit it (empty outside the API base, which scoped keys never reach); `details.current` is the key's scopes |
201
+ | `ACCESS_DENIED` | A token bound to one instance was used for another (namespace, tenant and realtime ticket routes), or the caller's credential does not admit an operator surface |
201
202
  | `ENTITLEMENT_REQUIRED` | An action's [`requires:`](/define/actions/defining#json-key-writes-and-requires) JSON key did not hold for the record. `details: { column, key }`. Checked before `execute` |
202
203
  | `ACCESS_NO_ARM` | The action declares [`access.arms`](/define/actions/access#arms-conditioned-on-input-accessarms) and no arm's `when` matches the validated input |
203
204
 
@@ -361,9 +362,11 @@ reports these `DB_*` codes per id, or as the `failFast` response), bulk
361
362
  actions, and changesets.
362
363
 
363
364
  `DB_INSERT_FAILED`, `DB_UPDATE_FAILED` and `DB_DELETE_FAILED` are the fallback
364
- for a failure that matches no known constraint. The raw driver message (D1 or
365
+ for a failure that matches no known constraint. The driver message (D1 or
365
366
  Postgres text, which can name tables, columns, and SQL fragments) is always
366
- logged with `console.error`, and the production body carries no `details`:
367
+ logged with `console.error` — with bound values redacted (see
368
+ [Bound values never leave the database](#bound-values-never-leave-the-database))
369
+ — and the production body carries no `details`:
367
370
 
368
371
  ```json
369
372
  {
@@ -374,14 +377,110 @@ logged with `console.error`, and the production body carries no `details`:
374
377
  }
375
378
  ```
376
379
 
377
- The raw message appears as `details.reason` only when the worker runs with
380
+ The (redacted) message appears as `details.reason` only when the worker runs with
378
381
  [`EXPOSE_ERROR_STACK`](#exposing-error-details-in-dev--staging) set.
379
382
 
383
+ ### Bound values never leave the database
384
+
385
+ A database error can carry the row it was writing: drizzle reports every driver
386
+ failure as `Failed query: <sql>` followed by `params: <values>`, and Postgres
387
+ inlines values into its own text (`Key (email)=(…) already exists`,
388
+ `Failing row contains (…)`). Every place the generated API records an error —
389
+ `console.error` in CRUD, batch, changeset and action catches, the global
390
+ `onError`, queue consumers, webhook event and delivery rows, `afterCommit`
391
+ failures, the `error_message` column of `audit_events`, and the
392
+ `EXPOSE_ERROR_STACK` bodies, and Better Auth's own logger (the generated
393
+ `betterAuth({ logger })`, which covers endpoint failures and the database
394
+ adapter) — passes it through `redactError` in the generated `src/lib/errors.ts`
395
+ first. Only the values are removed:
396
+
397
+ | Driver text | Logged / stored as |
398
+ |---|---|
399
+ | `Failed query: insert into "account" ("id", "user_id", "password") values (?, ?, ?)`<br/>`params: acc_1,usr_1,$argon2id$…` | `Failed query: insert into "account" ("id", "user_id", "password") values (?, ?, ?)`<br/>`params: [string(5), string(5), string(97)]` |
400
+ | `UNIQUE constraint failed: account.user_id` (D1, libsql) | unchanged |
401
+ | `duplicate key value violates unique constraint "users_email_key"`, `detail: Key (email)=(x@y.com) already exists.` (Postgres) | message unchanged; `detail: Key (email)=(<redacted>) already exists.` |
402
+ | `Failing row contains (r1, x@y.com, …)` | `Failing row contains (<redacted>)` |
403
+ | `invalid input syntax for type uuid: "…"` | `invalid input syntax for type uuid: "<redacted>"` |
404
+ | `Key (lower(email::text))=(…)` (expression index), `conflicts with existing key (…)=(…)` (exclusion constraint) | `=(<redacted>)` |
405
+ | `value "…" is out of range for type integer`, `date/time field value out of range: "…"`, `malformed array literal: "…"`, `Token "…" is invalid.` | the quoted literal becomes `"<redacted>"`; quoted constraint, relation, column and table names stay |
406
+
407
+ The SQL with its placeholders, table, column and constraint names, the driver
408
+ code (`SQLITE_CONSTRAINT_UNIQUE`, `23505`), the parameter count and each
409
+ parameter's type and length stay, so the log line still tells you which
410
+ statement failed and why; the `requestId` correlates it with the response,
411
+ and the global error log line also carries the driver `code` and `causeCode`.
412
+ Driver text past 16 KB is cut and marked `[truncated]`, so a hostile value can't
413
+ make redaction slow.
414
+ Classification is unaffected — the `DB_*` codes above are computed from the
415
+ original error. Your own code can call `redactError(error)` from
416
+ `src/lib/errors` before logging a caught error.
417
+
380
418
  `ENCRYPTION_UNREADABLE` always carries `details: { table, column, id }` — the
381
419
  row whose stored ciphertext is malformed, was not written under the caller's
382
420
  organization key, was copied from another column or table, or names a key
383
421
  version the organization does not have. Rewriting the field repairs the row.
384
422
 
423
+ ### Legacy forwards
424
+
425
+ A [legacy forward](/define/areas#keeping-the-old-url-legacy) answers these itself, before it
426
+ dispatches; every other response is the successor route's. Each carries the `Deprecation`,
427
+ `Sunset` and `Link` headers.
428
+
429
+ | Code | Status | Meaning |
430
+ |------|--------|---------|
431
+ | `LEGACY_ORG_REQUIRED` | 403 | The caller has no active organization, is an instance-bound OAuth token or a scope-only principal, or (database per tenant) its active organization is not the tenant. Call the successor URL in `Link`. |
432
+ | `LEGACY_INSTANCE_REQUIRED` | 400 | The request names no instance: no `?C=` (or a repeated / `?C.<op>=` one) on a collection, no `C` in the body, or an id that is not a valid instance id. |
433
+ | `LEGACY_INSTANCE_MISMATCH` | 400 | The request names more than one instance (a batch spanning instances, or a body `C` that disagrees with `?C=`). |
434
+
435
+ An instance outside the caller's organization answers the namespace gate's
436
+ `403 ACCESS_ROLE_REQUIRED`; a row outside it answers the table's firewall miss
437
+ (`403 FIREWALL_NOT_FOUND`, or `404` with `firewallErrorMode: 'hide'`).
438
+
439
+ ### Claimed tables
440
+
441
+ A table a namespace claims is [pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance).
442
+
443
+ | Code | Status | Meaning |
444
+ |------|--------|---------|
445
+ | `INSTANCE_MISMATCH` | 400 | A create body (or a batch record) sends the instance column with a value other than the instance in the URL. `layer: "validation"`, `details: { field, param }` (plus `index` for a batch record). Omit the column: it is taken from the URL. |
446
+
447
+ ### Tenancy (database per tenant)
448
+
449
+ With `tenancy.isolation: 'durable-object'`, responses about an organization's own database carry `layer: "tenancy"` and one of these codes. See [Database per Tenant](/configure/tenant-databases).
450
+
451
+ | Code | Meaning |
452
+ |------|---------|
453
+ | `TENANT_REQUIRED` | The route reads an organization's own database but the request names no organization (or names an invalid id) |
454
+ | `TENANT_MISMATCH` | The principal does not belong to the tenant object it reached |
455
+ | `TENANT_SCOPE_MISMATCH` | A scope claim names a different tenant than the request |
456
+ | `TENANT_AMBIGUOUS` | The instance resolves to more than one organization; set an active organization |
457
+ | `TENANT_UNAVAILABLE` | The organization database or directory is unavailable; retry (`Retry-After`) |
458
+ | `TENANT_OVERLOADED` | The organization database is overloaded; retry after `Retry-After` |
459
+ | `TENANT_DEPTH_EXCEEDED` | Subrequest depth limit exceeded calling the organization database (508) |
460
+ | `TENANT_ADMISSION_UNAVAILABLE` | Scope admission could not be checked right now; retry |
461
+ | `TENANT_LOOKUP_UNAVAILABLE` | The tenant lookup index could not be read; retry |
462
+ | `TENANT_LOOKUP_PENDING` | The instance is not indexed to a tenant yet; retry |
463
+ | `TENANT_NOT_PROVISIONED` | The organization has no tenant database registered (operator routes other than archive refuse it) |
464
+ | `TENANT_ARCHIVED` | The organization is archived (423); an operator can unarchive it |
465
+ | `TENANT_PURGED` | The organization's data was purged (410) |
466
+ | `TENANT_MIGRATION_FAILED` | The organization database failed to migrate (503); `details` names the migration |
467
+ | `TENANT_JURISDICTION_MISMATCH` | The registry row was written under another jurisdiction |
468
+ | `TENANT_RPC_VERSION_MISMATCH` | The edge and tenant Workers disagree on the RPC contract; deploy the tenant Worker first |
469
+ | `TENANT_AUTHORIZATION_EPOCH_CHANGED` | A restore advanced the tenant's authorization epoch; credentials issued before it are refused |
470
+ | `TENANT_RESTORE_PENDING` | A restore is pending or unreconciled; sync or cancel it first |
471
+ | `TENANT_RESTORE_TOO_LARGE` | Operator restore: the dump exceeds the restore limit (413) |
472
+ | `TENANT_OPERATION_FAILED` | Operator route refused or failed (409); `detail` says why |
473
+ | `TENANT_COMMAND_INVALID` | A tenant command request failed its schema |
474
+ | `TENANT_COMMAND_FINGERPRINT_MISMATCH` | A tenant command was compiled against a different contract |
475
+ | `TENANT_COMMAND_REPLY_INVALID` | The tenant object answered a command with a malformed reply |
476
+ | `TENANT_JOB_INVALID` | A tenant job message is invalid |
477
+ | `TENANT_JOB_CALL_ONLY` | A result job was delivered instead of called (callTenantJob) |
478
+ | `TENANT_JOB_FAILED` | A called tenant job failed |
479
+ | `TENANT_JOB_REPLY_INVALID` | The tenant object answered a job call with a malformed reply |
480
+ | `TENANT_JOB_RESULT_INVALID` | A tenant job result is not serializable |
481
+ | `TENANT_JOB_RESULT_TOO_LARGE` | A tenant job result exceeds the size limit |
482
+ | `TENANT_TABLE_ON_EDGE` | Edge code queried a tenant table (500, a compile-placement bug) |
483
+
385
484
  ## Batch Errors
386
485
 
387
486
  Batch operations can return:
@@ -465,7 +564,7 @@ fetch timeout, a third-party API error), the route returns
465
564
  `ACTION_EXECUTION_FAILED`. The production body is generic: it carries
466
565
  only the error class name in `details.name` (so callers can branch on
467
566
  e.g. `TypeError` vs a fetch timeout) — never the underlying message,
468
- cause, or stack frames. The raw error is always logged server-side.
567
+ cause, or stack frames. The error is logged server-side with bound database values redacted.
469
568
 
470
569
  ```json
471
570
  {
@@ -489,8 +588,8 @@ cause, or stack frames. The raw error is always logged server-side.
489
588
 
490
589
  Uncaught throws that escape every route handler land in the global
491
590
  `onError` and return `INTERNAL_ERROR`. Same contract: the production
492
- body is generic, and the full error (message, cause chain, stack) is
493
- logged via `console.error` keyed by the `requestId` in the body — so
591
+ body is generic, and the error (message, cause chain, stack), with bound
592
+ database values redacted, is logged via `console.error` keyed by the `requestId` in the body — so
494
593
  the response → log correlation is one grep.
495
594
 
496
595
  ```json
@@ -525,11 +624,13 @@ When set, the global 500 and `ACTION_EXECUTION_FAILED` bodies forward
525
624
  the underlying error message plus `details.cause` (cause-chain
526
625
  message), `details.frames` (top three stack frames with absolute paths
527
626
  sanitized to basename + line number), and `details.stack` (the full
528
- unsanitized stack trace). The same switch adds `details.reason` (the raw
627
+ unsanitized stack trace). The same switch adds `details.reason` (the
529
628
  error message) to the database fallbacks (`DB_INSERT_FAILED`,
530
629
  `DB_UPDATE_FAILED`, `DB_DELETE_FAILED`), `ACCESS_AUDIT_LOG_FAILED`, the
531
- `INTERNAL_ERROR` bodies of the auth handler and the operator `/admin/*`
532
- routes, and uses the raw message as the `TRIGGER_AFTER_FAILED` error text.
630
+ `INTERNAL_ERROR` bodies of the auth handler, operator `/admin/*` routes,
631
+ and storage upload, presign, and confirm routes, and uses the redacted message as the `TRIGGER_AFTER_FAILED` error text.
533
632
  Without it, none of those bodies carry anything derived from the thrown
534
- error. `1` and `true` turn it on; any other value leaves it off. Leave it
633
+ error. With it, they still never carry a bound value — the message, cause and
634
+ stack go through the same [redaction](#bound-values-never-leave-the-database)
635
+ as the server log. `1` and `true` turn it on; any other value leaves it off. Leave it
535
636
  unset in production.
@@ -33,6 +33,30 @@ For each resource with `export default defineTable(...)`:
33
33
  | `PATCH` | `/api/v1/{resource}/batch` | Batch update |
34
34
  | `DELETE` | `/api/v1/{resource}/batch` | Batch delete |
35
35
 
36
+ ## Moved routes (0.72)
37
+
38
+ Better Auth owns `/auth/v1/*`. Quickback's own routes there moved under the API base in 0.72 (plan 031 Q7), so a Better Auth upgrade or plugin cannot collide with them and a Cloudflare Access path rule can cover the operator plane in one prefix. The prefix follows `contract.routes` (`/api/v2/…` on v2).
39
+
40
+ | Before 0.72 | Since 0.72 | Emitted when |
41
+ |---|---|---|
42
+ | `GET /auth/v1/admin/list-organizations` | `GET /api/v1/operator/organizations` | `cms.sysadmin` or `account.auth.admin` |
43
+ | `GET /auth/v1/admin/get-organization?organizationId=:id` | `GET /api/v1/operator/organizations/:id` | same |
44
+ | `POST /auth/v1/admin/create-organization` | `POST /api/v1/operator/organizations` | same |
45
+ | `POST /auth/v1/admin/set-organization-member` `{ organizationId, userId, role }` | `PUT /api/v1/operator/organizations/:id/members/:userId` `{ role }` | same |
46
+ | `POST /auth/v1/admin/remove-organization-member` `{ organizationId, userId }` | `DELETE /api/v1/operator/organizations/:id/members/:userId` | same |
47
+ | `GET /auth/v1/organization/roster` | `GET /api/v1/organization/roster` | `auth.organizationRoster` |
48
+ | `GET /auth/v1/ses/status` | `GET /api/v1/auth/email-status` | always |
49
+
50
+ Response bodies are unchanged. The old paths keep working through 0.72.x and are removed in 0.73.0:
51
+
52
+ - The old `GET`s answer `308 Permanent Redirect` to the new path (the query string is kept; `get-organization?organizationId=X` redirects to `/operator/organizations/X`).
53
+ - The old `POST`s cannot redirect, because two of them changed verb. They run the same handler as the new route.
54
+ - Both add `Deprecation: true` and `Link: <new path>; rel="successor-version"`, and the Worker logs `[quickback] deprecated route <method> <path>` once per isolate per path. Grep your logs for it before upgrading to 0.73.
55
+
56
+ The bundled CMS and Account SPAs call the new paths. The OpenAPI document lists `GET /api/v1/auth/email-status` (operationId `getEmailStatus`, marked `x-quickback-auth-surface`, so like every auth endpoint it stays out of the MCP catalogue unless `agents.mcp.exposeAuthTools` is on, where the tool `auth__sesStatus` is now `auth__getEmailStatus`); the aliases are not advertised. A feature or table that would mount over one of these routes (`/api/v1/operator`, `/api/v1/auth`, `/api/v1/organization` with the roster on) is a compile error.
57
+
58
+ `ses/status` note: after 0.73.0, an `aws-ses` project's vendored Better Auth plugin answers `/auth/v1/ses/status` itself, with a different body (`provider: 'aws-ses'`, plus `region` and `fromEmail`). Use `email-status`.
59
+
36
60
  ## Guides
37
61
 
38
62
  - [CRUD Endpoints](/api/crud) — Detailed CRUD endpoint reference
@@ -24,6 +24,14 @@ The generated spec documents every route the compiler produces:
24
24
  - Actions (including standalone actions)
25
25
  - Auth routes (`/api/auth/**`)
26
26
  - Storage and webhook routes (when configured)
27
+ - [Legacy forwards](/define/areas#keeping-the-old-url-legacy) of namespace-claimed tables and actions, as `deprecated: true` operations
28
+
29
+ A legacy operation is its successor's operation at the old path: operationId `<successor>Legacy`,
30
+ the successor's path params dropped, a required `?C=` query param on collections, the
31
+ `Deprecation` / `Sunset` / `Link` response headers, and
32
+ `x-quickback-legacy-forward: { successor, successorPath, deprecated, sunset, instance }`. The
33
+ `LEGACY_*` codes join the `Error.code` enum. Generated clients see `@deprecated`. The MCP tool list
34
+ and the generated client SDK skip legacy operations: new code targets the successor.
27
35
 
28
36
  Each endpoint includes request/response schemas derived from your Drizzle column types, access control metadata, and error responses.
29
37