@quickback-dev/cli 0.51.0 → 0.52.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 (91) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +34 -19
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +31 -21
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/lib/action-harvest.d.ts +35 -4
  9. package/dist/lib/action-harvest.d.ts.map +1 -1
  10. package/dist/lib/action-harvest.js +233 -50
  11. package/dist/lib/action-harvest.js.map +1 -1
  12. package/dist/lib/action-harvest.test.js +130 -2
  13. package/dist/lib/action-harvest.test.js.map +1 -1
  14. package/dist/lib/auth.d.ts +6 -0
  15. package/dist/lib/auth.d.ts.map +1 -1
  16. package/dist/lib/auth.js +18 -1
  17. package/dist/lib/auth.js.map +1 -1
  18. package/dist/lib/auth.test.d.ts +2 -0
  19. package/dist/lib/auth.test.d.ts.map +1 -0
  20. package/dist/lib/auth.test.js +19 -0
  21. package/dist/lib/auth.test.js.map +1 -0
  22. package/dist/lib/compile-next-steps.d.ts +4 -0
  23. package/dist/lib/compile-next-steps.d.ts.map +1 -0
  24. package/dist/lib/compile-next-steps.js +69 -0
  25. package/dist/lib/compile-next-steps.js.map +1 -0
  26. package/dist/lib/compile-next-steps.test.d.ts +2 -0
  27. package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
  28. package/dist/lib/compile-next-steps.test.js +76 -0
  29. package/dist/lib/compile-next-steps.test.js.map +1 -0
  30. package/dist/lib/file-loader.d.ts.map +1 -1
  31. package/dist/lib/file-loader.js +1 -0
  32. package/dist/lib/file-loader.js.map +1 -1
  33. package/dist/lib/file-writer.d.ts +1 -1
  34. package/dist/lib/file-writer.d.ts.map +1 -1
  35. package/dist/lib/file-writer.js +20 -5
  36. package/dist/lib/file-writer.js.map +1 -1
  37. package/dist/lib/file-writer.test.d.ts +2 -0
  38. package/dist/lib/file-writer.test.d.ts.map +1 -0
  39. package/dist/lib/file-writer.test.js +90 -0
  40. package/dist/lib/file-writer.test.js.map +1 -0
  41. package/dist/lib/shell.test.d.ts +2 -0
  42. package/dist/lib/shell.test.d.ts.map +1 -0
  43. package/dist/lib/shell.test.js +39 -0
  44. package/dist/lib/shell.test.js.map +1 -0
  45. package/dist/skill/docs/changelog.md +476 -2
  46. package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  47. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  48. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  49. package/dist/skill/docs/compiler/config/auth.md +17 -2
  50. package/dist/skill/docs/compiler/config/index.md +271 -12
  51. package/dist/skill/docs/compiler/config/output.md +49 -3
  52. package/dist/skill/docs/compiler/config/providers.md +12 -1
  53. package/dist/skill/docs/compiler/config/variables.md +5 -0
  54. package/dist/skill/docs/compiler/definitions/access.md +7 -0
  55. package/dist/skill/docs/compiler/definitions/actions.md +267 -9
  56. package/dist/skill/docs/compiler/definitions/bundles.md +69 -0
  57. package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
  58. package/dist/skill/docs/compiler/definitions/masking.md +2 -2
  59. package/dist/skill/docs/compiler/definitions/schema.md +12 -0
  60. package/dist/skill/docs/compiler/definitions/transitions.md +149 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  63. package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
  64. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  65. package/dist/skill/docs/stack/cms/schema-format.md +4 -2
  66. package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
  67. package/dist/skill/docs/stack/realtime/durable-objects.md +17 -4
  68. package/package.json +1 -1
  69. package/src/skill/docs/changelog.md +476 -2
  70. package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  71. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  72. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  73. package/src/skill/docs/compiler/config/auth.md +17 -2
  74. package/src/skill/docs/compiler/config/index.md +271 -12
  75. package/src/skill/docs/compiler/config/output.md +49 -3
  76. package/src/skill/docs/compiler/config/providers.md +12 -1
  77. package/src/skill/docs/compiler/config/variables.md +5 -0
  78. package/src/skill/docs/compiler/definitions/access.md +7 -0
  79. package/src/skill/docs/compiler/definitions/actions.md +267 -9
  80. package/src/skill/docs/compiler/definitions/bundles.md +69 -0
  81. package/src/skill/docs/compiler/definitions/firewall.md +6 -1
  82. package/src/skill/docs/compiler/definitions/masking.md +2 -2
  83. package/src/skill/docs/compiler/definitions/schema.md +12 -0
  84. package/src/skill/docs/compiler/definitions/transitions.md +149 -0
  85. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  86. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  87. package/src/skill/docs/stack/account-ui/hooks.md +104 -1
  88. package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  89. package/src/skill/docs/stack/cms/schema-format.md +4 -2
  90. package/src/skill/docs/stack/cms/schema-registry.md +4 -2
  91. package/src/skill/docs/stack/realtime/durable-objects.md +17 -4
@@ -75,6 +75,22 @@ Reads your definitions and generates:
75
75
 
76
76
  Run this after making changes to your definitions.
77
77
 
78
+ #### Configuration-aware completion steps
79
+
80
+ After a successful compile, the CLI derives its next steps from the configured
81
+ database connection mode. Neon HTTP projects receive the direct
82
+ `DATABASE_URL`, `.dev.vars`, migration, and deploy workflow. Hyperdrive
83
+ projects instead receive migration-only `DATABASE_MIGRATION_URL` guidance and
84
+ local development instructions for the configured Hyperdrive
85
+ `localConnectionString`; the CLI never recommends `DATABASE_URL` as a Worker
86
+ secret for that mode.
87
+
88
+ When `providers.database.environments` defines isolated targets, the footer
89
+ lists the configured Neon branches, each target's required Worker secrets, and
90
+ explicit `wrangler ... --env <target>` deploy commands. It does not suggest a
91
+ bare deploy or the unnamed `.env.neon` / `.dev.vars` workflow for named
92
+ Hyperdrive environments.
93
+
78
94
  #### Generated `src/` is hermetic
79
95
 
80
96
  Every file under `src/` carries a `Generated by quickback.dev` header and is owned by the compiler. Before each compile writes its output, the CLI:
@@ -36,9 +36,11 @@ The map uses project-root-relative paths and follows the same layout `quickback
36
36
  Two constraints, both fail-closed:
37
37
 
38
38
  - **The config must be fully static.** The compiler parses `quickback.config.ts` with a literals-only evaluator — it never executes user code. Object/array/string/number/boolean literals, substitution-free template literals, and the `define*` helper calls all work; variables, computed values, and imports-as-values are rejected with a 400 that names the offending construct and line.
39
- - **Action input schemas are optional.** The CLI harvests `z.toJSONSchema` on your machine; raw-files requests may pass `actionInputSchemas` alongside `rawFiles`, otherwise the compiler's static parser supplies lower-fidelity input schemas.
39
+ - **Action input schemas are contract-sensitive.** For v1, raw-files requests may omit `actionInputSchemas` and use the compiler's lower-fidelity static parser. V2 requires one usable client-harvested `z.toJSONSchema(action.input)` entry for every authored action. The CLI reports each missing action with its local bundle or evaluation error; the API independently reports missing or invalid action keys.
40
40
 
41
- Works with both `?complete=true` and `?complete=false` (validation-only) compiles.
41
+ Raw-files requests work with both `?complete=true` and `?complete=false`
42
+ (validation-only) compiles. The v2 action-schema completeness gate applies to
43
+ both modes; `complete=false` is not an escape hatch for a partial harvest.
42
44
 
43
45
  ## Edge validation backend
44
46
 
@@ -6,7 +6,6 @@ Run the Quickback compiler locally using Docker. The local compiler uses the exa
6
6
 
7
7
  - Docker Desktop installed and running
8
8
  - Quickback monorepo cloned locally
9
- - Authenticated via `quickback login`
10
9
 
11
10
  ## Quick Start
12
11
 
@@ -20,7 +19,7 @@ This will:
20
19
  1. Ensure Docker Desktop is running
21
20
  2. Stop any existing compiler container
22
21
  3. Build the Docker image from `apps/compiler/Dockerfile`
23
- 4. Run it on port 3000
22
+ 4. Start it in explicit local mode, published only on `127.0.0.1:3000`
24
23
 
25
24
  ### Custom Port
26
25
 
@@ -43,7 +42,12 @@ export QUICKBACK_API_URL=http://localhost:3000
43
42
  quickback compile
44
43
  ```
45
44
 
46
- Authentication is always required. Run `quickback login` first if you haven't already.
45
+ The supported launcher does not require `quickback login`. It opts the compiler
46
+ into local mode and binds Docker's host port to loopback, so the unauthenticated
47
+ compile endpoint is not exposed to the LAN. The CLI skips its login prompt only
48
+ when `QUICKBACK_API_URL` has the exact hostname `localhost`, `127.0.0.1`, or
49
+ `::1`; longer hostnames and URLs that merely contain those strings still use
50
+ hosted authentication.
47
51
 
48
52
  ## Manual Build & Run
49
53
 
@@ -53,10 +57,18 @@ You can also build and run the Docker image directly from the monorepo root:
53
57
  # Build
54
58
  docker build -t quickback-compiler -f apps/compiler/Dockerfile .
55
59
 
56
- # Run
57
- docker run --rm -p 3000:3000 quickback-compiler
60
+ # Run with the same security boundary as the supported launcher
61
+ docker run --rm \
62
+ -e QUICKBACK_COMPILER_MODE=local \
63
+ -p 127.0.0.1:3000:3000 \
64
+ quickback-compiler
58
65
  ```
59
66
 
67
+ `QUICKBACK_COMPILER_MODE` is fail-closed: only the exact value `local` bypasses
68
+ compile authentication. If the variable is absent or misspelled, the compiler
69
+ uses hosted authentication. Never publish a local-mode container on
70
+ `0.0.0.0` or a non-loopback interface.
71
+
60
72
  ## Verify
61
73
 
62
74
  Check the compiler is running:
@@ -24,6 +24,20 @@ 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
+ > **Contract v2 is opt-in**
28
+ >
29
+ > On `contract: { version: "v2" }`, Quickback emits this custom JWT surface only
30
+ > when `auth.jwt` is present. If it is omitted, generated output has no generic
31
+ > `/api/v2/token` endpoint, `src/lib/jwt.ts`, JWT middleware verify/mint fast-path,
32
+ > or Quickback JWT imports. Generated `llms.txt` and RFC 8414 discovery metadata
33
+ > also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
34
+ > exist. Better Auth cookie and signed session-token bearer authentication remain
35
+ > available.
36
+ >
37
+ > Use `auth: { jwt: {} }` to opt a v2 project into the defaults documented below.
38
+ > Contract v1 keeps the historical always-emitted JWT surface for compatibility.
39
+
40
+
27
41
  ### Security posture at a glance
28
42
 
29
43
  The short version, before the knob-by-knob detail:
@@ -112,9 +126,10 @@ Semantics worth knowing:
112
126
  - **Eventual consistency:** KV propagates cross-PoP in ~60s. "Immediate" means seconds at the writing location, bounded-seconds globally — still far inside the 15-minute carry-forward cap that bounds revocation without this check.
113
127
  - **Coverage gap:** batch *hard* deletes don't return rows through the chokepoint; call `revokeScopeTokens` explicitly if you bulk-hard-delete conferring rows.
114
128
 
115
- ## Defaults preserve 0.10.13 behavior
129
+ ## Defaults when the JWT surface is enabled
116
130
 
117
- Adding the `auth.jwt` block without setting any field is a no-op vs. the 0.10.13 baseline. Each missing field falls back to its hardcoded value:
131
+ Adding `auth.jwt: {}` enables the surface with the historical defaults. Each
132
+ missing field falls back to its hardcoded value:
118
133
 
119
134
  | Field | Default |
120
135
  |---|---|
@@ -94,8 +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](/compiler/config/domains) |
97
- | `api` | `object` | Dedicated hostname for the feature API surface (`/api/v1/*`); additive alias — see [Domains](/compiler/config/domains) |
98
- | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, `loginUrl`/`profileUrl`, `domain`) — see [Access](/compiler/definitions/access#role-hierarchy) |
97
+ | `contract` | `{ version?: "v1" \| "v2" }` | Public API/auth contract version. Omit for the backward-compatible v1 default; select v2 for `/api/v2/*` and `/auth/v2/*` across generated routes, Better Auth, OpenAPI, MCP, and discovery. |
98
+ | `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/compiler/config/domains) |
99
+ | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`/`profileUrl`, `domain`) — see [Access](/compiler/definitions/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
99
100
  | `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `permissions`, `arrows`) — see [Permissions](/compiler/definitions/permissions) |
100
101
  | `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
101
102
  | `features` | `object` | Feature flags such as `organizations` / `pinnedOrganizationId` — see [Pinned Organization Mode](/compiler/config/single-tenant) |
@@ -109,11 +110,177 @@ Every optional top-level key the config accepts is listed below. You never have
109
110
  | `etag` | `object` | ETag caching for GET responses (`{ enabled: false }` to disable) — see [Caching & ETags](/compiler/targets/hono-api/using-the-api/caching) |
110
111
  | `email` | `object` | Email delivery config (`provider`, `from`, `fromName`, `region`) — see [Email Configuration](#email-configuration) |
111
112
  | `bindings` | `object` | Extra Cloudflare bindings (durable objects, queues, R2, services, `vars`, AI) — see [Bindings](/compiler/config/bindings) |
112
- | `compiler` | `object` | Compiler internals — `features.auditFields: false`, `migrations.renames` (headless CI), `securityContracts`, `injectId`, `routes` |
113
+ | `compiler` | `object` | Compiler internals — `features.auditFields: false`, `migrations.renames` (headless CI), Neon `migrations.foreignKeys`, `securityContracts`, `injectId`, `routes` |
113
114
  | `build` | `object` | Build options (`outputDir`, `packageManager`, `dependencies`) — see [Custom Dependencies](#custom-dependencies) |
114
115
  | `dev` | `object` | Local development settings (`port`, `api`, `cms`, `account`, `hostnames`) — see [Variables](/compiler/config/variables) |
115
116
  | `preset` | `string` | Inherit defaults from a named preset |
116
117
 
118
+ ## Public contract version
119
+
120
+ Quickback defaults to the existing v1 HTTP contract. New applications can opt
121
+ into v2 explicitly:
122
+
123
+ ```typescript
124
+ export default defineConfig({
125
+ name: "my-app",
126
+ template: "hono",
127
+ contract: { version: "v2" },
128
+ providers: cloudflare({}),
129
+ });
130
+ ```
131
+
132
+ The selection is atomic: feature routes move to `/api/v2/*`, Better Auth moves
133
+ to `/auth/v2/*`, and generated OpenAPI, MCP tool calls, OAuth discovery,
134
+ `llms.txt`, schema/embeddings routes, and dedicated-domain `/v2/*` shortcuts
135
+ use the same version. When CMS or Account is enabled, Quickback also bakes
136
+ those paths into the SPA build and injects them at runtime, so CRUD, schema,
137
+ live-view, and authentication requests use the selected contract. Quickback
138
+ does not expose a mixed v1/v2 surface from one compiled Worker. Omitting
139
+ `contract` remains byte-compatible with v1 projects.
140
+
141
+ V2 also makes action input-schema fidelity a compile gate. The CLI must
142
+ successfully harvest `z.toJSONSchema(action.input)` for every authored action;
143
+ partial or missing harvests fail with the exact action file keys, bundle or
144
+ evaluation phase, and underlying local error. Dependencies are resolved from
145
+ the generated runtime's `build.outputDir/node_modules` before unrelated
146
+ ancestor installs, so an isolated `quickback/` definition tree can use a
147
+ sibling `src/` runtime without a workspace-root symlink. The compiler enforces
148
+ the same invariant at its shared input boundary, including
149
+ `POST /compile?complete=false`, so validation-only or raw API calls cannot
150
+ bypass it. V1 retains the historical best-effort static-schema fallback.
151
+
152
+ ## Delegated principals (contract v2)
153
+
154
+ `auth.principals` defines non-account authority such as an event pass or a
155
+ short-lived event session. It is available only with all three of:
156
+
157
+ - `contract: { version: "v2" }`
158
+ - the Cloudflare runtime
159
+ - Neon with `connectionMode: "hyperdrive"`
160
+
161
+ Each principal type owns an exact Authorization scheme. `Bearer` is reserved
162
+ for Quickback account authentication, including case variants, and two
163
+ principal types cannot share a scheme.
164
+
165
+ ```typescript
166
+ export default defineConfig({
167
+ name: "attend-v2",
168
+ template: "hono",
169
+ contract: { version: "v2" },
170
+ auth: {
171
+ principals: {
172
+ event_pass: {
173
+ scheme: "EventPass",
174
+ authenticate: {
175
+ module: "./event-pass-proof",
176
+ export: "authenticateEventPass",
177
+ },
178
+ lookup: {
179
+ table: {
180
+ module: "../features/event-access/event-access",
181
+ export: "eventAccess",
182
+ sqlName: "event_access",
183
+ },
184
+ digest: { field: "digest", column: "digest" },
185
+ actorId: { field: "personId", column: "person_id" },
186
+ claims: {
187
+ eventId: { field: "eventId", column: "event_id" },
188
+ personId: { field: "personId", column: "person_id" },
189
+ },
190
+ status: { field: "status", column: "status", allow: ["active"] },
191
+ },
192
+ },
193
+ event_delegate: {
194
+ scheme: "EventSession",
195
+ authenticate: {
196
+ module: "./event-session-proof",
197
+ export: "authenticateEventSession",
198
+ },
199
+ lookup: {
200
+ table: {
201
+ module: "../features/event-sessions/event-sessions",
202
+ export: "eventSessions",
203
+ sqlName: "event_sessions",
204
+ },
205
+ digest: { field: "digest", column: "digest" },
206
+ actorId: { field: "personId", column: "person_id" },
207
+ sessionId: { field: "id", column: "id" },
208
+ familyId: { field: "familyId", column: "family_id" },
209
+ claims: {
210
+ eventId: { field: "eventId", column: "event_id" },
211
+ personId: { field: "personId", column: "person_id" },
212
+ },
213
+ status: { field: "status", column: "status", allow: ["active"] },
214
+ },
215
+ },
216
+ },
217
+ },
218
+ providers: {
219
+ runtime: defineRuntime("cloudflare"),
220
+ database: defineDatabase("neon", {
221
+ connectionMode: "hyperdrive",
222
+ hyperdrive: { id: "<32-character-hyperdrive-id>" },
223
+ }),
224
+ auth: defineAuth("better-auth"),
225
+ },
226
+ });
227
+ ```
228
+
229
+ The `authenticate.module` path is relative to generated
230
+ `src/lib/principal-auth.ts`. Put project proof hooks under `quickback/lib`; the
231
+ compiler stages them into `src/lib` even if no action imports them. A hook has
232
+ one job: prove the presented credential and return its stable digest.
233
+
234
+ ```typescript
235
+ // quickback/lib/event-session-proof.ts
236
+ export async function authenticateEventSession({ credential, env, request }: {
237
+ credential: string;
238
+ env: Env;
239
+ request: Request;
240
+ }): Promise<{ digest: string } | null> {
241
+ const valid = await verifySignedEventSession(credential, env, request);
242
+ return valid ? { digest: await sha256(credential) } : null;
243
+ }
244
+ ```
245
+
246
+ The hook receives no `db`, and it must not implement row authorization or
247
+ business behavior. Quickback performs exactly one narrow, unique digest lookup
248
+ under a lookup-only RLS principal. A digest must be 16–512 non-whitespace
249
+ characters; resolved identity strings must be 1–512 characters and serialized
250
+ claims are limited to 4096 characters. A lookup must resolve exactly one active
251
+ row or authentication fails.
252
+
253
+ On success, actions receive `ctx.principal`:
254
+
255
+ ```typescript
256
+ {
257
+ type: "event_delegate",
258
+ actor: { type: "event_delegate", id: "person_123" },
259
+ session: { id: "session_123", familyId: "family_123" },
260
+ claims: { eventId: "event_123", personId: "person_123" },
261
+ }
262
+ ```
263
+
264
+ Quickback never synthesizes `userId`, `activeOrgId`, `activeTeamId`, or
265
+ membership roles from a delegated credential. Use `principals` in an access
266
+ arm to admit it. Values inside one arm are ANDed; sibling `or` arms are ORed:
267
+
268
+ ```typescript
269
+ access: {
270
+ or: [
271
+ { roles: ["AUTHENTICATED"] },
272
+ { principals: ["event_delegate"], record: {
273
+ eventId: { equals: "$ctx.principal.claims.eventId" },
274
+ } },
275
+ ],
276
+ }
277
+ ```
278
+
279
+ An Authorization header cannot be combined with `x-api-key` or a Better Auth
280
+ session cookie. Quickback recognizes only Better Auth's exact session cookie
281
+ names for this conflict check, so analytics and preference cookies remain
282
+ harmless.
283
+
117
284
  ## Custom Dependencies
118
285
 
119
286
  Add third-party npm packages to the generated `package.json` using `build.dependencies`. This is useful when your action handlers import external libraries.
@@ -171,6 +338,87 @@ Rules:
171
338
  - Keys must match the names in your current schema (the new names)
172
339
  - Validation fails fast for malformed rename config, unsupported keys, or conflicting legacy/new rename paths.
173
340
 
341
+ ## Neon Foreign Key Migrations
342
+
343
+ Use `compiler.migrations.foreignKeys` when a Neon relationship cannot be
344
+ expressed in one generated Drizzle schema file—for example, a feature table
345
+ that references a Better Auth table, or a composite integrity relationship
346
+ between independently authored feature modules.
347
+
348
+ ```typescript
349
+ export default defineConfig({
350
+ // ...
351
+ providers: {
352
+ runtime: defineRuntime("cloudflare"),
353
+ database: defineDatabase("neon", { connectionMode: "hyperdrive" }),
354
+ auth: defineAuth("better-auth"),
355
+ },
356
+ compiler: {
357
+ migrations: {
358
+ foreignKeys: [
359
+ {
360
+ name: "person_account_links_user_fk",
361
+ source: {
362
+ schema: "app",
363
+ table: "person_account_links",
364
+ columns: ["user_id"],
365
+ },
366
+ target: {
367
+ schema: "auth",
368
+ table: "users",
369
+ columns: ["id"],
370
+ },
371
+ onDelete: "restrict",
372
+ onUpdate: "restrict",
373
+ },
374
+ {
375
+ name: "event_access_grants_consumed_family_fk",
376
+ source: {
377
+ schema: "app",
378
+ table: "event_access_grants",
379
+ columns: [
380
+ "consumed_by_family_id",
381
+ "id",
382
+ "organization_id",
383
+ "event_id",
384
+ "event_person_id",
385
+ ],
386
+ },
387
+ target: {
388
+ schema: "app",
389
+ table: "event_session_families",
390
+ columns: [
391
+ "id",
392
+ "source_grant_id",
393
+ "organization_id",
394
+ "event_id",
395
+ "event_person_id",
396
+ ],
397
+ },
398
+ onDelete: "restrict",
399
+ onUpdate: "restrict",
400
+ },
401
+ ],
402
+ },
403
+ },
404
+ });
405
+ ```
406
+
407
+ All identifiers must be lowercase Postgres identifiers of at most 63
408
+ characters. Source and target tuples must be nonempty and have equal arity;
409
+ column order is significant. Supported actions are `"no action"`,
410
+ `"restrict"`, `"cascade"`, `"set null"`, and `"set default"`.
411
+
412
+ Constraint names and source tuples must be unique in the config. On replay,
413
+ Quickback verifies that an existing same-named constraint has the exact target,
414
+ ordered columns, and referential actions. It fails instead of silently
415
+ accepting an ambiguous definition. Existing rows are validated during
416
+ migration, so clean up orphans before deploying.
417
+
418
+ This API is for database integrity, not business behavior. Keep authorization,
419
+ state transitions, event-pass consumption, and other business rules in the API
420
+ action layer.
421
+
174
422
  ## Disable Audit Field Injection
175
423
 
176
424
  By default, Quickback auto-injects four **audit fields** (`createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`) into every feature table, plus two **soft-delete fields** (`deletedAt`, `deletedBy`) into tables that use soft delete (the default delete mode). The audit fields drive record-provenance queries and the CMS audit panel; the soft-delete pair drives soft-delete filtering.
@@ -233,8 +481,8 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
233
481
 
234
482
  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:
235
483
 
236
- - `/api/v1/*` — feature routes
237
- - `/auth/v1/*` — Better Auth
484
+ - `/api/v1/*` and `/auth/v1/*` for the default contract, or `/api/v2/*` and
485
+ `/auth/v2/*` when `contract.version` is `"v2"`
238
486
  - `/storage/*` — R2 file storage
239
487
  - `/health`, `/openapi.json` — monitoring/discovery
240
488
  - `/account/*`, `/cms/*` — bundled SPAs (when enabled)
@@ -269,19 +517,19 @@ On a dedicated hostname, **the hostname IS the namespace** — the path drops th
269
517
 
270
518
  | URL on dedicated host | Internally rewritten to | Notes |
271
519
  |---|---|---|
272
- | `https://api.example.com/v1/users` | `/api/v1/users` | Worker-entry rewriter prepends `/api` |
273
- | `https://auth.example.com/v1/sign-in/email` | `/auth/v1/sign-in/email` | Same shape with `/auth` |
274
- | `https://api.example.com/api/v1/users` | (unchanged) | Long form also accepted |
275
- | `https://api.example.com/auth/v1/sign-in` | **404** | Auth doesn't live on the API hostname |
520
+ | `https://api.example.com/{version}/users` | `/api/{version}/users` | `{version}` is the selected `v1` or `v2`; the rewriter prepends `/api` |
521
+ | `https://auth.example.com/{version}/sign-in/email` | `/auth/{version}/sign-in/email` | Same selected version with `/auth` |
522
+ | `https://api.example.com/api/{version}/users` | (unchanged) | Long form also accepted |
523
+ | `https://api.example.com/auth/{version}/sign-in` | **404** | Auth doesn't live on the API hostname |
276
524
  | `https://api.example.com/health` | (unchanged) | Explicit exception — monitoring agents expect `/health` everywhere |
277
525
 
278
526
  Dual-reach is preserved on the unified host:
279
527
 
280
528
  | URL on unified host | Handler | Notes |
281
529
  |---|---|---|
282
- | `https://quickback.example.com/api/v1/users` | feature route | Works whether `api.domain` is set or not |
283
- | `https://quickback.example.com/auth/v1/sign-in/email` | Better Auth | Works whether `auth.domain` is set or not |
284
- | `https://quickback.example.com/v1/users` | **404** | Shortcut only applies on dedicated hostnames |
530
+ | `https://quickback.example.com/api/{version}/users` | feature route | Works for the selected version whether `api.domain` is set or not |
531
+ | `https://quickback.example.com/auth/{version}/sign-in/email` | Better Auth | Works for the selected version whether `auth.domain` is set or not |
532
+ | `https://quickback.example.com/{version}/users` | **404** | Shortcut only applies on dedicated hostnames |
285
533
 
286
534
  Each dedicated hostname also:
287
535
 
@@ -464,6 +712,17 @@ For the Cloudflare provider (the default), the compiler automatically:
464
712
  - Emits `[[send_email]] EMAIL` into `wrangler.toml`
465
713
  - Generates `src/lib/cloudflare-email.ts`
466
714
  - Wires `sendResetPassword`, `sendVerificationEmail`, `sendInvitationEmail`, etc. into Better Auth
715
+ - Types the binding with Cloudflare's native `SendEmail` / `EmailSendResult`
716
+ contract (`{ email, name }`, `replyTo`, and `contentId` on Workers). The REST
717
+ helper remains a separate `{ address, name }` / `reply_to` / `content_id`
718
+ contract.
719
+ - Anchors each authentication delivery to `executionCtx.waitUntil(...)`. The
720
+ background promise records a structured generic failure and stays rejected;
721
+ outside a Worker request, the callback returns the observed promise for the
722
+ caller to await. Every Cloudflare Email callback is wired through that shared
723
+ scheduler exactly once, so no auth action can bypass failure observation or
724
+ double-schedule the send. Provider error bodies are never written to
725
+ generated logs.
467
726
 
468
727
  …whenever any auth surface needs to send mail — `emailAndPassword.enabled`, the `emailOtp` / `magicLink` / `organization` plugins — or you set the top-level `email: {…}` config. You don't need to add `bindings.sendEmail` by hand for the standard cases.
469
728
 
@@ -108,6 +108,43 @@ data/ # SQLite database files
108
108
  | Migrations | `quickback/drizzle/auth/` + `quickback/drizzle/features/` | `quickback/drizzle/` |
109
109
  | Drizzle configs | 2 configs (auth + features) | 1 config |
110
110
 
111
+ ## Generated Package Dependency Security
112
+
113
+ For projects using Better Auth, the generated `package.json` keeps the stable
114
+ `auth@1.6.x` development dependency that provides the `better-auth` executable
115
+ used by `auth:schema`. It also emits this npm override:
116
+
117
+ ```json
118
+ {
119
+ "overrides": {
120
+ "lodash": "4.18.1"
121
+ }
122
+ }
123
+ ```
124
+
125
+ The override lifts the CLI's dev-only Prisma schema-parser chain off Lodash
126
+ versions affected by the 2026 code-injection and prototype-pollution
127
+ advisories. It does not change the Better Auth runtime package or generated
128
+ authentication behavior. Quickback preserves unrelated overrides already in
129
+ your package manifest, but the compiler-owned Lodash security pin wins if an
130
+ existing override conflicts.
131
+
132
+ After recompiling, run your package manager's install command so its lockfile
133
+ records the patched transitive version. Use `npm audit --omit=dev` when
134
+ evaluating the production dependency tree; development-tool advisories are a
135
+ separate review surface.
136
+
137
+ For Better Auth projects, `quickback compile` owns auth-schema generation.
138
+ The generated `build` script runs TypeScript only and never rewrites
139
+ `src/auth/schema.ts`, so build and deployment preflight checks preserve a clean
140
+ generated worktree. `auth:schema` remains an explicit diagnostic command; run
141
+ `quickback compile` afterward to restore canonical generated bytes.
142
+
143
+ On recompilation, Quickback replaces commands for script names it generates,
144
+ including `build`, with the current compiler output. Scripts with other names
145
+ are treated as project customizations and preserved. This lets existing
146
+ projects acquire build and deployment fixes without losing unrelated tooling.
147
+
111
148
  ## Optional Output Files
112
149
 
113
150
  These files are generated only when the corresponding features are configured:
@@ -121,7 +158,7 @@ src/
121
158
  ├── lib/
122
159
  │ └── embeddings.ts # Embedding helpers
123
160
  ├── routes/
124
- │ └── embeddings.ts # POST /api/v1/embeddings endpoint
161
+ │ └── embeddings.ts # POST /api/{v1|v2}/embeddings endpoint
125
162
  └── queue-consumer.ts # Queue handler for async embedding jobs
126
163
  ```
127
164
 
@@ -264,11 +301,20 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
264
301
  | `POST /:id/{action}` | Record-based actions defined |
265
302
  | `POST /{action}` | Standalone actions defined |
266
303
 
267
- All routes are mounted under `/api/v1/{feature}` in the main app.
304
+ Routes are mounted under `/api/v1/{feature}` for the default contract or
305
+ `/api/v2/{feature}` when `contract: { version: "v2" }` is selected.
268
306
 
269
307
  ## Migrations
270
308
 
271
- The compiler runs `drizzle-kit generate` during compilation to produce SQL migration files. On subsequent compiles, it uses `existingFiles` (your current migration state) to generate only incremental changes.
309
+ The compiler runs the project-local `drizzle-kit generate` binary during compilation to produce SQL migration files. On subsequent compiles, it uses `existingFiles` (your current migration state) to generate only incremental changes.
310
+
311
+ If a compiler response returns migration generation as a post-compile command,
312
+ the command matches `build.packageManager`: `npm exec`, `pnpm exec`, `yarn exec`,
313
+ or `bun run`. These forms resolve the binary from the generated project's
314
+ dependencies. The npm form runs offline and declines npm's missing package
315
+ install prompt, so Quickback never downloads an unpinned Drizzle CLI as a
316
+ fallback. If the local binary is missing, install the generated project's
317
+ dependencies and compile again.
272
318
 
273
319
  The CLI loads migration meta JSON from one location only — `<project>/quickback/drizzle/`:
274
320
 
@@ -114,7 +114,9 @@ single Postgres database with no bindings or split mode (see
114
114
 
115
115
  | Option | Type | Default | Description |
116
116
  |--------|------|---------|-------------|
117
- | `connectionMode` | `"auto" \| "http" \| "websocket"` | `"auto"` | How the generated runtime connects (`auto` detects the runtime) |
117
+ | `connectionMode` | `"auto" \| "http" \| "websocket" \| "hyperdrive"` | `"auto"` | How the generated runtime connects (`hyperdrive` enables interactive Postgres transactions on Workers) |
118
+ | `hyperdrive.id` | `string` | — | Required Cloudflare Hyperdrive configuration ID when `connectionMode: "hyperdrive"` |
119
+ | `hyperdrive.localConnectionString` | `string` | — | Optional local-only Postgres connection used by Wrangler dev |
118
120
  | `pooled` | `boolean` | `true` | Use the pooled Neon connection string (recommended for Workers) |
119
121
 
120
122
  The Worker connects through a single `DATABASE_URL` secret — auth and feature
@@ -284,6 +286,7 @@ providers: {
284
286
  | `rateLimit.enabled` | `boolean` | Enable rate limiting |
285
287
  | `rateLimit.window` | `number` | Rate limit window in seconds |
286
288
  | `rateLimit.max` | `number` | Max requests per window |
289
+ | `atomicAuthRoutes` | `("emailOtpSignIn")[]` | Runs the exact email-OTP sign-in handler and `before-email-otp-activate.ts` admission hook in one Neon Hyperdrive transaction. Contract v2 only. |
287
290
  | `socialProviders` | `object` | Social login providers (`google`, `github`, `discord`) |
288
291
  | `debugLogs` | `boolean` | Enable auth debug logging |
289
292
 
@@ -310,6 +313,14 @@ When `features: ["organizations"]` is set in your config, the compiler automatic
310
313
  | `jwt` | JWT token support |
311
314
  | `openAPI` | OpenAPI spec generation |
312
315
 
316
+ `emailOtp` also accepts an options object. Set `expiresIn` to a positive integer
317
+ number of seconds to override Better Auth's OTP lifetime. The setting is
318
+ transport-neutral and is emitted identically for Cloudflare Email and AWS SES:
319
+
320
+ ```typescript
321
+ plugins: { emailOtp: { expiresIn: 1200 } }
322
+ ```
323
+
313
324
  ## Storage Providers
314
325
 
315
326
  ```typescript
@@ -73,6 +73,11 @@ Set these in `wrangler.toml` under `[vars]` or in the Cloudflare dashboard:
73
73
 
74
74
  Uses the Cloudflare `send_email` binding. No API keys needed — the binding is configured automatically in `wrangler.toml`.
75
75
 
76
+ Generated TypeScript uses the native Workers `SendEmail` binding and its
77
+ `EmailSendResult`; do not replace it with a hand-written `send(any)` interface.
78
+ Worker address objects use `{ email, name }`. The HTTP REST API is a different
79
+ contract and uses `{ address, name }`.
80
+
76
81
  | Variable | Description | Where |
77
82
  |----------|-------------|-------|
78
83
  | `EMAIL_FROM` | Sender email address | `[vars]` |
@@ -178,6 +178,13 @@ GET /api/v1/listings?organizationId=org_abc123
178
178
 
179
179
  The firewall WHERE clause is always enforced. If no `organizationId` is provided, the API returns a `403` with code `ORG_REQUIRED`.
180
180
 
181
+ `?organizationId=` is an account/public addressing surface. A request using a
182
+ configured delegated principal cannot use it to acquire account organization
183
+ authority: the generated route returns `403 CROSS_TENANT_FORBIDDEN` and never
184
+ adds `activeOrgId` or account roles to the delegated `AppContext`. Delegated
185
+ scope continues to come only from the verified principal claims and database
186
+ RLS policy.
187
+
181
188
  ```typescript
182
189
  // Public listing page — anyone can browse, but scoped to an org
183
190
  export default defineTable(listings, {