@quickback-dev/cli 0.66.0 → 0.66.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -4
- package/dist/commands/build.d.ts +51 -0
- package/dist/commands/build.d.ts.map +1 -0
- package/dist/commands/build.js +793 -0
- package/dist/commands/build.js.map +1 -0
- package/dist/commands/build.test.d.ts +2 -0
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/build.test.js +150 -0
- package/dist/commands/build.test.js.map +1 -0
- package/dist/commands/check.d.ts +2 -2
- package/dist/commands/check.js +4 -4
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.d.ts +1 -1
- package/dist/commands/create.js +7 -7
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/deploy.d.ts +6 -6
- package/dist/commands/deploy.js +23 -23
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/example.js +1 -1
- package/dist/commands/example.js.map +1 -1
- package/dist/commands/mcp.js +1 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/commands/migrate.d.ts +1 -1
- package/dist/commands/migrate.js +3 -3
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrations.js +2 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/push.js +1 -1
- package/dist/commands/push.js.map +1 -1
- package/dist/commands/start.js +1 -1
- package/dist/commands/start.js.map +1 -1
- package/dist/cursor/quickback.mdc +1 -1
- package/dist/index.js +18 -15
- package/dist/index.js.map +1 -1
- package/dist/lib/auth.js +1 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/compiler-floor.d.ts +1 -1
- package/dist/lib/compiler-floor.js +1 -1
- package/dist/lib/file-loader.js +2 -2
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +16 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.js +16 -0
- package/dist/lib/file-writer.test.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +3 -3
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/prepare-output.test.js +1 -1
- package/dist/lib/prepare-output.test.js.map +1 -1
- package/dist/lib/schema-sync/index.js +1 -1
- package/dist/lib/schema-sync/index.test.js +1 -1
- package/dist/lib/schema-sync/index.test.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +5 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/lib/wrangler-resources.test.js +6 -0
- package/dist/lib/wrangler-resources.test.js.map +1 -1
- package/dist/skill/SKILL.md +24 -9
- package/dist/skill/docs/api/crud.md +7 -0
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/changelog/index.md +27 -1
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +11 -5
- package/dist/skill/docs/configure/providers.md +6 -3
- package/dist/skill/docs/configure/single-tenant.md +7 -3
- package/dist/skill/docs/configure/variables.md +3 -3
- package/dist/skill/docs/define/access.md +10 -0
- package/dist/skill/docs/define/actions/defining.md +35 -7
- package/dist/skill/docs/define/actions/index.md +1 -1
- package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/dist/skill/docs/define/actions/scoped-db.md +68 -21
- package/dist/skill/docs/define/areas.md +1 -1
- package/dist/skill/docs/define/diagnostics.md +1 -0
- package/dist/skill/docs/define/encryption.md +1 -1
- package/dist/skill/docs/define/feature.md +17 -8
- package/dist/skill/docs/define/firewall.md +2 -0
- package/dist/skill/docs/define/guards.md +27 -3
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/relationships.md +7 -0
- package/dist/skill/docs/define/schema.md +44 -14
- package/dist/skill/docs/define/security.md +1 -1
- package/dist/skill/docs/define/transitions.md +35 -4
- package/dist/skill/docs/define/triggers.md +14 -3
- package/dist/skill/docs/define/views.md +33 -0
- package/dist/skill/docs/index.md +2 -2
- package/dist/skill/docs/platform/auth/api-keys.md +2 -2
- package/dist/skill/docs/platform/auth/using-auth.md +37 -0
- package/dist/skill/docs/platform/database/d1.md +15 -3
- package/dist/skill/docs/platform/database/neon.md +4 -4
- package/dist/skill/docs/platform/email/index.md +1 -1
- package/dist/skill/docs/platform/queues/handlers.md +1 -1
- package/dist/skill/docs/platform/queues/using-queues.md +1 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +6 -4
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/index.md +3 -3
- package/dist/skill/docs/platform/storage/r2.md +87 -37
- package/dist/skill/docs/platform/storage/using-r2.md +99 -19
- package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
- package/dist/skill/docs/start/deploy-browser.md +40 -45
- package/dist/skill/docs/start/deploy-owner-access.md +60 -52
- package/dist/skill/docs/start/deploy.md +4 -4
- package/dist/skill/docs/start/first-api.md +2 -2
- package/dist/skill/docs/start/hand-crafted.md +3 -3
- package/dist/skill/docs/start/index.md +3 -3
- package/dist/skill/docs/start/patterns.md +17 -2
- package/dist/skill/docs/start/quickstart.md +3 -3
- package/dist/skill/docs/start/template-blog.md +2 -2
- package/dist/skill/docs/start/template-cloudflare.md +3 -3
- package/dist/skill/docs/start/template-empty.md +1 -1
- package/dist/skill/docs/start/templates.md +1 -1
- package/dist/skill/docs/tooling/claude-skill.md +1 -1
- package/dist/skill/docs/tooling/cli.md +21 -16
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
- package/dist/skill/docs/tooling/output.md +23 -2
- package/dist/skill/docs/tooling/troubleshooting.md +1 -1
- package/dist/skill/docs/ui/account/customization.md +1 -1
- package/dist/skill/docs/ui/account/environment-variables.md +2 -2
- package/dist/skill/docs/ui/account/features/admin.md +1 -1
- package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
- package/dist/skill/docs/ui/account/features/avatars.md +24 -8
- package/dist/skill/docs/ui/account/features/index.md +16 -11
- package/dist/skill/docs/ui/account/features/organizations.md +3 -2
- package/dist/skill/docs/ui/account/hooks.md +2 -0
- package/dist/skill/docs/ui/account/index.md +10 -5
- package/dist/skill/docs/ui/account/with-quickback.md +2 -2
- package/dist/skill/docs/ui/admin/actions.md +97 -3
- package/dist/skill/docs/ui/admin/components.md +4 -6
- package/dist/skill/docs/ui/admin/connecting.md +15 -3
- package/dist/skill/docs/ui/admin/index.md +71 -6
- package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
- package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
- package/dist/skill/docs/ui/admin/schema-format.md +39 -2
- package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
- package/dist/skill/docs/ui/admin/security.md +19 -4
- package/dist/skill/docs/ui/admin/table-views.md +59 -12
- package/package.json +1 -1
- package/src/cursor/quickback.mdc +1 -1
- package/src/skill/SKILL.md +24 -9
- package/src/skill/docs/api/crud.md +7 -0
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/changelog/index.md +27 -1
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +11 -5
- package/src/skill/docs/configure/providers.md +6 -3
- package/src/skill/docs/configure/single-tenant.md +7 -3
- package/src/skill/docs/configure/variables.md +3 -3
- package/src/skill/docs/define/access.md +10 -0
- package/src/skill/docs/define/actions/defining.md +35 -7
- package/src/skill/docs/define/actions/index.md +1 -1
- package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/src/skill/docs/define/actions/scoped-db.md +68 -21
- package/src/skill/docs/define/areas.md +1 -1
- package/src/skill/docs/define/diagnostics.md +1 -0
- package/src/skill/docs/define/encryption.md +1 -1
- package/src/skill/docs/define/feature.md +17 -8
- package/src/skill/docs/define/firewall.md +2 -0
- package/src/skill/docs/define/guards.md +27 -3
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/relationships.md +7 -0
- package/src/skill/docs/define/schema.md +44 -14
- package/src/skill/docs/define/security.md +1 -1
- package/src/skill/docs/define/transitions.md +35 -4
- package/src/skill/docs/define/triggers.md +14 -3
- package/src/skill/docs/define/views.md +33 -0
- package/src/skill/docs/index.md +2 -2
- package/src/skill/docs/platform/auth/api-keys.md +2 -2
- package/src/skill/docs/platform/auth/using-auth.md +37 -0
- package/src/skill/docs/platform/database/d1.md +15 -3
- package/src/skill/docs/platform/database/neon.md +4 -4
- package/src/skill/docs/platform/email/index.md +1 -1
- package/src/skill/docs/platform/queues/handlers.md +1 -1
- package/src/skill/docs/platform/queues/using-queues.md +1 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +6 -4
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/index.md +3 -3
- package/src/skill/docs/platform/storage/r2.md +87 -37
- package/src/skill/docs/platform/storage/using-r2.md +99 -19
- package/src/skill/docs/platform/webhooks/inbound.md +40 -0
- package/src/skill/docs/start/deploy-browser.md +40 -45
- package/src/skill/docs/start/deploy-owner-access.md +60 -52
- package/src/skill/docs/start/deploy.md +4 -4
- package/src/skill/docs/start/first-api.md +2 -2
- package/src/skill/docs/start/hand-crafted.md +3 -3
- package/src/skill/docs/start/index.md +3 -3
- package/src/skill/docs/start/patterns.md +17 -2
- package/src/skill/docs/start/quickstart.md +3 -3
- package/src/skill/docs/start/template-blog.md +2 -2
- package/src/skill/docs/start/template-cloudflare.md +3 -3
- package/src/skill/docs/start/template-empty.md +1 -1
- package/src/skill/docs/start/templates.md +1 -1
- package/src/skill/docs/tooling/claude-skill.md +1 -1
- package/src/skill/docs/tooling/cli.md +21 -16
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
- package/src/skill/docs/tooling/output.md +23 -2
- package/src/skill/docs/tooling/troubleshooting.md +1 -1
- package/src/skill/docs/ui/account/customization.md +1 -1
- package/src/skill/docs/ui/account/environment-variables.md +2 -2
- package/src/skill/docs/ui/account/features/admin.md +1 -1
- package/src/skill/docs/ui/account/features/api-keys.md +10 -8
- package/src/skill/docs/ui/account/features/avatars.md +24 -8
- package/src/skill/docs/ui/account/features/index.md +16 -11
- package/src/skill/docs/ui/account/features/organizations.md +3 -2
- package/src/skill/docs/ui/account/hooks.md +2 -0
- package/src/skill/docs/ui/account/index.md +10 -5
- package/src/skill/docs/ui/account/with-quickback.md +2 -2
- package/src/skill/docs/ui/admin/actions.md +97 -3
- package/src/skill/docs/ui/admin/components.md +4 -6
- package/src/skill/docs/ui/admin/connecting.md +15 -3
- package/src/skill/docs/ui/admin/index.md +71 -6
- package/src/skill/docs/ui/admin/inline-editing.md +38 -4
- package/src/skill/docs/ui/admin/record-layouts.md +22 -21
- package/src/skill/docs/ui/admin/schema-format.md +39 -2
- package/src/skill/docs/ui/admin/schema-registry.md +107 -7
- package/src/skill/docs/ui/admin/security.md +19 -4
- package/src/skill/docs/ui/admin/table-views.md +59 -12
|
@@ -100,12 +100,13 @@ single Postgres database with no bindings or split mode (see
|
|
|
100
100
|
| `featuresBinding` | `string` | `"DB"` | Binding name for features database |
|
|
101
101
|
| `databaseId` | `string` | — | D1 database ID for the features database (used in generated wrangler.toml) |
|
|
102
102
|
| `authDatabaseId` | `string` | — | D1 database ID for the auth database |
|
|
103
|
+
| `authMigrations` | `'managed' \| 'external'` | `'managed'` | `'external'` when another project owns the auth D1 (a sibling worker sharing one auth database): no `db:migrate:auth:*` script is emitted and `db:migrate:*` / `deploy` skip it. Deleting the step from `package.json` by hand does not stick — compiler-owned scripts converge on every compile |
|
|
103
104
|
| `featuresDatabaseId` | `string` | — | Explicit features DB ID (falls back to `databaseId`) |
|
|
104
105
|
| `filesDatabaseId` | `string` | — | D1 database ID for the files metadata database |
|
|
105
106
|
| `webhooksDatabaseId` | `string` | — | D1 database ID for the webhooks database |
|
|
106
107
|
| `auditBinding` | `string` | `"AUDIT_DB"` | Binding name for the security audit database |
|
|
107
108
|
| `auditDatabaseName` | `string` | `"{app}-audit"` | D1 database name for audit events |
|
|
108
|
-
| `auditDatabaseId` | `string` | — |
|
|
109
|
+
| `auditDatabaseId` | `string` | — | D1 database ID for audit events. Optional at compile time — a placeholder is emitted and `quickback deploy` / the Start broker create the database and splice the real id back |
|
|
109
110
|
| `experimentalRemote` | `{ auth?, features?, audit?, webhooks?, files? }` | `{}` | Per-binding `experimental_remote = true` flag for `wrangler dev` (see [below](#sharing-deployed-d1-in-dev-experimental_remote)) |
|
|
110
111
|
| `realtime` | `boolean \| { enabled?, wsTicket? }` | `false` | Enables the Broadcaster Durable Object and optional resource-scoped ws-ticket auth (see [below](#realtime-broadcast-config)) |
|
|
111
112
|
| `webhookAdminRoles` | `string[]` | `["owner", "admin"]` | Org roles allowed to manage webhook endpoints |
|
|
@@ -127,7 +128,9 @@ connection modes, RLS, and the migration workflow.
|
|
|
127
128
|
|
|
128
129
|
Cross-tenant `unsafe` actions (see [Actions → Unsafe mode](/define/actions/scoped-db#unsafe-mode)) write mandatory audit events. Those events land in a dedicated D1 database — separate from your features DB — so audit history stays isolated from application data and can't be tampered with through a normal CRUD route.
|
|
129
130
|
|
|
130
|
-
You don't need to do anything to enable it — the compiler wires up the binding automatically if your project declares any unsafe action.
|
|
131
|
+
You don't need to do anything to enable it — the compiler wires up the binding automatically if your project declares any unsafe, `PUBLIC`, or hard-delete action. Leave `auditDatabaseId` unset until deploy: compile emits a placeholder, and `quickback deploy` (or the Start Cloudflare card) creates the D1 and writes the id back. Do not put an empty string in the config.
|
|
132
|
+
|
|
133
|
+
To override defaults:
|
|
131
134
|
|
|
132
135
|
```typescript
|
|
133
136
|
providers: {
|
|
@@ -139,7 +142,7 @@ providers: {
|
|
|
139
142
|
}
|
|
140
143
|
```
|
|
141
144
|
|
|
142
|
-
The binding name must match what your Worker reads at runtime. If you don't declare any unsafe actions, no audit DB is provisioned and these options have no effect.
|
|
145
|
+
The binding name must match what your Worker reads at runtime. If you don't declare any unsafe, `PUBLIC`, or hard-delete actions, no audit DB is provisioned and these options have no effect.
|
|
143
146
|
|
|
144
147
|
#### Setting Database IDs for Deployment
|
|
145
148
|
|
|
@@ -25,9 +25,13 @@ export default defineConfig({
|
|
|
25
25
|
});
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
> **
|
|
28
|
+
> **The organization must exist**
|
|
29
29
|
>
|
|
30
|
-
> `pinnedOrganizationId`
|
|
30
|
+
> `pinnedOrganizationId` is the Better Auth organization id the compiled Worker hard-codes. The compiler does not insert that row.
|
|
31
|
+
>
|
|
32
|
+
> A **browser deploy** from Quickback Start does: the broker writes `organization.id` as this exact string, seeds `user.role = "sysadmin"`, and seats that user as `owner` of the org. `org_default` is a valid id — use it when you do not have a pre-existing org.
|
|
33
|
+
>
|
|
34
|
+
> A **CLI deploy** (`quickback deploy`) does not seed AUTH_DB. Create the organization yourself (or deploy once through Start) so the pin points at a real row.
|
|
31
35
|
|
|
32
36
|
|
|
33
37
|
## Removed Single-Tenant Settings
|
|
@@ -96,7 +100,7 @@ This is the intended replacement for the old single-tenant CMS flow.
|
|
|
96
100
|
## Migration from Single-Tenant Mode
|
|
97
101
|
|
|
98
102
|
1. Remove `features.organizations: false`.
|
|
99
|
-
2. Add `features.pinnedOrganizationId: "<
|
|
103
|
+
2. Add `features.pinnedOrganizationId: "<org-id>"`. On a Start deploy, that string is the org the broker inserts — `"org_default"` is fine. On a CLI deploy, it must already exist in AUTH_DB.
|
|
100
104
|
3. Remove any assumptions that `ctx.roles` mirrors `user.role`.
|
|
101
105
|
4. If you need platform-wide roles, keep those checks on `userRole`, not `roles`.
|
|
102
106
|
|
|
@@ -19,13 +19,13 @@ The CLI authenticates via two methods:
|
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
21
|
# Use the cloud compiler (default)
|
|
22
|
-
quickback
|
|
22
|
+
quickback build
|
|
23
23
|
|
|
24
24
|
# Use a local compiler instance
|
|
25
|
-
QUICKBACK_API_URL=http://localhost:3000 quickback
|
|
25
|
+
QUICKBACK_API_URL=http://localhost:3000 quickback build
|
|
26
26
|
|
|
27
27
|
# CI/CD with API key
|
|
28
|
-
QUICKBACK_API_KEY=qb_key_... quickback
|
|
28
|
+
QUICKBACK_API_KEY=qb_key_... quickback build
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
## Compiler Service Variables
|
|
@@ -23,6 +23,9 @@ Start here. **Most apps need only the first row** — this page, and nothing bel
|
|
|
23
23
|
> declare a relationship to ask "is this person in the org?" — a relationship's `from:` must
|
|
24
24
|
> be one of *your* feature tables, and the compiler rejects one pointing at Better Auth's
|
|
25
25
|
> `organization_memberships`. See [the authorization ladder](/define#the-authorization-ladder).
|
|
26
|
+
>
|
|
27
|
+
> To validate a *submitted* user id (an assignee), query AUTH_DB from an action —
|
|
28
|
+
> see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
26
29
|
|
|
27
30
|
|
|
28
31
|
## Basic Usage
|
|
@@ -411,6 +414,13 @@ opaque 404 instead.
|
|
|
411
414
|
Function-form access (`access: async (ctx, record) => ...`) is opaque to
|
|
412
415
|
the pre-record phase and always passes there; it's fully evaluated post-record.
|
|
413
416
|
|
|
417
|
+
Collection routes (`GET /`, `POST /batch`, and the generated MCP list tool)
|
|
418
|
+
stop at step 2: there is no record to evaluate, so `access.record` is **not**
|
|
419
|
+
applied to a list — row scoping on a list is the [firewall's](/define/firewall)
|
|
420
|
+
job. Don't use an unsatisfiable predicate (`record: { id: { equals: "never" } }`)
|
|
421
|
+
to hide a resource; it still lists. To give a resource no read surface, omit
|
|
422
|
+
`read` — no list, get, batch, or MCP route is emitted.
|
|
423
|
+
|
|
414
424
|
## Context Variables
|
|
415
425
|
|
|
416
426
|
Use `$ctx.` prefix to reference context values in conditions:
|
|
@@ -5,7 +5,6 @@
|
|
|
5
5
|
```typescript
|
|
6
6
|
// features/applications/actions/advance.ts
|
|
7
7
|
import { z } from "zod";
|
|
8
|
-
import { eq } from "drizzle-orm";
|
|
9
8
|
import { defineAction, applications } from "../.quickback/define-action";
|
|
10
9
|
|
|
11
10
|
export default defineAction({
|
|
@@ -56,11 +55,11 @@ export default defineAction({
|
|
|
56
55
|
> `db.insert().values()` and `db.update().set()` — handlers don't pass
|
|
57
56
|
> them and can't override them.
|
|
58
57
|
|
|
59
|
-
> **Your editor is typed too.** `quickback
|
|
58
|
+
> **Your editor is typed too.** `quickback build` writes the same typed
|
|
60
59
|
> helpers into `quickback/features/<feature>/.quickback/` (plus a
|
|
61
60
|
> `quickback/tsconfig.json`), so the import above resolves — and typechecks —
|
|
62
61
|
> in the tree you actually edit, not just in the generated output. The helper
|
|
63
|
-
> also **re-exports the feature
|
|
62
|
+
> also **re-exports every table in the feature** typed with the generated schema, so
|
|
64
63
|
> compiler-managed columns (`createdAt`, `modifiedBy`, `deletedAt`,
|
|
65
64
|
> `organizationId`) are visible on it without casts:
|
|
66
65
|
>
|
|
@@ -68,6 +67,10 @@ export default defineAction({
|
|
|
68
67
|
> import { defineAction, applications } from "../.quickback/define-action";
|
|
69
68
|
> ```
|
|
70
69
|
>
|
|
70
|
+
> Other tables in the same feature come from that same helper. The boundary is
|
|
71
|
+
> the **feature**, not the whole project: a table owned by another feature is
|
|
72
|
+
> not re-exported here.
|
|
73
|
+
>
|
|
71
74
|
> Prefer this single import over the older
|
|
72
75
|
> `import { applications } from "../applications"` — that path resolves to
|
|
73
76
|
> your authored file at edit time, which has no named export and none of the
|
|
@@ -75,6 +78,32 @@ export default defineAction({
|
|
|
75
78
|
> `quickback/features/*/.quickback/` in `.gitignore` (new projects get this
|
|
76
79
|
> automatically).
|
|
77
80
|
|
|
81
|
+
For an action that joins or writes a table owned by another feature, keep
|
|
82
|
+
`defineAction` from the action's own helper and import the other table
|
|
83
|
+
separately from its feature's generated helper (or generated table module).
|
|
84
|
+
Query operators come from the generated project `lib/q`, not from either
|
|
85
|
+
feature helper:
|
|
86
|
+
|
|
87
|
+
{/* doc-compile: skip — demonstrates generated cross-feature helper and runtime paths; the isolated fence does not declare either feature. */}
|
|
88
|
+
```typescript
|
|
89
|
+
// features/waitlist/actions/promote.ts
|
|
90
|
+
import {
|
|
91
|
+
defineAction,
|
|
92
|
+
waitlistEntries,
|
|
93
|
+
} from "../.quickback/define-action";
|
|
94
|
+
import { reservations } from "../../reservations/.quickback/define-action";
|
|
95
|
+
import { q } from "../../../lib/q";
|
|
96
|
+
|
|
97
|
+
// `defineAction` stays bound to waitlistEntries; reservations is only a table.
|
|
98
|
+
// For a direct generated-table import, use "../../reservations/reservations".
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
This waitlist/reservations shape is generic: for any cross-feature action, the
|
|
102
|
+
own-feature helper supplies the action's `record`, `whereRecord`, and
|
|
103
|
+
`whereTransition` context; each external feature supplies only its own tables.
|
|
104
|
+
Importing `defineAction` from the external feature would bind the wrong
|
|
105
|
+
context.
|
|
106
|
+
|
|
78
107
|
### Local action-schema harvest
|
|
79
108
|
|
|
80
109
|
Before sending a compile request, the CLI loads each action in an isolated
|
|
@@ -96,9 +125,8 @@ generated clients treat every required field as optional, and unknown keys pass.
|
|
|
96
125
|
Constructs it cannot parse at all degrade further, to a bare `{}` with no
|
|
97
126
|
`properties`. Neither is visible in a diff.
|
|
98
127
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
compiler warns again with the count and sampled paths.
|
|
128
|
+
There is no opt-out. Fix the action so its input schema harvests — the error
|
|
129
|
+
names each one, the phase that failed, and the underlying local error.
|
|
102
130
|
|
|
103
131
|
Bare imports are resolved from the generated runtime's configured
|
|
104
132
|
`build.outputDir/node_modules` first. If definitions live in `quickback/` and
|
|
@@ -183,6 +211,7 @@ namespace parameters.
|
|
|
183
211
|
| `record` | Standalone only | Feature-area transition adapter binding: `{ table, idFrom: "path.<param>", matchScope? }`. Binds + firewalls the record a `transition` operates on from a proven route param. See [Feature-area transition adapter](#feature-area-transition-adapter) |
|
|
184
212
|
| `bulkVariant` | No | Auto-generate a `POST /:resource/batch/{action}` route alongside the per-record route (record-based actions). See [Bulk Variant](#bulk-variant) |
|
|
185
213
|
| `webhook` | No | Standalone only. Compile-declared inbound signature verification (`standard-webhooks`, `hmac-sha256`, or `aws-sns`) that runs on the raw bytes **before** parse/access — see [Inbound webhooks](/platform/webhooks/inbound) |
|
|
214
|
+
| `rawBody` | No | Standalone, non-GET only. Hand `execute` the request body as received (`rawBody: string`, bounded to 1 MiB) for signature schemes the compiler does not model — a per-organization secret stored in the database, a provider with its own canonicalisation. `input` still parses from the same bytes. Actions with `webhook:` receive `rawBody` automatically — see [Per-organization secrets](/platform/webhooks/inbound#per-organization-secrets-verify-in-the-action) |
|
|
186
215
|
| `idempotency` | No | `'dedupe'` — PUBLIC-action opt-in for the `Idempotency-Key` header with dedupe-only semantics (duplicate ⇒ `409` reference; the cached body is never served to a second caller). Standalone actions with a **static** path only (a `:param` path is a compile error — the allowlist matches literal request paths) and the action's access must admit `PUBLIC`. Authenticated routes accept the header automatically — see [API contract](/platform/api-contract) |
|
|
187
216
|
| `cms` | No | Pass-through metadata blob for CMS surfaces |
|
|
188
217
|
|
|
@@ -243,4 +272,3 @@ export default defineAction({
|
|
|
243
272
|
- Ref keys must exist on the inline `z.object` input with agreeing
|
|
244
273
|
optionality; `as` names can't shadow reserved context keys. Injected rows
|
|
245
274
|
are the **unmasked** DB rows (masking remains a read-projection concern).
|
|
246
|
-
|
|
@@ -169,7 +169,7 @@ is not supported.
|
|
|
169
169
|
- **[Defining actions](/define/actions/defining)** — the action file, its configuration options, protected fields, and refs
|
|
170
170
|
- **[Record and standalone actions](/define/actions/record-and-standalone)** — the two shapes, and what `path:` changes
|
|
171
171
|
- **[Access](/define/actions/access)** — roles, record conditions, context substitution, relationship-roles
|
|
172
|
-
- **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, unsafe mode, raw SQL policy, sharing code
|
|
172
|
+
- **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, AUTH_DB vs `ctx`, unsafe mode, raw SQL policy, sharing code
|
|
173
173
|
- **[Examples](/define/actions/examples)** — end-to-end action files
|
|
174
174
|
|
|
175
175
|
Related: **[Transitions](/define/transitions)** for state-machine policy,
|
|
@@ -199,14 +199,17 @@ land in `success[]` masked the same way the single-record response is.
|
|
|
199
199
|
|
|
200
200
|
Standalone actions are independent endpoints that don't require a record context. Set a `path:` to declare the action standalone.
|
|
201
201
|
|
|
202
|
-
**
|
|
202
|
+
**Public URL:** `/api/v1` plus `path:`
|
|
203
203
|
|
|
204
204
|
```
|
|
205
|
-
POST /chat
|
|
206
|
-
GET /reports/summary
|
|
207
|
-
POST /webhooks/stripe
|
|
205
|
+
POST /api/v1/chat
|
|
206
|
+
GET /api/v1/reports/summary
|
|
207
|
+
POST /api/v1/webhooks/stripe
|
|
208
208
|
```
|
|
209
209
|
|
|
210
|
+
`path:` is the suffix under `/api/v1`. `path: "/chat"` and `path: "/api/v1/chat"`
|
|
211
|
+
are the same route. Write either; do not tell callers a URL that omits `/api/v1`.
|
|
212
|
+
|
|
210
213
|
Paths are absolute (`/...`). Inside a [feature area](/define/areas)
|
|
211
214
|
with a mounted prefix, two more forms apply:
|
|
212
215
|
|
|
@@ -157,11 +157,14 @@ Drizzle's relational query API — `db.query.<table>.findFirst()` /
|
|
|
157
157
|
relations config and your `where` alone, so the scoped wrapper cannot inject
|
|
158
158
|
the org/owner/team firewall into it. The scoped `db` therefore exposes the
|
|
159
159
|
Drizzle select builder—the path where Quickback can guarantee firewall
|
|
160
|
-
injection—and refuses `db.query.<table>` rather than returning unscoped rows
|
|
160
|
+
injection—and refuses `db.query.<table>` rather than returning unscoped rows.
|
|
161
|
+
The compiler rejects authored uses before code generation, including Start's
|
|
162
|
+
definition-validation build; the generated runtime guard remains as a
|
|
163
|
+
fail-closed backstop:
|
|
161
164
|
|
|
162
165
|
```typescript
|
|
163
166
|
async execute({ db, input }) {
|
|
164
|
-
// ❌
|
|
167
|
+
// ❌ Compile error: relational queries aren't org-scoped
|
|
165
168
|
const item = await db.query.media.findFirst({ where: eq(media.id, input.id) });
|
|
166
169
|
|
|
167
170
|
// ✅ Scoped builder — firewall conditions injected automatically
|
|
@@ -303,25 +306,53 @@ export default defineAction({
|
|
|
303
306
|
|
|
304
307
|
### Importing Tables
|
|
305
308
|
|
|
306
|
-
|
|
309
|
+
The action's own generated helper supplies `defineAction` and the tables owned
|
|
310
|
+
by that feature. It does not re-export tables from sibling features. Import a
|
|
311
|
+
cross-feature table from that feature's generated helper or generated table
|
|
312
|
+
module, and import Drizzle query operators through the generated project
|
|
313
|
+
`lib/q`:
|
|
307
314
|
|
|
315
|
+
{/* doc-compile: skip — demonstrates generated cross-feature helper and runtime paths; the isolated fence does not declare either feature. */}
|
|
308
316
|
```typescript
|
|
309
|
-
// features/
|
|
310
|
-
import {
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
import {
|
|
317
|
+
// features/waitlist/actions/promote.ts
|
|
318
|
+
import {
|
|
319
|
+
defineAction,
|
|
320
|
+
waitlistEntries,
|
|
321
|
+
} from "../.quickback/define-action";
|
|
322
|
+
import { reservations } from "../../reservations/.quickback/define-action";
|
|
323
|
+
import { q } from "../../../lib/q";
|
|
315
324
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
325
|
+
export default defineAction({
|
|
326
|
+
// ...input, access, and transition...
|
|
327
|
+
async execute({ db, record, whereRecord, now }) {
|
|
328
|
+
const existing = await db
|
|
329
|
+
.select()
|
|
330
|
+
.from(reservations)
|
|
331
|
+
.where(q.eq(reservations.waitlistEntryId, record.id));
|
|
332
|
+
|
|
333
|
+
await db
|
|
334
|
+
.update(waitlistEntries)
|
|
335
|
+
.set({ promotedAt: now })
|
|
336
|
+
.where(whereRecord!(waitlistEntries));
|
|
337
|
+
|
|
338
|
+
return existing;
|
|
339
|
+
},
|
|
340
|
+
});
|
|
319
341
|
```
|
|
320
342
|
|
|
321
343
|
**Path pattern from `features/{name}/actions/`:**
|
|
322
|
-
|
|
323
|
-
-
|
|
324
|
-
-
|
|
344
|
+
|
|
345
|
+
- Own feature helper: `../.quickback/define-action`
|
|
346
|
+
- Other feature helper: `../../{other-feature}/.quickback/define-action`
|
|
347
|
+
- Other generated table module: `../../{other-feature}/{table-file-name}`
|
|
348
|
+
- Generated project query helper: `../../../lib/q`
|
|
349
|
+
- Other generated lib files: `../../../lib/{module}` (for example,
|
|
350
|
+
`../../../lib/realtime` or `../../../lib/webhooks`)
|
|
351
|
+
|
|
352
|
+
Keep `defineAction` from the action's own feature: that helper binds `record`,
|
|
353
|
+
`whereRecord`, and `whereTransition`. Import only the external table from a
|
|
354
|
+
sibling feature. The waitlist/reservations names above are just the common
|
|
355
|
+
pattern; the rule applies to every cross-feature action.
|
|
325
356
|
|
|
326
357
|
### Executor Parameters
|
|
327
358
|
|
|
@@ -448,9 +479,14 @@ with the transition's "from" precondition for transition actions.
|
|
|
448
479
|
|
|
449
480
|
#### Reaching Better Auth tables (`authDb`)
|
|
450
481
|
|
|
451
|
-
The scoped `db`
|
|
452
|
-
|
|
453
|
-
|
|
482
|
+
The scoped `db` is the **features** database. Better Auth tables never appear
|
|
483
|
+
on it — that is by design. `AUTH_DB` is a separate Drizzle client.
|
|
484
|
+
|
|
485
|
+
**Caller identity — use `ctx`, do not query `AUTH_DB`.** `ctx.userId`,
|
|
486
|
+
`ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request.
|
|
487
|
+
|
|
488
|
+
To check that a *submitted* user id is an org member (assignee-style
|
|
489
|
+
features), use `c.get("authDb")` plus the generated `getOrgMemberRole` helper:
|
|
454
490
|
|
|
455
491
|
```typescript
|
|
456
492
|
// features/projects/actions/assign.ts — validate a userId is an org member
|
|
@@ -481,6 +517,17 @@ export default defineAction({
|
|
|
481
517
|
```
|
|
482
518
|
|
|
483
519
|
`c.get("authDb")` is the Drizzle connection to the auth database (in dual-DB
|
|
484
|
-
mode it's a separate D1 from your features).
|
|
485
|
-
|
|
486
|
-
|
|
520
|
+
mode it's a separate D1 from your features). That is the native membership
|
|
521
|
+
check.
|
|
522
|
+
|
|
523
|
+
For a richer query, use the same `authDb` and import tables from
|
|
524
|
+
`../../../auth/schema` — from an **`actions/` file**. On D1 the tables are
|
|
525
|
+
`user`, `organization`, and `member` — not `organization_membership`. (Neon
|
|
526
|
+
exports the Better Auth CLI's plural names: `users`, `organizations`,
|
|
527
|
+
`members`.)
|
|
528
|
+
|
|
529
|
+
| Surface | AUTH_DB handle | Notes |
|
|
530
|
+
|---|---|---|
|
|
531
|
+
| Action `execute` | `c.get("authDb")` | Import schema from `../../../auth/schema` |
|
|
532
|
+
| [Account hooks](/ui/account/hooks) | `{ authDb, authSchema }` injected | Use the injected namespace — do not invent a path to `auth/schema` |
|
|
533
|
+
| Trigger `handler:` | **none** | Args are `{ ctx, db, env }` — `db` is features only. There is no `c`. Prefer `ctx` for the acting user. Do not import `../../auth/schema` from the table file to reach AUTH_DB; that path used to compile and then fail package-mode wrangler. Check another user's membership in an action. |
|
|
@@ -553,7 +553,7 @@ Actions that keep their existing `import { defineAction } from '../.quickback/de
|
|
|
553
553
|
|
|
554
554
|
#### Compile-time advisory
|
|
555
555
|
|
|
556
|
-
When `quickback
|
|
556
|
+
When `quickback build` sees a namespace-scoped action still importing the generic helper, it emits a one-line advisory pointing at the narrowed path:
|
|
557
557
|
|
|
558
558
|
```text
|
|
559
559
|
[quickback:typing] action "feedMoments" in feature "feeds" lives under
|
|
@@ -58,6 +58,7 @@ compile.
|
|
|
58
58
|
| `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel. Dead config, deny-safe. |
|
|
59
59
|
| `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. (A reachability proxy — heuristic by design.) |
|
|
60
60
|
| `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The site resolution is conservative, so this stays advisory. |
|
|
61
|
+
| `AUTHZ_RECORD_PREDICATE_NOT_ON_LIST` | warn | A **constant** `read.access.record` predicate (`status: { equals: "published" }`, `id: { equals: "never" }`). `access.record` runs against a loaded row on `GET /:id` only — `GET /`, `POST /batch`, and the MCP list tool stop at the role gate, so the rows still list. Omit `read` to hide a resource; use the firewall to filter. `$ctx`-relative predicates are the per-record shape and stay silent. |
|
|
61
62
|
| `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth. Advisory, never fails a build. |
|
|
62
63
|
|
|
63
64
|
A few codes are reserved in the diagnostic enum for the milestones that emit
|
|
@@ -26,7 +26,7 @@ That one modifier changes what a database breach means: a leaked D1 backup, expo
|
|
|
26
26
|
- **`org_data_keys`** — one row per organization holding a random 256-bit data key (DEK), stored **wrapped** under the `ENCRYPTION_KEK` worker secret. Created lazily on the org's first encrypted write.
|
|
27
27
|
- **Write path** — every write (CRUD routes, batch routes, and `db.insert`/`db.update` inside your actions) flows through the same chokepoint, which AES-256-GCM-encrypts the column before anything else sees it. Audit snapshots, webhook payloads, and realtime deltas therefore carry ciphertext by construction.
|
|
28
28
|
- **Read path** — generated routes decrypt behind the firewall and then apply masking, so authorized callers see plaintext and everyone else sees the redaction — never ciphertext.
|
|
29
|
-
- **`ctx.crypto`** — explicit `await ctx.crypto.decrypt(value)` / `ctx.crypto.encrypt(value)` for action code that processes the field server-side (building a manifest, sending an email). Scoped to the caller's active organization.
|
|
29
|
+
- **`ctx.crypto`** — explicit `await ctx.crypto.decrypt(value)` / `ctx.crypto.encrypt(value)` for action code that processes the field server-side (building a manifest, sending an email). Scoped to the caller's active organization. `ctx.crypto` is only hydrated for authenticated requests — inside schedules, queue consumers, email handlers, and `PUBLIC` actions it is undefined. There, import the primitives directly: `import { encryptValue, decryptValue } from '../lib/encryption'` and call `decryptValue(env, db, organizationId, stored)`. Writes through the `withInternalContext` handle still encrypt automatically.
|
|
30
30
|
- **Boot guard** — a project with encrypted columns refuses to serve without `ENCRYPTION_KEK` (503 `MISSING_ENV`), instead of silently storing plaintext.
|
|
31
31
|
|
|
32
32
|
Values at rest look like `qbenc:1:<keyVersion>:<iv>:<ciphertext>` — the prefix makes accidental plaintext detectable, and the embedded key version supports rotation with lazy re-encryption on write.
|
|
@@ -96,7 +96,7 @@ export default feature("episodes", {
|
|
|
96
96
|
guards: { updatable: ["title"], protected: { isPublished: ["publish"] } },
|
|
97
97
|
masking: { submitterEmail: { type: "email", show: { roles: ["admin"] } } },
|
|
98
98
|
transitions: { publish: { field: "isPublished", from: false, to: true, access: { roles: ["admin+"] } } },
|
|
99
|
-
realtime: { enabled: true, onInsert: true, onUpdate: true },
|
|
99
|
+
realtime: { enabled: true, onInsert: true, onUpdate: true, access: { roles: ["member+"] } }, // access is mandatory — the audience of the broadcast
|
|
100
100
|
embeddings: { fields: ["title", "summary"] },
|
|
101
101
|
});
|
|
102
102
|
```
|
|
@@ -104,7 +104,7 @@ export default feature("episodes", {
|
|
|
104
104
|
| Key | Gives you | Reference |
|
|
105
105
|
|---|---|---|
|
|
106
106
|
| `read.views` | Named column projections, each with its own route and access rule | [Views](/define/views) |
|
|
107
|
-
| `transitions` | Guarded state changes generated as real `POST /:id/{name}` actions — guards, stamps, `undo`, cascades | [Transitions](/define/transitions) |
|
|
107
|
+
| `transitions` | Guarded state changes generated as real `POST /:id/{name}` actions — guards, stamps, `undo`, cascades. **Fixed target only**: each entry needs a literal `to` (with `from` or `fromTo`). A variable target read from input (`via: "nextStatus"`) is a hand-written `actions/<name>.ts` with `transition: { via }` — the compiler errors otherwise. | [Transitions](/define/transitions) |
|
|
108
108
|
| `triggers` | `before`/`after` hooks on write, lowered to a real SQL trigger or an application handler | [Triggers](/define/triggers) |
|
|
109
109
|
| `realtime` | Per-table broadcasts on insert/update/delete, audience-scoped | [Realtime](/platform/realtime/using-realtime) |
|
|
110
110
|
| `owns` | The composition boundary that turns on atomic parent-plus-children writes | [Changesets](/define/changesets) |
|
|
@@ -124,7 +124,7 @@ one" routing table at the top of [Actions](/define/actions).
|
|
|
124
124
|
That means:
|
|
125
125
|
|
|
126
126
|
- **Both forms remain supported indefinitely.** Mix them freely — some files `feature(...)`, some files `q.table() + defineTable()`, some files Drizzle `sqliteTable() + defineTable()`. The compiler dispatches per file.
|
|
127
|
-
- **Action files get
|
|
127
|
+
- **Action files get their bound context from the generated helper.** Each action lives in its own file under `actions/` and imports `defineAction` plus tables owned by that feature from `../.quickback/define-action`. The helper re-exports every table **in that feature** typed with the generated schema, so `record` and the audit columns are visible without casts. It does not export tables from a sibling feature: import those separately from that feature's generated helper or table module, while keeping `defineAction` local. Query operators come from project `lib/q`.
|
|
128
128
|
- **Diagnostics are identical.** Missing firewall → same warning. Protected-field wiring → same check. Nothing about `feature()` weakens the secure-by-default posture.
|
|
129
129
|
|
|
130
130
|
## Aliases
|
|
@@ -187,10 +187,13 @@ For everything action-related — record vs standalone, conflict rules, the gene
|
|
|
187
187
|
## Composition vs reference — `owns`
|
|
188
188
|
|
|
189
189
|
A schema-level FK (`references:` / `.references()`) says "this row points at
|
|
190
|
-
that row." It does **not** say who owns whom.
|
|
190
|
+
that row." It does **not** say who owns whom. `.references()` may only target
|
|
191
|
+
another **feature table in the same database** — never Better Auth `users` /
|
|
192
|
+
`user` / `organization` / `member` (those live in `AUTH_DB`). When a set of child rows has no
|
|
191
193
|
lifecycle of its own — junction memberships, normalized phones/emails, line
|
|
192
194
|
items — declare the composition with `owns` on the root table:
|
|
193
195
|
|
|
196
|
+
{/* doc-compile: skip — excerpt: the owned `tasks` / `projectMembers` tables and the `people` ref target live in sibling files the fence cannot carry; the compiler rejects `owns` that names an undefined table. */}
|
|
194
197
|
```ts
|
|
195
198
|
export default feature("projects", {
|
|
196
199
|
columns: {
|
|
@@ -204,6 +207,9 @@ export default feature("projects", {
|
|
|
204
207
|
tasks: { table: "tasks", fk: "projectId", inherit: ["organizationId"] },
|
|
205
208
|
members: { table: "projectMembers", fk: "projectId", refs: { personId: "people" }, inherit: ["organizationId"] },
|
|
206
209
|
},
|
|
210
|
+
// `owns` only matters on a write path — declare the changeset ops it rides
|
|
211
|
+
create: { access: { roles: ["member+"] } },
|
|
212
|
+
update: { access: { roles: ["member+"] } },
|
|
207
213
|
});
|
|
208
214
|
```
|
|
209
215
|
|
|
@@ -220,13 +226,16 @@ mounting its raw route.
|
|
|
220
226
|
|
|
221
227
|
Action bodies need to run queries against the database. Quickback's compiled projects expose the Drizzle query-builder helpers on the same `q` namespace you use for schema authoring, so `execute` stays inside one DSL:
|
|
222
228
|
|
|
229
|
+
{/* doc-compile: skip — excerpt: the `mail` feature's `mailboxes` / `messages` / `threads` tables live in sibling files the fence cannot carry, and the generated `define-action` helper only re-exports tables that exist in the feature. */}
|
|
223
230
|
```ts title="quickback/features/mail/actions/inbound.ts"
|
|
224
231
|
import { z } from "zod";
|
|
225
|
-
import {
|
|
232
|
+
import {
|
|
233
|
+
defineAction,
|
|
234
|
+
mailboxes,
|
|
235
|
+
messages,
|
|
236
|
+
threads,
|
|
237
|
+
} from "../.quickback/define-action";
|
|
226
238
|
import { q } from "../../../lib/q";
|
|
227
|
-
import { mailboxes } from "../mailboxes";
|
|
228
|
-
import { messages } from "../messages";
|
|
229
|
-
import { threads } from "../threads";
|
|
230
239
|
|
|
231
240
|
export default defineAction({
|
|
232
241
|
description: "Ingest an inbound email into the right thread.",
|
|
@@ -90,6 +90,8 @@ An explicit predicate on a custom-named column is honoured **on that table** via
|
|
|
90
90
|
|
|
91
91
|
If `userId` is genuinely informational, rename it to something that says so (`linkedUserId`, `assigneeId`, `inviteeId`) and the warning goes away.
|
|
92
92
|
|
|
93
|
+
Do **not** turn that column into a SQL FK to Better Auth. `.references(() => users.id)` (or `user`) is illegal across split D1s (`AUTH_DB` vs `DB`) and deploy fails with `Generate features database migrations`. Store it as `q.text().required()`. See [Schema → References](/define/schema).
|
|
94
|
+
|
|
93
95
|
## Predicate Shape
|
|
94
96
|
|
|
95
97
|
```typescript
|
|
@@ -55,7 +55,8 @@ guards: {
|
|
|
55
55
|
// Fields only modifiable via specific actions
|
|
56
56
|
protected?: Record<string, string[]>;
|
|
57
57
|
|
|
58
|
-
// Fields set on CREATE,
|
|
58
|
+
// Fields set on CREATE, blocked on every generic update.
|
|
59
|
+
// Actions can still write them — see the note below.
|
|
59
60
|
immutable?: string[];
|
|
60
61
|
}
|
|
61
62
|
```
|
|
@@ -66,8 +67,18 @@ guards: {
|
|
|
66
67
|
|------|------------------|
|
|
67
68
|
| `createable` | Fields allowed in create (POST) request body |
|
|
68
69
|
| `updatable` | Fields allowed in update (PATCH) request body |
|
|
69
|
-
| `protected` | Fields blocked from direct writes,
|
|
70
|
-
| `immutable` | Fields allowed on create, blocked on all updates |
|
|
70
|
+
| `protected` | Fields blocked from direct writes; the named actions are documentation, not enforcement (see below) |
|
|
71
|
+
| `immutable` | Fields allowed on create, blocked on all generic updates (actions can still write them) |
|
|
72
|
+
|
|
73
|
+
> **Guards bind the generic CRUD surface, not actions.** `createable`,
|
|
74
|
+
> `updatable`, `immutable`, and `protected` are enforced by the generated
|
|
75
|
+
> `validateCreate` / `validateUpdate`, which only the CRUD, batch, and changeset
|
|
76
|
+
> routes call. An action handler writes through a scoped `db` with no field-level
|
|
77
|
+
> checks, so it can write any column — including an `immutable` one, and including
|
|
78
|
+
> a `protected` one not listed in that field's action names. Treat the names in
|
|
79
|
+
> `protected` as intent you are documenting, and keep the enforcement in the
|
|
80
|
+
> action's own access rules.
|
|
81
|
+
|
|
71
82
|
|
|
72
83
|
**Combining lists:**
|
|
73
84
|
|
|
@@ -76,6 +87,15 @@ guards: {
|
|
|
76
87
|
- `protected` - Don't also list in `createable` or `updatable` (they're mutually exclusive)
|
|
77
88
|
- `immutable` - Don't also list in `updatable` (contradiction)
|
|
78
89
|
|
|
90
|
+
> **Workflow-owned fields have one writer.** If a status or state column is
|
|
91
|
+
> managed by transitions or named actions, put it only in `protected`, mapped to
|
|
92
|
+
> those transition/action names. Never also put it in `createable` or
|
|
93
|
+
> `updatable`: the compiler rejects either contradiction, and a direct POST or
|
|
94
|
+
> PATCH path would bypass the workflow. Give the column its initial value with a
|
|
95
|
+
> schema default. Records then begin in that state, and only the declared
|
|
96
|
+
> transitions/actions may write the field.
|
|
97
|
+
|
|
98
|
+
|
|
79
99
|
```typescript
|
|
80
100
|
guards: {
|
|
81
101
|
createable: ["candidateId", "jobId", "notes", "source"],
|
|
@@ -269,3 +289,7 @@ The Quickback compiler validates your guards configuration and will error if:
|
|
|
269
289
|
3. **Field in both `updatable` and `immutable`** - Contradictory: immutable fields cannot be updated
|
|
270
290
|
4. **Field in `protected` doesn't exist in schema** - Referenced field must exist in the table
|
|
271
291
|
5. **Field in `createable`/`updatable`/`immutable` doesn't exist in schema** - All referenced fields must exist
|
|
292
|
+
|
|
293
|
+
Transition/action-managed status fields belong only in `protected`, use a
|
|
294
|
+
schema default for their initial value, and may be written only by the named
|
|
295
|
+
transitions/actions.
|
|
@@ -17,7 +17,7 @@ Quickback is a **backend compiler**. You write definition files, and Quickback c
|
|
|
17
17
|
- **Don't** create a `workspaces` / `teams` / `tenants` table.
|
|
18
18
|
- **Don't** create a membership or `*_members` table.
|
|
19
19
|
- **Do** put `organizationId: q.scope("organization")` on every tenant-scoped table — the firewall is auto-derived from it.
|
|
20
|
-
- Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`.
|
|
20
|
+
- Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`. Do not query AUTH_DB for the **acting** user. To check that a *submitted* user id belongs to the org, query AUTH_DB from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
21
21
|
- Create a tenant with `POST /auth/v1/organization/create` and switch with `POST /auth/v1/organization/set-active` — not a custom action.
|
|
22
22
|
|
|
23
23
|
If your product calls it something else, that's a **label, not a schema decision** — the Account UI renames the organization surfaces for you (see [Account → Customization](/ui/account/customization)).
|
|
@@ -10,6 +10,8 @@ isn't in your org.
|
|
|
10
10
|
> A relationship's `from:` must be one of *your* feature tables — the compiler rejects one
|
|
11
11
|
> pointing at Better Auth's `organization_memberships`, `organizations`, or `user`. Org
|
|
12
12
|
> membership is already decided before your handler runs and is available as `ctx.roles`.
|
|
13
|
+
> To validate a *submitted* user id (an assignee), query AUTH_DB from an action —
|
|
14
|
+
> see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
13
15
|
>
|
|
14
16
|
> A relationship's `where:` also takes **scalar equality only** (`string | number |
|
|
15
17
|
> boolean`). `where: { role: ['admin','owner'] }` is not valid — declare one relationship
|
|
@@ -53,6 +55,11 @@ export default defineConfig({
|
|
|
53
55
|
});
|
|
54
56
|
```
|
|
55
57
|
|
|
58
|
+
> **userId is not a SQL FK to Better Auth**
|
|
59
|
+
>
|
|
60
|
+
> `subject: { column: 'userId', equals: 'ctx.userId' }` matches a **plain text** column on your join table. Do not write `.references(() => users.id)` (or `user`, `organization`, `member`) on that column. Better Auth tables live in `AUTH_DB`; feature tables live in `DB`. SQLite cannot FK across those databases, and drizzle-kit fails generating features migrations with `Critical command failed: Generate features database migrations`. Store it as `userId: q.text().required()`. See [Schema → References](/define/schema).
|
|
61
|
+
|
|
62
|
+
|
|
56
63
|
> **The `from:` table needs its own defineTable**
|
|
57
64
|
>
|
|
58
65
|
> A relationship resolves through the `from:` table's **generated resource module**
|