@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.
- package/dist/index.js +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 +18 -3
- package/dist/skill/docs/changelog/index.md +8 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +3 -2
- package/dist/skill/docs/configure/providers.md +5 -3
- package/dist/skill/docs/configure/single-tenant.md +7 -3
- package/dist/skill/docs/define/access.md +3 -0
- package/dist/skill/docs/define/actions/index.md +1 -1
- package/dist/skill/docs/define/actions/scoped-db.md +22 -5
- package/dist/skill/docs/define/feature.md +3 -1
- package/dist/skill/docs/define/firewall.md +2 -0
- 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 +21 -1
- package/dist/skill/docs/define/triggers.md +14 -3
- package/dist/skill/docs/platform/auth/api-keys.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +13 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +6 -4
- package/dist/skill/docs/start/deploy-browser.md +2 -2
- package/dist/skill/docs/start/deploy-owner-access.md +49 -50
- package/dist/skill/docs/start/deploy.md +2 -2
- package/dist/skill/docs/start/first-api.md +1 -1
- package/dist/skill/docs/start/patterns.md +17 -2
- package/dist/skill/docs/start/template-cloudflare.md +1 -1
- package/dist/skill/docs/tooling/cli.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
- package/dist/skill/docs/ui/account/customization.md +1 -1
- package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
- package/dist/skill/docs/ui/account/features/index.md +7 -6
- package/dist/skill/docs/ui/account/features/organizations.md +1 -1
- package/dist/skill/docs/ui/account/hooks.md +2 -0
- package/dist/skill/docs/ui/account/index.md +7 -4
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/package.json +1 -1
- package/src/skill/SKILL.md +18 -3
- package/src/skill/docs/changelog/index.md +8 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +3 -2
- package/src/skill/docs/configure/providers.md +5 -3
- package/src/skill/docs/configure/single-tenant.md +7 -3
- package/src/skill/docs/define/access.md +3 -0
- package/src/skill/docs/define/actions/index.md +1 -1
- package/src/skill/docs/define/actions/scoped-db.md +22 -5
- package/src/skill/docs/define/feature.md +3 -1
- package/src/skill/docs/define/firewall.md +2 -0
- 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 +21 -1
- package/src/skill/docs/define/triggers.md +14 -3
- package/src/skill/docs/platform/auth/api-keys.md +1 -1
- package/src/skill/docs/platform/database/d1.md +13 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +6 -4
- package/src/skill/docs/start/deploy-browser.md +2 -2
- package/src/skill/docs/start/deploy-owner-access.md +49 -50
- package/src/skill/docs/start/deploy.md +2 -2
- package/src/skill/docs/start/first-api.md +1 -1
- package/src/skill/docs/start/patterns.md +17 -2
- package/src/skill/docs/start/template-cloudflare.md +1 -1
- package/src/skill/docs/tooling/cli.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
- package/src/skill/docs/ui/account/customization.md +1 -1
- package/src/skill/docs/ui/account/features/api-keys.md +10 -8
- package/src/skill/docs/ui/account/features/index.md +7 -6
- package/src/skill/docs/ui/account/features/organizations.md +1 -1
- package/src/skill/docs/ui/account/hooks.md +2 -0
- package/src/skill/docs/ui/account/index.md +7 -4
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
|
@@ -448,9 +448,14 @@ with the transition's "from" precondition for transition actions.
|
|
|
448
448
|
|
|
449
449
|
#### Reaching Better Auth tables (`authDb`)
|
|
450
450
|
|
|
451
|
-
The scoped `db`
|
|
452
|
-
|
|
453
|
-
|
|
451
|
+
The scoped `db` is the **features** database. Better Auth tables never appear
|
|
452
|
+
on it — that is by design. `AUTH_DB` is a separate Drizzle client.
|
|
453
|
+
|
|
454
|
+
**Caller identity — use `ctx`, do not query `AUTH_DB`.** `ctx.userId`,
|
|
455
|
+
`ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request.
|
|
456
|
+
|
|
457
|
+
To check that a *submitted* user id is an org member (assignee-style
|
|
458
|
+
features), use `c.get("authDb")` plus the generated `getOrgMemberRole` helper:
|
|
454
459
|
|
|
455
460
|
```typescript
|
|
456
461
|
// features/projects/actions/assign.ts — validate a userId is an org member
|
|
@@ -481,6 +486,18 @@ export default defineAction({
|
|
|
481
486
|
```
|
|
482
487
|
|
|
483
488
|
`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
|
-
|
|
489
|
+
mode it's a separate D1 from your features). That is the native membership
|
|
490
|
+
check.
|
|
491
|
+
|
|
492
|
+
For a richer query, use the same `authDb` and import tables from
|
|
493
|
+
`../../../auth/schema` — from an **`actions/` file**. On D1 the tables are
|
|
494
|
+
`user`, `organization`, and `member` — not `organization_membership`. (Neon
|
|
495
|
+
exports the Better Auth CLI's plural names: `users`, `organizations`,
|
|
496
|
+
`members`.)
|
|
497
|
+
|
|
498
|
+
| Surface | AUTH_DB handle | Notes |
|
|
499
|
+
|---|---|---|
|
|
500
|
+
| Action `execute` | `c.get("authDb")` | Import schema from `../../../auth/schema` |
|
|
501
|
+
| [Account hooks](/ui/account/hooks) | `{ authDb, authSchema }` injected | Use the injected namespace — do not invent a path to `auth/schema` |
|
|
502
|
+
| 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. |
|
|
486
503
|
|
|
@@ -187,7 +187,9 @@ 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
|
|
|
@@ -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
|
|
@@ -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**
|
|
@@ -82,7 +82,27 @@ A few mechanics to know:
|
|
|
82
82
|
- **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
|
|
83
83
|
- **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
|
|
84
84
|
- **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
|
|
85
|
-
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path.
|
|
85
|
+
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path. `other` must be a **feature table in the same database**.
|
|
86
|
+
|
|
87
|
+
> **Never FK Better Auth tables**
|
|
88
|
+
>
|
|
89
|
+
> `.references(() => users.id)` (or `user`, `organization`, `member`, `session`) on a feature column is illegal. Those tables live in `AUTH_DB`; your features live in `DB`. SQLite cannot FK across D1 databases, and drizzle-kit fails generating features migrations:
|
|
90
|
+
>
|
|
91
|
+
> `Critical command failed: Generate features database migrations`
|
|
92
|
+
>
|
|
93
|
+
> A Start chat compile (`complete=false`) still succeeds — it never runs drizzle-kit. Deploy (`complete=true`) is the first time that command runs.
|
|
94
|
+
>
|
|
95
|
+
> A junction's `userId` is a **plain text** Better Auth id, not a SQL FK:
|
|
96
|
+
>
|
|
97
|
+
> {/* doc-compile: skip — two-column excerpt, not a host feature */}
|
|
98
|
+
> ```typescript
|
|
99
|
+
> userId: q.text().required(), // ctx.userId — no .references()
|
|
100
|
+
> channelId: q.text().required().references(() => channels.id, { onDelete: 'cascade' }),
|
|
101
|
+
> ```
|
|
102
|
+
>
|
|
103
|
+
> `authz.relationships` `subject: { column: 'userId', equals: 'ctx.userId' }` does not need, and must not create, a SQL FK. See [Relationships](/define/relationships). To query Better Auth tables, use `c.get("authDb")` from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
104
|
+
|
|
105
|
+
|
|
86
106
|
- **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
|
|
87
107
|
|
|
88
108
|
### Column Types
|
|
@@ -106,6 +106,15 @@ Live Views, with full application context:
|
|
|
106
106
|
handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) => { ... }
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
+
The `db` a handler receives is the **features** database. There is no `c` and
|
|
110
|
+
no `authDb`. Prefer `ctx.userId`, `ctx.activeOrgId`, `ctx.roles`, and
|
|
111
|
+
`ctx.userRole` for the acting user.
|
|
112
|
+
|
|
113
|
+
Do **not** import `../../auth/schema` from the table file to reach AUTH_DB —
|
|
114
|
+
that import used to survive compile and then fail package-mode wrangler with
|
|
115
|
+
`Could not resolve`. Checking that another user is an org member belongs in
|
|
116
|
+
an [action](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
117
|
+
|
|
109
118
|
- **`before*` hooks are synchronous.** Return a partial object to merge
|
|
110
119
|
into the write payload, or throw to reject — the write never executes and
|
|
111
120
|
the request gets a structured `TRIGGER_REJECTED` (422) error. Audit
|
|
@@ -116,9 +125,11 @@ handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) =>
|
|
|
116
125
|
`TRIGGER_AFTER_FAILED` (500) with `details.committed: true` — the row was
|
|
117
126
|
already persisted (no transactions on D1), so clients must not blind-retry.
|
|
118
127
|
- Handlers must be **inline arrow/function expressions**. Imports they
|
|
119
|
-
reference are hoisted into the generated registry
|
|
120
|
-
|
|
121
|
-
as
|
|
128
|
+
reference are hoisted into the generated registry (`src/lib/trigger-hooks.ts`)
|
|
129
|
+
with relative paths rewritten from the table file — including dynamic
|
|
130
|
+
`import("…")` inside the handler. Write them as they resolve next to the
|
|
131
|
+
table. Each table's drizzle object is auto-imported under its authored
|
|
132
|
+
name — so this works as written:
|
|
122
133
|
|
|
123
134
|
```typescript
|
|
124
135
|
import { eq } from 'drizzle-orm';
|
|
@@ -4,7 +4,7 @@ API keys provide programmatic access for CI/CD pipelines, scripts, and server-to
|
|
|
4
4
|
|
|
5
5
|
## Creating API Keys
|
|
6
6
|
|
|
7
|
-
Create API keys from
|
|
7
|
+
Create API keys from [Account UI](/ui/account/features/api-keys) (`/api-keys`, linked from profile). Each key is owned by you and scoped to an organization.
|
|
8
8
|
|
|
9
9
|
## Usage
|
|
10
10
|
|
|
@@ -22,7 +22,7 @@ Quickback generates separate D1 databases for different concerns:
|
|
|
22
22
|
|
|
23
23
|
| Database | Binding | Purpose |
|
|
24
24
|
|----------|---------|---------|
|
|
25
|
-
| `AUTH_DB` | `AUTH_DB` | Better Auth tables (user
|
|
25
|
+
| `AUTH_DB` | `AUTH_DB` | Better Auth tables (`user`, `session`, `account`, `organization`, `member`) |
|
|
26
26
|
| `DB` | `DB` | Your application data |
|
|
27
27
|
| `FILES_DB` | `FILES_DB` | File metadata for R2 uploads |
|
|
28
28
|
| `WEBHOOKS_DB` | `WEBHOOKS_DB` | Webhook delivery tracking |
|
|
@@ -32,6 +32,18 @@ This separation provides:
|
|
|
32
32
|
- **Isolation** - Auth schema changes don't touch your data
|
|
33
33
|
- **Clarity** - Clear ownership of each database
|
|
34
34
|
|
|
35
|
+
SQLite foreign keys cannot cross those databases. Feature columns must never
|
|
36
|
+
`.references()` Better Auth tables (`user` / `users` / `organization` /
|
|
37
|
+
`member`). Store a Better Auth id as plain text (`userId: q.text().required()`).
|
|
38
|
+
A `.references(() => users.id)` on a feature table makes deploy fail with
|
|
39
|
+
`Critical command failed: Generate features database migrations`. See
|
|
40
|
+
[Schema → References](/define/schema).
|
|
41
|
+
|
|
42
|
+
The scoped feature `db` never includes those tables — query them from an
|
|
43
|
+
action with `c.get("authDb")`, not from a trigger. On D1 the membership table
|
|
44
|
+
is `member`, not `organization_membership`. See
|
|
45
|
+
[Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
46
|
+
|
|
35
47
|
## Drizzle ORM Integration
|
|
36
48
|
|
|
37
49
|
Quickback uses [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access:
|
|
@@ -278,10 +278,12 @@ as a normal `postgres_changes` frame on the table's room.
|
|
|
278
278
|
"data": { "eventId": "…", "documentId": "…" } }
|
|
279
279
|
```
|
|
280
280
|
|
|
281
|
-
The bundled CMS
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
281
|
+
The bundled CMS and Account SPAs consume these envelopes as-is:
|
|
282
|
+
match on `qbframe`, read the row from `data`, and (for live views) the
|
|
283
|
+
monotonic seq from `qbseq`. The full channel/message catalog ships as
|
|
284
|
+
`GET /asyncapi.json` (AsyncAPI 3.0), served under the same auth gating as
|
|
285
|
+
`/openapi.json`. Any project with realtime or webhooks serves it, and it
|
|
286
|
+
documents the CloudEvents envelopes above.
|
|
285
287
|
|
|
286
288
|
## Cloudflare Only
|
|
287
289
|
|
|
@@ -113,7 +113,7 @@ Deploy is disabled while a reconnect is pending, so a deploy never starts on a c
|
|
|
113
113
|
|
|
114
114
|
### Reconnecting
|
|
115
115
|
|
|
116
|
-
**Reconnect** re-runs the same consent and lands on the **same connection record** — your account picker, deploys, and
|
|
116
|
+
**Reconnect** re-runs the same consent and lands on the **same connection record** — your account picker, deploys, and admin password reset all keep working. Reconnecting is also how you widen a grant that's missing a permission.
|
|
117
117
|
|
|
118
118
|
### Connecting more than one Cloudflare account
|
|
119
119
|
|
|
@@ -177,7 +177,7 @@ Start keeps a chip above the composer naming the app this chat deployed, with li
|
|
|
177
177
|
Your app answers at `https://<app-name>.<your-subdomain>.workers.dev`:
|
|
178
178
|
|
|
179
179
|
- **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.
|
|
180
|
-
- **Apps with the Account UI or CMS** redirect `/` to the login page or CMS. Both ship by default from Start, at `/cms/` and `/account/`. The CMS needs `user.role === "
|
|
180
|
+
- **Apps with the Account UI or CMS** redirect `/` to the login page or CMS. Both ship by default from Start, at `/cms/` and `/account/`. The CMS needs `user.role === "sysadmin"`, which your first deploy seeds (along with a first organization) — see [Owner access](/start/deploy-owner-access).
|
|
181
181
|
- `/health` reports status and whether email is configured.
|
|
182
182
|
|
|
183
183
|
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.
|
|
@@ -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 (
|
|
5
|
-
|
|
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/
|
|
9
|
+
https://<your-app>.<subdomain>.workers.dev/account/login
|
|
9
10
|
```
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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 === "
|
|
45
|
-
the only path to the first
|
|
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;
|
|
48
|
+
coming; use the credentials on the deploy card.
|
|
51
49
|
|
|
52
|
-
**Quickback is not your app's identity provider.** The
|
|
53
|
-
bootstrap window, not a login method: once
|
|
54
|
-
no runtime dependency on Quickback or the deploy broker for
|
|
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?
|
|
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
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
|
|
64
|
-
|
|
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
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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 (`
|
|
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/
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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,
|