@quickback-dev/cli 0.51.0 → 0.51.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +34 -19
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +19 -19
- 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 +401 -1
- 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 +156 -9
- package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
- package/dist/skill/docs/compiler/definitions/schema.md +12 -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/package.json +1 -1
- package/src/skill/docs/changelog.md +401 -1
- 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 +156 -9
- package/src/skill/docs/compiler/definitions/firewall.md +6 -1
- package/src/skill/docs/compiler/definitions/schema.md +12 -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
|
@@ -2,6 +2,406 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
### Generated builds no longer rewrite the auth schema
|
|
6
|
+
|
|
7
|
+
Generated Better Auth projects now run `tsc` directly from `npm run build`.
|
|
8
|
+
`quickback compile` already generates, qualifies, and envelopes
|
|
9
|
+
`src/auth/schema.ts`; invoking `auth:schema` again during every build rewrote
|
|
10
|
+
that compiler-owned artifact and made an otherwise clean release worktree
|
|
11
|
+
dirty. The explicit `auth:schema` diagnostic command remains available, while
|
|
12
|
+
normal build, Wrangler, and deployment preflight paths are source-read-only.
|
|
13
|
+
When recompiling an existing project, compiler-owned `package.json` script
|
|
14
|
+
names now converge to their current generated commands while unrelated custom
|
|
15
|
+
scripts are preserved. This upgrades projects whose previous generated
|
|
16
|
+
`build` script still invoked `auth:schema`.
|
|
17
|
+
|
|
18
|
+
### Non-cross-tenant unsafe actions preserve delegated RLS claims
|
|
19
|
+
|
|
20
|
+
Generated Neon handlers now reserve `createServiceDb` for actions that
|
|
21
|
+
explicitly enable `unsafe.crossTenant`. An action that enables raw database
|
|
22
|
+
access with `crossTenant: false` keeps the request database, so organization
|
|
23
|
+
and delegated-principal claims survive into Hyperdrive transactions instead of
|
|
24
|
+
being cleared by the service-role preamble. True cross-tenant sysadmin actions
|
|
25
|
+
retain their audited RLS bypass.
|
|
26
|
+
|
|
27
|
+
Neon Hyperdrive guidance now also calls out Postgres' `SELECT … FOR UPDATE`
|
|
28
|
+
authorization rule: a locked row must pass both `SELECT` and `UPDATE` policies.
|
|
29
|
+
Delegated actions should use ordinary selects for read-only eligibility tables
|
|
30
|
+
and lock only mutable rows they are authorized to update. A PGlite regression
|
|
31
|
+
proves that ordinary delegated reads remain visible while the generated
|
|
32
|
+
restrictive update fence blocks an unauthorized row lock.
|
|
33
|
+
|
|
34
|
+
### Atomic email-OTP auth routing no longer recurses on ordinary requests
|
|
35
|
+
|
|
36
|
+
The generated atomic email-OTP wrapper now captures and binds Better Auth's
|
|
37
|
+
original request handler before replacing the public `handler` property.
|
|
38
|
+
Session reads and every other non-atomic auth route therefore forward to Better
|
|
39
|
+
Auth exactly once instead of re-entering the wrapper until the Worker exhausts
|
|
40
|
+
its call stack. The exact email-OTP sign-in route retains its transactional
|
|
41
|
+
admission and rollback behavior.
|
|
42
|
+
|
|
43
|
+
### Generated Better Auth CLI dependencies no longer retain vulnerable Lodash
|
|
44
|
+
|
|
45
|
+
Better Auth projects now emit a root npm override for `lodash@4.18.1`. This
|
|
46
|
+
keeps the supported stable `auth@1.6.x` CLI and its `better-auth` executable,
|
|
47
|
+
while lifting the CLI's dev-only Prisma parser chain off Lodash releases
|
|
48
|
+
affected by the 2026 code-injection and prototype-pollution advisories. Runtime
|
|
49
|
+
Better Auth packages and generated authentication behavior are unchanged.
|
|
50
|
+
|
|
51
|
+
The CLI now merges generated npm overrides explicitly when recompiling an
|
|
52
|
+
existing project: unrelated user overrides remain, while compiler-owned
|
|
53
|
+
security pins win a conflict. Recompile and reinstall dependencies to refresh
|
|
54
|
+
the project lockfile. `npm audit --omit=dev` remains the production dependency
|
|
55
|
+
view; upstream development-server advisories may still appear separately.
|
|
56
|
+
|
|
57
|
+
### Postgres constraint replacements apply in dependency-safe order
|
|
58
|
+
|
|
59
|
+
Neon migration post-processing now orders both halves of a Drizzle constraint
|
|
60
|
+
replacement. A dependent foreign key is dropped before its referenced unique
|
|
61
|
+
or primary-key constraint, then the replacement key is added before the
|
|
62
|
+
foreign key that consumes it. This prevents Postgres `2BP01` failures when
|
|
63
|
+
Drizzle emits the parent key drop first, while preserving byte-identical output
|
|
64
|
+
for already-correct migrations and the relative order of unrelated statements.
|
|
65
|
+
|
|
66
|
+
### Schema registry output is byte-reproducible
|
|
67
|
+
|
|
68
|
+
`schema-registry.json` no longer includes the wall-clock `generatedAt` field.
|
|
69
|
+
Its remaining metadata and schema content are derived entirely from compiler
|
|
70
|
+
inputs, so consecutive compiles of identical logical input now produce the
|
|
71
|
+
same registry bytes. This makes artifact hashes, caches, and deployment diffs
|
|
72
|
+
stable without timestamp normalization.
|
|
73
|
+
|
|
74
|
+
### Generated auth and discovery surfaces now remain truthful and type-safe
|
|
75
|
+
|
|
76
|
+
Atomic email-OTP generation now imports and invokes
|
|
77
|
+
`before-email-otp-activate.ts` exactly once and preserves the transaction's
|
|
78
|
+
real Drizzle `select` capability in the hook context. Strict generated
|
|
79
|
+
TypeScript therefore accepts both the base Neon service database and its
|
|
80
|
+
interactive transaction without erasing the hook's read contract.
|
|
81
|
+
|
|
82
|
+
Contract-v2 projects that omit `auth.jwt` no longer advertise the disabled
|
|
83
|
+
Quickback JWT fast path in `llms.txt` or RFC 8414 metadata. Bearer-JWT guidance,
|
|
84
|
+
the fallback `/api/v2/token` endpoint, and JWT scopes are emitted only when the
|
|
85
|
+
corresponding JWT surface exists; real Better Auth OAuth-provider discovery is
|
|
86
|
+
unchanged.
|
|
87
|
+
|
|
88
|
+
Cloudflare Email callbacks now all enter the shared credential-delivery
|
|
89
|
+
scheduler exactly once. The scheduler anchors the observed rejection with
|
|
90
|
+
`waitUntil`, emits the metadata-only `auth.credential_delivery_failed` event,
|
|
91
|
+
and never leaks the provider error. Generated CRUD routes also keep delegated
|
|
92
|
+
principal and account authority disjoint: `?organizationId=` is rejected for a
|
|
93
|
+
delegated principal instead of synthesizing `activeOrgId` on its context. This
|
|
94
|
+
closes both the authority ambiguity and the generated `AppContext` union type
|
|
95
|
+
errors.
|
|
96
|
+
|
|
97
|
+
### Email-OTP activation can be admitted atomically in the API layer
|
|
98
|
+
|
|
99
|
+
Contract-v2 Cloudflare projects using one Neon Hyperdrive database can opt the
|
|
100
|
+
exact Better Auth `POST /sign-in/email-otp` handler into an interactive
|
|
101
|
+
transaction with `atomicAuthRoutes: ["emailOtpSignIn"]`. The paired recognized
|
|
102
|
+
hook, `quickback/hooks/before-email-otp-activate.ts`, receives a proven dormant
|
|
103
|
+
user `{ userId, email, user }` plus transaction-bound `db` / full `schema` and
|
|
104
|
+
`authDb` / `authSchema` handles. Quickback owns only identity proof and atomic
|
|
105
|
+
orchestration; application admission, status, event, pass, and eligibility
|
|
106
|
+
rules remain authored in the project API hook.
|
|
107
|
+
|
|
108
|
+
The hook executes after OTP validation but in Better Auth's
|
|
109
|
+
`databaseHooks.user.update.before`, before the user update lock. This preserves
|
|
110
|
+
application-first lock ordering and avoids the user-to-application inversion a
|
|
111
|
+
session-create hook would introduce. Unknown-email signup must be disabled;
|
|
112
|
+
already-verified users do not rerun dormant activation.
|
|
113
|
+
|
|
114
|
+
The generated handler rebuilds Better Auth over the transaction handle, so OTP
|
|
115
|
+
consumption, project hook writes, the `emailVerified` update, and session insert
|
|
116
|
+
commit together. Admission denial, a non-ok response after activation starts,
|
|
117
|
+
and any 5xx response throw a private rollback sentinel. Expected policy denial
|
|
118
|
+
returns a generic 403. Operational rollback emits the metadata-only
|
|
119
|
+
`auth.atomic_email_otp_operational_rollback` event and returns a generic 503,
|
|
120
|
+
without exposing raw errors. Ordinary invalid-OTP 4xx responses still commit
|
|
121
|
+
Better Auth's attempt accounting, and the OTP-send route remains outside the
|
|
122
|
+
transaction. Unsupported contracts, runtimes, database modes,
|
|
123
|
+
missing/duplicated config, enabled signup,
|
|
124
|
+
and a hook/config mismatch now fail at compile time.
|
|
125
|
+
|
|
126
|
+
### Neon migrations can declare cross-schema foreign keys
|
|
127
|
+
|
|
128
|
+
Neon projects can now declare fully qualified, single-column or composite
|
|
129
|
+
foreign keys under `compiler.migrations.foreignKeys`. Each entry names the
|
|
130
|
+
constraint, source and target schema/table/column tuples, and explicit
|
|
131
|
+
`onDelete` / `onUpdate` actions. The compiler rejects unsafe identifiers,
|
|
132
|
+
mismatched tuple arity, duplicate or ambiguous declarations, unknown keys,
|
|
133
|
+
and non-Neon providers before generating SQL.
|
|
134
|
+
|
|
135
|
+
Declared constraints are sorted deterministically and folded into Quickback's
|
|
136
|
+
content-addressed Postgres journal after the Drizzle schema migration. A new
|
|
137
|
+
constraint is added `NOT VALID` and then validated, so existing orphan rows
|
|
138
|
+
fail the migration; replay verifies an exact catalog match and rejects a
|
|
139
|
+
same-named constraint with different semantics. This surface enforces
|
|
140
|
+
relational integrity only—business rules remain in generated or authored API
|
|
141
|
+
actions, not database triggers.
|
|
142
|
+
|
|
143
|
+
### Compile completion steps honor the Neon connection mode
|
|
144
|
+
|
|
145
|
+
The CLI's successful-compile footer now distinguishes Neon HTTP from
|
|
146
|
+
Hyperdrive. HTTP projects retain the direct `DATABASE_URL` Worker setup.
|
|
147
|
+
Hyperdrive projects show `DATABASE_MIGRATION_URL` only as a local or CI
|
|
148
|
+
migration input, point local development at the configured Hyperdrive
|
|
149
|
+
`localConnectionString`, and never recommend deploying `DATABASE_URL` as a
|
|
150
|
+
Worker secret.
|
|
151
|
+
|
|
152
|
+
Named Hyperdrive environments also show their configured Neon branches,
|
|
153
|
+
required-secret inventories, and explicit Wrangler `--env` targets. The footer
|
|
154
|
+
no longer suggests the unnamed `.env.neon` / `.dev.vars` workflow or a bare
|
|
155
|
+
deploy for an isolated `dev` / `prod` setup.
|
|
156
|
+
|
|
157
|
+
### Cloudflare email delivery and named Neon targets fail visibly and deploy explicitly
|
|
158
|
+
|
|
159
|
+
Generated Cloudflare email code now uses the native Workers `SendEmail`,
|
|
160
|
+
`EmailAddress`, attachment, and `EmailSendResult` contracts. The Workers
|
|
161
|
+
builder keeps its camel-case fields and `{ email, name }` address shape, while
|
|
162
|
+
the REST transport retains its separate snake-case fields and `{ address,
|
|
163
|
+
name }` shape. Generated projects move to `@cloudflare/workers-types` v5 with
|
|
164
|
+
Wrangler 4.110 so the binding and result types agree without `any` casts.
|
|
165
|
+
|
|
166
|
+
Every Better Auth email callback now creates an observed delivery promise. On
|
|
167
|
+
Workers, the callback hands that still-rejecting promise to
|
|
168
|
+
`executionCtx.waitUntil(...)` and returns after the task is accepted; outside a
|
|
169
|
+
request lifecycle it returns the promise for the caller to await. Failures emit
|
|
170
|
+
only a structured generic event, never provider error content, and remain
|
|
171
|
+
rejected instead of being detached or swallowed. SES and SNS background sends
|
|
172
|
+
use the same lifecycle rule.
|
|
173
|
+
|
|
174
|
+
Neon Hyperdrive's generated postgres.js client now caps each request-scoped
|
|
175
|
+
pool at five connections. Named environments gain explicit `deploy:dev` and
|
|
176
|
+
`deploy:prod` package scripts (mapped to their configured Wrangler environment
|
|
177
|
+
names), while the unsafe bare `deploy` script remains absent and migrations
|
|
178
|
+
remain a separate target-owned step.
|
|
179
|
+
|
|
180
|
+
### Contract v2 auth and Neon authority boundaries are fail-closed
|
|
181
|
+
|
|
182
|
+
Contract-v2 projects no longer emit Quickback's generic JWT mint endpoint,
|
|
183
|
+
JWT helper, middleware verification/mint fast-path, or related imports unless
|
|
184
|
+
the project explicitly declares `auth.jwt`. Contract v1 retains its existing
|
|
185
|
+
default for compatibility. Adding `auth.jwt: {}` to a v2 config opts back into
|
|
186
|
+
the custom Quickback JWT with its normal default settings.
|
|
187
|
+
|
|
188
|
+
Configured delegated authenticators now produce closed TypeScript unions in
|
|
189
|
+
both generated `AppContext` and Neon RLS context. Request contexts contain only
|
|
190
|
+
resolved principal variants; the compiler-internal credential-lookup variants
|
|
191
|
+
exist only in the database context. Delegated standalone actions do not require
|
|
192
|
+
Better Auth `activeOrgId` / `activeTeamId` before their declared principal
|
|
193
|
+
access tree runs, and their context cannot acquire account, organization, team,
|
|
194
|
+
membership, or scope authority.
|
|
195
|
+
|
|
196
|
+
On Cloudflare + Neon, the API-key organization membership lookup now runs with
|
|
197
|
+
request-scoped user/org RLS claims before it stamps verified organization and
|
|
198
|
+
role authority into `AppContext`. Generated security migrations also converge
|
|
199
|
+
direct privilege drift: the audit schema/table revoke all direct grants from
|
|
200
|
+
`PUBLIC`, the runtime, and admin before restoring their exact write-only/admin
|
|
201
|
+
sets, while the Drizzle journal schema/table/sequences and database `CREATE`
|
|
202
|
+
capability explicitly revoke `PUBLIC` and runtime access before granting the
|
|
203
|
+
migration role.
|
|
204
|
+
|
|
205
|
+
### Standalone action routes preserve their exact authority context
|
|
206
|
+
|
|
207
|
+
Generated standalone routes now pass each action the context and scoped
|
|
208
|
+
database types inferred from that action's own `execute` signature. Account actions therefore receive a
|
|
209
|
+
required account identity, while `event_pass`, `event_delegate`, and other
|
|
210
|
+
delegated-principal actions retain their exact principal literal at the route
|
|
211
|
+
boundary. Relationship `loads` / `exposeAs` hydration is intersected with that
|
|
212
|
+
authority context, including required shared targets and optional distinct
|
|
213
|
+
multi-lane targets, instead of replacing it with the broad application
|
|
214
|
+
context.
|
|
215
|
+
|
|
216
|
+
The same boundary keeps ordinary request databases and temporary
|
|
217
|
+
service-role-backed scoped databases assignable to the generated Hyperdrive
|
|
218
|
+
action helper without widening the handler's schema-aware `db` type.
|
|
219
|
+
|
|
220
|
+
Generated principal-auth identity guards also emit explicit strict TypeScript
|
|
221
|
+
parameter and return types. Contract-v2 Cloudflare + Neon output no longer
|
|
222
|
+
fails `tsc` on implicit-`any` guard parameters.
|
|
223
|
+
|
|
224
|
+
### Parameterized actions keep complete v2 schema harvests
|
|
225
|
+
|
|
226
|
+
The action-input harvest plan now converts Hono-style `:param` segments to the
|
|
227
|
+
OpenAPI `{param}` form for standalone actions and parameterized resource paths.
|
|
228
|
+
Previously the CLI could harvest every schema successfully, but the compiler
|
|
229
|
+
could apply only parameter-free actions because it looked up parameterized
|
|
230
|
+
operations under the wrong OpenAPI key. Contract v2 now counts and patches the
|
|
231
|
+
same canonical path emitted by OpenAPI and MCP.
|
|
232
|
+
|
|
233
|
+
Generated standalone-action routes also remove template-only trailing spaces
|
|
234
|
+
when optional audit blocks are absent, keeping regenerated source diffs clean.
|
|
235
|
+
|
|
236
|
+
### Action-schema harvest uses the generated runtime dependency tree
|
|
237
|
+
|
|
238
|
+
The CLI now resolves action-harvest dependencies from the configured
|
|
239
|
+
`build.outputDir/node_modules` before unrelated ancestor installs. This fixes
|
|
240
|
+
isolated projects that keep authored definitions under `quickback/` and the
|
|
241
|
+
generated runtime under a sibling directory such as `src/`: their actions can
|
|
242
|
+
use the runtime's Zod 4 and Drizzle installation without adding workspace-root
|
|
243
|
+
symlinks. An older user-level or monorepo-level Zod can no longer shadow the
|
|
244
|
+
runtime's declared version during schema evaluation.
|
|
245
|
+
|
|
246
|
+
Schema-only evaluation also emits inert named table proxies for authored
|
|
247
|
+
Drizzle exports. Shared input/DTO modules may therefore construct top-level
|
|
248
|
+
selection objects such as `{ id: records.id }` without executing a database
|
|
249
|
+
operation or losing the action's Zod schema.
|
|
250
|
+
|
|
251
|
+
Harvest failures now retain the exact action key, failing phase (`bundle` or
|
|
252
|
+
`evaluation`), and bounded underlying error. Contract v2 includes those
|
|
253
|
+
per-action diagnostics in its fail-closed compile error; v1 retains its
|
|
254
|
+
best-effort static-schema fallback.
|
|
255
|
+
|
|
256
|
+
### Contract v2 delegated principals and RLS-only action tables
|
|
257
|
+
|
|
258
|
+
Cloudflare + Neon Hyperdrive projects on `contract.version: "v2"` can now
|
|
259
|
+
declare framework-generic delegated authenticators under `auth.principals`.
|
|
260
|
+
Each named principal owns an exact, non-`Bearer` Authorization scheme, a
|
|
261
|
+
project hook that proves the credential and returns only `{ digest }`, and one
|
|
262
|
+
compiler-owned indexed lookup that resolves the actor, optional session/family,
|
|
263
|
+
string claims, and active status. The hook receives no database handle. Proof
|
|
264
|
+
hooks authored under `quickback/lib` are staged into generated `src/lib`, even
|
|
265
|
+
when no action imports them directly.
|
|
266
|
+
|
|
267
|
+
Delegated authority is structurally disjoint from Better Auth accounts:
|
|
268
|
+
`ctx.principal` is populated while user, organization, team, and membership
|
|
269
|
+
fields remain absent. Access arms may use `principals: [...]`; fields inside an
|
|
270
|
+
arm are ANDed and sibling arms are ORed. Generated action helpers preserve
|
|
271
|
+
that boundary in TypeScript, including the anonymous possibility of a
|
|
272
|
+
`PUBLIC` sibling arm. Mixed credential transport rejects Authorization plus an
|
|
273
|
+
API key or an actual Better Auth session cookie, while unrelated analytics
|
|
274
|
+
cookies do not create a false conflict. `Bearer` remains reserved for account
|
|
275
|
+
authentication.
|
|
276
|
+
|
|
277
|
+
Resources can also declare operation-specific `databaseAccess` policies for
|
|
278
|
+
authored actions and support tables. This is an RLS-only surface: it emits no
|
|
279
|
+
generic route or OpenAPI operation and is accepted only on Cloudflare + Neon
|
|
280
|
+
Hyperdrive. Every authorization path must contain a nonempty SQL-lowerable
|
|
281
|
+
record equality; unbounded principal/role leaves, any unbounded OR arm, empty
|
|
282
|
+
records, ambiguous mixed boolean nodes, app-only predicates, and unsupported
|
|
283
|
+
providers fail compilation. This keeps business logic in authored API actions
|
|
284
|
+
while Postgres independently enforces the same event/person or account/org row
|
|
285
|
+
boundary.
|
|
286
|
+
|
|
287
|
+
Principal claims use the same transaction-local Hyperdrive preamble as account
|
|
288
|
+
claims, with query caching disabled. Restrictive per-operation principal
|
|
289
|
+
fences prevent a public, exception, or legacy permissive policy from admitting
|
|
290
|
+
the wrong principal type. Credential lookup indexes and RLS journal entries are
|
|
291
|
+
content-addressed and converge when a table, digest column, or definition
|
|
292
|
+
changes; generated Postgres identifiers include collision-resistant hashes and
|
|
293
|
+
stay within the 63-byte limit. Each security migration also drops the complete
|
|
294
|
+
compiler-owned `databaseAccess` policy family before recreating the current
|
|
295
|
+
operations, so removing or moving an operation revokes the old permissive
|
|
296
|
+
policy instead of leaving it active. Record fields resolve through authoritative
|
|
297
|
+
Drizzle metadata to exact quoted physical identifiers, unknown fields fail the
|
|
298
|
+
compile, and DB-only pseudo-roles follow the same ADMIN/SYSADMIN/INTERNAL
|
|
299
|
+
contract as the application surface.
|
|
300
|
+
|
|
301
|
+
### Action execute helpers preserve their typed boundary
|
|
302
|
+
|
|
303
|
+
Generated per-feature `defineAction` helpers no longer erase `services`, the
|
|
304
|
+
Hono request context, record predicates, or the action's return value to
|
|
305
|
+
`any`. Zod input and record inference remain intact, `whereRecord` and
|
|
306
|
+
`whereTransition` accept only the helper's bound table, and the existing D1 /
|
|
307
|
+
Neon Hyperdrive scoped `db` and interactive `tx` types now flow through the
|
|
308
|
+
same execute boundary. The returned value is inferred exactly; this does not
|
|
309
|
+
add a response schema, invalid-return rule, or new output contract.
|
|
310
|
+
|
|
311
|
+
HTTP/WebSocket Neon retains its intentionally dynamic `db`, and `AppContext`
|
|
312
|
+
retains its open index signature for runtime-hydrated namespace fields.
|
|
313
|
+
|
|
314
|
+
### Neon Hyperdrive is now the only Worker database lane, including Better Auth
|
|
315
|
+
|
|
316
|
+
For `connectionMode: "hyperdrive"`, generated Better Auth code now uses the
|
|
317
|
+
same HYPERDRIVE-backed, service-role-scoped database handle as the rest of the
|
|
318
|
+
generated API. `DATABASE_URL` is no longer emitted or required as a Worker
|
|
319
|
+
secret in Hyperdrive mode; migration credentials remain inputs to the compiler
|
|
320
|
+
or CI environment. HTTP-mode Neon retains its existing `DATABASE_URL` runtime
|
|
321
|
+
contract.
|
|
322
|
+
|
|
323
|
+
### Public contract v2 now compiles as one coherent API/auth surface
|
|
324
|
+
|
|
325
|
+
Projects may set `contract: { version: "v2" }` to select `/api/v2/*` feature
|
|
326
|
+
routes and `/auth/v2/*` Better Auth routes. The compiler now threads that
|
|
327
|
+
selection through generated route mounts, Better Auth configuration and
|
|
328
|
+
middleware, OpenAPI paths and server metadata, MCP internal tool calls, OAuth
|
|
329
|
+
discovery, `llms.txt`, schema/embeddings/system routes, live views, namespace
|
|
330
|
+
actions, and dedicated-domain `/v2/*` shortcuts. The option is no longer
|
|
331
|
+
fail-closed. Omitting `contract` or selecting `v1` preserves the existing v1
|
|
332
|
+
output.
|
|
333
|
+
|
|
334
|
+
Bundled CMS and Account clients now receive the selected API and auth base
|
|
335
|
+
paths through both their Vite build environment and the Worker-injected runtime
|
|
336
|
+
config. CMS CRUD, schema, sysadmin, and live-view requests and Account auth,
|
|
337
|
+
data, and live-view requests therefore stay on `/api/v2` and `/auth/v2` for a
|
|
338
|
+
v2 project instead of falling back to client-side v1 literals. V1 SPA config
|
|
339
|
+
retains its historical byte shape.
|
|
340
|
+
|
|
341
|
+
V2 compiles also require a complete client-side action input-schema harvest.
|
|
342
|
+
The current CLI reports the exact action files that failed to produce a JSON
|
|
343
|
+
Schema, and the compiler independently rejects missing, invalid, or partial
|
|
344
|
+
maps at the shared parse boundary used by both complete and validation-only
|
|
345
|
+
compiles. `POST /compile?complete=false` can no longer bypass the v2 gate. For
|
|
346
|
+
record actions with `bulkVariant: true`, the harvested schema now patches both
|
|
347
|
+
the single-record request body and the bulk operation's nested `input`; the
|
|
348
|
+
action is counted complete only when both OpenAPI targets exist. Harvest
|
|
349
|
+
planning also normalizes filename-based action bindings to the table's declared
|
|
350
|
+
name and resource path, so kebab-case filenames exporting snake/camel-case
|
|
351
|
+
tables are not silently omitted. V1 remains best-effort for backward
|
|
352
|
+
compatibility.
|
|
353
|
+
|
|
354
|
+
### Complete, isolated Wrangler targets for named Neon environments
|
|
355
|
+
|
|
356
|
+
`providers.database.environments` now defines deployable Neon Hyperdrive
|
|
357
|
+
targets instead of emitting empty `[env.*]` shells. Because Wrangler does not
|
|
358
|
+
inherit vars or bindings into named environments, each target must explicitly
|
|
359
|
+
own its generated vars, required-secret contract, Hyperdrive and KV IDs,
|
|
360
|
+
rate-limit namespace IDs, and Cloudflare Email binding. The compiler rejects
|
|
361
|
+
missing overrides, shared stateful IDs, optional secret declarations, invalid
|
|
362
|
+
target semantics, and unsupported binding families rather than generating a
|
|
363
|
+
Worker that starts without part of its runtime.
|
|
364
|
+
|
|
365
|
+
The required-secret inventory is now centralized and includes generated
|
|
366
|
+
credentials as well as custom declarations: `BETTER_AUTH_SECRET`, a configured
|
|
367
|
+
`auth.jwt.secretEnv`, `ENCRYPTION_KEK` when envelope encryption is present, and
|
|
368
|
+
every `bindings.secrets` entry marked `required`. Generated Better Auth SES/SNS
|
|
369
|
+
credentials, AWS-backed anonymous-upgrade credentials, enabled social-provider
|
|
370
|
+
client id/secret pairs, and R2 presign credential env names are included as
|
|
371
|
+
well. Cloudflare social auth now reads those credentials from the Worker `env`
|
|
372
|
+
binding instead of relying on `process.env` compatibility behavior. Named
|
|
373
|
+
targets also reject every generated top-level custom-domain source — including
|
|
374
|
+
runtime routes, the primary/CMS/Account/Admin/Auth/API domains, and app domains
|
|
375
|
+
or aliases — until routes can be declared with explicit per-environment
|
|
376
|
+
ownership; top-level routes can no longer produce an ambiguous deployment
|
|
377
|
+
target.
|
|
378
|
+
|
|
379
|
+
Named targets are currently limited to Neon Hyperdrive with Better Auth.
|
|
380
|
+
External auth remains fail-closed until its service binding can be declared
|
|
381
|
+
independently for every named environment.
|
|
382
|
+
|
|
383
|
+
For named-environment projects, the base Worker has no deployable stateful
|
|
384
|
+
bindings, local development selects a named target, and that selected target
|
|
385
|
+
is always the required logical `dev` environment, which must own an explicit
|
|
386
|
+
development-only Hyperdrive `localConnectionString`. Quickback emits it only
|
|
387
|
+
in the selected named binding, rejects a top-level
|
|
388
|
+
override when named environments exist, and rejects local URLs on staging or
|
|
389
|
+
production targets; deployed targets continue to resolve the remote
|
|
390
|
+
Hyperdrive configuration by ID. The generated package omits the unsafe bare
|
|
391
|
+
deploy script. Existing projects that omit
|
|
392
|
+
`environments` keep byte-identical Wrangler output and the existing dev/deploy
|
|
393
|
+
scripts. See [Neon → Named Cloudflare deployment environments](/compiler/targets/hono-api/database/neon#named-cloudflare-deployment-environments).
|
|
394
|
+
|
|
395
|
+
### Local compiler trust boundary and deterministic Drizzle commands
|
|
396
|
+
|
|
397
|
+
The supported Docker launcher now opts into unauthenticated local compilation
|
|
398
|
+
explicitly and publishes the compiler only on `127.0.0.1`; missing or unknown
|
|
399
|
+
compiler modes retain hosted authentication. The CLI recognizes only exact
|
|
400
|
+
loopback hostnames as local. Migration post-commands now use the configured
|
|
401
|
+
package manager's local binary execution form, with npm forced offline and its
|
|
402
|
+
implicit install prompt disabled, so a missing `drizzle-kit` fails clearly
|
|
403
|
+
instead of fetching an unpinned package.
|
|
404
|
+
|
|
5
405
|
### Action rate limits now emit — documented since the rate-limit pillar, wired now
|
|
6
406
|
|
|
7
407
|
The [rate-limit docs](/compiler/definitions/rate-limit#actions) have described
|
|
@@ -40,7 +440,7 @@ The generated `auth:schema` script runs `npx better-auth generate`, but the
|
|
|
40
440
|
lives in the npm package `auth` (the official Better Auth CLI; the team took
|
|
41
441
|
over that name at 1.5.0, superseding the frozen `@better-auth/cli`). Generated
|
|
42
442
|
projects now declare `auth` as a devDependency pinned to the runtime's minor
|
|
43
|
-
line, so `npm run
|
|
443
|
+
line, so `npm run auth:schema` resolves the CLI locally instead of requiring a
|
|
44
444
|
global install. The compiler image's global CLI is pinned to the same version,
|
|
45
445
|
eliminating silent skew between the CLI on `latest` and the pinned runtime.
|
|
46
446
|
|
|
@@ -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
|
|---|---|
|