@quickback-dev/cli 0.70.45 → 0.72.3
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.map +1 -1
- package/dist/commands/build.js +10 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +7 -1
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +6 -5
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +6 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -1
- package/dist/lib/access-manifest-diff.js +10 -0
- package/dist/lib/access-manifest-diff.js.map +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +36 -0
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +13 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +4 -0
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/file-loader.d.ts +22 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +80 -18
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.js +9 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +10 -0
- package/dist/lib/harness.d.ts.map +1 -1
- package/dist/lib/harness.js +31 -0
- package/dist/lib/harness.js.map +1 -1
- package/dist/lib/migrations/executor.js +5 -1
- package/dist/lib/migrations/executor.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +23 -2
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +13 -1
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +33 -2
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +2 -2
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +3 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +14 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +29 -7
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/SKILL.md +64 -0
- package/dist/skill/docs/api/actions.md +73 -2
- package/dist/skill/docs/api/batch-operations.md +2 -0
- package/dist/skill/docs/api/caching.md +2 -2
- package/dist/skill/docs/api/crud.md +13 -0
- package/dist/skill/docs/api/errors.md +111 -10
- package/dist/skill/docs/api/index.md +24 -0
- package/dist/skill/docs/api/openapi.md +8 -0
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/configure/agents.md +73 -1
- package/dist/skill/docs/configure/auth.md +7 -1
- package/dist/skill/docs/configure/bindings.md +55 -0
- package/dist/skill/docs/configure/cloudflare-access.md +191 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +4 -2
- package/dist/skill/docs/configure/providers.md +2 -1
- package/dist/skill/docs/configure/tenancy.md +3 -0
- package/dist/skill/docs/configure/tenant-databases.md +2407 -0
- package/dist/skill/docs/define/access.md +33 -1
- package/dist/skill/docs/define/actions/defining.md +118 -1
- package/dist/skill/docs/define/actions/scoped-db.md +32 -8
- package/dist/skill/docs/define/areas.md +145 -2
- package/dist/skill/docs/define/diagnostics.md +160 -21
- package/dist/skill/docs/define/encryption.md +13 -2
- package/dist/skill/docs/define/fga.md +320 -42
- package/dist/skill/docs/define/firewall.md +4 -0
- package/dist/skill/docs/define/index.md +1 -0
- package/dist/skill/docs/define/read.md +46 -5
- package/dist/skill/docs/define/relationships.md +30 -12
- package/dist/skill/docs/define/schema.md +2 -0
- package/dist/skill/docs/define/scopes.md +393 -9
- package/dist/skill/docs/define/sealed-protocol.md +67 -12
- package/dist/skill/docs/define/transitions.md +4 -1
- package/dist/skill/docs/define/triggers.md +55 -1
- package/dist/skill/docs/platform/api-contract/index.md +9 -3
- package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/dist/skill/docs/platform/auth/using-auth.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +112 -3
- package/dist/skill/docs/platform/database/data-migrations.md +3 -1
- package/dist/skill/docs/platform/database/neon.md +10 -2
- package/dist/skill/docs/platform/queues/handlers.md +48 -16
- package/dist/skill/docs/platform/queues/using-queues.md +16 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +294 -17
- package/dist/skill/docs/platform/realtime/index.md +9 -6
- package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/r2.md +10 -1
- package/dist/skill/docs/platform/storage/using-r2.md +42 -1
- package/dist/skill/docs/tooling/output.md +9 -2
- package/dist/skill/docs/ui/account/features/admin.md +5 -3
- package/dist/skill/docs/ui/account/hooks.md +9 -2
- package/dist/skill/docs/ui/admin/connecting.md +3 -3
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/package.json +1 -1
- package/src/skill/SKILL.md +64 -0
- package/src/skill/docs/api/actions.md +73 -2
- package/src/skill/docs/api/batch-operations.md +2 -0
- package/src/skill/docs/api/caching.md +2 -2
- package/src/skill/docs/api/crud.md +13 -0
- package/src/skill/docs/api/errors.md +111 -10
- package/src/skill/docs/api/index.md +24 -0
- package/src/skill/docs/api/openapi.md +8 -0
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/configure/agents.md +73 -1
- package/src/skill/docs/configure/auth.md +7 -1
- package/src/skill/docs/configure/bindings.md +55 -0
- package/src/skill/docs/configure/cloudflare-access.md +191 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +4 -2
- package/src/skill/docs/configure/providers.md +2 -1
- package/src/skill/docs/configure/tenancy.md +3 -0
- package/src/skill/docs/configure/tenant-databases.md +2407 -0
- package/src/skill/docs/define/access.md +33 -1
- package/src/skill/docs/define/actions/defining.md +118 -1
- package/src/skill/docs/define/actions/scoped-db.md +32 -8
- package/src/skill/docs/define/areas.md +145 -2
- package/src/skill/docs/define/diagnostics.md +160 -21
- package/src/skill/docs/define/encryption.md +13 -2
- package/src/skill/docs/define/fga.md +320 -42
- package/src/skill/docs/define/firewall.md +4 -0
- package/src/skill/docs/define/index.md +1 -0
- package/src/skill/docs/define/read.md +46 -5
- package/src/skill/docs/define/relationships.md +30 -12
- package/src/skill/docs/define/schema.md +2 -0
- package/src/skill/docs/define/scopes.md +393 -9
- package/src/skill/docs/define/sealed-protocol.md +67 -12
- package/src/skill/docs/define/transitions.md +4 -1
- package/src/skill/docs/define/triggers.md +55 -1
- package/src/skill/docs/platform/api-contract/index.md +9 -3
- package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/src/skill/docs/platform/auth/using-auth.md +1 -1
- package/src/skill/docs/platform/database/d1.md +112 -3
- package/src/skill/docs/platform/database/data-migrations.md +3 -1
- package/src/skill/docs/platform/database/neon.md +10 -2
- package/src/skill/docs/platform/queues/handlers.md +48 -16
- package/src/skill/docs/platform/queues/using-queues.md +16 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +294 -17
- package/src/skill/docs/platform/realtime/index.md +9 -6
- package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/r2.md +10 -1
- package/src/skill/docs/platform/storage/using-r2.md +42 -1
- package/src/skill/docs/tooling/output.md +9 -2
- package/src/skill/docs/ui/account/features/admin.md +5 -3
- package/src/skill/docs/ui/account/hooks.md +9 -2
- package/src/skill/docs/ui/admin/connecting.md +3 -3
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/dist/codex/AGENTS.md +0 -290
- package/dist/commands/build.test.d.ts.map +0 -1
- package/dist/commands/codex.d.ts +0 -16
- package/dist/commands/codex.d.ts.map +0 -1
- package/dist/commands/codex.js +0 -159
- package/dist/commands/codex.js.map +0 -1
- package/dist/commands/compile.d.ts +0 -62
- package/dist/commands/compile.d.ts.map +0 -1
- package/dist/commands/compile.js +0 -830
- package/dist/commands/compile.js.map +0 -1
- package/dist/commands/compile.test.d.ts.map +0 -1
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/commands/migrate.test.d.ts.map +0 -1
- package/dist/commands/migrations.test.d.ts.map +0 -1
- package/dist/commands/push.test.d.ts.map +0 -1
- package/dist/commands/schema.test.d.ts.map +0 -1
- package/dist/docs/content.d.ts +0 -7
- package/dist/docs/content.d.ts.map +0 -1
- package/dist/docs/content.js +0 -672
- package/dist/docs/content.js.map +0 -1
- package/dist/docs/index.test.d.ts.map +0 -1
- package/dist/lib/action-harvest.test.d.ts.map +0 -1
- package/dist/lib/api-client.test.d.ts.map +0 -1
- package/dist/lib/artifact-routing.test.d.ts.map +0 -1
- package/dist/lib/auth.test.d.ts.map +0 -1
- package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
- package/dist/lib/compiler-floor.test.d.ts.map +0 -1
- package/dist/lib/config-id-splice.test.d.ts.map +0 -1
- package/dist/lib/config-sync.test.d.ts.map +0 -1
- package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
- package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
- package/dist/lib/file-loader.test.d.ts.map +0 -1
- package/dist/lib/file-writer.test.d.ts.map +0 -1
- package/dist/lib/helpers.d.ts +0 -39
- package/dist/lib/helpers.d.ts.map +0 -1
- package/dist/lib/helpers.js +0 -299
- package/dist/lib/helpers.js.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
- package/dist/lib/migrations/executor.test.d.ts.map +0 -1
- package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
- package/dist/lib/migrations/lock.test.d.ts.map +0 -1
- package/dist/lib/migrations/paths.test.d.ts.map +0 -1
- package/dist/lib/migrations/plan.test.d.ts.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/staging.test.d.ts.map +0 -1
- package/dist/lib/neon-canary.test.d.ts.map +0 -1
- package/dist/lib/neon-target.test.d.ts.map +0 -1
- package/dist/lib/neon.test.d.ts.map +0 -1
- package/dist/lib/prepare-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
- package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
- package/dist/lib/shell.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
|
@@ -121,10 +121,22 @@ All routes are `POST`, JSON in/out, mounted at `/seal/v1`, and require an authen
|
|
|
121
121
|
|
|
122
122
|
`enroll`, `grant`, `rotate`, and `revoke` are gated by **`hasKeyAdminForScope`**:
|
|
123
123
|
|
|
124
|
-
- `
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
124
|
+
- a verified `ctx.scope.seal` claim with `kind: "admin"`, **for the exact
|
|
125
|
+
`scopeRef`**, carrying a key-admin-tier scoped role (configurable via
|
|
126
|
+
`encryption.seal.keyAdminRoles`; the literal `"key-admin"` scoped role always
|
|
127
|
+
qualifies).
|
|
128
|
+
|
|
129
|
+
There is deliberately **no platform-role bypass**: `sysadmin`, infrastructure
|
|
130
|
+
credentials, and an organization role do not become a seal administrator. The
|
|
131
|
+
application must explicitly decide who may mint the short-lived, exact-scope
|
|
132
|
+
admin claim. Scoped roles live **only** on `ctx.scope.seal`, never `ctx.roles` —
|
|
133
|
+
a forged `ctx.roles` entry can't satisfy the gate. There is **no automatic**
|
|
134
|
+
role→grant: the server holds no key material, so it cannot wrap the scope key to
|
|
135
|
+
a new reader itself. Instead a reader self-publishes their public key via
|
|
136
|
+
[`/grant-request`](#10-grant-request--request-access-to-a-scope-any-member) and
|
|
137
|
+
a key-admin fulfils it via
|
|
138
|
+
[`/grant`](#7-grant--enroll-a-reader--store-their-wrapped-scope-key-key-admin) —
|
|
139
|
+
see [role→grant](#rolegrant-readers-request-key-admins-fulfil).
|
|
128
140
|
|
|
129
141
|
---
|
|
130
142
|
|
|
@@ -150,13 +162,19 @@ Trust-on-first-use: **first write wins**, never overwrites. Persists `seal_keys`
|
|
|
150
162
|
|
|
151
163
|
### 3. `/challenge` — issue a step-up nonce (any member)
|
|
152
164
|
|
|
153
|
-
A single-use, **(issuing-user, scopeRef, vaultItemId)-bound** nonce
|
|
165
|
+
A single-use, **(issuing-user, scopeRef, vaultItemId)-bound** nonce. The server
|
|
166
|
+
stores only its SHA-256 hash in the features database with a **120 s** expiry;
|
|
167
|
+
consumption is one conditional `DELETE … RETURNING`, so concurrent replays can
|
|
168
|
+
produce only one winner. It is bound to the item's owning scopeRef so it can
|
|
169
|
+
only answer a reveal for *that* item, and to the issuing user so another user
|
|
170
|
+
can't burn it.
|
|
154
171
|
|
|
155
172
|
```jsonc
|
|
156
173
|
// → { vaultItemId }
|
|
157
174
|
// ← { nonce: "<b64url 32B>", scopeRef, vaultItemId, expiresIn: 120 }
|
|
158
175
|
```
|
|
159
|
-
|
|
176
|
+
Sealed deployments still require KV for JWT revocation, but raw step-up nonces
|
|
177
|
+
are never stored there.
|
|
160
178
|
|
|
161
179
|
### 4. `/reveal` — prove step-up, mint a reveal token (reader)
|
|
162
180
|
|
|
@@ -177,11 +195,21 @@ Verifies the step-up proof, writes a **committed** append-only reveal-log row, t
|
|
|
177
195
|
```
|
|
178
196
|
Each reveal-log row (`requested` here, `delivered` at `/key`) is also written to the separate security-audit database as an `audit_events` row with `event_kind = 'vault_reveal'`, `action_name = 'vault-reveal:<phase>'`, `resource = 'vault_items'`, `operation = 'reveal' | 'key'`, the actor, org, and `vaultItemId`, and `metadata = { scopeRef, reauthMethod, ip, userAgent }`. No key material and no before-image. The write is fail-closed: if the audit binding is missing or the insert throws, no token is minted and no key is returned. A sealed column therefore always provisions the security-audit pipeline (`AUDIT_DB` on D1, the `audit` schema on Postgres), even with no unsafe actions or hard deletes.
|
|
179
197
|
|
|
180
|
-
Gates, all fail-closed and in order: **(a)** tenant load, **(b)** any presented
|
|
198
|
+
Gates, all fail-closed and in order: **(a)** tenant load, **(b)** any presented
|
|
199
|
+
`ctx.scope.seal` claim must be `kind: "reveal"`, carry the `reveal` role, and
|
|
200
|
+
match the item's exact `scopeRef` and `vaultItemId`, **(c)** structural step-up
|
|
201
|
+
(single-use nonce, bound message), **(d)** `assertGrantLive` (a live,
|
|
202
|
+
current-enrollment `seal_key_grant` for the scope, or a version-bound audience
|
|
203
|
+
`vault_grant`). Direct owner access is not an implicit reveal grant.
|
|
181
204
|
|
|
182
205
|
### 5. `/key` — fetch the wrapped key (bearer the reveal token)
|
|
183
206
|
|
|
184
|
-
The **separate** post-mint route (never folded into `/reveal`). Re-runs three
|
|
207
|
+
The **separate** post-mint route (never folded into `/reveal`). Re-runs three
|
|
208
|
+
independent gates — tenant, exact-item reveal capability (`ctx.scope.seal`
|
|
209
|
+
only), `assertGrantLive` (database read, **prior to and independent of** the KV
|
|
210
|
+
token-revocation check) — and also compares the capability's enrollment version
|
|
211
|
+
and random enrollment revision with the current live grant. It writes a
|
|
212
|
+
committed `delivered` reveal-log row and returns the still-wrapped material.
|
|
185
213
|
|
|
186
214
|
```jsonc
|
|
187
215
|
// → { vaultItemId } (Authorization: Bearer <revealToken>)
|
|
@@ -196,22 +224,32 @@ For `wrapMethod: "scope"`, the client first unwraps the scope private key with i
|
|
|
196
224
|
|
|
197
225
|
```jsonc
|
|
198
226
|
// → { scopeRef }
|
|
199
|
-
// ← { wrappedPrivateKey: "<qbseal envelope>", wrapMethod: "scope"
|
|
227
|
+
// ← { wrappedPrivateKey: "<qbseal envelope>", wrapMethod: "scope",
|
|
228
|
+
// enrollmentVersion, enrollmentRevision }
|
|
200
229
|
```
|
|
201
230
|
|
|
202
231
|
### 7. `/grant` — enroll a reader + store their wrapped scope key (key-admin)
|
|
203
232
|
|
|
204
|
-
The
|
|
233
|
+
The grant endpoint. The server **never wraps** — it persists the client-supplied
|
|
234
|
+
opaque blob. The user must already have a current framework-owned enrollment;
|
|
235
|
+
the grant copies that enrollment's monotonic version and random revision.
|
|
236
|
+
Exactly one live grant per `(scopeRef, userId)` (it revokes any prior live grant
|
|
237
|
+
first). Replacing enrollment makes every older grant and capability stale even
|
|
238
|
+
if two replacement attempts race on the human-readable version counter.
|
|
205
239
|
|
|
206
240
|
```jsonc
|
|
207
|
-
// → { scopeRef, userId,
|
|
241
|
+
// → { scopeRef, userId, userPublicKey: "<b64url X25519>",
|
|
242
|
+
// wrappedPrivateKey: "<qbseal envelope>", wrapMethod: "scope",
|
|
208
243
|
// wrapMeta?,
|
|
209
244
|
// // OPTIONAL passphrase-reveal enrollment (the step-up verifier):
|
|
210
245
|
// stepUp?: { kind: "passphrase", publicKey: "<b64url Ed25519>",
|
|
211
246
|
// salt: "<b64url>", argon2: { memoryKiB, iterations, parallelism } } }
|
|
212
247
|
// ← { granted: true, scopeRef, userId, stepUpEnrolled: boolean }
|
|
213
248
|
```
|
|
214
|
-
|
|
249
|
+
Legacy callers may still include `stepUp` for compatibility, but new clients
|
|
250
|
+
should use `/enrollment/replace` first. Argon2 parameters are floor-checked at
|
|
251
|
+
enrollment; the `stepUpPublicKey` and params are public verifier material, and
|
|
252
|
+
the passphrase never leaves the client.
|
|
215
253
|
|
|
216
254
|
### 8. `/revoke` — sever future access (key-admin)
|
|
217
255
|
|
|
@@ -246,6 +284,23 @@ A reader who has a role for a scope but no grant publishes their X25519 USER pub
|
|
|
246
284
|
```
|
|
247
285
|
The key-admin wraps the scope key to each `userPublicKey` and calls [`/grant`](#7-grant--enroll-a-reader--store-their-wrapped-scope-key-key-admin), which **auto-resolves** the matching pending request.
|
|
248
286
|
|
|
287
|
+
### Enrollment lifecycle — replace and inspect verifier material
|
|
288
|
+
|
|
289
|
+
`/enrollment/replace` is the single framework-owned mutation for changing a
|
|
290
|
+
reader's public enrollment material. In one database batch it:
|
|
291
|
+
|
|
292
|
+
1. advances `enrollmentVersion` and generates a fresh random
|
|
293
|
+
`enrollmentRevision`;
|
|
294
|
+
2. replaces the X25519 and Ed25519 public keys plus Argon2 parameters;
|
|
295
|
+
3. revokes the previous live scope grant; and
|
|
296
|
+
4. creates or refreshes the pending grant request for custodian approval.
|
|
297
|
+
|
|
298
|
+
The reader stays locked until a key-admin wraps and grants the scope key to the
|
|
299
|
+
new public key. `/enrollment/me` returns only the caller's current public
|
|
300
|
+
enrollment. `/enrollments` is key-admin-gated and returns public enrollment
|
|
301
|
+
material for the requested users. These routes never accept or return a
|
|
302
|
+
passphrase, USER private key, or unwrapped scope key.
|
|
303
|
+
|
|
249
304
|
### 12. `/recovery/enroll` — escrow the scope key under a recovery factor (key-admin)
|
|
250
305
|
|
|
251
306
|
A key-admin (holding the scope private key) wraps it to a client-held recovery factor and escrows the blob. The server stores only the opaque recovery-wrapped material — the factor, held by the client, is what makes it usable; the server can never unwrap it.
|
|
@@ -216,7 +216,10 @@ export default defineTable(guests, {
|
|
|
216
216
|
- **`onEnter` steps** run in the generated `execute`, *after* the
|
|
217
217
|
compiler-applied primary write (parent row first). `update` steps go
|
|
218
218
|
through the scoped db — cross-feature targets resolve automatically and
|
|
219
|
-
inherit the firewall. `enqueue` steps ride the after-commit effects queue
|
|
219
|
+
inherit the firewall. `enqueue` steps ride the after-commit effects queue
|
|
220
|
+
(`effects.enqueue(binding, message)`); in a [tenant
|
|
221
|
+
feature](/configure/tenant-databases#platform-queues) they go through the
|
|
222
|
+
object's outbox instead.
|
|
220
223
|
Substitution values are a strict allowlist — `$record.<col>`,
|
|
221
224
|
`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id` — always
|
|
222
225
|
parameterized, never interpolated into SQL.
|
|
@@ -89,7 +89,11 @@ What is the same on every provider:
|
|
|
89
89
|
- `OLD.column` / `NEW.column` references use **SQL column names**
|
|
90
90
|
(`deleted_at`, not `deletedAt`) and are validated against the table at
|
|
91
91
|
compile time.
|
|
92
|
-
- Optional `when:` is a SQL expression guard (`WHEN` clause)
|
|
92
|
+
- Optional `when:` is a SQL expression guard (`WHEN` clause) and must be
|
|
93
|
+
exactly **one expression**: the compile fails on a `;`, a comment, an
|
|
94
|
+
unbalanced parenthesis, `BEGIN`, an `END` that closes no `CASE`, or a
|
|
95
|
+
statement keyword (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`,
|
|
96
|
+
`PRAGMA`, …) outside a string literal. On Postgres it
|
|
93
97
|
cannot contain a subquery (`EXISTS (SELECT …)`, `IN (SELECT …)`, or a scalar
|
|
94
98
|
`(SELECT …)`) — Postgres refuses that at `CREATE TRIGGER` time, so the
|
|
95
99
|
compile fails instead. Keep the subquery-free conjuncts in `when:` and move
|
|
@@ -250,6 +254,49 @@ Drops never use `CASCADE` — an unexpected dependency fails loudly rather than
|
|
|
250
254
|
being swept — and Postgres trigger drops are guarded on `to_regclass`, so a
|
|
251
255
|
table the preceding schema migration removed does not break the cleanup.
|
|
252
256
|
|
|
257
|
+
### Tenant databases
|
|
258
|
+
|
|
259
|
+
With [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases), a
|
|
260
|
+
tenant table's `sql:` triggers install **inside each tenant object**, not on
|
|
261
|
+
the features D1. They are reinstalled whenever the trigger set changes, after
|
|
262
|
+
every tenant migration, and after a dump restore.
|
|
263
|
+
|
|
264
|
+
Its `handler:` triggers run in the tenant Worker only: they are emitted into
|
|
265
|
+
`src/tenant/trigger-hooks.ts`, and the edge registry (`src/lib/trigger-hooks.ts`)
|
|
266
|
+
holds only platform tables' handlers. Tenant handlers get the same checks as
|
|
267
|
+
tenant actions (no `env` bindings, no edge-only modules).
|
|
268
|
+
|
|
269
|
+
A trigger runs inside one SQLite database, so every table its body or `when:`
|
|
270
|
+
names must live in the **same object** as the trigger's table — the same
|
|
271
|
+
tenant, or the same partition kind. The compiler reads every table position
|
|
272
|
+
(`FROM` / `JOIN` lists, `INSERT INTO`, `UPDATE`, `DELETE FROM`, `x IN table`,
|
|
273
|
+
subqueries), splitting the text the way SQLite does, and fails the compile
|
|
274
|
+
with `TENANCY_TRIGGER_CROSS_OBJECT`, listing each offender, when one names a
|
|
275
|
+
platform table, another partition kind, or a table no feature declares
|
|
276
|
+
(names are matched by their SQL name, not the export name). Shapes it does
|
|
277
|
+
not model are refused, not passed: a schema-qualified name, a CTE, a
|
|
278
|
+
string literal in a table position, a table-valued function other than
|
|
279
|
+
`json_each` / `json_tree`, a statement keyword such as `DROP` or `PRAGMA`,
|
|
280
|
+
or unbalanced parentheses. This is a conservative check, not a full SQL
|
|
281
|
+
parser — if it refuses a body you know is local, rewrite it with plain
|
|
282
|
+
table names. A platform
|
|
283
|
+
table's trigger may not name a tenant table either. Carry a cross-object
|
|
284
|
+
effect in application code (`tenantRuntime(env).send(...)`).
|
|
285
|
+
|
|
286
|
+
```typescript
|
|
287
|
+
// features/tasks/tasks.ts — a tenant table: installs in every tenant object
|
|
288
|
+
beforeUpdate: [
|
|
289
|
+
{
|
|
290
|
+
name: 'lockDone',
|
|
291
|
+
when: `OLD.done = 1`,
|
|
292
|
+
sql: `SELECT RAISE(ABORT, 'QB_TRIGGER_REJECTED:TASK_DONE: done tasks are immutable');`,
|
|
293
|
+
},
|
|
294
|
+
],
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
`handler:` triggers on tenant tables are governed separately; see
|
|
298
|
+
[Tenant databases](/configure/tenant-databases#what-the-compiler-refuses).
|
|
299
|
+
|
|
253
300
|
## Handler triggers (`handler:`)
|
|
254
301
|
|
|
255
302
|
Handlers run at the same write chokepoint that powers audit stamping and
|
|
@@ -419,6 +466,13 @@ execute: async ({ db, effects }) => {
|
|
|
419
466
|
}
|
|
420
467
|
```
|
|
421
468
|
|
|
469
|
+
To send a queue message after commit, pass the binding and the message:
|
|
470
|
+
`effects.enqueue("COMMS_QUEUE", { type: "mail.send", … })` calls
|
|
471
|
+
`env.COMMS_QUEUE.send(message)` with the other effects. In a [tenant
|
|
472
|
+
feature](/configure/tenant-databases#platform-queues) the message goes through
|
|
473
|
+
the tenant object's outbox before the response instead, with `tenantId` and
|
|
474
|
+
`dedupeKey` stamped by the edge.
|
|
475
|
+
|
|
422
476
|
Effects enqueued by an `execute` that later throws are dropped. The context
|
|
423
477
|
also carries `now` — one ISO timestamp per invocation; prefer it over
|
|
424
478
|
`new Date().toISOString()`. See [Column types](/define/schema#decimals-dates-64-bit-integers-and-arrays) for
|
|
@@ -81,8 +81,10 @@ caller-generated UUID, ≤ 255 chars) to make the write safe to retry:
|
|
|
81
81
|
- A concurrent duplicate gets `409 IDEMPOTENCY_IN_PROGRESS`.
|
|
82
82
|
- Reusing a key for a *different* request (method/path) is a
|
|
83
83
|
`422 IDEMPOTENCY_KEY_REUSED`.
|
|
84
|
-
- Keys expire after **24 hours** (Stripe semantics); 5xx
|
|
85
|
-
responses release the lock instead of caching.
|
|
84
|
+
- Keys expire after **24 hours** (Stripe semantics); 5xx, `Set-Cookie` and
|
|
85
|
+
`Cache-Control: no-store` responses release the lock instead of caching. A
|
|
86
|
+
`no-store` response (a grant code, a token) is never stored for any caller,
|
|
87
|
+
so a retry re-runs the handler rather than replaying a secret.
|
|
86
88
|
|
|
87
89
|
The key is per **request**. For "this client-side record exists exactly
|
|
88
90
|
once" across sessions and devices, store a per-**row** token instead — see
|
|
@@ -97,7 +99,11 @@ before the stale-claim takeover, so a foreign caller can neither read nor
|
|
|
97
99
|
overwrite your claim.
|
|
98
100
|
|
|
99
101
|
**Unauthenticated requests carrying the header are rejected (400)** — an
|
|
100
|
-
anonymous caller has no principal to bind the claim to.
|
|
102
|
+
anonymous caller has no principal to bind the claim to. Better Auth's own
|
|
103
|
+
routes (`/auth/v1/*` and `/cli/*`) are the exception: Better Auth
|
|
104
|
+
authenticates them itself, so the header is ignored there rather than
|
|
105
|
+
rejected, and a client can attach it to every write. The operator endpoints
|
|
106
|
+
mounted under the auth prefix still honor it. A PUBLIC standalone
|
|
101
107
|
action may opt in explicitly:
|
|
102
108
|
|
|
103
109
|
```ts title="quickback/features/orders/actions/submitForm.ts"
|
|
@@ -71,9 +71,14 @@ Validation steps (in generated `src/middleware/auth.ts`):
|
|
|
71
71
|
3. Verify the EdDSA signature with jose against the keyring's public JWKS — cached per isolate, refetched at most once when a token names an unknown `kid` (key rotation). Only `EdDSA` is accepted, so alg-confusion is rejected by construction, and `iss` / `aud` are pinned to the compile-time constants
|
|
72
72
|
4. Check `exp` against the current time
|
|
73
73
|
5. On success: hydrate `AppContext` from claims (`sub`, `sid`, `orgId`, `role`, `userRole`, `email`, `name`) — no DB query
|
|
74
|
-
6. On failure for a token **this project minted** (rotated key, expired, tampered, revoked — recognised by the pinned `iss`,
|
|
74
|
+
6. On failure for a token **this project minted** (rotated key, expired, tampered, revoked — recognised by the pinned `iss`, through the same `isQuickbackJwt()` exported from `src/lib/jwt.ts`): **`401`** with `AUTH_INVALID_TOKEN` (`AUTH_EXPIRED` when `exp` has passed) and `WWW-Authenticate: Bearer error="invalid_token"`. No fall-through: a presented-and-bad credential is never treated as no credential, so clients can key "drop the cached token and re-mint" on 401 alone. A foreign JWT (an OAuth access token — same keyring, OAuth issuer) falls through to its own verifier — which is why [`auth.jwt.issuer`](/configure/auth#issuer-string--iss-claim) may never equal the OAuth issuer (compile error). A token that *verifies* but is not one this lane admits (a session user's scope token on a project without `auth.jwt`) is a good credential, not a bad one: it falls through to session auth
|
|
75
75
|
7. With no JWT at all: fall back to Better Auth's session cookie auth; if that succeeds, mint a fresh JWT and return it in the `set-auth-token` response header
|
|
76
76
|
|
|
77
|
+
> **Removed: legacy HS256 token shape**
|
|
78
|
+
>
|
|
79
|
+
> Nothing has minted an HS256 Quickback JWT since the keyring (0.66, 2026-09-17), and an HS256 token never verified. Since 0.72 the middleware no longer recognises the shape: an HS256 bearer carries no pinned `iss`, so it falls through like any unrecognised token. An authenticated route answers `401` (`AUTH_MISSING`) and a public route serves the anonymous principal. No signed-in user is affected: a client still holding an HS256 token was already unable to authenticate.
|
|
80
|
+
|
|
81
|
+
|
|
77
82
|
The Files worker (R2 uploads) runs the same verifier (`src/lib/jwt-verify.ts`) over the public keys it reads from the `jwks` table — no shared secret, no network round-trip to the auth API for file operations.
|
|
78
83
|
|
|
79
84
|
---
|
|
@@ -110,6 +115,8 @@ The fast-path is stateless by default: it verifies the signature and **trusts th
|
|
|
110
115
|
|
|
111
116
|
**Lower the TTL.** `auth.jwt.expiresIn: 30` gives a hard 30-second ceiling. Browser SPAs auto-refresh via `set-auth-token` on every authed call, so a low TTL is invisible to logged-in users; only stale server-to-server bearer tokens feel it.
|
|
112
117
|
|
|
118
|
+
An `expiresIn` above one day (`86400`) without `revocationCheck: 'kv'` compiles with a **warning**: nothing can revoke such a token before it expires, so a ban or sign-out would take up to that long to reach it.
|
|
119
|
+
|
|
113
120
|
**Or enable sub-TTL revocation.** Set `revocationCheck: 'kv'` (Cloudflare runtime only):
|
|
114
121
|
|
|
115
122
|
```ts title="quickback.config.ts"
|
|
@@ -133,6 +140,11 @@ Revocation stamps are written **automatically** on:
|
|
|
133
140
|
|
|
134
141
|
The generated `src/lib/jwt-revocation.ts` exports `revokeUserTokens`, `revokeMemberTokens`, and `revokeScopeTokens` for explicit calls from your own action code.
|
|
135
142
|
|
|
143
|
+
> **Retiring: `qbrev:scope`**
|
|
144
|
+
>
|
|
145
|
+
> The scope markers (`qbrev:scope`, written by `revokeScopeTokens` and by relationship-row changes) only deny scope tokens from `POST /scope/v1/enter`, `ctx.mintScope`, and namespace `mintScope: true`. Those mints are [deprecated](/define/scopes#migrating-to-instance-bound-oauth-tokens) in favour of instance-bound OAuth tokens, which re-prove the relationship at every refresh and on every request. `qbrev:scope` keeps working while scope tokens do, and is removed with them in a later major. `qbrev:sid`, `qbrev:user`, and `qbrev:member` stay: they are the only sub-TTL revocation for Quickback-minted JWTs, bound OAuth tokens included.
|
|
146
|
+
|
|
147
|
+
|
|
136
148
|
Independently of revocation, a JWT **never outlives the session it was minted from**: both the session-path mint (`set-auth-token`) and `GET /auth/v1/token` clamp `exp` to `min(now + expiresIn, session.expiresAt)`. A token minted in the last minutes of a session expires with it instead of running the full TTL.
|
|
137
149
|
|
|
138
150
|
> **Honest limits**
|
|
@@ -107,7 +107,7 @@ export default defineConfig({
|
|
|
107
107
|
});
|
|
108
108
|
```
|
|
109
109
|
|
|
110
|
-
`GET /
|
|
110
|
+
`GET /api/v1/organization/roster` then returns `{ data: [{ id, name, email, image, role }] }` for `ctx.activeOrgId`:
|
|
111
111
|
|
|
112
112
|
- **401** with no credentials, **403** `ACCESS_NO_ORG` with no active organization, **403** when the caller holds none of `access.roles`.
|
|
113
113
|
- It reads on the service lane and filters to the active organization in the query, because Postgres RLS lets a caller-scoped handle read only their own `users` row.
|
|
@@ -261,8 +261,8 @@ complete as a hand-written one. The rules:
|
|
|
261
261
|
`worker.vars` keeps production's other vars and overrides
|
|
262
262
|
`BETTER_AUTH_URL`. `requiredSecrets`, `workersDev`, `previewUrls`,
|
|
263
263
|
`placement` and the email binding are inherited unchanged.
|
|
264
|
-
- **Identity and state are never inherited.** `name`, `domain` /
|
|
265
|
-
`filesWorker`, `branch`, `worker.env`, and the stateful bindings `d1`, `kv`,
|
|
264
|
+
- **Identity and state are never inherited.** `name`, `accountId`, `domain` /
|
|
265
|
+
`domains`, `filesWorker`, `tenantWorker`, `branch`, `worker.env`, and the stateful bindings `d1`, `kv`,
|
|
266
266
|
`hyperdrive`, `queues`, `r2Buckets` and `rateLimits` must be restated. If
|
|
267
267
|
any were inherited, a staging deploy would run on production's script,
|
|
268
268
|
hostnames, or data. If one is missing, the usual per-target errors name it
|
|
@@ -272,6 +272,102 @@ complete as a hand-written one. The rules:
|
|
|
272
272
|
- **Chains are allowed. A cycle or an unknown parent is a compile error** that
|
|
273
273
|
names the chain (`staging → preview → staging`).
|
|
274
274
|
|
|
275
|
+
### A target in another Cloudflare account (`accountId`)
|
|
276
|
+
|
|
277
|
+
Set `accountId` on a target to deploy it into a different Cloudflare account
|
|
278
|
+
than the rest of the project. It emits `account_id` inside that target's
|
|
279
|
+
`[env.<name>]` stanza:
|
|
280
|
+
|
|
281
|
+
{/* doc-compile: skip — excerpt of the `environments` block; the full target contract is shown above. */}
|
|
282
|
+
```typescript title="quickback/quickback.config.ts"
|
|
283
|
+
providers: {
|
|
284
|
+
runtime: defineRuntime("cloudflare", { accountId: "0123456789abcdef0123456789abcdef" }),
|
|
285
|
+
// …
|
|
286
|
+
},
|
|
287
|
+
environments: {
|
|
288
|
+
dev: { name: "my-app-dev", worker: { /* … */ } }, // our account
|
|
289
|
+
acme: {
|
|
290
|
+
name: "my-app-acme",
|
|
291
|
+
accountId: "fedcba9876543210fedcba9876543210", // the client's account
|
|
292
|
+
worker: { /* … every binding id from the client's account … */ },
|
|
293
|
+
},
|
|
294
|
+
},
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
```toml title="wrangler.toml (generated)"
|
|
298
|
+
account_id = "0123456789abcdef0123456789abcdef"
|
|
299
|
+
|
|
300
|
+
[env.acme]
|
|
301
|
+
name = "my-app-acme"
|
|
302
|
+
account_id = "fedcba9876543210fedcba9876543210"
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Wrangler reads the `[env.*]` `account_id` before the top-level one and before
|
|
306
|
+
`CLOUDFLARE_ACCOUNT_ID`, so `npm run deploy:acme` and
|
|
307
|
+
`npm run db:migrate:acme:remote` (both pass `--env acme`) can only reach the
|
|
308
|
+
client's account. The managed files Worker's `wrangler.toml` gets the same
|
|
309
|
+
`account_id` per target.
|
|
310
|
+
|
|
311
|
+
The compile fails closed:
|
|
312
|
+
|
|
313
|
+
- `accountId` must be a Cloudflare account id: 32 lowercase hex characters.
|
|
314
|
+
The same rule applies to `providers.runtime.config.accountId`.
|
|
315
|
+
- Once any target sets `accountId`, every target must resolve an account —
|
|
316
|
+
its own, or `providers.runtime.config.accountId`. Without either, Wrangler
|
|
317
|
+
deploys into whichever account the credential selects.
|
|
318
|
+
- A target in an account other than the top-level one must declare every
|
|
319
|
+
account-scoped resource itself. A resource lives in exactly one account, so
|
|
320
|
+
the compile error lists everything missing at once:
|
|
321
|
+
*Environment acme deploys into Cloudflare account fedcba…, not the top-level
|
|
322
|
+
account, and a resource lives in exactly one account — so it must declare
|
|
323
|
+
its own: bindings.d1.auth.databaseId, bindings.d1.features.databaseId.*
|
|
324
|
+
- `extends` never copies `accountId`. A target extending a pinned target must
|
|
325
|
+
state its own `accountId` (the same id to stay in that account); omitting
|
|
326
|
+
it is a compile error, not a silent fallback to the top-level account.
|
|
327
|
+
- `quickback deploy --env <name>` refuses a `wrangler.toml` whose
|
|
328
|
+
`account_id` differs from the config (*Run quickback build before
|
|
329
|
+
deploying*), so a stale build cannot deploy into the previous account.
|
|
330
|
+
- `providers.runtime.config.accountId` must also be 32 lowercase hex. A value
|
|
331
|
+
in any other format, which Wrangler would reject at deploy, now fails the
|
|
332
|
+
compile.
|
|
333
|
+
- The brokered deploy (Quickback Start) refuses a project with a pinned
|
|
334
|
+
target (`environment-account-unsupported`). It deploys only into the
|
|
335
|
+
account you connected. Deploy pinned targets with `quickback deploy --env`
|
|
336
|
+
or Wrangler.
|
|
337
|
+
|
|
338
|
+
### Private deployment in a client's account
|
|
339
|
+
|
|
340
|
+
To run a client on their own Cloudflare account, add one environment per
|
|
341
|
+
client account:
|
|
342
|
+
|
|
343
|
+
1. Get a credential for their account: a scoped API token (Workers Scripts,
|
|
344
|
+
D1, R2, KV, and Workers Routes on their zone), or membership with a scoped
|
|
345
|
+
role.
|
|
346
|
+
2. Create their D1 databases, KV namespace, R2 buckets, and queues **in their
|
|
347
|
+
account**.
|
|
348
|
+
3. Add `environments.<client>` with `accountId`, its own `name`, `domains`,
|
|
349
|
+
and every resource id from step 2.
|
|
350
|
+
4. Set secrets per target: `wrangler secret put BETTER_AUTH_SECRET --env <client>`.
|
|
351
|
+
5. Deploy with that client's credential: `npm run db:migrate:<client>:remote`,
|
|
352
|
+
then `npm run deploy:<client>`.
|
|
353
|
+
|
|
354
|
+
Every client runs the same compiled bundle. Only the `[env.<client>]` stanza
|
|
355
|
+
differs.
|
|
356
|
+
|
|
357
|
+
Check one thing by hand: **a target without `accountId` deploys into
|
|
358
|
+
`providers.runtime.config.accountId`**. The compiler cannot tell a client
|
|
359
|
+
target from one of yours, so a client target that omits `accountId` compiles
|
|
360
|
+
cleanly and deploys into your account. Review every client target for it.
|
|
361
|
+
|
|
362
|
+
Hand-written Wrangler commands must pass `--env <client>` too —
|
|
363
|
+
`wrangler r2 bucket create … --env acme`, `wrangler secret put … --env acme`.
|
|
364
|
+
Without `--env`, Wrangler reads the top-level `account_id`.
|
|
365
|
+
|
|
366
|
+
The generated `drizzle.*.config.ts` files (`driver: "d1-http"`, used by
|
|
367
|
+
`drizzle-kit studio` / `push`) read `CLOUDFLARE_ACCOUNT_ID` from the shell and
|
|
368
|
+
the top-level D1 ids. They are not per-target. Do not loop them over client
|
|
369
|
+
targets; run D1 migrations with `npm run db:migrate:<client>:remote`.
|
|
370
|
+
|
|
275
371
|
### Queues and R2 buckets per target
|
|
276
372
|
|
|
277
373
|
Queue names and R2 bucket names are stateful, so repeating the primary value
|
|
@@ -344,7 +440,16 @@ The contract fails closed:
|
|
|
344
440
|
sharing a queue or bucket would hand a dev deploy production state.
|
|
345
441
|
- `requiredSecrets` and `rateLimits` must match the generated runtime
|
|
346
442
|
inventory exactly, so adding a feature tells you which override changed.
|
|
347
|
-
- `workersDev
|
|
443
|
+
- `workersDev` (`true` or `false`) and `previewUrls: false` must be explicit on each target. `workersDev: false` turns the target's `<name>.<account>.workers.dev` hostname off (and its tenant Worker's, with `tenancy.isolation: 'durable-object'`); the target then needs a hostname of its own (`domain` / `domains`, or an MCP server's public URL for that environment), or the config is refused.
|
|
444
|
+
- The top-level `name` in `wrangler.toml` is an inert placeholder,
|
|
445
|
+
`<name>-unselected`, and no target may use it. A bare or positional
|
|
446
|
+
`wrangler deploy` without `--env` therefore creates an unbound Worker under
|
|
447
|
+
that name. It cannot replace a real target, such as the one that deploys as
|
|
448
|
+
the project `name`. The managed files Worker gets `<name>-files-unselected`
|
|
449
|
+
the same way. The top level keeps only settings that bind nothing (`[dev]`,
|
|
450
|
+
`observability`, `placement`). Assets and cron triggers are emitted per
|
|
451
|
+
target. Workers AI, Vectorize and a separate realtime service are refused
|
|
452
|
+
with named environments until they have per-target config.
|
|
348
453
|
- Every custom domain the config generates must be claimed per target via
|
|
349
454
|
`domains` (`{ api: "api-dev.example.com" }`, or the bare `domain` shorthand
|
|
350
455
|
for a single-hostname project). Quickback emits no top-level `routes` block
|
|
@@ -352,6 +457,10 @@ The contract fails closed:
|
|
|
352
457
|
hostname on a dev deploy. Each target names its own all-in-one host with
|
|
353
458
|
`domains.primary`; none is inferred. See
|
|
354
459
|
[Named Environments](/configure/domains#named-environments).
|
|
460
|
+
- With `tenancy.isolation: 'durable-object'`, each target also names its own
|
|
461
|
+
tenant Worker (`tenantWorker.name`, plus `backupBucketName` when
|
|
462
|
+
`tenancy.backup` is set). See
|
|
463
|
+
[Database per Tenant](/configure/tenant-databases#named-environments).
|
|
355
464
|
|
|
356
465
|
Set secrets per target: `wrangler secret put BETTER_AUTH_SECRET --env dev`.
|
|
357
466
|
|
|
@@ -72,7 +72,9 @@ do in action files, so `../../db/schema` is the generated schema barrel.
|
|
|
72
72
|
with a single conflict-free `INSERT`, so two concurrent applies cannot both
|
|
73
73
|
run. An applied id answers `409 DATA_MIGRATION_ALREADY_APPLIED`.
|
|
74
74
|
- **Failures are recorded and retryable.** A thrown error marks the row
|
|
75
|
-
`failed`, with the message and log.
|
|
75
|
+
`failed`, with the message and log. Recognizable bound database values are
|
|
76
|
+
redacted from failure messages and logged errors before storage or response;
|
|
77
|
+
SQL placeholders and diagnostic names remain. The next `quickback migrate data` re-runs
|
|
76
78
|
it.
|
|
77
79
|
- **No implied transaction.** D1 has no transactions across statements, so
|
|
78
80
|
write migrations that are safe to re-run after a partial failure. Select
|
|
@@ -112,6 +112,10 @@ deploys through Wrangler as `attend-v2-dev` and `attend-v2-prod`:
|
|
|
112
112
|
> error, because there would be no single source of truth.
|
|
113
113
|
|
|
114
114
|
|
|
115
|
+
To deploy one target into a different Cloudflare account, such as a client's,
|
|
116
|
+
set `environments.<name>.accountId`. The rules are the same on Neon and D1 —
|
|
117
|
+
see [A target in another Cloudflare account](/platform/database/d1#a-target-in-another-cloudflare-account-accountid).
|
|
118
|
+
|
|
115
119
|
```typescript title="quickback/quickback.config.ts"
|
|
116
120
|
export default defineConfig({
|
|
117
121
|
name: "attend-v2",
|
|
@@ -203,6 +207,9 @@ placeholder state.
|
|
|
203
207
|
The environment contract is intentionally exact and fails closed:
|
|
204
208
|
|
|
205
209
|
- `workersDev: true` and `previewUrls: false` must be explicit for each target.
|
|
210
|
+
- The top-level `name` in `wrangler.toml` is an inert placeholder,
|
|
211
|
+
`<name>-unselected`, so a `wrangler deploy` without `--env` cannot replace
|
|
212
|
+
a real target. No target may use it.
|
|
206
213
|
- `worker.placement` (`{ mode }` or `{ region }`) sets that target's
|
|
207
214
|
[placement](/configure/providers#runtime-options); without it, the top-level
|
|
208
215
|
`providers.runtime.config.placement` is emitted for the target.
|
|
@@ -569,8 +576,9 @@ write it makes runs on the service lane. The predicate:
|
|
|
569
576
|
Everything else is **service-only** — deny-anon plus the bootstrap lane is the
|
|
570
577
|
entire policy set, and no caller-scoped handle can read a row either: `verification`,
|
|
571
578
|
`jwks`, the Better Auth rate-limit counters, `device_code`, the
|
|
572
|
-
`oauth_*` provider tables
|
|
573
|
-
tables
|
|
579
|
+
`oauth_*` provider tables, the `agent_*` / `approval_request` agent-auth
|
|
580
|
+
tables, `two_factor` (the `twoFactor` plugin's TOTP secrets and backup codes),
|
|
581
|
+
and `wallet_address` (`siwe`). Better Auth's own adapter always stamps the service marker, so its
|
|
574
582
|
reads and writes never consult any of this; the policies exist for the handles
|
|
575
583
|
that are *not* Better Auth.
|
|
576
584
|
|
|
@@ -75,6 +75,10 @@ export default defineQueue<ProcessMaterialMessage>({
|
|
|
75
75
|
| `name` | `string` | Yes | Handler identifier (used in logs) |
|
|
76
76
|
| `messageType` | `string` | Yes | Message type to match (e.g., `'process_material'`) |
|
|
77
77
|
| `description` | `string` | No | Human-readable description |
|
|
78
|
+
| `tenant` | `true` | No | Run inside the tenant object named by `message.tenantId` (`tenancy.isolation: 'durable-object'`). See [Tenant databases](/configure/tenant-databases#background-work). |
|
|
79
|
+
| `result` | `true` | No | A result job: called from edge code with `callTenantJob(env, tenantId, message, runId)`, which returns the handler's `result`. Needs `tenant: true` and `resultSchema`; never queued. See [Result jobs](/configure/tenant-databases#result-jobs). |
|
|
80
|
+
| `resultSchema` | `z.object(…)` | With `result` | Validates the returned `result` before it is recorded and returned (at most 256 KiB). `z.object` strips unknown keys; a strict object refuses them; passthrough / loose schemas fail the build. |
|
|
81
|
+
| `resultTtlSeconds` | number literal | No | Result jobs only: how long the object keeps a call's result so a repeated `runId` replays it. 60 to 604800 (7 days, the default); a short one suits read-only pulls such as exports. See [Result jobs](/configure/tenant-databases#result-jobs). |
|
|
78
82
|
| `execute` | `function` | Yes | Handler function |
|
|
79
83
|
|
|
80
84
|
## Execute Function
|
|
@@ -122,7 +126,7 @@ payload (e.g. `message.body.organizationId`).
|
|
|
122
126
|
|
|
123
127
|
## Constants and Imports
|
|
124
128
|
|
|
125
|
-
The compiler extracts top-level
|
|
129
|
+
The compiler extracts top-level declarations and imports from your handler file and includes them in the generated queue consumer:
|
|
126
130
|
|
|
127
131
|
```typescript
|
|
128
132
|
// services/queues/ingest.ts
|
|
@@ -147,9 +151,24 @@ export default defineQueue({
|
|
|
147
151
|
|
|
148
152
|
The compiler:
|
|
149
153
|
1. Extracts all `import` statements
|
|
150
|
-
2. Extracts top-level `const`
|
|
154
|
+
2. Extracts top-level `const` / `let`, `function`, `class`, `enum`, type alias
|
|
155
|
+
and interface declarations, in source order, before or after `defineQueue`
|
|
151
156
|
3. Inlines them in the generated queue consumer
|
|
152
157
|
|
|
158
|
+
Every handler file's declarations share one generated module, so names must be
|
|
159
|
+
unique across handler files (a clash fails the build). `var` is refused because
|
|
160
|
+
a repeated `var` would silently shadow another file's. Directives
|
|
161
|
+
(`'use strict'`) and ambient `declare global` / `declare module` blocks are
|
|
162
|
+
skipped. Any other top-level statement (a bare call, an `if` block) fails the
|
|
163
|
+
build with `Unsupported top-level statement in <file>:<line>`: move it into a
|
|
164
|
+
declaration or into `execute`. The same rules apply to schedule and inbound
|
|
165
|
+
email handlers.
|
|
166
|
+
|
|
167
|
+
`execute` must be written inline: an arrow function with a block body, an
|
|
168
|
+
expression body (`async ({ message }) => ({ success: true })`) or a method
|
|
169
|
+
(`async execute({ message }) { … }`). A shorthand `execute,` or a computed
|
|
170
|
+
`['execute']` key fails the build.
|
|
171
|
+
|
|
153
172
|
Write static relative imports from your authored file's location. For example,
|
|
154
173
|
from `quickback/services/queues/ingest.ts`, import a feature helper with
|
|
155
174
|
`../../features/materials/lib/process`. The compiler relocates that import to
|
|
@@ -244,24 +263,37 @@ const ingestQueueHandler = async (batch, env) => {
|
|
|
244
263
|
}
|
|
245
264
|
};
|
|
246
265
|
|
|
247
|
-
// Unified dispatcher
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
266
|
+
// Unified dispatcher: groups the delivery by body.type, so each handler
|
|
267
|
+
// gets a batch of only its own messages (simplified).
|
|
268
|
+
export const queue = async (incoming, env) => {
|
|
269
|
+
for (const [messageType, messages] of groupByType(incoming.messages)) {
|
|
270
|
+
const batch = queueSubBatch(incoming, messages); // ackAll/retryAll: these messages only
|
|
271
|
+
switch (messageType) {
|
|
272
|
+
case 'embedding':
|
|
273
|
+
await embeddingQueueHandler(batch, env);
|
|
274
|
+
break;
|
|
275
|
+
case 'process_material':
|
|
276
|
+
await ingestQueueHandler(batch, env);
|
|
277
|
+
break;
|
|
278
|
+
default:
|
|
279
|
+
console.warn('[Queue] Unknown message type:', messageType);
|
|
280
|
+
for (const msg of batch.messages) msg.ack();
|
|
281
|
+
}
|
|
261
282
|
}
|
|
262
283
|
};
|
|
263
284
|
```
|
|
264
285
|
|
|
286
|
+
One queue can carry several producers' messages, so a single delivery may mix
|
|
287
|
+
types. The dispatcher routes **per message**: it groups the batch by
|
|
288
|
+
`body.type` and calls each type's handler with a batch of only that type's
|
|
289
|
+
messages (`ackAll()` / `retryAll()` on it touch only those). A handler that
|
|
290
|
+
throws does not stop the other types; the first error is rethrown afterwards,
|
|
291
|
+
so the runtime retries every message no handler acked. Ack (or retry) every
|
|
292
|
+
message explicitly: one left to the runtime's implicit ack is redelivered when
|
|
293
|
+
another type's handler in the same delivery throws. With webhooks, webhook
|
|
294
|
+
deliveries are handled one by one and the rest go to this dispatcher as their
|
|
295
|
+
own batch.
|
|
296
|
+
|
|
265
297
|
## wrangler.toml Configuration
|
|
266
298
|
|
|
267
299
|
Configure your queues in wrangler.toml:
|
|
@@ -40,6 +40,22 @@ await ctx.env.EMBEDDINGS_QUEUE.send({
|
|
|
40
40
|
|
|
41
41
|
**Webhooks** are enqueued via `emitWebhookEvent()` — see [Outbound Webhooks](/platform/webhooks/outbound).
|
|
42
42
|
|
|
43
|
+
### From tenant code
|
|
44
|
+
|
|
45
|
+
With [database-per-tenant](/configure/tenant-databases) tenancy, tenant
|
|
46
|
+
actions and tenant jobs have no queue bindings. They send through the tenant
|
|
47
|
+
object's outbox instead, and the edge Worker delivers the message with
|
|
48
|
+
`tenantId` and a `dedupeKey` stamped:
|
|
49
|
+
|
|
50
|
+
{/* doc-compile: skip — tenant action body fragment */}
|
|
51
|
+
```typescript
|
|
52
|
+
tenantRuntime(env).enqueue("PROCESSING_QUEUE", { type: "process_material", materialId: input.materialId });
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Delivery is at least once; dedupe on `message.dedupeKey`. Only the project's
|
|
56
|
+
declared queue bindings are accepted. See
|
|
57
|
+
[Platform queues](/configure/tenant-databases#platform-queues).
|
|
58
|
+
|
|
43
59
|
## Chaining Queues
|
|
44
60
|
|
|
45
61
|
Queue handlers can publish to other queues for multi-stage pipelines:
|