@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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +25 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/migrations.d.ts +17 -0
- package/dist/commands/migrations.d.ts.map +1 -0
- package/dist/commands/migrations.js +328 -0
- package/dist/commands/migrations.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +33 -63
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +17 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +39 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +73 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +22 -1
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +1118 -1
- package/dist/skill/docs/compiler/config/domains.md +70 -10
- package/dist/skill/docs/compiler/config/index.md +74 -3
- package/dist/skill/docs/compiler/config/output.md +1 -1
- package/dist/skill/docs/compiler/config/providers.md +6 -12
- package/dist/skill/docs/compiler/config/single-tenant.md +1 -1
- package/dist/skill/docs/compiler/config/variables.md +0 -30
- package/dist/skill/docs/compiler/definitions/access.md +357 -3
- package/dist/skill/docs/compiler/definitions/actions.md +85 -8
- package/dist/skill/docs/compiler/definitions/schema.md +6 -10
- package/dist/skill/docs/compiler/index.md +15 -34
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/dist/skill/docs/compiler/targets/index.md +6 -34
- package/dist/skill/docs/index.md +2 -5
- package/dist/skill/docs/stack/account-ui/customization.md +2 -14
- package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/dist/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/dist/skill/docs/stack/account-ui/hooks.md +4 -0
- package/dist/skill/docs/stack/account-ui/index.md +5 -43
- package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +106 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +1057 -0
- package/src/skill/docs/compiler/config/domains.md +26 -0
- package/src/skill/docs/compiler/config/index.md +74 -3
- package/src/skill/docs/compiler/config/providers.md +6 -12
- package/src/skill/docs/compiler/config/single-tenant.md +1 -1
- package/src/skill/docs/compiler/config/variables.md +0 -30
- package/src/skill/docs/compiler/definitions/access.md +357 -3
- package/src/skill/docs/compiler/definitions/actions.md +85 -8
- package/src/skill/docs/compiler/definitions/schema.md +6 -10
- package/src/skill/docs/compiler/index.md +15 -34
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/src/skill/docs/compiler/targets/index.md +6 -34
- package/src/skill/docs/index.md +2 -5
- package/src/skill/docs/stack/account-ui/customization.md +2 -14
- package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/src/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/src/skill/docs/stack/account-ui/features/index.md +1 -1
- package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/src/skill/docs/stack/account-ui/hooks.md +4 -0
- package/src/skill/docs/stack/account-ui/index.md +5 -43
- package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/src/skill/docs/stack/auth/plugins/index.md +32 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
- package/dist/skill/docs/stack/account-ui/worker.md +0 -362
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/src/skill/docs/stack/account-ui/standalone.md +0 -149
- 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 `/
|
|
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
|
|
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
|
-
|
|
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
|
-
| `
|
|
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 | `/
|
|
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`
|
|
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 `/
|
|
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']` |
|
|
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.
|