@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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +36 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/compile.test.d.ts +2 -0
- package/dist/commands/compile.test.d.ts.map +1 -0
- package/dist/commands/compile.test.js +83 -0
- package/dist/commands/compile.test.js.map +1 -0
- package/dist/commands/create.js +15 -11
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/migrations.d.ts +33 -0
- package/dist/commands/migrations.d.ts.map +1 -1
- package/dist/commands/migrations.js +41 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/migrations.test.d.ts +2 -0
- package/dist/commands/migrations.test.d.ts.map +1 -0
- package/dist/commands/migrations.test.js +67 -0
- package/dist/commands/migrations.test.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +56 -26
- package/dist/docs/content.js.map +1 -1
- package/dist/examples/recruitment.tar.gz +0 -0
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +48 -0
- package/dist/lib/action-harvest.d.ts.map +1 -0
- package/dist/lib/action-harvest.js +292 -0
- package/dist/lib/action-harvest.js.map +1 -0
- package/dist/lib/action-harvest.test.d.ts +2 -0
- package/dist/lib/action-harvest.test.d.ts.map +1 -0
- package/dist/lib/action-harvest.test.js +112 -0
- package/dist/lib/action-harvest.test.js.map +1 -0
- package/dist/lib/api-client.d.ts +10 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +17 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +19 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/artifact-routing.d.ts +1 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +15 -3
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/artifact-routing.test.js +12 -1
- package/dist/lib/artifact-routing.test.js.map +1 -1
- package/dist/lib/file-loader.d.ts +1 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +34 -1
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +28 -4
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/lib/prepare-state-output.d.ts +8 -0
- package/dist/lib/prepare-state-output.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.js +17 -0
- package/dist/lib/prepare-state-output.js.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts +2 -0
- package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.js +31 -0
- package/dist/lib/prepare-state-output.test.js.map +1 -0
- package/dist/skill/SKILL.md +4 -4
- package/dist/skill/agents/quickback-specialist/AGENT.md +3 -3
- package/dist/skill/docs/changelog.md +643 -0
- package/dist/skill/docs/compiler/config/agents.md +1 -1
- package/dist/skill/docs/compiler/config/auth.md +1 -1
- package/dist/skill/docs/compiler/config/index.md +8 -9
- package/dist/skill/docs/compiler/config/providers.md +3 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
- package/dist/skill/docs/compiler/definitions/access.md +40 -33
- package/dist/skill/docs/compiler/definitions/actions.md +1 -1
- package/dist/skill/docs/compiler/definitions/arrows.md +269 -0
- package/dist/skill/docs/compiler/definitions/diagnostics.md +136 -0
- package/dist/skill/docs/compiler/definitions/feature.md +3 -3
- package/dist/skill/docs/compiler/definitions/fga.md +314 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +94 -7
- package/dist/skill/docs/compiler/definitions/permissions.md +145 -0
- package/dist/skill/docs/compiler/definitions/schema.md +8 -2
- package/dist/skill/docs/compiler/definitions/scopes.md +339 -0
- package/dist/skill/docs/compiler/definitions/views.md +66 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
- package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
- package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
- package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
- package/dist/skill/docs/stack/cms/connecting.md +17 -16
- package/dist/skill/docs/stack/cms/index.md +7 -7
- package/dist/skill/docs/stack/cms/schema-format.md +0 -2
- package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
- package/dist/skill/docs/stack/cms/security.md +6 -6
- package/dist/skill/docs/stack/realtime/durable-objects.md +48 -7
- package/dist/skill/docs/stack/realtime/live-views.md +168 -0
- package/dist/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
- package/dist/skill/docs/stack/storage/r2.md +112 -3
- package/dist/skill/docs/stack/storage/using-r2.md +30 -10
- package/dist/templates/registry.js +2 -2
- package/dist/templates/registry.js.map +1 -1
- package/package.json +1 -1
- package/src/examples/recruitment.tar.gz +0 -0
- package/src/skill/SKILL.md +4 -4
- package/src/skill/agents/quickback-specialist/AGENT.md +3 -3
- package/src/skill/docs/changelog.md +643 -0
- package/src/skill/docs/compiler/config/agents.md +1 -1
- package/src/skill/docs/compiler/config/auth.md +1 -1
- package/src/skill/docs/compiler/config/index.md +8 -9
- package/src/skill/docs/compiler/config/providers.md +3 -0
- package/src/skill/docs/compiler/config/single-tenant.md +65 -73
- package/src/skill/docs/compiler/definitions/access.md +40 -33
- package/src/skill/docs/compiler/definitions/actions.md +1 -1
- package/src/skill/docs/compiler/definitions/arrows.md +269 -0
- package/src/skill/docs/compiler/definitions/diagnostics.md +136 -0
- package/src/skill/docs/compiler/definitions/feature.md +3 -3
- package/src/skill/docs/compiler/definitions/fga.md +314 -0
- package/src/skill/docs/compiler/definitions/firewall.md +94 -7
- package/src/skill/docs/compiler/definitions/permissions.md +145 -0
- package/src/skill/docs/compiler/definitions/schema.md +8 -2
- package/src/skill/docs/compiler/definitions/scopes.md +339 -0
- package/src/skill/docs/compiler/definitions/views.md +66 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
- package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
- package/src/skill/docs/compiler/getting-started/templates.md +6 -6
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
- package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
- package/src/skill/docs/stack/account-ui/features/index.md +2 -2
- package/src/skill/docs/stack/cms/connecting.md +17 -16
- package/src/skill/docs/stack/cms/index.md +7 -7
- package/src/skill/docs/stack/cms/schema-format.md +0 -2
- package/src/skill/docs/stack/cms/schema-registry.md +0 -6
- package/src/skill/docs/stack/cms/security.md +6 -6
- package/src/skill/docs/stack/realtime/durable-objects.md +48 -7
- package/src/skill/docs/stack/realtime/live-views.md +168 -0
- package/src/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
- package/src/skill/docs/stack/storage/r2.md +112 -3
- 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
|
|
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 [
|
|
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 #
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
- [
|
|
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
|
-
|
|
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
|
-
###
|
|
26
|
+
### Fixed-org starter (free)
|
|
27
27
|
|
|
28
28
|
| Template | Includes | Command |
|
|
29
29
|
|----------|----------|---------|
|
|
30
|
-
| `blog` |
|
|
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
|
|
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 (
|
|
71
|
+
### Blog (pinned-organization CMS)
|
|
72
72
|
|
|
73
|
-
Best for personal sites, blogs, or any app
|
|
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
|
-
- [
|
|
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
|
|
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
|
-
-
|
|
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"`,
|
|
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
|
|
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, //
|
|
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 === "
|
|
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
|
|
156
|
-
- **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-
|
|
157
|
-
- **`/api/v1/schema`** returns `403
|
|
158
|
-
- **`custom_view` routes** are gated on `userRole: ["
|
|
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
|
-
##
|
|
171
|
+
## Default Org Mode vs Pinned Organization Mode
|
|
172
172
|
|
|
173
|
-
The CMS supports two
|
|
173
|
+
The CMS supports two organization flows depending on your project's config.
|
|
174
174
|
|
|
175
|
-
###
|
|
175
|
+
### Default Org Mode
|
|
176
176
|
|
|
177
|
-
|
|
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
|
|
184
|
+
This is the default behavior for Quickback projects with no pinned org.
|
|
185
185
|
|
|
186
|
-
###
|
|
186
|
+
### Pinned Organization Mode
|
|
187
187
|
|
|
188
|
-
When your project
|
|
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
|
|
191
|
-
- The
|
|
192
|
-
-
|
|
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
|
-
|
|
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
|
|