@quickback-dev/cli 0.66.20 → 0.66.22

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 (102) hide show
  1. package/dist/commands/migrate.js +2 -2
  2. package/dist/commands/migrate.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  5. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  6. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  7. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  8. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  9. package/dist/lib/migrations/file-envelopes.js +21 -51
  10. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  11. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  12. package/dist/lib/migrations/prompt-runner.js +6 -1
  13. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  14. package/dist/skill/docs/api/actions.md +13 -6
  15. package/dist/skill/docs/api/batch-operations.md +6 -2
  16. package/dist/skill/docs/api/crud.md +72 -9
  17. package/dist/skill/docs/api/errors.md +86 -6
  18. package/dist/skill/docs/api/openapi.md +1 -1
  19. package/dist/skill/docs/api/query-params.md +8 -7
  20. package/dist/skill/docs/api/typescript.md +196 -0
  21. package/dist/skill/docs/configure/index.md +36 -2
  22. package/dist/skill/docs/configure/providers.md +37 -9
  23. package/dist/skill/docs/define/actions/defining.md +16 -7
  24. package/dist/skill/docs/define/actions/record-and-standalone.md +10 -0
  25. package/dist/skill/docs/define/actions/scoped-db.md +18 -3
  26. package/dist/skill/docs/define/changesets.md +2 -0
  27. package/dist/skill/docs/define/firewall.md +39 -0
  28. package/dist/skill/docs/define/guards.md +7 -2
  29. package/dist/skill/docs/define/masking.md +14 -0
  30. package/dist/skill/docs/define/read.md +3 -0
  31. package/dist/skill/docs/define/relationships.md +9 -0
  32. package/dist/skill/docs/define/schema.md +14 -10
  33. package/dist/skill/docs/define/transitions.md +12 -5
  34. package/dist/skill/docs/define/triggers.md +2 -1
  35. package/dist/skill/docs/index.md +1 -0
  36. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  37. package/dist/skill/docs/platform/database/neon.md +110 -30
  38. package/dist/skill/docs/platform/payments/index.md +1 -1
  39. package/dist/skill/docs/start/frontend.md +278 -0
  40. package/dist/skill/docs/start/index.md +1 -0
  41. package/dist/skill/docs/tooling/cli.md +28 -7
  42. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  43. package/dist/skill/docs/tooling/output.md +42 -11
  44. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  45. package/dist/skill/docs/ui/admin/actions.md +6 -2
  46. package/dist/skill/docs/ui/admin/index.md +1 -1
  47. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  48. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  49. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  50. package/dist/skill/docs/ui/admin/security.md +2 -2
  51. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  52. package/dist/skill/docs/ui/components/auth.md +90 -0
  53. package/dist/skill/docs/ui/components/index.md +48 -0
  54. package/dist/skill/docs/ui/components/install.md +118 -0
  55. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  56. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  57. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  58. package/package.json +1 -1
  59. package/src/skill/docs/api/actions.md +13 -6
  60. package/src/skill/docs/api/batch-operations.md +6 -2
  61. package/src/skill/docs/api/crud.md +72 -9
  62. package/src/skill/docs/api/errors.md +86 -6
  63. package/src/skill/docs/api/openapi.md +1 -1
  64. package/src/skill/docs/api/query-params.md +8 -7
  65. package/src/skill/docs/api/typescript.md +196 -0
  66. package/src/skill/docs/configure/index.md +36 -2
  67. package/src/skill/docs/configure/providers.md +37 -9
  68. package/src/skill/docs/define/actions/defining.md +16 -7
  69. package/src/skill/docs/define/actions/record-and-standalone.md +10 -0
  70. package/src/skill/docs/define/actions/scoped-db.md +18 -3
  71. package/src/skill/docs/define/changesets.md +2 -0
  72. package/src/skill/docs/define/firewall.md +39 -0
  73. package/src/skill/docs/define/guards.md +7 -2
  74. package/src/skill/docs/define/masking.md +14 -0
  75. package/src/skill/docs/define/read.md +3 -0
  76. package/src/skill/docs/define/relationships.md +9 -0
  77. package/src/skill/docs/define/schema.md +14 -10
  78. package/src/skill/docs/define/transitions.md +12 -5
  79. package/src/skill/docs/define/triggers.md +2 -1
  80. package/src/skill/docs/index.md +1 -0
  81. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  82. package/src/skill/docs/platform/database/neon.md +110 -30
  83. package/src/skill/docs/platform/payments/index.md +1 -1
  84. package/src/skill/docs/start/frontend.md +278 -0
  85. package/src/skill/docs/start/index.md +1 -0
  86. package/src/skill/docs/tooling/cli.md +28 -7
  87. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  88. package/src/skill/docs/tooling/output.md +42 -11
  89. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  90. package/src/skill/docs/ui/admin/actions.md +6 -2
  91. package/src/skill/docs/ui/admin/index.md +1 -1
  92. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  93. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  94. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  95. package/src/skill/docs/ui/admin/security.md +2 -2
  96. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  97. package/src/skill/docs/ui/components/auth.md +90 -0
  98. package/src/skill/docs/ui/components/index.md +48 -0
  99. package/src/skill/docs/ui/components/install.md +118 -0
  100. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  101. package/src/skill/docs/ui/components/resource-form.md +80 -0
  102. package/src/skill/docs/ui/components/resource-table.md +46 -0
@@ -74,16 +74,20 @@ registered provider; MySQL is not supported.
74
74
  One database provider per app: auth tables and feature tables always share the
75
75
  selected database. On either Postgres provider, Better Auth uses its PostgreSQL/Drizzle adapter
76
76
  in the same Postgres database as your features; on `cloudflare-d1`, both use
77
- D1. A per-service map (`database: { auth: ..., features: ... }`) is rejected at
78
- compile time — mixed database providers are not supported.
77
+ D1. A per-service map (`database: { auth: ..., features: ... }`) is not part
78
+ of the config type (`quickback check` flags it) and is rejected at compile
79
+ time — mixed database providers are not supported. On D1, auth still gets its
80
+ own database by default (`splitDatabases: true`); `authBinding` and
81
+ `featuresBinding` name the two bindings.
79
82
 
80
83
  ```typescript
81
84
  import { defineDatabase } from "@quickback/compiler";
82
85
 
83
86
  providers: {
84
87
  database: defineDatabase("cloudflare-d1", {
85
- generateId: "prefixed", // "uuid" | "cuid" | "nanoid" | "prefixed" | "serial" | false
88
+ generateId: "uuid", // default; "cuid" | "nanoid" | "short" | "prefixed" | "serial" | false
86
89
  allowClientIds: false, // true: POST bodies MAY carry a strategy-shaped id
90
+ validateIdParams: true, // false: /:id is a plain string again (see the hazard below)
87
91
  namingConvention: "snake_case", // "camelCase" | "snake_case"
88
92
  usePlurals: false, // Auth table names: "users" vs "user"
89
93
  }),
@@ -98,8 +102,9 @@ single Postgres database with no bindings or split mode (see
98
102
 
99
103
  | Option | Type | Default (D1) | Description |
100
104
  |--------|------|---------|-------------|
101
- | `generateId` | `string \| false` | `"prefixed"` | ID generation strategy |
105
+ | `generateId` | `string \| false` | `"uuid"` (every provider) | ID generation strategy — see [ID Generation Options](#id-generation-options) |
102
106
  | `allowClientIds` | `boolean` | `false` | Accept an optional client-supplied `id` on create, shaped like the `generateId` strategy — see [Client-supplied IDs](/api/crud#client-supplied-ids-optimistic-updates). Ignored under `generateId: false` (ids are already client-supplied and required) and `"serial"` / numeric PKs |
107
+ | `validateIdParams` | `boolean` | `true` | Check a record route's `:id` against the table's id format and answer `400 INVALID_ID` before any database work — see [Malformed ids](/api/crud#malformed-ids-400-invalid_id). **Set `false` if any table holds rows whose ids don't match the current `generateId` shape** (the strategy changed after rows were written, imported data, ids hand-minted by actions): with the check on, those rows answer 400 instead of the row. Tables whose format the compiler can't know (`generateId: false`, an authored id default) are never checked |
103
108
  | `namingConvention` | `string` | `"snake_case"` | Column naming convention |
104
109
  | `usePlurals` | `boolean` | `false` | Pluralize auth table names (e.g. `user` vs `users`) |
105
110
  | `splitDatabases` | `boolean` | `true` | Separate auth and features databases (D1 only) |
@@ -266,7 +271,7 @@ See [Realtime](/platform/realtime) for the client-side connection flow and helpe
266
271
 
267
272
  | Value | Description | Example |
268
273
  |-------|-------------|---------|
269
- | `"uuid"` | Server generates UUID | `550e8400-e29b-41d4-a716-446655440000` |
274
+ | `"uuid"` (default) | Server generates UUID | `550e8400-e29b-41d4-a716-446655440000` |
270
275
  | `"cuid"` | Server generates CUID | `clh2v8k9g0000l508h5gx8j1a` |
271
276
  | `"nanoid"` | Server generates nanoid (21-char, URL-safe) | `V1StGXR8_Z5jdHi6B-myT` |
272
277
  | `"short"` | 6-char alphanumeric (nanoid `customAlphabet`) | `a3F9xK` |
@@ -274,10 +279,33 @@ See [Realtime](/platform/realtime) for the client-side connection flow and helpe
274
279
  | `"serial"` | Database auto-increments | `1`, `2`, `3` |
275
280
  | `false` | Client provides ID (enables PUT/upsert) | Any string |
276
281
 
277
- > `"short"` produces IDs with ~56.8 billion possible values (62^6). That's fine for small/scoped tables like rooms, invites, or share codes — but at roughly 238,000 rows you hit a 50% chance of collision (birthday bound). Don't use it for high-volume records. `"nanoid"` and `"short"` both require the `nanoid` package in your project.
278
-
279
-
280
- > `generateId: "cuid"` is not byte-for-byte uniform across every compiler path. Import-capable runtime paths emit real `createId()` usage, but compiler-managed schema auto-injection may preserve the `createId()` call site with a file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes stay dependency-free. If you require true cuid2 strings everywhere, explicitly import `createId` from `@paralleldrive/cuid2` in the authored schema file.
282
+ Leave `generateId` unset and every provider mints UUIDs, in the CRUD route and
283
+ in the schema default an action's `db.insert()` falls back on alike.
284
+
285
+ > **Upgrading: the default changed from prefixed to uuid**
286
+ >
287
+ > Before this release an unset `generateId` minted **prefixed** ids on D1
288
+ > (`job_550e8400e29b41d4a716446655440000`), and on every provider the CRUD route
289
+ > fell back to prefixed. Unset now means `"uuid"` everywhere. Existing rows keep
290
+ > their ids, so a table that was on the old default holds both shapes:
291
+ >
292
+ > - **Old rows stay reachable.** While `generateId` is unset, record routes'
293
+ > [`:id` check](/api/crud#malformed-ids-400-invalid_id) accepts a UUID **or**
294
+ > any prefixed id the old default minted, and the OpenAPI spec declares no
295
+ > `format` on ids, so a strict client doesn't reject old ids.
296
+ > - **New rows are UUIDs**, including client-supplied ids under `allowClientIds`.
297
+ > - **To keep minting prefixed ids**, set `generateId: "prefixed"` explicitly.
298
+ > - **Once every row is a UUID** (or on a new project), set `generateId: "uuid"`
299
+ > explicitly. That is a promise about every row, so `:id` then accepts only a
300
+ > UUID and ids get `format: "uuid"` in OpenAPI.
301
+ >
302
+ > Code that parses the `<prefix>_` part of an id breaks on new rows either way.
303
+
304
+
305
+ > `"short"` produces IDs with ~56.8 billion possible values (62^6). That's fine for small/scoped tables like rooms, invites, or share codes — but at roughly 238,000 rows you hit a 50% chance of collision (birthday bound). Don't use it for high-volume records.
306
+
307
+
308
+ > `"cuid"`, `"nanoid"`, and `"short"` mint with an npm package: `@paralleldrive/cuid2` for `"cuid"`, and `nanoid` for the other two. The compiler adds the package to the generated `package.json` and imports it wherever it mints an id, so don't add it yourself, and don't import it in a table file (table files can't import it). Every server-side mint produces the shape in the table: the CRUD route, and the schema default that a `db.insert()` in an action falls back on. Older compilers backed the schema-side `createId()` with a `crypto.randomUUID()` polyfill, so a `cuid` table can hold UUID rows; record routes' [`:id` check](/api/crud#malformed-ids-400-invalid_id) accepts both.
281
309
 
282
310
 
283
311
  ## Auth Providers
@@ -74,10 +74,11 @@ export default defineAction({
74
74
  > the **feature**, not the whole project: a table owned by another feature is
75
75
  > not re-exported here.
76
76
  >
77
- > Prefer this single import over the older
78
- > `import { applications } from "../applications"` — that path resolves to
79
- > your authored file at edit time, which has no named export and none of the
80
- > injected columns. The helper files are regenerated on every compile; keep
77
+ > Prefer this single import over the older two-import form with
78
+ > `import { applications } from "../applications"`. That form still builds
79
+ > and typechecks — `quickback check` resolves a named import from a
80
+ > `feature()` file to the generated table, as the build does — it is just one
81
+ > import more. The helper files are regenerated on every compile; keep
81
82
  > `quickback/features/*/.quickback/` in `.gitignore` (new projects get this
82
83
  > automatically).
83
84
 
@@ -154,7 +155,10 @@ nothing under that substitution — see
154
155
  `output:` is optional, and omitting it degrades quietly: the operation's
155
156
  OpenAPI success response becomes `{}` and
156
157
  `Api.<feature>.actions.<action>.Output` becomes `unknown`. The compile still
157
- succeeds — it warns, naming how many actions are affected.
158
+ succeeds, but it warns, naming how many actions are affected. Every compile
159
+ emits the warning, validation compiles included. It skips actions whose
160
+ response the compiler owns: `responseType: 'file'` or `'stream'`, bundles, and
161
+ transitions without an `execute`.
158
162
 
159
163
  **An action that returns a row declares it with `row(<table>)`**, imported
160
164
  from the same helper as `defineAction`. **Any other shape is a literal Zod
@@ -166,6 +170,9 @@ import { defineAction, row, tickets } from "../.quickback/define-action";
166
170
  // Returns one ticket: Output = Api.tickets.Row, OpenAPI = the Tickets component.
167
171
  output: row(tickets)
168
172
 
173
+ // row() composes: nest it in an envelope, make it nullable, or put it in an array.
174
+ output: z.object({ ticket: row(tickets), previous: row(tickets).nullable(), related: z.array(row(tickets)) })
175
+
169
176
  // Any other shape — write it out.
170
177
  output: z.object({
171
178
  tickets: z.array(z.object({ id: z.string(), name: z.string(), priceCents: z.number() })),
@@ -177,8 +184,10 @@ output: z.object({ tickets: z.array(createSelectSchema(ticketTypes)) })
177
184
 
178
185
  `row(table)` is compiler-recognised: the harvester records which table it
179
186
  was handed, and the compiler resolves that to the table's `Row` type in
180
- `quickback.gen.ts` and to its resource component in OpenAPI (the table must
181
- be a `defineTable()` resource — anything else is a compile error). At
187
+ `quickback.gen.ts` and to its resource component in OpenAPI — wherever it
188
+ appears in the output: bare, as an object property, under `.nullable()`, or
189
+ as array items (the table must be a `defineTable()` resource — anything else
190
+ is a compile error). At
182
191
  runtime it is a real Zod object built from the table's columns.
183
192
 
184
193
  The harvest substitutes inert proxies for table modules, so anything that
@@ -224,6 +224,16 @@ with a mounted prefix, two more forms apply:
224
224
  An action's `access:` and `anchor:` may reference vocabulary declared by an ancestor area —
225
225
  and never vocabulary of an area the feature is not inside (compile error).
226
226
 
227
+ A standalone path under a feature's own collection, like `path: "/users/:id/likes"`, is still
228
+ standalone. It binds to nothing, so there is no record fetch. Read `:id` yourself and check it
229
+ through the scoped `db`. If you want the record fetched and firewalled for you, drop `path:`
230
+ and write a record-based action.
231
+
232
+ A standalone path may not land on a route the compiler already mounts. That includes a record
233
+ action with the same name (`actions/users/likes.ts` → `POST /users/:id/likes`) and the
234
+ generated CRUD routes (`GET /users/:id`). Parameter names don't matter to the router, so
235
+ `/users/:userId/likes` collides too. Either case is a compile error naming both routes.
236
+
227
237
  ### Feature-area transition adapter
228
238
 
229
239
  A record [state transition](/define/transitions) normally lives on a
@@ -9,13 +9,22 @@ the same generated `WHERE` clause the table's CRUD routes use:
9
9
  |-----------|---------------------------|
10
10
  | `SELECT` | the table's firewall (org / owner / team / scope / `via:` arms) AND soft-delete filter |
11
11
  | `UPDATE` / `DELETE` | the same firewall `WHERE`, AND-merged with yours |
12
- | `INSERT` | every required claim column the firewall binds (e.g. `organizationId` from `ctx.activeOrgId`), overwriting any value you passed |
13
- | `INSERT … onConflictDoUpdate` | the firewall AND-merged into `setWhere` — a conflict with a row the caller can't update (another tenant's id) is a no-op, never an overwrite |
12
+ | `INSERT` | every required claim column the firewall binds (e.g. `organizationId` from `ctx.activeOrgId`), overwriting any value you passed — then, where those stamps can't guarantee the row passes the firewall (a `via:` / `{ permission }` / literal / `any:` arm), the [firewall-on-write check](/define/firewall#firewall-on-write): every row of `.values(row)` or `.values([rows])` must pass the table's firewall, or nothing is written and the action answers **403 `FIREWALL_WRITE_DENIED`** |
13
+ | `INSERT … onConflictDoUpdate` / `onConflictDoNothing` | the insert branch runs the same firewall-on-write check; the conflict update gets the firewall AND-merged into `setWhere` — a conflict with a row the caller can't update (another tenant's id) is a no-op, never an overwrite |
14
14
 
15
15
  The firewall is set on the builder when you call `.from()` / `.set()` /
16
16
  `.delete()`, so every executor gets it: `await`, `.all()`, `.get()`,
17
17
  `.values()`, `.run()`, `.execute()`, `.prepare()`, and the builder embedded as
18
- a subquery (`inArray(col, db.select(...).from(t))`).
18
+ a subquery (`inArray(col, db.select(...).from(t))`). The firewall-on-write
19
+ check on an `INSERT` is async, so it runs when the insert executes — on
20
+ `await`, on any executor, and ahead of `db.batch([...])`. A `.prepare()`d
21
+ insert into a table that needs the check is refused (`FIREWALL_WRITE_CHECK_UNSUPPORTED`):
22
+ it would run later with nothing to check it.
23
+
24
+ The same refusal comes back from Postgres itself when an `INSERT` reaches the
25
+ database outside the caller's firewall (RLS `42501`): the action route maps it
26
+ to the same **403 `FIREWALL_WRITE_DENIED`** Problem, never a generic action
27
+ failure — so D1 and Postgres answer alike.
19
28
 
20
29
  It is not a guess from column names. `any:` groups, `optional` arms, scope
21
30
  (`ctx.scope.*`) and `via:` relationship arms, the null-claim deny, the
@@ -283,6 +292,12 @@ predicate in the `WHERE` (for example,
283
292
 
284
293
  Actions that need to bypass scoped DB filters (for example, platform-level support operations) can enable unsafe mode.
285
294
 
295
+ `unsafeDb` and a raw `createDb()` handle are **unchecked by design**: no
296
+ firewall `WHERE`, no claim stamping, no firewall-on-write check. On Postgres a
297
+ non-cross-tenant `unsafeDb` still runs under the caller's RLS claims, so an
298
+ insert the policy refuses comes back as 403 `FIREWALL_WRITE_DENIED`; on D1 it
299
+ lands. That is the point of the escape hatch — and why it is audited.
300
+
286
301
  `unsafe` is the only sanctioned way around the scoped `db`. The compiler warns
287
302
  when a non-`unsafe` action — or a file it imports from the feature's `lib/`,
288
303
  the project's `lib/`, `hooks/` or `plugins/` (relative or `~/` imports) —
@@ -197,6 +197,8 @@ Every **child op** then pays:
197
197
  8. **Server-minted child ids** — a client-supplied child primary key on an
198
198
  insert is rejected (like the plain POST's strict body schema), unless the
199
199
  project is configured for client-provided ids (`generateId: false`).
200
+ There the id is exempt from the child's `guards.createable`, as on the
201
+ plain POST.
200
202
 
201
203
  Child `delete` ops stamp the **fixed `deletedAt`** audit column — exactly what
202
204
  the plain DELETE route stamps (the audit wrapper then auto-stamps
@@ -118,6 +118,16 @@ type FirewallConfig = ReadonlyArray<FirewallPredicate>;
118
118
  firewallErrorMode?: 'reveal' | 'hide';
119
119
  ```
120
120
 
121
+ An `equals` value that doesn't start with `ctx.` is a **literal**: `{ field: 'visibility', equals: 'studio' }` emits `eq(table.visibility, "studio")`. Like any status filter it is enforced by the API only — in Postgres RLS a literal arm lowers to `true`, so `any: [studio, { all: [private, owner] }]` keeps its OR shape instead of hardening into an owner-only policy.
122
+
123
+ On Postgres the RLS scope policy mirrors the firewall's `all`/`any` tree arm for arm, and the **database enforces relationship arms too**:
124
+
125
+ - A `via:` arm lowers to `project_id IN (SELECT r.project_id FROM public.qb_rel_<relationship>() r)` — a `SECURITY DEFINER` helper that runs the same relationship lookup as the API (subject = the caller's claim, the `where:` literals, the related table's soft delete). The generated API calls the same helper for every relationship lookup on Postgres, so a caller with no active org gets the same rows from the API as the policy admits. `[org, { any: [owner, { via }] }]` becomes `org AND (owner OR project_id IN (…))`, never `org AND owner`. See [Relationship arms in SQL](/platform/database/neon#relationship-arms-in-sql).
126
+ - A `{ permission }` arm expands exactly as the API expands it: relation leaves become `via:` helpers, arrows become `qb_arrow_…` helpers (a recursive arrow is a `maxDepth`-bounded closure).
127
+ - Inside an `any` group that also has an org arm, the relationship, scope and principal arms are tenant-bound exactly where the API binds them — `(<arm> AND (organization_id = <active org> OR <no active org>))` — so an org-claiming caller never rides them into another org.
128
+ - The soft-delete filter the API adds to a table carrying `deletedAt` reaches the policy too, as `deleted_at IS NULL OR public.in_soft_delete()` in `USING` only — see [the soft-delete lane](/platform/database/neon#the-soft-delete-lane).
129
+ - Literals, literal `in` lists, and claims the Worker never writes into the transaction (`ctx.scope.<kind>.<subKey>`, area anchors like `ctx.event.id`, string `in` sets) stay API-only and lower to `true` — the policy has nothing to compare them against, and a literal conjunct would refuse status-changing updates.
130
+
121
131
  The top-level array is AND'd together. `firewallErrorMode` lives at the resource top level — it's a presentation-layer choice (403 vs 404), not a query-shape one.
122
132
 
123
133
  ## Boolean groups: `all` / `any`
@@ -516,6 +526,35 @@ export default defineTable(records, {
516
526
  });
517
527
  ```
518
528
 
529
+ ### Firewall on write
530
+
531
+ A create may not land a row the caller could not read. When a firewall's
532
+ admission isn't guaranteed by the values a create stamps — a `via:` or
533
+ `{ permission }` arm (a task in a project you have no relationship to), a
534
+ literal or `in` arm, any `any:` group — every create path (`POST /`,
535
+ `POST /batch`, the create side of `PUT /:id` and `PUT /batch`, and a changeset's
536
+ root and owned-child inserts) evaluates the table's own firewall against the new
537
+ row before inserting it — and so does an action's [scoped `db`](/define/actions/scoped-db)
538
+ on every `insert(...).values(...)` (single row or array, and the insert branch
539
+ of an upsert) — and refuses with:
540
+
541
+ ```json
542
+ {
543
+ "error": "Record would be outside your firewall",
544
+ "code": "FIREWALL_WRITE_DENIED",
545
+ "layer": "firewall"
546
+ }
547
+ ```
548
+
549
+ Status `403`. The verdict is the same on D1 and Postgres: it is the table's
550
+ generated `buildFirewallConditions` — the same WHERE every read applies —
551
+ evaluated over the candidate row. (On Postgres the RLS policy would refuse the
552
+ row anyway; a refusal that still reaches the database maps to the same Problem,
553
+ never a raw `42501` — in a CRUD route or an action.) Firewalls made only of
554
+ stamped `ctx.*` equalities and `isNull` skip the check — the stamps already
555
+ guarantee admission. An action's `unsafeDb` and a raw `createDb()` handle are
556
+ unchecked by design (see [Unsafe Mode](/define/actions/scoped-db#unsafe-mode)).
557
+
519
558
  ### Foreign-Key Referential Checks
520
559
 
521
560
  Every generated write handler — `POST /`, `POST /batch`, `PATCH /:id`, `PATCH /batch`, `PUT /:id` (both its update and create paths), `PUT /batch`, and the root of a [changeset](/define/changesets) — validates foreign-key columns against the **target table's** firewall before writing. Creates check every FK in the body; updates check every FK whose value **changes** (a value equal to the stored one costs no query). If a record references a row that the caller can't see (wrong org, soft-deleted, or non-existent), the request fails with:
@@ -65,7 +65,7 @@ guards: {
65
65
 
66
66
  | List | What it controls |
67
67
  |------|------------------|
68
- | `createable` | Fields allowed in create (POST) request body |
68
+ | `createable` | Fields allowed in create (POST) request body. A client-supplied `id` (`generateId: false` or `allowClientIds`) is exempt and need not be listed |
69
69
  | `updatable` | Fields allowed in update (PATCH) request body |
70
70
  | `protected` | Fields blocked from direct writes; writable only by the actions named for them |
71
71
  | `immutable` | Fields allowed on create, then never written again — by CRUD, batch, changeset, **or actions** |
@@ -284,7 +284,12 @@ When upsert creates a new record, ownership fields are auto-set from context:
284
284
  | `'short'` | No | Server generates 6-char alphanumeric ID (e.g. `a3F9xK`) |
285
285
  | `'prefixed'` | No | Server generates prefixed ID (e.g. `room_abc123`) |
286
286
  | `'serial'` | No | Database auto-increments |
287
- | `false` | Yes (if guards: false) | Client provides ID |
287
+ | `false` | Yes (if guards: false) | Client provides ID (required on create) |
288
+
289
+ Under `generateId: false` a guarded table still creates normally: the
290
+ client-supplied `id` is compiler-managed, not a guarded field, so it is exempt
291
+ from `createable` — list only the fields the client may set. Guards keep
292
+ rejecting every other field outside `createable`.
288
293
 
289
294
  Need client-generated ids without giving up server minting or guards? Set
290
295
  `allowClientIds: true` instead — creates accept an **optional**
@@ -168,6 +168,20 @@ export default feature('candidates', {
168
168
  | `'redact'` | `anything` | `[REDACTED]` |
169
169
  | `'custom'` | (your logic) | (your output) |
170
170
 
171
+ ### Non-string columns
172
+
173
+ The string-shaped masks (`email`, `phone`, `ssn`, `creditCard`, `name`) format
174
+ text, so they are a compile error on a column whose value isn't a string —
175
+ `q.int()`, `q.bigint()`, `q.smallint()`, `q.bool()`, `q.json()`,
176
+ `q.timestamp()` (a `Date` on Postgres), or any `.array()`. Use `'redact'` or
177
+ `'custom'` there.
178
+
179
+ A redacted non-string value arrives as the string `"[REDACTED]"` — a masked
180
+ `q.int()` is not a number for that caller. The generated types say so:
181
+ [`Qb.Masked<number>`](/api/typescript#masked-columns) admits `Qb.Redacted`,
182
+ and OpenAPI documents the column as
183
+ `anyOf: [{ type: "integer" }, { type: "string", enum: ["[REDACTED]"] }]`.
184
+
171
185
  ## Configuration
172
186
 
173
187
  ```typescript
@@ -115,6 +115,9 @@ Single-record `GET /:id` evaluates checks in this order to close the
115
115
  404-vs-403 ID-probe channel:
116
116
 
117
117
  1. **Auth gate** — 401 if unauthenticated
118
+ - **Id shape** — 400 `INVALID_ID` if `:id` can't be one of this table's ids
119
+ (see [Malformed ids](/api/crud#malformed-ids-400-invalid_id)); depends on
120
+ the URL string alone, so it reveals nothing about which rows exist
118
121
  2. **Pre-record access** — role-only check (skips `access.record` predicates)
119
122
  3. **Firewall query** — `WHERE` clause filters by ownership
120
123
  4. **Post-record access** — full check including record-level predicates
@@ -96,6 +96,15 @@ export default defineConfig({
96
96
  >
97
97
  > Adding `defineTable` does not force a public API onto the join table — gate or omit its
98
98
  > `read` / `crud` blocks as you would any other table. What it supplies is the firewall.
99
+ >
100
+ > The `from:` table may also be the table that consumes the relationship — e.g.
101
+ > `projectMemberOf = { from: 'projectMembers', … }` used as `{ field: 'projectId', via: 'projectMemberOf' }`
102
+ > on `projectMembers` itself ("see the members of projects I belong to"). The subquery then
103
+ > calls the module's own firewall with `skipTenantScopes`, which returns before any `via:`
104
+ > arm is built, so it cannot recurse. On Postgres the API and the database both read the
105
+ > relationship through a `SECURITY DEFINER` helper (`public.qb_rel_<relationship>()`) that reads
106
+ > the relationship table without its own policy, so neither can recurse — see
107
+ > [Relationship arms in SQL](/platform/database/neon#relationship-arms-in-sql).
99
108
 
100
109
 
101
110
  ### Using relationship-roles in resources
@@ -110,7 +110,7 @@ A few mechanics to know:
110
110
  | Builder | Drizzle equivalent | Zod type |
111
111
  |---------|---------------------|----------|
112
112
  | `q.text()` | `text(...)` | `z.string()` |
113
- | `q.url()` | `text(...)` | `z.string().url()` |
113
+ | `q.url()` | `text(...)` | `z.string().url({ protocol: /^https?$/ })` |
114
114
  | `q.int()` | `integer(...)` | `z.number().int()` |
115
115
  | `q.bigint()` | `bigint(..., { mode: 'number' })` | `z.number().int()` within ±(2^53 − 1) |
116
116
  | `q.smallint()` | `smallint(...)` | `z.number().int()` within −32768..32767 |
@@ -132,9 +132,9 @@ In request bodies a column that is not `.required()` is `.optional().nullable()`
132
132
 
133
133
  `q.text()` and `q.url()` accept either a SQL-name string or an options object — `q.text({ sqlName: 'org_id', maxLength: 80 })`. `maxLength` adds `z.string().max(n)` at the validation edge; the SQL column stays `text` (D1 ignores `VARCHAR(n)` length anyway).
134
134
 
135
- `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
135
+ `q.url()` is `q.text()` plus an absolute-`http(s)`-URL check at the validation edge, so `javascript:` / `data:` / `ftp:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
136
136
 
137
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting. This keeps q's output decoupled from any specific ID library.
137
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting (default `"uuid"`). This keeps q's output decoupled from any specific ID library.
138
138
 
139
139
  #### Typed JSON columns
140
140
 
@@ -168,11 +168,12 @@ The schema must be written inline from `z` and literals, because the compiler co
168
168
  - using `z` anywhere else in the table file
169
169
  - importing anything from `zod` other than `{ z }`
170
170
 
171
- For `generateId: "cuid"`, there is one important nuance: import-capable runtime
172
- paths can emit real `createId()` usage, but compiler-managed schema
173
- auto-injection may keep the same `createId()` call site and back it with a
174
- file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes do not
175
- depend on project `node_modules`.
171
+ Under `generateId: "cuid"`, `"nanoid"`, or `"short"`, the `q.id()` default
172
+ calls an npm helper (`createId` from `@paralleldrive/cuid2`, or `nanoid` /
173
+ `customAlphabet` from `nanoid`). Don't import it in the table file, which may
174
+ not import either package. The compiler adds the import to the generated
175
+ `schema.ts` and the package to `package.json`, so the default mints the same
176
+ id shape as the CRUD route.
176
177
 
177
178
  ### Decimals, dates, 64-bit integers, and arrays
178
179
 
@@ -212,6 +213,7 @@ export default feature("invoices", {
212
213
 
213
214
  - **Decimals are strings**, so no value passes through a float. Send `"19.9"` and the API stores and returns `"19.90"`: the value is padded to `scale` digits and leading zeros are dropped, which is how Postgres prints `numeric(p,s)`. D1 stores that same canonical text, so both dialects return identical strings. `precision` (1–1000) and `scale` (0–`precision`) must be number literals, or the compile fails.
214
215
  - **Dates have no time zone.** A `q.date()` value is never converted, so `"2026-03-31"` is the same day for every caller. Use `q.timestamp()` for an instant.
216
+ - **Timestamps are ISO strings on the wire, on both dialects.** On D1, `q.timestamp()` is `text` holding the ISO string. On Postgres it is `timestamptz`. The column accepts a `Date` or an ISO string on write, and its TypeScript type is `Date | string`. Reads come back as a `Date`, which serializes as the same ISO `Z` string. Because Drizzle uses one type for reads and writes, a read is also typed `Date | string` even though it is always a `Date` at runtime — wrap it as `new Date(row.dueAt)` before calling `Date` methods such as `.getTime()` (a breaking type change for Postgres projects written against the earlier `Date`-only type). So `.set({ archivedAt: now })` works and typechecks on either database, on every handle: the scoped `db`, `unsafeDb`, and a raw `createDb()`. Postgres feature schemas import this column's `timestamp` from the generated `src/lib/pg-timestamp.ts` instead of `drizzle-orm/pg-core`. Its SQL type and migrations are unchanged. Filter values for a Postgres timestamp column must parse as a timestamp, or the request returns `400`.
215
217
  - **`q.bigint()` values are JSON numbers, and are capped at ±(2^53 − 1).** Past that, a JSON number can't hold an exact integer, and D1 returns every `INTEGER` as a JS number. The cap still takes a cents column past $90 trillion, where `q.int()` (Postgres `integer`) stops at about $21.4 million. Values written to a Postgres `bigint` outside the API beyond 2^53 will read back rounded.
216
218
  - **Defaults are checked at compile time** against the same rules, because nothing re-validates a DDL default. `q.smallint().default(40000)` fails the compile. A decimal default must already be in canonical form, so write `.default("0.00")` for scale 2, not `"0"`.
217
219
  - **`.array()`** works on `q.text()`, `q.enum()`, `q.int()`, and `q.uuid()`, and must be written once. `.default([])` gives Postgres `'{}'` and D1 `'[]'`. An array column can't declare `.references()`: Postgres has no foreign keys over array elements, so use a join table.
@@ -228,6 +230,8 @@ What you can query depends on the type. The compiler refuses the rest at compile
228
230
 
229
231
  `.searchable()` and `.filterable("like")` are text-only. Masks that format strings (`email`, `phone`, `partial`, and the rest) are refused on `q.bigint()`, `q.smallint()`, and array columns; use `redact` or `custom` there. Decimal and date values are strings, so every mask type works on them. `.defaultNow()` is only accepted on `q.timestamp()`.
230
232
 
233
+ `.defaultNow()` stamps the insert time whenever an insert omits the column. On Postgres it is a real `DEFAULT now()`. On SQLite / D1 the column carries a constant `DEFAULT '1970-01-01T00:00:00.000Z'` (D1 refuses a non-constant default on `ALTER TABLE ADD COLUMN`) plus a `$defaultFn`, and the generated `src/db/index.ts` makes every Drizzle insert use the `$defaultFn` — so only raw SQL that omits the column gets the epoch. Compilers from v0.33.2 until this fix wrote the epoch for Drizzle inserts too; see [Troubleshooting → timestamps read 1970-01-01](/tooling/troubleshooting#timestamps-read-1970-01-01-sqlite--d1) to find and repair affected rows.
234
+
231
235
  ### q.scope() — tenant scope columns
232
236
 
233
237
  `q.scope(kind)` is the canonical way to declare a column that holds a tenant-scope value (org / owner / team). It compiles to `text(...).notNull()` like a regular required text column, plus metadata that the compiler reads to:
@@ -671,7 +675,7 @@ Opt out of audit injection entirely with `compiler.features.auditFields: false`
671
675
 
672
676
  The scoped `db` injected into actions stamps these four columns for you. A handle built directly from `createDb()` does not — that's the documented escape hatch for system writes, sessionless principals, and broad reads the scoped wrapper over-narrows.
673
677
 
674
- Those writes still land in audit-managed tables, and the managed columns carry a DDL default of the unix epoch (so `ALTER TABLE ADD COLUMN` works on populated tables). An omitted column therefore **does not** fail loudly on `NOT NULL` — it silently persists `1970-01-01T00:00:00.000Z`, which reads as a real timestamp everywhere downstream.
678
+ Those writes still land in audit-managed tables. A Drizzle insert that omits `createdAt` / `modifiedAt` gets the insert time (Postgres `DEFAULT now()`; on SQLite the column's `$defaultFn`), but nothing fills `createdBy` / `modifiedBy` — they stay `NULL`. On SQLite the managed timestamps also carry a DDL default of the unix epoch (so `ALTER TABLE ADD COLUMN` works on populated tables), so **raw SQL** that omits them does not fail on `NOT NULL` — it silently persists `1970-01-01T00:00:00.000Z`, which reads as a real timestamp everywhere downstream.
675
679
 
676
680
  Spread the stamp instead of hand-writing four columns at each call site:
677
681
 
@@ -770,7 +774,7 @@ If this is an intentional system-side write, use the unwrapped db directly.
770
774
  Two paths to fix it, depending on intent:
771
775
 
772
776
  - **Mint a synthetic actor** (preferred — preserves attribution) — populate `ctx.userId` with one of the conventions above before calling into your handler.
773
- - **Bypass the wrapper entirely** — use the unwrapped `createDb` instead of the request-context `db`. Use this only for migrations, schema repair, or backfill scripts where you genuinely don't want any audit attribution. The audit columns will fall back to DB defaults (`createdAt`/`modifiedAt` populate from `defaultNow()`; `createdBy`/`modifiedBy` end up `NULL`).
777
+ - **Bypass the wrapper entirely** — use the unwrapped `createDb` instead of the request-context `db`. Use this only for migrations, schema repair, or backfill scripts where you genuinely don't want any audit attribution. `createdAt`/`modifiedAt` still get the insert time from their column default (a raw SQL insert that omits them on SQLite gets the epoch — set them yourself); `createdBy`/`modifiedBy` end up `NULL`.
774
778
 
775
779
  ### Disabling Audit Fields
776
780
 
@@ -123,7 +123,9 @@ Semantics:
123
123
  - **`field: null`** declares a pure stamp transition (check-in/check-out
124
124
  style) — guards + stamps with no state column.
125
125
  - **`actx.now`**: every action's execute context now carries `now` — one ISO
126
- timestamp per invocation. Prefer it over `new Date().toISOString()`.
126
+ timestamp per invocation. Prefer it over `new Date().toISOString()`. It
127
+ writes into a `q.timestamp()` column as-is, on every database and every
128
+ `db` handle — see [Column types](/define/schema#decimals-dates-64-bit-integers-and-arrays).
127
129
 
128
130
  ### On a feature-area route
129
131
 
@@ -254,14 +256,19 @@ otherwise the action would be unreachable, which is almost certainly a bug.
254
256
 
255
257
  ### Wire-level errors
256
258
 
257
- The compiled guard returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** with
258
- the field, the current value, the requested target, and the allowed set:
259
+ The compiled guard returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** as
260
+ `application/problem+json` (like every [API error](/api/errors)), with the
261
+ field, the current value, the requested target, and the allowed set:
259
262
 
260
263
  ```json
261
264
  {
262
- "error": "Action not allowed for current record state",
263
- "layer": "access",
265
+ "type": "https://quickback.dev/problems/access-action-not-allowed-for-state",
266
+ "title": "Access action not allowed for state",
267
+ "status": 409,
264
268
  "code": "ACCESS_ACTION_NOT_ALLOWED_FOR_STATE",
269
+ "detail": "Action not allowed for current record state",
270
+ "instance": "/api/v1/applications/app_123/advance",
271
+ "layer": "access",
265
272
  "details": {
266
273
  "field": "status",
267
274
  "current": "interview",
@@ -372,5 +372,6 @@ execute: async ({ db, effects }) => {
372
372
 
373
373
  Effects enqueued by an `execute` that later throws are dropped. The context
374
374
  also carries `now` — one ISO timestamp per invocation; prefer it over
375
- `new Date().toISOString()`.
375
+ `new Date().toISOString()`. See [Column types](/define/schema#decimals-dates-64-bit-integers-and-arrays) for
376
+ writing it into a `q.timestamp()` column.
376
377
 
@@ -76,5 +76,6 @@ The runtime services around your compiled code. Everything you need for a comple
76
76
  - **[Webhooks](/platform/webhooks)** — Inbound (signed) and outbound (retried)
77
77
  - **[Admin UI](/ui/admin)** — Schema-driven admin UI
78
78
  - **[Account UI](/ui/account)** — Pre-built auth and profile pages
79
+ - **[Components](/ui/components)** — shadcn tables, forms, and action dialogs for your own React app
79
80
 
80
81
  Everything runs on **your own Cloudflare account** — no Quickback infrastructure between you and your data.
@@ -124,7 +124,7 @@ When `fromOpenAPI: false`, the emitted call has `capabilities: []` and no proxy
124
124
  - **WebAuthn step-up isn't wired in the approval UI yet.** Capabilities tagged `approvalStrength: "webauthn"` show a Step-up badge but the actual escalation call isn't made — the upstream API for that escalation is still settling. Until it lands, those capabilities will fail server-side regardless of approval.
125
125
  - **No CLI helpers for listing / revoking agents.** Use the BA admin API directly.
126
126
  - **Self-fetch on Cloudflare Workers** adds one subrequest per capability call (~50ms). For typical agent traffic this is fine; for very high-frequency agents consider pinning a custom `onExecute` that uses `app.request()` for in-process routing.
127
- - **`@better-auth/agent-auth` 0.4.5 ships ESM-only exports** without a `require` condition. The compiler image patches the package's `package.json` at install time so the Better Auth CLI's `auth generate` step (jiti / CJS) can resolve it. Remove the patch in the Dockerfile when upstream ships proper exports.
127
+ - **`@better-auth/agent-auth` 0.6.2 ships ESM-only exports** without a `require` condition. The compiler image patches the package's `package.json` at install time so the Better Auth CLI's `auth generate` step (jiti / CJS) can resolve it. Remove the patch in the Dockerfile when upstream ships proper exports.
128
128
 
129
129
  ## Why bearer-only?
130
130