@quickback-dev/cli 0.70.27 → 0.70.38
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/codex/AGENTS.md +290 -0
- 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/build.test.d.ts.map +1 -0
- package/dist/commands/codex.d.ts +16 -0
- package/dist/commands/codex.d.ts.map +1 -0
- package/dist/commands/codex.js +159 -0
- package/dist/commands/codex.js.map +1 -0
- package/dist/commands/compile.d.ts +62 -0
- package/dist/commands/compile.d.ts.map +1 -0
- package/dist/commands/compile.js +830 -0
- package/dist/commands/compile.js.map +1 -0
- package/dist/commands/compile.test.d.ts.map +1 -0
- 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/init.d.ts +6 -0
- package/dist/commands/init.d.ts.map +1 -0
- package/dist/commands/init.js +405 -0
- package/dist/commands/init.js.map +1 -0
- 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/migrate.test.d.ts.map +1 -0
- package/dist/commands/migrations.test.d.ts.map +1 -0
- package/dist/commands/push.test.d.ts.map +1 -0
- package/dist/commands/schema.test.d.ts.map +1 -0
- 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/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +672 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/docs/index.test.d.ts.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/action-harvest.test.d.ts.map +1 -0
- package/dist/lib/api-client.test.d.ts.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/artifact-routing.test.d.ts.map +1 -0
- package/dist/lib/auth.test.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
- package/dist/lib/compiler-floor.test.d.ts.map +1 -0
- 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/config-id-splice.test.d.ts.map +1 -0
- package/dist/lib/config-sync.test.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.test.d.ts.map +1 -0
- package/dist/lib/copy-source-apps.test.d.ts.map +1 -0
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +1 -0
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +1 -0
- 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/file-loader.test.d.ts.map +1 -0
- package/dist/lib/file-writer.test.d.ts.map +1 -0
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +1 -0
- package/dist/lib/migrations/drizzle.test.d.ts.map +1 -0
- package/dist/lib/migrations/executor.test.d.ts.map +1 -0
- package/dist/lib/migrations/inventory.test.d.ts.map +1 -0
- package/dist/lib/migrations/lock.test.d.ts.map +1 -0
- package/dist/lib/migrations/paths.test.d.ts.map +1 -0
- package/dist/lib/migrations/plan.test.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +1 -0
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +1 -0
- package/dist/lib/migrations/staging.test.d.ts.map +1 -0
- package/dist/lib/neon-canary.test.d.ts.map +1 -0
- package/dist/lib/neon-target.test.d.ts.map +1 -0
- package/dist/lib/neon.test.d.ts.map +1 -0
- 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/prepare-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts.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/schema-sync/index.test.d.ts.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/lib/shell.test.d.ts.map +1 -0
- package/dist/lib/sweep-stale.d.ts +25 -0
- package/dist/lib/sweep-stale.d.ts.map +1 -0
- package/dist/lib/sweep-stale.js +179 -0
- package/dist/lib/sweep-stale.js.map +1 -0
- package/dist/lib/sweep-stale.test.d.ts.map +1 -0
- package/dist/lib/wrangler-resources.test.d.ts.map +1 -0
- 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/providers.md +1 -0
- 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 +34 -2
- 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/sealed-protocol.md +111 -9
- 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/index.md +1 -0
- package/dist/skill/docs/platform/database/read-replication.md +257 -0
- package/dist/skill/docs/platform/database/using-d1.md +2 -1
- 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/providers.md +1 -0
- 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 +34 -2
- 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/sealed-protocol.md +111 -9
- 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/index.md +1 -0
- package/src/skill/docs/platform/database/read-replication.md +257 -0
- package/src/skill/docs/platform/database/using-d1.md +2 -1
- 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
|
@@ -34,6 +34,7 @@ All standard; no hand-rolled constructions. A conforming port maps each to its p
|
|
|
34
34
|
| Step-up proof | **Ed25519** sign/verify | over the [step-up message](#step-up-message) |
|
|
35
35
|
| Sealed box (wrap a key to a pubkey) | **X25519 ECDH → HKDF-SHA256 → AES-256-GCM** | see below |
|
|
36
36
|
| Content / key encryption | **AES-256-GCM** | 12-byte IV, 16-byte tag appended to ciphertext |
|
|
37
|
+
| Passkey PRF unlock (wrap the user master) | **HKDF-SHA256 → AES-256-GCM** | see [Multi-factor unlock](#multi-factor-unlock-passkey-prf) |
|
|
37
38
|
|
|
38
39
|
### Argon2id floor
|
|
39
40
|
|
|
@@ -243,22 +244,32 @@ A reader who has a role for a scope but no grant publishes their X25519 USER pub
|
|
|
243
244
|
```
|
|
244
245
|
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.
|
|
245
246
|
|
|
246
|
-
### 12. `/recovery/enroll` — escrow the scope key under a recovery
|
|
247
|
+
### 12. `/recovery/enroll` — escrow the scope key under a recovery factor (key-admin)
|
|
247
248
|
|
|
248
|
-
A key-admin (holding the scope private key) wraps it to a
|
|
249
|
+
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.
|
|
250
|
+
|
|
251
|
+
`wrapMethod` names the client-side wrap and defaults to `recovery-code`. One live recovery per **(scope key version, wrapMethod)**, so a passkey-wrapped recovery can sit next to the recovery code; re-enrolling the same method on the same key version is a 409 until it is revoked or the key rotates. `wrapMeta` is an optional JSON object the server stores verbatim and hands back at `/recovery/use` (public wrap material only — a credential id, salts, a label; capped at 4 KiB). The server never reads either field.
|
|
252
|
+
|
|
253
|
+
| `wrapMethod` | The blob is… |
|
|
254
|
+
|---|---|
|
|
255
|
+
| `recovery-code` (default) | the scope key wrapped to a key derived from a recovery code |
|
|
256
|
+
| `prf-aesgcm` | the scope key wrapped under a KEK derived from a WebAuthn PRF output (a hardware security key or a shared vault passkey); `wrapMeta` carries the credential id and salts the client needs to re-derive the KEK |
|
|
249
257
|
|
|
250
258
|
```jsonc
|
|
251
|
-
// → { scopeRef, wrappedPrivateKey: "<qbseal envelope,
|
|
252
|
-
// ← { enrolled: true, scopeRef, keyVersion: 1 }
|
|
259
|
+
// → { scopeRef, wrappedPrivateKey: "<qbseal envelope>", wrapMethod?: "recovery-code" | "prf-aesgcm", wrapMeta?: { … } }
|
|
260
|
+
// ← { enrolled: true, scopeRef, keyVersion: 1, wrapMethod: "recovery-code" }
|
|
253
261
|
```
|
|
254
262
|
|
|
255
|
-
### 13. `/recovery/use` — retrieve the recovery blob (key-admin)
|
|
263
|
+
### 13. `/recovery/use` — retrieve the recovery blob(s) (key-admin)
|
|
256
264
|
|
|
257
|
-
Returns the live recovery-wrapped scope key (and appends a `recovery` entry to the reveal log). The client unwraps it with
|
|
265
|
+
Returns the live recovery-wrapped scope key for the newest key version that has one (and appends a `recovery` entry to the reveal log). The client unwraps it with its recovery factor to recover the scope private key, then re-grants readers. The returned blobs are **useless without the factor** — the server gates *who* may fetch them, the factor gates whether one can be unwrapped.
|
|
266
|
+
|
|
267
|
+
Without `wrapMethod`, every live method for that key version rides along in `recoveries`, so a client can offer "use your security key or enter the recovery code" from one call; the top-level fields are the `recovery-code` row when one exists (wire-compatible with clients that predate `wrapMethod`). Pass `wrapMethod` to narrow to one method; 404 parity when none of that method is live.
|
|
258
268
|
|
|
259
269
|
```jsonc
|
|
260
|
-
// → { scopeRef }
|
|
261
|
-
// ← { scopeRef, keyVersion, wrappedPrivateKey: "<qbseal envelope>"
|
|
270
|
+
// → { scopeRef, wrapMethod?: "recovery-code" | "prf-aesgcm" }
|
|
271
|
+
// ← { scopeRef, keyVersion, wrappedPrivateKey: "<qbseal envelope>", wrapMethod, wrapMeta,
|
|
272
|
+
// recoveries: [{ wrapMethod, wrapMeta, wrappedPrivateKey }, …] } // 404 parity if none
|
|
262
273
|
```
|
|
263
274
|
|
|
264
275
|
#### role→grant: readers request, key-admins fulfil
|
|
@@ -274,10 +285,99 @@ When the passkey plugin is enabled, `/reveal` verifies a WebAuthn assertion whos
|
|
|
274
285
|
| `challenge` | the `/challenge` `nonce` **as the base64url string** (the client signs the b64url text, the server passes `expectedChallenge = nonce`) |
|
|
275
286
|
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the registrable host of `env.ACCOUNT_URL`, else the compile-time account origin (both emissions share one resolution, so they cannot skew) |
|
|
276
287
|
| `userVerification` | **required** (`requireUserVerification: true` — a reveal is a deliberate re-auth) |
|
|
277
|
-
| origin | the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin) |
|
|
288
|
+
| origin | any of: the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin), `https://<rpID>` (what an Apple associated-domain app asserts), and every entry of `encryption.seal.extraOrigins` (e.g. `android:apk-key-hash:<sha256>`) |
|
|
278
289
|
|
|
279
290
|
The credential is looked up in the **auth** database (`passkey` table) and the signature counter is clone-checked. Conformance for passkey is **verify-based** at the server; the client's job is to bind `challenge = nonce` exactly.
|
|
280
291
|
|
|
292
|
+
## Multi-factor unlock (passkey PRF)
|
|
293
|
+
|
|
294
|
+
The passphrase is one way to reach the USER keys; a passkey with the WebAuthn **PRF extension** is the other. The two converge on one secret — the 32-byte **user master** (the raw Argon2id output, before the HKDF split) — so either factor yields byte-identical keys:
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
master = Argon2id(passphrase, salt, params) deriveUserMaster
|
|
298
|
+
keys = HKDF-split(master) userKeysFromMaster (ed25519 / x25519, as above)
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
A PRF-capable passkey evaluates a per-credential pseudo-random function inside the authenticator, released only after user verification. The client wraps the master under a key derived from that output and stores the wrapped blob next to the enrollment. At reveal time **one ceremony** both proves the step-up (the assertion) and unlocks the keys (the PRF output) — no passphrase prompt. The server stores the blob as opaque ciphertext: it never sees the PRF output, the KEK, or the master.
|
|
302
|
+
|
|
303
|
+
### Derivation
|
|
304
|
+
|
|
305
|
+
```
|
|
306
|
+
prfSalt = SHA-256( utf8("qbseal-prf-salt-v1") ‖ utf8(orgId) ) ← extensions.prf.eval.first
|
|
307
|
+
prf = PRF(credential, prfSalt) ← 32 bytes, from the authenticator
|
|
308
|
+
|
|
309
|
+
binding = utf8(userId) ‖ 0x00 ‖ utf8(orgId) ‖ 0x00 ‖ utf8(credentialId)
|
|
310
|
+
|
|
311
|
+
KEK = HKDF-SHA256( ikm = prf, salt = kekSalt,
|
|
312
|
+
info = utf8("qbseal-prf-kek-v1") ‖ binding, L = 32 )
|
|
313
|
+
ct = AES-256-GCM( KEK, iv, plaintext = master, AAD = binding )
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
- `prfSalt` is **per org**, so one user's PRF outputs across orgs are unrelated. Pass the same salt at registration and every assertion.
|
|
317
|
+
- `credentialId` is the passkey's **base64url credential id string exactly as WebAuthn returns it** (`PublicKeyCredential.id`); it is never re-encoded. The envelope carries it verbatim so a client can pick the matching passkey before the ceremony.
|
|
318
|
+
- `kekSalt` is 32 fresh random bytes and `iv` 12; both are stored in the envelope. The `(userId, orgId, credentialId)` binding is in **both** the KEK info and the AAD, so a blob lifted from another user, org, or credential fails on the GCM tag. Open fails closed on any mismatch.
|
|
319
|
+
|
|
320
|
+
### Envelope
|
|
321
|
+
|
|
322
|
+
A `qbseal:1` envelope with a new `alg` — the wire version is unchanged and every existing decoder keeps accepting it structurally:
|
|
323
|
+
|
|
324
|
+
```jsonc
|
|
325
|
+
{ "alg": "prf-aesgcm",
|
|
326
|
+
"cred": "<credentialId, verbatim>",
|
|
327
|
+
"salt": "<base64url kekSalt, 32 bytes>",
|
|
328
|
+
"iv": "<base64url, 12 bytes>",
|
|
329
|
+
"ct": "<base64url AES-GCM ciphertext ‖ tag of the 32-byte master>" }
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### Client usage
|
|
333
|
+
|
|
334
|
+
```typescript
|
|
335
|
+
import { deriveUserMaster, prfSaltFor, wrapMasterWithPrf, SealClient } from './lib/seal-client';
|
|
336
|
+
|
|
337
|
+
// ENROLL the passkey as a second factor (once, with the passphrase in hand).
|
|
338
|
+
const master = deriveUserMaster(passphrase, salt, enrollment.argon2);
|
|
339
|
+
const reg = await startAuthentication({ optionsJSON: {
|
|
340
|
+
...options, extensions: { prf: { eval: { first: prfSaltFor(orgId) } } },
|
|
341
|
+
} });
|
|
342
|
+
const prf = new Uint8Array(reg.clientExtensionResults.prf!.results!.first);
|
|
343
|
+
const wrapped = await wrapMasterWithPrf({ master, prf, userId, orgId, credentialId: reg.id });
|
|
344
|
+
// store `wrapped` (opaque) alongside the user's enrollment
|
|
345
|
+
|
|
346
|
+
// REVEAL with the passkey only — no passphrase prompt.
|
|
347
|
+
const seal = new SealClient(transport);
|
|
348
|
+
const plaintext = await seal.revealWithPasskey({
|
|
349
|
+
scopeRef, vaultItemId,
|
|
350
|
+
getAssertion: async (nonce) => {
|
|
351
|
+
const a = await startAuthentication({ optionsJSON: {
|
|
352
|
+
challenge: nonce, rpId, userVerification: 'required',
|
|
353
|
+
extensions: { prf: { eval: { first: prfSaltFor(orgId) } } },
|
|
354
|
+
} });
|
|
355
|
+
return { assertion: a, prf: new Uint8Array(a.clientExtensionResults.prf!.results!.first) };
|
|
356
|
+
},
|
|
357
|
+
prfUnwrap: { wrapped, userId, orgId, credentialId, argon2: enrollment.argon2 },
|
|
358
|
+
});
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
`getAssertion` may still return the raw `AuthenticationResponseJSON` with a passphrase-derived `session` — the original signature is unchanged. When `prfUnwrap` is given and no `session`, the SDK opens the blob with the assertion's PRF output (`unwrapMasterWithPrf`), builds the session from the master (`sessionFromMaster`), and completes the unwrap; it fails closed if the assertion carried no PRF output. Only the assertion is sent to `/reveal` — the PRF output never leaves the client. The Swift (`KDF.deriveUserMaster`, `KDF.userKeysFromMaster`, `Prf`) and Kotlin (`Kdf.deriveUserMaster`, `Kdf.userKeysFromMaster`, `Prf`) SDKs expose the same primitives, vector-locked to the TS reference.
|
|
362
|
+
|
|
363
|
+
### Compiler support
|
|
364
|
+
|
|
365
|
+
- With **`encryption.seal.passkeyPrf: true`** the emitted `passkey({ rpID, origin })` plugin call adds `registration: { extensions: { prf: {} } }`, so sign-in passkeys are PRF-capable at creation and the same credential serves as the unlock factor — no second enrollment ceremony. It is off by default because it changes the registration ceremony for every passkey the project creates; authenticators without PRF ignore the flag. Creation-time PRF evaluation is optional in WebAuthn, so clients should still run one assertion with `prf.eval` after registration to obtain the output they wrap with.
|
|
366
|
+
- **Reveal-log honesty.** After a PRF unlock, follow-up reveals inside the client's unlock window present the Ed25519 `passphrase`-kind proof (the key came from the unwrapped master, not from a passphrase). The server records the proof kind it verified; it cannot see how the client obtained the key. A client may declare `stepUp.unlockedBy: 'passkey' | 'passphrase'` as an unverifiable hint, which the server records verbatim next to `reauthMethod` — treat it as telemetry, never as evidence.
|
|
367
|
+
- The reveal verify accepts assertions from native apps as well as the browser. `expectedOrigin` is the account origin, `https://<rpID>` (the origin Apple's `ASAuthorization` asserts for an associated-domain app), and anything listed in **`encryption.seal.extraOrigins`** — the home for Android's `android:apk-key-hash:<sha256>`:
|
|
368
|
+
|
|
369
|
+
```typescript
|
|
370
|
+
// quickback.config.ts (fragment)
|
|
371
|
+
encryption: {
|
|
372
|
+
seal: {
|
|
373
|
+
keyAdminRoles: ['owner', 'admin'],
|
|
374
|
+
extraOrigins: ['android:apk-key-hash:pNiP5iKyQ8JwgGOaKA1zGPUB3eTSh-f-5d7HsAwBGFQ'],
|
|
375
|
+
},
|
|
376
|
+
},
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
Entries must be non-empty strings without whitespace; duplicates are dropped. A browser origin other than the account origin cannot be smuggled in — the passkey plugin's own registration check already refuses credentials from it, so listing it here widens nothing.
|
|
380
|
+
|
|
281
381
|
## Conformance vectors
|
|
282
382
|
|
|
283
383
|
Canonical vectors live at **`packages/seal-client/vectors/qbseal-v1.json`**, generated from the reference TS SDK (`bun packages/seal-client/scripts/generate-vectors.ts`) and self-validated against it (`src/vectors.test.ts`). Every input (passphrase, salt, key seeds, IVs, ephemerals) is fixed, so the file is byte-stable and each vector reproduces from its inputs alone.
|
|
@@ -291,6 +391,8 @@ Canonical vectors live at **`packages/seal-client/vectors/qbseal-v1.json`**, gen
|
|
|
291
391
|
| `sealedBoxOpen` | recipient secret + box → plaintext | open-direction (canonical) |
|
|
292
392
|
| `reveal` | passphrase → keys; owner + scope unwrap paths → plaintext | open-direction (canonical) |
|
|
293
393
|
| `envelope` | `qbseal:1:` sealed-cell decodes structurally | full |
|
|
394
|
+
| `masterSplit` | passphrase → the 32-byte master; master → the `kdf` public keys | full |
|
|
395
|
+
| `prfWrap` | `prfSaltFor(orgId)`; pinned prf + kekSalt + iv + ids → the `prf-aesgcm` envelope; a `wrongCredentialId` that must NOT open it | full (wrap is pinned by fixed salt/iv) |
|
|
294
396
|
|
|
295
397
|
A port verifies the open-direction vectors exactly, and proves its *seal* direction by round-tripping through its own open. Vectors are the **cross-language byte-for-byte guarantee** — CI runs every client (TypeScript, Swift, and Kotlin) against this one file and fails on drift.
|
|
296
398
|
|
|
@@ -127,6 +127,45 @@ Semantics:
|
|
|
127
127
|
writes into a `q.timestamp()` column as-is, on every database and every
|
|
128
128
|
`db` handle — see [Column types](/define/schema#decimals-dates-64-bit-integers-and-arrays).
|
|
129
129
|
|
|
130
|
+
### Concurrency: the guard is in the UPDATE
|
|
131
|
+
|
|
132
|
+
D1 has no transaction across statements, so a transition that read the row
|
|
133
|
+
and then wrote it by id would let two concurrent requests both succeed (two
|
|
134
|
+
scanners checking in one guest). The compiler-applied write never does that:
|
|
135
|
+
the UPDATE itself carries the state it checked.
|
|
136
|
+
|
|
137
|
+
```sql
|
|
138
|
+
-- field transition (close: open → closed)
|
|
139
|
+
UPDATE tickets SET status = 'closed', modified_at = ?, …
|
|
140
|
+
WHERE <firewall> AND id = ? AND status = 'open' -- the from-state it read
|
|
141
|
+
RETURNING *;
|
|
142
|
+
|
|
143
|
+
-- stamp-only transition (checkIn, guard: { checkedInAt: { null: true } })
|
|
144
|
+
UPDATE guests SET checked_in_at = ?, checked_in_by_id = ?, …
|
|
145
|
+
WHERE <firewall> AND id = ? AND status = 'confirmed' AND checked_in_at IS NULL
|
|
146
|
+
RETURNING *;
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The WHERE pins the exact value the pre-check saw (a compare-and-set), which is
|
|
150
|
+
stricter than `status IN (<every from-state>)`: if a twin moved the row
|
|
151
|
+
between two legal source states, the stale request loses instead of acting on
|
|
152
|
+
a row it never checked. When two requests race:
|
|
153
|
+
|
|
154
|
+
- one UPDATE matches and wins (`200`);
|
|
155
|
+
- the other sees the new state in its pre-check (`409
|
|
156
|
+
ACCESS_ACTION_NOT_ALLOWED_FOR_STATE` / `onIllegal`), or matches no row at the
|
|
157
|
+
UPDATE (`409 ACCESS_TRANSITION_LOST`);
|
|
158
|
+
- with `idempotent: "noop"`, a request that loses to a twin that already
|
|
159
|
+
reached the target answers `{ success: true, unchanged: true }`, exactly as
|
|
160
|
+
if it had arrived second.
|
|
161
|
+
|
|
162
|
+
This holds for every table-level transition (the compiler always applies the
|
|
163
|
+
write) and every action-level `transition` with `stamp`, `clears`,
|
|
164
|
+
`applyBefore: true` or no `execute`. A hand-written `execute` that does its own
|
|
165
|
+
write must use `whereTransition(table)` in its WHERE and throw
|
|
166
|
+
`TransitionLostError` on an empty `RETURNING` — a write by `whereRecord` alone
|
|
167
|
+
is the race.
|
|
168
|
+
|
|
130
169
|
### On a feature-area route
|
|
131
170
|
|
|
132
171
|
A transition normally lives on a table-bound record action (`POST /:id/{action}`).
|
|
@@ -318,11 +318,12 @@ Response now carries the aggregations alongside `data`:
|
|
|
318
318
|
| `count` | optional | `COUNT(*)` if omitted, `COUNT(field)` (non-null) if given | `{ fn: 'count' }` |
|
|
319
319
|
| `count_distinct` | required | scalar number | `{ fn: 'count_distinct', field: 'sourceId' }` |
|
|
320
320
|
| `groupBy` | required | `{ value: count }` map | `{ fn: 'groupBy', field: 'status' }` |
|
|
321
|
+
| `rollup` | — (`groupBy`, `count`, `sum`) | array of bucket rows | `{ fn: 'rollup', groupBy: 'optionId', count: true, sum: ['weight'] }` |
|
|
321
322
|
|
|
322
323
|
`groupBy` always returns a count map keyed by the distinct values of `field`.
|
|
323
|
-
`NULL` values bucket under the literal string `"(none)"`.
|
|
324
|
-
|
|
325
|
-
|
|
324
|
+
`NULL` values bucket under the literal string `"(none)"`. To sum other
|
|
325
|
+
columns per bucket, use a [declared rollup](#declared-rollups-fn-rollup) on
|
|
326
|
+
an aggregate-only view.
|
|
326
327
|
|
|
327
328
|
### Filter and firewall inheritance
|
|
328
329
|
|
|
@@ -427,6 +428,79 @@ buckets ("1 guest, allergy = shellfish"):
|
|
|
427
428
|
row-returning views, where the aggregations ride alongside the rows and the
|
|
428
429
|
row firewall already governs disclosure.
|
|
429
430
|
|
|
431
|
+
### Declared rollups (`fn: 'rollup'`)
|
|
432
|
+
|
|
433
|
+
A rollup is the grouped aggregate an action would otherwise compute in
|
|
434
|
+
JavaScript — and actions can't run raw aggregates. It emits one firewalled
|
|
435
|
+
`SELECT <groupBy>, COUNT(*), SUM(<col>)… GROUP BY <groupBy>` over the view's
|
|
436
|
+
filtered set, and each returned row carries the bucket and its totals — never
|
|
437
|
+
a row id or a subject. A caller who may not read individual ballots can read
|
|
438
|
+
the tally if the view's `access` admits them:
|
|
439
|
+
|
|
440
|
+
```typescript
|
|
441
|
+
import { feature, q } from '@quickback/compiler';
|
|
442
|
+
|
|
443
|
+
export default feature('votes', {
|
|
444
|
+
columns: {
|
|
445
|
+
id: q.id(),
|
|
446
|
+
pollId: q.text().required(),
|
|
447
|
+
optionId: q.text().required(),
|
|
448
|
+
weight: q.int().default(1).required(),
|
|
449
|
+
organizationId: q.scope('organization'),
|
|
450
|
+
...q.audit(),
|
|
451
|
+
...q.softDelete(),
|
|
452
|
+
},
|
|
453
|
+
guards: { createable: ['pollId', 'optionId', 'weight'], updatable: [] },
|
|
454
|
+
read: {
|
|
455
|
+
access: { roles: ['admin'] }, // individual ballots: admins only
|
|
456
|
+
views: {
|
|
457
|
+
tally: {
|
|
458
|
+
aggregateOnly: true,
|
|
459
|
+
fields: [],
|
|
460
|
+
kMin: 1, // a poll tally may show single votes
|
|
461
|
+
access: { roles: ['member', 'admin'] },
|
|
462
|
+
query: { filterable: ['pollId'] },
|
|
463
|
+
aggregations: {
|
|
464
|
+
tally: { fn: 'rollup', groupBy: 'optionId', count: true, sum: ['weight'] },
|
|
465
|
+
},
|
|
466
|
+
},
|
|
467
|
+
},
|
|
468
|
+
},
|
|
469
|
+
create: { access: { roles: ['member', 'admin'] } },
|
|
470
|
+
update: { access: { roles: ['admin'] } },
|
|
471
|
+
delete: { access: { roles: ['admin'] }, mode: 'soft' },
|
|
472
|
+
});
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
`GET /api/v1/votes/views/tally?pollId=p1` returns:
|
|
476
|
+
|
|
477
|
+
```json
|
|
478
|
+
{
|
|
479
|
+
"view": "tally",
|
|
480
|
+
"aggregations": {
|
|
481
|
+
"tally": [
|
|
482
|
+
{ "optionId": "opt_a", "count": 12, "sum": { "weight": 15 } },
|
|
483
|
+
{ "optionId": "opt_b", "count": 7, "sum": { "weight": 7 } }
|
|
484
|
+
]
|
|
485
|
+
}
|
|
486
|
+
}
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
- `groupBy` names one column; `count: true` adds the bucket size; `sum` lists
|
|
490
|
+
numeric columns, returned under `sum`. At least one of `count` / `sum`.
|
|
491
|
+
- Only on `aggregateOnly: true` views — a rollup is its own surface, gated by
|
|
492
|
+
its own `access`, never a side-channel of a row view. `kMin` applies:
|
|
493
|
+
buckets smaller than k fold into one `"(other)"` row, and a non-empty set
|
|
494
|
+
smaller than k returns `"(suppressed)"`.
|
|
495
|
+
- **The bucket may not identify a subject.** Grouping by the primary key, the
|
|
496
|
+
owner column, a `q.stamp()` identity column, `createdBy` / `modifiedBy` /
|
|
497
|
+
`deletedBy`, a reference to the auth user table, or an encrypted column is
|
|
498
|
+
a compile error — one bucket per subject is a per-subject read.
|
|
499
|
+
- A masked `groupBy` or `sum` column needs every role that can reach the view
|
|
500
|
+
to be in its masking query roles (the `groupBy` / `min` / `max` rule
|
|
501
|
+
above), and at request time a caller who may not query one of them gets
|
|
502
|
+
`"(suppressed)"`.
|
|
503
|
+
|
|
430
504
|
## Response Format
|
|
431
505
|
|
|
432
506
|
View responses include metadata about the view:
|
|
@@ -84,6 +84,10 @@ caller-generated UUID, ≤ 255 chars) to make the write safe to retry:
|
|
|
84
84
|
- Keys expire after **24 hours** (Stripe semantics); 5xx and `Set-Cookie`
|
|
85
85
|
responses release the lock instead of caching.
|
|
86
86
|
|
|
87
|
+
The key is per **request**. For "this client-side record exists exactly
|
|
88
|
+
once" across sessions and devices, store a per-**row** token instead — see
|
|
89
|
+
[Row-token idempotency](/api/crud#row-token-idempotency).
|
|
90
|
+
|
|
87
91
|
**Claims are bound to the calling principal.** A replay from a different
|
|
88
92
|
principal — another user, another scope subject, a delegated machine
|
|
89
93
|
principal, or a legacy row with no principal — is refused with a `422`
|
|
@@ -125,6 +125,8 @@ There is no same-second gap: markers are epoch milliseconds (written `m<ms>`), t
|
|
|
125
125
|
Revocation stamps are written **automatically** on:
|
|
126
126
|
|
|
127
127
|
- user ban
|
|
128
|
+
- the target of the admin plugin's `/admin/set-role`, `/admin/remove-user`, `/admin/update-user`, and `/admin/revoke-user-sessions`
|
|
129
|
+
- every [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound) write (ban, role change, account deletion)
|
|
128
130
|
- org-member removal and member role change (Better Auth `organizationHooks`)
|
|
129
131
|
- `UPDATE` / `DELETE` of scope-conferring relationship rows
|
|
130
132
|
|
|
@@ -80,16 +80,17 @@ const esc = (v: string) =>
|
|
|
80
80
|
.replace(/"/g, '"').replace(/'/g, ''');
|
|
81
81
|
|
|
82
82
|
export default function welcomeTemplate({ otp, name, appName, appUrl }: Input) {
|
|
83
|
-
|
|
83
|
+
// Plain text: TEMPLATE_UNESCAPED skips names containing `text`, `subject`, or `plain`.
|
|
84
|
+
const greetingText = name ? `Hi ${name},` : "Hi,";
|
|
84
85
|
return {
|
|
85
86
|
subject: `Welcome to ${appName} — set your password`,
|
|
86
87
|
html: `
|
|
87
88
|
<h1>Welcome to ${esc(appName)}</h1>
|
|
88
|
-
<p>${esc(
|
|
89
|
+
<p>${esc(greetingText)} your account is ready. Use this code to set your password and sign in:</p>
|
|
89
90
|
<p style="font-size:32px;letter-spacing:8px"><b>${esc(otp)}</b></p>
|
|
90
91
|
<p>Visit <a href="${esc(appUrl)}/set-password">${esc(appUrl)}/set-password</a> to finish setup.</p>
|
|
91
92
|
`,
|
|
92
|
-
text: `${
|
|
93
|
+
text: `${greetingText}\n\nYour ${appName} code: ${otp}\n\nFinish setup at ${appUrl}/set-password`,
|
|
93
94
|
};
|
|
94
95
|
}
|
|
95
96
|
```
|
|
@@ -114,6 +114,12 @@ export default defineConfig({
|
|
|
114
114
|
- The column set is fixed. Sessions, accounts and credentials are never returned.
|
|
115
115
|
- `roles` is required, and the organization plugin must be enabled — otherwise the compile fails.
|
|
116
116
|
|
|
117
|
+
## Changing users from actions — `ctx.auth`
|
|
118
|
+
|
|
119
|
+
Action code that bans a user, changes a member's role, deletes an account, or lists an organization's members uses `ctx.auth` — typed, bound to the caller's active organization, written through Better Auth's adapter, and stamping the `qbrev:user` [revocation entry](/configure/auth#revocationcheck-none--kv--token-revocation-strategy) so outstanding JWTs die. Never write the auth tables through `authDb`. Full reference: [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound).
|
|
120
|
+
|
|
121
|
+
Rows addressed to an email before the account exists (invitations, guest lists) can be linked automatically when the account verifies that email: [`auth.claims`](/configure/auth#authclaims--link-rows-to-the-account-that-verifies-their-email).
|
|
122
|
+
|
|
117
123
|
## Related
|
|
118
124
|
|
|
119
125
|
- [Auth Overview](/platform/auth) — Setup and configuration
|
|
@@ -225,6 +225,53 @@ binding name unchanged across environments; only the stateful identifiers —
|
|
|
225
225
|
`database_id`, queue names, bucket names (and optionally `database_name`) —
|
|
226
226
|
are per-environment.
|
|
227
227
|
|
|
228
|
+
### Inheriting from another target (`extends`)
|
|
229
|
+
|
|
230
|
+
A staging target is usually production with different identities. Instead of
|
|
231
|
+
copying production's block, extend it and list only what differs:
|
|
232
|
+
|
|
233
|
+
{/* doc-compile: skip — excerpt of the `environments` block; `production` is the entry shown above. */}
|
|
234
|
+
```typescript title="quickback/quickback.config.ts"
|
|
235
|
+
environments: {
|
|
236
|
+
production: { /* … as above … */ },
|
|
237
|
+
staging: {
|
|
238
|
+
extends: "production",
|
|
239
|
+
name: "my-app-staging",
|
|
240
|
+
domain: "api-staging.example.com",
|
|
241
|
+
worker: {
|
|
242
|
+
env: "staging",
|
|
243
|
+
vars: { BETTER_AUTH_URL: "https://api-staging.example.com" },
|
|
244
|
+
bindings: {
|
|
245
|
+
d1: {
|
|
246
|
+
auth: { databaseId: "…" },
|
|
247
|
+
features: { databaseId: "…" },
|
|
248
|
+
},
|
|
249
|
+
},
|
|
250
|
+
},
|
|
251
|
+
},
|
|
252
|
+
},
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
The compiler resolves `extends` before anything else reads the config. The
|
|
256
|
+
validator, the `[env.*]` emitter, the hostname resolver, and the ops manifest
|
|
257
|
+
all see one complete target, so the generated `[env.staging]` stanza is as
|
|
258
|
+
complete as a hand-written one. The rules:
|
|
259
|
+
|
|
260
|
+
- **Objects merge key by key, arrays and scalars replace.** In the example,
|
|
261
|
+
`worker.vars` keeps production's other vars and overrides
|
|
262
|
+
`BETTER_AUTH_URL`. `requiredSecrets`, `workersDev`, `previewUrls`,
|
|
263
|
+
`placement` and the email binding are inherited unchanged.
|
|
264
|
+
- **Identity and state are never inherited.** `name`, `domain` / `domains`,
|
|
265
|
+
`filesWorker`, `branch`, `worker.env`, and the stateful bindings `d1`, `kv`,
|
|
266
|
+
`hyperdrive`, `queues`, `r2Buckets` and `rateLimits` must be restated. If
|
|
267
|
+
any were inherited, a staging deploy would run on production's script,
|
|
268
|
+
hostnames, or data. If one is missing, the usual per-target errors name it
|
|
269
|
+
(for example, *must declare bindings.d1.features.databaseId*). When
|
|
270
|
+
production gains a new database role, every child that has not restated it
|
|
271
|
+
fails the compile, so a staging target cannot silently drift.
|
|
272
|
+
- **Chains are allowed. A cycle or an unknown parent is a compile error** that
|
|
273
|
+
names the chain (`staging → preview → staging`).
|
|
274
|
+
|
|
228
275
|
### Queues and R2 buckets per target
|
|
229
276
|
|
|
230
277
|
Queue names and R2 bucket names are stateful, so repeating the primary value
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Data Migrations
|
|
2
|
+
|
|
3
|
+
Schema migrations change the **shape** of your tables, and Drizzle generates
|
|
4
|
+
them for you. Data migrations change the **rows**: a backfill, a repair, a
|
|
5
|
+
one-time move. You write them as ordinary TypeScript under
|
|
6
|
+
`quickback/migrations/data/`, and `quickback migrate data` runs them inside the
|
|
7
|
+
deployed Worker for one environment.
|
|
8
|
+
|
|
9
|
+
```ts title="quickback/migrations/data/2026-10-21-archive-stale-drafts.ts"
|
|
10
|
+
import { defineDataMigration } from "@quickback/compiler";
|
|
11
|
+
import { and, eq, isNull } from "drizzle-orm";
|
|
12
|
+
import { projects } from "../../db/schema";
|
|
13
|
+
|
|
14
|
+
export default defineDataMigration({
|
|
15
|
+
id: "2026-10-21-archive-stale-drafts",
|
|
16
|
+
databases: ["DB"],
|
|
17
|
+
description: "Archive draft projects that never got a budget",
|
|
18
|
+
async run({ db, dryRun, log }) {
|
|
19
|
+
const stale = await db
|
|
20
|
+
.select({ id: projects.id })
|
|
21
|
+
.from(projects)
|
|
22
|
+
.where(and(eq(projects.status, "draft"), isNull(projects.budget)));
|
|
23
|
+
log(`${stale.length} stale draft project(s)`);
|
|
24
|
+
if (dryRun) return;
|
|
25
|
+
for (const row of stale) {
|
|
26
|
+
await db.update(projects).set({ status: "archived" }).where(eq(projects.id, row.id));
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
});
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Declare who may run them. There is no default role:
|
|
33
|
+
|
|
34
|
+
{/* doc-compile: skip — excerpt of the top-level `dataMigrations` key; the rest of `defineConfig` is unchanged. */}
|
|
35
|
+
```ts title="quickback/quickback.config.ts"
|
|
36
|
+
dataMigrations: {
|
|
37
|
+
access: { userRole: ["sysadmin"] },
|
|
38
|
+
},
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Then deploy and run:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
quickback deploy --env staging
|
|
45
|
+
quickback migrate data --env staging # dry run: logs, writes nothing
|
|
46
|
+
quickback migrate data --env staging --apply # writes, records the id
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## The definition
|
|
50
|
+
|
|
51
|
+
| Field | |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `id` | Ledger key, as a string literal. It runs once per environment. Ids run in sorted order, so start them with a date. |
|
|
54
|
+
| `databases` | Database bindings the migration touches (`["DB"]`). `db` is the first one, and `dbs[binding]` gives each. On D1 with split databases, the auth binding (`AUTH_DB`) is also allowed. |
|
|
55
|
+
| `description` | Shown by `quickback migrate data`. |
|
|
56
|
+
| `run({ db, dbs, env, dryRun, log })` | The work. `log()` lines (up to 500) go to the CLI and the ledger row. |
|
|
57
|
+
|
|
58
|
+
The compiler reads `id` and `databases` statically. A computed id, an unknown
|
|
59
|
+
binding, a duplicate id, or a missing `run` is a compile error that names the
|
|
60
|
+
file. From `@quickback/compiler` you may import only `defineDataMigration` (and
|
|
61
|
+
types). Relative imports resolve against the generated tree the same way they
|
|
62
|
+
do in action files, so `../../db/schema` is the generated schema barrel.
|
|
63
|
+
|
|
64
|
+
## Guarantees
|
|
65
|
+
|
|
66
|
+
- **Dry run by default.** Without `--apply`, the runner calls
|
|
67
|
+
`run({ dryRun: true })`, and every write method on the handle (`insert`,
|
|
68
|
+
`update`, `delete`, `batch`, `run`, `execute`, `transaction`) throws. A
|
|
69
|
+
migration that forgets to check `dryRun` fails loudly instead of writing.
|
|
70
|
+
- **Once per environment.** Each target's features database has its own
|
|
71
|
+
`_qb_data_migrations` ledger. Before `run` starts, `--apply` claims the id
|
|
72
|
+
with a single conflict-free `INSERT`, so two concurrent applies cannot both
|
|
73
|
+
run. An applied id answers `409 DATA_MIGRATION_ALREADY_APPLIED`.
|
|
74
|
+
- **Failures are recorded and retryable.** A thrown error marks the row
|
|
75
|
+
`failed`, with the message and log. The next `quickback migrate data` re-runs
|
|
76
|
+
it.
|
|
77
|
+
- **No implied transaction.** D1 has no transactions across statements, so
|
|
78
|
+
write migrations that are safe to re-run after a partial failure. Select
|
|
79
|
+
what still needs changing, as in the example above.
|
|
80
|
+
- **Audited.** When the project has the audit wrapper, writes are stamped
|
|
81
|
+
`system:data-migration-<id>`, and the ledger row records the operator's
|
|
82
|
+
user id. With [release stamping](/start/deploy#release-stamps) on, it also
|
|
83
|
+
records the release that applied the migration.
|
|
84
|
+
|
|
85
|
+
## Why it runs in the Worker
|
|
86
|
+
|
|
87
|
+
The runner is a route the compiler mounts at
|
|
88
|
+
`/api/v1/system/data-migrations`, gated to `dataMigrations.access.userRole`.
|
|
89
|
+
It is not a local script, and it is not a separate Wrangler entrypoint. The
|
|
90
|
+
Worker is the one place where both database families are reachable through the
|
|
91
|
+
bindings the app itself uses. Code outside a Worker cannot run JavaScript
|
|
92
|
+
against a D1 binding, and a Postgres database behind Hyperdrive is only
|
|
93
|
+
reachable from inside the Worker. The runner uses the same service handle as
|
|
94
|
+
cron and queue handlers: `drizzle(env.DB)` on D1, and the service-role
|
|
95
|
+
`createServiceDb(env)` on Neon and PlanetScale, where the ledger lives in the
|
|
96
|
+
`app` schema behind a service-role-only RLS policy. Your machine needs only an
|
|
97
|
+
operator's bearer token, never database credentials.
|
|
98
|
+
|
|
99
|
+
Each request must finish within the Worker's request limits. Split very large
|
|
100
|
+
backfills into several migrations, or make one resumable: a failed run can be
|
|
101
|
+
re-applied, and it picks up whatever rows still match.
|
|
102
|
+
|
|
103
|
+
## The CLI
|
|
104
|
+
|
|
105
|
+
`quickback migrate data` finds the route and each target's API hostname in
|
|
106
|
+
`reports/ops.manifest.json`. See the
|
|
107
|
+
[CLI reference](/tooling/cli#run-data-migrations) for every flag. It refuses
|
|
108
|
+
to run when the deployed Worker does not know a migration the build declares,
|
|
109
|
+
because that means the current build is not deployed yet.
|
|
@@ -29,5 +29,6 @@ security definitions compile to either provider.
|
|
|
29
29
|
|
|
30
30
|
- **[D1 Setup](/platform/database/d1)** — Bindings, wrangler config, migrations
|
|
31
31
|
- **[Using D1](/platform/database/using-d1)** — Drizzle queries, dual-DB mode, schema patterns
|
|
32
|
+
- **[Read replication](/platform/database/read-replication)** — Serve reads from D1's regional replicas with the Sessions API
|
|
32
33
|
- **[Neon](/platform/database/neon)** — Serverless Postgres setup and usage
|
|
33
34
|
- **[PlanetScale Postgres](/platform/database/planetscale-postgres)** — Roles, connection usernames, the cache-disabled Hyperdrive binding
|