@quickback-dev/cli 0.66.5 → 0.66.6
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/README.md +0 -1
- package/dist/index.js +1 -1
- package/dist/skill/SKILL.md +0 -2
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/configure/auth.md +4 -5
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +4 -4
- package/dist/skill/docs/configure/security.md +3 -3
- package/dist/skill/docs/define/access.md +23 -3
- package/dist/skill/docs/define/actions/defining.md +2 -2
- package/dist/skill/docs/define/actions/record-and-standalone.md +1 -2
- package/dist/skill/docs/define/areas.md +14 -15
- package/dist/skill/docs/define/changesets.md +5 -0
- package/dist/skill/docs/define/diagnostics.md +2 -2
- package/dist/skill/docs/define/fga.md +1 -1
- package/dist/skill/docs/define/firewall.md +5 -5
- package/dist/skill/docs/define/guards.md +2 -1
- package/dist/skill/docs/define/masking.md +2 -2
- package/dist/skill/docs/define/relationships.md +8 -10
- package/dist/skill/docs/define/scopes.md +1 -1
- package/dist/skill/docs/index.md +0 -6
- package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -2
- package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
- package/dist/skill/docs/platform/webhooks/inbound.md +1 -1
- package/dist/skill/docs/tooling/claude-skill.md +0 -7
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +1 -1
- package/dist/skill/docs/tooling/output.md +7 -6
- package/dist/skill/docs/ui/account/features/admin.md +1 -1
- package/dist/skill/docs/ui/account/features/organizations.md +1 -1
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/dist/skill/docs/ui/admin/owned-records.md +81 -0
- package/dist/skill/docs/ui/admin/schema-format.md +16 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +0 -2
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/configure/auth.md +4 -5
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +4 -4
- package/src/skill/docs/configure/security.md +3 -3
- package/src/skill/docs/define/access.md +23 -3
- package/src/skill/docs/define/actions/defining.md +2 -2
- package/src/skill/docs/define/actions/record-and-standalone.md +1 -2
- package/src/skill/docs/define/areas.md +14 -15
- package/src/skill/docs/define/changesets.md +5 -0
- package/src/skill/docs/define/diagnostics.md +2 -2
- package/src/skill/docs/define/fga.md +1 -1
- package/src/skill/docs/define/firewall.md +5 -5
- package/src/skill/docs/define/guards.md +2 -1
- package/src/skill/docs/define/masking.md +2 -2
- package/src/skill/docs/define/relationships.md +8 -10
- package/src/skill/docs/define/scopes.md +1 -1
- package/src/skill/docs/index.md +0 -6
- package/src/skill/docs/platform/auth/jwt-optimization.md +2 -2
- package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
- package/src/skill/docs/platform/webhooks/inbound.md +1 -1
- package/src/skill/docs/tooling/claude-skill.md +0 -7
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +1 -1
- package/src/skill/docs/tooling/output.md +7 -6
- package/src/skill/docs/ui/account/features/admin.md +1 -1
- package/src/skill/docs/ui/account/features/organizations.md +1 -1
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/owned-records.md +81 -0
- package/src/skill/docs/ui/admin/schema-format.md +16 -0
- package/dist/skill/docs/changelog/index.md +0 -945
- package/dist/skill/docs/changelog/v0.1x.md +0 -1202
- package/dist/skill/docs/changelog/v0.2x.md +0 -589
- package/dist/skill/docs/changelog/v0.3x.md +0 -1152
- package/dist/skill/docs/changelog/v0.4x.md +0 -1108
- package/dist/skill/docs/changelog/v0.5x.md +0 -885
- package/src/skill/docs/changelog/index.md +0 -945
- package/src/skill/docs/changelog/v0.1x.md +0 -1202
- package/src/skill/docs/changelog/v0.2x.md +0 -589
- package/src/skill/docs/changelog/v0.3x.md +0 -1152
- package/src/skill/docs/changelog/v0.4x.md +0 -1108
- package/src/skill/docs/changelog/v0.5x.md +0 -885
|
@@ -26,7 +26,7 @@ The first line stays greppable (`[quickback:<channel>] CODE: message`); the
|
|
|
26
26
|
source location, fix hint, and — for promoted errors — the exact override
|
|
27
27
|
recipe render on continuation lines.
|
|
28
28
|
|
|
29
|
-
## Errors vs warnings
|
|
29
|
+
## Errors vs warnings
|
|
30
30
|
|
|
31
31
|
The checks split into two tiers:
|
|
32
32
|
|
|
@@ -114,7 +114,7 @@ authz: {
|
|
|
114
114
|
{
|
|
115
115
|
check: 'AUTHZ_CAPABILITY_CEILING',
|
|
116
116
|
target: 'sessions/scope:event:organizer',
|
|
117
|
-
reason: '
|
|
117
|
+
reason: 'temporary exception while the organizer grant profile is implemented',
|
|
118
118
|
},
|
|
119
119
|
],
|
|
120
120
|
},
|
|
@@ -307,7 +307,7 @@ stored tuple whose subject shape isn't allowed for the relation is inert. So a
|
|
|
307
307
|
`user:*` tuple on a relation declared `[user]` (no wildcard) can never grant
|
|
308
308
|
access, even if it was written out-of-band — the model is the ceiling.
|
|
309
309
|
|
|
310
|
-
## Limitations
|
|
310
|
+
## Limitations
|
|
311
311
|
|
|
312
312
|
- `access: { fga }` covers **per-record** operations (`GET /:id`, `update`,
|
|
313
313
|
`delete`, record-based actions) and **collection filtering** on
|
|
@@ -100,9 +100,9 @@ type FirewallPredicate =
|
|
|
100
100
|
| { field: string; isNull: true } // column IS NULL
|
|
101
101
|
| { field: string; in: string[] | string; optional?: boolean } // column IN (...)
|
|
102
102
|
| { field: string; via: string } // column IN (relationship subquery)
|
|
103
|
-
| { field?: string; permission: string } // named authz.permissions reference
|
|
104
|
-
| { all: FirewallPredicate[] } // AND group
|
|
105
|
-
| { any: FirewallPredicate[] }
|
|
103
|
+
| { field?: string; permission: string } // named authz.permissions reference
|
|
104
|
+
| { all: FirewallPredicate[] } // AND group
|
|
105
|
+
| { any: FirewallPredicate[] } // OR group
|
|
106
106
|
| { exception: true }; // opt out of tenant scoping
|
|
107
107
|
|
|
108
108
|
type FirewallConfig = ReadonlyArray<FirewallPredicate>;
|
|
@@ -113,7 +113,7 @@ firewallErrorMode?: 'reveal' | 'hide';
|
|
|
113
113
|
|
|
114
114
|
The top-level array is AND'd together. `firewallErrorMode` lives at the resource top level — it's a presentation-layer choice (403 vs 404), not a query-shape one.
|
|
115
115
|
|
|
116
|
-
## Boolean groups: `all` / `any`
|
|
116
|
+
## Boolean groups: `all` / `any`
|
|
117
117
|
|
|
118
118
|
A flat array can only express AND. To grant access through **either** of two independent paths — "an org member **OR** an event attendee" — nest an `any` group. The top-level array stays sugar for `all`, so every existing firewall is byte-identical.
|
|
119
119
|
|
|
@@ -389,7 +389,7 @@ So `firewall: [{ exception: true }]` on the default configuration returns `isNul
|
|
|
389
389
|
|
|
390
390
|
## Sysadmin Escape Hatch
|
|
391
391
|
|
|
392
|
-
When `cms: { sysadmin: true }` is set on the project
|
|
392
|
+
When `cms: { sysadmin: true }` is set on the project, every `buildFirewallConditions()` emits a runtime branch that drops tenant scopes for `ctx.userRole === 'sysadmin'` callers while keeping the soft-delete predicate:
|
|
393
393
|
|
|
394
394
|
```typescript
|
|
395
395
|
// Generated for an org-scoped table when cms.sysadmin: true
|
|
@@ -76,7 +76,8 @@ guards: {
|
|
|
76
76
|
> to the table for `db.update(<table>).set({ … })` / `db.insert(<table>).values({ … })`
|
|
77
77
|
> and refuses an `immutable` column in any update, or a `protected` column
|
|
78
78
|
> written by an action that is not in its list — with an error naming the action,
|
|
79
|
-
> the column, and the fix.
|
|
79
|
+
> the column, and the fix. Every offending action in the project is listed in
|
|
80
|
+
> that one error, so a single compile surfaces all of them. The two tiers are therefore distinct: `immutable` is
|
|
80
81
|
> written once at create and never again; if a column needs an action to change
|
|
81
82
|
> it, it is `protected`, mapped to that action.
|
|
82
83
|
>
|
|
@@ -50,7 +50,7 @@ Whether `customers.email` is PII to hide or the display label of a contact list
|
|
|
50
50
|
|
|
51
51
|
So the compiler asks. A false positive costs you one line (`cc: false`) — which is also a durable, reviewable record that somebody looked.
|
|
52
52
|
|
|
53
|
-
It also removes a bug class outright. When detection can never quietly supply a rule, the set of masked columns is the set you declared, so no two surfaces can disagree about it.
|
|
53
|
+
It also removes a bug class outright. When detection can never quietly supply a rule, the set of masked columns is the set you declared, so no two surfaces can disagree about it.
|
|
54
54
|
|
|
55
55
|
### What a decision controls
|
|
56
56
|
|
|
@@ -215,7 +215,7 @@ masking: {
|
|
|
215
215
|
}
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
`show: { roles: [] }` has the same effect, but it doesn't say the same thing. An empty role list reads as an oversight, and it is also what authors fall back to when the audience they wanted is **inexpressible** — masking gates on org and scoped roles, so a table gated `access: { userRole: ['sysadmin'] }` cannot name its own audience in a mask. Two different intentions, one spelling, and no way for the next reader to tell them apart.
|
|
218
|
+
`show: { roles: [] }` has the same effect, but it doesn't say the same thing. An empty role list reads as an oversight, and it is also what authors fall back to when the audience they wanted is **inexpressible** — masking gates on org and scoped roles, so a table gated `access: { userRole: ['sysadmin'] }` cannot name its own audience in a mask. Two different intentions, one spelling, and no way for the next reader to tell them apart. Note the asymmetry with access, where an empty list would mean *everyone* — which is why [access refuses it at compile time](/define/access#an-empty-list-is-a-compile-error).
|
|
219
219
|
|
|
220
220
|
Write `'never'` when nobody is the intent. Any other string is a compile error rather than a guess — `show: 'admin'` is a plausible typo, and masking-for-everyone is the wrong thing to assume from it.
|
|
221
221
|
|
|
@@ -118,7 +118,7 @@ the compiler rejects a relationship-bearing `masking.show` rule and points to a
|
|
|
118
118
|
relationship-gated view instead. It never drops the relationship arm or turns
|
|
119
119
|
it into a broader role grant.
|
|
120
120
|
|
|
121
|
-
### Standalone actions: surface keys and `loads` / `exposeAs`
|
|
121
|
+
### Standalone actions: surface keys and `loads` / `exposeAs`
|
|
122
122
|
|
|
123
123
|
When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the current compiler stops with a clear build error; an action can never ship with a relationship rule it has no key to evaluate.
|
|
124
124
|
|
|
@@ -132,7 +132,7 @@ authz: {
|
|
|
132
132
|
subject: { column: 'userId', equals: 'ctx.userId' },
|
|
133
133
|
resource: { column: 'eventId' },
|
|
134
134
|
where: { status: 'confirmed' },
|
|
135
|
-
loads: 'events', //
|
|
135
|
+
loads: 'events', // load matching event row
|
|
136
136
|
exposeAs: 'event', // ← onto ctx.event for the action body
|
|
137
137
|
},
|
|
138
138
|
},
|
|
@@ -142,7 +142,7 @@ authz: {
|
|
|
142
142
|
}
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
The resolver
|
|
145
|
+
The resolver:
|
|
146
146
|
|
|
147
147
|
1. **Cheap in-memory role check** first — `ctx.roles?.includes('admin')` and friends. If the caller has a qualifying role, this short-circuits and no DB queries fire for the access gate.
|
|
148
148
|
2. **Firewall-gated relationship match** if the role check failed — `SELECT { organizationId, teamId } FROM guests WHERE userId=ctx.userId AND eventId=input.eventId AND status='confirmed'` with the `guests` table's full firewall AND-applied. If neither role nor relationship qualifies → 403.
|
|
@@ -152,24 +152,22 @@ The resolver (v0.20):
|
|
|
152
152
|
|
|
153
153
|
**No firewall bypass anywhere.** Both queries run with their respective tables' full firewalls. The relationship row's existence is the proof that the caller is authorized; its tenant columns are the source of the stamped claim.
|
|
154
154
|
|
|
155
|
-
### Conditional tenant preconditions
|
|
155
|
+
### Conditional tenant preconditions
|
|
156
156
|
|
|
157
|
-
Standalone actions in features with org/team-scoped tables
|
|
157
|
+
Standalone actions in features with org/team-scoped tables emit tenant preconditions only when a relationship cannot supply the tenant:
|
|
158
158
|
|
|
159
159
|
```ts
|
|
160
160
|
if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
|
|
161
161
|
if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
|
|
162
162
|
```
|
|
163
163
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before. `ADMIN` is now rejected at compile time.
|
|
164
|
+
If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` also bypass the preconditions. `ADMIN` is rejected at compile time.
|
|
167
165
|
|
|
168
166
|
Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
|
|
169
167
|
|
|
170
168
|
### Requirement on the relationship's `from` table
|
|
171
169
|
|
|
172
|
-
For
|
|
170
|
+
For tenant-stamping to work, the relationship's `from` table must carry tenant columns:
|
|
173
171
|
|
|
174
172
|
- For org stamping: an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
|
|
175
173
|
- For team stamping: a `teamId` column.
|
|
@@ -213,7 +211,7 @@ export default defineAction({
|
|
|
213
211
|
|
|
214
212
|
`loads` and `exposeAs` are co-required (set both or neither). `exposeAs` must be a valid JS identifier and must not collide with built-in `ctx` fields (`userId`, `activeOrgId`, `activeTeamId`, `db`, etc.).
|
|
215
213
|
|
|
216
|
-
### Action firewall escape hatch
|
|
214
|
+
### Action firewall escape hatch
|
|
217
215
|
|
|
218
216
|
`defineAction({ firewall: { exception: true } })` opts the action out of the inherited session-key preconditions (`ctx.activeOrgId` / `ctx.activeTeamId` requirements) AND the relationship resolver. The handler receives `unsafeDb` for raw Drizzle access. Use for cross-tenant or admin routes whose surface intentionally doesn't name a session/relationship key:
|
|
219
217
|
|
|
@@ -672,7 +672,7 @@ The scope claim is trusted between proofs — it is never re-checked against the
|
|
|
672
672
|
|
|
673
673
|
So removing a guest/staff row takes effect within **cap + one TTL** for a client that keeps polling, and within one TTL once it goes idle. Two ways to tighten that:
|
|
674
674
|
|
|
675
|
-
- **`auth.jwt.revocationCheck: 'kv'`** (
|
|
675
|
+
- **`auth.jwt.revocationCheck: 'kv'`** (Cloudflare runtime) — sub-TTL revocation: updating or deleting a conferring relationship row stamps a revocation timestamp in KV, and the bearer fast-path rejects a carried scope claim whose proof is at or before it — no same-second gap. Each kind is compared against **its own** proof time (`sctMs` on the entry; tokens without one fall back to the token-level `sct`/`sctMs`), so a mint of one kind can't carry a revoked kind past its marker. Neither the refresh nor a re-mint ever substitutes its own clock for a proof it didn't take. The check fails closed — a scope claim whose revocation state can't be read is not trusted either. See [auth config](/configure/auth).
|
|
676
676
|
- **`via` arms** — for tables where any caching is too wide, gate with a `via` arm instead of a bare `ctx.scope.<kind>` arm: `via` emits a live subquery against the relationship table on every request, immune to a stale claim entirely.
|
|
677
677
|
|
|
678
678
|
## Reference
|
package/src/skill/docs/index.md
CHANGED
|
@@ -76,9 +76,3 @@ The runtime services around your compiled code. Everything you need for a comple
|
|
|
76
76
|
- **[Account UI](/ui/account)** — Pre-built auth and profile pages
|
|
77
77
|
|
|
78
78
|
Everything runs on **your own Cloudflare account** — no Quickback infrastructure between you and your data.
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
### Changelog
|
|
83
|
-
|
|
84
|
-
[**Changelog**](/changelog) — what's new in Quickback. Release notes, new features, and improvements.
|
|
@@ -110,7 +110,7 @@ The fast-path is stateless by default: it verifies the signature and **trusts th
|
|
|
110
110
|
|
|
111
111
|
**Lower the TTL.** `auth.jwt.expiresIn: 30` gives a hard 30-second ceiling. Browser SPAs auto-refresh via `set-auth-token` on every authed call, so a low TTL is invisible to logged-in users; only stale server-to-server bearer tokens feel it.
|
|
112
112
|
|
|
113
|
-
**Or enable sub-TTL revocation.** Set `revocationCheck: 'kv'` (
|
|
113
|
+
**Or enable sub-TTL revocation.** Set `revocationCheck: 'kv'` (Cloudflare runtime only):
|
|
114
114
|
|
|
115
115
|
```ts title="quickback.config.ts"
|
|
116
116
|
auth: {
|
|
@@ -120,7 +120,7 @@ auth: {
|
|
|
120
120
|
|
|
121
121
|
The fast-path then consults per-principal revocation timestamps in your project's existing `KV` binding (keys prefixed `qbrev:`, self-expiring) *before* trusting a token. A token is rejected when its mint timestamp (`iat`/`iatMs`, or the proof time of the scope kind being checked) is **at or before** the stored timestamp. Cost: 2+ edge-cached KV reads per bearer verify.
|
|
122
122
|
|
|
123
|
-
There is no same-second gap: markers are epoch milliseconds (written `m<ms
|
|
123
|
+
There is no same-second gap: markers are epoch milliseconds (written `m<ms>`), tokens carry millisecond companions, and the comparison denies a tie — so a token minted a few milliseconds *before* the revocation is rejected, while one legitimately re-minted *after* it in that same second is still accepted.
|
|
124
124
|
|
|
125
125
|
Revocation stamps are written **automatically** on:
|
|
126
126
|
|
|
@@ -367,7 +367,7 @@ await realtime.update('applications', newRecord, oldRecord, ctx.activeOrgId!, {
|
|
|
367
367
|
});
|
|
368
368
|
```
|
|
369
369
|
|
|
370
|
-
**Fail-closed
|
|
370
|
+
**Fail-closed:** an omitted or empty `targetRoles` delivers to
|
|
371
371
|
**nobody** — there is no implicit "everyone" fallback. To reach every
|
|
372
372
|
authenticated subscriber in the scope, say so explicitly with
|
|
373
373
|
`targetRoles: ['AUTHENTICATED']`. UPPERCASE pseudo-roles (`PUBLIC`,
|
|
@@ -119,7 +119,7 @@ The auto-mounted middleware is **secure by default** — anonymous WebSocket upg
|
|
|
119
119
|
|
|
120
120
|
The default gate only checks **whether** the caller is authenticated, not whether they're allowed in *this* room. For per-room authorization, the `access` field on the binding lets the compiler emit a path-scoped gate that runs your existing resource firewall + `read.access` pipeline before the WebSocket upgrade — no hand-written code, same status semantics as `GET /api/v1/<resource>/:id`.
|
|
121
121
|
|
|
122
|
-
### Per-room authorization via `access`
|
|
122
|
+
### Per-room authorization via `access`
|
|
123
123
|
|
|
124
124
|
```ts
|
|
125
125
|
// quickback/quickback.config.ts
|
|
@@ -149,13 +149,13 @@ bindings: {
|
|
|
149
149
|
},
|
|
150
150
|
|
|
151
151
|
// Multi-table feature: pin the gate to a specific table so the
|
|
152
|
-
// firewall + id query is unambiguous
|
|
152
|
+
// firewall + id query is unambiguous.
|
|
153
153
|
{
|
|
154
154
|
name: 'NotepadInteractions', className: 'NotepadInteractions', from: 'lib/NotepadInteractions',
|
|
155
155
|
access: { resource: { feature: 'interactions', table: 'interactions' } },
|
|
156
156
|
},
|
|
157
157
|
|
|
158
|
-
// Room keyed by a unique non-PK column
|
|
158
|
+
// Room keyed by a unique non-PK column. A Yjs page editor is
|
|
159
159
|
// addressed by `event_pages.yjsRoomId`, not the row id — `key` tells the
|
|
160
160
|
// gate which column the roomId matches.
|
|
161
161
|
{
|
|
@@ -188,7 +188,7 @@ What the compiler emits:
|
|
|
188
188
|
- **Multi-resource form** — same gate but with a regex parser dispatching to per-kind firewall lookups. Unknown kinds 400 at the gate. Each `resources[kind].resource` accepts either form (string shorthand or `{ feature, table, key? }`).
|
|
189
189
|
- **`access: { roomIdEquals: 'ctx.userId' }`** — an **identity gate** for rooms with no backing table, where the roomId *is* the caller's own id. Emits `app.use('/realtime/<kebab>/*', …)` that 401s anonymous, 400s a missing segment, and 403s unless the decoded room segment equals `ctx.userId`. No schema import, no firewall, no DB query — a string compare against the server-resolved `ctx`. Use `'ctx.activeOrgId'` for a per-org room. This is the right gate for per-user gateways, presence, or inbox DOs keyed on `ns.idFromName(ctx.userId)`. Only `'ctx.userId'` and `'ctx.activeOrgId'` are accepted (validated at compile time); anything else is a build error. Distinct from `resource` because there's no row to firewall — it closes the cross-user hole that "no `access` declared" leaves open (any authenticated user could otherwise open another user's room via the catchall).
|
|
190
190
|
- **`access: 'public'`** — `app.use('/realtime/<kebab>/*', …)` that just passes through. Use for anonymous game lobbies / public collab pads where the room itself is the unit of access.
|
|
191
|
-
- **No `access` declared** — falls through to the catchall `/realtime/*` gate that just checks `ctx.authenticated`.
|
|
191
|
+
- **No `access` declared** — falls through to the catchall `/realtime/*` gate that just checks `ctx.authenticated`.
|
|
192
192
|
|
|
193
193
|
Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table. When `key` is set, the column is checked against the pinned table's schema.
|
|
194
194
|
|
|
@@ -178,7 +178,7 @@ Events without an `externalId` (NULL) are not deduplicated. SQLite treats NULLs
|
|
|
178
178
|
|
|
179
179
|
### Migrating an existing deployment
|
|
180
180
|
|
|
181
|
-
|
|
181
|
+
If an existing deployment contains duplicate rows, drizzle-kit's unique-index migration will fail until they are cleaned up. Run this once before applying the migration:
|
|
182
182
|
|
|
183
183
|
```sql
|
|
184
184
|
DELETE FROM webhook_events
|
|
@@ -303,10 +303,3 @@ The MCP server always uses the latest installed version automatically.
|
|
|
303
303
|
- [Getting Started](/start/quickstart) - Get your first Quickback project running
|
|
304
304
|
- [Definitions Overview](/define) - Understand the security layer model
|
|
305
305
|
- [npm package](https://www.npmjs.com/package/@quickback-dev/cli) - CLI package
|
|
306
|
-
|
|
307
|
-
## Feedback
|
|
308
|
-
|
|
309
|
-
Found an issue with the AI tools integration?
|
|
310
|
-
|
|
311
|
-
- [GitHub Issues](https://github.com/kardoe/quickback/issues)
|
|
312
|
-
- [Quickback Documentation](https://docs.quickback.dev)
|
|
@@ -94,7 +94,7 @@ The server echoes the chosen version back as the response `X-Quickback-Stream` h
|
|
|
94
94
|
|
|
95
95
|
Multi-megabyte SPA bundles (CMS + Account, with sourcemaps) take long enough to `JSON.stringify` that the v1 single-frame `result` event blocks Cloudflare's container event loop. Two things break: Docker's `HEALTHCHECK` fails, and the CLI's 120-second connection timeout fires before the body flushes. v2 emits files one at a time and yields back to the event loop every 10 files (`setImmediate`), keeping `/health` responsive and TCP backpressure alive.
|
|
96
96
|
|
|
97
|
-
The `@quickback-dev/cli`
|
|
97
|
+
The `@quickback-dev/cli` sends `X-Quickback-Stream: v2` automatically.
|
|
98
98
|
|
|
99
99
|
### Event shapes (v2)
|
|
100
100
|
|
|
@@ -151,9 +151,9 @@ The compiler's output is a manifest of files to **write**. It has no way to say
|
|
|
151
151
|
|
|
152
152
|
For most moves that gap is invisible: the CLI wipes `src/` from the manifest
|
|
153
153
|
before each write, so relocating a file *within* `src/` cleans up after itself.
|
|
154
|
-
It bites the moment a path crosses that boundary
|
|
155
|
-
|
|
156
|
-
|
|
154
|
+
It bites the moment a path crosses that boundary. For example, spec blobs now
|
|
155
|
+
live in `src/apps/__quickback/spec/`; retired root copies can survive as
|
|
156
|
+
multi-MB orphans that tooling keeps reading.
|
|
157
157
|
|
|
158
158
|
So the compiler now also returns **retired paths** — things it used to emit and
|
|
159
159
|
no longer does — and the CLI deletes them:
|
|
@@ -172,9 +172,8 @@ unrecoverable while a missed one is only untidy:
|
|
|
172
172
|
actually in this compile's manifest. Disable the surface
|
|
173
173
|
(`openapi.generate: false`) and neither path is emitted, so nothing is
|
|
174
174
|
removed.
|
|
175
|
-
- A path the current manifest still writes is **never** deleted
|
|
176
|
-
|
|
177
|
-
its live output pulled out from under it.
|
|
175
|
+
- A path the current manifest still writes is **never** deleted, so live output
|
|
176
|
+
cannot be pulled out from under the compile.
|
|
178
177
|
- The CLI re-checks both conditions itself and refuses any path that would
|
|
179
178
|
escape the output directory.
|
|
180
179
|
|
|
@@ -342,6 +341,8 @@ reports/
|
|
|
342
341
|
The signature file uses HMAC-SHA256 when a signing key is configured, otherwise it falls back to SHA-256 digest mode.
|
|
343
342
|
Set `compiler.securityContracts.report.signature.required: true` to fail compilation when a signing key is missing.
|
|
344
343
|
|
|
344
|
+
The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
|
|
345
|
+
|
|
345
346
|
### Realtime
|
|
346
347
|
|
|
347
348
|
When any feature has `realtime` configured:
|
|
@@ -45,7 +45,7 @@ These run on `/auth/v1/admin/*`, emitted by Quickback because Better Auth's orga
|
|
|
45
45
|
|
|
46
46
|
The admin panel is restricted to platform roles on the Better Auth user record: **`appmanager`** (the control plane) and **`sysadmin`** (which adds cross-tenant data access on top). Everyone else is redirected away from `/admin`.
|
|
47
47
|
|
|
48
|
-
> **`role: "admin"` is not a platform role.** By default the compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]
|
|
48
|
+
> **`role: "admin"` is not a platform role.** By default the compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`. Migrate rows with `role: "admin"` to `"appmanager"`.
|
|
49
49
|
>
|
|
50
50
|
> A project that declares `plugins: { admin: { adminRoles, roles } }` gets **exactly** that: the declared `adminRoles` list and role → access-controller map are emitted verbatim (`appmanager: userAc` narrows the provisioning operator to no admin API at all; `adminRoles: ["sysadmin"]` keeps set-role / impersonate / ban for `sysadmin` only). The compiler never re-widens a declared role, and refuses a declaration it cannot honour.
|
|
51
51
|
|
|
@@ -16,7 +16,7 @@ Account UI provides a complete organization management interface when `VITE_ENAB
|
|
|
16
16
|
- Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
|
|
17
17
|
- Leave the organization
|
|
18
18
|
|
|
19
|
-
> **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/define/access) rules — with [`auth.roleHierarchy`](/define/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/define/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin
|
|
19
|
+
> **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/define/access) rules — with [`auth.roleHierarchy`](/define/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/define/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin, so `invite-member` / `update-member-role` accept them too.
|
|
20
20
|
|
|
21
21
|
## Invitations
|
|
22
22
|
|
|
@@ -207,7 +207,7 @@ The gates that carry real data:
|
|
|
207
207
|
|
|
208
208
|
Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
|
|
209
209
|
|
|
210
|
-
>
|
|
210
|
+
> `cms.access` accepts `"sysadmin"` or `"member"`. The retired `"admin"` and `"user"` spellings are rejected at compile time; migrate `"admin"` → `"sysadmin"` and `"user"` → `"member"`.
|
|
211
211
|
|
|
212
212
|
|
|
213
213
|
#### What a blocked caller actually sees
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Owned Records
|
|
2
|
+
|
|
3
|
+
A table that declares an [`owns` boundary](/define/changesets) gets its owned
|
|
4
|
+
children rendered **inline on the record page**: each relation appears as a
|
|
5
|
+
section below the record's fields, with a row table and Add / Edit / Delete
|
|
6
|
+
controls. Line items live on the expense report, not in a sidebar collection.
|
|
7
|
+
|
|
8
|
+
## When a relation renders
|
|
9
|
+
|
|
10
|
+
All three must hold — a relation missing any of them is skipped:
|
|
11
|
+
|
|
12
|
+
1. The relation is declared in the root's `owns`.
|
|
13
|
+
2. The relation name is in the root's `read.include` allowlist — reads ride
|
|
14
|
+
`GET /:id?include=<relation>`, and a non-allowlisted include is a 400.
|
|
15
|
+
3. The child table exists in the schema registry.
|
|
16
|
+
|
|
17
|
+
{/* doc-compile: skip — the fence is the owns + include wiring only; columns, firewall, guards, and the child table are elided. */}
|
|
18
|
+
```ts title="quickback/features/expenseReports/expenseReports.ts"
|
|
19
|
+
export default feature("expenseReports", {
|
|
20
|
+
// ...columns, firewall, guards, crud...
|
|
21
|
+
owns: {
|
|
22
|
+
lineItems: { table: "lineItems", fk: "reportId", inherit: ["organizationId"] },
|
|
23
|
+
},
|
|
24
|
+
read: {
|
|
25
|
+
access: { roles: ["member+"] },
|
|
26
|
+
include: ["lineItems"], // without this, the CMS has no way to read the rows
|
|
27
|
+
},
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Writes go through the changeset engine
|
|
32
|
+
|
|
33
|
+
Every Add, Edit, and Delete is a single-op
|
|
34
|
+
[changeset](/define/changesets) `PATCH` on the **root** —
|
|
35
|
+
`Content-Type: application/vnd.quickback.changeset+json` — never a raw child
|
|
36
|
+
route. The generated aggregate engine enforces the child's own access,
|
|
37
|
+
guards, body schema, and firewall on every op, and stamps the spine FK and
|
|
38
|
+
`inherit` columns from the firewall-verified parent row.
|
|
39
|
+
|
|
40
|
+
Consequences in the UI:
|
|
41
|
+
|
|
42
|
+
- The child's `fk` and `inherit` columns are **excluded from the form** — the
|
|
43
|
+
engine stamps them, and a client-supplied value is rejected.
|
|
44
|
+
- The Add / Edit / Delete buttons gate on the **child table's** `create` /
|
|
45
|
+
`update` / `delete` access for the signed-in role, exactly like the child's
|
|
46
|
+
own raw routes would.
|
|
47
|
+
- Child deletes are soft (changeset v1 admits soft-delete children only).
|
|
48
|
+
|
|
49
|
+
## `routes: false` children
|
|
50
|
+
|
|
51
|
+
The usual shape for a pure composition child — line items that only ever
|
|
52
|
+
exist inside a report — is `routes: false` on every op plus
|
|
53
|
+
`cms: { internal: true }`:
|
|
54
|
+
|
|
55
|
+
{/* doc-compile: skip — crud-op fragments without the surrounding table definition. */}
|
|
56
|
+
```ts title="quickback/features/expenseReports/lineItems.ts"
|
|
57
|
+
read: { access: { roles: ["member+"] }, routes: false },
|
|
58
|
+
create: { access: { roles: ["member+"] }, routes: false },
|
|
59
|
+
update: { access: { roles: ["member+"] }, routes: false },
|
|
60
|
+
delete: { access: { roles: ["member+"] }, routes: false, mode: "soft" },
|
|
61
|
+
|
|
62
|
+
cms: { internal: true }, // no standalone sidebar entry
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`routes: false` keeps the access declared (it is the changeset admission
|
|
66
|
+
gate) but mounts no raw HTTP route. The CMS reads the registry's
|
|
67
|
+
`routesDisabled` list and suppresses every raw-CRUD affordance for those ops
|
|
68
|
+
— New button, row Edit/Delete, record-page Edit/Delete, and inline cell
|
|
69
|
+
editing — so it never renders a button whose request can only 405. The
|
|
70
|
+
owned-records section is unaffected: its writes are changeset ops, which
|
|
71
|
+
`routes: false` deliberately leaves open.
|
|
72
|
+
|
|
73
|
+
Note the child's `read` access above is what gates the embedded rows:
|
|
74
|
+
`?include=` inherits the **target's** read access, firewall, and masking. A
|
|
75
|
+
child readable only by `admin+` renders an empty section for members.
|
|
76
|
+
|
|
77
|
+
## Next Steps
|
|
78
|
+
|
|
79
|
+
- **[Changesets](/define/changesets)** — the `owns` boundary and the wire contract
|
|
80
|
+
- **[Record Layouts](/ui/admin/record-layouts)** — grouping the root's own fields
|
|
81
|
+
- **[Schema Format](/ui/admin/schema-format)** — `ownsRelations`, `readInclude`, `routesDisabled`
|
|
@@ -62,6 +62,18 @@ interface TableMeta {
|
|
|
62
62
|
inputHints?: Record<string, string>;
|
|
63
63
|
layouts?: Record<string, CmsLayout>;
|
|
64
64
|
internal?: boolean;
|
|
65
|
+
ownsRelations?: Record<string, OwnsRelation>;
|
|
66
|
+
ownedBy?: string;
|
|
67
|
+
readInclude?: string[];
|
|
68
|
+
routesDisabled?: string[];
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
interface OwnsRelation {
|
|
72
|
+
table: string; // owned child table (camelCase registry name)
|
|
73
|
+
fk: string; // FK on the child pointing at this root — compiler-stamped
|
|
74
|
+
inherit?: string[]; // parent columns copied onto inserted children — compiler-stamped
|
|
75
|
+
refs?: Record<string, string>; // client-supplied pointers at independent entities
|
|
76
|
+
owns?: Record<string, OwnsRelation>; // nested owned relations
|
|
65
77
|
}
|
|
66
78
|
```
|
|
67
79
|
|
|
@@ -86,6 +98,10 @@ interface TableMeta {
|
|
|
86
98
|
| `inputHints` | Map of column name to preferred CMS input type (e.g., `"richtext"`, `"select"`, `"textarea"`, `"checkbox"`) |
|
|
87
99
|
| `layouts` | Named record page layouts keyed by layout name (see CmsLayout below) |
|
|
88
100
|
| `internal` | When `true`, table is hidden from CMS sidebar |
|
|
101
|
+
| `ownsRelations` | The [`owns`](/define/changesets) config verbatim — the CMS renders these as inline [owned-records sections](/ui/admin/owned-records) on the root's record page |
|
|
102
|
+
| `ownedBy` | Set on owned children: the aggregate-root table that owns this table |
|
|
103
|
+
| `readInclude` | The `read.include` allowlist — tokens fetchable via `?include=` |
|
|
104
|
+
| `routesDisabled` | Ops declared `routes: false` — access exists (changeset admission) but no raw HTTP route, so the CMS suppresses New/Edit/Delete buttons and inline editing for them |
|
|
89
105
|
|
|
90
106
|
## ColumnMeta
|
|
91
107
|
|