@quickback-dev/cli 0.66.5 → 0.66.7

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 (109) hide show
  1. package/README.md +0 -1
  2. package/dist/index.js +1 -1
  3. package/dist/lib/api-client.d.ts +1 -1
  4. package/dist/lib/api-client.d.ts.map +1 -1
  5. package/dist/lib/api-client.js +13 -8
  6. package/dist/lib/api-client.js.map +1 -1
  7. package/dist/lib/api-client.test.js +47 -0
  8. package/dist/lib/api-client.test.js.map +1 -1
  9. package/dist/lib/migrations/drizzle.d.ts.map +1 -1
  10. package/dist/lib/migrations/drizzle.js +6 -1
  11. package/dist/lib/migrations/drizzle.js.map +1 -1
  12. package/dist/lib/migrations/drizzle.test.js +7 -0
  13. package/dist/lib/migrations/drizzle.test.js.map +1 -1
  14. package/dist/lib/migrations/executor.d.ts.map +1 -1
  15. package/dist/lib/migrations/executor.js +4 -0
  16. package/dist/lib/migrations/executor.js.map +1 -1
  17. package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts +7 -0
  18. package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts.map +1 -0
  19. package/dist/lib/migrations/postprocessors/better-auth-upgrade.js +149 -0
  20. package/dist/lib/migrations/postprocessors/better-auth-upgrade.js.map +1 -0
  21. package/dist/skill/SKILL.md +0 -2
  22. package/dist/skill/docs/api/openapi.md +1 -1
  23. package/dist/skill/docs/configure/auth.md +4 -5
  24. package/dist/skill/docs/configure/domains.md +1 -1
  25. package/dist/skill/docs/configure/index.md +4 -4
  26. package/dist/skill/docs/configure/security.md +3 -3
  27. package/dist/skill/docs/define/access.md +23 -3
  28. package/dist/skill/docs/define/actions/defining.md +2 -2
  29. package/dist/skill/docs/define/actions/index.md +6 -0
  30. package/dist/skill/docs/define/actions/record-and-standalone.md +1 -2
  31. package/dist/skill/docs/define/areas.md +14 -15
  32. package/dist/skill/docs/define/changesets.md +5 -0
  33. package/dist/skill/docs/define/diagnostics.md +2 -2
  34. package/dist/skill/docs/define/fga.md +1 -1
  35. package/dist/skill/docs/define/firewall.md +5 -5
  36. package/dist/skill/docs/define/guards.md +2 -1
  37. package/dist/skill/docs/define/masking.md +2 -2
  38. package/dist/skill/docs/define/relationships.md +8 -10
  39. package/dist/skill/docs/define/scopes.md +1 -1
  40. package/dist/skill/docs/define/transitions.md +11 -0
  41. package/dist/skill/docs/define/triggers.md +4 -0
  42. package/dist/skill/docs/index.md +0 -6
  43. package/dist/skill/docs/platform/auth/index.md +37 -0
  44. package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -2
  45. package/dist/skill/docs/platform/queues/handlers.md +12 -0
  46. package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
  47. package/dist/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
  48. package/dist/skill/docs/platform/schedules/index.md +3 -1
  49. package/dist/skill/docs/platform/webhooks/inbound.md +1 -1
  50. package/dist/skill/docs/tooling/claude-skill.md +0 -7
  51. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +11 -1
  52. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +16 -0
  53. package/dist/skill/docs/tooling/output.md +7 -6
  54. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  55. package/dist/skill/docs/ui/account/features/organizations.md +1 -1
  56. package/dist/skill/docs/ui/admin/index.md +1 -1
  57. package/dist/skill/docs/ui/admin/owned-records.md +81 -0
  58. package/dist/skill/docs/ui/admin/schema-format.md +16 -0
  59. package/package.json +1 -1
  60. package/src/skill/SKILL.md +0 -2
  61. package/src/skill/docs/api/openapi.md +1 -1
  62. package/src/skill/docs/configure/auth.md +4 -5
  63. package/src/skill/docs/configure/domains.md +1 -1
  64. package/src/skill/docs/configure/index.md +4 -4
  65. package/src/skill/docs/configure/security.md +3 -3
  66. package/src/skill/docs/define/access.md +23 -3
  67. package/src/skill/docs/define/actions/defining.md +2 -2
  68. package/src/skill/docs/define/actions/index.md +6 -0
  69. package/src/skill/docs/define/actions/record-and-standalone.md +1 -2
  70. package/src/skill/docs/define/areas.md +14 -15
  71. package/src/skill/docs/define/changesets.md +5 -0
  72. package/src/skill/docs/define/diagnostics.md +2 -2
  73. package/src/skill/docs/define/fga.md +1 -1
  74. package/src/skill/docs/define/firewall.md +5 -5
  75. package/src/skill/docs/define/guards.md +2 -1
  76. package/src/skill/docs/define/masking.md +2 -2
  77. package/src/skill/docs/define/relationships.md +8 -10
  78. package/src/skill/docs/define/scopes.md +1 -1
  79. package/src/skill/docs/define/transitions.md +11 -0
  80. package/src/skill/docs/define/triggers.md +4 -0
  81. package/src/skill/docs/index.md +0 -6
  82. package/src/skill/docs/platform/auth/index.md +37 -0
  83. package/src/skill/docs/platform/auth/jwt-optimization.md +2 -2
  84. package/src/skill/docs/platform/queues/handlers.md +12 -0
  85. package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
  86. package/src/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
  87. package/src/skill/docs/platform/schedules/index.md +3 -1
  88. package/src/skill/docs/platform/webhooks/inbound.md +1 -1
  89. package/src/skill/docs/tooling/claude-skill.md +0 -7
  90. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +11 -1
  91. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +16 -0
  92. package/src/skill/docs/tooling/output.md +7 -6
  93. package/src/skill/docs/ui/account/features/admin.md +1 -1
  94. package/src/skill/docs/ui/account/features/organizations.md +1 -1
  95. package/src/skill/docs/ui/admin/index.md +1 -1
  96. package/src/skill/docs/ui/admin/owned-records.md +81 -0
  97. package/src/skill/docs/ui/admin/schema-format.md +16 -0
  98. package/dist/skill/docs/changelog/index.md +0 -945
  99. package/dist/skill/docs/changelog/v0.1x.md +0 -1202
  100. package/dist/skill/docs/changelog/v0.2x.md +0 -589
  101. package/dist/skill/docs/changelog/v0.3x.md +0 -1152
  102. package/dist/skill/docs/changelog/v0.4x.md +0 -1108
  103. package/dist/skill/docs/changelog/v0.5x.md +0 -885
  104. package/src/skill/docs/changelog/index.md +0 -945
  105. package/src/skill/docs/changelog/v0.1x.md +0 -1202
  106. package/src/skill/docs/changelog/v0.2x.md +0 -589
  107. package/src/skill/docs/changelog/v0.3x.md +0 -1152
  108. package/src/skill/docs/changelog/v0.4x.md +0 -1108
  109. package/src/skill/docs/changelog/v0.5x.md +0 -885
@@ -1,1152 +0,0 @@
1
- # v0.32 – v0.39
2
-
3
- ## v0.39.1 — June 2, 2026
4
-
5
- Deduplicate colliding OpenAPI `operationId`s. The auto-generated list id
6
- `list<Resource>` collided when a user named an action `list<Resource>` (e.g.
7
- `message_reactions` + an action `listMessageReactions`), producing a duplicate
8
- operationId that failed OpenAPI validation and broke `api-types.gen.ts`. The
9
- user's action keeps its id; the colliding auto-generated CRUD op is suffixed,
10
- with a `[quickback:openapi]` warning per rename.
11
-
12
- ## v0.39.0 — June 2, 2026
13
-
14
- Media and large-binary uploads are now first-class. Instead of streaming file
15
- bytes through your Worker — which hits the request-body cap and burns Worker
16
- CPU/duration — an action mints a short-lived **presigned URL** and the client
17
- uploads the bytes **directly to R2**. The Worker only signs; it never sits in
18
- the data path. This is the supported way to author image/video/document upload
19
- endpoints, and it survives every `quickback compile` with no generated-file
20
- patching.
21
-
22
- Requires R2 file storage (`defineFileStorage("cloudflare-r2", …)`).
23
-
24
- ### `ctx.storage` — sign uploads from any action
25
-
26
- When R2 file storage is configured, every `defineAction` execute receives a
27
- typed `storage` signer. Your action runs all the usual security layers (auth,
28
- roles, org/relationship scope), computes a tenant-scoped key, hands the client
29
- an upload URL, and stores the key in **your own table** — no separate metadata
30
- system required:
31
-
32
- ```ts title="features/media/actions/uploadFileBinary.ts"
33
- import { z } from "zod";
34
- import { defineAction } from "../.quickback/define-action";
35
-
36
- export default defineAction({
37
- description: "Mint a presigned R2 upload URL for an event media file.",
38
- path: "/event/:eventId/media/upload-file-binary",
39
- method: "POST",
40
- input: z.object({ filename: z.string(), contentType: z.string() }),
41
- access: { roles: ["admin", "member", "scope:event:attendee"] },
42
- async execute({ input, ctx, c, db, storage }) {
43
- const eventId = c.req.param("eventId");
44
- const key = `org/${ctx.activeOrgId}/event/${eventId}/${crypto.randomUUID()}-${input.filename}`;
45
- const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
46
- await db.insert(images).values({ key, eventId });
47
- return { uploadUrl: upload.url, key, headers: upload.headers, expiresAt: upload.expiresAt };
48
- },
49
- });
50
- ```
51
-
52
- `storage` exposes `signPutUrl(key, { contentType?, expiresIn? })` (returns
53
- `{ url, method, headers, key, expiresAt }`) and
54
- `signGetUrl(key, { expiresIn?, downloadFilename? })` (returns a presigned GET
55
- URL). Construction is zero-cost — actions that never touch `storage` pay
56
- nothing.
57
-
58
- ### Managed presign + confirm endpoints
59
-
60
- For the zero-config path, the built-in storage API now exposes a presigned
61
- upload alongside the existing through-Worker upload:
62
-
63
- - `POST /storage/v1/presign/:bucket/*path` — runs the bucket's auth/role/scope
64
- checks, validates the declared `contentType` + `size` against bucket limits,
65
- records a pending object row, and returns `{ id, key, uploadUrl, method,
66
- headers, expiresAt }`
67
- - `POST /storage/v1/confirm/:bucket/*path` — reconciles the recorded size and
68
- etag against what actually landed in R2 (`HEAD`)
69
-
70
- ### Setup: R2 API token
71
-
72
- Presigning uses R2's S3 API, which needs an **R2 API token** — the Workers R2
73
- binding cannot presign on its own. Set three secrets:
74
-
75
- ```bash
76
- wrangler secret put R2_ACCOUNT_ID
77
- wrangler secret put R2_ACCESS_KEY_ID
78
- wrangler secret put R2_SECRET_ACCESS_KEY
79
- ```
80
-
81
- `aws4fetch` is added to the generated `package.json` automatically, and the R2
82
- presign secrets are added to the generated `Env` type. If you pass `contentType`
83
- to `signPutUrl`, the client must replay exactly that `Content-Type` header on
84
- the `PUT`.
85
-
86
- ### No raw-body action flag
87
-
88
- Streaming a raw binary request body through an action is intentionally **not**
89
- supported. Presigning delivers the same result — large files, no body cap —
90
- without poking a hole in the body-parsing layer, so JSON actions and the ~1 MiB
91
- JSON cap stay intact for every other route.
92
-
93
- ### Storage routes hardened
94
-
95
- Enabling R2 file storage previously exposed several latent type errors in the
96
- generated `/storage/v1/*` routes (dead references from an old multipart
97
- refactor, JSON-string role columns treated as arrays, a few undefined
98
- variables). The full storage surface now type-checks cleanly when file storage
99
- is configured.
100
-
101
- ## v0.38.1 — May 26, 2026
102
-
103
- Custom action handlers get the same typed ergonomics as generated CRUD paths:
104
- typed Cloudflare bindings on `env`, a first-class typed `realtime` helper when
105
- realtime is enabled, and no more `createRealtime(...)` boilerplate inside every
106
- action just to emit an explicit broadcast.
107
-
108
- ### Neon compile output and local recompile state are now stable
109
-
110
- The Neon + Cloudflare path now emits a correct runtime/output surface instead
111
- of leaking SQLite-era state.
112
-
113
- - `wrangler.toml` no longer emits a stray `[[d1_databases]]` block for Neon
114
- projects
115
- - repeated local Neon compiles now upload and sync the root PostgreSQL Drizzle
116
- state correctly, so `drizzle-kit` can report "No schema changes" instead of
117
- regenerating duplicate `0000_*.sql` files
118
- - stale root Drizzle migrations from earlier bad compiles are pruned during the
119
- compile/sync path
120
-
121
- ### Shared-target namespace hydration now works for bulk-grant lanes
122
-
123
- Bulk-grant namespace callers (`{ roles: [...] }`, `{ team: true }`) now inherit
124
- the namespace's shared hydration target when every relationship lane points at
125
- the same resource load shape.
126
-
127
- That fixes the case where a namespace like:
128
-
129
- ```ts
130
- via: ['attendeeOf', 'organizerOf', { roles: ['admin', 'owner'] }]
131
- ```
132
-
133
- would authorize an org admin through the bulk lane but leave `ctx.event`
134
- undefined, even though the sibling relationship lanes all hydrated the same
135
- `events` row.
136
-
137
- Runtime behavior is now split cleanly:
138
-
139
- - **Shared target** — if all hydrating lanes share the same `loads`,
140
- `exposeAs`, and resource key, hydration runs unconditionally after the gate
141
- passes, so bulk callers get the same `ctx.<exposeAs>` as relationship callers
142
- - **Distinct targets** — if lanes hydrate different tables / keys / ctx slots,
143
- hydration stays per-matched-lane to avoid cross-table false 404s
144
-
145
- Standalone action typing now matches that runtime behavior too: shared-target
146
- hydration remains non-optional, while distinct-target multi-lane hydration stays
147
- optional.
148
-
149
- ### Platform role split: `appmanager` for control-plane, `sysadmin` for cross-tenant
150
-
151
- Quickback no longer treats `user.role === "admin"` as the platform-wide role.
152
- The control-plane role is now `user.role === "appmanager"` (CMS shell, Better
153
- Auth admin endpoints, support tooling), while `user.role === "sysadmin"`
154
- remains the only true cross-tenant data-plane tier.
155
-
156
- This also retires the `ADMIN` pseudo-role. Any `roles: ["ADMIN"]` usage now
157
- fails the compile with migration guidance:
158
-
159
- - `userRole: ["appmanager"]` for platform control-plane access
160
- - `roles: ["admin"]` for org-membership admin access
161
- - `roles: ["SYSADMIN"]` for true cross-tenant access
162
-
163
- Runtime behavior now matches that split end-to-end:
164
-
165
- - Better Auth's admin plugin is generated with `adminRoles: ["appmanager", "sysadmin"]`
166
- - CMS / OpenAPI / auth-admin surfaces gate on `appmanager` (and admit
167
- `sysadmin` where appropriate)
168
- - unsafe cross-tenant actions and tenant-bypass helpers require `sysadmin` only
169
-
170
- ### Typed `env` + injected `realtime` in action handlers
171
-
172
- The generated `<feature>/.quickback/define-action.ts` helper now types action
173
- `env` from the project's runtime bindings surface instead of `any`, so custom
174
- bindings like R2 buckets, queues, Durable Objects, auth env vars, and split DB
175
- bindings no longer need `(env as any)` casts inside action handlers.
176
-
177
- When realtime is enabled in config, action handlers also receive a typed
178
- `realtime` helper directly in `execute(...)`. It exposes the same
179
- `insert/update/delete/broadcast` methods as `createRealtime(env)`, but without
180
- the extra import or hand-rolled factory call in every custom action.
181
-
182
- This is a DX-only change. The auto-broadcast boundary is unchanged: generated
183
- CRUD routes still broadcast automatically, while custom action writes still
184
- broadcast explicitly.
185
-
186
- ### `generateId: "cuid"` docs now reflect the split runtime/schema behavior
187
-
188
- Quickback's `cuid` strategy is now documented as the split path it actually is:
189
- compiler-managed schema auto-injection keeps the `createId()` call site but may
190
- back it with a file-local `crypto.randomUUID()` polyfill, while import-capable
191
- runtime paths still emit real `createId()` usage.
192
-
193
- That matters most for `compiler.injectId` and other schema-emission paths that
194
- run in sandboxes where project `node_modules` are not visible. The generated
195
- schema can safely keep:
196
-
197
- ```ts
198
- id: text("id").primaryKey().$defaultFn(() => createId())
199
- ```
200
-
201
- while satisfying the reference via:
202
-
203
- ```ts
204
- const createId = () => crypto.randomUUID();
205
- ```
206
-
207
- instead of importing `@paralleldrive/cuid2` inside the schema-generation
208
- environment.
209
-
210
- **Important nuance:** this is not a guarantee that every generated id is a true
211
- cuid2 string. Auto-injected schema paths may produce UUID-shaped strings
212
- through the polyfill, while runtime paths that can import helpers may still use
213
- real `createId()`. If you need strict cuid2 shape everywhere, explicitly import
214
- `createId` from `@paralleldrive/cuid2` in the authored schema file; the
215
- compiler preserves that import and skips the polyfill.
216
-
217
- ## v0.38.0 — May 26, 2026
218
-
219
- **Per-matched-lane authorization** for multi-lane namespaces — across both the
220
- REST scope refresh/mint and the realtime ws-ticket. A namespace gated by several
221
- `via:` lanes (attendees *or* organizers *or* contractors *or* org admins) now
222
- confers the scope role of **whichever lane the caller actually matched**, instead
223
- of suppressing the grant. This retires the v0.37.0 single-conferring-lane
224
- limitation.
225
-
226
- ### Scope refresh & `mintScope` — per matched lane
227
-
228
- A **multi-lane `via:`** now refreshes and mints the matched lane's role:
229
- `attendeeOf` → `scope.event.roles = ['attendee']`, `organizerOf` → `['organizer']`.
230
- The resolver records which lane opened the gate (first-match-wins), so a caller
231
- can only ever carry the role they proved this request. A **bulk-grant lane**
232
- (`{ roles: [...] }` / `{ team: true }`) still confers **no** scope role — it
233
- authorizes via the caller's org role, with nothing to stamp. Previously any
234
- multi-lane / bulk / mixed `via:` suppressed the stamp and mint entirely; that
235
- restriction is lifted. See [Scopes](/define/scopes#mintscope-mint-the-scope-token-from-the-namespace-resolver).
236
-
237
- ### Namespace-backed ws-ticket — realtime, per matched lane
238
-
239
- `realtime.wsTicket` accepts a **`namespace`** reference, so the
240
- `/broadcast/v1/ws-ticket` route authorizes through that namespace's full
241
- multi-lane `via:` and issues a per-matched-lane WebSocket ticket — the socket
242
- gate and the REST gate stay identical, from a single source of truth.
243
-
244
- ```typescript
245
- realtime: {
246
- wsTicket: { namespace: "eventScope", requestField: "eventId", scopeTable: "events" },
247
- },
248
- ```
249
-
250
- An attendee gets an `attendee` ticket, an organizer an `organizer` ticket, and an
251
- org admin who reaches the room through the bulk lane now gets a ticket scoped to
252
- their org/membership roles — closing the gap where the single-`role` form `403`'d
253
- a legitimate admin and left their realtime socket dead.
254
-
255
- **Tenant-bound, fail-closed.** Before minting, the route loads the `scopeTable`
256
- row through *its own firewall*, so a ticket can only target a room whose resource
257
- resolves under the caller's tenant — an org-A admin requesting an org-B `eventId`
258
- gets `403`, never a cross-tenant socket. Because the room *is* the data (no
259
- firewall sits between a ticket and a Durable Object room), the compiler **rejects
260
- at build time** a namespace-backed `wsTicket` whose `scopeTable` isn't
261
- tenant-scoped (`firewall: { exception: true }` or a literal-only firewall with no
262
- org/owner/team isolation). See
263
- [Realtime tickets](/platform/realtime/durable-objects#namespace-backed-tickets-per-matched-lane).
264
-
265
- ## v0.37.0 — May 26, 2026
266
-
267
- The **authz-as-compile-target** roadmap ships. Your authorization model —
268
- relationships, named permissions, FK-traversal arrows, scope axes — compiles
269
- into one normalized policy IR, lowers to SQL `WHERE` clauses / signed claims /
270
- guards, and is checked by a static analyzer before a single route is emitted.
271
- This release lands milestones M0.1, M0.3, M1, M2, and M4, plus §5.3 namespace
272
- scope-minting.
273
-
274
- ### Named permissions (`authz.permissions`) — M1
275
-
276
- A `via:` arm references **one** relationship. When the *same* grant rule recurs
277
- across resources — "organizer **or** confirmed attendee" — name it **once**
278
- under `authz.permissions` as a boolean expression and reference it everywhere
279
- with a `{ permission }` firewall arm.
280
-
281
- ```typescript
282
- authz: {
283
- permissions: {
284
- 'event:view': { anyOf: ['organizerOf', 'attendeeOf'] },
285
- 'org:admin': { anyOf: [{ role: 'admin' }, { role: 'owner' }] },
286
- },
287
- }
288
- // then on a resource:
289
- // firewall: [ { field: 'eventId', permission: 'event:view' } ]
290
- ```
291
-
292
- `anyOf` lowers to an OR of relationship subqueries, `allOf` to an AND, and a
293
- `{ permissionRef }` inlines another permission's arms — byte-identical to
294
- writing the `via:` arms by hand. The full DSL (`anyOf` / `allOf` / `not`, bare
295
- strings, and the object-leaf escape hatch) is accepted so configs stay
296
- forward-compatible; a firewall enforces the **SQL-pushable** subset (claim-site
297
- leaves like `{ role }` / `{ scopeRole }` and `not` over a SQL site are rejected
298
- at compile time — gate those on `access` instead). See
299
- [Permissions](/define/permissions).
300
-
301
- ### FK-traversal arrows (`authz.arrows`) — M2
302
-
303
- An **arrow** inherits authority across a foreign key: *"you can see this row
304
- because you administer the organization it belongs to"*, or *"because you
305
- control an ancestor in the tree."* Declare an FK hop, reference it from a
306
- permission as `{ arrowRef, permission }`, and it lowers to SQL.
307
-
308
- ```typescript
309
- authz: {
310
- arrows: {
311
- eventOrg: { from: 'event', fk: 'organizationId', to: 'organization' },
312
- folderTree: { from: 'folder', fk: 'parentId', to: 'folder', recursive: true },
313
- },
314
- permissions: {
315
- 'event:view': { anyOf: ['organizerOf', { arrowRef: 'eventOrg', permission: 'org:admin' }] },
316
- 'folder:read': { anyOf: [{ arrowRef: 'folderTree', permission: 'org:admin' }] },
317
- },
318
- }
319
- ```
320
-
321
- A single hop lowers to an FK-hop subquery; a self-referential hop
322
- (`folder.parentId -> folder`) lowers to a **bounded `WITH RECURSIVE` CTE**
323
- (default depth 8, override per-arrow with `maxDepth` or per-permission with
324
- `permissionMaxDepth`). The seed and **every walked row** are re-constrained to
325
- the caller's active-org claim, an absent claim fails closed (`1 = 0`), and the
326
- identifiers are compile-time constants while the claim binds as a parameter —
327
- so an arrow is never an injection surface. An `unbounded: true` arrow with no
328
- claim path is a hard compile error. Valid on both D1 and Neon. See
329
- [Arrows](/define/arrows).
330
-
331
- ### Compile-time authz analyzer + diagnostics — M4
332
-
333
- The compiler now projects your whole authorization model into a single policy
334
- IR and runs static checks over it, reporting on the existing
335
- **`[quickback:authz]`** console channel with stable, greppable codes:
336
-
337
- - `AUTHZ_EMPTY_PERMISSION` — a permission that can never be satisfied (e.g. `allOf(a, not(a))`).
338
- - `AUTHZ_SHADOWED_ARM` — an `anyOf` arm subsumed by a broader sibling.
339
- - `AUTHZ_UNREACHABLE_ROLE` / `AUTHZ_UNREACHABLE_VIEW` — dead scope config.
340
- - `AUTHZ_NOT_OVER_RESOURCE` — a `not` over a SQL site (the null-trap).
341
- - `AUTHZ_PUSHDOWN_COST` — an `info` report of each permission's subquery count and recursive-CTE depth.
342
- - `AUTHZ_CAPABILITY_CEILING` — **error** — a resource grants a `scope:<kind>:<role>` read beyond its `grants` profile.
343
-
344
- Checks are **warn-by-default, compile-continues** (so a new check never breaks
345
- an existing build on upgrade); set **`QUICKBACK_AUTHZ_STRICT=true`** to promote
346
- every warning to a hard error. The analyzer is compile-time only — a defect in
347
- a check downgrades to a single warning in the default path and can never take
348
- down an otherwise-valid compile. See
349
- [Diagnostics](/define/diagnostics).
350
-
351
- ### Aggregate-only views — M0.1
352
-
353
- A view can return a rollup and **nothing else** — no `data[]`, no per-row field
354
- selection — via `aggregateOnly: true`, with an optional `kMin` k-anonymity floor
355
- that suppresses the aggregate below a threshold. This is what lets an F&B vendor
356
- read dietary **counts** for an event with zero attendee rows. See
357
- [Views](/define/views).
358
-
359
- ### Scope leftovers — M0.3
360
-
361
- The relationship-scope surface gains three pieces:
362
-
363
- - **Namespace scope-claim refresh** — a namespace gating `/event/:eventId/*` on a single conferring relationship lane refreshes `ctx.scope.<kind>` in memory for the request, so an attendee hitting an action under the prefix gets the scoped role stamped without a separate `/scope/v1/enter` round-trip.
364
- - **`q.scope()` autofill** — `q.scope('event')` auto-stamps a column from the verified scope claim (`ctx.scope.event.id`) on insert, the same way `q.scope('organization')` stamps the tenant column. Insert-only and null-safe; it adds no read-time `WHERE`.
365
- - **Set-valued sub-keys** — a `subKeys` entry ending in `[]` (e.g. `'shuttleId[]'`) projects **every** matched relationship row's value into the claim as a `string[]`, and the matching firewall arm is rewritten to an `inArray` row-slice (a driver covering multiple buses). An absent claim lowers to `inArray(col, [])` — a clean deny.
366
-
367
- See [Scopes & capability grants](/define/scopes).
368
-
369
- ### Namespace scope-minting (`mintScope`) — §5.3
370
-
371
- A namespace can now MINT a persisted scope JWT from its resolver. Set
372
- **`mintScope: true`** and, on a successful relationship probe, the resolver
373
- returns a scope token via `set-auth-token` — so a native client hitting
374
- `/event/:eventId/*` carries the scoped role forward **without** calling
375
- `/scope/v1/enter`.
376
-
377
- ```typescript
378
- authz: {
379
- namespaces: {
380
- eventScope: { prefix: '/event/:eventId', via: ['attendeeOf'], mintScope: true },
381
- },
382
- }
383
- ```
384
-
385
- The mint fires **only** when `via:` confers exactly one scope role
386
- unambiguously (a single conferring relationship lane); a multi-lane,
387
- bulk-grant, or asymmetric `via:` **suppresses** the mint (fail-closed — those
388
- callers use `/scope/v1/enter`). The token reuses the shared mint helper (TTL
389
- clamped to ≤180s, sibling scope kinds carried forward) and the mint is
390
- **best-effort** — a mint failure never fails the request, since the in-memory
391
- stamp already authorized it. Opt-in per namespace; defaults to `false`. See
392
- [Scopes — `mintScope`](/define/scopes#mintscope-mint-the-scope-token-from-the-namespace-resolver).
393
-
394
- > **Gotcha:** a namespace emits its resolver — and thus the refresh and the
395
- > mint — **only** when at least one *standalone* action's `path:` falls under
396
- > the prefix. A namespace containing only record-based actions (which mount
397
- > under their resource's CRUD routes, not the prefix) is **inert**. Add a
398
- > standalone action like `eventHome` at `/event/:eventId/home`. See
399
- > [Scopes — the resolver gotcha](/define/scopes#gotcha-a-namespace-only-emits-its-resolver-when-it-claims-a-standalone-action).
400
-
401
- ## v0.36.3 — May 25, 2026
402
-
403
- ### Fix: `/auth/v1/*` handler forwards `executionCtx` so OTP emails actually send
404
-
405
- The generated `createAuth(env, cf?, executionCtx?)` schedules the fire-and-forget
406
- verification-OTP send through `executionCtx.waitUntil(...)` — Better Auth advises
407
- **not** awaiting the send so its latency doesn't leak into auth response timing.
408
- That only works when `executionCtx` is passed. The composed Cloudflare worker
409
- index emitted a **bare** `createAuth(c.env)` at the `app.all('/auth/v1/*')`
410
- handler, so on Cloudflare the unawaited SES/SNS send was cancelled the moment the
411
- handler returned — `send-verification-otp` returned 200 but no email went out.
412
-
413
- The handler now threads `createAuth(c.env, c.req.raw.cf as any, c.executionCtx)`,
414
- matching the action call-sites (`record-based`, `standalone`, `core/helpers`) and
415
- the `getSession` call now passes the `cf` binding. (The earlier waitUntil fix had
416
- only patched the legacy `providers/runtime` index emitter, not this composed one —
417
- the two had drifted.) Recompile + redeploy to pick it up.
418
-
419
- ## v0.36.2 — May 25, 2026
420
-
421
- Two firewall fixes uncovered in a relationship-scoped (event-attendee) project:
422
- scoped reads stopped hiding rows behind a misclassified soft-delete column, and
423
- the list route stopped rejecting org-optional callers before the firewall ran.
424
-
425
- ### Fix: a firewall `isNull` predicate on a non-`deletedAt` column no longer globalizes as soft-delete
426
-
427
- The scoped `db` wrapper used by actions enforces soft-delete by injecting
428
- `isNull(<col>)` into reads. It built its list of soft-delete columns by treating
429
- **any** firewall `{ field, isNull: true }` predicate as a project-wide soft-delete
430
- marker — so an `isNull` predicate on a foreign-key column (e.g.
431
- `{ field: 'agendaItemId', isNull: true }`) was broadcast to **every** table that
432
- merely had an `agendaItemId` column, rewriting scoped reads to
433
- `agenda_item_id IS NULL`. Real rows (non-null FK) became invisible, so an action
434
- that read-before-write saw "no row," attempted an insert, and 500'd on the
435
- `(agenda_item_id, guest_id)` unique constraint.
436
-
437
- Only `deletedAt` — the column the compiler injects into every table — now enters
438
- the project-global soft-delete list. A custom `isNull` predicate is still enforced
439
- **per-table** by that table's firewall (route layer); it is simply no longer
440
- broadcast across the whole schema. This mirrors the v0.28 fix that made custom
441
- owner columns per-table rather than global.
442
-
443
- ### Fix: list route no longer hard-requires an org when the firewall makes org optional
444
-
445
- The generated CRUD **list** route emits an `ORG_REQUIRED` 400 (with a sysadmin
446
- escape) before the firewall runs. It fired whenever an org scope appeared
447
- **anywhere** in the firewall — including when org is just one arm of an `any:`
448
- group. So after the relationship-scope migration made a firewall org-optional
449
- (`any: [ { organizationId = ctx.activeOrgId }, { …via relationship } ]`), a
450
- plain-JWT caller with no `activeOrgId` (e.g. an event attendee scoped by
451
- relationship) got an instant 400 — the org-optional firewall that would have
452
- scoped them correctly never even ran.
453
-
454
- The gate now keys off org **mandatoriness** (`firewallRequiresOrg`): it fires
455
- only when an org claim is genuinely required — a top-level (implicit-AND) or
456
- `all`-nested org predicate. When org is one arm of an `any:` group, the list
457
- route skips the 400 and lets the null-safe firewall scope the caller: the org
458
- arm drops when `activeOrgId` is absent, sibling arms (relationship/owner) bind,
459
- and `anyGuarded` denies (`1 = 0`) when every arm drops — so a no-org caller sees
460
- exactly what the declared policy grants, never an unbounded cross-tenant read.
461
- `?organizationId=` cross-tenant addressing and the sysadmin escape are unchanged,
462
- and a plain org-scoped resource (no `any:` group) keeps the `ORG_REQUIRED` gate
463
- byte-for-byte. Write paths (create / put / batch) still require an org so new
464
- rows are always stamped with a tenant.
465
-
466
- ## v0.36.1 — May 25, 2026
467
-
468
- Relationship-derived **scoped roles** — request-scoped authorization minted from
469
- a verified relationship into a short-lived JWT.
470
-
471
- ### `authz.scopes` — scoped roles via a relationship probe
472
-
473
- A new `authz.scopes` block turns a declared relationship into a request-scoped
474
- role. Key the scope by a request field and back each role with a relationship:
475
-
476
- ```ts
477
- authz: {
478
- relationships: {
479
- attendeeOf: {
480
- from: 'guests',
481
- subject: { column: 'userId', equals: 'ctx.userId' },
482
- resource: { column: 'eventId' },
483
- where: { status: 'confirmed' },
484
- },
485
- },
486
- scopes: {
487
- event: {
488
- requestField: 'eventId',
489
- roles: { attendee: { via: 'attendeeOf' } }, // shorthand: attendee: 'attendeeOf'
490
- },
491
- },
492
- }
493
- ```
494
-
495
- The compiler emits a `/scope/v1/enter` route that probes the relationship for the
496
- caller ("is this user a confirmed guest of `eventId`?") and, on success, mints a
497
- short-lived JWT carrying the verified scope. The auth middleware reads that claim
498
- into `ctx.scope.<kind>` (e.g. `ctx.scope.event`).
499
-
500
- Scoped roles then work everywhere roles do — `read.access`, view access,
501
- `masking.show`, action access — as `scope:<kind>:<role>`, and the firewall can
502
- scope rows by the verified id:
503
-
504
- ```ts
505
- read: { access: { roles: ['admin', 'member', 'scope:event:attendee'] } },
506
- masking: { email: { type: 'email', show: { roles: ['admin', 'scope:event:organizer'] } } },
507
- firewall: { any: [
508
- { field: 'organizationId', equals: 'ctx.activeOrgId' },
509
- { field: 'eventId', equals: 'ctx.scope.event' },
510
- ] },
511
- ```
512
-
513
- So an attendee who "enters" an event reads that event's guest list — the `eventId`
514
- firewall arm matches their verified scope — with no org-membership role, and
515
- `email` stays masked unless they hold `scope:event:organizer`.
516
-
517
- ### Scoped-role name sugar
518
-
519
- Write the bare role name and the compiler lowers it to canonical
520
- `scope:<kind>:<role>` when it resolves uniquely:
521
-
522
- ```ts
523
- access: { roles: ['attendee'] } // → scope:event:attendee
524
- ```
525
-
526
- Reserved names (`admin`, `member`, `owner`), pseudo-roles, and anything declared
527
- in `authz.roles` are never rewritten. A bare name that's ambiguous across scopes
528
- is a compile error pointing you to the explicit `scope:<kind>:<role>` form.
529
-
530
- ## v0.36.0 — May 25, 2026
531
-
532
- Project-wide `id` generation now applies to every write path, action `db` is
533
- typed on Cloudflare D1, and realtime rooms can be gated on a unique non-PK column.
534
-
535
- ### `id` default moves to the column (`$defaultFn`)
536
-
537
- The configured `generateId` strategy now lands on the `id` column itself —
538
- `id: text("id").primaryKey().$defaultFn(() => createId())` — not just inside the
539
- auto-CRUD route handler. Previously a table with an explicit `text("id").primaryKey()`
540
- kept a bare PK, so a hand-written action doing `db.insert(...).values({…})` got no
541
- `id` and failed at runtime with a `NOT NULL` 500 — invisible to `tsc` because the
542
- scoped `db` was `any`. The injector (which already did this for tables with no
543
- declared PK) now also appends the strategy's `$defaultFn` to an explicit `id` PK.
544
- `generateId: false` (client-supplied ids) and `serial`/integer PKs are left
545
- untouched; the rewrite is idempotent. `$inferInsert` now marks `id` optional.
546
-
547
- ### Action `db` is typed on Cloudflare D1
548
-
549
- The scoped `db` passed to custom actions is no longer `any`. On D1 projects the
550
- per-feature `define-action` helper types it as a Drizzle client whose
551
- `.insert().values()` makes the org/owner/team scope columns optional (the runtime
552
- fills them from context), while every other column you declared stays required —
553
- so `tsc` catches a forgotten column, typos, and wrong types, and query results
554
- come back typed. Neon/Postgres keep `db: any` for now.
555
-
556
- `ctx.userId` is also narrowed to `string` (not `string | undefined`) in actions
557
- whose `access` requires authentication — so a trusted write like
558
- `db.insert(t).values({ ownerId: ctx.userId })` type-checks without a cast.
559
- Actions reachable anonymously (a `PUBLIC` arm, including inside `or`/`and`) keep
560
- `ctx.userId` optional.
561
-
562
- ### `access.resource` gains an optional `key`
563
-
564
- The per-room authorization gate (`bindings.durableObjects[].access`) always
565
- matched the WebSocket roomId against the backing table's primary key —
566
- `eq(table.id, rowId)`. Rooms addressed by a different unique column had no way
567
- to use it: a Yjs collaborative editor keyed by `event_pages.yjsRoomId`
568
- (`ns.idFromName(row.yjsRoomId)`) would never match on `id`, so projects dropped
569
- the `access` block and hand-rolled enforcement in `onConnect` — or, more often,
570
- shipped no row-level check at all, leaving the room reachable by any
571
- authenticated user who could guess a room id.
572
-
573
- The long form now accepts `key`:
574
-
575
- ```ts
576
- access: { resource: { feature: 'event-pages', table: 'eventPages', key: 'yjsRoomId' } }
577
- ```
578
-
579
- The gate emits `eq(table.<key>, rowId)` against the named column. `key` defaults
580
- to `'id'`, so every existing pin is byte-for-byte unchanged, and it also works
581
- inside each `resources[kind].resource` of the multi-resource form. The compiler
582
- validates the column exists against the pinned table's schema at compile time.
583
-
584
- The "multi-table feature is ambiguous" compile error now points at all three
585
- escapes — the long-form pin, the `key` option for non-id rooms, and declaring
586
- the table's firewall with a `via:` relationship so membership gating runs in the
587
- gate with no hand-written `onConnect`. See
588
- [PartyServer rooms → per-room authorization](/platform/realtime/partyserver-rooms).
589
-
590
- ## v0.35.0 — May 25, 2026
591
-
592
- New **FGA pillar** — OpenFGA / Google Zanzibar Relationship-Based Access
593
- Control (ReBAC), compiled into your Worker. Plus a public-sharing surface
594
- (type-bound public access + signed share links) built on it.
595
-
596
- ### Relationship-based access control (`authz.fga`)
597
-
598
- Role-based access and one-hop relationship joins can't express *graph-shaped*
599
- permissions: an `editor` who is automatically a `viewer`, a document that
600
- inherits viewers from its folder, a `team#member` group grant, or a per-record
601
- assignment that doesn't require a global role. The new `authz.fga` block adds a
602
- true ReBAC engine modeled on [OpenFGA](https://openfga.dev):
603
-
604
- - **Model** — declare object types, relations, and userset rewrites in the
605
- OpenFGA modeling DSL (`or` / `and` / `but not`, `[user:*]` public access,
606
- `[team#member]` usersets, `viewer from parent` tuple-to-userset). The compiler
607
- parses and semantically validates it at compile time — dangling type or
608
- relation references fail the compile loudly.
609
- - **Tuples** — stored in a compiler-owned, organization-scoped `fga_tuples`
610
- table the compiler emits and migrates. A Check never reads another tenant's
611
- tuples.
612
- - **Check engine** — resolved entirely inside the Worker (no external auth
613
- service): direct tuples, type-bound public access, userset subjects, computed
614
- usersets, tuple-to-userset, request-scoped contextual tuples, with cycle
615
- detection and a depth cap.
616
- - **`ctx.fga`** — `check` / `listObjects` / `expand` / `write` / `read`,
617
- org-scoped, available in every action and handler.
618
- - **`access: { fga: { relation, object } }`** — a new declarative access arm.
619
- The compiler fetches the record and emits an inline, fail-closed
620
- `ctx.fga.check('user:' + ctx.userId, relation, object)` gate (`object` is a
621
- `job:{id}` template over the record's columns).
622
- - **Collection-level FGA filtering** — an `fga` arm on `read.access` (or a named
623
- view) now filters the collection `GET /`, not just `GET /:id`. The compiler
624
- resolves the caller's authorized object ids via the engine's `ListObjects` and
625
- injects an `inArray(id, …)` into the list query, so pagination, `total`, and
626
- `hasMore` stay correct. Supported shapes are bare `{ fga }`,
627
- `or:[{ roles }, { fga }]`, and `and:[{ roles }, { fga }]`; deeper nesting is a
628
- compile error. The authorized set is bounded by `authz.fga.listObjects.maxIds`
629
- (default 1000) — past the cap the request fails with a hard 422
630
- (`FGA_LIST_TOO_LARGE`) pointing to `POST /fga/v1/list-objects` for paginated
631
- enumeration.
632
- - **REST API** — an OpenFGA-compatible surface at `/api/v1/fga/v1`
633
- (`check`, `list-objects`, `expand`, `read`, `write`), tenant-scoped; writes
634
- gated by `authz.fga.writeRoles` (default `['admin']`).
635
-
636
- ### Public sharing
637
-
638
- `authz.fga.sharing` turns the FGA engine into a public-sharing mechanism:
639
-
640
- - **Type-bound public access** — a model relation listing `user:*` becomes
641
- shareable-to-everyone by writing one tuple.
642
- - **Signed share links** — `POST /api/v1/fga/v1/share` mints an HMAC-signed,
643
- opaque token for one `(object, relation)` grant; `GET /share/v1/:token` is a
644
- **public, unauthenticated** route that verifies the token and returns a
645
- configured public projection of the object (it leaks nothing beyond that
646
- object + relation).
647
- - **Share URL** — both a dedicated route (`/share/v1/:token`, always mounted)
648
- and an optional vanity base URL (`share.<your-domain>`, added to your runtime
649
- routes) are supported.
650
-
651
- ### q-recruit showcase
652
-
653
- The recruitment example now models `organization → job → application/interview`
654
- with FGA: a `recruiter` is automatically a `viewer` and `can_manage` of a job,
655
- applications inherit viewers from their job, and a job can be made publicly
656
- shareable. New `assign-recruiter` and `make-public` actions demonstrate
657
- `ctx.fga.write`, and `jobs.update` gates on `{ or: [{ roles }, { fga }] }`.
658
-
659
- ## v0.34.1 — May 24, 2026
660
-
661
- Patch fixing a silent-skip bug in drizzle migration emission, plus a new
662
- CLI subcommand for inspecting and repairing migration-state drift.
663
-
664
- ### Compiler now fails loud on drizzle migration state drift
665
-
666
- When `quickback/drizzle/<dialect>/meta/_journal.json` fell out of sync
667
- with the on-disk `.sql` files — typically because someone hand-rolled a
668
- migration without a journal bump, or because a prior compile collided
669
- with an existing tag — drizzle-kit's diff base became stale and it
670
- silently skipped emission. The compile reported success, no new `.sql`
671
- was written for newly defined tables, and the next `wrangler deploy`
672
- shipped a Worker that 500'd on every request touching those tables.
673
-
674
- The compiler now runs a precheck before any drizzle-kit invocation and
675
- refuses to compile when it detects any of:
676
-
677
- - `.sql` files on disk with no matching entry in `_journal.json`
678
- - journal entries that reference missing `.sql` files
679
- - non-sequential `idx` values in `_journal.json`
680
- - two `.sql` files sharing the same `idx`
681
- - (for `auth/` and `features/` only) journal entries with no matching
682
- `<idx>_snapshot.json` — drizzle-kit needs the snapshot as a diff base
683
-
684
- Snapshot/journal drift that the previous `console.warn` only logged
685
- server-side is now propagated to the CLI and printed under
686
- "Compilation warnings".
687
-
688
- ### New `quickback migrations doctor` CLI command
689
-
690
- Two modes:
691
-
692
- ```bash
693
- quickback migrations doctor # diagnose
694
- quickback migrations doctor --rebuild-journal # repair
695
- ```
696
-
697
- Diagnose walks `quickback/drizzle/{auth,features,files,webhooks,audit}/`,
698
- prints a per-dir table (`.sql files`, `journal entries`, `snapshots`),
699
- and flags every drift kind the compiler precheck enforces. Repair
700
- rewrites `_journal.json` from on-disk `.sql` filenames in sorted order —
701
- this is the recovery recipe users were applying by hand. Snapshot drift
702
- on drizzle-kit dirs (`auth/`, `features/`) can only be repaired by
703
- running `drizzle-kit introspect` against the live DB; the doctor prints
704
- the exact command.
705
-
706
- ### Upgrade path for projects in the broken state
707
-
708
- Projects with existing drift will get a clear error message and an
709
- explicit fix command on the next compile against v0.34.1:
710
-
711
- ```
712
- ✖ Drizzle migration state is inconsistent — refusing to compile.
713
- Causes:
714
- - quickback/drizzle/features: 7 .sql file(s) have no matching journal entry: ...
715
- Fixes:
716
- - Run `quickback migrations doctor` to diagnose, then
717
- `quickback migrations doctor --rebuild-journal` to repair.
718
- ```
719
-
720
- No action needed for projects whose journals are already in sync.
721
-
722
- ## v0.34.0 — May 23, 2026
723
-
724
- Customizable email-OTP templates and a dedicated admin-create-user hook
725
- — closes a longstanding gap where projects on `email.provider: 'aws-ses'`
726
- had to live with the generic "Your password reset code is ..." copy for
727
- admin-bootstrapped accounts.
728
-
729
- ### Per-type email-OTP template overrides
730
-
731
- Drop a `.ts` file at `quickback/email-templates/<name>.ts` that
732
- default-exports `(input) => ({ subject, html, text })`, then reference
733
- it from the new `plugins.emailOtp.templates` map. Missing keys fall
734
- through to the package defaults from `@quickback-dev/better-auth-aws-ses`
735
- — this is purely additive; existing `emailOtp: true` projects emit the
736
- same code they did before.
737
-
738
- ```ts title="quickback/quickback.config.ts"
739
- defineAuth("better-auth", {
740
- plugins: {
741
- emailOtp: {
742
- templates: {
743
- 'forget-password': './email-templates/forget-password',
744
- 'welcome': './email-templates/welcome',
745
- },
746
- },
747
- },
748
- });
749
- ```
750
-
751
- ```ts title="quickback/email-templates/welcome.ts"
752
- export default function welcome({ otp, name, appName, appUrl }) {
753
- const greeting = name ? `Hi ${name},` : 'Hi,';
754
- return {
755
- subject: `Welcome to ${appName} — set your password`,
756
- html: `<h1>Welcome to ${appName}</h1><p>${greeting} use this code: <b>${otp}</b></p>`,
757
- text: `${greeting}\n\nYour ${appName} code: ${otp}`,
758
- };
759
- }
760
- ```
761
-
762
- Recognized keys: `'sign-in' | 'email-verification' | 'forget-password' |
763
- 'welcome'`. The first three map 1:1 to Better Auth's emailOTP `type`
764
- enum.
765
-
766
- ### Synthetic `welcome` routing — credential-row lookup
767
-
768
- `'welcome'` has no native Better Auth OTP type. When configured, the
769
- generated `sendVerificationOTP` callback queries the `account` table
770
- for a `credential`-provider row for the recipient *before* rendering;
771
- if the user has none (typical of an admin-plugin-created account
772
- without a password), the send is rerouted through the welcome
773
- template. Without a welcome template, those sends fall through to
774
- `forget-password` — same behavior as before. DB-error path fails open
775
- to the normal forget-password flow so a transient failure can't
776
- deadlock the password-reset surface.
777
-
778
- Provider scope: overrides are only honored on `email.provider:
779
- 'aws-ses'`. The Cloudflare Email path uses the helper's own template
780
- pipeline and ignores the new config.
781
-
782
- ### New recognized hook: `after-admin-user-create.ts`
783
-
784
- A virtual event that wires into the same Better Auth
785
- `databaseHooks.user.create.after` slot as the generic
786
- `after-user-create.ts`, but the generator gates the call on
787
- `_baCtx?.context?.path` matching `/admin/create-user` so it only fires
788
- when the row came from the admin plugin's create-user endpoint. Use it
789
- for first-time-user provisioning (welcome email, default org
790
- assignment, audit-log writes) without inspecting the BA context by
791
- hand. The generic `after-user-create.ts` still runs for every signup,
792
- including admin-created ones; the two coexist in a single merged
793
- `after:` handler.
794
-
795
- ```
796
- quickback/hooks/
797
- after-user-create.ts # every signup
798
- after-admin-user-create.ts # admin-plugin /admin/create-user only
799
- ```
800
-
801
- ### File transport mirrors existing slots
802
-
803
- The new `quickback/email-templates/` directory follows the same
804
- pattern as `quickback/plugins/`, `quickback/hooks/`, and
805
- `quickback/lib/`: the CLI walks the folder and uploads each `.ts` file
806
- in a new `projectEmailTemplates` field on the compile request; the
807
- better-auth provider stages referenced files into
808
- `src/email-templates/<name>.ts` and emits default imports in
809
- `src/lib/auth.ts`. Files not referenced by any template entry are
810
- ignored — the CLI uploads the whole directory; the compiler picks only
811
- what's needed. A relative path pointing at a file the CLI never
812
- shipped fails compile fast with a "place the file at … and rerun"
813
- hint.
814
-
815
- See [AWS SES Plugin → Per-Type Template Overrides](/platform/auth/plugins/aws-ses#per-type-template-overrides)
816
- and [Account UI → Hooks](/ui/account/hooks#recognized-events).
817
-
818
- ## v0.33.6 — May 22, 2026
819
-
820
- Two compiler-side fixes for the queue-consumer / embedding surface and one
821
- schema-emission bug that blocked `generateId: 'cuid'` projects.
822
-
823
- ### Schema-emitted `createId()` now ships with a polyfill (no missing import)
824
-
825
- When `providers.database.config.generateId` is set to `'cuid'`, the audit-
826
- field injector emits an id column like
827
- `id: text('id').primaryKey().$defaultFn(() => createId())`. Previously the
828
- schema source referenced `createId` but no import landed, so `tsc` on the
829
- generated project failed with `Cannot find name 'createId'`. Recurring
830
- bug — every recompile re-emitted the broken file (the "do not edit"
831
- banner doesn't protect from regeneration).
832
-
833
- Fix: the injector now prepends a top-of-file polyfill backed by
834
- `crypto.randomUUID()` — a Workers / Node 19+ / Bun global — instead of
835
- trying to import `@paralleldrive/cuid2`. The package isn't bundled by
836
- Quickback (per the [hooks doc](/ui/account/hooks)'s "stick to
837
- built-ins" guidance) and the schema-gen sandbox can't resolve project
838
- node_modules anyway, so the polyfill is the only path that works
839
- out-of-the-box.
840
-
841
- ```ts title="Generated schema header (cuid strategy)"
842
- import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
843
-
844
- // Polyfill — Quickback compiler does not ship @paralleldrive/cuid2 in
845
- // generated projects, and the schema-gen sandbox can't see node_modules.
846
- // crypto.randomUUID() is a Workers / Node 19+ / Bun global.
847
- const createId = () => crypto.randomUUID();
848
-
849
- export const widgets = sqliteTable('widgets', {
850
- id: text('id').primaryKey().$defaultFn(() => createId()),
851
- // ...
852
- });
853
- ```
854
-
855
- If you want real cuid2 strings (collision-resistant, shorter than UUIDs)
856
- you can still install `@paralleldrive/cuid2` and add the import yourself —
857
- the injector honours an existing import and skips the polyfill.
858
-
859
- ### queue-consumer.ts header reflects what the file actually does
860
-
861
- Before v0.33.6 the generated `src/queue-consumer.ts` always carried the
862
- preamble:
863
-
864
- ```
865
- * Queue Consumer for Embedding Jobs & Custom Queue Handlers
866
- *
867
- * Processes embedding jobs asynchronously using Workers AI and Vectorize.
868
- * Also supports custom queue handlers defined in services/queues/.
869
- ```
870
-
871
- — even on projects with zero embedding features. Users on
872
- custom-queue-only deployments would search for `EMBEDDINGS_QUEUE` /
873
- Vectorize bindings that wrangler.toml correctly didn't emit, wasting
874
- diagnostic time.
875
-
876
- The preamble now reflects the actual surface:
877
-
878
- | `hasEmbeddings` | `hasCustomHandlers` | Header |
879
- |---|---|---|
880
- | ✓ | ✓ | "Queue Consumer for Embedding Jobs & Custom Queue Handlers" |
881
- | ✓ | — | "Queue Consumer for Embedding Jobs" |
882
- | — | ✓ | "Queue Consumer for Custom Queue Handlers" + explicit "No embedding bindings (EMBEDDINGS_QUEUE / Vectorize / AI) are referenced" |
883
- | — | — | "Queue Consumer Stub" (additionalQueues with no handler yet) |
884
-
885
- ### Symmetric embedding detection prevents silent drift
886
-
887
- The wrangler.toml emit path (`EMBEDDINGS_QUEUE` producer/consumer
888
- declaration) and the queue-consumer.ts emit path (embedding handler code)
889
- previously used two different functions to detect "this project has
890
- embeddings": `hasEmbeddingsConfig` checked both `feature.resource.
891
- embeddings` and `feature.tables[].resource.embeddings`;
892
- `extractEmbeddingFeatures` only iterated the tables array. A feature
893
- shape with feature-level embeddings sugar but no populated tables would
894
- land in the wrangler binding while NOT landing in the consumer file
895
- — silent drift.
896
-
897
- `hasEmbeddingsConfig` is now defined as
898
- `extractEmbeddingFeatures(...).length > 0`. The two stay in lock-step
899
- by construction. `extractEmbeddingFeatures` now reads from both shapes
900
- (tables-level when present, feature-level otherwise).
901
-
902
- ## v0.33.5 — May 22, 2026
903
-
904
- Two structural fixes that resolve recurring classes of bug for projects with
905
- integer primary keys and for projects whose audit columns drift between
906
- schema and database.
907
-
908
- ### URL `:id` params coerce to Number when the PK column is integer
909
-
910
- Per-id CRUD handlers (`GET /:id`, `PATCH /:id`, `DELETE /:id`, `PUT /:id`)
911
- extracted the URL param as a string and passed it straight into
912
- `eq(table.id, id)`. For resources with `integer().primaryKey()` columns —
913
- triggered either by `generateId: 'serial'` on the database config or by
914
- imported legacy schemas — every per-id route raised a downstream tsc
915
- type error (integer ≠ string). One production project reported 249 such
916
- errors across 30+ generated `*.routes.ts` files.
917
-
918
- Generated handlers for integer-PK resources now emit:
919
-
920
- ```ts
921
- const __idRaw = c.req.param('id');
922
- const id = Number(__idRaw);
923
- if (!Number.isInteger(id)) {
924
- return c.json(ValidationErrors.invalidInput([{
925
- path: ['id'],
926
- message: `Expected integer, got "${__idRaw}"`,
927
- code: 'invalid_type',
928
- }]), 400);
929
- }
930
- ```
931
-
932
- Text-PK resources (the default and the recommended path) are unchanged.
933
-
934
- A soft-deprecation warning now fires at compile time when
935
- `providers.database.config.generateId === 'serial'` is set, nudging new
936
- projects toward text-PK strategies (`'cuid'`, `'uuid'`, `'prefixed'`, or
937
- the default). Existing serial-PK projects keep working.
938
-
939
- ### Audit-field injection now runs for every dialect
940
-
941
- The compiler auto-injects `created_at`, `modified_at`, `created_by`, and
942
- `modified_by` columns into every feature table, and the scoped-db
943
- runtime auto-fills them on insert. Until v0.33.5, the early injection
944
- step in `parseCompilerInput` was gated on `targetDialect ===
945
- 'postgresql'`. SQLite/D1 projects fell back to a later injection inside
946
- `generateFeature`, which only fired when `feature.tables.length > 0` —
947
- features arriving without a populated tables array (raw-drizzle shapes,
948
- certain legacy migration tables) silently skipped audit injection.
949
-
950
- Symptom: schemas claimed the columns existed (so the scoped-db proxy
951
- tried to fill them on insert), but the database table didn't have them.
952
- Inserts failed with "column doesn't exist." Users reported this for the
953
- `user_preferences` table and, earlier, for `chat_reads` (the
954
- `0028_chat_reads_id_column.sql` incident).
955
-
956
- The early injection now runs for all dialects. `injectAuditFields` is
957
- already idempotent, so the subsequent per-target injections in
958
- `compilePureSQLTarget` and `feature-generator.ts` are no-ops when the
959
- columns are already present. Net: every feature's schema source has
960
- audit columns by the time drizzle-kit reads it, regardless of dialect
961
- or feature shape.
962
-
963
- Upgrade path: recompile against v0.33.5, commit the generated migration
964
- that adds the missing audit columns, then `wrangler d1 migrations apply`.
965
-
966
- ## v0.33.4 — May 21, 2026
967
-
968
- Patch fixes covering upgrade-path bugs and OpenAPI spec/route divergence. No
969
- new features or breaking changes.
970
-
971
- ### OpenAPI emits CRUD endpoints only when the route emitter registers them
972
-
973
- The OpenAPI emitter previously advertised `GET /`, `POST /`, `GET /:id`,
974
- `PATCH /:id`, `DELETE /:id`, and the corresponding `/batch` operations on
975
- every resource, regardless of which CRUD verbs were actually declared.
976
- Clients generated from `openapi.json` then issued requests that fell
977
- through to `ROUTE_NOT_FOUND` from the firewall layer — a silent contract
978
- break for anyone whose code path was driven by openapi-typescript or
979
- similar codegen.
980
-
981
- Each gate now mirrors the route emitter exactly. A resource that only
982
- declares `read + create + delete` (no `update`) gets no PATCH operations
983
- in the spec. A write-only sink (`create` only, no `read`) gets no GET
984
- operations. Same for batch variants — `POST /batch` only when
985
- `crud.create` is set, `DELETE /batch` only when `crud.delete` is set,
986
- etc.
987
-
988
- If your generated client was calling these spurious endpoints, those
989
- calls were already failing at runtime; this just removes them from the
990
- spec.
991
-
992
- ### Legacy D1 audit-timestamp migrations rewritten in place
993
-
994
- Compilers ≤ v0.33.1 emitted
995
- `DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))` for audit columns
996
- (`created_at`, `modified_at`, etc.). Cloudflare D1 rejects this in
997
- `ALTER TABLE ADD COLUMN` with `SQLITE_ERROR [code: 7500] "Cannot add a
998
- column with non-constant default"`. v0.33.2 stopped emitting the
999
- non-constant form, but pending unapplied legacy migration files on
1000
- upgrading projects still poisoned `wrangler d1 migrations apply` and
1001
- left the deploy stuck.
1002
-
1003
- The D1 migration safety pass now retrofits these files in place,
1004
- replacing the strftime expression with the same `'1970-01-01T00:00:00.000Z'`
1005
- constant v0.33.2+ uses. The compile-time warning lists the affected
1006
- columns:
1007
-
1008
- ```
1009
- ⚠ D1 helper adjusted features migrations for Cloudflare D1 safety:
1010
- 0004_early_dracula.sql [rewrote=applied_at,created_at,modified_at]
1011
- ```
1012
-
1013
- Upgrade path: recompile against v0.33.4, commit the rewritten SQL, then
1014
- `wrangler d1 migrations apply` proceeds.
1015
-
1016
- ### D1 helper warning is now actionable
1017
-
1018
- The same migration safety pass auto-prepends `PRAGMA defer_foreign_keys
1019
- = on` to every drizzle table-rebuild migration — required on D1
1020
- because it doesn't honour `PRAGMA foreign_keys=OFF/ON` mid-migration the
1021
- way SQLite does. The pass used to surface this insertion as a warning
1022
- on every recompile, training users to ignore the warning entirely.
1023
-
1024
- The PRAGMA is still inserted (it has to be), but no longer fires the
1025
- warning. Stripped Better Auth cleanup, reordered child-first DROPs, and
1026
- the new `rewrote=…` annotation above still warn — those are cases where
1027
- a human should look.
1028
-
1029
- ### Reference: `account.appUrl` / `account.tenantPattern`
1030
-
1031
- v0.33's redesigned dashboard org-card uses two new optional fields on
1032
- the `account` config to deep-link into the tenant's own app:
1033
-
1034
- ```ts
1035
- // quickback.config.ts
1036
- account: {
1037
- // …existing fields
1038
- appUrl: 'https://app.example.com',
1039
- tenantPattern: '/{slug}',
1040
- }
1041
- ```
1042
-
1043
- Both are typed in the config schema and baked into the Account SPA at
1044
- build time as `VITE_QUICKBACK_APP_URL` and `VITE_TENANT_URL_PATTERN`.
1045
- Without them, the dashboard falls back to a single-target card that
1046
- links to the account org-settings page (legacy v0.32 behaviour). Adding
1047
- them enables the two-zone layout with the external deep-link affordance.
1048
-
1049
- (No code change in v0.33.4 — the fields shipped with v0.33.0 but weren't
1050
- called out in the changelog.)
1051
-
1052
- ## v0.33.0 — May 21, 2026
1053
-
1054
- ### Dedicated hostnames for `/auth/v1/*` and `/api/v1/*` (Shape 1)
1055
-
1056
- Two new optional overrides let you carve specific backend surfaces onto dedicated hostnames, served by the same Worker:
1057
-
1058
- ```ts
1059
- // quickback.config.ts
1060
- auth: { domain: 'auth.example.com' }, // /auth/v1/* lives here too
1061
- api: { domain: 'api.example.com' }, // /api/v1/* lives here too
1062
- ```
1063
-
1064
- On the dedicated hostname, the hostname IS the namespace — `/v1/*` is a shortcut that the Worker-entry rewriter prepends with `/auth` or `/api` before route matching. So `https://api.example.com/v1/users` reaches the same handler as `https://quickback.example.com/api/v1/users`. Both forms work; the long form is also accepted on the dedicated host. Non-matching paths return a JSON 404 ("Not found on api.domain — this hostname serves /api/v1/* and the /v1/* shortcut only") — each hostname stays dedicated to its surface. `/health` and `/openapi.json` are explicit exceptions because monitoring/discovery agents expect them everywhere.
1065
-
1066
- Both new domains:
1067
- - Get a `{ pattern, custom_domain: true }` route in `wrangler.toml`
1068
- - Join `trustedOrigins` (CORS allowlist)
1069
- - Join the cross-subdomain cookie inference (auto-enables `crossSubDomainCookies` when ≥2 same-parent subdomains are configured)
1070
- - Join CSP `connect-src` so SPAs can fetch from them
1071
-
1072
- **Dual-reach:** all routes remain reachable at the unified backend host (see below) regardless of which dedicated hostnames are configured. The dedicated hostnames are aliases, never replacements.
1073
-
1074
- ### `quickback.{baseDomain}` codified as the always-present unified backend
1075
-
1076
- The compiler has always auto-inferred a `quickback.{baseDomain}` hostname when any subdomain is configured. v0.33 promotes this from inferred fallback to **load-bearing contract**:
1077
-
1078
- - The unified backend hostname is GUARANTEED to exist when any custom subdomain (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`) is set.
1079
- - Every compiler-emitted backend route (api, auth, storage, health, openapi, realtime, mcp, bundled SPAs, sysadmin endpoints) is reachable at the unified host, always.
1080
- - Per-surface domain overrides are additive (Shape 1) — they create more hostnames, never remove routes from the unified host.
1081
-
1082
- This is forward-pointing: the future management layer can rely on a single discovery URL pattern (`https://quickback.{baseDomain}/...`) to find any backend regardless of how the operator split their surfaces onto subdomains.
1083
-
1084
- Inference also extends to consider `auth.domain` and `api.domain` as domain sources, so a project configuring only one of them still derives `quickback.{baseDomain}` automatically. Explicit `config.domain` still wins over inference.
1085
-
1086
- ### `compiler.routes` config block (scaffold — partial)
1087
-
1088
- Optional path-prefix overrides for compiler-emitted system routes:
1089
-
1090
- ```ts
1091
- compiler: {
1092
- routes: {
1093
- storage: '/files', // default '/storage'
1094
- broadcast: '/realtime', // default '/broadcast/v1'
1095
- mcp: '/agent', // default '/mcp'
1096
- health: '/_health', // default '/health'
1097
- openapi: '/openapi.yaml', // default '/openapi.json'
1098
- },
1099
- }
1100
- ```
1101
-
1102
- **Status:** the config is validated and reaches the reserved-prefix registry (so SPA pass-through and compile-time collision detection already honor overrides), but the per-section route emitters still hardcode the defaults. Setting a non-default value today will produce a misconfigured Worker — the registry knows the new path but the actual `app.route('/storage/v1', …)` mount uses the old one. **Don't set these in production yet.** Per-section emit wiring lands in a follow-up.
1103
-
1104
- `/api/v1/` and `/auth/v1/` are NOT configurable here — those are deep contracts touched by feature emitters, OpenAPI generation, generated clients, and BA's own basePath. The Shape 1 hostname overrides above are the supported way to relocate them.
1105
-
1106
- ## v0.32.0 — May 21, 2026
1107
-
1108
- ### Single-origin path-routed architecture
1109
-
1110
- A modern Quickback project now runs on **one Cloudflare Worker behind one custom domain**, with the bundled Account and CMS SPAs path-mounted at `/account/` and `/cms/`, system routes at `/api/`, `/auth/`, `/storage/`, and the user's own SPAs anywhere else they want. No cross-subdomain cookies, zero CORS preflights, no separate `api.`/`account.`/`cms.` subdomains required:
1111
-
1112
- ```ts
1113
- // quickback.config.ts
1114
- apps: { www: { domain: 'app.example.com' } }, // user's root SPA
1115
- account: true, // bundled at /account/
1116
- cms: true, // bundled at /cms/
1117
- // /api/, /auth/, /storage/, /openapi.json, /health all live here too
1118
- ```
1119
-
1120
- The bug that previously broke this shape: when a hostname-mounted root SPA was configured (`apps.www.domain`), its middleware swallowed every path that wasn't in a hardcoded list (`/api/`, `/auth/`, `/admin/`, `/storage/`, `/health`). Requests to `/account/profile` got remapped to `/www/account/profile`, 404'd, then SPA-fallback'd to the wrong SPA. v0.32 introduces a **reserved-prefix registry** (`resolveReservedPrefixes` in `apps/compiler/src/generators/core/reserved-prefixes.ts`) as the single source of truth for what every catchall middleware must pass through:
1121
-
1122
- - **System** (always present): `/api/`, `/auth/`, `/storage/`, `/health`, `/openapi.json`
1123
- - **Conditional** (only when feature is on): `/account/` (when `account: true`), `/cms/` (when `cms: true`), `/broadcast/v1/` (realtime), `/mcp` (MCP server)
1124
- - **User-contributed**: every `apps.<name>.path` for path-mounted apps
1125
-
1126
- Path-mounted apps that collide with a system or bundled-SPA reservation throw a compile-time error naming both owners. `apps.api = { path: '/api' }` errors clearly instead of silently hijacking feature routes at runtime.
1127
-
1128
- ### Admin URL namespace migration: `/admin/v1/*` → `/auth/v1/admin/*`
1129
-
1130
- Quickback's legacy admin tier emitted three things under `/admin/v1/*`:
1131
-
1132
- 1. A role-admit middleware that admitted both `'admin'` and `'sysadmin'` — contradicting the pseudo-role evaluator's strict-independence model (`ADMIN` admits `'admin'` only; `SYSADMIN` admits `'sysadmin'` only).
1133
- 2. `GET /admin/v1/organizations` — a thin proxy to Better Auth's own `/auth/v1/organization/list`.
1134
- 3. `GET /admin/v1/sysadmin/organizations` — cross-tenant org listing, sysadmin-only.
1135
-
1136
- In v0.32, the first two are **removed** and the third **renames** to `GET /auth/v1/admin/list-organizations`. The new path sits under Better Auth's admin URL namespace (sibling of `/auth/v1/admin/list-users`, `/auth/v1/admin/ban-user`, etc.), follows BA's verb-noun convention, and keeps its sysadmin-only gate inside the handler — Quickback-emitted, not BA-mounted.
1137
-
1138
- What this enables: `/admin/*` is no longer a reserved system prefix. Projects can mount their own admin SPA via `apps.admin = { path: '/admin' }` without colliding with anything.
1139
-
1140
- What changes for callers:
1141
- - The bundled CMS SPA's sysadmin org switcher is updated in lockstep (no migration needed for projects using the SPA as-is).
1142
- - External callers of `/admin/v1/organizations` should migrate to BA's `/auth/v1/organization/list` (same behavior — caller's memberships).
1143
- - External callers of `/admin/v1/sysadmin/organizations` should migrate to `/auth/v1/admin/list-organizations`.
1144
- - Features that previously relied on the "admit both admin AND sysadmin" middleware should declare `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly on each route.
1145
-
1146
- The `ADMIN_ROUTE_FEATURES` carve-out in the compiler is also removed — feature routes always mount at `/api/v1/<feature>`, and admin-only behavior is enforced by per-operation `access: { roles: ['ADMIN'] }` at the resource level.
1147
-
1148
- ### Two compiler bug fixes
1149
-
1150
- - **Soft-delete index callback parameter bug.** The auto-index injector emitted hardcoded `t.<col>` references regardless of the existing extras callback's parameter name. When a user (or upstream transform) wrote `(table3) => ({ … })`, the appended composite-index entries referenced `t.organizationId, t.deletedAt` — `t` undefined inside the arrow scope, `ReferenceError` at module load. Fixed in `apps/compiler/src/utils/auto-indexes.ts` by capturing and reusing the callback's parameter name.
1151
- - **Reserved-word action filename collision.** Action discovery walks `actions/*.ts` and emits `import <name> from './actions/<name>'`. A user filename of `import.ts`, `delete.ts`, `await.ts`, `export.ts`, etc. produced `import import from './actions/import';` — a SyntaxError on module load. Fixed in `apps/compiler/src/codegen/discovered-actions.ts` by aliasing reserved-word and invalid-identifier filenames to `__action_<sanitized>` bindings while preserving the public action key (route emitters use bracket notation, so reserved-word keys are fine in the lookup map).
1152
-