@quickback-dev/cli 0.66.0 → 0.66.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 (75) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  3. package/dist/lib/wrangler-resources.js +5 -2
  4. package/dist/lib/wrangler-resources.js.map +1 -1
  5. package/dist/lib/wrangler-resources.test.js +6 -0
  6. package/dist/lib/wrangler-resources.test.js.map +1 -1
  7. package/dist/skill/SKILL.md +18 -3
  8. package/dist/skill/docs/changelog/index.md +8 -0
  9. package/dist/skill/docs/configure/domains.md +1 -1
  10. package/dist/skill/docs/configure/index.md +3 -2
  11. package/dist/skill/docs/configure/providers.md +5 -3
  12. package/dist/skill/docs/configure/single-tenant.md +7 -3
  13. package/dist/skill/docs/define/access.md +3 -0
  14. package/dist/skill/docs/define/actions/index.md +1 -1
  15. package/dist/skill/docs/define/actions/scoped-db.md +22 -5
  16. package/dist/skill/docs/define/feature.md +3 -1
  17. package/dist/skill/docs/define/firewall.md +2 -0
  18. package/dist/skill/docs/define/index.md +1 -1
  19. package/dist/skill/docs/define/relationships.md +7 -0
  20. package/dist/skill/docs/define/schema.md +21 -1
  21. package/dist/skill/docs/define/triggers.md +14 -3
  22. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  23. package/dist/skill/docs/platform/database/d1.md +13 -1
  24. package/dist/skill/docs/platform/realtime/using-realtime.md +6 -4
  25. package/dist/skill/docs/start/deploy-browser.md +2 -2
  26. package/dist/skill/docs/start/deploy-owner-access.md +49 -50
  27. package/dist/skill/docs/start/deploy.md +2 -2
  28. package/dist/skill/docs/start/first-api.md +1 -1
  29. package/dist/skill/docs/start/patterns.md +17 -2
  30. package/dist/skill/docs/start/template-cloudflare.md +1 -1
  31. package/dist/skill/docs/tooling/cli.md +1 -1
  32. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  33. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
  34. package/dist/skill/docs/ui/account/customization.md +1 -1
  35. package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
  36. package/dist/skill/docs/ui/account/features/index.md +7 -6
  37. package/dist/skill/docs/ui/account/features/organizations.md +1 -1
  38. package/dist/skill/docs/ui/account/hooks.md +2 -0
  39. package/dist/skill/docs/ui/account/index.md +7 -4
  40. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  41. package/package.json +1 -1
  42. package/src/skill/SKILL.md +18 -3
  43. package/src/skill/docs/changelog/index.md +8 -0
  44. package/src/skill/docs/configure/domains.md +1 -1
  45. package/src/skill/docs/configure/index.md +3 -2
  46. package/src/skill/docs/configure/providers.md +5 -3
  47. package/src/skill/docs/configure/single-tenant.md +7 -3
  48. package/src/skill/docs/define/access.md +3 -0
  49. package/src/skill/docs/define/actions/index.md +1 -1
  50. package/src/skill/docs/define/actions/scoped-db.md +22 -5
  51. package/src/skill/docs/define/feature.md +3 -1
  52. package/src/skill/docs/define/firewall.md +2 -0
  53. package/src/skill/docs/define/index.md +1 -1
  54. package/src/skill/docs/define/relationships.md +7 -0
  55. package/src/skill/docs/define/schema.md +21 -1
  56. package/src/skill/docs/define/triggers.md +14 -3
  57. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  58. package/src/skill/docs/platform/database/d1.md +13 -1
  59. package/src/skill/docs/platform/realtime/using-realtime.md +6 -4
  60. package/src/skill/docs/start/deploy-browser.md +2 -2
  61. package/src/skill/docs/start/deploy-owner-access.md +49 -50
  62. package/src/skill/docs/start/deploy.md +2 -2
  63. package/src/skill/docs/start/first-api.md +1 -1
  64. package/src/skill/docs/start/patterns.md +17 -2
  65. package/src/skill/docs/start/template-cloudflare.md +1 -1
  66. package/src/skill/docs/tooling/cli.md +1 -1
  67. package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  68. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
  69. package/src/skill/docs/ui/account/customization.md +1 -1
  70. package/src/skill/docs/ui/account/features/api-keys.md +10 -8
  71. package/src/skill/docs/ui/account/features/index.md +7 -6
  72. package/src/skill/docs/ui/account/features/organizations.md +1 -1
  73. package/src/skill/docs/ui/account/hooks.md +2 -0
  74. package/src/skill/docs/ui/account/index.md +7 -4
  75. package/src/skill/docs/ui/account/with-quickback.md +1 -1
@@ -1,73 +1,72 @@
1
1
  # Owner access after a browser deploy
2
2
 
3
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:
4
+ first deploy seeds your app's first administrator (`user.role === "sysadmin"`),
5
+ a first organization they own, and a password. The card shows the **email**, a
6
+ **click-to-reveal password**, and a normal link to your app's Account login:
6
7
 
7
8
  ```
8
- https://<your-app>.<subdomain>.workers.dev/__quickback/claim#token=…
9
+ https://<your-app>.<subdomain>.workers.dev/account/login
9
10
  ```
10
11
 
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`.
12
+ Sign in with that email and password. That's the whole setup. After sign-in,
13
+ `/cms/` opens because the seeded role is `sysadmin` — the CMS data-plane tier,
14
+ one above `appmanager`.
15
+
16
+ ## What you get
17
+
18
+ - **Shown once.** The plaintext password is returned to Start on the deploy
19
+ that created the admin, and again only if you explicitly reset it. Quickback
20
+ stores the hash in your app's auth database, never the password.
21
+ - **A first organization.** The deploy also inserts an organization named after
22
+ your Worker and seats the admin as `owner`, so org-scoped tables and the CMS
23
+ tenant picker have somewhere to land. A routine redeploy does not create a
24
+ second one. If the compiled config sets `features.pinnedOrganizationId`, that
25
+ string **is** the organization id — the pin and the AUTH_DB row match, the
26
+ CMS skips the tenant picker, and the seeded sysadmin is `owner` of that org
27
+ (so create/update/delete in the CMS actually work). Without a pin the id is
28
+ a random hex.
29
+ - **Your app's login.** After that reveal you sign in through **your app's
30
+ own auth** — the same email + password login every other user of your app
31
+ gets. If your app has the Account UI enabled, that's `/account/login`.
32
+ - **A public URL, not a secret.** The login link is an ordinary
33
+ `<a href="…/account/login">`. It does not carry a token. Anyone can open
34
+ the page; only the password signs you in.
35
+
36
+ The synthetic email looks like `owner@<your-app>.invalid`. Type it exactly as
37
+ shown next to the password.
40
38
 
41
39
  ## Signing up yourself doesn't make you an admin
42
40
 
43
41
  `/account/signup` creates an ordinary user. It never sets
44
- `role === "appmanager"`, so that account can't open `/cms/`. The claim link is
45
- the only path to the first admin.
42
+ `role === "sysadmin"`, so that account can't open `/cms/`. The seeded
43
+ admin is the only path to the first administrator.
46
44
 
47
45
  No confirmation email is sent, either — apps built from Start default to email
48
46
  and password with verification off, because a `workers.dev` deploy has no
49
47
  verified sending domain. If you're waiting on a signup email, nothing is
50
- coming; open the claim link instead, or re-issue one from the deploy card.
48
+ coming; use the credentials on the deploy card.
51
49
 
52
- **Quickback is not your app's identity provider.** The claim link is a
53
- bootstrap window, not a login method: once claimed (or expired), your app has
54
- no runtime dependency on Quickback or the deploy broker for authentication.
50
+ **Quickback is not your app's identity provider.** The password reveal is a
51
+ bootstrap window, not a login method: once you've signed in (or reset), your
52
+ app has no runtime dependency on Quickback or the deploy broker for
53
+ authentication.
55
54
 
56
- ## Lost access? Re-issue from Start
55
+ ## Lost access? Reset from Start
57
56
 
58
57
  Deployed apps on `workers.dev` can't send password-reset email, so your
59
- Cloudflare account is the recovery root: in the deploy card, **Re-issue admin
60
- claim link** mints a fresh link — authorized by the same Cloudflare connection
61
- that deployed the app. Re-claiming resets the admin password.
58
+ Cloudflare account is the recovery root: in the deploy card (or the chip above
59
+ the composer), **Reset admin password** writes a new hash and shows a fresh
60
+ password once — authorized by the same Cloudflare connection that deployed
61
+ the app.
62
62
 
63
- Every issue **rotates the signing key**, so any older link immediately stops
64
- working, claimed or not. A fresh link re-opens the claim page on its own —
65
- nothing has to be reset first, because "claimable" just means a signed,
66
- unexpired, unused token exists.
63
+ A routine redeploy does **not** re-surface credentials. Only an explicit
64
+ reset does.
67
65
 
68
66
  ## For CLI deploys
69
67
 
70
- The claim route only activates when the `QUICKBACK_CLAIM_KEY` Worker secret is
71
- set — the browser-deploy broker mints it automatically. Apps deployed with
72
- `quickback deploy` don't get a claim link (the route answers 404); create your
73
- admin through your own flow, or deploy once through Start to bootstrap.
68
+ Browser deploys seed the admin automatically. Apps deployed with
69
+ `quickback deploy` don't; create your admin through your own flow, or deploy
70
+ once through Start to bootstrap. The generated `/__quickback/claim` route
71
+ still exists for older apps and answers 404 unless a leftover
72
+ `QUICKBACK_CLAIM_KEY` Worker secret is set — new deploys do not set it.
@@ -15,7 +15,7 @@ cd my-app && quickback deploy
15
15
  1. **Preflight** — verifies `wrangler` is runnable (via `npx`) and authenticated with Cloudflare (`wrangler whoami`). Log in with `npx wrangler login` or set `CLOUDFLARE_API_TOKEN`.
16
16
  2. **Compiles first if needed** — if the project has never compiled (no `wrangler.toml`), it runs the same flow as `quickback compile` before planning anything.
17
17
  3. **Plans from wrangler.toml** — reads the generated `wrangler.toml` and finds every resource whose id is still a placeholder:
18
- - **D1 databases** — auth, features, files, and webhooks databases (whichever your project's features pull in; split-database projects get one entry each)
18
+ - **D1 databases** — auth, features, files, webhooks, and audit databases (whichever your project's features pull in; split-database projects get one entry each)
19
19
  - **KV namespace** — the `KV` binding used for rate limiting and session overflow
20
20
  - **R2 buckets** — file-storage buckets (R2 is referenced by name, so buckets are simply ensured to exist)
21
21
  4. **Creates what's missing** — `wrangler d1 create <name>`, `wrangler kv namespace create <BINDING>`, `wrangler r2 bucket create <name>`. Resources are named from your project name exactly the way the compiler names them (`my-app-auth`, `my-app-features`, `my-app-files`, `my-app-KV`, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.
@@ -78,7 +78,7 @@ Re-run with `--force` to take Cloudflare's value, or fix the config by hand.
78
78
 
79
79
  ## Notes
80
80
 
81
- - **Security-audit database** — projects using unsafe cross-tenant actions require an audit D1 database, and the compiler fails closed at compile time until `auditDatabaseId` is set. Follow the compile error's instructions (create the database, set the id), then re-run `quickback deploy`.
81
+ - **Security-audit database** — projects using unsafe, `PUBLIC`, or hard-delete actions get an `AUDIT_DB` D1. Compile emits a placeholder id; `quickback deploy` creates the database and writes `auditDatabaseId` back, same as AUTH_DB / features DB. Direct `wrangler deploy` of the placeholder fails Cloudflare 10021 — use `quickback deploy`.
82
82
  - **Neon projects** — `quickback deploy` does not apply Postgres migrations. Run `npm run db:migrate` (needs `DATABASE_MIGRATION_URL`) before traffic hits the worker, or use the generated project's `npm run deploy` script which chains both.
83
83
  - **Hyperdrive** — a Hyperdrive binding can't be auto-created (it needs your database connection string). Create it with `wrangler hyperdrive create <name> --connection-string=… --caching-disabled` and set `providers.database.config.hyperdrive.id`.
84
84
  - **Two logins** — the compile step uses your Quickback account (`quickback login`); resource creation and deploy use your wrangler credentials.
@@ -70,7 +70,7 @@ export default feature('candidates', {
70
70
  });
71
71
  ```
72
72
 
73
- > `mode: 'hard'` is also available, but hard deletes erase the row — so they require the security-audit pipeline. On D1 that means setting `auditDatabaseId` on the database provider config (the compiler errors with setup instructions if it's missing). A table only drops `...q.softDelete()` when **both** `delete.mode` and `batchDelete.mode` are `'hard'`; declaring the pair on a hard-delete table is itself a compile error.
73
+ > `mode: 'hard'` is also available, but hard deletes erase the row — so they require the security-audit pipeline. On D1 the compiler emits an `AUDIT_DB` binding (placeholder id until `quickback deploy` creates the database). A table only drops `...q.softDelete()` when **both** `delete.mode` and `batchDelete.mode` are `'hard'`; declaring the pair on a hard-delete table is itself a compile error.
74
74
 
75
75
  > Prefer the explicit two-export form (or interop with existing Drizzle schemas)? See [feature() — single-export sugar](/define/feature) and [Schema: choosing between `q` and Drizzle](/define/schema#choosing-between-q-and-drizzle). All forms compile identically; mix freely per file.
76
76
 
@@ -161,7 +161,14 @@ export default defineAction({
161
161
 
162
162
  ## Referencing Users / Org Members (Assignees)
163
163
 
164
- Assignee-style features need to validate that a submitted `userId` is actually a member of the caller's organization. The scoped `db` only sees feature tables — reach the Better Auth tables via `c.get("authDb")` and the generated `getOrgMemberRole` helper:
164
+ The **caller's** identity is already on the request — `ctx.userId`,
165
+ `ctx.activeOrgId`, `ctx.roles`, `ctx.userRole`. Do not query `AUTH_DB` for
166
+ the acting user.
167
+
168
+ Assignee-style features need to validate that a *submitted* `userId` is
169
+ actually a member of the caller's organization. The scoped `db` never
170
+ includes Better Auth tables — that is by design. Reach AUTH_DB from an
171
+ **action** via `c.get("authDb")` and the generated `getOrgMemberRole` helper:
165
172
 
166
173
  ```typescript
167
174
  // quickback/features/projects/actions/assign.ts
@@ -189,7 +196,15 @@ export default defineAction({
189
196
  });
190
197
  ```
191
198
 
192
- Store the assignee as a plain text column (e.g. `assigneeId: q.text().optional()`) — don't name it `userId`. `userId` is *not* auto-detected as an owner column on feature tables (that column is `ownerId`), but the compiler flags it: an error if it's the only candidate column on the table, a warning alongside a detected isolation column. Rename to `assigneeId`, or declare `firewall: { owner: { column: "userId" } }` if the column really is the row's owner. See [Firewall](/define/firewall).
199
+ Store the assignee as a plain text column (e.g. `assigneeId: q.text().optional()`) — don't name it `userId`, and **never** `.references(() => users.id)`. Better Auth tables live in `AUTH_DB`; feature tables live in `DB`. A SQL FK across those databases is not possible, and drizzle-kit fails generating features migrations. `userId` is *not* auto-detected as an owner column on feature tables (that column is `ownerId`), but the compiler flags it: an error if it's the only candidate column on the table, a warning alongside a detected isolation column. Rename to `assigneeId`, or declare `firewall: { owner: { column: "userId" } }` if the column really is the row's owner. See [Firewall](/define/firewall) and [Schema → References](/define/schema).
200
+
201
+ On D1 the Better Auth tables are `user`, `organization`, and `member` — not
202
+ `organization_membership`. For a richer query from an `actions/` file, import
203
+ those from `../../../auth/schema` and query `c.get("authDb")`. Account hooks
204
+ get `{ authDb, authSchema }` injected ([Auth Hooks](/ui/account/hooks)).
205
+ Trigger `handler:` args are `{ ctx, db, env }` — `db` is features only; there
206
+ is no `c` and no `authDb`. Prefer `ctx`. Do not import `../../auth/schema`
207
+ from a table file ([Triggers](/define/triggers)).
193
208
 
194
209
  ## Admin-Only Status Field
195
210
 
@@ -216,7 +216,7 @@ Depending on your configuration, the compiler may also generate bindings for:
216
216
 
217
217
  By default, the Cloudflare template separates auth tables from application tables:
218
218
 
219
- - **`AUTH_DB`** — Better Auth tables (`users`, `sessions`, `accounts`, `organizations`, `members`)
219
+ - **`AUTH_DB`** — Better Auth tables (`user`, `session`, `account`, `organization`, `member`)
220
220
  - **`DB`** — Your feature tables (`todos`, etc.)
221
221
 
222
222
  This keeps auth data isolated and allows independent scaling. Each database gets its own migration directory:
@@ -372,7 +372,7 @@ quickback compile
372
372
 
373
373
  The API key takes precedence over stored credentials from `quickback login`.
374
374
 
375
- You can create API keys from your [Quickback account](https://account.quickback.dev/profile). Each key is scoped to your organization.
375
+ You can create API keys from your [Quickback account](https://account.quickback.dev/api-keys). Each key is scoped to your organization.
376
376
 
377
377
  ### Custom Compiler URL
378
378
 
@@ -22,7 +22,7 @@ For non-interactive environments (CI/CD, scripts), use an API key:
22
22
  QUICKBACK_API_KEY=your_api_key quickback compile
23
23
  ```
24
24
 
25
- Create API keys from your [Quickback account](https://account.quickback.dev/profile). Each key is scoped to your organization.
25
+ Create API keys from your [Quickback account](https://account.quickback.dev/api-keys). Each key is scoped to your organization.
26
26
 
27
27
  The API key takes precedence over stored credentials from `quickback login`.
28
28
 
@@ -67,6 +67,34 @@ If a hint is missing, compile now fails loudly with the exact key path to add, f
67
67
  - `Expected hint key: compiler.migrations.renames.tables["events_v2"]`
68
68
  - `Expected hint key: compiler.migrations.renames.columns["events"]["summary_text"]`
69
69
 
70
+ ## `Critical command failed: Generate features database migrations`
71
+
72
+ drizzle-kit could not load the generated **features** schema. The usual cause on
73
+ D1 (`splitDatabases: true`) is a feature column that `.references()` a Better
74
+ Auth table:
75
+
76
+ {/* doc-compile: skip — illegal one-liner, not a host feature */}
77
+ ```typescript
78
+ userId: q.text().required().references(() => users.id, { onDelete: 'cascade' }) // illegal
79
+ ```
80
+
81
+ `users` / `user` / `organization` / `member` live in `AUTH_DB`. Features live in
82
+ `DB`. SQLite cannot FK across them, and drizzle-kit cannot resolve `users` when
83
+ generating features migrations.
84
+
85
+ A Start chat compile (`complete=false`) still succeeds — it never runs
86
+ drizzle-kit. Deploy (`complete=true`) is the first time that command runs.
87
+
88
+ Store the Better Auth id as plain text:
89
+
90
+ {/* doc-compile: skip — one-liner, not a host feature */}
91
+ ```typescript
92
+ userId: q.text().required()
93
+ ```
94
+
95
+ `.references()` is only for another feature table in `DB`. See
96
+ [Schema → References](/define/schema).
97
+
70
98
  ## "Could not load organizations"
71
99
 
72
100
  This can happen if your session token expired or if the API is temporarily unavailable. Re-login:
@@ -93,7 +93,7 @@ setAppConfig({
93
93
  | `privacy` | "Privacy Policy" | Footer link text |
94
94
  | `support` | "Contact Support" | Footer link text |
95
95
  | `company` | (from `VITE_COMPANY_NAME`) | Footer company name |
96
- | `organizations` | "Organizations" | Navigation and page titles |
96
+ | `organizations` | "Organizations" | Navigation and page titles. Profile and the user menu prefix this as **Manage …** (`Manage Organizations`). |
97
97
 
98
98
  ## Custom Messages
99
99
 
@@ -1,21 +1,23 @@
1
1
  # API Key Management
2
2
 
3
- Account UI provides an API key management interface for users to create, view, and revoke API keys.
3
+ API keys are a user credential. Manage them at `/api-keys`, linked from `/profile`. The `apiKey` plugin is on by default.
4
4
 
5
5
  ## Creating API Keys
6
6
 
7
- Users can create API keys with:
8
-
9
- - Custom name/description
10
- - Optional expiration date
11
- - Scoped to the current organization
7
+ - Custom name
8
+ - Shown once at creation — copy it then
9
+ - Scoped to an organization via `metadata.organizationId` so the key inherits your role in that tenant
10
+ - One organization: stamped automatically
11
+ - Several organizations: pick one when creating
12
12
 
13
13
  ## Managing Keys
14
14
 
15
- - View all active API keys
16
- - See last-used timestamp
15
+ - List every key you own (not filtered to the current org)
16
+ - See last-used timestamp and which organization the key is scoped to
17
17
  - Revoke individual keys
18
18
 
19
+ `/$slug/api-keys` redirects here so old bookmarks still work.
20
+
19
21
  ## Related
20
22
 
21
23
  - [API Keys Auth](/platform/auth/api-keys) — Server-side API key authentication
@@ -171,10 +171,10 @@ VITE_ENABLE_GOOGLE_OAUTH=false # default: false
171
171
 
172
172
  **When enabled:**
173
173
  - "Continue with Google" button on the login and signup pages
174
- - Google row in the profile page's Connected Accounts card
174
+ - Google row on `/connected-accounts` (linked from **Manage Connected Accounts** on `/profile`)
175
175
 
176
176
  **When disabled:**
177
- - No social sign-in button, no Connected Accounts row
177
+ - No social sign-in button, no **Manage Connected Accounts** link, no `/connected-accounts` page
178
178
 
179
179
  **Requirements:**
180
180
  - Google OAuth credentials configured on the Better Auth side
@@ -187,14 +187,14 @@ VITE_ENABLE_CLOUDFLARE_OAUTH=false # default: false
187
187
 
188
188
  **When enabled:**
189
189
  - "Continue with Cloudflare" button on the login and signup pages
190
- - Cloudflare rows in the profile page's Connected Accounts card — unlike
190
+ - Cloudflare rows on `/connected-accounts` — unlike
191
191
  Google, more than one Cloudflare identity can be linked to the same user
192
192
  (**Connect another Cloudflare account**), and every linked identity signs
193
193
  in to this user. Link work and personal Cloudflare logins here so each one
194
194
  doesn't mint its own separate account.
195
195
 
196
196
  **When disabled:**
197
- - No Cloudflare sign-in button, no Connected Accounts rows
197
+ - No Cloudflare sign-in button, no **Manage Connected Accounts** link, no `/connected-accounts` page
198
198
 
199
199
  **Requirements:**
200
200
  - `socialProviders.cloudflare.enabled` in the auth config (Cloudflare rides
@@ -256,10 +256,11 @@ VITE_ENABLE_ORGANIZATIONS=false # default: false
256
256
  ```
257
257
 
258
258
  **When enabled:**
259
- - Users can create organizations
260
- - Organization management pages
259
+ - `/dashboard` lists organizations and pending invitations
260
+ - Organization management pages (`/$slug`)
261
261
  - Member invitations and roles
262
262
  - `/organizations/*` routes
263
+ - Sign-in still lands on `/profile`; **Manage Organizations** opens `/dashboard`
263
264
 
264
265
  **When disabled:**
265
266
  - Single-user mode only
@@ -1,6 +1,6 @@
1
1
  # Organizations
2
2
 
3
- Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
3
+ Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. `/dashboard` is that surface: the organizations you belong to and pending invitations. **Manage Organizations** on `/profile` (and in the user menu) opens it. Personal account settings live on `/profile`. The profile **Go to…** picker opens the tenant app using `account.appUrl` and `account.tenantPattern` — see [Customization](/ui/account/customization#tenant-url-patterns). Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
4
4
 
5
5
  ## Organization CRUD
6
6
 
@@ -219,6 +219,8 @@ type HookCtx = {
219
219
 
220
220
  `authDb` is the load-bearing piece: hooks must write to the auth DB via Drizzle directly. See the [CSRF caveat](#csrf-caveat-server-side-org-create) below. `authSchema` is the namespace export of the generated auth schema module; destructure the tables you need.
221
221
 
222
+ This injection is unique to account hooks. Actions reach AUTH_DB via `c.get("authDb")` ([Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb)). Trigger handlers on a table file get neither — use `ctx` for the acting user, and do not import `../../auth/schema` from the table file.
223
+
222
224
  The atomic email-OTP hook additionally receives `db` (the transaction-bound
223
225
  full application Drizzle client), `schema` (the full generated application
224
226
  schema), and `atomicRoute: "emailOtpSignIn"`. In a single-database Neon project,
@@ -8,13 +8,15 @@ Account UI is a single React SPA that contains three distinct sections:
8
8
 
9
9
  ### Account (every user)
10
10
 
11
- Login, signup, profile editing, password management, device sessions, email changes, and account deletion. This is what every user interacts with.
11
+ Login, signup, profile editing, password management, device sessions, email changes, and account deletion. This is what every user interacts with. After sign-in, Account UI lands on `/profile`.
12
+
13
+ When organizations are enabled, `/profile` has **Manage Organizations** (the `/dashboard` org list and invites) and a **Go to…** control that opens the tenant app. The URL is `account.appUrl` plus `account.tenantPattern` with the org slug substituted (the same `getTenantUrl` used on the org dashboard). One org is a single button; several orgs is a picker. The control is hidden when those config values cannot produce a URL.
12
14
 
13
15
  Served on its own domain (e.g., `auth.example.com`) or at `/account/` when embedded alongside the CMS.
14
16
 
15
17
  ### Organization Management (multi-tenant)
16
18
 
17
- Dashboard with org switching, org creation, member invitations, role management, and org settings. Only available when `auth.organizations` is enabled.
19
+ `/dashboard` is org management — org list, pending invitations, and the path into org settings (`/$slug`). Personal account settings stay on `/profile`. Only available when `auth.organizations` is enabled.
18
20
 
19
21
  ### Admin Panel (admin users only)
20
22
 
@@ -86,7 +88,7 @@ Auth feature flags control which pages are included in the bundle:
86
88
  | `auth.password` | Password login, inline password change on profile |
87
89
  | `auth.emailOTP` | Email OTP login flow, email-based password reset |
88
90
  | `auth.passkey` | Passkey setup and management |
89
- | `auth.organizations` | Dashboard, org creation, member management, invitations |
91
+ | `auth.organizations` | `/dashboard` (org list + invitations), org creation, member management |
90
92
  | `auth.admin` | Admin panel (user management) |
91
93
 
92
94
  When a flag is `false`, the corresponding routes **guard themselves at runtime** — each feature route checks its flag from the worker-injected `window.__QUICKBACK_RUNTIME` config in `beforeLoad` and redirects away, and navigation entries for it are hidden. The Account SPA ships as one generic prebuilt bundle; flags decide which surfaces exist for your project.
@@ -95,9 +97,10 @@ When a flag is `false`, the corresponding routes **guard themselves at runtime**
95
97
 
96
98
  - **Authentication** — Email/password, passkeys (WebAuthn), email OTP, magic links, email verification, password reset
97
99
  - **Account Management** — Profile editing, avatar upload, password changes, device/session management, account deletion
100
+ - **Connected Accounts** — Link Google and Cloudflare logins from `/connected-accounts` (linked from profile)
98
101
  - **Organizations** — Multi-tenant org management with owner/admin/member roles, invitations, and org settings
99
102
  - **Admin Panel** — User management dashboard with search, create, ban/unban, password reset, and session viewing
100
- - **API Keys** — Generate and manage API keys for programmatic access
103
+ - **API Keys** — Generate and manage API keys from `/api-keys` (linked from profile)
101
104
  - **CLI Authorization** — Device authorization flow for `quickback login`
102
105
 
103
106
  ## Next Steps
@@ -68,7 +68,7 @@ auth: {
68
68
  password: true, // Email/password login + inline password change
69
69
  emailOTP: false, // Email OTP login flow
70
70
  passkey: true, // WebAuthn passkey setup + management
71
- organizations: true, // Dashboard, org management, invitations
71
+ organizations: true, // /dashboard org list, org management, invitations
72
72
  admin: true, // Admin panel (user management)
73
73
  }
74
74
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.66.0",
3
+ "version": "0.66.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",
@@ -273,9 +273,17 @@ throw new ActionError("Not enough balance", "INSUFFICIENT_FUNDS", 400, { availab
273
273
 
274
274
  Constructor: `(message, code, statusCode = 400, details?)`. Do **NOT** throw Hono's `HTTPException` — it isn't unwrapped and surfaces as a 500 `ACTION_EXECUTION_FAILED`. Returning `c.json({...}, 400)` directly also works (the executor receives `c`).
275
275
 
276
- ## Reaching auth tables (org members, users) from actions
276
+ ## Reaching auth tables (org members, users)
277
277
 
278
- The scoped `db` only sees feature tables. For "is this userId a member of the caller's org?" (assignee-style features), use the Hono context's auth DB plus the generated helper:
278
+ The scoped feature `db` never includes Better Auth tables — that is by design.
279
+ `AUTH_DB` is a separate Drizzle client.
280
+
281
+ **Caller identity — use `ctx`, do not query AUTH_DB.** `ctx.userId`,
282
+ `ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request
283
+ (there is no `ctx.orgId`).
284
+
285
+ To check that a *submitted* userId is a member of the caller's org, use the
286
+ Hono context's auth DB plus the generated helper — from an **action**:
279
287
 
280
288
  ```ts
281
289
  import { getOrgMemberRole } from "../../../lib/org-access";
@@ -284,7 +292,14 @@ const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activ
284
292
  if (!role) throw new ActionError("Not a member of this organization", "NOT_A_MEMBER", 400);
285
293
  ```
286
294
 
287
- `c.get("authDb")` is the Drizzle connection to the Better Auth database (a separate D1 in dual-DB mode). For richer queries import tables from `../../../auth/schema`. The `ctx` fields are `userId`, `roles` (org-member roles), `activeOrgId`, `activeTeamId`, `userRole` — there is no `ctx.orgId`.
295
+ That is the native membership check. For a richer query from an `actions/`
296
+ file, import tables from `../../../auth/schema`. On D1 the tables are `user`,
297
+ `organization`, and `member` — not `organization_membership`.
298
+
299
+ Account hooks get `{ authDb, authSchema }` injected. Trigger `handler:` args
300
+ are `{ ctx, db, env }` — `db` is features only; there is no `c` and no
301
+ `authDb`. Prefer `ctx` for the acting user. Do not import `../../auth/schema`
302
+ from a table file to reach AUTH_DB.
288
303
 
289
304
  ---
290
305
 
@@ -86,6 +86,14 @@ without `auth.jwt` it still cannot be admitted: 200 from the mint, 401 on
86
86
  presentation. The compiler now warns instead of failing silently. Declare
87
87
  `auth: { jwt: {} }` if you use those routes.
88
88
 
89
+ ### CMS and Account consume CloudEvents frames as-is
90
+
91
+ The bundled SPAs no longer invert realtime frames back into a private
92
+ `{ type, table, event }` shape, and they no longer sniff `/api/v2` to pick
93
+ the broadcast URL. They match on `qbframe`, read `data` / `qbseq`, and take
94
+ `/broadcast/v1` or `/broadcast/v2` from the injected runtime config — the
95
+ same prefixes the worker actually mounts.
96
+
89
97
  ## v0.65.x — August 16, 2026
90
98
 
91
99
  ### Passkeys no longer silently degrade to `rpID: 'localhost'`
@@ -146,7 +146,7 @@ When the compiler builds the Account SPA, it excludes route files for disabled f
146
146
 
147
147
  | Feature Flag | Routes Excluded When `false` |
148
148
  |-------------|------------------------------|
149
- | `auth.organizations` | Dashboard, organization CRUD, org switching (`$slug`) |
149
+ | `auth.organizations` | `/dashboard` (org list + invitations), organization CRUD, org switching (`$slug`) |
150
150
  | `auth.passkey` | Passkey management and setup |
151
151
  | `auth.admin` | Admin panel routes |
152
152
 
@@ -620,7 +620,8 @@ account: {
620
620
  |--------|------|-------------|
621
621
  | `domain` | `string` | Custom domain for Account UI (e.g., `auth.example.com`) |
622
622
  | `adminDomain` | `string` | Custom domain for admin-only access (e.g., `admin.example.com`). Serves the same Account SPA — the client-side router handles admin routing. |
623
- | `appUrl` | `string` | URL of the tenant's main application — where users are redirected after login. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Independent from `domain`. |
623
+ | `appUrl` | `string` | Origin of the tenant's main application. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Combined with `tenantPattern` for the profile **Go to…** picker. Independent from `domain`. A deploy-target `APP_URL` can override this at serve time. |
624
+ | `tenantPattern` | `string` | URL pattern for a tenant, with `{slug}` substituted. Default `/{slug}`. Relative patterns are resolved against `appUrl`; a full `https://{slug}.example.com` pattern is used as-is. Baked as `VITE_TENANT_URL_PATTERN`. |
624
625
  | `name` | `string` | App display name shown on login, profile, and email templates |
625
626
  | `companyName` | `string` | Company name for branding |
626
627
  | `tagline` | `string` | App tagline shown on login page |
@@ -638,7 +639,7 @@ Control which authentication features are exposed. Disabled features are exclude
638
639
  | `auth.emailOTP` | `boolean` | `false` | adds `emailOtp` plugin | Email one-time password login — adds plugin server-side, surfaces UI |
639
640
  | `auth.passkey` | `boolean` | `false` | adds `passkey` plugin | WebAuthn/FIDO2 passkey authentication — adds plugin server-side, surfaces UI |
640
641
  | `auth.signup` | `boolean` | `true` | `emailAndPassword.disableSignUp` (inverted) | Self-service account registration — false hides the UI **and** rejects the server endpoint with 403 |
641
- | `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (dashboard, invitations, roles). Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
642
+ | `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (`/dashboard` org list, invitations, roles). Sign-in lands on `/profile`. Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
642
643
  | `auth.admin` | `boolean` | `false` | UI surface only | Admin panel for user management in the Account SPA. The Better Auth admin plugin is compiler-managed separately from this UI toggle |
643
644
  | `auth.emailVerification` | `boolean` | `false` | `emailAndPassword.requireEmailVerification` | Require email verification before sessions are issued. False = sessions usable immediately after signup |
644
645
 
@@ -105,7 +105,7 @@ single Postgres database with no bindings or split mode (see
105
105
  | `webhooksDatabaseId` | `string` | — | D1 database ID for the webhooks database |
106
106
  | `auditBinding` | `string` | `"AUDIT_DB"` | Binding name for the security audit database |
107
107
  | `auditDatabaseName` | `string` | `"{app}-audit"` | D1 database name for audit events |
108
- | `auditDatabaseId` | `string` | — | Explicit D1 database ID for audit events |
108
+ | `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
109
  | `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
110
  | `realtime` | `boolean \| { enabled?, wsTicket? }` | `false` | Enables the Broadcaster Durable Object and optional resource-scoped ws-ticket auth (see [below](#realtime-broadcast-config)) |
111
111
  | `webhookAdminRoles` | `string[]` | `["owner", "admin"]` | Org roles allowed to manage webhook endpoints |
@@ -127,7 +127,9 @@ connection modes, RLS, and the migration workflow.
127
127
 
128
128
  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
129
 
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. To override defaults:
130
+ 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.
131
+
132
+ To override defaults:
131
133
 
132
134
  ```typescript
133
135
  providers: {
@@ -139,7 +141,7 @@ providers: {
139
141
  }
140
142
  ```
141
143
 
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.
144
+ 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
145
 
144
146
  #### Setting Database IDs for Deployment
145
147
 
@@ -25,9 +25,13 @@ export default defineConfig({
25
25
  });
26
26
  ```
27
27
 
28
- > **Use a Real Organization ID**
28
+ > **The organization must exist**
29
29
  >
30
- > `pinnedOrganizationId` must point at an organization that actually exists in your Better Auth data. The compiler does not create the organization for you.
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: "<real-org-id>"`.
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
 
@@ -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
@@ -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,