@quickback-dev/cli 0.46.0 → 0.47.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 (44) hide show
  1. package/dist/commands/compile.d.ts +1 -1
  2. package/dist/commands/compile.js +1 -1
  3. package/dist/docs/content.js +11 -11
  4. package/dist/docs/content.js.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/lib/file-loader.d.ts +1 -1
  7. package/dist/lib/file-loader.d.ts.map +1 -1
  8. package/dist/lib/file-loader.js +16 -3
  9. package/dist/lib/file-loader.js.map +1 -1
  10. package/dist/skill/docs/changelog.md +389 -0
  11. package/dist/skill/docs/compiler/definitions/access.md +17 -0
  12. package/dist/skill/docs/compiler/definitions/actions.md +9 -4
  13. package/dist/skill/docs/compiler/definitions/diagnostics.md +88 -57
  14. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +27 -8
  15. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +2 -1
  16. package/dist/skill/docs/stack/account-ui/features/organizations.md +1 -1
  17. package/dist/skill/docs/stack/cms/pages.md +1 -1
  18. package/dist/skill/docs/stack/realtime/durable-objects.md +9 -0
  19. package/dist/skill/docs/stack/realtime/live-views.md +4 -0
  20. package/dist/skill/docs/stack/realtime/using-realtime.md +2 -2
  21. package/package.json +1 -1
  22. package/src/skill/docs/changelog.md +389 -0
  23. package/src/skill/docs/compiler/definitions/access.md +17 -0
  24. package/src/skill/docs/compiler/definitions/actions.md +9 -4
  25. package/src/skill/docs/compiler/definitions/diagnostics.md +88 -57
  26. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +27 -8
  27. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +2 -1
  28. package/src/skill/docs/stack/account-ui/features/organizations.md +1 -1
  29. package/src/skill/docs/stack/cms/pages.md +1 -1
  30. package/src/skill/docs/stack/realtime/durable-objects.md +9 -0
  31. package/src/skill/docs/stack/realtime/live-views.md +4 -0
  32. package/src/skill/docs/stack/realtime/using-realtime.md +2 -2
  33. package/dist/commands/init.d.ts +0 -6
  34. package/dist/commands/init.d.ts.map +0 -1
  35. package/dist/commands/init.js +0 -405
  36. package/dist/commands/init.js.map +0 -1
  37. package/dist/lib/sweep-stale.d.ts +0 -25
  38. package/dist/lib/sweep-stale.d.ts.map +0 -1
  39. package/dist/lib/sweep-stale.js +0 -179
  40. package/dist/lib/sweep-stale.js.map +0 -1
  41. package/dist/lib/sweep-stale.test.d.ts +0 -2
  42. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  43. package/dist/lib/sweep-stale.test.js +0 -130
  44. package/dist/lib/sweep-stale.test.js.map +0 -1
@@ -1,5 +1,103 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.47.0 — June 11, 2026
4
+
5
+ ### Breaking: zero-false-positive analyzer checks are now compile errors
6
+
7
+ The authz/authn analyzer (v0.37) shipped warn-only. After a release cycle of
8
+ data, the checks whose every trip is a definite misconfiguration — never a
9
+ legitimate config — are **promoted to compile errors**. Warnings nobody is
10
+ forced to read are documentation; the pillar guarantees are now enforced.
11
+
12
+ **Breaking** — a config that previously compiled with one of these warnings
13
+ now fails the compile:
14
+
15
+ - `AUTHZ_EMPTY_PERMISSION` — a permission that is structurally unsatisfiable
16
+ (`allOf(a, not(a))`: a fact AND its exact negation at the same AND-level).
17
+ - `AUTHZ_CAPABILITY_CEILING` — a resource's firewall grants a
18
+ `scope:<kind>:<role>` role access beyond its capability profile (or the
19
+ role has no profile at all). This is the M0.2 pillar guarantee — it was
20
+ authored as an error all along and is now enforced.
21
+ - `AUTHN_ROUTE_COVERAGE`, `AUTHN_SURFACE_INVARIANT`,
22
+ `AUTHN_SECRET_CONSISTENCY`, `AUTHN_CREDENTIAL_DELIVERY`,
23
+ `AUTHN_CLAIM_PROVENANCE` — the structural-authn set (route auth coverage,
24
+ bearer-only `/mcp`/agent surfaces + INTERNAL unreachability, mint↔verify
25
+ key/issuer/audience pairing, anchored credential delivery, verifier-only
26
+ identity claims). These still run against empty route/credential metadata
27
+ on a real compile (no-ops until the generators emit it), but the severity
28
+ contract is locked in now — they fail the build the moment they can fire.
29
+
30
+ The heuristic/advisory checks are unchanged: `AUTHZ_SHADOWED_ARM`,
31
+ `AUTHZ_UNREACHABLE_ROLE`, `AUTHZ_UNREACHABLE_VIEW`, and
32
+ `AUTHZ_NOT_OVER_RESOURCE` stay warnings; `AUTHZ_PUSHDOWN_COST` stays an info
33
+ report. `QUICKBACK_AUTHZ_STRICT=true` still promotes those warnings too.
34
+
35
+ **The override escape hatch** — every promoted finding can be explicitly
36
+ accepted, per finding, with a required reason:
37
+
38
+ ```ts
39
+ authz: {
40
+ analyzer: {
41
+ allow: [
42
+ {
43
+ check: 'AUTHZ_CAPABILITY_CEILING',
44
+ target: 'sessions/scope:event:organizer', // from the rendered finding
45
+ reason: 'organizer grant profile lands with the v2 rollout (TICKET-123)',
46
+ },
47
+ ],
48
+ },
49
+ }
50
+ ```
51
+
52
+ An override downgrades that exact `(check, target)` finding back to a warning
53
+ that cites the reason — even under strict mode (it's an explicit, reasoned
54
+ acceptance). Every rendered error prints its exact override recipe. Guard
55
+ rails: `check` must be one of the promoted ids (unknown or keep-warn ids are
56
+ rejected at config validation), `reason` is required, and an `allow` entry
57
+ that matches no current finding is itself a compile error — no dead
58
+ overrides accumulating after the underlying issue is fixed.
59
+
60
+ Analyzer-internal defects are still fail-open: a bug in the analyzer itself
61
+ downgrades to a single warning and the compile continues. Only real findings
62
+ fail builds.
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
+
3
101
  ## v0.46.0 — June 11, 2026
4
102
 
5
103
  ### Breaking: "no organization context" responses unified on HTTP 403
@@ -43,6 +141,225 @@ redeploy; switch to the documented root URL. Actions declared *under* the
43
141
  feature prefix are untouched, and a feature whose standalone actions are all
44
142
  root-mounted no longer emits an (empty) feature actions routes file.
45
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
+
46
363
  ## v0.45.0 — June 9, 2026
47
364
 
48
365
  ### `auth.jwt.revocationCheck: 'kv'` — sub-TTL JWT revocation
@@ -91,6 +408,78 @@ the Cloudflare KV binding; those runtimes own immediate-revoke via the
91
408
  cookie/session path). Default remains `'none'`; without the flag the emitted
92
409
  middleware is byte-identical to v0.44.0.
93
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
+
94
483
  ## v0.44.0 — June 9, 2026
95
484
 
96
485
  ### Scope carry-forward is now bounded (revocation fix)
@@ -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