@quickback-dev/cli 0.18.0 → 0.34.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 (93) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +25 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/migrations.d.ts +17 -0
  5. package/dist/commands/migrations.d.ts.map +1 -0
  6. package/dist/commands/migrations.js +328 -0
  7. package/dist/commands/migrations.js.map +1 -0
  8. package/dist/docs/content.d.ts.map +1 -1
  9. package/dist/docs/content.js +33 -63
  10. package/dist/docs/content.js.map +1 -1
  11. package/dist/index.js +7 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/lib/api-client.d.ts +17 -0
  14. package/dist/lib/api-client.d.ts.map +1 -1
  15. package/dist/lib/api-client.js.map +1 -1
  16. package/dist/lib/file-loader.d.ts +39 -0
  17. package/dist/lib/file-loader.d.ts.map +1 -1
  18. package/dist/lib/file-loader.js +73 -0
  19. package/dist/lib/file-loader.js.map +1 -1
  20. package/dist/lib/file-loader.test.js +22 -1
  21. package/dist/lib/file-loader.test.js.map +1 -1
  22. package/dist/skill/docs/changelog.md +1118 -1
  23. package/dist/skill/docs/compiler/config/domains.md +70 -10
  24. package/dist/skill/docs/compiler/config/index.md +74 -3
  25. package/dist/skill/docs/compiler/config/output.md +1 -1
  26. package/dist/skill/docs/compiler/config/providers.md +6 -12
  27. package/dist/skill/docs/compiler/config/single-tenant.md +1 -1
  28. package/dist/skill/docs/compiler/config/variables.md +0 -30
  29. package/dist/skill/docs/compiler/definitions/access.md +357 -3
  30. package/dist/skill/docs/compiler/definitions/actions.md +85 -8
  31. package/dist/skill/docs/compiler/definitions/schema.md +6 -10
  32. package/dist/skill/docs/compiler/index.md +15 -34
  33. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  34. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  35. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  36. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  37. package/dist/skill/docs/compiler/targets/index.md +6 -34
  38. package/dist/skill/docs/index.md +2 -5
  39. package/dist/skill/docs/stack/account-ui/customization.md +2 -14
  40. package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
  41. package/dist/skill/docs/stack/account-ui/features/admin.md +2 -2
  42. package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
  43. package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
  44. package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
  45. package/dist/skill/docs/stack/account-ui/hooks.md +4 -0
  46. package/dist/skill/docs/stack/account-ui/index.md +5 -43
  47. package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
  48. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
  49. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
  50. package/dist/skill/docs/stack/auth/plugins/index.md +106 -0
  51. package/package.json +1 -1
  52. package/src/skill/docs/changelog.md +1057 -0
  53. package/src/skill/docs/compiler/config/domains.md +26 -0
  54. package/src/skill/docs/compiler/config/index.md +74 -3
  55. package/src/skill/docs/compiler/config/providers.md +6 -12
  56. package/src/skill/docs/compiler/config/single-tenant.md +1 -1
  57. package/src/skill/docs/compiler/config/variables.md +0 -30
  58. package/src/skill/docs/compiler/definitions/access.md +357 -3
  59. package/src/skill/docs/compiler/definitions/actions.md +85 -8
  60. package/src/skill/docs/compiler/definitions/schema.md +6 -10
  61. package/src/skill/docs/compiler/index.md +15 -34
  62. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  63. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  64. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  65. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  66. package/src/skill/docs/compiler/targets/index.md +6 -34
  67. package/src/skill/docs/index.md +2 -5
  68. package/src/skill/docs/stack/account-ui/customization.md +2 -14
  69. package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
  70. package/src/skill/docs/stack/account-ui/features/admin.md +2 -2
  71. package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
  72. package/src/skill/docs/stack/account-ui/features/index.md +1 -1
  73. package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
  74. package/src/skill/docs/stack/account-ui/hooks.md +4 -0
  75. package/src/skill/docs/stack/account-ui/index.md +5 -43
  76. package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
  77. package/src/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
  78. package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
  79. package/src/skill/docs/stack/auth/plugins/index.md +32 -0
  80. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  81. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  82. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  83. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
  85. package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
  86. package/dist/skill/docs/stack/account-ui/worker.md +0 -362
  87. package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  88. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  89. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  90. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  91. package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
  92. package/src/skill/docs/stack/account-ui/standalone.md +0 -149
  93. package/src/skill/docs/stack/account-ui/worker.md +0 -362
@@ -220,9 +220,9 @@ Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platfor
220
220
  read: { access: { roles: ["SYSADMIN"] } }
221
221
  ```
222
222
 
223
- `SYSADMIN` is a strict superset of `ADMIN` — at runtime, the universal-bypass shortcuts in `evaluateAccess` admit `userRole === 'sysadmin'` anywhere they admit `userRole === 'admin'`. The distinction matters for one thing only: **the firewall escape hatch**. When `cms.sysadmin: true`, every `buildFirewallConditions` emits an `if (ctx.userRole === 'sysadmin') return undefined;` (or just the soft-delete predicate when present) at the top — so sysadmins see every tenant's rows, not just their own org's. That escape hatch does NOT fire for `userRole === 'admin'`; admins still go through the firewall like everyone else.
223
+ `ADMIN` and `SYSADMIN` are **independent** at the evaluator level — `ADMIN` admits `userRole === 'admin'` only, `SYSADMIN` admits `userRole === 'sysadmin'` only. Routes that need both write `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly. The one place sysadmin gets implicit extra powers is **the firewall escape hatch**: when `cms.sysadmin: true`, every `buildFirewallConditions` emits an `if (ctx.userRole === 'sysadmin') return undefined;` (or just the soft-delete predicate when present) at the top — so sysadmins see every tenant's rows, not just their own org's. That escape hatch does NOT fire for `userRole === 'admin'`; admins still go through the firewall like everyone else.
224
224
 
225
- This separation exists so Better Auth admin-plugin powers (user management, impersonation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'admin'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/compiler/config#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `/admin/v1/sysadmin/organizations` endpoint, and the SPA's "All organizations" sentinel.
225
+ This separation exists so Better Auth admin-plugin powers (user management, impersonation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'admin'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/compiler/config#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `/auth/v1/admin/list-organizations` endpoint, and the SPA's "All organizations" sentinel.
226
226
 
227
227
  #### Mixing pseudo-roles with real roles
228
228
 
@@ -321,10 +321,121 @@ Resource definitions reference declared roles by name in `roles: [...]` arrays e
321
321
  | `crud.*.access` `roles: ['guest']` | ✓ Supported | Inline async lookup per request |
322
322
  | `read.access` / `read.views.*.access` `roles: ['guest']` | ✓ Supported | Same inline path |
323
323
  | `masking.<field>.show` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — async/batched mask functions deferred |
324
- | `actions.<name>.access` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — explicit `relationshipBindings` deferred |
324
+ | **Standalone** `actions.<name>.access` `roles: ['guest']` | ✓ Supported (v0.19+) | Inline gate; surface must expose `resource.column` as path param or input field |
325
+ | **Record-based** `actions.<name>.access` `roles: ['guest']` | ⚠ Fail-closed at runtime | Runtime helper denies; inline emission is a planned follow-up. Use `firewall: { exception: true }` or move the check into `execute()` until then |
325
326
 
326
327
  For the surfaces that are not yet supported, the compiler refuses at build time with a clear error pointing to a workaround. The runtime evaluator fails closed on relationship arms regardless, so silent grants are impossible.
327
328
 
329
+ ### Standalone actions: surface keys and `loads` / `exposeAs` (v0.19+)
330
+
331
+ When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the compiler:
332
+
333
+ - **v0.19** — emits a `[quickback:authz]` warning and skips resolver emission. The action's own hand-rolled gate (if any) keeps the route working at runtime.
334
+ - **v0.20** — hard compile error. Set `firewall: { exception: true }` to opt out (cross-tenant/admin routes only).
335
+
336
+ Pair the relationship with `loads` + `exposeAs` to hydrate the loaded resource onto `ctx`:
337
+
338
+ ```typescript
339
+ authz: {
340
+ relationships: {
341
+ attendeeOf: {
342
+ from: 'guests',
343
+ subject: { column: 'userId', equals: 'ctx.userId' },
344
+ resource: { column: 'eventId' },
345
+ where: { status: 'confirmed' },
346
+ loads: 'events', // ← v0.19+: load matching event row
347
+ exposeAs: 'event', // ← onto ctx.event for the action body
348
+ },
349
+ },
350
+ roles: {
351
+ attendee: { via: 'attendeeOf' },
352
+ },
353
+ }
354
+ ```
355
+
356
+ The resolver (v0.20):
357
+
358
+ 1. **Cheap in-memory role check** first — `ctx.roles?.includes('admin')` and friends. If the caller has a qualifying role, this short-circuits and no DB queries fire for the access gate.
359
+ 2. **Firewall-gated relationship match** if the role check failed — `SELECT { organizationId, teamId } FROM guests WHERE userId=ctx.userId AND eventId=input.eventId AND status='confirmed'` with the `guests` table's full firewall AND-applied. If neither role nor relationship qualifies → 403.
360
+ 3. **Tenant stamping from the matched row** — for any tenant column the `from` table carries (`organizationId`, `teamId`), the resolver stamps `ctx.activeOrgId ??= matchedRow.organizationId` (and similar for team). This is **in-memory mutation of the request-scoped ctx only** — no JWT remint, no session-record write, no persistent grant.
361
+ 4. **Firewall-gated load of the loaded resource** — `SELECT * FROM events WHERE id = :eventId AND buildEventsFirewallConditions(ctx, db)`. The events firewall is applied as normal; it succeeds for attendees because tenant was just stamped from the relationship row.
362
+ 5. Assigns the loaded row to `ctx.event` for the action body.
363
+
364
+ **No firewall bypass anywhere.** Both queries run with their respective tables' full firewalls. The relationship row's existence is the proof that the caller is authorized; its tenant columns are the source of the stamped claim.
365
+
366
+ ### Conditional tenant preconditions (v0.20+)
367
+
368
+ Standalone actions in features with org/team-scoped tables previously emitted unconditional preconditions:
369
+
370
+ ```ts
371
+ if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
372
+ if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
373
+ ```
374
+
375
+ These ran **before** the relationship resolver, which 403'd attendees whose sessions don't carry an active tenant claim (the canonical event-attendee shape).
376
+
377
+ v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / ADMIN / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before.
378
+
379
+ Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
380
+
381
+ ### Requirement on the relationship's `from` table
382
+
383
+ For the v0.20 tenant-stamping to work, the relationship's `from` table must carry tenant columns:
384
+
385
+ - For org stamping: an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
386
+ - For team stamping: a `teamId` column.
387
+
388
+ When the `from` table has **neither**, the compiler emits a `[quickback:authz]` warning at compile time:
389
+
390
+ ```
391
+ Relationship "X" at authz.relationships.X has no organization or team columns
392
+ on its `from` table ("guests"). Action "Y" will compile, but downstream
393
+ scoped-db queries inside execute() may 403 because ctx.activeOrgId /
394
+ activeTeamId cannot be stamped from the match row. Either add the tenant
395
+ column to "guests", or set firewall: { exception: true } on the action.
396
+ ```
397
+
398
+ The relationship match still works (existence check), but no tenant gets stamped — so the conventional precondition still fires and the action still 403s for callers without a session-resident tenant claim. Add the tenant column (or denormalize it onto the relationship table during writes) to enable the stamping path.
399
+
400
+ The body can then trust `ctx.event` and drop the hand-rolled `SELECT … FROM guests WHERE …` boilerplate:
401
+
402
+ ```ts
403
+ // features/chat/actions/getInbox.ts
404
+ export default defineAction({
405
+ path: '/chat/get-inbox',
406
+ input: z.object({ eventId: z.number().int().positive() }),
407
+ access: { roles: ['admin', 'member', 'attendee'] }, // attendee is a relationship-role
408
+ execute: async ({ db, ctx, input }) => {
409
+ // No hand-rolled attendance check needed — the resolver already ran.
410
+ // ctx.event is the loaded events row. Typed as `any` here because the
411
+ // hand-rolled `roles: ['attendee']` action gates per-action, not per-
412
+ // namespace — see "Narrow ctx.<exposeAs> typing" below for the typed
413
+ // import flip available when the same hydration runs through a
414
+ // namespace mount.
415
+ const event = ctx.event as typeof events.$inferSelect;
416
+ // … domain logic only.
417
+ },
418
+ });
419
+ ```
420
+
421
+ `loads` and `exposeAs` are co-required (set both or neither). `exposeAs` must be a valid JS identifier and must not collide with built-in `ctx` fields (`userId`, `activeOrgId`, `activeTeamId`, `db`, etc.).
422
+
423
+ ### Action firewall escape hatch (v0.19+)
424
+
425
+ `defineAction({ firewall: { exception: true } })` opts the action out of the inherited session-key preconditions (`ctx.activeOrgId` / `ctx.activeTeamId` requirements) AND the relationship resolver. The handler receives `unsafeDb` for raw Drizzle access. Use for cross-tenant or admin routes whose surface intentionally doesn't name a session/relationship key:
426
+
427
+ ```ts
428
+ defineAction({
429
+ path: '/admin/cross-tenant-report',
430
+ firewall: { exception: true },
431
+ unsafe: { reason: 'cross-tenant audit', adminOnly: true, targetScope: 'all' },
432
+ access: { roles: ['ADMIN'] },
433
+ execute: async ({ unsafeDb, ctx }) => { /* cross-org query */ },
434
+ });
435
+ ```
436
+
437
+ `firewall: { exception: true }` is the declarative twin of `unsafe: true` — they're conceptually distinct: `firewall.exception` opts out of the gate-emission pillars; `unsafe` signals audit/cross-tenant intent (and still applies for logging). Most cross-tenant actions set both.
438
+
328
439
  ### Recommended pattern: gate at the firewall layer
329
440
 
330
441
  Most of the time, relationship-based row visibility is what you want, and putting it at the **firewall** layer is the cleanest expression. The firewall is row-filter; the access layer is route/role-filter; let each do its job:
@@ -434,6 +545,249 @@ The validator and resolver reject:
434
545
  - `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
435
546
  - Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
436
547
 
548
+ ## Namespace mounts (hoisted relationship middleware)
549
+
550
+ When several standalone actions share a path prefix and the same relationship gate — `/event/:eventId/announce`, `/event/:eventId/cancel`, `/event/:eventId/respond` — declaring the gate per-action means writing the same `roles: ['attendee']` over and over AND paying the relationship-resolver cost N times per request (one subquery + one row-load, multiplied by the number of actions).
551
+
552
+ Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware before the action's `execute()` runs. With the per-namespace helper (v0.27+, [below](#narrow-ctxexposeas-typing-v027)), that field is also statically typed as the loaded row.
553
+
554
+ ### When to use roles vs. relationships
555
+
556
+ A user is authorized for a row when **any** of the following is true:
557
+
558
+ - they have a **per-row relationship** to it (e.g. an attendee row, a named organizer row), or
559
+ - they have a **role on the row's tenant** (org admin/owner of the row's `organizationId`), or
560
+ - they have **team membership** matching the row's `teamId`.
561
+
562
+ Use **relationships** when membership is specific to *this row* — external collaborators who aren't in your org, attendees, anyone connected to the resource by virtue of data rather than payroll. Use **roles / team** when staff at your org/team should see everything in their scope by default.
563
+
564
+ The two compose at the action level (`access.or` accepts both relationship-roles and tenant roles) and — as of v0.25 — at the namespace level too: `namespace.via` accepts an array of lanes, first match wins.
565
+
566
+ > **Rule of thumb.** If the answer is *"yes if you work here,"* reach for org/team roles. If the answer is *"yes if you have something to do with **this** row,"* reach for a per-row relationship. Reach for both together — at the namespace or via `access.or` — when an action should let either side in.
567
+
568
+ Two declaration sites depending on whether the participating actions live in one feature or many:
569
+
570
+ ### Single feature: `defineTable({ namespace })` (v0.23+)
571
+
572
+ Use when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it — no addition to `quickback.config.ts` needed.
573
+
574
+ ```typescript
575
+ // features/events/events.ts
576
+ export default defineTable(events, {
577
+ firewall: [...],
578
+ crud: { ... },
579
+ namespace: {
580
+ prefix: '/event/:eventId', // absolute URL path
581
+ via: 'attendeeOf', // relationship gate (must exist in authz.relationships)
582
+ },
583
+ });
584
+
585
+ // features/events/actions/post-announcement.ts
586
+ export default defineAction({
587
+ path: '/event/:eventId/announcements',
588
+ method: 'POST',
589
+ // No gate boilerplate. ctx.event is typed inside execute().
590
+ });
591
+ ```
592
+
593
+ The compiler emits one `app.use(...)` on the events feature's Hono app. Every standalone action in `features/events/actions/` whose path starts with `/event/:eventId/` joins the namespace automatically.
594
+
595
+ Multi-lane via (v0.25+) and bulk-grant lanes (v0.26+) work identically on the table-level declaration — `via:` accepts the same shapes documented below for the project-level form.
596
+
597
+ ### Cross-feature: `authz.namespaces` (v0.24+)
598
+
599
+ Use when the namespace spans multiple features. The declaration sits next to your other authz config in `quickback.config.ts`.
600
+
601
+ ```typescript
602
+ // quickback.config.ts
603
+ authz: {
604
+ relationships: {
605
+ attendeeOf: {
606
+ from: 'guests',
607
+ subject: { column: 'userId', equals: 'ctx.userId' },
608
+ resource: { column: 'eventId' },
609
+ loads: 'events',
610
+ exposeAs: 'event',
611
+ },
612
+ },
613
+ namespaces: {
614
+ eventScope: { prefix: '/event/:eventId', via: 'attendeeOf' },
615
+ },
616
+ }
617
+ ```
618
+
619
+ With the namespace declared, any standalone action whose `path:` matches the prefix joins the gate — regardless of which feature owns it:
620
+
621
+ ```typescript
622
+ // features/feeds/actions/feed-moments.ts (in one feature)
623
+ export default defineAction({
624
+ path: '/event/:eventId/feed-moments',
625
+ method: 'POST',
626
+ });
627
+
628
+ // features/rsvp/actions/respond.ts (in a different feature)
629
+ export default defineAction({
630
+ path: '/event/:eventId/respond',
631
+ method: 'POST',
632
+ });
633
+ ```
634
+
635
+ The compiler emits one synthetic `src/routes/__namespace-event-scope.routes.ts` that imports each contributing feature's `actions` map under a distinct alias, mounts the resolver middleware once, and dispatches to the matching action. Worker-root mount order ensures the middleware fires before any per-feature route handler under the prefix.
636
+
637
+ ### Multi-lane via (v0.25+) — first match wins
638
+
639
+ When more than one relationship can authorize a caller for the namespaced resource, pass `via:` as an array. The middleware tries each lane in declaration order and stops at the first match — `ctx.<exposeAs>` is hydrated from whichever lane fired.
640
+
641
+ ```typescript
642
+ authz: {
643
+ relationships: {
644
+ attendeeOf: {
645
+ from: 'guests',
646
+ subject: { column: 'linkedUserId', equals: 'ctx.userId' },
647
+ resource: { column: 'eventId' },
648
+ where: { status: 'confirmed' },
649
+ loads: 'events',
650
+ exposeAs: 'event',
651
+ },
652
+ // Named per-event organizers (potentially EXTERNAL — these users may
653
+ // not be a member of the event's org. That's the point: lets you grant
654
+ // event-level access to freelancers / partner staff without adding
655
+ // them to the org's member list.)
656
+ organizerOf: {
657
+ from: 'eventOrganizers',
658
+ subject: { column: 'linkedUserId', equals: 'ctx.userId' },
659
+ resource: { column: 'eventId' },
660
+ loads: 'events',
661
+ exposeAs: 'event',
662
+ },
663
+ },
664
+ namespaces: {
665
+ eventScope: {
666
+ prefix: '/event/:eventId',
667
+ via: ['attendeeOf', 'organizerOf'],
668
+ },
669
+ },
670
+ }
671
+ ```
672
+
673
+ All relationship lanes in a namespace **must agree on `loads:` + `exposeAs:`** — that's what guarantees `ctx.event` has the same shape regardless of which lane matched. The compiler rejects heterogeneous lanes at parse time.
674
+
675
+ ### Bulk-grant lanes (v0.26+)
676
+
677
+ Relationship lanes cover "specifically connected to this row." Bulk-grant lanes cover "anyone with this role / team membership in the row's tenant" — the case where an org admin or a team member should see every event in their scope without writing per-event relationship rows.
678
+
679
+ ```typescript
680
+ namespaces: {
681
+ eventScope: {
682
+ prefix: '/event/:eventId',
683
+ via: [
684
+ 'attendeeOf',
685
+ 'organizerOf',
686
+ { roles: ['admin', 'owner'] }, // org-role bulk grant
687
+ { team: true }, // active-team-membership bulk grant
688
+ ],
689
+ },
690
+ }
691
+ ```
692
+
693
+ Each bulk-grant lane:
694
+
695
+ - **`{ roles: [...] }`** — passes when the caller's BA org-role for the loaded resource's tenant includes any listed role. Short-circuits the relationship loop entirely; the role check is in-memory and cheap. Use for the "company admin sees everything" case.
696
+ - **`{ team: true }`** — passes when `ctx.activeTeamId` is set. The loads-table firewall does the actual `events.teamId === ctx.activeTeamId` check during hydration. Use when the resource is team-scoped and you want active-team membership to grant access.
697
+
698
+ Both bulk-grant lanes piggyback on the namespace's relationship lane(s) for hydration — they don't fetch a separate per-row subject; they just gate access and let the loads-table firewall handle the tenant scoping. **At least one relationship lane is required** alongside bulk-grant lanes in v0.26 (to anchor `loads:` + `exposeAs:`).
699
+
700
+ When a request misses every lane, the 403 deny payload lists every authorization path the caller could have taken — relationship names, role names, and `"team-membership"` for `{ team: true }` lanes — so a developer debugging an unexpected 403 sees the full surface they need to satisfy.
701
+
702
+ ### Discovery is path-prefix-only
703
+
704
+ Actions opt in by matching `path:` against a declared namespace prefix. There's no `namespace: 'foo'` field on `defineAction` — the path string is the discoverable surface, consistent with how `path:` already determines an action's URL.
705
+
706
+ ### Requirements (enforced at compile time)
707
+
708
+ Both forms share the same shape checks:
709
+
710
+ - **`via:` accepts one of three shapes.** A single relationship name (v0.23+), an array of relationship names (v0.25+, first match wins), or — as of v0.26 — an array mixing relationship names with bulk-grant guards (`{ roles: [...] }`, `{ team: true }`).
711
+ - **Every relationship lane must declare `loads + exposeAs`.** Without `loads` there's nothing for the middleware to hydrate; the namespace gate would be indistinguishable from a per-action access rule.
712
+ - **All relationship lanes in one namespace must agree on `loads:` + `exposeAs:`.** Otherwise `ctx.<exposeAs>` would change shape depending on which lane matched.
713
+ - **Bulk-grant lanes inherit `loads:` + `exposeAs:` from sibling relationship lanes.** Pure bulk-grant namespaces (no relationship lane at all) are also accepted — set `loads:` + `exposeAs:` directly on the namespace declaration so hydration has somewhere to anchor.
714
+ - **`prefix:` must contain at least one `:param` segment** (e.g. `/event/:eventId`). The middleware reads the relationship key from `c.req.param()` because no request body has been parsed at middleware time.
715
+ - **One declaration per namespace name.** The same name in both `defineTable({ namespace })` and `authz.namespaces` is rejected. The project-level form is canonical for cross-feature; the table-level form is the single-feature shorthand.
716
+
717
+ Project-level only:
718
+
719
+ - **Ambiguous prefixes** like `/a/:x` and `/a/:y` (same shape, different `:param` names) are rejected. Strict super/sub-set relationships (`/event/:e` vs `/event/:e/admin`) are fine — the harvester routes each action to the longest matching prefix.
720
+ - **Unused namespace** emits a `[quickback:authz]` warning when no action's path matches the declared prefix. Not a hard error — the namespace may be staged ahead of the actions.
721
+
722
+ ### What namespace actions get for free
723
+
724
+ Inside a namespace action's `execute()`:
725
+
726
+ - `ctx.<exposeAs>` is populated by the middleware with the loaded resource row. Statically `any` by default — narrowed to `typeof <loadsTable>.$inferSelect` when the action's import points at the per-namespace helper (see [below](#narrow-ctxexposeas-typing-v027)).
727
+ - Tenant context (`ctx.activeOrgId` / `ctx.activeTeamId`) is stamped from the matched relationship row when its `from` table carries those columns. Downstream scoped queries work without further setup.
728
+ - The action's own `access:` block (additional roles, userRole, record predicates, OTHER relationship arms) still runs after the namespace gate — namespace handles entry, per-action gates further.
729
+
730
+ ### Narrow `ctx.<exposeAs>` typing (v0.27+)
731
+
732
+ The namespace middleware hydrates `ctx.<exposeAs>` at runtime — that's been true since v0.23. The static type of that field, though, is `any` via the `AppContext` index signature: useful for not blocking access, but a missed opportunity for autocomplete and typo-catching.
733
+
734
+ v0.27 emits one **per-namespace `defineAction` helper** alongside the standard `<feature>/.quickback/define-action.ts`. Importing from the narrowed helper retypes `ctx.<exposeAs>` inside `execute({ ctx })` to the loaded row's `$inferSelect` shape. Nothing else changes — runtime behavior, action discovery, and the `path:` namespace match are identical.
735
+
736
+ ```ts title="features/feeds/actions/feed-moments.ts"
737
+ // One-line flip per namespace-scoped action:
738
+ import { defineAction } from '../.quickback/define-action.event-scope';
739
+ // └──────┬──────┘
740
+ // kebab(namespaceName)
741
+
742
+ export default defineAction({
743
+ path: '/event/:eventId/feed-moments',
744
+ method: 'POST',
745
+ input: z.object({ body: z.string() }),
746
+ access: { roles: ['attendee'] },
747
+ async execute({ ctx, input }) {
748
+ ctx.event.id // ✓ string
749
+ ctx.event.startsAt // ✓ Date — autocomplete works
750
+ ctx.event.organizerId // ✓ narrows on the field's declared type
751
+
752
+ ctx.event.idd // ✗ TS2339 — typo caught at compile time
753
+ },
754
+ });
755
+ ```
756
+
757
+ The compiler emits one helper per `(feature, namespace)` pair where the feature owns at least one action whose `path:` falls under the namespace prefix. Filename is `define-action.<kebab(namespaceName)>.ts` — `eventScope` becomes `define-action.event-scope.ts`. Helpers live next to the standard `define-action.ts` in `<feature>/.quickback/`, so the relative import is the same shape as every other action file in your project.
758
+
759
+ #### Opt-in, not breaking
760
+
761
+ Actions that keep their existing `import { defineAction } from '../.quickback/define-action'` continue to compile unchanged — `ctx.<exposeAs>` is `any` via the `AppContext` index signature, which is exactly the v0.23–v0.26 behavior. You flip imports per action at your own pace.
762
+
763
+ #### Compile-time advisory
764
+
765
+ When `quickback compile` sees a namespace-scoped action still importing the generic helper, it emits a one-line advisory pointing at the narrowed path:
766
+
767
+ ```text
768
+ [quickback:typing] action "feedMoments" in feature "feeds" lives under
769
+ namespace "eventScope" — switch its import to
770
+ `../.quickback/define-action.event-scope` for narrow ctx.<exposeAs> typing.
771
+ (Runtime behavior is unchanged; the narrowed helper only refines TS types.)
772
+ ```
773
+
774
+ Non-blocking — same `[quickback:typing]` family as `[quickback:authz]`. The advisory only mentions actions the compiler can be confident about (namespace-claimed actions whose source still imports the generic helper).
775
+
776
+ #### Multi-namespace features
777
+
778
+ A single feature can contribute actions to several namespaces — say, an `interviews` feature with actions under both `interviewScope` and `eventScope`. The compiler emits one narrowed helper per namespace the feature participates in, and each action picks the import that matches its path.
779
+
780
+ ```text
781
+ src/features/interviews/.quickback/
782
+ ├── define-action.ts # generic — standard fallback
783
+ ├── define-action.interview-scope.ts # ctx.interview typed
784
+ └── define-action.event-scope.ts # ctx.event typed
785
+ ```
786
+
787
+ #### Why per-namespace and not per-action
788
+
789
+ A `defineAction` helper that's narrow to *one* exposed key (the namespace's `exposeAs`) is enough — every action under a namespace sees the same hydrated key. The alternative (per-action emit) duplicates the same prelude N times for the same shape; per-namespace keeps emission proportional to the number of distinct hydration shapes in the project.
790
+
437
791
  ## Read & Write Configuration
438
792
 
439
793
  Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under top-level `create:`, `update:`, `delete:`, and `upsert:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.
@@ -127,7 +127,7 @@ export default defineAction({
127
127
  | `access` | Yes | Access control (roles, record conditions, or function) |
128
128
  | `execute` | Yes | Inline async arrow function (`async (ctx) => { … }`) |
129
129
  | `path` | Standalone only | Custom route path. Presence of `path` makes the action standalone. |
130
- | `method` | No | HTTP method: GET, POST, PUT, PATCH, DELETE (default: POST) |
130
+ | `method` | No | HTTP method: GET, POST, PUT, PATCH, DELETE (default: POST). GET actions parse `input` from query params; all other methods parse from the JSON body. See [GET vs POST for input](#get-vs-post-for-input). |
131
131
  | `responseType` | No | Response format: json, stream, file (default: json) |
132
132
  | `sideEffects` | No | Hint for AI tools: `'sync'`, `'async'`, or `'fire-and-forget'` |
133
133
  | `allowRawSql` | No | Explicit compile-time opt-in for raw SQL in execute code |
@@ -304,9 +304,9 @@ land in `success[]` masked the same way the single-record response is.
304
304
 
305
305
  | Provider | failFast | transactional | Behavior |
306
306
  |---|---|---|---|
307
- | postgres / supabase / neon / libsql / sqlite drivers | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
307
+ | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
308
308
  | (any) | `false` | `false` | Independent per-record outcomes, partial success |
309
- | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed |
309
+ | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed (D1 has no `db.transaction`) |
310
310
 
311
311
  **Constraints:**
312
312
 
@@ -404,6 +404,50 @@ export default defineAction({
404
404
  });
405
405
  ```
406
406
 
407
+ ### GET vs POST for input
408
+
409
+ GET actions read `input` from URL query parameters; every other method (POST,
410
+ PUT, PATCH, DELETE) reads from the JSON body. The Zod schema is the same in
411
+ both cases — the compiler picks the right parser based on `method`.
412
+
413
+ ```typescript
414
+ // GET — input populated from ?q=…&limit=…
415
+ defineAction({
416
+ method: "GET",
417
+ path: "/search",
418
+ input: z.object({
419
+ q: z.string(),
420
+ limit: z.coerce.number().int().positive().max(100).default(20),
421
+ }),
422
+ access: { roles: ["AUTHENTICATED"] },
423
+ async execute({ input }) {
424
+ // input is { q: string, limit: number } — fully typed.
425
+ },
426
+ });
427
+ ```
428
+
429
+ Repeated query keys (`?tag=a&tag=b`) come through as arrays automatically;
430
+ single values stay as strings. Use Zod's `.coerce.number()` /
431
+ `.coerce.boolean()` when you want typed primitives from the parsed strings.
432
+
433
+ **Use POST when input is structured.** GET requests cannot carry a JSON body
434
+ in any of the surfaces Quickback APIs are commonly called from:
435
+
436
+ - Browsers throw on `fetch(url, { method: 'GET', body })`.
437
+ - CDNs and caches key on URL+method; a GET with a body either gets the body
438
+ stripped at the edge or cache-collides with semantically different requests.
439
+ - OpenAPI client generators (axios, openapi-fetch, openapi-typescript-codegen)
440
+ refuse to emit GET-with-body, so the generated SDKs break.
441
+ - The MCP agent surface treats GET as parameter-only — agents calling a GET
442
+ action will only see what the URL exposes.
443
+
444
+ If your action takes nested objects, arrays of objects, or large inputs that
445
+ don't serialize cleanly to a query string, set `method: "POST"`. POST doesn't
446
+ imply "this writes data" — it's the right method whenever the request body is
447
+ load-bearing. Use the response shape (`responseType: "json"`, or just the data
448
+ your handler returns) to convey read semantics; HTTP method choice is about
449
+ input transport, not action intent.
450
+
407
451
  ## Access Configuration
408
452
 
409
453
  Access controls who can execute an action and under what conditions.
@@ -502,13 +546,46 @@ access: async (ctx, record) => {
502
546
  }
503
547
  ```
504
548
 
505
- ### Relationship-roles in actions (v1 limitation)
549
+ ### Relationship-roles in actions
550
+
551
+ **v0.19+** — standalone actions now support relationship-roles in `access.roles` directly. Declare the relationship under `authz.relationships` with optional `loads` / `exposeAs` for ctx hydration, and reference the role by name on the action:
552
+
553
+ ```ts
554
+ // quickback.config.ts
555
+ authz: {
556
+ relationships: {
557
+ attendeeOf: {
558
+ from: 'guests',
559
+ subject: { column: 'userId', equals: 'ctx.userId' },
560
+ resource: { column: 'eventId' },
561
+ where: { status: 'confirmed' },
562
+ loads: 'events',
563
+ exposeAs: 'event',
564
+ },
565
+ },
566
+ roles: { attendee: { via: 'attendeeOf' } },
567
+ }
568
+
569
+ // features/chat/actions/getInbox.ts
570
+ export default defineAction({
571
+ path: '/chat/get-inbox',
572
+ input: z.object({ eventId: z.number().int().positive() }),
573
+ access: { roles: ['admin', 'member', 'attendee'] },
574
+ execute: async ({ db, ctx, input }) => {
575
+ // The resolver already verified attendance and loaded ctx.event.
576
+ // No hand-rolled `SELECT … FROM guests WHERE …` needed.
577
+ },
578
+ });
579
+ ```
580
+
581
+ The action's surface (path params + input fields) must expose the relationship's `resource.column`. At v0.19 a missing key emits a `[quickback:authz]` warning and skips resolver emission; at v0.20 it becomes a compile error. See [Access — standalone actions](/compiler/definitions/access#standalone-actions-surface-keys-and-loads--exposeas-v019) for the full mechanism.
506
582
 
507
- Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in action access blocks**. The compiler refuses to build with a clear error message because the binding semantics — which input field or which loaded record's column to check the relationship against — differ between record-actions and standalone-actions and require explicit declaration not yet wired in v1.
583
+ **Record-based actions** are NOT yet supported — the runtime evaluator fail-closes (403) on relationship arms reached without an inline gate. Until inline emission for record-based actions lands, either:
508
584
 
509
- The runtime evaluator fails closed on unrecognized relationship arms, so silent grants are impossible.
585
+ - Set `firewall: { exception: true }` on the action and gate manually in `execute()`, OR
586
+ - Apply the relationship at the resource's firewall layer (worked example below).
510
587
 
511
- **Workaround**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
588
+ **Resource-layer workaround for record-based actions**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
512
589
 
513
590
  ```typescript
514
591
  // quickback.config.ts
@@ -543,7 +620,7 @@ actions: {
543
620
 
544
621
  This pattern composes cleanly: the firewall guarantees the caller has the relationship to the record being acted on; the action's access list keeps the role surface obvious.
545
622
 
546
- A future `actions.<name>.relationshipBindings` declaration is on the roadmap to remove this limitation. See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture.
623
+ See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture, including `loads` / `exposeAs` and the `firewall: { exception: true }` escape hatch.
547
624
 
548
625
  ## Scoped Database
549
626
 
@@ -95,7 +95,7 @@ A few mechanics to know:
95
95
 
96
96
  `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
97
97
 
98
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, cuid for libsql/bun-sqlite, `crypto.randomUUID()` for supabase, etc. This keeps q's output decoupled from any specific ID library.
98
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, `crypto.randomUUID()` for Neon, etc. This keeps q's output decoupled from any specific ID library.
99
99
 
100
100
  ### q.scope() — tenant scope columns
101
101
 
@@ -123,10 +123,7 @@ ownerId: q.scope('owner', { source: 'ctx.userId' }),
123
123
 
124
124
  ### Naming Convention
125
125
 
126
- By default, `q` picks the SQL column name from the JS key using the target database's conventional casing:
127
-
128
- - **Postgres family (Supabase, Neon, D1)** → `snake_case` (`organizationId` → `organization_id`)
129
- - **SQLite family (bun-sqlite, better-sqlite3, libsql)** → `camelCase` (`organizationId` → `organizationId`)
126
+ By default, `q` picks the SQL column name from the JS key using the target database's conventional casing. Both `cloudflare-d1` and `neon` default to **`snake_case`** (`organizationId` → `organization_id`).
130
127
 
131
128
  You can override for any project by setting `namingConvention` on the database provider config:
132
129
 
@@ -135,10 +132,9 @@ You can override for any project by setting `namingConvention` on the database p
135
132
  export default {
136
133
  providers: {
137
134
  database: {
138
- name: 'bun-sqlite',
135
+ name: 'cloudflare-d1',
139
136
  config: {
140
- path: './data/app.db',
141
- namingConvention: 'snake_case', // force snake_case everywhere
137
+ namingConvention: 'camelCase', // keep JS-style names in the SQL
142
138
  },
143
139
  },
144
140
  },
@@ -661,7 +657,7 @@ export default defineConfig({
661
657
 
662
658
  Use the Drizzle dialect that matches your database provider:
663
659
 
664
- ### SQLite (D1, Turso, better-sqlite3)
660
+ ### SQLite (Cloudflare D1)
665
661
 
666
662
  ```typescript
667
663
  import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
@@ -675,7 +671,7 @@ export const jobs = sqliteTable('jobs', {
675
671
  });
676
672
  ```
677
673
 
678
- ### PostgreSQL (Supabase, Neon)
674
+ ### PostgreSQL (Neon)
679
675
 
680
676
  ```typescript
681
677
  import { pgTable, text, serial, jsonb, boolean } from 'drizzle-orm/pg-core';