@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,269 @@
|
|
|
1
|
+
# Arrows
|
|
2
|
+
|
|
3
|
+
A relationship answers *"does the caller have a row linking them to this
|
|
4
|
+
resource?"* An **arrow** answers a different question: *"the caller has
|
|
5
|
+
authority over **another** object — does that authority **flow across a
|
|
6
|
+
foreign key** to this one?"* An event's announcements inherit the authority
|
|
7
|
+
of the event's organization; a folder's documents inherit the authority of
|
|
8
|
+
the folder; a child section inherits the authority of its ancestors.
|
|
9
|
+
|
|
10
|
+
An arrow is a declared **FK hop**: it names a foreign-key column on a `from`
|
|
11
|
+
table and the `to` table that FK resolves to. Referenced from a permission,
|
|
12
|
+
it resolves the row's FK to its target object and requires a permission
|
|
13
|
+
**there** — SpiceDB's `relation->permission`, lowered to SQL. Two emit
|
|
14
|
+
shapes: a single FK hop lowers to a subquery; a self-referential hop
|
|
15
|
+
(`folder.parentId -> folder`) lowers to a depth-bounded `WITH RECURSIVE` CTE.
|
|
16
|
+
|
|
17
|
+
## Declaring arrows
|
|
18
|
+
|
|
19
|
+
Arrows live in `quickback.config.ts` under `authz.arrows`, alongside
|
|
20
|
+
`authz.relationships` and `authz.permissions`:
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
// quickback.config.ts
|
|
24
|
+
import { defineConfig } from '@quickback/compiler';
|
|
25
|
+
|
|
26
|
+
export default defineConfig({
|
|
27
|
+
// ...providers...
|
|
28
|
+
authz: {
|
|
29
|
+
arrows: {
|
|
30
|
+
// single FK hop: an event row → the organization that owns it
|
|
31
|
+
eventOrg: { from: 'event', fk: 'organizationId', to: 'organization' },
|
|
32
|
+
// self-referential hierarchy: a folder → its parent folder
|
|
33
|
+
folderTree: { from: 'folder', fk: 'parentId', to: 'folder', recursive: true },
|
|
34
|
+
},
|
|
35
|
+
permissions: {
|
|
36
|
+
'org:admin': { anyOf: [{ role: 'admin' }, { role: 'owner' }] },
|
|
37
|
+
// org admins of an event's org inherit access to the event
|
|
38
|
+
'event:view': { anyOf: ['organizerOf', { arrowRef: 'eventOrg', permission: 'org:admin' }] },
|
|
39
|
+
// anyone who can administer an ancestor folder can read this folder
|
|
40
|
+
'folder:read': { anyOf: [{ arrowRef: 'folderTree', permission: 'org:admin' }] },
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
| Field | Meaning |
|
|
47
|
+
|---|---|
|
|
48
|
+
| `from` | Source table the FK column lives on. |
|
|
49
|
+
| `fk` | Foreign-key column on `from`. **For a non-recursive arrow this is the tenant column** the claim binds against (see below); for a recursive arrow it is the recursion pointer (`parentId`). |
|
|
50
|
+
| `to` | Target table the FK resolves to. A self-hop has `from === to`. |
|
|
51
|
+
| `recursive?` | Forces the recursive-CTE lowering. When `from === to` the compiler auto-detects recursion even if this is omitted. Default `false`. |
|
|
52
|
+
| `maxDepth?` | Per-arrow recursion bound (positive integer). Ignored for non-recursive arrows. Default is the global bound, `8`. |
|
|
53
|
+
| `tenantColumn?` | The tenant column the seed of a **recursive** arrow binds the org claim against — defaults to `organizationId`. Set it when the hierarchy table spells the column differently (e.g. `organisationId`). Ignored for non-recursive arrows. |
|
|
54
|
+
|
|
55
|
+
## Referencing an arrow from a permission
|
|
56
|
+
|
|
57
|
+
An arrow is never used directly. It is a **leaf** inside a
|
|
58
|
+
[permission](/compiler/definitions/permissions) expression, written as
|
|
59
|
+
`{ arrowRef: '<name>', permission: '<perm-at-target>' }`:
|
|
60
|
+
|
|
61
|
+
```typescript
|
|
62
|
+
'event:view': { anyOf: ['organizerOf', { arrowRef: 'eventOrg', permission: 'org:admin' }] },
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Read it as: *"`event:view` holds if the caller is an `organizerOf` the
|
|
66
|
+
event, **or** if — hopping across `eventOrg` to the event's organization —
|
|
67
|
+
the caller has `org:admin` **there**."* The `permission` named on the leaf is
|
|
68
|
+
the permission required **at the target object**, and it participates in the
|
|
69
|
+
permission composition graph (resolution + cycle detection) exactly like a
|
|
70
|
+
`{ permissionRef }`.
|
|
71
|
+
|
|
72
|
+
**M2 target restriction.** The target permission must reduce to
|
|
73
|
+
**org-membership roles** (`admin` / `owner` / `member`) — directly or
|
|
74
|
+
through a `permissionRef` / `anyOf` / `allOf` of org roles. That's what lets
|
|
75
|
+
the hop bind to the caller's verified active-org claim (`ctx.activeOrgId`).
|
|
76
|
+
A target permission that references a relation, a scoped role, a pseudo-role,
|
|
77
|
+
a `not`, or a nested arrow is a **compile error** in M2 (never a silent
|
|
78
|
+
allow) — those richer targets are a documented fast-follow. So
|
|
79
|
+
`org:admin = anyOf(role('admin'), role('owner'))` is the canonical target.
|
|
80
|
+
|
|
81
|
+
## Using the permission in a firewall
|
|
82
|
+
|
|
83
|
+
The permission that contains the arrow is referenced from a resource's
|
|
84
|
+
[`firewall`](/compiler/definitions/firewall) with a `{ field, permission }`
|
|
85
|
+
arm, like any other named permission. `field` is the resource-side column the
|
|
86
|
+
lowered subquery constrains:
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
// features/event-documents/event-documents.ts
|
|
90
|
+
firewall: {
|
|
91
|
+
all: [
|
|
92
|
+
{ field: 'eventId', permission: 'event:view' },
|
|
93
|
+
{ field: 'deletedAt', isNull: true },
|
|
94
|
+
],
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The arrow arm of `event:view` lowers to an FK-hop subquery on `eventId`; the
|
|
99
|
+
relationship arms (`organizerOf`) lower to relationship subqueries; the
|
|
100
|
+
`anyOf` OR's them under the null-safe empty-guard (`anyGuarded`) so an absent
|
|
101
|
+
claim **denies** rather than reading the whole table.
|
|
102
|
+
|
|
103
|
+
## Emit shape 1 — non-recursive (FK-hop subquery)
|
|
104
|
+
|
|
105
|
+
For `eventOrg = { from: 'event', fk: 'organizationId', to: 'organization' }`
|
|
106
|
+
with target permission `org:admin`, an `{ arrowRef: 'eventOrg' }` arm on a
|
|
107
|
+
resource constrained by `eventId` lowers to:
|
|
108
|
+
|
|
109
|
+
```sql
|
|
110
|
+
WHERE event_documents.eventId IN (
|
|
111
|
+
SELECT event.id FROM event
|
|
112
|
+
WHERE event.organizationId = ? -- ? = ctx.activeOrgId (signed claim)
|
|
113
|
+
)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
In Drizzle terms:
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
inArray(event_documents.eventId,
|
|
120
|
+
db.select({ x: event.id }).from(event)
|
|
121
|
+
.where(eq(event.organizationId, ctx.activeOrgId!)))
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The seed of every non-recursive hop binds the **`fk` column** to the active-org
|
|
125
|
+
claim — so for a non-recursive arrow, **`fk` is the org/tenant column on
|
|
126
|
+
`from`**, not an unrelated FK. (A self-FK hierarchy is the recursive case
|
|
127
|
+
below; that's where `fk` is a recursion pointer and the tenant column is
|
|
128
|
+
separate.)
|
|
129
|
+
|
|
130
|
+
## Emit shape 2 — recursive (bounded `WITH RECURSIVE` CTE)
|
|
131
|
+
|
|
132
|
+
A self-referential arrow expresses **inherited authority down a hierarchy**:
|
|
133
|
+
a row is visible if the caller controls it directly **or** controls any of
|
|
134
|
+
its ancestors. For `folderTree = { from: 'folder', fk: 'parentId', to: 'folder', recursive: true }`
|
|
135
|
+
the arrow lowers to a recursive CTE bounded by `maxDepth`:
|
|
136
|
+
|
|
137
|
+
```sql
|
|
138
|
+
WITH RECURSIVE __arrow_closure(id, depth) AS (
|
|
139
|
+
-- seed: the folders the caller directly controls (tenant-constrained)
|
|
140
|
+
SELECT folder.id, 0 FROM folder
|
|
141
|
+
WHERE folder.organizationId = ? -- ? = ctx.activeOrgId
|
|
142
|
+
UNION ALL
|
|
143
|
+
-- step: walk parent → child, RE-constraining tenancy on every walked row
|
|
144
|
+
SELECT folder.id, c.depth + 1
|
|
145
|
+
FROM folder JOIN __arrow_closure c ON folder.parentId = c.id
|
|
146
|
+
WHERE c.depth < 8 AND folder.organizationId = ?
|
|
147
|
+
)
|
|
148
|
+
SELECT id FROM __arrow_closure
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Both D1 (SQLite) and Neon (Postgres) speak `WITH RECURSIVE`, so the same
|
|
152
|
+
arrow is valid on either provider. Drizzle interpolates the column/table
|
|
153
|
+
**objects** (dialect-correct identifiers) and binds the claim as a
|
|
154
|
+
**parameter** — never string-concatenated, so an arrow is never an injection
|
|
155
|
+
surface (the FK column and tables are compile-time identifiers; the only
|
|
156
|
+
runtime value is the signed org claim).
|
|
157
|
+
|
|
158
|
+
## Tenant isolation semantics
|
|
159
|
+
|
|
160
|
+
Arrows are tenant-safe by construction. Three guarantees, all enforced at
|
|
161
|
+
the SQL level:
|
|
162
|
+
|
|
163
|
+
- **The seed is tenant-constrained.** The CTE root (and the non-recursive
|
|
164
|
+
hop's `WHERE`) binds the tenant column to `ctx.activeOrgId`. A caller only
|
|
165
|
+
ever seeds the closure with rows in their own org.
|
|
166
|
+
- **The recursive arm re-constrains tenancy on *every* walked row** — not
|
|
167
|
+
just the seed. The step is `JOIN __arrow_closure c ON folder.parentId = c.id`
|
|
168
|
+
**`AND folder.organizationId = ctx.activeOrgId`**. A row that was reparented
|
|
169
|
+
under an in-tenant parent but whose **own** org differs is excluded. This is
|
|
170
|
+
defense-in-depth: cross-org inheritance must never happen, and the SQL
|
|
171
|
+
enforces it regardless of what the write path allows. Strict per-row
|
|
172
|
+
tenancy is the correct default for an org-membership arrow.
|
|
173
|
+
- **A missing claim fails closed.** When `ctx.activeOrgId` is null (anonymous
|
|
174
|
+
or cross-tenant caller), the subquery short-circuits to `sql\`1 = 0\`` —
|
|
175
|
+
a deny, never an unconstrained read and never an `undefined` bind.
|
|
176
|
+
|
|
177
|
+
## Bounded recursion
|
|
178
|
+
|
|
179
|
+
Recursion is **always** finite. The recursive arm's `WHERE c.depth < maxDepth`
|
|
180
|
+
caps the walk so a deep or cyclic hierarchy can never run away. The bound is
|
|
181
|
+
resolved with this precedence:
|
|
182
|
+
|
|
183
|
+
1. Per-permission override — `authz.permissionMaxDepth['<perm>']`.
|
|
184
|
+
2. Per-arrow `maxDepth`.
|
|
185
|
+
3. The global default, **8**.
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
authz: {
|
|
189
|
+
arrows: {
|
|
190
|
+
sectionTree: { from: 'sections', fk: 'parentId', to: 'sections', recursive: true, maxDepth: 6 },
|
|
191
|
+
},
|
|
192
|
+
permissions: {
|
|
193
|
+
'section:inTree': { anyOf: [{ arrowRef: 'sectionTree', permission: 'org:admin' }] },
|
|
194
|
+
},
|
|
195
|
+
// optional: raise the bound for one permission without touching the arrow
|
|
196
|
+
permissionMaxDepth: { 'section:inTree': 16 },
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
An author who **explicitly opts out** of the bound — `unbounded: true` —
|
|
201
|
+
with no token-closure path is a **compile error**: there is no safe finite
|
|
202
|
+
SQL for unbounded recursion, so the compiler refuses to emit a
|
|
203
|
+
non-terminating CTE. The fix is to set a `maxDepth`. Quickback never silently
|
|
204
|
+
allows an unbounded traversal.
|
|
205
|
+
|
|
206
|
+
## Worked example — q-events
|
|
207
|
+
|
|
208
|
+
The `q-events` example ships both shapes.
|
|
209
|
+
|
|
210
|
+
A **recursive** self-FK on the `sections` feature. `sections.parentId`
|
|
211
|
+
points back at `sections`; access to an ancestor section confers access to
|
|
212
|
+
all descendants:
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
// quickback.config.ts
|
|
216
|
+
authz: {
|
|
217
|
+
arrows: {
|
|
218
|
+
sectionTree: { from: 'sections', fk: 'parentId', to: 'sections', recursive: true, maxDepth: 6 },
|
|
219
|
+
},
|
|
220
|
+
permissions: {
|
|
221
|
+
'org:admin': { anyOf: [{ role: 'admin' }, { role: 'owner' }] },
|
|
222
|
+
'section:inTree': { anyOf: [{ arrowRef: 'sectionTree', permission: 'org:admin' }] },
|
|
223
|
+
},
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
// features/sections/sections.ts — the permission arm rides alongside the org scope
|
|
227
|
+
firewall: {
|
|
228
|
+
all: [
|
|
229
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
230
|
+
{ field: 'id', permission: 'section:inTree' }, // emits the tenant-gated WITH RECURSIVE CTE
|
|
231
|
+
{ field: 'deletedAt', isNull: true },
|
|
232
|
+
],
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
The org `equals` arm and the recursive arrow's per-row tenant re-constraint
|
|
237
|
+
are belt-and-suspenders — both pin the closure to the caller's org. The arrow
|
|
238
|
+
adds the *ancestor-authority* dimension on top of the flat org scope.
|
|
239
|
+
|
|
240
|
+
## Reference
|
|
241
|
+
|
|
242
|
+
```typescript
|
|
243
|
+
// authz.arrows.<name>
|
|
244
|
+
interface ArrowDefinition {
|
|
245
|
+
from: string; // source table the FK lives on
|
|
246
|
+
fk: string; // FK column (non-recursive: the tenant column; recursive: the parent pointer)
|
|
247
|
+
to: string; // target table the FK resolves to (self-hop: from === to)
|
|
248
|
+
recursive?: boolean; // force the recursive-CTE lowering (auto when from === to)
|
|
249
|
+
maxDepth?: number; // per-arrow recursion bound (default 8)
|
|
250
|
+
tenantColumn?: string; // recursive-seed tenant column override (default 'organizationId')
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// referenced from a permission as a leaf:
|
|
254
|
+
{ arrowRef: '<arrowName>', permission: '<permissionAtTarget>' }
|
|
255
|
+
|
|
256
|
+
// per-permission depth override (overrides per-arrow maxDepth + the global 8):
|
|
257
|
+
authz.permissionMaxDepth?: Record<string, number>
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- Every `{ arrowRef }` in a permission must name a declared `authz.arrows[*]`
|
|
261
|
+
entry, and the arrow's `fk` / `to` are checked against the real schema at
|
|
262
|
+
compile time.
|
|
263
|
+
- The target `permission` must reduce to org-membership roles in M2.
|
|
264
|
+
- See [Permissions](/compiler/definitions/permissions) for the expression DSL
|
|
265
|
+
the arrow leaf lives in, and [Firewall — named permissions](/compiler/definitions/firewall#named-permissions-permission)
|
|
266
|
+
for how the resulting `{ permission }` arm sits inside a firewall. The
|
|
267
|
+
compile-time analyzer reports the subquery / CTE depth of every arrow-bearing
|
|
268
|
+
permission — see [Diagnostics](/compiler/definitions/diagnostics).
|
|
269
|
+
```
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Diagnostics
|
|
2
|
+
|
|
3
|
+
Quickback compiles your authorization model into a single normalized **policy
|
|
4
|
+
IR** — relations, permissions, arrows, scopes, grants, and per-resource
|
|
5
|
+
firewalls — and then runs a set of static checks over it. The analyzer never
|
|
6
|
+
changes what's emitted; it reports problems it can prove from the policy
|
|
7
|
+
graph: a permission that can never be satisfied, a scoped role no grant
|
|
8
|
+
reaches, a resource that hands a scope role more than its profile allows, a
|
|
9
|
+
negation that can silently pass.
|
|
10
|
+
|
|
11
|
+
## The console channel
|
|
12
|
+
|
|
13
|
+
Diagnostics render to the existing `[quickback:authz]` / `[quickback:authn]`
|
|
14
|
+
console channel — the same prefix the compiler has always used for security
|
|
15
|
+
warnings, so any CI grep you already key on keeps working. Each line carries
|
|
16
|
+
a stable, greppable **code**:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
[quickback:authz] AUTHZ_EMPTY_PERMISSION: permission "event:locked" can never be satisfied — it requires organizerOf AND its negation simultaneously.
|
|
20
|
+
at resource=sessions authz.permissions["event:locked"]
|
|
21
|
+
hint: Remove the contradictory arm, or split into separate permissions.
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The first line stays greppable (`[quickback:<channel>] CODE: message`); the
|
|
25
|
+
source location and fix hint render on continuation lines.
|
|
26
|
+
|
|
27
|
+
## Warn by default, opt-in strict
|
|
28
|
+
|
|
29
|
+
The analyzer is **warn-by-default, compile-continues**. This is deliberate:
|
|
30
|
+
the analyzer runs on the shared compiler that serves every project, so a new
|
|
31
|
+
check must never break an existing build on upgrade. In the default path
|
|
32
|
+
every diagnostic — *including* the one check authored at `error` severity
|
|
33
|
+
(the capability ceiling) — is rendered as a warning line and the compile
|
|
34
|
+
proceeds.
|
|
35
|
+
|
|
36
|
+
Set **`QUICKBACK_AUTHZ_STRICT=true`** to promote every `warn` to `error`.
|
|
37
|
+
Under strict mode the compile **fails** (throws an aggregate error listing the
|
|
38
|
+
codes) if any diagnostic is — after promotion — an error. `info` lines
|
|
39
|
+
(the pushdown-cost report) stay informational and never fail a build.
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
# warn-only (default): prints diagnostics, compile succeeds
|
|
43
|
+
quickback compile
|
|
44
|
+
|
|
45
|
+
# strict: any warn or error fails the compile
|
|
46
|
+
QUICKBACK_AUTHZ_STRICT=true quickback compile
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
> The analyzer is compile-time only — zero runtime blast radius. A defect in
|
|
50
|
+
> the analyzer itself is caught and downgraded to a single warning in the
|
|
51
|
+
> default path, so an analyzer bug can never take down an otherwise-valid
|
|
52
|
+
> compile. (Strict mode re-raises, because there the throw is the intended
|
|
53
|
+
> hard failure.)
|
|
54
|
+
|
|
55
|
+
## Authz codes
|
|
56
|
+
|
|
57
|
+
These read the permission graph projected from the policy IR. All are `warn`
|
|
58
|
+
severity (so `info` for the pushdown report) **except** the capability ceiling,
|
|
59
|
+
which is authored as `error`.
|
|
60
|
+
|
|
61
|
+
| Code | Severity | What it catches |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `AUTHZ_EMPTY_PERMISSION` | warn | A permission that can never be satisfied — e.g. `allOf(a, not(a))`, which requires a fact and its negation at the same AND-level. |
|
|
64
|
+
| `AUTHZ_SHADOWED_ARM` | warn | An `anyOf` arm subsumed by a broader arm: a leaf `X` and an `allOf(X, …)` in the same union — the narrower arm can never widen the result. |
|
|
65
|
+
| `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel, so it's dead config. |
|
|
66
|
+
| `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. |
|
|
67
|
+
| `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth (from recursive arrows). Advisory, never fails a build. |
|
|
68
|
+
| `AUTHZ_CAPABILITY_CEILING` | **error** | A resource's firewall grants a `scope:<kind>:<role>` role read access **beyond its capability profile** — either the role has no profile at all, or the profile doesn't list this resource. |
|
|
69
|
+
| `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The analyzer resolves the operand's site from its leaves, so it fires even when the lowering left the site unset. |
|
|
70
|
+
|
|
71
|
+
A few codes are reserved in the diagnostic enum for the milestones that emit
|
|
72
|
+
them and don't fire on a shipped config today: `AUTHZ_UNBOUNDED_RECURSION`
|
|
73
|
+
(an unbounded recursive arrow with no claim path — currently a hard compile
|
|
74
|
+
error raised at config validation, before the analyzer runs),
|
|
75
|
+
`AUTHZ_UNENFORCEABLE_FACT`, and `AUTHZ_CAVEAT_SITE_MISMATCH` (M3 caveats).
|
|
76
|
+
|
|
77
|
+
### The capability ceiling
|
|
78
|
+
|
|
79
|
+
The one `error`-severity authz check. It is the M0.2 deliverable that backs
|
|
80
|
+
[scope grant profiles](/compiler/definitions/scopes): a scoped role is
|
|
81
|
+
deny-by-default and may touch only what its `grants` profile lists. The
|
|
82
|
+
analyzer walks every resource firewall, follows each `{ permission }` arm
|
|
83
|
+
into the permission graph to find the scope roles it references, and fails the
|
|
84
|
+
build (in strict mode) if a resource grants a scope role access the profile
|
|
85
|
+
doesn't cover. In the default path it warns loudly. This is what makes the
|
|
86
|
+
grant profile the single auditable manifest of what an external principal can
|
|
87
|
+
see.
|
|
88
|
+
|
|
89
|
+
## Authn codes
|
|
90
|
+
|
|
91
|
+
Four **structural authentication** checks — proving properties over the
|
|
92
|
+
generated route + credential surface rather than the authz policy:
|
|
93
|
+
|
|
94
|
+
| Code | Severity | What it catches |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| `AUTHN_ROUTE_COVERAGE` | warn | A route that reaches data with an **unclassified** auth gate and isn't declared `PUBLIC` — the signup / flag-gap bug class (data delivered to an unauthenticated ctx). |
|
|
97
|
+
| `AUTHN_SECRET_CONSISTENCY` | error | A credential's mint site and verify site don't share key / issuer / audience — every minted token would fail verification (the ws-ticket "401 on every upgrade" trap). |
|
|
98
|
+
| `AUTHN_CREDENTIAL_DELIVERY` | error | A fire-and-forget credential send (the OTP-email shape) not anchored to `waitUntil` / `await` — the Worker may drop the promise and never deliver (the OTP-500 bug class). |
|
|
99
|
+
| `AUTHN_CLAIM_PROVENANCE` | error | An identity `ctx` field written from **request input** rather than a credential verifier — client-asserted identity, which is forbidden. |
|
|
100
|
+
| `AUTHN_SURFACE_INVARIANT` | warn / error | A surface contract breach: an `/mcp` or agent route not gated bearer-only (warn), or an `INTERNAL`-gated route mounted on an HTTP-reachable surface (error). |
|
|
101
|
+
|
|
102
|
+
These check definitions are **wired and fully unit-tested**, but their inputs
|
|
103
|
+
— the per-route and per-credential metadata (`RouteNode` / `MintSite` /
|
|
104
|
+
`VerifySite` / `ClaimWrite`) — are not yet emitted by the route, middleware,
|
|
105
|
+
and credential generators. Until those generators emit that metadata the
|
|
106
|
+
analyzer runs the authn checks against **empty** route/credential graphs, so
|
|
107
|
+
they are effectively no-ops on a real compile. The check logic needs no change
|
|
108
|
+
when the metadata lands — the route/credential coverage activates the moment
|
|
109
|
+
the generators emit it. The authz / permission-graph checks above run
|
|
110
|
+
unconditionally today, because the policy IR is always present.
|
|
111
|
+
|
|
112
|
+
## Reading the pushdown-cost report
|
|
113
|
+
|
|
114
|
+
`AUTHZ_PUSHDOWN_COST` is an `info` line per permission that pushes down to
|
|
115
|
+
SQL — it never fails a build, but it surfaces the query cost of an
|
|
116
|
+
authorization rule before you ship it:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
[quickback:authz] AUTHZ_PUSHDOWN_COST: permission "section:inTree" lowers to 1 SQL subquery, recursive CTE depth 6 (sites: resource).
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
A high subquery count or a deep recursive CTE (from a recursive
|
|
123
|
+
[arrow](/compiler/definitions/arrows)) is a signal to reconsider the rule —
|
|
124
|
+
not an error, but worth a look.
|
|
125
|
+
|
|
126
|
+
## See also
|
|
127
|
+
|
|
128
|
+
- [Permissions](/compiler/definitions/permissions) — the `anyOf` / `allOf` /
|
|
129
|
+
`not` DSL the empty / shadowed / not-over-resource checks analyze.
|
|
130
|
+
- [Arrows](/compiler/definitions/arrows) — recursive-CTE depth feeds the
|
|
131
|
+
pushdown-cost report; the unbounded-recursion guard is a hard error.
|
|
132
|
+
- [Scopes & capability grants](/compiler/definitions/scopes) — the grant
|
|
133
|
+
profiles the capability-ceiling check enforces.
|
|
134
|
+
- [Firewall](/compiler/definitions/firewall) — the `{ permission }` arms the
|
|
135
|
+
ceiling check follows into the permission graph.
|
|
136
|
+
```
|
|
@@ -117,9 +117,9 @@ Custom action handlers need to run queries against the database. Quickback's com
|
|
|
117
117
|
|
|
118
118
|
```ts title="quickback/features/mail/handlers/inbound.ts"
|
|
119
119
|
import { q } from "../../../lib/q";
|
|
120
|
-
import mailboxes from "../mailboxes";
|
|
121
|
-
import messages from "../messages";
|
|
122
|
-
import threads from "../threads";
|
|
120
|
+
import { mailboxes } from "../mailboxes";
|
|
121
|
+
import { messages } from "../messages";
|
|
122
|
+
import { threads } from "../threads";
|
|
123
123
|
|
|
124
124
|
export const execute = async ({ unsafeDb, input }) => {
|
|
125
125
|
// Find the mailbox this email was addressed to
|