@quickback-dev/cli 0.61.0 → 0.63.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 +11 -0
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +57 -13
- package/dist/commands/compile.js.map +1 -1
- package/dist/index.js +4 -2
- package/dist/index.js.map +1 -1
- package/dist/lib/compiler-stubs.d.ts +4 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +4 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/file-loader.d.ts +11 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +35 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/skill/SKILL.md +3 -0
- package/dist/skill/docs/api/crud.md +17 -0
- package/dist/skill/docs/changelog/index.md +112 -0
- package/dist/skill/docs/configure/auth.md +2 -1
- package/dist/skill/docs/configure/index.md +1 -1
- package/dist/skill/docs/define/actions/defining.md +55 -6
- package/dist/skill/docs/define/actions/index.md +73 -0
- package/dist/skill/docs/define/feature.md +2 -1
- package/dist/skill/docs/define/scopes.md +9 -4
- package/dist/skill/docs/platform/api-contract/index.md +19 -1
- package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -2
- package/dist/skill/docs/platform/email/index.md +112 -0
- package/dist/skill/docs/platform/index.md +1 -0
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +3 -1
- package/dist/skill/docs/tooling/output.md +21 -0
- package/package.json +2 -10
- package/src/skill/SKILL.md +3 -0
- package/src/skill/docs/api/crud.md +17 -0
- package/src/skill/docs/changelog/index.md +112 -0
- package/src/skill/docs/configure/auth.md +2 -1
- package/src/skill/docs/configure/index.md +1 -1
- package/src/skill/docs/define/actions/defining.md +55 -6
- package/src/skill/docs/define/actions/index.md +73 -0
- package/src/skill/docs/define/feature.md +2 -1
- package/src/skill/docs/define/scopes.md +9 -4
- package/src/skill/docs/platform/api-contract/index.md +19 -1
- package/src/skill/docs/platform/auth/jwt-optimization.md +2 -2
- package/src/skill/docs/platform/email/index.md +112 -0
- package/src/skill/docs/platform/index.md +1 -0
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +3 -1
- package/src/skill/docs/tooling/output.md +21 -0
|
@@ -111,6 +111,24 @@ export default defineAction({
|
|
|
111
111
|
});
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
+
## The default becomes v2 in v0.64.0
|
|
115
|
+
|
|
116
|
+
`contract.version` resolves to `'v1'` when unset. That default becomes `'v2'`
|
|
117
|
+
in Quickback **v0.64.0**. Every project without an explicit `contract.version`
|
|
118
|
+
moves the entire matrix below on its next compile after that release.
|
|
119
|
+
|
|
120
|
+
Pin the current wire:
|
|
121
|
+
|
|
122
|
+
```typescript
|
|
123
|
+
{/* doc-compile: skip — config fragment */}
|
|
124
|
+
contract: { version: "v1" }
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**Pinning your CLI version does not pin the contract.** The default lives in the
|
|
128
|
+
compiler, which is a hosted service — an older CLI inherits the flip too. The
|
|
129
|
+
config key is the only pin. v0.63.0 warns on every compile that leaves
|
|
130
|
+
`contract.version` unset.
|
|
131
|
+
|
|
114
132
|
## Contract version matrix
|
|
115
133
|
|
|
116
134
|
Flipping `contract.version` moves the **entire** contract at once — plan the
|
|
@@ -128,7 +146,7 @@ client migration as one move:
|
|
|
128
146
|
| Aggregate changesets (`application/vnd.quickback.changeset+json` on PATCH/POST, [`owns`](/define/changesets)) | not available | available where `owns` is declared |
|
|
129
147
|
| Bare `?fields=` unknown names | silently dropped | **400** |
|
|
130
148
|
| `fields[<fk>]=` unknown names | n/a | **400** |
|
|
131
|
-
| Action input schemas |
|
|
149
|
+
| Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
|
|
132
150
|
|
|
133
151
|
Sequencing a migration: ship clients that speak the v2 paths, CloudEvents
|
|
134
152
|
frames, and session-first auth (or declare `auth.jwt`); confirm webhook
|
|
@@ -31,7 +31,7 @@ The JWT encodes everything needed for auth middleware:
|
|
|
31
31
|
| `iatMs` | Issued-at in epoch **milliseconds** — Quickback ordering metadata, not a standard claim. Same clock sample as `iat`, set by the signer only. Lets [revocation](#revocation--revocationcheck-kv) order a token against a marker written in the same second |
|
|
32
32
|
| `exp` | Expiry — **180 seconds** (3 minutes) after `iat` by default; set via [`auth.jwt.expiresIn`](/configure/auth) |
|
|
33
33
|
|
|
34
|
-
Scope-bearing tokens also carry `sct` (proof timestamp, unix seconds) and its millisecond companion `sctMs` —
|
|
34
|
+
Scope-bearing tokens also carry `sct` (proof timestamp, unix seconds) and its millisecond companion `sctMs`, plus a per-kind `sctMs` stamp (`m<ms>`) inside each `scope.<kind>` entry — a mint proves one kind and carries the others forward with the proof time they already had. See [Scopes](/define/scopes). Read `iat` / `sct` from external tooling; the millisecond values exist only so revocation can break ties inside a second.
|
|
35
35
|
|
|
36
36
|
### Signing
|
|
37
37
|
|
|
@@ -116,7 +116,7 @@ auth: {
|
|
|
116
116
|
},
|
|
117
117
|
```
|
|
118
118
|
|
|
119
|
-
The fast-path then consults per-principal revocation timestamps in your project's existing `KV` binding (keys prefixed `qbrev:`, self-expiring) *before* trusting a token. A token is rejected when its mint timestamp (`iat`/`iatMs`, or
|
|
119
|
+
The fast-path then consults per-principal revocation timestamps in your project's existing `KV` binding (keys prefixed `qbrev:`, self-expiring) *before* trusting a token. A token is rejected when its mint timestamp (`iat`/`iatMs`, or the proof time of the scope kind being checked) is **at or before** the stored timestamp. Cost: 2+ edge-cached KV reads per bearer verify.
|
|
120
120
|
|
|
121
121
|
There is no same-second gap: markers are epoch milliseconds (written `m<ms>`, v0.61.0+), tokens carry millisecond companions, and the comparison denies a tie — so a token minted a few milliseconds *before* the revocation is rejected, while one legitimately re-minted *after* it in that same second is still accepted. Pre-v0.61.0 workers don't understand that marker format and read it as "not revoked" — don't roll back across the upgrade or share one KV namespace between versions; see [`revocationCheck`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy).
|
|
122
122
|
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Email (Inbound)
|
|
2
|
+
|
|
3
|
+
`defineEmail` is the inbound-mail mirror of [`defineSchedule`](/platform/schedules). Drop a file in `services/email/` and the compiler emits a shared `deliverInboundEmail()` dispatcher. **Execute is provider-agnostic** — you parse RFC 822 bytes and write the store. Ingress is an adapter:
|
|
4
|
+
|
|
5
|
+
| Provider | Ingress | How it reaches `execute` |
|
|
6
|
+
|----------|---------|--------------------------|
|
|
7
|
+
| Cloudflare (`email.provider: 'cloudflare'`, default) | Email Routing → Worker `email()` | Compiler emits `email` on the Worker export. Buffers `message.raw` once, then calls `deliverInboundEmail`. |
|
|
8
|
+
| Amazon SES (`email.provider: 'aws-ses'`) | Receipt rule → S3 + SNS | Build the same `InboundEmailMessage` (`provider: 'ses'`, `raw` = the `.eml` bytes) and call `deliverInboundEmail(message, env)`. |
|
|
9
|
+
|
|
10
|
+
Outbound sending is a separate surface (`email.provider` already switches Cloudflare `send_email` vs AWS SES) — see [Email Configuration](/configure#email-configuration).
|
|
11
|
+
|
|
12
|
+
## Define a handler
|
|
13
|
+
|
|
14
|
+
```typescript
|
|
15
|
+
// services/email/inbound.ts
|
|
16
|
+
import { defineEmail } from "quickback";
|
|
17
|
+
import { ingestMessage } from "../../features/mail/lib/ingest";
|
|
18
|
+
|
|
19
|
+
export default defineEmail({
|
|
20
|
+
name: "inbound", // identifier + audit actor (system:email-<name>)
|
|
21
|
+
to: "paul@kardoe.com", // optional; omit to match every recipient
|
|
22
|
+
description: "Ingest inbound mail",
|
|
23
|
+
execute: async ({ message, db, env, services }) => {
|
|
24
|
+
// message.raw is already-buffered RFC 822 bytes (not a stream).
|
|
25
|
+
await ingestMessage(db, env, services, message.raw);
|
|
26
|
+
},
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
One file per handler under `services/email/*.ts`. Files prefixed with `_` are ignored. `name` must be a valid camelCase identifier (it's used as a generated symbol and the audit actor). The same file is what runs on Cloudflare and on SES — do not import `ForwardableEmailMessage` or SES receipt types in `execute`.
|
|
31
|
+
|
|
32
|
+
## Envelope matching
|
|
33
|
+
|
|
34
|
+
| `to` | Behavior |
|
|
35
|
+
|------|----------|
|
|
36
|
+
| omitted | Handler runs for every inbound message |
|
|
37
|
+
| `"user@example.com"` | Exact, case-insensitive match against `message.to` |
|
|
38
|
+
|
|
39
|
+
Multiple handlers can match the same message (a catch-all plus an address-specific handler). Failures are isolated so one throwing handler does not abort the others.
|
|
40
|
+
|
|
41
|
+
If **no** handler matches, the runner logs a warning and returns. It does **not** call Cloudflare `setReject()` — Email Routing can still fall through, and SES has already accepted the message.
|
|
42
|
+
|
|
43
|
+
## Importing feature code
|
|
44
|
+
|
|
45
|
+
Email files live at `quickback/services/email/<name>.ts`, so imports are relative to **that** location. To reach a feature table, a feature `lib/` helper, or `db/`, climb up to the `quickback/` root first (`../../`):
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
// quickback/services/email/inbound.ts
|
|
49
|
+
import { messages } from "../../features/mail/messages";
|
|
50
|
+
import { ingestMessage } from "../../features/mail/lib/ingest";
|
|
51
|
+
import { parseRfc822 } from "../../lib/rfc822";
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Two `../` — up from `services/email/` to `quickback/`, then down into `features/` (or `lib/`, `db/`). The compiler relocates the handler into the generated `src/lib/email.ts` and **rewrites these paths to resolve from there automatically** — you always write them relative to your own source file, exactly as your editor resolves them.
|
|
55
|
+
|
|
56
|
+
> A single `../features/…` is the common mistake — from `services/email/` that resolves to `services/features/…`, which doesn't exist. Use `../../features/…`.
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
## What the compiler emits
|
|
60
|
+
|
|
61
|
+
1. **`deliverInboundEmail(message, env)`** in `src/lib/email.ts` — the shared dispatcher.
|
|
62
|
+
2. **`email(cfMessage, env, ctx)`** on the Worker default export — Cloudflare adapter. Regenerated on every `quickback compile`.
|
|
63
|
+
3. **No wrangler inbound binding.** Cloudflare: configure Email Routing in the dashboard. SES: Receipt rule + S3 + SNS; call `deliverInboundEmail` with the fetched `.eml`.
|
|
64
|
+
4. The existing outbound `[[send_email]]` binding (Cloudflare) / SES plugin (aws-ses) is unchanged.
|
|
65
|
+
|
|
66
|
+
## Execute context
|
|
67
|
+
|
|
68
|
+
| Field | Type | Notes |
|
|
69
|
+
|-------|------|-------|
|
|
70
|
+
| `message` | `InboundEmailMessage` | `{ provider, from, to, headers, raw }`. `raw` is `ArrayBuffer`. |
|
|
71
|
+
| `message.provider` | `'cloudflare' \| 'ses'` | Ingress tag for logs. Parse `raw`, don't branch on this. |
|
|
72
|
+
| `db` | Drizzle instance | The same DB the queue/schedule handlers get |
|
|
73
|
+
| `env` | `CloudflareBindings` | All worker bindings |
|
|
74
|
+
| `services` | `Services` | The services layer (`createServices(env)`) |
|
|
75
|
+
| `withInternalContext` | helper | Opt into the `INTERNAL` trust zone for `roles: ['INTERNAL']`-gated rows |
|
|
76
|
+
|
|
77
|
+
Cloudflare-only methods (`setReject`, `forward`, `reply`) are **not** on `InboundEmailMessage`. SES has already accepted the mail; Cloudflare fall-through is the adapter's job (it does not reject unmatched recipients).
|
|
78
|
+
|
|
79
|
+
## Amazon SES inbound
|
|
80
|
+
|
|
81
|
+
SES cannot invoke a Worker `email()` export — receipt is S3 + SNS. After you verify the SNS signature and fetch the object:
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
import { deliverInboundEmail } from "../lib/email";
|
|
85
|
+
|
|
86
|
+
await deliverInboundEmail({
|
|
87
|
+
provider: "ses",
|
|
88
|
+
from: receipt.mail.source,
|
|
89
|
+
to: receipt.receipt.recipients[0],
|
|
90
|
+
headers: new Headers(/* from the .eml or commonHeaders */),
|
|
91
|
+
raw: await s3.getObject(bucket, key).arrayBuffer(),
|
|
92
|
+
}, env);
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`execute` does not change. MX, Receipt rules, the S3 bucket, and the SNS subscription stay in AWS — the compiler does not emit those.
|
|
96
|
+
|
|
97
|
+
## Audit & trust
|
|
98
|
+
|
|
99
|
+
Inbound email runs are **server-internal**: there's no authenticated user, no request, no org scope. A delivered message gets a plain `db` (unscoped Drizzle) plus a `withInternalContext` helper:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
execute: async ({ db, withInternalContext, message }) => {
|
|
103
|
+
// `db` here is unscoped — no firewall WHERE, no audit actor.
|
|
104
|
+
|
|
105
|
+
await withInternalContext(async ({ ctx, db, services }) => {
|
|
106
|
+
// ctx.internal = true, ctx.userId = "system:email-<name>"
|
|
107
|
+
// audited writes are attributable to e.g. system:email-inbound
|
|
108
|
+
});
|
|
109
|
+
},
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`withInternalContext` builds a context with `internal: true` and `userId: "system:email-<name>"`, so audited writes made through it are attributable to the handler and can reach `roles: ['INTERNAL']`-gated rows.
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
| [Realtime](/platform/realtime) | Durable Objects | WebSocket for live updates |
|
|
12
12
|
| [Queues](/platform/queues) | Cloudflare Queues | Background jobs, webhook delivery |
|
|
13
13
|
| [Schedules](/platform/schedules) | Cron Triggers | `defineSchedule` cron jobs, server-internal |
|
|
14
|
+
| [Email](/platform/email) | Email Workers | `defineEmail` inbound handlers, server-internal |
|
|
14
15
|
| [Vector & AI](/platform/vector) | Workers AI | Embeddings, semantic search |
|
|
15
16
|
| [Webhooks](/platform/webhooks) | Hono + Queues | Signed inbound, retried outbound |
|
|
16
17
|
| [Push](/platform/push) | Web Push | VAPID subscriptions, typed payloads |
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Endpoints
|
|
2
2
|
|
|
3
|
-
The cloud compiler API is hosted at `https://compiler.quickback.dev
|
|
3
|
+
The cloud compiler API is hosted at `https://compiler.quickback.dev`
|
|
4
|
+
(alias: `https://build.quickback.dev` — same Worker, same auth via
|
|
5
|
+
`quickback-api`, identical `/health` / `/templates` / `/compile`).
|
|
4
6
|
|
|
5
7
|
## Public (No Auth)
|
|
6
8
|
|
|
@@ -184,6 +184,27 @@ authentication behavior. Quickback preserves unrelated overrides already in
|
|
|
184
184
|
your package manifest, but the compiler-owned Lodash security pin wins if an
|
|
185
185
|
existing override conflicts.
|
|
186
186
|
|
|
187
|
+
A project that declares an in-worker Durable Object also gets `hono-party`
|
|
188
|
+
plus a second entry in the same block:
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"overrides": {
|
|
193
|
+
"hono-party": {
|
|
194
|
+
"@cloudflare/workers-types": "$@cloudflare/workers-types"
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
`hono-party` still declares a peer dependency on `@cloudflare/workers-types`
|
|
201
|
+
major 4, which cannot be satisfied alongside the major 5 the compiler pins, so
|
|
202
|
+
a plain `npm install` would fail with `ERESOLVE`. The override is scoped to
|
|
203
|
+
`hono-party` — nothing else in the tree is relaxed — and the `$` form resolves
|
|
204
|
+
to whatever your `package.json` already declares, so it tracks the pin instead
|
|
205
|
+
of drifting from it. Projects without an in-worker Durable Object do not get
|
|
206
|
+
this entry.
|
|
207
|
+
|
|
187
208
|
After recompiling, run your package manager's install command so its lockfile
|
|
188
209
|
records the patched transitive version. Use `npm audit --omit=dev` when
|
|
189
210
|
evaluating the production dependency tree; development-tool advisories are a
|
package/package.json
CHANGED
|
@@ -1,18 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.63.0",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
7
|
-
"homepage": "https://docs.quickback.dev/
|
|
8
|
-
"repository": {
|
|
9
|
-
"type": "git",
|
|
10
|
-
"url": "git+https://github.com/paulstenhouse/quickback-compiler.git",
|
|
11
|
-
"directory": "packages/cli"
|
|
12
|
-
},
|
|
13
|
-
"bugs": {
|
|
14
|
-
"url": "https://github.com/paulstenhouse/quickback-compiler/issues"
|
|
15
|
-
},
|
|
7
|
+
"homepage": "https://docs.quickback.dev/tooling/cli",
|
|
16
8
|
"keywords": [
|
|
17
9
|
"quickback",
|
|
18
10
|
"cli",
|
package/src/skill/SKILL.md
CHANGED
|
@@ -29,6 +29,8 @@ Everything you need around the compiled API for a complete Supabase alternative
|
|
|
29
29
|
| **Storage** | KV (sessions, cache) and R2 (files) | Cloudflare KV + R2 |
|
|
30
30
|
| **Realtime** | WebSocket for live updates | Durable Objects |
|
|
31
31
|
| **Queues** | Background jobs, webhook delivery | Cloudflare Queues |
|
|
32
|
+
| **Schedules** | Cron jobs via `defineSchedule` | Cron Triggers |
|
|
33
|
+
| **Email** | Inbound handlers via `defineEmail` | Email Workers |
|
|
32
34
|
| **Vector & AI** | Embeddings, semantic search | Workers AI |
|
|
33
35
|
| **Webhooks** | Signed inbound, retried outbound | Hono + Queues |
|
|
34
36
|
| **CMS** | Schema-driven admin UI | Embedded SPA |
|
|
@@ -402,6 +404,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
402
404
|
- `api-contract` — the HTTP contract layer: RFC 9457 Problem Details, keyset cursors, `Idempotency-Key`, `?include=`/sparse fields, the contract `v1`→`v2` matrix
|
|
403
405
|
- `push` — Web Push (VAPID + aes128gcm), queue fan-out, identity-tag targeting, hardened subscriptions schema
|
|
404
406
|
- `schedules` — `defineSchedule` cron jobs
|
|
407
|
+
- `email` — `defineEmail` inbound Email Worker handlers
|
|
405
408
|
|
|
406
409
|
**Bundled UIs** (`docs/ui/<topic>.md`)
|
|
407
410
|
- `admin` — schema-driven admin UI, dashboard, record layouts, table views, schema registry
|
|
@@ -55,6 +55,23 @@ For a resource named `jobs`, Quickback generates:
|
|
|
55
55
|
| `PUT` | `/jobs/:id` | Upsert a record (requires config) |
|
|
56
56
|
| `PUT` | `/jobs/batch` | Batch upsert multiple records (requires config) |
|
|
57
57
|
|
|
58
|
+
## Replace a generated verb with an action
|
|
59
|
+
|
|
60
|
+
Map `create`, `update`, or `delete` to a named action when the public URL
|
|
61
|
+
must stay and the handler has to become real code. See
|
|
62
|
+
[Replace a CRUD verb](/define/actions#replace-a-crud-verb).
|
|
63
|
+
|
|
64
|
+
{/* doc-compile: skip — one-key excerpt; the whole-file form is on the actions page. */}
|
|
65
|
+
```ts
|
|
66
|
+
create: {
|
|
67
|
+
access: { roles: ["member"] },
|
|
68
|
+
action: "send",
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`POST /api/v1/jobs` then runs `send`'s `execute`. Clients, OpenAPI, and MCP
|
|
73
|
+
keep the CRUD path and operation id. Unmapped verbs are unchanged.
|
|
74
|
+
|
|
58
75
|
## List & Get Records
|
|
59
76
|
|
|
60
77
|
`GET /{resource}` and `GET /{resource}/:id` are part of the [read pipeline](/define/read). Configuration (access, pagination, view projections) lives under `read:`. Filtering, sorting, and pagination query parameters work the same on both endpoints — see [Query Parameters](/api/query-params).
|
|
@@ -8,6 +8,118 @@ The current release series. Older entries are archived by version range:
|
|
|
8
8
|
- [v0.20 – v0.29](/changelog/v0.2x)
|
|
9
9
|
- [v0.18 and earlier](/changelog/v0.1x)
|
|
10
10
|
|
|
11
|
+
## v0.63.0 — August 14, 2026
|
|
12
|
+
|
|
13
|
+
### Action input schemas now fail the compile instead of degrading
|
|
14
|
+
|
|
15
|
+
**Affects every project with actions, on every contract version.**
|
|
16
|
+
|
|
17
|
+
The CLI harvests each action's `input` locally with `z.toJSONSchema`. When an
|
|
18
|
+
action failed to harvest, the compiler fell back to a static parser that reads
|
|
19
|
+
Zod as text — and that parser cannot emit `required` or `additionalProperties`.
|
|
20
|
+
The resulting operation kept its `properties` and looked fully typed in
|
|
21
|
+
`openapi.json` and the MCP tool list while enforcing nothing: generated clients
|
|
22
|
+
treated required fields as optional and unknown keys passed. Constructs the
|
|
23
|
+
parser could not read at all degraded further, to a bare `{}`.
|
|
24
|
+
|
|
25
|
+
None of it was visible in a diff. One project shipped ~346 unenforced request
|
|
26
|
+
schemas this way; the change read as reformatting.
|
|
27
|
+
|
|
28
|
+
A failed harvest is now a compile error naming each action, whether bundling or
|
|
29
|
+
evaluation failed, and the underlying local error. This was previously the
|
|
30
|
+
behavior of `contract.version: 'v2'` only.
|
|
31
|
+
|
|
32
|
+
`quickback compile --allow-degraded-schemas` restores degrade-and-continue for a
|
|
33
|
+
single compile. It prints every action that fell back and why.
|
|
34
|
+
|
|
35
|
+
The compiler also warns when a caller supplies no schemas at all — `rawFiles`
|
|
36
|
+
callers such as the Start app cannot harvest — naming how many actions of the
|
|
37
|
+
total lost `required`, with sampled paths.
|
|
38
|
+
|
|
39
|
+
### `contract.version` default flips to v2 in v0.64.0
|
|
40
|
+
|
|
41
|
+
An unset `contract.version` resolves to `'v1'` today. That default becomes
|
|
42
|
+
`'v2'` in **v0.64.0**, which moves `/api/v1` → `/api/v2` (plus `/auth` and
|
|
43
|
+
`/broadcast`), switches realtime frames to CloudEvents 1.0 envelopes, drops the
|
|
44
|
+
legacy `X-Webhook-*` signing headers, and disables the Quickback HMAC-JWT lane
|
|
45
|
+
unless `auth.jwt` is declared. See the
|
|
46
|
+
[contract matrix](/platform/api-contract#contract-version-matrix).
|
|
47
|
+
|
|
48
|
+
Every compile that leaves `contract.version` unset now warns. Pin
|
|
49
|
+
`contract: { version: "v1" }` to keep the current wire, or set `"v2"` to migrate
|
|
50
|
+
now.
|
|
51
|
+
|
|
52
|
+
**Pinning your CLI version does not pin the contract.** The default lives in the
|
|
53
|
+
compiler, which is a hosted service, so an older CLI inherits the flip too. The
|
|
54
|
+
config key is the only pin.
|
|
55
|
+
|
|
56
|
+
### MCP tool grouping no longer assumes a `v1` path segment
|
|
57
|
+
|
|
58
|
+
Internal. Group derivation matched the literal segment `v1`, so a contract-v2
|
|
59
|
+
path would have fallen through and grouped under `api`. Operation tags take
|
|
60
|
+
precedence and every generated operation carries one, so no shipped tool list
|
|
61
|
+
was affected — the fallback is now correct for any `/api/v<n>/` prefix ahead of
|
|
62
|
+
the v0.64.0 default flip.
|
|
63
|
+
|
|
64
|
+
## v0.62.0 — August 13, 2026
|
|
65
|
+
|
|
66
|
+
### Security: `record:` access arms on `GET /:id` were never evaluated
|
|
67
|
+
|
|
68
|
+
**Affects any resource whose `read.access` contains a `record:` arm.**
|
|
69
|
+
|
|
70
|
+
A code rewrite corrupted `"$ctx.userId"` into `"$effectiveCtx.userId"` inside the
|
|
71
|
+
serialized access tree, and only the `$ctx.` prefix is recognised at runtime. The
|
|
72
|
+
arm therefore compared a column against the literal string and was permanently
|
|
73
|
+
false: a caller the config named was denied with 403 on the single-record read,
|
|
74
|
+
while the same tree admitted them everywhere else.
|
|
75
|
+
|
|
76
|
+
Those arms now evaluate. **Callers your config grants access to will start
|
|
77
|
+
receiving 200 where they previously received 403.** That is the documented
|
|
78
|
+
behavior being restored, not a widening — no caller is admitted whom the tree
|
|
79
|
+
does not name. Durable Object room gates already behaved correctly, so this also
|
|
80
|
+
removes a divergence where a room admitted a caller that `GET /:id` refused.
|
|
81
|
+
|
|
82
|
+
### Security: revocation is per scope kind, not per token
|
|
83
|
+
|
|
84
|
+
**Affects projects using `authz.scopes`.**
|
|
85
|
+
|
|
86
|
+
A token carried one proof timestamp for a claim map whose kinds were proven at
|
|
87
|
+
different moments, so re-proving one kind restamped the others. A revoked kind
|
|
88
|
+
survived indefinitely as long as the caller kept re-proving any sibling.
|
|
89
|
+
|
|
90
|
+
Each entry now carries its own proof time, and both readers use it: the
|
|
91
|
+
revocation check, and the carry-forward cap. **The cap matters more** — it
|
|
92
|
+
applies on the default configuration, where `revocationCheck` is unset and no
|
|
93
|
+
KV marker is ever read, so it was the only bound on a carried claim.
|
|
94
|
+
|
|
95
|
+
Tokens minted before this release have no per-entry stamp and fall back to the
|
|
96
|
+
token-level proof time, conservatively. `authz.scopes[].roles[].subKeys` may no
|
|
97
|
+
longer declare `id`, `roles`, `subjectId`, or `sctMs` — those are server-minted,
|
|
98
|
+
and a row value overwriting one would forge a proof time. Compile fails naming
|
|
99
|
+
the path.
|
|
100
|
+
|
|
101
|
+
### Generated projects with in-worker Durable Objects can install again
|
|
102
|
+
|
|
103
|
+
`npm install` failed with `ERESOLVE` immediately after a successful compile:
|
|
104
|
+
`hono-party` requires `@cloudflare/workers-types@^4`, and Quickback pins `^5`.
|
|
105
|
+
Unsatisfiable at any version — no `hono-party` release accepts 5.x.
|
|
106
|
+
|
|
107
|
+
Generated `package.json` now carries a scoped override so the peer resolves to
|
|
108
|
+
the project's own pin. Nothing outside `hono-party` is relaxed. Only projects
|
|
109
|
+
declaring an in-worker Durable Object receive it.
|
|
110
|
+
|
|
111
|
+
### Fixed: two configurations that emitted uncompilable projects
|
|
112
|
+
|
|
113
|
+
- `plugins: { apiKey: false }` emitted a `problemJson(...)` call without its
|
|
114
|
+
import, so the generated project failed `tsc`.
|
|
115
|
+
- `organization: { allowUserToCreateOrganization: … }` in object form emitted the
|
|
116
|
+
key twice in one object literal (`TS1117`). `organizationHooks` had the same
|
|
117
|
+
collision and is now stripped from the merged options — the compiler owns it.
|
|
118
|
+
|
|
119
|
+
### `defineEmail` — inbound mail, provider-agnostic execute
|
|
120
|
+
|
|
121
|
+
Declare an inbound handler in `services/email/*.ts`. The compiler emits a shared `deliverInboundEmail()` dispatcher plus a Cloudflare Worker `email()` adapter. **Execute sees a portable `InboundEmailMessage`** (`from`, `to`, `headers`, `raw: ArrayBuffer`) — the same body runs for Cloudflare Email Routing and Amazon SES (Receipt → S3 → SNS calling `deliverInboundEmail`). Optional `to` matches the envelope recipient. Unmatched messages log a warning and are **not** rejected. Audit actor is `system:email-<name>`. See [Email](/platform/email).
|
|
122
|
+
|
|
11
123
|
## v0.61.0 — August 12, 2026
|
|
12
124
|
|
|
13
125
|
### Security: JWT revocation now fails closed when KV is unreachable
|
|
@@ -109,7 +109,7 @@ Default `'none'`.
|
|
|
109
109
|
|
|
110
110
|
`'kv'` (v0.45+, **Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
|
|
111
111
|
|
|
112
|
-
A token is rejected when its mint timestamp (`iat`/`iatMs`, or
|
|
112
|
+
A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's proof time) is **at or before** the stored timestamp for any principal key it rides on:
|
|
113
113
|
|
|
114
114
|
| Key | Revokes | Written automatically on |
|
|
115
115
|
|---|---|---|
|
|
@@ -122,6 +122,7 @@ A token is rejected when its mint timestamp (`iat`/`iatMs`, or `sct`/`sctMs` for
|
|
|
122
122
|
Semantics worth knowing:
|
|
123
123
|
|
|
124
124
|
- **Revoke-on-touch for scopes:** any update or delete of a conferring row stamps the revocation, without evaluating whether the change actually ended the relationship. A false positive just forces a cheap re-prove (`/scope/v1/enter` or a minting namespace route).
|
|
125
|
+
- **Scope proof time is per kind:** a token can carry several scope kinds proven at different instants, so each entry carries its own proof stamp (`sctMs`, `m<ms>`) and is compared against its own marker. Proving one kind never restamps the others — re-entering `event` cannot bring a revoked `location` claim back to life. Entries minted before the release that added the stamp carry none, and fall back to the token-level `sct`/`sctMs` until they expire (bounded by the carry-forward cap plus one TTL).
|
|
125
126
|
- **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format version, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, so a token minted a few milliseconds before the revocation is rejected — while one legitimately re-minted *after* it in that same second is still accepted. Tokens and markers written by v0.60.4 or earlier are handled **conservatively**: with no sub-second information on one side, the whole marker second is revoked. That over-revocation is bounded — the last old token expires within its TTL, and the last old marker within the entry lifetime. Like any rejected token it costs the caller a `401`, not a silent recovery: the bearer falls through unauthenticated (its cookie having been stripped, per the next bullet), and the client re-authenticates for a fresh token.
|
|
126
127
|
- **Do not straddle the v0.61.0 upgrade.** A worker from **before** v0.61.0 reads `m<ms>` markers as `NaN` and treats them as *no revocation at all* — not as a corrupt entry. So rolling back across this release, or pointing two differently-versioned deploy targets at one shared KV namespace, means every revocation written by the new version is **silently unenforced** by the old one until the entry expires (`ENTRY_TTL_SECONDS`, ~19 minutes at default settings). Upgrade all targets sharing a namespace together; if you must roll back, treat outstanding bearer tokens as unrevoked for that window — lower `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
|
|
127
128
|
- **Fails closed:** a missing binding, a failed read, or a corrupt entry means the token's revocation state is *unknown* — and an unknown bearer is not authenticated. The caller gets `503 AUTH_REVOCATION_UNAVAILABLE` (RFC 9457, retryable). Recovery is a **separate cookie-only request**: a request carrying `Authorization` has its cookie stripped before session auth, so within that one request there is nothing left to fall back to. Reads are never silently skipped, because the outage that hides a revocation is exactly the moment this check exists for.
|
|
@@ -697,7 +697,7 @@ dev: {
|
|
|
697
697
|
|
|
698
698
|
## Email Configuration
|
|
699
699
|
|
|
700
|
-
Configure email delivery for authentication emails (verification, password reset, invitations).
|
|
700
|
+
Configure email delivery for authentication emails (verification, password reset, invitations). Inbound mail (Email Routing or SES → a Worker handler) is a separate surface — see [Email (Inbound)](/platform/email) (`defineEmail`). This section is outbound only.
|
|
701
701
|
|
|
702
702
|
> **Cloudflare Email Sending is now in public beta** and is Quickback's default transport for Cloudflare deploys. The Workers `send_email` binding is zero-config — no API keys, no third-party accounts. AWS SES remains supported as an explicit opt-in (`email.provider: 'aws-ses'`) for non-Cloudflare runtimes or existing SES setups.
|
|
703
703
|
|
|
@@ -81,11 +81,24 @@ Before sending a compile request, the CLI loads each action in an isolated
|
|
|
81
81
|
local bundle and converts `action.input` plus an optional `action.output` with
|
|
82
82
|
Zod 4's `z.toJSONSchema`. It does not call `execute`; the hosted compiler never
|
|
83
83
|
evaluates project code. The output contract feeds OpenAPI and
|
|
84
|
-
`Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
84
|
+
`Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
|
|
85
|
+
|
|
86
|
+
**Every action input must produce a schema, on every contract version.** Since
|
|
87
|
+
v0.63.0 a failed harvest fails the compile, naming the exact action, whether
|
|
88
|
+
bundling or evaluation failed, and the underlying local error. Output remains
|
|
89
|
+
optional.
|
|
90
|
+
|
|
91
|
+
**Why it fails instead of degrading.** The compiler's static fallback parser
|
|
92
|
+
reads your Zod as text and can only produce `type` and `properties`. It never
|
|
93
|
+
emits `required` or `additionalProperties` — so a fallback request schema looks
|
|
94
|
+
fully typed in `openapi.json` and the MCP tool list while enforcing nothing:
|
|
95
|
+
generated clients treat every required field as optional, and unknown keys pass.
|
|
96
|
+
Constructs it cannot parse at all degrade further, to a bare `{}` with no
|
|
97
|
+
`properties`. Neither is visible in a diff.
|
|
98
|
+
|
|
99
|
+
`--allow-degraded-schemas` restores the old degrade-and-continue behavior for a
|
|
100
|
+
single compile. It still prints every action that fell back and why, and the
|
|
101
|
+
compiler warns again with the count and sampled paths.
|
|
89
102
|
|
|
90
103
|
Bare imports are resolved from the generated runtime's configured
|
|
91
104
|
`build.outputDir/node_modules` first. If definitions live in `quickback/` and
|
|
@@ -94,7 +107,43 @@ as usual; no project-root dependency symlink is required. Shared schema or DTO
|
|
|
94
107
|
modules may also declare top-level Drizzle selection objects. Quickback
|
|
95
108
|
replaces authored table exports with inert proxies during this schema-only
|
|
96
109
|
evaluation, so reading `records.id` to build a projection does not execute
|
|
97
|
-
application or database logic.
|
|
110
|
+
application or database logic. A schema **derived** from a table enumerates
|
|
111
|
+
nothing under that substitution — see
|
|
112
|
+
[Declaring action outputs](#declaring-action-outputs).
|
|
113
|
+
|
|
114
|
+
### Declaring action outputs
|
|
115
|
+
|
|
116
|
+
`output:` is optional, and omitting it degrades quietly: the operation's
|
|
117
|
+
OpenAPI success response becomes `{}` and
|
|
118
|
+
`Api.<feature>.actions.<action>.Output` becomes `unknown`. The compile still
|
|
119
|
+
succeeds — it warns, naming how many actions are affected.
|
|
120
|
+
|
|
121
|
+
**Declare the output shape as a literal Zod schema.** Do not derive it from a
|
|
122
|
+
table:
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
// Silently produces an EMPTY contract — do not do this.
|
|
126
|
+
output: z.object({ tickets: z.array(createSelectSchema(ticketTypes)) })
|
|
127
|
+
|
|
128
|
+
// Documents the response.
|
|
129
|
+
output: z.object({
|
|
130
|
+
tickets: z.array(z.object({ id: z.string(), name: z.string(), priceCents: z.number() })),
|
|
131
|
+
})
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The harvest substitutes inert proxies for table modules, so anything that
|
|
135
|
+
derives a schema by enumerating a table's columns — `createSelectSchema` and
|
|
136
|
+
every equivalent — enumerates **zero** columns. It does not throw. It returns a
|
|
137
|
+
valid, empty object schema, which is then published as the documented success
|
|
138
|
+
response. The compiler warns when a declared `output:` resolves to an empty
|
|
139
|
+
object, but the warning is the only signal; the compile passes and the spec
|
|
140
|
+
looks fine.
|
|
141
|
+
|
|
142
|
+
The proxy substitution has one exception, and it is not a supported escape
|
|
143
|
+
hatch: a table module that also contains a `z.object(...)` is bundled and
|
|
144
|
+
evaluated for real, so a derivation in that file happens to work. Whether it
|
|
145
|
+
works depends on unrelated content in the table file — declare the shape
|
|
146
|
+
instead.
|
|
98
147
|
|
|
99
148
|
Parameterized standalone paths use Hono's `:param` syntax in authored source,
|
|
100
149
|
for example `path: "/events/:eventId/check-in"`. The harvest planner converts
|
|
@@ -91,6 +91,79 @@ For shared Zod schemas or helpers, put them under `<feature>/lib/` and import
|
|
|
91
91
|
from each action file. Files under `lib/` are copied verbatim into the
|
|
92
92
|
generated output.
|
|
93
93
|
|
|
94
|
+
## Replace a CRUD verb
|
|
95
|
+
|
|
96
|
+
CRUD routes are compiler-owned. When a live `POST /messages` (or
|
|
97
|
+
`PATCH` / `DELETE /:id`) has to grow — side effects, a different body, a
|
|
98
|
+
protocol-shaped response — map that verb to a named action. The URL, OpenAPI
|
|
99
|
+
operation id, and MCP tool stay; `execute` becomes the handler.
|
|
100
|
+
|
|
101
|
+
{/* doc-compile: skip — two files (table + action); the gate compiles each fence as an isolated project. */}
|
|
102
|
+
```ts
|
|
103
|
+
// features/messages/messages.ts
|
|
104
|
+
export default feature("messages", {
|
|
105
|
+
columns: { /* … */ },
|
|
106
|
+
read: { access: { roles: ["member"] } },
|
|
107
|
+
create: {
|
|
108
|
+
access: { roles: ["member"] },
|
|
109
|
+
action: "send", // features/messages/actions/send.ts
|
|
110
|
+
},
|
|
111
|
+
update: { access: { roles: ["member"] } },
|
|
112
|
+
delete: { access: { roles: ["admin"] } },
|
|
113
|
+
});
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
// features/messages/actions/send.ts
|
|
118
|
+
import { z } from "zod";
|
|
119
|
+
import { defineAction, messages } from "../.quickback/define-action";
|
|
120
|
+
|
|
121
|
+
export default defineAction({
|
|
122
|
+
description: "Send a message",
|
|
123
|
+
path: "/messages", // must equal the collection URL
|
|
124
|
+
method: "POST",
|
|
125
|
+
input: z.object({ body: z.string().min(1) }),
|
|
126
|
+
access: { roles: ["member"] },
|
|
127
|
+
async execute({ db, input, ctx }) {
|
|
128
|
+
const [row] = await db.insert(messages).values({
|
|
129
|
+
body: input.body,
|
|
130
|
+
organizationId: ctx.activeOrgId!,
|
|
131
|
+
}).returning();
|
|
132
|
+
return row;
|
|
133
|
+
},
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Expected:
|
|
138
|
+
|
|
139
|
+
- `POST /api/v1/messages` runs `send`'s `execute`. Status is `201`.
|
|
140
|
+
- OpenAPI / MCP keep `createMessages` (or the table's CRUD operation id). The
|
|
141
|
+
request body is the action's `input`, not the table's createable fields.
|
|
142
|
+
- Unmapped verbs keep the generated handler. Mapping is per-verb.
|
|
143
|
+
- The action's own route is not mounted — there is no second `POST /messages/send`.
|
|
144
|
+
- Auto-promoted `POST /batch` is suppressed (the stock batch would skip `send`).
|
|
145
|
+
Set `batch: false` explicitly if you also declare a batch config.
|
|
146
|
+
|
|
147
|
+
### Composition
|
|
148
|
+
|
|
149
|
+
Fail-closed, one rule:
|
|
150
|
+
|
|
151
|
+
| Layer | Who owns it |
|
|
152
|
+
|---|---|
|
|
153
|
+
| URL, method, operation id | The CRUD verb |
|
|
154
|
+
| Access | Both: `create.access` AND the action's `access` must pass |
|
|
155
|
+
| Guards | Skipped — the action's `input` is the body contract |
|
|
156
|
+
| Firewall | Table firewall on update/delete record fetch; create uses scoped `db` in `execute` |
|
|
157
|
+
|
|
158
|
+
### Compile errors
|
|
159
|
+
|
|
160
|
+
The compile fails if the named action is missing, bound to a different table,
|
|
161
|
+
the wrong shape (create needs a standalone `path:` equal to the collection URL;
|
|
162
|
+
update/delete need a record-based action with no `path:`), declares a
|
|
163
|
+
conflicting `method`, is already mapped to another verb, or the table also
|
|
164
|
+
declares `owns` (changeset dispatch lives on the stock handler). `read.action`
|
|
165
|
+
is not supported.
|
|
166
|
+
|
|
94
167
|
## The rest of this section
|
|
95
168
|
|
|
96
169
|
- **[Defining actions](/define/actions/defining)** — the action file, its configuration options, protected fields, and refs
|
|
@@ -15,7 +15,7 @@ feature("name", {
|
|
|
15
15
|
// Security — the five pillars
|
|
16
16
|
firewall: {}, // which ROWS (auto-derived from organizationId / ownerId / teamId)
|
|
17
17
|
read: {}, // who may read + `views` — named column projections
|
|
18
|
-
create: {}, // who may write
|
|
18
|
+
create: {}, // who may write — `action: "send"` maps the URL to an action file
|
|
19
19
|
update: {},
|
|
20
20
|
delete: {}, // + `mode: "soft" | "hard"`
|
|
21
21
|
guards: {}, // which FIELDS a caller may set
|
|
@@ -41,6 +41,7 @@ feature("name", {
|
|
|
41
41
|
| Tenant isolation, role gates, field and value control | `firewall`, `read`/`create`/`update`/`delete`, `guards`, `masking` | [Security](/define/security) |
|
|
42
42
|
| A narrower shape for a broader audience | `read.views` | [Views](/define/views) |
|
|
43
43
|
| `publish` / `approve` / `checkIn` — a state change | `transitions` | [Transitions](/define/transitions) |
|
|
44
|
+
| A live CRUD URL that needs custom `execute` | `create.action` / `update.action` / `delete.action` | [Actions](/define/actions#replace-a-crud-verb) |
|
|
44
45
|
| A side-effect or data rule on every write | `triggers` | [Triggers](/define/triggers) |
|
|
45
46
|
| Parent plus its children written atomically | `owns` | [Changesets](/define/changesets) |
|
|
46
47
|
| Clients updated live | `realtime` | [Realtime](/platform/realtime/using-realtime) |
|