@quickback-dev/cli 0.66.4 → 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 +8 -8
- 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 +52 -9
- 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 +17 -11
- 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 +2 -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 +8 -8
- 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 +52 -9
- 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 +17 -11
- 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 +2 -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 -928
- 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 -928
- 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
|
@@ -348,6 +348,7 @@ so it can only ever carry the role the caller actually proved this request.
|
|
|
348
348
|
- A **multi-lane `via:`** (e.g. `via: ['attendeeOf', 'organizerOf']`) mints the matched lane's role — `attendeeOf` → `scope.event.roles = ['attendee']`, `organizerOf` → `['organizer']`. The resolver records which lane opened the gate, so there is no ambiguity.
|
|
349
349
|
- A **bulk-grant lane** (`{ roles: [...] }` or `{ team: true }`) mints **no** scope role — it opens the gate via the caller's org role without proving a relationship. The gate passes; the caller carries their org role, not a minted scope role.
|
|
350
350
|
- **The org claim is only ever signed beside a membership role.** Every mint site — `/scope/v1/enter`, the namespace resolver, `/api/v1/token` — writes `orgId` into the token only when a membership `role` accompanies it, and the auth middleware ignores an `orgId` claim that arrives without a `role`. A relationship-promoted tenant (the in-request `ctx.activeOrgId` stamped from the proven row so the firewall resolves) is never persisted as a bare tenant grant.
|
|
351
|
+
- **`/scope/v1/enter` drops the org claims for a foreign-tenant instance.** When the relationship's `from` table carries an organization column, the enter route reads it off the proven row (the same row the probe already fetched — no extra query) and compares it with `ctx.activeOrgId`. A mismatch — an org-B member entering an org-A event — mints the token **without** `orgId` / `role`: a relationship-only principal, exactly the state the namespace resolver gives the same caller. The caller keeps their org seat for org-B requests by using their session or a plain `/api/v1/token`; the scope token is for the scope. A `from` table with no organization column (a global reference relationship) leaves the claim untouched.
|
|
351
352
|
|
|
352
353
|
### The bulk-grant lane is tenant-bound
|
|
353
354
|
|
|
@@ -671,7 +672,7 @@ The scope claim is trusted between proofs — it is never re-checked against the
|
|
|
671
672
|
|
|
672
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:
|
|
673
674
|
|
|
674
|
-
- **`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).
|
|
675
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.
|
|
676
677
|
|
|
677
678
|
## Reference
|
package/dist/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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.66.
|
|
3
|
+
"version": "0.66.6",
|
|
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",
|
package/src/skill/SKILL.md
CHANGED
|
@@ -443,6 +443,4 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
443
443
|
- `claude-skill` / `claude-code` — this skill
|
|
444
444
|
- `cloud-compiler/{index,authentication,endpoints,local-compiler,troubleshooting}` — the hosted build service
|
|
445
445
|
|
|
446
|
-
**Other** — `docs/changelog/index.md`
|
|
447
|
-
|
|
448
446
|
For online navigation: <https://docs.quickback.dev>.
|
|
@@ -232,7 +232,7 @@ Or enable the in-project browser via the [`docs` config option](#interactive-api
|
|
|
232
232
|
|
|
233
233
|
Alongside the spec, every compile writes `reports/operations.manifest.json` — a
|
|
234
234
|
stable, machine-readable index of the full route surface (resource, action,
|
|
235
|
-
view,
|
|
235
|
+
view, auth, realtime, storage, and FGA routes, plus
|
|
236
236
|
surfaces):
|
|
237
237
|
|
|
238
238
|
```json
|
|
@@ -53,9 +53,9 @@ Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so
|
|
|
53
53
|
The short version, before the knob-by-knob detail:
|
|
54
54
|
|
|
55
55
|
- **Default: 180-second TTL, auto-refreshed.** Every authenticated call returns a fresh token via the `set-auth-token` header, so the low TTL is invisible to logged-in users. The worst-case window for a stolen or pre-revocation token is 3 minutes — and you can shrink it to 30 seconds with one config line.
|
|
56
|
-
- **Need revocation faster than the TTL?** Set [`revocationCheck: 'kv'`](#revocationcheck-none--kv--token-revocation-strategy). Revoked tokens are rejected within seconds; revocation stamps are written automatically on user ban, org-member removal, role change, and changes to scope-conferring relationship rows.
|
|
56
|
+
- **Need revocation faster than the TTL?** Set [`revocationCheck: 'kv'`](#revocationcheck-none--kv--token-revocation-strategy). Revoked tokens are rejected within seconds; revocation stamps are written automatically on sign-out and session revocation (per session), on password change with `revokeOtherSessions`, account deletion, user ban, org-member removal, role change, and changes to scope-conferring relationship rows. Long-lived tokens are therefore safe to pair with it: a remote "sign out everywhere" kills a lost device's bearer.
|
|
57
57
|
|
|
58
|
-
Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling
|
|
58
|
+
Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling.
|
|
59
59
|
|
|
60
60
|
### Behavior recap
|
|
61
61
|
|
|
@@ -130,24 +130,24 @@ Default `'none'`.
|
|
|
130
130
|
| `'none'` | No revocation check. Stolen / pre-revocation tokens valid until TTL expires (scope claims: until the carry-forward cap). Use a low `expiresIn` to bound the replay window. | 0 |
|
|
131
131
|
| `'kv'` | Fast-path checks per-principal revocation timestamps in the project's existing `KV` binding before trusting a verified token. Fails closed: an unreadable store means the bearer is not trusted. | 2+ KV reads (~5-15ms, edge-cached) |
|
|
132
132
|
|
|
133
|
-
`'kv'` (
|
|
133
|
+
`'kv'` (**Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
|
|
134
134
|
|
|
135
135
|
A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's proof time) is **at or before** the stored timestamp for any principal key it rides on:
|
|
136
136
|
|
|
137
137
|
| Key | Revokes | Written automatically on |
|
|
138
138
|
|---|---|---|
|
|
139
|
-
| `qbrev:
|
|
139
|
+
| `qbrev:sid:<sessionId>` | every JWT minted from one Better Auth session (tokens carry the minting session as `sid`) | `POST /sign-out` and `POST /revoke-session` (Better Auth endpoint hooks) — a lost device's token dies with its session while the user's other devices keep theirs |
|
|
140
|
+
| `qbrev:user:<userId>` | every JWT for the user | user ban (`databaseHooks.user.update.after` — flipping `banned` stamps the key and, when outbound webhooks are enabled, emits a `user.banned` event); `revoke-sessions`, `revoke-other-sessions`, `change-password` with `revokeOtherSessions`, and `delete-user` (endpoint hooks). Call `revokeUserTokens` for custom flows |
|
|
140
141
|
| `qbrev:member:<userId>:<orgId>` | the user's org-membership claims | member removal / role change (Better Auth `organizationHooks`) |
|
|
141
142
|
| `qbrev:scope:<userId>:<kind>:<id>` | the user's carried scope claim | UPDATE/DELETE of a scope-conferring relationship row (audit-wrapper chokepoint + the single DELETE route) |
|
|
142
143
|
|
|
143
|
-
`src/lib/jwt-revocation.ts` exports `revokeUserTokens` / `revokeMemberTokens` / `revokeScopeTokens` for explicit calls from actions. A rejected token falls through to session auth, which re-checks membership and re-mints — an active legitimate session recovers transparently.
|
|
144
|
+
`src/lib/jwt-revocation.ts` exports `revokeUserTokens` / `revokeSessionTokens` / `revokeMemberTokens` / `revokeScopeTokens` for explicit calls from actions. A rejected token falls through to session auth, which re-checks membership and re-mints — an active legitimate session recovers transparently.
|
|
144
145
|
|
|
145
146
|
Semantics worth knowing:
|
|
146
147
|
|
|
147
148
|
- **Revoke-on-touch for scopes:** any update or delete of a conferring row stamps the revocation, without evaluating whether the change actually ended the relationship. A false positive just forces a cheap re-prove (`/scope/v1/enter` or a minting namespace route).
|
|
148
149
|
- **Scope proof time is per kind:** a token can carry several scope kinds proven at different instants, so each entry carries its own proof stamp (`sctMs`, `m<ms>`) and is compared against its own marker. Proving one kind never restamps the others — re-entering `event` cannot bring a revoked `location` claim back to life. Entries minted before the release that added the stamp carry none, and fall back to the token-level `sct`/`sctMs` until they expire (bounded by the carry-forward cap plus one TTL).
|
|
149
|
-
- **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format
|
|
150
|
-
- **Do not straddle the v0.61.0 upgrade.** A worker from **before** v0.61.0 reads `m<ms>` markers as `NaN` and treats them as *no revocation at all* — not as a corrupt entry. So rolling back across this release, or pointing two differently-versioned deploy targets at one shared KV namespace, means every revocation written by the new version is **silently unenforced** by the old one until the entry expires (`ENTRY_TTL_SECONDS`, ~19 minutes at default settings). Upgrade all targets sharing a namespace together; if you must roll back, treat outstanding bearer tokens as unrevoked for that window — lower `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
|
|
150
|
+
- **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format marker, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, 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.
|
|
151
151
|
- **Fails closed:** a missing binding, a failed read, or a corrupt entry means the token's revocation state is *unknown* — and an unknown bearer is not authenticated. The caller gets `503 AUTH_REVOCATION_UNAVAILABLE` (RFC 9457, retryable). Recovery is a **separate cookie-only request**: a request carrying `Authorization` has its cookie stripped before session auth, so within that one request there is nothing left to fall back to. Reads are never silently skipped, because the outage that hides a revocation is exactly the moment this check exists for.
|
|
152
152
|
- **Availability coupling:** the flip side of the above. Bearer-token auth now depends on KV being readable. Alert on `AUTH_REVOCATION_UNAVAILABLE`; a sustained rate means the binding is missing on some deployment target, or KV is degraded. Every named environment must declare `bindings.kv` — the compiler rejects a target that doesn't.
|
|
153
153
|
- **Eventual consistency:** KV propagates cross-PoP in ~60s. "Immediate" means seconds at the writing location, bounded-seconds globally — still far inside the 15-minute carry-forward cap that bounds revocation without this check.
|
|
@@ -194,7 +194,7 @@ The `?redirect=…` query param is preserved unchanged so the central sign-in su
|
|
|
194
194
|
|
|
195
195
|
Signing in is the *only* thing the CMS gate redirects for. A signed-in caller who isn't admitted is served the CMS shell and shown a screen naming what they'd need — see [CMS access](/ui/admin#access-gate). There is no wrong-role redirect, and no `auth.profileUrl`.
|
|
196
196
|
|
|
197
|
-
>
|
|
197
|
+
> `auth.profileUrl` is not supported. The config schema is strict, so a `profileUrl` key fails the compile — delete it.
|
|
198
198
|
|
|
199
199
|
|
|
200
200
|
### Resolution precedence
|
|
@@ -280,7 +280,7 @@ EXTRA_APP_HOSTS = "app-preview.example.com,pr-42.example.com"
|
|
|
280
280
|
wrangler secret put EXTRA_APP_HOSTS --env preview
|
|
281
281
|
```
|
|
282
282
|
|
|
283
|
-
Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`.
|
|
283
|
+
Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`.
|
|
284
284
|
|
|
285
285
|
> **Multi-app deploys**
|
|
286
286
|
>
|
|
@@ -145,7 +145,7 @@ a compile error; delete that line and keep `routes`. See
|
|
|
145
145
|
[API Contract](/platform/api-contract#contractversion-is-retired) for what
|
|
146
146
|
changes if you were pinned to `version: "v1"`.
|
|
147
147
|
|
|
148
|
-
Action input-schema fidelity is a compile gate
|
|
148
|
+
Action input-schema fidelity is a compile gate. The CLI must
|
|
149
149
|
successfully harvest `z.toJSONSchema(action.input)` for every authored action;
|
|
150
150
|
partial or missing harvests fail with the exact action file keys, bundle or
|
|
151
151
|
evaluation phase, and underlying local error. Dependencies are resolved from
|
|
@@ -433,7 +433,7 @@ action layer.
|
|
|
433
433
|
|
|
434
434
|
Quickback manages four **audit columns** (`createdAt`, `modifiedAt`, `createdBy`, `modifiedBy`) on every feature table, plus two **soft-delete columns** (`deletedAt`, `deletedBy`) on tables whose resource uses soft delete (the default delete mode). The audit columns drive record-provenance queries and the CMS audit panel; the soft-delete pair drives soft-delete filtering.
|
|
435
435
|
|
|
436
|
-
You declare them in the table's `columns` object with `...q.audit()` and `...q.softDelete()`. The compiler validates every managed column against its canonical shape and fails the compile when one is missing, diverges, or is present on a hard-delete table — run `quickback migrate visible-columns` to adopt the declarations on an existing project. Set `compiler.features.visibleAuditColumns: false` to downgrade those checks to warnings and
|
|
436
|
+
You declare them in the table's `columns` object with `...q.audit()` and `...q.softDelete()`. The compiler validates every managed column against its canonical shape and fails the compile when one is missing, diverges, or is present on a hard-delete table — run `quickback migrate visible-columns` to adopt the declarations on an existing project. Set `compiler.features.visibleAuditColumns: false` to downgrade those checks to warnings and silently inject the columns.
|
|
437
437
|
|
|
438
438
|
To opt out of the managed columns entirely, project-wide:
|
|
439
439
|
|
|
@@ -485,7 +485,7 @@ export default defineConfig({
|
|
|
485
485
|
|
|
486
486
|
If `signature.required: true` and no key is available, compilation fails with a clear error message (or warning in `failMode: "warn"`).
|
|
487
487
|
|
|
488
|
-
## Hostname architecture
|
|
488
|
+
## Hostname architecture
|
|
489
489
|
|
|
490
490
|
A modern Quickback project runs on **one Cloudflare Worker** that serves multiple URL surfaces. By default, everything lives under a single unified backend hostname (auto-inferred as `quickback.{baseDomain}` from your other configured subdomains, or overridable via `config.domain`). For larger deployments, you can opt-in to **dedicated hostnames** for specific surfaces — they're additive aliases, never replacements.
|
|
491
491
|
|
|
@@ -515,7 +515,7 @@ For branding or operational separation, you can opt specific surfaces onto their
|
|
|
515
515
|
cms: { domain: 'cms.example.com' },
|
|
516
516
|
account: { domain: 'account.example.com' },
|
|
517
517
|
|
|
518
|
-
//
|
|
518
|
+
// Backend surfaces on their own hosts:
|
|
519
519
|
auth: { domain: 'auth.example.com' },
|
|
520
520
|
api: { domain: 'api.example.com' },
|
|
521
521
|
|
|
@@ -118,7 +118,7 @@ The compiler applies these so config stays minimal:
|
|
|
118
118
|
- **`X-Frame-Options` derives from `csp.frameAncestors`** (`['@none']` → `DENY`, contains `@self` → `SAMEORIGIN`, otherwise omitted — XFO can't represent arbitrary origins so CSP becomes the truth there). Override with `security.frameOptions`.
|
|
119
119
|
- **`corp: 'same-origin'` is auto-emitted when `coep` is set.** `require-corp` without CORP breaks the ASSETS binding fetches on Cloudflare; the compiler couples them so users don't have to remember.
|
|
120
120
|
|
|
121
|
-
### CSP auto-config
|
|
121
|
+
### CSP auto-config
|
|
122
122
|
|
|
123
123
|
When you opt into a `csp` object, the compiler additively widens directives based on which Quickback features your project has enabled. **Additive** means anything you already wrote stays; we only push values that aren't already present.
|
|
124
124
|
|
|
@@ -140,7 +140,7 @@ font-src 'self' https://fonts.gstatic.com
|
|
|
140
140
|
connect-src 'self' @trustedOrigins https://api.your-app.com
|
|
141
141
|
```
|
|
142
142
|
|
|
143
|
-
Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened with style-only or connect-only hosts — that would let those hosts also reach `script-src` / `img-src` / `media-src` via fall-back, which is wider than the bundled SPA actually needs.
|
|
143
|
+
Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened with style-only or connect-only hosts — that would let those hosts also reach `script-src` / `img-src` / `media-src` via fall-back, which is wider than the bundled SPA actually needs.
|
|
144
144
|
|
|
145
145
|
**Visibility:** every applied addition prints to stderr at compile time — one line per addition with the directive, value, and reason. No silent magic. Loop's compile output now looks like:
|
|
146
146
|
|
|
@@ -155,7 +155,7 @@ Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened
|
|
|
155
155
|
|
|
156
156
|
#### Why the SPA-baked origin shows up capitalised in CSP
|
|
157
157
|
|
|
158
|
-
Projects with `domain: "..."` + bundled CMS / Account SPAs will see `connect-src 'self' https://Api.example.com …` in their served CSP — note the capital `A`. That's deliberate
|
|
158
|
+
Projects with `domain: "..."` + bundled CMS / Account SPAs will see `connect-src 'self' https://Api.example.com …` in their served CSP — note the capital `A`. That's deliberate and works around a `wrangler dev` quirk, not a typo on our end.
|
|
159
159
|
|
|
160
160
|
`wrangler dev` rewrites the configured `custom_domain` host string in **every** response header value (Location, Content-Security-Policy, X-…) to the local hostname, with a case-sensitive substring matcher. Without the case-shift, the served CSP becomes `connect-src 'self' https://localhost:8787 …` and the bundled SPA's hardcoded `VITE_QUICKBACK_API_URL` fetches get blocked because the prod URL no longer appears in the allowlist.
|
|
161
161
|
|
|
@@ -100,7 +100,7 @@ any lowercase role name you reference in an access tree (`"recruiter"`,
|
|
|
100
100
|
`"hiring-manager"`, `"support"`, …) is a custom org-membership role, matched
|
|
101
101
|
against `ctx.roles` like the built-ins.
|
|
102
102
|
|
|
103
|
-
|
|
103
|
+
Custom roles declared in access trees are **auto-registered
|
|
104
104
|
with the Better Auth organization plugin**, so members can actually be
|
|
105
105
|
provisioned into them: `invite-member` and `update-member-role` accept them
|
|
106
106
|
(previously they rejected custom roles with `400 ROLE_NOT_FOUND`).
|
|
@@ -132,6 +132,26 @@ interface Access {
|
|
|
132
132
|
}
|
|
133
133
|
```
|
|
134
134
|
|
|
135
|
+
### An empty list is a compile error
|
|
136
|
+
|
|
137
|
+
`roles: []`, `userRole: []`, and `principals: []` are refused at compile
|
|
138
|
+
time, on every access node — CRUD operations, `read`, views, actions, and
|
|
139
|
+
the arms of `or` / `and`. The runtime evaluator treats an empty list as
|
|
140
|
+
"no gate on this axis", so an arm that names nobody would admit **every
|
|
141
|
+
authenticated caller**. Masking uses the same literal the other way round
|
|
142
|
+
(`show: { roles: [] }` shows nobody), which is exactly why the compiler will
|
|
143
|
+
not guess here. Say what you mean:
|
|
144
|
+
|
|
145
|
+
{/* doc-compile: skip — config fragments, not a compilable project */}
|
|
146
|
+
```typescript
|
|
147
|
+
create: { access: { userRole: ['sysadmin'] } } // closed to everyone but platform admins
|
|
148
|
+
// or omit `create` entirely — the route is not emitted
|
|
149
|
+
read: { access: { roles: ['AUTHENTICATED'] } } // every signed-in caller really is the audience
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Every empty arm in the project is listed in one compile error, so a project
|
|
153
|
+
fixes them all in one pass.
|
|
154
|
+
|
|
135
155
|
## `userRole` vs `roles`
|
|
136
156
|
|
|
137
157
|
`roles` and `userRole` check **two different fields** and are often confused — get this wrong and you'll grant access too broadly.
|
|
@@ -200,7 +220,7 @@ access: { roles: ["PUBLIC"] }
|
|
|
200
220
|
- `PUBLIC` skips authentication and role checks — anyone can call the endpoint
|
|
201
221
|
- **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, top-level writes (`create`/`update`/`delete`/`upsert`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous write endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
|
|
202
222
|
- **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
|
|
203
|
-
- **Tree semantics:** `PUBLIC` admits anonymous callers from anywhere in the access tree, not just a flat `roles` list. An `or:` arm containing `PUBLIC` admits anonymous callers past the authentication gate; an `and:` group admits them only when *every* arm does. The access, org, and firewall layers still evaluate the full tree afterwards.
|
|
223
|
+
- **Tree semantics:** `PUBLIC` admits anonymous callers from anywhere in the access tree, not just a flat `roles` list. An `or:` arm containing `PUBLIC` admits anonymous callers past the authentication gate; an `and:` group admits them only when *every* arm does. The access, org, and firewall layers still evaluate the full tree afterwards.
|
|
204
224
|
- Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
|
|
205
225
|
- The wildcard `"*"` is **not supported** — using it throws a compile-time error
|
|
206
226
|
- Tables with no isolation columns and any `PUBLIC` route do not require `firewall: [{ exception: true }]`
|
|
@@ -330,7 +350,7 @@ Use one of these instead:
|
|
|
330
350
|
|
|
331
351
|
#### `SYSADMIN` — cross-tenant DB-admin tier
|
|
332
352
|
|
|
333
|
-
Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platform sysadmins — the cross-tenant DB-admin tier
|
|
353
|
+
Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platform sysadmins — the cross-tenant DB-admin tier. Compiles to `ctx.userRole === "sysadmin"`. **Requires `cms: { sysadmin: true }` on the project config**; without that flag, using `SYSADMIN` fails the compile so the role can't sit as dead code.
|
|
334
354
|
|
|
335
355
|
```typescript
|
|
336
356
|
// Cross-tenant audit dashboard, sysadmin-only
|
|
@@ -413,12 +433,35 @@ opaque 404 instead.
|
|
|
413
433
|
|
|
414
434
|
Function-form access (`access: async (ctx, record) => ...`) is opaque to
|
|
415
435
|
the pre-record phase and always passes there; it's fully evaluated post-record.
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
436
|
+
It is accepted on `create` / `update` / `delete`, where the generated route
|
|
437
|
+
references it at runtime. It is **not** accepted as `read.access`: the
|
|
438
|
+
generated `GET /:id` route serialises the read tree inline, so a function
|
|
439
|
+
there is a compile error naming the resource. Express read rules
|
|
440
|
+
declaratively (`roles`, `userRole`, `record`, `or`, `and`).
|
|
441
|
+
|
|
442
|
+
### Collection routes honour `access.record` too
|
|
443
|
+
|
|
444
|
+
`GET /`, the per-view lists, and the generated MCP list tool fold the same
|
|
445
|
+
`record:` predicates into the query's `WHERE`, arm for arm, so a list can never
|
|
446
|
+
return a row the caller could not `GET` one at a time:
|
|
447
|
+
|
|
448
|
+
- Each `or` arm whose role / `userRole` gates admit the caller contributes its
|
|
449
|
+
`record` predicates as one AND-group; the groups are OR'd together.
|
|
450
|
+
- An admitted arm with **no** `record` block lifts the constraint for the
|
|
451
|
+
whole list (that arm would admit every row on `GET /:id` as well).
|
|
452
|
+
- A `$ctx.` value that is absent for the caller (no `activeOrgId`, no
|
|
453
|
+
`scope`) makes that arm unsatisfiable — it denies, never matches.
|
|
454
|
+
- A predicate on a column the table does not have yields no rows.
|
|
455
|
+
- No admitted arm at all → `403` from the role gate, as before.
|
|
456
|
+
|
|
457
|
+
`POST /batch` runs the same per-record check single `POST` does
|
|
458
|
+
(`record:` against each input body), and rejects the offending records
|
|
459
|
+
individually in the batch `errors` array.
|
|
460
|
+
|
|
461
|
+
Row scoping by tenant is still the [firewall's](/define/firewall) job; an
|
|
462
|
+
unsatisfiable predicate (`record: { id: { equals: "__never__" } }`) now hides
|
|
463
|
+
every row on every read surface, which is a legitimate way to give a resource
|
|
464
|
+
a get-only or write-only surface. To give it no read surface at all, omit
|
|
422
465
|
`read` — no list, get, batch, or MCP route is emitted.
|
|
423
466
|
|
|
424
467
|
## Context Variables
|
|
@@ -115,8 +115,8 @@ Zod 4's `z.toJSONSchema`. It does not call `execute`; the hosted compiler never
|
|
|
115
115
|
evaluates project code. The output contract feeds OpenAPI and
|
|
116
116
|
`Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
|
|
117
117
|
|
|
118
|
-
**Every action input must produce a schema.**
|
|
119
|
-
|
|
118
|
+
**Every action input must produce a schema.** A failed harvest fails the
|
|
119
|
+
compile, naming the exact action, whether
|
|
120
120
|
bundling or evaluation failed, and the underlying local error. Output remains
|
|
121
121
|
optional.
|
|
122
122
|
|
|
@@ -17,7 +17,7 @@ POST /applications/:id/schedule-interview
|
|
|
17
17
|
1. **Authentication** - User token is validated
|
|
18
18
|
2. **Input Validation** - Request body validated against Zod schema
|
|
19
19
|
3. **Role Gate** - The access roles are checked *before* the record is
|
|
20
|
-
fetched
|
|
20
|
+
fetched, so a wrong-role caller gets a uniform
|
|
21
21
|
`403 ACCESS_ROLE_REQUIRED` whether or not the record exists — the
|
|
22
22
|
response can't be used to probe for record ids
|
|
23
23
|
4. **Record Loading** - The record is fetched by ID **through the firewall**
|
|
@@ -420,4 +420,3 @@ imply "this writes data" — it's the right method whenever the request body is
|
|
|
420
420
|
load-bearing. Use the response shape (`responseType: "json"`, or just the data
|
|
421
421
|
your handler returns) to convey read semantics; HTTP method choice is about
|
|
422
422
|
input transport, not action intent.
|
|
423
|
-
|