@quickback-dev/cli 0.34.3 → 0.39.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 (130) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +36 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/compile.test.d.ts +2 -0
  5. package/dist/commands/compile.test.d.ts.map +1 -0
  6. package/dist/commands/compile.test.js +83 -0
  7. package/dist/commands/compile.test.js.map +1 -0
  8. package/dist/commands/create.js +15 -11
  9. package/dist/commands/create.js.map +1 -1
  10. package/dist/commands/migrations.d.ts +33 -0
  11. package/dist/commands/migrations.d.ts.map +1 -1
  12. package/dist/commands/migrations.js +41 -2
  13. package/dist/commands/migrations.js.map +1 -1
  14. package/dist/commands/migrations.test.d.ts +2 -0
  15. package/dist/commands/migrations.test.d.ts.map +1 -0
  16. package/dist/commands/migrations.test.js +67 -0
  17. package/dist/commands/migrations.test.js.map +1 -0
  18. package/dist/docs/content.d.ts.map +1 -1
  19. package/dist/docs/content.js +56 -26
  20. package/dist/docs/content.js.map +1 -1
  21. package/dist/examples/recruitment.tar.gz +0 -0
  22. package/dist/index.js +1 -1
  23. package/dist/lib/action-harvest.d.ts +48 -0
  24. package/dist/lib/action-harvest.d.ts.map +1 -0
  25. package/dist/lib/action-harvest.js +292 -0
  26. package/dist/lib/action-harvest.js.map +1 -0
  27. package/dist/lib/action-harvest.test.d.ts +2 -0
  28. package/dist/lib/action-harvest.test.d.ts.map +1 -0
  29. package/dist/lib/action-harvest.test.js +112 -0
  30. package/dist/lib/action-harvest.test.js.map +1 -0
  31. package/dist/lib/api-client.d.ts +10 -0
  32. package/dist/lib/api-client.d.ts.map +1 -1
  33. package/dist/lib/api-client.js +17 -1
  34. package/dist/lib/api-client.js.map +1 -1
  35. package/dist/lib/api-client.test.js +19 -0
  36. package/dist/lib/api-client.test.js.map +1 -1
  37. package/dist/lib/artifact-routing.d.ts +1 -0
  38. package/dist/lib/artifact-routing.d.ts.map +1 -1
  39. package/dist/lib/artifact-routing.js +15 -3
  40. package/dist/lib/artifact-routing.js.map +1 -1
  41. package/dist/lib/artifact-routing.test.js +12 -1
  42. package/dist/lib/artifact-routing.test.js.map +1 -1
  43. package/dist/lib/file-loader.d.ts +1 -0
  44. package/dist/lib/file-loader.d.ts.map +1 -1
  45. package/dist/lib/file-loader.js +34 -1
  46. package/dist/lib/file-loader.js.map +1 -1
  47. package/dist/lib/file-loader.test.js +28 -4
  48. package/dist/lib/file-loader.test.js.map +1 -1
  49. package/dist/lib/prepare-state-output.d.ts +8 -0
  50. package/dist/lib/prepare-state-output.d.ts.map +1 -0
  51. package/dist/lib/prepare-state-output.js +17 -0
  52. package/dist/lib/prepare-state-output.js.map +1 -0
  53. package/dist/lib/prepare-state-output.test.d.ts +2 -0
  54. package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
  55. package/dist/lib/prepare-state-output.test.js +31 -0
  56. package/dist/lib/prepare-state-output.test.js.map +1 -0
  57. package/dist/skill/SKILL.md +4 -4
  58. package/dist/skill/agents/quickback-specialist/AGENT.md +3 -3
  59. package/dist/skill/docs/changelog.md +643 -0
  60. package/dist/skill/docs/compiler/config/agents.md +1 -1
  61. package/dist/skill/docs/compiler/config/auth.md +1 -1
  62. package/dist/skill/docs/compiler/config/index.md +8 -9
  63. package/dist/skill/docs/compiler/config/providers.md +3 -0
  64. package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
  65. package/dist/skill/docs/compiler/definitions/access.md +40 -33
  66. package/dist/skill/docs/compiler/definitions/actions.md +1 -1
  67. package/dist/skill/docs/compiler/definitions/arrows.md +269 -0
  68. package/dist/skill/docs/compiler/definitions/diagnostics.md +136 -0
  69. package/dist/skill/docs/compiler/definitions/feature.md +3 -3
  70. package/dist/skill/docs/compiler/definitions/fga.md +314 -0
  71. package/dist/skill/docs/compiler/definitions/firewall.md +94 -7
  72. package/dist/skill/docs/compiler/definitions/permissions.md +145 -0
  73. package/dist/skill/docs/compiler/definitions/schema.md +8 -2
  74. package/dist/skill/docs/compiler/definitions/scopes.md +339 -0
  75. package/dist/skill/docs/compiler/definitions/views.md +66 -0
  76. package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
  77. package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
  78. package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
  79. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  80. package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
  81. package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
  82. package/dist/skill/docs/stack/cms/connecting.md +17 -16
  83. package/dist/skill/docs/stack/cms/index.md +7 -7
  84. package/dist/skill/docs/stack/cms/schema-format.md +0 -2
  85. package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
  86. package/dist/skill/docs/stack/cms/security.md +6 -6
  87. package/dist/skill/docs/stack/realtime/durable-objects.md +48 -7
  88. package/dist/skill/docs/stack/realtime/live-views.md +168 -0
  89. package/dist/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
  90. package/dist/skill/docs/stack/storage/r2.md +112 -3
  91. package/dist/skill/docs/stack/storage/using-r2.md +30 -10
  92. package/dist/templates/registry.js +2 -2
  93. package/dist/templates/registry.js.map +1 -1
  94. package/package.json +1 -1
  95. package/src/examples/recruitment.tar.gz +0 -0
  96. package/src/skill/SKILL.md +4 -4
  97. package/src/skill/agents/quickback-specialist/AGENT.md +3 -3
  98. package/src/skill/docs/changelog.md +643 -0
  99. package/src/skill/docs/compiler/config/agents.md +1 -1
  100. package/src/skill/docs/compiler/config/auth.md +1 -1
  101. package/src/skill/docs/compiler/config/index.md +8 -9
  102. package/src/skill/docs/compiler/config/providers.md +3 -0
  103. package/src/skill/docs/compiler/config/single-tenant.md +65 -73
  104. package/src/skill/docs/compiler/definitions/access.md +40 -33
  105. package/src/skill/docs/compiler/definitions/actions.md +1 -1
  106. package/src/skill/docs/compiler/definitions/arrows.md +269 -0
  107. package/src/skill/docs/compiler/definitions/diagnostics.md +136 -0
  108. package/src/skill/docs/compiler/definitions/feature.md +3 -3
  109. package/src/skill/docs/compiler/definitions/fga.md +314 -0
  110. package/src/skill/docs/compiler/definitions/firewall.md +94 -7
  111. package/src/skill/docs/compiler/definitions/permissions.md +145 -0
  112. package/src/skill/docs/compiler/definitions/schema.md +8 -2
  113. package/src/skill/docs/compiler/definitions/scopes.md +339 -0
  114. package/src/skill/docs/compiler/definitions/views.md +66 -0
  115. package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
  116. package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
  117. package/src/skill/docs/compiler/getting-started/templates.md +6 -6
  118. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  119. package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
  120. package/src/skill/docs/stack/account-ui/features/index.md +2 -2
  121. package/src/skill/docs/stack/cms/connecting.md +17 -16
  122. package/src/skill/docs/stack/cms/index.md +7 -7
  123. package/src/skill/docs/stack/cms/schema-format.md +0 -2
  124. package/src/skill/docs/stack/cms/schema-registry.md +0 -6
  125. package/src/skill/docs/stack/cms/security.md +6 -6
  126. package/src/skill/docs/stack/realtime/durable-objects.md +48 -7
  127. package/src/skill/docs/stack/realtime/live-views.md +168 -0
  128. package/src/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
  129. package/src/skill/docs/stack/storage/r2.md +112 -3
  130. package/src/skill/docs/stack/storage/using-r2.md +30 -10
@@ -1,5 +1,648 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.39.0 — June 2, 2026
4
+
5
+ Media and large-binary uploads are now first-class. Instead of streaming file
6
+ bytes through your Worker — which hits the request-body cap and burns Worker
7
+ CPU/duration — an action mints a short-lived **presigned URL** and the client
8
+ uploads the bytes **directly to R2**. The Worker only signs; it never sits in
9
+ the data path. This is the supported way to author image/video/document upload
10
+ endpoints, and it survives every `quickback compile` with no generated-file
11
+ patching.
12
+
13
+ Requires R2 file storage (`defineFileStorage("cloudflare-r2", …)`).
14
+
15
+ ### `ctx.storage` — sign uploads from any action
16
+
17
+ When R2 file storage is configured, every `defineAction` execute receives a
18
+ typed `storage` signer. Your action runs all the usual security layers (auth,
19
+ roles, org/relationship scope), computes a tenant-scoped key, hands the client
20
+ an upload URL, and stores the key in **your own table** — no separate metadata
21
+ system required:
22
+
23
+ ```ts
24
+ export default defineAction({
25
+ path: "/event/:eventId/media/upload-file-binary",
26
+ method: "POST",
27
+ input: z.object({ filename: z.string(), contentType: z.string() }),
28
+ access: { roles: ["admin", "member", "scope:event:attendee"] },
29
+ async execute({ input, ctx, c, db, storage }) {
30
+ const eventId = c.req.param("eventId");
31
+ const key = `org/${ctx.activeOrgId}/event/${eventId}/${crypto.randomUUID()}-${input.filename}`;
32
+ const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
33
+ await db.insert(images).values({ key, eventId });
34
+ return { uploadUrl: upload.url, key, headers: upload.headers, expiresAt: upload.expiresAt };
35
+ },
36
+ });
37
+ ```
38
+
39
+ `storage` exposes `signPutUrl(key, { contentType?, expiresIn? })` (returns
40
+ `{ url, method, headers, key, expiresAt }`) and
41
+ `signGetUrl(key, { expiresIn?, downloadFilename? })` (returns a presigned GET
42
+ URL). Construction is zero-cost — actions that never touch `storage` pay
43
+ nothing.
44
+
45
+ ### Managed presign + confirm endpoints
46
+
47
+ For the zero-config path, the built-in storage API now exposes a presigned
48
+ upload alongside the existing through-Worker upload:
49
+
50
+ - `POST /storage/v1/presign/:bucket/*path` — runs the bucket's auth/role/scope
51
+ checks, validates the declared `contentType` + `size` against bucket limits,
52
+ records a pending object row, and returns `{ id, key, uploadUrl, method,
53
+ headers, expiresAt }`
54
+ - `POST /storage/v1/confirm/:bucket/*path` — reconciles the recorded size and
55
+ etag against what actually landed in R2 (`HEAD`)
56
+
57
+ ### Setup: R2 API token
58
+
59
+ Presigning uses R2's S3 API, which needs an **R2 API token** — the Workers R2
60
+ binding cannot presign on its own. Set three secrets:
61
+
62
+ ```bash
63
+ wrangler secret put R2_ACCOUNT_ID
64
+ wrangler secret put R2_ACCESS_KEY_ID
65
+ wrangler secret put R2_SECRET_ACCESS_KEY
66
+ ```
67
+
68
+ `aws4fetch` is added to the generated `package.json` automatically, and the R2
69
+ presign secrets are added to the generated `Env` type. If you pass `contentType`
70
+ to `signPutUrl`, the client must replay exactly that `Content-Type` header on
71
+ the `PUT`.
72
+
73
+ ### No raw-body action flag
74
+
75
+ Streaming a raw binary request body through an action is intentionally **not**
76
+ supported. Presigning delivers the same result — large files, no body cap —
77
+ without poking a hole in the body-parsing layer, so JSON actions and the ~1 MiB
78
+ JSON cap stay intact for every other route.
79
+
80
+ ### Storage routes hardened
81
+
82
+ Enabling R2 file storage previously exposed several latent type errors in the
83
+ generated `/storage/v1/*` routes (dead references from an old multipart
84
+ refactor, JSON-string role columns treated as arrays, a few undefined
85
+ variables). The full storage surface now type-checks cleanly when file storage
86
+ is configured.
87
+
88
+ ## v0.38.1 — May 26, 2026
89
+
90
+ Custom action handlers get the same typed ergonomics as generated CRUD paths:
91
+ typed Cloudflare bindings on `env`, a first-class typed `realtime` helper when
92
+ realtime is enabled, and no more `createRealtime(...)` boilerplate inside every
93
+ action just to emit an explicit broadcast.
94
+
95
+ ### Neon compile output and local recompile state are now stable
96
+
97
+ The Neon + Cloudflare path now emits a correct runtime/output surface instead
98
+ of leaking SQLite-era state.
99
+
100
+ - `wrangler.toml` no longer emits a stray `[[d1_databases]]` block for Neon
101
+ projects
102
+ - repeated local Neon compiles now upload and sync the root PostgreSQL Drizzle
103
+ state correctly, so `drizzle-kit` can report "No schema changes" instead of
104
+ regenerating duplicate `0000_*.sql` files
105
+ - stale root Drizzle migrations from earlier bad compiles are pruned during the
106
+ compile/sync path
107
+
108
+ ### Shared-target namespace hydration now works for bulk-grant lanes
109
+
110
+ Bulk-grant namespace callers (`{ roles: [...] }`, `{ team: true }`) now inherit
111
+ the namespace's shared hydration target when every relationship lane points at
112
+ the same resource load shape.
113
+
114
+ That fixes the case where a namespace like:
115
+
116
+ ```ts
117
+ via: ['attendeeOf', 'organizerOf', { roles: ['admin', 'owner'] }]
118
+ ```
119
+
120
+ would authorize an org admin through the bulk lane but leave `ctx.event`
121
+ undefined, even though the sibling relationship lanes all hydrated the same
122
+ `events` row.
123
+
124
+ Runtime behavior is now split cleanly:
125
+
126
+ - **Shared target** — if all hydrating lanes share the same `loads`,
127
+ `exposeAs`, and resource key, hydration runs unconditionally after the gate
128
+ passes, so bulk callers get the same `ctx.<exposeAs>` as relationship callers
129
+ - **Distinct targets** — if lanes hydrate different tables / keys / ctx slots,
130
+ hydration stays per-matched-lane to avoid cross-table false 404s
131
+
132
+ Standalone action typing now matches that runtime behavior too: shared-target
133
+ hydration remains non-optional, while distinct-target multi-lane hydration stays
134
+ optional.
135
+
136
+ ### Platform role split: `appmanager` for control-plane, `sysadmin` for cross-tenant
137
+
138
+ Quickback no longer treats `user.role === "admin"` as the platform-wide role.
139
+ The control-plane role is now `user.role === "appmanager"` (CMS shell, Better
140
+ Auth admin endpoints, support tooling), while `user.role === "sysadmin"`
141
+ remains the only true cross-tenant data-plane tier.
142
+
143
+ This also retires the `ADMIN` pseudo-role. Any `roles: ["ADMIN"]` usage now
144
+ fails the compile with migration guidance:
145
+
146
+ - `userRole: ["appmanager"]` for platform control-plane access
147
+ - `roles: ["admin"]` for org-membership admin access
148
+ - `roles: ["SYSADMIN"]` for true cross-tenant access
149
+
150
+ Runtime behavior now matches that split end-to-end:
151
+
152
+ - Better Auth's admin plugin is generated with `adminRoles: ["appmanager", "sysadmin"]`
153
+ - CMS / OpenAPI / auth-admin surfaces gate on `appmanager` (and admit
154
+ `sysadmin` where appropriate)
155
+ - unsafe cross-tenant actions and tenant-bypass helpers require `sysadmin` only
156
+
157
+ ### Typed `env` + injected `realtime` in action handlers
158
+
159
+ The generated `<feature>/.quickback/define-action.ts` helper now types action
160
+ `env` from the project's runtime bindings surface instead of `any`, so custom
161
+ bindings like R2 buckets, queues, Durable Objects, auth env vars, and split DB
162
+ bindings no longer need `(env as any)` casts inside action handlers.
163
+
164
+ When realtime is enabled in config, action handlers also receive a typed
165
+ `realtime` helper directly in `execute(...)`. It exposes the same
166
+ `insert/update/delete/broadcast` methods as `createRealtime(env)`, but without
167
+ the extra import or hand-rolled factory call in every custom action.
168
+
169
+ This is a DX-only change. The auto-broadcast boundary is unchanged: generated
170
+ CRUD routes still broadcast automatically, while custom action writes still
171
+ broadcast explicitly.
172
+
173
+ ### `generateId: "cuid"` docs now reflect the split runtime/schema behavior
174
+
175
+ Quickback's `cuid` strategy is now documented as the split path it actually is:
176
+ compiler-managed schema auto-injection keeps the `createId()` call site but may
177
+ back it with a file-local `crypto.randomUUID()` polyfill, while import-capable
178
+ runtime paths still emit real `createId()` usage.
179
+
180
+ That matters most for `compiler.injectId` and other schema-emission paths that
181
+ run in sandboxes where project `node_modules` are not visible. The generated
182
+ schema can safely keep:
183
+
184
+ ```ts
185
+ id: text("id").primaryKey().$defaultFn(() => createId())
186
+ ```
187
+
188
+ while satisfying the reference via:
189
+
190
+ ```ts
191
+ const createId = () => crypto.randomUUID();
192
+ ```
193
+
194
+ instead of importing `@paralleldrive/cuid2` inside the schema-generation
195
+ environment.
196
+
197
+ **Important nuance:** this is not a guarantee that every generated id is a true
198
+ cuid2 string. Auto-injected schema paths may produce UUID-shaped strings
199
+ through the polyfill, while runtime paths that can import helpers may still use
200
+ real `createId()`. If you need strict cuid2 shape everywhere, explicitly import
201
+ `createId` from `@paralleldrive/cuid2` in the authored schema file; the
202
+ compiler preserves that import and skips the polyfill.
203
+
204
+ ## v0.38.0 — May 26, 2026
205
+
206
+ **Per-matched-lane authorization** for multi-lane namespaces — across both the
207
+ REST scope refresh/mint and the realtime ws-ticket. A namespace gated by several
208
+ `via:` lanes (attendees *or* organizers *or* contractors *or* org admins) now
209
+ confers the scope role of **whichever lane the caller actually matched**, instead
210
+ of suppressing the grant. This retires the v0.37.0 single-conferring-lane
211
+ limitation.
212
+
213
+ ### Scope refresh & `mintScope` — per matched lane
214
+
215
+ A **multi-lane `via:`** now refreshes and mints the matched lane's role:
216
+ `attendeeOf` → `scope.event.roles = ['attendee']`, `organizerOf` → `['organizer']`.
217
+ The resolver records which lane opened the gate (first-match-wins), so a caller
218
+ can only ever carry the role they proved this request. A **bulk-grant lane**
219
+ (`{ roles: [...] }` / `{ team: true }`) still confers **no** scope role — it
220
+ authorizes via the caller's org role, with nothing to stamp. Previously any
221
+ multi-lane / bulk / mixed `via:` suppressed the stamp and mint entirely; that
222
+ restriction is lifted. See [Scopes](/compiler/definitions/scopes#mintscope-mint-the-scope-token-from-the-namespace-resolver).
223
+
224
+ ### Namespace-backed ws-ticket — realtime, per matched lane
225
+
226
+ `realtime.wsTicket` accepts a **`namespace`** reference, so the
227
+ `/broadcast/v1/ws-ticket` route authorizes through that namespace's full
228
+ multi-lane `via:` and issues a per-matched-lane WebSocket ticket — the socket
229
+ gate and the REST gate stay identical, from a single source of truth.
230
+
231
+ ```typescript
232
+ realtime: {
233
+ wsTicket: { namespace: "eventScope", requestField: "eventId", scopeTable: "events" },
234
+ },
235
+ ```
236
+
237
+ An attendee gets an `attendee` ticket, an organizer an `organizer` ticket, and an
238
+ org admin who reaches the room through the bulk lane now gets a ticket scoped to
239
+ their org/membership roles — closing the gap where the single-`role` form `403`'d
240
+ a legitimate admin and left their realtime socket dead.
241
+
242
+ **Tenant-bound, fail-closed.** Before minting, the route loads the `scopeTable`
243
+ row through *its own firewall*, so a ticket can only target a room whose resource
244
+ resolves under the caller's tenant — an org-A admin requesting an org-B `eventId`
245
+ gets `403`, never a cross-tenant socket. Because the room *is* the data (no
246
+ firewall sits between a ticket and a Durable Object room), the compiler **rejects
247
+ at build time** a namespace-backed `wsTicket` whose `scopeTable` isn't
248
+ tenant-scoped (`firewall: { exception: true }` or a literal-only firewall with no
249
+ org/owner/team isolation). See
250
+ [Realtime tickets](/stack/realtime/durable-objects#namespace-backed-tickets-per-matched-lane).
251
+
252
+ ## v0.37.0 — May 26, 2026
253
+
254
+ The **authz-as-compile-target** roadmap ships. Your authorization model —
255
+ relationships, named permissions, FK-traversal arrows, scope axes — compiles
256
+ into one normalized policy IR, lowers to SQL `WHERE` clauses / signed claims /
257
+ guards, and is checked by a static analyzer before a single route is emitted.
258
+ This release lands milestones M0.1, M0.3, M1, M2, and M4, plus §5.3 namespace
259
+ scope-minting.
260
+
261
+ ### Named permissions (`authz.permissions`) — M1
262
+
263
+ A `via:` arm references **one** relationship. When the *same* grant rule recurs
264
+ across resources — "organizer **or** confirmed attendee" — name it **once**
265
+ under `authz.permissions` as a boolean expression and reference it everywhere
266
+ with a `{ permission }` firewall arm.
267
+
268
+ ```typescript
269
+ authz: {
270
+ permissions: {
271
+ 'event:view': { anyOf: ['organizerOf', 'attendeeOf'] },
272
+ 'org:admin': { anyOf: [{ role: 'admin' }, { role: 'owner' }] },
273
+ },
274
+ }
275
+ // then on a resource:
276
+ // firewall: [ { field: 'eventId', permission: 'event:view' } ]
277
+ ```
278
+
279
+ `anyOf` lowers to an OR of relationship subqueries, `allOf` to an AND, and a
280
+ `{ permissionRef }` inlines another permission's arms — byte-identical to
281
+ writing the `via:` arms by hand. The full DSL (`anyOf` / `allOf` / `not`, bare
282
+ strings, and the object-leaf escape hatch) is accepted so configs stay
283
+ forward-compatible; a firewall enforces the **SQL-pushable** subset (claim-site
284
+ leaves like `{ role }` / `{ scopeRole }` and `not` over a SQL site are rejected
285
+ at compile time — gate those on `access` instead). See
286
+ [Permissions](/compiler/definitions/permissions).
287
+
288
+ ### FK-traversal arrows (`authz.arrows`) — M2
289
+
290
+ An **arrow** inherits authority across a foreign key: *"you can see this row
291
+ because you administer the organization it belongs to"*, or *"because you
292
+ control an ancestor in the tree."* Declare an FK hop, reference it from a
293
+ permission as `{ arrowRef, permission }`, and it lowers to SQL.
294
+
295
+ ```typescript
296
+ authz: {
297
+ arrows: {
298
+ eventOrg: { from: 'event', fk: 'organizationId', to: 'organization' },
299
+ folderTree: { from: 'folder', fk: 'parentId', to: 'folder', recursive: true },
300
+ },
301
+ permissions: {
302
+ 'event:view': { anyOf: ['organizerOf', { arrowRef: 'eventOrg', permission: 'org:admin' }] },
303
+ 'folder:read': { anyOf: [{ arrowRef: 'folderTree', permission: 'org:admin' }] },
304
+ },
305
+ }
306
+ ```
307
+
308
+ A single hop lowers to an FK-hop subquery; a self-referential hop
309
+ (`folder.parentId -> folder`) lowers to a **bounded `WITH RECURSIVE` CTE**
310
+ (default depth 8, override per-arrow with `maxDepth` or per-permission with
311
+ `permissionMaxDepth`). The seed and **every walked row** are re-constrained to
312
+ the caller's active-org claim, an absent claim fails closed (`1 = 0`), and the
313
+ identifiers are compile-time constants while the claim binds as a parameter —
314
+ so an arrow is never an injection surface. An `unbounded: true` arrow with no
315
+ claim path is a hard compile error. Valid on both D1 and Neon. See
316
+ [Arrows](/compiler/definitions/arrows).
317
+
318
+ ### Compile-time authz analyzer + diagnostics — M4
319
+
320
+ The compiler now projects your whole authorization model into a single policy
321
+ IR and runs static checks over it, reporting on the existing
322
+ **`[quickback:authz]`** console channel with stable, greppable codes:
323
+
324
+ - `AUTHZ_EMPTY_PERMISSION` — a permission that can never be satisfied (e.g. `allOf(a, not(a))`).
325
+ - `AUTHZ_SHADOWED_ARM` — an `anyOf` arm subsumed by a broader sibling.
326
+ - `AUTHZ_UNREACHABLE_ROLE` / `AUTHZ_UNREACHABLE_VIEW` — dead scope config.
327
+ - `AUTHZ_NOT_OVER_RESOURCE` — a `not` over a SQL site (the null-trap).
328
+ - `AUTHZ_PUSHDOWN_COST` — an `info` report of each permission's subquery count and recursive-CTE depth.
329
+ - `AUTHZ_CAPABILITY_CEILING` — **error** — a resource grants a `scope:<kind>:<role>` read beyond its `grants` profile.
330
+
331
+ Checks are **warn-by-default, compile-continues** (so a new check never breaks
332
+ an existing build on upgrade); set **`QUICKBACK_AUTHZ_STRICT=true`** to promote
333
+ every warning to a hard error. The analyzer is compile-time only — a defect in
334
+ a check downgrades to a single warning in the default path and can never take
335
+ down an otherwise-valid compile. See
336
+ [Diagnostics](/compiler/definitions/diagnostics).
337
+
338
+ ### Aggregate-only views — M0.1
339
+
340
+ A view can return a rollup and **nothing else** — no `data[]`, no per-row field
341
+ selection — via `aggregateOnly: true`, with an optional `kMin` k-anonymity floor
342
+ that suppresses the aggregate below a threshold. This is what lets an F&B vendor
343
+ read dietary **counts** for an event with zero attendee rows. See
344
+ [Views](/compiler/definitions/views).
345
+
346
+ ### Scope leftovers — M0.3
347
+
348
+ The relationship-scope surface gains three pieces:
349
+
350
+ - **Namespace scope-claim refresh** — a namespace gating `/event/:eventId/*` on a single conferring relationship lane refreshes `ctx.scope.<kind>` in memory for the request, so an attendee hitting an action under the prefix gets the scoped role stamped without a separate `/scope/v1/enter` round-trip.
351
+ - **`q.scope()` autofill** — `q.scope('event')` auto-stamps a column from the verified scope claim (`ctx.scope.event.id`) on insert, the same way `q.scope('organization')` stamps the tenant column. Insert-only and null-safe; it adds no read-time `WHERE`.
352
+ - **Set-valued sub-keys** — a `subKeys` entry ending in `[]` (e.g. `'shuttleId[]'`) projects **every** matched relationship row's value into the claim as a `string[]`, and the matching firewall arm is rewritten to an `inArray` row-slice (a driver covering multiple buses). An absent claim lowers to `inArray(col, [])` — a clean deny.
353
+
354
+ See [Scopes & capability grants](/compiler/definitions/scopes).
355
+
356
+ ### Namespace scope-minting (`mintScope`) — §5.3
357
+
358
+ A namespace can now MINT a persisted scope JWT from its resolver. Set
359
+ **`mintScope: true`** and, on a successful relationship probe, the resolver
360
+ returns a scope token via `set-auth-token` — so a native client hitting
361
+ `/event/:eventId/*` carries the scoped role forward **without** calling
362
+ `/scope/v1/enter`.
363
+
364
+ ```typescript
365
+ authz: {
366
+ namespaces: {
367
+ eventScope: { prefix: '/event/:eventId', via: ['attendeeOf'], mintScope: true },
368
+ },
369
+ }
370
+ ```
371
+
372
+ The mint fires **only** when `via:` confers exactly one scope role
373
+ unambiguously (a single conferring relationship lane); a multi-lane,
374
+ bulk-grant, or asymmetric `via:` **suppresses** the mint (fail-closed — those
375
+ callers use `/scope/v1/enter`). The token reuses the shared mint helper (TTL
376
+ clamped to ≤180s, sibling scope kinds carried forward) and the mint is
377
+ **best-effort** — a mint failure never fails the request, since the in-memory
378
+ stamp already authorized it. Opt-in per namespace; defaults to `false`. See
379
+ [Scopes — `mintScope`](/compiler/definitions/scopes#mintscope-mint-the-scope-token-from-the-namespace-resolver).
380
+
381
+ > **Gotcha:** a namespace emits its resolver — and thus the refresh and the
382
+ > mint — **only** when at least one *standalone* action's `path:` falls under
383
+ > the prefix. A namespace containing only record-based actions (which mount
384
+ > under their resource's CRUD routes, not the prefix) is **inert**. Add a
385
+ > standalone action like `eventHome` at `/event/:eventId/home`. See
386
+ > [Scopes — the resolver gotcha](/compiler/definitions/scopes#gotcha-a-namespace-only-emits-its-resolver-when-it-claims-a-standalone-action).
387
+
388
+ ## v0.36.3 — May 25, 2026
389
+
390
+ ### Fix: `/auth/v1/*` handler forwards `executionCtx` so OTP emails actually send
391
+
392
+ The generated `createAuth(env, cf?, executionCtx?)` schedules the fire-and-forget
393
+ verification-OTP send through `executionCtx.waitUntil(...)` — Better Auth advises
394
+ **not** awaiting the send so its latency doesn't leak into auth response timing.
395
+ That only works when `executionCtx` is passed. The composed Cloudflare worker
396
+ index emitted a **bare** `createAuth(c.env)` at the `app.all('/auth/v1/*')`
397
+ handler, so on Cloudflare the unawaited SES/SNS send was cancelled the moment the
398
+ handler returned — `send-verification-otp` returned 200 but no email went out.
399
+
400
+ The handler now threads `createAuth(c.env, c.req.raw.cf as any, c.executionCtx)`,
401
+ matching the action call-sites (`record-based`, `standalone`, `core/helpers`) and
402
+ the `getSession` call now passes the `cf` binding. (The earlier waitUntil fix had
403
+ only patched the legacy `providers/runtime` index emitter, not this composed one —
404
+ the two had drifted.) Recompile + redeploy to pick it up.
405
+
406
+ ## v0.36.2 — May 25, 2026
407
+
408
+ Two firewall fixes uncovered in a relationship-scoped (event-attendee) project:
409
+ scoped reads stopped hiding rows behind a misclassified soft-delete column, and
410
+ the list route stopped rejecting org-optional callers before the firewall ran.
411
+
412
+ ### Fix: a firewall `isNull` predicate on a non-`deletedAt` column no longer globalizes as soft-delete
413
+
414
+ The scoped `db` wrapper used by actions enforces soft-delete by injecting
415
+ `isNull(<col>)` into reads. It built its list of soft-delete columns by treating
416
+ **any** firewall `{ field, isNull: true }` predicate as a project-wide soft-delete
417
+ marker — so an `isNull` predicate on a foreign-key column (e.g.
418
+ `{ field: 'agendaItemId', isNull: true }`) was broadcast to **every** table that
419
+ merely had an `agendaItemId` column, rewriting scoped reads to
420
+ `agenda_item_id IS NULL`. Real rows (non-null FK) became invisible, so an action
421
+ that read-before-write saw "no row," attempted an insert, and 500'd on the
422
+ `(agenda_item_id, guest_id)` unique constraint.
423
+
424
+ Only `deletedAt` — the column the compiler injects into every table — now enters
425
+ the project-global soft-delete list. A custom `isNull` predicate is still enforced
426
+ **per-table** by that table's firewall (route layer); it is simply no longer
427
+ broadcast across the whole schema. This mirrors the v0.28 fix that made custom
428
+ owner columns per-table rather than global.
429
+
430
+ ### Fix: list route no longer hard-requires an org when the firewall makes org optional
431
+
432
+ The generated CRUD **list** route emits an `ORG_REQUIRED` 400 (with a sysadmin
433
+ escape) before the firewall runs. It fired whenever an org scope appeared
434
+ **anywhere** in the firewall — including when org is just one arm of an `any:`
435
+ group. So after the relationship-scope migration made a firewall org-optional
436
+ (`any: [ { organizationId = ctx.activeOrgId }, { …via relationship } ]`), a
437
+ plain-JWT caller with no `activeOrgId` (e.g. an event attendee scoped by
438
+ relationship) got an instant 400 — the org-optional firewall that would have
439
+ scoped them correctly never even ran.
440
+
441
+ The gate now keys off org **mandatoriness** (`firewallRequiresOrg`): it fires
442
+ only when an org claim is genuinely required — a top-level (implicit-AND) or
443
+ `all`-nested org predicate. When org is one arm of an `any:` group, the list
444
+ route skips the 400 and lets the null-safe firewall scope the caller: the org
445
+ arm drops when `activeOrgId` is absent, sibling arms (relationship/owner) bind,
446
+ and `anyGuarded` denies (`1 = 0`) when every arm drops — so a no-org caller sees
447
+ exactly what the declared policy grants, never an unbounded cross-tenant read.
448
+ `?organizationId=` cross-tenant addressing and the sysadmin escape are unchanged,
449
+ and a plain org-scoped resource (no `any:` group) keeps the `ORG_REQUIRED` gate
450
+ byte-for-byte. Write paths (create / put / batch) still require an org so new
451
+ rows are always stamped with a tenant.
452
+
453
+ ## v0.36.1 — May 25, 2026
454
+
455
+ Relationship-derived **scoped roles** — request-scoped authorization minted from
456
+ a verified relationship into a short-lived JWT.
457
+
458
+ ### `authz.scopes` — scoped roles via a relationship probe
459
+
460
+ A new `authz.scopes` block turns a declared relationship into a request-scoped
461
+ role. Key the scope by a request field and back each role with a relationship:
462
+
463
+ ```ts
464
+ authz: {
465
+ relationships: {
466
+ attendeeOf: {
467
+ from: 'guests',
468
+ subject: { column: 'userId', equals: 'ctx.userId' },
469
+ resource: { column: 'eventId' },
470
+ where: { status: 'confirmed' },
471
+ },
472
+ },
473
+ scopes: {
474
+ event: {
475
+ requestField: 'eventId',
476
+ roles: { attendee: { via: 'attendeeOf' } }, // shorthand: attendee: 'attendeeOf'
477
+ },
478
+ },
479
+ }
480
+ ```
481
+
482
+ The compiler emits a `/scope/v1/enter` route that probes the relationship for the
483
+ caller ("is this user a confirmed guest of `eventId`?") and, on success, mints a
484
+ short-lived JWT carrying the verified scope. The auth middleware reads that claim
485
+ into `ctx.scope.<kind>` (e.g. `ctx.scope.event`).
486
+
487
+ Scoped roles then work everywhere roles do — `read.access`, view access,
488
+ `masking.show`, action access — as `scope:<kind>:<role>`, and the firewall can
489
+ scope rows by the verified id:
490
+
491
+ ```ts
492
+ read: { access: { roles: ['admin', 'member', 'scope:event:attendee'] } },
493
+ masking: { email: { type: 'email', show: { roles: ['admin', 'scope:event:organizer'] } } },
494
+ firewall: { any: [
495
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
496
+ { field: 'eventId', equals: 'ctx.scope.event' },
497
+ ] },
498
+ ```
499
+
500
+ So an attendee who "enters" an event reads that event's guest list — the `eventId`
501
+ firewall arm matches their verified scope — with no org-membership role, and
502
+ `email` stays masked unless they hold `scope:event:organizer`.
503
+
504
+ ### Scoped-role name sugar
505
+
506
+ Write the bare role name and the compiler lowers it to canonical
507
+ `scope:<kind>:<role>` when it resolves uniquely:
508
+
509
+ ```ts
510
+ access: { roles: ['attendee'] } // → scope:event:attendee
511
+ ```
512
+
513
+ Reserved names (`admin`, `member`, `owner`), pseudo-roles, and anything declared
514
+ in `authz.roles` are never rewritten. A bare name that's ambiguous across scopes
515
+ is a compile error pointing you to the explicit `scope:<kind>:<role>` form.
516
+
517
+ ## v0.36.0 — May 25, 2026
518
+
519
+ Project-wide `id` generation now applies to every write path, action `db` is
520
+ typed on Cloudflare D1, and realtime rooms can be gated on a unique non-PK column.
521
+
522
+ ### `id` default moves to the column (`$defaultFn`)
523
+
524
+ The configured `generateId` strategy now lands on the `id` column itself —
525
+ `id: text("id").primaryKey().$defaultFn(() => createId())` — not just inside the
526
+ auto-CRUD route handler. Previously a table with an explicit `text("id").primaryKey()`
527
+ kept a bare PK, so a hand-written action doing `db.insert(...).values({…})` got no
528
+ `id` and failed at runtime with a `NOT NULL` 500 — invisible to `tsc` because the
529
+ scoped `db` was `any`. The injector (which already did this for tables with no
530
+ declared PK) now also appends the strategy's `$defaultFn` to an explicit `id` PK.
531
+ `generateId: false` (client-supplied ids) and `serial`/integer PKs are left
532
+ untouched; the rewrite is idempotent. `$inferInsert` now marks `id` optional.
533
+
534
+ ### Action `db` is typed on Cloudflare D1
535
+
536
+ The scoped `db` passed to custom actions is no longer `any`. On D1 projects the
537
+ per-feature `define-action` helper types it as a Drizzle client whose
538
+ `.insert().values()` makes the org/owner/team scope columns optional (the runtime
539
+ fills them from context), while every other column you declared stays required —
540
+ so `tsc` catches a forgotten column, typos, and wrong types, and query results
541
+ come back typed. Neon/Postgres keep `db: any` for now.
542
+
543
+ `ctx.userId` is also narrowed to `string` (not `string | undefined`) in actions
544
+ whose `access` requires authentication — so a trusted write like
545
+ `db.insert(t).values({ ownerId: ctx.userId })` type-checks without a cast.
546
+ Actions reachable anonymously (a `PUBLIC` arm, including inside `or`/`and`) keep
547
+ `ctx.userId` optional.
548
+
549
+ ### `access.resource` gains an optional `key`
550
+
551
+ The per-room authorization gate (`bindings.durableObjects[].access`) always
552
+ matched the WebSocket roomId against the backing table's primary key —
553
+ `eq(table.id, rowId)`. Rooms addressed by a different unique column had no way
554
+ to use it: a Yjs collaborative editor keyed by `event_pages.yjsRoomId`
555
+ (`ns.idFromName(row.yjsRoomId)`) would never match on `id`, so projects dropped
556
+ the `access` block and hand-rolled enforcement in `onConnect` — or, more often,
557
+ shipped no row-level check at all, leaving the room reachable by any
558
+ authenticated user who could guess a room id.
559
+
560
+ The long form now accepts `key`:
561
+
562
+ ```ts
563
+ access: { resource: { feature: 'event-pages', table: 'eventPages', key: 'yjsRoomId' } }
564
+ ```
565
+
566
+ The gate emits `eq(table.<key>, rowId)` against the named column. `key` defaults
567
+ to `'id'`, so every existing pin is byte-for-byte unchanged, and it also works
568
+ inside each `resources[kind].resource` of the multi-resource form. The compiler
569
+ validates the column exists against the pinned table's schema at compile time.
570
+
571
+ The "multi-table feature is ambiguous" compile error now points at all three
572
+ escapes — the long-form pin, the `key` option for non-id rooms, and declaring
573
+ the table's firewall with a `via:` relationship so membership gating runs in the
574
+ gate with no hand-written `onConnect`. See
575
+ [PartyServer rooms → per-room authorization](/stack/realtime/partyserver-rooms).
576
+
577
+ ## v0.35.0 — May 25, 2026
578
+
579
+ New **FGA pillar** — OpenFGA / Google Zanzibar Relationship-Based Access
580
+ Control (ReBAC), compiled into your Worker. Plus a public-sharing surface
581
+ (type-bound public access + signed share links) built on it.
582
+
583
+ ### Relationship-based access control (`authz.fga`)
584
+
585
+ Role-based access and one-hop relationship joins can't express *graph-shaped*
586
+ permissions: an `editor` who is automatically a `viewer`, a document that
587
+ inherits viewers from its folder, a `team#member` group grant, or a per-record
588
+ assignment that doesn't require a global role. The new `authz.fga` block adds a
589
+ true ReBAC engine modeled on [OpenFGA](https://openfga.dev):
590
+
591
+ - **Model** — declare object types, relations, and userset rewrites in the
592
+ OpenFGA modeling DSL (`or` / `and` / `but not`, `[user:*]` public access,
593
+ `[team#member]` usersets, `viewer from parent` tuple-to-userset). The compiler
594
+ parses and semantically validates it at compile time — dangling type or
595
+ relation references fail the compile loudly.
596
+ - **Tuples** — stored in a compiler-owned, organization-scoped `fga_tuples`
597
+ table the compiler emits and migrates. A Check never reads another tenant's
598
+ tuples.
599
+ - **Check engine** — resolved entirely inside the Worker (no external auth
600
+ service): direct tuples, type-bound public access, userset subjects, computed
601
+ usersets, tuple-to-userset, request-scoped contextual tuples, with cycle
602
+ detection and a depth cap.
603
+ - **`ctx.fga`** — `check` / `listObjects` / `expand` / `write` / `read`,
604
+ org-scoped, available in every action and handler.
605
+ - **`access: { fga: { relation, object } }`** — a new declarative access arm.
606
+ The compiler fetches the record and emits an inline, fail-closed
607
+ `ctx.fga.check('user:' + ctx.userId, relation, object)` gate (`object` is a
608
+ `job:{id}` template over the record's columns).
609
+ - **Collection-level FGA filtering** — an `fga` arm on `read.access` (or a named
610
+ view) now filters the collection `GET /`, not just `GET /:id`. The compiler
611
+ resolves the caller's authorized object ids via the engine's `ListObjects` and
612
+ injects an `inArray(id, …)` into the list query, so pagination, `total`, and
613
+ `hasMore` stay correct. Supported shapes are bare `{ fga }`,
614
+ `or:[{ roles }, { fga }]`, and `and:[{ roles }, { fga }]`; deeper nesting is a
615
+ compile error. The authorized set is bounded by `authz.fga.listObjects.maxIds`
616
+ (default 1000) — past the cap the request fails with a hard 422
617
+ (`FGA_LIST_TOO_LARGE`) pointing to `POST /fga/v1/list-objects` for paginated
618
+ enumeration.
619
+ - **REST API** — an OpenFGA-compatible surface at `/api/v1/fga/v1`
620
+ (`check`, `list-objects`, `expand`, `read`, `write`), tenant-scoped; writes
621
+ gated by `authz.fga.writeRoles` (default `['admin']`).
622
+
623
+ ### Public sharing
624
+
625
+ `authz.fga.sharing` turns the FGA engine into a public-sharing mechanism:
626
+
627
+ - **Type-bound public access** — a model relation listing `user:*` becomes
628
+ shareable-to-everyone by writing one tuple.
629
+ - **Signed share links** — `POST /api/v1/fga/v1/share` mints an HMAC-signed,
630
+ opaque token for one `(object, relation)` grant; `GET /share/v1/:token` is a
631
+ **public, unauthenticated** route that verifies the token and returns a
632
+ configured public projection of the object (it leaks nothing beyond that
633
+ object + relation).
634
+ - **Share URL** — both a dedicated route (`/share/v1/:token`, always mounted)
635
+ and an optional vanity base URL (`share.<your-domain>`, added to your runtime
636
+ routes) are supported.
637
+
638
+ ### q-recruit showcase
639
+
640
+ The recruitment example now models `organization → job → application/interview`
641
+ with FGA: a `recruiter` is automatically a `viewer` and `can_manage` of a job,
642
+ applications inherit viewers from their job, and a job can be made publicly
643
+ shareable. New `assign-recruiter` and `make-public` actions demonstrate
644
+ `ctx.fga.write`, and `jobs.update` gates on `{ or: [{ roles }, { fga }] }`.
645
+
3
646
  ## v0.34.1 — May 24, 2026
4
647
 
5
648
  Patch fixing a silent-skip bug in drizzle migration emission, plus a new
@@ -70,7 +70,7 @@ Every operation in your generated OpenAPI spec becomes one MCP tool. The tool na
70
70
  `tools/list` only returns tools the calling identity could actually invoke. Each generated tool entry carries the operation's access metadata (`roles`, `userRole`, `or` / `and` combinators) and `tools/list` filters against `ctx` before responding:
71
71
 
72
72
  - **Unauthenticated callers** see only tools whose access declares the `PUBLIC` pseudo-role, or operations that have no security requirement at all (e.g. sign-in / sign-up).
73
- - **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Admin-only endpoints don't appear for non-admins.
73
+ - **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Platform-operator endpoints don't appear for callers outside the required user roles.
74
74
  - **Function-form access** (escape hatch) is opaque at list time — surfaced to any authenticated caller, then evaluated for real on `tools/call`.
75
75
  - **Record predicates** are dropped from the list-time check (no record yet) and applied normally on the actual call.
76
76
 
@@ -125,7 +125,7 @@ export default defineConfig({
125
125
  Both fields override compiler-emitted browser redirects in the CMS shell:
126
126
 
127
127
  - **Unauthenticated visitor hits a CMS route** → `302 → <loginUrl>?redirect=<original-url>`
128
- - **Authenticated user fails the `cms.access: 'admin'` role check** → `302 → <profileUrl>`
128
+ - **Authenticated user fails the `cms.access: 'admin'` platform-role check** → `302 → <profileUrl>`
129
129
 
130
130
  The `?redirect=…` query param is preserved unchanged so the central sign-in surface can bounce the user back after authentication.
131
131