@quickback-dev/cli 0.54.0 → 0.55.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +41 -4
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/create.d.ts.map +1 -1
- package/dist/commands/create.js +5 -1
- package/dist/commands/create.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +37 -22
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +16 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +21 -1
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +122 -3
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/api-client.d.ts +11 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +3 -0
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/compiler-floor.d.ts +39 -0
- package/dist/lib/compiler-floor.d.ts.map +1 -0
- package/dist/lib/compiler-floor.js +75 -0
- package/dist/lib/compiler-floor.js.map +1 -0
- package/dist/lib/compiler-floor.test.d.ts +2 -0
- package/dist/lib/compiler-floor.test.d.ts.map +1 -0
- package/dist/lib/compiler-floor.test.js +67 -0
- package/dist/lib/compiler-floor.test.js.map +1 -0
- package/dist/lib/compiler-stubs.d.ts +6 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +8 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/file-loader.d.ts +45 -4
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +116 -19
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +80 -4
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/SKILL.md +3 -1
- package/dist/skill/docs/changelog.md +66 -0
- package/dist/skill/docs/compiler/config/index.md +14 -1
- package/dist/skill/docs/compiler/config/providers.md +13 -9
- package/dist/skill/docs/compiler/definitions/access.md +134 -2
- package/dist/skill/docs/compiler/definitions/actions.md +22 -0
- package/dist/skill/docs/compiler/definitions/changesets.md +375 -0
- package/dist/skill/docs/compiler/definitions/feature-areas.md +189 -0
- package/dist/skill/docs/compiler/definitions/feature.md +33 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +60 -1
- package/dist/skill/docs/compiler/definitions/guards.md +14 -0
- package/dist/skill/docs/compiler/definitions/index.md +28 -3
- package/dist/skill/docs/compiler/definitions/masking.md +8 -0
- package/dist/skill/docs/compiler/definitions/read.md +13 -0
- package/dist/skill/docs/compiler/definitions/schema.md +36 -1
- package/dist/skill/docs/compiler/definitions/scopes.md +23 -1
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +27 -28
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +2 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +49 -17
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +66 -0
- package/dist/skill/docs/stack/api-contract/index.md +136 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +7 -0
- package/dist/skill/docs/stack/realtime/index.md +22 -0
- package/dist/skill/docs/stack/realtime/live-views.md +56 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +53 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +79 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +33 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +3 -1
- package/src/skill/docs/changelog.md +66 -0
- package/src/skill/docs/compiler/config/index.md +14 -1
- package/src/skill/docs/compiler/config/providers.md +13 -9
- package/src/skill/docs/compiler/definitions/access.md +134 -2
- package/src/skill/docs/compiler/definitions/actions.md +22 -0
- package/src/skill/docs/compiler/definitions/changesets.md +375 -0
- package/src/skill/docs/compiler/definitions/feature-areas.md +189 -0
- package/src/skill/docs/compiler/definitions/feature.md +33 -0
- package/src/skill/docs/compiler/definitions/firewall.md +60 -1
- package/src/skill/docs/compiler/definitions/guards.md +14 -0
- package/src/skill/docs/compiler/definitions/index.md +28 -3
- package/src/skill/docs/compiler/definitions/masking.md +8 -0
- package/src/skill/docs/compiler/definitions/read.md +13 -0
- package/src/skill/docs/compiler/definitions/schema.md +36 -1
- package/src/skill/docs/compiler/definitions/scopes.md +23 -1
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +27 -28
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +2 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +49 -17
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +66 -0
- package/src/skill/docs/stack/api-contract/index.md +136 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +7 -0
- package/src/skill/docs/stack/realtime/index.md +22 -0
- package/src/skill/docs/stack/realtime/live-views.md +56 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +53 -0
- package/src/skill/docs/stack/webhooks/inbound.md +79 -0
- package/src/skill/docs/stack/webhooks/outbound.md +33 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.55.1",
|
|
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
|
@@ -313,6 +313,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
313
313
|
- `views` — named projections with column-level access
|
|
314
314
|
- `triggers` — Postgres-style table triggers: `sql:` → real SQLite trigger (all write paths, atomic), `handler:` → app hook at the write chokepoint (before mutate/reject, awaited after)
|
|
315
315
|
- `actions` — record-based vs standalone, transitions, `unsafe:`, `whereRecord(table)`, `ActionError`, `authDb`
|
|
316
|
+
- `changesets` — `owns` composition boundary; atomic parent+children writes via the changeset media type (lids, If-Match, Problem pointers)
|
|
316
317
|
- `validation` — minLength, max, enum, pattern, email
|
|
317
318
|
- `concepts` — secure-by-default, defense in depth, request flow
|
|
318
319
|
- `scopes` — relationship-derived scopes (`ctx.scope.*`), scoped roles, JWT claims
|
|
@@ -338,7 +339,8 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
338
339
|
- `realtime` — Durable Objects, WebSocket
|
|
339
340
|
- `queues` — handlers, retries, dead-letter
|
|
340
341
|
- `vector/embeddings` — auto-embedding columns, semantic search
|
|
341
|
-
- `webhooks/{inbound,outbound}` —
|
|
342
|
+
- `webhooks/{inbound,outbound}` — compile-declared inbound verification (`standard-webhooks` / `hmac-sha256` / `aws-sns`), Standard Webhooks-signed retried outbound
|
|
343
|
+
- `api-contract` — the HTTP contract layer: RFC 9457 Problem Details, keyset cursors, `Idempotency-Key`, `?include=`/sparse fields, the contract `v1`→`v2` matrix
|
|
342
344
|
- `push` — Web Push (VAPID + aes128gcm), queue fan-out, identity-tag targeting, hardened subscriptions schema
|
|
343
345
|
- `cms` — schema-driven admin UI, dashboard, record layouts, table views, schema registry
|
|
344
346
|
- `account-ui` — login, profile, orgs, admin, passkeys, API keys, CLI authorize, with Quickback or standalone
|
|
@@ -1,5 +1,71 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Feature areas — hierarchical authz grouping (`_area.ts`)
|
|
6
|
+
|
|
7
|
+
A folder under `features/` carrying an `_area.ts` (`export default defineArea({...})`) is now
|
|
8
|
+
an **area**: it declares a route prefix + admission lanes (the same shape as a project
|
|
9
|
+
namespace, incl. `mintScope`/`acceptScope`) and an authz vocabulary — relationships, composed
|
|
10
|
+
roles, named gates, tenant anchors, scope kinds — that every feature inside the folder
|
|
11
|
+
references by bare name. The vocabulary is visible to the area's subtree ONLY: the compiler
|
|
12
|
+
checks every reference channel (access roles/gates/scoped aliases, action `access`/`anchor`,
|
|
13
|
+
firewall `via`/`{ rule }`/`{ tenant }` arms, `ctx.scope.<kind>` accessors, auth-view tenant
|
|
14
|
+
includes, realtime handshake roles, table-level namespace lanes, and other `_area.ts` nodes)
|
|
15
|
+
and fails the build on any outside reference. Root `authz` stays the global level, and root
|
|
16
|
+
bodies may reference root-declared names only (no laundering an area name project-wide).
|
|
17
|
+
|
|
18
|
+
Fail-closed rules shipped with it: re-declaring an inherited name is a compile error (no
|
|
19
|
+
overrides in v1); a descendant action whose path opts out of the area prefix must carry an
|
|
20
|
+
explicit `route: 'self'` marker; relative `path: './…'` resolves against the area prefix with
|
|
21
|
+
dot segments rejected; foreign features can't claim paths (or table-level namespace prefixes)
|
|
22
|
+
under an area's prefix; nested areas may add vocabulary but not mount a second prefix under a
|
|
23
|
+
mounted ancestor (unlinked parent/child admission never compiles); and area-tree projects
|
|
24
|
+
must declare `requires: ['feature-areas']` — the marker reaches the compiler through ANY CLI
|
|
25
|
+
version, so an area-unaware toolchain is rejected instead of silently dropping nested
|
|
26
|
+
features. Area projects also emit a reviewed audit artifact, `quickback/authz-manifest.json`
|
|
27
|
+
(area tree, declared names, member features, area-gated vs self-gated actions, root-config
|
|
28
|
+
namespace consumers), and the generated `AGENTS.md` gains a feature-areas section.
|
|
29
|
+
|
|
30
|
+
Byte-parity guarantee: a flat root-authz project re-expressed as an area tree compiles to
|
|
31
|
+
byte-identical output (the emit-site key-order determinism pass from v2 step 0 makes the fold
|
|
32
|
+
order provably irrelevant). See [Feature areas](/compiler/definitions/feature-areas).
|
|
33
|
+
|
|
34
|
+
One cosmetic side effect of that determinism pass: the first recompile of an existing project
|
|
35
|
+
on this release may reorder generated relationship-table **import lines** (they are now
|
|
36
|
+
emitted in sorted order instead of authz-map insertion order). The reordering is a one-time,
|
|
37
|
+
behavior-free diff.
|
|
38
|
+
|
|
39
|
+
### Access rules: named gates (`authz.rules`) and tenant anchors (`authz.tenants`)
|
|
40
|
+
|
|
41
|
+
Two new root-`authz` blocks let you declare a row/role rule once and stamp it by name instead
|
|
42
|
+
of copying predicates across files. A **named gate** in `authz.rules` bundles up to three
|
|
43
|
+
arms — `who` (roles), `record:` (record-aware predicates), and `firewall` lanes — under one
|
|
44
|
+
name, referenced by bare name in any `access: { roles: [...] }` array (applies who + record)
|
|
45
|
+
and as `{ rule: '<name>' }` in a resource's `firewall:` (splices the lanes into the top-level
|
|
46
|
+
AND array — a reference can only *narrow* row admission, never widen it). A **tenant anchor**
|
|
47
|
+
in `authz.tenants` names the tenant predicate (`{ column, equals }`, claim side locked to
|
|
48
|
+
verified ctx claims) and is written `{ tenant: 'org' }` in firewalls — with an optional
|
|
49
|
+
per-site column override — and `tenant: 'org'` in auth-view includes. Expansion happens at
|
|
50
|
+
compile time; emitted SQL is byte-identical to the inline spelling.
|
|
51
|
+
|
|
52
|
+
Everything fails closed: gate/role/scoped-role/`+`/`:` name collisions, `+` hierarchy sugar
|
|
53
|
+
inside rule bodies, `{ rule }` inside `all`/`any` groups, firewall-less gates referenced from
|
|
54
|
+
`firewall:`, firewall-bearing gates on actions or in `masking.show`, and an access-side
|
|
55
|
+
reference to a firewall-bearing gate whose lanes the resource doesn't also stamp are all
|
|
56
|
+
compile errors. Gates in `realtime.requiredRoles` lower to static who-roles at the handshake;
|
|
57
|
+
a declared non-empty list that lowers to nothing is a compile error, never a silent `[]`. A
|
|
58
|
+
new `AUTHZ_UNKNOWN_ROLE_NAME` warning flags reference-shaped names that resolve to nothing.
|
|
59
|
+
See [named gates](/compiler/definitions/access#named-gates-authzrules) ·
|
|
60
|
+
[`{ tenant }`](/compiler/definitions/firewall#named-tenant-anchors-tenant) ·
|
|
61
|
+
[`{ rule }`](/compiler/definitions/firewall#named-gate-references-rule).
|
|
62
|
+
|
|
63
|
+
## v0.55.0 — July 17, 2026
|
|
64
|
+
|
|
65
|
+
### Generated projects ship an `AGENTS.md`
|
|
66
|
+
|
|
67
|
+
Every compiled project now emits an `AGENTS.md` at its root — the file coding agents read first — weaving Quickback's security model and a *"when to use what"* decision guide into the output. An agent editing the features is steered to the right primitive: a **view** for a filtered read, a **transition** for a guarded state change, an **action** for custom logic, **guards**/**masking** for field-level control, **named invalidations** for realtime refresh — each with a `docs.quickback.dev` link. It also documents the access tiers (incl. `SESSION`/`SCOPED`), the `WHERE column = value` firewall model with the org-OR-scope `{ any: [...] }` pattern for non-org callers, and the fail-closed coherence guardrail (with the *"never `exception: true` as a workaround"* rule). Regenerated on every compile.
|
|
68
|
+
|
|
3
69
|
## v0.54.0 — July 17, 2026
|
|
4
70
|
|
|
5
71
|
### Realtime: named invalidations
|
|
@@ -97,7 +97,8 @@ Every optional top-level key the config accepts is listed below. You never have
|
|
|
97
97
|
| `contract` | `{ version?: "v1" \| "v2" }` | Public API/auth contract version. Omit for the backward-compatible v1 default; select v2 for `/api/v2/*` and `/auth/v2/*` across generated routes, Better Auth, OpenAPI, MCP, and discovery. |
|
|
98
98
|
| `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/compiler/config/domains) |
|
|
99
99
|
| `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`/`profileUrl`, `domain`) — see [Access](/compiler/definitions/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
|
|
100
|
-
| `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `permissions`, `arrows`) — see [Permissions](/compiler/definitions/permissions) |
|
|
100
|
+
| `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/compiler/definitions/access#centrally-defined-access-rules) and [Permissions](/compiler/definitions/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/compiler/definitions/feature-areas) (`_area.ts`), and root bodies may reference root-declared names only |
|
|
101
|
+
| `requires` | `string[]` | Capability floor (fail-closed guard). Declare `['feature-areas']` when the project uses `features/**/_area.ts` — an area-unaware CLI/compiler then refuses the compile instead of silently dropping nested features. See [Feature areas](/compiler/definitions/feature-areas#the-capability-floor-requires-feature-areas) |
|
|
101
102
|
| `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
|
|
102
103
|
| `features` | `object` | Feature flags such as `organizations` / `pinnedOrganizationId` — see [Pinned Organization Mode](/compiler/config/single-tenant) |
|
|
103
104
|
| `cms` | `boolean \| object` | Embed CMS in compiled Worker (`domain`, `access`, `sysadmin`) — see [CMS](/stack/cms) |
|
|
@@ -149,6 +150,18 @@ the same invariant at its shared input boundary, including
|
|
|
149
150
|
`POST /compile?complete=false`, so validation-only or raw API calls cannot
|
|
150
151
|
bypass it. V1 retains the historical best-effort static-schema fallback.
|
|
151
152
|
|
|
153
|
+
The version selection also moves the event and read surfaces:
|
|
154
|
+
|
|
155
|
+
| Surface | v1 (pinned) | v2 (flagship) |
|
|
156
|
+
|---|---|---|
|
|
157
|
+
| Realtime data frames (`/broadcast/*`) | raw frames, byte-stable | CloudEvents 1.0 envelopes at DO egress ([realtime](/stack/realtime)) |
|
|
158
|
+
| Outbound webhook signing | Standard Webhooks headers **plus** legacy `X-Webhook-*` | Standard Webhooks **only** |
|
|
159
|
+
| `?include=` FK-graph embedding | not available | available where a resource/view allowlists it |
|
|
160
|
+
| Bare `?fields=` / `fields[<fk>]=` unknown names | silent drop / n/a | 400 on both |
|
|
161
|
+
|
|
162
|
+
See [API Contract](/stack/api-contract) for the full v1 → v2 matrix and
|
|
163
|
+
migration sequencing.
|
|
164
|
+
|
|
152
165
|
## Delegated principals (contract v2)
|
|
153
166
|
|
|
154
167
|
`auth.principals` defines non-account authority such as an event pass or a
|
|
@@ -223,6 +223,13 @@ providers: {
|
|
|
223
223
|
- `requestField`: the JSON body field the client posts to `/broadcast/v1/ws-ticket`
|
|
224
224
|
- `scopeTable`: the parent resource table that defines the broadcast scope key
|
|
225
225
|
|
|
226
|
+
Instead of `access`, `wsTicket` may name a **namespace** (`namespace: "eventScope"`) to
|
|
227
|
+
authorize through that namespace's full multi-lane `via` — including a namespace declared by
|
|
228
|
+
a [feature area](/compiler/definitions/feature-areas)'s `_area.ts` (the one root-config
|
|
229
|
+
surface allowed to reference an area-declared name; it attaches the area's complete gate and
|
|
230
|
+
is listed in the authz manifest under the owning area). See
|
|
231
|
+
[Namespace-backed tickets](/stack/realtime/durable-objects#namespace-backed-tickets-per-matched-lane).
|
|
232
|
+
|
|
226
233
|
In other words: the declared gate proves access, and the `scopeTable` row defines the channel. For an attendee flow, `guests` (or RSVP) would be the relationship evidence and `events` would be the `scopeTable`; see [Realtime](/stack/realtime#enabling-realtime) for the full per-arm semantics.
|
|
227
234
|
|
|
228
235
|
Quickback keeps Better Auth as the front door, then mints its own 60-second websocket ticket after the authz check succeeds. The generated `createRealtime()` helper and Broadcaster share the same targeting model:
|
|
@@ -232,9 +239,8 @@ Quickback keeps Better Auth as the front door, then mints its own 60-second webs
|
|
|
232
239
|
|
|
233
240
|
See [Realtime](/stack/realtime) for the client-side connection flow and helper examples.
|
|
234
241
|
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
</Callout>
|
|
242
|
+
> `usePlurals` only affects **auth tables** generated by Better Auth (e.g. `user` vs `users`, `session` vs `sessions`). Feature table names come directly from your Drizzle schema definitions — whatever you pass to `sqliteTable()` or `pgTable()` is used as-is. The `namingConvention` setting applies to both auth and feature column names.
|
|
243
|
+
|
|
238
244
|
|
|
239
245
|
### ID Generation Options
|
|
240
246
|
|
|
@@ -292,9 +298,8 @@ providers: {
|
|
|
292
298
|
| `socialProviders` | `object` | Social login providers (`google`, `github`, `discord`) |
|
|
293
299
|
| `debugLogs` | `boolean` | Enable auth debug logging |
|
|
294
300
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
</Callout>
|
|
301
|
+
> Auth table naming (`usePlurals`, `namingConvention`) is inherited from your database provider config — you don't need to set it separately on the auth provider. `usePlurals` controls whether auth tables are named `user`/`session` or `users`/`sessions`. It does not affect feature tables, which use whatever name you define in your schema.
|
|
302
|
+
|
|
298
303
|
|
|
299
304
|
### Better Auth Plugins
|
|
300
305
|
|
|
@@ -342,9 +347,8 @@ providers: {
|
|
|
342
347
|
}
|
|
343
348
|
```
|
|
344
349
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
</Callout>
|
|
350
|
+
> The KV `namespaceId` can be set on the storage provider config, or as `kvId` on the auth provider config (since KV is primarily used for auth sessions). The compiler checks both locations.
|
|
351
|
+
|
|
348
352
|
|
|
349
353
|
### Storage Types
|
|
350
354
|
|
|
@@ -149,7 +149,7 @@ Quickback ships seven reserved UPPERCASE markers. Six are real pseudo-roles hand
|
|
|
149
149
|
| `AUTHENTICATED` | required | none | `ctx.authenticated === true` (a full session **or** a scope principal — the wrapper over `SESSION` ∪ `SCOPED`) |
|
|
150
150
|
| `SESSION` | required | none | a full Better Auth session **only** — `ctx.authenticated && !ctx.principal && !ctx.scopePrincipal` |
|
|
151
151
|
| `SCOPED` | required | none | a sessionless scope principal **only** — `ctx.authenticated && ctx.scopePrincipal === true` |
|
|
152
|
-
| `USER` | required | resource firewall **must** scope by `userId` | `ctx.authenticated` AND (`ctx.userRole`
|
|
152
|
+
| `USER` | required | resource firewall **must** scope by `userId` | a real signed-in user — `ctx.authenticated` AND **not** a scope principal (`!ctx.scopePrincipal`) AND (`ctx.userRole` unset OR `=== "user"`). A sessionless scope caller does **not** satisfy `USER` (use `SCOPED` / `scope:<kind>:<role>`); `AUTHENTICATED` is the marker that admits both flavors. |
|
|
153
153
|
| `ADMIN` | required | reserved legacy marker — compiler rejects it | `false` |
|
|
154
154
|
| `SYSADMIN` | required | `cms: { sysadmin: true }` **must** be set on the project | `ctx.authenticated && ctx.userRole === "sysadmin"` |
|
|
155
155
|
|
|
@@ -328,9 +328,141 @@ type FieldCondition =
|
|
|
328
328
|
| { greaterThanOrEqual: number };
|
|
329
329
|
```
|
|
330
330
|
|
|
331
|
+
## Centrally defined access rules
|
|
332
|
+
|
|
333
|
+
Instead of repeating the same `roles: [...]` expression across every feature, define it **once** in `authz.roles` and reference it by name everywhere. This is the recommended way to manage access as your app grows: one source of truth per rule, changed in one place.
|
|
334
|
+
|
|
335
|
+
Named roles (and named gates, tenant anchors, scope kinds) can be declared at **two levels**:
|
|
336
|
+
at root `authz` in `quickback.config.ts` (visible everywhere), or inside a
|
|
337
|
+
[feature area](/compiler/definitions/feature-areas)'s `_area.ts` (visible to that area's
|
|
338
|
+
subtree only — a feature outside the area referencing the name is a compile error, and root
|
|
339
|
+
`authz` bodies may reference root-declared names only). Declare each name in exactly one
|
|
340
|
+
place: re-declaring an inherited name is a compile error.
|
|
341
|
+
|
|
342
|
+
```typescript
|
|
343
|
+
// quickback.config.ts — define ONCE
|
|
344
|
+
export default defineConfig({
|
|
345
|
+
// ...providers...
|
|
346
|
+
authz: {
|
|
347
|
+
roles: {
|
|
348
|
+
// Compose from BA roles, pseudo-roles, and other named rules:
|
|
349
|
+
staff: { roles: ['admin', 'member'] },
|
|
350
|
+
// Boolean combinators:
|
|
351
|
+
eventStaff: { or: [{ roles: ['staff'] }, { via: 'organizerOf' }] },
|
|
352
|
+
// Relationship-backed (see below):
|
|
353
|
+
attendee: { via: 'attendeeOf' },
|
|
354
|
+
},
|
|
355
|
+
},
|
|
356
|
+
});
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
```typescript
|
|
360
|
+
// any feature — REFERENCE by bare name
|
|
361
|
+
export default defineTable(agendaItems, {
|
|
362
|
+
read: { access: { roles: ['eventStaff'] } },
|
|
363
|
+
update: { access: { roles: ['eventStaff'] } },
|
|
364
|
+
});
|
|
365
|
+
|
|
366
|
+
// actions.ts
|
|
367
|
+
checkIn: { access: { roles: ['eventStaff', 'attendee'] }, /* ... */ },
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
### Rule shapes
|
|
371
|
+
|
|
372
|
+
Each entry in `authz.roles` is one of four shapes:
|
|
373
|
+
|
|
374
|
+
| Shape | Meaning |
|
|
375
|
+
|---|---|
|
|
376
|
+
| `{ roles: ['admin', 'member'] }` | Composition — matches any of the listed roles (BA, pseudo, or other named rules) |
|
|
377
|
+
| `{ or: [ruleA, ruleB] }` | Matches if **any** sub-rule matches |
|
|
378
|
+
| `{ and: [ruleA, ruleB] }` | Matches only if **all** sub-rules match |
|
|
379
|
+
| `{ via: 'relationshipName' }` | Caller proves a declared relationship — see [Relationship-based authorization](#relationship-based-authorization) below |
|
|
380
|
+
|
|
381
|
+
Rules compose freely — a rule may reference another rule by name (cycles are a compile error).
|
|
382
|
+
|
|
383
|
+
### Where references resolve
|
|
384
|
+
|
|
385
|
+
A named rule works in the `roles: [...]` array of every access surface. The compiler expands it at build time:
|
|
386
|
+
|
|
387
|
+
| Surface | |
|
|
388
|
+
|---|---|
|
|
389
|
+
| `crud.*.access` | ✓ |
|
|
390
|
+
| `read.access` / `read.views.*.access` | ✓ |
|
|
391
|
+
| `masking.<field>.show` | ✓ for role/composite rules; relationship (`via`) rules refused at compile (v1) |
|
|
392
|
+
| `actions.<name>.access` | ✓ |
|
|
393
|
+
| `realtime.requiredRoles` | ✓ — relationship arms fail closed at the WS handshake and are enforced by the row-stream firewall |
|
|
394
|
+
|
|
395
|
+
Names that **aren't** declared in `authz.roles` — Better Auth roles, pseudo-roles like `AUTHENTICATED` — pass through untouched, so you can mix named rules and raw roles in the same array.
|
|
396
|
+
|
|
397
|
+
### Beyond roles: named permissions
|
|
398
|
+
|
|
399
|
+
For access that traverses the data graph (FK hops, SpiceDB-style permission composition), see [`authz.permissions` + `authz.arrows`](/compiler/definitions/permissions) — the same define-once-reference-by-name model, one level richer than `authz.roles`.
|
|
400
|
+
|
|
401
|
+
## Named gates (`authz.rules`)
|
|
402
|
+
|
|
403
|
+
`authz.roles` centralizes the *who*. A **gate** (`authz.rules.<name>`) bundles a full access rule — *who* + an optional row predicate (`record:`) + optional [firewall lanes](/compiler/definitions/firewall#named-gate-references-rule) — under ONE name, declared once:
|
|
404
|
+
|
|
405
|
+
```typescript
|
|
406
|
+
// quickback.config.ts
|
|
407
|
+
authz: {
|
|
408
|
+
tenants: { org: { column: 'organizationId', equals: 'ctx.activeOrgId' } },
|
|
409
|
+
rules: {
|
|
410
|
+
// who + record: "org staff, but only rows still active"
|
|
411
|
+
activeStaff: {
|
|
412
|
+
who: { roles: ['member', 'admin', 'owner'] },
|
|
413
|
+
record: { status: { equals: 'active' } },
|
|
414
|
+
},
|
|
415
|
+
// who + firewall: an org-OR-event-scope row gate, declared ONCE
|
|
416
|
+
eventRow: {
|
|
417
|
+
who: { roles: ['owner', 'admin', 'member'] },
|
|
418
|
+
firewall: [{ any: [
|
|
419
|
+
{ tenant: 'org' },
|
|
420
|
+
{ field: 'eventId', equals: 'ctx.scope.event' },
|
|
421
|
+
] }],
|
|
422
|
+
},
|
|
423
|
+
},
|
|
424
|
+
}
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
```typescript
|
|
428
|
+
// any feature — the gate name works like a role name
|
|
429
|
+
export default defineTable(eventLinks, {
|
|
430
|
+
firewall: [{ rule: 'eventRow' }], // firewall stamp
|
|
431
|
+
read: { access: { roles: ['eventRow'] } }, // access stamp
|
|
432
|
+
});
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
### The two-stamp contract
|
|
436
|
+
|
|
437
|
+
One shared name, two independent stamps — **a single reference never applies both**:
|
|
438
|
+
|
|
439
|
+
- An **access-position reference** (the bare name in any `roles: [...]` array) applies the gate's `who` + `record` arms **only**. It expands exactly like an inline rule: a who-only gate splices as the flat role list; a who+record gate as `{ and: [who, { record }] }`.
|
|
440
|
+
- A **firewall reference** (`firewall: [{ rule: '<name>' }]`) applies the gate's `firewall` lanes **only**, spliced into the resource's top-level AND array. The `who` of a gate referenced only from `firewall:` is **not consulted** — that is the documented contract, not a silent drop. Firewall-who is legitimately *wider* than access-who (e.g. the firewall admits scope-token holders to rows while read access stays staff-only).
|
|
441
|
+
|
|
442
|
+
Both directions are enforced fail-closed at compile time:
|
|
443
|
+
|
|
444
|
+
| You wrote | Compiler says |
|
|
445
|
+
|---|---|
|
|
446
|
+
| Access reference to a firewall-bearing gate, but the resource's `firewall:` doesn't reference it | **Error** — the row lanes would silently not apply |
|
|
447
|
+
| `firewall: [{ rule }]` naming a gate with no `firewall` arm | **Error** — a who/record-only gate would splice zero lanes |
|
|
448
|
+
| A firewall-bearing gate referenced from an **action's** access or from `masking.show` | **Error, unconditional** — no firewall array exists at those sites (nested `show.or` / `show.and` arms included) |
|
|
449
|
+
| A who-less (firewall-only) gate referenced from an access position | **Error** — row lanes can't masquerade as a who-grant |
|
|
450
|
+
| A gate's `record:` field is not a column of the referencing table | **Error, per reference** — a missing field evaluates against `undefined` at runtime (`notEquals`/`notIn` would silently *grant*) |
|
|
451
|
+
| A spliced gate's firewall lane filters on a column the stamped table doesn't have | **Error, per reference** — the lane could never scope rows there |
|
|
452
|
+
|
|
453
|
+
### Naming rules
|
|
454
|
+
|
|
455
|
+
Rule names share the reference namespace with roles, so the compiler rejects (at declaration time) a rule name that collides with an `authz.roles` entry, a reserved/provider role, **any scoped-role name** (bare sugar like `attendee` or the canonical `scope:<kind>:<role>` spelling), or a name containing `+` or `:` (the `scope:` prefix always means a token-verified scope principal — a colon-named rule could capture references meant for one).
|
|
456
|
+
|
|
457
|
+
Inside `authz.roles` / gate `who` bodies, `+` hierarchy sugar is banned — write the expanded list (`['member', 'admin', 'owner']`), because `+` expansion runs at resource sites only and a `member+` inside a body would silently never match. Roles may not reference rules (the dependency arrow is one-way), and gates never nest.
|
|
458
|
+
|
|
459
|
+
### Typo safety
|
|
460
|
+
|
|
461
|
+
A `roles: [...]` name that matches nothing declared is fail-closed at runtime (it never grants) but historically silent. The compiler now emits a warning-level `AUTHZ_UNKNOWN_ROLE_NAME` diagnostic for any name that is not a provider/hierarchy role, pseudo-role, scoped role, or declared role/rule — a typo'd gate name is visible at compile time without breaking projects that use dynamic auth-provider role names. The heuristic runs only for projects that use the authz naming system (any of `authz.roles`, `authz.rules`, or `authz.scopes` declared); projects outside it keep the pre-existing silent-passthrough behavior for dynamic role names.
|
|
462
|
+
|
|
331
463
|
## Relationship-based authorization
|
|
332
464
|
|
|
333
|
-
Beyond Better Auth roles (org membership, user-table role) and pseudo-roles, Quickback supports **relationship-based authorization roles** — names that bind to a declared relationship between the caller and a resource. Use these when access should follow a domain-table membership ("user is a confirmed guest of this event") rather than an org/admin gate.
|
|
465
|
+
Beyond Better Auth roles (org membership, user-table role) and pseudo-roles, Quickback supports **relationship-based authorization roles** — names that bind to a declared relationship between the caller and a resource. Use these when access should follow a domain-table membership ("user is a confirmed guest of this event") rather than an org/admin gate. These are the `{ via: '...' }` rule shape from [Centrally defined access rules](#centrally-defined-access-rules) above.
|
|
334
466
|
|
|
335
467
|
### `authz.relationships`
|
|
336
468
|
|
|
@@ -168,6 +168,8 @@ namespace parameters.
|
|
|
168
168
|
| `unsafe` | No | Unsafe raw DB mode. Object config (`reason`, `adminOnly`, `crossTenant`, `targetScope`). |
|
|
169
169
|
| `transition` | No | State-machine policy enforcing the from/to pair (record-based actions). See [Transitions](#transition-state-machine-policy) |
|
|
170
170
|
| `bulkVariant` | No | Auto-generate a `POST /:resource/batch/{action}` route alongside the per-record route (record-based actions). See [Bulk Variant](#bulk-variant) |
|
|
171
|
+
| `webhook` | No | Standalone only. Compile-declared inbound signature verification (`standard-webhooks`, `hmac-sha256`, or `aws-sns`) that runs on the raw bytes **before** parse/access — see [Inbound webhooks](/stack/webhooks/inbound) |
|
|
172
|
+
| `idempotency` | No | `'dedupe'` — PUBLIC-action opt-in for the `Idempotency-Key` header with dedupe-only semantics (duplicate ⇒ `409` reference; the cached body is never served to a second caller). Standalone actions with a **static** path only (a `:param` path is a compile error — the allowlist matches literal request paths) and the action's access must admit `PUBLIC`. Authenticated routes accept the header automatically — see [API contract](/stack/api-contract) |
|
|
171
173
|
| `cms` | No | Pass-through metadata blob for CMS surfaces |
|
|
172
174
|
|
|
173
175
|
`execute` must be an `async (ctx) => { … }` arrow function. `async function`
|
|
@@ -378,6 +380,20 @@ GET /reports/summary
|
|
|
378
380
|
POST /webhooks/stripe
|
|
379
381
|
```
|
|
380
382
|
|
|
383
|
+
Paths are absolute (`/...`). Inside a [feature area](/compiler/definitions/feature-areas)
|
|
384
|
+
with a mounted prefix, two more forms apply:
|
|
385
|
+
|
|
386
|
+
- **Relative** — `path: './tasks/add'` resolves against the area's prefix
|
|
387
|
+
(`/project/:projectId/tasks/add`). Plain descending segments only; `.` / `..` segments are
|
|
388
|
+
rejected at compile time.
|
|
389
|
+
- **Self-gated** — an absolute path *outside* the area's prefix opts the action out of the
|
|
390
|
+
area's admission gate and MUST carry `route: 'self'` (fail-closed; the marker is rejected
|
|
391
|
+
where it would be dead). The action is then gated solely by its own `access:` and listed in
|
|
392
|
+
`quickback/authz-manifest.json`.
|
|
393
|
+
|
|
394
|
+
An action's `access:` and `anchor:` may reference vocabulary declared by an ancestor area —
|
|
395
|
+
and never vocabulary of an area the feature is not inside (compile error).
|
|
396
|
+
|
|
381
397
|
### Example: AI Chat with Streaming
|
|
382
398
|
|
|
383
399
|
```typescript
|
|
@@ -507,6 +523,12 @@ access: {
|
|
|
507
523
|
}
|
|
508
524
|
```
|
|
509
525
|
|
|
526
|
+
If the same role expression shows up on more than one action or resource, define it once in `authz.roles` and reference it by name — see [Centrally defined access rules](/compiler/definitions/access#centrally-defined-access-rules).
|
|
527
|
+
|
|
528
|
+
[Named gates](/compiler/definitions/access#named-gates-authzrules) (`authz.rules`) also work in an action's `roles: [...]` array — a who-only gate expands as its `who`, a who+`record` gate as `{ and: [who, { record }] }` (the record predicate is evaluated against the bound record, exactly like an inline `access.record`). Function-form `access` is opaque to the rewrite and is left untouched.
|
|
529
|
+
|
|
530
|
+
**A firewall-bearing gate on an action is a compile error.** An action has no firewall array — there is no row query for the gate's lanes to constrain before execution — so the compiler refuses rather than letting the row lanes silently not apply. The escape hatch: split the gate into a who-rule referenced from the action plus a firewall-only gate stamped on the owning resource's `firewall:`.
|
|
531
|
+
|
|
510
532
|
### Public Access
|
|
511
533
|
|
|
512
534
|
Use `roles: ["PUBLIC"]` for unauthenticated endpoints (contact forms, webhooks, public APIs). Every invocation is **mandatory audit logged** with IP address, input, result, and timing.
|