@quickback-dev/cli 0.59.0 → 0.59.1

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 (97) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +14 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/schema.d.ts +10 -0
  5. package/dist/commands/schema.d.ts.map +1 -1
  6. package/dist/commands/schema.js +48 -16
  7. package/dist/commands/schema.js.map +1 -1
  8. package/dist/commands/schema.test.js +81 -1
  9. package/dist/commands/schema.test.js.map +1 -1
  10. package/dist/docs/content.d.ts.map +1 -1
  11. package/dist/docs/content.js +41 -21
  12. package/dist/docs/content.js.map +1 -1
  13. package/dist/index.js +1 -1
  14. package/dist/lib/file-loader.d.ts +10 -0
  15. package/dist/lib/file-loader.d.ts.map +1 -1
  16. package/dist/lib/file-loader.js +41 -22
  17. package/dist/lib/file-loader.js.map +1 -1
  18. package/dist/lib/file-loader.test.js +20 -1
  19. package/dist/lib/file-loader.test.js.map +1 -1
  20. package/dist/lib/prepare-output.d.ts +2 -0
  21. package/dist/lib/prepare-output.d.ts.map +1 -1
  22. package/dist/lib/prepare-output.js +2 -2
  23. package/dist/lib/prepare-output.js.map +1 -1
  24. package/dist/lib/prepare-state-output.d.ts +33 -4
  25. package/dist/lib/prepare-state-output.d.ts.map +1 -1
  26. package/dist/lib/prepare-state-output.js +71 -12
  27. package/dist/lib/prepare-state-output.js.map +1 -1
  28. package/dist/lib/prepare-state-output.test.js +91 -11
  29. package/dist/lib/prepare-state-output.test.js.map +1 -1
  30. package/dist/lib/schema-sync/index.d.ts.map +1 -1
  31. package/dist/lib/schema-sync/index.js +39 -4
  32. package/dist/lib/schema-sync/index.js.map +1 -1
  33. package/dist/lib/schema-sync/index.test.js +89 -1
  34. package/dist/lib/schema-sync/index.test.js.map +1 -1
  35. package/dist/schema-engine/index.d.ts +1 -0
  36. package/dist/schema-engine/index.d.ts.map +1 -1
  37. package/dist/schema-engine/index.js +50 -0
  38. package/dist/schema-engine/index.js.map +3 -3
  39. package/dist/schema-engine/provider-dialects.d.ts +22 -0
  40. package/dist/schema-engine/provider-dialects.d.ts.map +1 -0
  41. package/dist/schema-engine/source-sync.d.ts +8 -0
  42. package/dist/schema-engine/source-sync.d.ts.map +1 -1
  43. package/dist/skill/SKILL.md +45 -0
  44. package/dist/skill/agents/quickback-specialist/AGENT.md +18 -1
  45. package/dist/skill/docs/changelog/index.md +28 -2
  46. package/dist/skill/docs/changelog/v0.1x.md +2 -2
  47. package/dist/skill/docs/configure/agents.md +19 -0
  48. package/dist/skill/docs/configure/index.md +1 -1
  49. package/dist/skill/docs/define/access.md +23 -820
  50. package/dist/skill/docs/define/actions/access.md +4 -4
  51. package/dist/skill/docs/define/areas.md +307 -4
  52. package/dist/skill/docs/define/authz-roles.md +164 -0
  53. package/dist/skill/docs/define/changesets.md +1 -1
  54. package/dist/skill/docs/define/fga.md +1 -1
  55. package/dist/skill/docs/define/firewall.md +3 -3
  56. package/dist/skill/docs/define/index.md +32 -3
  57. package/dist/skill/docs/define/masking.md +1 -1
  58. package/dist/skill/docs/define/permissions.md +1 -1
  59. package/dist/skill/docs/define/read.md +103 -1
  60. package/dist/skill/docs/define/relationships.md +313 -0
  61. package/dist/skill/docs/define/scopes.md +1 -1
  62. package/dist/skill/docs/platform/realtime/using-realtime.md +1 -1
  63. package/dist/skill/docs/platform/storage/r2.md +39 -0
  64. package/dist/skill/docs/platform/webhooks/inbound.md +17 -6
  65. package/dist/skill/docs/start/deploy-browser.md +118 -0
  66. package/dist/skill/docs/start/deploy-owner-access.md +62 -0
  67. package/dist/skill/docs/start/deploy.md +2 -0
  68. package/dist/skill/docs/tooling/cli.md +22 -0
  69. package/dist/skill/docs/tooling/output.md +64 -0
  70. package/package.json +1 -1
  71. package/src/skill/SKILL.md +45 -0
  72. package/src/skill/agents/quickback-specialist/AGENT.md +18 -1
  73. package/src/skill/docs/changelog/index.md +28 -2
  74. package/src/skill/docs/changelog/v0.1x.md +2 -2
  75. package/src/skill/docs/configure/agents.md +19 -0
  76. package/src/skill/docs/configure/index.md +1 -1
  77. package/src/skill/docs/define/access.md +23 -820
  78. package/src/skill/docs/define/actions/access.md +4 -4
  79. package/src/skill/docs/define/areas.md +307 -4
  80. package/src/skill/docs/define/authz-roles.md +164 -0
  81. package/src/skill/docs/define/changesets.md +1 -1
  82. package/src/skill/docs/define/fga.md +1 -1
  83. package/src/skill/docs/define/firewall.md +3 -3
  84. package/src/skill/docs/define/index.md +32 -3
  85. package/src/skill/docs/define/masking.md +1 -1
  86. package/src/skill/docs/define/permissions.md +1 -1
  87. package/src/skill/docs/define/read.md +103 -1
  88. package/src/skill/docs/define/relationships.md +313 -0
  89. package/src/skill/docs/define/scopes.md +1 -1
  90. package/src/skill/docs/platform/realtime/using-realtime.md +1 -1
  91. package/src/skill/docs/platform/storage/r2.md +39 -0
  92. package/src/skill/docs/platform/webhooks/inbound.md +17 -6
  93. package/src/skill/docs/start/deploy-browser.md +118 -0
  94. package/src/skill/docs/start/deploy-owner-access.md +62 -0
  95. package/src/skill/docs/start/deploy.md +2 -0
  96. package/src/skill/docs/tooling/cli.md +22 -0
  97. package/src/skill/docs/tooling/output.md +64 -0
@@ -0,0 +1,118 @@
1
+ # Deploy from your browser
2
+
3
+ Build a backend in [Quickback Start](https://start.quickback.dev), get a green compile, and ship it to **your own Cloudflare account** with one click — databases created, migrations applied, secrets minted, Worker live on a `workers.dev` URL. No local tooling required.
4
+
5
+ This page covers the browser flow. For local projects, or anything the browser flow doesn't support yet, use [`quickback deploy`](/start/deploy) — the CLI covers every resource type and is always available.
6
+
7
+ > Browser deployment is rolling out. The hosted deploy service ships fail-closed behind a kill switch while the final authentication work lands; if the Deploy card doesn't appear in Start, your session isn't in the rollout yet. `quickback deploy` works for everyone today.
8
+
9
+
10
+ ## Browser vs CLI
11
+
12
+ | | Deploy from Start | `quickback deploy` |
13
+ |---|---|---|
14
+ | Where you work | start.quickback.dev chat | Your terminal, local project |
15
+ | Cloudflare auth | OAuth consent (no tokens handled by you) | `wrangler login` / `CLOUDFLARE_API_TOKEN` |
16
+ | Resource coverage | The supported matrix below, fail-closed | Everything the compiler emits |
17
+ | Custom domains | Not yet — `workers.dev` only | Yes, via your `wrangler.toml` routes |
18
+ | Best for | Chat-built apps, first deploys, demos | Local development, full-featured apps, CI |
19
+
20
+ ## How a deploy runs
21
+
22
+ When you click **Deploy this app**, the pipeline runs four phases and reports each one:
23
+
24
+ 1. **Compile** — your project compiles on the hosted compiler and emits a *deployment manifest*: the exact set of resources, migrations, and secrets the deploy will touch. Anything the browser flow can't deploy fails **here**, with a named reason — never as a half-deployed app.
25
+ 2. **Provision** — each D1 database, KV namespace, and R2 bucket is created in your account, or **adopted** if a resource with the same name already exists. Retries and redeploys never create duplicates. Nothing is ever deleted automatically.
26
+ 3. **Package** — the project recompiles with the real resource ids folded in and is bundled into Worker modules (plus your CMS/Account SPA assets, when enabled). Every byte is hash-verified against the manifest before anything is uploaded.
27
+ 4. **Finalize** — migrations apply, the Worker uploads with its bindings, secrets are set, and the `workers.dev` route is enabled. Start probes the URL and only shows **Live** once it actually answers.
28
+
29
+ A typical deploy takes one to two minutes, most of it compilation.
30
+
31
+ ## What deploys
32
+
33
+ Supported today, end to end:
34
+
35
+ | Resource | Notes |
36
+ |---|---|
37
+ | D1 databases | All of a project's databases — auth, features, and (when your features pull them in) audit, webhooks, and file-metadata |
38
+ | KV namespace | The `KV` binding for rate limiting and session overflow |
39
+ | R2 bucket | Managed file storage (`managed: true`) |
40
+ | Realtime | The inline Broadcaster Durable Object, including its class registration |
41
+ | Email binding | The Cloudflare Email Service binding is attached (see the delivery caveat below) |
42
+ | CMS / Account UI | The bundled SPAs upload as static assets on the same Worker, with your app's real URL baked in |
43
+
44
+ Blocked, fail-closed at the compile phase — the deploy stops with the reason, and `quickback deploy` remains the path for these:
45
+
46
+ | Blocked | Why |
47
+ |---|---|
48
+ | Webhooks, embeddings | Need queue and Workers AI bindings the broker can't create yet |
49
+ | Vectorize | Not yet supported |
50
+ | Neon / Postgres | Browser deploys are D1-only; Neon projects deploy via the CLI |
51
+ | Separate-worker realtime | Needs a second Worker + service binding |
52
+ | Custom `apps:` mounts | Typically need custom domains |
53
+ | Custom `bindings:` (Durable Objects, queues, services, extra R2 buckets) | Not represented by the deploy contract yet |
54
+ | Secrets you supply (third-party API keys, etc.) | The browser flow has no way to collect them yet — a project that *requires* one is refused rather than deployed broken |
55
+ | Hyperdrive, public R2 buckets, containers, workflows | Out of MVP scope |
56
+
57
+ > **Email delivery**: the email *binding* is attached so your app boots and auth works, but actually sending mail requires Email Sending to be configured on your Cloudflare account with a verified sending domain — which a fresh `workers.dev` app doesn't have. Start's builder defaults new apps to email + password **without** email verification for exactly this reason; enable verification, OTP, or magic links after you've configured a sending domain.
58
+
59
+
60
+ ## Connecting your Cloudflare account
61
+
62
+ The first deploy starts with **Continue with Cloudflare** — a standard OAuth consent against Cloudflare's own dashboard, shown by the **Quickback** OAuth client. You pick the account, see exactly which permissions are requested, and can revoke at any time from Cloudflare under **My Profile → Access Management → Connected Applications** (or disconnect from Start).
63
+
64
+ What's requested, and why:
65
+
66
+ | Scope | Used for |
67
+ |---|---|
68
+ | `openid`, `user-details.read` | Identifying the connection (your email is stored masked, e.g. `p***@example.com`) |
69
+ | `memberships.read` | The account picker — so you never copy a 32-character account id |
70
+ | `account-settings.read` | Looking up your `workers.dev` subdomain to build your app's URL |
71
+ | `workers-scripts.write` | Uploading the Worker, enabling its route, setting its secrets |
72
+ | `d1.write` | Creating databases and applying migrations |
73
+ | `workers-kv-storage.write` | Creating the KV namespace |
74
+ | `workers-r2.write` | Creating file-storage buckets |
75
+
76
+ Nothing broader is requested — no zone, DNS, billing, or account-management access.
77
+
78
+ ## Where your token lives
79
+
80
+ The OAuth token never reaches your browser, the chat model, or the compiler. It is held by the deploy service and:
81
+
82
+ - encrypted at rest with AES-256-GCM under a versioned key-encryption key;
83
+ - bound to its connection record (the ciphertext is unusable if copied elsewhere);
84
+ - decrypted only inside the API calls of an active deploy, then discarded.
85
+
86
+ Tokens expire; when one does, Start shows a reconnect prompt and a fresh consent re-issues it onto the same connection. Revoking in Cloudflare kills the token immediately — the stored ciphertext becomes useless.
87
+
88
+ ## Secrets on the deployed app
89
+
90
+ - `BETTER_AUTH_SECRET` is minted by the deploy service — 256 bits of fresh entropy per app — and set on the Worker directly. It's never shown to the browser or stored in your project.
91
+ - **Existing Worker secrets are always preserved.** Cloudflare's upload API replaces a Worker's bindings wholesale; the deploy explicitly carries every existing secret across, so a redeploy can never silently delete a secret you set by hand.
92
+
93
+ ## Redeploys are safe by construction
94
+
95
+ Click Deploy as often as you like:
96
+
97
+ - **Provisioning adopts** — existing resources are matched by name and reused, never duplicated, never deleted.
98
+ - **Migrations apply exactly once** — a ledger in each database records every applied migration with a content hash. Already-applied migrations are skipped (even when a recompile renames the file), and a migration whose *content changed after it ran* refuses the deploy outright instead of corrupting the schema.
99
+ - **Assets are content-addressed** — a redeploy with unchanged CMS/Account assets uploads zero bytes.
100
+ - **Realtime classes register once** — Durable Object registrations follow Cloudflare's append-only chronology; a redeploy sends nothing new.
101
+
102
+ ## After it's live
103
+
104
+ Your app answers at `https://<app-name>.<your-subdomain>.workers.dev`:
105
+
106
+ - **API-only apps** serve a small landing page at `/` (browsers) and a JSON service descriptor (everything else), linking `/api/v1`, `/openapi.json`, and `/health` — never a bare 404 on first visit.
107
+ - **Apps with the Account UI or CMS** redirect `/` to the login page or CMS.
108
+ - `/health` reports status and whether email is configured.
109
+
110
+ The deployed app is a normal Worker in *your* account: logs, metrics, and settings live in your Cloudflare dashboard, and you can take over management with the CLI at any time — download the project from Start and `quickback deploy` picks up the same resources by name.
111
+
112
+ ## Not yet available
113
+
114
+ - **Owner login in deployed apps** ("Continue with Cloudflare" as the app's admin sign-in) — the UI half ships with the Account SPA, but the server half and its per-app OAuth client are still in progress.
115
+ - **Custom domains** for browser-deployed apps — `workers.dev` only for now.
116
+ - The blocked resources listed above.
117
+
118
+ These all work — or will work first — through [`quickback deploy`](/start/deploy).
@@ -0,0 +1,62 @@
1
+ # Owner access after a browser deploy
2
+
3
+ When you deploy from Quickback Start's **Deploy to Cloudflare** card, the very
4
+ first deploy seeds your app's first administrator (an `appmanager` user) and
5
+ shows a **one-time claim link** next to the live URL:
6
+
7
+ ```
8
+ https://<your-app>.<subdomain>.workers.dev/__quickback/claim#token=…
9
+ ```
10
+
11
+ Opening it lets you set your email and a password, and you're the app's admin.
12
+ That's the whole setup.
13
+
14
+ ## What the claim link is
15
+
16
+ - **One-time and short-lived.** The link works once and expires about six
17
+ hours after the deploy. It's shown exactly once, in the deploy card —
18
+ Quickback keeps no copy of it.
19
+ - **Owner-only.** The link can only claim the admin account the deploy
20
+ seeded. It can never create a new account or elevate an existing one.
21
+ - **Fragment-carried.** The token rides the URL fragment (`#token=…`), which
22
+ browsers never send to servers — it stays out of request logs entirely.
23
+ - **Closed once it's used.** The claim page checks the link before it renders
24
+ anything: a spent, expired, or unrecognised token gets a "this app has
25
+ already been claimed" message instead of a form. Visiting
26
+ `/__quickback/claim` without a valid token never shows a working signup.
27
+
28
+ The record of a used link lives in your app's own database, so single-use is
29
+ enforced exactly — there's no window in which a spent link claims again.
30
+
31
+ ## What happens when you claim
32
+
33
+ 1. You open the link and choose your **email** and a **password** (the seeded
34
+ placeholder email is synthetic — deployed apps can't send mail, so your
35
+ chosen address is marked verified directly).
36
+ 2. From that moment you sign in through **your app's own auth** — the same
37
+ email + password login every other user of your app gets. If your app has
38
+ the Account UI enabled, you land on `/account`; API-only apps sign in via
39
+ `POST /auth/v1/sign-in/email`.
40
+
41
+ **Quickback is not your app's identity provider.** The claim link is a
42
+ bootstrap window, not a login method: once claimed (or expired), your app has
43
+ no runtime dependency on Quickback or the deploy broker for authentication.
44
+
45
+ ## Lost access? Re-issue from Start
46
+
47
+ Deployed apps on `workers.dev` can't send password-reset email, so your
48
+ Cloudflare account is the recovery root: in the deploy card, **Re-issue admin
49
+ claim link** mints a fresh link — authorized by the same Cloudflare connection
50
+ that deployed the app. Re-claiming resets the admin password.
51
+
52
+ Every issue **rotates the signing key**, so any older link immediately stops
53
+ working, claimed or not. A fresh link re-opens the claim page on its own —
54
+ nothing has to be reset first, because "claimable" just means a signed,
55
+ unexpired, unused token exists.
56
+
57
+ ## For CLI deploys
58
+
59
+ The claim route only activates when the `QUICKBACK_CLAIM_KEY` Worker secret is
60
+ set — the browser-deploy broker mints it automatically. Apps deployed with
61
+ `quickback deploy` don't get a claim link (the route answers 404); create your
62
+ admin through your own flow, or deploy once through Start to bootstrap.
@@ -1,5 +1,7 @@
1
1
  # Deploying
2
2
 
3
+ Building in [Quickback Start](https://start.quickback.dev) instead of locally? You can also [deploy straight from the browser](/start/deploy-browser) — no CLI needed.
4
+
3
5
  A freshly compiled project's `wrangler.toml` contains **placeholder resource ids** — the compiler can't know your D1 database ids or KV namespace id until those resources exist in your Cloudflare account. Historically that meant a manual dance: `wrangler d1 create`, copy the id, paste it into `quickback.config.ts`, repeat for every database, recompile, deploy.
4
6
 
5
7
  `quickback deploy` does the whole dance for you:
@@ -130,6 +130,28 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
130
130
  resolves against. Re-run `quickback compile` after schema changes so the
131
131
  helpers track your tables.
132
132
 
133
+ ### Synchronize Managed Columns
134
+
135
+ ```bash
136
+ quickback schema check # report missing managed-column declarations; read-only
137
+ quickback schema sync # write the safe additive declarations into authored files
138
+ quickback schema sync --dry-run # show the sync diff without writing
139
+ ```
140
+
141
+ Checks every authored table under `quickback/features/` for the managed
142
+ columns the compiler expects (audit timestamps, soft-delete markers) and —
143
+ on `sync` — writes the missing declarations into your source. `check` never
144
+ writes; anything that needs a human decision is reported as a diagnostic and
145
+ blocks the write.
146
+
147
+ The SQL dialect for written declarations comes from your configured database
148
+ provider — the same provider→dialect table the compiler uses. Postgres
149
+ providers (`supabase`, `neon`, `vercel-postgres`, `postgres`, `postgresql`)
150
+ get Postgres declarations; SQLite providers (`cloudflare-d1`,
151
+ `better-sqlite3`, `bun-sqlite`, `libsql`, `turso`) get SQLite. MySQL
152
+ providers are refused with an error rather than written in the wrong
153
+ dialect; no provider (or an unrecognized one) defaults to SQLite.
154
+
133
155
  ### Authored-Source Codemods
134
156
 
135
157
  ```bash
@@ -74,6 +74,49 @@ Not every per-feature file is always emitted:
74
74
  - `schema.ts`, `{feature}.ts`, and `{feature}.resource.ts` are skipped for tableless features.
75
75
  - A multi-table feature gets one alias file per table (`{feature}.ts`, `{other_table}.ts`) alongside the single `schema.ts`.
76
76
 
77
+ ## Spec Blobs Load As Text
78
+
79
+ The generated `wrangler.toml` contains a rule you did not configure:
80
+
81
+ ```toml
82
+ [[rules]]
83
+ type = "Text"
84
+ globs = ["**/openapi.json", "**/asyncapi.json", "**/schema-registry.json"]
85
+ ```
86
+
87
+ This is deliberate, and it exists to protect cold-start time.
88
+
89
+ A Worker has a limited CPU budget for its **startup window** — the module
90
+ evaluation that runs before the first request is served. A plain JSON import is
91
+ inlined by the bundler as a JavaScript object literal, so the runtime parses it
92
+ as source and builds the entire object graph during that window. For a large
93
+ API the spec is the single biggest thing in the bundle, and the cost is paid on
94
+ every cold start to serve discovery routes that most callers never request.
95
+
96
+ Loading the blobs as text means startup only allocates a string. The generated
97
+ `src/index.ts` parses each one lazily, on first request, and memoizes it:
98
+
99
+ ```ts
100
+ import openapiSpecText from '../openapi.json';
101
+
102
+ let __openapiSpec: unknown;
103
+ const openapiSpec = () => (__openapiSpec ??= JSON.parse(openapiSpecText as unknown as string));
104
+
105
+ app.get('/openapi.json', (c) => c.json(openapiSpec()));
106
+ ```
107
+
108
+ Behavior is unchanged — the same routes return the same payloads. Only *when*
109
+ the parse happens moves.
110
+
111
+ The saving scales with spec size. On a ~7 MB spec this cut measured startup CPU
112
+ by roughly 40%; below ~0.5 MB it is within measurement noise. Projects that
113
+ emit no spec are unaffected, because bundler rules only apply to files that are
114
+ actually imported.
115
+
116
+ **Warning:** Do not hand-edit this rule out. Without it the `…Text` imports
117
+ resolve to parsed objects and `JSON.parse` receives an object instead of a
118
+ string.
119
+
77
120
  ## Generated Package Dependency Security
78
121
 
79
122
  For projects using Better Auth, the generated `package.json` keeps the stable
@@ -298,6 +341,27 @@ Migration and report artifacts are written to the `quickback/` state directory:
298
341
  - `quickback/drizzle/...` for Drizzle migration SQL/meta artifacts
299
342
  - `quickback/reports/...` for security contract report artifacts
300
343
 
344
+ ### Migration history is never wiped
345
+
346
+ Unlike `src/`, the `quickback/drizzle/` tree is **not** hermetic — it is history,
347
+ and history is only ever appended to or superseded.
348
+
349
+ To keep compile payloads small, the CLI uploads every migration `.sql` and
350
+ `_journal.json` but only the **newest** `NNNN_snapshot.json` per meta directory.
351
+ The compiler's response is therefore a partial view by construction, and a file
352
+ missing from it carries no instruction. Compile removes a file only when the
353
+ compiler was actually shown it and left it out; anything never uploaded — every
354
+ historical snapshot — is preserved untouched.
355
+
356
+ When something is removed, the previous tree is archived to
357
+ `quickback/.archives/drizzle-<timestamp>/` (the three most recent are kept) and
358
+ the compile prints what it removed and what it preserved.
359
+
360
+ > If `quickback migrations doctor` reports snapshot drift — more journal entries
361
+ > than snapshot files — that drift came from your project's history, not from
362
+ > compiling. Compile does not delete snapshots it was never given.
363
+
364
+
301
365
  For non-interactive environments (cloud compile, CI), table/column renames must be declared with `compiler.migrations.renames` in `quickback.config.ts`. This avoids interactive rename prompts during migration generation.
302
366
 
303
367
  Migration files follow the Drizzle Kit naming convention:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.59.0",
3
+ "version": "0.59.1",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -102,6 +102,51 @@ meta in git.
102
102
 
103
103
  ---
104
104
 
105
+ ## Tenancy is not yours to model
106
+
107
+ **Workspace, team, tenant, account, org — they are all the Better Auth organization.**
108
+ Quickback ships multi-tenancy. Building your own is the single most expensive mistake in a
109
+ Quickback project, and the compiler will fight you the whole way.
110
+
111
+ - **Never** create a `workspaces` / `teams` / `tenants` / `accounts` table.
112
+ - **Never** create a membership or `*_members` table for it.
113
+ - **Do** put `organizationId: q.scope("organization")` on every tenant-scoped table. The
114
+ firewall is auto-derived from it, and the column is auto-populated on insert.
115
+ - Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`. Never
116
+ query for them, and never write an action that checks them by hand.
117
+ - Create a tenant with `POST /auth/v1/organization/create`; switch with
118
+ `POST /auth/v1/organization/set-active`. Both already exist — don't write an action for it.
119
+ - Invitations, roles, and member management are Better Auth's too (`/auth/v1/organization/*`),
120
+ and the Account SPA already has UI for all of it.
121
+
122
+ If the product calls it something else, that's a **label, not a schema decision** — the Account
123
+ UI renames the organization surfaces (`quickback docs ui/account/customization`).
124
+
125
+ ## The authorization ladder
126
+
127
+ Four rungs, in order. **Most apps never leave rung 1.** Climb only when the rung you are on
128
+ genuinely cannot express the rule.
129
+
130
+ | Rung | Reach for it when | Skip it when |
131
+ |---|---|---|
132
+ | **1. Org roles + firewall** | `organizationId: q.scope('organization')` plus `roles: ['member+']` / `['admin+']`. No `authz` block at all. | — this is the floor, and it covers most apps end to end |
133
+ | **2. Named rules** (`authz.roles` / `authz.rules`) | the same role expression repeats across many features | only a couple of repeats — inline them |
134
+ | **3. Relationships + areas** (`authz.relationships`, `_area.ts`) | membership lives in **your own** domain table (attendee, collaborator, external reviewer), or a subtree shares a URL prefix **and** a per-row admission gate | org membership already answers it — that's rung 1 |
135
+ | **4. FGA** (OpenFGA / Zanzibar) | you need a permission *graph*: derived, inherited, hierarchical, public share links | a single hop answers it |
136
+
137
+ Two constraints that make rung 3 the wrong tool for org membership:
138
+
139
+ - A relationship's `from:` must be one of **your feature tables**. The compiler rejects a
140
+ relationship pointing at Better Auth's `organization_memberships`, `organizations`, or
141
+ `user` — so "is this person in the org?" is never a relationship. It's already in `ctx.roles`.
142
+ - A relationship's `where:` takes **scalar equality only** (`string | number | boolean`).
143
+ `where: { role: ['admin','owner'] }` is not valid; declare one relationship per role, or use
144
+ org roles.
145
+
146
+ `quickback docs define` for the full ladder; `define/access`, `define/areas`, `define/fga` per rung.
147
+
148
+ ---
149
+
105
150
  ## The security model
106
151
 
107
152
  Every API request passes through four pillars (the "Definitions"):
@@ -22,11 +22,28 @@ You deeply understand:
22
22
  - **Layouts**: CMS record page field grouping with sections, columns, and collapsed state
23
23
  - **Account UI**: Pre-built auth/account/org/admin SPA with compile-time feature gating
24
24
 
25
+ ## Never model tenancy
26
+
27
+ **Workspace, team, tenant, account, org — they are all the Better Auth organization.** Never
28
+ create a table for the tenant, and never create a membership table for it. Put
29
+ `organizationId: q.scope("organization")` on every tenant-scoped table; membership and roles
30
+ arrive as `ctx.activeOrgId` and `ctx.roles`. Tenants are created with
31
+ `POST /auth/v1/organization/create`, not a custom action.
32
+
33
+ Climb the authorization ladder only as far as the rule requires — **most apps stop at rung 1**:
34
+
35
+ 1. **Org roles + firewall** — `q.scope('organization')` + `roles: ['member+' / 'admin+']`. No `authz` block.
36
+ 2. **Named rules** — `authz.roles` / `authz.rules`, when one expression repeats across features.
37
+ 3. **Relationships + areas** — only when membership lives in *your own* domain table, or a
38
+ subtree needs a shared prefix *and* a per-row gate. A relationship's `from:` must be a
39
+ feature table (never a Better Auth table), and its `where:` is scalar equality only.
40
+ 4. **FGA** — only for a true permission graph.
41
+
25
42
  ## When Invoked
26
43
 
27
44
  1. **Understand the requirement** - What kind of resource? What security pattern?
28
45
  2. **Choose the right pattern**:
29
- - Multi-tenant B2B → Organization-scoped firewall
46
+ - Multi-tenant B2B → Organization-scoped firewall (the org already exists — never build one)
30
47
  - Personal data → Owner-scoped firewall
31
48
  - Hierarchical access → Organization + owner-optional
32
49
  - Public/reference data → `exception: true`
@@ -8,7 +8,33 @@ The current release series. Older entries are archived by version range:
8
8
  - [v0.20 – v0.29](/changelog/v0.2x)
9
9
  - [v0.18 and earlier](/changelog/v0.1x)
10
10
 
11
- ## Unreleased
11
+ ## v0.59.1 — July 29, 2026
12
+
13
+ ### Fix: auth and features D1 bindings could collapse onto one name
14
+
15
+ A project whose database config carried a single `binding` (e.g.
16
+ `binding: 'DB'`) emitted **two** `[[d1_databases]]` entries bound to the same
17
+ name, while the generated code still called `env.AUTH_DB`. Half the runtime
18
+ therefore reached a database with no auth tables.
19
+
20
+ In split mode — the default for `cloudflare-d1` — `binding` names the
21
+ **features** database only; auth is a separate D1 with its own `authBinding`.
22
+ The service resolver was letting auth fall back to the generic `binding`, so one
23
+ value drove both.
24
+
25
+ It went unnoticed because three places resolved the auth binding independently
26
+ and only one carried that extra fallback, so the reserved-name validator
27
+ computed `AUTH_DB`/`DB`, saw no clash, and passed while the wrangler emit
28
+ computed `DB`/`DB`. All three now agree.
29
+
30
+ A binding collision in split mode is also a **compile error** now rather than a
31
+ silently broken deploy, naming `authBinding` / `featuresBinding` and the
32
+ `splitDatabases: false` single-database alternative as the fixes.
33
+
34
+ Not introduced by v0.59.0 — the same behaviour is present in v0.58.3 and
35
+ earlier. If you hit it, set `authBinding` explicitly or upgrade.
36
+
37
+ ## v0.59.0 — July 29, 2026
12
38
 
13
39
  ### BREAKING · Masking: sensitive columns now require an explicit decision
14
40
 
@@ -332,7 +358,7 @@ reference to a firewall-bearing gate whose lanes the resource doesn't also stamp
332
358
  compile errors. Gates in `realtime.requiredRoles` lower to static who-roles at the handshake;
333
359
  a declared non-empty list that lowers to nothing is a compile error, never a silent `[]`. A
334
360
  new `AUTHZ_UNKNOWN_ROLE_NAME` warning flags reference-shaped names that resolve to nothing.
335
- See [named gates](/define/access#named-gates-authzrules) ·
361
+ See [named gates](/define/authz-roles#named-gates-authzrules) ·
336
362
  [`{ tenant }`](/define/firewall#named-tenant-anchors-tenant) ·
337
363
  [`{ rule }`](/define/firewall#named-gate-references-rule).
338
364
 
@@ -448,7 +448,7 @@ Record-based actions with `bulkVariant: true` are now emitted as sibling operati
448
448
 
449
449
  ### Cross-tenant "my events" patterns
450
450
 
451
- The access docs now include a worked example for the cross-tenant aggregation pattern (e.g. `GET /my-events` returning resources across all tenants a caller is invited to). See [Access → Cross-tenant dashboards](/define/access#cross-tenant-my-events-dashboards-are-not-this).
451
+ The access docs now include a worked example for the cross-tenant aggregation pattern (e.g. `GET /my-events` returning resources across all tenants a caller is invited to). See [Access → Cross-tenant dashboards](/define/relationships#cross-tenant-my-events-dashboards-are-not-this).
452
452
 
453
453
  ---
454
454
 
@@ -490,7 +490,7 @@ Supported surfaces: row-level scoping via `firewall: [{ field, via }]`, role gat
490
490
 
491
491
  Cross-tenant aggregation dashboards aren't solved by relationship-roles — the tenant firewall remains the outermost AND. For that pattern, use a user-scoped firewall or function-form access on a dedicated route.
492
492
 
493
- See [Firewall → Relationship-based scoping](/define/firewall#relationship-based-scoping-via) and [Access → Relationship-based authorization](/define/access#relationship-based-authorization).
493
+ See [Firewall → Relationship-based scoping](/define/firewall#relationship-based-scoping-via) and [Access → Relationship-based authorization](/define/relationships).
494
494
 
495
495
  ### Bulk variants on record-based actions
496
496
 
@@ -91,6 +91,25 @@ This is recon-mitigation, not a security boundary. Hiding a tool from the list n
91
91
 
92
92
  The unauthenticated `GET /mcp` discovery payload returns server info only; it does **not** enumerate tool names. Inventory is exclusively available via the access-filtered `tools/list`.
93
93
 
94
+ ### Request limits
95
+
96
+ Unless `requireAuth` is set, `/mcp` accepts anonymous POSTs, so both the body
97
+ and the JSON-RPC batch array are attacker-controlled. Two limits apply:
98
+
99
+ | Limit | Value | Behaviour when exceeded |
100
+ | --- | --- | --- |
101
+ | Request body | 1 MiB | `413` with JSON-RPC error `-32600` |
102
+ | Batch elements | 50 | `413` with `-32600`; split the batch |
103
+
104
+ The body is read through a byte counter rather than buffered whole, so an
105
+ oversized request is cut off mid-stream instead of being materialized first.
106
+ A size rejection is deliberately distinct from `-32700` *Parse error* — a
107
+ client told "parse error" would retry the same oversized body.
108
+
109
+ Batches are dispatched in waves of 8 rather than all at once. Every element
110
+ becomes its own internal request through the full middleware chain, so peak
111
+ concurrency stays flat regardless of how large a batch is submitted.
112
+
94
113
  ### Authentication
95
114
 
96
115
  MCP clients pass their credentials through the standard `Authorization: Bearer <jwt>` header. The generated MCP handler forwards the header verbatim into the internal request, and the same JWT middleware that guards `/api/v1/*` validates it.
@@ -97,7 +97,7 @@ Every optional top-level key the config accepts is listed below. You never have
97
97
  | `contract` | `{ version?: "v1" \| "v2" }` | Public API/auth contract version. Omit for the backward-compatible v1 default; select v2 for `/api/v2/*` and `/auth/v2/*` across generated routes, Better Auth, OpenAPI, MCP, and discovery. |
98
98
  | `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/configure/domains) |
99
99
  | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`/`profileUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
100
- | `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/define/access#centrally-defined-access-rules) and [Permissions](/define/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/define/areas) (`_area.ts`), and root bodies may reference root-declared names only |
100
+ | `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/define/authz-roles#centrally-defined-access-rules) and [Permissions](/define/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/define/areas) (`_area.ts`), and root bodies may reference root-declared names only |
101
101
  | `requires` | `string[]` | Capability floor (fail-closed guard). Declare `['feature-areas']` when the project uses `features/**/_area.ts` — an area-unaware CLI/compiler then refuses the compile instead of silently dropping nested features. See [Feature areas](/define/areas#the-capability-floor-requires-feature-areas) |
102
102
  | `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
103
103
  | `features` | `object` | Feature flags such as `organizations` / `pinnedOrganizationId` — see [Pinned Organization Mode](/configure/single-tenant) |