@quickback-dev/cli 0.60.9 → 0.61.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/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +10 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +737 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/index.js +1 -1
- package/dist/lib/compiler-stubs.d.ts +4 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +4 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/file-loader.d.ts +11 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +35 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/skill/SKILL.md +3 -0
- package/dist/skill/docs/api/errors.md +1 -0
- package/dist/skill/docs/api/query-params.md +26 -0
- package/dist/skill/docs/changelog/index.md +85 -0
- package/dist/skill/docs/configure/auth.md +17 -12
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +6 -6
- package/dist/skill/docs/define/actions/defining.md +37 -1
- package/dist/skill/docs/define/actions/index.md +18 -0
- package/dist/skill/docs/define/areas.md +90 -7
- package/dist/skill/docs/define/feature.md +88 -27
- package/dist/skill/docs/define/index.md +7 -1
- package/dist/skill/docs/define/scopes.md +1 -1
- package/dist/skill/docs/define/security.md +10 -0
- package/dist/skill/docs/define/transitions.md +11 -35
- package/dist/skill/docs/platform/auth/jwt-optimization.md +15 -3
- package/dist/skill/docs/platform/database/d1.md +6 -1
- package/dist/skill/docs/platform/email/index.md +112 -0
- package/dist/skill/docs/platform/index.md +1 -0
- package/dist/skill/docs/platform/realtime/index.md +17 -0
- package/dist/skill/docs/platform/webhooks/outbound.md +31 -6
- package/dist/skill/docs/start/deploy-browser.md +15 -6
- package/dist/skill/docs/start/first-api.md +16 -0
- package/dist/skill/docs/ui/account/features/admin.md +29 -5
- package/dist/skill/docs/ui/account/features/index.md +22 -0
- package/dist/skill/docs/ui/admin/connecting.md +6 -4
- package/dist/skill/docs/ui/admin/index.md +49 -10
- package/dist/skill/docs/ui/admin/security.md +6 -7
- package/package.json +2 -10
- package/src/skill/SKILL.md +3 -0
- package/src/skill/docs/api/errors.md +1 -0
- package/src/skill/docs/api/query-params.md +26 -0
- package/src/skill/docs/changelog/index.md +85 -0
- package/src/skill/docs/configure/auth.md +17 -12
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +6 -6
- package/src/skill/docs/define/actions/defining.md +37 -1
- package/src/skill/docs/define/actions/index.md +18 -0
- package/src/skill/docs/define/areas.md +90 -7
- package/src/skill/docs/define/feature.md +88 -27
- package/src/skill/docs/define/index.md +7 -1
- package/src/skill/docs/define/scopes.md +1 -1
- package/src/skill/docs/define/security.md +10 -0
- package/src/skill/docs/define/transitions.md +11 -35
- package/src/skill/docs/platform/auth/jwt-optimization.md +15 -3
- package/src/skill/docs/platform/database/d1.md +6 -1
- package/src/skill/docs/platform/email/index.md +112 -0
- package/src/skill/docs/platform/index.md +1 -0
- package/src/skill/docs/platform/realtime/index.md +17 -0
- package/src/skill/docs/platform/webhooks/outbound.md +31 -6
- package/src/skill/docs/start/deploy-browser.md +15 -6
- package/src/skill/docs/start/first-api.md +16 -0
- package/src/skill/docs/ui/account/features/admin.md +29 -5
- package/src/skill/docs/ui/account/features/index.md +22 -0
- package/src/skill/docs/ui/admin/connecting.md +6 -4
- package/src/skill/docs/ui/admin/index.md +49 -10
- package/src/skill/docs/ui/admin/security.md +6 -7
|
@@ -22,25 +22,49 @@ When `auth.admin` is `false` (the default), the admin surface does not exist for
|
|
|
22
22
|
|
|
23
23
|
## What It Can Do
|
|
24
24
|
|
|
25
|
+
**Users** — every account in the app, independent of organization:
|
|
26
|
+
|
|
25
27
|
- **View all users** — Paginated list with search
|
|
26
28
|
- **Create users** — Manually create accounts with email/password
|
|
27
29
|
- **Ban/unban users** — Suspend or reactivate user accounts
|
|
28
30
|
- **Reset passwords** — Generate password reset for any user
|
|
29
31
|
- **View sessions** — See active sessions for any user
|
|
30
32
|
|
|
33
|
+
**Organizations** — every tenant, whether or not you belong to it:
|
|
34
|
+
|
|
35
|
+
- **List all organizations** — cross-tenant, not just your memberships
|
|
36
|
+
- **Create an organization** — you name the **owner**; the operator creating it is deliberately not seated (see below)
|
|
37
|
+
- **Seat, re-role and remove members** — manage a tenant's roster without joining it
|
|
38
|
+
|
|
39
|
+
These run on `/auth/v1/admin/*`, emitted by Quickback because Better Auth's organization plugin cannot serve them: every one of its endpoints resolves through the *caller's* membership, and an operator administers organizations it does not belong to.
|
|
40
|
+
|
|
41
|
+
> **Users sign themselves up.** Self-serve signup stays on — a new account simply has no organization, and lands on a screen saying so until someone invites or seats them. What operators control is *organizations*, not accounts.
|
|
42
|
+
|
|
43
|
+
|
|
31
44
|
## Access Control
|
|
32
45
|
|
|
33
|
-
The admin panel is restricted to
|
|
46
|
+
The admin panel is restricted to platform roles on the Better Auth user record: **`appmanager`** (the control plane) and **`sysadmin`** (which adds cross-tenant data access on top). Everyone else is redirected away from `/admin`.
|
|
34
47
|
|
|
35
|
-
|
|
48
|
+
> **`role: "admin"` is not a platform role.** The compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`, so a user set to `"admin"` passed the UI guard and then got `403` from every admin API call — an operator who looked promoted and could not act. Removed in v0.62; migrate those rows to `"appmanager"`.
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
To grant operator access to a user:
|
|
36
52
|
|
|
37
53
|
```bash
|
|
38
54
|
curl -X POST https://api.example.com/auth/v1/admin/set-role \
|
|
39
55
|
-H "Authorization: Bearer $TOKEN" \
|
|
40
56
|
-H "Content-Type: application/json" \
|
|
41
|
-
-d '{ "userId": "user_123", "role": "
|
|
57
|
+
-d '{ "userId": "user_123", "role": "appmanager" }'
|
|
42
58
|
```
|
|
43
59
|
|
|
60
|
+
### Why creating an organization names an owner
|
|
61
|
+
|
|
62
|
+
Better Auth's `organization.create` seats whoever calls it. For an operator that is an escalation rather than a convenience: the membership it grants is tenant-data access — under `cms.access: "member"`, access to that organization's records — which is exactly what the `appmanager`/`sysadmin` split withholds.
|
|
63
|
+
|
|
64
|
+
So organization creation asks for an `ownerUserId`, seats that user, and never seats the caller. Self-serve creation (`POST /auth/v1/organization/create`) is closed by default for the same reason; a project that wants it sets `plugins.organization.allowUserToCreateOrganization: true`.
|
|
65
|
+
|
|
66
|
+
An operator who genuinely wants their own organization creates one naming themselves as owner — explicit, and visible in the audit trail rather than implied by whoever happened to make the call.
|
|
67
|
+
|
|
44
68
|
## Custom Admin Domain
|
|
45
69
|
|
|
46
70
|
Give the admin panel its own subdomain with `adminDomain`:
|
|
@@ -64,10 +88,10 @@ The admin domain serves the same Account SPA at root (`/`). The SPA's client-sid
|
|
|
64
88
|
When both CMS and Account UI are enabled, the admin panel's profile page shows a "Go to CMS" button. You can restrict this to admin users only:
|
|
65
89
|
|
|
66
90
|
```typescript
|
|
67
|
-
cms: { domain: "cms.example.com", access: "
|
|
91
|
+
cms: { domain: "cms.example.com", access: "sysadmin" },
|
|
68
92
|
```
|
|
69
93
|
|
|
70
|
-
With `access: "
|
|
94
|
+
With `access: "sysadmin"`, only the cross-tenant `sysadmin` tier reaches the CMS: the link is hidden in Account UI, `/api/v1/schema` returns `403`, and `custom_view` CRUD is locked to `userRole: ["sysadmin"]`. Note that an **appmanager does not get in** — `/account/admin` (this page) is the appmanager's surface, and the CMS is not. See [CMS access gate](/ui/admin#access-gate) for the full model.
|
|
71
95
|
|
|
72
96
|
## Related
|
|
73
97
|
|
|
@@ -179,6 +179,28 @@ VITE_ENABLE_GOOGLE_OAUTH=false # default: false
|
|
|
179
179
|
**Requirements:**
|
|
180
180
|
- Google OAuth credentials configured on the Better Auth side
|
|
181
181
|
|
|
182
|
+
### Cloudflare OAuth
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
VITE_ENABLE_CLOUDFLARE_OAUTH=false # default: false
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**When enabled:**
|
|
189
|
+
- "Continue with Cloudflare" button on the login and signup pages
|
|
190
|
+
- Cloudflare rows in the profile page's Connected Accounts card — unlike
|
|
191
|
+
Google, more than one Cloudflare identity can be linked to the same user
|
|
192
|
+
(**Connect another Cloudflare account**), and every linked identity signs
|
|
193
|
+
in to this user. Link work and personal Cloudflare logins here so each one
|
|
194
|
+
doesn't mint its own separate account.
|
|
195
|
+
|
|
196
|
+
**When disabled:**
|
|
197
|
+
- No Cloudflare sign-in button, no Connected Accounts rows
|
|
198
|
+
|
|
199
|
+
**Requirements:**
|
|
200
|
+
- `socialProviders.cloudflare.enabled` in the auth config (Cloudflare rides
|
|
201
|
+
the genericOAuth plugin, not a Better Auth built-in) and the
|
|
202
|
+
`AUTH_CLOUDFLARE_CLIENT_ID` / `AUTH_CLOUDFLARE_CLIENT_SECRET` secrets
|
|
203
|
+
|
|
182
204
|
## Account Management Features
|
|
183
205
|
|
|
184
206
|
### File Uploads
|
|
@@ -136,22 +136,24 @@ cms: { domain: "cms.example.com" }
|
|
|
136
136
|
|
|
137
137
|
This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `cms.example.com` point to the same Worker. The compiler auto-configures hostname-based routing and cross-subdomain cookies.
|
|
138
138
|
|
|
139
|
-
CMS access defaults to `access: "
|
|
139
|
+
CMS access defaults to `access: "sysadmin"` — only `user.role === "sysadmin"` (the cross-tenant data-plane tier) can use `/cms/*`. Set `access: "member"` to also admit anyone holding an organization membership. `user.role === "appmanager"` opens the CMS in neither mode: it is the control-plane tier and belongs at `/account/admin`. The gate is enforced at multiple layers:
|
|
140
140
|
|
|
141
141
|
- **Account UI** hides the "Go to CMS" button for callers outside those roles.
|
|
142
142
|
- **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-operator. A non-operator who types the CMS URL directly cannot load the app.
|
|
143
143
|
- **`/api/v1/schema`** returns `403 Platform operator access required` to callers outside those roles, so schema metadata can't be scraped by hitting the API directly.
|
|
144
144
|
- **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
|
|
145
|
-
- **In-SPA
|
|
145
|
+
- **In-SPA screen** — a signed-in caller who isn't admitted is served the shell and shown a screen naming what they'd need. There is no wrong-role redirect.
|
|
146
146
|
|
|
147
147
|
Your resource API endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
|
|
148
148
|
|
|
149
|
-
To
|
|
149
|
+
To let organization members in as well as sysadmins:
|
|
150
150
|
|
|
151
151
|
```typescript
|
|
152
|
-
cms: { access: "
|
|
152
|
+
cms: { access: "member" }
|
|
153
153
|
```
|
|
154
154
|
|
|
155
|
+
See [Access gate](/ui/admin#access-gate) for the full model — including why `appmanager` opens the CMS in neither mode.
|
|
156
|
+
|
|
155
157
|
See [Multi-Domain Architecture](/configure/domains) for details on multi-domain routing.
|
|
156
158
|
|
|
157
159
|
## Default Org Mode vs Pinned Organization Mode
|
|
@@ -112,22 +112,61 @@ cms: { domain: "cms.example.com" }
|
|
|
112
112
|
|
|
113
113
|
This adds a custom domain route to `wrangler.toml`. Both domains serve the same Worker — `api.example.com` for the API, `cms.example.com` for the CMS. The compiler also auto-infers a unified `quickback.example.com` domain where everything is available. See [Multi-Domain Architecture](/configure/domains).
|
|
114
114
|
|
|
115
|
-
### Access gate
|
|
115
|
+
### Access gate
|
|
116
116
|
|
|
117
|
-
|
|
117
|
+
`cms.access` answers one question: **can anyone in the organization hierarchy use the CMS, or only a platform sysadmin?**
|
|
118
118
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
119
|
+
| Value | Who gets in |
|
|
120
|
+
|-------|-------------|
|
|
121
|
+
| `"sysadmin"` (default) | Only `user.role === "sysadmin"` — the cross-tenant data-plane tier. They choose a tenant from the org picker. |
|
|
122
|
+
| `"member"` | The above, **plus** any caller holding a membership in an organization, scoped to that organization. |
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
cms: { access: "member" } // let organization members in
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
> **`user.role === "appmanager"` does not open the CMS in either mode.** appmanager is the *control plane* — users, organizations, and subscriptions at [`/account/admin`](/ui/account) — and deliberately holds no tenant-data powers. Keeping those separable is the entire point of the appmanager/sysadmin split. An appmanager who is also a member of an organization gets in as that member, on the membership, not on the platform role.
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
#### Where the gate actually lives
|
|
132
|
+
|
|
133
|
+
The CMS **shell** is served to any signed-in caller. Authorization is decided in the SPA, which renders a screen naming the caller's state and what to do about it — a signed-in user who can't get in is told why, instead of being silently bounced.
|
|
134
|
+
|
|
135
|
+
That is a deliberate trade: the old gate answered a wrong-role caller with a `302` so it couldn't be used to probe roles. The shell is a generic prebuilt bundle with no project data in it, and being unable to distinguish a permissions problem from a broken deploy cost more than the deniability was worth.
|
|
136
|
+
|
|
137
|
+
The gates that carry real data:
|
|
138
|
+
|
|
139
|
+
1. **`/api/v1/schema`** — the metadata endpoint. Admits `sysadmin`, plus any caller with a membership when `access: "member"`. Otherwise `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
|
|
140
|
+
2. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, org membership *or* sysadmin in `"member"` mode.
|
|
141
|
+
3. **Account UI link** — the "Go to CMS" button is hidden for callers who wouldn't get in.
|
|
123
142
|
|
|
124
143
|
Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
|
|
125
144
|
|
|
126
|
-
|
|
145
|
+
> **Breaking in v0.62.** `cms.access` was renamed from `"admin" | "user"`, and both old values meant something different: `"admin"` admitted `appmanager`, and `"user"` admitted *any* authenticated caller — including one belonging to no organization, who then reached a CMS with nothing in it. The old spellings are rejected at compile time rather than aliased, because aliasing would preserve the old behaviour under a familiar name. Migrate `"admin"` → `"sysadmin"`, `"user"` → `"member"`.
|
|
127
146
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
147
|
+
|
|
148
|
+
#### What a blocked caller actually sees
|
|
149
|
+
|
|
150
|
+
The shell is served to any signed-in caller, and the SPA resolves one of six states — each its own screen naming what is true and what to do next. Nothing redirects: a signed-in user bounced elsewhere cannot tell a permissions problem from a broken deploy.
|
|
151
|
+
|
|
152
|
+
| State | Screen |
|
|
153
|
+
|-------|--------|
|
|
154
|
+
| Not signed in | Redirect to sign-in (the one redirect that remains — it is where you were going anyway) |
|
|
155
|
+
| `sysadmin`, no tenant chosen | Tenant picker, filterable, with **All organizations** as a first-class choice |
|
|
156
|
+
| `sysadmin`, tenant chosen | The CMS, scoped to that tenant |
|
|
157
|
+
| `appmanager`, `access: "sysadmin"` | *"The CMS shows organization data"* → **Go to admin** |
|
|
158
|
+
| Anyone else, `access: "sysadmin"` | *"This CMS is restricted"* — names the config value that would admit them |
|
|
159
|
+
| `access: "member"`, no membership | *"You're not in any organization yet"* → **View invitations** (an appmanager gets **Go to admin** instead — telling them to ask an admin for an invite when they are the admin is a dead end) |
|
|
160
|
+
| `access: "member"`, one membership | Auto-selected; straight in |
|
|
161
|
+
| `access: "member"`, several | Membership picker |
|
|
162
|
+
|
|
163
|
+
The decision is a pure function (`resolveCmsAccess`), so the table above is tested rather than described.
|
|
164
|
+
|
|
165
|
+
Sysadmin scope lives in the browser and rides every request as `?organizationId=` — it is not part of the session, because a sysadmin holds no membership row for Better Auth to make active. Change it from the sidebar.
|
|
166
|
+
|
|
167
|
+
#### `access: "sysadmin"` without `cms.sysadmin`
|
|
168
|
+
|
|
169
|
+
A sysadmin can still pin a single tenant — `?organizationId=` cross-tenant addressing is admitted for sysadmins unconditionally. The **"All organizations"** unfiltered view is what needs the firewall escape that `cms.sysadmin: true` emits.
|
|
131
170
|
|
|
132
171
|
### Optional: Skip SPA rebuild
|
|
133
172
|
|
|
@@ -2,19 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
The CMS respects all four Quickback security layers. Every UI element — buttons, form fields, table columns, action menus — adapts based on the current user's role and the security rules defined in your feature files.
|
|
4
4
|
|
|
5
|
-
## CMS Access
|
|
5
|
+
## CMS Access
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
`cms.access` decides whether the CMS is for platform sysadmins only (`"sysadmin"`, the default) or for organization members too (`"member"`). `user.role === "appmanager"` opens it in neither mode — that tier is the control plane, not the data plane.
|
|
8
8
|
|
|
9
9
|
```typescript
|
|
10
|
-
cms: { access: "
|
|
10
|
+
cms: { access: "member" }
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
The shell is served to any signed-in caller so the SPA can explain who is and isn't admitted; the gates that carry data are:
|
|
14
14
|
|
|
15
|
-
1. **Account UI** — the "Go to CMS" button is hidden.
|
|
16
|
-
2.
|
|
17
|
-
3. **`/api/v1/schema`** — the CMS metadata endpoint returns `403` to callers outside those roles.
|
|
15
|
+
1. **Account UI** — the "Go to CMS" button is hidden for callers who wouldn't get in.
|
|
16
|
+
2. **`/api/v1/schema`** — the metadata endpoint returns `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
|
|
18
17
|
4. **`custom_view` routes** — the CMS-internal saved-views table uses `userRole: ["appmanager"]` (and, when `cms.sysadmin: true`, also admits `sysadmin`), so saved views can't be read or modified from outside the CMS by non-operator accounts.
|
|
19
18
|
5. **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
|
|
20
19
|
|