@quickback-dev/cli 0.66.4 → 0.66.5

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/index.js CHANGED
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import pc from "picocolors";
12
12
  // Version injected at build time by scripts/inject-version.ts
13
- const CLI_VERSION = "0.66.4";
13
+ const CLI_VERSION = "0.66.5";
14
14
  function getPackageVersion() {
15
15
  return CLI_VERSION;
16
16
  }
@@ -8,6 +8,23 @@ The current release series. Older entries are archived by version range:
8
8
  - [v0.20 – v0.29](/changelog/v0.2x)
9
9
  - [v0.18 and earlier](/changelog/v0.1x)
10
10
 
11
+ ## Unreleased — delete rows reach after-write consumers
12
+
13
+ - **Every delete statement now carries `.returning()`** ([#414](https://github.com/paulstenhouse/quickback-compiler/issues/414)). The single-record soft delete, the single-record hard delete, and the batch hard delete emitted no `RETURNING`, so on D1 the write result carried no rows and the audit-wrapper chokepoint had nothing to hand to its consumers: `afterDelete` trigger hooks never ran, live-view deltas were not emitted, and the scope-revocation and SEALED hard-delete audit-snapshot taps were skipped on those paths. Recompile to pick it up; response shapes are unchanged.
14
+
15
+ ## Unreleased — scope enter tenant drop
16
+
17
+ - **`/scope/v1/enter` mints a relationship-only token for a foreign-tenant instance** (follow-up to [#391](https://github.com/paulstenhouse/quickback-compiler/issues/391)). When the relationship's `from` table carries an organization column, the proven row's tenant is compared with `ctx.activeOrgId`; on a mismatch the token carries no `orgId` / `role`. Previously such a token was harmless (the tenant-bound firewall and resolver refused it) but still persisted the foreign org beside the scope. See [scopes](/define/scopes#per-matched-lane-minting-forging-safety).
18
+ - **The shipped access evaluator and the compiler's reference copy are parity-tested** — `access-evaluator-parity.test.ts` runs both through one behavioural table (roles, principals, `userRole`, every `record:` condition, `or` / `and` nesting, collection predicates), so a fix that lands in one copy and not the other fails a test instead of drifting.
19
+
20
+ ## Unreleased — access-evaluator hardening
21
+
22
+ - **`access.record` is enforced on collection reads and batch-create** ([#394](https://github.com/paulstenhouse/quickback-compiler/issues/394)). `GET /`, per-view lists, and the MCP list tool fold each admitted arm's `record:` predicates into the query `WHERE`; `POST /batch` checks every input record the way single `POST` does. The `AUTHZ_RECORD_PREDICATE_NOT_ON_LIST` warning is retired because the list now honours the predicate. See [access](/define/access#collection-routes-honour-accessrecord-too).
23
+ - **The access evaluator denies instead of throwing** ([#354](https://github.com/paulstenhouse/quickback-compiler/issues/354)). A `$ctx.` path with a missing intermediate resolves to undefined (403, not 500), and `equals` / `notEquals` deny when either side is absent instead of matching `undefined === undefined`.
24
+ - **Function-form `read.access` is a compile error** ([#353](https://github.com/paulstenhouse/quickback-compiler/issues/353)) instead of emitting `const getAccess = undefined` into `GET /:id`.
25
+ - **Dependency overrides land in the key your package manager reads** ([#359](https://github.com/paulstenhouse/quickback-compiler/issues/359)): `overrides` for npm and bun, `pnpm.overrides` for pnpm, `resolutions` for yarn — so the lodash security pin is no longer silently inert off npm.
26
+ - **Top-level `rateLimit` is accepted by the config schema** ([#180](https://github.com/paulstenhouse/quickback-compiler/issues/180)); it was typed and consumed but rejected by the strict validator.
27
+
11
28
  ## Unreleased — tenant binding and credential hygiene
12
29
 
13
30
  Fixes from the attend-vip API security review. All are compiler changes;
@@ -53,7 +53,7 @@ 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
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 — and [tell us about your use case](https://github.com/kardoe/quickback/issues); an opaque-session mode is under consideration.
59
59
 
@@ -136,11 +136,12 @@ A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's
136
136
 
137
137
  | Key | Revokes | Written automatically on |
138
138
  |---|---|---|
139
- | `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). Call `revokeUserTokens` for custom flows (revoke-all, etc.) |
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
 
@@ -413,12 +413,35 @@ opaque 404 instead.
413
413
 
414
414
  Function-form access (`access: async (ctx, record) => ...`) is opaque to
415
415
  the pre-record phase and always passes there; it's fully evaluated post-record.
416
-
417
- Collection routes (`GET /`, `POST /batch`, and the generated MCP list tool)
418
- stop at step 2: there is no record to evaluate, so `access.record` is **not**
419
- applied to a list — row scoping on a list is the [firewall's](/define/firewall)
420
- job. Don't use an unsatisfiable predicate (`record: { id: { equals: "never" } }`)
421
- to hide a resource; it still lists. To give a resource no read surface, omit
416
+ It is accepted on `create` / `update` / `delete`, where the generated route
417
+ references it at runtime. It is **not** accepted as `read.access`: the
418
+ generated `GET /:id` route serialises the read tree inline, so a function
419
+ there is a compile error naming the resource. Express read rules
420
+ declaratively (`roles`, `userRole`, `record`, `or`, `and`).
421
+
422
+ ### Collection routes honour `access.record` too
423
+
424
+ `GET /`, the per-view lists, and the generated MCP list tool fold the same
425
+ `record:` predicates into the query's `WHERE`, arm for arm, so a list can never
426
+ return a row the caller could not `GET` one at a time:
427
+
428
+ - Each `or` arm whose role / `userRole` gates admit the caller contributes its
429
+ `record` predicates as one AND-group; the groups are OR'd together.
430
+ - An admitted arm with **no** `record` block lifts the constraint for the
431
+ whole list (that arm would admit every row on `GET /:id` as well).
432
+ - A `$ctx.` value that is absent for the caller (no `activeOrgId`, no
433
+ `scope`) makes that arm unsatisfiable — it denies, never matches.
434
+ - A predicate on a column the table does not have yields no rows.
435
+ - No admitted arm at all → `403` from the role gate, as before.
436
+
437
+ `POST /batch` runs the same per-record check single `POST` does
438
+ (`record:` against each input body), and rejects the offending records
439
+ individually in the batch `errors` array.
440
+
441
+ Row scoping by tenant is still the [firewall's](/define/firewall) job; an
442
+ unsatisfiable predicate (`record: { id: { equals: "__never__" } }`) now hides
443
+ every row on every read surface, which is a legitimate way to give a resource
444
+ a get-only or write-only surface. To give it no read surface at all, omit
422
445
  `read` — no list, get, batch, or MCP route is emitted.
423
446
 
424
447
  ## Context Variables
@@ -67,17 +67,22 @@ guards: {
67
67
  |------|------------------|
68
68
  | `createable` | Fields allowed in create (POST) request body |
69
69
  | `updatable` | Fields allowed in update (PATCH) request body |
70
- | `protected` | Fields blocked from direct writes; the named actions are documentation, not enforcement (see below) |
71
- | `immutable` | Fields allowed on create, blocked on all generic updates (actions can still write them) |
72
-
73
- > **Guards bind the generic CRUD surface, not actions.** `createable`,
74
- > `updatable`, `immutable`, and `protected` are enforced by the generated
75
- > `validateCreate` / `validateUpdate`, which only the CRUD, batch, and changeset
76
- > routes call. An action handler writes through a scoped `db` with no field-level
77
- > checks, so it can write any column — including an `immutable` one, and including
78
- > a `protected` one not listed in that field's action names. Treat the names in
79
- > `protected` as intent you are documenting, and keep the enforcement in the
80
- > action's own access rules.
70
+ | `protected` | Fields blocked from direct writes; writable only by the actions named for them |
71
+ | `immutable` | Fields allowed on create, then never written again — by CRUD, batch, changeset, **or actions** |
72
+
73
+ > **Guards bind actions too.** `createable` and `updatable` shape the CRUD
74
+ > request bodies. `immutable` and `protected` are additionally enforced against
75
+ > your action handlers at **compile time**: the compiler scans each action bound
76
+ > to the table for `db.update(<table>).set({ … })` / `db.insert(<table>).values({ … })`
77
+ > and refuses an `immutable` column in any update, or a `protected` column
78
+ > written by an action that is not in its list — with an error naming the action,
79
+ > the column, and the fix. The two tiers are therefore distinct: `immutable` is
80
+ > written once at create and never again; if a column needs an action to change
81
+ > it, it is `protected`, mapped to that action.
82
+ >
83
+ > The scan sees object-literal payloads only. A spread (`.set({ ...input })`) or
84
+ > a variable payload (`.set(patch)`) is not analysed, so keep guarded columns out
85
+ > of such payloads yourself — that is the documented residual.
81
86
 
82
87
 
83
88
  **Combining lists:**
@@ -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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.66.4",
3
+ "version": "0.66.5",
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",
@@ -8,6 +8,23 @@ The current release series. Older entries are archived by version range:
8
8
  - [v0.20 – v0.29](/changelog/v0.2x)
9
9
  - [v0.18 and earlier](/changelog/v0.1x)
10
10
 
11
+ ## Unreleased — delete rows reach after-write consumers
12
+
13
+ - **Every delete statement now carries `.returning()`** ([#414](https://github.com/paulstenhouse/quickback-compiler/issues/414)). The single-record soft delete, the single-record hard delete, and the batch hard delete emitted no `RETURNING`, so on D1 the write result carried no rows and the audit-wrapper chokepoint had nothing to hand to its consumers: `afterDelete` trigger hooks never ran, live-view deltas were not emitted, and the scope-revocation and SEALED hard-delete audit-snapshot taps were skipped on those paths. Recompile to pick it up; response shapes are unchanged.
14
+
15
+ ## Unreleased — scope enter tenant drop
16
+
17
+ - **`/scope/v1/enter` mints a relationship-only token for a foreign-tenant instance** (follow-up to [#391](https://github.com/paulstenhouse/quickback-compiler/issues/391)). When the relationship's `from` table carries an organization column, the proven row's tenant is compared with `ctx.activeOrgId`; on a mismatch the token carries no `orgId` / `role`. Previously such a token was harmless (the tenant-bound firewall and resolver refused it) but still persisted the foreign org beside the scope. See [scopes](/define/scopes#per-matched-lane-minting-forging-safety).
18
+ - **The shipped access evaluator and the compiler's reference copy are parity-tested** — `access-evaluator-parity.test.ts` runs both through one behavioural table (roles, principals, `userRole`, every `record:` condition, `or` / `and` nesting, collection predicates), so a fix that lands in one copy and not the other fails a test instead of drifting.
19
+
20
+ ## Unreleased — access-evaluator hardening
21
+
22
+ - **`access.record` is enforced on collection reads and batch-create** ([#394](https://github.com/paulstenhouse/quickback-compiler/issues/394)). `GET /`, per-view lists, and the MCP list tool fold each admitted arm's `record:` predicates into the query `WHERE`; `POST /batch` checks every input record the way single `POST` does. The `AUTHZ_RECORD_PREDICATE_NOT_ON_LIST` warning is retired because the list now honours the predicate. See [access](/define/access#collection-routes-honour-accessrecord-too).
23
+ - **The access evaluator denies instead of throwing** ([#354](https://github.com/paulstenhouse/quickback-compiler/issues/354)). A `$ctx.` path with a missing intermediate resolves to undefined (403, not 500), and `equals` / `notEquals` deny when either side is absent instead of matching `undefined === undefined`.
24
+ - **Function-form `read.access` is a compile error** ([#353](https://github.com/paulstenhouse/quickback-compiler/issues/353)) instead of emitting `const getAccess = undefined` into `GET /:id`.
25
+ - **Dependency overrides land in the key your package manager reads** ([#359](https://github.com/paulstenhouse/quickback-compiler/issues/359)): `overrides` for npm and bun, `pnpm.overrides` for pnpm, `resolutions` for yarn — so the lodash security pin is no longer silently inert off npm.
26
+ - **Top-level `rateLimit` is accepted by the config schema** ([#180](https://github.com/paulstenhouse/quickback-compiler/issues/180)); it was typed and consumed but rejected by the strict validator.
27
+
11
28
  ## Unreleased — tenant binding and credential hygiene
12
29
 
13
30
  Fixes from the attend-vip API security review. All are compiler changes;
@@ -53,7 +53,7 @@ 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
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 — and [tell us about your use case](https://github.com/kardoe/quickback/issues); an opaque-session mode is under consideration.
59
59
 
@@ -136,11 +136,12 @@ A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's
136
136
 
137
137
  | Key | Revokes | Written automatically on |
138
138
  |---|---|---|
139
- | `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). Call `revokeUserTokens` for custom flows (revoke-all, etc.) |
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
 
@@ -413,12 +413,35 @@ opaque 404 instead.
413
413
 
414
414
  Function-form access (`access: async (ctx, record) => ...`) is opaque to
415
415
  the pre-record phase and always passes there; it's fully evaluated post-record.
416
-
417
- Collection routes (`GET /`, `POST /batch`, and the generated MCP list tool)
418
- stop at step 2: there is no record to evaluate, so `access.record` is **not**
419
- applied to a list — row scoping on a list is the [firewall's](/define/firewall)
420
- job. Don't use an unsatisfiable predicate (`record: { id: { equals: "never" } }`)
421
- to hide a resource; it still lists. To give a resource no read surface, omit
416
+ It is accepted on `create` / `update` / `delete`, where the generated route
417
+ references it at runtime. It is **not** accepted as `read.access`: the
418
+ generated `GET /:id` route serialises the read tree inline, so a function
419
+ there is a compile error naming the resource. Express read rules
420
+ declaratively (`roles`, `userRole`, `record`, `or`, `and`).
421
+
422
+ ### Collection routes honour `access.record` too
423
+
424
+ `GET /`, the per-view lists, and the generated MCP list tool fold the same
425
+ `record:` predicates into the query's `WHERE`, arm for arm, so a list can never
426
+ return a row the caller could not `GET` one at a time:
427
+
428
+ - Each `or` arm whose role / `userRole` gates admit the caller contributes its
429
+ `record` predicates as one AND-group; the groups are OR'd together.
430
+ - An admitted arm with **no** `record` block lifts the constraint for the
431
+ whole list (that arm would admit every row on `GET /:id` as well).
432
+ - A `$ctx.` value that is absent for the caller (no `activeOrgId`, no
433
+ `scope`) makes that arm unsatisfiable — it denies, never matches.
434
+ - A predicate on a column the table does not have yields no rows.
435
+ - No admitted arm at all → `403` from the role gate, as before.
436
+
437
+ `POST /batch` runs the same per-record check single `POST` does
438
+ (`record:` against each input body), and rejects the offending records
439
+ individually in the batch `errors` array.
440
+
441
+ Row scoping by tenant is still the [firewall's](/define/firewall) job; an
442
+ unsatisfiable predicate (`record: { id: { equals: "__never__" } }`) now hides
443
+ every row on every read surface, which is a legitimate way to give a resource
444
+ a get-only or write-only surface. To give it no read surface at all, omit
422
445
  `read` — no list, get, batch, or MCP route is emitted.
423
446
 
424
447
  ## Context Variables
@@ -67,17 +67,22 @@ guards: {
67
67
  |------|------------------|
68
68
  | `createable` | Fields allowed in create (POST) request body |
69
69
  | `updatable` | Fields allowed in update (PATCH) request body |
70
- | `protected` | Fields blocked from direct writes; the named actions are documentation, not enforcement (see below) |
71
- | `immutable` | Fields allowed on create, blocked on all generic updates (actions can still write them) |
72
-
73
- > **Guards bind the generic CRUD surface, not actions.** `createable`,
74
- > `updatable`, `immutable`, and `protected` are enforced by the generated
75
- > `validateCreate` / `validateUpdate`, which only the CRUD, batch, and changeset
76
- > routes call. An action handler writes through a scoped `db` with no field-level
77
- > checks, so it can write any column — including an `immutable` one, and including
78
- > a `protected` one not listed in that field's action names. Treat the names in
79
- > `protected` as intent you are documenting, and keep the enforcement in the
80
- > action's own access rules.
70
+ | `protected` | Fields blocked from direct writes; writable only by the actions named for them |
71
+ | `immutable` | Fields allowed on create, then never written again — by CRUD, batch, changeset, **or actions** |
72
+
73
+ > **Guards bind actions too.** `createable` and `updatable` shape the CRUD
74
+ > request bodies. `immutable` and `protected` are additionally enforced against
75
+ > your action handlers at **compile time**: the compiler scans each action bound
76
+ > to the table for `db.update(<table>).set({ … })` / `db.insert(<table>).values({ … })`
77
+ > and refuses an `immutable` column in any update, or a `protected` column
78
+ > written by an action that is not in its list — with an error naming the action,
79
+ > the column, and the fix. The two tiers are therefore distinct: `immutable` is
80
+ > written once at create and never again; if a column needs an action to change
81
+ > it, it is `protected`, mapped to that action.
82
+ >
83
+ > The scan sees object-literal payloads only. A spread (`.set({ ...input })`) or
84
+ > a variable payload (`.set(patch)`) is not analysed, so keep guarded columns out
85
+ > of such payloads yourself — that is the documented residual.
81
86
 
82
87
 
83
88
  **Combining lists:**
@@ -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