@quickback-dev/cli 0.60.8 → 0.61.0

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 (70) hide show
  1. package/dist/docs/content.d.ts +7 -0
  2. package/dist/docs/content.d.ts.map +1 -0
  3. package/dist/docs/content.js +737 -0
  4. package/dist/docs/content.js.map +1 -0
  5. package/dist/index.js +1 -1
  6. package/dist/lib/helpers.d.ts +39 -0
  7. package/dist/lib/helpers.d.ts.map +1 -0
  8. package/dist/lib/helpers.js +299 -0
  9. package/dist/lib/helpers.js.map +1 -0
  10. package/dist/lib/wrangler-resources.d.ts +1 -1
  11. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  12. package/dist/lib/wrangler-resources.js +12 -4
  13. package/dist/lib/wrangler-resources.js.map +1 -1
  14. package/dist/skill/docs/api/errors.md +1 -0
  15. package/dist/skill/docs/api/query-params.md +26 -0
  16. package/dist/skill/docs/changelog/index.md +79 -0
  17. package/dist/skill/docs/configure/auth.md +17 -12
  18. package/dist/skill/docs/configure/bindings.md +27 -0
  19. package/dist/skill/docs/configure/domains.md +1 -1
  20. package/dist/skill/docs/configure/index.md +5 -5
  21. package/dist/skill/docs/define/actions/index.md +18 -0
  22. package/dist/skill/docs/define/areas.md +90 -7
  23. package/dist/skill/docs/define/feature.md +88 -27
  24. package/dist/skill/docs/define/fga.md +10 -2
  25. package/dist/skill/docs/define/index.md +7 -1
  26. package/dist/skill/docs/define/scopes.md +1 -1
  27. package/dist/skill/docs/define/security.md +10 -0
  28. package/dist/skill/docs/define/transitions.md +11 -35
  29. package/dist/skill/docs/platform/auth/jwt-optimization.md +15 -3
  30. package/dist/skill/docs/platform/database/d1.md +17 -2
  31. package/dist/skill/docs/platform/database/neon.md +7 -0
  32. package/dist/skill/docs/platform/realtime/index.md +17 -0
  33. package/dist/skill/docs/platform/webhooks/outbound.md +31 -6
  34. package/dist/skill/docs/start/deploy-browser.md +36 -7
  35. package/dist/skill/docs/start/deploy-owner-access.md +11 -0
  36. package/dist/skill/docs/start/first-api.md +16 -0
  37. package/dist/skill/docs/ui/account/features/admin.md +29 -5
  38. package/dist/skill/docs/ui/account/features/index.md +22 -0
  39. package/dist/skill/docs/ui/admin/connecting.md +6 -4
  40. package/dist/skill/docs/ui/admin/index.md +49 -10
  41. package/dist/skill/docs/ui/admin/security.md +6 -7
  42. package/package.json +1 -1
  43. package/src/skill/docs/api/errors.md +1 -0
  44. package/src/skill/docs/api/query-params.md +26 -0
  45. package/src/skill/docs/changelog/index.md +79 -0
  46. package/src/skill/docs/configure/auth.md +17 -12
  47. package/src/skill/docs/configure/bindings.md +27 -0
  48. package/src/skill/docs/configure/domains.md +1 -1
  49. package/src/skill/docs/configure/index.md +5 -5
  50. package/src/skill/docs/define/actions/index.md +18 -0
  51. package/src/skill/docs/define/areas.md +90 -7
  52. package/src/skill/docs/define/feature.md +88 -27
  53. package/src/skill/docs/define/fga.md +10 -2
  54. package/src/skill/docs/define/index.md +7 -1
  55. package/src/skill/docs/define/scopes.md +1 -1
  56. package/src/skill/docs/define/security.md +10 -0
  57. package/src/skill/docs/define/transitions.md +11 -35
  58. package/src/skill/docs/platform/auth/jwt-optimization.md +15 -3
  59. package/src/skill/docs/platform/database/d1.md +17 -2
  60. package/src/skill/docs/platform/database/neon.md +7 -0
  61. package/src/skill/docs/platform/realtime/index.md +17 -0
  62. package/src/skill/docs/platform/webhooks/outbound.md +31 -6
  63. package/src/skill/docs/start/deploy-browser.md +36 -7
  64. package/src/skill/docs/start/deploy-owner-access.md +11 -0
  65. package/src/skill/docs/start/first-api.md +16 -0
  66. package/src/skill/docs/ui/account/features/admin.md +29 -5
  67. package/src/skill/docs/ui/account/features/index.md +22 -0
  68. package/src/skill/docs/ui/admin/connecting.md +6 -4
  69. package/src/skill/docs/ui/admin/index.md +49 -10
  70. package/src/skill/docs/ui/admin/security.md +6 -7
@@ -8,6 +8,85 @@ The current release series. Older entries are archived by version range:
8
8
  - [v0.20 – v0.29](/changelog/v0.2x)
9
9
  - [v0.18 and earlier](/changelog/v0.1x)
10
10
 
11
+ ## v0.61.0 — August 12, 2026
12
+
13
+ ### Security: JWT revocation now fails closed when KV is unreachable
14
+
15
+ **Affects projects using `auth.jwt.revocationCheck: 'kv'`** — including every
16
+ project with a `.sealed()` column, which force-enables it.
17
+
18
+ Setting `revocationCheck: 'kv'` asks the verifier to consult current security
19
+ state before trusting a signed bearer. It did the opposite under failure: a
20
+ missing `KV` binding, a failed read, or a corrupt entry all returned "not
21
+ revoked," so a token was accepted during exactly the outage that hid its
22
+ revocation. A banned user's bearer kept working for the rest of its TTL, and
23
+ the one signal that would have caught it was the thing that had broken.
24
+
25
+ The check now returns `active` / `revoked` / `unavailable`, and only `active`
26
+ authenticates the bearer. A corrupt stamp is `unavailable` too — it used to
27
+ parse as `NaN` and compare as "not revoked."
28
+
29
+ **What changes operationally.** A bearer whose revocation state can't be read
30
+ gets a retryable `503 AUTH_REVOCATION_UNAVAILABLE` ([RFC 9457](/api/errors))
31
+ instead of being let through. Recovery is a separate cookie-only request: a
32
+ request carrying `Authorization` has its cookie stripped before session auth,
33
+ so during a KV outage every JWT-bearer request gets the 503 until the client
34
+ retries on its session cookie. One reason-only log line per occurrence carries
35
+ the cause (`missing-binding` / `read-error`) with no token, claim, or KV key in
36
+ it — **alert on it.**
37
+
38
+ This ties bearer-token availability to KV. That is the trade the opt-in now
39
+ makes honestly, and it is the right way round: a revocation check that gives
40
+ up under load is worth nothing. If you want the TTL bound *without* the
41
+ coupling, leave `revocationCheck` at `'none'` and set `expiresIn: 30`.
42
+
43
+ Because the binding is now load-bearing, a project with named `environments`
44
+ must declare `bindings.kv` on **every** target — a compile error naming the
45
+ environment, rather than a 503 discovered after deploy.
46
+
47
+ `revocationCheck: 'none'` output is byte-identical. See
48
+ [`revocationCheck`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy).
49
+
50
+ ### Security: revocation was off by one second
51
+
52
+ **Also affects projects using `auth.jwt.revocationCheck: 'kv'`.**
53
+
54
+ Revocation markers and token mint timestamps were both whole seconds, and the
55
+ check rejected only a token stamped *strictly before* the marker. A token
56
+ minted earlier in the same second as the revocation therefore compared **equal**
57
+ and survived — a sub-second hole in a mechanism whose whole promise is
58
+ "revoked within seconds." Whether an attacker landed in it was a coin flip on
59
+ clock alignment, not on anything defensible.
60
+
61
+ Markers are now epoch milliseconds, tokens carry millisecond companions
62
+ (`iatMs`, and `sctMs` for the relationship-scope proof), and the comparison
63
+ denies a tie. A token minted milliseconds before the revocation is rejected; one
64
+ legitimately re-minted *after* it in that same second is still accepted, which
65
+ is why simply flipping `<` to `<=` on seconds was not the fix.
66
+
67
+ `iat` and `sct` remain standards-compatible unix **seconds** for external
68
+ tooling — the millisecond claims are internal ordering metadata, set by the
69
+ signer from the same clock sample and never accepted from a caller.
70
+
71
+ **Rollout is conservative, not clever.** Marker format is read from an explicit
72
+ version marker, never guessed from magnitude. Where one side is from v0.60.4 or
73
+ earlier — an old token against a new marker, or any token against an old marker
74
+ — there is no sub-second information to compare, so the **entire marker second**
75
+ is revoked. That over-revocation is bounded (old tokens expire within their TTL,
76
+ old markers within the entry lifetime), and it costs the caller a `401` and a
77
+ re-authentication, exactly as any other rejected token does. No action is needed
78
+ upgrading forward.
79
+
80
+ **Do not straddle this release, though.** A worker from before v0.61.0 reads a
81
+ millisecond marker as `NaN` and concludes *not revoked* — it does not recognise
82
+ it as corrupt, so the fail-closed path added above never fires. Rolling back
83
+ across this release, or running two differently-versioned deploy targets against
84
+ one shared KV namespace, means every revocation written by the new version is
85
+ **silently unenforced** by the old one until the entry expires (~19 minutes at
86
+ default settings). Upgrade targets that share a namespace together. If you must
87
+ roll back, treat outstanding bearers as unrevoked for that window: lower
88
+ `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
89
+
11
90
  ## v0.60.4 — August 4, 2026
12
91
 
13
92
  ### Fix: retired-path cleanup was inert in v0.60.1–v0.60.3
@@ -45,7 +45,7 @@ The short version, before the knob-by-knob detail:
45
45
  - **Default: 180-second TTL, auto-refreshed.** Every authenticated call returns a fresh token via the `set-auth-token` header, so the low TTL is invisible to logged-in users. The worst-case window for a stolen or pre-revocation token is 3 minutes — and you can shrink it to 30 seconds with one config line.
46
46
  - **Need revocation faster than the TTL?** Set [`revocationCheck: 'kv'`](#revocationcheck-none--kv--token-revocation-strategy). Revoked tokens are rejected within seconds; revocation stamps are written automatically on user ban, org-member removal, role change, and changes to scope-conferring relationship rows.
47
47
 
48
- Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session), fails open if KV is unreachable (degrading to the TTL bound), and propagates cross-PoP in ~60s. If you need fail-closed, per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling — and [tell us about your use case](https://github.com/kardoe/quickback/issues); an opaque-session mode is under consideration.
48
+ Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling — and [tell us about your use case](https://github.com/kardoe/quickback/issues); an opaque-session mode is under consideration.
49
49
 
50
50
  ### Behavior recap
51
51
 
@@ -105,11 +105,11 @@ Default `'none'`.
105
105
  | Value | Behavior | Cost per verify |
106
106
  |---|---|---|
107
107
  | `'none'` | No revocation check. Stolen / pre-revocation tokens valid until TTL expires (scope claims: until the carry-forward cap). Use a low `expiresIn` to bound the replay window. | 0 |
108
- | `'kv'` | Fast-path checks per-principal revocation timestamps in the project's existing `KV` binding before trusting a verified token. | 2+ KV reads (~5-15ms, edge-cached) |
108
+ | `'kv'` | Fast-path checks per-principal revocation timestamps in the project's existing `KV` binding before trusting a verified token. Fails closed: an unreadable store means the bearer is not trusted. | 2+ KV reads (~5-15ms, edge-cached) |
109
109
 
110
110
  `'kv'` (v0.45+, **Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
111
111
 
112
- A token is rejected when its mint timestamp (`iat`, or `sct` for the relationship-scope claim) predates the stored timestamp for any principal key it rides on:
112
+ A token is rejected when its mint timestamp (`iat`/`iatMs`, or `sct`/`sctMs` for the relationship-scope claim) is **at or before** the stored timestamp for any principal key it rides on:
113
113
 
114
114
  | Key | Revokes | Written automatically on |
115
115
  |---|---|---|
@@ -122,8 +122,12 @@ A token is rejected when its mint timestamp (`iat`, or `sct` for the relationshi
122
122
  Semantics worth knowing:
123
123
 
124
124
  - **Revoke-on-touch for scopes:** any update or delete of a conferring row stamps the revocation, without evaluating whether the change actually ended the relationship. A false positive just forces a cheap re-prove (`/scope/v1/enter` or a minting namespace route).
125
- - **Fails open:** a missing binding or KV outage skips the check (logged) — revocation degrades to the TTL / carry-forward-cap bound rather than locking every bearer out.
125
+ - **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format version, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, so a token minted a few milliseconds before the revocation is rejected — while one legitimately re-minted *after* it in that same second is still accepted. Tokens and markers written by v0.60.4 or earlier are handled **conservatively**: with no sub-second information on one side, the whole marker second is revoked. That over-revocation is bounded — the last old token expires within its TTL, and the last old marker within the entry lifetime. Like any rejected token it costs the caller a `401`, not a silent recovery: the bearer falls through unauthenticated (its cookie having been stripped, per the next bullet), and the client re-authenticates for a fresh token.
126
+ - **Do not straddle the v0.61.0 upgrade.** A worker from **before** v0.61.0 reads `m<ms>` markers as `NaN` and treats them as *no revocation at all* — not as a corrupt entry. So rolling back across this release, or pointing two differently-versioned deploy targets at one shared KV namespace, means every revocation written by the new version is **silently unenforced** by the old one until the entry expires (`ENTRY_TTL_SECONDS`, ~19 minutes at default settings). Upgrade all targets sharing a namespace together; if you must roll back, treat outstanding bearer tokens as unrevoked for that window — lower `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
127
+ - **Fails closed:** a missing binding, a failed read, or a corrupt entry means the token's revocation state is *unknown* — and an unknown bearer is not authenticated. The caller gets `503 AUTH_REVOCATION_UNAVAILABLE` (RFC 9457, retryable). Recovery is a **separate cookie-only request**: a request carrying `Authorization` has its cookie stripped before session auth, so within that one request there is nothing left to fall back to. Reads are never silently skipped, because the outage that hides a revocation is exactly the moment this check exists for.
128
+ - **Availability coupling:** the flip side of the above. Bearer-token auth now depends on KV being readable. Alert on `AUTH_REVOCATION_UNAVAILABLE`; a sustained rate means the binding is missing on some deployment target, or KV is degraded. Every named environment must declare `bindings.kv` — the compiler rejects a target that doesn't.
126
129
  - **Eventual consistency:** KV propagates cross-PoP in ~60s. "Immediate" means seconds at the writing location, bounded-seconds globally — still far inside the 15-minute carry-forward cap that bounds revocation without this check.
130
+ - **Writes stay best-effort:** the *stamps* are written after the authorization change has already committed (the ban row, the removed membership, the deleted conferring row). A failed stamp does not fail that write — the DB state is the durable cut. It is only the *read* side that fails closed.
127
131
  - **Coverage gap:** batch *hard* deletes don't return rows through the chokepoint; call `revokeScopeTokens` explicitly if you bulk-hard-delete conferring rows.
128
132
 
129
133
  ## Defaults when the JWT surface is enabled
@@ -145,34 +149,35 @@ missing field falls back to its hardcoded value:
145
149
  - **B2C SaaS, mostly browser traffic:** keep defaults. The 180s TTL + auto-refresh model just works.
146
150
  - **Pentest engagement / enterprise compliance:** set `expiresIn: 30`. Tokens stay invisible to logged-in users (auto-refreshed every authed call) but stolen-token windows shrink to 30s.
147
151
  - **CLI-heavy / long-running CI tokens:** `expiresIn: 3600` for one-hour bearer tokens. Pair with `issuer` / `audience` if multiple services consume the same JWT.
148
- - **Need immediate revocation:** set `revocationCheck: 'kv'` (Cloudflare runtime) — revoked tokens are rejected within seconds, and stamps are written automatically on user ban, member removal, role change, and scope-conferring row changes (see the [scope revocation notes](/define/scopes#revocation--ttl)). Or drop TTL to ~30s — similar effect with bounded delay and zero KV reads.
152
+ - **Need immediate revocation:** set `revocationCheck: 'kv'` (Cloudflare runtime) — revoked tokens are rejected within seconds, and stamps are written automatically on user ban, member removal, role change, and scope-conferring row changes (see the [scope revocation notes](/define/scopes#revocation--ttl)). It fails closed, so bearer auth then depends on KV being readable — declare `bindings.kv` on every environment and alert on `AUTH_REVOCATION_UNAVAILABLE`. Or drop TTL to ~30s — similar effect with bounded delay, zero KV reads, and no availability coupling.
149
153
 
150
- ## `auth.loginUrl` / `auth.profileUrl` — external sign-in for consumer Workers
154
+ ## `auth.loginUrl` — external sign-in for consumer Workers
151
155
 
152
- When a Quickback Worker doesn't host its own Account SPA — e.g. an internal-app mesh where one Worker on the parent domain owns identity (`auth.example.com`) and other Workers share cookies — the compiler-emitted CMS access gates need to redirect unauthenticated visitors to the central sign-in surface, not the local `/account/login` (which doesn't exist there).
156
+ When a Quickback Worker doesn't host its own Account SPA — e.g. an internal-app mesh where one Worker on the parent domain owns identity (`auth.example.com`) and other Workers share cookies — the compiler-emitted CMS access gate needs to redirect unauthenticated visitors to the central sign-in surface, not the local `/account/login` (which doesn't exist there).
153
157
 
154
158
  ```ts title="quickback.config.ts"
155
159
  export default defineConfig({
156
160
  // ...
157
161
  auth: {
158
162
  loginUrl: 'https://auth.example.com/login',
159
- profileUrl: 'https://auth.example.com/profile',
160
163
  },
161
164
  });
162
165
  ```
163
166
 
164
- Both fields override compiler-emitted browser redirects in the CMS shell:
165
-
166
167
  - **Unauthenticated visitor hits a CMS route** → `302 → <loginUrl>?redirect=<original-url>`
167
- - **Authenticated user fails the `cms.access: 'admin'` platform-role check** → `302 → <profileUrl>`
168
168
 
169
169
  The `?redirect=…` query param is preserved unchanged so the central sign-in surface can bounce the user back after authentication.
170
170
 
171
+ Signing in is the *only* thing the CMS gate redirects for. A signed-in caller who isn't admitted is served the CMS shell and shown a screen naming what they'd need — see [CMS access](/ui/admin#access-gate). There is no wrong-role redirect, and no `auth.profileUrl`.
172
+
173
+ > **Removed in v0.62:** `auth.profileUrl`. Its only consumer was the CMS wrong-role redirect. The config schema is strict, so a leftover `profileUrl` key now fails the compile — delete it.
174
+
175
+
171
176
  ### Resolution precedence
172
177
 
173
178
  Most-specific wins:
174
179
 
175
- 1. Explicit `auth.loginUrl` / `auth.profileUrl` — the cookie-trusting consumer-Worker case (this section).
180
+ 1. Explicit `auth.loginUrl` — the cookie-trusting consumer-Worker case (this section).
176
181
  2. `https://<account.domain>/login` — inferred when this project hosts its own Account SPA on a custom domain.
177
182
  3. `/account/login` — built-in fallback, when neither knob is set.
178
183
 
@@ -243,6 +243,33 @@ Binding names that clash with compiler-owned bindings are rejected at validation
243
243
 
244
244
  Pick a different name — the generated `env` on the handler side takes whatever binding you pick.
245
245
 
246
+ ## One name, one thing
247
+
248
+ Bindings and vars share a single namespace: `env.DB` is one slot, whatever
249
+ declares it. A name claimed twice within one deploy target fails the compile,
250
+ naming both claimants and what each points at:
251
+
252
+ ```
253
+ Two declarations claim the same name on env: "MEDIA" is claimed by
254
+ [r2_buckets] (studio-media) and by [r2_buckets] (studio-uploads) in the
255
+ top-level config.
256
+ ```
257
+
258
+ This catches what the reserved-name table above cannot — that compares your
259
+ names against compiler-owned ones, never against each other:
260
+
261
+ - two of your own declarations sharing a name (`r2Buckets`, `queueProducers`,
262
+ `services`, `durableObjects`);
263
+ - a [`vars`](/configure/variables) key shadowing a binding — the easy one to
264
+ miss, since a var looks nothing like a binding but lands on the same `env`;
265
+ - collisions inside a named environment's `[env.*]` stanza.
266
+
267
+ Scoped **per target**, so [named environments](/platform/database/d1#named-cloudflare-deployment-environments)
268
+ are unaffected: every target declares the same binding names pointing at its
269
+ own resources, and `ASSETS` is emitted at the top level and in each stanza by
270
+ design. Two identical declarations are redundant rather than ambiguous and are
271
+ allowed — only a name pointing at two *different* things is rejected.
272
+
246
273
  ## See also
247
274
 
248
275
  - [Environment Variables](/configure/variables) — the non-secret `[vars]` / secret split
@@ -88,7 +88,7 @@ The unified domain is useful for development and debugging. You can override it
88
88
  export default {
89
89
  name: "my-app",
90
90
  template: "hono",
91
- cms: { domain: "cms.example.com", access: "admin" },
91
+ cms: { domain: "cms.example.com", access: "sysadmin" },
92
92
  account: {
93
93
  domain: "auth.example.com",
94
94
  adminDomain: "admin.example.com",
@@ -96,7 +96,7 @@ Every optional top-level key the config accepts is listed below. You never have
96
96
  | `domain` | `string` | Primary custom domain (auto-inferred from `cms`/`account`/`api` domains if unset) — see [Domains](/configure/domains) |
97
97
  | `contract` | `{ version?: "v1" \| "v2" }` | Public API/auth contract version. Omit for the backward-compatible v1 default; select v2 for `/api/v2/*` and `/auth/v2/*` across generated routes, Better Auth, OpenAPI, MCP, and discovery. |
98
98
  | `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/configure/domains) |
99
- | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`/`profileUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
99
+ | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
100
100
  | `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/define/authz-roles#centrally-defined-access-rules) and [Permissions](/define/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/define/areas) (`_area.ts`), and root bodies may reference root-declared names only |
101
101
  | `requires` | `string[]` | Capability floor (fail-closed guard). Declare `['feature-areas']` when the project uses `features/**/_area.ts` — an area-unaware CLI/compiler then refuses the compile instead of silently dropping nested features. See [Feature areas](/define/areas#the-capability-floor-requires-feature-areas) |
102
102
  | `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
@@ -574,7 +574,7 @@ cms: true,
574
574
  cms: { domain: "cms.example.com" },
575
575
 
576
576
  // With access control (only admins can access CMS)
577
- cms: { domain: "cms.example.com", access: "admin" },
577
+ cms: { domain: "cms.example.com", access: "sysadmin" },
578
578
 
579
579
  // Cross-tenant DB-admin tier — sysadmins see every tenant's data
580
580
  cms: { domain: "cms.example.com", sysadmin: true },
@@ -592,11 +592,11 @@ Quickback's default model assumes every CMS user belongs to at least one organiz
592
592
 
593
593
  `cms: { sysadmin: true }` introduces a separate role tier:
594
594
 
595
- - **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"appmanager"` — appmanagers keep platform control-plane access (CMS shell, Better Auth admin surfaces, support tooling), while sysadmins get true cross-tenant data access. `ADMIN` is now a rejected legacy pseudo-role; use `userRole: ["appmanager"]` for control-plane gates and `roles: ["SYSADMIN"]` for cross-tenant access.
595
+ - **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"appmanager"` — appmanagers keep platform control-plane access (Better Auth admin surfaces, organization and user management, support tooling — but NOT the CMS), while sysadmins get true cross-tenant data access. `ADMIN` is now a rejected legacy pseudo-role; use `userRole: ["appmanager"]` for control-plane gates and `roles: ["SYSADMIN"]` for cross-tenant access.
596
596
  - **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](/define/firewall#sysadmin-escape-hatch).
597
597
  - **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`.
598
598
  - **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.
599
- - **CMS HTML gate**: admits `userRole === "sysadmin"` alongside `"appmanager"`. Org admins are not locked out when you set `cms.access: "user"`; `cms.access: "admin"` is specifically the platform control-plane gate.
599
+ - **CMS gate**: `cms.access: "sysadmin"` (the default) admits the `sysadmin` tier only; `cms.access: "member"` also admits any caller with an organization membership. `appmanager` opens the CMS in neither mode — see [Access gate](/ui/admin#access-gate).
600
600
 
601
601
  Off by default. Projects that don't enable it get zero behavior change; setting `cms.sysadmin: true` and granting a user `user.role = "sysadmin"` is the only way to unlock the cross-tenant view.
602
602
 
@@ -754,7 +754,7 @@ A complete config with CMS, Account UI, and Admin on separate subdomains:
754
754
  export default {
755
755
  name: "my-app",
756
756
  template: "hono",
757
- cms: { domain: "cms.example.com", access: "admin" },
757
+ cms: { domain: "cms.example.com", access: "sysadmin" },
758
758
  account: {
759
759
  domain: "auth.example.com",
760
760
  adminDomain: "admin.example.com",
@@ -2,6 +2,23 @@
2
2
 
3
3
  Actions are custom API endpoints for business logic beyond CRUD operations. They enable workflows, integrations, and complex operations.
4
4
 
5
+ ## Before you write one — four primitives that may already do it
6
+
7
+ An action is a file you own and maintain. These are declarations the compiler
8
+ owns, and each generates the same real endpoint, OpenAPI operation, and MCP
9
+ tool, on the same firewall/access/guards pipeline. Check all four first — the
10
+ most common needless action is one of these hand-rolled.
11
+
12
+ | If the action would… | Declare instead | Where |
13
+ |---|---|---|
14
+ | check a row's current state, flip a column, stamp who/when | `transitions` on the table — plus `guard`, `stamp`/`clears` (which makes `execute` optional), `idempotent`, `undo`, `onEnter` cascades | [Transitions](/define/transitions) |
15
+ | write a parent row plus its owned children in one call | `changesets` — declare the `owns` boundary; each op still pays the child's own firewall, access, and guards | [Changesets](/define/changesets) |
16
+ | fire a side-effect after a write — denormalize a counter, stamp a column, enqueue a job | `triggers` — SQL triggers cover **every** write path (REST, actions, cron, raw SQL), not just the one route you remembered | [Triggers](/define/triggers) |
17
+ | return the same rows with a different column set per role | `read.views` — its own route, access rule, pagination, and masking | [Views](/define/views) |
18
+
19
+ Write the action for the remainder: third-party calls, multi-step orchestration,
20
+ AI/streaming responses, anything genuinely imperative.
21
+
5
22
  ## Overview
6
23
 
7
24
  Quickback supports two types of actions:
@@ -83,5 +100,6 @@ generated output.
83
100
  - **[Examples](/define/actions/examples)** — end-to-end action files
84
101
 
85
102
  Related: **[Transitions](/define/transitions)** for state-machine policy,
103
+ **[Changesets](/define/changesets)** for aggregate writes,
86
104
  **[Triggers](/define/triggers)** for after-commit hooks, and the
87
105
  **[Actions API](/api/actions)** for calling an action over HTTP.
@@ -55,6 +55,13 @@ quickback/features/
55
55
  The gate here is `collaboratorOf` — a row in *your* `project_collaborators` table. That's what
56
56
  makes it an area: the answer isn't in `ctx.roles` already.
57
57
 
58
+ **Folder membership is the whole opt-in, and it is all-or-nothing.** Every feature in the folder
59
+ inherits the prefix and the gate; there is no per-feature or per-table marker to opt out. To keep
60
+ a feature flat, put it outside the area folder. The one per-*action* escape is
61
+ [`route: 'self'`](#containment-and-the-route-self-marker), and it exists for actions that must
62
+ live in the subtree yet answer off-prefix — a collection route or a `create`, which by definition
63
+ has no row to be related to yet. See [Where `create` goes](#where-create-goes).
64
+
58
65
  Reserved sub-directories (`actions/`, `lib/`, `pages/`) are never child features. A directory
59
66
  **without** `_area.ts` is a leaf feature — its unreserved subdirectories are not loaded, and a
60
67
  subdirectory containing `defineTable(...)` / `defineAction(...)` **fails the compile** (silent
@@ -74,7 +81,10 @@ export default defineArea({
74
81
 
75
82
  // Inherited route mount + admission gate. Optional: an area with no
76
83
  // prefix contributes shared vocabulary only. A prefix REQUIRES at least
77
- // one `via` lane (a mounted prefix with no gate would be ungated).
84
+ // one `via` lane (a mounted prefix with no gate would be ungated), and at
85
+ // least one `:param` segment — the gate runs as middleware, before any
86
+ // request body is parsed, so `c.req.param()` is the only place it can read
87
+ // the resource key from. `prefix: '/project'` is a compile error.
78
88
  prefix: '/project/:projectId',
79
89
  via: ['collaboratorOf', { roles: ['admin', 'owner'] }],
80
90
  mintScope: true,
@@ -105,6 +115,23 @@ export default defineArea({
105
115
  });
106
116
  ```
107
117
 
118
+ > **A bare string in `via:` is a relationship name — never a role name**
119
+ >
120
+ > `via: ['collaboratorOf']` names a **relationship** declared in `relationships:`. Roles go in an
121
+ > object lane: `via: [{ roles: ['admin', 'owner'] }]`, and those are Better Auth **org roles**, not
122
+ > your composed `roles:` entries. A relationship name that isn't declared fails with *"lane
123
+ > &lt;name&gt; is not declared in authz.relationships"*; a role name in the string position fails the
124
+ > same way, because the compiler has no reason to think you meant a role.
125
+ >
126
+ > `via:` accepts exactly three lane shapes:
127
+ >
128
+ > | Lane | Passes when |
129
+ > |---|---|
130
+ > | `'collaboratorOf'` | a row in the named relationship links the caller to the `:param` row |
131
+ > | `{ roles: ['admin'] }` | the caller's Better Auth org role on the row's tenant matches |
132
+ > | `{ team: true }` | `ctx.activeTeamId` is set (the loads-table firewall does the row check) |
133
+
134
+
108
135
  A descendant feature references everything by bare name — no imports, no root declaration:
109
136
 
110
137
  {/* doc-compile: skip — cross-fence dependency: the relative `path: './tasks/add'` and the `projectStaff` role both resolve against the `_area.ts` in the fence directly above, and the area is the whole point of the example. The gate compiles each fence as an isolated project, so this feature has no ancestor area to inherit a prefix from. */}
@@ -142,8 +169,10 @@ is genuinely global.
142
169
  Two structural rules keep the fold sound:
143
170
 
144
171
  - **No overrides (v1).** Re-declaring an inherited name — in any class, including scope kinds,
145
- scoped-role aliases, and namespace names — is a compile error. Declare each name in exactly
146
- one place. (`overrides:` marker syntax is reserved for a future release.)
172
+ scoped-role aliases, and namespace names — is a compile error. Declare each name in exactly one
173
+ place; the fix is always to **delete the duplicate**, keeping the declaration in the deepest
174
+ area that owns it. There is no merge, no shadowing, and no override mechanism. (`overrides:` is
175
+ a reserved key name for a future release — it does nothing today and is not the fix.)
147
176
  - **Declaration-site rule.** Root `authz` bodies (roles, rules, tenants, scopes, namespaces)
148
177
  may reference **root-declared names only** — a root definition is visible everywhere and
149
178
  would launder an area name out of its subtree. An area's bodies may reference root ∪
@@ -156,6 +185,12 @@ manifest under the owning area.
156
185
 
157
186
  ## Containment and the `route: 'self'` marker
158
187
 
188
+ `route: 'self'` marks **one standalone action, inside the area folder, whose `path:` is outside
189
+ the area's prefix**. It is a label on a path you already chose — not a switch that moves a route
190
+ or exempts a feature. Outside those exact conditions the compiler rejects it: on an action whose
191
+ path is *inside* the prefix (the gate applies; the marker is dead), and in a feature with no
192
+ ancestor area that mounts a prefix (there is nothing to opt out of).
193
+
159
194
  The area's prefix is an audited surface:
160
195
 
161
196
  - A feature **outside** the area may not declare an action path (or a table-level
@@ -175,6 +210,44 @@ The area's prefix is an audited surface:
175
210
  Relative paths (`path: './…'`) resolve against the area prefix. Dot segments (`.` / `..`) are
176
211
  rejected outright — the resolved route must stay under the prefix.
177
212
 
213
+ ### Where `create` goes
214
+
215
+ An area gate answers *"is the caller related to **this** row?"* — so it cannot gate the action
216
+ that creates the row. `POST /conversations` has no `:conversationId` to prove anything about.
217
+ Same for the collection list: `GET /conversations` is a query across rows, not a request about one.
218
+
219
+ Split by cardinality, not by feature:
220
+
221
+ ```
222
+ features/conversations/
223
+ ├── _area.ts prefix: '/conversations/:conversationId'
224
+ │ via: ['participant']
225
+ ├── conversations.ts the table — resource path '/conversations'
226
+ │ (collection + create; NOT under the prefix)
227
+ ├── startConversation.ts path: '/conversations', route: 'self'
228
+ └── messages/ everything per-conversation — gated by the area
229
+ └── messages.ts path: './messages' → /conversations/:conversationId/messages
230
+ ```
231
+
232
+ `startConversation` stays in the folder, so it still reads the area's relationships and roles by
233
+ bare name, and `route: 'self'` says out loud that it is gated by its own `access:` only —
234
+ `{ roles: ['member'] }`, or whatever "may open a conversation" means in your app. Its job is to
235
+ insert the row *and* the `conversation_members` row that makes the caller a participant; every
236
+ route under the prefix works from there.
237
+
238
+ Two constraints fall out of the same split:
239
+
240
+ - **The area prefix must carry a `:param`.** `prefix: '/conversations'` is a compile error — the
241
+ gate runs as middleware, before the body is parsed, so `c.req.param()` is the only key it can
242
+ read.
243
+ - **A generated table router under the prefix needs a relationship lane.** The compiler mounts a
244
+ table's CRUD behind an area gate only when the area has one; a bulk-grant-only `via:` can't
245
+ anchor the resolver, and the table is rejected rather than mounted unscoped. A table whose path
246
+ sits outside the prefix (like `conversations` above) is unaffected.
247
+
248
+ Scoping the collection itself — "don't list conversations I'm not in" — is
249
+ [firewall](/define/firewall) work on the table, not area work.
250
+
178
251
  ## Nested areas
179
252
 
180
253
  Areas nest to arbitrary depth. A nested area may declare additional **vocabulary** freely. A
@@ -217,6 +290,17 @@ Root `authz` remains the home for genuinely global vocabulary — names used acr
217
290
  flat features. Everything scoped to one concept belongs in that concept's `_area.ts`. When in
218
291
  doubt: if only one folder's features reference it, it belongs in that folder's area.
219
292
 
293
+ ## Common mistakes
294
+
295
+ | Symptom | Cause | Fix |
296
+ |---|---|---|
297
+ | *"lane &lt;name&gt; is not declared in authz.relationships"* | A role name in the string position of `via:`. | Bare strings name **relationships** only. Roles go in `{ roles: [...] }` — and those are Better Auth org roles, not your composed `roles:`. |
298
+ | *"…has at least one RELATIONSHIP lane… this one does not"* on a table under the prefix | `via:` is bulk-grant-only (`{ roles }` / `{ team }`), which can't anchor the resolver. | Add a relationship lane, or move the table's path outside the prefix. Wrapping a relationship-backed role in `{ roles: [...] }` does **not** make it a relationship lane. |
299
+ | *"prefix … must contain at least one `:param` segment"* | The prefix names a collection (`/conversations`). | The gate is per-row: `/conversations/:conversationId`. Collection and `create` routes belong outside the prefix — see [Where `create` goes](#where-create-goes). |
300
+ | *"already declared at …"* / *"Overrides are not supported in v1"* | The same name declared in two places. | Delete one. Keep it in the deepest area that owns it. `overrides:` is reserved and does nothing. |
301
+ | A feature in the folder should not be area-scoped | Membership is the folder — no per-feature opt-out exists. | Move it out of the folder, or (single action only) give it an off-prefix `path:` and `route: 'self'`. |
302
+ | *"path is OUTSIDE that prefix … mark it explicitly with `route: 'self'`"* | Intentional off-prefix action, or a typo in the path. | If intentional, add `route: 'self'`. If not, fix the path — this error exists so a typo can't silently self-gate. |
303
+
220
304
  ## Namespace mounts (hoisted relationship middleware)
221
305
 
222
306
  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).
@@ -374,7 +458,7 @@ authz: {
374
458
  }
375
459
  ```
376
460
 
377
- 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.
461
+ Hydration is **per matched lane** (v0.37+): each lane fills `ctx.<its own exposeAs>` from its own `loads:` table, so lanes may load different tables into different keys. Both lanes above name `events` / `event`, so `ctx.event` is populated whichever fires. A lane declaring neither `loads:` nor `exposeAs:` is authorization-only — it opens the gate and hydrates nothing.
378
462
 
379
463
  ### Bulk-grant lanes (v0.26+)
380
464
 
@@ -413,9 +497,8 @@ Actions opt in by matching `path:` against a declared namespace prefix. There's
413
497
 
414
498
  Both forms share the same shape checks:
415
499
 
416
- - **`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 }`).
417
- - **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.
418
- - **All relationship lanes in one namespace must agree on `loads:` + `exposeAs:`.** Otherwise `ctx.<exposeAs>` would change shape depending on which lane matched.
500
+ - **`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 }`). **A bare string is always a relationship name.** There is no string form for a role: `{ roles: [...] }` is a bulk-grant lane against Better Auth org roles, even when the name you put in it is a composed role defined `via` a relationship.
501
+ - **Each relationship lane declares `loads` + `exposeAs`, or neither.** Both → the lane hydrates `ctx.<exposeAs>` from `loads` when it matches. Neither → an authorization-only lane. Exactly one is a compile error.
419
502
  - **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.
420
503
  - **`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.
421
504
  - **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.
@@ -1,35 +1,56 @@
1
1
  # feature() — the canonical form
2
2
 
3
- `feature()` is **the** way to write a Quickback feature: one file, one default export, the table and its security contract together. The older `q.table()` + `defineTable()` pair still exists underneath (it's what `feature()` expands into), but it means two exports and two concepts for something a feature file treats as one unit.
3
+ `feature()` is **the** way to write a Quickback feature: one file, one default export, the table and its security contract together. It expands at compile time into `q.table()` + `defineTable()`, which stays available for the cases that need it — see [When to use which](#when-to-use-which).
4
4
 
5
- ## Before
5
+ ## Quick reference
6
6
 
7
- ```ts title="quickback/features/contacts.ts"
8
- import { q, defineTable } from "@quickback/compiler";
9
-
10
- export const contacts = q.table("contacts", {
11
- id: q.id(),
12
- organizationId: q.text().required().index(),
13
- address: q.text().required().index(),
14
- name: q.text().optional(),
15
- ...q.audit(),
16
- ...q.softDelete(),
17
- });
7
+ One object. Everything a table exposes is a key in it, and every key is optional
8
+ except `columns`.
18
9
 
19
- export default defineTable(contacts, {
20
- firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
21
- // "+" role expansion requires auth.roleHierarchy in quickback.config.ts
22
- read: { access: { roles: ["member+"] } },
23
- create: { access: { roles: ["member+"] } },
24
- update: { access: { roles: ["member+"] } },
25
- delete: { access: { roles: ["admin+"] }, mode: "soft" },
26
- guards: { createable: ["address", "name"] },
10
+ {/* doc-compile: skip — key map, not a config: every value is an empty placeholder. The compiled forms are in the fences below and on each key's own page. */}
11
+ ```ts
12
+ feature("name", {
13
+ columns: {}, // q.* column helpers — the Drizzle schema
14
+
15
+ // Security — the five pillars
16
+ firewall: {}, // which ROWS (auto-derived from organizationId / ownerId / teamId)
17
+ read: {}, // who may read + `views` — named column projections
18
+ create: {}, // who may write
19
+ update: {},
20
+ delete: {}, // + `mode: "soft" | "hard"`
21
+ guards: {}, // which FIELDS a caller may set
22
+ masking: {}, // which VALUES come back redacted
23
+ rateLimit: {}, // per-operation caps
24
+
25
+ // Endpoints beyond CRUD — declared here, not written as action files
26
+ transitions: {}, // guarded state changes → POST /:id/{name}
27
+ triggers: {}, // before/after hooks on every write
28
+ owns: {}, // composition boundary → atomic parent+children writes
29
+ realtime: {}, // broadcast insert/update/delete
30
+ embeddings: {}, // vectors generated on write
31
+
32
+ // Placement + presentation
33
+ path: "", // route base (defaults to the feature name)
34
+ namespace: {}, // hoisted route prefix + admission gate
35
+ displayColumn: "", defaultSort: {}, inputHints: {}, layouts: {}, references: {},
27
36
  });
28
-
29
- export type Contact = typeof contacts.$infer;
30
37
  ```
31
38
 
32
- ## After
39
+ | You want | Key | Page |
40
+ |---|---|---|
41
+ | Tenant isolation, role gates, field and value control | `firewall`, `read`/`create`/`update`/`delete`, `guards`, `masking` | [Security](/define/security) |
42
+ | A narrower shape for a broader audience | `read.views` | [Views](/define/views) |
43
+ | `publish` / `approve` / `checkIn` — a state change | `transitions` | [Transitions](/define/transitions) |
44
+ | A side-effect or data rule on every write | `triggers` | [Triggers](/define/triggers) |
45
+ | Parent plus its children written atomically | `owns` | [Changesets](/define/changesets) |
46
+ | Clients updated live | `realtime` | [Realtime](/platform/realtime/using-realtime) |
47
+ | Semantic search over the table | `embeddings` | [Embeddings](/platform/vector/using-embeddings) |
48
+ | The CMS to render it well | `displayColumn`, `defaultSort`, `inputHints`, `layouts` | [CMS](/ui/admin/table-views) |
49
+
50
+ The rest of this page is the form itself; [One object, not just
51
+ CRUD](#one-object-not-just-crud) shows the non-CRUD keys filled in.
52
+
53
+ ## The form
33
54
 
34
55
  ```ts title="quickback/features/contacts.ts"
35
56
  import { feature, q } from "@quickback/compiler";
@@ -37,13 +58,12 @@ import { feature, q } from "@quickback/compiler";
37
58
  export default feature("contacts", {
38
59
  columns: {
39
60
  id: q.id(),
40
- organizationId: q.text().required().index(),
61
+ organizationId: q.scope("organization"), // firewall auto-derives from this
41
62
  address: q.text().required().index(),
42
63
  name: q.text().optional(),
43
64
  ...q.audit(),
44
65
  ...q.softDelete(),
45
66
  },
46
- firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
47
67
  // "+" role expansion requires auth.roleHierarchy in quickback.config.ts
48
68
  read: { access: { roles: ["member+"] } },
49
69
  create: { access: { roles: ["member+"] } },
@@ -53,7 +73,48 @@ export default feature("contacts", {
53
73
  });
54
74
  ```
55
75
 
56
- Type inference still works — `typeof import("./contacts").default.$infer` gives you the `Contact` row type.
76
+ Type inference comes with it — `typeof import("./contacts").default.$infer` gives you the `Contact` row type.
77
+
78
+ ## One object, not just CRUD
79
+
80
+ The example above declares security and CRUD because that is the floor. The same
81
+ config object carries every other per-table capability — a live feed, a state
82
+ machine, a narrower projection, a write hook. They are keys next to `read:` and
83
+ `guards:`, not separate files or services, and each generates a real endpoint on
84
+ the same firewall → access → guards → masking pipeline.
85
+
86
+ {/* doc-compile: skip — shape sketch: `columns` is elided so the keys stay readable side by side, and `member+`/`admin+` need `auth.roleHierarchy` in quickback.config.ts. Each key's own page carries the compiled version. */}
87
+ ```ts
88
+ export default feature("episodes", {
89
+ columns: { /* … */ },
90
+ firewall: [{ field: "organizationId", equals: "ctx.activeOrgId" }],
91
+ read: {
92
+ access: { roles: ["member+"] },
93
+ views: { public: { fields: ["id", "title"], access: { roles: ["member+"] } } },
94
+ },
95
+ guards: { updatable: ["title"], protected: { isPublished: ["publish"] } },
96
+ masking: { submitterEmail: { type: "email", show: { roles: ["admin"] } } },
97
+ transitions: { publish: { field: "isPublished", from: false, to: true, access: { roles: ["admin+"] } } },
98
+ realtime: { enabled: true, onInsert: true, onUpdate: true },
99
+ embeddings: { fields: ["title", "summary"] },
100
+ });
101
+ ```
102
+
103
+ | Key | Gives you | Reference |
104
+ |---|---|---|
105
+ | `read.views` | Named column projections, each with its own route and access rule | [Views](/define/views) |
106
+ | `transitions` | Guarded state changes generated as real `POST /:id/{name}` actions — guards, stamps, `undo`, cascades | [Transitions](/define/transitions) |
107
+ | `triggers` | `before`/`after` hooks on write, lowered to a real SQL trigger or an application handler | [Triggers](/define/triggers) |
108
+ | `realtime` | Per-table broadcasts on insert/update/delete, audience-scoped | [Realtime](/platform/realtime/using-realtime) |
109
+ | `owns` | The composition boundary that turns on atomic parent-plus-children writes | [Changesets](/define/changesets) |
110
+ | `embeddings` | Vector embeddings generated on insert/update | [Embeddings](/platform/vector/using-embeddings) |
111
+ | `masking` / `rateLimit` / `namespace` | Field redaction, per-operation caps, a hoisted route prefix + gate | [Masking](/define/masking), [Rate limit](/define/rate-limit), [Areas](/define/areas) |
112
+ | `displayColumn` / `defaultSort` / `inputHints` / `layouts` / `references` | How the CMS renders the table — no runtime effect | [CMS](/ui/admin/table-views) |
113
+
114
+ Reach for these before writing an action file: an action is code you maintain,
115
+ these are declarations the compiler owns. See the full option list in
116
+ [Definitions Overview](/define#other-resource-options) and the "before you write
117
+ one" routing table at the top of [Actions](/define/actions).
57
118
 
58
119
  ## How it works
59
120
 
@@ -320,7 +320,15 @@ access, even if it was written out-of-band — the model is the ceiling.
320
320
  **422 `FGA_LIST_TOO_LARGE`**, not a partial page — paginate via
321
321
  `POST /fga/v1/list-objects` for those cases. Only the bare/`or`/`and`-with-roles
322
322
  shapes are filtered; deeper nesting is a compile error.
323
- - **Conditional tuples** (CEL conditions / ABAC) — the schema reserves the
324
- columns, but condition evaluation is not yet wired.
323
+ - **Conditional tuples** (CEL conditions / ABAC) are **not supported, and fail
324
+ closed**. The tuple table reserves `condition_name` / `condition_context`, but
325
+ there is no CEL evaluator — so a tuple carrying a condition is treated as
326
+ unevaluatable. Touching one makes the whole Check **deny**, including through
327
+ `ListObjects` and tuple-to-userset traversal. Denying the Check rather than
328
+ skipping the tuple is deliberate: a condition can sit on the `but not` side of
329
+ an exclusion, where ignoring it would *grant*. `POST /fga/v1/write` rejects a
330
+ conditional tuple with a 400, and `POST /fga/v1/read` still returns one, so a
331
+ row planted out-of-band stays visible to an audit. Nothing Quickback generates
332
+ writes those columns — only raw SQL, a seed, or an OpenFGA import can.
325
333
  - `ListObjects` enumerates candidate objects from tuples and Checks each — a
326
334
  reverse-index optimization is a planned follow-up.