@quickback-dev/cli 0.34.3 → 0.39.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 (130) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +36 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/compile.test.d.ts +2 -0
  5. package/dist/commands/compile.test.d.ts.map +1 -0
  6. package/dist/commands/compile.test.js +83 -0
  7. package/dist/commands/compile.test.js.map +1 -0
  8. package/dist/commands/create.js +15 -11
  9. package/dist/commands/create.js.map +1 -1
  10. package/dist/commands/migrations.d.ts +33 -0
  11. package/dist/commands/migrations.d.ts.map +1 -1
  12. package/dist/commands/migrations.js +41 -2
  13. package/dist/commands/migrations.js.map +1 -1
  14. package/dist/commands/migrations.test.d.ts +2 -0
  15. package/dist/commands/migrations.test.d.ts.map +1 -0
  16. package/dist/commands/migrations.test.js +67 -0
  17. package/dist/commands/migrations.test.js.map +1 -0
  18. package/dist/docs/content.d.ts.map +1 -1
  19. package/dist/docs/content.js +56 -26
  20. package/dist/docs/content.js.map +1 -1
  21. package/dist/examples/recruitment.tar.gz +0 -0
  22. package/dist/index.js +1 -1
  23. package/dist/lib/action-harvest.d.ts +48 -0
  24. package/dist/lib/action-harvest.d.ts.map +1 -0
  25. package/dist/lib/action-harvest.js +292 -0
  26. package/dist/lib/action-harvest.js.map +1 -0
  27. package/dist/lib/action-harvest.test.d.ts +2 -0
  28. package/dist/lib/action-harvest.test.d.ts.map +1 -0
  29. package/dist/lib/action-harvest.test.js +112 -0
  30. package/dist/lib/action-harvest.test.js.map +1 -0
  31. package/dist/lib/api-client.d.ts +10 -0
  32. package/dist/lib/api-client.d.ts.map +1 -1
  33. package/dist/lib/api-client.js +17 -1
  34. package/dist/lib/api-client.js.map +1 -1
  35. package/dist/lib/api-client.test.js +19 -0
  36. package/dist/lib/api-client.test.js.map +1 -1
  37. package/dist/lib/artifact-routing.d.ts +1 -0
  38. package/dist/lib/artifact-routing.d.ts.map +1 -1
  39. package/dist/lib/artifact-routing.js +15 -3
  40. package/dist/lib/artifact-routing.js.map +1 -1
  41. package/dist/lib/artifact-routing.test.js +12 -1
  42. package/dist/lib/artifact-routing.test.js.map +1 -1
  43. package/dist/lib/file-loader.d.ts +1 -0
  44. package/dist/lib/file-loader.d.ts.map +1 -1
  45. package/dist/lib/file-loader.js +34 -1
  46. package/dist/lib/file-loader.js.map +1 -1
  47. package/dist/lib/file-loader.test.js +28 -4
  48. package/dist/lib/file-loader.test.js.map +1 -1
  49. package/dist/lib/prepare-state-output.d.ts +8 -0
  50. package/dist/lib/prepare-state-output.d.ts.map +1 -0
  51. package/dist/lib/prepare-state-output.js +17 -0
  52. package/dist/lib/prepare-state-output.js.map +1 -0
  53. package/dist/lib/prepare-state-output.test.d.ts +2 -0
  54. package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
  55. package/dist/lib/prepare-state-output.test.js +31 -0
  56. package/dist/lib/prepare-state-output.test.js.map +1 -0
  57. package/dist/skill/SKILL.md +4 -4
  58. package/dist/skill/agents/quickback-specialist/AGENT.md +3 -3
  59. package/dist/skill/docs/changelog.md +643 -0
  60. package/dist/skill/docs/compiler/config/agents.md +1 -1
  61. package/dist/skill/docs/compiler/config/auth.md +1 -1
  62. package/dist/skill/docs/compiler/config/index.md +8 -9
  63. package/dist/skill/docs/compiler/config/providers.md +3 -0
  64. package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
  65. package/dist/skill/docs/compiler/definitions/access.md +40 -33
  66. package/dist/skill/docs/compiler/definitions/actions.md +1 -1
  67. package/dist/skill/docs/compiler/definitions/arrows.md +269 -0
  68. package/dist/skill/docs/compiler/definitions/diagnostics.md +136 -0
  69. package/dist/skill/docs/compiler/definitions/feature.md +3 -3
  70. package/dist/skill/docs/compiler/definitions/fga.md +314 -0
  71. package/dist/skill/docs/compiler/definitions/firewall.md +94 -7
  72. package/dist/skill/docs/compiler/definitions/permissions.md +145 -0
  73. package/dist/skill/docs/compiler/definitions/schema.md +8 -2
  74. package/dist/skill/docs/compiler/definitions/scopes.md +339 -0
  75. package/dist/skill/docs/compiler/definitions/views.md +66 -0
  76. package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
  77. package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
  78. package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
  79. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  80. package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
  81. package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
  82. package/dist/skill/docs/stack/cms/connecting.md +17 -16
  83. package/dist/skill/docs/stack/cms/index.md +7 -7
  84. package/dist/skill/docs/stack/cms/schema-format.md +0 -2
  85. package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
  86. package/dist/skill/docs/stack/cms/security.md +6 -6
  87. package/dist/skill/docs/stack/realtime/durable-objects.md +48 -7
  88. package/dist/skill/docs/stack/realtime/live-views.md +168 -0
  89. package/dist/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
  90. package/dist/skill/docs/stack/storage/r2.md +112 -3
  91. package/dist/skill/docs/stack/storage/using-r2.md +30 -10
  92. package/dist/templates/registry.js +2 -2
  93. package/dist/templates/registry.js.map +1 -1
  94. package/package.json +1 -1
  95. package/src/examples/recruitment.tar.gz +0 -0
  96. package/src/skill/SKILL.md +4 -4
  97. package/src/skill/agents/quickback-specialist/AGENT.md +3 -3
  98. package/src/skill/docs/changelog.md +643 -0
  99. package/src/skill/docs/compiler/config/agents.md +1 -1
  100. package/src/skill/docs/compiler/config/auth.md +1 -1
  101. package/src/skill/docs/compiler/config/index.md +8 -9
  102. package/src/skill/docs/compiler/config/providers.md +3 -0
  103. package/src/skill/docs/compiler/config/single-tenant.md +65 -73
  104. package/src/skill/docs/compiler/definitions/access.md +40 -33
  105. package/src/skill/docs/compiler/definitions/actions.md +1 -1
  106. package/src/skill/docs/compiler/definitions/arrows.md +269 -0
  107. package/src/skill/docs/compiler/definitions/diagnostics.md +136 -0
  108. package/src/skill/docs/compiler/definitions/feature.md +3 -3
  109. package/src/skill/docs/compiler/definitions/fga.md +314 -0
  110. package/src/skill/docs/compiler/definitions/firewall.md +94 -7
  111. package/src/skill/docs/compiler/definitions/permissions.md +145 -0
  112. package/src/skill/docs/compiler/definitions/schema.md +8 -2
  113. package/src/skill/docs/compiler/definitions/scopes.md +339 -0
  114. package/src/skill/docs/compiler/definitions/views.md +66 -0
  115. package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
  116. package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
  117. package/src/skill/docs/compiler/getting-started/templates.md +6 -6
  118. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  119. package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
  120. package/src/skill/docs/stack/account-ui/features/index.md +2 -2
  121. package/src/skill/docs/stack/cms/connecting.md +17 -16
  122. package/src/skill/docs/stack/cms/index.md +7 -7
  123. package/src/skill/docs/stack/cms/schema-format.md +0 -2
  124. package/src/skill/docs/stack/cms/schema-registry.md +0 -6
  125. package/src/skill/docs/stack/cms/security.md +6 -6
  126. package/src/skill/docs/stack/realtime/durable-objects.md +48 -7
  127. package/src/skill/docs/stack/realtime/live-views.md +168 -0
  128. package/src/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
  129. package/src/skill/docs/stack/storage/r2.md +112 -3
  130. package/src/skill/docs/stack/storage/using-r2.md +30 -10
@@ -0,0 +1,339 @@
1
+ # Scopes & Capability Grants
2
+
3
+ Org membership answers *"which tenant is this caller in?"* Scopes answer a different question: *"this caller isn't an org member, but they're a **confirmed attendee of event E** — let them see exactly E's rows, as exactly the role they hold, and nothing else."*
4
+
5
+ A **scope** is a tenant axis whose value is established by a **relationship you prove once** (at `POST /scope/v1/enter`) and then carry in a signed JWT claim — verified cryptographically on every later request with **no database round-trip**. It's the REST/JWT twin of the realtime ws-ticket.
6
+
7
+ ## When to use it
8
+
9
+ Reach for a scope when a principal must touch a bounded slice of an instance **without being an org member**:
10
+
11
+ - **Event attendee** — reads their event's announcements / sessions, not the org.
12
+ - **Shuttle driver** — sees only the passengers on *their* bus (a row slice), can DM them.
13
+ - **F&B vendor** — reads dietary *counts*, zero attendee rows.
14
+ - **Visiting nurse / carrier / contractor** — one patient's meds, one carrier's shipments.
15
+
16
+ Each is *event-scoped* but a **distinct least-privilege role**. Org members are unaffected — they keep their normal tenant access.
17
+
18
+ ## The model
19
+
20
+ ### 1. Declare relationships + scopes
21
+
22
+ A scope **kind** (`event`) declares named **roles**, each conferred by a relationship whose `from` row carries the role (and optionally a **sub-key** for row slicing):
23
+
24
+ ```typescript
25
+ // quickback.config.ts
26
+ authz: {
27
+ relationships: {
28
+ attendeeOf: { from: 'guests', subject: { column: 'linkedUserId', equals: 'ctx.userId' }, resource: { column: 'eventId' }, where: { status: 'confirmed' } },
29
+ organizerOf: { from: 'staff', subject: { column: 'linkedUserId', equals: 'ctx.userId' }, resource: { column: 'eventId' }, where: { role: 'organizer' } },
30
+ shuttleDriverOf: { from: 'staff', subject: { column: 'linkedUserId', equals: 'ctx.userId' }, resource: { column: 'eventId' }, where: { role: 'shuttleDriver' } },
31
+ },
32
+ scopes: {
33
+ event: {
34
+ requestField: 'eventId', // the body field the client sends to /enter
35
+ roles: {
36
+ attendee: { via: 'attendeeOf' },
37
+ organizer: { via: 'organizerOf' },
38
+ shuttleDriver: { via: 'shuttleDriverOf', subKeys: ['shuttleId'] }, // row-slice sub-key
39
+ },
40
+ },
41
+ },
42
+ }
43
+ ```
44
+
45
+ ### 2. Enter the scope
46
+
47
+ ```http
48
+ POST /scope/v1/enter (session OR existing JWT auth)
49
+ { "eventId": "evt_123" }
50
+ ```
51
+
52
+ The server probes **every declared role** for the proposed instance (one DB touch), and mints the proven roles + sub-keys into a signed JWT `scope` claim, returned via the `set-auth-token` header and the body:
53
+
54
+ ```jsonc
55
+ // a shuttle driver who is also a confirmed guest
56
+ "scope": { "event": { "id": "evt_123", "roles": ["attendee", "shuttleDriver"], "shuttleId": "shA" } }
57
+ ```
58
+
59
+ The client sends that JWT as `Authorization: Bearer …` on subsequent requests. The auth middleware verifies the signature and sets `ctx.scope` — **no DB**. The claim is carried forward on every authed call (rolling refresh) until you `enter` a different instance.
60
+
61
+ > **Invariant:** the client only *proposes* the instance id (from the URL). The server proves membership before signing. No client-asserted scope is ever trusted.
62
+
63
+ ### 3. Gate the pillars
64
+
65
+ Scoped roles are referenced everywhere a pillar takes a role as the namespaced identifier **`scope:<kind>:<role>`**:
66
+
67
+ ```typescript
68
+ // features/guests/guests.ts — the manifest, row-sliced + PII-masked
69
+ export default feature('guests', {
70
+ columns: { /* … eventId, shuttleId, email, … */ },
71
+ // org staff see the whole event; a shuttle driver sees only their bus
72
+ firewall: {
73
+ any: [
74
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
75
+ { all: [
76
+ { field: 'eventId', equals: 'ctx.scope.event' },
77
+ { field: 'shuttleId', equals: 'ctx.scope.event.shuttleId' }, // sub-key row slice
78
+ ] },
79
+ ],
80
+ },
81
+ masking: {
82
+ email: { type: 'email', show: { roles: ['admin', 'scope:event:organizer'] } }, // hidden from the driver
83
+ },
84
+ read: {
85
+ views: {
86
+ manifest: {
87
+ fields: ['id', 'nameAtInvite', 'shuttleId', 'pickupLocation'],
88
+ access: { roles: ['admin', 'scope:event:organizer', 'scope:event:shuttleDriver'] },
89
+ },
90
+ },
91
+ },
92
+ });
93
+ ```
94
+
95
+ | Pillar | How it reads the scoped role |
96
+ |--------|------------------------------|
97
+ | **Firewall** (rows) | `all`/`any` arms keyed on `ctx.scope.<kind>` (+ sub-keys) — see [Firewall](/compiler/definitions/firewall) |
98
+ | **Access** (verbs/views) | `access.roles: ['scope:event:shuttleDriver']` on CRUD, actions, and views |
99
+ | **Masking** (fields) | `masking.<col>.show.roles` includes / excludes `scope:event:<role>` |
100
+
101
+ ## The org / scope split (security)
102
+
103
+ **Scoped roles never merge into `ctx.roles`.** A `scope:*` identifier matches **only** the verified scope claim (`ctx.scope.<kind>.roles`); a bare org role (`admin`, `member`) matches **only** `ctx.roles`. The compiler enforces the split so an externally-provisioned `shuttleDriver` can **never** satisfy an `admin` gate by string coincidence, and a tampered scope claim can't impersonate an org role. This is the precondition for admitting limited outside users at all.
104
+
105
+ ## Sub-keys (row slicing)
106
+
107
+ A role's `subKeys` name columns on the relationship's `from` row that are projected into the claim. A firewall arm then slices on them:
108
+
109
+ ```typescript
110
+ { field: 'shuttleId', equals: 'ctx.scope.event.shuttleId' }
111
+ ```
112
+
113
+ Because sub-key arms compose with `all`, an **absent** sub-key denies (`sql\`1 = 0\``) rather than widening — a driver can never see *all* shuttles by simply lacking the claim. The scope accessor is always emitted null-safe (`ctx.scope?.event?.shuttleId`), so an org caller who never entered the scope hits a clean deny, not a 500.
114
+
115
+ ### Set-valued sub-keys
116
+
117
+ A driver may cover **more than one** bus. Append a `[]` marker to the
118
+ sub-key name to project **every** matched `from` row's value into the claim
119
+ as a `string[]`:
120
+
121
+ ```typescript
122
+ roles: {
123
+ shuttleDriver: { via: 'shuttleDriverOf', subKeys: ['shuttleId[]'] }, // set-valued
124
+ }
125
+ ```
126
+
127
+ The `[]` is a marker only — it's stripped from the column name (the
128
+ relationship's `from` row still reads `shuttleId`). At `/scope/v1/enter` the
129
+ proven rows union their values, so the claim carries an array:
130
+
131
+ ```jsonc
132
+ "scope": { "event": { "id": "evt_123", "roles": ["shuttleDriver"], "shuttleId": ["shA", "shC"] } }
133
+ ```
134
+
135
+ The matching firewall arm — written exactly as for the scalar case
136
+ (`{ field: 'shuttleId', equals: 'ctx.scope.event.shuttleId' }`) — is
137
+ **rewritten by the compiler** to an `inArray` row-slice:
138
+
139
+ ```sql
140
+ WHERE shuttle_id IN (ctx.scope?.event?.shuttleId ?? [])
141
+ ```
142
+
143
+ The `?? []` default makes an absent claim lower to `inArray(col, [])` — a
144
+ clean DENY, never a malformed SQL fragment or a 500. A scalar sub-key (no
145
+ `[]` marker) is untouched and keeps lowering to `eq`. You write the same
146
+ `equals` arm either way; declaring `shuttleId[]` vs `shuttleId` in the scope
147
+ role is the only switch.
148
+
149
+ ## Auto-stamping the scope column on insert (`q.scope`)
150
+
151
+ `q.scope('organization')` auto-stamps the tenant column on write, the same
152
+ way `q.scope('owner')` stamps `ownerId`. A relationship-derived kind works
153
+ identically: `q.scope('event')` auto-stamps the column from the **verified
154
+ scope claim** (`ctx.scope.event.id`) on insert — no need to pass `eventId`
155
+ in the request body:
156
+
157
+ ```typescript
158
+ export const eventNotes = q.table('event_notes', {
159
+ id: q.id(),
160
+ eventId: q.scope('event'), // INSERT autofill from ctx.scope.event.id
161
+ body: q.text().required(),
162
+ organizationId: q.scope('organization'), // INSERT autofill from ctx.activeOrgId
163
+ });
164
+ ```
165
+
166
+ The stamp is **insert-only** and null-safe — the generated CREATE handler
167
+ writes `eventId: ctx.scope?.event?.id`, so it never binds `undefined`. It
168
+ does **not** add a read-time `WHERE` filter (that's the firewall's job; a
169
+ read scoped to `eventId = ctx.scope.event.id` would be wrong here). Infra
170
+ kinds map to their session fields (`organization` → `ctx.activeOrgId`,
171
+ `owner` → `ctx.userId`, `team` → `ctx.activeTeamId`); any other kind maps to
172
+ `ctx.scope.<kind>.id`.
173
+
174
+ ## Namespace scope-claim refresh
175
+
176
+ A scope is normally minted at `POST /scope/v1/enter`. When you also mount a
177
+ [namespace](/compiler/definitions/access#namespace-mounts-hoisted-relationship-middleware)
178
+ that gates `/event/:eventId/*` on the **same** relationship, the namespace
179
+ resolver can refresh `ctx.scope.<kind>` in memory for the duration of that
180
+ request — so an attendee hitting `/event/evt_123/announce` gets
181
+ `ctx.scope.event = { id: 'evt_123', roles: ['attendee'] }` without a separate
182
+ `enter` round-trip. The refresh runs **after** the gate (the gate proves the
183
+ relationship; the refresh stamps the proven role from the path param).
184
+
185
+ This is a strictly-guarded convenience, and it stamps **per matched lane**. The
186
+ resolver records which `via:` lane opened the gate (first-match-wins) and stamps
187
+ **only that lane's** scope role — an attendee who matched `attendeeOf` gets
188
+ `roles: ['attendee']`; an organizer who matched `organizerOf` gets
189
+ `roles: ['organizer']`. A caller can never receive a role they didn't prove this
190
+ request.
191
+
192
+ - **Relationship lanes** each confer their own scope role, stamped only when that exact lane matched — so a **multi-lane `via:`** (e.g. `via: ['attendeeOf', 'organizerOf']`) refreshes the matched lane's role, not an ambiguous union.
193
+ - A **bulk-grant lane** (`{ roles: [...] }` or `{ team: true }`) confers **no** scope role — it opens the gate via the caller's org role *without* proving any relationship, so there is nothing to stamp (stamping one would forge it). The gate still passes; the caller is simply authorized by their org role.
194
+
195
+ The refresh described so far is in-memory and single-request. To also hand the
196
+ caller a **persisted** scope token, opt the namespace into `mintScope` — see
197
+ below.
198
+
199
+ ### Gotcha: a namespace only emits its resolver when it claims a standalone action
200
+
201
+ This is the single most common surprise (it has tripped up a customer): **a
202
+ namespace emits its resolver — and therefore the scope refresh and the
203
+ [`mintScope`](#mintscope-mint-the-scope-token-from-the-namespace-resolver)
204
+ mint — only when at least one STANDALONE action's `path:` falls under the
205
+ namespace prefix.**
206
+
207
+ A standalone action declares its own `path:` (e.g.
208
+ `path: '/event/:eventId/home'`), so the compiler can match it against the
209
+ namespace prefix and hoist it into the synthetic namespace routes file.
210
+ **Record-based actions are different** — they mount under their resource's CRUD
211
+ routes (`/api/v1/guests/:id/checkin`), which live *outside* the
212
+ `/event/:eventId` prefix. They never match the prefix, so they never get
213
+ claimed.
214
+
215
+ A namespace that contains **only** record-based actions is therefore **inert**:
216
+ nothing matches the prefix, no synthetic routes file is emitted, and so there
217
+ is **no resolver, no scope refresh, and no mint** — even though the namespace
218
+ is declared and validates cleanly. The middleware you expected to gate
219
+ `/event/:eventId/*` simply isn't there.
220
+
221
+ The fix is to give the namespace at least one standalone action under the
222
+ prefix. In `q-events`, `eventHome` exists precisely for this — a standalone
223
+ `GET /event/:eventId/home` that pulls the resolver (and the §5.3 mint) into
224
+ existence:
225
+
226
+ ```typescript
227
+ // features/events/actions/eventHome.ts
228
+ export default defineAction({
229
+ path: '/event/:eventId/home', // ← standalone path UNDER the namespace prefix
230
+ method: 'GET',
231
+ input: z.object({}),
232
+ access: { roles: ['scope:event:attendee', 'scope:event:organizer', 'manager+'] },
233
+ async execute({ db, ctx, c }) { /* … */ },
234
+ });
235
+ ```
236
+
237
+ With that action present, the `eventScope` resolver is emitted, runs the
238
+ `attendeeOf` probe once per `/event/:eventId/*` request, stamps
239
+ `ctx.scope.event`, and (because the namespace sets `mintScope: true`) mints the
240
+ scope token. Without a standalone action under the prefix, none of that fires.
241
+
242
+ ## `mintScope` — mint the scope token from the namespace resolver
243
+
244
+ A scope is normally minted by an explicit `POST /scope/v1/enter` round-trip.
245
+ Setting **`mintScope: true`** on a namespace folds that mint into the
246
+ namespace resolver: on a successful relationship probe the resolver MINTS a
247
+ persisted scope JWT and returns it via the `set-auth-token` header — so a
248
+ native client hitting `/event/:eventId/*` gets a scope token **without ever
249
+ calling `/scope/v1/enter`**.
250
+
251
+ ```typescript
252
+ // quickback.config.ts
253
+ authz: {
254
+ relationships: {
255
+ attendeeOf: {
256
+ from: 'guests',
257
+ subject: { column: 'linkedUserId', equals: 'ctx.userId' },
258
+ resource: { column: 'eventId' },
259
+ where: { status: 'confirmed' },
260
+ loads: 'guests',
261
+ exposeAs: 'guest',
262
+ },
263
+ },
264
+ namespaces: {
265
+ eventScope: {
266
+ prefix: '/event/:eventId',
267
+ via: ['attendeeOf'], // one or more lanes — mints the matched lane's role
268
+ mintScope: true, // ← fold the scope-token mint into the resolver
269
+ },
270
+ },
271
+ }
272
+ ```
273
+
274
+ A confirmed attendee then hits the standalone action under the prefix:
275
+
276
+ ```http
277
+ GET /api/v1/event/evt_123/home
278
+ Authorization: Bearer <existing-jwt>
279
+
280
+ 200 OK
281
+ set-auth-token: <new-scoped-jwt> ← carries scope.event.roles = ["attendee"]
282
+ ```
283
+
284
+ The client stores the `set-auth-token` value and sends it as the bearer on
285
+ every subsequent `/event/:eventId/*` request. The JWT carries
286
+ `scope.event = { id: 'evt_123', roles: ['attendee'] }`, so the scoped-role
287
+ access checks (`scope:event:attendee`) pass with no DB touch and no second
288
+ `enter` call.
289
+
290
+ `mintScope` is **opt-in per namespace** and defaults to `false`. With it off,
291
+ the resolver does the in-memory `ctx.scope.<kind>` refresh only (the section
292
+ above); subsequent requests must still call `/scope/v1/enter` for a persisted
293
+ token.
294
+
295
+ ### Per-matched-lane minting (forging safety)
296
+
297
+ The mint stamps the scope role of **whichever lane matched**, gated on the
298
+ first-match-wins probe — the *same* per-lane discipline as the in-memory stamp,
299
+ applied here with higher stakes: a minted token **persists for its whole TTL**,
300
+ so it can only ever carry the role the caller actually proved this request.
301
+
302
+ - A **multi-lane `via:`** (e.g. `via: ['attendeeOf', 'organizerOf']`) mints the matched lane's role — `attendeeOf` → `scope.event.roles = ['attendee']`, `organizerOf` → `['organizer']`. The resolver records which lane opened the gate, so there is no ambiguity.
303
+ - A **bulk-grant lane** (`{ roles: [...] }` or `{ team: true }`) mints **no** scope role — it opens the gate via the caller's org role without proving a relationship. The gate passes; the caller carries their org role, not a minted scope role.
304
+
305
+ > The realtime [ws-ticket](/stack/realtime/durable-objects#namespace-backed-tickets-per-matched-lane) can authorize through this same namespace `via:`, issuing a per-matched-lane WebSocket ticket — so the socket gate and the REST gate stay identical.
306
+
307
+ In every suppressed case the gate still authorizes the request; only the mint
308
+ (and the in-memory refresh) are skipped, and those callers obtain a scope
309
+ token through `/scope/v1/enter` as usual. Flipping `mintScope: true` can never
310
+ forge a scope role — the guard, not the flag, is the gate.
311
+
312
+ ### TTL and best-effort semantics
313
+
314
+ - **TTL is the scope-token TTL** — `auth.jwt.expiresIn` (default 180s), **clamped to a hard ≤180s ceiling** at the mint site. A longer-lived scope token would widen the post-revocation replay window past the spec bound, so the clamp is non-negotiable.
315
+ - **The mint is gated by the same proven-relationship guard as the in-memory stamp.** It runs *after* the gate has granted access, reading the instance id from the proven path param (`:eventId`) — never from request input — so the minted `scope:<kind>:<role>` is backed by exactly the proof `/scope/v1/enter` requires. The token is **byte-identical** to one `/scope/v1/enter` would produce: same shared mint helper, same carry-forward of any *other* verified scope kinds already on the incoming token (the freshly-proven kind takes precedence; siblings survive the re-mint).
316
+ - **The mint is best-effort.** A mint failure (e.g. a missing signing secret) **never fails the request** — the in-memory stamp already authorized it; the caller simply doesn't receive a refreshed token on that response and can fall back to `/scope/v1/enter`.
317
+
318
+ ## Revocation & TTL
319
+
320
+ The scope claim is trusted for the JWT TTL (default 180s, `auth.jwt.expiresIn`) — identical to how `orgId` / `role` claims already behave. Removing a guest/staff row takes effect within one TTL (the next `enter` won't re-mint the role). Immediate revocation (`auth.jwt.revocationCheck: 'kv'`) is on the roadmap.
321
+
322
+ ## Reference
323
+
324
+ ```typescript
325
+ // AppContext (generated lib/types.ts)
326
+ ctx.scope?: Record<string, { id: string; roles?: string[]; [subKey: string]: string | string[] | undefined }>;
327
+
328
+ // authz.scopes.<kind>
329
+ {
330
+ requestField: string; // body field carrying the instance id
331
+ roles: Record<string, { via: string; subKeys?: string[] }>; // 'col' → eq, 'col[]' → inArray
332
+ }
333
+ ```
334
+
335
+ - `requestField` must equal every role-relationship's `resource.column`.
336
+ - Each relationship's `from` table must exist and ship a generated firewall (it can't be `exception`).
337
+ - A `subKeys` entry ending in `[]` is **set-valued** (lowers to `inArray`, minted as `string[]`); without the marker it's scalar (`eq`, minted as `string`).
338
+ - `q.scope('<kind>')` auto-stamps the column from `ctx.scope.<kind>.id` on insert.
339
+ - Generated route: `POST /scope/v1/enter` (mounted only when `authz.scopes` is declared).
@@ -312,6 +312,72 @@ the metric from the user's filters would surprise.
312
312
  - No raw SQL `expr:` form. Column references only — declare a generated
313
313
  column or write a custom action if you need arithmetic.
314
314
 
315
+ ## Aggregate-only views
316
+
317
+ A normal view returns rows *and* (optionally) aggregations. An
318
+ **aggregate-only** view returns the rollup and **nothing else** — no
319
+ `data[]`, no field selection. Set `aggregateOnly: true`:
320
+
321
+ ```typescript
322
+ read: {
323
+ views: {
324
+ 'dietary-rollup': {
325
+ aggregateOnly: true,
326
+ fields: [], // must be empty/absent
327
+ kMin: 5, // k-anonymity bucket size
328
+ access: { roles: ['scope:event:fnb', 'admin'] },
329
+ aggregations: {
330
+ dietaryRollup: { fn: 'groupBy', field: 'dietaryNotes' },
331
+ totalGuests: { fn: 'sum', field: 'guestCount' },
332
+ headcount: { fn: 'count' },
333
+ },
334
+ },
335
+ },
336
+ }
337
+ ```
338
+
339
+ The response carries only `aggregations`:
340
+
341
+ ```json
342
+ {
343
+ "view": "dietary-rollup",
344
+ "aggregations": {
345
+ "dietaryRollup": { "vegan": 18, "gluten-free": 12, "(none)": 143 },
346
+ "totalGuests": 184,
347
+ "headcount": 173
348
+ }
349
+ }
350
+ ```
351
+
352
+ This lets a vendor see *"12 guests need a gluten-free meal"* without ever
353
+ reading the roster. The endpoint is gated **independently** of the base
354
+ collection and the per-row views — reading the rollup grants zero row or
355
+ field access.
356
+
357
+ **Constraints (compile-time):**
358
+
359
+ - Requires a non-empty `aggregations` map.
360
+ - `fields` must be empty or absent — field selection is disabled, and
361
+ `?fields=` cannot coax row-level data out.
362
+ - Only the view's `query.filterable` allowlist is honored. `query.searchable`
363
+ and `query.sortable` are rejected (no `?search=`, no `?sort=`, no
364
+ free-form `?<col>=` outside the allowlist).
365
+
366
+ ### `kMin` — k-anonymity suppression
367
+
368
+ `kMin` (default `5`) protects against re-identification through small
369
+ buckets ("1 guest, allergy = shellfish"):
370
+
371
+ - `groupBy` buckets with fewer than `kMin` rows collapse into a single
372
+ `"(other)"` bucket carrying their summed count.
373
+ - A scalar `count` / `sum` / `avg` / `min` / `max` / `count_distinct`
374
+ computed over a filtered set smaller than `kMin` rows returns the literal
375
+ string `"(suppressed)"` instead of a number.
376
+
377
+ `kMin` is only meaningful on `aggregateOnly: true` views. It's ignored on
378
+ row-returning views, where the aggregations ride alongside the rows and the
379
+ row firewall already governs disclosure.
380
+
315
381
  ## Response Format
316
382
 
317
383
  View responses include metadata about the view:
@@ -1,8 +1,8 @@
1
1
  # Blog Template
2
2
 
3
- The blog template creates a single-tenant backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts via Better Auth's admin plugin.
3
+ The blog template creates a fixed-org backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts through their membership in one pinned organization.
4
4
 
5
- This template uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, no `organizationId` columns. Roles come from `user.role` instead of org membership.
5
+ This template uses [pinned organization mode](/compiler/config/single-tenant). Organization support stays on, but the generated project hard-codes one organization id and hides org switching UI.
6
6
 
7
7
  ## Create the Project
8
8
 
@@ -16,7 +16,7 @@ This scaffolds a project with:
16
16
  ```
17
17
  my-site/
18
18
  ├── quickback/
19
- │ ├── quickback.config.ts # Single-tenant config
19
+ │ ├── quickback.config.ts # Pinned-organization config
20
20
  │ └── features/
21
21
  │ └── posts/
22
22
  │ ├── posts.ts # Schema + security (defineTable)
@@ -37,7 +37,7 @@ export default {
37
37
  name: "my-site",
38
38
  template: "hono",
39
39
  features: {
40
- organizations: false,
40
+ pinnedOrganizationId: "org_replace_me",
41
41
  },
42
42
  providers: {
43
43
  runtime: { name: "cloudflare", config: {} },
@@ -50,7 +50,7 @@ export default {
50
50
  };
51
51
  ```
52
52
 
53
- Key difference from the multi-tenant templates: `organizations: false` disables the Better Auth organization plugin. See [Single-Tenant Mode](/compiler/config/single-tenant) for details.
53
+ Replace `org_replace_me` with a real Better Auth organization id before deploying. Unlike the removed single-tenant mode, this template keeps the Better Auth organization plugin and resolves roles from membership in that pinned org. See [Pinned Organization Mode](/compiler/config/single-tenant) for details.
54
54
 
55
55
  ### Posts Feature (posts.ts)
56
56
 
@@ -91,7 +91,7 @@ export default defineTable(posts, {
91
91
  ```
92
92
 
93
93
  - **`PUBLIC`** role on `read.access` means no authentication required for `GET /` and `GET /:id`
94
- - **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `role: "admin"` (set via Better Auth's admin plugin)
94
+ - **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `member.role === "admin"` in the pinned organization
95
95
  - **`owner`** firewall scope tracks who created each post via `ownerId`
96
96
  - **`softDelete`** marks posts as deleted rather than removing them from the database
97
97
 
@@ -270,7 +270,7 @@ npm run deploy
270
270
 
271
271
  ## Next Steps
272
272
 
273
- - [Single-Tenant Mode](/compiler/config/single-tenant) — How single-tenant mode works
273
+ - [Pinned Organization Mode](/compiler/config/single-tenant) — How fixed-org mode works
274
274
  - [Access Control](/compiler/definitions/access) — PUBLIC role and role-based permissions
275
275
  - [Custom Actions](/compiler/definitions/actions) — Add business logic beyond CRUD
276
276
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Multi-tenant alternative
@@ -33,9 +33,6 @@ my-app/
33
33
  export default {
34
34
  name: "my-app",
35
35
  template: "hono",
36
- features: {
37
- organizations: true,
38
- },
39
36
  providers: {
40
37
  runtime: { name: "cloudflare", config: {} },
41
38
  database: {
@@ -47,7 +44,7 @@ export default {
47
44
  };
48
45
  ```
49
46
 
50
- Multi-tenant mode (`organizations: true`) is the default. Change to `organizations: false` for [single-tenant mode](/compiler/config/single-tenant).
47
+ Organization-backed auth is the default. If you want a fixed-org deployment with no org switching UI, add `features.pinnedOrganizationId` as described in [Pinned Organization Mode](/compiler/config/single-tenant).
51
48
 
52
49
  ## Adding Your First Feature
53
50
 
@@ -23,13 +23,13 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
23
23
 
24
24
  The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
25
25
 
26
- ### Single-tenant starter (free)
26
+ ### Fixed-org starter (free)
27
27
 
28
28
  | Template | Includes | Command |
29
29
  |----------|----------|---------|
30
- | `blog` | Single-tenant blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions | `quickback create blog my-site` |
30
+ | `blog` | Blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions, and a pinned organization id placeholder | `quickback create blog my-site` |
31
31
 
32
- The **blog** template uses Better Auth's admin plugin (not the org plugin) and [single-tenant mode](/compiler/config/single-tenant) (`organizations: false`).
32
+ The **blog** template uses [pinned organization mode](/compiler/config/single-tenant) and scaffolds `features.pinnedOrganizationId: "org_replace_me"`.
33
33
 
34
34
  ### Empty scaffold (free)
35
35
 
@@ -68,9 +68,9 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
68
68
 
69
69
  Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
70
70
 
71
- ### Blog (single-tenant CMS)
71
+ ### Blog (pinned-organization CMS)
72
72
 
73
- Best for personal sites, blogs, or any app with a single tenant. Uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, roles come from `user.role` via Better Auth's admin plugin.
73
+ Best for personal sites, blogs, or any app that only needs one organization at runtime. Uses [pinned organization mode](/compiler/config/single-tenant) — organization support stays on, but the generated app hard-codes one org id and hides org switching.
74
74
 
75
75
  - Public JSON API for content
76
76
  - Admin-only editing
@@ -110,4 +110,4 @@ See the individual template guides for detailed setup:
110
110
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare)
111
111
  - [Blog Template](/compiler/getting-started/template-blog)
112
112
  - [Empty Scaffolding](/compiler/getting-started/template-empty)
113
- - [Single-Tenant Mode](/compiler/config/single-tenant)
113
+ - [Pinned Organization Mode](/compiler/config/single-tenant)
@@ -131,7 +131,7 @@ execute: async ({ db, ctx, input }) => {
131
131
  }
132
132
  ```
133
133
 
134
- If you need unscoped access (for example, audited platform admin operations), declare `unsafe` on the action:
134
+ If you need unscoped access (for example, audited cross-tenant sysadmin operations), declare `unsafe` on the action:
135
135
 
136
136
  ```typescript
137
137
  adminReport: {
@@ -152,7 +152,7 @@ adminReport: {
152
152
  Cross-tenant unsafe actions are generated with:
153
153
 
154
154
  - Better Auth authentication required
155
- - platform admin gate (`ctx.userRole === 'admin'`)
155
+ - sysadmin gate (`ctx.userRole === 'sysadmin'`)
156
156
  - mandatory audit logging on denial/success/error
157
157
 
158
158
  Without unsafe mode, `unsafeDb` is `undefined`.
@@ -67,7 +67,7 @@ When both CMS and Account UI are enabled, the admin panel's profile page shows a
67
67
  cms: { domain: "cms.example.com", access: "admin" },
68
68
  ```
69
69
 
70
- With `access: "admin"`, non-admin users can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to admins. See [CMS Connecting](/stack/cms/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
70
+ With `access: "admin"`, callers outside the platform control-plane roles can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to `userRole: ["appmanager"]` (plus `sysadmin` when enabled). See [CMS Connecting](/stack/cms/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
71
71
 
72
72
  ## Related
73
73
 
@@ -196,7 +196,7 @@ ENABLE_ORGANIZATIONS=false
196
196
  ENABLE_ADMIN=false
197
197
  ```
198
198
 
199
- Simple email/password authentication for single-tenant apps.
199
+ Simple email/password authentication for apps that do not need advanced auth methods.
200
200
 
201
201
  ### Maximum Security
202
202
 
@@ -256,7 +256,7 @@ import { setAppConfig } from '@/config/app';
256
256
 
257
257
  setAppConfig({
258
258
  features: {
259
- organizations: false, // Disable organizations
259
+ organizations: false, // Hide organization-management UI
260
260
  passkey: true, // Enable passkey
261
261
  },
262
262
  });
@@ -150,12 +150,12 @@ cms: { domain: "cms.example.com" }
150
150
 
151
151
  This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `cms.example.com` point to the same Worker. The compiler auto-configures hostname-based routing and cross-subdomain cookies.
152
152
 
153
- CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the Better Auth platform-admin tier) can reach `/cms/*`. Non-admin authenticated users are redirected to `/account/profile`. The gate is enforced at multiple layers:
153
+ CMS access defaults to `access: "admin"` — only `user.role === "appmanager"` (the Better Auth platform control-plane tier) can reach `/cms/*`. When `cms.sysadmin: true`, `user.role === "sysadmin"` is also admitted. Other authenticated users are redirected to `/account/profile`. The gate is enforced at multiple layers:
154
154
 
155
- - **Account UI** hides the "Go to CMS" button for non-admins.
156
- - **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-admin. A non-admin who types the CMS URL directly cannot load the app.
157
- - **`/api/v1/schema`** returns `403 Admin access required` to non-admin callers, so schema metadata can't be scraped by hitting the API directly.
158
- - **`custom_view` routes** are gated on `userRole: ["admin"]` rather than org membership, so saved views can't be listed or modified without admin rights.
155
+ - **Account UI** hides the "Go to CMS" button for callers outside those roles.
156
+ - **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-operator. A non-operator who types the CMS URL directly cannot load the app.
157
+ - **`/api/v1/schema`** returns `403 Platform operator access required` to callers outside those roles, so schema metadata can't be scraped by hitting the API directly.
158
+ - **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
159
159
  - **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
160
160
 
161
161
  Your resource API endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
@@ -168,30 +168,31 @@ cms: { access: "user" }
168
168
 
169
169
  See [Multi-Domain Architecture](/compiler/config/domains) for details on multi-domain routing.
170
170
 
171
- ## Multi-Tenant vs Single-Tenant
171
+ ## Default Org Mode vs Pinned Organization Mode
172
172
 
173
- The CMS supports two authentication modes depending on your project's organization configuration.
173
+ The CMS supports two organization flows depending on your project's config.
174
174
 
175
- ### Multi-Tenant (Default)
175
+ ### Default Org Mode
176
176
 
177
- In multi-tenant mode, the CMS gates access behind organization membership:
177
+ By default, the CMS gates access behind organization membership:
178
178
 
179
179
  1. User logs in via Better Auth session
180
180
  2. CMS fetches the user's organization memberships
181
181
  3. If the user belongs to multiple organizations, an **org selector** is displayed
182
182
  4. Once an org is selected, the user's role within that org determines their CMS permissions
183
183
 
184
- This is the default behavior for all Quickback projects.
184
+ This is the default behavior for Quickback projects with no pinned org.
185
185
 
186
- ### Single-Tenant Mode
186
+ ### Pinned Organization Mode
187
187
 
188
- When your project disables organizations (`features.organizations: false` in config), the compiler sets `singleTenant: true` in the schema registry. In this mode:
188
+ When your project sets `features.pinnedOrganizationId`, the CMS keeps org-backed auth but fixes the active org at runtime. In this mode:
189
189
 
190
- - No org gate or org selector is shown
191
- - The user's role is read directly from `user.role` on the session
192
- - All data is unscoped (no `organizationId` filtering)
190
+ - No org selector is shown
191
+ - The org gate is bypassed because the active org is known up front
192
+ - The user's `roles` still come from membership in the pinned org
193
+ - Org-scoped data remains scoped by `organizationId`
193
194
 
194
- Single-tenant mode is useful for internal tools, personal projects, or apps that don't need multi-org isolation.
195
+ Pinned organization mode is useful for internal tools, blogs, and one-customer deployments that still want org-backed roles and schema conventions without runtime org switching.
195
196
 
196
197
  ## Next Steps
197
198