@quickback-dev/cli 0.47.0 → 0.47.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/commands/claude.d.ts +1 -1
  2. package/dist/commands/claude.d.ts.map +1 -1
  3. package/dist/commands/claude.js +9 -6
  4. package/dist/commands/claude.js.map +1 -1
  5. package/dist/commands/compile.d.ts +1 -1
  6. package/dist/commands/compile.js +1 -1
  7. package/dist/commands/start.d.ts +2 -0
  8. package/dist/commands/start.d.ts.map +1 -1
  9. package/dist/commands/start.js +84 -39
  10. package/dist/commands/start.js.map +1 -1
  11. package/dist/docs/content.js +14 -14
  12. package/dist/docs/content.js.map +1 -1
  13. package/dist/index.js +7 -3
  14. package/dist/index.js.map +1 -1
  15. package/dist/lib/file-loader.d.ts +1 -1
  16. package/dist/lib/file-loader.d.ts.map +1 -1
  17. package/dist/lib/file-loader.js +16 -3
  18. package/dist/lib/file-loader.js.map +1 -1
  19. package/dist/skill/docs/changelog.md +328 -0
  20. package/dist/skill/docs/compiler/cloud-compiler/cli.md +1 -1
  21. package/dist/skill/docs/compiler/definitions/access.md +17 -0
  22. package/dist/skill/docs/compiler/definitions/actions.md +9 -4
  23. package/dist/skill/docs/compiler/getting-started/claude-code.md +1 -1
  24. package/dist/skill/docs/compiler/getting-started/index.md +9 -1
  25. package/dist/skill/docs/compiler/getting-started/templates.md +11 -7
  26. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +27 -8
  27. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +2 -1
  28. package/dist/skill/docs/stack/account-ui/features/organizations.md +1 -1
  29. package/dist/skill/docs/stack/cms/pages.md +1 -1
  30. package/dist/skill/docs/stack/realtime/durable-objects.md +9 -0
  31. package/dist/skill/docs/stack/realtime/live-views.md +4 -0
  32. package/dist/skill/docs/stack/realtime/using-realtime.md +2 -2
  33. package/dist/templates/registry.d.ts.map +1 -1
  34. package/dist/templates/registry.js +1 -0
  35. package/dist/templates/registry.js.map +1 -1
  36. package/package.json +1 -1
  37. package/src/skill/docs/changelog.md +328 -0
  38. package/src/skill/docs/compiler/cloud-compiler/cli.md +1 -1
  39. package/src/skill/docs/compiler/definitions/access.md +17 -0
  40. package/src/skill/docs/compiler/definitions/actions.md +9 -4
  41. package/src/skill/docs/compiler/getting-started/claude-code.md +1 -1
  42. package/src/skill/docs/compiler/getting-started/index.md +9 -1
  43. package/src/skill/docs/compiler/getting-started/templates.md +11 -7
  44. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +27 -8
  45. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +2 -1
  46. package/src/skill/docs/stack/account-ui/features/organizations.md +1 -1
  47. package/src/skill/docs/stack/cms/pages.md +1 -1
  48. package/src/skill/docs/stack/realtime/durable-objects.md +9 -0
  49. package/src/skill/docs/stack/realtime/live-views.md +4 -0
  50. package/src/skill/docs/stack/realtime/using-realtime.md +2 -2
@@ -61,6 +61,43 @@ Analyzer-internal defects are still fail-open: a bug in the analyzer itself
61
61
  downgrades to a single warning and the compile continues. Only real findings
62
62
  fail builds.
63
63
 
64
+ ### CLI: live views now compile through the CLI
65
+
66
+ `defineView` files under `quickback/services/views/` were never loaded by
67
+ the CLI — the compile payload simply omitted them, so
68
+ [live views](/stack/realtime/live-views) (v0.35) only worked when driving
69
+ the compiler API directly. The CLI now discovers and ships them like every
70
+ other service definition, and the compile summary counts them
71
+ (`Loaded services: … 1 live view(s)`). If you declared views and wondered
72
+ why no surface ever went live: upgrade the CLI and recompile.
73
+
74
+ ### CLI: deterministic compile output across machines
75
+
76
+ Feature and service discovery used raw `readdir` order, which differs
77
+ between macOS and Linux — route registration order, schema re-exports,
78
+ OpenAPI paths, and the Neon RLS document's content hash could all churn when
79
+ the same project was recompiled on a different machine. All discovery sites
80
+ now sort by codepoint, so the same input compiles to the same bytes
81
+ everywhere. Expect a one-time diff on the first recompile if your previous
82
+ output was generated in a different filesystem order.
83
+
84
+ ### Fixes
85
+
86
+ - Read-only resources (no `crud` block) generated routes importing a
87
+ `CRUD_ACCESS` symbol their resource file never exported — a tsc/bundle
88
+ break. The export is now unconditional.
89
+ - The `blog` starter template gated writes on the removed `ADMIN`
90
+ pseudo-role, which hard-fails current compiles; it now uses the
91
+ org-membership `admin` role.
92
+ - `reports/operations.manifest.json` and `reports/conformance.manifest.json`
93
+ now also cover the realtime (`/broadcast/v1`), storage (`/storage/v1`),
94
+ and FGA (`/fga/v1`) surfaces.
95
+ - The dead free/pro tier plumbing is gone: no Tier row in
96
+ `quickback whoami`, no upsell copy at login. Compiling complete projects
97
+ requires login, exactly as before — there was never a paid gate behind it.
98
+ - The CLI is published to npm via trusted publishing (GitHub OIDC) — signed
99
+ provenance, no long-lived npm token in the pipeline.
100
+
64
101
  ## v0.46.0 — June 11, 2026
65
102
 
66
103
  ### Breaking: "no organization context" responses unified on HTTP 403
@@ -104,6 +141,225 @@ redeploy; switch to the documented root URL. Actions declared *under* the
104
141
  feature prefix are untouched, and a feature whose standalone actions are all
105
142
  root-mounted no longer emits an (empty) feature actions routes file.
106
143
 
144
+ ### Behavior change: `PUBLIC` inside `or:` arms admits anonymous callers
145
+
146
+ [Access](/compiler/definitions/access) has always documented `PUBLIC` as
147
+ working on every access node, but the emitted auth gate only honored it in a
148
+ flat `roles: [...]` list. A tree like
149
+
150
+ ```ts
151
+ access: {
152
+ or: [
153
+ { roles: ["PUBLIC"] },
154
+ { roles: ["admin"] },
155
+ ],
156
+ }
157
+ ```
158
+
159
+ still answered anonymous callers with `401`. The auth gate is now tree-aware
160
+ and matches the documented semantics: a `PUBLIC` `or:` arm admits anonymous
161
+ callers past the authentication gate (an `and:` group admits them only when
162
+ *every* arm does), and the access / org / firewall layers still evaluate the
163
+ full tree. One shared predicate now drives the emitted gates, the OpenAPI
164
+ `security` blocks, and view routes (which gate per view on the
165
+ view-effective access).
166
+
167
+ **Worth a loud note:** if you have a nested `PUBLIC` arm that was silently
168
+ 401-ing, that endpoint becomes anonymously reachable after recompile —
169
+ exactly what the config declares, but verify it's what you meant. `PUBLIC`
170
+ audit logging applies to the newly-admitted routes as usual.
171
+
172
+ ### Realtime broadcasts now enforce `requiredRoles` and masking
173
+
174
+ A table's declared realtime gates weren't being applied to the generated
175
+ CRUD broadcasts: `realtime: { requiredRoles: [...] }` and column masking were
176
+ honored on the HTTP surface but not on the WebSocket fanout. The docs
177
+ promised per-role, masked realtime delivery; the generated broadcasts now
178
+ match it. **Recompile and redeploy** any project using realtime on
179
+ role-gated or masked tables.
180
+
181
+ Generated `realtime.insert / update / delete` calls now carry:
182
+
183
+ - **`targetRoles`** — the table's `realtime.requiredRoles` (post role-
184
+ hierarchy `+` expansion), enforced per subscriber at fanout.
185
+ - **`maskingConfig`** — serialized from the same effective masking
186
+ (declared + auto-detected sensitive columns) the HTTP mask functions are
187
+ generated from. What HTTP masks is what the WebSocket wire masks.
188
+
189
+ Live-view `view_changes` deltas honor the same table-level `requiredRoles`
190
+ at fanout, so a role-gated table can't leak through a
191
+ [live view](/stack/realtime/live-views) subscription either.
192
+
193
+ Notes:
194
+
195
+ - Recompile suffices — no config change needed.
196
+ - If you worked around this with hand-written `realtime.*` calls passing
197
+ `targetRoles` / `maskingConfig`, those workaround broadcasts can be
198
+ removed.
199
+ - `type: 'custom'` mask functions can't ride the wire — the Broadcaster
200
+ fails closed and broadcasts `[REDACTED]` for those columns.
201
+ - Tables without `requiredRoles` or masking are byte-identical: the open
202
+ broadcast default is unchanged.
203
+
204
+ ### Batch operations inherit the base operation's access
205
+
206
+ When a batch operation was declared without its own `access`, it didn't pick
207
+ up the base operation's role requirement:
208
+
209
+ ```ts
210
+ crud: {
211
+ update: { access: { roles: ["admin"] } },
212
+ batchUpdate: { maxBatchSize: 25 }, // ← no access of its own
213
+ }
214
+ ```
215
+
216
+ A batch config declared without `access` now inherits the base operation's
217
+ access at compile time — fail closed, so runtime, the OpenAPI spec, and the
218
+ generated code all agree. Explicit batch `access` still wins (including
219
+ per-side on upserts); a base op without access still yields an
220
+ authenticated-only batch op. The flat `update: { batch: true }` shape and
221
+ auto-promoted batch ops were never affected. **Recompile and redeploy** if
222
+ you use the explicit-batch shape without per-batch access.
223
+
224
+ ### Record actions, PUT upserts, and legacy firewall arms fail closed
225
+
226
+ Three fail-closed hardening fixes, found and verified against the new
227
+ conformance catalog (route × principal expectations derived from the
228
+ compiler's own IR — see the
229
+ [conformance manifest](/compiler/targets/hono-api/using-the-api/openapi#operations-manifest)).
230
+ All apply on recompile + redeploy; no config change needed:
231
+
232
+ - **Record actions evaluate the role gate before fetching the record**, so
233
+ the denial response no longer varies with record state — a uniform
234
+ `403 ACCESS_ROLE_REQUIRED`. (Bulk actions already had this order; unsafe
235
+ actions write their audit row on the pre-record denial.)
236
+ - **PUT upsert treats an out-of-scope id as a firewall miss** (`403` reveal /
237
+ `404` hide, per your firewall error mode; a standard 207 miss entry on
238
+ `PUT /batch`) instead of routing it into the create path. Genuinely new
239
+ ids keep the create path.
240
+ - **Legacy (array-form) firewall arms deny cleanly when a bound context
241
+ claim is absent at runtime** (e.g. no active org), rather than surfacing a
242
+ database error — the same deny-when-absent behavior the explicit `all:` /
243
+ `any:` group forms already had.
244
+
245
+ ### Root-mounted standalone actions use the standard gate stack
246
+
247
+ Standalone actions mounted outside their feature prefix
248
+ (`path: "/reports/orders"`) were emitted through a separate code path that
249
+ did not apply the full access / audit / scoped-database treatment that
250
+ in-feature standalone actions receive. They now render through the same
251
+ generator, so the same access checks, security-audit writes, and
252
+ tenant-scoped database wrapping apply everywhere. If you use root-mounted
253
+ standalone actions, recompile and redeploy. (Unifying the two code paths is
254
+ also what surfaced the two breaking changes above.)
255
+
256
+ ### Namespace routing fixes
257
+
258
+ - An action whose declared `path` exactly equals its namespace prefix is now
259
+ claimed by the namespace like any nested action (Hono's `/x/*` mount
260
+ already matched the bare `/x`) — it's served through the namespace's gate
261
+ instead of carrying a second inline copy of the resolver.
262
+ - A namespace with zero claimed standalone actions (e.g. record-based-only)
263
+ no longer mounts its middleware at all — a dead gate can no longer
264
+ intercept requests under its prefix.
265
+
266
+ ### Custom org roles work with Better Auth member management
267
+
268
+ Custom roles referenced in access trees (e.g. `roles: ["support"]`) are now
269
+ auto-registered with the Better Auth organization plugin. They were already
270
+ enforceable on routes but unprovisionable through Better Auth —
271
+ `invite-member` / `update-member-role` rejected them with
272
+ `400 ROLE_NOT_FOUND`, so there was no supported way to actually give a
273
+ member the role. Auto-registered roles carry member-equivalent permissions
274
+ (this is about assignability; your access trees remain the authorization
275
+ model). If you pass your own `roles` / `ac` to the organization plugin
276
+ options, those win and auto-registration is skipped. Built-in, pseudo, and
277
+ `scope:` roles are excluded; projects with no custom roles emit
278
+ byte-identical output.
279
+
280
+ ### snake_case tables: dropped record actions and broken helpers fixed
281
+
282
+ Two fixes for tables declared with snake_case names (`event_notes`):
283
+
284
+ - The generated `.quickback/define-action.ts` helpers imported the camelCase
285
+ identifier while the generated alias file exports the verbatim declared
286
+ name (`export { event_notes }`) — a TS2724 compile failure for any
287
+ snake_case table with action files. The helpers now import the real export
288
+ aliased to the camelCase local.
289
+ - Record actions on a snake-declared table living in a kebab-named feature
290
+ file (`event-notes/actions/pin.ts`) were not emitted — missing from both
291
+ the generated routes and OpenAPI. They now emit and document consistently.
292
+
293
+ If you have snake_case tables with record actions, recompiling **adds routes
294
+ that previously didn't exist** — review the new surface.
295
+
296
+ ### First-class MCP OAuth config: `auth.oauth`
297
+
298
+ The OAuth 2.1 surface behind `agents.mcp.requireAuth` (v0.42.0) gains a
299
+ first-class config block — env-resolvable issuer / login / consent URLs,
300
+ scopes, RFC 8707 audiences, and a dynamic-client-registration toggle:
301
+
302
+ ```ts
303
+ auth: defineAuth("better-auth", {
304
+ oauth: {
305
+ enabled: true,
306
+ issuerUrl: { env: "OAUTH_ISSUER_URL", fallback: "http://localhost:8787/auth/v1" },
307
+ loginPage: { env: "OAUTH_LOGIN_URL", fallback: "http://localhost:8787/account/login" },
308
+ consentPage: { env: "OAUTH_CONSENT_URL", fallback: "http://localhost:8787/account/consent" },
309
+ scopes: ["openid", "profile", "email", "offline_access"],
310
+ audiences: [{ env: "OAUTH_MCP_AUDIENCE", fallback: "http://localhost:8787/mcp" }],
311
+ allowDynamicClientRegistration: true,
312
+ },
313
+ }),
314
+ ```
315
+
316
+ Setting it auto-enables the `oauthProvider`, `jwt`, and `bearer` plugins,
317
+ emits the RFC 8414 / RFC 9728 discovery documents, and accepts the
318
+ provider's JWKS-signed access tokens in the standard auth middleware. A new
319
+ project hook, `quickback/hooks/resolve-oauth-context.ts`, lets you derive
320
+ tenant fields (`activeOrgId` / `activeTeamId` / roles) from the validated
321
+ OAuth identity. On Neon, the auth schema is now owned by the Better Auth CLI
322
+ end to end (the compiler no longer emits its placeholder `src/auth/schema.ts`
323
+ or `src/lib/neon.ts`). See
324
+ [OAuth Provider (MCP-ready)](/stack/auth/plugins#oauth-provider-mcp-ready)
325
+ and [Auth Hooks](/stack/account-ui/hooks#oauth-context-resolver).
326
+
327
+ ### Neon RLS covers force-enabled plugin tables
328
+
329
+ On Neon, row-level-security policies are generated for the Better Auth
330
+ tables. The list of tables receiving policies was derived from your declared
331
+ auth config and didn't account for plugins the compiler force-enables
332
+ automatically — so some auth-owned tables could be created without RLS
333
+ policies. The list now derives from the fully resolved plugin set, so every
334
+ generated auth table receives appropriate policies (self-scoped where there
335
+ is a clear owner, service-role-only otherwise — fail closed). The RLS
336
+ migration is content-addressed, so the update arrives as a new journaled
337
+ entry on the next recompile + `db:migrate`. **Neon projects should recompile
338
+ and run `db:migrate`.**
339
+
340
+ ### New compile reports: operations + conformance manifests
341
+
342
+ Every compile now writes two machine-readable reports next to
343
+ `openapi.json`:
344
+
345
+ - **`reports/operations.manifest.json`** — a stable, sorted index of every
346
+ operation: `{ operationId, method, path, auth, feature, kind }`, covering
347
+ the resource, action, view, auth, realtime, storage, and FGA surfaces. An
348
+ extend-only public contract — the recommended integration point for
349
+ scripting against the generated surface.
350
+ - **`reports/conformance.manifest.json`** — for each route × principal
351
+ class, the expected outcome (allow / 401 / 403 / cross-tenant miss …),
352
+ derived from the same IR the emitters consume. This is the artifact the
353
+ conformance fixes above were found and verified against.
354
+
355
+ The OpenAPI generator itself now reads the same IR as the route emitters, so
356
+ the spec follows the emitted surface by construction — including four
357
+ accuracy fixes: `PUT /{id}` is documented only when actually enabled, the
358
+ batch surface documents the emitter's auto-promotion + access inheritance,
359
+ and views document their effective (view-level, falling back to read-level)
360
+ access. See
361
+ [Operations manifest](/compiler/targets/hono-api/using-the-api/openapi#operations-manifest).
362
+
107
363
  ## v0.45.0 — June 9, 2026
108
364
 
109
365
  ### `auth.jwt.revocationCheck: 'kv'` — sub-TTL JWT revocation
@@ -152,6 +408,78 @@ the Cloudflare KV binding; those runtimes own immediate-revoke via the
152
408
  cookie/session path). Default remains `'none'`; without the flag the emitted
153
409
  middleware is byte-identical to v0.44.0.
154
410
 
411
+ ### Neon: `npm run db:migrate` now applies the RLS layer
412
+
413
+ The RLS SQL (helper functions, policies, triggers) used to be emitted as
414
+ orphaned `drizzle/migrations/0099–0102` files that no tool ever applied —
415
+ `db:migrate` ran the schema migrations and silently skipped the security
416
+ layer. The RLS document now rides the journaled drizzle set in
417
+ `quickback/drizzle/` as a content-addressed migration
418
+ (`<idx>_quickback_rls_<hash>`), so one `npm run db:migrate` applies schema
419
+ **and** security, in dependency order. The migration is idempotent
420
+ (`DROP POLICY IF EXISTS` + re-create), so it converges over databases where
421
+ the old files were applied by hand; an unchanged security config appends
422
+ nothing (the journal stays byte-stable across recompiles), and a changed one
423
+ appends a new content-addressed entry — append-only, like every other
424
+ migration. Existing Neon projects: recompile + `db:migrate`, nothing breaks.
425
+
426
+ ### Neon: `user_sessions` is real, and the SQL layer speaks TEXT ids
427
+
428
+ `get_active_org_id()` — the helper every org-scoped RLS policy reads — was
429
+ querying a `public.user_sessions` table that **no migration created**, and
430
+ the helper layer was typed `uuid` against Better Auth's TEXT ids
431
+ (`org_abc123`), which would throw on first contact. Now:
432
+
433
+ - `user_sessions` is compiler-owned migration state
434
+ (`src/db/rls-support.schema.ts`), created by the normal journaled flow
435
+ with a FK to the users table — outside `src/auth/schema.ts`, which the
436
+ Better Auth CLI rewrites.
437
+ - Generated Better Auth session hooks mirror the session's active
438
+ organization (and team, in teams mode) into it on create/update.
439
+ Switching to "no org" nulls it through — SQL-side access revokes, fail
440
+ closed.
441
+ - The RLS helper layer (`get_active_org_id`, `get_active_team_id`,
442
+ `is_owner`, the audit helpers) is TEXT-typed to match Better Auth ids.
443
+ - Policies for Better Auth's own tables use the plural physical names the
444
+ BA CLI actually generates on Neon, and BA tables no longer get Quickback
445
+ audit triggers for columns they don't have.
446
+
447
+ ### Hard deletes wire into the audit pipeline correctly
448
+
449
+ Two codegen bugs around `delete: { mode: 'hard' }`:
450
+
451
+ - Firewall auto-detection emitted an `isNull(deletedAt)` predicate for
452
+ tables with no soft-delete column — every read on a hard-delete table
453
+ referenced a column that doesn't exist.
454
+ - Hard-delete routes import the `logHardDelete` audit helper, but the helper
455
+ file was only emitted when the project also had unsafe or `PUBLIC` actions
456
+ — a project with hard deletes and neither failed at deploy time. Hard
457
+ deletes are now a first-class trigger of the security-audit pipeline
458
+ (helper file, `AUDIT_DB` binding, env types, audit migration); on D1 that
459
+ means [`auditDatabaseId`](/compiler/config/providers) is required, and the
460
+ compile error says so.
461
+
462
+ ### Generated output is now typechecked — with the first crop of fixes
463
+
464
+ Every compiler change now compiles a matrix of fixture projects and runs
465
+ `tsc` + `wrangler deploy --dry-run` against the **generated output** — the
466
+ class of bug where the compiler emits syntactically valid TypeScript that
467
+ fails downstream. The first runs caught real ones, all fixed here:
468
+
469
+ - **Neon:** `src/db/org.schema.ts` re-exported tables that don't exist after
470
+ the Better Auth CLI's plural rewrite; a missing `AuthDatabase` type
471
+ export; transaction callbacks typed bare `(tx)` failing `noImplicitAny`;
472
+ the auth middleware's member-table fallback hardcoded the singular name.
473
+ - **Embeddings:** the queue consumer's `Ai.run` result and the optional
474
+ `EMBEDDINGS_QUEUE` binding both failed strict checks — the route now
475
+ returns a structured `503` when the producer binding is missing instead
476
+ of crashing.
477
+ - **snake_case relationship tables:** relationship/arrow emitters imported
478
+ the camelCase identifier where the generated file exports the verbatim
479
+ table name (`export { event_guests }`) — TS2724 for any snake_case
480
+ relationship table. Imports now alias the real export
481
+ (`event_guests as eventGuests`).
482
+
155
483
  ## v0.44.0 — June 9, 2026
156
484
 
157
485
  ### Scope carry-forward is now bounded (revocation fix)
@@ -117,7 +117,7 @@ Documentation is bundled with the CLI and works offline.
117
117
  ```bash
118
118
  quickback claude install # Interactive install
119
119
  quickback claude install --global # Install to ~/.claude/skills/
120
- quickback claude install --local # Install to ./quickback/.claude/
120
+ quickback claude install --local # Install to ./.claude/
121
121
  quickback claude update # Update to latest version
122
122
  quickback claude remove # Remove installed skill
123
123
  quickback claude status # Check installation status
@@ -60,6 +60,22 @@ The `+` suffix expands at compile time — `"member+"` becomes `["member", "admi
60
60
  - Using `+` with a role not in the hierarchy throws a compile error
61
61
  - Using `+` without configuring `auth.roleHierarchy` throws a compile error
62
62
 
63
+ ## Custom org roles
64
+
65
+ You're not limited to Better Auth's built-in `owner` / `admin` / `member` —
66
+ any lowercase role name you reference in an access tree (`"recruiter"`,
67
+ `"hiring-manager"`, `"support"`, …) is a custom org-membership role, matched
68
+ against `ctx.roles` like the built-ins.
69
+
70
+ As of v0.46, custom roles declared in access trees are **auto-registered
71
+ with the Better Auth organization plugin**, so members can actually be
72
+ provisioned into them: `invite-member` and `update-member-role` accept them
73
+ (previously they rejected custom roles with `400 ROLE_NOT_FOUND`).
74
+ Auto-registered roles carry member-equivalent Better Auth permissions —
75
+ registration is about assignability; your access trees remain the
76
+ authorization model. If you pass your own `roles` / `ac` to the organization
77
+ plugin options, those win and auto-registration is skipped.
78
+
63
79
  ## Configuration Options
64
80
 
65
81
  ```typescript
@@ -149,6 +165,7 @@ access: { roles: ["PUBLIC"] }
149
165
  - `PUBLIC` skips authentication and role checks — anyone can call the endpoint
150
166
  - **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, top-level writes (`create`/`update`/`delete`/`upsert`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous write endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
151
167
  - **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
168
+ - **Tree semantics:** `PUBLIC` admits anonymous callers from anywhere in the access tree, not just a flat `roles` list. An `or:` arm containing `PUBLIC` admits anonymous callers past the authentication gate; an `and:` group admits them only when *every* arm does. The access, org, and firewall layers still evaluate the full tree afterwards. (Before v0.46 the emitted auth gate only honored `PUBLIC` in a flat `roles` list — a nested `PUBLIC` arm incorrectly answered `401`.)
152
169
  - Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
153
170
  - The wildcard `"*"` is **not supported** — using it throws a compile-time error
154
171
  - Tables with no isolation columns and any `PUBLIC` route do not require `firewall: [{ exception: true }]`
@@ -154,10 +154,15 @@ POST /applications/:id/schedule-interview
154
154
  ### Runtime Flow
155
155
 
156
156
  1. **Authentication** - User token is validated
157
- 2. **Record Loading** - The record is fetched by ID
158
- 3. **Firewall Check** - Ensures user can access this record
159
- 4. **Access Check** - Validates roles and preconditions
160
- 5. **Input Validation** - Request body validated against Zod schema
157
+ 2. **Input Validation** - Request body validated against Zod schema
158
+ 3. **Role Gate** - The access roles are checked *before* the record is
159
+ fetched (v0.46+), so a wrong-role caller gets a uniform
160
+ `403 ACCESS_ROLE_REQUIRED` whether or not the record exists — the
161
+ response can't be used to probe for record ids
162
+ 4. **Record Loading** - The record is fetched by ID **through the firewall**
163
+ (a cross-tenant or missing id is a standard firewall miss)
164
+ 5. **Access Check** - Record preconditions (`access.record`) and transition
165
+ policy are validated against the loaded record
161
166
  6. **Execution** - Your action handler runs
162
167
  7. **Response** - Result is returned to client
163
168
 
@@ -67,7 +67,7 @@ quickback claude install
67
67
  | Flag | Description |
68
68
  |------|-------------|
69
69
  | `--global` | Install to `~/.claude/` (available in all projects) |
70
- | `--local` | Install to `./quickback/.claude/` (project-specific) |
70
+ | `--local` | Install to `./.claude/` (project-specific) |
71
71
 
72
72
  ### Manage
73
73
 
@@ -11,6 +11,14 @@ npx @quickback-dev/cli start
11
11
 
12
12
  `quickback start` is interactive — it asks for a template and project name, scaffolds the project on disk, and only prompts for an account just before compiling. If you cancel at the login prompt the scaffold stays put; finish later with `quickback login && quickback compile`.
13
13
 
14
+ Already know what you want? Pass the template (and optionally a name) to skip the prompts:
15
+
16
+ ```bash
17
+ npx @quickback-dev/cli start blank # config only, no features
18
+ npx @quickback-dev/cli start todos # working CRUD example
19
+ npx @quickback-dev/cli start blog my-site # blog starter, named my-site
20
+ ```
21
+
14
22
  Prefer a scriptable form?
15
23
 
16
24
  ```bash
@@ -28,7 +36,7 @@ Both paths scaffold the same project:
28
36
  - `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold
29
37
  - `todos` — Working CRUD example with masking + actions
30
38
  - `blog` — Single-tenant blog, PUBLIC reads, admin writes
31
- - `empty` — Cloudflare scaffold, no example features
39
+ - `blank` — Cloudflare scaffold, no example features (alias: `empty`)
32
40
  - `saas` — Full B2B SaaS with orgs, R2 file storage, webhooks
33
41
 
34
42
  ## File Structure
@@ -2,12 +2,16 @@
2
2
 
3
3
  Quickback provides pre-configured templates to get you started quickly. Each template combines a runtime, database, and auth provider into a working project.
4
4
 
5
- The fastest way to start is `quickback start` — an interactive picker that asks for a template + project name and scaffolds in the current directory if it's empty, otherwise creates a subfolder. The picker offers `cloudflare`, `todos`, `blog`, and `empty`; every template (including `saas`) is available scriptably via `quickback create <template> <name>`.
5
+ The fastest way to start is `quickback start` — an interactive picker that asks for a template + project name and scaffolds in the current directory if it's empty, otherwise creates a subfolder. The picker offers `cloudflare`, `todos`, `blog`, and `blank`; every template (including `saas`) is available scriptably via `quickback create <template> <name>`.
6
6
 
7
7
  ```bash
8
8
  # Interactive (recommended for first-time use)
9
9
  mkdir my-app && cd my-app
10
10
  npx @quickback-dev/cli start
11
+
12
+ # Already know what you want? Skip the prompts:
13
+ npx @quickback-dev/cli start blank # config only, no features
14
+ npx @quickback-dev/cli start todos my-app # working CRUD example
11
15
  ```
12
16
 
13
17
  ## Available Templates
@@ -31,13 +35,13 @@ The **todos** template is the recommended first read — it exercises every secu
31
35
 
32
36
  The **blog** template uses [pinned organization mode](/compiler/config/single-tenant) and scaffolds `features.pinnedOrganizationId: "org_replace_me"`.
33
37
 
34
- ### Empty scaffold
38
+ ### Blank scaffold
35
39
 
36
40
  | Template | Includes | Command |
37
41
  |----------|----------|---------|
38
- | `empty` | `quickback.config.ts` only — no example features | `quickback create empty my-app` |
42
+ | `blank` | `quickback.config.ts` only — no example features | `quickback start blank` |
39
43
 
40
- The empty template creates the project structure with `quickback.config.ts` only. Add your first feature by creating a file under `quickback/features/<name>/<name>.ts` exporting `defineTable(...)` — there is no separate `init` step.
44
+ The blank template creates the project structure with `quickback.config.ts` only. Add your first feature by creating a file under `quickback/features/<name>/<name>.ts` exporting `defineTable(...)` — there is no separate `init` step.
41
45
 
42
46
  ### B2B SaaS
43
47
 
@@ -53,7 +57,7 @@ The `cloudflare`, `todos`, `blog`, and `saas` templates all scaffold:
53
57
  - **`quickback/features/`** — Feature definitions (empty for `cloudflare`; populated for `todos` / `blog` / `saas`)
54
58
  - **Deployment scripts** — `npm run deploy` for Cloudflare via wrangler
55
59
 
56
- The `empty` template includes only:
60
+ The `blank` template includes only:
57
61
 
58
62
  - **`quickback.config.ts`**
59
63
  - **`package.json`** — dependencies ready to install
@@ -76,7 +80,7 @@ Best for personal sites, blogs, or any app that only needs one organization at r
76
80
  - Admin-only editing
77
81
  - Pair with any frontend (Astro, Next.js, SvelteKit, etc.)
78
82
 
79
- ### Empty
83
+ ### Blank
80
84
 
81
85
  Best when you know exactly what you want to build. Gets you the project structure and config without any opinionated features.
82
86
 
@@ -94,7 +98,7 @@ For convenience, templates have short aliases:
94
98
  | `todos` | `todos-cloudflare` |
95
99
  | `blog` | `blog-cloudflare` |
96
100
  | `saas` | `b2bsaas-cloudflare` |
97
- | `empty` / `scaffold` | `empty-cloudflare` |
101
+ | `blank` / `empty` / `scaffold` | `empty-cloudflare` |
98
102
 
99
103
  ## After Scaffolding
100
104
 
@@ -53,9 +53,17 @@ Neon uses PostgreSQL migrations, distinct from D1's SQLite migrations:
53
53
 
54
54
  ```bash
55
55
  quickback compile # generates migrations under quickback/drizzle/
56
- npm run db:migrate # applies them
56
+ npm run db:migrate # applies them — schema AND the RLS layer
57
57
  ```
58
58
 
59
+ The RLS layer (helper functions, policies, triggers) rides the same
60
+ journaled migration set as your schema (v0.45+): the compiler appends a
61
+ content-addressed `<idx>_quickback_rls_<hash>` migration, so one
62
+ `db:migrate` applies everything in order. The RLS migration is idempotent
63
+ (`DROP POLICY IF EXISTS` + re-create) and only a *changed* security config
64
+ appends a new entry — recompiles with unchanged security append nothing. No
65
+ manual SQL application step exists anymore.
66
+
59
67
  ## Row Level Security
60
68
 
61
69
  Quickback emits RLS policies from your `firewall` and `access` config. The Neon target uses Neon Authorize's `auth.user_id()` JWT claim function (the Supabase target uses `auth.uid()` instead — same pattern, different function).
@@ -107,6 +115,18 @@ CREATE POLICY "categories_all" ON categories FOR ALL TO authenticated USING (tru
107
115
  | `is_org_member()` | Checks org membership |
108
116
  | `is_owner(owner_id)` | Checks record ownership |
109
117
 
118
+ All helpers are TEXT-typed to match Better Auth's prefixed ids
119
+ (`org_abc123`). The `user_sessions` table the org helpers read is
120
+ compiler-owned migration state (`src/db/rls-support.schema.ts`), created by
121
+ the journaled migrations and kept in sync automatically: generated Better
122
+ Auth session hooks mirror the session's active organization (and team) into
123
+ it on every session create/update. Switching to "no org" revokes SQL-side
124
+ access — fail closed.
125
+
126
+ RLS coverage includes Better Auth's own tables — including those the
127
+ compiler force-enables (organization, admin, `apikeys`; plus the OAuth/agent
128
+ table families when those surfaces are on, locked to service-role only).
129
+
110
130
  ## Setting up Neon Authorize
111
131
 
112
132
  1. Open **Project Settings → Authorize** in the Neon console
@@ -117,14 +137,13 @@ CREATE POLICY "categories_all" ON categories FOR ALL TO authenticated USING (tru
117
137
 
118
138
  ```
119
139
  quickback/drizzle/
120
- ├── migrations/
121
- │ ├── 0100_create_rls_helpers.sql
122
- │ ├── 0101_create_rls_policies.sql
123
- │ └── 0102_create_indexes.sql
140
+ ├── 0000_<name>.sql # schema migrations (drizzle-kit)
141
+ ├── 0001_quickback_rls_<hash>.sql # journaled RLS layer (content-addressed)
142
+ └── meta/_journal.json # one journal covers both
124
143
  src/
125
- ├── db/schema.ts # Drizzle schema
126
- ├── auth/schema.ts # Better Auth schema
127
- └── lib/neon.ts # Connection helper
144
+ ├── db/schema.ts # Drizzle schema barrel
145
+ ├── db/rls-support.schema.ts # user_sessions + RLS support tables
146
+ └── auth/schema.ts # Better Auth schema (owned by the BA CLI)
128
147
  ```
129
148
 
130
149
  ## When to choose Neon vs D1
@@ -209,7 +209,8 @@ Or enable the in-project browser via the [`docs` config option](#interactive-api
209
209
 
210
210
  Alongside the spec, every compile writes `reports/operations.manifest.json` — a
211
211
  stable, machine-readable index of the full route surface (resource, action,
212
- view, and auth routes):
212
+ view, and auth routes; since v0.47 also the realtime, storage, and FGA
213
+ surfaces):
213
214
 
214
215
  ```json
215
216
  [
@@ -15,7 +15,7 @@ Account UI provides a complete organization management interface when `VITE_ENAB
15
15
  - Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
16
16
  - Leave the organization
17
17
 
18
- > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/compiler/definitions/access) rules — with [`auth.roleHierarchy`](/compiler/definitions/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above."
18
+ > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/compiler/definitions/access) rules — with [`auth.roleHierarchy`](/compiler/definitions/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/compiler/definitions/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin (v0.46+), so `invite-member` / `update-member-role` accept them too.
19
19
 
20
20
  ## Invitations
21
21
 
@@ -7,7 +7,7 @@ Custom pages extend the CMS beyond standard table views. Define split-panel layo
7
7
  Pages are defined in your feature directory under a `pages/` folder:
8
8
 
9
9
  ```
10
- quickback/definitions/features/
10
+ quickback/features/
11
11
  banking/
12
12
  bank-accounts.ts # One table per file — any filename
13
13
  bank-transactions.ts
@@ -107,6 +107,15 @@ attendee — their realtime socket now opens.
107
107
 
108
108
  Quickback emits auto-broadcasts in **only one place**: the generated CRUD route handlers (`POST /` create, `PATCH /:id` update, `DELETE /:id` delete) for resources with `realtime.enabled` (or covered by `dbConfig.realtime: true`'s project-level default). Those handlers wrap each successful write with a `realtime.insert / update / delete` call before responding.
109
109
 
110
+ Auto-broadcasts carry the table's declared gates (v0.46+): the
111
+ `realtime.requiredRoles` list becomes the broadcast's `targetRoles` (with
112
+ role-hierarchy `+` expanded), and the table's effective masking config —
113
+ declared plus auto-detected sensitive columns — is applied per subscriber
114
+ role at fanout, matching what the HTTP routes mask. A `type: 'custom'` mask
115
+ function can't be replicated by the Broadcaster, so those columns broadcast
116
+ as `[REDACTED]` (fail closed). Tables that declare neither broadcast openly,
117
+ as before.
118
+
110
119
  Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hono routes — you broadcast manually. In action handlers on realtime-enabled projects, Quickback now injects a typed `realtime` helper directly into `execute(...)`; outside actions you still call `createRealtime(env)` yourself.
111
120
 
112
121
  | Mutation site | Auto-broadcast? | Why |
@@ -145,6 +145,10 @@ are emitted as `DELETE` so the row leaves the surface.
145
145
  - Each included table's `firewall` + `masking` apply on both the initial
146
146
  materialize and the live deltas (masking is applied per subscriber role at
147
147
  fanout), so the two are consistent.
148
+ - A table-level `realtime.requiredRoles` declaration is honored on view
149
+ deltas too (v0.46+): `view_changes` for that table fan out only to
150
+ subscribers holding one of the required roles, exactly like its row-stream
151
+ broadcasts. Tables without `requiredRoles` are unaffected.
148
152
  - **Stricter-child guard.** When a reverse-FK child's firewall is *stricter*
149
153
  than the root's (e.g. an owner-scoped note under an org-scoped person), the
150
154
  raw child row is **never broadcast**. Instead the server emits a *resync
@@ -130,7 +130,7 @@ Custom namespaces (from `defineRealtime()`) use the format `namespace:event` —
130
130
 
131
131
  ### Role-Based Filtering
132
132
 
133
- Events are only delivered to users whose role matches the broadcast's `targetRoles`. If a table's realtime config specifies `requiredRoles: ["hiring-manager", "recruiter"]`, only users with those roles receive the events.
133
+ Events are only delivered to users whose role matches the broadcast's `targetRoles`. If a table's realtime config specifies `requiredRoles: ["hiring-manager", "recruiter"]`, only users with those roles receive the events. This applies to generated CRUD broadcasts and to [live view](/stack/realtime/live-views) `view_changes` deltas alike, enforced at fanout (v0.46+ — recompile and redeploy to pick up the enforcement).
134
134
 
135
135
  ### Per-Role Masking
136
136
 
@@ -145,7 +145,7 @@ masking: {
145
145
  - **Owner sees:** `{ ssn: "123-45-6789" }`
146
146
  - **Recruiter sees:** `{ ssn: "*****6789" }`
147
147
 
148
- Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency.
148
+ Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency. A `type: 'custom'` mask function can't run inside the Broadcaster — those columns broadcast as `[REDACTED]` (fail closed).
149
149
 
150
150
  ### User-Specific Events
151
151