@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
@@ -175,6 +175,32 @@ If you enable `cms` and `account` without custom domains, everything is served o
175
175
 
176
176
  This is the simplest setup — no DNS configuration needed, no cross-subdomain cookies. Auth cookies work naturally because everything is same-origin.
177
177
 
178
+ ## Preview Deploys
179
+
180
+ The same compiled bundle can be deployed to additional hostnames — preview environments, staging, per-PR URLs — without recompiling. Set the `EXTRA_APP_HOSTS` env var on the deploy target (a comma-separated list of hostnames) and the worker treats each one like an entry in `apps[*].domain`:
181
+
182
+ - Apps hostname middleware serves the SPA at root.
183
+ - CORS / Better Auth `trustedOrigins` trusts requests whose `Origin` hostname matches.
184
+
185
+ Empty or unset means no extension and zero behavior change for production.
186
+
187
+ ```toml title="wrangler.preview.toml"
188
+ [vars]
189
+ EXTRA_APP_HOSTS = "app-preview.example.com,pr-42.example.com"
190
+ ```
191
+
192
+ ```bash
193
+ # Or set as a secret per deploy target
194
+ wrangler secret put EXTRA_APP_HOSTS --env preview
195
+ ```
196
+
197
+ Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends both the apps allowlist and the CORS allowlist.
198
+
199
+ > **Multi-app deploys**
200
+ >
201
+ > When more than one app is hostname-mounted, extras attach to the first registered apps middleware (Hono runs middleware in registration order and terminates on first match). If you need extras to route to a specific app in a multi-app deploy, set `apps[*].domain` directly and recompile rather than using this env var.
202
+
203
+
178
204
  ## See Also
179
205
 
180
206
  - [Configuration](/compiler/config) — CMS and Account config options
@@ -212,6 +212,77 @@ export default defineConfig({
212
212
 
213
213
  If `signature.required: true` and no key is available, compilation fails with a clear error message (or warning in `failMode: "warn"`).
214
214
 
215
+ ## Hostname architecture (v0.33+)
216
+
217
+ A modern Quickback project runs on **one Cloudflare Worker** that serves multiple URL surfaces. By default, everything lives under a single unified backend hostname (auto-inferred as `quickback.{baseDomain}` from your other configured subdomains, or overridable via `config.domain`). For larger deployments, you can opt-in to **dedicated hostnames** for specific surfaces — they're additive aliases, never replacements.
218
+
219
+ ### The unified backend contract
220
+
221
+ When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
222
+
223
+ - `/api/v1/*` — feature routes
224
+ - `/auth/v1/*` — Better Auth
225
+ - `/storage/*` — R2 file storage
226
+ - `/health`, `/openapi.json` — monitoring/discovery
227
+ - `/account/*`, `/cms/*` — bundled SPAs (when enabled)
228
+ - `/broadcast/v1/*` (realtime), `/mcp` (MCP), etc.
229
+
230
+ The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
231
+
232
+ This contract is forward-pointing: it gives a stable URL pattern for future management tooling — `https://quickback.{baseDomain}/...` will always reach a Quickback backend regardless of how the operator splits their surfaces.
233
+
234
+ ### Dedicated hostnames (optional, additive)
235
+
236
+ For branding or operational separation, you can opt specific surfaces onto their own hostnames:
237
+
238
+ ```ts
239
+ {
240
+ // Bundled SPAs on their own hosts (already-shipped pattern):
241
+ cms: { domain: 'cms.example.com' },
242
+ account: { domain: 'account.example.com' },
243
+
244
+ // v0.33+ — backend surfaces on their own hosts:
245
+ auth: { domain: 'auth.example.com' },
246
+ api: { domain: 'api.example.com' },
247
+
248
+ // User SPAs (existing pattern):
249
+ apps: {
250
+ www: { domain: 'app.example.com' },
251
+ },
252
+ }
253
+ ```
254
+
255
+ On a dedicated hostname, **the hostname IS the namespace** — the path drops the prefix that matches the hostname:
256
+
257
+ | URL on dedicated host | Internally rewritten to | Notes |
258
+ |---|---|---|
259
+ | `https://api.example.com/v1/users` | `/api/v1/users` | Worker-entry rewriter prepends `/api` |
260
+ | `https://auth.example.com/v1/sign-in/email` | `/auth/v1/sign-in/email` | Same shape with `/auth` |
261
+ | `https://api.example.com/api/v1/users` | (unchanged) | Long form also accepted |
262
+ | `https://api.example.com/auth/v1/sign-in` | **404** | Auth doesn't live on the API hostname |
263
+ | `https://api.example.com/health` | (unchanged) | Explicit exception — monitoring agents expect `/health` everywhere |
264
+
265
+ Dual-reach is preserved on the unified host:
266
+
267
+ | URL on unified host | Handler | Notes |
268
+ |---|---|---|
269
+ | `https://quickback.example.com/api/v1/users` | feature route | Works whether `api.domain` is set or not |
270
+ | `https://quickback.example.com/auth/v1/sign-in/email` | Better Auth | Works whether `auth.domain` is set or not |
271
+ | `https://quickback.example.com/v1/users` | **404** | Shortcut only applies on dedicated hostnames |
272
+
273
+ Each dedicated hostname also:
274
+
275
+ - Gets a `{ pattern, custom_domain: true }` route in `wrangler.toml` automatically
276
+ - Joins `trustedOrigins` for CORS
277
+ - Joins the cross-subdomain cookie inference (auto-enables `crossSubDomainCookies` when ≥2 same-parent subdomains are configured, so `auth.example.com` and `app.example.com` can share session cookies)
278
+ - Joins CSP `connect-src` so SPAs can fetch from it
279
+
280
+ ### Why two URL shapes (Shape 1 vs Shape 2)
281
+
282
+ If you only want Better Auth to **advertise** itself on a different URL (e.g. so verification emails link to `auth.example.com` instead of the unified host), set the `BETTER_AUTH_URL` env var on the Worker — no code change required. BA generates outgoing URLs against that value. This is sufficient when the goal is branding email/OAuth callback URLs without changing where requests actually land.
283
+
284
+ `auth.domain` (Shape 1, above) is the heavier option: it binds an actual hostname to the Worker, configures CORS/cookies/CSP for it, and adds the path-shortcut rewriter. Use it when you want the dedicated hostname as a real ingress, not just a label.
285
+
215
286
  ## CMS Configuration
216
287
 
217
288
  Embed the [Quickback CMS](/stack/cms) in your compiled Worker. The CMS reads your schema registry and renders a complete admin interface — zero UI code per table.
@@ -234,7 +305,7 @@ cms: { domain: "cms.example.com", sysadmin: true },
234
305
  |--------|------|---------|-------------|
235
306
  | `domain` | `string` | — | Custom domain for CMS. Adds a `custom_domain` route to `wrangler.toml`. |
236
307
  | `access` | `"user" \| "admin"` | `"user"` | Controls who can access the CMS. When `"admin"`, only users with `user.role === "admin"` can enter — enforced at the Worker level (SPA shell, `/api/v1/schema`, and `custom_view` CRUD all return 403 to non-admins) and in the SPA. Also hides the CMS link in Account UI. See [CMS Connecting](/stack/cms/connecting) for the full enforcement model. |
237
- | `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/admin/v1/sysadmin/organizations` endpoint, and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"admin"` — sysadmin is a strict superset. Off by default. See [`SYSADMIN` pseudo-role](/compiler/definitions/access#sysadmin--cross-tenant-db-admin-tier). |
308
+ | `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/auth/v1/admin/list-organizations` endpoint (sibling of Better Auth's `/auth/v1/admin/list-users`, gated to sysadmin only), and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"admin"`. Off by default. See [`SYSADMIN` pseudo-role](/compiler/definitions/access#sysadmin--cross-tenant-db-admin-tier). |
238
309
 
239
310
  ### Sysadmin tier (`cms.sysadmin: true`)
240
311
 
@@ -242,9 +313,9 @@ Quickback's default model assumes every CMS user belongs to at least one organiz
242
313
 
243
314
  `cms: { sysadmin: true }` introduces a separate role tier:
244
315
 
245
- - **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"admin"` — admins keep org-scoped CMS access via the membership switcher; sysadmins get cross-tenant.
316
+ - **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"admin"` — admins keep org-scoped CMS access via the membership switcher; sysadmins get cross-tenant. The two roles are independent at the pseudo-role evaluator level: `ADMIN` admits `'admin'` only, `SYSADMIN` admits `'sysadmin'` only. Routes that need both write `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly.
246
317
  - **Firewall**: 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. See [Firewall escape hatch](/compiler/definitions/firewall#sysadmin-escape-hatch).
247
- - **Org listing**: a new `GET /admin/v1/sysadmin/organizations` endpoint selects directly from the auth-schema `organization` table — every row, every tenant. The existing `/admin/v1/organizations` (membership-bound, used by org admins) is unchanged.
318
+ - **Org listing**: a `GET /auth/v1/admin/list-organizations` endpoint selects directly from the auth-schema `organization` table — every row, every tenant. Sits under Better Auth's admin URL namespace (sibling of `/auth/v1/admin/list-users`) so the URL shape matches BA convention; the handler is Quickback-emitted and gated to `user.role === "sysadmin"` only. For the membership-bound caller's-orgs listing, use BA's own `/auth/v1/organization/list`.
248
319
  - **CMS SPA**: when the user is a sysadmin, the header switcher loads from the cross-tenant endpoint, defaults to "All organizations" (which omits `?organizationId=` and reaches the firewall escape), and pins selected tenants via `?organizationId=` on every API call. Org admins keep the existing membership-based switcher.
249
320
  - **CMS HTML gate**: admits `userRole === "sysadmin"` alongside `"admin"`. Org admins are not locked out — both roles can enter the CMS in `cms.access: "admin"` mode.
250
321
 
@@ -4,11 +4,7 @@ Providers configure which services your compiled backend targets.
4
4
 
5
5
  ## Runtime Providers
6
6
 
7
- | Provider | Description |
8
- |----------|-------------|
9
- | `cloudflare` | Cloudflare Workers (Hono) |
10
- | `bun` | Bun runtime (Hono) |
11
- | `node` | Node.js runtime (Hono) |
7
+ The Quickback Stack is **Cloudflare-only**. `cloudflare` is the single supported runtime.
12
8
 
13
9
  ```typescript
14
10
  import { defineRuntime } from "@quickback/compiler";
@@ -63,13 +59,12 @@ providers: {
63
59
 
64
60
  ## Database Providers
65
61
 
62
+ Two databases are supported, both Cloudflare-native:
63
+
66
64
  | Provider | Description |
67
65
  |----------|-------------|
68
- | `cloudflare-d1` | Cloudflare D1 (SQLite) |
69
- | `better-sqlite3` | SQLite via better-sqlite3 (Bun/Node) |
70
- | `libsql` | LibSQL / Turso |
71
- | `neon` | Neon (PostgreSQL) |
72
- | `supabase` | Supabase (PostgreSQL) |
66
+ | `cloudflare-d1` | Cloudflare D1 (SQLite at the edge) |
67
+ | `neon` | Neon (PostgreSQL over Hyperdrive) |
73
68
 
74
69
  ```typescript
75
70
  import { defineDatabase } from "@quickback/compiler";
@@ -235,8 +230,7 @@ See [Realtime](/stack/realtime) for the client-side connection flow and helper e
235
230
 
236
231
  | Provider | Description |
237
232
  |----------|-------------|
238
- | `better-auth` | Better Auth with plugins |
239
- | `supabase-auth` | Supabase Auth |
233
+ | `better-auth` | Better Auth with plugins (default) |
240
234
  | `external` | External auth via Cloudflare service binding |
241
235
 
242
236
  ```typescript
@@ -31,7 +31,7 @@ export default defineConfig({
31
31
  | `organizationId` columns | Required on resources | Not used |
32
32
  | Role source | Org membership table | `user.role` field |
33
33
  | Firewall scopes | `owner`, `organization`, `team`, `exception` | `owner`, `exception` only |
34
- | Admin org endpoints | `/admin/v1/organizations` generated | Skipped |
34
+ | Admin org endpoints | Use Better Auth's `/auth/v1/organization/list` (caller's orgs) and `/auth/v1/admin/list-organizations` when `cms.sysadmin: true` (cross-tenant) | N/A (no org plugin) |
35
35
  | `ctx.activeOrgId` | From session/JWT | Always `undefined` |
36
36
  | `ctx.roles` | From org member role | From `user.role` |
37
37
 
@@ -107,36 +107,6 @@ For running remote migrations with `drizzle-kit`, set these in `.env`:
107
107
  | `CLOUDFLARE_AUDIT_DATABASE_ID` | Security audit D1 database ID (unsafe cross-tenant actions) |
108
108
  | `CLOUDFLARE_DATABASE_ID` | Database ID (single DB mode) |
109
109
 
110
- ## Bun Variables
111
-
112
- Set these in a `.env` file in your project root:
113
-
114
- | Variable | Description | Default |
115
- |----------|-------------|---------|
116
- | `NODE_ENV` | Runtime environment | `development` |
117
- | `PORT` | Server port | `3000` |
118
- | `BETTER_AUTH_SECRET` | Auth encryption secret | — (required) |
119
- | `BETTER_AUTH_URL` | Public URL of your server | `http://localhost:3000` |
120
- | `DATABASE_PATH` | Path to SQLite file | `./data/app.db` |
121
-
122
- ## Turso (LibSQL) Variables
123
-
124
- In addition to the Bun variables above:
125
-
126
- | Variable | Description | Default |
127
- |----------|-------------|---------|
128
- | `DATABASE_URL` | LibSQL connection URL | `file:./data/app.db` |
129
- | `DATABASE_AUTH_TOKEN` | Turso auth token (required for remote) | — |
130
-
131
- ```bash
132
- # Local development
133
- DATABASE_URL=file:./data/app.db
134
-
135
- # Production (Turso cloud)
136
- DATABASE_URL=libsql://your-db-slug.turso.io
137
- DATABASE_AUTH_TOKEN=eyJhbGciOi...
138
- ```
139
-
140
110
  ## Social Login Providers
141
111
 
142
112
  When social login is configured in your auth provider:
@@ -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.