@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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +34 -19
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +31 -21
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +35 -4
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +233 -50
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +130 -2
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/auth.d.ts +6 -0
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js +18 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/auth.test.d.ts +2 -0
- package/dist/lib/auth.test.d.ts.map +1 -0
- package/dist/lib/auth.test.js +19 -0
- package/dist/lib/auth.test.js.map +1 -0
- package/dist/lib/compile-next-steps.d.ts +4 -0
- package/dist/lib/compile-next-steps.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.js +69 -0
- package/dist/lib/compile-next-steps.js.map +1 -0
- package/dist/lib/compile-next-steps.test.d.ts +2 -0
- package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.test.js +76 -0
- package/dist/lib/compile-next-steps.test.js.map +1 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +1 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +1 -1
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +20 -5
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.d.ts +2 -0
- package/dist/lib/file-writer.test.d.ts.map +1 -0
- package/dist/lib/file-writer.test.js +90 -0
- package/dist/lib/file-writer.test.js.map +1 -0
- package/dist/lib/shell.test.d.ts +2 -0
- package/dist/lib/shell.test.d.ts.map +1 -0
- package/dist/lib/shell.test.js +39 -0
- package/dist/lib/shell.test.js.map +1 -0
- package/dist/skill/docs/changelog.md +476 -2
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
- package/dist/skill/docs/compiler/config/auth.md +17 -2
- package/dist/skill/docs/compiler/config/index.md +271 -12
- package/dist/skill/docs/compiler/config/output.md +49 -3
- package/dist/skill/docs/compiler/config/providers.md +12 -1
- package/dist/skill/docs/compiler/config/variables.md +5 -0
- package/dist/skill/docs/compiler/definitions/access.md +7 -0
- package/dist/skill/docs/compiler/definitions/actions.md +267 -9
- package/dist/skill/docs/compiler/definitions/bundles.md +69 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
- package/dist/skill/docs/compiler/definitions/masking.md +2 -2
- package/dist/skill/docs/compiler/definitions/schema.md +12 -0
- package/dist/skill/docs/compiler/definitions/transitions.md +149 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
- package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
- package/dist/skill/docs/stack/cms/schema-format.md +4 -2
- package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
- package/dist/skill/docs/stack/realtime/durable-objects.md +17 -4
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +476 -2
- package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
- package/src/skill/docs/compiler/config/auth.md +17 -2
- package/src/skill/docs/compiler/config/index.md +271 -12
- package/src/skill/docs/compiler/config/output.md +49 -3
- package/src/skill/docs/compiler/config/providers.md +12 -1
- package/src/skill/docs/compiler/config/variables.md +5 -0
- package/src/skill/docs/compiler/definitions/access.md +7 -0
- package/src/skill/docs/compiler/definitions/actions.md +267 -9
- package/src/skill/docs/compiler/definitions/bundles.md +69 -0
- package/src/skill/docs/compiler/definitions/firewall.md +6 -1
- package/src/skill/docs/compiler/definitions/masking.md +2 -2
- package/src/skill/docs/compiler/definitions/schema.md +12 -0
- package/src/skill/docs/compiler/definitions/transitions.md +149 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
- package/src/skill/docs/stack/account-ui/hooks.md +104 -1
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
- package/src/skill/docs/stack/cms/schema-format.md +4 -2
- package/src/skill/docs/stack/cms/schema-registry.md +4 -2
- 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
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
129
|
+
## Defaults when the JWT surface is enabled
|
|
116
130
|
|
|
117
|
-
Adding
|
|
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
|
-
| `
|
|
98
|
-
| `
|
|
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/*`
|
|
237
|
-
|
|
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/
|
|
273
|
-
| `https://auth.example.com/
|
|
274
|
-
| `https://api.example.com/api/
|
|
275
|
-
| `https://api.example.com/auth/
|
|
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/
|
|
283
|
-
| `https://quickback.example.com/auth/
|
|
284
|
-
| `https://quickback.example.com/
|
|
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
|
-
|
|
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 (`
|
|
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, {
|