@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.
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 +60 -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 +60 -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
@@ -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.