@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.
- package/dist/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +737 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/index.js +1 -1
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/lib/wrangler-resources.d.ts +1 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +12 -4
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/docs/api/errors.md +1 -0
- package/dist/skill/docs/api/query-params.md +26 -0
- package/dist/skill/docs/changelog/index.md +79 -0
- package/dist/skill/docs/configure/auth.md +17 -12
- package/dist/skill/docs/configure/bindings.md +27 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +5 -5
- package/dist/skill/docs/define/actions/index.md +18 -0
- package/dist/skill/docs/define/areas.md +90 -7
- package/dist/skill/docs/define/feature.md +88 -27
- package/dist/skill/docs/define/fga.md +10 -2
- package/dist/skill/docs/define/index.md +7 -1
- package/dist/skill/docs/define/scopes.md +1 -1
- package/dist/skill/docs/define/security.md +10 -0
- package/dist/skill/docs/define/transitions.md +11 -35
- package/dist/skill/docs/platform/auth/jwt-optimization.md +15 -3
- package/dist/skill/docs/platform/database/d1.md +17 -2
- package/dist/skill/docs/platform/database/neon.md +7 -0
- package/dist/skill/docs/platform/realtime/index.md +17 -0
- package/dist/skill/docs/platform/webhooks/outbound.md +31 -6
- package/dist/skill/docs/start/deploy-browser.md +36 -7
- package/dist/skill/docs/start/deploy-owner-access.md +11 -0
- package/dist/skill/docs/start/first-api.md +16 -0
- package/dist/skill/docs/ui/account/features/admin.md +29 -5
- package/dist/skill/docs/ui/account/features/index.md +22 -0
- package/dist/skill/docs/ui/admin/connecting.md +6 -4
- package/dist/skill/docs/ui/admin/index.md +49 -10
- package/dist/skill/docs/ui/admin/security.md +6 -7
- package/package.json +1 -1
- package/src/skill/docs/api/errors.md +1 -0
- package/src/skill/docs/api/query-params.md +26 -0
- package/src/skill/docs/changelog/index.md +79 -0
- package/src/skill/docs/configure/auth.md +17 -12
- package/src/skill/docs/configure/bindings.md +27 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +5 -5
- package/src/skill/docs/define/actions/index.md +18 -0
- package/src/skill/docs/define/areas.md +90 -7
- package/src/skill/docs/define/feature.md +88 -27
- package/src/skill/docs/define/fga.md +10 -2
- package/src/skill/docs/define/index.md +7 -1
- package/src/skill/docs/define/scopes.md +1 -1
- package/src/skill/docs/define/security.md +10 -0
- package/src/skill/docs/define/transitions.md +11 -35
- package/src/skill/docs/platform/auth/jwt-optimization.md +15 -3
- package/src/skill/docs/platform/database/d1.md +17 -2
- package/src/skill/docs/platform/database/neon.md +7 -0
- package/src/skill/docs/platform/realtime/index.md +17 -0
- package/src/skill/docs/platform/webhooks/outbound.md +31 -6
- package/src/skill/docs/start/deploy-browser.md +36 -7
- package/src/skill/docs/start/deploy-owner-access.md +11 -0
- package/src/skill/docs/start/first-api.md +16 -0
- package/src/skill/docs/ui/account/features/admin.md +29 -5
- package/src/skill/docs/ui/account/features/index.md +22 -0
- package/src/skill/docs/ui/admin/connecting.md +6 -4
- package/src/skill/docs/ui/admin/index.md +49 -10
- 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)
|
|
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)
|
|
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
|
-
- **
|
|
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
|
|
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`
|
|
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
|
|
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`
|
|
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: "
|
|
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
|
|
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: "
|
|
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 (
|
|
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
|
|
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: "
|
|
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
|
+
> <name> 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
|
-
|
|
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 <name> 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
|
-
|
|
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
|
-
- **
|
|
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.
|
|
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
|
-
##
|
|
5
|
+
## Quick reference
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
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)
|
|
324
|
-
|
|
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.
|