@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.
Files changed (200) hide show
  1. package/dist/codex/AGENTS.md +290 -0
  2. package/dist/commands/build.d.ts +12 -0
  3. package/dist/commands/build.d.ts.map +1 -1
  4. package/dist/commands/build.js +69 -1
  5. package/dist/commands/build.js.map +1 -1
  6. package/dist/commands/build.test.d.ts.map +1 -0
  7. package/dist/commands/codex.d.ts +16 -0
  8. package/dist/commands/codex.d.ts.map +1 -0
  9. package/dist/commands/codex.js +159 -0
  10. package/dist/commands/codex.js.map +1 -0
  11. package/dist/commands/compile.d.ts +62 -0
  12. package/dist/commands/compile.d.ts.map +1 -0
  13. package/dist/commands/compile.js +830 -0
  14. package/dist/commands/compile.js.map +1 -0
  15. package/dist/commands/compile.test.d.ts.map +1 -0
  16. package/dist/commands/deploy.d.ts +9 -0
  17. package/dist/commands/deploy.d.ts.map +1 -1
  18. package/dist/commands/deploy.js +20 -2
  19. package/dist/commands/deploy.js.map +1 -1
  20. package/dist/commands/init.d.ts +6 -0
  21. package/dist/commands/init.d.ts.map +1 -0
  22. package/dist/commands/init.js +405 -0
  23. package/dist/commands/init.js.map +1 -0
  24. package/dist/commands/migrate-data.d.ts +12 -0
  25. package/dist/commands/migrate-data.d.ts.map +1 -0
  26. package/dist/commands/migrate-data.js +134 -0
  27. package/dist/commands/migrate-data.js.map +1 -0
  28. package/dist/commands/migrate.d.ts.map +1 -1
  29. package/dist/commands/migrate.js +11 -0
  30. package/dist/commands/migrate.js.map +1 -1
  31. package/dist/commands/migrate.test.d.ts.map +1 -0
  32. package/dist/commands/migrations.test.d.ts.map +1 -0
  33. package/dist/commands/push.test.d.ts.map +1 -0
  34. package/dist/commands/schema.test.d.ts.map +1 -0
  35. package/dist/commands/secrets.d.ts +27 -0
  36. package/dist/commands/secrets.d.ts.map +1 -0
  37. package/dist/commands/secrets.js +186 -0
  38. package/dist/commands/secrets.js.map +1 -0
  39. package/dist/docs/content.d.ts +7 -0
  40. package/dist/docs/content.d.ts.map +1 -0
  41. package/dist/docs/content.js +672 -0
  42. package/dist/docs/content.js.map +1 -0
  43. package/dist/docs/index.test.d.ts.map +1 -0
  44. package/dist/index.js +23 -3
  45. package/dist/index.js.map +1 -1
  46. package/dist/lib/access-manifest-diff.d.ts +87 -0
  47. package/dist/lib/access-manifest-diff.d.ts.map +1 -0
  48. package/dist/lib/access-manifest-diff.js +331 -0
  49. package/dist/lib/access-manifest-diff.js.map +1 -0
  50. package/dist/lib/action-harvest.test.d.ts.map +1 -0
  51. package/dist/lib/api-client.test.d.ts.map +1 -0
  52. package/dist/lib/artifact-routing.d.ts.map +1 -1
  53. package/dist/lib/artifact-routing.js +3 -0
  54. package/dist/lib/artifact-routing.js.map +1 -1
  55. package/dist/lib/artifact-routing.test.d.ts.map +1 -0
  56. package/dist/lib/auth.test.d.ts.map +1 -0
  57. package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
  58. package/dist/lib/compiler-floor.test.d.ts.map +1 -0
  59. package/dist/lib/compiler-stubs.d.ts +2 -0
  60. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  61. package/dist/lib/compiler-stubs.js +2 -0
  62. package/dist/lib/compiler-stubs.js.map +1 -1
  63. package/dist/lib/config-id-splice.test.d.ts.map +1 -0
  64. package/dist/lib/config-sync.test.d.ts.map +1 -0
  65. package/dist/lib/copy-public-assets.test.d.ts.map +1 -0
  66. package/dist/lib/copy-source-apps.test.d.ts.map +1 -0
  67. package/dist/lib/drizzle-meta-routing.test.d.ts.map +1 -0
  68. package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +1 -0
  69. package/dist/lib/file-loader.d.ts +6 -0
  70. package/dist/lib/file-loader.d.ts.map +1 -1
  71. package/dist/lib/file-loader.js +17 -0
  72. package/dist/lib/file-loader.js.map +1 -1
  73. package/dist/lib/file-loader.test.d.ts.map +1 -0
  74. package/dist/lib/file-writer.test.d.ts.map +1 -0
  75. package/dist/lib/helpers.d.ts +39 -0
  76. package/dist/lib/helpers.d.ts.map +1 -0
  77. package/dist/lib/helpers.js +299 -0
  78. package/dist/lib/helpers.js.map +1 -0
  79. package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +1 -0
  80. package/dist/lib/migrations/drizzle.test.d.ts.map +1 -0
  81. package/dist/lib/migrations/executor.test.d.ts.map +1 -0
  82. package/dist/lib/migrations/inventory.test.d.ts.map +1 -0
  83. package/dist/lib/migrations/lock.test.d.ts.map +1 -0
  84. package/dist/lib/migrations/paths.test.d.ts.map +1 -0
  85. package/dist/lib/migrations/plan.test.d.ts.map +1 -0
  86. package/dist/lib/migrations/postprocessors/index.test.d.ts.map +1 -0
  87. package/dist/lib/migrations/prompt-runner.test.d.ts.map +1 -0
  88. package/dist/lib/migrations/staging.test.d.ts.map +1 -0
  89. package/dist/lib/neon-canary.test.d.ts.map +1 -0
  90. package/dist/lib/neon-target.test.d.ts.map +1 -0
  91. package/dist/lib/neon.test.d.ts.map +1 -0
  92. package/dist/lib/ops-manifest.d.ts +76 -0
  93. package/dist/lib/ops-manifest.d.ts.map +1 -0
  94. package/dist/lib/ops-manifest.js +94 -0
  95. package/dist/lib/ops-manifest.js.map +1 -0
  96. package/dist/lib/prepare-output.test.d.ts.map +1 -0
  97. package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
  98. package/dist/lib/release-and-pin.d.ts +34 -0
  99. package/dist/lib/release-and-pin.d.ts.map +1 -0
  100. package/dist/lib/release-and-pin.js +71 -0
  101. package/dist/lib/release-and-pin.js.map +1 -0
  102. package/dist/lib/schema-sync/index.test.d.ts.map +1 -0
  103. package/dist/lib/shell.d.ts +4 -1
  104. package/dist/lib/shell.d.ts.map +1 -1
  105. package/dist/lib/shell.js +8 -3
  106. package/dist/lib/shell.js.map +1 -1
  107. package/dist/lib/shell.test.d.ts.map +1 -0
  108. package/dist/lib/sweep-stale.d.ts +25 -0
  109. package/dist/lib/sweep-stale.d.ts.map +1 -0
  110. package/dist/lib/sweep-stale.js +179 -0
  111. package/dist/lib/sweep-stale.js.map +1 -0
  112. package/dist/lib/sweep-stale.test.d.ts.map +1 -0
  113. package/dist/lib/wrangler-resources.test.d.ts.map +1 -0
  114. package/dist/skill/docs/api/actions.md +2 -0
  115. package/dist/skill/docs/api/batch-operations.md +18 -4
  116. package/dist/skill/docs/api/crud.md +62 -0
  117. package/dist/skill/docs/api/errors.md +17 -2
  118. package/dist/skill/docs/configure/auth.md +49 -2
  119. package/dist/skill/docs/configure/bindings.md +15 -0
  120. package/dist/skill/docs/configure/domains.md +4 -0
  121. package/dist/skill/docs/configure/index.md +29 -11
  122. package/dist/skill/docs/configure/providers.md +1 -0
  123. package/dist/skill/docs/configure/tenancy.md +117 -0
  124. package/dist/skill/docs/define/access.md +19 -0
  125. package/dist/skill/docs/define/actions/access.md +76 -0
  126. package/dist/skill/docs/define/actions/defining.md +156 -1
  127. package/dist/skill/docs/define/actions/scoped-db.md +236 -9
  128. package/dist/skill/docs/define/areas.md +46 -0
  129. package/dist/skill/docs/define/authz-roles.md +10 -0
  130. package/dist/skill/docs/define/diagnostics.md +263 -0
  131. package/dist/skill/docs/define/encryption.md +34 -2
  132. package/dist/skill/docs/define/guards.md +13 -0
  133. package/dist/skill/docs/define/masking.md +77 -3
  134. package/dist/skill/docs/define/rate-limit.md +3 -3
  135. package/dist/skill/docs/define/schema.md +148 -7
  136. package/dist/skill/docs/define/scopes.md +79 -0
  137. package/dist/skill/docs/define/sealed-protocol.md +111 -9
  138. package/dist/skill/docs/define/transitions.md +39 -0
  139. package/dist/skill/docs/define/views.md +77 -3
  140. package/dist/skill/docs/platform/api-contract/index.md +4 -0
  141. package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -0
  142. package/dist/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
  143. package/dist/skill/docs/platform/auth/using-auth.md +6 -0
  144. package/dist/skill/docs/platform/database/d1.md +47 -0
  145. package/dist/skill/docs/platform/database/data-migrations.md +109 -0
  146. package/dist/skill/docs/platform/database/index.md +1 -0
  147. package/dist/skill/docs/platform/database/read-replication.md +257 -0
  148. package/dist/skill/docs/platform/database/using-d1.md +2 -1
  149. package/dist/skill/docs/platform/payments/one-off-checkout.md +6 -1
  150. package/dist/skill/docs/platform/push/index.md +2 -0
  151. package/dist/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
  152. package/dist/skill/docs/platform/storage/using-r2.md +135 -19
  153. package/dist/skill/docs/start/deploy.md +38 -0
  154. package/dist/skill/docs/tooling/cli.md +120 -0
  155. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
  156. package/dist/skill/docs/tooling/output.md +70 -2
  157. package/package.json +1 -1
  158. package/src/skill/docs/api/actions.md +2 -0
  159. package/src/skill/docs/api/batch-operations.md +18 -4
  160. package/src/skill/docs/api/crud.md +62 -0
  161. package/src/skill/docs/api/errors.md +17 -2
  162. package/src/skill/docs/configure/auth.md +49 -2
  163. package/src/skill/docs/configure/bindings.md +15 -0
  164. package/src/skill/docs/configure/domains.md +4 -0
  165. package/src/skill/docs/configure/index.md +29 -11
  166. package/src/skill/docs/configure/providers.md +1 -0
  167. package/src/skill/docs/configure/tenancy.md +117 -0
  168. package/src/skill/docs/define/access.md +19 -0
  169. package/src/skill/docs/define/actions/access.md +76 -0
  170. package/src/skill/docs/define/actions/defining.md +156 -1
  171. package/src/skill/docs/define/actions/scoped-db.md +236 -9
  172. package/src/skill/docs/define/areas.md +46 -0
  173. package/src/skill/docs/define/authz-roles.md +10 -0
  174. package/src/skill/docs/define/diagnostics.md +263 -0
  175. package/src/skill/docs/define/encryption.md +34 -2
  176. package/src/skill/docs/define/guards.md +13 -0
  177. package/src/skill/docs/define/masking.md +77 -3
  178. package/src/skill/docs/define/rate-limit.md +3 -3
  179. package/src/skill/docs/define/schema.md +148 -7
  180. package/src/skill/docs/define/scopes.md +79 -0
  181. package/src/skill/docs/define/sealed-protocol.md +111 -9
  182. package/src/skill/docs/define/transitions.md +39 -0
  183. package/src/skill/docs/define/views.md +77 -3
  184. package/src/skill/docs/platform/api-contract/index.md +4 -0
  185. package/src/skill/docs/platform/auth/jwt-optimization.md +2 -0
  186. package/src/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
  187. package/src/skill/docs/platform/auth/using-auth.md +6 -0
  188. package/src/skill/docs/platform/database/d1.md +47 -0
  189. package/src/skill/docs/platform/database/data-migrations.md +109 -0
  190. package/src/skill/docs/platform/database/index.md +1 -0
  191. package/src/skill/docs/platform/database/read-replication.md +257 -0
  192. package/src/skill/docs/platform/database/using-d1.md +2 -1
  193. package/src/skill/docs/platform/payments/one-off-checkout.md +6 -1
  194. package/src/skill/docs/platform/push/index.md +2 -0
  195. package/src/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
  196. package/src/skill/docs/platform/storage/using-r2.md +135 -19
  197. package/src/skill/docs/start/deploy.md +38 -0
  198. package/src/skill/docs/tooling/cli.md +120 -0
  199. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
  200. 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 code (key-admin)
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 key derived from a **recovery code** and escrows the blob. The server stores only the opaque recovery-wrapped material — the recovery code, held by the client, is what makes it usable; the server can never unwrap it. One live recovery per scope key version.
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, scope key wrapped to the recovery key>" }
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 the recovery-code key to recover the scope private key, then re-grants readers. The returned blob is **useless without the recovery code** — the server gates *who* may fetch it, the code gates whether it can be unwrapped.
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>" } // 404 parity if none
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)"`. Other rollup
324
- functions (`groupBy` + `sum` of another column) are deferred to a future
325
- release.
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, '&quot;').replace(/'/g, '&#39;');
81
81
 
82
82
  export default function welcomeTemplate({ otp, name, appName, appUrl }: Input) {
83
- const greeting = name ? `Hi ${name},` : 'Hi,';
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(greeting)} your account is ready. Use this code to set your password and sign in:</p>
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: `${greeting}\n\nYour ${appName} code: ${otp}\n\nFinish setup at ${appUrl}/set-password`,
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