@quickback-dev/cli 0.55.0 → 0.56.0
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 +60 -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 +60 -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
|
@@ -119,7 +119,7 @@ The `ctx.scope.*` arms are how **relationship-derived scopes** (attendees, shutt
|
|
|
119
119
|
|
|
120
120
|
## Relationship-based scoping (`via:`)
|
|
121
121
|
|
|
122
|
-
For relationship authorization — "this user can see rows X if they have a confirmed `event_guests` row pointing at X" — declare the relationship under `authz.relationships` in `quickback.config.ts`, then reference it from `firewall:` with a `via:` predicate
|
|
122
|
+
For relationship authorization — "this user can see rows X if they have a confirmed `event_guests` row pointing at X" — declare the relationship under `authz.relationships` in `quickback.config.ts`, then reference it from `firewall:` with a `via:` predicate. These relationships (and the named roles/permissions built on them) are defined once, centrally — see [Centrally defined access rules](/compiler/definitions/access#centrally-defined-access-rules).
|
|
123
123
|
|
|
124
124
|
```typescript
|
|
125
125
|
// quickback.config.ts
|
|
@@ -212,6 +212,65 @@ The compile-time analyzer additionally flags a referenced permission that can
|
|
|
212
212
|
never be satisfied, an arm shadowed by a broader one, and the SQL / CTE cost
|
|
213
213
|
of each permission — see [Diagnostics](/compiler/definitions/diagnostics).
|
|
214
214
|
|
|
215
|
+
## Named tenant anchors (`{ tenant }`)
|
|
216
|
+
|
|
217
|
+
The tenant predicate `{ field: 'organizationId', equals: 'ctx.activeOrgId' }` tends to be repeated on every table. Declare it **once** as a named anchor and reference it by name:
|
|
218
|
+
|
|
219
|
+
```typescript
|
|
220
|
+
// quickback.config.ts
|
|
221
|
+
authz: {
|
|
222
|
+
tenants: {
|
|
223
|
+
org: { column: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
224
|
+
},
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// any firewall — top level or inside all/any groups:
|
|
228
|
+
firewall: [
|
|
229
|
+
{ tenant: 'org' }, // → { field: 'organizationId', equals: 'ctx.activeOrgId' }
|
|
230
|
+
{ field: 'deletedAt', isNull: true },
|
|
231
|
+
]
|
|
232
|
+
|
|
233
|
+
// per-site COLUMN override (the claim side is never overridable):
|
|
234
|
+
firewall: [{ field: 'orgId', tenant: 'org' }]
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The anchor's `equals` must be a **verified ctx claim**: `ctx.activeOrgId` | `ctx.userId` | `ctx.scope.<kind>` | `ctx.scope.<kind>.<subKey>`. `ctx.activeTeamId` (drop-when-absent semantics stay a per-resource decision) and legacy aliases are rejected at declaration time — an anchor can never bind a request-derived value. A `{ tenant }` reference carrying its own `equals` is a compile error (one source of truth); an unknown anchor name is a compile error listing the declared anchors.
|
|
238
|
+
|
|
239
|
+
Expansion happens at compile time, before rendering — the emitted SQL is byte-identical to writing the predicate inline. Auth-DB read views accept the same anchors as a string: [`tenant: 'org'`](/stack/realtime/live-views#auth-db-includes-source-auth) — with one extra constraint: an anchor referenced from an auth-view include must bind a single-segment session claim (`ctx.<claim>`); scope-principal claims (`ctx.scope.*`) are firewall-lane bindings and are rejected there.
|
|
240
|
+
|
|
241
|
+
## Named gate references (`{ rule }`)
|
|
242
|
+
|
|
243
|
+
A [gate](/compiler/definitions/access#named-gates-authzrules) that declares `firewall` lanes can be stamped onto a resource by name:
|
|
244
|
+
|
|
245
|
+
```typescript
|
|
246
|
+
// quickback.config.ts
|
|
247
|
+
authz: {
|
|
248
|
+
rules: {
|
|
249
|
+
eventRow: {
|
|
250
|
+
who: { roles: ['owner', 'admin', 'member'] },
|
|
251
|
+
firewall: [{ any: [
|
|
252
|
+
{ tenant: 'org' }, // org staff
|
|
253
|
+
{ field: 'eventId', equals: 'ctx.scope.event' }, // signed scope claim
|
|
254
|
+
] }],
|
|
255
|
+
},
|
|
256
|
+
},
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
// the resource:
|
|
260
|
+
firewall: [{ rule: 'eventRow' }]
|
|
261
|
+
// composes with the resource's own lanes (top-level AND):
|
|
262
|
+
firewall: [{ rule: 'eventRow' }, { field: 'kind', equals: 'ctx.scope.event.kind' }]
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Semantics — **AND-compose, top-level only, a reference can only narrow**:
|
|
266
|
+
|
|
267
|
+
- The gate's lanes splice into the resource's **top-level AND array** in place. They never replace the resource's own lanes, and composition can only *narrow* the row set.
|
|
268
|
+
- `{ rule }` is **not** valid inside an `{ all }` / `{ any }` group — a gate's firewall is one-or-more AND lanes, and splicing a multi-lane gate into an `any` group would OR-flatten it, admitting rows in **other tenants** that merely match one lane. This is a type error at authoring time and a compile error at coerce time.
|
|
269
|
+
- A gate's firewall may not contain `{ exception: true }` (a named bundle can never smuggle a firewall opt-out) or another `{ rule }` (gates don't nest — expansion is single-step, so cycles are impossible by construction).
|
|
270
|
+
- A gate with **no** `firewall` arm referenced from `firewall:` is a compile error — a who/record-only gate would silently contribute zero row lanes while the `record:` filter only ever applies at access sites.
|
|
271
|
+
|
|
272
|
+
The splice expands before validation and rendering, so the emitted `buildFirewallConditions` helper is byte-identical to writing the lanes inline — same groups, same absent-claim `1 = 0` guards, same `via:` subqueries.
|
|
273
|
+
|
|
215
274
|
## Context Sources
|
|
216
275
|
|
|
217
276
|
When `equals` references the request context, use these standard sources:
|
|
@@ -111,6 +111,20 @@ firewall: [
|
|
|
111
111
|
|
|
112
112
|
The semantic rule is "if the firewall says this column's value comes from the request context, the client cannot submit it." The value is auto-populated on create / upsert from `ctx`.
|
|
113
113
|
|
|
114
|
+
### Changeset ops widen the set per-surface
|
|
115
|
+
|
|
116
|
+
On [changeset](/compiler/definitions/changesets) ops, an owned child's
|
|
117
|
+
systemManaged set additionally includes its **spine FK and every `inherit`
|
|
118
|
+
column** — the changeset supplies those structurally (the FK from the parent
|
|
119
|
+
op's id, inherit columns from the firewall-verified parent row), so a
|
|
120
|
+
client-supplied value is a pointer-carrying `GUARD_SYSTEM_MANAGED` rejection
|
|
121
|
+
(never silently stripped or stamped-over).
|
|
122
|
+
|
|
123
|
+
The child's **plain-CRUD guards are unaffected**: a junction that keeps its FK
|
|
124
|
+
in `createable` for its raw `POST` route stays correct — the same field
|
|
125
|
+
arriving in a changeset op is rejected because that surface stamps it. Two
|
|
126
|
+
surfaces, one declared rule each.
|
|
127
|
+
|
|
114
128
|
## Example
|
|
115
129
|
|
|
116
130
|
```typescript
|
|
@@ -23,13 +23,38 @@ my-app/
|
|
|
23
23
|
│ ├── candidates.ts # Table + config (defineTable)
|
|
24
24
|
│ ├── applications.ts # Secondary table + config
|
|
25
25
|
│ ├── interview-scores.ts # Internal table (no routes)
|
|
26
|
-
│ ├── actions
|
|
27
|
-
│ └──
|
|
28
|
-
│
|
|
26
|
+
│ ├── actions/ # Custom actions — one file per action
|
|
27
|
+
│ │ └── advance-stage.ts
|
|
28
|
+
│ ├── lib/ # Feature-local helpers (optional)
|
|
29
|
+
│ └── pages/ # CMS page definitions (optional)
|
|
29
30
|
├── src/ # Generated code (output)
|
|
30
31
|
└── package.json
|
|
31
32
|
```
|
|
32
33
|
|
|
34
|
+
`actions/`, `handlers/`, `lib/`, and `pages/` are the **reserved** sub-directories of a
|
|
35
|
+
feature — nothing else inside a feature folder is loaded, and a stray subdirectory that
|
|
36
|
+
contains `defineTable(...)` / `defineAction(...)` files fails the compile (files silently
|
|
37
|
+
disappearing after a mis-move is the failure mode this guards against).
|
|
38
|
+
|
|
39
|
+
Features can also be grouped into **areas**: a folder carrying an `_area.ts`
|
|
40
|
+
(`export default defineArea({...})`) declares a route prefix + admission gate and a shared
|
|
41
|
+
authz vocabulary, and every unreserved child directory becomes a child feature (nesting to
|
|
42
|
+
arbitrary depth):
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
quickback/features/
|
|
46
|
+
├── workspace/ # AREA (has _area.ts)
|
|
47
|
+
│ ├── _area.ts # defineArea({...}) — prefix, via lanes, vocabulary
|
|
48
|
+
│ ├── projects.ts # the area folder may itself be a feature
|
|
49
|
+
│ └── tasks/ # child feature
|
|
50
|
+
│ ├── tasks.ts
|
|
51
|
+
│ └── actions/addTask.ts
|
|
52
|
+
└── billing/ # flat feature (unchanged)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Area projects must declare `requires: ['feature-areas']` in `quickback.config.ts`.
|
|
56
|
+
See [Feature areas](/compiler/definitions/feature-areas) for the full model.
|
|
57
|
+
|
|
33
58
|
**Table files** use `defineTable` to combine schema and security config:
|
|
34
59
|
|
|
35
60
|
```typescript
|
|
@@ -145,6 +145,14 @@ The `'owner'` condition compares against the owner column declared via `q.scope(
|
|
|
145
145
|
|
|
146
146
|
Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in `show:` clauses**. The compiler refuses to build with a clear error message because async, db-aware mask functions plus a batched relationship matcher (to avoid N+1 on list responses) are required to ship safely — that pipeline has not yet landed. The runtime evaluator fails closed on unrecognized arms, so silent grants are impossible.
|
|
147
147
|
|
|
148
|
+
### Named gates in masking
|
|
149
|
+
|
|
150
|
+
[Named gates](/compiler/definitions/access#named-gates-authzrules) (`authz.rules`) follow the same discipline in `show:`:
|
|
151
|
+
|
|
152
|
+
- A **who-only** gate expands like a named role (its flat role list; the owner-gated flat-role constraint above applies).
|
|
153
|
+
- A gate carrying a **`record:`** predicate is a **compile error** — masking cannot evaluate record conditions, so the record dimension would be silently dropped.
|
|
154
|
+
- A gate carrying **firewall lanes** is a **compile error** — masking has no firewall array to satisfy, so the gate's row lanes would silently not apply. Reference a who-only rule (or inline the roles) in `show:`, and stamp the firewall gate on the resource's `firewall:` instead.
|
|
155
|
+
|
|
148
156
|
**Workarounds**, depending on intent:
|
|
149
157
|
|
|
150
158
|
- **Gate on BA roles only**: keep masking simple and put the relationship check at the access layer instead — `read.views.<v>.access: { roles: ['guest'] }` returns a curated field projection that excludes the sensitive column entirely for non-staff callers, without involving masking.
|
|
@@ -53,6 +53,8 @@ export default defineTable(customers, {
|
|
|
53
53
|
| `GET /api/v1/{resource}/:id` | `read.access` |
|
|
54
54
|
| `GET /api/v1/{resource}/views/{name}` | `read.views[name].access` (falls back to `read.access`) |
|
|
55
55
|
|
|
56
|
+
Each `access` block takes a `roles: [...]` array. When the same role expression recurs across reads/views/CRUD, define it once in `authz.roles` and reference it by name — see [Centrally defined access rules](/compiler/definitions/access#centrally-defined-access-rules).
|
|
57
|
+
|
|
56
58
|
Single-record `GET /:id` inherits `read.access` automatically — there's no
|
|
57
59
|
separate `read.get` block. If you need different access for single records,
|
|
58
60
|
use record-level conditions on `read.access`:
|
|
@@ -208,9 +210,20 @@ export default defineTable(balanceSnapshots, {
|
|
|
208
210
|
});
|
|
209
211
|
```
|
|
210
212
|
|
|
213
|
+
## Aggregate Reads
|
|
214
|
+
|
|
215
|
+
Reading a parent **with** its owned relations is served today by `defineView`
|
|
216
|
+
includes (reverse-FK embedding with per-included-table firewall + masking) and
|
|
217
|
+
contract-v2 `?include=` on FK columns. The aggregate-changeset write surface
|
|
218
|
+
([changesets](/compiler/definitions/changesets)) deliberately returns the
|
|
219
|
+
**root row only** in v1 — a nested aggregate representation is the phase-2
|
|
220
|
+
reader and will land on `?include=` over the `owns` graph, not on the write
|
|
221
|
+
response.
|
|
222
|
+
|
|
211
223
|
## See Also
|
|
212
224
|
|
|
213
225
|
- [Views](/compiler/definitions/views) — Full reference for named projections
|
|
226
|
+
- [Changesets](/compiler/definitions/changesets) — Atomic writes over the `owns` graph
|
|
214
227
|
- [Access](/compiler/definitions/access) — Roles, record conditions, and combinators
|
|
215
228
|
- [Firewall](/compiler/definitions/firewall) — Tenant scoping and `firewallErrorMode`
|
|
216
229
|
- [Views API](/compiler/targets/hono-api/using-the-api/views-api) — Calling views from clients
|
|
@@ -78,7 +78,7 @@ A few mechanics to know:
|
|
|
78
78
|
- **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
|
|
79
79
|
- **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
|
|
80
80
|
- **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
|
|
81
|
-
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`.
|
|
81
|
+
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/compiler/definitions/changesets) on the root to generate the atomic aggregate write path.
|
|
82
82
|
- **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
|
|
83
83
|
|
|
84
84
|
### Column Types
|
|
@@ -95,6 +95,7 @@ A few mechanics to know:
|
|
|
95
95
|
| `q.enum(['a','b'])` | `text(..., { enum: [...] })` | `z.enum([...])` |
|
|
96
96
|
| `q.id()` | `text('id').primaryKey()` | `z.string()` |
|
|
97
97
|
| `q.scope(kind)` | `text(...).notNull()` | `z.string()` |
|
|
98
|
+
| `q.stamp({ fromScope, claim })` | `text(...).notNull()` (nullable with `optional: true`) | `z.string().optional()` |
|
|
98
99
|
|
|
99
100
|
`q.text()` and `q.url()` accept either a SQL-name string or an options object — `q.text({ sqlName: 'org_id', maxLength: 80 })`. `maxLength` adds `z.string().max(n)` at the validation edge; the SQL column stays `text` (D1 ignores `VARCHAR(n)` length anyway).
|
|
100
101
|
|
|
@@ -132,6 +133,38 @@ ownerId: q.scope('owner', { source: 'ctx.userId' }),
|
|
|
132
133
|
|
|
133
134
|
`q.scope()` is preferred over `q.text().required()` for tenant columns. Auto-detection on column names (`organizationId`, `userId`, etc.) still works as a fallback for projects bringing forward Drizzle schemas, but the explicit `q.scope()` form locks in the semantics in the source.
|
|
134
135
|
|
|
136
|
+
### q.stamp() — proven-principal identity columns
|
|
137
|
+
|
|
138
|
+
`q.stamp({ fromScope, claim })` server-stamps a column from a **proven** scope claim — the caller's own identity within a relationship they were cryptographically proven to hold (e.g. an event attendee's own guest id). It is the identity sibling of `q.scope`:
|
|
139
|
+
|
|
140
|
+
| | `q.scope('<kind>')` | `q.stamp({ fromScope, claim })` |
|
|
141
|
+
|---|---|---|
|
|
142
|
+
| **Purpose** | tenant isolation column | proven-principal **identity** column |
|
|
143
|
+
| **Value** | `ctx.scope.<kind>.id` / `activeOrgId` / `userId` | `ctx.scope.<kind>.<claim>` (`id` \| `subjectId` \| a scalar sub-key) |
|
|
144
|
+
| **Firewall arm?** | **yes** — it is the tenant `WHERE` | **never** — identity is not a tenant scope |
|
|
145
|
+
| **Guarantee** | "stamp **and verify**" (firewall re-checks on read/patch/delete) | "stamp **and prove**" (un-spoofable by token provenance) |
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
columns: {
|
|
149
|
+
eventId: q.scope('event'), // tenant firewall column
|
|
150
|
+
authorId: q.stamp({ fromScope: 'event', claim: 'subjectId' }), // proven identity — un-spoofable
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**Runtime precedence — the org/admin hierarchy takes priority.** The stamp fires **only when the caller is admitted as a scope-only principal** (a scope-token holder, `ctx.scopePrincipal === true`): the column is force-stamped from the proven claim and any client-sent value is ignored. A caller admitted via the **org role hierarchy** (member / admin / owner) writes the column through the **org path** — a normal client-settable value, bounded by the org firewall (this is legitimate org-admin capability over their own org's rows). So a table whose `create` admits *both* org roles and a scope role needs **no split**: each identity writes the column the way its principal allows. The invariant that always holds is that a scope-only principal can never set a scope-stamped column to anything but its proven token.
|
|
155
|
+
|
|
156
|
+
**Fail-closed.** If a scope-only caller reaches the write without the required claim (`ctx.scope.<kind>.<claim>` absent) the write is refused with **403** *before* the insert — never a `NULL` identity row — for nullable stamp columns too. A `q.stamp` column may not also be a firewall arm, live on an `exception: true` table, or be sourced from a set-valued sub-key; each is a compile error.
|
|
157
|
+
|
|
158
|
+
`optional: true` makes the DDL column nullable (an org caller may then omit it); it does **not** relax the scope-principal 403.
|
|
159
|
+
|
|
160
|
+
**Set-on-insert, immutable thereafter.** A `q.stamp` column is a **create-time identity** — it is never re-derived on update. On every update-shaped write (`PATCH`, `PUT`, batch update, upsert, and a changeset root/child patch) the column is **systemManaged**: a client value for it is **rejected** (400), regardless of your `guards.updatable` list. Re-keying a proven identity is not an operation. (The force-stamp and the org-writable-on-create allowance apply to the create path only.)
|
|
161
|
+
|
|
162
|
+
**A non-nullable stamp on the org path must be supplied by the caller.** The force-stamp fires for scope-only principals; an org-admitted caller writes the column as normal client input. So a `NOT NULL` `q.stamp` column (the default) that an org caller *omits* lands on the database `NOT NULL` constraint (a deterministic field-named 400), not a NULL row. Add the column to `guards.createable` so org callers can supply it, or mark it `optional: true` if an org-created row may legitimately have no identity.
|
|
163
|
+
|
|
164
|
+
**The scope-only lane needs a scope-reachable write.** The force-stamp only runs once the scope-only principal actually *reaches* the insert. A table with a **hard organization firewall arm** (an `organizationId` sourced from `ctx.activeOrgId`) emits an `ORG_REQUIRED` gate that denies a sessionless scope principal (who has no active org) *before* the stamp — so on such tables the stamp serves the **org-admitted** caller, and the scope-only principal writes these rows as a **changeset child** that *inherits* `organizationId` from a firewall-verified parent. For a plain create/batch by a scope-only principal, firewall the table on the **scope** arm only (e.g. `firewall: { any: [{ field: 'eventId', equals: 'ctx.scope.event' }] }`, no org column) so no `ORG_REQUIRED` gate is emitted.
|
|
165
|
+
|
|
166
|
+
**Idempotency (at-least-once).** The stamp rides inside the write, so it inherits the endpoint's replay semantics: a **keyed** replay (a repeated `Idempotency-Key` whose handler is skipped) neither re-writes nor re-stamps; a **keyless** retry re-writes and therefore re-stamps from the caller's then-current proven claim.
|
|
167
|
+
|
|
135
168
|
### Naming Convention
|
|
136
169
|
|
|
137
170
|
By default, `q` picks the SQL column name from the JS key using the target database's conventional casing. Both `cloudflare-d1` and `neon` default to **`snake_case`** (`organizationId` → `organization_id`).
|
|
@@ -490,6 +523,8 @@ ownerId: text('owner_id').notNull()
|
|
|
490
523
|
teamId: text('team_id').notNull()
|
|
491
524
|
```
|
|
492
525
|
|
|
526
|
+
Those three are **tenant** auto-stamps (org / owner / team). To auto-stamp a **proven-principal identity** column instead — the caller's own id within a relationship, not a tenant key — use [`q.stamp()`](#qstamp--proven-principal-identity-columns). It sources from `ctx.scope.<kind>.<claim>` for scope-only principals and, unlike the tenant stamps, is never a firewall arm.
|
|
527
|
+
|
|
493
528
|
## Display Column
|
|
494
529
|
|
|
495
530
|
When a table has foreign key columns (e.g., `departmentId` referencing `departments`), Quickback can automatically resolve the human-readable label in GET and LIST responses. This eliminates the need for frontend lookup calls.
|
|
@@ -21,7 +21,12 @@ Most scope principals are signed-in users who prove a relationship at [`/scope/v
|
|
|
21
21
|
|
|
22
22
|
### 1. Declare relationships + scopes
|
|
23
23
|
|
|
24
|
-
A scope **kind** (`event`) declares named **roles**, each conferred by a relationship whose `from` row carries the role (and optionally a **sub-key** for row slicing)
|
|
24
|
+
A scope **kind** (`event`) declares named **roles**, each conferred by a relationship whose `from` row carries the role (and optionally a **sub-key** for row slicing).
|
|
25
|
+
|
|
26
|
+
Scope kinds declare at root `authz` (visible everywhere) or inside a
|
|
27
|
+
[feature area](/compiler/definitions/feature-areas)'s `_area.ts` — then the kind, its bare
|
|
28
|
+
role aliases, the canonical `scope:<kind>:<role>` spellings, and `ctx.scope.<kind>` accessors
|
|
29
|
+
are all visible to that area's subtree only (any outside reference is a compile error):
|
|
25
30
|
|
|
26
31
|
```typescript
|
|
27
32
|
// quickback.config.ts
|
|
@@ -173,6 +178,23 @@ kinds map to their session fields (`organization` → `ctx.activeOrgId`,
|
|
|
173
178
|
`owner` → `ctx.userId`, `team` → `ctx.activeTeamId`); any other kind maps to
|
|
174
179
|
`ctx.scope.<kind>.id`.
|
|
175
180
|
|
|
181
|
+
### Stamping a proven *identity* claim (`q.stamp`)
|
|
182
|
+
|
|
183
|
+
`q.scope('event')` stamps the **tenant** id (`ctx.scope.event.id`). To stamp a
|
|
184
|
+
different **proven claim** off the same verified scope — the caller's own
|
|
185
|
+
`subjectId` (the conferring row's PK) or a scalar sub-key — use
|
|
186
|
+
[`q.stamp`](/compiler/definitions/schema#qstamp--proven-principal-identity-columns):
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
authorId: q.stamp({ fromScope: 'event', claim: 'subjectId' }),
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Every proven scope carries `id`, `subjectId`, and any projected sub-keys; a
|
|
193
|
+
`q.stamp` column reads one of those. Unlike `q.scope` it is **never** a firewall
|
|
194
|
+
arm (identity is not a tenant scope), and it force-stamps **only** for scope-only
|
|
195
|
+
principals — an org member/admin/owner writes it via the org path. A scope-only
|
|
196
|
+
caller missing the claim gets a fail-closed **403**, never a `NULL` row.
|
|
197
|
+
|
|
176
198
|
## Namespace scope-claim refresh
|
|
177
199
|
|
|
178
200
|
A scope is normally minted at `POST /scope/v1/enter`. When you also mount a
|
|
@@ -286,34 +286,33 @@ on staging or production targets. Wrangler uses this field only for local
|
|
|
286
286
|
development; deployed Workers obtain their
|
|
287
287
|
connection string from the Hyperdrive configuration identified by `id`.
|
|
288
288
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
`
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
</Callout>
|
|
289
|
+
> The generated setup uses three Postgres roles: `quickback_owner` (NOLOGIN object
|
|
290
|
+
> owner for the app/auth schemas), `quickback_admin` (migration/setup actor — use
|
|
291
|
+
> its unpooled URL for `DATABASE_MIGRATION_URL`), and `quickback` (the Worker
|
|
292
|
+
> runtime role, the **only** deployed DB role — use its pooled URL for
|
|
293
|
+
> `DATABASE_URL`). The first generated migration bootstraps these roles as
|
|
294
|
+
> NOLOGIN; enable login and set passwords before use. Full walkthrough in the
|
|
295
|
+
> generated `docs/neon-setup.md`.
|
|
296
|
+
>
|
|
297
|
+
> Run the **first** `db:migrate` with your database owner credential (Neon's
|
|
298
|
+
> `neondb_owner`) — that bootstrap run also grants `quickback_admin` everything
|
|
299
|
+
> the Drizzle journal needs (`CREATE` on the database, plus ownership of the
|
|
300
|
+
> `drizzle` schema and `drizzle.__drizzle_migrations`). Routine migrates **after**
|
|
301
|
+
> bootstrap — applying new schema deltas — then run entirely as `quickback_admin`
|
|
302
|
+
> via `DATABASE_MIGRATION_URL`, no owner credential required. This includes the
|
|
303
|
+
> pinned runner's `CREATE SCHEMA IF NOT EXISTS drizzle` preamble, which needs
|
|
304
|
+
> database-level `CREATE` even as a no-op and previously forced every migrate
|
|
305
|
+
> back onto the owner credential. (A change to the **security/RLS config** appends
|
|
306
|
+
> a new `quickback_rls` migration that re-runs the role bootstrap, so re-point
|
|
307
|
+
> `DATABASE_MIGRATION_URL` at the owner credential for that one apply.)
|
|
308
|
+
>
|
|
309
|
+
> Each security migration first removes direct `PUBLIC` and `quickback` runtime
|
|
310
|
+
> privileges from the Drizzle schema, journal table, journal sequences, and
|
|
311
|
+
> database-level `CREATE`, then restores the migration role's capability. The
|
|
312
|
+
> audit schema/table likewise revoke prior direct grants before restoring only
|
|
313
|
+
> runtime schema usage + table `INSERT` and admin forensic access. Reapplying a
|
|
314
|
+
> migration therefore converges privilege drift instead of merely adding grants.
|
|
315
|
+
|
|
317
316
|
|
|
318
317
|
## Better Auth schema generation
|
|
319
318
|
|
|
@@ -277,6 +277,8 @@ fail-fast per-record loop, `meta.transactional: false`.
|
|
|
277
277
|
| `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
|
|
278
278
|
| `POST /batch` (create) | (any) | (any) | `true` | Single bulk `INSERT` — atomic at the DB level. |
|
|
279
279
|
| `DELETE /batch` | (any) | (any) | `true` | Single bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. |
|
|
280
|
+
| [Changeset](/compiler/definitions/changesets) (`application/vnd.quickback.changeset+json`, contract v2) | tx-supporting (postgres, neon over websocket/hyperdrive) | n/a | `true` | Root op + every child op share one transaction; any op failure rolls back the whole changeset. |
|
|
281
|
+
| [Changeset](/compiler/definitions/changesets) | cloudflare-d1, neon over http (Cloudflare default) | n/a | `false` | Deterministic parent-first fail-fast — the first op failure stops the changeset; already-applied ops stay committed (a consistent, independently-authorized prefix). |
|
|
280
282
|
|
|
281
283
|
### Reading `meta.transactional` in clients
|
|
282
284
|
|
|
@@ -13,15 +13,32 @@ The generated API returns structured error responses with consistent fields acro
|
|
|
13
13
|
| `401` | Unauthorized | Missing or expired authentication |
|
|
14
14
|
| `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
|
|
15
15
|
| `404` | Not Found | Record doesn't exist (or firewall blocked with `errorMode: 'hide'`) |
|
|
16
|
+
| `409` | Conflict | Unique constraint hit, or a duplicate [`Idempotency-Key`](/stack/api-contract#idempotency-key) still in flight |
|
|
17
|
+
| `412` | Precondition Failed | [Changeset](/compiler/definitions/changesets) `If-Match` revision mismatch |
|
|
18
|
+
| `422` | Unprocessable | `Idempotency-Key` reused with a different request or principal |
|
|
19
|
+
| `428` | Precondition Required | `If-Match` sent where no revision exists (root without `updatedAt`, or the POST changeset variant) |
|
|
16
20
|
| `429` | Too Many Requests | Rate limit exceeded |
|
|
21
|
+
| `500` | Internal Error | Uncaught throw — generic body, full error server-side |
|
|
17
22
|
|
|
18
|
-
## Error Response Format
|
|
23
|
+
## Error Response Format — RFC 9457 Problem Details
|
|
19
24
|
|
|
20
|
-
|
|
25
|
+
Every top-level error response is an
|
|
26
|
+
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details document,
|
|
27
|
+
served as `application/problem+json` (see
|
|
28
|
+
[API Contract](/stack/api-contract)).
|
|
29
|
+
Quickback's contextual fields (`code`, `layer`, `details`, `hint`, `request`)
|
|
30
|
+
survive as 9457 **extension members**, so clients that switch on `code` keep
|
|
31
|
+
working. Every structured error also carries a `request` block with the HTTP
|
|
32
|
+
method, URL, request ID, and a redacted+truncated copy of the request body —
|
|
33
|
+
enough to triage or hand the response to an LLM agent without grepping logs:
|
|
21
34
|
|
|
22
35
|
```json
|
|
23
36
|
{
|
|
24
|
-
"
|
|
37
|
+
"type": "https://quickback.dev/problems/access-role-required",
|
|
38
|
+
"title": "Access role required",
|
|
39
|
+
"status": 403,
|
|
40
|
+
"detail": "Insufficient permissions",
|
|
41
|
+
"instance": "/api/v1/candidates/cnd_01H.../advance",
|
|
25
42
|
"layer": "access",
|
|
26
43
|
"code": "ACCESS_ROLE_REQUIRED",
|
|
27
44
|
"details": {
|
|
@@ -40,12 +57,21 @@ All errors use a flat structure with contextual fields. Every structured error r
|
|
|
40
57
|
|
|
41
58
|
| Field | Type | Description |
|
|
42
59
|
|-------|------|-------------|
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
60
|
+
| `type` | string | Problem type URI — `https://quickback.dev/problems/<code-in-kebab-case>` |
|
|
61
|
+
| `title` | string | Human-stable summary derived from the code |
|
|
62
|
+
| `status` | number | The HTTP status, repeated in the body |
|
|
63
|
+
| `detail` | string | Human-readable error message (optional) |
|
|
64
|
+
| `instance` | string | Request path (optional) |
|
|
65
|
+
| `layer` | string | Extension — security layer that rejected the request |
|
|
66
|
+
| `code` | string | Extension — machine-readable error code (the full enum ships in `openapi.json` as `Problem.code`) |
|
|
67
|
+
| `details` | object | Extension — layer-specific context (optional) |
|
|
68
|
+
| `pointer` | string | Extension — first offending field for validation failures, e.g. `/stage` (optional) |
|
|
69
|
+
| `hint` | string | Extension — actionable guidance for resolution (optional) |
|
|
70
|
+
| `request` | object | Extension — method, URL, redacted body, and request ID. Auto-attached by the runtime so the error body is self-contained — bodies are capped at 4 KB and well-known sensitive keys (`password`, `token`, `secret`, `apiKey`, `otp`, `code`, `authorization`, …) are replaced with `"[REDACTED]"` |
|
|
71
|
+
|
|
72
|
+
The per-layer examples below are abbreviated to `detail` plus each layer's
|
|
73
|
+
extension members — every real response also carries `type`, `title`,
|
|
74
|
+
`status`, and (where derivable) `instance`.
|
|
49
75
|
|
|
50
76
|
## Errors by Security Layer
|
|
51
77
|
|
|
@@ -55,7 +81,7 @@ Missing or invalid authentication tokens.
|
|
|
55
81
|
|
|
56
82
|
```json
|
|
57
83
|
{
|
|
58
|
-
"
|
|
84
|
+
"detail": "Authentication required",
|
|
59
85
|
"layer": "authentication",
|
|
60
86
|
"code": "AUTH_MISSING",
|
|
61
87
|
"hint": "Include Authorization header with Bearer token"
|
|
@@ -78,7 +104,7 @@ Records outside the user's firewall scope return **403 Forbidden** by default wi
|
|
|
78
104
|
|
|
79
105
|
```json
|
|
80
106
|
{
|
|
81
|
-
"
|
|
107
|
+
"detail": "Record not found or not accessible",
|
|
82
108
|
"layer": "firewall",
|
|
83
109
|
"code": "FIREWALL_NOT_FOUND",
|
|
84
110
|
"hint": "Check the record ID and your organization membership"
|
|
@@ -104,7 +130,7 @@ Access violations return **403 Forbidden** when the user's role doesn't match th
|
|
|
104
130
|
|
|
105
131
|
```json
|
|
106
132
|
{
|
|
107
|
-
"
|
|
133
|
+
"detail": "Insufficient permissions",
|
|
108
134
|
"layer": "access",
|
|
109
135
|
"code": "ACCESS_ROLE_REQUIRED",
|
|
110
136
|
"details": {
|
|
@@ -130,12 +156,13 @@ Guard violations return **400 Bad Request** when the request body contains field
|
|
|
130
156
|
|
|
131
157
|
```json
|
|
132
158
|
{
|
|
133
|
-
"
|
|
159
|
+
"detail": "Field cannot be set during creation",
|
|
134
160
|
"layer": "guards",
|
|
135
161
|
"code": "GUARD_FIELD_NOT_CREATEABLE",
|
|
136
162
|
"details": {
|
|
137
163
|
"fields": ["stage"]
|
|
138
164
|
},
|
|
165
|
+
"pointer": "/stage",
|
|
139
166
|
"hint": "These fields are set automatically or must be omitted"
|
|
140
167
|
}
|
|
141
168
|
```
|
|
@@ -160,7 +187,7 @@ Surfaced when a SQL write fails *post-validation* — most often a `NOT NULL` or
|
|
|
160
187
|
|
|
161
188
|
```json
|
|
162
189
|
{
|
|
163
|
-
"
|
|
190
|
+
"detail": "Duplicate value",
|
|
164
191
|
"layer": "database",
|
|
165
192
|
"code": "DB_UNIQUE_VIOLATION",
|
|
166
193
|
"details": { "column": "email" },
|
|
@@ -188,6 +215,11 @@ Batch operations can return:
|
|
|
188
215
|
|
|
189
216
|
### Partial Success (207)
|
|
190
217
|
|
|
218
|
+
A 207 body is a **success envelope** (plain `application/json`, not
|
|
219
|
+
`application/problem+json`) — the per-record `error` objects embedded in it
|
|
220
|
+
keep the internal flat shape (`error` message field, `layer`, `code`,
|
|
221
|
+
`details`, `hint`):
|
|
222
|
+
|
|
191
223
|
```json
|
|
192
224
|
{
|
|
193
225
|
"success": [{ "id": "app_1", "candidateId": "cand_101", "stage": "applied" }],
|
|
@@ -212,7 +244,7 @@ Batch operations can return:
|
|
|
212
244
|
|
|
213
245
|
```json
|
|
214
246
|
{
|
|
215
|
-
"
|
|
247
|
+
"detail": "Batch operation failed in atomic mode",
|
|
216
248
|
"layer": "validation",
|
|
217
249
|
"code": "BATCH_ATOMIC_FAILED",
|
|
218
250
|
"details": {
|
|
@@ -243,7 +275,7 @@ cause, or stack frames. The raw error is always logged server-side.
|
|
|
243
275
|
|
|
244
276
|
```json
|
|
245
277
|
{
|
|
246
|
-
"
|
|
278
|
+
"detail": "Action execution failed",
|
|
247
279
|
"layer": "action",
|
|
248
280
|
"code": "ACTION_EXECUTION_FAILED",
|
|
249
281
|
"details": {
|
|
@@ -269,7 +301,7 @@ the response → log correlation is one grep.
|
|
|
269
301
|
|
|
270
302
|
```json
|
|
271
303
|
{
|
|
272
|
-
"
|
|
304
|
+
"detail": "Internal error",
|
|
273
305
|
"layer": "database",
|
|
274
306
|
"code": "INTERNAL_ERROR",
|
|
275
307
|
"details": { "operation": "request handling" },
|
|
@@ -195,3 +195,69 @@ This request:
|
|
|
195
195
|
| `search` | LIST, VIEW | Search text across all text columns |
|
|
196
196
|
| `field=value` | LIST, VIEW | Filter by exact match |
|
|
197
197
|
| `field.op=value` | LIST, VIEW | Filter with operator (gt, gte, lt, lte, ne, like, in) |
|
|
198
|
+
| `starting_after` | LIST, VIEW | Opaque keyset cursor — rows strictly after the boundary |
|
|
199
|
+
| `ending_before` | LIST, VIEW | Opaque keyset cursor — rows strictly before the boundary |
|
|
200
|
+
| `include` | LIST, VIEW, GET | FK-graph embedding (contract v2, allowlisted — see below) |
|
|
201
|
+
| `fields[<fk>]` | LIST, VIEW, GET | Sparse fields for an embedded include target (contract v2) |
|
|
202
|
+
|
|
203
|
+
## Include & Sparse Fields (contract v2)
|
|
204
|
+
|
|
205
|
+
On the v2 contract a resource can allowlist FK columns for **FK-graph
|
|
206
|
+
embedding**, collapsing client-side N+1 fetches:
|
|
207
|
+
|
|
208
|
+
```ts title="quickback/features/orders/order-items.ts"
|
|
209
|
+
export default feature("orderItems", {
|
|
210
|
+
columns: {
|
|
211
|
+
id: q.id(),
|
|
212
|
+
orderId: q.text().required().references(() => orders.id),
|
|
213
|
+
organizationId: q.scope("organization"),
|
|
214
|
+
},
|
|
215
|
+
read: {
|
|
216
|
+
access: { roles: ["member", "admin"] },
|
|
217
|
+
include: ["orderId"], // FK columns eligible for ?include=
|
|
218
|
+
},
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
GET /api/v2/order-items?include=orderId&fields[orderId]=id,total
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
```json
|
|
227
|
+
{
|
|
228
|
+
"data": [ { "id": "oi_1", "orderId": "ord_9" } ],
|
|
229
|
+
"included": { "orderId": { "ord_9": { "id": "ord_9", "total": 129 } } }
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Embedded rows land in a **top-level `included` map** keyed by FK column, then
|
|
234
|
+
by target primary key — row objects are never mutated.
|
|
235
|
+
|
|
236
|
+
**Security semantics (all enforced, fail-closed):**
|
|
237
|
+
|
|
238
|
+
- An embedded read **is a read of the target resource**: the target's own
|
|
239
|
+
`read.access` is checked before any fetch (403 on failure, never silent
|
|
240
|
+
omission), the child query runs under the target's tenant firewall on the
|
|
241
|
+
caller's own database handle, and embedded rows pass through the target's
|
|
242
|
+
masking before attachment.
|
|
243
|
+
- Targets whose `read.access` is **record-aware** (function access, `record:`
|
|
244
|
+
conditions, `relationship` or `fga` arms) are refused **at compile time** —
|
|
245
|
+
embedding them would skip their post-fetch record checks.
|
|
246
|
+
- A tenant-scoped target with no resolvable firewall clause is a compile
|
|
247
|
+
error; a global reference table must opt out explicitly with
|
|
248
|
+
`firewall: { exception: true }`. Even then, the child fetch still calls
|
|
249
|
+
the target's own firewall helper — for a soft-deleting reference table
|
|
250
|
+
that helper is the soft-delete predicate, so an embed never serves rows
|
|
251
|
+
the target's own routes refuse.
|
|
252
|
+
- `?include=` on a resource (or view) without an allowlist is a **400**.
|
|
253
|
+
Explicit views declare their own `include: [...]` — nothing is expandable
|
|
254
|
+
undeclared. Depth is exactly 1. A view that declares `include` must keep
|
|
255
|
+
each listed FK column in its `fields` projection (compile error
|
|
256
|
+
otherwise — the embedded lookup pivots on that column).
|
|
257
|
+
|
|
258
|
+
**Strict fields on v2:** unknown names in bare `?fields=` and in
|
|
259
|
+
`fields[<fk>]=` are rejected with a 400 Problem. (Pinned v1 keeps its
|
|
260
|
+
historical silent-drop for bare `?fields=`.) A `?fields=` projection that
|
|
261
|
+
drops the FK column of a requested `?include=` is also a **400** —
|
|
262
|
+
`include=orderId requires "orderId" in ?fields=` — never a silently-empty
|
|
263
|
+
`included` slot.
|