@quickback-dev/cli 0.60.9 → 0.61.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +10 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts +7 -0
  5. package/dist/docs/content.d.ts.map +1 -0
  6. package/dist/docs/content.js +737 -0
  7. package/dist/docs/content.js.map +1 -0
  8. package/dist/index.js +1 -1
  9. package/dist/lib/compiler-stubs.d.ts +4 -0
  10. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  11. package/dist/lib/compiler-stubs.js +4 -0
  12. package/dist/lib/compiler-stubs.js.map +1 -1
  13. package/dist/lib/file-loader.d.ts +11 -0
  14. package/dist/lib/file-loader.d.ts.map +1 -1
  15. package/dist/lib/file-loader.js +35 -0
  16. package/dist/lib/file-loader.js.map +1 -1
  17. package/dist/lib/helpers.d.ts +39 -0
  18. package/dist/lib/helpers.d.ts.map +1 -0
  19. package/dist/lib/helpers.js +299 -0
  20. package/dist/lib/helpers.js.map +1 -0
  21. package/dist/skill/SKILL.md +3 -0
  22. package/dist/skill/docs/api/errors.md +1 -0
  23. package/dist/skill/docs/api/query-params.md +26 -0
  24. package/dist/skill/docs/changelog/index.md +85 -0
  25. package/dist/skill/docs/configure/auth.md +17 -12
  26. package/dist/skill/docs/configure/domains.md +1 -1
  27. package/dist/skill/docs/configure/index.md +6 -6
  28. package/dist/skill/docs/define/actions/defining.md +37 -1
  29. package/dist/skill/docs/define/actions/index.md +18 -0
  30. package/dist/skill/docs/define/areas.md +90 -7
  31. package/dist/skill/docs/define/feature.md +88 -27
  32. package/dist/skill/docs/define/index.md +7 -1
  33. package/dist/skill/docs/define/scopes.md +1 -1
  34. package/dist/skill/docs/define/security.md +10 -0
  35. package/dist/skill/docs/define/transitions.md +11 -35
  36. package/dist/skill/docs/platform/auth/jwt-optimization.md +15 -3
  37. package/dist/skill/docs/platform/database/d1.md +6 -1
  38. package/dist/skill/docs/platform/email/index.md +112 -0
  39. package/dist/skill/docs/platform/index.md +1 -0
  40. package/dist/skill/docs/platform/realtime/index.md +17 -0
  41. package/dist/skill/docs/platform/webhooks/outbound.md +31 -6
  42. package/dist/skill/docs/start/deploy-browser.md +15 -6
  43. package/dist/skill/docs/start/first-api.md +16 -0
  44. package/dist/skill/docs/ui/account/features/admin.md +29 -5
  45. package/dist/skill/docs/ui/account/features/index.md +22 -0
  46. package/dist/skill/docs/ui/admin/connecting.md +6 -4
  47. package/dist/skill/docs/ui/admin/index.md +49 -10
  48. package/dist/skill/docs/ui/admin/security.md +6 -7
  49. package/package.json +2 -10
  50. package/src/skill/SKILL.md +3 -0
  51. package/src/skill/docs/api/errors.md +1 -0
  52. package/src/skill/docs/api/query-params.md +26 -0
  53. package/src/skill/docs/changelog/index.md +85 -0
  54. package/src/skill/docs/configure/auth.md +17 -12
  55. package/src/skill/docs/configure/domains.md +1 -1
  56. package/src/skill/docs/configure/index.md +6 -6
  57. package/src/skill/docs/define/actions/defining.md +37 -1
  58. package/src/skill/docs/define/actions/index.md +18 -0
  59. package/src/skill/docs/define/areas.md +90 -7
  60. package/src/skill/docs/define/feature.md +88 -27
  61. package/src/skill/docs/define/index.md +7 -1
  62. package/src/skill/docs/define/scopes.md +1 -1
  63. package/src/skill/docs/define/security.md +10 -0
  64. package/src/skill/docs/define/transitions.md +11 -35
  65. package/src/skill/docs/platform/auth/jwt-optimization.md +15 -3
  66. package/src/skill/docs/platform/database/d1.md +6 -1
  67. package/src/skill/docs/platform/email/index.md +112 -0
  68. package/src/skill/docs/platform/index.md +1 -0
  69. package/src/skill/docs/platform/realtime/index.md +17 -0
  70. package/src/skill/docs/platform/webhooks/outbound.md +31 -6
  71. package/src/skill/docs/start/deploy-browser.md +15 -6
  72. package/src/skill/docs/start/first-api.md +16 -0
  73. package/src/skill/docs/ui/account/features/admin.md +29 -5
  74. package/src/skill/docs/ui/account/features/index.md +22 -0
  75. package/src/skill/docs/ui/admin/connecting.md +6 -4
  76. package/src/skill/docs/ui/admin/index.md +49 -10
  77. package/src/skill/docs/ui/admin/security.md +6 -7
@@ -8,6 +8,91 @@ 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
+ ## Unreleased
12
+
13
+ ### `defineEmail` — inbound mail, provider-agnostic execute
14
+
15
+ Declare an inbound handler in `services/email/*.ts`. The compiler emits a shared `deliverInboundEmail()` dispatcher plus a Cloudflare Worker `email()` adapter. **Execute sees a portable `InboundEmailMessage`** (`from`, `to`, `headers`, `raw: ArrayBuffer`) — the same body runs for Cloudflare Email Routing and Amazon SES (Receipt → S3 → SNS calling `deliverInboundEmail`). Optional `to` matches the envelope recipient. Unmatched messages log a warning and are **not** rejected. Audit actor is `system:email-<name>`. See [Email](/platform/email).
16
+
17
+ ## v0.61.0 — August 12, 2026
18
+
19
+ ### Security: JWT revocation now fails closed when KV is unreachable
20
+
21
+ **Affects projects using `auth.jwt.revocationCheck: 'kv'`** — including every
22
+ project with a `.sealed()` column, which force-enables it.
23
+
24
+ Setting `revocationCheck: 'kv'` asks the verifier to consult current security
25
+ state before trusting a signed bearer. It did the opposite under failure: a
26
+ missing `KV` binding, a failed read, or a corrupt entry all returned "not
27
+ revoked," so a token was accepted during exactly the outage that hid its
28
+ revocation. A banned user's bearer kept working for the rest of its TTL, and
29
+ the one signal that would have caught it was the thing that had broken.
30
+
31
+ The check now returns `active` / `revoked` / `unavailable`, and only `active`
32
+ authenticates the bearer. A corrupt stamp is `unavailable` too — it used to
33
+ parse as `NaN` and compare as "not revoked."
34
+
35
+ **What changes operationally.** A bearer whose revocation state can't be read
36
+ gets a retryable `503 AUTH_REVOCATION_UNAVAILABLE` ([RFC 9457](/api/errors))
37
+ instead of being let through. Recovery is a separate cookie-only request: a
38
+ request carrying `Authorization` has its cookie stripped before session auth,
39
+ so during a KV outage every JWT-bearer request gets the 503 until the client
40
+ retries on its session cookie. One reason-only log line per occurrence carries
41
+ the cause (`missing-binding` / `read-error`) with no token, claim, or KV key in
42
+ it — **alert on it.**
43
+
44
+ This ties bearer-token availability to KV. That is the trade the opt-in now
45
+ makes honestly, and it is the right way round: a revocation check that gives
46
+ up under load is worth nothing. If you want the TTL bound *without* the
47
+ coupling, leave `revocationCheck` at `'none'` and set `expiresIn: 30`.
48
+
49
+ Because the binding is now load-bearing, a project with named `environments`
50
+ must declare `bindings.kv` on **every** target — a compile error naming the
51
+ environment, rather than a 503 discovered after deploy.
52
+
53
+ `revocationCheck: 'none'` output is byte-identical. See
54
+ [`revocationCheck`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy).
55
+
56
+ ### Security: revocation was off by one second
57
+
58
+ **Also affects projects using `auth.jwt.revocationCheck: 'kv'`.**
59
+
60
+ Revocation markers and token mint timestamps were both whole seconds, and the
61
+ check rejected only a token stamped *strictly before* the marker. A token
62
+ minted earlier in the same second as the revocation therefore compared **equal**
63
+ and survived — a sub-second hole in a mechanism whose whole promise is
64
+ "revoked within seconds." Whether an attacker landed in it was a coin flip on
65
+ clock alignment, not on anything defensible.
66
+
67
+ Markers are now epoch milliseconds, tokens carry millisecond companions
68
+ (`iatMs`, and `sctMs` for the relationship-scope proof), and the comparison
69
+ denies a tie. A token minted milliseconds before the revocation is rejected; one
70
+ legitimately re-minted *after* it in that same second is still accepted, which
71
+ is why simply flipping `<` to `<=` on seconds was not the fix.
72
+
73
+ `iat` and `sct` remain standards-compatible unix **seconds** for external
74
+ tooling — the millisecond claims are internal ordering metadata, set by the
75
+ signer from the same clock sample and never accepted from a caller.
76
+
77
+ **Rollout is conservative, not clever.** Marker format is read from an explicit
78
+ version marker, never guessed from magnitude. Where one side is from v0.60.4 or
79
+ earlier — an old token against a new marker, or any token against an old marker
80
+ — there is no sub-second information to compare, so the **entire marker second**
81
+ is revoked. That over-revocation is bounded (old tokens expire within their TTL,
82
+ old markers within the entry lifetime), and it costs the caller a `401` and a
83
+ re-authentication, exactly as any other rejected token does. No action is needed
84
+ upgrading forward.
85
+
86
+ **Do not straddle this release, though.** A worker from before v0.61.0 reads a
87
+ millisecond marker as `NaN` and concludes *not revoked* — it does not recognise
88
+ it as corrupt, so the fail-closed path added above never fires. Rolling back
89
+ across this release, or running two differently-versioned deploy targets against
90
+ one shared KV namespace, means every revocation written by the new version is
91
+ **silently unenforced** by the old one until the entry expires (~19 minutes at
92
+ default settings). Upgrade targets that share a namespace together. If you must
93
+ roll back, treat outstanding bearers as unrevoked for that window: lower
94
+ `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
95
+
11
96
  ## v0.60.4 — August 4, 2026
12
97
 
13
98
  ### 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
 
@@ -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
 
@@ -697,7 +697,7 @@ dev: {
697
697
 
698
698
  ## Email Configuration
699
699
 
700
- Configure email delivery for authentication emails (verification, password reset, invitations).
700
+ Configure email delivery for authentication emails (verification, password reset, invitations). Inbound mail (Email Routing or SES → a Worker handler) is a separate surface — see [Email (Inbound)](/platform/email) (`defineEmail`). This section is outbound only.
701
701
 
702
702
  > **Cloudflare Email Sending is now in public beta** and is Quickback's default transport for Cloudflare deploys. The Workers `send_email` binding is zero-config — no API keys, no third-party accounts. AWS SES remains supported as an explicit opt-in (`email.provider: 'aws-ses'`) for non-Cloudflare runtimes or existing SES setups.
703
703
 
@@ -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",
@@ -94,7 +94,43 @@ as usual; no project-root dependency symlink is required. Shared schema or DTO
94
94
  modules may also declare top-level Drizzle selection objects. Quickback
95
95
  replaces authored table exports with inert proxies during this schema-only
96
96
  evaluation, so reading `records.id` to build a projection does not execute
97
- application or database logic.
97
+ application or database logic. A schema **derived** from a table enumerates
98
+ nothing under that substitution — see
99
+ [Declaring action outputs](#declaring-action-outputs).
100
+
101
+ ### Declaring action outputs
102
+
103
+ `output:` is optional, and omitting it degrades quietly: the operation's
104
+ OpenAPI success response becomes `{}` and
105
+ `Api.<feature>.actions.<action>.Output` becomes `unknown`. The compile still
106
+ succeeds — it warns, naming how many actions are affected.
107
+
108
+ **Declare the output shape as a literal Zod schema.** Do not derive it from a
109
+ table:
110
+
111
+ ```typescript
112
+ // Silently produces an EMPTY contract — do not do this.
113
+ output: z.object({ tickets: z.array(createSelectSchema(ticketTypes)) })
114
+
115
+ // Documents the response.
116
+ output: z.object({
117
+ tickets: z.array(z.object({ id: z.string(), name: z.string(), priceCents: z.number() })),
118
+ })
119
+ ```
120
+
121
+ The harvest substitutes inert proxies for table modules, so anything that
122
+ derives a schema by enumerating a table's columns — `createSelectSchema` and
123
+ every equivalent — enumerates **zero** columns. It does not throw. It returns a
124
+ valid, empty object schema, which is then published as the documented success
125
+ response. The compiler warns when a declared `output:` resolves to an empty
126
+ object, but the warning is the only signal; the compile passes and the spec
127
+ looks fine.
128
+
129
+ The proxy substitution has one exception, and it is not a supported escape
130
+ hatch: a table module that also contains a `z.object(...)` is bundled and
131
+ evaluated for real, so a derivation in that file happens to work. Whether it
132
+ works depends on unrelated content in the table file — declare the shape
133
+ instead.
98
134
 
99
135
  Parameterized standalone paths use Hono's `:param` syntax in authored source,
100
136
  for example `path: "/events/:eventId/check-in"`. The harvest planner converts
@@ -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.