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