@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.
- 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 +66 -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 +66 -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
|
@@ -13,15 +13,32 @@ The generated API returns structured error responses with consistent fields acro
|
|
|
13
13
|
| `401` | Unauthorized | Missing or expired authentication |
|
|
14
14
|
| `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
|
|
15
15
|
| `404` | Not Found | Record doesn't exist (or firewall blocked with `errorMode: 'hide'`) |
|
|
16
|
+
| `409` | Conflict | Unique constraint hit, or a duplicate [`Idempotency-Key`](/stack/api-contract#idempotency-key) still in flight |
|
|
17
|
+
| `412` | Precondition Failed | [Changeset](/compiler/definitions/changesets) `If-Match` revision mismatch |
|
|
18
|
+
| `422` | Unprocessable | `Idempotency-Key` reused with a different request or principal |
|
|
19
|
+
| `428` | Precondition Required | `If-Match` sent where no revision exists (root without `updatedAt`, or the POST changeset variant) |
|
|
16
20
|
| `429` | Too Many Requests | Rate limit exceeded |
|
|
21
|
+
| `500` | Internal Error | Uncaught throw — generic body, full error server-side |
|
|
17
22
|
|
|
18
|
-
## Error Response Format
|
|
23
|
+
## Error Response Format — RFC 9457 Problem Details
|
|
19
24
|
|
|
20
|
-
|
|
25
|
+
Every top-level error response is an
|
|
26
|
+
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details document,
|
|
27
|
+
served as `application/problem+json` (see
|
|
28
|
+
[API Contract](/stack/api-contract)).
|
|
29
|
+
Quickback's contextual fields (`code`, `layer`, `details`, `hint`, `request`)
|
|
30
|
+
survive as 9457 **extension members**, so clients that switch on `code` keep
|
|
31
|
+
working. Every structured error also carries a `request` block with the HTTP
|
|
32
|
+
method, URL, request ID, and a redacted+truncated copy of the request body —
|
|
33
|
+
enough to triage or hand the response to an LLM agent without grepping logs:
|
|
21
34
|
|
|
22
35
|
```json
|
|
23
36
|
{
|
|
24
|
-
"
|
|
37
|
+
"type": "https://quickback.dev/problems/access-role-required",
|
|
38
|
+
"title": "Access role required",
|
|
39
|
+
"status": 403,
|
|
40
|
+
"detail": "Insufficient permissions",
|
|
41
|
+
"instance": "/api/v1/candidates/cnd_01H.../advance",
|
|
25
42
|
"layer": "access",
|
|
26
43
|
"code": "ACCESS_ROLE_REQUIRED",
|
|
27
44
|
"details": {
|
|
@@ -40,12 +57,21 @@ All errors use a flat structure with contextual fields. Every structured error r
|
|
|
40
57
|
|
|
41
58
|
| Field | Type | Description |
|
|
42
59
|
|-------|------|-------------|
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
60
|
+
| `type` | string | Problem type URI — `https://quickback.dev/problems/<code-in-kebab-case>` |
|
|
61
|
+
| `title` | string | Human-stable summary derived from the code |
|
|
62
|
+
| `status` | number | The HTTP status, repeated in the body |
|
|
63
|
+
| `detail` | string | Human-readable error message (optional) |
|
|
64
|
+
| `instance` | string | Request path (optional) |
|
|
65
|
+
| `layer` | string | Extension — security layer that rejected the request |
|
|
66
|
+
| `code` | string | Extension — machine-readable error code (the full enum ships in `openapi.json` as `Problem.code`) |
|
|
67
|
+
| `details` | object | Extension — layer-specific context (optional) |
|
|
68
|
+
| `pointer` | string | Extension — first offending field for validation failures, e.g. `/stage` (optional) |
|
|
69
|
+
| `hint` | string | Extension — actionable guidance for resolution (optional) |
|
|
70
|
+
| `request` | object | Extension — method, URL, redacted body, and request ID. Auto-attached by the runtime so the error body is self-contained — bodies are capped at 4 KB and well-known sensitive keys (`password`, `token`, `secret`, `apiKey`, `otp`, `code`, `authorization`, …) are replaced with `"[REDACTED]"` |
|
|
71
|
+
|
|
72
|
+
The per-layer examples below are abbreviated to `detail` plus each layer's
|
|
73
|
+
extension members — every real response also carries `type`, `title`,
|
|
74
|
+
`status`, and (where derivable) `instance`.
|
|
49
75
|
|
|
50
76
|
## Errors by Security Layer
|
|
51
77
|
|
|
@@ -55,7 +81,7 @@ Missing or invalid authentication tokens.
|
|
|
55
81
|
|
|
56
82
|
```json
|
|
57
83
|
{
|
|
58
|
-
"
|
|
84
|
+
"detail": "Authentication required",
|
|
59
85
|
"layer": "authentication",
|
|
60
86
|
"code": "AUTH_MISSING",
|
|
61
87
|
"hint": "Include Authorization header with Bearer token"
|
|
@@ -78,7 +104,7 @@ Records outside the user's firewall scope return **403 Forbidden** by default wi
|
|
|
78
104
|
|
|
79
105
|
```json
|
|
80
106
|
{
|
|
81
|
-
"
|
|
107
|
+
"detail": "Record not found or not accessible",
|
|
82
108
|
"layer": "firewall",
|
|
83
109
|
"code": "FIREWALL_NOT_FOUND",
|
|
84
110
|
"hint": "Check the record ID and your organization membership"
|
|
@@ -104,7 +130,7 @@ Access violations return **403 Forbidden** when the user's role doesn't match th
|
|
|
104
130
|
|
|
105
131
|
```json
|
|
106
132
|
{
|
|
107
|
-
"
|
|
133
|
+
"detail": "Insufficient permissions",
|
|
108
134
|
"layer": "access",
|
|
109
135
|
"code": "ACCESS_ROLE_REQUIRED",
|
|
110
136
|
"details": {
|
|
@@ -130,12 +156,13 @@ Guard violations return **400 Bad Request** when the request body contains field
|
|
|
130
156
|
|
|
131
157
|
```json
|
|
132
158
|
{
|
|
133
|
-
"
|
|
159
|
+
"detail": "Field cannot be set during creation",
|
|
134
160
|
"layer": "guards",
|
|
135
161
|
"code": "GUARD_FIELD_NOT_CREATEABLE",
|
|
136
162
|
"details": {
|
|
137
163
|
"fields": ["stage"]
|
|
138
164
|
},
|
|
165
|
+
"pointer": "/stage",
|
|
139
166
|
"hint": "These fields are set automatically or must be omitted"
|
|
140
167
|
}
|
|
141
168
|
```
|
|
@@ -160,7 +187,7 @@ Surfaced when a SQL write fails *post-validation* — most often a `NOT NULL` or
|
|
|
160
187
|
|
|
161
188
|
```json
|
|
162
189
|
{
|
|
163
|
-
"
|
|
190
|
+
"detail": "Duplicate value",
|
|
164
191
|
"layer": "database",
|
|
165
192
|
"code": "DB_UNIQUE_VIOLATION",
|
|
166
193
|
"details": { "column": "email" },
|
|
@@ -188,6 +215,11 @@ Batch operations can return:
|
|
|
188
215
|
|
|
189
216
|
### Partial Success (207)
|
|
190
217
|
|
|
218
|
+
A 207 body is a **success envelope** (plain `application/json`, not
|
|
219
|
+
`application/problem+json`) — the per-record `error` objects embedded in it
|
|
220
|
+
keep the internal flat shape (`error` message field, `layer`, `code`,
|
|
221
|
+
`details`, `hint`):
|
|
222
|
+
|
|
191
223
|
```json
|
|
192
224
|
{
|
|
193
225
|
"success": [{ "id": "app_1", "candidateId": "cand_101", "stage": "applied" }],
|
|
@@ -212,7 +244,7 @@ Batch operations can return:
|
|
|
212
244
|
|
|
213
245
|
```json
|
|
214
246
|
{
|
|
215
|
-
"
|
|
247
|
+
"detail": "Batch operation failed in atomic mode",
|
|
216
248
|
"layer": "validation",
|
|
217
249
|
"code": "BATCH_ATOMIC_FAILED",
|
|
218
250
|
"details": {
|
|
@@ -243,7 +275,7 @@ cause, or stack frames. The raw error is always logged server-side.
|
|
|
243
275
|
|
|
244
276
|
```json
|
|
245
277
|
{
|
|
246
|
-
"
|
|
278
|
+
"detail": "Action execution failed",
|
|
247
279
|
"layer": "action",
|
|
248
280
|
"code": "ACTION_EXECUTION_FAILED",
|
|
249
281
|
"details": {
|
|
@@ -269,7 +301,7 @@ the response → log correlation is one grep.
|
|
|
269
301
|
|
|
270
302
|
```json
|
|
271
303
|
{
|
|
272
|
-
"
|
|
304
|
+
"detail": "Internal error",
|
|
273
305
|
"layer": "database",
|
|
274
306
|
"code": "INTERNAL_ERROR",
|
|
275
307
|
"details": { "operation": "request handling" },
|
|
@@ -195,3 +195,69 @@ This request:
|
|
|
195
195
|
| `search` | LIST, VIEW | Search text across all text columns |
|
|
196
196
|
| `field=value` | LIST, VIEW | Filter by exact match |
|
|
197
197
|
| `field.op=value` | LIST, VIEW | Filter with operator (gt, gte, lt, lte, ne, like, in) |
|
|
198
|
+
| `starting_after` | LIST, VIEW | Opaque keyset cursor — rows strictly after the boundary |
|
|
199
|
+
| `ending_before` | LIST, VIEW | Opaque keyset cursor — rows strictly before the boundary |
|
|
200
|
+
| `include` | LIST, VIEW, GET | FK-graph embedding (contract v2, allowlisted — see below) |
|
|
201
|
+
| `fields[<fk>]` | LIST, VIEW, GET | Sparse fields for an embedded include target (contract v2) |
|
|
202
|
+
|
|
203
|
+
## Include & Sparse Fields (contract v2)
|
|
204
|
+
|
|
205
|
+
On the v2 contract a resource can allowlist FK columns for **FK-graph
|
|
206
|
+
embedding**, collapsing client-side N+1 fetches:
|
|
207
|
+
|
|
208
|
+
```ts title="quickback/features/orders/order-items.ts"
|
|
209
|
+
export default feature("orderItems", {
|
|
210
|
+
columns: {
|
|
211
|
+
id: q.id(),
|
|
212
|
+
orderId: q.text().required().references(() => orders.id),
|
|
213
|
+
organizationId: q.scope("organization"),
|
|
214
|
+
},
|
|
215
|
+
read: {
|
|
216
|
+
access: { roles: ["member", "admin"] },
|
|
217
|
+
include: ["orderId"], // FK columns eligible for ?include=
|
|
218
|
+
},
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
GET /api/v2/order-items?include=orderId&fields[orderId]=id,total
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
```json
|
|
227
|
+
{
|
|
228
|
+
"data": [ { "id": "oi_1", "orderId": "ord_9" } ],
|
|
229
|
+
"included": { "orderId": { "ord_9": { "id": "ord_9", "total": 129 } } }
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Embedded rows land in a **top-level `included` map** keyed by FK column, then
|
|
234
|
+
by target primary key — row objects are never mutated.
|
|
235
|
+
|
|
236
|
+
**Security semantics (all enforced, fail-closed):**
|
|
237
|
+
|
|
238
|
+
- An embedded read **is a read of the target resource**: the target's own
|
|
239
|
+
`read.access` is checked before any fetch (403 on failure, never silent
|
|
240
|
+
omission), the child query runs under the target's tenant firewall on the
|
|
241
|
+
caller's own database handle, and embedded rows pass through the target's
|
|
242
|
+
masking before attachment.
|
|
243
|
+
- Targets whose `read.access` is **record-aware** (function access, `record:`
|
|
244
|
+
conditions, `relationship` or `fga` arms) are refused **at compile time** —
|
|
245
|
+
embedding them would skip their post-fetch record checks.
|
|
246
|
+
- A tenant-scoped target with no resolvable firewall clause is a compile
|
|
247
|
+
error; a global reference table must opt out explicitly with
|
|
248
|
+
`firewall: { exception: true }`. Even then, the child fetch still calls
|
|
249
|
+
the target's own firewall helper — for a soft-deleting reference table
|
|
250
|
+
that helper is the soft-delete predicate, so an embed never serves rows
|
|
251
|
+
the target's own routes refuse.
|
|
252
|
+
- `?include=` on a resource (or view) without an allowlist is a **400**.
|
|
253
|
+
Explicit views declare their own `include: [...]` — nothing is expandable
|
|
254
|
+
undeclared. Depth is exactly 1. A view that declares `include` must keep
|
|
255
|
+
each listed FK column in its `fields` projection (compile error
|
|
256
|
+
otherwise — the embedded lookup pivots on that column).
|
|
257
|
+
|
|
258
|
+
**Strict fields on v2:** unknown names in bare `?fields=` and in
|
|
259
|
+
`fields[<fk>]=` are rejected with a 400 Problem. (Pinned v1 keeps its
|
|
260
|
+
historical silent-drop for bare `?fields=`.) A `?fields=` projection that
|
|
261
|
+
drops the FK column of a requested `?include=` is also a **400** —
|
|
262
|
+
`include=orderId requires "orderId" in ?fields=` — never a silently-empty
|
|
263
|
+
`included` slot.
|
|
@@ -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.
|