@quickback-dev/cli 0.70.31 → 0.70.40
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/build.d.ts +12 -0
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +69 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/deploy.d.ts +9 -0
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +20 -2
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/migrate-data.d.ts +12 -0
- package/dist/commands/migrate-data.d.ts.map +1 -0
- package/dist/commands/migrate-data.js +134 -0
- package/dist/commands/migrate-data.js.map +1 -0
- package/dist/commands/migrate.d.ts.map +1 -1
- package/dist/commands/migrate.js +11 -0
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/secrets.d.ts +27 -0
- package/dist/commands/secrets.d.ts.map +1 -0
- package/dist/commands/secrets.js +186 -0
- package/dist/commands/secrets.js.map +1 -0
- package/dist/index.js +23 -3
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +87 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -0
- package/dist/lib/access-manifest-diff.js +331 -0
- package/dist/lib/access-manifest-diff.js.map +1 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +3 -0
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/compiler-stubs.d.ts +2 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +2 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/file-loader.d.ts +6 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +17 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/ops-manifest.d.ts +76 -0
- package/dist/lib/ops-manifest.d.ts.map +1 -0
- package/dist/lib/ops-manifest.js +94 -0
- package/dist/lib/ops-manifest.js.map +1 -0
- package/dist/lib/release-and-pin.d.ts +34 -0
- package/dist/lib/release-and-pin.d.ts.map +1 -0
- package/dist/lib/release-and-pin.js +71 -0
- package/dist/lib/release-and-pin.js.map +1 -0
- package/dist/lib/shell.d.ts +4 -1
- package/dist/lib/shell.d.ts.map +1 -1
- package/dist/lib/shell.js +8 -3
- package/dist/lib/shell.js.map +1 -1
- package/dist/skill/docs/api/actions.md +2 -0
- package/dist/skill/docs/api/batch-operations.md +18 -4
- package/dist/skill/docs/api/crud.md +62 -0
- package/dist/skill/docs/api/errors.md +17 -2
- package/dist/skill/docs/configure/auth.md +49 -2
- package/dist/skill/docs/configure/bindings.md +15 -0
- package/dist/skill/docs/configure/domains.md +4 -0
- package/dist/skill/docs/configure/index.md +29 -11
- package/dist/skill/docs/configure/tenancy.md +117 -0
- package/dist/skill/docs/define/access.md +19 -0
- package/dist/skill/docs/define/actions/access.md +76 -0
- package/dist/skill/docs/define/actions/defining.md +156 -1
- package/dist/skill/docs/define/actions/scoped-db.md +236 -9
- package/dist/skill/docs/define/areas.md +46 -0
- package/dist/skill/docs/define/authz-roles.md +10 -0
- package/dist/skill/docs/define/diagnostics.md +263 -0
- package/dist/skill/docs/define/encryption.md +32 -0
- package/dist/skill/docs/define/guards.md +13 -0
- package/dist/skill/docs/define/masking.md +77 -3
- package/dist/skill/docs/define/rate-limit.md +3 -3
- package/dist/skill/docs/define/schema.md +148 -7
- package/dist/skill/docs/define/scopes.md +79 -0
- package/dist/skill/docs/define/transitions.md +39 -0
- package/dist/skill/docs/define/views.md +77 -3
- package/dist/skill/docs/platform/api-contract/index.md +4 -0
- package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/dist/skill/docs/platform/auth/using-auth.md +6 -0
- package/dist/skill/docs/platform/database/d1.md +47 -0
- package/dist/skill/docs/platform/database/data-migrations.md +109 -0
- package/dist/skill/docs/platform/database/read-replication.md +142 -7
- package/dist/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/dist/skill/docs/platform/push/index.md +2 -0
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/dist/skill/docs/platform/storage/using-r2.md +135 -19
- package/dist/skill/docs/start/deploy.md +38 -0
- package/dist/skill/docs/tooling/cli.md +120 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/dist/skill/docs/tooling/output.md +70 -2
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +2 -0
- package/src/skill/docs/api/batch-operations.md +18 -4
- package/src/skill/docs/api/crud.md +62 -0
- package/src/skill/docs/api/errors.md +17 -2
- package/src/skill/docs/configure/auth.md +49 -2
- package/src/skill/docs/configure/bindings.md +15 -0
- package/src/skill/docs/configure/domains.md +4 -0
- package/src/skill/docs/configure/index.md +29 -11
- package/src/skill/docs/configure/tenancy.md +117 -0
- package/src/skill/docs/define/access.md +19 -0
- package/src/skill/docs/define/actions/access.md +76 -0
- package/src/skill/docs/define/actions/defining.md +156 -1
- package/src/skill/docs/define/actions/scoped-db.md +236 -9
- package/src/skill/docs/define/areas.md +46 -0
- package/src/skill/docs/define/authz-roles.md +10 -0
- package/src/skill/docs/define/diagnostics.md +263 -0
- package/src/skill/docs/define/encryption.md +32 -0
- package/src/skill/docs/define/guards.md +13 -0
- package/src/skill/docs/define/masking.md +77 -3
- package/src/skill/docs/define/rate-limit.md +3 -3
- package/src/skill/docs/define/schema.md +148 -7
- package/src/skill/docs/define/scopes.md +79 -0
- package/src/skill/docs/define/transitions.md +39 -0
- package/src/skill/docs/define/views.md +77 -3
- package/src/skill/docs/platform/api-contract/index.md +4 -0
- package/src/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/src/skill/docs/platform/auth/using-auth.md +6 -0
- package/src/skill/docs/platform/database/d1.md +47 -0
- package/src/skill/docs/platform/database/data-migrations.md +109 -0
- package/src/skill/docs/platform/database/read-replication.md +142 -7
- package/src/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/src/skill/docs/platform/push/index.md +2 -0
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/src/skill/docs/platform/storage/using-r2.md +135 -19
- package/src/skill/docs/start/deploy.md +38 -0
- package/src/skill/docs/tooling/cli.md +120 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/src/skill/docs/tooling/output.md +70 -2
|
@@ -81,41 +81,157 @@ https://files.yourdomain.com/public/org_abc/listings/3f2a9c…-hero.jpg
|
|
|
81
81
|
|
|
82
82
|
## Signed upload (large or confidential files)
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
|
|
84
|
+
Declare the key column as `q.storageKey(...)` and let `db.allocateUpload`
|
|
85
|
+
write it. Bytes go directly to R2 — the Worker only signs. The client never
|
|
86
|
+
names the key, so it can't point a row at another tenant's object.
|
|
87
|
+
|
|
88
|
+
```ts title="quickback/quickback.config.ts"
|
|
89
|
+
import { defineConfig, defineRuntime, defineDatabase, defineAuth, defineFileStorage } from "@quickback/compiler";
|
|
90
|
+
|
|
91
|
+
export default defineConfig({
|
|
92
|
+
name: "events-app",
|
|
93
|
+
template: "hono",
|
|
94
|
+
features: { organizations: true },
|
|
95
|
+
providers: {
|
|
96
|
+
runtime: defineRuntime("cloudflare"),
|
|
97
|
+
database: defineDatabase("cloudflare-d1"),
|
|
98
|
+
auth: defineAuth("better-auth", { plugins: { organization: true } }),
|
|
99
|
+
fileStorage: defineFileStorage("cloudflare-r2", { bucketName: "events-app-media" }),
|
|
100
|
+
},
|
|
101
|
+
bindings: {
|
|
102
|
+
r2Buckets: [{ binding: "MEDIA", bucketName: "events-app-media" }],
|
|
103
|
+
},
|
|
104
|
+
});
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
// quickback/features/media/media.ts
|
|
109
|
+
import { feature, q } from "@quickback/compiler";
|
|
110
|
+
|
|
111
|
+
export default feature("media", {
|
|
112
|
+
columns: {
|
|
113
|
+
id: q.id(),
|
|
114
|
+
eventId: q.text().required(),
|
|
115
|
+
title: q.text({ maxLength: 200 }).required(),
|
|
116
|
+
r2Key: q.storageKey({
|
|
117
|
+
bucket: "MEDIA",
|
|
118
|
+
key: "media/{organizationId}/{eventId}/{uuid}.{ext}",
|
|
119
|
+
mime: ["image/*", "application/pdf"],
|
|
120
|
+
maxBytes: 10_000_000,
|
|
121
|
+
}),
|
|
122
|
+
organizationId: q.scope("organization"),
|
|
123
|
+
...q.audit(),
|
|
124
|
+
},
|
|
125
|
+
read: { access: { roles: ["member"] } },
|
|
126
|
+
update: { access: { roles: ["member"] } },
|
|
127
|
+
delete: { access: { roles: ["admin"] }, mode: "hard" },
|
|
128
|
+
guards: { updatable: ["title"] },
|
|
129
|
+
});
|
|
86
130
|
|
|
87
|
-
|
|
131
|
+
// quickback/features/media/actions/upload.ts
|
|
88
132
|
import { z } from "zod";
|
|
89
133
|
import { defineAction, media } from "../.quickback/define-action";
|
|
90
134
|
|
|
91
135
|
export default defineAction({
|
|
92
|
-
description: "
|
|
93
|
-
path: "/media/
|
|
136
|
+
description: "Create a media row and sign its direct-to-R2 upload.",
|
|
137
|
+
path: "/media/upload",
|
|
94
138
|
method: "POST",
|
|
95
|
-
input: z.object({
|
|
139
|
+
input: z.object({ eventId: z.string(), title: z.string(), ext: z.string(), mime: z.string(), size: z.number().int() }),
|
|
96
140
|
access: { roles: ["member"] },
|
|
97
|
-
async execute({
|
|
98
|
-
const
|
|
99
|
-
|
|
100
|
-
contentType: input.contentType, // bound into the signature
|
|
101
|
-
contentLength: input.size, // required — bound into the signature, checked against maxFileSize
|
|
102
|
-
expiresIn: 600,
|
|
103
|
-
});
|
|
104
|
-
await db.insert(media).values({ key /* … */ });
|
|
105
|
-
return { uploadUrl: upload.url, key, headers: upload.headers };
|
|
141
|
+
async execute({ db, input }) {
|
|
142
|
+
const { row, putUrl, headers } = await db.allocateUpload(media, input);
|
|
143
|
+
return { id: row.id, putUrl, headers };
|
|
106
144
|
},
|
|
107
145
|
});
|
|
108
146
|
```
|
|
109
147
|
|
|
110
148
|
```bash
|
|
111
149
|
# 1. Ask your action for a signed URL (your auth/roles run here)
|
|
112
|
-
curl -X POST https://api.example.com/api/v1/media/
|
|
150
|
+
curl -X POST https://api.example.com/api/v1/media/upload \
|
|
113
151
|
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
|
|
114
|
-
-d '{ "
|
|
115
|
-
# → { "
|
|
152
|
+
-d '{ "eventId": "evt_1", "title": "Floor plan", "ext": "pdf", "mime": "application/pdf", "size": 48213 }'
|
|
153
|
+
# → { "id": "…", "putUrl": "https://<account>.r2.cloudflarestorage.com/events-app-media/media/org_abc/evt_1/<uuid>.pdf?…X-Amz-Signature=…", "headers": { "Content-Length": "48213", "Content-Type": "application/pdf" } }
|
|
116
154
|
|
|
117
155
|
# 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
|
|
118
|
-
curl -X PUT "<
|
|
156
|
+
curl -X PUT "<putUrl>" -H "Content-Type: application/pdf" -H "Content-Length: 48213" --data-binary @plan.pdf
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
`db.allocateUpload(table, { ...rowValues, ext, mime, size }, { id?, expiresIn? })`:
|
|
160
|
+
|
|
161
|
+
1. Checks `mime` against the column's `mime` list (`415 STORAGE_UPLOAD_TYPE_REFUSED`),
|
|
162
|
+
`size` against `maxBytes` (`413 STORAGE_UPLOAD_TOO_LARGE`), and `ext`
|
|
163
|
+
(1–16 letters or digits, lower-cased).
|
|
164
|
+
2. Stamps the row exactly as the scoped `db.insert` would (`organizationId`
|
|
165
|
+
from the caller's active org), then renders the key from the template:
|
|
166
|
+
`{column}` from the row, a fresh `{uuid}`, `{ext}` from the call. A value
|
|
167
|
+
that cannot fill a whole path segment (`/`, `..`, anything outside
|
|
168
|
+
`A–Z a–z 0–9 _ -`) is a `400 STORAGE_KEY_SEGMENT_INVALID`.
|
|
169
|
+
3. Signs a PUT with `ctx.storage.signPutUrl` underneath. The `mime` and `size`
|
|
170
|
+
are bound into the signature as `Content-Type` / `Content-Length`. When the
|
|
171
|
+
project also declares `fileStorage.allowedTypes`, the type must be on that
|
|
172
|
+
list too.
|
|
173
|
+
4. Inserts the row (or, with `{ id }`, re-keys that row and deletes its
|
|
174
|
+
previous object) and returns `{ row, key, putUrl, headers, expiresAt }`.
|
|
175
|
+
|
|
176
|
+
If the table also has columns named `mime`, `size`, or `ext`, the upload's
|
|
177
|
+
values fill them.
|
|
178
|
+
|
|
179
|
+
**Reads.** `db.signDownload(table, id, { expiresIn?, downloadFilename? })` loads
|
|
180
|
+
the row through the firewall and signs a GET for its key. It refuses with
|
|
181
|
+
`403 STORAGE_KEY_OUTSIDE_PREFIX` when the stored key is not under the row's
|
|
182
|
+
own prefix.
|
|
183
|
+
|
|
184
|
+
**The prefix** is the template up to `{uuid}` with the row's values
|
|
185
|
+
substituted: `media/org_abc/evt_1/`. Every column placeholder fills a whole
|
|
186
|
+
`/`-separated segment, so "starts with the row's prefix" can't match a
|
|
187
|
+
neighbouring tenant. Reads, deletes, and [tenant purge](/configure/tenancy) all
|
|
188
|
+
refuse a key outside its row's prefix — a row whose key was tampered to name
|
|
189
|
+
another tenant's object never reaches that object.
|
|
190
|
+
|
|
191
|
+
**Deletes.** Deleting a row deletes its object:
|
|
192
|
+
|
|
193
|
+
- The generated hard `DELETE /:id` and `DELETE /batch` delete the objects of
|
|
194
|
+
the rows they erased.
|
|
195
|
+
- In an action, `db.delete(table)` on a storage-key table deletes the objects
|
|
196
|
+
of the rows it removed — from a full `.returning()`, or else by selecting
|
|
197
|
+
the matching rows through the same scoped `db` first. Inside
|
|
198
|
+
`db.transaction(...)` the objects are deleted after the outermost commit.
|
|
199
|
+
`db.batch([...])` refuses a storage-key delete, because a batch skips this
|
|
200
|
+
step.
|
|
201
|
+
- Soft deletes keep the object, because the row still exists.
|
|
202
|
+
- `unsafeDb`, schedules, and queue handlers bypass the scoped `db`. After a
|
|
203
|
+
hard delete there, call `deleteStorageObjects(env, table, deletedRows)` from
|
|
204
|
+
`src/lib/storage-keys`. It runs the same prefix check.
|
|
205
|
+
|
|
206
|
+
**What the compiler refuses** (each is a compile error):
|
|
207
|
+
|
|
208
|
+
| Code | Cause |
|
|
209
|
+
|---|---|
|
|
210
|
+
| `STORAGE_KEY_GUARDED` | The column is listed in `guards.createable` / `updatable` / `immutable` / `protected`. It is never client-writable, and no generated write body carries it. |
|
|
211
|
+
| `STORAGE_KEY_TENANT_PREFIX` | A tenant column of the table's firewall (`organizationId`, `ownerId`, a scope column) is not a placeholder before `{uuid}`. |
|
|
212
|
+
| `STORAGE_KEY_TEMPLATE` | No `{uuid}`, `{uuid}` not starting its own segment, a placeholder that isn't a column, a column after `{uuid}` (only `{ext}` may follow), `..`, or characters outside `A–Z a–z 0–9 . _ - /`. |
|
|
213
|
+
| `STORAGE_KEY_BUCKET` | `bucket` is not a `bindings.r2Buckets` binding (or the managed `fileStorage` binding), or an environment maps that binding to a different bucket name. |
|
|
214
|
+
| `STORAGE_KEY_PRESIGN` | No `providers.fileStorage: defineFileStorage("cloudflare-r2", …)` — the presigner signs the PUT. |
|
|
215
|
+
| `STORAGE_KEY_MIME` / `STORAGE_KEY_MAX_BYTES` | A malformed MIME pattern, or `maxBytes` that isn't a positive integer or exceeds `fileStorage.maxFileSize`. |
|
|
216
|
+
| `STORAGE_KEY_REQUIRED_WITH_CREATE` | The column is `.required()` and the table has a generic create route, which could never supply the key. |
|
|
217
|
+
| `STORAGE_KEY_CASCADE` | The table declares `onDelete: 'cascade'`. A cascaded delete removes rows without deleting their objects. |
|
|
218
|
+
| `STORAGE_KEY_MULTIPLE` / `STORAGE_KEY_NO_RESOURCE` | More than one storage key on a table, or a storage key on a table with no resource (no firewall to check the row against). |
|
|
219
|
+
|
|
220
|
+
In action code, writing the column directly (`db.insert(...).values({ r2Key })`,
|
|
221
|
+
`db.update(...).set({ r2Key })`, an upsert's `set`) throws
|
|
222
|
+
`STORAGE_KEY_NOT_WRITABLE`.
|
|
223
|
+
|
|
224
|
+
### Lower level: `storage.signPutUrl`
|
|
225
|
+
|
|
226
|
+
When the key does not belong to a row (a one-off export, an import staging
|
|
227
|
+
area), sign it yourself. You own the key's tenancy in that case.
|
|
228
|
+
|
|
229
|
+
```ts no-compile
|
|
230
|
+
const upload = await storage.signPutUrl(`exports/${ctx.activeOrgId}/${crypto.randomUUID()}.csv`, {
|
|
231
|
+
contentType: "text/csv",
|
|
232
|
+
contentLength: input.size, // required — bound into the signature
|
|
233
|
+
expiresIn: 600,
|
|
234
|
+
});
|
|
119
235
|
```
|
|
120
236
|
|
|
121
237
|
`storage.signPutUrl(key, { contentLength, contentType?, expiresIn?, bucket? })`
|
|
@@ -93,6 +93,44 @@ verify that the Hyperdrive origin matches the intended Neon branch, inspect
|
|
|
93
93
|
remote query caching, or apply Postgres migrations. Configure Hyperdrive with
|
|
94
94
|
query caching disabled and migrate the intended branch before deployment.
|
|
95
95
|
|
|
96
|
+
## Release stamps
|
|
97
|
+
|
|
98
|
+
{/* doc-compile: skip — excerpt of the top-level `release` key. */}
|
|
99
|
+
```ts title="quickback/quickback.config.ts"
|
|
100
|
+
release: { stampVars: true }, // optional: version: "1.4.0"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
With `stampVars` on, `quickback build` reads the release identity from your
|
|
104
|
+
repository: the version (`release.version`, else the project `package.json`
|
|
105
|
+
version), the git commit (`git rev-parse HEAD`, suffixed `-dirty` when the
|
|
106
|
+
tree has uncommitted changes), and the build time. The compiler cannot see your
|
|
107
|
+
repository, so the CLI supplies these values and the compiler validates them.
|
|
108
|
+
They are stamped as `QUICKBACK_RELEASE_VERSION`, `QUICKBACK_RELEASE_SHA` and
|
|
109
|
+
`QUICKBACK_RELEASE_AT` into `[vars]` and into every `[env.*.vars]` block.
|
|
110
|
+
Then:
|
|
111
|
+
|
|
112
|
+
- `GET /health` includes `release: { version, sha, at }`;
|
|
113
|
+
- handlers read the same values as `ctx.release`;
|
|
114
|
+
- `quickback deploy` passes `--tag <version> --message <version>@<sha>@<at>`
|
|
115
|
+
to `wrangler deploy`, so each Worker version in the Cloudflare dashboard
|
|
116
|
+
names the build it came from. It refuses to deploy if the built output
|
|
117
|
+
carries no stamp.
|
|
118
|
+
|
|
119
|
+
The three names are compiler-owned. Declaring a var with one of these names is
|
|
120
|
+
a compile error, whether or not stamping is on. The build fails if the project
|
|
121
|
+
is not a git checkout or has no version. `QUICKBACK_RELEASE_AT` changes on
|
|
122
|
+
every build, so `wrangler.toml` changes on every build too.
|
|
123
|
+
|
|
124
|
+
## Before you ship a target
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
quickback secrets check --env production # every required secret set, nothing undeclared
|
|
128
|
+
quickback migrate data --env production # dry-run pending data migrations
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
See [Check and Push Secrets](/tooling/cli#check-and-push-secrets) and
|
|
132
|
+
[Data Migrations](/platform/database/data-migrations).
|
|
133
|
+
|
|
96
134
|
## Conflicting ids
|
|
97
135
|
|
|
98
136
|
If `quickback.config.ts` already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, `quickback deploy` prints both and stops:
|
|
@@ -69,6 +69,9 @@ quickback build
|
|
|
69
69
|
> the name used throughout the docs.
|
|
70
70
|
|
|
71
71
|
|
|
72
|
+
Use `quickback build --accept-compiler` to accept a compiler other than the
|
|
73
|
+
one `compiler.pin` names (see [Pin the Compiler](#pin-the-compiler)).
|
|
74
|
+
|
|
72
75
|
Use `quickback build --verbose` when a remote build fails and you need the
|
|
73
76
|
underlying command, exit code, stderr/stdout tail, and suggested fixes.
|
|
74
77
|
|
|
@@ -96,6 +99,40 @@ explicit `wrangler ... --env <target>` deploy commands. It does not suggest a
|
|
|
96
99
|
bare deploy or the unnamed `.env.neon` / `.dev.vars` workflow for named
|
|
97
100
|
Hyperdrive environments.
|
|
98
101
|
|
|
102
|
+
#### Diff the access manifest
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
quickback build --diff quickback/reports/access-manifest.json
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`--diff <baseline.json>` compares a committed
|
|
109
|
+
[access manifest](/tooling/output#access-manifest) with the one this build
|
|
110
|
+
produces, prints a readable diff, and **exits 1 on any widening**:
|
|
111
|
+
|
|
112
|
+
- a new route or Durable Object room, or a new room kind;
|
|
113
|
+
- a weaker `auth` requirement (`session` → `public`) or room gate
|
|
114
|
+
(`resource-gated` → `authenticated`);
|
|
115
|
+
- an access tree that admits a principal the baseline did not — wider roles,
|
|
116
|
+
a new `or` arm, a dropped `and` arm, a removed gate, a new `fga` arm;
|
|
117
|
+
- wider room `roles` or effective `writeRoles`, including removal of a write
|
|
118
|
+
restriction or a change to inherited table access;
|
|
119
|
+
- a firewall arm removed from an AND, added to an `any:` group, or that lost
|
|
120
|
+
its `tenantBound` flag; a firewall that went from `scoped` to `exception`;
|
|
121
|
+
- an `unsafe` action that became `crossTenant`, `targetScope: 'all'`, or not
|
|
122
|
+
`adminOnly`;
|
|
123
|
+
- a new trusted origin, in the bundle or for any named environment.
|
|
124
|
+
|
|
125
|
+
Narrowings (removed routes, tighter roles, new AND arms) print but never fail.
|
|
126
|
+
When the comparison cannot prove a change narrows, it reports a widening.
|
|
127
|
+
Older room baselines without `connectAccess` and `writeAccess` cannot establish
|
|
128
|
+
what the room admitted: regenerate and review them before accepting a new baseline.
|
|
129
|
+
|
|
130
|
+
The baseline is read **before** the build, so `--diff` may point at the very
|
|
131
|
+
file the build overwrites — the usual setup is to commit
|
|
132
|
+
`quickback/reports/access-manifest.json` and run the line above in CI. After
|
|
133
|
+
reviewing an intended widening, commit the freshly written manifest as the new
|
|
134
|
+
baseline.
|
|
135
|
+
|
|
99
136
|
#### Generated `src/` is hermetic
|
|
100
137
|
|
|
101
138
|
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:
|
|
@@ -261,6 +298,88 @@ cross-feature imports are left untouched, and unusual shapes (aliases,
|
|
|
261
298
|
multi-line imports, `import type`) are reported for manual attention instead
|
|
262
299
|
of guessed at.
|
|
263
300
|
|
|
301
|
+
### Pin the Compiler
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
quickback build --accept-compiler # accept a different compiler and rewrite the pin
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Set `compiler.pin` to the exact compiler build a project may be built by, as
|
|
308
|
+
`<version>@<gitSha>`:
|
|
309
|
+
|
|
310
|
+
{/* doc-compile: skip — excerpt of the `compiler` block; the rest of `defineConfig` is unchanged. */}
|
|
311
|
+
```ts title="quickback/quickback.config.ts"
|
|
312
|
+
compiler: {
|
|
313
|
+
pin: "0.70.36@3f9c2ab",
|
|
314
|
+
},
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
The compiler compares the pin against its own version and image sha
|
|
318
|
+
(the same values `/health` reports) **before generating anything**. Any other
|
|
319
|
+
build fails the compile and nothing is written. The sha matches by prefix, so a
|
|
320
|
+
7-character short sha is enough; the version must match exactly.
|
|
321
|
+
|
|
322
|
+
`--accept-compiler` lets the mismatch through and rewrites `compiler.pin` to
|
|
323
|
+
the compiler that answered, so the upgrade shows up as a one-line diff in
|
|
324
|
+
review. A compiler that cannot report its build sha (a local build without
|
|
325
|
+
build metadata) can neither satisfy a pin nor be accepted into one. A compiler
|
|
326
|
+
too old to know about pins is refused by the CLI.
|
|
327
|
+
|
|
328
|
+
### Check and Push Secrets
|
|
329
|
+
|
|
330
|
+
```bash
|
|
331
|
+
quickback secrets check --env staging
|
|
332
|
+
quickback secrets push --env staging # reads .env.staging
|
|
333
|
+
quickback secrets push --env staging --from ./secrets/staging.env
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Every build writes the declared secrets contract to
|
|
337
|
+
`reports/ops.manifest.json`: every secret the generated Worker reads
|
|
338
|
+
([`bindings.secrets`](/configure/bindings#secrets) plus those your providers
|
|
339
|
+
imply, such as `BETTER_AUTH_SECRET`, social-login credentials, R2 presign keys,
|
|
340
|
+
`ENCRYPTION_KEK`, Neon's `DATABASE_URL`), and which ones the boot guard refuses
|
|
341
|
+
to serve without.
|
|
342
|
+
|
|
343
|
+
- `check` runs `wrangler secret list` for the target and exits `1` when a
|
|
344
|
+
required secret is **missing** or a secret is set but **not declared**.
|
|
345
|
+
Code that reads an undeclared secret is code the compiler cannot see, so
|
|
346
|
+
that state counts as a failure.
|
|
347
|
+
- `push` sets secrets from a dotenv file with `wrangler secret put`. Values go
|
|
348
|
+
over stdin, not argv, and are never printed. If the file names an
|
|
349
|
+
undeclared secret or has an empty value, nothing is pushed. Without
|
|
350
|
+
`--from`, it reads `.env.<target>`, which the generated `.gitignore` ignores
|
|
351
|
+
(`.env.*`, keeping `*.example`).
|
|
352
|
+
|
|
353
|
+
Projects without named environments omit `--env` and pass `--from`. The build
|
|
354
|
+
also writes `.dev.vars.example` with every declared secret, for local
|
|
355
|
+
`wrangler dev`. Neon and PlanetScale keep their own template, and any declared
|
|
356
|
+
secret it lacks is appended to it.
|
|
357
|
+
|
|
358
|
+
### Run Data Migrations
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
quickback migrate data --env staging # dry run
|
|
362
|
+
quickback migrate data --env staging --apply
|
|
363
|
+
quickback migrate data --env production --apply --id 2026-10-21-backfill-slugs
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
Runs [data migrations](/platform/database/data-migrations) inside the
|
|
367
|
+
deployed Worker for that target. By default it dry-runs every pending (or
|
|
368
|
+
previously failed) migration in id order. `--apply` writes the changes and
|
|
369
|
+
records each id in that environment's ledger, so it never runs there again.
|
|
370
|
+
|
|
371
|
+
| Flag | |
|
|
372
|
+
| --- | --- |
|
|
373
|
+
| `--env <target>` | Named target (required when the project has named environments). |
|
|
374
|
+
| `--apply` | Write and record. Without it, nothing is written. |
|
|
375
|
+
| `--id <id>` | Run one migration instead of every pending one. |
|
|
376
|
+
| `--token <bearer>` | Bearer for a user whose `user.role` is in `dataMigrations.access.userRole`. Also read from `QUICKBACK_ADMIN_TOKEN`. |
|
|
377
|
+
| `--url <origin>` | Override the target's API origin (required for workers.dev-only targets). |
|
|
378
|
+
|
|
379
|
+
The route path and each target's API hostname come from
|
|
380
|
+
`reports/ops.manifest.json`. The command needs no database credentials. The
|
|
381
|
+
first failure stops the run and exits `1`.
|
|
382
|
+
|
|
264
383
|
### View Documentation
|
|
265
384
|
|
|
266
385
|
```bash
|
|
@@ -420,6 +539,7 @@ quickback build
|
|
|
420
539
|
|------|-------------|
|
|
421
540
|
| `-v, --version` | Show version number |
|
|
422
541
|
| `-h, --help` | Show help message |
|
|
542
|
+
| `build --diff <baseline>` | Fail the build on any access widening against a committed access manifest ([details](#diff-the-access-manifest)) |
|
|
423
543
|
|
|
424
544
|
## Environment Variables
|
|
425
545
|
|
|
@@ -149,23 +149,23 @@ and corrective import. If an older compiler or an already-generated project
|
|
|
149
149
|
reaches Wrangler first, apply the same fix above and rebuild Generated Backend
|
|
150
150
|
before Deploy.
|
|
151
151
|
|
|
152
|
-
The
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
152
|
+
The bundle check resolves dependencies from the compiler image first. A
|
|
153
|
+
package declared in [`build.dependencies`](/configure#custom-dependencies) that
|
|
154
|
+
the image lacks is installed from the npm registry for that compile, with
|
|
155
|
+
install scripts disabled. If that install fails, the compile stops before the
|
|
156
|
+
bundle check and names the packages:
|
|
156
157
|
|
|
157
158
|
```
|
|
158
|
-
|
|
159
|
-
|
|
159
|
+
build.dependencies could not be installed for the Worker bundle check:
|
|
160
|
+
fast-xml-parser. npm: …
|
|
160
161
|
```
|
|
161
162
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
packages
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
bundle check.
|
|
163
|
+
Check that the package name and range exist on npm. Only registry packages at
|
|
164
|
+
a semver range or dist-tag can be installed; `file:`, `git`, URL, `npm:` alias,
|
|
165
|
+
and `workspace:` specifiers fail with `build.dependencies must be npm registry
|
|
166
|
+
packages at a semver range or dist-tag`. Type-only `@types/*` packages never
|
|
167
|
+
block the check. Validation compiles (`complete=false`) still generate output
|
|
168
|
+
without running the Worker bundle check.
|
|
169
169
|
|
|
170
170
|
Store the Better Auth id as plain text:
|
|
171
171
|
|
|
@@ -277,7 +277,7 @@ schema qualifier script:
|
|
|
277
277
|
|
|
278
278
|
| Provider | Emitted |
|
|
279
279
|
|----------|---------|
|
|
280
|
-
| `cloudflare-d1` | `.env.cloudflare-d1.example`, `wrangler.d1.example`, `drizzle.auth.config.ts` (dual-database mode) |
|
|
280
|
+
| `cloudflare-d1` | `.env.cloudflare-d1.example`, `.dev.vars.example`, `wrangler.d1.example`, `drizzle.auth.config.ts` (dual-database mode) |
|
|
281
281
|
| `neon` | `.env.neon.example`, `.dev.vars.example`, `docs/neon-setup.md`, `scripts/quickback-qualify-auth-schema.mjs` |
|
|
282
282
|
| `planetscale-postgres` | `.env.planetscale.example`, `.dev.vars.example`, `docs/planetscale-postgres-setup.md`, `scripts/quickback-qualify-auth-schema.mjs` |
|
|
283
283
|
|
|
@@ -288,6 +288,39 @@ they emit a single `drizzle.config.ts` rather than the D1 dual-database pair.
|
|
|
288
288
|
See [Neon](/platform/database/neon) and
|
|
289
289
|
[PlanetScale Postgres](/platform/database/planetscale-postgres).
|
|
290
290
|
|
|
291
|
+
Every Cloudflare project gets a `.dev.vars.example` that lists every declared
|
|
292
|
+
secret (see below). The Postgres providers keep their own connection guidance
|
|
293
|
+
in that file, and any declared secret they do not mention is appended. The
|
|
294
|
+
generated `.gitignore` ignores `.dev.vars` and `.env.*` (keeping `*.example`),
|
|
295
|
+
so files that hold secret values are never committed.
|
|
296
|
+
|
|
297
|
+
### Ops manifest
|
|
298
|
+
|
|
299
|
+
`reports/ops.manifest.json` is written on every Cloudflare build. It is the
|
|
300
|
+
one place the CLI reads operational facts from, so the CLI never re-derives a
|
|
301
|
+
compiler rule:
|
|
302
|
+
|
|
303
|
+
| Key | Contents | Read by |
|
|
304
|
+
| --- | --- | --- |
|
|
305
|
+
| `compiler` | `version` and `gitSha` of the build that produced the output | — |
|
|
306
|
+
| `targets` | each deploy target: logical name, Worker name, `wrangler --env`, API origin | every command below |
|
|
307
|
+
| `secrets` | `required`, `optional`, and `declared[]` (source, `bootGuarded`, description) | `quickback secrets check\|push` |
|
|
308
|
+
| `release` | the stamped `{ version, sha, at }` when `release.stampVars` is on | `quickback deploy` (`--tag` / `--message`) |
|
|
309
|
+
| `dataMigrations` | runner path, ledger table, allowed roles, declared ids | `quickback migrate data` |
|
|
310
|
+
|
|
311
|
+
Readers ignore unknown keys. New sections are added over time, and existing
|
|
312
|
+
ones are never restructured.
|
|
313
|
+
|
|
314
|
+
### Data migrations
|
|
315
|
+
|
|
316
|
+
When `quickback/migrations/data/*.ts` exist, each file is emitted as a module
|
|
317
|
+
under `src/data-migrations/`, along with `src/lib/data-migration-define.ts`,
|
|
318
|
+
the gated runner `src/lib/data-migrations.ts` (mounted at
|
|
319
|
+
`/api/v1/system/data-migrations`), and the `_qb_data_migrations` ledger table
|
|
320
|
+
in the features database. On Postgres, that table lives in the `app` schema
|
|
321
|
+
behind a service-role-only RLS policy. See
|
|
322
|
+
[Data Migrations](/platform/database/data-migrations).
|
|
323
|
+
|
|
291
324
|
### Embeddings
|
|
292
325
|
|
|
293
326
|
When any feature has `embeddings` configured:
|
|
@@ -384,7 +417,7 @@ quickback/drizzle/
|
|
|
384
417
|
|
|
385
418
|
### Security Audit Database (Unsafe Actions)
|
|
386
419
|
|
|
387
|
-
When any action enables unsafe cross-tenant mode (`unsafe.crossTenant: true`):
|
|
420
|
+
When any action enables unsafe cross-tenant mode (`unsafe.crossTenant: true`), declares the [operator lane](/define/actions/scoped-db#operator-lane-operator) (`operator:`), is `PUBLIC`, or a resource hard-deletes:
|
|
388
421
|
|
|
389
422
|
```
|
|
390
423
|
src/
|
|
@@ -422,6 +455,41 @@ Set `compiler.securityContracts.report.signature.required: true` to fail compila
|
|
|
422
455
|
|
|
423
456
|
The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
|
|
424
457
|
|
|
458
|
+
### Access Manifest
|
|
459
|
+
|
|
460
|
+
`reports/access-manifest.json` is emitted on every compile. The contract
|
|
461
|
+
report says how many invariants held; the manifest says **what the backend
|
|
462
|
+
admits**:
|
|
463
|
+
|
|
464
|
+
- **`routes`** — one entry per HTTP route (CRUD, batch, views, actions), keyed
|
|
465
|
+
`<METHOD> <path>`: the `auth` requirement (`public` / `session` /
|
|
466
|
+
`bearer-only`), the access tree, and the flattened principals that open it —
|
|
467
|
+
`roles`, `pseudoRoles`, `userRole`, `scopeLanes` (`scope:<kind>:<role>`) and
|
|
468
|
+
`relationships`. `firewall` lists the row arms (`mode` is `scoped`,
|
|
469
|
+
`exception` or `none`); each arm carries its boolean `path`
|
|
470
|
+
(`and`, `and > any`, …), a canonical `predicate`, and **`tenantBound`** —
|
|
471
|
+
true when every row the arm admits is bound to the caller's org (the org
|
|
472
|
+
equality itself, an arm under an AND with it, or a scope / relationship arm
|
|
473
|
+
the compiler wraps in `tenantBound(arm, orgEq)` inside an org-anchored
|
|
474
|
+
`any:` group). Actions with `unsafe` enabled carry `adminOnly`,
|
|
475
|
+
`crossTenant` and `targetScope`.
|
|
476
|
+
- **`realtimeRooms`** — each Durable Object mount with its `connectAuth` and,
|
|
477
|
+
for resource-gated rooms, the keyed table's read access and firewall arms.
|
|
478
|
+
Each gate also records `connectAccess` (the expanded room `roles`, or the
|
|
479
|
+
table read policy when inherited) and `writeAccess` (the additional expanded
|
|
480
|
+
`writeRoles` restriction, or `null` when every admitted connection may write).
|
|
481
|
+
The table firewall still applies when a room overrides its role policy.
|
|
482
|
+
- **`trustedOrigins`** — `bundle` is the `TRUSTED_ORIGINS` list baked into the
|
|
483
|
+
one shared Worker bundle; `environments` lists, per named environment, the
|
|
484
|
+
origins of the hostnames it claims.
|
|
485
|
+
|
|
486
|
+
The file is deterministic — no timestamps, no compiler version, sorted
|
|
487
|
+
arrays — so a committed copy is a baseline. The CLI writes it to
|
|
488
|
+
`quickback/reports/access-manifest.json` alongside the contract report.
|
|
489
|
+
`quickback build --diff <baseline>` compares the fresh manifest to it and
|
|
490
|
+
exits non-zero on any widening; see
|
|
491
|
+
[CLI → Diff the access manifest](/tooling/cli#diff-the-access-manifest).
|
|
492
|
+
|
|
425
493
|
### Data Remediation Report
|
|
426
494
|
|
|
427
495
|
`reports/data-remediation.sql` is emitted when the project has something to check. It is **read-only as emitted** — every statement is a `SELECT`, and the compiler never runs it:
|