@quickback-dev/cli 0.17.1 → 0.31.1

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 (85) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +17 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +28 -63
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/lib/api-client.d.ts +17 -0
  9. package/dist/lib/api-client.d.ts.map +1 -1
  10. package/dist/lib/api-client.js.map +1 -1
  11. package/dist/lib/file-loader.d.ts +24 -0
  12. package/dist/lib/file-loader.d.ts.map +1 -1
  13. package/dist/lib/file-loader.js +46 -0
  14. package/dist/lib/file-loader.js.map +1 -1
  15. package/dist/skill/docs/changelog.md +780 -1174
  16. package/dist/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  17. package/dist/skill/docs/compiler/cloud-compiler/index.md +9 -9
  18. package/dist/skill/docs/compiler/config/domains.md +44 -10
  19. package/dist/skill/docs/compiler/config/output.md +1 -1
  20. package/dist/skill/docs/compiler/config/providers.md +6 -12
  21. package/dist/skill/docs/compiler/config/variables.md +0 -30
  22. package/dist/skill/docs/compiler/definitions/access.md +203 -1
  23. package/dist/skill/docs/compiler/definitions/actions.md +40 -7
  24. package/dist/skill/docs/compiler/definitions/schema.md +6 -10
  25. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
  26. package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
  27. package/dist/skill/docs/compiler/index.md +15 -34
  28. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  29. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  30. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  31. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  32. package/dist/skill/docs/compiler/targets/index.md +6 -34
  33. package/dist/skill/docs/index.md +11 -5
  34. package/dist/skill/docs/stack/account-ui/customization.md +2 -14
  35. package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
  36. package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
  37. package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
  38. package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
  39. package/dist/skill/docs/stack/account-ui/index.md +5 -43
  40. package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
  41. package/dist/skill/docs/stack/auth/plugins/index.md +74 -0
  42. package/dist/skill/docs/stack/index.md +8 -4
  43. package/package.json +1 -1
  44. package/src/skill/docs/changelog.md +780 -1174
  45. package/src/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  46. package/src/skill/docs/compiler/cloud-compiler/index.md +9 -9
  47. package/src/skill/docs/compiler/config/domains.md +44 -10
  48. package/src/skill/docs/compiler/config/output.md +1 -1
  49. package/src/skill/docs/compiler/config/providers.md +6 -12
  50. package/src/skill/docs/compiler/config/variables.md +0 -30
  51. package/src/skill/docs/compiler/definitions/access.md +203 -1
  52. package/src/skill/docs/compiler/definitions/actions.md +40 -7
  53. package/src/skill/docs/compiler/definitions/schema.md +6 -10
  54. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
  55. package/src/skill/docs/compiler/getting-started/templates.md +58 -56
  56. package/src/skill/docs/compiler/index.md +15 -34
  57. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  58. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  59. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  60. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  61. package/src/skill/docs/compiler/targets/index.md +6 -34
  62. package/src/skill/docs/index.md +11 -5
  63. package/src/skill/docs/stack/account-ui/customization.md +2 -14
  64. package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
  65. package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
  66. package/src/skill/docs/stack/account-ui/features/index.md +1 -1
  67. package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
  68. package/src/skill/docs/stack/account-ui/index.md +5 -43
  69. package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
  70. package/src/skill/docs/stack/auth/plugins/index.md +74 -0
  71. package/src/skill/docs/stack/index.md +8 -4
  72. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  73. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  74. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  75. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  76. package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
  77. package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
  78. package/dist/skill/docs/stack/account-ui/worker.md +0 -362
  79. package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  80. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  81. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  82. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  83. package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
  84. package/src/skill/docs/stack/account-ui/standalone.md +0 -149
  85. package/src/skill/docs/stack/account-ui/worker.md +0 -362
@@ -1,582 +1,835 @@
1
1
  # Changelog
2
2
 
3
- Release notes for the Quickback compiler, CLI, and platform.
3
+ ## v0.24.0 — May 19, 2026
4
4
 
5
- ---
5
+ ### Cross-feature namespaces: one hoisted gate, many features
6
6
 
7
- ## v0.16.10 — May 14, 2026
7
+ v0.23 shipped `defineTable({ namespace: { prefix, via } })` — a hoisted relationship-resolver middleware that gates every standalone action in *one feature's* Hono app. That covers the 95% case where a domain concept (events) and the actions under it all live in the same feature directory.
8
+
9
+ v0.24 lifts the namespace to the project level so it can span multiple features. A new `authz.namespaces` block on `quickback.config.ts` declares a path-prefix gate that any feature's standalone action can participate in by matching the prefix in its `path:`. One synthetic routes file, one resolver mount, one relationship match per request — regardless of how many feature directories contribute actions.
10
+
11
+ ```ts
12
+ // quickback.config.ts
13
+ authz: {
14
+ relationships: {
15
+ attendeeOf: {
16
+ from: 'guests',
17
+ subject: { column: 'userId', equals: 'ctx.userId' },
18
+ resource: { column: 'eventId' },
19
+ loads: 'events',
20
+ exposeAs: 'event',
21
+ },
22
+ },
23
+ namespaces: {
24
+ eventScope: { prefix: '/event/:eventId', via: 'attendeeOf' },
25
+ },
26
+ }
27
+
28
+ // features/feeds/actions/feed-moments.ts (cross-feature)
29
+ export default defineAction({
30
+ path: '/event/:eventId/feed-moments',
31
+ method: 'POST',
32
+ // No gate boilerplate. ctx.event is typed.
33
+ });
34
+
35
+ // features/rsvp/actions/respond.ts (different feature, same namespace)
36
+ export default defineAction({
37
+ path: '/event/:eventId/respond',
38
+ method: 'POST',
39
+ });
40
+ ```
41
+
42
+ The compiler emits one `src/routes/__namespace-event-scope.routes.ts` mounted at `/api/v1/event/:eventId/*`. The file imports each contributing feature's `actions` map under a distinct alias (`feedsActions`, `rsvpActions`), runs the `attendeeOf` resolver once per request at the head of the file, and dispatches to the matching action handler.
43
+
44
+ #### Discovery is path-prefix-only
45
+
46
+ No new `namespace: 'eventScope'` field on `defineAction`. Actions opt in by matching `path:` against a declared namespace prefix — same model the table-level v0.23 form uses, just lifted to the project level. This means actions move in/out of the namespace based on their path strings, which is the simplest discovery story and matches today's convention (filenames and paths are already the discoverable surface).
47
+
48
+ #### Source-feature stays the action's home for metadata
49
+
50
+ OpenAPI tags, MCP tool grouping, and CMS form discovery continue to bucket each action under its source feature. Only the *runtime routes file* moves to the synthetic location — the feed-moments action is still tagged "feeds" in OpenAPI, the response shape doesn't change, and your generated SDK reads identically. The URL conveys the namespace membership without forcing every layer of the compiler to re-anchor the action.
51
+
52
+ #### Worker-root mount order
53
+
54
+ Synthetic namespace routes files register at priority `20` — ahead of per-feature mounts (priority `0`/`10`). `sortRoutesBySpecificity` keeps the order stable, and the namespace prefix's path parameter makes it sort more specific than `/api/v1/<feature>` anyway, so the middleware fires first for every request under its prefix.
55
+
56
+ #### Compile-time guardrails
57
+
58
+ The same v0.23 invariants apply at the project level, with two additions:
59
+
60
+ - **`via:` must point at a declared `authz.relationships[*]` entry**, and that relationship must declare `loads + exposeAs` — without `loads` there's nothing for the middleware to hydrate, and a namespace that only gates without hydrating is indistinguishable from a per-action access rule.
61
+ - **`prefix:` must contain at least one `:param` segment** — middleware runs before input parsing, so the relationship key comes from `c.req.param()`.
62
+ - **Same-name conflict** between `defineTable({ namespace })` and `authz.namespaces.<sameName>` is rejected. Pick one declaration site.
63
+ - **Ambiguous prefixes** like `/a/:x` and `/a/:y` (same shape, different `:param` names) error at compile time. Strict super/sub-set relationships (e.g. `/event/:e` and `/event/:e/admin`) are fine — the harvester routes each action to the longest matching prefix.
64
+ - **Unused namespace warning** emits `[quickback:authz]` when no standalone action's path matches a declared prefix. Not a hard error — the namespace may be staged ahead of the actions.
65
+
66
+ #### Picking the right declaration site
8
67
 
9
- ### Cloudflare D1 now gets a compiler-native Drizzle safety layer
68
+ The table-level v0.23 form is now the **single-feature shorthand**. The project-level v0.24 form is **canonical for cross-feature**.
10
69
 
11
- Quickback's `cloudflare-d1` provider no longer treats `drizzle-kit generate` output as deploy-ready SQL by default.
70
+ - **Use `defineTable({ namespace })`** when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it; nothing to add to `quickback.config.ts`.
71
+ - **Use `authz.namespaces`** when the namespace spans features. The declaration sits next to your `authz.relationships` and `authz.roles` — the canonical home for cross-cutting authz config.
12
72
 
13
- **A D1-specific post-generation pass now runs inside the compiler.** After Drizzle emits auth, features, webhooks, or audit migrations, the D1 provider inspects the generated SQL before the compile finishes:
73
+ The two forms can't coexist for the same namespace name. If a v0.23 table-level namespace is starting to attract cross-feature actions, lift it to `authz.namespaces` — same shape, just at the project level, and the matching paths in other features will join automatically.
14
74
 
15
- - **Better Auth cleanup for retired managed tables** is stripped instead of being shipped as raw `DROP TABLE` statements.
16
- - **Drop-only cleanup migrations** are reordered child-first when foreign-key dependencies require it.
17
- - **Every generated D1 migration directory** is replayed against SQLite during compile, so a D1-breaking migration fails before `wrangler d1 migrations apply`.
75
+ #### Migration
18
76
 
19
- This closes the class of failures where a compile succeeded but the later deploy exploded inside Cloudflare D1 because SQLite foreign-key enforcement rejected Drizzle's destructive cleanup ordering.
77
+ Zero breaking changes. Nothing in v0.23 needs to change for v0.24 to land. The new field is opt-in; existing projects pick it up the moment they declare an `authz.namespaces` entry.
20
78
 
21
- Pinned by `d1-drizzle-helper.test.ts` plus the existing compile-runner and migration-order regressions.
79
+ The harvester runs after Zod schema validation but before route generation, so unused or misconfigured namespaces surface immediately as errors or warnings rather than as silently-broken routes.
22
80
 
23
81
  ---
24
82
 
25
- ## v0.16.9 — May 13, 2026
83
+ ## v0.23.0 — May 19, 2026
26
84
 
27
- ### Resource-scoped realtime tickets and a shared broadcast targeting model
85
+ ### Authz relationships: compile-time guarantees, less boilerplate, hoisted middleware
28
86
 
29
- Quickback's realtime layer no longer assumes every WebSocket subscriber is an org member.
87
+ This release closes the gap between what `authz.relationships` *promised* in v0.19 and what it actually enforced. Every documented invariant is now a real compile-time check; every per-action ergonomic friction has a fix. Net effect: relationship-based authorization feels native — declare the relationship once, use the role anywhere, the compiler does the wiring.
30
88
 
31
- **`providers.database.config.realtime` can now be object-shaped.** `realtime: true` still enables the historical org-scoped broadcaster, but projects can now opt into a declarative ws-ticket policy:
89
+ #### Compile-time guarantees (the authz `firewall` parity)
32
90
 
33
- ```ts
34
- providers: {
35
- database: defineDatabase("cloudflare-d1", {
36
- realtime: {
37
- wsTicket: {
38
- role: "attendee",
39
- requestField: "eventId",
40
- scopeTable: "events",
41
- },
42
- },
43
- }),
44
- }
45
- ```
91
+ The org/owner/team firewall has always been compile-time-checked: a routed resource without a scope fails the compile, full stop. As of this release, `authz.relationships` carries the same guarantees:
92
+
93
+ - **Bad `via:` names fail at parse time.** A typo in a firewall predicate (`firewall: [{ field: 'eventId', via: 'guestOff' }]`) used to surface deep inside the firewall generator after most validation had passed. It's now caught alongside the `authz.roles` `via:` validation, same layer, same error format.
94
+ - **Relationship-from tables can't opt out.** The doc at `define/types/authz.ts:73-74` always said a relationship `from:` table with `firewall: { exception: true }` "refuses to compile" — that's now enforced. Without this check, every `via:` subquery that pivots through an exception-marked table loses tenant isolation and can return rows from other tenants.
95
+ - **`allowResourceMigration` is now mandatory** when the relationship's `resource.column` is on a writable update endpoint. A guest doing `PATCH /messages/:id { eventId: <other-event-id> }` to migrate a row out of their access scope used to slip past the runtime — it now fails compile with a three-option remediation (set the flag, mark the column immutable, or drop it from the guards.updatable allowlist).
96
+ - **`via: string[]` in firewall predicates.** "Member of attendees OR speakers" no longer requires inventing a composite role just to use it once in a firewall — `firewall: [{ field: 'eventId', via: ['attendeeOf', 'speakerOf'] }]` lowers to an OR-combined subquery.
97
+
98
+ #### Less boilerplate: auto-derivation + realtime resolver
99
+
100
+ - **`resource.column` auto-derives from FKs.** Omit it and the compiler scans the relationship's `from:` table for foreign-key columns, drops the `subject.column`, and picks the remaining FK. One match → auto; zero or many → error with the candidate list. Pattern mirrors the existing firewall auto-detection.
101
+ - **`realtime.requiredRoles` accepts authz roles.** Previously a relationship-role in `realtime.requiredRoles` fell through with a misleading "unknown role" error. The compiler now flattens declared authz roles into their composing Better Auth roles before the realtime ticket-handshake sees them. Relationship-only roles (no static BA fallback) emit a `[quickback:authz]` warning and fail-close at handshake — the row-stream firewall continues to enforce the relationship dimension on the data side.
102
+
103
+ #### Record-based actions can finally use relationship-roles
104
+
105
+ The v0.19 fail-closed hardening had an unintended side effect: a record-based action with `access: { roles: ['attendee'] }` (where `attendee` was a relationship-role) 403'd every caller, including the legitimate ones. The runtime helper couldn't evaluate `relationship:` arms, so it fail-closed correctly — but the inline match expression that *would* evaluate the relationship was never wired up for record-based actions.
106
+
107
+ This release routes record-based actions with relationship arms through the same inline access generator the resource CRUD path already uses. `roles: ['attendee']` on `/applications/:id/recap` now actually checks whether the caller is an attendee, with the loaded record in scope. Non-relationship access trees keep the runtime path unchanged.
46
108
 
47
- That lets the generated `/broadcast/v1/ws-ticket` route authenticate the caller with Better Auth, evaluate a declared authz relationship role like `attendee` against the request body, and mint a short-lived Quickback websocket ticket for the resolved resource scope. `scopeTable` is the parent resource that defines the broadcast channel; the relationship/junction table remains the proof of access.
109
+ #### Typed `ctx.<exposeAs>` in action handlers
48
110
 
49
- **Realtime and broadcast now share one targeting model.** The generated helper and Broadcaster both route by `scopeKey || organizationId || userId`. Historical string targets still mean "organizationId shorthand", so existing code like `realtime.insert("claims", record, ctx.activeOrgId!)` keeps working. New explicit targets can scope a broadcast to a resource or a single user:
111
+ When a relationship declares `loads: 'events', exposeAs: 'event'`, the runtime hydrates `ctx.event` with the loaded row — but the static type was always `any`, so handlers had to write `const event = ctx.event as typeof events.$inferSelect`. As of this release, when an action's access references **exactly one** relationship with `loads + exposeAs`, the compiler emits the cast for you at the execute() call site. Handlers read `ctx.event` with the right shape; no per-handler boilerplate.
112
+
113
+ Multi-arm OR actions (referencing two relationships with hydration) keep the `any` shape — we can't statically know which arm matched.
114
+
115
+ #### New: `defineNamespace` — one mount, one resolver, many actions
116
+
117
+ The marquee Wave 3 change. Today's pattern for "five standalone actions under `/event/:eventId/*` all gated by `attendeeOf`" requires writing the same inline relationship resolver in each action — and pays the resolver cost (one subquery, one row-load) on every request, multiplied by N actions. The new `namespace` field on `defineTable` hoists the resolver into a single Hono middleware mount:
50
118
 
51
119
  ```ts
52
- await realtime.broadcast("event-page-updated", payload, {
53
- scopeKey: "events:evt_123",
120
+ // features/events/events.ts
121
+ export default defineTable(events, {
122
+ firewall: [...],
123
+ crud: { ... },
124
+ namespace: {
125
+ prefix: '/event/:eventId', // absolute URL path the mount covers
126
+ via: 'attendeeOf', // relationship gate
127
+ },
54
128
  });
55
129
 
56
- await realtime.broadcast("dm", payload, {
57
- userId: recipientId,
130
+ // features/events/actions/post-announcement.ts
131
+ export default defineAction({
132
+ path: '/event/:eventId/announcements',
133
+ method: 'POST',
134
+ // No relationship-gate boilerplate. ctx.event is typed
135
+ // `typeof events.$inferSelect` inside execute().
58
136
  });
59
137
  ```
60
138
 
61
- **WebSocket tickets are still Quickback-minted, not Better Auth tokens.** The front door remains your normal Better Auth cookie/bearer/JWT auth. After authorization succeeds, Quickback signs its own 60-second ws ticket and the Broadcaster verifies that ticket at upgrade time. Inline and separate broadcast-worker modes now both reuse `BETTER_AUTH_SECRET` for ticket signing so there is no extra secret to configure during beta.
139
+ The compiler:
140
+ 1. Emits one `app.use('/:eventId/*', async (c, next) => { /* relationship resolver */; await next(); })` at the head of the feature's standalone-routes file (path-prefix stripping handles the feature mount).
141
+ 2. Skips the inline relationship resolver in every per-action handler under the prefix — the middleware already ran it.
142
+ 3. Hydrates `ctx.event` once per request and threads the typed cast into every namespace action's execute() call.
143
+
144
+ **Validation guardrails:**
145
+ - `namespace.via` must point at a declared `authz.relationships[*]` entry.
146
+ - The referenced relationship must declare `loads + exposeAs` — without `loads` there's nothing for the middleware to hydrate, and the namespace gate would be indistinguishable from a per-action access rule.
147
+ - `namespace.prefix` must contain at least one `:param` segment — the middleware reads the relationship key from `c.req.param()`, not from request body (body parsing hasn't run at middleware time).
148
+
149
+ **Scope (v1):**
150
+ - Namespace lives within a single feature's Hono `app`; cross-feature shared namespaces are deferred to v2.
151
+ - One namespace per `defineTable` declaration; multiple namespaces in a feature mount as siblings.
152
+ - For namespace actions whose access references additional relationships beyond the namespace's via, the inline resolver still fires for those — namespace handles only its own.
153
+
154
+ #### Migration
62
155
 
63
- Pinned by `realtime-ws-ticket-scope.test.ts`, plus the existing realtime routing and relationship-access regression suites.
156
+ Nothing in v0.20 → v0.23 breaks existing code that compiles cleanly. The new errors fire only against patterns that were already latent bugs:
157
+
158
+ - A `via:` typo that previously surfaced as a deep codegen error now surfaces at parse time, same message.
159
+ - A `firewall: { exception: true }` on a relationship-from table now errors; this configuration was always documented as unsupported.
160
+ - A relationship's `resource.column` writable on the resource's UPDATE endpoint now errors unless `allowResourceMigration: true` is set; previously this was a runtime escape hatch.
161
+ - Record-based actions with `roles: ['<relationship-role>']` previously 403'd every caller; they now work as the v0.19 docs originally promised.
162
+
163
+ #### Why this matters
164
+
165
+ Authz relationships are how Quickback expresses "the caller is allowed to touch this resource because of a row in *that* table" — guest-of-event, member-of-organization, scorer-of-interview. Until now, the feature worked but had sharp edges: typos surfaced late, the documented exception-not-allowed constraint wasn't enforced, and the namespace pattern (which most apps with nested resources end up wanting) required repeating the same gate in every action. This release brings authz to parity with the org/owner/team firewall: declare it once, the compiler enforces it everywhere, the runtime emits exactly one query per request.
64
166
 
65
167
  ---
66
168
 
67
- ## v0.16.8 — May 13, 2026
169
+ ## v0.22.0 — May 19, 2026
170
+
171
+ ### Quickback Stack is Cloudflare-only: one runtime, two databases, one auth provider
172
+
173
+ We've focused the platform on the stack we actually believe in: **Cloudflare Workers + Hono + Better Auth**, with **Cloudflare D1** or **Neon** as the database. Providers and modes that targeted non-Cloudflare backends are gone. The result is a smaller concept set, fewer footguns, and clearer docs.
174
+
175
+ #### What's been removed
68
176
 
69
- ### Auth transport separation, cookie-backed CSRF middleware, and first-class Wrangler observability
177
+ - **Runtimes**: `bun` and `supabase-edge` are no longer supported. The only runtime is `cloudflare`. Local development for compiled projects has always used `wrangler dev` — that's unchanged.
178
+ - **Databases**: `supabase`, `libsql`, `better-sqlite3`, `bun-sqlite` are removed. Use `cloudflare-d1` for SQLite at the edge or `neon` for PostgreSQL via Hyperdrive.
179
+ - **Auth providers**: `supabase-auth` is removed. `better-auth` is the default; `external` (Cloudflare service binding) remains for advanced setups.
180
+ - **Template**: `template: 'nextjs'` is removed from the public config type. It was never fully implemented. The only template is `'hono'`. If you need a Next.js frontend, bring it as a separate deploy and call the Quickback API, or drop a static export into the `apps:` mount.
181
+ - **Quickback for Supabase RLS** product line is retired. The compiler no longer emits Supabase Row Level Security policies. The `/products/quickback-supabase-rls/` and `/for/supabase-users/` pages have been removed from the marketing site, and the `compiler/targets/supabase-rls/` docs section has been deleted.
70
182
 
71
- Three security/runtime hardenings landed together.
183
+ #### Account UI: one delivery mode
72
184
 
73
- **Exactly one auth transport per request.** Generated auth middleware now treats `Cookie`, `Authorization: Bearer`, and `x-api-key` as separate auth methods and rejects any mixed request with `400 AUTH_METHOD_CONFLICT`. Query-string API keys (`?api_key=` / `?key=`) are no longer accepted, which removes ambiguous precedence rules from the hot path and keeps machine-to-machine auth explicit.
185
+ The standalone `quickback-better-auth-account-ui` npm package has been **deprecated** and the upstream GitHub repo (`Kardoe-com/quickback-better-auth-account-ui`) has been **archived**. Account UI is now exclusively delivered the way 99% of projects already use it: the compiler builds it from source and bundles it into your Worker.
74
186
 
75
- **Cookie-backed mutating requests now get a CSRF gate.** Generated apps now block cross-site `POST` / `PUT` / `PATCH` / `DELETE` requests when the caller is relying on cookies. The middleware skips explicit `Authorization` clients, requires a trusted `Origin` or `Referer`, and blocks `Sec-Fetch-Site: cross-site`. This matters most for cross-subdomain session setups where `SameSite=None` is intentional and origin validation has to carry the load.
187
+ - `account: { domain: 'auth.example.com', ... }` in `quickback.config.ts` — that's the entire integration story.
188
+ - The compiler builds the SPA inside Docker with your branding and feature flags baked in, emits hostname-based routing, and wires cross-subdomain cookies automatically.
189
+ - The three standalone delivery-mode docs (`stack/account-ui/standalone`, `library-usage`, `worker`) are removed; the remaining pages explain the compiler-bundled flow.
76
190
 
77
- **Wrangler observability is now a first-class compiler surface.** `providers.runtime.config.observability` no longer stops at `enabled: true`. The compiler now understands top-level Workers Logs sampling plus nested `logs` / `traces` blocks for `headSamplingRate`, `destinations`, `persist`, and `logs.invocationLogs`, and emits the matching `[observability]`, `[observability.logs]`, and `[observability.traces]` TOML. The config validator also rejects ambiguous double-mapping of Workers Logs sampling (`observability.headSamplingRate` plus `observability.logs.headSamplingRate`) and requires explicit per-signal `enabled` flags when trace/log export settings are present.
191
+ If you previously deployed the standalone Account UI Worker against a Quickback backend, switch to `account: { domain }` in the config — same end result, one less deploy.
78
192
 
79
- Pinned by `config-wiring.test.ts`, `csrf-middleware.test.ts`, `cookie-security.test.ts`, `auth-api-key-query-param.test.ts`, and the deployed negative-auth regression checks.
193
+ #### `VITE_AUTH_ROUTE` hardcoded to Quickback
194
+
195
+ The `VITE_AUTH_ROUTE` env var (which used to switch between `quickback` and `better-auth` routing dialects) is gone. The auth-client always uses Quickback's namespaced routes (`/auth/v1`, `/api/v1`, `/storage/v1`). Generic Better Auth backends are no longer a supported target. Removing the var also closes a known footgun where setting the wrong value silently 404'd every auth call.
196
+
197
+ #### New: every config option is now discoverable
198
+
199
+ When you bootstrap a project, the kitchen-sink marker block in `quickback.config.ts` lists every option Quickback supports — with descriptions and sensible defaults — commented out for you to copy above the marker as needed. Three top-level options were missing from this discovery surface and are now included:
200
+
201
+ - **`apps`** — mount your own prebuilt SPA on its own hostname (`apps: { www: { domain: 'www.example.com', aliasDomains: ['example.com'] } }`). Drop the build at `quickback/apps/<name>/` and the compiler serves it from your Worker alongside the API. Reserved names: `cms`, `account`, `public`.
202
+ - **`security`** — HTTP security headers (CSP, COOP, COEP, HSTS, Referrer-Policy, Permissions-Policy, X-Frame-Options). Set `security: false` to suppress everything; defaults are sensible for the embedded SPAs.
203
+ - **`authz`** — relationship-based authorization roles. Declare joins between the caller and a resource column, then bind role names to those joins for use in `access: { roles: [...] }`.
204
+
205
+ #### Migration
206
+
207
+ Projects that compile cleanly against v0.21 and use any of these providers will hit a clear error at compile time:
208
+
209
+ ```
210
+ Unknown database provider: "supabase". Available: cloudflare-d1, neon
211
+ ```
212
+
213
+ To migrate:
214
+
215
+ 1. **From Supabase**: switch `providers.database` to `cloudflare-d1` or `neon`, and `providers.auth` to `better-auth`. Your `defineTable()` definitions transfer as-is; the security DSL (firewall, access, guards, masking) compiles to Better Auth + Drizzle queries instead of RLS policies.
216
+ 2. **From Bun runtime / `bun-sqlite`**: switch `providers.runtime` to `cloudflare` and `providers.database` to `cloudflare-d1`. Local dev becomes `wrangler dev`.
217
+ 3. **From libsql / Turso**: switch to `cloudflare-d1` or `neon`. Both run natively from Cloudflare Workers via the right binding.
218
+ 4. **From `template: 'nextjs'`**: deploy Next.js separately and call the Quickback API, or drop a static export into `apps:`.
219
+
220
+ #### Why this matters
221
+
222
+ The Quickback Stack is the Supabase alternative for Cloudflare. Every Quickback project ships a Hono API, an Account SPA, a CMS SPA, optional realtime/storage/queues — all built from one config and bundled into one Worker. Keeping that promise focused is more valuable than supporting deployment targets that don't share the runtime.
80
223
 
81
224
  ---
82
225
 
83
- ## v0.16.7 — May 12, 2026
226
+ ## v0.21.0 — May 19, 2026
227
+
228
+ ### Auto-firewall column swap: `ownerId` is now canonical on feature tables, `userId` warns
84
229
 
85
- ### Bearer wins over cookie, and bearer plugin defaults to `requireSignature: true`
230
+ The compiler's default auto-firewall column for feature tables flips from `userId` to `ownerId`. This closes a long-standing footgun where a `userId` column meaning "a user this row references" (a member, a contact, an invitee) got silently clobbered with `ctx.userId` on insert, because the wrapper matched purely on column name across every table in the project.
86
231
 
87
- Two hardenings to the auth middleware closing a mixed-credential ambiguity and a session-token replay path.
232
+ **What changed in the compiler**
88
233
 
89
- **Bearer-vs-cookie precedence.** A request that carries both an `Authorization` header and a session `Cookie` now resolves entirely from the bearer — the cookie is dropped before `getSession()` runs. Previously the api-key and JWT fast-paths already short-circuited above cookie resolution, but session-token bearers fell through to Better Auth's `getSession()` where cookie auth resolved first and the bearer was silently ignored. That meant a request with `Cookie: alice` + `Authorization: Bearer bob-session-token` would resolve as alice, silently dropping bob's explicit credential. The inconsistency between bearer flavors (api-key/JWT bearer-wins, session-bearer cookie-wins) was the bug; making bearer win universally aligns with Better Auth's own framing of the plugin as "intended only for APIs that don't support cookies, or require Bearer tokens for authentication." Cookie remains the resolution path when no `Authorization` header is present, so browser SPA flows are unchanged.
234
+ - `BETTER_AUTH_DEFAULTS.owner.column`: `'userId'` → `'ownerId'`. Schemas with an `ownerId` column auto-resolve to `firewall: [{ field: 'ownerId', equals: 'ctx.userId' }]` and have `ownerId` auto-stamped on insert.
235
+ - The generated `OWNER_SCOPE_RULES` in `src/lib/scoped-db.ts` is seeded with `ownerId` instead of `userId`. Schemas that don't explicitly name `userId` in a `firewall:` block no longer trigger the global `userId`-stamping rule — the most common collision goes away without renames.
236
+ - A new compile-time warning fires when a feature table carries both an auto-resolved isolation column AND a `userId` column. The warning recommends renaming the column to `linkedUserId` (or similar) if it's informational, or declaring `firewall: [{ field: 'userId', equals: 'ctx.userId' }]` if it really is the access boundary on that table.
237
+ - The targeted compile-time error for "the only candidate column is `userId`" now points users at `ownerId` and the explicit-firewall escape hatch. The previous error wording (which assumed `ownerId` was business-logic) is removed.
90
238
 
91
- **`requireSignature: true` on the bearer plugin.** Better Auth's `bearer` plugin defaults `requireSignature` to `false`, which means the session token emitted in the CORS-exposed `set-auth-token` response header is a literal session secret — anyone who sees it in a proxy access log, a browser dev-tools panel, or a misrouted `Referer` can replay it. Quickback now emits `bearer({ requireSignature: true })` so Better Auth signs the token server-side with `BETTER_AUTH_SECRET` and rejects unsigned bearers on verify. JWT bearers and agent-auth bearers are independently signed and unaffected. Projects that genuinely need unsigned bearers can override by passing `bearer: { requireSignature: false }` in `providers.auth.config.plugins` — user-supplied options merge on top of the secure default.
239
+ **What stayed the same**
92
240
 
93
- See [Authentication Security → Bearer Tokens and Cookie Precedence](/stack/auth/security#bearer-tokens-and-cookie-precedence) for the full threat model and the four credential flavors Quickback supports.
241
+ - Better Auth's own internal tables (`session`, `account`, `member`, `passkey`, `subscriptions`) still use `userId` by convention. They aren't feature tables and don't pass through the auto-firewall.
242
+ - Explicit `firewall: [{ field: 'userId', equals: 'ctx.userId' }]` declarations continue to work and are still recognized as the "owner" pattern in the generated comment header.
243
+ - The `USER` pseudo-role validator behaviour is unchanged; only the error-message wording flips to lead with `ownerId` and list `userId` as the explicit fallback.
244
+ - Audit-wrapper (`createdBy` / `modifiedBy`) behavior is untouched.
94
245
 
95
- Pinned by `agent-auth.test.ts` (asserts the `bearer({ requireSignature: true })` emission shape).
246
+ **Migration**
247
+
248
+ Projects that auto-firewalled on a `userId` column will see a hard error on next compile telling them which table is affected, with two suggested fixes:
249
+
250
+ 1. **Recommended**: rename the column to `ownerId` in the schema. Cleanest semantics — readers immediately understand the column is access-control.
251
+ 2. **Explicit firewall**: keep the `userId` column and add `firewall: [{ field: 'userId', equals: 'ctx.userId' }]` to the resource. The auto-stamping and auto-scoping still happen; you've just opted in by name.
252
+
253
+ Projects that have a `userId` column meaning "a user this row references" no longer need the `linkedUserId` rename workaround — auto-stamping won't touch the column unless you name it in a firewall block. The new warning makes this audit-discoverable.
254
+
255
+ **Caveat (deferred)**: explicit `firewall: { owner: { column: 'X' } }` declarations still populate the project-global `OWNER_SCOPE_RULES` list, so a hand-named owner column on one resource will still match by name on every other table that happens to have a column called `X`. A future release will make scope-rule resolution per-table rather than project-global. The warning text calls this out so callers know what to expect.
96
256
 
97
257
  ---
98
258
 
99
- ## v0.16.5 — May 12, 2026
259
+ ## v0.20.0 — May 19, 2026
100
260
 
101
- ### Flat write DSL is now the preferred authored shape, with compatibility aliases preserved
261
+ ### CMS + Account SPAs: shadcn base-ui migration, central Tailwind config
102
262
 
103
- Quickback's resource DSL had drifted into an awkward split: reads already lived under `read`, while writes still sat under a nested `crud` block that no longer represented the full CRUD surface. That shape was technically supported, but it was teaching the wrong mental model.
263
+ Both first-party SPAs are now on the shadcn **base-ui** variants (`@base-ui/react`) instead of the Radix-based primitives, applied via shadcn preset **`bdvxIkMq`** (style `base-mira`, `baseColor: zinc`, `iconLibrary: remixicon`, Inter Variable font). The migration also collapses the previously duplicated per-SPA theme + `components.json` into a single source at `packages/ui/`.
104
264
 
105
- The preferred authored surface is now flat at the table level:
265
+ #### Single source of truth in `packages/ui/`
106
266
 
107
- ```ts
108
- defineTable(customers, {
109
- read: { ... },
110
- create: { access: { roles: ["admin"] } },
111
- update: { access: { roles: ["admin"] } },
112
- delete: { access: { roles: ["admin"] }, mode: "soft" },
113
- upsert: { access: { roles: ["admin"] } },
114
- guards: { ... },
115
- });
116
- ```
267
+ Both SPAs were independently declaring the same `@theme` / `:root` / `.dark` token blocks in their own `app.css`, and each had its own `components.json` pointing at non-existent local component directories. That's gone:
117
268
 
118
- `crud` and top-level `put` still compile in v0.16.5 as deprecated compatibility aliases. The compiler now normalizes the flat shape into the existing internal write surface, rejects mixed usage on the same resource, and warns when legacy aliases are used. Generated outputs that expose authored table policy — including `schema-registry.json` — now emit flat `create` / `update` / `delete` / `upsert` aliases alongside the legacy normalized `crud` block so older consumers keep working during the transition.
269
+ - `packages/ui/styles/theme.css` — the only place tokens live. Includes the base-mira palette, sidebar + chart tokens, and the Inter font import.
270
+ - `packages/ui/components.json` — the only shadcn config in the repo. Future `pnpm dlx shadcn@latest add <name>` runs from `packages/ui/`.
271
+ - `packages/cms/app/app.css` and `packages/account/app/app.css` reduce to two imports plus SPA-specific layers (CMS keeps its AG Grid + richtext-display overrides). `packages/{cms,account}/components.json` deleted.
119
272
 
120
- ### CMS standalone actions now have an explicit placement model for multi-table features
273
+ #### Components, icons, deps
121
274
 
122
- Standalone actions were unambiguous for single-table features and for clearly table-scoped paths, but multi-table feature-root actions had no clean place to live in the CMS metadata contract. The API knew what the action was; the CMS had to guess where to render it.
275
+ - All 22 shadcn primitives regenerated against `@base-ui/react` (`@radix-ui/*` removed everywhere). `Drawer` stays on `vaul` — base-ui has no Drawer primitive.
276
+ - Icons migrated from `lucide-react` to `@remixicon/react` line variants across ~100 source files (`Plus → RiAddLine`, `ChevronDown → RiArrowDownSLine`, `X → RiCloseLine`, etc.). `lucide-react` removed from all `package.json` + `deps-spa-*` files.
277
+ - `pnpm.overrides` pin `@types/react ^19.2.0` workspace-wide to resolve the duplicate-React-types conflict introduced by `@base-ui/react`'s bundled type peer.
278
+ - Per-SPA deps and the Docker build mirrors (`apps/compiler/deps-spa-{cms,account}-package.json`) both gain `@base-ui/react`, `@remixicon/react`, `@fontsource-variable/inter`, and bump `shadcn` to `^4.7.0`.
123
279
 
124
- The contract is now explicit:
280
+ #### Backwards-compat `asChild` shim
125
281
 
126
- - `cms.placement: "feature"` shows the standalone action in the table toolbar for every table in the feature
127
- - `cms.placement: "tables"` with `cms.tables` shows it only on specific tables
128
- - `cms.hidden: true` keeps it API-only
282
+ Base-ui replaces Radix's `asChild` boolean with a `render={<X />}` prop. To avoid rewriting ~44 caller sites, the shadcn-generated wrappers for `Button`, `DropdownMenuTrigger`, `DropdownMenuItem`, and `PopoverTrigger` carry an `asChild?: boolean` prop that delegates to base-ui's `render` API when set:
129
283
 
130
- The compiler now emits feature-root standalone actions under a new `featureActions` bucket in `schema-registry.json` instead of duplicating them across every table entry. The CMS merges those `featureActions` into table toolbars according to placement, while record action bars remain table-scoped by default. Ambiguous multi-table feature-root standalone actions without placement now compile with a warning instead of silently landing in the wrong UI surface.
284
+ ```tsx
285
+ // Caller code keeps working as-is:
286
+ <Button asChild>
287
+ <Link to="/foo">Click</Link>
288
+ </Button>
289
+ ```
131
290
 
132
- ### `openapi.types` can now keep colocated SPA clients in sync from a single compile
291
+ `ResponsiveModal` survived the migration unchanged — it composes the higher-level Dialog + Drawer wrappers (preserved public API), not the underlying primitives.
133
292
 
134
- `quickback compile` already emitted `openapi.json` and a generated `api-types.gen.ts`, but projects with a colocated SPA often kept a second copy under something like `apps/web/src/lib/api-types.gen.ts`. That second file drifted unless a separate `codegen:api` step was run after every compile.
293
+ #### Caller-side API changes worth noting
135
294
 
136
- `openapi.types` now accepts a string array as well as `true`, `false`, or a single custom path. One compile can write the same generated types file to multiple locations, for example:
295
+ Base-ui ships some real behavioural changes the Radix variants didn't:
137
296
 
138
- ```ts
139
- openapi: {
140
- types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'],
141
- }
297
+ - `<Select onValueChange>` now receives `(value: string | null, eventDetails) => void` (was `(value: string) => void`). Existing `Dispatch<SetStateAction<string>>` setters reject `null` — wrap callbacks defensively: `onValueChange={(v) => v != null && setX(v)}`.
298
+ - `<DropdownMenuContent forceMount>` removed (base-ui has no `forceMount`). Use base-ui's `keepMounted` on the Popup/Positioner if you need to preserve unmounted state.
299
+ - Component sub-names shifted (`Dialog.Content` → `Dialog.Popup`, `Dialog.Overlay` → `Dialog.Backdrop`). Data attributes are now `data-open` / `data-closed` (no more `data-state="open"`).
300
+
301
+ #### Adding a new primitive after this release
302
+
303
+ ```bash
304
+ cd packages/ui
305
+ pnpm dlx shadcn@latest add <component> --overwrite --yes
306
+ # Sweep generated `@/` imports to relative paths — the SPAs' vite-tsconfig-paths
307
+ # plugin doesn't see packages/ui's @/* mapping at bundle time:
308
+ sed -i.bak \
309
+ -e 's|"@/lib/utils"|"../lib/utils"|g' \
310
+ -e 's|"@/components/|"./|g' \
311
+ -e 's|"@/hooks/|"../hooks/|g' \
312
+ components/<component>.tsx && rm components/<component>.tsx.bak
142
313
  ```
143
314
 
144
- This keeps the API root artifact and any colocated SPA copy aligned without a second codegen command. The bundled Quickback CMS and Account SPAs do not use `api-types.gen.ts` themselves — CMS is schema-registry driven, and Account uses Better Auth plus hand-written fetch helpers — so this option is aimed at user-authored client apps that live beside the compiled API.
315
+ If the new primitive pulls in fresh deps, mirror them into `apps/compiler/deps-spa-{cms,account}-package.json` per the SPA build pipeline or Docker SPA builds will fail.
145
316
 
146
- ### Generated route files and `schema-registry.json` are now emitted in a stable order
317
+ ---
147
318
 
148
- Back-to-back `quickback compile` runs could previously regenerate functionally identical route files or `schema-registry.json` with different ordering. The API behavior did not change, but the diff noise was real.
319
+ ## v0.18.1 — May 18, 2026
149
320
 
150
- The compiler now normalizes discovery order before it builds action bundles, route files, and the schema registry. Identical logical input produces stable emitted artifacts, which means fewer no-op diffs after a recompile and cleaner review when something actually changed.
321
+ ### Account SPA — teams, active-team picker, permission-aware UI
151
322
 
152
- ## v0.16.4 — May 12, 2026
323
+ The Account SPA's organization surface is now feature-parity with Better Auth's `organization` plugin for the basic team workflow, and replaces the long-standing hardcoded `role === 'owner' || 'admin'` checks with `checkRolePermission` so projects that ship custom roles get a UI that respects them.
324
+
325
+ #### Teams (opt-in)
326
+
327
+ When the BA config enables teams — `organization({ teams: { enabled: true } })` — the compiler emits `VITE_ENABLE_ORG_TEAMS=true` and the Account SPA exposes a Teams tab on each organization:
328
+
329
+ - **Teams index** (`/$slug/teams`) — splits into "Your teams" (from `listUserTeams`) and "Other teams" so non-admins land on what's relevant. Create / rename / delete from the list, gated on `team:create` / `team:update` / `team:delete`.
330
+ - **Team detail** (`/$slug/teams/$teamId`) — member roster with add / remove, joining `listTeamMembers` against the org's full member list for display.
331
+ - **Active-team picker** in the org header — calls `setActiveTeam` and exposes the choice via `OrganizationContext.activeTeamId` so downstream routes (and the BA `session.activeTeamId` server-side) stay in sync.
332
+ - **Team-aware invites** — `InviteMemberDialog` shows an optional team picker when teams are on and forwards `teamId` to `inviteMember`, so accepting the invite drops the new member straight into the right team.
153
333
 
154
- ### Compile didn't emit a migration — v0.16.3 corrupted drizzle snapshots, fixed + self-heal
334
+ Teams are loaded once by the `$slug` layout (`listTeams` + `listUserTeams`) and exposed via `OrganizationContext.teams` / `userTeamIds` / `refreshTeams`, so individual team routes don't re-fetch the list.
155
335
 
156
- The v0.16.3 release stamped a `$$__quickback_warning__$$` key onto every drizzle metadata JSON file under `quickback/drizzle/<dialect>/meta/` — both `_journal.json` and each `<n>_snapshot.json`. The original change description noted that drizzle-kit "ignores unknown top-level fields when reading journals/snapshots" — but that's only true for journals. Snapshots are parsed by a strict Zod schema that rejects extras, so on every compile after the upgrade, drizzle-kit logged each `<n>_snapshot.json` as `"data is malformed"`, lost its diff base, and silently emitted no migration on schema changes. Users hand-wrote migrations (e.g. `0033`) to compensate. Reproduced against `examples/recruitment` by adding a column to `candidates` — the recruit tree's 8 snapshots all came back malformed and zero migrations were generated.
336
+ #### Permission-aware UI via `checkRolePermission`
157
337
 
158
- The fix narrows `DRIZZLE_META_JSON_RE` to a journal-only matcher (`DRIZZLE_JOURNAL_JSON_RE`) so the warning is stamped only where it's safe. A new `stripJsonHeader()` helper runs over `existingFiles` when the staging step encounters a `<n>_snapshot.json`, so projects whose tree was already corrupted by v0.16.3 self-heal on the next compile: the bad header is stripped on the way into the staging dir, drizzle-kit's diff resolves correctly, and the emitted snapshot writes back without the offending key. No manual snapshot surgery required after upgrading — the next `quickback compile` quietly cleans up the prior corruption.
338
+ `OrganizationContext.isOwnerOrAdmin` is gone. Routes now read `can(resource, action)` from context, which delegates to `authClient.organization.checkRolePermission` — synchronous, no roundtrip, and aware of any custom roles registered via the BA `ac` option. Multi-role users (BA stores multiple roles comma-separated) are handled by checking each role; the action is allowed if any role grants it.
159
339
 
160
- Pinned by `drizzle-meta-header.test.ts`: journals receive the warning key at position 0; snapshots are byte-identical input/output (no warning key); `stripJsonHeader` strips a present warning, no-ops on absent, and tolerates unparseable / array-shaped JSON.
340
+ Migrated sites:
161
341
 
162
- ### `account.auth.*` now drives the server, not just the UI — closes a signup-disabled bypass
342
+ - `$slug.tsx` tab gates → `can('invitation', 'create')`, `can('organization', 'update')`
343
+ - `members.tsx` action menu → `can('member', 'update' | 'delete')`; the owner-hierarchy guard (non-owners can't touch owner-role members) is preserved as a client-side mirror of BA's server enforcement
344
+ - `invitations.tsx` → `can('invitation', 'create' | 'cancel')` gates the Invite button, resend, and cancel separately
345
+ - `settings.tsx` → `can('organization', 'update')` for the form, `can('organization', 'delete')` for the danger zone (was owner-only)
346
+ - `teams.tsx` / `teams.$teamId.tsx` → `can('team', 'create' | 'update' | 'delete')`
163
347
 
164
- A 2026-05-11 external pentest of a production Loop deployment confirmed that `account.auth.signup: false` only hid the SPA's signup screen while leaving `POST /auth/v1/sign-up/email` wide open. A new account could be created against the server, and because `account.auth.emailVerification: false` was the only emit point (it never set the server's `requireEmailVerification`), the freshly issued session was immediately usable. The same shape applied to `password`, `passkey`, and `emailOTP` — every "friendly" `account.auth.*` flag was a SPA build flag with no server counterpart. The Account UI promised "signup is off"; the server cheerfully accepted the registration.
348
+ Projects on the default three-role hierarchy see no behaviour change; projects that defined `admin`/`member` overrides via BA's access-control API now get a UI that matches what the server will actually authorize.
165
349
 
166
- `apps/compiler/src/providers/auth/providers/better-auth/normalize-from-account.ts` introduces a one-way normalizer that runs in `parseCompilerInput` before any generator reads `providers.auth`. It maps `account.auth.*` into the Better Auth server config — `signup → emailAndPassword.disableSignUp` (inverted), `password → emailAndPassword.enabled`, `emailVerification → emailAndPassword.requireEmailVerification`, `passkey`/`emailOTP` → plugin additions — only when the user hasn't already set the BA field explicitly. Setting both sides incompatibly (e.g. `account.auth.signup: false` AND `emailAndPassword.disableSignUp: false`) throws at compile time with a precise multi-line error rather than picking a silent winner; the silent precedence is what created the bug in the first place.
350
+ #### Editable slug + metadata on organization settings
167
351
 
168
- The Account SPA's `VITE_ENABLE_*` flags are now derived from the same canonicalized BA config via a new `resolveAuthFeatureFlags()` helper in `generators/spa-builder.ts`, so the SPA bundle and the server cannot drift. The helper self-normalizes (idempotent) for direct callers and unit tests. Two new SPA flags ride along: `VITE_ENABLE_API_KEYS` (driven by the `apiKey` plugin) and `VITE_ENABLE_MAGIC_LINK` (driven by the `magicLink` plugin), so the existing api-keys route in `packages/account` can self-gate the same way passkey/emailOTP already do.
352
+ The `$slug/settings.tsx` form now edits two more `organization.update` fields:
169
353
 
170
- **Breaking** for anyone who was implicitly relying on the open signup endpoint: projects that set `account.auth.signup: false` but actually wanted server signup to remain open must now explicitly set `providers.auth.config.emailAndPassword.disableSignUp: false` (and accept the risk). Same migration path for `emailVerification` (now actually enforced server-side when set) and the plugin flags. Loop's existing config requires no change — the next recompile + deploy starts returning `403` on `POST /auth/v1/sign-up/email`, which is exactly what the config has been claiming since the field was added.
354
+ - **URL slug** — full debounced `checkSlug` flow (mirroring the create-org form); on rename, the SPA navigates to `/${newSlug}/settings` and the layout re-fetches with the new slug.
355
+ - **Metadata** — single `Record<string, any> | null` JSON textarea, parsed on submit with inline error messaging. Empty clears the field.
171
356
 
172
- Pinned by `account-auth-normalize.test.ts` (19 unit tests covering the normalizer + flag resolver + contradiction detection on both array- and object-form plugins) and `loop-pentest-regression.test.ts` (compiles a trimmed Loop config and asserts the generated `auth.ts` carries `disableSignUp: true`).
357
+ Slug rename is non-breaking for the SPA itself, but every external link / bookmark that references the old slug becomes a 404 — the form warns about this before saving.
358
+
359
+ #### Auth client wiring
360
+
361
+ When `VITE_ENABLE_ORG_TEAMS=true`, the SPA's `organizationClient(...)` is instantiated with `teams: { enabled: true }` so the team APIs are typed end-to-end. When the flag is off, team methods aren't surfaced — and the Teams tab is hidden — keeping the bundle and UI honest about what the server actually supports.
173
362
 
174
363
  ---
175
364
 
176
- ## v0.16.3 — May 9, 2026
365
+ ## v0.18.0 — May 17, 2026
177
366
 
178
- ### Standalone action mount order — literal paths no longer get swallowed by sibling CRUD `/:id` routes
367
+ ### `config.apps` — mount user-authored SPAs on dedicated hostnames
179
368
 
180
- When a feature exposed both CRUD routes and a standalone action at the same mount prefix, Hono could register the CRUD router first. A literal standalone path like `GET /api/v1/records/today-bundle` would then hit the CRUD router's `GET /:id`, treat `"today-bundle"` as a record id, and fail in the firewall layer as a fake record lookup instead of ever reaching the standalone handler.
369
+ The compiler now generates per-hostname Worker middleware for arbitrary user SPAs alongside the built-in CMS and Account UIs. Previously the only way to host a product app next to a Quickback API was a second Worker; `config.apps` brings the full stack — API, account, and product UI — onto one deployment with same-origin auth.
181
370
 
182
- The compiler now attaches an explicit registration priority to generated route mounts. Feature-level standalone action routers register before sibling CRUD routers when both mount at the exact same prefix, so literal paths win and `/:id` remains the fallback. The regression is pinned in `standalone-route-mount-order.test.ts`, which asserts both emitted routes and the final mount order in `src/index.ts`.
371
+ ```ts
372
+ apps: {
373
+ www: {
374
+ domain: "www.example.com",
375
+ aliasDomains: ["example.com"], // apex serves the same SPA
376
+ },
377
+ }
378
+ ```
379
+
380
+ Each entry binds one or more hostnames to a directory under `src/apps/<name>/` and inherits the Account-domain pass-through behavior — `/api/`, `/auth/`, `/admin/`, `/storage/`, and `/health` route to Hono so the SPA fetches its API without CORS. The compiler:
381
+
382
+ - emits a `custom_domain = true` route in `wrangler.toml` for the primary hostname and every alias
383
+ - adds each hostname to Better Auth's `TRUSTED_ORIGINS` (when `trustedOrigins` is left unset)
384
+ - widens the CSP `connect-src` to cover the SPA-baked origins
385
+ - folds the new hostnames into shared-parent detection for `crossSubDomainCookies`
386
+
387
+ Drop the prebuilt SPA bundle at `quickback/apps/<name>/` — the existing source-apps passthrough copies it byte-for-byte into `src/apps/<name>/`. The compiler doesn't build the SPA; it only emits routing for whatever's already there. The names `cms`, `account`, and `public` are reserved; hostname collisions with `cms.domain` / `account.domain` / `account.adminDomain` or between two `apps[*]` entries fail at compile time.
388
+
389
+ When `cms` and `account` are both configured, the multi-domain catchall now explicitly skips app hostnames — an API miss on an app host returns the standard 404 JSON via `app.notFound` instead of stray-serving a sibling SPA's HTML shell.
183
390
 
184
- This is a routing-correctness fix, not a public API redesign. No user code changes are required, and existing standalone action paths do not need to be renamed. Recompile and shared-prefix standalone routes resolve correctly.
391
+ ### Cross-subdomain cookie inference handles apex aliases
392
+
393
+ The shared-parent detection that drives `advanced.crossSubDomainCookies` previously reduced any hostname by stripping the leftmost label — `'example.com'` collapsed to `'com'`, which broke equality against sibling subdomains. Apex hostnames (exactly two dot-segments) are now treated as already being the parent, so apex aliases (`example.com` listed alongside `www.example.com`) coexist cleanly with `auth.example.com` / `cms.example.com` and the compiler still emits `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`.
185
394
 
186
395
  ---
187
396
 
188
- ## v0.16.1 — May 9, 2026
397
+ ## v0.17.2 — May 15, 2026
189
398
 
190
- ### Cloudflare ASSETS canonicalization — worker SPA emits no longer 307-loop
399
+ ### `customPlugins` escape hatch on `defineAuth("better-auth", …)`
191
400
 
192
- Cloudflare's static-assets binding canonicalizes any request for `/<dir>/index.html` into a 307 redirect to `/<dir>/` (the default `html_handling=auto-trailing-slash`). When a worker subrequest issues `c.env.ASSETS.fetch(new Request(new URL('/<dir>/index.html', …)))`, the binding returns the 307; the worker forwards it; the browser re-requests `/<dir>/`; the same SPA-fallback handler (or hostname middleware) catches the directory request and re-fetches `/<dir>/index.html`. Infinite loop. Caught by AttendVIP writing custom `/admin/` and `/m/` host-routing patches on the deployed worker — the fix in their patches was switching to `/admin/` (trailing slash, no `index.html`), which Cloudflare resolves to the directory's `index.html` content with a 200.
401
+ The Better Auth provider now accepts `customPlugins` alongside the named-plugin registry — a path to ship third-party plugins (`@better-auth-kit/audit`, …), unregistered built-ins, or one-off project-local plugins without forking the compiler.
193
402
 
194
- The compiler had the same bug baked into every emit point. `cloudflare.ts` now fetches `/<dir>/` everywhere it previously asked for `/<dir>/index.html`: CMS hostname middleware, `/cms/*` SPA catchall, apex `/` handler, account/admin hostname middleware, `/account/*` SPA catchall, and the multi-domain catchall. Eight regression tests in `cf-assets-canonicalization-spa-fallback.test.ts` pin every emit so a future copy/paste can't sneak the literal back in.
403
+ Each entry is an explicit import descriptor:
195
404
 
196
- ### `account.customLogin` — drop a project-branded sign-in page in front of the SPA
405
+ ```ts
406
+ auth: defineAuth("better-auth", {
407
+ emailAndPassword: { enabled: true },
408
+ plugins: { passkey: true, organization: true },
409
+ customPlugins: [
410
+ // (1) Project-local plugin file at quickback/plugins/long-session.ts
411
+ { from: "./plugins/long-session", export: "longSessionPlugin" },
412
+ // (2) Third-party npm package
413
+ {
414
+ from: "@better-auth-kit/audit",
415
+ export: "auditPlugin",
416
+ args: { events: ["sign-in"] },
417
+ dependencies: { "@better-auth-kit/audit": "^1.0.0" },
418
+ },
419
+ ],
420
+ }),
421
+ ```
197
422
 
198
- A new `account: { customLogin: true }` flag emits an explicit `app.get('/account/login', …)` route that serves a project-supplied static page instead of letting the bundled Account SPA's client router handle the path. Drop the page at `quickback/public/account/login/index.html` (a *directory*, not a bare `login.html` — see the canonicalization note above) and the existing `quickback/public/` passthrough copies it into the asset binding. The route is registered before the `/account/*` SPA catch-all so the static handler wins; everything else under `/account/...` (profile, organizations, devices, …) keeps going through the React SPA. Same surface AttendVIP was hand-patching post-compile — promoting the flag means the next compile no longer wipes their override. Default `false`.
423
+ `from` is either a relative path under `./plugins/` (the CLI auto-uploads matching files from `quickback/plugins/`; the compiler copies them into `src/plugins/<name>.ts` and rewrites the emitted import) or a bare npm specifier (emitted verbatim; declare `dependencies` so the package lands in the generated `package.json`). Omit `args` to emit the symbol uncalled (plugin instance); provide `args` to emit a JSON-serialized factory call.
199
424
 
200
- ### Project-level realtime auto-broadcasts every resource by default
425
+ The descriptor is validated with Zod — typos in `from`/`export`, paths that escape `./plugins/`, and references to files the CLI didn't ship all fail at compile time with a targeted message.
201
426
 
202
- `dbConfig.realtime: true` now treats every resource as realtime-enabled unless its `realtime` block explicitly opts out. The previous behavior set `effectiveResourceRealtime` to `undefined` when a resource didn't declare its own block — so a project that flipped the project-level flag still had to add per-table `realtime: { enabled: true }` everywhere to actually get auto-broadcasts. Caught against AttendVIP after the v0.15.x auto-broadcast wiring landed but didn't fire. New default: project-level on with no per-resource override = `{ enabled: true }`. Per-resource `realtime: { enabled: false }` still wins.
427
+ ---
428
+
429
+ ## v0.17.1 — May 14, 2026
203
430
 
204
- ### Drizzle metadata gets a DO NOT EDIT header + journal drift warning
431
+ ### `quickback start` — interactive onboarding
205
432
 
206
- Two changes that protect the drizzle plumbing from quiet corruption.
433
+ ```bash
434
+ mkdir my-app && cd my-app
435
+ npx @quickback-dev/cli start
436
+ ```
207
437
 
208
- `compile-runner.ts:addJsonHeader` now stamps drizzle's generated JSON (`_journal.json`, `<n>_snapshot.json`) with a `$__quickback_warning__$` key explaining the file is regenerated by the compiler and should not be edited by hand. The disclaimer matches the one already on `.ts` outputs — the journal had been the one drizzle file users felt entitled to "tidy up" because nothing in it said otherwise.
438
+ `start` walks new users through template selection, scaffolds the project on disk, and only prompts for an account when it's ready to compile. Cancelling at the login prompt leaves the scaffold intact — sign in and run `quickback compile` whenever you're ready.
209
439
 
210
- A new check in the same module compares the journal entry count against the snapshot file count. drizzle-kit only produces one snapshot per `generate` run, so `journal.entries.length > snapshots + 1` means the journal claims migrations the snapshot side has lost (typical cause: a manual delete of an `<n>_snapshot.json` that left the journal entry behind). The compiler logs a warning and lists the orphan entries. Detected directly out of AttendVIP's `Travel 500` triage — drizzle-kit was diffing against a stale `0002_snapshot.json` and emitting bogus full `CREATE TABLE` migrations for tables that had been added in subsequent (now-orphaned) journal entries.
440
+ The same deferred-auth flow applies to `quickback create`. Scaffolding and (optional) Cloudflare D1 setup run before authentication, so you can preview the project on disk before committing to an account.
211
441
 
212
- ### Two new compile-time validators (LOUD failures over silent traps)
442
+ ### Named views on the free tier
213
443
 
214
- **`AUTHENTICATED` + tenant-scoped firewall now refuses to compile.** `pseudo-role-validator.ts` rejects any access tree that admits `AUTHENTICATED` on a resource whose firewall scopes by `organizationId`. The combination is the silent-empty trap: a sign-in-only caller with no active org passes the role gate, the firewall WHERE clause filters every row out, and the API returns `[]` with a 200. The error message names three valid resolutions — drop the org scope (`firewall: { exception: true }`), tighten the role to `USER` or a role with implied org membership, or split the route into a token-auth branch and an org-membership branch.
444
+ The `todos` template now ships a `dashboard` named view, exposing a projected response at `GET /api/v1/todos/views/dashboard`. Named views support per-view access rules and per-view field selection while inheriting the table's firewall and masking — the canonical way to ship list-view payloads that are cheaper to fetch and easier to cache than a full collection read.
215
445
 
216
- **`createRealtime` imports without `dbConfig.realtime: true` now throw.** Project lib + action + feature-lib files are scanned at compile time for `import { createRealtime }` (and the equivalent named binding). When the project hasn't enabled realtime, the compile fails with the offending file paths and remediation: either enable `dbConfig.realtime: true` so the runtime helper exists, or remove the import. Caught against AttendVIP — three handler files (`broadcastAnnouncement.ts`, `declineActivityForGuest.ts`, `applyRsvp.ts`) imported `createRealtime` after the v0.15 auto-broadcast wiring landed, but their config never set `realtime: true`. The Worker compiled, deployed, and 500'd at first call. The user's framing was "config should be the source of truth" — this validator enforces that. Five regression tests in `realtime-import-without-config-rejected.test.ts`.
446
+ ### `quickback init` removed
217
447
 
218
- ### Fixes
448
+ Folded into `start` and `create`. The legacy command name prints a deprecation notice pointing at its replacements.
219
449
 
220
- **1. `SYSADMIN` was missing from the per-feature standalone gate's `allowsWithoutOrg` set.** The standalone-action wrapper skips its `if (!ctx.activeOrgId)` gate for any access tree referencing a pseudo-role (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`) — but `SYSADMIN`, the v0.15.0 fifth marker, was missing from the matcher. Sysadmin actions on `cms.sysadmin: true` projects were 403'ing on cross-tenant calls (sysadmins have no member rows, so `ctx.activeOrgId` is unset by design). The matcher now includes `SYSADMIN`.
450
+ ### Minor
221
451
 
222
- **2. Apex `/` and `/account/login` get fallback redirects when neither CMS nor Account SPA is bundled.** Projects that opt out of both bundled SPAs still receive traffic at `/` (no apex handler, 404) and `/account/login` (no Account fallback, 404). Setting `auth.loginUrl` to an external sign-in host now activates two compiler-emitted redirects so those natural inbound URLs land somewhere useful: `/account/login → loginUrl?redirect=…` (preserves the bounce param) and `/ → loginUrl` (or `/account` when the Account SPA is bundled). Both opt in via `auth.loginUrl !== '/account/login'` so projects using the built-in `/account/login` keep the existing SPA-fallback behavior unchanged.
452
+ - `quickback whoami` reads the stored tier from your credentials.
453
+ - Pro upsell copy in `quickback login` is shown only when the server returns an explicit free-tier subscription.
454
+ - Bare scaffolds (`cloudflare`, `empty`) report accurately when there are no features to generate migrations for.
223
455
 
224
- **3. Record-based action URLs are now kebab-case to match OpenAPI.** `record-based.ts` was emitting URL paths from the camelCase action name (e.g. `/api/v1/widgets/:id/sendInvite`) while OpenAPI emit produced `/widgets/:id/send-invite`. Admin tooling and SDK consumers reading the OpenAPI spec hit 404s on every multi-word action. URL paths and OpenAPI emit now share a `urlPath = toKebabCase(urlSegment)` helper. Identifiers in audit `actionName`, error messages, and console logs stay camel — those are programmatic surfaces and breaking them would churn audit logs. Same fix shape as the v0.15.0 standalone-action URL casing.
456
+ ---
225
457
 
226
- ### Notes
458
+ ## v0.16.10 — May 14, 2026
227
459
 
228
- Test coverage: 1175 → 1183 (+8 across the canonicalization, customLogin, and createRealtime regression files). Verified end-to-end against AttendVIP — `quickback compile` produces a worker whose `/account/login`, hostname-routed account/admin SPAs, and apex / handler all return 200 with the right SPA shell on the deployed Cloudflare worker, no 307 loops.
460
+ ### D1-specific safety pass on generated migrations
229
461
 
230
- The bundled docs (`packages/claude-skill/docs/changelog.md`, `packages/cli/src/skill/docs/changelog.md`) and the CLI's `packages/cli/src/docs/content.ts` are regenerated by `scripts/bundle-docs.ts` — run that before publishing the CLI bump.
462
+ The `cloudflare-d1` provider now runs a post-generation pass over every Drizzle migration directory (auth, features, webhooks, audit) before the compile finishes. Better Auth cleanup for retired managed tables is stripped from raw `DROP TABLE` statements. Drop-only cleanup migrations are reordered child-first when foreign-key dependencies require it. Every generated D1 migration directory is replayed against SQLite during compile, so a D1-breaking migration fails at compile time rather than at `wrangler d1 migrations apply`.
231
463
 
232
464
  ---
233
465
 
234
- ## v0.16.0 — May 9, 2026
466
+ ## v0.16.9 — May 13, 2026
235
467
 
236
- ### Agent Auth Protocol — first-class agent identity for AI callers
468
+ ### Resource-scoped realtime tickets
237
469
 
238
- Quickback now ships a server implementation of the [Agent Auth Protocol](https://agentauthprotocol.com) by way of `@better-auth/agent-auth`. Opt in with `auth.plugins.agentAuth: true` (or the array form `plugins: ["agentAuth"]`). When enabled, the compiler emits a complete agent-auth surface: discovery at `/.well-known/agent-configuration`, capability projection from the project's OpenAPI spec, a device-authorization approval page in the Account SPA at `/agents/approve`, and the four agent-auth tables (`agent`, `agentHost`, `agentCapabilityGrant`, `approvalRequest`) added to the auth schema automatically by `auth generate`.
470
+ `providers.database.config.realtime` accepts an object form for projects whose WebSocket subscribers aren't org members:
239
471
 
240
- **OpenAPI capability projection runs by default.** The compiler emits `src/lib/openapi-spec.ts` (the project's full OpenAPI spec inlined as a const) and wires `createFromOpenAPI(openapiSpec, { ... })` into the `agentAuth(...)` call. Every operation with an `operationId` becomes an agent capability. Default `approvalStrength` map: `GET → "session"`, `POST/PUT/PATCH/DELETE → "webauthn"`. Default `defaultHostCapabilities`: `["GET", "HEAD"]`.
472
+ ```ts
473
+ realtime: {
474
+ wsTicket: {
475
+ role: "attendee",
476
+ requestField: "eventId",
477
+ scopeTable: "events",
478
+ },
479
+ }
480
+ ```
241
481
 
242
- The proxy `onExecute` makes a self-fetch to the worker's own URL with a Better Auth JWT minted for `agentSession.user.id`, so the inner request hits the existing JWT fast-path, populates `ctx`, and the full firewall + access + masking pipeline runs on the proxied call. No new middleware code, no parallel security path — agent capability calls go through the same gates as regular REST traffic. The cost is one Cloudflare subrequest per capability call (~50ms); fine for typical agent traffic. Opt out of OpenAPI projection with `agentAuth: { fromOpenAPI: false }` and wire `capabilities` + `onExecute` by hand.
482
+ The generated `/broadcast/v1/ws-ticket` route authenticates the caller, evaluates the declared relationship role against the request, and mints a short-lived WebSocket ticket scoped to the resolved resource. `realtime: true` continues to enable the org-scoped broadcaster.
243
483
 
244
- The Account SPA gains `/agents/approve` (`packages/account/app/routes/agents.approve.tsx`) — modeled on the existing `/cli/authorize` device-code page. Pastes the user code, fetches the pending request, lists the requested capabilities with a "Step-up" badge on any capability whose `approvalStrength` is `"webauthn"`, then approves or denies. WebAuthn step-up itself is a placeholder for v0.16.0 — the upstream agent-auth API for the escalation call is still settling, so capabilities tagged `"webauthn"` will fail server-side until that lands. The badge tells the user what's coming.
484
+ ### Unified broadcast targeting
245
485
 
246
- ### Bearer-only on `/mcp` and the agent-auth surface
486
+ The realtime helper and Broadcaster now route by `scopeKey || organizationId || userId`. String targets remain shorthand for `organizationId`; explicit targets can scope a broadcast to a resource or a single user:
247
487
 
248
- `/mcp` now forwards **only** `Authorization: Bearer …` into the inner `app.request()` re-entry. Cookie + `x-api-key` forwarding has been removed. The MCP surface is server-to-server by nature — there are no browser callers, no CSRF surface to defend, and no benefit to fragmenting the auth model across three header conventions. Three Bearer flavors all land on the same header, resolved by the inner Hono middleware chain:
488
+ ```ts
489
+ await realtime.broadcast("event-page-updated", payload, { scopeKey: "events:evt_123" });
490
+ await realtime.broadcast("dm", payload, { userId: recipientId });
491
+ ```
249
492
 
250
- - Better Auth session token via the official `bearer` plugin
251
- - OAuth access token via the OAuth Provider plugin
252
- - Agent JWT via `@better-auth/agent-auth`
493
+ WebSocket tickets are Quickback-minted (signed with `BETTER_AUTH_SECRET`), not Better Auth tokens — Better Auth remains the front-door auth check; Quickback signs the upgrade ticket after authorization succeeds.
253
494
 
254
- If a project still wants API-key auth here, configure the `apiKey` plugin to accept its key via `Authorization: Bearer` so everything stays one channel. The existing `mcp-server.test.ts` regression seal flips from "forwards Cookie + x-api-key" to "forwards only Authorization (bearer-only surface)".
495
+ ---
255
496
 
256
- ### Auth DSL: `bearer`, `oauthProvider`, `agentAuth` are now first-class plugin entries
497
+ ## v0.16.8 — May 13, 2026
257
498
 
258
- Both the array-form union and the `BetterAuthPlugins` interface in `apps/compiler/src/define/auth.ts` gain `"bearer"`, `"oauthProvider"`, and `"agentAuth"`. `bearer` was previously in the runtime registry but missing from the TS type, so callsites had to use `as any` or `// @ts-expect-error` to set it. Both are gone now. New typed options interfaces — `OAuthProviderOptions` (audience, login/consent paths, dynamic registration) and `AgentAuthOptions` (providerName, providerDescription, modes, fromOpenAPI, approvalStrength, defaultHostCapabilities) — let users override defaults through the object form.
499
+ ### One auth transport per request
259
500
 
260
- Auto-enable rule lives in the canonical `computeAutoAddedPlugins` (`generators/auth.ts`): turning on `agentAuth` force-adds `bearer` + `oauthProvider`. There is no useful agent-auth deployment without those two — surfacing it as auto-add rather than a confusing "missing dependency" runtime error matches the existing pattern (`oauthProvider` already auto-adds `jwt`).
501
+ Generated middleware treats `Cookie`, `Authorization: Bearer`, and `x-api-key` as distinct auth methods and rejects mixed requests with `400 AUTH_METHOD_CONFLICT`. Query-string API keys (`?api_key=` / `?key=`) are no longer accepted. Machine-to-machine auth is explicit; precedence rules between transports are gone.
261
502
 
262
- ### `queue-consumer.ts` now emitted for `additionalQueues` too
503
+ ### Cookie-backed CSRF gate
263
504
 
264
- Prior to this release, the queue consumer emit gated on `embeddingFeatures.length > 0 || queueHandlers.length > 0`. Projects that declared queue infrastructure via `dbConfig.additionalQueues` but had no embeddings + no `services/queues/*` handlers shipped a `wrangler.toml` with `[[queues.consumers]]` entries pointing at a missing worker `queue` export. The CLI's archive-restore step kept a stale `queue-consumer.ts` around, so the file appeared "stuck" across compiles — same class of bug as the v0.15.0 services/queues/* regression caught against AttendVIP, just one source removed.
505
+ Generated apps now block cross-site `POST` / `PUT` / `PATCH` / `DELETE` requests from cookie-relying callers. The middleware skips explicit `Authorization` clients, requires a trusted `Origin` or `Referer`, and blocks `Sec-Fetch-Site: cross-site`. This matters most for cross-subdomain session setups where `SameSite=None` is intentional.
265
506
 
266
- The gate is now a three-way OR: `hasEmbeddings || hasQueueHandlers || hasAdditionalQueues`. When only `additionalQueues` is set, the compiler emits a stub `queue-consumer.ts` whose `queue` export acks every message with a warning — Cloudflare needs an export for every consumer binding, and a noisy-but-correct stub beats a silent deploy break. `MainAppOptions` and `CloudflareMainAppOptions` gain `hasAdditionalQueues`; `generateQueueImport` and `generateCloudflareExport` mirror the new gate. Regression test: `src/__tests__/queue-additional-queues-gate.test.ts`.
507
+ ### First-class Wrangler observability
267
508
 
268
- ### Fixes
509
+ `providers.runtime.config.observability` now supports nested `logs` / `traces` blocks for `headSamplingRate`, `destinations`, `persist`, and `logs.invocationLogs`, emitting matching `[observability]`, `[observability.logs]`, and `[observability.traces]` TOML.
269
510
 
270
- **1. `bearer` was missing from the `BetterAuthPlugins` TypeScript interface.** The runtime plugin registry has had `bearer` since the pre-1.0 cuts, but `apps/compiler/src/define/auth.ts` never declared it on the typed shape — so any `quickback.config.ts` using `plugins: { bearer: true }` had to `as any`-cast or sit behind a `@ts-expect-error`. Both `bearer` and `oauthProvider` (same gap, same workaround) are now first-class typed entries; `agentAuth` joins them. The array-form union also gains all three. No behavior change at runtime; existing casts can come out.
511
+ ---
271
512
 
272
- **2. MCP `buildInternalRequest` no longer forwards Cookie or `x-api-key`.** The MCP surface is server-to-server — there are no browser callers, no CSRF surface to defend, and no benefit to fragmenting the auth model across three header conventions. The inner `app.request()` re-entry now forwards only `Authorization: Bearer …`. Three Bearer flavors all land on the same header (BA session token via the `bearer` plugin, OAuth access token via OAuth Provider, agent JWT via `@better-auth/agent-auth`). Existing `mcp-server.test.ts` regression flipped from "forwards Cookie + x-api-key" to "forwards only Authorization (bearer-only surface)".
513
+ ## v0.16.7 — May 12, 2026
273
514
 
274
- **3. `agentAuth` now auto-enables `bearer` + `oauthProvider`.** There is no useful agent-auth deployment without those two — the agent surface is bearer-only and MCP clients need OAuth to register. Auto-enable lives in the canonical `computeAutoAddedPlugins` (`generators/auth.ts`), so it propagates to every consumer (better-auth generator, schema generation, package-deps emission). Same pattern as the existing `oauthProvider` → `jwt` rule. Surfaced in `agent-auth.test.ts` with a regression seal that asserts both plugins land in the merged plugin list whether the user wrote the array form or the object form.
515
+ ### Bearer wins over cookie
275
516
 
276
- **4. `OpenAPISpec` literal type rejected by tsc on inlined spec.** Quickback's OpenAPI emit produces `$ref`-style parameter entries (`{ "$ref": "#/components/parameters/X" }`) that the agent-auth plugin's stricter `OpenAPIParameter` type doesn't model — `tsc` fails the generated project with "Type … is not assignable to OpenAPIParameter". The plugin handles refs correctly at runtime; only the structural narrowing on the TS literal needed help. The generated `agentAuth({ ...createFromOpenAPI(openapiSpec as any, { ... }) })` call now carries an `as any` cast on the spec with an inline comment explaining why. Drop when upstream models `$ref` parameters.
517
+ A request carrying both `Authorization` and a session `Cookie` resolves entirely from the bearer; the cookie is dropped before `getSession()` runs. All three Bearer flavors (API key, JWT, session-token) now behave consistently — no more silent cookie precedence on session-token bearers.
277
518
 
278
- ### Notes
519
+ ### Bearer plugin defaults to `requireSignature: true`
279
520
 
280
- `@better-auth/agent-auth` 0.4.5 ships ESM-only exports without a `require` condition, so the Better Auth CLI's `auth generate` step (jiti / CJS resolver) bails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. The compiler image patches the package's `package.json` at install time to add a matching `require` condition pointing at the same dist file (Node 22+ supports `require(esm)`). Remove the patch in `apps/compiler/Dockerfile` when upstream ships proper exports.
521
+ Better Auth's `bearer` plugin defaults to unsigned tokens; Quickback now emits `bearer({ requireSignature: true })`. Tokens emitted in the CORS-exposed `set-auth-token` header are server-signed with `BETTER_AUTH_SECRET` and verified on every request. Projects that genuinely need unsigned bearers can override via `providers.auth.config.plugins.bearer`.
281
522
 
282
- Test coverage: 1136 → 1152 (+11 `agent-auth.test.ts`, +5 `queue-additional-queues-gate.test.ts`). Verified end-to-end against `examples/recruitment` with `agentAuth` enabled — `quickback compile` produces a project whose `npm run build` typechecks clean and whose generated schema includes all four agent-auth tables (`agent`, `agentHost`, `agentCapabilityGrant`, `approvalRequest`).
523
+ See [Authentication Security → Bearer Tokens and Cookie Precedence](/stack/auth/security#bearer-tokens-and-cookie-precedence).
283
524
 
284
525
  ---
285
526
 
286
- ## v0.15.0 — May 7, 2026
527
+ ## v0.16.5 — May 12, 2026
528
+
529
+ ### Flat write DSL
530
+
531
+ Resource write operations are now declared at the table level alongside `read`, replacing the nested `crud` block:
532
+
533
+ ```ts
534
+ defineTable(customers, {
535
+ read: { ... },
536
+ create: { access: { roles: ["admin"] } },
537
+ update: { access: { roles: ["admin"] } },
538
+ delete: { access: { roles: ["admin"] }, mode: "soft" },
539
+ upsert: { access: { roles: ["admin"] } },
540
+ guards: { ... },
541
+ });
542
+ ```
287
543
 
288
- ### Sysadmin tier — cross-tenant DB-admin role for the CMS
544
+ `crud` and top-level `put` still compile as deprecated compatibility aliases. Mixed usage on the same resource is rejected. `schema-registry.json` emits both shapes during the transition.
289
545
 
290
- A new opt-in `cms: { sysadmin: true }` flag turns the CMS into a Supabase-style cross-tenant DB-admin tool gated by `user.role === 'sysadmin'`. Distinct from `'admin'` so Better Auth admin-plugin powers (user management, impersonation) and DB-admin powers stay decoupled. Off by default — projects without the feature get zero behavior change.
546
+ ### CMS placement for multi-table feature actions
291
547
 
292
- When enabled, the compiler emits a `SYSADMIN` pseudo-role (fifth marker alongside `PUBLIC` / `AUTHENTICATED` / `USER` / `ADMIN`); a firewall escape hatch in every `buildFirewallConditions` that drops tenant scopes for `ctx.userRole === 'sysadmin'` while preserving soft-delete; a true cross-tenant `/admin/v1/sysadmin/organizations` endpoint that selects directly from the auth-schema `organization` table; and a relaxed cross-tenant guard that skips the `ORG_REQUIRED` 400 for sysadmins on list routes — that's how the SPA's "All organizations" sentinel reaches the firewall escape end-to-end.
548
+ Standalone actions on multi-table features have an explicit placement model:
293
549
 
294
- The CMS SPA gains a two-mode design: org admins keep the existing membership-based switcher (Better Auth's `setActiveOrganization`); sysadmins get a `SysadminOrgSelector` that loads from the cross-tenant endpoint, defaults to "All organizations" (omits the org filter on reads), and pins selected tenants via `?organizationId=` on every API call (sysadmins have no member rows, so `setActive` would 403). A new `OrgGate` component handles no-active-org cases for org users — auto-pick when there's exactly one membership, full-frame picker for multiple, empty state for zero — so sessions that lost their active org don't dead-end.
550
+ - `cms.placement: "feature"` shows the action on every table toolbar in the feature
551
+ - `cms.placement: "tables"` with `cms.tables` scopes it to specific tables
552
+ - `cms.hidden: true` keeps it API-only
295
553
 
296
- Refusing to compile `roles: ["SYSADMIN"]` without `cms.sysadmin: true` keeps the role from sitting as dead code. RLS providers (Neon, Supabase) emit `false` for `SYSADMIN` today; per-table RLS policy emit is a follow-up.
554
+ Feature-root standalone actions are emitted under a new `featureActions` bucket in `schema-registry.json`. Ambiguous multi-table standalone actions without placement compile with a warning.
297
555
 
298
- ### Durable Object `[[migrations]]` order is now preserved across recompiles
556
+ ### `openapi.types` accepts a string array
299
557
 
300
- Cloudflare's migration system is append-only — every deploy must include previously-deployed migration tags in their original order, with new ones appended last. CF rejects deploys with `code: 10061` when the order shifts. The compiler used to iterate `bindings.durableObjects` in config order at emit time, so a user inserting a new DO into the middle of the array bumped every later auto-migration into the wrong slot, breaking deploys for projects with multiple DOs (caught by AttendVIP).
558
+ One compile can write the generated types file to multiple locations, keeping colocated SPA clients in sync:
301
559
 
302
- The CLI now sends the project's existing `wrangler.toml` (when present) in `existingFiles` alongside the drizzle meta. The compiler parses migration tags from it via `parseExistingMigrationTags`, then emits auto-generated DO `[[migrations]]` blocks in two phases: deployed entries first (preserving the existing wrangler.toml order), net-new entries appended last in `bindings.durableObjects` config order. Reordering DOs in the config array no longer reshuffles deployed migrations; inserting a new DO anywhere in the array always appends its migration block last. First compiles (no existing wrangler.toml) keep the current config-order behavior — no behavior change for new projects. User-declared `bindings.durableObjectMigrations` (historical entries) are unaffected; they continue to emit first.
560
+ ```ts
561
+ openapi: { types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'] }
562
+ ```
303
563
 
304
- ### Standalone-action wrapper no longer 403s `AUTHENTICATED`-only routes on org-scoped projects
564
+ ### Stable artifact ordering
305
565
 
306
- Standalone actions (`standalone: true`) on org-scoped projects emitted an unconditional `if (!ctx.activeOrgId) return 403 ACCESS_NO_ORG` gate before role checking. For an action declared `access: { roles: ["AUTHENTICATED"] }`, this contradicted the access rule itself: a signed-in user with no active org (e.g. just signed up but not yet joined an organization, or a token-auth caller) was the exact caller `AUTHENTICATED` was supposed to admit. Found by AttendVIP — every recompile re-introduced the bug because the fix lived in handler-side patches, not the generator. The standalone wrapper now skips the org gate when the access tree references any pseudo-role anywhere, including under `or:`/`and:` arms.
566
+ Generated route files and `schema-registry.json` are emitted in a stable order across runs. Identical logical input produces identical artifacts.
307
567
 
308
- ### Queue handler emit no longer drops the `queue` export when there are no embeddings
568
+ ---
309
569
 
310
- `compiler.ts` emits `src/queue-consumer.ts` whenever `embeddingFeatures.length > 0 || queueHandlers.length > 0`, but the worker entry only checked `hasEmbeddings`. Projects with custom queue handlers under `services/queues/*` and no embeddings got the consumer file generated and then no entry-point wiring — wrangler bound the queue to a missing handler at deploy time. Caught against AttendVIP's `sendCancelEmail` queue handler. `MainAppOptions` and `CloudflareMainAppOptions` gain a `hasQueueHandlers` flag; `generateQueueImport` and `generateCloudflareExport` now gate on `hasEmbeddings || hasQueueHandlers`.
570
+ ## v0.16.4 — May 12, 2026
311
571
 
312
- ### `quickback/public/` — static-asset passthrough into `src/apps/`
572
+ ### Drizzle snapshot integrity
313
573
 
314
- A new opt-in folder. Anything you drop under `quickback/public/` is copied verbatim into `src/apps/` on every compile, where the wrangler `[assets]` binding (`directory = "src/apps"`) already serves it. So `quickback/public/robots.txt` becomes reachable at `https://your-domain/robots.txt`, `quickback/public/og/og-image.png` at `/og/og-image.png`, and so on. Favicons, `robots.txt`, OG images, marketing PDFs, sitemap fragments, `.well-known/` files — anything you'd previously have had to post-process into `src/apps/` after each compile.
574
+ Drizzle metadata files (`<n>_snapshot.json`) are no longer stamped with a Quickback warning key. The warning is now journal-only. Projects whose snapshots were corrupted by an earlier release self-heal on the next compile — the stripped header is removed during staging and the rewritten snapshot is clean.
315
575
 
316
- The compiler does **not** parse, template, or otherwise touch these files. They ride past it as bytes — the CLI does the copy after `writeFilesWithMerge`, using `fs.copyFile` so binaries (PNGs, fonts, PDFs) stay byte-perfect rather than being corrupted by the utf-8 string channel the compiler manifest uses for source files. The compiler API contract is unchanged; nothing round-trips through `compile.quickback.dev`.
576
+ ### `account.auth.*` drives the server, not just the SPA
317
577
 
318
- Rules:
578
+ The Account UI's auth flags (`signup`, `password`, `passkey`, `emailOTP`, `emailVerification`) now configure the Better Auth server alongside the SPA bundle. A normalizer maps them into the server config:
319
579
 
320
- - **Optional.** If the folder doesn't exist, the step is a no-op.
321
- - **Stale-cleaned.** `src/` is wiped and rewritten each compile, so files removed from `quickback/public/` disappear from `src/apps/` automatically on the next run.
322
- - **Hidden entries skipped.** `.DS_Store`, `.git/`, dotfiles — none of these were intentional drops; including them would break worker asset bindings.
323
- - **Collisions fail loud.** A file in `quickback/public/` whose path would shadow a compiler-emitted manifest entry — e.g. `quickback/public/cms/index.html` against the SPA shell — fails the compile with the offending paths listed, rather than silently overwriting and producing a confused-looking SPA build. Move or rename the offending file.
580
+ - `signup → emailAndPassword.disableSignUp` (inverted)
581
+ - `password → emailAndPassword.enabled`
582
+ - `emailVerification → emailAndPassword.requireEmailVerification`
583
+ - `passkey` / `emailOTP` → plugin additions
324
584
 
325
- The change is contained to the CLI: `packages/cli/src/lib/copy-public-assets.ts` (helper + `PublicAssetCollisionError`) and one block in `packages/cli/src/commands/compile.ts`. Test coverage in `copy-public-assets.test.ts` walks the missing-folder, single-file, nested-tree, binary-preservation, hidden-entry, single-collision, multi-collision, empty-folder, and split-output cases — nine tests, byte-level assertions on the binary path.
585
+ The SPA's `VITE_ENABLE_*` flags are derived from the same canonicalized server config, so the bundle and the server cannot drift. Two new flags ride along: `VITE_ENABLE_API_KEYS` and `VITE_ENABLE_MAGIC_LINK`.
586
+
587
+ **Breaking** for projects that implicitly relied on the SPA-only behaviour: `account.auth.signup: false` now actually disables `POST /auth/v1/sign-up/email` on the server. Set `providers.auth.config.emailAndPassword.disableSignUp: false` explicitly to keep server signup open while hiding the SPA screen.
326
588
 
327
589
  ---
328
590
 
329
- ## v0.14.7 — May 7, 2026
591
+ ## v0.16.3 — May 9, 2026
330
592
 
331
- ### Four more codegen bugs caught by AttendVIP — generated output now typechecks for projects with non-`id` PKs and DO-only features
593
+ ### Standalone action mount order
332
594
 
333
- Filed after AttendVIP's `tsc` reported 230 errors against the generated `src/`. Triage split them into six patterns; four are surgical and ship here. The other two (TS2769 ×156 + TS2339 ×~50) trace to a deeper assumption — every queryable table has a string-typed `id` column — and are deferred to v0.14.8 along with the agreed `id` auto-inject design (see *Coming next* below).
595
+ Feature-level standalone action routers now register before sibling CRUD routers when both mount at the exact same prefix. A literal path like `GET /api/v1/records/today-bundle` resolves to the standalone handler instead of falling through to `GET /:id` and treating `"today-bundle"` as a record ID.
334
596
 
335
- **1. Duplicate `guests` import in routes that use relationship-roles (`TS2300`).** The relationship-import injector (`generators/feature-generator.ts`) added `import { <table>, buildFirewallConditions as build<Table>FirewallConditions } from './<table>.resource'` whenever it detected a relationship-table reference in the routes file — without checking that the table binding was already imported from `./schema` upstream. So `guests.routes.ts` ended up with `guests` declared twice. Fix: scan the existing import block, only add identifiers that aren't already in scope (drop the binding from the new import line, or skip the line entirely if both binding and alias are imported).
597
+ ---
336
598
 
337
- **2. `db` referenced before declaration in single-record + bulk action handlers (`TS2448` / `TS2304`).** `record-based.ts:195,541` baked `firewallClause = ...buildFirewallConditions(ctx, db)...` and used the same string in two places: (a) the outer pre-fetch `await unsafeDb.select().from(table).where(firewallClause)` — where `db` doesn't exist yet (`db = createScopedDb(unsafeDb, ctx)` is declared later for handler scope), and (b) inside `processBatch` where `db` is created from the tx/handle param. The outer use threw at typecheck (`'db' is used before its declaration`); at runtime it would have been a `ReferenceError`. Fix: pass `unsafeDb` (the in-scope handle) to `buildFirewallConditions` in both `firewallClause` definitions. The helper only uses its `db` arg for relationship-role subqueries (when `via:` is in play); either handle is a valid Drizzle client for that lookup.
599
+ ## v0.16.1 — May 9, 2026
338
600
 
339
- **3. PartyServer realtime gates passed 1 arg to a 2-arg `buildFirewall_X` (`TS2554`).** `optional-routes.ts` emitted `buildFirewall_<feature>(ctx as any)` in the WebSocket-upgrade gate for every Durable Object that declared `access: { resource }`. After v0.14.4 made `buildFirewallConditions(ctx, db)` 2-arg whenever the resource has any `via:` predicate, this gate stopped compiling for any DO whose target feature uses relationship-roles. AttendVIP's `event-pages` DO sits on `event_pages` (admin via `guestOf`), which is exactly that case. Fix: the gate already constructs `db = drizzle(c.env.<binding>)` for its own `db.select(...).limit(1)` — pass that same `db` into the firewall call. Mirrored in both the single-resource and multi-resource gate branches.
601
+ ### Cloudflare ASSETS canonicalization
340
602
 
341
- **4. Durable-object-only features dropped their `lib/` files from output (`TS2307`).** `compiler.ts:546` only ran the feature-walker (and copied `featureLibFiles` to output) when the feature had at least one action file. AttendVIP's `user-profiles/` declares a single DO source under `lib/UserGateway.ts` and zero `actions/` — perfectly valid (per-user realtime gateway, the Slack/Linear pattern), but the walker skipped the feature entirely. The compile finished without error, then `index.ts` tried to import `./features/user-profiles/lib/UserGateway` and `tsc` 404'd the module. `event-pages/PageRoom.ts` worked only because that feature happens to also have `actions/`. Fix: run the discovery + lib-copy path whenever the feature has either actions OR lib files. Copying `lib/` files when the feature has at least one of either is the safe reading of the original intent.
603
+ Worker SPA fallbacks now request `/<dir>/` instead of `/<dir>/index.html`. Cloudflare's static-assets binding rewrites `/index.html` requests as 307 redirects to the trailing-slash path under the default `html_handling=auto-trailing-slash`, which previously caused redirect loops in SPA fallback handlers. Affects CMS, Account, admin, and the multi-domain catchall.
342
604
 
343
- **Drops ~20 of the 230 attendvip errors** (TS2300 ×2, TS2448 ×11, TS2304 ×6, TS2554 ×2 from the realtime gate, TS2307 ×1 — depending on cache state). The remaining 210 are TS2769 (numeric-ID arrays where the column is `integer`, not `text`) and TS2339 (`.id` referenced on tables that have a non-`id` PK or a compound PK) — both downstream of the same root: `id` is currently *not* auto-injected, only audit columns are.
605
+ ### `account.customLogin`
344
606
 
345
- ### Account auth: emailOtp on AWS SES drops the magic-link companion (OTP-only)
607
+ Set `account: { customLogin: true }` to drop a project-branded sign-in page in front of the bundled SPA. Place the page at `quickback/public/account/login/index.html` (as a directory) and the existing public passthrough serves it. The route registers before the `/account/*` SPA catch-all so the static handler wins; everything else under `/account/` continues to route through the bundled SPA.
346
608
 
347
- The compiler used to auto-wire `createComboAuthSendVerificationOTP` from `@quickback-dev/better-auth-combo-auth` whenever a project used `emailOtp` with the `aws-ses` email provider — sign-in / sign-up / verify emails carried *both* a 6-digit OTP and a clickable magic link, with `useComboAuthEmail: true` in the SES config. This was on by default for every account-app project that picked AWS SES.
609
+ ### Project-level realtime defaults
348
610
 
349
- Two reasons to drop the magic-link half:
611
+ `providers.database.config.realtime: true` now treats every resource as realtime-enabled by default. Per-resource `realtime: { enabled: false }` still wins.
350
612
 
351
- 1. **Mail-client URL prefetching can burn the OTP before the human sees the email.** Outlook Safe Links, Gmail mobile, corporate proxies, and security scanners all eagerly fetch URLs in incoming mail; the magic link's `?data=...` payload includes the OTP server-side, so the first GET completes the sign-in (consuming the one-time code) and the user clicking through 30 seconds later gets a "code already used" failure.
352
- 2. **Two sign-in surfaces are harder to support.** The account SPA's `/welcome` and `/email-otp` routes only render the OTP form; the magic-link arm bypasses that UI entirely. One canonical entry point (enter the code) keeps the account flow legible.
613
+ ### Compile-time validators
353
614
 
354
- The compiler now emits a plain `sendVerificationOTP` callback that calls `sendEmailWithSES` with `emailTemplates.emailOTP` directly — no combo wrapper, no magic-link URL. `useComboAuthEmail` is hardcoded to `false`. The `@quickback-dev/better-auth-combo-auth` package and the `magicLink` plugin are still available for users who explicitly opt in via a custom `sendVerificationOTP` in their config; the change here is just the auto-wired default.
615
+ Two new compile-time errors over silent runtime failures:
355
616
 
356
- Test coverage: `auth-email-wiring.test.ts` was updated to assert the new shape — generated auth files for `emailOtp + aws-ses` now contain `emailTemplates.emailOTP` and `useComboAuthEmail: false`, and explicitly do not contain `createComboAuthSendVerificationOTP` or `better-auth-combo-auth`.
617
+ - `AUTHENTICATED` + org-scoped firewall is rejected. The combination silently returned empty lists to sign-in-only callers who lacked an active org; the validator names three valid resolutions (drop the org scope, use `USER`, or split the route).
618
+ - `createRealtime` imports without `realtime: true` enabled in the config are rejected at compile.
357
619
 
358
- ### Coming next — `id` field auto-injection (v0.14.8)
620
+ ### Drizzle metadata hardening
359
621
 
360
- The compiler treats `id` as load-bearing across CRUD/action route generators, FK probing, access checks, OpenAPI emission, and CMS — but doesn't add it for you the way it adds `createdAt`/`modifiedAt`/`createdBy`/`modifiedBy` (or `organizationId` in org-scoped features, or `deletedAt`/`deletedBy` for soft-delete tables). At the time of v0.14.7, tables that omitted `id` (or used a non-`id` single PK like `userId.primaryKey()`, or a compound `primaryKey({ columns: [...] })` constraint) were not yet supported by the generated route and OpenAPI pipeline.
622
+ Drizzle journal files carry a "do not edit" header. The compiler warns when the journal entry count exceeds the snapshot file count (typically the trace of a hand-deleted snapshot).
361
623
 
362
- **Agreed direction:** mirror `injectAuditFields` with a new `injectIdField` that runs unconditionally — including on junction tables. Tables with no PK or a non-`id` PK get an `id` column auto-injected; existing column-level `.primaryKey()` on a non-`id` column gets demoted to `.notNull()`; `primaryKey({ columns: [...] })` constraints get rewritten to `uniqueIndex().on(...)`. The cost (one extra column per junction row) is minimal and closes the asymmetry — every table participating in routes gets a single string-typed `id`, just like every table gets `createdAt`. Migration tail (existing D1 databases need an ADD COLUMN + index rewrite per affected table) is generated alongside.
624
+ ### Minor
363
625
 
364
- No user code changes required for the four fixes shipping in v0.14.7. Recompile and the affected features typecheck.
626
+ - `SYSADMIN` is now recognised by the standalone-action org gate's pseudo-role matcher.
627
+ - Apex `/` and `/account/login` get fallback redirects to `auth.loginUrl` when neither bundled SPA is enabled.
628
+ - Record-based action URLs are kebab-case to match the OpenAPI spec (e.g. `/api/v1/widgets/:id/send-invite`).
365
629
 
366
630
  ---
367
631
 
368
- ## v0.14.6 — May 7, 2026
632
+ ## v0.16.0 — May 9, 2026
369
633
 
370
- ### Four more v0.14 compiler bugs caught by AttendVIP's MCP rollout
634
+ ### Agent Auth Protocol
371
635
 
372
- Filed in `research/attendvip-v014-mcp-and-firewall-gaps.md` after AttendVIP patched these locally and asked us to upstream them. All four ride a single MCP `tools/call` against a team-scoped resource over a Bearer api-key — fix any one and the next bug surfaces. We're shipping them as one patch release with end-to-end coverage of the chain.
636
+ Quickback ships a server implementation of the [Agent Auth Protocol](https://agentauthprotocol.com) via `@better-auth/agent-auth`. Enable with `auth.plugins.agentAuth: true` and the compiler emits the full agent-auth surface: discovery at `/.well-known/agent-configuration`, capability projection from the project's OpenAPI spec, a device-authorization approval page in the Account SPA at `/agents/approve`, and the four agent-auth tables added to the auth schema automatically.
373
637
 
374
- **1. MCP `tools/call` URL is double-prefixed for action tools.** The OpenAPI spec emits action paths as `/api/v1/<action>` already-absolute, but the MCP request builder did `'/api/v1' + tool._path` unconditionally — so action tool calls hit `/api/v1/api/v1/<action>` and 404'd. CRUD tools (bare `_path: '/customers'`) were unaffected. Fix: prefix only when `_path` doesn't already start with `/api/v1/`.
638
+ **OpenAPI capability projection runs by default.** Every operation with an `operationId` becomes an agent capability. Default `approvalStrength` map: `GET → "session"`, `POST/PUT/PATCH/DELETE → "webauthn"`. The proxy `onExecute` makes a self-fetch with a Better Auth JWT minted for the agent session, so the inner request hits the existing JWT fast-path and runs the full firewall + access + masking pipeline. Opt out of OpenAPI projection with `agentAuth: { fromOpenAPI: false }` and wire `capabilities` + `onExecute` by hand.
375
639
 
376
- **2. Auth middleware ignored `Authorization: Bearer <api-key>`.** MCP clients (claude.ai, etc.) only set `Authorization: Bearer ...`. The api-key block read from `x-api-key` header / `?api_key=` / `?key=` query but not from `Authorization`; the JWT fast-path narrowly gated on `bearerToken.startsWith('eyJ')`. Non-JWT bearers fell through to BA session auth, which doesn't recognise api-keys, so the request authenticated as anonymous and `tools/list` returned only PUBLIC tools. Fix: api-key extraction now also accepts a non-JWT `Authorization: Bearer <token>` as the key candidate. Three transports for one credential — header / query / Bearer.
640
+ ### Bearer-only on `/mcp` and the agent-auth surface
377
641
 
378
- **3. `auth.roleHierarchy` was silently inert for runtime role checks.** A user configured `auth.roleHierarchy: ['owner', 'admin', 'member']` and expected an `owner` to satisfy any check requiring `admin` or `member`. But the api-key + JWT fast-paths populated `ctx.roles` with the single org-member role, and the access checker did strict intersection — `owner ∩ {admin, member} = ∅` → 403. Fix: at the api-key, JWT fast-path, AND BA session paths, expand the user's role via `auth.roleHierarchy` so a higher role inherits all lower-role privileges. The hierarchy is auto-normalized — users who write the array reversed (`['owner', 'admin', 'member']` instead of the documented `['member', 'admin', 'owner']`) now get the same correct expansion.
642
+ `/mcp` forwards only `Authorization: Bearer …` into the inner request. Cookie and `x-api-key` forwarding are removed. Three Bearer flavors land on the same header — Better Auth session token (via the `bearer` plugin), OAuth access token (via OAuth Provider), and agent JWT (via `@better-auth/agent-auth`).
379
643
 
380
- **4. Team-firewall predicate hardcoded `eq(table.teamId, ctx.activeTeamId!)` even when no team was active.** The `!` non-null assertion lied at runtime — api-keys, JWTs, and sessions without an active team carry `undefined`. The resulting SQL was `team_id = NULL` which matches nothing, so api-key callers saw zero rows on team-scoped resources. Fix: emit the team predicate as `(ctx.activeTeamId ? eq(...) : undefined)` — drizzle's `and(...)` drops `undefined`, so the WHERE collapses to the org scope only. Org and owner predicates are deliberately NOT softened the same way (those are security boundaries, not optional scopes).
644
+ ### Auth DSL gains first-class plugin entries
381
645
 
382
- After upstreaming, the AttendVIP one-shot verification passes:
646
+ `bearer`, `oauthProvider`, and `agentAuth` are now typed entries in both the array-form union and the `BetterAuthPlugins` interface, with their own options shapes (`OAuthProviderOptions`, `AgentAuthOptions`). Existing `as any` casts can come out.
383
647
 
384
- ```bash
385
- curl -fs -X POST https://attend.vip/mcp \
386
- -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
387
- -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"listEvents","arguments":{}}}' \
388
- | jq '.result.content[0].text | fromjson | .data | length' # > 0
389
- ```
648
+ Auto-enable rule: turning on `agentAuth` force-adds `bearer` + `oauthProvider`. No useful agent-auth deployment ships without those two.
649
+
650
+ ### `queue-consumer.ts` gating
390
651
 
391
- No user code changes required for any of the four. Recompile and the MCP path works end-to-end against team-scoped, role-gated resources via Bearer api-key.
652
+ The queue consumer is emitted when any of the following are true: embeddings are configured, queue handlers exist under `services/queues/*`, or `additionalQueues` is declared. Previously the third case left projects with a wrangler binding pointing at a missing handler.
392
653
 
393
654
  ---
394
655
 
395
- ## v0.14.5 — May 7, 2026
656
+ ## v0.15.0 — May 7, 2026
657
+
658
+ ### Sysadmin tier for the CMS
659
+
660
+ A new opt-in `cms: { sysadmin: true }` flag turns the CMS into a cross-tenant DB-admin tool gated by `user.role === 'sysadmin'`. Distinct from the Better Auth `'admin'` plugin role, so user-management powers and DB-admin powers stay decoupled. Off by default.
661
+
662
+ When enabled, the compiler emits a `SYSADMIN` pseudo-role (a fifth marker alongside `PUBLIC` / `AUTHENTICATED` / `USER` / `ADMIN`), a firewall escape hatch that drops tenant scopes for sysadmins while preserving soft-delete, a true cross-tenant `/admin/v1/sysadmin/organizations` endpoint, and a relaxed cross-tenant guard for list routes.
663
+
664
+ The CMS SPA gains a two-mode design: org admins keep the existing membership-based switcher, sysadmins get an "All organizations" selector that pins tenants via `?organizationId=` on every API call.
665
+
666
+ ### Durable Object `[[migrations]]` order is preserved
667
+
668
+ Cloudflare's migration list is append-only. The compiler now reads your existing `wrangler.toml` (when present) and emits auto-generated DO `[[migrations]]` blocks in two phases: deployed entries first (preserving order), net-new entries appended last. Reordering DOs in the config array no longer reshuffles deployed migrations.
669
+
670
+ ### `quickback/public/` — static-asset passthrough
396
671
 
397
- ### MCP `tools/call` no longer crashes with `undefined (reading 'AUTH_DB')`
672
+ Anything dropped under `quickback/public/` is copied verbatim into `src/apps/` on every compile and served by the wrangler `[assets]` binding. Use for favicons, `robots.txt`, OG images, `.well-known/` files, marketing PDFs — anything that needs to ride past the compiler as bytes.
398
673
 
399
- The generated MCP server's `tools/call` dispatch re-enters the same Hono app via `app.request(internalReq)` so every tool invocation runs through the full middleware chain (auth, firewall, access, guards, masking). But the call passed only the request — not `env` or `executionCtx` — so the sub-request handler ran with `c.env === undefined`. Any tool whose route touched a Cloudflare binding (e.g. the `AUTH_DB` D1, KV, R2, Queues) crashed with `Cannot read properties of undefined (reading 'AUTH_DB')`. Found by AttendVIP — every action that hit auth-side data (acceptInvite, etc.) failed.
674
+ - Optional. Missing folder is a no-op.
675
+ - Stale-cleaned. Files removed from `quickback/public/` disappear on the next compile.
676
+ - Hidden entries (`.DS_Store`, dotfiles) are skipped.
677
+ - Collisions with compiler-emitted manifest paths fail the compile loudly.
400
678
 
401
- **Fix:** `mountMcp` now threads `c.env` and `c.executionCtx` through to `handle → handleRpc → callTool → app.request(internalReq, undefined, env, executionCtx)`. Hono's `request()` 3rd/4th args set the bindings + execution context for the sub-request, so the action handler sees the same env the outer worker received. Tools/list was unaffected — it reads ctx in-process and never re-enters the app.
679
+ ### Minor
402
680
 
403
- No user code changes required. Recompile against v0.14.5 and the MCP endpoint dispatches actions correctly against all bindings.
681
+ - Standalone-action wrapper skips the org gate when the access tree references any pseudo-role.
682
+ - Queue handler emit no longer drops the `queue` export when there are no embeddings.
404
683
 
405
684
  ---
406
685
 
407
- ## v0.14.4 — May 7, 2026
686
+ ## v0.14.7 — May 7, 2026
687
+
688
+ ### Codegen fixes for projects with non-`id` primary keys and DO-only features
689
+
690
+ Four surgical fixes to the generated output:
408
691
 
409
- ### `via:` firewall predicates no longer crash with `ReferenceError: db is not defined`
692
+ - Duplicate table imports in relationship-role routes are deduplicated.
693
+ - `db` references in single-record and bulk action handlers now resolve correctly during pre-fetch.
694
+ - PartyServer auth gates pass the in-scope `db` handle into firewall calls.
695
+ - Durable-object-only features keep their `lib/` files in the output.
410
696
 
411
- The relationship-role generator (v0.14.0) emits a `buildFirewallConditions` body that references `db`, `inArray`, and `sql` at function scope when any predicate has `via:` — but the resource-file imports it generated only pulled in `eq, and, isNull, type SQL`. So every endpoint guarded by `firewall: [{ field, via }]` threw `ReferenceError: db is not defined` at the very first request, and the catch-all returned 500 before the firewall query ever ran. Found by AttendVIP on `/api/v1/event-pages` against v0.14.3 — none of the v0.14.0 → v0.14.3 unit tests exercised emitted-import resolution, so the bug rode through three patch releases.
697
+ ### `emailOtp` + AWS SES is OTP-only
412
698
 
413
- Two fixes:
699
+ `auth.emailOtp` with the AWS SES email provider no longer auto-wires the magic-link companion. Mail-client URL prefetching can burn the one-time code before the human sees it; the Account SPA's `/email-otp` route is the single canonical entry point. Projects that explicitly want the magic-link arm can wire `sendVerificationOTP` directly.
700
+
701
+ ---
702
+
703
+ ## v0.14.6 — May 7, 2026
414
704
 
415
- 1. **Imports in the generated resource file now include `inArray, sql`** when the firewall has any `via:` predicate. Hidden behind a flag so a no-via resource still gets the minimal import surface.
416
- 2. **`buildFirewallConditions` now takes `(ctx, db)`** and the wrapper template (`WITH_FIREWALL_HELPER`) pulls `const db = c.get('db' as never) as any;` from the Hono context before invoking it. Every CRUD/action call site (single-record + batch + record-based-action) was updated to pass `db` through.
705
+ ### MCP transport correctness
417
706
 
418
- Regression test added (`firewall-via-imports.test.ts`) that parses the generated resource file's top-level imports and asserts every free identifier referenced in `buildFirewallConditions` resolves to either an import or a function parameter — so a future generator change that introduces a new free identifier (`exists`, `not`, etc.) without importing it fails the unit suite instead of leaking to a real project.
707
+ Four fixes to the MCP-over-HTTP path:
419
708
 
420
- No user code changes required — recompile and `via:` predicates work end-to-end.
709
+ - `tools/call` URLs are no longer double-prefixed for action tools.
710
+ - Auth middleware accepts API keys via `Authorization: Bearer` in addition to `x-api-key` and query parameters — the channel MCP clients use exclusively.
711
+ - `auth.roleHierarchy` is expanded for runtime role checks across api-key, JWT, and session auth paths. A higher role inherits the privileges of every lower role.
712
+ - Team-scoped firewall predicates degrade gracefully when no team is active (org scoping continues to apply; team scoping is optional).
421
713
 
422
714
  ---
423
715
 
424
- ## v0.14.3 — May 7, 2026
716
+ ## v0.14.5 — May 7, 2026
425
717
 
426
- ### Relationship-role consumers now resolve the relationship-table binding at runtime
718
+ ### MCP environment threading
427
719
 
428
- Pre-fix, the v0.14.0 relationship-role generator emitted imports like `import { eventGuests, buildFirewallConditions as buildEventGuestsFirewallConditions } from '../event-guests/event-guests.resource'` on every consuming resource — but the relationship-table's own `.resource.ts` file imported `event_guests` from `./schema` for its own use without re-exporting it. So the consuming file got `undefined` at runtime, every relationship subquery failed with `Cannot read properties of undefined`, and the whole authz layer was unreachable on real projects.
720
+ The generated MCP server's `tools/call` dispatch threads `env` and `executionCtx` into the inner request, so action tools that touch Cloudflare bindings (D1, KV, R2, Queues) no longer crash with `undefined` env access.
429
721
 
430
- Found by AttendVIP within minutes of recompiling against v0.14.2: the moment they hit any endpoint guarded by `firewall: [{ field, via }]` or `crud.<op>.access roles: ['guest']`, the request errored before the firewall query ran.
722
+ ---
431
723
 
432
- The fix is one line in `generateTableResourceHelpers` — re-export the Drizzle table binding from the `.resource` file alongside the existing import. The `.resource` file is the public surface of the table; the schema is an implementation detail. This decision was implicit in the relationship-import resolver's path choice but not enforced on the producer side.
724
+ ## v0.14.4 — May 7, 2026
433
725
 
434
- ```ts
435
- // generated <table>.resource.ts (after fix)
436
- import { event_guests } from './schema';
437
- export { event_guests }; // ← was missing
438
- ```
726
+ ### `via:` firewall predicates pull required imports
439
727
 
440
- Regression test added (`authz-end-to-end.test.ts`) that asserts every `.resource` file re-exports its Drizzle binding, so this can't drift again. No user code changes required — recompile and the cross-feature relationship subqueries resolve correctly.
728
+ The relationship-role generator emits `inArray` and `sql` imports when the firewall has any `via:` predicate, and `buildFirewallConditions` accepts `(ctx, db)` so the relationship subquery has a Drizzle client to evaluate against. Every CRUD and action call site passes `db` through automatically.
441
729
 
442
730
  ---
443
731
 
444
- ## v0.14.2 — May 7, 2026
732
+ ## v0.14.3 — May 7, 2026
733
+
734
+ ### Relationship-role table re-exports
445
735
 
446
- ### Wrangler `[[migrations]]` no longer drops historical Durable Object lifecycle entries
736
+ Generated `<table>.resource.ts` files now re-export their Drizzle table binding. Cross-feature relationship subqueries that import the binding from the resource file (rather than the schema) resolve correctly.
737
+
738
+ ---
447
739
 
448
- Cloudflare requires the `[[migrations]]` list in `wrangler.toml` to be **append-only**: once a tag has been deployed, removing it on a subsequent compile causes the next deploy to fail with `Cannot apply <new|deleted|renamed|transferred>-class migration to class <X>` — CF replays the full migrations log on every push and notices the tag is gone.
740
+ ## v0.14.2 — May 7, 2026
449
741
 
450
- Pre-fix, the compiler regenerated the `[[migrations]]` blocks from scratch on every compile, emitting only entries for the *current* `durableObjects` bindings. Any historical lifecycle events the user had hand-maintained — `deleted_classes`, `renamed_classes`, `transferred_classes` — were silently dropped and the deploy then broke. AttendVIP hit this first: a `qb-do-deleted-legacy-notes-2026-05-05` deletion entry got dropped, and the next deploy tried to re-apply `qb-do-Notepad`'s `new_sqlite_classes` against the existing class.
742
+ ### Historical DO `[[migrations]]` are preserved
451
743
 
452
- The fix adds a new config slot — `bindings.durableObjectMigrations` — for historical entries that survive recompiles. Declared entries are emitted FIRST in the generated `wrangler.toml`'s migrations list (preserving chronological order), then the auto-generated current-class creation entries follow, deduplicated by tag so an explicit user entry wins over the auto-emit.
744
+ A new `bindings.durableObjectMigrations` config slot carries forward `deleted_classes`, `renamed_classes`, and `transferred_classes` lifecycle entries across recompiles. Cloudflare's migration list is append-only; entries declared here are emitted first in `wrangler.toml`, then auto-generated current-class entries follow:
453
745
 
454
746
  ```ts
455
- // quickback.config.ts
456
747
  bindings: {
457
- durableObjects: [
458
- { name: 'NOTEPAD', className: 'Notepad', from: 'lib/Notepad' },
459
- ],
748
+ durableObjects: [{ name: 'NOTEPAD', className: 'Notepad', from: 'lib/Notepad' }],
460
749
  durableObjectMigrations: [
461
- // Carry forward across recompiles — Cloudflare's migration list is append-only.
462
- {
463
- tag: 'qb-do-deleted-legacy-notes-2026-05-05',
464
- deletedClasses: ['LegacyNotes'],
465
- },
750
+ { tag: 'qb-do-deleted-legacy-notes-2026-05-05', deletedClasses: ['LegacyNotes'] },
466
751
  ],
467
752
  }
468
753
  ```
469
754
 
470
- All four lifecycle shapes are supported: `newClasses` / `newSqliteClasses` (creations), `deletedClasses` (removals), `renamedClasses` (`{ from, to }` inline-table-array), `transferredClasses` (`{ from, from_script, to }` for moves between workers). The user-declared entry can also override the auto-emit by reusing the same tag — useful when a DO started life as KV-backed before SQLite-DOs existed.
471
-
472
- This is a config-side fix, not a wrangler.toml-merging one — Quickback doesn't read your existing `wrangler.toml`. The discipline is the same as for any append-only log: declare lifecycle events as you make them. Auto-detection of removed classes from the schema diff is on the roadmap; for now the compiler trusts your declaration.
473
-
474
- 7 new tests covering deletion, rename, transfer, multi-entry ordering, override-via-same-tag, no-history bit-identical output, and the historical-only-no-current-DOs edge case.
755
+ All four lifecycle shapes are supported. User-declared entries can override auto-emit by reusing the same tag.
475
756
 
476
757
  ---
477
758
 
478
759
  ## v0.14.1 — May 7, 2026
479
760
 
480
- ### Bulk action variants now appear in `openapi.json`
481
-
482
- Record-based actions with `bulkVariant: true` (introduced in v0.14.0) generate a working `POST /<base>/batch/<actionName>` route at runtime, but the OpenAPI generator wasn't aware of them — so the bulk endpoints were invisible to typed-client codegen (`api-types.gen.ts`) and to MCP-driven agents discovering operations from the spec. AttendVIP's v0.14.0 rollout (seven actions with `bulkVariant: true`: `approve`, `checkIn`, `checkOut`, `setVisibility`, `cancelInvite`, `sendInvite`, `sessionApprove`) found this within hours of shipping.
761
+ ### Bulk action variants in `openapi.json`
483
762
 
484
- The OpenAPI generator now emits each bulk variant as a sibling operation to its per-record action, with the documented request shape (`{ ids: string[], input, failFast? }`), correct 200 / 207 / 400 responses, an `x-bulk-variant: true` marker, and a separate `<resource><Action>Bulk` `operationId` so client codegen can distinguish single from bulk. The fix also threads `bulkVariant` through `getAllActions` so any other downstream consumer of the action registry sees the flag — previously the parser captured it but the spec-emit path silently dropped it.
763
+ Record-based actions with `bulkVariant: true` are now emitted as sibling operations in the OpenAPI spec, with the documented `{ ids, input, failFast? }` request shape, 200/207/400 responses, and a separate `<Resource><Action>Bulk` `operationId` so typed-client codegen distinguishes single from bulk.
485
764
 
486
- No changes required in user code. Re-running `quickback compile` regenerates `openapi.json` with both routes per `bulkVariant: true` action; downstream `api-types.gen.ts` builds pick up the new operations on the next codegen run.
765
+ ### Cross-tenant "my events" patterns
487
766
 
488
- ### Cross-tenant "my events" pattern documented with a worked example
489
-
490
- The v0.14.0 docs noted that relationship-roles do **not** solve cross-tenant aggregation ("a guest's view of events across all tenants they were invited to") and pointed at function-form access as the workaround, but didn't show what that looked like in practice. The access docs now carry a full standalone-action example for `GET /my-events` — the canonical attendee-dashboard pattern — including the two security guardrails (always filter by `ctx.userId`; the action takes responsibility for soft-delete and other invariants the firewall would otherwise apply). Standalone actions are already mandatorily audit-logged in the runtime, so the cross-tenant traversal is recorded automatically.
491
-
492
- See [Access → Cross-tenant "my events" dashboards](/compiler/definitions/access#cross-tenant-my-events-dashboards-are-not-this).
767
+ The access docs now include a worked example for the cross-tenant aggregation pattern (e.g. `GET /my-events` returning resources across all tenants a caller is invited to). See [Access → Cross-tenant dashboards](/compiler/definitions/access#cross-tenant-my-events-dashboards-are-not-this).
493
768
 
494
769
  ---
495
770
 
496
771
  ## v0.14.0 — May 7, 2026
497
772
 
498
- ### Relationship-based authorization roles
499
-
500
- Quickback's role system now supports a third kind of role beyond Better Auth org membership and the four pseudo-roles (`PUBLIC`/`AUTHENTICATED`/`USER`/`ADMIN`): **relationship-roles** that bind to a domain-table membership ("user is a confirmed guest of this event") rather than an org/admin gate. The original ask was a B2B event-management app where logged-in users who aren't team members but ARE confirmed guests of an event need to see that event's sessions, pages, and tracks — same data, different access lane. The old workarounds (function-form access, hand-written actions, `firewall: { exception: true }`) all gave up some combination of OpenAPI/MCP visibility, CRUD code generation, or tenant safety.
773
+ ### Relationship-based authorization
501
774
 
502
- Declare the relationship once in `quickback.config.ts`, then reference it from `firewall:` or `access.roles:`:
775
+ Roles can now be bound to a domain-table membership ("user is a confirmed guest of this event") rather than an org membership or a pseudo-role. Declare the relationship once and reference it from `firewall:` or `access.roles:`:
503
776
 
504
777
  ```ts
505
- // quickback.config.ts
506
778
  authz: {
507
779
  relationships: {
508
780
  guestOf: {
509
- from: 'event_guests', // relationship table
510
- subject: { column: 'userId', equals: 'ctx.userId' }, // caller side
511
- resource: { column: 'eventId' }, // resource side
512
- where: { status: 'confirmed' }, // optional row filter
781
+ from: 'event_guests',
782
+ subject: { column: 'userId', equals: 'ctx.userId' },
783
+ resource: { column: 'eventId' },
784
+ where: { status: 'confirmed' },
513
785
  },
514
786
  },
515
787
  roles: {
516
788
  guest: { via: 'guestOf' },
517
- eventStaff: {
518
- or: [{ via: 'guestOf' }, { roles: ['admin', 'owner'] }],
519
- },
789
+ eventStaff: { or: [{ via: 'guestOf' }, { roles: ['admin', 'owner'] }] },
520
790
  },
521
791
  }
522
792
 
523
793
  // features/sessions/sessions.ts
524
794
  firewall: [
525
795
  { field: 'organizationId', equals: 'ctx.activeOrgId' },
526
- { field: 'eventId', via: 'guestOf' }, // ← row scoping
796
+ { field: 'eventId', via: 'guestOf' },
527
797
  ],
528
- read: { access: { roles: ['admin', 'member', 'guest'] } }, // ← OR-composed
529
- crud: {
530
- create: { access: { roles: ['admin', 'guest'] } }, // inline async lookup
531
- update: { access: { roles: ['admin'] } },
532
- }
798
+ read: { access: { roles: ['admin', 'member', 'guest'] } },
799
+ create: { access: { roles: ['admin', 'guest'] } },
800
+ update: { access: { roles: ['admin'] } },
533
801
  ```
534
802
 
535
- The compiler emits an inline Drizzle subquery against the relationship table and AND-composes it as the outermost firewall clause. The relationship table's own `buildFirewallConditions(ctx)` is called inside the subquery so soft-delete and tenant scope on the relationship row are always honored — soft-deleting an `event_guests` row revokes access immediately. Anonymous callers fail closed (the subquery short-circuits to `WHERE 1 = 0` when `ctx.userId` is null). Cross-tenant grants are impossible because the resource's tenant filter sits as the outermost AND, never folded into a role OR. See [Firewall → Relationship-based scoping](/compiler/definitions/firewall#relationship-based-scoping-via) and [Access → Relationship-based authorization](/compiler/definitions/access#relationship-based-authorization).
536
-
537
- What works in v0.14.0:
538
-
539
- | Surface | Status |
540
- |---|---|
541
- | `firewall: [{ field, via }]` row-level scoping | Full |
542
- | `crud.<op>.access` `roles: ['guest']` (inline emission) | Full |
543
- | `read.access` and `read.views.*.access` | Full |
544
- | `masking.<f>.show` `roles: ['guest']` | Compile-refused (workaround pointer) |
545
- | `actions.<n>.access` `roles: ['guest']` | Compile-refused (workaround pointer) |
546
-
547
- The runtime evaluator fails closed on relationship arms regardless of which surface you hit, so silent grants are impossible everywhere. The two refused surfaces have clear compile-time errors pointing to the working pattern (gate the row at the firewall layer with `via:`, gate the role at the access layer with BA roles).
803
+ The compiler emits an inline Drizzle subquery against the relationship table and AND-composes it as the outermost firewall clause. The relationship table's own firewall (tenant scope, soft-delete) is honored inside the subquery; cross-tenant grants are impossible because the resource's tenant filter sits outermost.
548
804
 
549
- Compile-time refusals also catch: unknown `via:` reference, cycles in role composition (`a → b → a`), reserved role-name shadowing (auth-provider-derived only — `guest`/`speaker`/`attendee` are free; `admin`/`owner`/`member` are reserved when the BA org plugin is on), unknown relationship `from` table, resource missing the `resource.column`, relationship table with `firewall: { exception: true }` (would let cross-tenant grants slip through), `lowering: 'session'` (reserved for v2 — staleness/invalidation ergonomics not yet shipped), and `+` hierarchy on relationship-roles (terminal, like pseudo-roles).
805
+ Supported surfaces: row-level scoping via `firewall: [{ field, via }]`, role gates on writes and reads, view access. Masking and action access reject relationship-roles at compile time with pointers to the working pattern (gate the row at the firewall layer, gate the role at the access layer).
550
806
 
551
- Cross-tenant "my events" dashboards (a logged-in user wants `GET /my-events` returning events they're a guest of *across all tenants*) are **not** solved by relationship-roles — the tenant firewall stays the outermost AND. For that pattern, use a user-scoped firewall (`firewall: { owner: { column: 'userId' } }`) or function-form access on a dedicated route. Documented prominently in [access.mdx](/compiler/definitions/access#cross-tenant-my-events-dashboards-are-not-this) so users don't reach for relationship-roles first and get confused.
807
+ Cross-tenant aggregation dashboards aren't solved by relationship-roles — the tenant firewall remains the outermost AND. For that pattern, use a user-scoped firewall or function-form access on a dedicated route.
552
808
 
553
- Roadmap: `lowering: 'session'` ergonomics, inline relationship emission for `actions.access` (needs `relationshipBindings` design), async/batched mask functions for `masking.show`. The schema slots are reserved so v2 lands non-breaking.
809
+ See [Firewall → Relationship-based scoping](/compiler/definitions/firewall#relationship-based-scoping-via) and [Access → Relationship-based authorization](/compiler/definitions/access#relationship-based-authorization).
554
810
 
555
- ### Bulk variants of record-based actions
811
+ ### Bulk variants on record-based actions
556
812
 
557
- Record-based actions can now opt into an auto-generated bulk route alongside the per-record route. Set `bulkVariant: true` on a `defineAction({...})` and the compiler emits `POST /:resource/batch/{action}` that loops the same access + transition + execute pipeline over a `{ ids: [...], input, failFast? }` body. The original ask was an event-management UX where every domain bulk operation (approve N guests, rescind N invites, advance N applications) became a hand-written standalone action that re-implemented a per-record action's transition + execute logic in a `for` loop — `PATCH /:resource/batch` couldn't do it because state lives on a protected field, which is the right call for safety.
813
+ `defineAction({ bulkVariant: true })` emits `POST /:resource/batch/{action}` alongside the per-record route. The bulk handler loops the same access + transition + execute pipeline over a `{ ids, input, failFast? }` body:
558
814
 
559
815
  ```ts
560
- // features/applications/actions/advance.ts
561
816
  export default defineAction({
562
817
  description: "Move an application forward in the pipeline.",
563
818
  input: z.object({ nextStatus: z.enum(["screening", "interview", "offer"]) }),
564
819
  access: { roles: ["owner", "admin"] },
565
- bulkVariant: true, // ← opt-in
820
+ bulkVariant: true,
566
821
  transition: { field: "status", via: "nextStatus", fromTo: { /* ... */ } },
567
822
  async execute({ db, record, input, whereTransition }) {
568
- // exact same body as before — runs once per id
823
+ // exact same body — runs once per id
569
824
  },
570
825
  });
571
826
  ```
572
827
 
573
- Per-record outcomes return as 207 Multi-Status with the same `{ success, errors, meta }` shape as `PATCH /batch`. Each id flows through the firewall fetch, the per-record `evaluateAccessReason` split (403 role / 409 record-precondition), the transition pre-check, and the same `whereTransition` factory the single-record route uses — so a stale-state record fails for that id alone, not the whole batch. `failFast: true` aborts on the first failure and (on Postgres / Supabase / Neon / libsql / sqlite drivers) wraps the loop in `db.transaction()` so prior writes roll back; D1 is documented as fail-fast-without-rollback because it has no `db.transaction`.
574
-
575
- Compile-time refusals: `bulkVariant: true` is rejected on standalone actions (no record context to loop over) and on actions that declare `unsafe` (cross-tenant per-record audit not yet wired). Method is forced to POST regardless of the action's `method` setting — the one-row-to-many-rows asymmetry makes inheriting GET/DELETE confusing. Max batch size is 100 ids per request, mirroring the CRUD batch endpoints. See [Actions → Bulk variant](/compiler/definitions/actions#bulk-variant).
828
+ Per-record outcomes return as 207 Multi-Status. `failFast: true` aborts on the first failure and wraps the loop in `db.transaction()` on tx-supporting providers; D1 fails fast without rollback. Max 100 IDs per request. Rejected on standalone actions and `unsafe` actions.
576
829
 
577
830
  ### Aggregations on read views
578
831
 
579
- Read views can now declare pre-computed metrics that surface on the response next to the row payload, without a custom standalone action. Every dashboard tile that previously turned into a standalone action just for "count of X grouped by Y" now lives in the same view config that drives the rows.
832
+ Read views can declare pre-computed metrics that surface alongside the row payload:
580
833
 
581
834
  ```ts
582
835
  read: {
@@ -592,51 +845,29 @@ read: {
592
845
  }
593
846
  ```
594
847
 
595
- Response carries `aggregations: { ... }` alongside `data`:
596
-
597
- ```json
598
- {
599
- "data": [/* paginated rows */],
600
- "view": "pipeline",
601
- "pagination": { "count": 50, "page": 1, "pageSize": 50, "hasMore": true },
602
- "aggregations": {
603
- "totalApplications": 173,
604
- "byStatus": { "applied": 102, "screening": 41, "interview": 18, "offer": 7, "rejected": 5 }
605
- }
606
- }
607
- ```
608
-
609
- Aggregations always run over the **same firewalled, filtered set** as the row query — pagination is intentionally ignored, so `?status=applied&limit=10` returns the 10 paged rows AND the count over every applied row. Supported `fn`s: `sum`, `avg`, `min`, `max`, `count` (with or without `field` — `COUNT(*)` vs `COUNT(field)`), `count_distinct`, and `groupBy` (returns `{ value: count }`, NULLs bucket as `"(none)"`).
610
-
611
- Compile-time validation: `field` must reference a real column; `sum`/`avg` require numeric column types; the same masking opt-out gate that governs `query.{filterable, sortable, searchable}` applies to aggregations (a `sum(salary)` leaks structure even when the row payload is redacted); aggregation names cannot collide with the reserved response fields `data`, `pagination`, `view`. No raw SQL `expr:` form in v1 — column references only. See [Views → Aggregations](/compiler/definitions/views#aggregations).
848
+ Aggregations run over the same firewalled, filtered set as the row query; pagination is intentionally ignored. Supported functions: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `groupBy`. See [Views → Aggregations](/compiler/definitions/views#aggregations).
612
849
 
613
850
  ---
614
851
 
615
852
  ## v0.13.5 — May 6, 2026
616
853
 
617
- ### Object-form `auth.plugins` no longer crashes the compiler
618
-
619
- The documented object form for per-plugin config — `plugins: { oauthProvider: {...} }`, `plugins: { organization: { teams: { enabled: true } } }`, etc. (see [Better Auth Plugins → Custom configuration](/stack/auth/plugins#oauth-provider-mcp-ready)) — was rejected by the compiler with `plugins.includes is not a function`. `hasCliAuthRoutes` called `.includes()` directly on `auth.config.plugins` to detect `deviceAuthorization`, and `generateAuthFiles` flattened plugins to a string array before handing them to the better-auth generator, silently dropping every per-plugin user option on the way through.
854
+ ### Object-form `auth.plugins` config is honored
620
855
 
621
- Both paths now run through a shared resolver that preserves the user's input format (object in → object out, array in → array out) and only adds the compiler's auto-included plugins (`organization`, `admin`, `apiKey`, plus `bearer` when `deviceAuthorization` is present) as `true` entries that don't clobber user config. Per-plugin options like `oauthProvider: { scopes: [...] }`, `organization: { teams: { enabled: true } }`, and `deviceAuthorization: { verificationUri: '...' }` now reach the generated `auth.ts` as written.
856
+ The documented `plugins: { oauthProvider: {...} }`, `plugins: { organization: { teams: { enabled: true } } }` shapes now flow through the compiler unchanged. Per-plugin options reach the generated `auth.ts` as written.
622
857
 
623
- Better Auth's `ac` / `roles` access-control objects (the result of `createAccessControl(...)`) still require a custom `auth.ts` override — they're live runtime values that can't survive the JSON config trip from CLI → compiler. A declarative escape hatch for that is on the roadmap.
858
+ ### `roles: ["PUBLIC"]` allowed on writes and actions
624
859
 
625
- ### `roles: ["PUBLIC"]` is allowed on writes and actions again
860
+ `PUBLIC` is the explicit, uppercase opt-in for unauthenticated access on every access node — reads, writes, views, and actions. The runtime trusts the marker; row-level safety comes from firewall, masking, and the action's own validation. `PUBLIC` actions continue to receive mandatory audit logging.
626
861
 
627
- v0.10.17 added a compile-time block that rejected `roles: ["PUBLIC"]` on `crud.create` / `crud.update` / `crud.delete` and on every action. The intent — "anonymous mutations are usually a misconfiguration" — collided with the legitimate use cases the rest of Quickback was built around: Gmail one-click RSVP confirms, public RSVP forms, magic-link redemption, List-Unsubscribe-Post handlers, webhook ingest, captcha-gated contact forms. None of those carry a session, so `AUTHENTICATED` 401s the caller before the handler can validate its own token, and the suggested escape hatch ("custom action that does its own auth + `firewall: { exception: true }`") was itself blocked by the same validator.
628
-
629
- The block is removed. `PUBLIC` is the explicit, uppercase opt-in for unauthenticated access on every access node — reads, CRUD writes, views, and actions. The compiler trusts the marker; row-level safety comes from firewall, masking, and the action's own token validation. `PUBLIC` actions continue to receive **mandatory audit logging** (IP, input, result, timing) in the runtime regardless. `crud.create`/`update`/`delete` typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
630
-
631
- `USER` and `ADMIN` keep their compile-time prerequisites (firewall must scope by `userId` / admin plugin must be enabled).
862
+ Common pattern: pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
632
863
 
633
864
  ---
634
865
 
635
866
  ## v0.12.0 — May 5, 2026
636
867
 
637
- ### Per-room authorization for PartyServer rooms
868
+ ### Per-room authorization for PartyServer
638
869
 
639
- `bindings.durableObjects[].access` lets the compiler emit a path-scoped gate that runs the declared resource's existing firewall + `read.access` pipeline before the WebSocket upgrade — same pillars `GET /api/v1/<resource>/:id` enforces, zero hand-written auth code.
870
+ `bindings.durableObjects[].access` declares a path-scoped gate that runs the declared resource's firewall and `read.access` pipeline before the WebSocket upgrade:
640
871
 
641
872
  ```ts
642
873
  durableObjects: [
@@ -655,119 +886,70 @@ durableObjects: [
655
886
  },
656
887
  } },
657
888
 
658
- // Anonymous game lobbies / public pads: explicit opt-out.
889
+ // Anonymous lobbies / public pads: explicit opt-out.
659
890
  { name: 'PublicLobby', className: 'PublicLobby', from: 'lib/PublicLobby',
660
891
  access: 'public' },
661
- ],
892
+ ]
662
893
  ```
663
894
 
664
- The gate 401s unauthenticated callers, 403s when the firewall hides the row, 404s when the row is missing, and lets the upgrade proceed otherwise. DOs without an `access` declaration keep the v0.11.1 catchall (just `ctx.authenticated`). Resource references are validated against feature names at compile time so typos break the build, not the first WebSocket upgrade. See [PartyServer Rooms → Per-room authorization via access](/stack/realtime/partyserver-rooms#per-room-authorization-via-access-v012).
895
+ The gate 401s unauthenticated callers, 403s when the firewall hides the row, 404s when the row is missing. Resource references are validated against feature names at compile time. See [PartyServer Rooms → Per-room authorization](/stack/realtime/partyserver-rooms#per-room-authorization-via-access-v012).
665
896
 
666
897
  ---
667
898
 
668
899
  ## v0.11.1 — May 5, 2026
669
900
 
670
- ### PartyServer auto-mount is now secure by default
671
-
672
- The `/realtime/*` auto-mount shipped in v0.11.0 didn't gate WebSocket upgrades — anyone who knew a room ID (CUID2, hard to guess but not a security boundary) could open a connection. `authMiddleware` populated the request context but `partyserverMiddleware` doesn't 401 anonymous upgrades on its own.
673
-
674
- The auto-mount now wraps `partyserverMiddleware` in an auth check: `401 Unauthorized` if the caller has no resolved auth context, otherwise the upgrade proceeds. The four auth mechanisms the rest of the worker honors (session cookie, JWT bearer, `x-api-key` header, `?api_key=` / `?key=` query) all unlock connections automatically.
675
-
676
- Per-room access (e.g., "is this user a member of the org that owns this room?") is still your `Server` class's responsibility in `onConnect` — the auto-mount only enforces "are you authenticated at all." Hand-written mounts with custom `onBeforeConnect` continue to work unchanged; declare them at `/realtime/*` before the auto-mount runs to opt out of the default gate.
901
+ ### PartyServer auto-mount is secure by default
677
902
 
678
- No code changes required — `quickback compile` regenerates the gated mount automatically. Single-tenant alphas weren't exploitable in practice (room IDs aren't logged or surfaced); multi-tenant projects should redeploy to pick this up.
903
+ The `/realtime/*` auto-mount now wraps `partyserverMiddleware` in an auth check. Unauthenticated upgrades return 401; the four auth mechanisms (session cookie, JWT bearer, `x-api-key` header, query parameter) all unlock connections. Per-room access remains the `Server` class's responsibility in `onConnect`.
679
904
 
680
905
  ---
681
906
 
682
907
  ## v0.11.0 — May 5, 2026
683
908
 
684
- ### OAuth Provider plugin (MCP-ready)
909
+ ### OAuth Provider (MCP-ready)
685
910
 
686
- Quickback can now act as a standards-compliant OAuth 2.1 + OIDC authorization server via [`@better-auth/oauth-provider`](https://better-auth.com/docs/plugins/oauth-provider). Enable it with `plugins: ["oauthProvider"]` in your auth config — the compiler auto-includes Better Auth's `jwt` plugin (the OAuth provider delegates access-token signing to it) and the Account SPA gains a `/consent` page for the standard authorization-code flow.
911
+ Quickback can act as a standards-compliant OAuth 2.1 + OIDC authorization server via [`@better-auth/oauth-provider`](https://better-auth.com/docs/plugins/oauth-provider). Enable with `plugins: ["oauthProvider"]`. The compiler auto-includes Better Auth's `jwt` plugin and the Account SPA gains a `/consent` page for the standard authorization-code flow.
687
912
 
688
- This replaces Better Auth's deprecated `mcp` plugin and gives every future MCP client (Cursor, Claude Desktop, claude.ai connectors, custom tooling) RFC 7591 dynamic client registration + the well-known discovery documents they need to bootstrap themselves. See [Auth Plugins → OAuth Provider](/stack/auth/plugins#oauth-provider-mcp-ready).
913
+ This replaces Better Auth's deprecated `mcp` plugin and gives every MCP client (Cursor, Claude Desktop, claude.ai connectors, custom tooling) RFC 7591 dynamic client registration plus the discovery documents they need to bootstrap. See [Auth Plugins → OAuth Provider](/stack/auth/plugins#oauth-provider-mcp-ready).
689
914
 
690
- ### API key auth via query parameter
915
+ ### API keys via query parameter
691
916
 
692
- The auth middleware now accepts API keys as `?api_key=...` or `?key=...` query parameters in addition to the `x-api-key` header. The header takes precedence when both are sent. This unblocks clients that can't inject custom headers — most notably claude.ai's MCP connector, which previously returned zero tools because every list/call attempt was unauthenticated.
917
+ The auth middleware now accepts API keys as `?api_key=…` or `?key=…` query parameters. The `x-api-key` header takes precedence when both are sent. Prefer the header whenever the client supports it — query parameters land in access logs and `Referer` headers.
693
918
 
694
- The query-param form lands in access logs and `Referer` headers; prefer the header whenever the client supports it. See [Auth Plugins → API Keys](/stack/auth/plugins#api-keys).
919
+ ### PartyServer rooms + realtime URL split
695
920
 
696
- ### PartyServer rooms + realtime URL split (breaking)
921
+ The realtime URL space is reorganized so names match what each primitive does:
697
922
 
698
- The realtime URL space is reorganized so the names match what each primitive does:
923
+ - **`/realtime/v1/*` → `/broadcast/v1/*`** — the org-wide Broadcaster moves to its semantically accurate prefix.
924
+ - **`/realtime/<binding>/<room-id>`** — new mount for [PartyServer](/stack/realtime/partyserver-rooms) rooms. Per-room Durable Objects with presence and lifecycle hooks. Auto-mounted whenever a project declares any in-worker DO.
699
925
 
700
- - **`/realtime/v1/*` → `/broadcast/v1/*`** — the existing org-wide Broadcaster (Postgres-changes fan-out, ws-ticket auth) moves to its semantically accurate prefix. Same code, same behavior, just a different mount point.
701
- - **`/realtime/<binding>/<room-id>` is the new mount for [PartyServer](/stack/realtime/partyserver-rooms) rooms** — bidirectional, per-room (per-document) Durable Objects with presence and lifecycle hooks. Auto-mounted via `hono-party` whenever a project declares any in-worker DO via `bindings.durableObjects[].from`. Use these for collaborative editing, live cursors, and per-room state.
926
+ **Breaking** — recompile + redeploy required:
702
927
 
703
- **Breaking changes** — recompile + redeploy required:
928
+ - `REALTIME_URL` env var renamed to `BROADCAST_URL`.
929
+ - SPA helpers `getRealtimeWsUrl()` / `getRealtimeTicketUrl()` renamed to `getBroadcastWsUrl()` / `getBroadcastTicketUrl()`.
930
+ - `appConfig.routes.api.realtime` renamed to `appConfig.routes.api.broadcast`.
704
931
 
705
- - The `REALTIME_URL` runtime env var is renamed to `BROADCAST_URL` (used by the org member-update broadcast hook in separate-mode realtime). If you set this via `wrangler secret put REALTIME_URL`, re-set it as `BROADCAST_URL`.
706
- - The auth-ui SPA helpers `getRealtimeWsUrl()` / `getRealtimeTicketUrl()` are renamed to `getBroadcastWsUrl()` / `getBroadcastTicketUrl()`. The `appConfig.routes.api.realtime` field is renamed to `appConfig.routes.api.broadcast`.
707
- - WebSocket subscribers that hardcoded `/realtime/v1/websocket` or `/realtime/v1/ws-ticket` need to be updated to `/broadcast/v1/...`. The bundled CMS and Account SPAs handle this automatically; custom clients need a one-line change.
708
-
709
- **Pre-installed deps in the compiler image:** `partyserver`, `partysocket`, and `hono-party` are now cached in `/deps/node_modules` so opt-in collab projects compile without an extra `npm install` step. `Y-PartyServer` (Yjs CRDT support) stays opt-in.
710
-
711
- **Recipe:** see the new [PartyServer Rooms](/stack/realtime/partyserver-rooms) doc page and the `examples/recruitment` interview-room demo for an end-to-end example with presence and live notes.
932
+ `partyserver`, `partysocket`, and `hono-party` are pre-installed in the compiler image; collab projects compile without an extra `npm install` step.
712
933
 
713
934
  ---
714
935
 
715
936
  ## v0.10.20 — May 4, 2026
716
937
 
717
- ### In-worker Durable Objects via `bindings.durableObjects[].from`
938
+ ### In-worker Durable Objects
718
939
 
719
- `bindings.durableObjects` previously only emitted the binding declaration — useful for cross-worker DOs (`scriptName: "other-worker"`), but not enough for app-owned classes that live in this worker's source. Authors had to hand-edit `src/index.ts` (to add `export { ItemStream } from './...'`) and `wrangler.toml` (to add the `[[migrations]]` block) on every compile.
720
-
721
- Adding `from` flips the entry into in-worker mode and the compiler does both:
940
+ `bindings.durableObjects[].from` flips a DO binding into in-worker mode and emits the export, the `[[migrations]]` block, and the `CloudflareBindings` type all together:
722
941
 
723
942
  ```ts
724
- durableObjects: [
725
- {
726
- name: "ITEM_STREAM",
727
- className: "ItemStream",
728
- from: "features/loops/lib/ItemStream", // module path under src/
729
- },
730
- ]
731
- ```
732
-
733
- Generates:
734
- - `src/index.ts`: `export { ItemStream } from './features/loops/lib/ItemStream';` — wrangler resolves the binding by class export.
735
- - `wrangler.toml`: a `[[migrations]]` block with `tag = "qb-do-ItemStream"` and `new_sqlite_classes = ["ItemStream"]`.
736
- - `CloudflareBindings`: `ITEM_STREAM: DurableObjectNamespace` so `c.env.ITEM_STREAM.idFromName(...)` typechecks.
737
-
738
- Where the class file lives: in-worker DO classes go under `quickback/lib/` or `quickback/features/<feature>/lib/` — both copy verbatim into the generated `src/` tree on every compile (the rest of `src/` is wiped). The `from` value is the resulting `src/`-relative path with no `./` prefix and no `.ts` suffix.
739
-
740
- `from` and `scriptName` are mutually exclusive — the compiler rejects entries that set both. Cross-worker entries (`scriptName` set) skip the re-export and the migration block; the exporting worker owns its own migration table.
741
-
742
- `migrationTag` (default `qb-do-${className}`) is stable across regenerations and **must never be removed or renamed once deployed** — wrangler tracks applied tags and will reject deploys that try to walk them back. `useSqlite` defaults to `true`; set to `false` for legacy KV-backed DOs.
743
-
744
- See [Bindings → Durable Objects](/compiler/config/bindings#durableobjects) for the full reference.
745
-
746
- ---
747
-
748
- ## v0.10.19 — May 4, 2026
749
-
750
- ### Fix: bundled-SPA auth survives `wrangler dev` on custom_domain projects
751
-
752
- `wrangler dev` rewrites the configured `custom_domain` host in **every** response header value (Location, Content-Security-Policy, X-…) to the local hostname, with a case-sensitive substring matcher. That mangles the CSP `connect-src` for projects with `domain: "api.example.com"` + bundled CMS / Account SPAs:
753
-
943
+ durableObjects: [{
944
+ name: "ITEM_STREAM",
945
+ className: "ItemStream",
946
+ from: "features/loops/lib/ItemStream",
947
+ }]
754
948
  ```
755
- # Compiled (correct)
756
- connect-src 'self' https://api.example.com …
757
-
758
- # Served by wrangler dev (mangled)
759
- connect-src 'self' https://localhost:8787 …
760
- ```
761
-
762
- Result: the bundled SPA's hardcoded `VITE_QUICKBACK_API_URL` fetches get blocked in dev because the CSP only allows localhost. Reported by Loop on the 0.10.18 thread; verified end-to-end with a minimal `wrangler@4.85.0 dev --local` repro.
763
-
764
- The compiler now emits the SPA-baked-origin literal in `connect-src` with the host's first letter capitalised (`https://Api.example.com`). CSP host-source matching is ASCII case-insensitive per CSP3, so browsers accept it for connections to `https://api.example.com`; wrangler's case-sensitive matcher misses it. The case-shift is applied at compile time and only to URLs whose host matches the configured `custom_domain` — other origins (localhost, third-party hosts) are unchanged.
765
949
 
766
- `TRUSTED_ORIGINS` keeps its lowercase prod entries: it's consumed by the CORS `isTrustedOrigin` check via `Array.includes()` against the browser-supplied Origin header (always lowercase). The CSP fix only needs to land on the SPA-baked literal — that's the entry the SPA's hardcoded fetch needs covered.
950
+ DO class files live under `quickback/lib/` or `quickback/features/<feature>/lib/` — both copy verbatim into the generated `src/` tree on every compile. `from` and `scriptName` are mutually exclusive; cross-worker DOs (`scriptName` set) skip the re-export and migration block.
767
951
 
768
- If wrangler ships a fix for the response-header rewrite, the case-shifted source remains a valid CSP entry that browsers match identically — no follow-up needed in user code.
769
-
770
- **Action required:** none. Recompile (`quickback compile`) to pick up the fix.
952
+ `migrationTag` (default `qb-do-${className}`) is stable across regenerations and must never be removed or renamed once deployed. `useSqlite` defaults to `true`. See [Bindings → Durable Objects](/compiler/config/bindings#durableobjects).
771
953
 
772
954
  ---
773
955
 
@@ -775,93 +957,45 @@ If wrangler ships a fix for the response-header rewrite, the case-shifted source
775
957
 
776
958
  ### `experimentalRemote` — share deployed D1 with `wrangler dev`
777
959
 
778
- Per-binding `experimental_remote = true` flag emitted into the generated `wrangler.toml`. Useful for "share prod auth in dev, keep feature writes sandboxed":
960
+ Per-binding `experimental_remote = true` lets `wrangler dev` read/write deployed D1 for selected bindings:
779
961
 
780
962
  ```ts
781
963
  providers: {
782
964
  database: defineDatabase("cloudflare-d1", {
783
965
  splitDatabases: true,
784
- experimentalRemote: {
785
- auth: true, // wrangler dev reads/writes deployed AUTH_DB
786
- features: false, // (default) features stays local
787
- audit: false,
788
- webhooks: false,
789
- files: false,
790
- },
966
+ experimentalRemote: { auth: true, features: false },
791
967
  }),
792
968
  }
793
969
  ```
794
970
 
795
- Keys are logical binding names — `auth` flips the flag on the `AUTH_DB` binding, `features` flips it on `DB` (or the legacy single-DB binding), `audit` / `webhooks` / `files` follow the same pattern. Off by default; only enable for databases you intend to share.
971
+ Useful for "share prod auth in dev, keep feature writes sandboxed." Off by default.
796
972
 
797
973
  ### Google OAuth + signup ToS
798
974
 
799
- The Account SPA now wires Google OAuth end-to-end when `auth.providers.auth.config.socialProviders.google.enabled: true`. The compiler bakes the right `VITE_ENABLE_GOOGLE_OAUTH` flag into the SPA's `.env` so the social-login button renders only when the provider is enabled — no more dead buttons.
800
-
801
- Signup flow gains a Terms-of-Service checkbox gate (configurable via the Account SPA's branding config).
802
-
803
- ### CLI compile auth gate + device-auth redirect fix
804
-
805
- - `quickback compile` now requires authentication for cloud-compiler runs (closes the unauth public-compile path).
806
- - The device-flow `/cli/authorize` page was sending `?returnTo=` to login, but `signup.tsx` and the `_authenticated` middleware only read `?redirect=` — so a user who clicked "Create one" from `/login` lost the return URL. Standardized on `?redirect=` everywhere.
807
-
808
- ### Skill restructure (Claude Code skill)
809
-
810
- The bundled Claude Code skill was reorganized for clarity:
811
-
812
- - `SKILL.md` is now a thin orientation pointer, not a 600-line dump
813
- - Reference docs split into `Compiler` and `Stack` sections
814
- - Docs bundled as **files** the model navigates with `Read` / `Glob` rather than via `quickback docs <topic>` shell calls — same content, fewer tool calls per lookup
815
- - Tightened against audit gaps surfaced by red-team review
816
-
817
- Run `quickback claude install` to pick up the new skill layout.
818
-
819
- ---
820
-
821
- ## v0.10.17 — May 2, 2026
822
-
823
- ### Security fix: CSP auto-config no longer widens `default-src`
824
-
825
- When 0.10.15's auto-config was asked to add a value to a directive the user hadn't declared (e.g. `https://fonts.googleapis.com` → `style-src` when only `default-src` was set), it incorrectly pushed the value into `default-src` itself. Because CSP3 fall-back semantics make `default-src` the fallback for `script-src`, `img-src`, `media-src`, and others, this widened the attack surface to every directive that fell back to it — a `style-src`-only host became reachable from `script-src`.
826
-
827
- 0.10.17 fixes the logic: missing target directives are now **scaffolded** with the user's `default-src` values as baseline, then extended with the auto-config addition. `default-src` stays clean. The new directive (e.g. `style-src`) covers exactly the styles the SPA needs and nothing else.
975
+ The Account SPA wires Google OAuth end-to-end when configured under `auth.config.socialProviders.google.enabled`. The signup flow gains a Terms-of-Service checkbox gate (configurable via the Account SPA branding).
828
976
 
829
- Before (0.10.16):
830
- ```
831
- default-src 'self' https://fonts.googleapis.com https://fonts.gstatic.com @trustedOrigins https://api.example.com
832
- ```
833
-
834
- After (0.10.17):
835
- ```
836
- default-src 'self'
837
- style-src 'self' 'unsafe-inline' https://fonts.googleapis.com
838
- font-src 'self' https://fonts.gstatic.com
839
- connect-src 'self' @trustedOrigins https://api.example.com
840
- ```
841
-
842
- **Action required:** recompile (`quickback compile`) to regenerate the security middleware with the corrected scaffolding. Configs that already declared each `*-src` directive explicitly were unaffected by the bug — the regression only surfaced when users wrote `defaultSrc: ['@self']` and let auto-config fill in the rest.
977
+ ### CLI compile auth gate
843
978
 
844
- The user-side workaround from 0.10.16 (declaring each directive with `['@self']` to force scaffold) is no longer needed in 0.10.17 — the compiler does the right thing automatically.
979
+ `quickback compile` now requires authentication for cloud-compiler runs. Device-flow `?redirect=` parameters are standardized across the login + signup pages so a user clicking "Create one" no longer loses their return URL.
845
980
 
846
981
  ---
847
982
 
848
- ## v0.10.16 — May 2, 2026
849
-
850
- ### CSP auto-config now covers SPA-baked-in API origins
851
-
852
- When the bundled CMS or Account SPA is enabled, the compiler already inlines the API URL into the SPA bundle as a string literal at build time (`VITE_QUICKBACK_API_URL=https://${unifiedDomain}`). That hardcoded URL is what the SPA actually fetches — regardless of which origin is currently serving the page. CSP `connect-src` must allow it explicitly.
983
+ ## v0.10.15–v0.10.17 — May 2, 2026
853
984
 
854
- 0.10.16's auto-config picks up every domain the compiler already knows about — `config.domain`, the inferred `quickback.{baseDomain}`, `cms.domain`, `account.domain`, the admin domain — and adds `https://${each}` to `connectSrc` whenever a bundled SPA is enabled.
985
+ ### CSP auto-config
855
986
 
856
- The motivating case: running the SPA on `localhost:5173` while it's still baked against `https://quickback.your-app.com`. Pre-0.10.16 the localhost CSP's `'self'` blocked the prod URL; users were patching it manually. Now it just works.
987
+ When `security.csp` is set, the compiler widens directives additively based on the project's enabled features:
857
988
 
858
- ```
859
- [security] auto-added https://quickback.loop.kardoe.com to csp.connectSrc — account: true → bundled Account SPA → SPA bundle hardcodes https://quickback.loop.kardoe.com as VITE_QUICKBACK_API_URL / etc.
860
- ```
989
+ | Trigger | Auto-added | Directive |
990
+ |---|---|---|
991
+ | `cms: true` OR `account: true` | `'unsafe-inline'`, `https://fonts.googleapis.com` | `styleSrc` |
992
+ | `cms: true` OR `account: true` | `https://fonts.gstatic.com` | `fontSrc` |
993
+ | `csp` set (always) | `@trustedOrigins` | `connectSrc` |
994
+ | Bundled SPA enabled | SPA-baked API origin (`config.domain`, `quickback.{baseDomain}`, `cms.domain`, `account.domain`) | `connectSrc` |
861
995
 
862
- `@trustedOrigins` (the CORS allowlist) is unchanged — it still gets added independently. The two cover different things: `@trustedOrigins` permits CORS-allowed sibling subdomains; the new SPA-baked addition permits the exact URL the SPA's compiled bundle hardcodes.
996
+ Anything you already wrote stays — auto-config never removes or overrides. Each applied addition is logged to stderr. Opt out with `security: { cspAutoConfig: false }`.
863
997
 
864
- Combined with 0.10.15's bundled-SPA defaults, most projects can now write the minimal:
998
+ Most projects can write the minimal:
865
999
 
866
1000
  ```ts
867
1001
  security: {
@@ -874,286 +1008,107 @@ security: {
874
1008
  }
875
1009
  ```
876
1010
 
877
- …and the compiler fills in styleSrc font hosts, fontSrc gstatic, connectSrc trusted origins, and connectSrc SPA-baked URLs.
878
-
879
- ---
880
-
881
- ## v0.10.15 — May 2, 2026
882
-
883
- ### CSP auto-config — bundled-SPA origins added automatically
884
-
885
- When `security.csp` is set, the compiler now widens directives **additively** based on the project's enabled features. The four rules:
886
-
887
- | Trigger | Auto-added | Directive |
888
- |---|---|---|
889
- | `cms: true` OR `account: true` | `'unsafe-inline'`, `https://fonts.googleapis.com` | `styleSrc` |
890
- | `cms: true` OR `account: true` | `https://fonts.gstatic.com` | `fontSrc` |
891
- | `csp` set (always) | `@trustedOrigins` | `connectSrc` |
892
-
893
- Anything you already wrote stays — auto-config never removes or overrides. Every applied addition prints to stderr at compile so the magic is visible:
894
-
895
- ```
896
- [security] auto-added 'unsafe-inline' to csp.styleSrc — account: true → bundled Account SPA → inline style attributes from Tailwind / TanStack Router
897
- [security] auto-added @trustedOrigins to csp.connectSrc — CORS-trusted origins must be reachable from XHR/fetch (matches cors() allowlist)
898
- ```
899
-
900
- The recipe in [the security docs](/compiler/config/security#example-paste-in-csp-for-a-quickback-spa-project) becomes ~5 lines shorter — most projects no longer need to list `fonts.googleapis.com` / `fonts.gstatic.com` / `@trustedOrigins` themselves. **Loop's CSP shrinks dramatically** after recompiling against this version.
901
-
902
- **Opt-out:** `security: { cspAutoConfig: false, csp: { ... } }` for projects fronted by a CDN that injects its own CSP, or teams that want strict from-scratch control.
903
-
904
- **Smart fallback:** if you set `defaultSrc` but omit the target directive (e.g. `defaultSrc: ['@self']` and nothing for `connectSrc`), the addition lands in `defaultSrc` rather than creating a sibling directive — CSP fall-back semantics mean a sibling would *narrow* your intent, so we preserve the broader fallback.
905
-
906
- ### Troubleshooting table for CSP violations
1011
+ …and the compiler fills in font hosts, trusted origins, and SPA-baked URLs.
907
1012
 
908
- The security docs page now includes a [Troubleshooting CSP violations](/compiler/config/security#troubleshooting-csp-violations) table mapping browser console errors back to the directive that needs widening. Useful when auto-config is disabled or the project has a non-bundled SPA hitting third-party origins.
909
-
910
- ### Out of scope (deferred)
911
-
912
- - **Per-request CSP nonces** (`@nonce` sentinel implementation) — Phase 2 / 0.10.16. Sentinel still errors at compile in 0.10.15.
913
- - **`revocationCheck: 'kv'` for `auth.jwt`** — schema accepts it, runtime still errors at compile. Slipped from 0.10.15 to 0.10.16.
914
- - **Public R2 host auto-add to `imgSrc`** — most R2 access today goes through the worker so the SPA fetches from `'@self'`. Will revisit once we have a clean way to discover public-bucket hosts at compile.
1013
+ When a target directive is missing, auto-config scaffolds it from `default-src` baseline rather than widening `default-src` itself — CSP3 fall-back semantics would otherwise leak the addition to every directive that falls back to `default-src`.
915
1014
 
916
1015
  ---
917
1016
 
918
1017
  ## v0.10.14 — May 1, 2026
919
1018
 
920
- ### `auth.jwt` — JWT bearer-token fast-path config
1019
+ ### `auth.jwt` config
921
1020
 
922
- Quickback's bearer-token JWT (the one minted by the auth middleware and consumed by the fast-path on every subsequent request) is now configurable. The most-tuned knob is `expiresIn` — drop it to bound the post-revocation replay window without affecting browser SPAs, which auto-refresh via `set-auth-token` on every authed call:
1021
+ The bearer-token JWT used by the auth fast-path is configurable. Tune `expiresIn` to bound the post-revocation replay window without affecting browser SPAs (which auto-refresh on every authed call):
923
1022
 
924
1023
  ```ts
925
1024
  auth: {
926
1025
  jwt: {
927
- expiresIn: 30, // 30s post-revocation replay window
928
- issuer: 'my-api', // iss claim (verified on the way back in)
929
- audience: 'partner-svc', // aud claim
930
- secretEnv: 'CUSTOM_JWT_SECRET', // override BETTER_AUTH_SECRET if you need the JWT secret rotated independently
931
- },
932
- }
933
- ```
934
-
935
- `revocationCheck: 'kv'` (KV-denylist consult on every fast-path verify, ~5-15ms edge-cached, no D1 hit) is reserved in the schema today but **deferred to 0.10.15** — setting it errors at compile so the migration path is explicit. `'none'` (today's behaviour, 0 cost, replay bound by TTL) stays the default.
936
-
937
- See [the docs page](/compiler/config/auth) for the full knob list and tuning recommendations.
938
-
939
- ### MCP admin endpoints hidden from non-admin `tools/list`
940
-
941
- Better Auth admin endpoints (`/admin/list-users`, `/admin/ban-user`, `/admin/impersonate-user`, etc. — 9 in total) now carry `x-access: { userRole: ['admin'] }` in the generated OpenAPI spec, which means the MCP server's existing access-filter automatically drops them from `tools/list` for callers without an admin token. Anonymous and member-role callers no longer see admin tooling enumerated through MCP; admin endpoints still exist on the HTTP surface (Better Auth gates them server-side regardless).
942
-
943
- ### Declarative `security` config block
944
-
945
- Every security response-header (`Content-Security-Policy`, `Cross-Origin-Opener-Policy`, `Cross-Origin-Embedder-Policy`, `Cross-Origin-Resource-Policy`, `X-Frame-Options`, `Strict-Transport-Security`, `Referrer-Policy`, `Permissions-Policy`) is now configurable from `quickback.config.ts`. Loop's `postcompile-patch.mjs` (which re-injected a fuller CSP and COOP after every `quickback compile`) can now be deleted in favour of:
946
-
947
- ```ts
948
- security: {
949
- csp: {
950
- defaultSrc: ['@self'],
951
- scriptSrc: ['@self'],
952
- styleSrc: ['@self', '@unsafe-inline'],
953
- frameAncestors: ['@none'],
954
- objectSrc: ['@none'],
955
- upgradeInsecureRequests: true,
1026
+ expiresIn: 30,
1027
+ issuer: 'my-api',
1028
+ audience: 'partner-svc',
1029
+ secretEnv: 'CUSTOM_JWT_SECRET',
956
1030
  },
957
- coop: 'same-origin',
958
1031
  }
959
1032
  ```
960
1033
 
961
- `@`-prefixed sentinels (`@self`, `@none`, `@unsafe-inline`, `@unsafe-eval`, `@trustedOrigins`, `@nonce`) save users from awkward `"'self'"` quoting and let `@trustedOrigins` resolve to the same allowlist `cors()` uses. Unknown sentinels throw at compile rather than silently stringify into the wire CSP.
1034
+ ### Admin MCP endpoints filtered
962
1035
 
963
- The compiler runs lint rules over the resolved config — errors for `@nonce` (deferred to 0.10.15), `@unsafe-inline + @nonce` (silently broken), and sentinel-only directives that would resolve to nothing at runtime; warnings for `@unsafe-inline` in `script-src`, wildcard sources, missing `default-src`, HSTS preload-list misconfiguration, etc.
1036
+ Better Auth admin endpoints (`/admin/list-users`, `/admin/ban-user`, etc.) now carry `x-access: { userRole: ['admin'] }` in the generated OpenAPI spec. The MCP `tools/list` access-filter drops them for non-admin callers.
964
1037
 
965
- Defaults preserve 0.10.13 behaviour byte-for-byte — adding the block without setting any field is a no-op.
1038
+ ### Declarative `security` config
966
1039
 
967
- See [the docs page](/compiler/config/security) for the full reference.
1040
+ Every security response header (`Content-Security-Policy`, COOP, COEP, CORP, HSTS, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`) is configurable from `quickback.config.ts`. `@`-prefixed sentinels (`@self`, `@none`, `@unsafe-inline`, `@trustedOrigins`, etc.) replace awkward `"'self'"` quoting.
968
1041
 
969
- ### HSTS no longer pins `localhost` to HTTPS
1042
+ The compiler lints the resolved config for known footguns: `@unsafe-inline` in `script-src`, wildcard sources, missing `default-src`, HSTS preload-list misconfiguration.
970
1043
 
971
- The generated middleware now skips `Strict-Transport-Security` when the request hostname is `localhost`, `127.0.0.1`, or `*.localhost`. Without this gate, `wrangler dev` would pin the developer's browser to HTTPS for `max-age` seconds — observable across every project on that machine since HSTS keys on hostname, not port. Affects every project running locally.
1044
+ ### HSTS skipped on localhost
972
1045
 
973
- ### Out of scope (deferred)
974
-
975
- - **Per-request CSP nonces** — Phase 2 / 0.10.15. Sentinel exists at config-validation level so users can author their final CSP today knowing it'll start working when nonces ship.
976
- - **Asset-hash CSP** for inline `<style>` and `<script>` blocks emitted by the bundled SPAs — Phase 3.
977
- - **Per-route CSP overrides** (e.g. one looser policy for `/admin`) — single global CSP for now.
1046
+ Generated middleware skips `Strict-Transport-Security` when the request hostname is `localhost`, `127.0.0.1`, or `*.localhost`. Without this gate, `wrangler dev` would pin a developer's browser to HTTPS across every project on that machine.
978
1047
 
979
1048
  ---
980
1049
 
981
1050
  ## v0.10.13 — May 1, 2026
982
1051
 
983
- ### Clickjacking protection on every generated Worker
984
-
985
- Every Worker now emits two clickjacking-defence headers on every
986
- response:
987
-
988
- - `Content-Security-Policy: frame-ancestors 'self' <TRUSTED_ORIGINS…>`
989
- - `X-Frame-Options: SAMEORIGIN`
990
-
991
- The CSP allowlist is sourced from the same `TRUSTED_ORIGINS` constant
992
- that gates CORS, so users configure their domains in one place
993
- (`auth.trustedOrigins` / `auth.trustedOriginDefaults` in
994
- `quickback.config.ts`) and both CORS and frame-ancestors stay in
995
- lockstep. `'self'` is always allowed so an app's own SPAs can frame
996
- their own routes (e.g. an account login popover hosted on the same
997
- origin).
998
-
999
- Modern browsers obey `frame-ancestors` and ignore `X-Frame-Options`
1000
- when both are set; the legacy header is included for clients that
1001
- don't speak CSP3. The CSP intentionally only sets `frame-ancestors` —
1002
- adding `script-src` / `default-src` would need a much wider audit
1003
- across SPA assets, inline scripts, and third-party embeds, so that's
1004
- left as a follow-up.
1005
-
1006
- Recompile (`quickback compile`) and redeploy to pick this up — no
1007
- config change needed unless you want to allow extra cross-origin
1008
- iframe embeds, in which case add them to `auth.trustedOrigins`.
1009
-
1010
- ---
1011
-
1012
- ## v0.10.12 — May 1, 2026
1013
-
1014
- ### Bundled-docs sync for the MCP recon fix
1015
-
1016
- Patch release that re-bundles the CLI's offline docs (consulted by the
1017
- Claude Code skill, Cursor rules, and other AI assistants) so they
1018
- reflect the corrected `tools/list` access-filter behavior and CORS
1019
- posture shipped in v0.10.11. The `compiler/config/agents.mdx` page
1020
- itself was already corrected on the docs site immediately after the
1021
- 0.10.11 release; this bump propagates that text into the bundle inside
1022
- `@quickback-dev/cli`.
1052
+ ### Clickjacking defence on every Worker
1023
1053
 
1024
- No runtime or compiler behavior change — re-running `quickback compile`
1025
- against this version produces the same output as v0.10.11.
1054
+ Every Worker emits `Content-Security-Policy: frame-ancestors 'self' <TRUSTED_ORIGINS…>` and `X-Frame-Options: SAMEORIGIN` on every response. The CSP allowlist is sourced from the same `TRUSTED_ORIGINS` constant that gates CORS.
1026
1055
 
1027
1056
  ---
1028
1057
 
1029
1058
  ## v0.10.11 — May 1, 2026
1030
1059
 
1031
- ### MCP `tools/list` is now access-filtered + recon-tightened
1032
-
1033
- The generated MCP-over-HTTP server (`src/routes/mcp.ts`) had three holes
1034
- that turned a standard pentest into trivial recon:
1035
-
1036
- 1. `tools/list` returned the entire tool catalogue to anyone — including
1037
- admin-only endpoints — without checking auth or roles. Tool
1038
- descriptions also leaked sentences like `[UNSAFE] bypasses tenant
1039
- scoping and requires elevated access` verbatim.
1040
- 2. The endpoint set `Access-Control-Allow-Origin: *` so any origin could
1041
- pull the catalogue from a browser.
1042
- 3. Unauthenticated `GET /mcp` enumerated every tool name in its
1043
- discovery payload.
1044
-
1045
- Fix:
1046
-
1047
- - Each tool now carries sanitised access metadata (`_access` covering
1048
- `roles` / `userRole` / `or` / `and`, plus `_public` for `PUBLIC`
1049
- pseudo-role or empty `security`). `tools/list` filters against the
1050
- caller's `ctx` — unauth callers see only `_public` tools, authed
1051
- callers see only role-gated tools they pass. Record predicates and
1052
- function-form access (opaque at list time) are dropped.
1053
- - Wildcard CORS removed entirely. The parent app's `cors()` middleware
1054
- (origin allowlist via `TRUSTED_ORIGINS` + `BETTER_AUTH_URL`) now
1055
- applies uniformly to `/mcp`, same as every other route.
1056
- - `[UNSAFE] ... bypasses tenant scoping ...` flavour text is gone.
1057
- `annotations.destructiveHint` and `_unsafe` remain — those are the
1058
- spec-correct signals for clients to warn users.
1059
- - Unauthenticated `GET /mcp` no longer lists tool names. Inventory is
1060
- only available via the access-filtered `tools/list`.
1061
-
1062
- This filter is recon-mitigation, not a security boundary: `tools/call`
1063
- still re-enters the Hono app and runs every middleware (auth, firewall,
1064
- access, guards, masking), so hiding a tool from list never weakens the
1065
- underlying gate.
1066
-
1067
- Known follow-up: Better Auth admin endpoints (`ban-user`, `create-user`,
1068
- `impersonate-user`, etc.) don't yet emit `x-access` in the OpenAPI spec,
1069
- so any logged-in user still sees them in `tools/list` (the actual call
1070
- is still gated by the admin plugin). Tracked separately.
1071
-
1072
- ---
1073
-
1074
- ## v0.10.10 — April 29, 2026
1060
+ ### MCP `tools/list` is access-filtered
1075
1061
 
1076
- ### Reject reserved keys inside `access.record` at compile time
1062
+ Each MCP tool now carries sanitised access metadata. `tools/list` filters against the caller's `ctx`: unauthenticated callers see only `PUBLIC` tools, authenticated callers see only role-gated tools they pass.
1077
1063
 
1078
- `access.record` is a flat field map evaluated as implicit AND between
1079
- entries — keys must be column names. Putting `and: [...]` (or `or` /
1080
- `roles` / `userRole`) inside `record` was a real-world footgun: the
1081
- runtime treated the literal string `"and"` as a column lookup, the
1082
- predicate failed on every row, and the caller got a silent `403` /
1083
- empty list with nothing pointing at the misuse. The TypeScript type
1084
- couldn't catch this — `RecordConditions` is an open-ended index
1085
- signature, so any key parses.
1064
+ - Wildcard CORS removed from the MCP endpoint.
1065
+ - Unauthenticated `GET /mcp` no longer enumerates tool names.
1066
+ - Internal flavor text is removed; `annotations.destructiveHint` and `_unsafe` remain — those are the spec-correct signals for clients.
1086
1067
 
1087
- The compiler now walks every access node attached to a resource (CRUD
1088
- ops, `read.access`, view access, masking `show` / `query`, action
1089
- access) and throws a clear migration error when `record` contains a
1090
- reserved key:
1091
-
1092
- - `and` / `or` inside `record` → use the top-level `and` / `or`
1093
- sibling: `{ and: [{ record: { ... } }, { record: { ... } }] }`
1094
- - `roles` / `userRole` inside `record` → put them at the access node
1095
- alongside `record`: `{ roles: [...], record: { ... } }`
1096
-
1097
- The error names the exact origin (`crud.update.access`,
1098
- `actions.focus.access.or[1]`, etc.) so the fix lands in the right place.
1068
+ `tools/call` continues to re-enter the Hono app and run every middleware (auth, firewall, access, guards, masking), so hiding a tool from list never weakens the underlying gate.
1099
1069
 
1100
1070
  ---
1101
1071
 
1102
- ## v0.10.9 — April 29, 2026
1103
-
1104
- ### Role hierarchy now expands in record-based action access
1105
-
1106
- `auth.roleHierarchy: ['member', 'admin', 'owner']` plus
1107
- `access: { roles: ['member+'] }` on a record-based action used to
1108
- silently 403 valid callers. The standalone-action route generator
1109
- inlined the expanded role list as a JSON literal, but the
1110
- record-based generator read the access config back through the
1111
- runtime `actions['name'].access` import — the user's source, where
1112
- the unexpanded `'member+'` shorthand still lived. The runtime did
1113
- literal string matching against `ctx.roles`, so an `owner` calling
1114
- the action got `['member+'] !== 'owner'` and was rejected.
1072
+ ## v0.10.10 — April 29, 2026
1115
1073
 
1116
- Fixed: record-based action routes now inline the expanded list the
1117
- same way standalone routes do. `input` and `execute` still flow
1118
- through the runtime import (closures aren't serializable); only the
1119
- access config is lifted to a JSON literal so the compile-time
1120
- expansion actually reaches the matcher.
1074
+ ### Reserved keys in `access.record` are rejected
1121
1075
 
1122
- A regression test (`role-hierarchy-action-routes.test.ts`) locks the
1123
- behavior in — it asserts that `member+` never reaches the route
1124
- output and that the access config is no longer read from
1125
- `actions[name].access` at runtime.
1076
+ `access.record` is a flat field map evaluated as implicit AND between entries — keys must be column names. The compiler now rejects reserved keys (`and`, `or`, `roles`, `userRole`) inside `record` with migration guidance pointing at the working pattern (top-level siblings with their own `record:` blocks).
1126
1077
 
1127
1078
  ---
1128
1079
 
1129
1080
  ## v0.10.8 — April 29, 2026
1130
1081
 
1131
- ### Audit support on postgres targets, plus a generated-API quality pass
1082
+ ### Audit logging on Postgres targets
1083
+
1084
+ `audit_events` previously only existed on `cloudflare-d1`. The audit table now lives in a dedicated `audit` schema (`drizzle.pgSchema('audit')`) on Postgres targets. The `hasSecurityAudit` gate accepts D1 or any PG dialect; `auditDatabaseId` remains a D1-only requirement.
1132
1085
 
1133
- **Audit on PG.** Until this release, `audit_events` only existed on cloudflare-d1 — projects on Neon (or any postgres target) silently skipped audit logging on `unsafe:` and `PUBLIC`-role actions, and hard delete was hard-blocked. Postgres has no equivalent of D1's separate-database binding model, but it has native schemas — so the audit table now lives in a dedicated `audit` schema in the same database as features (`drizzle.pgSchema('audit')`). The `hasSecurityAudit` gate accepts D1 OR any PG dialect; the `auditDatabaseId` requirement only fires for D1 (which still uses the separate-binding model). The recruitment example wires `auditDatabaseId` so the recompile path stays green.
1086
+ ### `auditDatabaseId` is a compile-time requirement
1134
1087
 
1135
- **`auditDatabaseId` is now a compile-time requirement** (D1 only). Previously, projects with unsafe/PUBLIC actions but no audit id silently produced a `database_id = "local-audit"` placeholder in production `wrangler.toml`; Cloudflare's worker upload step then rejected it with code 10021 *after* assets and migrations had already run. The compile-time error names the exact `wrangler d1 create <project>-audit` command and the `auditDatabaseId` config key where the returned id goes.
1088
+ Projects with unsafe or `PUBLIC` actions that previously produced a placeholder `database_id = "local-audit"` in production now fail at compile time with the exact `wrangler d1 create <project>-audit` command and the config key where the returned ID goes.
1136
1089
 
1137
- ### Five fixes from a Loop integration ticket pass
1090
+ ### Action input → OpenAPI / MCP
1138
1091
 
1139
- **Action input → OpenAPI / MCP.** `defineAction({ input: z.object({...}) })` schemas now flow into `requestBody` on the OpenAPI operation and `inputSchema.properties` / `_bodyFields` on the MCP tool list. Simple `z.object` shapes are extracted at compile time; for discriminated unions, refinements, recursive schemas, and bare-identifier references (`input: createPersonInput`), the compiler runs your action file through Zod 4's native `z.toJSONSchema()` during compilation — full-fidelity output with no static translator to maintain. Pre-fix, every action came out as a no-arg endpoint, which gutted typed SDK generation and made MCP useless for actions that take parameters.
1092
+ `defineAction({ input: z.object({...}) })` schemas flow into the OpenAPI `requestBody` and the MCP tool's `inputSchema.properties`. Simple `z.object` shapes are extracted at compile time; discriminated unions, refinements, recursive schemas, and bare-identifier references run through Zod's native `z.toJSONSchema()` for full-fidelity output.
1140
1093
 
1141
- **OpenAPI fidelity.** Three surgical fixes that strict validators (zod, openapi-typescript, openapi-fetch) had been complaining about:
1142
- - Response schemas now emit `required[]` for every non-nullable column, so generated SDKs treat them as guaranteed-present rather than optional.
1143
- - `text(_, { enum: [...] })` columns emit as closed `{ type: "string", enum: [...] }`, narrowing to literal unions.
1144
- - `id` only claims `format: "uuid"` when the project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators get plain `{ type: "string" }` — strict validators stop rejecting responses against their own spec.
1094
+ ### OpenAPI fidelity
1145
1095
 
1146
- **Mask auto-detector now checks the column exists.** The auto-mask predicate used to be unconditionally `show: { or: 'owner', roles: ['admin'] }` — including for tables with no owner column at all (no `userId` / `ownerId` and no `q.scope('owner')`). The generated mask function would reference a non-existent column and fail under TypeScript checks. The auto-detector now verifies the resolved owner column exists in the parsed schema before emitting the `or` clause; when it doesn't, the rule falls back to roles-only and the compiler emits a warning so the behavior is transparent.
1096
+ - Response schemas emit `required[]` for every non-nullable column.
1097
+ - `text(_, { enum: [...] })` columns emit as closed `{ type: "string", enum: [...] }`.
1098
+ - `id` claims `format: "uuid"` only when the project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators emit plain `{ type: "string" }`.
1147
1099
 
1148
- **Error code consistency.** The generated CRUD layer was emitting raw codes (`'UNAUTHORIZED'`, `'NOT_NULL_VIOLATION'`, `'UNIQUE_VIOLATION'`, `'INSERT_FAILED'`, `'UPDATE_FAILED'`) that were never in the `QuickbackErrorCode` enum, so consumers couldn't switch exhaustively on `code`. New `database` layer + `DB_NOT_NULL_VIOLATION` / `DB_UNIQUE_VIOLATION` / `DB_INSERT_FAILED` / `DB_UPDATE_FAILED` / `NOT_FOUND` codes are now in the enum, the routes use `AuthErrors.missing()` / `DatabaseErrors.*()` helpers throughout, and the OpenAPI `Error` component emits `code` as a closed enum sourced from the canonical `QUICKBACK_ERROR_CODES` list. Generated SDKs can now `switch` on `code` without a default branch swallowing unknown values. See [API errors](/compiler/targets/hono-api/using-the-api/errors#database).
1100
+ ### Minor
1149
1101
 
1150
- **Dropped dead `auditFields` preamble from action route generators.** The audit wrapper's `Proxy` already hard-stamps `createdAt` / `createdBy` / `modifiedAt` / `modifiedBy` on every INSERT and `modifiedAt` / `modifiedBy` on every UPDATE — the `auditFields` const the route preamble built was never read. Dropped from `standalone.ts` / `record-based.ts` and from the `ActionExecutorParams` JSDoc. Migrated 7 example handlers (drop `modifiedAt: auditFields!.modifiedAt` from `.set` payloads — the wrapper handles it). Note: `.onConflictDoUpdate({ set })` is *not* intercepted by the wrapper, so `upsertBatch`-style handlers keep an explicit `modifiedAt: now`.
1102
+ - Auto-mask predicate verifies the resolved owner column exists before emitting an `or: 'owner'` clause; falls back to roles-only with a warning otherwise.
1103
+ - Generated CRUD errors emit canonical `QuickbackErrorCode` enum values (`DB_NOT_NULL_VIOLATION`, `DB_UNIQUE_VIOLATION`, etc.) so generated SDKs can exhaustively switch on `code`. See [API errors](/compiler/targets/hono-api/using-the-api/errors#database).
1151
1104
 
1152
1105
  ---
1153
1106
 
1154
- ## One file per action: greenfield action authoring
1107
+ ## DSL: one file per action, multi-table per feature
1108
+
1109
+ ### One file per action
1155
1110
 
1156
- Action authoring collapses to a single shape. Each action is its own file under `<feature>/actions/<name>.ts` using `defineAction({...})`. The filename is the action name AND the URL segment.
1111
+ Action authoring is one file per action under `<feature>/actions/<name>.ts`. The filename is the action name and the URL segment:
1157
1112
 
1158
1113
  ```typescript
1159
1114
  // features/applications/actions/advance.ts
@@ -1174,65 +1129,37 @@ export default defineAction({
1174
1129
  });
1175
1130
  ```
1176
1131
 
1177
- `defineAction` is imported from a generated per-feature helper at `<feature>/.quickback/define-action.ts` — types `record`, `input`, and audit fields without manual annotations. The directory says what `:id` mounts to; the imports say what the body reads or writes.
1132
+ `defineAction` is imported from a generated per-feature helper at `<feature>/.quickback/define-action.ts` — `record`, `input`, and audit fields are typed without manual annotations.
1178
1133
 
1179
1134
  **Discovery rules:**
1180
- - `actions/<name>.ts` binds to the feature's primary table (the `<feature>.ts` file at the feature root).
1181
- - `actions/<table>/<name>.ts` binds to the sibling table file `<table>.ts` — for multi-table features.
1182
- - Setting `path:` makes the action standalone (custom URL, no record fetch, no firewall preload).
1183
- - Tableless features (no top-level `*.ts` files) require every action to be standalone.
1184
- - Action names are unique per `(bindTable, name)` pair — sibling-bound actions on different tables may share a verb (e.g. `actions/episodes/publish.ts` + `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish` and don't collide). Standalone actions are unique per `(method, path)`.
1185
- - Files under `<feature>/lib/` are copied verbatim for feature-local helpers; `quickback/lib/` is exposed via the `~/lib/*` alias for cross-feature shared code (with a one-way import rule enforced at compile time).
1135
+ - `actions/<name>.ts` binds to the feature's primary table.
1136
+ - `actions/<table>/<name>.ts` binds to the sibling table file.
1137
+ - Setting `path:` makes the action standalone (custom URL, no record fetch).
1138
+ - Tableless features require every action to be standalone.
1186
1139
 
1187
- **Retired** (rejected at load time with migration guidance):
1140
+ **Retired** (rejected at load time with migration guidance): `actions.ts` (bundled multi-action file), `_feature.ts`, `handlers/` directory + `handler:` string ref, `defineActions(table, {…})`, colocated `defineActions` inside table files, `standalone: true` flag, `*-actions.ts` / `*.actions.ts` filename patterns.
1188
1141
 
1189
- - `actions.ts` (bundled multi-action file)
1190
- - `_feature.ts` (shared preamble + tableless actions)
1191
- - `handlers/` directory + `handler:` string ref
1192
- - `defineActions(table, {…})` and `defineActions(null, {…})`
1193
- - `export default { actions: {…} }`
1194
- - Colocated `defineActions` inside table files
1195
- - `standalone: true` flag (presence of `path:` is the new signal)
1196
- - `*-actions.ts` / `*.actions.ts` filename patterns
1142
+ See [Actions docs](/compiler/definitions/actions).
1197
1143
 
1198
- The phantom-`unsafe` regex bug that flattened nested `unsafe: { … }` blocks into a fake top-level action is gone — the parser now reads action files as real TS modules with real imports, so type inference, jump-to-definition, and rename refactoring all work end-to-end.
1144
+ ### Multi-table actions per feature
1199
1145
 
1200
- The CLI loader rejects retired primitives at load time with batched migration errors. Existing projects need to be migrated by hand to the new shape before recompiling.
1146
+ One feature directory can own actions on multiple tables. Three discovery modes:
1201
1147
 
1202
- See the [Actions docs](/compiler/definitions/actions) for the full reference.
1148
+ - **Colocated** (canonical) — `<table>.ts` containing both `defineTable` and `defineActions(<table>, …)`. One file per entity.
1149
+ - **`actions.ts`** — single primary-table actions file at feature root.
1150
+ - **`actions/<table>.ts`** — per-table action files for strict schema/behavior separation.
1203
1151
 
1204
- ---
1205
-
1206
- ## Multi-table actions per feature
1207
-
1208
- Features used to support exactly one `defineActions(table, …)` call via `actions.ts`, which forced unnatural feature splits whenever multiple tables in the same feature needed actions (a podcast feature with `episodes`, `shows`, `seasons`, `collections`, etc.). One feature directory can now own actions on multiple tables across three discovery modes:
1209
-
1210
- - **Colocated** (canonical) — `<table>.ts` containing both `defineTable` and `defineActions(<table>, …)`. One file per entity. Default for new features.
1211
- - **`actions.ts`** (existing) — single primary-table actions file at feature root. Unchanged behaviour.
1212
- - **`actions/<table>.ts`** — per-table action files for teams that want strict schema/behavior separation or need to break an import cycle.
1213
-
1214
- Plus the universal `_feature.ts` slot (at feature root) for **non-table-bound feature-level actions** (`export default { actions: { … } }` shape) and **shared Zod schemas** that get prepended once to the merged actions module so every sibling action sees them. Allowed in any of the three modes — orthogonal to table binding.
1215
-
1216
- The decision flowchart: *one table with actions → colocate. Multiple tables with actions → colocate each. Hit a cycle or want strict separation → `actions/<table>.ts`. Want schema/actions split for a single-table feature → `actions.ts`. Non-table actions → always `_feature.ts`.*
1217
-
1218
- Conflicts are batched and printed once before the compiler aborts — no "fix one, recompile, fix the next" loop. The CLI hard-errors when a feature mixes `actions.ts` with table-bound mode, when the same table has its `defineActions` declared in two places, when an `actions/<x>.ts` first-arg doesn't match the basename, or when `_feature.ts` contains `defineActions(table, …)`. Legacy `*-actions.ts` / `*.actions.ts` filenames in a feature dir trigger a soft warning naming the offending paths.
1219
-
1220
- Within the legacy bundled `actions.ts` DSL, action names had to be unique within a feature — the runtime module merged every source into one keyspace, so colliding `publish` actions on `episodes` and `shows` would have silently overwritten each other. The retired `actions.ts` shape is no longer accepted, so this constraint is gone: the current one-file-per-action layout keys uniqueness per `(bindTable, name)` pair, and the codegen aggregator mangles the JS map key per bind-table while keeping the URL segment bare. Sibling-bound `actions/episodes/publish.ts` and `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish` and compile cleanly.
1152
+ Plus a universal `_feature.ts` slot for non-table-bound feature-level actions and shared Zod schemas.
1221
1153
 
1222
- Inline `execute:` bodies must be arrow functions (`execute: async (ctx) => { … }`). `async function` and plain `function` shapes were silently misparsed by the route emitter — they now hard-error at parse time pointing at the canonical arrow form, with a suggestion to use `handler:` for callers who genuinely need a named function declaration.
1223
-
1224
- `handlers/` walks recursively now — `handlers/<table>/<action>.ts` is the canonical layout. A new `lib/` directory under each feature gets copied verbatim into the output for feature-local helpers.
1225
-
1226
- Migration: existing `actions.ts` projects compile bit-identically — the legacy single-table path is unchanged. Legacy `*-actions.ts` filenames produce a soft warning and silently aren't picked up; rename to `<table>.ts` (colocated), `actions/<table>.ts`, or single `actions.ts`.
1154
+ Action names are unique per `(bindTable, name)` pair. Sibling-bound `actions/episodes/publish.ts` and `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish` and compile cleanly.
1227
1155
 
1228
1156
  ---
1229
1157
 
1230
- ## Firewall: named-scope shape restored, auto-detection synonyms widened
1158
+ ## Firewall: named-scope shape
1231
1159
 
1232
- The named-scope firewall shape (`firewall: { organization: { column: 'tenant_id' } }`) is back as a co-equal user-facing input alongside the predicate array. DSL v2 step 8 had walled it off, but the internal architecture still kept named-scope around for the route + scoped-db generators — so re-accepting it at the input boundary is a thin coercion layer, not an architectural change.
1160
+ The named-scope firewall shape is a co-equal user-facing input alongside the predicate array:
1233
1161
 
1234
1162
  ```typescript
1235
- // All three are now valid; all compile to the same predicate array internally.
1236
1163
  firewall: { organization: { column: 'tenant_id' } } // named-scope (compact)
1237
1164
  firewall: { owner: { column: 'account_user_id' } }
1238
1165
  firewall: { exception: true }
@@ -1244,27 +1171,17 @@ firewall: [
1244
1171
 
1245
1172
  Pick the form that reads better — named-scope for the common one-line case, predicate array when you need custom `in`-lists or non-scope predicates.
1246
1173
 
1247
- **Auto-detection synonyms expanded.** When `firewall:` is omitted entirely, the compiler scans the schema for an isolation column. The org-scope list now accepts `organizationId`, `organisationId`, `orgId`, `organization`, `organisation`, `org` (American + British). User-scope still accepts `userId` only.
1174
+ **Auto-detection synonyms.** When `firewall:` is omitted, the compiler scans the schema for an isolation column. The org-scope list accepts `organizationId`, `organisationId`, `orgId`, `organization`, `organisation`, `org` (American + British). User-scope accepts `userId`.
1248
1175
 
1249
- **`ownerId` is now a targeted error signal.** When a table carries `ownerId` but no isolation column AND no explicit `firewall:`, the compiler raises a specific error: `\`ownerId\` is business-logic ownership, not access control — Quickback won't auto-derive a firewall from it. Either rename to \`userId\` if this column controls access, add a separate \`userId\` / \`organizationId\` column, or specify \`firewall:\` explicitly.` This replaces the generic "missing isolation column" error in the `ownerId`-only case and preserves the documented distinction between RLS-style access control (`userId`) and business-logic ownership (`ownerId`).
1250
-
1251
- Migration: nothing breaks. Projects on the predicate-array shape compile bit-identically. Projects on the named-scope shape — including any test fixtures or example projects that were left on the legacy form — now compile cleanly again.
1176
+ **`ownerId` is a targeted error signal.** When a table carries `ownerId` but no isolation column and no explicit `firewall:`, the compiler raises a specific error — `ownerId` is business-logic ownership, not access control. Use `userId` for access control, declare an explicit `firewall:`, or add a separate isolation column.
1252
1177
 
1253
1178
  ---
1254
1179
 
1255
1180
  ## v0.10.0 — April 26, 2026
1256
1181
 
1257
- ### `q.scope()` column DSL + unified `masking.query` gate
1258
-
1259
- Two related DSL consolidations land. The `q.scope()` half is purely additive; the `masking.query` half rejects three legacy per-capability flags at compile time (migration is mechanical — see below).
1182
+ ### `q.scope()` — single-declaration tenant scoping
1260
1183
 
1261
- **`q.scope(kind)` — single-declaration tenant scoping.** Replaces the three-place pattern (column declaration + firewall predicate + implicit ownership-guard) with one column. `q.scope('organization')` compiles to `text(...).notNull()` and tells the compiler:
1262
-
1263
- 1. Auto-derive the firewall predicate (`{ field: 'organizationId', equals: 'ctx.activeOrgId' }`) so the explicit `firewall:` block can be omitted entirely.
1264
- 2. Add the column to `GUARDS_CONFIG.systemManaged` so client input is rejected at the guard layer.
1265
- 3. Auto-populate from `ctx` on create / upsert.
1266
-
1267
- The systemManaged extension generalises beyond `q.scope()`: any firewall predicate whose `equals` references `ctx.*` adds its `field` to the systemManaged set. So a hand-rolled `firewall: [{ field: 'tenantId', equals: 'ctx.activeOrgId' }]` gets the same treatment.
1184
+ `q.scope(kind)` replaces the three-place pattern (column declaration + firewall predicate + ownership-guard) with one column:
1268
1185
 
1269
1186
  ```typescript
1270
1187
  columns: {
@@ -1274,304 +1191,148 @@ columns: {
1274
1191
  }
1275
1192
  ```
1276
1193
 
1277
- The auto-derived firewall also includes the soft-delete predicate (`{ field: 'deletedAt', isNull: true }`) when audit-field injection is on (the default). See [`q.scope()` in the schema docs](/compiler/definitions/schema#qscope--tenant-scope-columns).
1194
+ `q.scope()` columns auto-derive the firewall predicate, register with the guards layer as `systemManaged` (client input rejected), and auto-populate from `ctx` on create / upsert. The systemManaged extension generalises beyond `q.scope()`: any firewall predicate whose `equals` references `ctx.*` registers its `field` automatically.
1195
+
1196
+ See [`q.scope()`](/compiler/definitions/schema#qscope--tenant-scope-columns).
1278
1197
 
1279
- **`masking[col].query.roles` — unified role gate for filter / sort / search.** The three legacy per-capability flags (`filterable`, `searchable`, `sortable`) are replaced by a single allowlist that says "these roles can query the column."
1198
+ ### `masking[col].query.roles` — unified filter / sort / search gate
1199
+
1200
+ The three legacy per-capability flags (`filterable`, `searchable`, `sortable`) are replaced by a single `query.roles` allowlist:
1280
1201
 
1281
1202
  ```typescript
1282
1203
  masking: {
1283
1204
  email: {
1284
1205
  type: 'email',
1285
1206
  show: { roles: ['admin'] },
1286
- query: { roles: ['admin'] }, // optional — defaults to show.roles
1207
+ query: { roles: ['admin'] }, // defaults to show.roles when omitted
1287
1208
  },
1288
1209
  }
1289
1210
  ```
1290
1211
 
1291
- When omitted, `query` inherits from `show.roles` ("if you can see it, you can query it") which is the right shape for almost all PII. A view's own `query.{filterable,searchable,sortable}` allowlist is the opt-in for higher-privileged roles; the existing intersection validator gates it at compile time. See [Masking query gate](/compiler/definitions/masking#query-gate-filter--sort--search).
1212
+ A view's own `query.{filterable,searchable,sortable}` allowlist is the opt-in for higher-privileged roles; the existing intersection validator gates it at compile time.
1292
1213
 
1293
- **Breaking:** Setting `masking[col].filterable / .searchable / .sortable` is rejected at compile time with a migration hint. Replace with `query.roles` (or just delete the flags — `query` defaults to `show.roles`).
1214
+ **Breaking:** `masking[col].filterable / .searchable / .sortable` is rejected at compile time with a migration hint. Replace with `query.roles` (or delete the flags — `query` defaults to `show.roles`).
1294
1215
 
1295
1216
  ---
1296
1217
 
1297
1218
  ## v0.9.0 — April 25, 2026
1298
1219
 
1299
- ### DSL v2: unified `read:` pipeline, transactional batches, ID-probe defense
1220
+ ### Unified `read:` pipeline
1300
1221
 
1301
- Step 8 of the DSL v2 refactor lands. The headline shift is that the read
1302
- side of every resource now has its own block — `read:` — that owns the
1303
- collection-level `GET /` endpoint, single-record `GET /:id`, and named view
1304
- projections. The legacy `crud.list` and `crud.get` shapes are rejected at
1305
- compile time. See the new [Read pipeline](/compiler/definitions/read) page
1306
- for the full reference and migration table.
1222
+ The read side of every resource has its own block — `read:` — that owns the collection-level `GET /` endpoint, single-record `GET /:id`, and named view projections.
1307
1223
 
1308
1224
  **Breaking changes** (compile-time errors with migration hints):
1309
1225
 
1310
- - `crud.list` → [`read.access`](/compiler/definitions/read) (plus `read.pageSize` / `read.maxPageSize`)
1311
- - `crud.get` → `read.access` (single-record GET inherits automatically; use record-level conditions on `read.access` for differentiated single-record gates)
1312
- - Top-level `views: {...}` → [`read.views: {...}`](/compiler/definitions/read#views-under-read-views)
1226
+ - `crud.list` → `read.access` (plus `read.pageSize` / `read.maxPageSize`)
1227
+ - `crud.get` → `read.access` (single-record GET inherits automatically)
1228
+ - Top-level `views: {...}` → `read.views: {...}`
1313
1229
  - `crud.list.fields` / `crud.get.fields` → declare a named view under `read.views` and call `/views/{name}`
1314
1230
 
1315
- **Pre-record access ordering on `/:id`**: handlers now run a role-only
1316
- access check **before** the firewall query, so a caller without a matching
1317
- role gets 403 before the database is touched. This closes the 404-vs-403
1318
- ID-probe channel — an unauthorized caller can no longer distinguish "row
1319
- exists in another tenant" from "row doesn't exist." See
1320
- [Access evaluation order](/compiler/definitions/access#evaluation-order).
1321
-
1322
- **Transactional batch operations**: batch endpoints now expose a
1323
- `failFast` option (replacing the old `atomic` naming) and a
1324
- `meta.transactional` response field. On tx-supporting providers
1325
- (postgres, supabase, neon, libsql, better-sqlite3, bun-sqlite), `failFast: true`
1326
- wraps the per-record loop in `db.transaction(...)` so any failure rolls
1327
- back the entire batch. On Cloudflare D1 (no `db.transaction`), `failFast: true`
1328
- still stops on the first error but prior writes stay committed; inspect
1329
- `meta.transactional` to know which guarantee you got. Embedding queue
1330
- messages and realtime broadcasts are emitted **after** the transaction
1331
- commits, so a rolled-back batch produces no orphan jobs. See
1332
- [Batch Operations: Transactional semantics](/compiler/targets/hono-api/using-the-api/batch-operations#transactional-semantics).
1333
-
1334
- **`firewallErrorMode` lifted off the firewall block**: the field that
1335
- controls 403-vs-404 on firewall misses now lives at the resource top level
1336
- (sibling to `firewall:`), since the firewall config is now a predicate
1337
- array and this is a presentation-layer choice. Existing `firewall.errorMode`
1338
- values should be lifted to `firewallErrorMode` at the resource level.
1339
-
1340
- **Read-only resources**: an empty `crud: {}` block (or omitting `crud:`
1341
- entirely) is valid for read-only resources. `read:` alone is enough to
1342
- expose `GET /` and `GET /:id`.
1343
-
1344
- **Strict-mode top-level keys**: the strict allow-list now includes `dev` so
1345
- `defineConfig({ dev: { ... } })` is accepted at the top level.
1346
-
1347
- ---
1348
-
1349
- ## v0.8.7 — April 17, 2026
1350
-
1351
- ### Security: Hono CVE cluster fix
1231
+ ### Pre-record access ordering
1352
1232
 
1353
- Hono is bumped to `^4.12.14` across the monorepo, the compiler Docker image's pre-installed deps, and every generator path that emits Hono into compiled projects. Older ranges (`^4.0.0` / `^4.5.0` / `^4.6.0` / `^4.7.11`) covered the vulnerable window. Recompile to pick up the fix in your generated project's `package.json`.
1233
+ Handlers on `/:id` run a role-only access check before the firewall query. A caller without a matching role gets 403 before the database is touched. This closes the 404-vs-403 ID-probe channel — an unauthorized caller can no longer distinguish "row exists in another tenant" from "row doesn't exist." See [Access evaluation order](/compiler/definitions/access#evaluation-order).
1354
1234
 
1355
- ### Cloudflare Email Sending is now in public beta
1235
+ ### Transactional batch operations
1356
1236
 
1357
- Quickback already defaults to the Workers `send_email` binding for Cloudflare deploys, and Cloudflare Email Sending has now graduated to public beta — production-ready with zero-config, no API keys, no third-party accounts. No action needed; recompiling any existing project continues to wire the default Cloudflare transport. AWS SES remains a fully supported opt-in (`email.provider: 'aws-ses'`) for non-Cloudflare runtimes or existing SES setups. See [Email Configuration](/compiler/config#email-configuration).
1237
+ Batch endpoints expose `failFast` and a `meta.transactional` response field. On tx-supporting providers (postgres, supabase, neon, libsql, better-sqlite3, bun-sqlite), `failFast: true` wraps the per-record loop in `db.transaction(...)` so any failure rolls back the entire batch. On Cloudflare D1 (no `db.transaction`), `failFast: true` stops on the first error but prior writes stay committed.
1358
1238
 
1359
- ### Minor/patch dep sweep
1239
+ Embedding queue messages and realtime broadcasts emit after the transaction commits — rolled-back batches produce no orphan jobs.
1360
1240
 
1361
- Aligned the whole dep surface — monorepo, compiler Docker image, and generator emissions into compiled projects — so new compiles and existing recompiles converge on the same versions:
1362
-
1363
- - `wrangler@^4.83.0`
1364
- - `drizzle-orm@^0.45.2`, `drizzle-kit@^0.31.10`
1365
- - `zod@^4.3.6`
1366
- - `@cloudflare/workers-types@^4.20260417.1` (also deduped — was accidentally declared in both `dependencies` and `devDependencies` in some paths)
1367
- - `@tanstack/react-query@^5.99.0` (Account app)
1241
+ See [Batch Operations → Transactional semantics](/compiler/targets/hono-api/using-the-api/batch-operations#transactional-semantics).
1368
1242
 
1369
1243
  ---
1370
1244
 
1371
- ## v0.8.5 — April 15, 2026
1372
-
1373
- ### Fix: Better Auth 1.5 and `@cloudflare/workers-types` Compatibility
1245
+ ## v0.8.7 — April 17, 2026
1374
1246
 
1375
- Generated API code failed to typecheck after Better Auth bumped to 1.5 and `@cloudflare/workers-types` tightened `BufferSource` to `ArrayBufferView<ArrayBuffer>`. Four unrelated surfaces broke:
1247
+ ### Hono CVE bump
1376
1248
 
1377
- - **`databaseHooks.member.update.after` was removed** in Better Auth 1.5. The compiler now emits the member role-change broadcast hook as `organizationHooks.afterUpdateMemberRole` inside the `organization()` plugin call, which is the current supported shape.
1378
- - **`REALTIME_URL` and `ACCESS_TOKEN`** are always emitted as optional `CloudflareBindings` fields when the organization plugin is active, so the broadcast hook typechecks even when `realtimeMode` is `"inline"` (or realtime isn't configured at all).
1379
- - **`auth.api.listOrganizations` / `getFullOrganization` / `session.session.activeOrganizationId`** — third-party Better Auth plugins narrow the inferred `auth.api` type and hide organization-plugin endpoints. The generated middleware and `/admin/v1/organizations` route now cast through `any` for these calls.
1380
- - **`crypto.subtle.sign` / `verify`** no longer accept `Uint8Array<ArrayBufferLike>` directly. Generated `jwt.ts` casts encoded payloads to `BufferSource`.
1249
+ Hono is bumped to `^4.12.14` across the monorepo, the compiler Docker image's pre-installed deps, and every generator path that emits Hono into compiled projects. Older ranges covered the vulnerable window. Recompile to pick up the fix in your generated project's `package.json`.
1381
1250
 
1382
- No config changes required — recompile to pick up the fixes.
1251
+ ### Cloudflare Email Sending in public beta
1383
1252
 
1384
- ### CMS Admin Gate Now Enforced Server-Side
1253
+ Quickback defaults to the Workers `send_email` binding for Cloudflare deploys. Cloudflare Email Sending has graduated to public beta — production-ready with zero-config. AWS SES remains a fully supported opt-in (`email.provider: 'aws-ses'`) for non-Cloudflare runtimes. See [Email Configuration](/compiler/config#email-configuration).
1385
1254
 
1386
- `cms: { access: "admin" }` previously only hid the CMS link in Account UI and rendered an "Access Denied" screen inside the SPA — the static assets, `/api/v1/schema`, and `/api/v1/custom_view` CRUD were reachable by any authenticated user. A non-admin with an API token or cookie could bypass the UI and read schema metadata or saved CMS views directly.
1255
+ ### Dependency sweep
1387
1256
 
1388
- This release adds server-side enforcement at every CMS-facing surface:
1257
+ `wrangler@^4.83.0`, `drizzle-orm@^0.45.2`, `drizzle-kit@^0.31.10`, `zod@^4.3.6`, `@cloudflare/workers-types@^4.20260417.1`.
1389
1258
 
1390
- - **CMS SPA shell** — the Worker checks `ctx.userRole === "admin"` before serving `index.html`. Unauthenticated requests redirect to login; authenticated non-admins get `403 Admin access required`. Static bundles (JS/CSS) remain reachable so browser caches aren't invalidated.
1391
- - **`/api/v1/schema`** — returns `403` to non-admins.
1392
- - **`custom_view` CRUD** — now gated on the new `userRole: ["admin"]` primitive rather than org membership.
1393
- - **In-SPA gate** — unchanged; defense in depth behind the server-side gates.
1259
+ ---
1394
1260
 
1395
- Your resource CRUD endpoints are unaffected — they keep their per-resource `crud.access.roles`.
1261
+ ## v0.8.5 — April 15, 2026
1396
1262
 
1397
- ### New `userRole` Access Primitive
1263
+ ### `userRole` access primitive
1398
1264
 
1399
- Added `userRole?: string[]` to the declarative `Access` config, evaluated against `ctx.userRole` (the Better Auth admin-plugin `user.role` column). This is distinct from `roles`, which matches `ctx.roles` (org membership).
1265
+ A new `userRole?: string[]` field in the declarative `Access` config evaluates against `ctx.userRole` (the Better Auth admin-plugin `user.role` column). Distinct from `roles`, which matches `ctx.roles` (org membership).
1400
1266
 
1401
1267
  ```typescript
1402
- // Old: in multi-tenant this meant org-admin, not platform-admin
1403
- access: { roles: ['admin'] }
1404
-
1405
- // New: explicitly require user.role === 'admin' regardless of org membership
1406
- access: { userRole: ['admin'] }
1407
-
1408
- // "Org owner OR platform admin"
1268
+ // Org owner OR platform admin
1409
1269
  access: { or: [{ roles: ['owner'] }, { userRole: ['admin'] }] }
1410
1270
 
1411
1271
  // Platform admins see SSNs across every org
1412
1272
  masking: { ssn: { type: 'ssn', show: { userRole: ['admin'] } } }
1413
1273
  ```
1414
1274
 
1415
- `userRole` works everywhere `Access` is accepted — CRUD, actions, views, masking, and inside `or`/`and` combinators. See [Access - userRole vs roles](/compiler/definitions/access#userrole-vs-roles).
1416
-
1417
- ### Fix: `ReferenceError: customAlphabet is not defined` in generated POST handlers
1418
-
1419
- Projects with `providers.database.config.generateId: "short"` (or `"nanoid"` / `"cuid"`) compiled routes that called the ID helper but never imported it. Every generated `src/features/**/*.routes.ts` had `customAlphabet('0123...', 6)()` in its POST body but no matching `import { customAlphabet } from 'nanoid';` at the top of the file. Every `POST /api/v1/<resource>` and batch-create returned `500` with `ReferenceError: customAlphabet is not defined` on the first write.
1420
-
1421
- The compiler now emits the correct import alongside the ID expression for all three modes: `nanoid`, `customAlphabet`, and `createId` from `@paralleldrive/cuid2`.
1422
-
1423
- No config changes required — recompile to pick up the fix.
1424
-
1425
- ### Fix: Dangling `export const` in generated `actions.ts` breaks `tsc`
1426
-
1427
- When a feature authored actions as `export const xActions = defineActions(...)` (instead of `export default defineActions(...)`), the compiler's preamble extractor leaked the assignment's left-hand side into the generated `src/features/<feature>/actions.ts`. The output contained a dangling `export const xActions =` with no right-hand side, and `tsc --noEmit` failed with `TS1109: Expression expected`. Runtime happened to work because the unused placeholder was never evaluated, but typecheck was red.
1428
-
1429
- The preamble extractor now anchors its boundary to the start of the top-level statement containing `defineActions(...)`, covering `export default`, `export const X =`, `const X =`, and bare call forms. Local Zod helper declarations above the call continue to be preserved.
1430
-
1431
- ### Fix: Files worker `database_id` reverted to `"local-files"` on every compile
1432
-
1433
- Projects using the two-worker R2 architecture had their files worker's `wrangler.toml` (`apps/backend/cloudflare-workers/files/wrangler.toml`) rewritten with `database_id = "local-files"` on every `quickback compile`, even when `providers.database.config.filesDatabaseId` was set to a real D1 UUID. The main worker's binding was correct — only the files worker fell through. Remote deploys of the files worker bound to a non-existent D1, so file serving and access-control reads failed with a binding error.
1434
-
1435
- The files-worker wrangler generator now reads `filesDatabaseId` (and `filesDatabaseName`) from `providers.database.config` as a fallback when they aren't set on `providers.fileStorage.config`, matching the precedence chain already used by the main worker. Local dev is unaffected — `wrangler dev --local` uses `.wrangler/state/` regardless of the configured ID.
1436
-
1437
- No config changes required — recompile and redeploy the files worker.
1438
-
1439
- ---
1440
-
1441
- ## v0.8.6 — April 16, 2026
1442
-
1443
- ### Fix: Audit columns silently dropped from tables with a same-line index callback
1444
-
1445
- Tables authored with the composite-index shape Drizzle / prettier produces —
1446
-
1447
- ```ts
1448
- export const episodeTags = sqliteTable("episode_tags", {
1449
- id: text("id").primaryKey(),
1450
- episodeId: text("episode_id").notNull(),
1451
- tagId: text("tag_id").notNull(),
1452
- }, (t) => [ // <-- "}, (t) =>" on one line
1453
- uniqueIndex("episode_tag_unique").on(t.episodeId, t.tagId),
1454
- ]);
1455
- ```
1456
-
1457
- never received audit field injection. A regex in `injectAuditFields` required a literal `\n` between the columns-object `},` and the `(t) =>` index callback, so same-line closers were silently skipped and the function returned the source unchanged. drizzle-kit then diffed the audit-less schema against the previous snapshot and emitted `ALTER TABLE ... DROP COLUMN created_at/modified_at/deleted_at/created_by/modified_by/deleted_by` for every affected table. Any project that applied those migrations had production CRUD return `500` because the generated firewall helper still referenced `deletedAt`.
1458
-
1459
- The regex is now whitespace-flexible and the identifier class accepts any valid JS identifier (`t`, `table`, `_t`, `tbl2`). A defensive guard throws at compile time if all three terminator patterns fail on a recognizable Drizzle table — no more silent drops.
1460
-
1461
- **Recovery path:**
1462
-
1463
- - Most projects: recompile. drizzle-kit will detect the audit columns are missing from the DB snapshot and emit an `ADD COLUMN` migration to restore them. Apply it.
1464
- - Projects that already hand-patched their schema and ran a manual `ADD COLUMN` migration (like the `podcast-app` workaround in commit `98d8758`): the next compile will regenerate a matching `ADD COLUMN` migration that will fail with "duplicate column name" against a DB that already has the columns. Mark the new migration as applied without running it (e.g. `INSERT INTO __drizzle_migrations` in the features DB) or hand-edit the generated SQL to a no-op, then continue normally.
1465
-
1466
- ### Fix: `firewall.exception` generated `isNull(<table>.deletedAt)` against a missing column
1275
+ `userRole` works everywhere `Access` is accepted — CRUD, actions, views, masking, and inside `or` / `and` combinators. See [Access → userRole vs roles](/compiler/definitions/access#userrole-vs-roles).
1467
1276
 
1468
- Resources with `firewall: { exception: true }` always emitted `return isNull(<table>.deletedAt);` inside `buildFirewallConditions()`, regardless of whether the table actually had a `deletedAt` column. Projects that disabled audit injection globally (`compiler.features.auditFields: false`) or authored a schema without `deletedAt` ended up with Drizzle resolving `<table>.deletedAt` to `undefined` at query time — every `GET /api/v1/<resource>` returned `500`.
1277
+ ### CMS admin gate enforced server-side
1469
1278
 
1470
- The three concerns are now fully independent:
1279
+ `cms: { access: "admin" }` previously only hid the CMS link in Account UI and rendered an "Access Denied" screen inside the SPA. Server-side enforcement now applies at every CMS-facing surface: the SPA shell, `/api/v1/schema`, and `custom_view` CRUD.
1471
1280
 
1472
- - **`firewall.exception: true`** — only disables tenant scoping (org/user/team `WHERE` clauses). It does not gate audit fields or soft-delete.
1473
- - **Audit fields** — always injected unless globally opted out. Unchanged.
1474
- - **Soft-delete filter** — emitted only when the schema actually has `deletedAt` *or* the user explicitly set `firewall.softDelete`.
1281
+ ### Better Auth 1.5 + `@cloudflare/workers-types` compatibility
1475
1282
 
1476
- In the default configuration (audit injection on), behavior is unchanged: exception resources still filter `deletedAt IS NULL`. Only the broken case changes — exception resources on a schema without `deletedAt` now return `undefined` (no firewall), matching the column reality.
1477
-
1478
- No config changes required — recompile to pick up the fix.
1283
+ Generated API code typechecks against the new versions. The org-member role-change broadcast hook is emitted via `organizationHooks.afterUpdateMemberRole` (the supported shape after the 1.5 deprecation of `databaseHooks.member.update.after`). `REALTIME_URL` and `ACCESS_TOKEN` are always emitted as optional bindings when the organization plugin is active.
1479
1284
 
1480
1285
  ---
1481
1286
 
1482
1287
  ## v0.8.4 — April 14, 2026
1483
1288
 
1484
- ### New `generateId: "short"` Strategy
1289
+ ### `generateId: "short"` strategy
1485
1290
 
1486
- Added a compact ID option for tables where short, shareable codes matter more than collision resistance at scale:
1291
+ A compact ID option for tables where short, shareable codes matter more than collision resistance at scale:
1487
1292
 
1488
1293
  ```typescript
1489
1294
  providers: {
1490
- database: defineDatabase("cloudflare-d1", {
1491
- generateId: "short",
1492
- }),
1295
+ database: defineDatabase("cloudflare-d1", { generateId: "short" }),
1493
1296
  }
1494
1297
  ```
1495
1298
 
1496
- Generates 6-character alphanumeric IDs (e.g. `a3F9xK`) using nanoid's `customAlphabet` with the full 62-char alphabet (`0-9A-Za-z`). Requires the `nanoid` package in your project (same as the existing `"nanoid"` strategy).
1497
-
1498
- **When to use:** room codes, invite links, share URLs, ephemeral records — anywhere the ID appears in a URL or needs to be human-typeable.
1499
-
1500
- **When not to use:** high-volume tables. 62^6 ≈ 56.8B combinations means ~238K rows before a 50% collision probability (birthday bound). For large tables stick with `"uuid"`, `"cuid"`, or `"prefixed"`.
1501
-
1502
- See [Providers - ID Generation Options](/compiler/config/providers#id-generation-options) for the full list of strategies.
1503
-
1504
- ---
1505
-
1506
- ## v0.8.3 — April 14, 2026
1507
-
1508
- ### Fix: `wrangler.toml` Route Placement and Binding IDs
1509
-
1510
- Two bugs in the generated `wrangler.toml` that blocked production deployment without manual edits:
1511
-
1512
- **Routes were nested under `[dev]`.** The `routes = [...]` array was emitted after the `[dev]` section header, so TOML parsed it as `dev.routes` and wrangler ignored the custom domain (warning: `Unexpected fields found in dev field: "routes"`). Routes now emit as a top-level key.
1513
-
1514
- **D1 and KV bindings used placeholder IDs.** Despite `databaseId`, `filesDatabaseId`, and `kvId` being set in the quickback config, the generated `wrangler.toml` wrote `"local-features"`, `"local-files"`, and `"local"` instead of the real UUIDs. The compiler now resolves IDs from multiple config sources:
1515
-
1516
- | Binding | Config sources checked (in order) |
1517
- |---------|-----------------------------------|
1518
- | `AUTH_DB` | `database.config.authDatabaseId` |
1519
- | `DB` | `database.config.featuresDatabaseId`, `database.config.databaseId` |
1520
- | `FILES_DB` | `fileStorage.config.filesDatabaseId`, `database.config.filesDatabaseId` |
1521
- | `KV` | `database.config.kvNamespaceId`, `storage.config.namespaceId`, `auth.config.kvId` |
1522
-
1523
- See [Providers - Database Options](/compiler/config/providers#database-options) for the full list of supported ID properties.
1299
+ Generates 6-character alphanumeric IDs (e.g. `a3F9xK`) using nanoid's `customAlphabet` with the full 62-char alphabet (`0-9A-Za-z`). Requires the `nanoid` package.
1524
1300
 
1525
- ### Fix: Account SPA Post-Login Redirect on Unified Domain
1301
+ **When to use:** room codes, invite links, share URLs, ephemeral records.
1526
1302
 
1527
- When the Account SPA was served at `/account/` on the unified quickback domain (e.g. `secure.example.com/account/`), post-login redirects dropped the basepath and sent users to `/dashboard` instead of `/account/dashboard`. Sign-out redirects had the same issue.
1528
-
1529
- The SPA now shares a basepath module across the router and all raw `window.location.href` assignments, so login, signup, email OTP, welcome, and sign-out flows all stay under the correct path prefix regardless of whether the SPA is on the unified domain or its own dedicated auth subdomain.
1530
-
1531
- No config changes required — recompile to pick up the fix.
1303
+ **When not to use:** high-volume tables. 62^6 ≈ 56.8B combinations means ~238K rows before a 50% collision probability. For large tables stick with `"uuid"`, `"cuid"`, or `"prefixed"`. See [Providers → ID Generation Options](/compiler/config/providers#id-generation-options).
1532
1304
 
1533
1305
  ---
1534
1306
 
1535
1307
  ## v0.8.2 — April 11, 2026
1536
1308
 
1537
- ### Catch-All `VITE_QUICKBACK_URL` Environment Variable
1309
+ ### Catch-all `VITE_QUICKBACK_URL`
1538
1310
 
1539
- Instead of setting four separate URL env vars, you can now point at a single Quickback origin:
1311
+ A single Quickback origin can be set in place of four separate URL env vars:
1540
1312
 
1541
1313
  ```bash
1542
- # One variable — done.
1543
1314
  VITE_QUICKBACK_URL=https://secure.example.com
1544
1315
  ```
1545
1316
 
1546
- When set, it's used as a fallback for the individual URLs:
1547
-
1548
1317
  | Individual var (explicit) | Fallback when unset |
1549
1318
  |---|---|
1550
1319
  | `VITE_QUICKBACK_API_URL` | `${VITE_QUICKBACK_URL}` |
1551
1320
  | `VITE_QUICKBACK_ACCOUNT_URL` | `${VITE_QUICKBACK_URL}/account` |
1552
1321
  | `VITE_QUICKBACK_CMS_URL` | `${VITE_QUICKBACK_URL}/cms` |
1553
1322
 
1554
- `VITE_QUICKBACK_APP_URL` stays independent — it points at the tenant's own frontend, not the Quickback server.
1555
-
1556
- **Non-breaking.** Individual vars still take precedence when set, so existing configurations work unchanged. The compiler now also emits `VITE_QUICKBACK_URL` into the generated SPA `.env` files, and library users can set `__QUICKBACK_URL__` on `globalThis` for the same effect.
1557
-
1558
- See [Environment Variables](/stack/account-ui/environment-variables) for the full reference.
1323
+ `VITE_QUICKBACK_APP_URL` stays independent — it points at the tenant's own frontend. Non-breaking; individual vars take precedence when set. Library users can set `__QUICKBACK_URL__` on `globalThis`. See [Environment Variables](/stack/account-ui/environment-variables).
1559
1324
 
1560
1325
  ---
1561
1326
 
1562
1327
  ## v0.8.1 — April 9, 2026
1563
1328
 
1564
- ### Role Hierarchy with `+` Suffix
1329
+ ### Role hierarchy with `+` suffix
1565
1330
 
1566
- You can now define a role hierarchy in your config and use the `+` suffix in access rules to mean "this role and above":
1331
+ Define a hierarchy and use `+` to mean "this role and above":
1567
1332
 
1568
1333
  ```typescript
1569
- // quickback.config.ts
1570
- auth: {
1571
- roleHierarchy: ['member', 'admin', 'owner'],
1572
- }
1334
+ auth: { roleHierarchy: ['member', 'admin', 'owner'] }
1573
1335
 
1574
- // In resource definitions
1575
1336
  crud: {
1576
1337
  list: { access: { roles: ["member+"] } }, // member, admin, owner
1577
1338
  create: { access: { roles: ["admin+"] } }, // admin, owner
@@ -1579,15 +1340,15 @@ crud: {
1579
1340
  }
1580
1341
  ```
1581
1342
 
1582
- Roles are expanded at compile time. No `+` = exact match. See [Access - Role Hierarchy](/compiler/definitions/access#role-hierarchy) for details.
1343
+ Roles are expanded at compile time. No `+` = exact match. See [Access → Role Hierarchy](/compiler/definitions/access#role-hierarchy).
1583
1344
 
1584
1345
  ---
1585
1346
 
1586
1347
  ## v0.8.0 — April 9, 2026
1587
1348
 
1588
- ### Breaking: VITE URL Environment Variables Renamed
1349
+ ### Breaking: VITE URL environment variables namespaced
1589
1350
 
1590
- All Quickback-generated URL environment variables are now namespaced under `VITE_QUICKBACK_*` to avoid collisions with other Vite projects.
1351
+ All Quickback-generated URL environment variables are namespaced under `VITE_QUICKBACK_*` to avoid collisions with other Vite projects.
1591
1352
 
1592
1353
  | Old | New |
1593
1354
  |-----|-----|
@@ -1596,129 +1357,58 @@ All Quickback-generated URL environment variables are now namespaced under `VITE
1596
1357
  | `VITE_APP_URL` | `VITE_QUICKBACK_APP_URL` |
1597
1358
  | `VITE_CMS_URL` | `VITE_QUICKBACK_CMS_URL` |
1598
1359
 
1599
- **Non-URL variables are unchanged:** `VITE_ENABLE_*` feature flags, branding vars (`VITE_APP_NAME`, etc.), and `VITE_STRIPE_PUBLISHABLE_KEY` stay as-is.
1360
+ Non-URL variables are unchanged (`VITE_ENABLE_*`, branding vars, `VITE_STRIPE_PUBLISHABLE_KEY`).
1600
1361
 
1601
1362
  **Action required:**
1602
- - **Compiled projects** — re-run `quickback compile`. The compiler generates the new names automatically.
1603
- - **Standalone deploys** — update `.env`, `.env.production`, and `wrangler.toml` files manually.
1604
- - **Library users** — the `__QUICKBACK_API_URL__` / `__QUICKBACK_APP_URL__` globalThis names are unchanged, but if you pipe Vite env vars into them, update the var names.
1605
-
1606
- See [Environment Variables](/stack/account-ui/environment-variables) for the full reference.
1607
-
1608
- ### CMS Access Control
1609
-
1610
- The `cms.access` config option now enforces access at the CMS level, not just link visibility in Account UI.
1611
-
1612
- ```typescript
1613
- cms: { access: "admin" }
1614
- ```
1615
-
1616
- When set to `"admin"`, non-admin users (`user.role !== "admin"`) see an "Access Denied" screen with a sign-out button instead of the CMS. When set to `"user"` (the default), any authenticated user can access the CMS.
1363
+ - Compiled projects: re-run `quickback compile`.
1364
+ - Standalone deploys: update `.env`, `.env.production`, and `wrangler.toml` files manually.
1365
+ - Library users: `__QUICKBACK_API_URL__` / `__QUICKBACK_APP_URL__` globals are unchanged.
1617
1366
 
1618
- See [CMS Connecting](/stack/cms/connecting) and [Compiler Config](/compiler/config) for details.
1367
+ ### CMS access control
1619
1368
 
1620
- ### SPA Sub-Route Fix
1621
-
1622
- Fixed a bug where hard-refreshing or directly navigating to SPA sub-routes (e.g., `/account/profile`, `/cms/tables/users`) returned a blank white screen. The Worker now correctly serves `index.html` for all SPA paths, allowing the client-side router to handle routing.
1369
+ `cms.access: "admin"` enforces access at the CMS level, not just link visibility. Non-admin users (`user.role !== "admin"`) see an "Access Denied" screen with a sign-out button.
1623
1370
 
1624
1371
  ---
1625
1372
 
1626
1373
  ## v0.5.11 — February 24, 2026
1627
1374
 
1628
- ### Email OTP & Auth Fixes
1629
-
1630
- - Fixed email-OTP magic links not working correctly
1631
- - Removed deprecated `/internal/validate` endpoint — use standard Better Auth session validation instead
1632
- - Auth is now required for all API routes when running locally (previously some routes were unprotected in dev)
1633
-
1634
- ### Multiple Table Exports Fix
1635
-
1636
- - Fixed a compiler error when a single file exports multiple Drizzle tables alongside a `defineTable()` default export
1637
- - The CLI now properly detects and reports this with a clear error message pointing to the fix
1638
-
1639
- ### Headless Drizzle Rename Hints
1640
-
1641
- - Added `compiler.migrations.renames` configuration for CI/CD environments where Drizzle's interactive rename prompts would block compilation
1642
- - Compile errors now include explicit rename key paths and fail fast on malformed rename config keys
1643
- - See [Configuration](/compiler/config) for details
1644
-
1645
- ### Security Contract Report Artifacts
1375
+ ### Mandatory unsafe action audit trail
1646
1376
 
1647
- - Added generated security contract artifacts to compiler output:
1648
- - `reports/security-contracts.report.json`
1649
- - `reports/security-contracts.report.sig.json`
1650
- - Added config-driven signing controls:
1651
- - `compiler.securityContracts.report.signature.enabled`
1652
- - `compiler.securityContracts.report.signature.required`
1653
- - `compiler.securityContracts.report.signature.key` / `keyEnv` / `keyId`
1654
- - Missing required signing keys now fail loudly with explicit remediation guidance
1655
- - Added strict config validation for report/signature paths and signing options
1377
+ Structured `unsafe` config (`unsafe: { reason, adminOnly, crossTenant, targetScope }`). Cross-tenant unsafe actions require Better Auth authentication plus platform admin role (`ctx.userRole === "admin"`). Mandatory audit logging on success, denial, and error paths. Cloudflare output includes `AUDIT_DB` wiring, `drizzle.audit.config.ts`, and `db:migrate:audit:*` scripts when unsafe actions are present.
1656
1378
 
1657
- ### Mandatory Unsafe Action Audit Trail
1379
+ Compile-time raw SQL guard for actions and handlers (`allowRawSql: true` required per action).
1658
1380
 
1659
- - Added structured unsafe action config (`unsafe: { reason, adminOnly, crossTenant, targetScope }`)
1660
- - Cross-tenant unsafe actions now require Better Auth authentication plus platform admin role (`ctx.userRole === "admin"`)
1661
- - Added mandatory audit logging for unsafe cross-tenant actions (success, denial, and error paths)
1662
- - Cloudflare output now includes optional `AUDIT_DB` wiring, `drizzle.audit.config.ts`, and `db:migrate:audit:*` scripts when unsafe actions are present
1663
- - Added compile-time raw SQL guard for actions and handlers (`allowRawSql: true` required per action)
1381
+ ### Security contract report artifacts
1664
1382
 
1665
- ---
1666
-
1667
- ## v0.5.10 — February 19, 2026
1668
-
1669
- ### Compiler Page Parsing & CLI Output
1670
-
1671
- - Improved compiler page parsing for `definePage()` definitions
1672
- - Better CLI output formatting during compilation
1673
- - Added `apiPath` to schema registry for CMS integration
1383
+ Generated security contract artifacts: `reports/security-contracts.report.json`, `reports/security-contracts.report.sig.json`. Config-driven signing controls (`compiler.securityContracts.report.signature.*`). Missing required signing keys fail loudly with explicit remediation.
1674
1384
 
1675
- ### Bug Fixes
1385
+ ### Headless Drizzle rename hints
1676
1386
 
1677
- - Fixed hyphenated action names not being properly quoted in generated code (e.g., `mark-complete` now generates valid JavaScript)
1678
- - API key authentication (`x-api-key` header) is now handled separately from session tokens (`Bearer` header)
1387
+ `compiler.migrations.renames` configuration for CI/CD environments where Drizzle's interactive rename prompts block compilation. See [Configuration](/compiler/config).
1679
1388
 
1680
- ---
1681
-
1682
- ## v0.5.9 — February 16, 2026
1389
+ ### Minor
1683
1390
 
1684
- ### CMS Pages & CLI Page Support
1685
-
1686
- - Added `definePage()` support for CMS-managed pages
1687
- - Auth middleware improvements for page routes
1688
- - CLI now supports page definitions alongside table and action definitions
1391
+ - Email OTP magic links work correctly.
1392
+ - Auth is required for all API routes when running locally.
1393
+ - Single-file multi-table exports alongside `defineTable()` produce a clear error.
1689
1394
 
1690
1395
  ---
1691
1396
 
1692
1397
  ## v0.5.8 — February 14, 2026
1693
1398
 
1694
- ### CMS App
1695
-
1696
- - Introduced the Quickback CMS — a schema-driven admin panel that connects to your generated API
1697
- - CMS namespace added to actions for admin-specific operations
1698
- - Fixed `guard` → `access` naming inconsistency in CMS action definitions
1399
+ ### Quickback CMS
1699
1400
 
1700
- ### Schema Registry & Firewall Improvements
1701
-
1702
- - Added schema registry generator — the compiler now outputs a JSON schema registry used by the CMS
1703
- - Firewall error modes: choose between `reveal` (403 with details) and `hide` (opaque 404) for security-sensitive deployments
1704
-
1705
- ### Bug Fixes
1706
-
1707
- - Fixed anonymous user email format generation
1708
- - Organization selector improvements in Account UI
1709
- - Config validation now catches more errors at compile time
1710
- - Better CRUD error handling with structured error responses
1711
- - Fixed masking to use representative star counts instead of fixed formatting
1401
+ A schema-driven admin panel that connects to your generated API. The compiler now outputs a JSON schema registry consumed by the CMS at runtime. Firewall error modes (`reveal` for 403 with details, `hide` for opaque 404) are configurable per resource for security-sensitive deployments.
1712
1402
 
1713
1403
  ---
1714
1404
 
1715
1405
  ## v0.5.7 — February 12, 2026
1716
1406
 
1717
- ### Scoped Database for Actions
1407
+ ### Scoped database for actions
1718
1408
 
1719
- Actions now receive a **security-scoped database** instead of a raw Drizzle instance. The compiler generates a proxy wrapper that automatically enforces org isolation, owner filtering, and soft-delete visibility — the same protections that CRUD routes have always had.
1409
+ Actions receive a security-scoped database instead of a raw Drizzle instance. The compiler generates a proxy wrapper that automatically enforces org isolation, owner filtering, and soft-delete visibility — the same protections that CRUD routes have always had.
1720
1410
 
1721
- The scoped DB uses duck-typed column detection at runtime:
1411
+ Duck-typed column detection at runtime:
1722
1412
 
1723
1413
  | Column Detected | SELECT / UPDATE / DELETE | INSERT |
1724
1414
  |---|---|---|
@@ -1726,24 +1416,9 @@ The scoped DB uses duck-typed column detection at runtime:
1726
1416
  | `ownerId` | Adds `WHERE ownerId = ?` | Auto-injects `ownerId` from context |
1727
1417
  | `deletedAt` | Adds `WHERE deletedAt IS NULL` | — |
1728
1418
 
1729
- This means **every action is secure by default** — no manual `WHERE` clauses needed.
1419
+ Every action is secure by default — no manual `WHERE` clauses needed.
1730
1420
 
1731
- ```typescript
1732
- defineActions(todos, {
1733
- complete: {
1734
- type: "record",
1735
- execute: async ({ db, ctx, record, input }) => {
1736
- // db is scoped — only sees records in user's org, excludes soft-deleted
1737
- const siblings = await db.select().from(todos);
1738
- // ↑ automatically filtered to ctx.activeOrgId + deletedAt IS NULL
1739
- },
1740
- },
1741
- });
1742
- ```
1743
-
1744
- #### Unsafe Mode
1745
-
1746
- Actions that intentionally need to bypass security (admin reports, cross-org queries, migrations) can declare `unsafe: true` to receive a raw, unscoped database handle:
1421
+ Actions that intentionally need to bypass security (admin reports, cross-org queries, migrations) can declare `unsafe: true` to receive a raw, unscoped database handle via `rawDb`:
1747
1422
 
1748
1423
  ```typescript
1749
1424
  defineActions(analytics, {
@@ -1758,108 +1433,45 @@ defineActions(analytics, {
1758
1433
  });
1759
1434
  ```
1760
1435
 
1761
- Without `unsafe: true`, `rawDb` is `undefined`.
1762
-
1763
- **Related docs:** [Actions](/compiler/definitions/actions), [Actions API](/compiler/targets/hono-api/using-the-api/actions-api)
1436
+ Without `unsafe: true`, `rawDb` is `undefined`. See [Actions](/compiler/definitions/actions).
1764
1437
 
1765
- ---
1766
-
1767
- ### Cascading Soft Delete
1438
+ ### Cascading soft delete
1768
1439
 
1769
- Soft-deleting a parent record now **automatically cascades** to child and junction tables within the same feature. The compiler detects foreign key references at build time and generates cascade UPDATE statements.
1770
-
1771
- ```
1772
- DELETE /api/v1/projects/:id
1773
- ```
1774
-
1775
- Generated behavior:
1776
- ```typescript
1777
- // 1. Soft delete the parent
1778
- await db.update(projects)
1779
- .set({ deletedAt: now, deletedBy: userId })
1780
- .where(eq(projects.id, id));
1781
-
1782
- // 2. Auto-cascade to children (compiler-generated)
1783
- await db.update(projectMembers)
1784
- .set({ deletedAt: now, deletedBy: userId })
1785
- .where(eq(projectMembers.projectId, id));
1786
-
1787
- await db.update(projectTasks)
1788
- .set({ deletedAt: now, deletedBy: userId })
1789
- .where(eq(projectTasks.projectId, id));
1790
- ```
1440
+ Soft-deleting a parent record automatically cascades to child and junction tables within the same feature. The compiler detects foreign key references at build time and generates cascade `UPDATE` statements.
1791
1441
 
1792
1442
  Rules:
1793
- - Only applies to **soft delete** (the default). Hard delete relies on database-level `ON DELETE CASCADE`.
1794
- - Only cascades within the **same feature** — cross-feature references are not affected.
1795
- - Child tables must have `deletedAt` / `deletedBy` columns (auto-added by the compiler's audit fields).
1443
+ - Applies to soft delete only. Hard delete relies on database-level `ON DELETE CASCADE`.
1444
+ - Cascades within the same feature only — cross-feature references are not affected.
1445
+ - Child tables must have `deletedAt` / `deletedBy` columns (auto-added by the compiler).
1796
1446
 
1797
- **Related docs:** [Actions API — Cascading Soft Delete](/compiler/targets/hono-api/using-the-api/actions-api#cascading-soft-delete)
1447
+ See [Actions API → Cascading Soft Delete](/compiler/targets/hono-api/using-the-api/actions-api#cascading-soft-delete).
1798
1448
 
1799
- ---
1800
-
1801
- ### Advanced Query Parameters
1449
+ ### Advanced query parameters
1802
1450
 
1803
- New query parameter capabilities for all list endpoints:
1451
+ New capabilities for all list endpoints:
1804
1452
 
1805
- - **Field selection** — `?fields=id,name,status` returns only the columns you need
1806
- - **Multi-sort** — `?sort=status:asc,createdAt:desc` sorts by multiple fields
1807
- - **Total count** — `?count=true` returns total matching records in response headers (`X-Total-Count`)
1453
+ - **Field selection** — `?fields=id,name,status`
1454
+ - **Multi-sort** — `?sort=status:asc,createdAt:desc`
1455
+ - **Total count** — `?count=true` returns total matching records in `X-Total-Count`
1808
1456
  - **Full-text search** — `?search=keyword` searches across all text columns
1809
1457
 
1810
- ```bash
1811
- # Get only names and statuses, sorted by status then date, with total count
1812
- GET /api/v1/todos?fields=id,name,status&sort=status:asc,createdAt:desc&count=true
1813
-
1814
- # Search across all text fields
1815
- GET /api/v1/todos?search=urgent
1816
- ```
1817
-
1818
- **Related docs:** [Query Parameters](/compiler/targets/hono-api/using-the-api/query-params)
1819
-
1820
- ---
1821
-
1822
- ### Audit Field Improvements
1823
-
1824
- - `deletedAt` and `deletedBy` fields are now **always injected** by the compiler for tables with soft delete enabled — no need to define them in your schema
1825
- - All audit fields (`createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`) are auto-managed
1826
-
1827
- ---
1828
-
1829
- ## v0.5.6 — February 8, 2026
1830
-
1831
- ### Database Naming Conventions
1832
-
1833
- - Default table and column naming changed to **snake_case** with `usePlurals: false`
1834
- - Table names derived from generated Better Auth schema for consistency
1835
- - Removed legacy single-database mode — split databases (auth + features) is now the standard
1836
-
1837
- ### Auth Variable Shadowing Fix
1838
-
1839
- - Fixed `member` variable in auth middleware that shadowed the Drizzle `member` table import
1840
- - Renamed to `sessionMember` to avoid conflicts in generated routes
1458
+ See [Query Parameters](/compiler/targets/hono-api/using-the-api/query-params).
1841
1459
 
1842
1460
  ---
1843
1461
 
1844
1462
  ## v0.5.5 — February 5, 2026
1845
1463
 
1846
- ### Better Auth Plugins
1464
+ ### OpenAPI spec generation
1847
1465
 
1848
- - Published `@quickback-dev/better-auth-upgrade-anonymous` v1.1.0 — post-passkey email collection flow
1849
- - Published `@quickback-dev/better-auth-combo-auth` — combined email + password + OTP authentication
1850
- - Published `@quickback-dev/better-auth-aws-ses` — AWS SES email provider for Better Auth
1466
+ Generated APIs include a full OpenAPI specification at `/openapi.json`. Better Auth endpoints are included in the spec.
1851
1467
 
1852
- ### OpenAPI Spec Generation
1468
+ ### Better Auth plugins
1853
1469
 
1854
- - Generated APIs now include a full OpenAPI specification at `/openapi.json`
1855
- - Better Auth endpoints included in the spec
1856
- - Runtime route: `GET /openapi.json`
1470
+ Published `@quickback-dev/better-auth-upgrade-anonymous` (post-passkey email collection flow), `@quickback-dev/better-auth-combo-auth` (combined email + password + OTP), and `@quickback-dev/better-auth-aws-ses` (AWS SES email provider).
1857
1471
 
1858
- ### Security Hardening
1472
+ ### Security headers
1859
1473
 
1860
- - Global error handler prevents leaking internal error details
1861
- - Security headers middleware (CSP, HSTS, X-Frame-Options, X-Content-Type-Options)
1862
- - `BETTER_AUTH_SECRET` properly passed to generated config
1474
+ Global error handler prevents leaking internal error details. Security headers middleware (CSP, HSTS, X-Frame-Options, X-Content-Type-Options). `BETTER_AUTH_SECRET` properly passed to generated config.
1863
1475
 
1864
1476
  ---
1865
1477
 
@@ -1867,34 +1479,28 @@ GET /api/v1/todos?search=urgent
1867
1479
 
1868
1480
  ### Account UI
1869
1481
 
1870
- - Pre-built authentication UI deployed as Cloudflare Workers
1871
- - Features: sessions, organizations, passkeys, passwordless, admin panel, API keys
1872
- - Dual-mode: standalone (degit template) or embedded with Quickback projects
1482
+ Pre-built authentication UI deployed as Cloudflare Workers. Sessions, organizations, passkeys, passwordless, admin panel, API keys. Dual-mode: standalone (degit template) or embedded with Quickback projects.
1873
1483
 
1874
- ### Webhook System
1484
+ ### Webhook system
1875
1485
 
1876
- - Inbound webhook endpoints with signature verification
1877
- - Outbound webhooks via Cloudflare Queues with automatic retries
1878
- - Configurable per-feature webhook events
1486
+ Inbound webhook endpoints with signature verification. Outbound webhooks via Cloudflare Queues with automatic retries. Configurable per-feature webhook events.
1879
1487
 
1880
- ### Realtime & Vector Search
1488
+ ### Realtime & vector search
1881
1489
 
1882
- - Durable Objects + WebSocket realtime subscriptions
1883
- - Vector embeddings via Cloudflare Vectorize
1884
- - KV and R2 storage integrations
1490
+ Durable Objects + WebSocket realtime subscriptions. Vector embeddings via Cloudflare Vectorize. KV and R2 storage integrations.
1885
1491
 
1886
1492
  ---
1887
1493
 
1888
1494
  ## v0.5.0 — January 2026
1889
1495
 
1890
- ### Initial Release
1891
-
1892
- - **Quickback Compiler** — TypeScript-first backend compiler
1893
- - **Four Security Pillars** — Firewall, Access, Guards, Masking
1894
- - **`defineTable()`** — Schema + security configuration in a single file
1895
- - **Templates** — Cloudflare Workers, Bun standalone, B2B SaaS
1896
- - **Cloud Compiler** — Remote compilation via `compiler.quickback.dev`
1897
- - **CLI** — `quickback create`, `quickback compile`, `quickback init`
1898
- - **Better Auth Integration** — Organizations, roles, sessions
1899
- - **Drizzle ORM** — Schema-first with automatic migrations
1900
- - **Cloudflare D1** — Split database support (auth + features)
1496
+ ### Initial release
1497
+
1498
+ - **Quickback Compiler** — TypeScript-first backend compiler.
1499
+ - **Four security pillars** — Firewall, Access, Guards, Masking.
1500
+ - **`defineTable()`** — schema + security configuration in a single file.
1501
+ - **Templates** — Cloudflare Workers, B2B SaaS.
1502
+ - **Cloud compiler** — remote compilation via `compiler.quickback.dev`.
1503
+ - **CLI** — `quickback create`, `quickback compile`.
1504
+ - **Better Auth integration** — organizations, roles, sessions.
1505
+ - **Drizzle ORM** — schema-first with automatic migrations.
1506
+ - **Cloudflare D1** — split database support (auth + features).