@quickback-dev/cli 0.13.0 → 0.14.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/docs/content.js +11 -11
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/docs/changelog.md +192 -1
- package/dist/skill/docs/compiler/definitions/access.md +164 -2
- package/dist/skill/docs/compiler/definitions/actions.md +145 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +46 -0
- package/dist/skill/docs/compiler/definitions/index.md +2 -0
- package/dist/skill/docs/compiler/definitions/masking.md +11 -0
- package/dist/skill/docs/compiler/definitions/read.md +8 -7
- package/dist/skill/docs/compiler/definitions/views.md +100 -12
- package/dist/skill/docs/compiler/getting-started/full-example.md +12 -11
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +8 -13
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +192 -1
- package/src/skill/docs/compiler/definitions/access.md +164 -2
- package/src/skill/docs/compiler/definitions/actions.md +145 -0
- package/src/skill/docs/compiler/definitions/firewall.md +46 -0
- package/src/skill/docs/compiler/definitions/index.md +2 -0
- package/src/skill/docs/compiler/definitions/masking.md +11 -0
- package/src/skill/docs/compiler/definitions/read.md +8 -7
- package/src/skill/docs/compiler/definitions/views.md +100 -12
- package/src/skill/docs/compiler/getting-started/full-example.md +12 -11
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +8 -13
|
@@ -64,6 +64,7 @@ type FirewallPredicate =
|
|
|
64
64
|
| { field: string; equals: string } // column = ctx.* (or literal)
|
|
65
65
|
| { field: string; isNull: true } // column IS NULL
|
|
66
66
|
| { field: string; in: string[] | string }// column IN (...)
|
|
67
|
+
| { field: string; via: string } // column IN (relationship subquery)
|
|
67
68
|
| { exception: true }; // opt out of tenant scoping
|
|
68
69
|
|
|
69
70
|
type FirewallConfig = ReadonlyArray<FirewallPredicate>;
|
|
@@ -74,6 +75,51 @@ firewallErrorMode?: 'reveal' | 'hide';
|
|
|
74
75
|
|
|
75
76
|
Predicates are AND'd together. `firewallErrorMode` lives at the resource top level — it's a presentation-layer choice (403 vs 404), not a query-shape one.
|
|
76
77
|
|
|
78
|
+
## Relationship-based scoping (`via:`)
|
|
79
|
+
|
|
80
|
+
For relationship authorization — "this user can see rows X if they have a confirmed `event_guests` row pointing at X" — declare the relationship under `authz.relationships` in `quickback.config.ts`, then reference it from `firewall:` with a `via:` predicate:
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
// quickback.config.ts
|
|
84
|
+
authz: {
|
|
85
|
+
relationships: {
|
|
86
|
+
guestOf: {
|
|
87
|
+
from: 'event_guests', // table name
|
|
88
|
+
subject: { column: 'userId', equals: 'ctx.userId' }, // caller side
|
|
89
|
+
resource: { column: 'eventId' }, // resource side
|
|
90
|
+
where: { status: 'confirmed' }, // optional row filter
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
// features/sessions/sessions.ts
|
|
96
|
+
firewall: [
|
|
97
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
98
|
+
{ field: 'eventId', via: 'guestOf' },
|
|
99
|
+
]
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Compiles to:
|
|
103
|
+
|
|
104
|
+
```sql
|
|
105
|
+
WHERE sessions.organizationId = ?
|
|
106
|
+
AND sessions.eventId IN (
|
|
107
|
+
SELECT eventId FROM event_guests
|
|
108
|
+
WHERE userId = ?
|
|
109
|
+
AND status = 'confirmed'
|
|
110
|
+
AND <event_guests' own firewall — tenant scope + soft-delete>
|
|
111
|
+
)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Key properties:
|
|
115
|
+
|
|
116
|
+
- **Firewall stays the outermost AND.** A guest of an event in another tenant is still blocked by your tenant predicate. Relationship-based scoping never bypasses tenant isolation.
|
|
117
|
+
- **The relationship table's own firewall is AND'd into the subquery.** Soft-deleting a `event_guests` row revokes access immediately; cross-tenant relationship rows can't grant access.
|
|
118
|
+
- **Anonymous callers fail closed.** `ctx.userId` is null-guarded; the subquery short-circuits to `WHERE 1 = 0` for unauthenticated requests.
|
|
119
|
+
- **The relationship table must be tenant-scoped** (`firewall: { exception: true }` is rejected at compile time on relationship tables).
|
|
120
|
+
|
|
121
|
+
See [Access — relationships](/compiler/definitions/access#authz-relationships) for the full `authz.relationships` shape and role-binding patterns.
|
|
122
|
+
|
|
77
123
|
## Context Sources
|
|
78
124
|
|
|
79
125
|
When `equals` references the request context, use these standard sources:
|
|
@@ -110,6 +110,8 @@ The firewall controls **which records** a user can see. It automatically adds WH
|
|
|
110
110
|
|
|
111
111
|
No manual configuration needed - Quickback applies smart rules based on your schema.
|
|
112
112
|
|
|
113
|
+
For relationship-based row visibility (e.g. "user can see this event because they have a confirmed `event_guests` row pointing at it"), declare the relationship under `authz.relationships` and reference it from the firewall with a `via:` predicate. See [Firewall → Relationship-based scoping](/compiler/definitions/firewall#relationship-based-scoping-via).
|
|
114
|
+
|
|
113
115
|
[Learn more about Firewall →](/compiler/definitions/firewall)
|
|
114
116
|
|
|
115
117
|
### 2. Access (CRUD Permissions)
|
|
@@ -139,6 +139,17 @@ show: {
|
|
|
139
139
|
|
|
140
140
|
The `'owner'` condition compares against the owner column declared via `q.scope('owner')` (or auto-detected from a `userId` / `ownerId` column). If no owner scope is present, it falls back to `createdBy`.
|
|
141
141
|
|
|
142
|
+
### Relationship-roles in masking (v1 limitation)
|
|
143
|
+
|
|
144
|
+
Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in `show:` clauses**. The compiler refuses to build with a clear error message because async, db-aware mask functions plus a batched relationship matcher (to avoid N+1 on list responses) are required to ship safely — that pipeline has not yet landed. The runtime evaluator fails closed on unrecognized arms, so silent grants are impossible.
|
|
145
|
+
|
|
146
|
+
**Workarounds**, depending on intent:
|
|
147
|
+
|
|
148
|
+
- **Gate on BA roles only**: keep masking simple and put the relationship check at the access layer instead — `read.views.<v>.access: { roles: ['guest'] }` returns a curated field projection that excludes the sensitive column entirely for non-staff callers, without involving masking.
|
|
149
|
+
- **Move the field into a view that's gated by the relationship-role at access**: same pattern — column-level security via field projection rather than per-row masking.
|
|
150
|
+
|
|
151
|
+
A future async-mask pipeline with batched lookups will lift this limitation; the schema slot is reserved so the v2 add will be non-breaking.
|
|
152
|
+
|
|
142
153
|
## Query Gate (filter / sort / search)
|
|
143
154
|
|
|
144
155
|
Masking has a second concern beyond hiding values in the response: a non-admin caller could enumerate masked PII via the query string — e.g. `?filter=email:like:%@target.com` — and infer presence even when the response payload is redacted. The `query` allowlist closes this:
|
|
@@ -53,8 +53,7 @@ export default defineTable(customers, {
|
|
|
53
53
|
|----------|------|
|
|
54
54
|
| `GET /api/v1/{resource}` | `read.access` |
|
|
55
55
|
| `GET /api/v1/{resource}/:id` | `read.access` |
|
|
56
|
-
| `GET /api/v1/{resource}
|
|
57
|
-
| `GET /api/v1/{resource}/views/{name}` | Same — explicit path form of the `?view=` dispatch |
|
|
56
|
+
| `GET /api/v1/{resource}/views/{name}` | `read.views[name].access` (falls back to `read.access`) |
|
|
58
57
|
|
|
59
58
|
Single-record `GET /:id` inherits `read.access` automatically — there's no
|
|
60
59
|
separate `read.get` block. If you need different access for single records,
|
|
@@ -145,10 +144,10 @@ read: {
|
|
|
145
144
|
}
|
|
146
145
|
```
|
|
147
146
|
|
|
148
|
-
|
|
147
|
+
Named views are emitted at dedicated path routes:
|
|
149
148
|
|
|
150
|
-
-
|
|
151
|
-
-
|
|
149
|
+
- `GET /api/v1/jobs/views/internal`
|
|
150
|
+
- If `read.defaultView` is set, bare `GET /api/v1/jobs` resolves to that view.
|
|
152
151
|
|
|
153
152
|
## Migrating from `crud.list` / `crud.get`
|
|
154
153
|
|
|
@@ -161,7 +160,7 @@ DSL v2 rejects both at compile time. The migration is mechanical:
|
|
|
161
160
|
| `crud.list.maxPageSize` | `read.maxPageSize` |
|
|
162
161
|
| `crud.list.fields: [...]` | Move to a named view under `read.views` |
|
|
163
162
|
| `crud.get.access` | `read.access` (or record-level conditions) |
|
|
164
|
-
| `crud.get.fields: [...]` | Move to a named view; clients call
|
|
163
|
+
| `crud.get.fields: [...]` | Move to a named view; clients call `/views/{name}` |
|
|
165
164
|
| Top-level `views: {...}` | `read.views: {...}` |
|
|
166
165
|
|
|
167
166
|
Example before/after:
|
|
@@ -197,7 +196,9 @@ crud: {
|
|
|
197
196
|
```
|
|
198
197
|
|
|
199
198
|
Clients that previously hit `GET /:id` to retrieve only summary fields now
|
|
200
|
-
|
|
199
|
+
move that projection to a named collection view such as
|
|
200
|
+
`GET /api/v1/jobs/views/summary`. Single-record `GET /:id` always returns the
|
|
201
|
+
full masked record.
|
|
201
202
|
|
|
202
203
|
## Read-Only Resources
|
|
203
204
|
|
|
@@ -75,20 +75,18 @@ export default defineTable(candidates, {
|
|
|
75
75
|
|
|
76
76
|
## Generated Endpoints
|
|
77
77
|
|
|
78
|
-
Each view generates
|
|
78
|
+
Each named view generates a dedicated GET endpoint:
|
|
79
79
|
|
|
80
80
|
```
|
|
81
81
|
GET /api/v1/candidates # Full read - read.access fields
|
|
82
|
-
GET /api/v1/candidates
|
|
83
|
-
GET /api/v1/candidates/views/
|
|
84
|
-
GET /api/v1/candidates?view=full # hiring-manager/recruiter only
|
|
82
|
+
GET /api/v1/candidates/views/pipeline # interviewer/recruiter/etc.
|
|
83
|
+
GET /api/v1/candidates/views/full # hiring-manager/recruiter only
|
|
85
84
|
GET /api/v1/candidates/views/report # report fields
|
|
86
85
|
```
|
|
87
86
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
projection.
|
|
87
|
+
If `read.defaultView` is set, bare `GET /api/v1/candidates` can also resolve
|
|
88
|
+
to that named view. Without `defaultView`, bare `GET /api/v1/candidates`
|
|
89
|
+
returns `VIEW_REQUIRED` once views are declared.
|
|
92
90
|
|
|
93
91
|
## Query Parameters
|
|
94
92
|
|
|
@@ -227,6 +225,93 @@ read: {
|
|
|
227
225
|
| `/views/full` | interviewer | Yes | `j***@c******.com` |
|
|
228
226
|
| `/views/full` | recruiter | Yes | `jane@company.com` |
|
|
229
227
|
|
|
228
|
+
## Aggregations
|
|
229
|
+
|
|
230
|
+
Views can declare pre-computed aggregations that run alongside the row
|
|
231
|
+
query and surface as `aggregations: { ... }` on the response. This avoids a
|
|
232
|
+
custom standalone action for every "count of X grouped by Y" dashboard
|
|
233
|
+
tile — the firewall and view filters already in place drive the metric.
|
|
234
|
+
|
|
235
|
+
```typescript
|
|
236
|
+
read: {
|
|
237
|
+
access: { roles: ['owner', 'admin', 'member'] },
|
|
238
|
+
views: {
|
|
239
|
+
pipeline: {
|
|
240
|
+
fields: ['id', 'jobId', 'candidateId', 'status', 'appliedAt'],
|
|
241
|
+
aggregations: {
|
|
242
|
+
totalApplications: { fn: 'count' },
|
|
243
|
+
byStatus: { fn: 'groupBy', field: 'status' },
|
|
244
|
+
},
|
|
245
|
+
},
|
|
246
|
+
},
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Response now carries the aggregations alongside `data`:
|
|
251
|
+
|
|
252
|
+
```json
|
|
253
|
+
{
|
|
254
|
+
"data": [/* paginated rows */],
|
|
255
|
+
"view": "pipeline",
|
|
256
|
+
"pagination": { "count": 50, "page": 1, "pageSize": 50, "hasMore": true },
|
|
257
|
+
"aggregations": {
|
|
258
|
+
"totalApplications": 173,
|
|
259
|
+
"byStatus": {
|
|
260
|
+
"applied": 102,
|
|
261
|
+
"screening": 41,
|
|
262
|
+
"interview": 18,
|
|
263
|
+
"offer": 7,
|
|
264
|
+
"rejected": 5
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### Supported aggregation functions
|
|
271
|
+
|
|
272
|
+
| `fn` | `field` | Returns | Example |
|
|
273
|
+
|---|---|---|---|
|
|
274
|
+
| `sum` | required, numeric | scalar number | `{ fn: 'sum', field: 'guestCount' }` |
|
|
275
|
+
| `avg` | required, numeric | scalar number | `{ fn: 'avg', field: 'salary' }` |
|
|
276
|
+
| `min` | required | scalar number | `{ fn: 'min', field: 'price' }` |
|
|
277
|
+
| `max` | required | scalar number | `{ fn: 'max', field: 'price' }` |
|
|
278
|
+
| `count` | optional | `COUNT(*)` if omitted, `COUNT(field)` (non-null) if given | `{ fn: 'count' }` |
|
|
279
|
+
| `count_distinct` | required | scalar number | `{ fn: 'count_distinct', field: 'sourceId' }` |
|
|
280
|
+
| `groupBy` | required | `{ value: count }` map | `{ fn: 'groupBy', field: 'status' }` |
|
|
281
|
+
|
|
282
|
+
`groupBy` always returns a count map keyed by the distinct values of `field`.
|
|
283
|
+
`NULL` values bucket under the literal string `"(none)"`. Other rollup
|
|
284
|
+
functions (`groupBy` + `sum` of another column) are deferred to a future
|
|
285
|
+
release.
|
|
286
|
+
|
|
287
|
+
### Filter and firewall inheritance
|
|
288
|
+
|
|
289
|
+
Aggregations always run over the **same** filtered, firewalled set as the
|
|
290
|
+
row query. Pagination is intentionally ignored — you get the value over
|
|
291
|
+
every matching record, not just the current page.
|
|
292
|
+
|
|
293
|
+
In practice: a request like
|
|
294
|
+
`GET /applications/views/pipeline?status=applied&jobId=job_123&limit=10`
|
|
295
|
+
returns the first 10 applied rows for that job, AND `byStatus` reflects
|
|
296
|
+
only that filtered set (which will be `{ applied: <total> }` since the
|
|
297
|
+
filter pinned the status). This is the only consistent default — divorcing
|
|
298
|
+
the metric from the user's filters would surprise.
|
|
299
|
+
|
|
300
|
+
### Constraints (compile-time)
|
|
301
|
+
|
|
302
|
+
- `field` must reference a real column on the table.
|
|
303
|
+
- `sum`/`avg` require numeric column types (`int`, `real`, `decimal`,
|
|
304
|
+
`numeric`, `bigint`). Non-numeric columns are rejected at compile time.
|
|
305
|
+
- The same masking opt-out gate that governs `query.{filterable, sortable,
|
|
306
|
+
searchable}` applies to aggregations: the view's roles must satisfy the
|
|
307
|
+
masking rule, otherwise the aggregation is rejected. (A `sum(salary)`
|
|
308
|
+
leaks structure across the masked set even when the row payload is
|
|
309
|
+
redacted.)
|
|
310
|
+
- Aggregation names cannot collide with the reserved response fields
|
|
311
|
+
`data`, `pagination`, `view`.
|
|
312
|
+
- No raw SQL `expr:` form. Column references only — declare a generated
|
|
313
|
+
column or write a custom action if you need arithmetic.
|
|
314
|
+
|
|
230
315
|
## Response Format
|
|
231
316
|
|
|
232
317
|
View responses include metadata about the view:
|
|
@@ -238,15 +323,18 @@ View responses include metadata about the view:
|
|
|
238
323
|
{ "id": "cnd_456", "name": "John Smith", "source": "referral" }
|
|
239
324
|
],
|
|
240
325
|
"view": "pipeline",
|
|
241
|
-
"fields": ["id", "name", "source"],
|
|
242
326
|
"pagination": {
|
|
243
|
-
"
|
|
244
|
-
"
|
|
245
|
-
"
|
|
327
|
+
"count": 2,
|
|
328
|
+
"page": 1,
|
|
329
|
+
"pageSize": 50,
|
|
330
|
+
"hasMore": false
|
|
246
331
|
}
|
|
247
332
|
}
|
|
248
333
|
```
|
|
249
334
|
|
|
335
|
+
When the view declares `aggregations`, the response also includes an
|
|
336
|
+
`aggregations: { ... }` field. See [Aggregations](#aggregations).
|
|
337
|
+
|
|
250
338
|
## Complete Example
|
|
251
339
|
|
|
252
340
|
```typescript
|
|
@@ -253,16 +253,17 @@ import { AuthErrors, AccessErrors, GuardErrors } from '../../lib/errors';
|
|
|
253
253
|
|
|
254
254
|
const app = new Hono();
|
|
255
255
|
|
|
256
|
-
// GET /candidates
|
|
256
|
+
// GET /candidates/views/:viewName — named view projection
|
|
257
257
|
const READ_ACCESS = { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] };
|
|
258
258
|
|
|
259
|
-
app.get('/', async (c) => {
|
|
259
|
+
app.get('/views/:viewName', async (c) => {
|
|
260
260
|
const ctx = c.get('ctx');
|
|
261
261
|
const db = c.get('db');
|
|
262
262
|
|
|
263
|
+
const viewName = c.req.param('viewName');
|
|
263
264
|
const params = Object.fromEntries(new URL(c.req.url).searchParams);
|
|
264
|
-
const view = VIEWS_CONFIG[
|
|
265
|
-
if (!view) return c.json({ error: '
|
|
265
|
+
const view = VIEWS_CONFIG[viewName as keyof typeof VIEWS_CONFIG];
|
|
266
|
+
if (!view) return c.json({ error: 'Unknown view', code: 'VIEW_NOT_FOUND' }, 400);
|
|
266
267
|
|
|
267
268
|
// Per-view access gate (falls back to read-level access)
|
|
268
269
|
if (!await evaluateAccess(view.access ?? READ_ACCESS, ctx)) {
|
|
@@ -273,7 +274,7 @@ app.get('/', async (c) => {
|
|
|
273
274
|
const results = await db.select(/* projected fields */).from(candidates)
|
|
274
275
|
.where(buildFirewallConditions(ctx));
|
|
275
276
|
|
|
276
|
-
return c.json({ data: maskCandidates(results, ctx), view:
|
|
277
|
+
return c.json({ data: maskCandidates(results, ctx), view: viewName });
|
|
277
278
|
});
|
|
278
279
|
|
|
279
280
|
// POST /candidates - Create with guards
|
|
@@ -383,10 +384,10 @@ Views control **which fields are returned**. Masking controls **what values are
|
|
|
383
384
|
|
|
384
385
|
| Endpoint | Role | `phone` in response? | `phone` value |
|
|
385
386
|
|----------|------|--------------------|-------------|
|
|
386
|
-
| `/candidates
|
|
387
|
-
| `/candidates
|
|
388
|
-
| `/candidates
|
|
389
|
-
| `/candidates
|
|
387
|
+
| `/candidates/views/pipeline` | interviewer | No | N/A |
|
|
388
|
+
| `/candidates/views/pipeline` | recruiter | No | N/A |
|
|
389
|
+
| `/candidates/views/full` | interviewer | No | N/A (no access) |
|
|
390
|
+
| `/candidates/views/full` | recruiter | Yes | `555-123-4567` |
|
|
390
391
|
|
|
391
392
|
### Guards Enforcement
|
|
392
393
|
|
|
@@ -417,8 +418,8 @@ POST /candidates
|
|
|
417
418
|
| `POST` | `/candidates` | hiring-manager, recruiter |
|
|
418
419
|
| `PATCH` | `/candidates/:id` | hiring-manager, recruiter |
|
|
419
420
|
| `DELETE` | `/candidates/:id` | hiring-manager |
|
|
420
|
-
| `GET` | `/candidates
|
|
421
|
-
| `GET` | `/candidates
|
|
421
|
+
| `GET` | `/candidates/views/pipeline` | owner, hiring-manager, recruiter, interviewer |
|
|
422
|
+
| `GET` | `/candidates/views/full` | hiring-manager, recruiter |
|
|
422
423
|
|
|
423
424
|
---
|
|
424
425
|
|
|
@@ -75,8 +75,7 @@ Calls a client makes:
|
|
|
75
75
|
```bash
|
|
76
76
|
GET /jobs # Collection — gated by read.access
|
|
77
77
|
GET /jobs/:id # Single — gated by read.access (with ID-probe defense)
|
|
78
|
-
GET /jobs
|
|
79
|
-
GET /jobs/views/summary # Explicit view path
|
|
78
|
+
GET /jobs/views/summary # Named view projection
|
|
80
79
|
```
|
|
81
80
|
|
|
82
81
|
### ID-probe defense on `/:id`
|
|
@@ -4,14 +4,14 @@ Views provide named column projections that limit which fields are returned in A
|
|
|
4
4
|
|
|
5
5
|
## Endpoints
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Named views are queried through a dedicated path endpoint:
|
|
8
8
|
|
|
9
9
|
```
|
|
10
|
-
GET /api/v1/{resource}
|
|
11
|
-
GET /api/v1/{resource}/views/{view-name} # Explicit path
|
|
10
|
+
GET /api/v1/{resource}/views/{view-name}
|
|
12
11
|
```
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
If you set `read.defaultView`, bare `GET /api/v1/{resource}` can still resolve
|
|
14
|
+
to that view. Named views themselves are addressed via `/views/{view-name}`.
|
|
15
15
|
|
|
16
16
|
## Example
|
|
17
17
|
|
|
@@ -39,11 +39,6 @@ export default defineTable(candidates, {
|
|
|
39
39
|
### Request
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
-
# Query-string form
|
|
43
|
-
curl '/api/v1/candidates?view=pipeline' \
|
|
44
|
-
-H "Authorization: Bearer <token>"
|
|
45
|
-
|
|
46
|
-
# Path form (equivalent)
|
|
47
42
|
curl /api/v1/candidates/views/pipeline \
|
|
48
43
|
-H "Authorization: Bearer <token>"
|
|
49
44
|
```
|
|
@@ -57,11 +52,11 @@ curl /api/v1/candidates/views/pipeline \
|
|
|
57
52
|
{ "id": "cand_002", "name": "Bob Martinez", "source": "referral" }
|
|
58
53
|
],
|
|
59
54
|
"view": "pipeline",
|
|
60
|
-
"fields": ["id", "name", "source"],
|
|
61
55
|
"pagination": {
|
|
62
|
-
"
|
|
63
|
-
"
|
|
64
|
-
"
|
|
56
|
+
"count": 2,
|
|
57
|
+
"page": 1,
|
|
58
|
+
"pageSize": 50,
|
|
59
|
+
"hasMore": false
|
|
65
60
|
}
|
|
66
61
|
}
|
|
67
62
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.2",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -4,6 +4,197 @@ Release notes for the Quickback compiler, CLI, and platform.
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## v0.14.2 — May 7, 2026
|
|
8
|
+
|
|
9
|
+
### Wrangler `[[migrations]]` no longer drops historical Durable Object lifecycle entries
|
|
10
|
+
|
|
11
|
+
Cloudflare requires the `[[migrations]]` list in `wrangler.toml` to be **append-only**: once a tag has been deployed, removing it on a subsequent compile causes the next deploy to fail with `Cannot apply <new|deleted|renamed|transferred>-class migration to class <X>` — CF replays the full migrations log on every push and notices the tag is gone.
|
|
12
|
+
|
|
13
|
+
Pre-fix, the compiler regenerated the `[[migrations]]` blocks from scratch on every compile, emitting only entries for the *current* `durableObjects` bindings. Any historical lifecycle events the user had hand-maintained — `deleted_classes`, `renamed_classes`, `transferred_classes` — were silently dropped and the deploy then broke. AttendVIP hit this first: a `qb-do-deleted-legacy-notes-2026-05-05` deletion entry got dropped, and the next deploy tried to re-apply `qb-do-Notepad`'s `new_sqlite_classes` against the existing class.
|
|
14
|
+
|
|
15
|
+
The fix adds a new config slot — `bindings.durableObjectMigrations` — for historical entries that survive recompiles. Declared entries are emitted FIRST in the generated `wrangler.toml`'s migrations list (preserving chronological order), then the auto-generated current-class creation entries follow, deduplicated by tag so an explicit user entry wins over the auto-emit.
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
// quickback.config.ts
|
|
19
|
+
bindings: {
|
|
20
|
+
durableObjects: [
|
|
21
|
+
{ name: 'NOTEPAD', className: 'Notepad', from: 'lib/Notepad' },
|
|
22
|
+
],
|
|
23
|
+
durableObjectMigrations: [
|
|
24
|
+
// Carry forward across recompiles — Cloudflare's migration list is append-only.
|
|
25
|
+
{
|
|
26
|
+
tag: 'qb-do-deleted-legacy-notes-2026-05-05',
|
|
27
|
+
deletedClasses: ['LegacyNotes'],
|
|
28
|
+
},
|
|
29
|
+
],
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
All four lifecycle shapes are supported: `newClasses` / `newSqliteClasses` (creations), `deletedClasses` (removals), `renamedClasses` (`{ from, to }` inline-table-array), `transferredClasses` (`{ from, from_script, to }` for moves between workers). The user-declared entry can also override the auto-emit by reusing the same tag — useful when a DO started life as KV-backed before SQLite-DOs existed.
|
|
34
|
+
|
|
35
|
+
This is a config-side fix, not a wrangler.toml-merging one — Quickback doesn't read your existing `wrangler.toml`. The discipline is the same as for any append-only log: declare lifecycle events as you make them. Auto-detection of removed classes from the schema diff is on the roadmap; for now the compiler trusts your declaration.
|
|
36
|
+
|
|
37
|
+
7 new tests covering deletion, rename, transfer, multi-entry ordering, override-via-same-tag, no-history bit-identical output, and the historical-only-no-current-DOs edge case.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## v0.14.1 — May 7, 2026
|
|
42
|
+
|
|
43
|
+
### Bulk action variants now appear in `openapi.json`
|
|
44
|
+
|
|
45
|
+
Record-based actions with `bulkVariant: true` (introduced in v0.14.0) generate a working `POST /<base>/batch/<actionName>` route at runtime, but the OpenAPI generator wasn't aware of them — so the bulk endpoints were invisible to typed-client codegen (`api-types.gen.ts`) and to MCP-driven agents discovering operations from the spec. AttendVIP's v0.14.0 rollout (seven actions with `bulkVariant: true`: `approve`, `checkIn`, `checkOut`, `setVisibility`, `cancelInvite`, `sendInvite`, `sessionApprove`) found this within hours of shipping.
|
|
46
|
+
|
|
47
|
+
The OpenAPI generator now emits each bulk variant as a sibling operation to its per-record action, with the documented request shape (`{ ids: string[], input, failFast? }`), correct 200 / 207 / 400 responses, an `x-bulk-variant: true` marker, and a separate `<resource><Action>Bulk` `operationId` so client codegen can distinguish single from bulk. The fix also threads `bulkVariant` through `getAllActions` so any other downstream consumer of the action registry sees the flag — previously the parser captured it but the spec-emit path silently dropped it.
|
|
48
|
+
|
|
49
|
+
No changes required in user code. Re-running `quickback compile` regenerates `openapi.json` with both routes per `bulkVariant: true` action; downstream `api-types.gen.ts` builds pick up the new operations on the next codegen run.
|
|
50
|
+
|
|
51
|
+
### Cross-tenant "my events" pattern documented with a worked example
|
|
52
|
+
|
|
53
|
+
The v0.14.0 docs noted that relationship-roles do **not** solve cross-tenant aggregation ("a guest's view of events across all tenants they were invited to") and pointed at function-form access as the workaround, but didn't show what that looked like in practice. The access docs now carry a full standalone-action example for `GET /my-events` — the canonical attendee-dashboard pattern — including the two security guardrails (always filter by `ctx.userId`; the action takes responsibility for soft-delete and other invariants the firewall would otherwise apply). Standalone actions are already mandatorily audit-logged in the runtime, so the cross-tenant traversal is recorded automatically.
|
|
54
|
+
|
|
55
|
+
See [Access → Cross-tenant "my events" dashboards](/compiler/definitions/access#cross-tenant-my-events-dashboards-are-not-this).
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## v0.14.0 — May 7, 2026
|
|
60
|
+
|
|
61
|
+
### Relationship-based authorization roles
|
|
62
|
+
|
|
63
|
+
Quickback's role system now supports a third kind of role beyond Better Auth org membership and the four pseudo-roles (`PUBLIC`/`AUTHENTICATED`/`USER`/`ADMIN`): **relationship-roles** that bind to a domain-table membership ("user is a confirmed guest of this event") rather than an org/admin gate. The original ask was a B2B event-management app where logged-in users who aren't team members but ARE confirmed guests of an event need to see that event's sessions, pages, and tracks — same data, different access lane. The old workarounds (function-form access, hand-written actions, `firewall: { exception: true }`) all gave up some combination of OpenAPI/MCP visibility, CRUD code generation, or tenant safety.
|
|
64
|
+
|
|
65
|
+
Declare the relationship once in `quickback.config.ts`, then reference it from `firewall:` or `access.roles:`:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
// quickback.config.ts
|
|
69
|
+
authz: {
|
|
70
|
+
relationships: {
|
|
71
|
+
guestOf: {
|
|
72
|
+
from: 'event_guests', // relationship table
|
|
73
|
+
subject: { column: 'userId', equals: 'ctx.userId' }, // caller side
|
|
74
|
+
resource: { column: 'eventId' }, // resource side
|
|
75
|
+
where: { status: 'confirmed' }, // optional row filter
|
|
76
|
+
},
|
|
77
|
+
},
|
|
78
|
+
roles: {
|
|
79
|
+
guest: { via: 'guestOf' },
|
|
80
|
+
eventStaff: {
|
|
81
|
+
or: [{ via: 'guestOf' }, { roles: ['admin', 'owner'] }],
|
|
82
|
+
},
|
|
83
|
+
},
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
// features/sessions/sessions.ts
|
|
87
|
+
firewall: [
|
|
88
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
89
|
+
{ field: 'eventId', via: 'guestOf' }, // ← row scoping
|
|
90
|
+
],
|
|
91
|
+
read: { access: { roles: ['admin', 'member', 'guest'] } }, // ← OR-composed
|
|
92
|
+
crud: {
|
|
93
|
+
create: { access: { roles: ['admin', 'guest'] } }, // inline async lookup
|
|
94
|
+
update: { access: { roles: ['admin'] } },
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The compiler emits an inline Drizzle subquery against the relationship table and AND-composes it as the outermost firewall clause. The relationship table's own `buildFirewallConditions(ctx)` is called inside the subquery so soft-delete and tenant scope on the relationship row are always honored — soft-deleting an `event_guests` row revokes access immediately. Anonymous callers fail closed (the subquery short-circuits to `WHERE 1 = 0` when `ctx.userId` is null). Cross-tenant grants are impossible because the resource's tenant filter sits as the outermost AND, never folded into a role OR. See [Firewall → Relationship-based scoping](/compiler/definitions/firewall#relationship-based-scoping-via) and [Access → Relationship-based authorization](/compiler/definitions/access#relationship-based-authorization).
|
|
99
|
+
|
|
100
|
+
What works in v0.14.0:
|
|
101
|
+
|
|
102
|
+
| Surface | Status |
|
|
103
|
+
|---|---|
|
|
104
|
+
| `firewall: [{ field, via }]` row-level scoping | Full |
|
|
105
|
+
| `crud.<op>.access` `roles: ['guest']` (inline emission) | Full |
|
|
106
|
+
| `read.access` and `read.views.*.access` | Full |
|
|
107
|
+
| `masking.<f>.show` `roles: ['guest']` | Compile-refused (workaround pointer) |
|
|
108
|
+
| `actions.<n>.access` `roles: ['guest']` | Compile-refused (workaround pointer) |
|
|
109
|
+
|
|
110
|
+
The runtime evaluator fails closed on relationship arms regardless of which surface you hit, so silent grants are impossible everywhere. The two refused surfaces have clear compile-time errors pointing to the working pattern (gate the row at the firewall layer with `via:`, gate the role at the access layer with BA roles).
|
|
111
|
+
|
|
112
|
+
Compile-time refusals also catch: unknown `via:` reference, cycles in role composition (`a → b → a`), reserved role-name shadowing (auth-provider-derived only — `guest`/`speaker`/`attendee` are free; `admin`/`owner`/`member` are reserved when the BA org plugin is on), unknown relationship `from` table, resource missing the `resource.column`, relationship table with `firewall: { exception: true }` (would let cross-tenant grants slip through), `lowering: 'session'` (reserved for v2 — staleness/invalidation ergonomics not yet shipped), and `+` hierarchy on relationship-roles (terminal, like pseudo-roles).
|
|
113
|
+
|
|
114
|
+
Cross-tenant "my events" dashboards (a logged-in user wants `GET /my-events` returning events they're a guest of *across all tenants*) are **not** solved by relationship-roles — the tenant firewall stays the outermost AND. For that pattern, use a user-scoped firewall (`firewall: { owner: { column: 'userId' } }`) or function-form access on a dedicated route. Documented prominently in [access.mdx](/compiler/definitions/access#cross-tenant-my-events-dashboards-are-not-this) so users don't reach for relationship-roles first and get confused.
|
|
115
|
+
|
|
116
|
+
Roadmap: `lowering: 'session'` ergonomics, inline relationship emission for `actions.access` (needs `relationshipBindings` design), async/batched mask functions for `masking.show`. The schema slots are reserved so v2 lands non-breaking.
|
|
117
|
+
|
|
118
|
+
### Bulk variants of record-based actions
|
|
119
|
+
|
|
120
|
+
Record-based actions can now opt into an auto-generated bulk route alongside the per-record route. Set `bulkVariant: true` on a `defineAction({...})` and the compiler emits `POST /:resource/batch/{action}` that loops the same access + transition + execute pipeline over a `{ ids: [...], input, failFast? }` body. The original ask was an event-management UX where every domain bulk operation (approve N guests, rescind N invites, advance N applications) became a hand-written standalone action that re-implemented a per-record action's transition + execute logic in a `for` loop — `PATCH /:resource/batch` couldn't do it because state lives on a protected field, which is the right call for safety.
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
// features/applications/actions/advance.ts
|
|
124
|
+
export default defineAction({
|
|
125
|
+
description: "Move an application forward in the pipeline.",
|
|
126
|
+
input: z.object({ nextStatus: z.enum(["screening", "interview", "offer"]) }),
|
|
127
|
+
access: { roles: ["owner", "admin"] },
|
|
128
|
+
bulkVariant: true, // ← opt-in
|
|
129
|
+
transition: { field: "status", via: "nextStatus", fromTo: { /* ... */ } },
|
|
130
|
+
async execute({ db, record, input, whereTransition }) {
|
|
131
|
+
// exact same body as before — runs once per id
|
|
132
|
+
},
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Per-record outcomes return as 207 Multi-Status with the same `{ success, errors, meta }` shape as `PATCH /batch`. Each id flows through the firewall fetch, the per-record `evaluateAccessReason` split (403 role / 409 record-precondition), the transition pre-check, and the same `whereTransition` factory the single-record route uses — so a stale-state record fails for that id alone, not the whole batch. `failFast: true` aborts on the first failure and (on Postgres / Supabase / Neon / libsql / sqlite drivers) wraps the loop in `db.transaction()` so prior writes roll back; D1 is documented as fail-fast-without-rollback because it has no `db.transaction`.
|
|
137
|
+
|
|
138
|
+
Compile-time refusals: `bulkVariant: true` is rejected on standalone actions (no record context to loop over) and on actions that declare `unsafe` (cross-tenant per-record audit not yet wired). Method is forced to POST regardless of the action's `method` setting — the one-row-to-many-rows asymmetry makes inheriting GET/DELETE confusing. Max batch size is 100 ids per request, mirroring the CRUD batch endpoints. See [Actions → Bulk variant](/compiler/definitions/actions#bulk-variant).
|
|
139
|
+
|
|
140
|
+
### Aggregations on read views
|
|
141
|
+
|
|
142
|
+
Read views can now declare pre-computed metrics that surface on the response next to the row payload, without a custom standalone action. Every dashboard tile that previously turned into a standalone action just for "count of X grouped by Y" now lives in the same view config that drives the rows.
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
read: {
|
|
146
|
+
views: {
|
|
147
|
+
pipeline: {
|
|
148
|
+
fields: ["id", "jobId", "candidateId", "status", "appliedAt"],
|
|
149
|
+
aggregations: {
|
|
150
|
+
totalApplications: { fn: "count" },
|
|
151
|
+
byStatus: { fn: "groupBy", field: "status" },
|
|
152
|
+
},
|
|
153
|
+
},
|
|
154
|
+
},
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Response carries `aggregations: { ... }` alongside `data`:
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"data": [/* paginated rows */],
|
|
163
|
+
"view": "pipeline",
|
|
164
|
+
"pagination": { "count": 50, "page": 1, "pageSize": 50, "hasMore": true },
|
|
165
|
+
"aggregations": {
|
|
166
|
+
"totalApplications": 173,
|
|
167
|
+
"byStatus": { "applied": 102, "screening": 41, "interview": 18, "offer": 7, "rejected": 5 }
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Aggregations always run over the **same firewalled, filtered set** as the row query — pagination is intentionally ignored, so `?status=applied&limit=10` returns the 10 paged rows AND the count over every applied row. Supported `fn`s: `sum`, `avg`, `min`, `max`, `count` (with or without `field` — `COUNT(*)` vs `COUNT(field)`), `count_distinct`, and `groupBy` (returns `{ value: count }`, NULLs bucket as `"(none)"`).
|
|
173
|
+
|
|
174
|
+
Compile-time validation: `field` must reference a real column; `sum`/`avg` require numeric column types; the same masking opt-out gate that governs `query.{filterable, sortable, searchable}` applies to aggregations (a `sum(salary)` leaks structure even when the row payload is redacted); aggregation names cannot collide with the reserved response fields `data`, `pagination`, `view`. No raw SQL `expr:` form in v1 — column references only. See [Views → Aggregations](/compiler/definitions/views#aggregations).
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## v0.13.5 — May 6, 2026
|
|
179
|
+
|
|
180
|
+
### Object-form `auth.plugins` no longer crashes the compiler
|
|
181
|
+
|
|
182
|
+
The documented object form for per-plugin config — `plugins: { oauthProvider: {...} }`, `plugins: { organization: { teams: { enabled: true } } }`, etc. (see [Better Auth Plugins → Custom configuration](/stack/auth/plugins#oauth-provider-mcp-ready)) — was rejected by the compiler with `plugins.includes is not a function`. `hasCliAuthRoutes` called `.includes()` directly on `auth.config.plugins` to detect `deviceAuthorization`, and `generateAuthFiles` flattened plugins to a string array before handing them to the better-auth generator, silently dropping every per-plugin user option on the way through.
|
|
183
|
+
|
|
184
|
+
Both paths now run through a shared resolver that preserves the user's input format (object in → object out, array in → array out) and only adds the compiler's auto-included plugins (`organization`, `admin`, `apiKey`, plus `bearer` when `deviceAuthorization` is present) as `true` entries that don't clobber user config. Per-plugin options like `oauthProvider: { scopes: [...] }`, `organization: { teams: { enabled: true } }`, and `deviceAuthorization: { verificationUri: '...' }` now reach the generated `auth.ts` as written.
|
|
185
|
+
|
|
186
|
+
Better Auth's `ac` / `roles` access-control objects (the result of `createAccessControl(...)`) still require a custom `auth.ts` override — they're live runtime values that can't survive the JSON config trip from CLI → compiler. A declarative escape hatch for that is on the roadmap.
|
|
187
|
+
|
|
188
|
+
### `roles: ["PUBLIC"]` is allowed on writes and actions again
|
|
189
|
+
|
|
190
|
+
v0.10.17 added a compile-time block that rejected `roles: ["PUBLIC"]` on `crud.create` / `crud.update` / `crud.delete` and on every action. The intent — "anonymous mutations are usually a misconfiguration" — collided with the legitimate use cases the rest of Quickback was built around: Gmail one-click RSVP confirms, public RSVP forms, magic-link redemption, List-Unsubscribe-Post handlers, webhook ingest, captcha-gated contact forms. None of those carry a session, so `AUTHENTICATED` 401s the caller before the handler can validate its own token, and the suggested escape hatch ("custom action that does its own auth + `firewall: { exception: true }`") was itself blocked by the same validator.
|
|
191
|
+
|
|
192
|
+
The block is removed. `PUBLIC` is the explicit, uppercase opt-in for unauthenticated access on every access node — reads, CRUD writes, views, and actions. The compiler trusts the marker; row-level safety comes from firewall, masking, and the action's own token validation. `PUBLIC` actions continue to receive **mandatory audit logging** (IP, input, result, timing) in the runtime regardless. `crud.create`/`update`/`delete` typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
|
|
193
|
+
|
|
194
|
+
`USER` and `ADMIN` keep their compile-time prerequisites (firewall must scope by `userId` / admin plugin must be enabled).
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
7
198
|
## v0.12.0 — May 5, 2026
|
|
8
199
|
|
|
9
200
|
### Per-room authorization for PartyServer rooms
|
|
@@ -682,7 +873,7 @@ for the full reference and migration table.
|
|
|
682
873
|
- `crud.list` → [`read.access`](/compiler/definitions/read) (plus `read.pageSize` / `read.maxPageSize`)
|
|
683
874
|
- `crud.get` → `read.access` (single-record GET inherits automatically; use record-level conditions on `read.access` for differentiated single-record gates)
|
|
684
875
|
- Top-level `views: {...}` → [`read.views: {...}`](/compiler/definitions/read#views-under-read-views)
|
|
685
|
-
- `crud.list.fields` / `crud.get.fields` → declare a named view under `read.views` and call
|
|
876
|
+
- `crud.list.fields` / `crud.get.fields` → declare a named view under `read.views` and call `/views/{name}`
|
|
686
877
|
|
|
687
878
|
**Pre-record access ordering on `/:id`**: handlers now run a role-only
|
|
688
879
|
access check **before** the firewall query, so a caller without a matching
|