@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.
Files changed (95) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +41 -4
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/create.d.ts.map +1 -1
  5. package/dist/commands/create.js +5 -1
  6. package/dist/commands/create.js.map +1 -1
  7. package/dist/docs/content.d.ts.map +1 -1
  8. package/dist/docs/content.js +37 -22
  9. package/dist/docs/content.js.map +1 -1
  10. package/dist/index.js +1 -1
  11. package/dist/lib/action-harvest.d.ts +16 -1
  12. package/dist/lib/action-harvest.d.ts.map +1 -1
  13. package/dist/lib/action-harvest.js +21 -1
  14. package/dist/lib/action-harvest.js.map +1 -1
  15. package/dist/lib/action-harvest.test.js +122 -3
  16. package/dist/lib/action-harvest.test.js.map +1 -1
  17. package/dist/lib/api-client.d.ts +11 -0
  18. package/dist/lib/api-client.d.ts.map +1 -1
  19. package/dist/lib/api-client.js.map +1 -1
  20. package/dist/lib/artifact-routing.d.ts.map +1 -1
  21. package/dist/lib/artifact-routing.js +3 -0
  22. package/dist/lib/artifact-routing.js.map +1 -1
  23. package/dist/lib/compiler-floor.d.ts +39 -0
  24. package/dist/lib/compiler-floor.d.ts.map +1 -0
  25. package/dist/lib/compiler-floor.js +75 -0
  26. package/dist/lib/compiler-floor.js.map +1 -0
  27. package/dist/lib/compiler-floor.test.d.ts +2 -0
  28. package/dist/lib/compiler-floor.test.d.ts.map +1 -0
  29. package/dist/lib/compiler-floor.test.js +67 -0
  30. package/dist/lib/compiler-floor.test.js.map +1 -0
  31. package/dist/lib/compiler-stubs.d.ts +6 -0
  32. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  33. package/dist/lib/compiler-stubs.js +8 -0
  34. package/dist/lib/compiler-stubs.js.map +1 -1
  35. package/dist/lib/file-loader.d.ts +45 -4
  36. package/dist/lib/file-loader.d.ts.map +1 -1
  37. package/dist/lib/file-loader.js +116 -19
  38. package/dist/lib/file-loader.js.map +1 -1
  39. package/dist/lib/file-loader.test.js +80 -4
  40. package/dist/lib/file-loader.test.js.map +1 -1
  41. package/dist/skill/SKILL.md +3 -1
  42. package/dist/skill/docs/changelog.md +66 -0
  43. package/dist/skill/docs/compiler/config/index.md +14 -1
  44. package/dist/skill/docs/compiler/config/providers.md +13 -9
  45. package/dist/skill/docs/compiler/definitions/access.md +134 -2
  46. package/dist/skill/docs/compiler/definitions/actions.md +22 -0
  47. package/dist/skill/docs/compiler/definitions/changesets.md +375 -0
  48. package/dist/skill/docs/compiler/definitions/feature-areas.md +189 -0
  49. package/dist/skill/docs/compiler/definitions/feature.md +33 -0
  50. package/dist/skill/docs/compiler/definitions/firewall.md +60 -1
  51. package/dist/skill/docs/compiler/definitions/guards.md +14 -0
  52. package/dist/skill/docs/compiler/definitions/index.md +28 -3
  53. package/dist/skill/docs/compiler/definitions/masking.md +8 -0
  54. package/dist/skill/docs/compiler/definitions/read.md +13 -0
  55. package/dist/skill/docs/compiler/definitions/schema.md +36 -1
  56. package/dist/skill/docs/compiler/definitions/scopes.md +23 -1
  57. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +27 -28
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +2 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +49 -17
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +66 -0
  61. package/dist/skill/docs/stack/api-contract/index.md +136 -0
  62. package/dist/skill/docs/stack/realtime/durable-objects.md +7 -0
  63. package/dist/skill/docs/stack/realtime/index.md +22 -0
  64. package/dist/skill/docs/stack/realtime/live-views.md +56 -0
  65. package/dist/skill/docs/stack/realtime/using-realtime.md +53 -0
  66. package/dist/skill/docs/stack/webhooks/inbound.md +79 -0
  67. package/dist/skill/docs/stack/webhooks/outbound.md +33 -0
  68. package/package.json +1 -1
  69. package/src/skill/SKILL.md +3 -1
  70. package/src/skill/docs/changelog.md +66 -0
  71. package/src/skill/docs/compiler/config/index.md +14 -1
  72. package/src/skill/docs/compiler/config/providers.md +13 -9
  73. package/src/skill/docs/compiler/definitions/access.md +134 -2
  74. package/src/skill/docs/compiler/definitions/actions.md +22 -0
  75. package/src/skill/docs/compiler/definitions/changesets.md +375 -0
  76. package/src/skill/docs/compiler/definitions/feature-areas.md +189 -0
  77. package/src/skill/docs/compiler/definitions/feature.md +33 -0
  78. package/src/skill/docs/compiler/definitions/firewall.md +60 -1
  79. package/src/skill/docs/compiler/definitions/guards.md +14 -0
  80. package/src/skill/docs/compiler/definitions/index.md +28 -3
  81. package/src/skill/docs/compiler/definitions/masking.md +8 -0
  82. package/src/skill/docs/compiler/definitions/read.md +13 -0
  83. package/src/skill/docs/compiler/definitions/schema.md +36 -1
  84. package/src/skill/docs/compiler/definitions/scopes.md +23 -1
  85. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +27 -28
  86. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +2 -0
  87. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +49 -17
  88. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +66 -0
  89. package/src/skill/docs/stack/api-contract/index.md +136 -0
  90. package/src/skill/docs/stack/realtime/durable-objects.md +7 -0
  91. package/src/skill/docs/stack/realtime/index.md +22 -0
  92. package/src/skill/docs/stack/realtime/live-views.md +56 -0
  93. package/src/skill/docs/stack/realtime/using-realtime.md +53 -0
  94. package/src/skill/docs/stack/webhooks/inbound.md +79 -0
  95. package/src/skill/docs/stack/webhooks/outbound.md +33 -0
@@ -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
- All errors use a flat structure with contextual fields. Every structured error response also carries a `request` block with the HTTP method, URL, request ID, and a redacted+truncated copy of the request body — enough to triage or hand the response to an LLM agent without grepping logs:
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
- "error": "Insufficient permissions",
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
- | `error` | string | Human-readable error message |
44
- | `layer` | string | Security layer that rejected the request |
45
- | `code` | string | Machine-readable error code |
46
- | `details` | object | Layer-specific context (optional) |
47
- | `hint` | string | Actionable guidance for resolution (optional) |
48
- | `request` | object | 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]"` |
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
- "error": "Authentication required",
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
- "error": "Record not found or not accessible",
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
- "error": "Insufficient permissions",
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
- "error": "Field cannot be set during creation",
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
- "error": "Duplicate value",
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
- "error": "Batch operation failed in atomic mode",
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
- "error": "Action execution failed",
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
- "error": "Internal error",
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.
@@ -0,0 +1,136 @@
1
+ # API Contract
2
+
3
+ Every generated API speaks one public HTTP contract, selected once per project:
4
+
5
+ ```ts title="quickback/quickback.config.ts"
6
+ export default defineConfig({
7
+ // Omitted = v1 (the pinned compatibility mode for already-deployed clients).
8
+ contract: { version: "v2" },
9
+ // ...
10
+ });
11
+ ```
12
+
13
+ **v2 is the flagship contract.** Everything new lands on v2; projects pinned to
14
+ v1 keep today's byte-stable wire and receive no new contract features until
15
+ they migrate.
16
+
17
+ ## Response envelope
18
+
19
+ Collection reads return a flat envelope; single reads return the resource
20
+ object itself:
21
+
22
+ ```json
23
+ {
24
+ "data": [ { "id": "po_1", "vendorId": "ven_1", "status": "open" } ],
25
+ "pagination": { "count": 1, "page": 1, "pageSize": 50, "hasMore": false,
26
+ "nextCursor": "…", "prevCursor": null },
27
+ "included": { "vendorId": { "ven_1": { "id": "ven_1", "name": "Acme" } } }
28
+ }
29
+ ```
30
+
31
+ `included` appears only when the request carried `?include=` (contract v2 —
32
+ see [query params](/compiler/targets/hono-api/using-the-api/query-params)).
33
+
34
+ ## Errors — RFC 9457 Problem Details
35
+
36
+ Every error response is `application/problem+json`:
37
+
38
+ ```json
39
+ {
40
+ "type": "https://quickback.dev/problems/access-role-required",
41
+ "title": "Access role required",
42
+ "status": 403,
43
+ "detail": "Access denied",
44
+ "instance": "/api/v2/purchase-orders",
45
+ "code": "ACCESS_ROLE_REQUIRED",
46
+ "layer": "access"
47
+ }
48
+ ```
49
+
50
+ The internal fields (`code`, `layer`, `details`, `hint`, `request`) survive as
51
+ extension members, so clients that switch on `code` keep working. The full
52
+ code catalog ships in `openapi.json` as the `Problem.code` enum.
53
+
54
+ ## Cursor pagination
55
+
56
+ List endpoints accept an opaque keyset cursor alongside classic
57
+ `?limit=`/`?offset=`:
58
+
59
+ | Param | Meaning |
60
+ |---|---|
61
+ | `?starting_after=<cursor>` | rows strictly after the boundary (forward) |
62
+ | `?ending_before=<cursor>` | rows strictly before the boundary (backward) |
63
+ | `?total=true` | opt into a counted total |
64
+
65
+ `pagination.nextCursor` / `prevCursor` carry the boundaries. Cursors are
66
+ opaque — never parse them.
67
+
68
+ ## Idempotency-Key
69
+
70
+ Any `POST`/`PATCH`/`PUT`/`DELETE` may carry an `Idempotency-Key` header (a
71
+ caller-generated UUID, ≤ 255 chars) to make the write safe to retry:
72
+
73
+ - First request **claims** the key (the claim is the concurrency lock) and
74
+ caches the response.
75
+ - A retry with the same key replays the cached response byte-identically with
76
+ `Idempotency-Replayed: true`.
77
+ - A concurrent duplicate gets `409 IDEMPOTENCY_IN_PROGRESS`.
78
+ - Reusing a key for a *different* request (method/path) is a
79
+ `422 IDEMPOTENCY_KEY_REUSED`.
80
+ - Keys expire after **24 hours** (Stripe semantics); 5xx and `Set-Cookie`
81
+ responses release the lock instead of caching.
82
+
83
+ **Claims are bound to the calling principal.** A replay from a different
84
+ principal — another user, another scope subject, a delegated machine
85
+ principal, or a legacy row with no principal — is refused with a `422`
86
+ Problem: the cached response body is **never served to a foreign
87
+ principal**, and nothing beyond the `422` itself leaks. The comparison runs
88
+ before the stale-claim takeover, so a foreign caller can neither read nor
89
+ overwrite your claim.
90
+
91
+ **Unauthenticated requests carrying the header are rejected (400)** — an
92
+ anonymous caller has no principal to bind the claim to. A PUBLIC standalone
93
+ action may opt in explicitly:
94
+
95
+ ```ts title="quickback/features/orders/actions/submitForm.ts"
96
+ export default defineAction({
97
+ path: "/orders/submit-form",
98
+ method: "POST",
99
+ access: { roles: ["PUBLIC"] },
100
+ idempotency: "dedupe", // dedupe-only: duplicate ⇒ 409 reference,
101
+ // the cached body is NEVER served to a second caller
102
+ // ...
103
+ });
104
+ ```
105
+
106
+ ## Contract version matrix
107
+
108
+ Flipping `contract.version` moves the **entire** contract at once — plan the
109
+ client migration as one move:
110
+
111
+ | Surface | v1 (pinned) | v2 (flagship) |
112
+ |---|---|---|
113
+ | API base | `/api/v1` | `/api/v2` |
114
+ | Auth base | `/auth/v1` | `/auth/v2` |
115
+ | Realtime base | `/broadcast/v1` | `/broadcast/v2` |
116
+ | Quickback HMAC-JWT lane | on by default | only with explicit `auth.jwt` |
117
+ | Realtime data frames | raw (byte-stable) | CloudEvents 1.0 envelopes ([realtime](/stack/realtime)) |
118
+ | Outbound webhook signing | Standard Webhooks **+** legacy `X-Webhook-*` | Standard Webhooks **only** |
119
+ | `?include=` FK embedding | not available | available where allowlisted |
120
+ | Aggregate changesets (`application/vnd.quickback.changeset+json` on PATCH/POST, [`owns`](/compiler/definitions/changesets)) | not available | available where `owns` is declared |
121
+ | Bare `?fields=` unknown names | silently dropped | **400** |
122
+ | `fields[<fk>]=` unknown names | n/a | **400** |
123
+ | Action input schemas | best-effort static parse | complete client-side harvest **required** |
124
+
125
+ Sequencing a migration: ship clients that speak the v2 paths, CloudEvents
126
+ frames, and session-first auth (or declare `auth.jwt`); confirm webhook
127
+ consumers validate the `webhook-*` headers; then flip the switch. Until then
128
+ v1 stays byte-identical.
129
+
130
+ ## Machine-readable contract
131
+
132
+ - `GET /openapi.json` — OpenAPI 3.1: Problem responses, cursor params,
133
+ `Idempotency-Key` on every write op, per-resource `include` params.
134
+ - `GET /asyncapi.json` — AsyncAPI 3.0: the realtime channel + named
135
+ invalidation events + outbound webhook messages. Served under the **same**
136
+ auth gating as `/openapi.json` (`openapi.publish`).
@@ -106,6 +106,13 @@ This closes the gap where the single-`role` form denied (`403`) an org admin who
106
106
  could legitimately reach the room through the bulk lane but isn't a confirmed
107
107
  attendee — their realtime socket now opens.
108
108
 
109
+ `wsTicket.namespace` may also name a namespace declared by a
110
+ [feature area](/compiler/definitions/feature-areas) (`_area.ts`). This is the one
111
+ deliberate exception to the rule that root config never references area-declared
112
+ names: namespace-identity wiring attaches the area's **complete** gate (its full
113
+ lane set) and constructs no new grant, so it cannot widen what the area declared.
114
+ Such consumers are listed in `quickback/authz-manifest.json` under the owning area.
115
+
109
116
  > **`scopeTable` must be tenant-scoped.** Before minting, the route loads the
110
117
  > `scopeTable` row by `requestField` through *its own firewall* — so a ticket can
111
118
  > only target a room whose resource resolves under the caller's tenant (an org-A
@@ -157,3 +157,25 @@ missing organization column fails the build with an actionable message.
157
157
  - **[Named Invalidations](/stack/realtime/named-invalidations)** — Typed, targeted "this changed — refresh" signals fired from actions after commit, with optional per-recipient narrowing
158
158
  - **[Live Views](/stack/realtime/live-views)** — Keep an open view's full join-surface (root + related children) live with hybrid-delta updates and resync-on-reconnect
159
159
  - **[PartyServer Rooms](/stack/realtime/partyserver-rooms)** — Per-room collab via `/realtime/<binding>/<room-id>`: presence, live notes, room IDs
160
+
161
+ There are **three declarative emission surfaces** — pick by what did the write:
162
+
163
+ | The write is… | Emit with | Where |
164
+ |---|---|---|
165
+ | A CRUD row change | the table's **`realtime`** block (postgres_changes frames) | this page |
166
+ | A custom action | **`invalidates:`** on the action | [Named invalidations](/stack/realtime/named-invalidations) |
167
+ | An [aggregate changeset](/compiler/definitions/changesets) (`owns`) | **`afterCommit`** on the aggregate root — one CloudEvent after commit | [changesets → afterCommit](/compiler/definitions/changesets#aftercommit--emit-a-realtime-signal-after-the-changeset-commits) |
168
+
169
+ ## CloudEvents (contract v2) + AsyncAPI (any contract)
170
+
171
+ On the v2 contract, realtime data frames are delivered as CloudEvents 1.0
172
+ envelopes on `/broadcast/v2` (control frames stay raw). See
173
+ [Using Realtime](/stack/realtime/using-realtime#cloudevents-envelopes-contract-v2)
174
+ for the frame mapping.
175
+
176
+ The project's event surface — realtime channels, named-invalidation events,
177
+ and outbound webhook messages — is published as an AsyncAPI 3.0 document at
178
+ `GET /asyncapi.json` (same auth gating as `/openapi.json`). The document is
179
+ **contract-version-independent**: it is emitted for any project with realtime
180
+ or webhooks (v1 included); only the message payload *schemas* are shaped by
181
+ the pinned contract — raw frames on v1, CloudEvents envelopes on v2.
@@ -64,6 +64,55 @@ Every included table is read through **its own** `firewall` and `masking` — a
64
64
  subscriber only ever sees related rows they're already allowed to read, masked
65
65
  exactly as they would be on a normal read.
66
66
 
67
+ ## Auth-DB includes (`source: 'auth'`)
68
+
69
+ A view may join **read-only** display data from the Better Auth tables
70
+ (`user`, `member`, `invitation`, `organization`) — the "staff picker" pattern:
71
+
72
+ ```typescript
73
+ export default defineView({
74
+ name: 'staff-board',
75
+ root: 'sessions',
76
+ include: [
77
+ // dereference the creating user's display fields
78
+ { source: 'auth', table: 'user', on: { local: 'createdBy', auth: 'id' },
79
+ fields: ['name', 'email'], as: 'creator' },
80
+ // the creator's role in the caller's org — tenant-anchored
81
+ { source: 'auth', table: 'member', on: { local: 'createdBy', auth: 'userId' },
82
+ tenant: { auth: 'organizationId', equals: 'ctx.activeOrgId' },
83
+ fields: ['role'], as: 'creatorMembership' },
84
+ ],
85
+ });
86
+ ```
87
+
88
+ Auth tables carry no firewall/masking to inherit, so the include **is** the
89
+ security boundary — every rule is fail-closed at compile time:
90
+
91
+ - **`fields` is a mandatory allowlist** of compiler-known display columns
92
+ (deny-by-default; secret/auth-internal tables and columns are never
93
+ exposable).
94
+ - **`tenant` is mandatory for `member` / `invitation`** — those tables hold
95
+ per-organization rows keyed by columns that recur across orgs; an
96
+ un-anchored single-row join would return an arbitrary org's row.
97
+ - An **un-tenanted** join's `on.local` must be a non-writable, auto-stamped
98
+ column (`createdBy` / `modifiedBy`, or the root's declared scope columns) —
99
+ a caller-writable join key would let a caller dereference arbitrary
100
+ identities.
101
+
102
+ With a declared [`authz.tenants` anchor](/compiler/definitions/firewall#named-tenant-anchors-tenant),
103
+ the tenant can be referenced **by name** — same resolved include, same gates:
104
+
105
+ ```typescript
106
+ // quickback.config.ts
107
+ authz: { tenants: { org: { column: 'organizationId', equals: 'ctx.activeOrgId' } } }
108
+
109
+ // the include
110
+ { source: 'auth', table: 'member', on: { local: 'createdBy', auth: 'userId' },
111
+ tenant: 'org', fields: ['role'], as: 'creatorMembership' }
112
+ ```
113
+
114
+ The referenced anchor must bind a **single-segment session claim** (`ctx.<claim>`, e.g. `ctx.activeOrgId`) — the same grammar the inline object form enforces. An anchor bound to a scope-principal claim (`ctx.scope.*`) is valid in firewall lanes but is a compile error when referenced from an auth-view include.
115
+
67
116
  ## Reading a surface
68
117
 
69
118
  The compiler generates a read endpoint per view:
@@ -138,6 +187,13 @@ hook to wire. A write taps its result and, when it used `.returning()`, fans a
138
187
  delta to each affected surface. Soft deletes (an `UPDATE` that sets `deletedAt`)
139
188
  are emitted as `DELETE` so the row leaves the surface.
140
189
 
190
+ **Changeset writes** ([aggregate `owns`](/compiler/definitions/changesets)) do not
191
+ flow through the per-row delta chokepoint — they emit one aggregate-level signal
192
+ via [`afterCommit`](/compiler/definitions/changesets#aftercommit--emit-a-realtime-signal-after-the-changeset-commits)
193
+ on the root. Declare `afterCommit` on the aggregate root so live views observe
194
+ changeset writes; without it the compiler warns that changeset writes to a
195
+ `realtime` table go unobserved.
196
+
141
197
  ## Security
142
198
 
143
199
  - The **subscribe gate** reuses the view materializer: a ticket is only minted
@@ -133,6 +133,14 @@ Custom namespaces (from `defineRealtime()`) use the format `namespace:event` —
133
133
 
134
134
  Events are only delivered to subscribers who fall within the broadcast's audience. A broadcasting table's realtime config **must** declare `access: { roles: [...] }` — e.g. `access: { roles: ["hiring-manager", "recruiter"] }` delivers only to those roles. The audience is evaluated at fanout with the same uppercase pseudo-role semantics as REST (`PUBLIC` = everyone in the room, `AUTHENTICATED`, `USER`, `SYSADMIN`), plus concrete membership/scope roles. This is **fail-closed**: an empty or omitted audience delivers to no one (and is a compile error for a broadcasting resource). Applies to generated CRUD broadcasts and to [live view](/stack/realtime/live-views) `view_changes` deltas alike.
135
135
 
136
+ ### Named rules and gates in `requiredRoles`
137
+
138
+ Declared [`authz.roles`](/compiler/definitions/access#centrally-defined-access-rules) and [`authz.rules` gates](/compiler/definitions/access#named-gates-authzrules) can appear in `realtime.requiredRoles`. The compiler lowers them to flat static role names at build time, because the WebSocket ticket handshake has no DB in hand:
139
+
140
+ - A named role lowers to its composing static roles; relationship (`via:`) arms contribute nothing at the handshake (the row-stream firewall enforces that dimension later) and emit a warning.
141
+ - A **who-only gate** lowers as its `who`. A gate carrying `record:` or `firewall` arms is undecidable at the handshake — it contributes nothing, with a warning.
142
+ - **Fail-closed rule:** a declared non-empty `requiredRoles` that lowers to an **empty** set is a **compile error**, never a silently-assigned `[]`. The error names which entries lowered to nothing and why. Fix it by referencing a who-only rule, adding a static BA/pseudo-role fallback arm, or dropping the undecidable entries and relying on the row-stream firewall.
143
+
136
144
  ### Per-Role Masking
137
145
 
138
146
  Field values are masked according to the subscriber's role. For example, with this masking config:
@@ -204,6 +212,51 @@ tag = "v1"
204
212
  new_classes = ["Broadcaster"]
205
213
  ```
206
214
 
215
+ ## CloudEvents envelopes (contract v2)
216
+
217
+ On `contract: { version: "v2" }` the WebSocket endpoint moves to
218
+ `/broadcast/v2` and every **data frame** is wrapped in a
219
+ [CloudEvents 1.0](https://cloudevents.io) envelope at the Durable Object's
220
+ send boundary. Control frames (`pong`, `error`, `reauth_ok`) stay raw on both
221
+ versions, and pinned-v1 projects keep the raw frames byte-identically.
222
+
223
+ | v1 frame | CloudEvents `type` | `data` | extensions |
224
+ |---|---|---|---|
225
+ | `broadcast` (named invalidation) | the wire name verbatim | payload minus `version`/`reason` | `qbframe: "broadcast"`, `qbversion`, `qbreason` |
226
+ | `postgres_changes` | `<project>.<table>.<insert\|update\|delete>` | `{ table, schema, eventType, new, old }` | `qbframe: "postgres_changes"` |
227
+ | `view_changes` | `<project>.view.<viewName>.changed` | `{ view, rootId, delta }` | `qbframe: "view_changes"`, `qbseq` (the per-surface monotonic seq — your reconnect/gap-detection contract) |
228
+
229
+ Discriminate frames on the `qbframe` extension, **never** on payload keys —
230
+ named-invalidation payloads are author-supplied maps, so a broadcast whose
231
+ payload happens to carry `view`/`delta` or `table`/`eventType` keys must not
232
+ be mistaken for a system frame.
233
+
234
+ A changeset's [`afterCommit`](/compiler/definitions/changesets#aftercommit--emit-a-realtime-signal-after-the-changeset-commits)
235
+ broadcast rides the **same `broadcast` frame** (the referenced typed event's
236
+ `wireName` verbatim), so clients handle it exactly like any named invalidation —
237
+ one CloudEvent per aggregate write, carrying the mapped payload (e.g.
238
+ `{ eventId, reservationId, occupantIds }`). Its optional root-row frame arrives
239
+ as a normal `postgres_changes` frame on the table's room.
240
+
241
+ ```json
242
+ { "specversion": "1.0",
243
+ "id": "evt_9f2…",
244
+ "source": "/broadcast/v2/websocket",
245
+ "type": "event.mobile-bundle.changed",
246
+ "time": "2026-07-20T12:00:00Z",
247
+ "datacontenttype": "application/json",
248
+ "qbframe": "broadcast",
249
+ "qbversion": 1, "qbreason": "document.created",
250
+ "data": { "eventId": "…", "documentId": "…" } }
251
+ ```
252
+
253
+ The bundled CMS unwraps envelopes automatically. The full channel/message
254
+ catalog ships as `GET /asyncapi.json` (AsyncAPI 3.0), served under the same
255
+ auth gating as `/openapi.json`. The catalog itself is not v2-only — any
256
+ project with realtime or webhooks serves it, on either contract version;
257
+ what the pinned contract shapes is the message payload schemas it documents
258
+ (raw frames on v1, the CloudEvents envelopes above on v2).
259
+
207
260
  ## Cloudflare Only
208
261
 
209
262
  Realtime requires Cloudflare Durable Objects and is only available with the Cloudflare runtime.
@@ -241,3 +241,82 @@ wrangler secret put STRIPE_WEBHOOK_SECRET
241
241
 
242
242
  - [Outbound Webhooks](/stack/webhooks/outbound) — Send webhooks when data changes
243
243
  - [Queues](/stack/queues) — Background processing infrastructure
244
+
245
+ ## Verified webhook actions (`webhook:` on defineAction)
246
+
247
+ For gateways that should hit a **custom action** rather than the queued
248
+ `/webhooks/v1/inbound/:provider` pipeline, declare verification on the action
249
+ itself. Verification runs **before** JSON parse, input validation, and access
250
+ evaluation, over the raw request bytes — and it is additive to the access
251
+ gate (a PUBLIC webhook action keeps its public-audit block).
252
+
253
+ ```ts title="quickback/features/comms/actions/sesDeliveryWebhook.ts"
254
+ export default defineAction({
255
+ path: "/comms/hooks/delivery",
256
+ method: "POST",
257
+ access: { roles: ["PUBLIC"] },
258
+ webhook: {
259
+ verify: "standard-webhooks", // webhook-id / webhook-timestamp / webhook-signature
260
+ secretEnv: "SES_WEBHOOK_SECRET", // env binding, validated at compile time
261
+ tolerance: 300, // seconds (default 300)
262
+ },
263
+ input: z.object({ messageId: z.string(), event: z.string() }),
264
+ execute: async ({ input }) => { /* ... */ },
265
+ });
266
+ ```
267
+
268
+ For gateways speaking `sha256=`-hex HMAC instead of Standard Webhooks:
269
+
270
+ ```ts
271
+ webhook: {
272
+ verify: {
273
+ scheme: "hmac-sha256",
274
+ header: "X-Signature",
275
+ prefix: "sha256=",
276
+ timestampHeader: "X-Webhook-Timestamp",
277
+ signedContent: "timestamp.body", // MAC covers `${timestamp}.${rawBody}`
278
+ tolerance: 300,
279
+ },
280
+ secretEnv: "WEBHOOK_SIGNING_SECRET",
281
+ }
282
+ ```
283
+
284
+ **Replay semantics — read this before choosing `signedContent`:** a tolerance
285
+ window only closes replay when the timestamp is *inside* the signed content.
286
+ With `signedContent: "body"` the MAC covers raw bytes only, so a captured
287
+ request can be replayed forever with a fresh timestamp header — which is why
288
+ the compiler **rejects** `tolerance`/`timestampHeader` on body-only schemes
289
+ instead of pretending they help. Pair body-only receivers with
290
+ [`Idempotency-Key`](/stack/api-contract) or gateway-event-id dedupe.
291
+
292
+ For AWS SNS (SES/SMS event topics) — asymmetric X.509 verification, no shared
293
+ secret:
294
+
295
+ ```ts
296
+ webhook: {
297
+ verify: {
298
+ scheme: "aws-sns",
299
+ topicArnsEnv: "AWS_SES_SNS_TOPIC_ARNS", // comma-separated allowlist (REQUIRED)
300
+ // autoConfirmSubscription: true (default) — verified SubscriptionConfirmation
301
+ // handshakes are completed and short-circuited; your action never runs for them.
302
+ },
303
+ }
304
+ ```
305
+
306
+ `topicArnsEnv` is **compile-required**: without a TopicArn allowlist the
307
+ signature check proves only "AWS signed it" — any AWS account could create
308
+ its own topic, subscribe your endpoint (auto-confirmed by the handshake),
309
+ and deliver arbitrary messages that pass verification. The compiler refuses
310
+ the declaration rather than defaulting to accept-any-topic.
311
+
312
+ The signing certificate URL and SubscribeURL are validated against the
313
+ `sns.<region>.amazonaws.com` allowlist before any fetch; a topic allowlist
314
+ that resolves empty at runtime fails closed (500). The signed `Timestamp`
315
+ is bounded to a 1-hour tolerance window — it sits *inside* the signed
316
+ canonical string, so this is a real replay bound (a captured envelope stops
317
+ replaying), while staying generous enough for SNS's own delivery retries,
318
+ which re-send the original signed envelope.
319
+
320
+ **Fail-closed runtime posture for every scheme:** an unset secret env is a
321
+ 500 rejection — never a verify-skip; any signature failure is a 401 Problem
322
+ before the body is ever parsed.
@@ -302,3 +302,36 @@ dead letter queue) is identical across providers.
302
302
 
303
303
  - [Inbound Webhooks](/stack/webhooks/inbound) — Receive webhooks from external services
304
304
  - [Queues](/stack/queues) — Background processing infrastructure
305
+
306
+ ## Standard Webhooks signing
307
+
308
+ Outbound deliveries are signed in the [Standard Webhooks](https://www.standardwebhooks.com)
309
+ format:
310
+
311
+ | Header | Value |
312
+ |---|---|
313
+ | `webhook-id` | the delivery id (unique per delivery) |
314
+ | `webhook-timestamp` | unix seconds |
315
+ | `webhook-signature` | `v1,<base64 HMAC-SHA256 over id.timestamp.body>` |
316
+
317
+ On **contract v1** these are sent **in addition to** the legacy
318
+ `X-Webhook-Signature` / `X-Webhook-Event` / `X-Webhook-Delivery` set, so
319
+ existing receivers keep working during the migration window. On
320
+ **contract v2** only the Standard Webhooks headers are sent — the legacy set
321
+ (and its Stripe-format signature) is dropped.
322
+
323
+ Receiver verification (any Standard Webhooks library works):
324
+
325
+ ```ts
326
+ import { Webhook } from "standardwebhooks";
327
+
328
+ const wh = new Webhook(endpointSecret); // whsec_…
329
+ const payload = wh.verify(rawBody, {
330
+ "webhook-id": req.headers["webhook-id"],
331
+ "webhook-timestamp": req.headers["webhook-timestamp"],
332
+ "webhook-signature": req.headers["webhook-signature"],
333
+ });
334
+ ```
335
+
336
+ The timestamp is inside the MAC, so the library's tolerance window is a real
337
+ replay bound.