@quickback-dev/cli 0.65.0 → 0.66.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/dist/commands/compile.d.ts +1 -1
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +13 -0
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/lib/action-harvest.d.ts.map +1 -1
  7. package/dist/lib/action-harvest.js +14 -6
  8. package/dist/lib/action-harvest.js.map +1 -1
  9. package/dist/lib/action-harvest.test.js +26 -0
  10. package/dist/lib/action-harvest.test.js.map +1 -1
  11. package/dist/lib/migrations/drizzle.d.ts.map +1 -1
  12. package/dist/lib/migrations/drizzle.js +6 -1
  13. package/dist/lib/migrations/drizzle.js.map +1 -1
  14. package/dist/lib/migrations/drizzle.test.js +3 -0
  15. package/dist/lib/migrations/drizzle.test.js.map +1 -1
  16. package/dist/skill/docs/api/batch-operations.md +1 -1
  17. package/dist/skill/docs/api/crud.md +1 -1
  18. package/dist/skill/docs/api/index.md +1 -1
  19. package/dist/skill/docs/api/query-params.md +5 -8
  20. package/dist/skill/docs/changelog/index.md +109 -1
  21. package/dist/skill/docs/configure/auth.md +20 -12
  22. package/dist/skill/docs/configure/domains.md +11 -0
  23. package/dist/skill/docs/configure/index.md +16 -27
  24. package/dist/skill/docs/configure/providers.md +1 -1
  25. package/dist/skill/docs/define/actions/defining.md +2 -2
  26. package/dist/skill/docs/define/actions/record-and-standalone.md +1 -1
  27. package/dist/skill/docs/define/actions/scoped-db.md +1 -1
  28. package/dist/skill/docs/define/changesets.md +7 -8
  29. package/dist/skill/docs/define/feature.md +0 -1
  30. package/dist/skill/docs/define/read.md +2 -2
  31. package/dist/skill/docs/define/sealed-protocol.md +1 -1
  32. package/dist/skill/docs/platform/api-contract/index.md +52 -42
  33. package/dist/skill/docs/platform/auth/jwt-optimization.md +1 -1
  34. package/dist/skill/docs/platform/auth/plugins/index.md +9 -2
  35. package/dist/skill/docs/platform/database/neon.md +1 -1
  36. package/dist/skill/docs/platform/realtime/durable-objects.md +69 -36
  37. package/dist/skill/docs/platform/realtime/index.md +8 -10
  38. package/dist/skill/docs/platform/realtime/named-invalidations.md +23 -9
  39. package/dist/skill/docs/platform/realtime/using-realtime.md +58 -34
  40. package/dist/skill/docs/platform/webhooks/outbound.md +4 -5
  41. package/dist/skill/docs/tooling/output.md +1 -1
  42. package/dist/skill/docs/ui/account/hooks.md +0 -1
  43. package/package.json +1 -1
  44. package/src/skill/docs/api/batch-operations.md +1 -1
  45. package/src/skill/docs/api/crud.md +1 -1
  46. package/src/skill/docs/api/index.md +1 -1
  47. package/src/skill/docs/api/query-params.md +5 -8
  48. package/src/skill/docs/changelog/index.md +109 -1
  49. package/src/skill/docs/configure/auth.md +20 -12
  50. package/src/skill/docs/configure/domains.md +11 -0
  51. package/src/skill/docs/configure/index.md +16 -27
  52. package/src/skill/docs/configure/providers.md +1 -1
  53. package/src/skill/docs/define/actions/defining.md +2 -2
  54. package/src/skill/docs/define/actions/record-and-standalone.md +1 -1
  55. package/src/skill/docs/define/actions/scoped-db.md +1 -1
  56. package/src/skill/docs/define/changesets.md +7 -8
  57. package/src/skill/docs/define/feature.md +0 -1
  58. package/src/skill/docs/define/read.md +2 -2
  59. package/src/skill/docs/define/sealed-protocol.md +1 -1
  60. package/src/skill/docs/platform/api-contract/index.md +52 -42
  61. package/src/skill/docs/platform/auth/jwt-optimization.md +1 -1
  62. package/src/skill/docs/platform/auth/plugins/index.md +9 -2
  63. package/src/skill/docs/platform/database/neon.md +1 -1
  64. package/src/skill/docs/platform/realtime/durable-objects.md +69 -36
  65. package/src/skill/docs/platform/realtime/index.md +8 -10
  66. package/src/skill/docs/platform/realtime/named-invalidations.md +23 -9
  67. package/src/skill/docs/platform/realtime/using-realtime.md +58 -34
  68. package/src/skill/docs/platform/webhooks/outbound.md +4 -5
  69. package/src/skill/docs/tooling/output.md +1 -1
  70. package/src/skill/docs/ui/account/hooks.md +0 -1
@@ -24,20 +24,28 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
24
24
 
25
25
  Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
26
26
 
27
- > **This JWT surface is opt-in by default**
27
+ > **This JWT surface is opt-in**
28
28
  >
29
- > Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
30
- > JWT surface only when `auth.jwt` is present. If it is omitted, generated output
31
- > has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
32
- > fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
33
- > the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
34
- > JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
35
- > also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
36
- > exist. Better Auth cookie and signed session-token bearer authentication remain
37
- > available.
29
+ > Quickback emits this custom JWT surface only when `auth.jwt` is present. Omit
30
+ > it and the generated output has no generic `/api/v1/token` endpoint, no
31
+ > identity JWT mint, and no Bearer-JWT instructions in `llms.txt` or RFC 8414
32
+ > discovery metadata. Better Auth cookie and signed session-token bearer
33
+ > authentication remain available.
38
34
  >
39
- > Use `auth: { jwt: {} }` to opt a v2 project into the defaults documented below.
40
- > Contract v1 keeps the historical always-emitted JWT surface for compatibility.
35
+ > **Scopes are the exception.** A project that declares
36
+ > [`authz.scopes`](/define/scopes) always emits `src/lib/jwt.ts` (scope tokens
37
+ > are signed JWTs) *and* a scope-only verification block that admits them —
38
+ > without the token endpoint or the identity fast-path. Declaring scopes does
39
+ > not open the credential surface.
40
+ >
41
+ > One gap to know about: that block admits **sessionless** scope tokens
42
+ > (`ctx.mintScope`). A token minted from a session — `POST /scope/v1/enter`, or
43
+ > a namespace with `mintScope: true` — carries user claims instead of the
44
+ > scope-only marker, and without `auth.jwt` nothing can admit it, so the caller
45
+ > gets 200 from the mint and 401 when presenting it. The compiler warns. Declare
46
+ > `auth: { jwt: {} }` if you rely on those routes.
47
+ >
48
+ > Use `auth: { jwt: {} }` to opt into the defaults documented below.
41
49
 
42
50
 
43
51
  ### Security posture at a glance
@@ -287,6 +287,17 @@ Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed w
287
287
  > When more than one app is hostname-mounted, extras attach to the first registered apps middleware (Hono runs middleware in registration order and terminates on first match). If you need extras to route to a specific app in a multi-app deploy, set `apps[*].domain` directly and recompile rather than using this env var.
288
288
 
289
289
 
290
+ ### Per-deploy app URL
291
+
292
+ `account.appUrl` is baked at compile time into the Account SPA's runtime config and used as the "Go To App" link base in transactional emails — so a preview or dev worker would send emails and render links pointing at production. Set `APP_URL` on the deploy target to override both at serve time: the worker merges it into the runtime config injected into every served shell, and email templates prefer it over `ACCOUNT_URL`.
293
+
294
+ ```toml title="wrangler.preview.toml"
295
+ [vars]
296
+ APP_URL = "https://app-preview.example.com"
297
+ ```
298
+
299
+ Unset means zero behavior change. (Setting it changes the injected runtime-config bytes, so a strict-CSP deploy relying on the precomputed script hash should keep it unset on the production target — the same tradeoff as named-dev host injection.)
300
+
290
301
  ## See Also
291
302
 
292
303
  - [Configuration](/configure) — CMS and Account config options
@@ -94,9 +94,9 @@ Every optional top-level key the config accepts is listed below. You never have
94
94
  | Field | Type | Description |
95
95
  |-------|------|-------------|
96
96
  | `domain` | `string` | Primary custom domain (auto-inferred from `cms`/`account`/`api` domains if unset) — see [Domains](/configure/domains) |
97
- | `contract` | `{ version?: "v1" \| "v2", routes?: "v1" \| "v2" }` | Two independent axes. `version` selects SEMANTICS (default `"v2"`); `routes` selects the URL prefix (default `"v1"`). See [API Contract](/platform/api-contract#two-axes-semantics-and-routes). |
97
+ | `contract` | `{ routes?: "v1" \| "v2" }` | `routes` selects the URL prefix and nothing else (default `"v1"`). See [API Contract](/platform/api-contract#one-axis-routes). |
98
98
  | `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/configure/domains) |
99
- | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
99
+ | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals) |
100
100
  | `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/define/authz-roles#centrally-defined-access-rules) and [Permissions](/define/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/define/areas) (`_area.ts`), and root bodies may reference root-declared names only |
101
101
  | `requires` | `string[]` | Capability floor (fail-closed guard). Declare `['feature-areas']` when the project uses `features/**/_area.ts` — an area-unaware CLI/compiler then refuses the compile instead of silently dropping nested features. See [Feature areas](/define/areas#the-capability-floor-requires-feature-areas) |
102
102
  | `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
@@ -119,17 +119,16 @@ Every optional top-level key the config accepts is listed below. You never have
119
119
  | `dev` | `object` | Local development settings (`port`, `api`, `cms`, `account`, `hostnames`) — see [Variables](/configure/variables) |
120
120
  | `preset` | `string` | Inherit defaults from a named preset |
121
121
 
122
- ## Public contract version
122
+ ## Public contract routes
123
123
 
124
- Quickback runs the **v2 contract on `/api/v1` by default** — `version` and
125
- `routes` are independent. Pin `version: "v1"` to opt out of v2 semantics; set
126
- `routes: "v2"` to move the URLs:
124
+ `contract.routes` selects the URL prefix and nothing else. It defaults to
125
+ `"v1"`; set `"v2"` to move the URLs:
127
126
 
128
127
  ```typescript
129
128
  export default defineConfig({
130
129
  name: "my-app",
131
130
  template: "hono",
132
- contract: { version: "v2", routes: "v2" },
131
+ contract: { routes: "v2" },
133
132
  providers: cloudflare({}),
134
133
  });
135
134
  ```
@@ -141,8 +140,12 @@ and dedicated-domain shortcuts follow. When CMS or Account is enabled Quickback
141
140
  bakes those paths into the SPA build and injects them at runtime. Quickback
142
141
  does not expose a mixed v1/v2 URL surface from one compiled Worker.
143
142
 
144
- Action input-schema fidelity is a compile gate on **every** contract version
145
- since v0.63.0, not just v2. The CLI must
143
+ `contract.version` is retired — there is one standard API shape. Pinning it is
144
+ a compile error; delete that line and keep `routes`. See
145
+ [API Contract](/platform/api-contract#contractversion-is-retired) for what
146
+ changes if you were pinned to `version: "v1"`.
147
+
148
+ Action input-schema fidelity is a compile gate since v0.63.0. The CLI must
146
149
  successfully harvest `z.toJSONSchema(action.input)` for every authored action;
147
150
  partial or missing harvests fail with the exact action file keys, bundle or
148
151
  evaluation phase, and underlying local error. Dependencies are resolved from
@@ -151,26 +154,13 @@ ancestor installs, so an isolated `quickback/` definition tree can use a
151
154
  sibling `src/` runtime without a workspace-root symlink. The compiler enforces
152
155
  the same invariant at its shared input boundary, including
153
156
  `POST /compile?complete=false`, so validation-only or raw API calls cannot
154
- bypass it. V1 retains the historical best-effort static-schema fallback.
155
-
156
- The version selection also moves the event and read surfaces:
157
-
158
- | Surface | v1 (pinned) | v2 (flagship) |
159
- |---|---|---|
160
- | Realtime data frames (`/broadcast/*`) | raw frames, byte-stable | CloudEvents 1.0 envelopes at DO egress ([realtime](/platform/realtime)) |
161
- | Outbound webhook signing | Standard Webhooks headers **plus** legacy `X-Webhook-*` | Standard Webhooks **only** |
162
- | `?include=` FK-graph embedding | not available | available where a resource/view allowlists it |
163
- | Bare `?fields=` / `fields[<fk>]=` unknown names | silent drop / n/a | 400 on both |
164
-
165
- See [API Contract](/platform/api-contract) for the full v1 → v2 matrix and
166
- migration sequencing.
157
+ bypass it.
167
158
 
168
- ## Delegated principals (contract v2)
159
+ ## Delegated principals
169
160
 
170
161
  `auth.principals` defines non-account authority such as an event pass or a
171
- short-lived event session. It is available only with all three of:
162
+ short-lived event session. It requires both of:
172
163
 
173
- - `contract: { version: "v2" }`
174
164
  - the Cloudflare runtime
175
165
  - Neon with `connectionMode: "hyperdrive"`
176
166
 
@@ -182,7 +172,6 @@ principal types cannot share a scheme.
182
172
  export default defineConfig({
183
173
  name: "attend-v2",
184
174
  template: "hono",
185
- contract: { version: "v2" },
186
175
  auth: {
187
176
  principals: {
188
177
  event_pass: {
@@ -500,7 +489,7 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
500
489
  When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
501
490
 
502
491
  - `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
503
- when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
492
+ when `contract.routes` is `"v2"` (the URL axis — the standard shape does
504
493
  not move these)
505
494
  - `/storage/*` — R2 file storage
506
495
  - `/health`, `/openapi.json` — monitoring/discovery
@@ -215,7 +215,7 @@ providers: {
215
215
  }
216
216
  ```
217
217
 
218
- > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
218
+ > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. The path is the only thing `routes` moves — frame format is unaffected.
219
219
 
220
220
  `wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
221
221
 
@@ -83,7 +83,7 @@ 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
84
  `Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
85
85
 
86
- **Every action input must produce a schema, on every contract version.** Since
86
+ **Every action input must produce a schema.** Since
87
87
  v0.63.0 a failed harvest fails the compile, naming the exact action, whether
88
88
  bundling or evaluation failed, and the underlying local error. Output remains
89
89
  optional.
@@ -160,7 +160,7 @@ see [Error Handling](/api/actions#error-handling) for what actually happens.
160
160
  Parameterized standalone paths use Hono's `:param` syntax in authored source,
161
161
  for example `path: "/events/:eventId/check-in"`. The harvest planner converts
162
162
  those segments to the OpenAPI `{param}` form before applying the schema, so
163
- contract-v2 completeness uses the same route key as the emitted OpenAPI and MCP
163
+ completeness uses the same route key as the emitted OpenAPI and MCP
164
164
  surfaces. The same normalization applies when a record resource path contains
165
165
  namespace parameters.
166
166
 
@@ -138,7 +138,7 @@ single-record endpoint (`POST /:id/{action}`) or write a standalone action.
138
138
 
139
139
  The generated OpenAPI document and MCP tools reuse that exact action schema
140
140
  in both places: as the single-record request body and as the bulk wrapper's
141
- nested `input` property. Under contract v2, Quickback considers the action's
141
+ nested `input` property. Quickback considers the action's
142
142
  schema harvest complete only after both operations are patched. This also
143
143
  holds when the table filename and declared table name use different casing or
144
144
  separators (for example, `event-guests.ts` exporting `event_guests`); the
@@ -32,7 +32,7 @@ async execute({ db, ctx, input }) {
32
32
 
33
33
  ### Delegated principals and `databaseAccess`
34
34
 
35
- On a contract-v2 Cloudflare + Neon Hyperdrive project, an action can admit a
35
+ On a Cloudflare + Neon Hyperdrive project, an action can admit a
36
36
  configured delegated principal with `access.principals`:
37
37
 
38
38
  ```typescript
@@ -7,12 +7,11 @@ compiler was missing — which relations are **compositions** (owned by this
7
7
  root) vs **references** (independent entities) — and the compiler generates
8
8
  the whole write path.
9
9
 
10
- Changesets are a **contract v2** capability (`contract: { version: "v2" }`).
11
10
  Declaring `owns` on a v1-pinned project is a compile error.
12
11
 
13
12
  ## Declaring the boundary — `owns`
14
13
 
15
- {/* doc-compile: skip — two reasons. (1) Project-config prerequisite: `owns` is a contract-v2 capability (stated two paragraphs above) and needs `contract: { version: "v2" }`; the gate's harness config pins v1. (2) The fence is the `owns` boundary only — columns/firewall/guards/masking/read are elided, and it names three sibling tables (`tasks`, `people`, `taskChecklistItems`) it deliberately does not repeat. */}
14
+ {/* doc-compile: skip — the fence is the `owns` boundary only: columns/firewall/guards/masking/read are elided, and it names three sibling tables (`tasks`, `people`, `taskChecklistItems`) it deliberately does not repeat. */}
16
15
  ```ts title="quickback/features/projects/projects.ts"
17
16
  export default feature("projects", {
18
17
  // ...columns, firewall, guards, masking, read...
@@ -70,9 +69,9 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
70
69
  One blessed path — **RFC 5789 media-type dispatch** on the routes you already
71
70
  have. No subpath.
72
71
 
73
- Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
72
+ Paths below use the default `/api/v1` prefix. Changesets are a
74
73
  **semantics** feature and v2 is the default, so they are available without
75
- moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
74
+ moving your URLs — set [`contract.routes`](/platform/api-contract#one-axis-routes)
76
75
  to `"v2"` only if you also want the `/api/v2` prefix.
77
76
 
78
77
  - `PATCH /api/v1/<resource>/:id` with
@@ -212,7 +211,7 @@ stamping (`createdBy` / `modifiedBy`) rides the same chokepoint. The only gap is
212
211
  `afterDelete`, which the soft-delete stamp can't see — identical to the plain
213
212
  DELETE route's own limitation. (`sql:` triggers fire on every path regardless,
214
213
  as always.) This is the parity the trigger docs promise: a generated
215
- contract-v2 changeset is a compiler write surface, not one of the
214
+ changeset is a compiler write surface, not one of the
216
215
  queue/cron/raw-SQL bypasses that skip handler hooks.
217
216
 
218
217
  Compile-time, fail-closed (everything throws, nothing normalizes silently):
@@ -244,7 +243,7 @@ Compile-time, fail-closed (everything throws, nothing normalizes silently):
244
243
  the wire parser reserves those payload keys, so such a relation would be
245
244
  silently unreachable on the wire.
246
245
  - One aggregate root per table, acyclic graph, bounded depth, declared child
247
- ops only, soft-delete children only, contract v2 only.
246
+ ops only, soft-delete children only.
248
247
 
249
248
  ## `afterCommit` — emit a realtime signal after the changeset commits
250
249
 
@@ -255,7 +254,7 @@ strictly **after** the transaction commits, riding the existing
255
254
  [named-invalidation / Broadcaster egress](/platform/realtime/named-invalidations)
256
255
  (so it inherits the CloudEvents envelope + AsyncAPI description for free).
257
256
 
258
- {/* doc-compile: skip — project-config prerequisites this fence cannot carry: `owns` needs `contract: { version: "v2" }`, and the `broadcast` event `attendRealtime.mobileBundleChanged.travelUpdated` plus its `thisEvent` delivery profile must be declared in a realtime registry under `services/realtime/`. Columns/firewall/read/crud are elided to `// ...` and the owned child table is not repeated. */}
257
+ {/* doc-compile: skip — project-config prerequisite this fence cannot carry: the `broadcast` event `attendRealtime.mobileBundleChanged.travelUpdated` plus its `thisEvent` delivery profile must be declared in a realtime registry under `services/realtime/`. Columns/firewall/read/crud are elided to `// ...` and the owned child table is not repeated. */}
259
258
  ```ts title="quickback/features/travel/lodging-reservations.ts"
260
259
  export default defineTable(lodgingReservations, {
261
260
  // ...firewall / read / crud ...
@@ -423,7 +422,7 @@ authored actions delegate through when they still need residue logic
423
422
  (preconditions, server-side transforms, notifications) around the aggregate
424
423
  write:
425
424
 
426
- {/* doc-compile: skip — the fence imports `../projects.changeset`, a module the compiler only generates for a contract-v2 root that declares `owns`; the gate's harness config pins v1, so the import cannot resolve. `description` / `input` / `access` are elided to `// ...` on purpose — the point is the delegation seam. */}
425
+ {/* doc-compile: skip — the fence imports `../projects.changeset`, a module the compiler only generates for a root that declares `owns`, which this fence does not carry, so the import cannot resolve. `description` / `input` / `access` are elided to `// ...` on purpose — the point is the delegation seam. */}
427
426
  ```ts title="quickback/features/projects/actions/importBoard.ts"
428
427
  // Action files are compiled into the feature directory, next to the
429
428
  // generated module — the relative import resolves at runtime.
@@ -191,7 +191,6 @@ that row." It does **not** say who owns whom. When a set of child rows has no
191
191
  lifecycle of its own — junction memberships, normalized phones/emails, line
192
192
  items — declare the composition with `owns` on the root table:
193
193
 
194
- {/* doc-compile: skip — project-config prerequisite: `owns` is a contract-v2 capability (the prose below says so) and needs `contract: { version: 'v2' }` in quickback.config.ts; the gate's harness config pins v1. The file is otherwise whole. */}
195
194
  ```ts
196
195
  export default feature("projects", {
197
196
  columns: {
@@ -233,7 +233,7 @@ export default defineTable(balanceSnapshots, {
233
233
 
234
234
  ## Aggregate Reads
235
235
 
236
- Reading a parent **with** its owned relations rides contract-v2 `?include=`,
236
+ Reading a parent **with** its owned relations rides `?include=`,
237
237
  which accepts two kinds of tokens in the same `read.include` allowlist:
238
238
 
239
239
  - **FK columns** (`?include=vendorId`) — forward embeds: the target rows the
@@ -242,7 +242,7 @@ which accepts two kinds of tokens in the same `read.include` allowlist:
242
242
  reader: the changeset root's owned **child rows**, pivoting on the root PK
243
243
  and matching the child's declared `fk` column.
244
244
 
245
- {/* doc-compile: skip — project-config prerequisite: `owns` + `?include=` are contract-v2 capabilities (the prose above says so) and need `contract: { version: 'v2' }` in quickback.config.ts; the gate's harness config pins v1. It also names a `noteReactions` child table that the fence deliberately does not repeat. */}
245
+ {/* doc-compile: skip — the fence names a `noteReactions` child table it deliberately does not repeat. */}
246
246
  ```typescript
247
247
  export default defineTable(notes, {
248
248
  owns: { reactions: { table: 'noteReactions', fk: 'noteId' } },
@@ -269,7 +269,7 @@ When the passkey plugin is enabled, `/reveal` verifies a WebAuthn assertion whos
269
269
  | Field | Value |
270
270
  |---|---|
271
271
  | `challenge` | the `/challenge` `nonce` **as the base64url string** (the client signs the b64url text, the server passes `expectedChallenge = nonce`) |
272
- | `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the host of `env.ACCOUNT_URL` |
272
+ | `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the registrable host of `env.ACCOUNT_URL`, else the compile-time account origin (both emissions share one resolution, so they cannot skew) |
273
273
  | `userVerification` | **required** (`requireUserVerification: true` — a reveal is a deliberate re-auth) |
274
274
  | origin | the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin) |
275
275
 
@@ -1,19 +1,20 @@
1
1
  # API Contract
2
2
 
3
- Every generated API speaks one public HTTP contract, selected once per project:
3
+ Every generated API speaks **one** public HTTP contract. There is no version to
4
+ select: the behavior on this page is what every project gets.
5
+
6
+ The only contract choice is the URL prefix, and it defaults to `/api/v1` so
7
+ existing clients keep the address they already call:
4
8
 
5
9
  ```ts title="quickback/quickback.config.ts"
6
10
  export default defineConfig({
7
- // Omitted = v2 semantics on /api/v1. Pin "v1" to opt out.
8
- contract: { version: "v2" },
11
+ contract: { routes: "v2" }, // optional — serve on /api/v2 instead
9
12
  // ...
10
13
  });
11
14
  ```
12
15
 
13
- **v2 is the flagship contract, and the default since v0.64.0.** Everything new
14
- lands on v2; a project pinned to v1 keeps the byte-stable legacy wire and
15
- receives no new contract features until it migrates. Your URLs are a separate
16
- choice — see [below](#two-axes-semantics-and-routes).
16
+ `contract.version` is retired and pinning it is a compile error — see
17
+ [below](#contractversion-is-retired).
17
18
 
18
19
  ## Response envelope
19
20
 
@@ -29,8 +30,8 @@ object itself:
29
30
  }
30
31
  ```
31
32
 
32
- `included` appears only when the request carried `?include=` (contract v2 —
33
- see [query params](/api/query-params)).
33
+ `included` appears only when the request carried `?include=` — see
34
+ [query params](/api/query-params).
34
35
 
35
36
  ## Errors — RFC 9457 Problem Details
36
37
 
@@ -112,59 +113,68 @@ export default defineAction({
112
113
  });
113
114
  ```
114
115
 
115
- ## Two axes: semantics and routes
116
+ ## One axis: routes
116
117
 
117
- `contract` has two independent keys, and conflating them is the most common
118
- mistake:
118
+ `contract` has a single key. It selects the URL prefix and nothing else.
119
119
 
120
120
  | Key | Controls | Default |
121
121
  |---|---|---|
122
- | `version` | Semantics — framing, strictness, the auth lane | `'v2'` |
123
122
  | `routes` | The URL prefix, and nothing else | `'v1'` |
124
123
 
125
- So a project with no `contract` block **runs the v2 contract on `/api/v1`.**
126
- Taking the flagship semantics does not move your URLs, and moving your URLs
127
- does not change your semantics.
124
+ A project with no `contract` block serves `/api/v1`. Set `routes: "v2"` to
125
+ serve `/api/v2` instead — the behavior is identical either way.
128
126
 
129
127
  {/* doc-compile: skip — config fragment, not a compilable project */}
130
128
  ```typescript
131
- contract: { version: "v1" } // opt out of v2 semantics
132
- contract: { routes: "v2" } // serve on /api/v2, keep v1 semantics
133
- contract: { version: "v2", routes: "v2" } // both — the pre-v0.64.0 "v2"
129
+ contract: { routes: "v2" } // serve on /api/v2 instead of /api/v1
134
130
  ```
135
131
 
136
- **This changed in v0.64.0.** Before it, `version: 'v2'` moved the URLs too, and
137
- the default was `'v1'` on both axes. A project that pinned `version: 'v2'` to
138
- get `/api/v2` must now add `routes: 'v2'` to keep those URLs.
132
+ ### `contract.version` is retired
133
+
134
+ There is one standard API shape, so there is nothing to select. Pinning
135
+ `contract.version` is a compile error.
139
136
 
140
- **Pinning your CLI version does not pin the contract.** The default lives in the
141
- compiler, which is a hosted service — an older CLI inherits it too. The config
142
- key is the only pin.
137
+ **Delete that one line and keep `routes` if you have it.** `routes` is the
138
+ surviving axis and controls your URLs — removing it would move them.
143
139
 
144
- ## Contract version matrix
140
+ {/* doc-compile: skip — config fragment, not a compilable project */}
141
+ ```typescript
142
+ contract: { version: "v2", routes: "v1" } // before
143
+ contract: { routes: "v1" } // after — same URLs, same behavior
144
+ ```
145
145
 
146
- `version` moves everything in this table except the three base paths, which
147
- follow `routes`:
146
+ Deleting `version: "v2"` changes nothing: it selected what is now simply the
147
+ standard shape. Deleting `version: "v1"` is a real migration — that pin opted
148
+ out of four behaviors that are now unconditional:
148
149
 
149
- | Surface | v1 (pinned) | v2 (flagship) |
150
+ | Surface | What `version: "v1"` did | What you get now |
150
151
  |---|---|---|
151
- | API base | `/api/v1` | `/api/v2` |
152
- | Auth base | `/auth/v1` | `/auth/v2` |
153
- | Realtime base | `/broadcast/v1` | `/broadcast/v2` |
154
152
  | Quickback HMAC-JWT lane | on by default | only with explicit `auth.jwt` |
155
153
  | Realtime data frames | raw (byte-stable) | CloudEvents 1.0 envelopes ([realtime](/platform/realtime)) |
156
154
  | Outbound webhook signing | Standard Webhooks **+** legacy `X-Webhook-*` | Standard Webhooks **only** |
157
- | `?include=` FK embedding | not available | available where allowlisted |
158
- | Aggregate changesets (`application/vnd.quickback.changeset+json` on PATCH/POST, [`owns`](/define/changesets)) | not available | available where `owns` is declared |
159
155
  | Bare `?fields=` unknown names | silently dropped | **400** |
160
- | `fields[<fk>]=` unknown names | n/a | **400** |
161
- | Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
162
-
163
- Sequencing a migration: the URL row is the only one you can defer with
164
- `routes`. For the rest — ship subscribers that parse CloudEvents frames, move
165
- webhook consumers onto the `webhook-*` headers (v1 already sends **both** sets,
166
- so that step needs no coordination), and either adopt session-first auth or
167
- declare `auth.jwt`. Pin `version: "v1"` while that work lands.
156
+
157
+ Features that a v1 pin refused are now always available: `?include=` FK
158
+ embedding where allowlisted, aggregate changesets on PATCH/POST where
159
+ [`owns`](/define/changesets) is declared, `fields[<fk>]=` projection (unknown
160
+ names **400**), `auth.principals`, and `atomicAuthRoutes: 'emailOtpSignIn'`.
161
+
162
+ Migrating off a v1 pin: ship subscribers that parse CloudEvents frames, move
163
+ webhook consumers onto the `webhook-*` headers, and either adopt session-first
164
+ auth or declare `auth.jwt`.
165
+
166
+ **Pinning your CLI version does not pin behavior.** The compiler is a hosted
167
+ service, so an older CLI gets the same output.
168
+
169
+ ### Base paths
170
+
171
+ `routes` moves all three together:
172
+
173
+ | Surface | `routes: "v1"` (default) | `routes: "v2"` |
174
+ |---|---|---|
175
+ | API base | `/api/v1` | `/api/v2` |
176
+ | Auth base | `/auth/v1` | `/auth/v2` |
177
+ | Realtime base | `/broadcast/v1` | `/broadcast/v2` |
168
178
 
169
179
  ## Machine-readable contract
170
180
 
@@ -51,7 +51,7 @@ auth: {
51
51
 
52
52
  > **This surface is opt-in by default**
53
53
  >
54
- > Contract v2 is the default since v0.64.0, and on it the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
54
+ > The custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. A project that declares `authz.scopes` does **not** need `auth.jwt`: it gets scope-token admission on its own, without the token endpoint or the identity fast-path. Declaring `auth.jwt` is what opts into the full credential lane. See [Auth & JWT config](/configure/auth).
55
55
  >
56
56
  > `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
57
57
 
@@ -193,8 +193,15 @@ auth: defineAuth("better-auth", {
193
193
  }),
194
194
  ```
195
195
 
196
- **Required environment variable:**
197
- - `ACCOUNT_URL` - Your account/frontend URL (used as the relying party origin for WebAuthn)
196
+ **Relying party resolution:**
197
+
198
+ WebAuthn needs a relying party ID and origin. The generated plugin resolves them in this order:
199
+
200
+ 1. `advanced.crossSubDomainCookies.domain` (leading dot stripped) becomes the `rpID` when configured — credentials then work across sibling subdomains.
201
+ 2. The `ACCOUNT_URL` env var, when set on the deploy target: `rpID` is its registrable hostname (`account.example.com` → `example.com`; a two-label host like `example.com` is kept whole) and the origin is its **bare origin** — a path suffix such as `/account` is dropped, so the same variable can keep serving as the email link base.
202
+ 3. The compile-time account origin — `account.domain` when configured, else the project's unified host. Baked automatically; no env var required.
203
+
204
+ `rpID: 'localhost'` applies only when the project has no configured domain at all (pure local dev). If passkey registration returns 500 on a deployed worker, check that one of the three sources above resolves to the hostname the Account UI is actually served from.
198
205
 
199
206
  **Endpoints:**
200
207
  - `POST /auth/v1/passkey/register/options` - Get registration challenge
@@ -504,7 +504,7 @@ with neither a stamped user id nor a delegated principal) and a `service_role`
504
504
  policy (admits Worker-internal contexts — see
505
505
  [Background jobs and cross-tenant actions](#background-jobs-and-cross-tenant-actions)).
506
506
 
507
- ### Delegated principal RLS (contract v2)
507
+ ### Delegated principal RLS
508
508
 
509
509
  Delegated principals require Cloudflare + Neon Hyperdrive. Their proof hook
510
510
  returns only a digest and receives no database handle. Quickback then runs one