@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.
Files changed (232) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +10 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/deploy.d.ts.map +1 -1
  5. package/dist/commands/deploy.js +7 -1
  6. package/dist/commands/deploy.js.map +1 -1
  7. package/dist/commands/mcp.d.ts.map +1 -1
  8. package/dist/commands/mcp.js +6 -5
  9. package/dist/commands/mcp.js.map +1 -1
  10. package/dist/index.js +1 -1
  11. package/dist/index.js.map +1 -1
  12. package/dist/lib/access-manifest-diff.d.ts +6 -0
  13. package/dist/lib/access-manifest-diff.d.ts.map +1 -1
  14. package/dist/lib/access-manifest-diff.js +10 -0
  15. package/dist/lib/access-manifest-diff.js.map +1 -1
  16. package/dist/lib/action-harvest.d.ts.map +1 -1
  17. package/dist/lib/action-harvest.js +36 -0
  18. package/dist/lib/action-harvest.js.map +1 -1
  19. package/dist/lib/api-client.d.ts +8 -0
  20. package/dist/lib/api-client.d.ts.map +1 -1
  21. package/dist/lib/api-client.js.map +1 -1
  22. package/dist/lib/deployment-target.d.ts +13 -0
  23. package/dist/lib/deployment-target.d.ts.map +1 -1
  24. package/dist/lib/deployment-target.js +4 -0
  25. package/dist/lib/deployment-target.js.map +1 -1
  26. package/dist/lib/file-loader.d.ts +22 -0
  27. package/dist/lib/file-loader.d.ts.map +1 -1
  28. package/dist/lib/file-loader.js +80 -18
  29. package/dist/lib/file-loader.js.map +1 -1
  30. package/dist/lib/file-writer.js +9 -0
  31. package/dist/lib/file-writer.js.map +1 -1
  32. package/dist/lib/harness.d.ts +10 -0
  33. package/dist/lib/harness.d.ts.map +1 -1
  34. package/dist/lib/harness.js +31 -0
  35. package/dist/lib/harness.js.map +1 -1
  36. package/dist/lib/migrations/executor.js +5 -1
  37. package/dist/lib/migrations/executor.js.map +1 -1
  38. package/dist/lib/migrations/plan.js +3 -0
  39. package/dist/lib/migrations/plan.js.map +1 -1
  40. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  41. package/dist/lib/migrations/postprocessors/index.js +23 -2
  42. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  43. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
  44. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
  45. package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
  46. package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
  47. package/dist/lib/migrations/prior-state.d.ts +13 -1
  48. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  49. package/dist/lib/migrations/prior-state.js +33 -2
  50. package/dist/lib/migrations/prior-state.js.map +1 -1
  51. package/dist/lib/migrations/types.d.ts +2 -2
  52. package/dist/lib/migrations/types.d.ts.map +1 -1
  53. package/dist/lib/migrations/types.js +3 -0
  54. package/dist/lib/migrations/types.js.map +1 -1
  55. package/dist/lib/wrangler-resources.d.ts +14 -1
  56. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  57. package/dist/lib/wrangler-resources.js +29 -7
  58. package/dist/lib/wrangler-resources.js.map +1 -1
  59. package/dist/skill/SKILL.md +64 -0
  60. package/dist/skill/docs/api/actions.md +73 -2
  61. package/dist/skill/docs/api/batch-operations.md +2 -0
  62. package/dist/skill/docs/api/caching.md +2 -2
  63. package/dist/skill/docs/api/crud.md +13 -0
  64. package/dist/skill/docs/api/errors.md +111 -10
  65. package/dist/skill/docs/api/index.md +24 -0
  66. package/dist/skill/docs/api/openapi.md +8 -0
  67. package/dist/skill/docs/api/query-params.md +6 -0
  68. package/dist/skill/docs/configure/agents.md +73 -1
  69. package/dist/skill/docs/configure/auth.md +7 -1
  70. package/dist/skill/docs/configure/bindings.md +55 -0
  71. package/dist/skill/docs/configure/cloudflare-access.md +191 -0
  72. package/dist/skill/docs/configure/domains.md +1 -1
  73. package/dist/skill/docs/configure/index.md +4 -2
  74. package/dist/skill/docs/configure/providers.md +2 -1
  75. package/dist/skill/docs/configure/tenancy.md +3 -0
  76. package/dist/skill/docs/configure/tenant-databases.md +2407 -0
  77. package/dist/skill/docs/define/access.md +33 -1
  78. package/dist/skill/docs/define/actions/defining.md +118 -1
  79. package/dist/skill/docs/define/actions/scoped-db.md +32 -8
  80. package/dist/skill/docs/define/areas.md +145 -2
  81. package/dist/skill/docs/define/diagnostics.md +160 -21
  82. package/dist/skill/docs/define/encryption.md +13 -2
  83. package/dist/skill/docs/define/fga.md +320 -42
  84. package/dist/skill/docs/define/firewall.md +4 -0
  85. package/dist/skill/docs/define/index.md +1 -0
  86. package/dist/skill/docs/define/read.md +46 -5
  87. package/dist/skill/docs/define/relationships.md +30 -12
  88. package/dist/skill/docs/define/schema.md +2 -0
  89. package/dist/skill/docs/define/scopes.md +393 -9
  90. package/dist/skill/docs/define/sealed-protocol.md +67 -12
  91. package/dist/skill/docs/define/transitions.md +4 -1
  92. package/dist/skill/docs/define/triggers.md +55 -1
  93. package/dist/skill/docs/platform/api-contract/index.md +9 -3
  94. package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
  95. package/dist/skill/docs/platform/auth/using-auth.md +1 -1
  96. package/dist/skill/docs/platform/database/d1.md +112 -3
  97. package/dist/skill/docs/platform/database/data-migrations.md +3 -1
  98. package/dist/skill/docs/platform/database/neon.md +10 -2
  99. package/dist/skill/docs/platform/queues/handlers.md +48 -16
  100. package/dist/skill/docs/platform/queues/using-queues.md +16 -0
  101. package/dist/skill/docs/platform/realtime/durable-objects.md +294 -17
  102. package/dist/skill/docs/platform/realtime/index.md +9 -6
  103. package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
  104. package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
  105. package/dist/skill/docs/platform/schedules/index.md +1 -1
  106. package/dist/skill/docs/platform/storage/r2.md +10 -1
  107. package/dist/skill/docs/platform/storage/using-r2.md +42 -1
  108. package/dist/skill/docs/tooling/output.md +9 -2
  109. package/dist/skill/docs/ui/account/features/admin.md +5 -3
  110. package/dist/skill/docs/ui/account/hooks.md +9 -2
  111. package/dist/skill/docs/ui/admin/connecting.md +3 -3
  112. package/dist/skill/docs/ui/admin/index.md +1 -1
  113. package/package.json +1 -1
  114. package/src/skill/SKILL.md +64 -0
  115. package/src/skill/docs/api/actions.md +73 -2
  116. package/src/skill/docs/api/batch-operations.md +2 -0
  117. package/src/skill/docs/api/caching.md +2 -2
  118. package/src/skill/docs/api/crud.md +13 -0
  119. package/src/skill/docs/api/errors.md +111 -10
  120. package/src/skill/docs/api/index.md +24 -0
  121. package/src/skill/docs/api/openapi.md +8 -0
  122. package/src/skill/docs/api/query-params.md +6 -0
  123. package/src/skill/docs/configure/agents.md +73 -1
  124. package/src/skill/docs/configure/auth.md +7 -1
  125. package/src/skill/docs/configure/bindings.md +55 -0
  126. package/src/skill/docs/configure/cloudflare-access.md +191 -0
  127. package/src/skill/docs/configure/domains.md +1 -1
  128. package/src/skill/docs/configure/index.md +4 -2
  129. package/src/skill/docs/configure/providers.md +2 -1
  130. package/src/skill/docs/configure/tenancy.md +3 -0
  131. package/src/skill/docs/configure/tenant-databases.md +2407 -0
  132. package/src/skill/docs/define/access.md +33 -1
  133. package/src/skill/docs/define/actions/defining.md +118 -1
  134. package/src/skill/docs/define/actions/scoped-db.md +32 -8
  135. package/src/skill/docs/define/areas.md +145 -2
  136. package/src/skill/docs/define/diagnostics.md +160 -21
  137. package/src/skill/docs/define/encryption.md +13 -2
  138. package/src/skill/docs/define/fga.md +320 -42
  139. package/src/skill/docs/define/firewall.md +4 -0
  140. package/src/skill/docs/define/index.md +1 -0
  141. package/src/skill/docs/define/read.md +46 -5
  142. package/src/skill/docs/define/relationships.md +30 -12
  143. package/src/skill/docs/define/schema.md +2 -0
  144. package/src/skill/docs/define/scopes.md +393 -9
  145. package/src/skill/docs/define/sealed-protocol.md +67 -12
  146. package/src/skill/docs/define/transitions.md +4 -1
  147. package/src/skill/docs/define/triggers.md +55 -1
  148. package/src/skill/docs/platform/api-contract/index.md +9 -3
  149. package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
  150. package/src/skill/docs/platform/auth/using-auth.md +1 -1
  151. package/src/skill/docs/platform/database/d1.md +112 -3
  152. package/src/skill/docs/platform/database/data-migrations.md +3 -1
  153. package/src/skill/docs/platform/database/neon.md +10 -2
  154. package/src/skill/docs/platform/queues/handlers.md +48 -16
  155. package/src/skill/docs/platform/queues/using-queues.md +16 -0
  156. package/src/skill/docs/platform/realtime/durable-objects.md +294 -17
  157. package/src/skill/docs/platform/realtime/index.md +9 -6
  158. package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
  159. package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
  160. package/src/skill/docs/platform/schedules/index.md +1 -1
  161. package/src/skill/docs/platform/storage/r2.md +10 -1
  162. package/src/skill/docs/platform/storage/using-r2.md +42 -1
  163. package/src/skill/docs/tooling/output.md +9 -2
  164. package/src/skill/docs/ui/account/features/admin.md +5 -3
  165. package/src/skill/docs/ui/account/hooks.md +9 -2
  166. package/src/skill/docs/ui/admin/connecting.md +3 -3
  167. package/src/skill/docs/ui/admin/index.md +1 -1
  168. package/dist/codex/AGENTS.md +0 -290
  169. package/dist/commands/build.test.d.ts.map +0 -1
  170. package/dist/commands/codex.d.ts +0 -16
  171. package/dist/commands/codex.d.ts.map +0 -1
  172. package/dist/commands/codex.js +0 -159
  173. package/dist/commands/codex.js.map +0 -1
  174. package/dist/commands/compile.d.ts +0 -62
  175. package/dist/commands/compile.d.ts.map +0 -1
  176. package/dist/commands/compile.js +0 -830
  177. package/dist/commands/compile.js.map +0 -1
  178. package/dist/commands/compile.test.d.ts.map +0 -1
  179. package/dist/commands/init.d.ts +0 -6
  180. package/dist/commands/init.d.ts.map +0 -1
  181. package/dist/commands/init.js +0 -405
  182. package/dist/commands/init.js.map +0 -1
  183. package/dist/commands/migrate.test.d.ts.map +0 -1
  184. package/dist/commands/migrations.test.d.ts.map +0 -1
  185. package/dist/commands/push.test.d.ts.map +0 -1
  186. package/dist/commands/schema.test.d.ts.map +0 -1
  187. package/dist/docs/content.d.ts +0 -7
  188. package/dist/docs/content.d.ts.map +0 -1
  189. package/dist/docs/content.js +0 -672
  190. package/dist/docs/content.js.map +0 -1
  191. package/dist/docs/index.test.d.ts.map +0 -1
  192. package/dist/lib/action-harvest.test.d.ts.map +0 -1
  193. package/dist/lib/api-client.test.d.ts.map +0 -1
  194. package/dist/lib/artifact-routing.test.d.ts.map +0 -1
  195. package/dist/lib/auth.test.d.ts.map +0 -1
  196. package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
  197. package/dist/lib/compiler-floor.test.d.ts.map +0 -1
  198. package/dist/lib/config-id-splice.test.d.ts.map +0 -1
  199. package/dist/lib/config-sync.test.d.ts.map +0 -1
  200. package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
  201. package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
  202. package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
  203. package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
  204. package/dist/lib/file-loader.test.d.ts.map +0 -1
  205. package/dist/lib/file-writer.test.d.ts.map +0 -1
  206. package/dist/lib/helpers.d.ts +0 -39
  207. package/dist/lib/helpers.d.ts.map +0 -1
  208. package/dist/lib/helpers.js +0 -299
  209. package/dist/lib/helpers.js.map +0 -1
  210. package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
  211. package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
  212. package/dist/lib/migrations/executor.test.d.ts.map +0 -1
  213. package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
  214. package/dist/lib/migrations/lock.test.d.ts.map +0 -1
  215. package/dist/lib/migrations/paths.test.d.ts.map +0 -1
  216. package/dist/lib/migrations/plan.test.d.ts.map +0 -1
  217. package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
  218. package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
  219. package/dist/lib/migrations/staging.test.d.ts.map +0 -1
  220. package/dist/lib/neon-canary.test.d.ts.map +0 -1
  221. package/dist/lib/neon-target.test.d.ts.map +0 -1
  222. package/dist/lib/neon.test.d.ts.map +0 -1
  223. package/dist/lib/prepare-output.test.d.ts.map +0 -1
  224. package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
  225. package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
  226. package/dist/lib/shell.test.d.ts.map +0 -1
  227. package/dist/lib/sweep-stale.d.ts +0 -25
  228. package/dist/lib/sweep-stale.d.ts.map +0 -1
  229. package/dist/lib/sweep-stale.js +0 -179
  230. package/dist/lib/sweep-stale.js.map +0 -1
  231. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  232. package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
@@ -134,6 +134,14 @@ Every opt-out needs a non-empty `reason`. The compiler rejects an opt-out
134
134
  without one, a `references` entry it does not recognise, or one naming a
135
135
  column the table does not have.
136
136
 
137
+ Two more warnings cover tables a namespace claims. They never fail the build;
138
+ fix the firewall or the column to clear them.
139
+
140
+ | Code | What it catches | Fix |
141
+ |---|---|---|
142
+ | `CLAIMED_TABLE_UNPINNED` | A claimed table with no firewall arm bound to the namespace's instance (`ctx.scope.<kind>`, `ctx.scope.<kind>.id`, `ctx.<exposeAs>.id`), or with several. It cannot be [pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance): relationship lanes see only their instance, org members see every instance of the organization. | Give the table exactly one instance arm, e.g. `{ field: 'eventId', equals: 'ctx.scope.event' }`. |
143
+ | `CLAIMED_INSTANCE_COLUMN_NULLABLE` | The pinned instance column is nullable. Rows with a `NULL` instance are unreachable through the namespace for every lane. | Make the column `.required()` / `.notNull()`. |
144
+
137
145
  {/* doc-compile: skip — excerpt of a defineTable config; `guests` and its columns are elided */}
138
146
  ```ts
139
147
  export default defineTable(guests, {
@@ -162,6 +170,24 @@ export default defineConfig({
162
170
  [security contract](/tooling/output#security-contract-report-and-signature)
163
171
  checks, so treat it as temporary.
164
172
 
173
+ ## Legacy forward codes
174
+
175
+ [`legacy`](/define/areas#keeping-the-old-url-legacy) on `defineTable` / `defineAction` fails the
176
+ build on every misuse. These are always errors.
177
+
178
+ | Code | When |
179
+ |---|---|
180
+ | `LEGACY_NOT_CLAIMED` | `legacy` on a table or action no namespace claims (its `path:` is under no prefix), or `instance.table` names a table the same namespace does not claim. Nothing to forward to. |
181
+ | `LEGACY_NO_ORG_LANE` | The claiming namespace has no `{ roles }` lane. The forward serves org members, and without that lane they don't pass the gate. |
182
+ | `LEGACY_NO_ORG_ARM` | The table (or `instance.table`, or the namespace's instance table) has no `ctx.activeOrgId` firewall arm, or the namespace has no resolvable instance table (`loads`, or the scope kind's `instance`). |
183
+ | `LEGACY_NO_INSTANCE_COLUMN` | No single firewall arm binds a column to the namespace's scope kind (`ctx.scope.<kind>`, `ctx.scope.<kind>.id`, `ctx.<exposeAs>.id`). |
184
+ | `LEGACY_PATH_COLLISION` | A legacy route lands on another emitted route (method + path), or the legacy base is another table's mount, another legacy base, or routes into a namespace prefix. |
185
+ | `LEGACY_BAD_DATE` | `deprecated` or `sunset` is not a `YYYY-MM-DD` date, or `sunset` is not after `deprecated`. |
186
+ | `LEGACY_UNSUPPORTED` | An `edge: true` action, a partitioned table (`placement: { partition }`), a table `legacy.path` with params, an action `legacy.path` whose first segment is a param or that does not carry the successor's other params by name, or an unknown `legacy` key. |
187
+
188
+ `LEGACY_PAST_SUNSET` is a **warning**: the build date is on or after `sunset`. The forward keeps
189
+ serving until you remove the key.
190
+
165
191
  ## The override surface
166
192
 
167
193
  Every promoted finding can be explicitly accepted — per finding, with a
@@ -235,7 +261,7 @@ type checker), it runs on every compile, and it renders on the
235
261
  | Code | Tier | Scope | What it catches |
236
262
  |---|---|---|---|
237
263
  | `ACTION_RAW_DB_WITHOUT_UNSAFE` | **error** | action files, and every project file they import | A raw database handle reached by an action with no `unsafe:` declaration. |
238
- | `ACTION_AUTH_DB_WRITE` | **error** | action files, and every project file they import | An insert, update, or delete against a Better Auth table that does not go through Better Auth. |
264
+ | `ACTION_AUTH_DB_WRITE` | **error** (warn in `hooks/`) | every authored file except `plugins/`, plus every `services/` file (handlers, `_` helpers, realtime, views, embeddings) | An insert, update, or delete against a Better Auth table that does not go through Better Auth. |
239
265
  | `ACTION_ROLE_CHECK_IN_BODY` | warn | the `execute` function of action files | A role check written in the handler body instead of in the declared `access`. |
240
266
  | `ENV_UNDECLARED` | **error** | every authored file (Cloudflare runtime) | An `env.X` read where nothing declares `X`. |
241
267
  | `TEMPLATE_UNESCAPED` | **error** | every authored file | A `${}` value in an HTML template literal that is not escaped. |
@@ -267,28 +293,141 @@ the action imports but does not call.
267
293
 
268
294
  ### `ACTION_AUTH_DB_WRITE`
269
295
 
296
+ Only Better Auth's API writes Better Auth's tables. A direct write skips
297
+ Better Auth's hooks, session revocation, and `qbrev` stamping. It is a
298
+ compile error in actions and every file they import, the feature and project
299
+ `lib/`, `middlewares/`, `email-templates/`, and every `.ts` file under
300
+ `services/` — and in every file those import. `services/` includes queue,
301
+ schedule, email, realtime, view, and embedding files, `_`-prefixed helpers,
302
+ and files the CLI skips for a missing `defineX` or `name`. The compiler reads
303
+ those for this check only; nothing else changes about what it emits.
304
+
305
+ A write in a `hooks/` file, reached from a hook, is a **warning** whatever
306
+ `failMode` says: an account hook sometimes has no Better Auth endpoint it can
307
+ call (see [Account hooks](/ui/account/hooks#csrf-caveat-server-side-org-create)).
308
+ The same `hooks/` file imported by an action is an action write — an error. A
309
+ `lib/` helper a hook imports is an error too.
310
+ `plugins/` is not swept — a custom Better Auth plugin is part of Better Auth's
311
+ API — unless an action imports it. Reads are never flagged.
312
+
270
313
  It fires on `.insert(T)`, `.update(T)`, and `.delete(T)` when `T` is:
271
314
 
272
- - a table imported from the generated auth schema (`…/auth/schema`,
273
- `…/auth-schema`), by name or through a namespace (`authSchema.user`,
274
- `const { member } = authSchema`), or
275
- - anything, when the receiver is the auth database handle (`authDb`,
276
- `c.get("authDb")`, `AUTH_DB`).
277
-
278
- It also fires on raw SQL strings that write a Better Auth table:
279
- `INSERT INTO <t> (…|VALUES|SELECT)`, `UPDATE <t> SET`, `DELETE FROM <t>
280
- WHERE`. The table names are `user`, `session`, `account`, `verification`,
281
- `organization`, `member`, `invitation`, `team`, `teamMember`, `apikey`,
282
- `passkey`, `twoFactor`, `jwks`, and the subscriptions and OAuth plugin tables,
283
- under both the singular (D1) and plural (Postgres) spellings. A project table
284
- with the same name is excluded. Reads are never flagged.
285
-
286
- The check runs whether or not the action is `unsafe`. `unsafe` lets an action
287
- read across tenants. It does not let it bypass Better Auth's hooks, session
288
- revocation, or `qbrev` stamping. Use Better Auth for writes: `auth.api.*` on
289
- the action's `auth` parameter.
290
-
291
- **Opt-out:** `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>`.
315
+ - a table from the generated auth schema (`…/auth/schema`, `…/auth-schema`):
316
+ imported by name, through a namespace (`authSchema.user`,
317
+ `const { member } = authSchema`), or destructured from a dynamic
318
+ `await import("…/auth/schema")`, or
319
+ - anything, when the receiver IS the auth database handle: `authDb`,
320
+ `c.get("authDb")`, `env.AUTH_DB`, your configured `authBinding`,
321
+ `drizzle(…)` of one, or a variable bound to one. A variable that only *uses*
322
+ the handle (`new Set((await authDb.select()…))`) is not one, and neither is
323
+ any other call taking it (`buildCache(authDb).delete(k)`).
324
+
325
+ An auth-schema table re-exported through a barrel counts:
326
+ `export { session } from "../auth/schema"`, `export *`, renames, and chains of
327
+ barrels are followed.
328
+
329
+ A helper call that is passed both the auth database handle and an auth-schema
330
+ table is an error when its name says it writes (`insertRows(authDb, member, rows)`,
331
+ `removeAll`, `updateX`, …). A name that says nothing either way (`paginate`,
332
+ `ensure`) is a warning. A name that says it reads (`select…`, `get…`, `find…`,
333
+ `count…`, `list…`, …) is not flagged.
334
+
335
+ It also fires on raw SQL that writes a Better Auth table. In a file that opens
336
+ the auth database, every string literal with a statement shape is checked
337
+ (`const q = "DELETE FROM session WHERE …"; env.AUTH_DB.prepare(q)`): `SET col =`,
338
+ `VALUES (`, `WHERE` / `USING` / `RETURNING` / `;`, or the string ending at the
339
+ table. Log text like `"could not delete from session store"` is not. Elsewhere
340
+ only a SQL context is — a `sql` tagged template, an argument of `prepare` / `run` /
341
+ `execute` / `query` / `exec` / `batch` (and the other driver calls), or a
342
+ `const` named like SQL (`deleteSql`, `query`, `stmt`). A file opens the auth
343
+ database when its code names the handle (`authDb`, `env.AUTH_DB`,
344
+ `c.get("authDb")`, your `authBinding`); a comment or string mentioning
345
+ `AUTH_DB` does not count.
346
+
347
+ - `INSERT INTO` / `REPLACE INTO <t>`
348
+ - `UPDATE [ONLY] <t> [AS alias] SET`
349
+ - `DELETE FROM [ONLY] <t> [alias] WHERE | USING | RETURNING`
350
+ - `TRUNCATE [TABLE] <t>`
351
+ - schema-qualified or quoted (`"auth"."session"`)
352
+ - a `${}` that is an auth-schema table (`` sql`DELETE FROM ${user} WHERE …` ``)
353
+ - in a file that opens the auth database, a SQL-context write whose table is
354
+ any `${}` (`` `DELETE FROM ${where}` ``) — it cannot be proven not to be an
355
+ auth table
356
+
357
+ Prose that reads like SQL (an email subject "Delete from organization") in a
358
+ file that does not open the auth database is not flagged.
359
+
360
+ The check is a syntactic, best-effort lint. Known gaps: SQL assembled across
361
+ variables, a handle passed through several functions, and writes through any
362
+ wrapper of the handle other than `drizzle(…)` (`withRetry(authDb).update(x)`)
363
+ slip past it. On Postgres, the
364
+ [RLS backstop](/platform/database/neon#better-auths-tables-stay-vanilla-better-auth)
365
+ is what actually refuses a caller-lane write to Better Auth's tables.
366
+
367
+ The table list is your compile's: every table Better Auth creates for the
368
+ plugins you enable, plus whatever the generated `src/auth/schema.ts` declares,
369
+ in SQL (`two_factor`), export (`twoFactor`), and plural spellings. A project
370
+ table with the same name is yours and is excluded. A project with no Better
371
+ Auth provider has nothing to check.
372
+
373
+ The message names the call to make instead, and the hint says where that call
374
+ lives for the kind of file — an action, a hook, a handler, a middleware, an
375
+ email template, or a lib file:
376
+
377
+ | Write | Call instead |
378
+ |---|---|
379
+ | insert `user` | `auth.api.createUser` (admin plugin) or `auth.api.signUpEmail` |
380
+ | update `user` | `auth.api.updateUser`; to ban, `ctx.auth.ban(userId, reason)` |
381
+ | delete `user` | `ctx.auth.deleteAccount(userId)`, `auth.api.deleteUser`, or `auth.api.removeUser` (admin plugin) |
382
+ | insert `session` | a sign-in endpoint: `signInEmail`, `signInEmailOTP`, `signInMagicLink`, passkey sign-in |
383
+ | delete `session` | `auth.api.revokeSession` / `revokeSessions`, or `revokeUserSessions` |
384
+ | `organization`, `member`, `invitation` | `createOrganization` / `updateOrganization` / `deleteOrganization`, `addMember` / `ctx.auth.setRole(userId, role)` / `removeMember`, `createInvitation` / `cancelInvitation` |
385
+
386
+ Plain `unsafe` does not silence it. `unsafe` lets an action read across
387
+ tenants; it is not a licence to write Better Auth's tables.
388
+
389
+ **Opt-out, in an action:** when Better Auth has no endpoint for the write,
390
+ declare `unsafe: { reason, crossTenant: false, authWrites: true }`.
391
+ `authWrites` turns unsafe mode on: every call writes a security audit row
392
+ (success, error, and denial) carrying your `reason`, with or without
393
+ `crossTenant`, and `unsafeDb` is in scope. The route fails closed: when the
394
+ audit write fails, the request returns 500 `ACCESS_AUDIT_LOG_FAILED`
395
+ (`auditTrailRequired`) instead of the action's result. Set `crossTenant: false` — unsafe
396
+ mode defaults to `crossTenant: true`, which makes the action sysadmin-only. `unsafeDb` is the
397
+ features database on D1, so reach the auth tables through `c.get("authDb")`:
398
+
399
+ ```typescript
400
+ // features/account/actions/anonymiseAccount.ts
401
+ import { z } from "zod";
402
+ import { eq } from "drizzle-orm";
403
+ import { defineAction } from "../.quickback/define-action";
404
+ import { user } from "../../../auth/schema";
405
+
406
+ export default defineAction({
407
+ description: "Anonymise a deleted account",
408
+ path: "/anonymise",
409
+ input: z.object({}),
410
+ access: { roles: ["AUTHENTICATED"] },
411
+ unsafe: {
412
+ reason: "GDPR anonymisation keeps the row; Better Auth only deletes",
413
+ crossTenant: false,
414
+ authWrites: true,
415
+ },
416
+ async execute({ c, ctx }) {
417
+ await c.get("authDb").update(user).set({ name: "Deleted user" }).where(eq(user.id, ctx.userId!));
418
+ return { ok: true };
419
+ },
420
+ });
421
+ ```
422
+
423
+ `authWrites: true` with no `reason`, or with `enabled: false`, fails the
424
+ compile. It covers the action file and the files it imports. A shared file
425
+ stays an error while any other importer — another action, a hook, a handler —
426
+ reaches it without the same opt-in.
427
+
428
+ **Opt-out, anywhere else** (hooks, handlers, lib):
429
+ `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>` on the line or the line
430
+ above, or `quickback-allow-file` for the whole file.
292
431
 
293
432
  ### `ACTION_ROLE_CHECK_IN_BODY`
294
433
 
@@ -226,10 +226,12 @@ new TextDecoder().decode(plaintext); // "Background check: clear"
226
226
  Behind that one call:
227
227
 
228
228
  1. **`/seal/v1/my-grant`** → the reader's wrapped scope private key.
229
- 2. **`/seal/v1/challenge`** → a fresh, single-use nonce bound to this reader + item.
229
+ 2. **`/seal/v1/challenge`** → a fresh, single-use nonce bound to this reader + item; only its hash is stored, and one conditional SQL delete consumes it.
230
230
  3. The client signs a **step-up proof** over the nonce (Ed25519 from the passphrase, or a passkey assertion whose WebAuthn challenge *is* the nonce).
231
231
  4. **`/seal/v1/reveal`** verifies the proof, writes an append-only reveal-log entry (mirrored fail-closed into the security-audit DB as a [`vault_reveal` event](/define/sealed-protocol)), and mints a short-lived (≤180s) `scope:seal:reveal` capability.
232
- 5. **`/seal/v1/key`** (bearer that capability) passes three fail-closed gates — tenant, capability, live-grant — and returns the still-wrapped content key.
232
+ 5. **`/seal/v1/key`** (bearer that capability) passes fail-closed tenant,
233
+ exact-item capability, live-grant, and current-enrollment revision gates,
234
+ then returns the still-wrapped content key.
233
235
  6. The client unwraps the scope key, unwraps the content key, and decrypts. **None of this touches the server with a readable key.**
234
236
 
235
237
  Passkey reveal is the same call as `revealWithPasskey({ ..., getAssertion })`, where `getAssertion(nonce)` runs the WebAuthn ceremony. A PRF-capable passkey can also **replace the passphrase prompt**: the client wraps the passphrase-derived user master under the passkey's PRF output once (`wrapMasterWithPrf`), and from then on a single ceremony both proves the step-up and unlocks the keys (`revealWithPasskey({ ..., prfUnwrap })`). Sign-in passkeys are emitted PRF-capable at creation; native-app origins go in `encryption.seal.extraOrigins`. The derivation and envelope are specified in [Multi-factor unlock (passkey PRF)](/define/sealed-protocol#multi-factor-unlock-passkey-prf).
@@ -243,6 +245,12 @@ Sealed values are opaque references at rest, so they're fenced off from every su
243
245
  - The table **must** carry a `q.scope('organization')` column — keys are per-scope.
244
246
  - Reading a sealed column server-side is a **type error**: the column is branded `$type<SealedValue>()`, an opaque non-string, so `db.select()` on it won't typecheck. The server's structural inability to read it is enforced by `tsc`, not convention.
245
247
  - Sealed projects **force-enable** KV-backed JWT revocation (so a revoked reader's in-flight reveal token dies); a project with sealed columns and no KV binding **fails to compile**.
248
+ - Seal key administration has no platform-role bypass. A caller needs an
249
+ explicit short-lived `kind: "admin"` capability for the exact scope;
250
+ `sysadmin` and organization roles do not imply it.
251
+ - Reveal is never implied by ownership or administration. The caller needs a
252
+ live grant bound to their current enrollment version and random revision,
253
+ plus a fresh exact-item reveal capability after step-up.
246
254
  - Database provider must be **Cloudflare D1** or **Neon over HTTP/Hyperdrive** — anything else fails to compile. On Neon, the seal/vault tables carry **deny-all row-level security for request connections**: only the worker-internal service-role lane (the generated `/seal/v1` routes, `ctx.seal`, and the sealed write chokepoint) can touch them, and every one of those queries is still explicitly organization-scoped.
247
255
 
248
256
  ## What this tier does and doesn't claim
@@ -250,6 +258,9 @@ Sealed values are opaque references at rest, so they're fenced off from every su
250
258
  The sealed tier protects against **full Worker compromise** — leaked secrets, malicious or buggy server code, a coerced operator. All of them get ciphertext; the keys to read it never exist server-side. Its operating model is explicit:
251
259
 
252
260
  - **A reveal needs a real second factor.** The vault passphrase (or passkey) is separate from login and never leaves the client.
261
+ - **Changing enrollment invalidates old access.** `/enrollment/replace`
262
+ advances the enrollment identity, revokes the old grant, and leaves a new
263
+ request pending until a key admin re-grants the scope key.
253
264
  - **Recovery is opt-in and zero-knowledge.** A key admin can enroll a scope key wrapped under a client-held recovery factor through `/seal/v1/recovery/enroll` — a recovery code, or (`wrapMethod: 'prf-aesgcm'`) a hardware security key or shared vault passkey, one live row per method; `/recovery/use` returns only those opaque wrapped blobs. If no recovery is enrolled and every reader loses their factor, the data is unrecoverable by design.
254
265
  - **Rotation includes re-granting.** `/rotate` versions the scope key and returns the live-reader worklist and public keys so the key-admin client can wrap and grant the new private key without exposing it to the server.
255
266
  - **No server-side processing.** Your actions can't read, mask, search, or index a sealed value — it's plaintext only in a client that just revealed it. If the server needs to process the field, you want the envelope tier instead.