@quickback-dev/cli 0.18.0 → 0.34.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 +25 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/migrations.d.ts +17 -0
- package/dist/commands/migrations.d.ts.map +1 -0
- package/dist/commands/migrations.js +328 -0
- package/dist/commands/migrations.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +33 -63
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +17 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +39 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +73 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +22 -1
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +1118 -1
- package/dist/skill/docs/compiler/config/domains.md +70 -10
- package/dist/skill/docs/compiler/config/index.md +74 -3
- package/dist/skill/docs/compiler/config/output.md +1 -1
- package/dist/skill/docs/compiler/config/providers.md +6 -12
- package/dist/skill/docs/compiler/config/single-tenant.md +1 -1
- package/dist/skill/docs/compiler/config/variables.md +0 -30
- package/dist/skill/docs/compiler/definitions/access.md +357 -3
- package/dist/skill/docs/compiler/definitions/actions.md +85 -8
- package/dist/skill/docs/compiler/definitions/schema.md +6 -10
- package/dist/skill/docs/compiler/index.md +15 -34
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/dist/skill/docs/compiler/targets/index.md +6 -34
- package/dist/skill/docs/index.md +2 -5
- package/dist/skill/docs/stack/account-ui/customization.md +2 -14
- package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/dist/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/dist/skill/docs/stack/account-ui/hooks.md +4 -0
- package/dist/skill/docs/stack/account-ui/index.md +5 -43
- package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +106 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +1057 -0
- package/src/skill/docs/compiler/config/domains.md +26 -0
- package/src/skill/docs/compiler/config/index.md +74 -3
- package/src/skill/docs/compiler/config/providers.md +6 -12
- package/src/skill/docs/compiler/config/single-tenant.md +1 -1
- package/src/skill/docs/compiler/config/variables.md +0 -30
- package/src/skill/docs/compiler/definitions/access.md +357 -3
- package/src/skill/docs/compiler/definitions/actions.md +85 -8
- package/src/skill/docs/compiler/definitions/schema.md +6 -10
- package/src/skill/docs/compiler/index.md +15 -34
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/src/skill/docs/compiler/targets/index.md +6 -34
- package/src/skill/docs/index.md +2 -5
- package/src/skill/docs/stack/account-ui/customization.md +2 -14
- package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/src/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/src/skill/docs/stack/account-ui/features/index.md +1 -1
- package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/src/skill/docs/stack/account-ui/hooks.md +4 -0
- package/src/skill/docs/stack/account-ui/index.md +5 -43
- package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/src/skill/docs/stack/auth/plugins/index.md +32 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
- package/dist/skill/docs/stack/account-ui/worker.md +0 -362
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/src/skill/docs/stack/account-ui/standalone.md +0 -149
- package/src/skill/docs/stack/account-ui/worker.md +0 -362
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
# Multi-Domain Architecture
|
|
2
2
|
|
|
3
|
-
A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI,
|
|
3
|
+
A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI, Admin panel, and your own product SPAs on separate custom domains. The compiler generates hostname-based routing so each domain serves the right content.
|
|
4
4
|
|
|
5
5
|
## How It Works
|
|
6
6
|
|
|
7
|
-
When you configure custom domains for CMS, Account,
|
|
7
|
+
When you configure custom domains for CMS, Account, Admin, or `apps`, the compiler:
|
|
8
8
|
|
|
9
9
|
1. Adds `custom_domain` routes to `wrangler.toml`
|
|
10
10
|
2. Generates hostname-based middleware in the Worker
|
|
11
11
|
3. Auto-configures cross-subdomain cookies for shared authentication
|
|
12
12
|
4. Auto-infers a unified `quickback.{baseDomain}` fallback domain
|
|
13
13
|
|
|
14
|
-
All
|
|
14
|
+
All configured domains point to the **same Worker** — there's only one deployment.
|
|
15
15
|
|
|
16
16
|
## Domain Types
|
|
17
17
|
|
|
@@ -21,6 +21,7 @@ All five domains point to the **same Worker** — there's only one deployment.
|
|
|
21
21
|
| `cms.example.com` | `cms: { domain }` | CMS SPA | Blocked (404) |
|
|
22
22
|
| `auth.example.com` | `account: { domain }` | Account SPA | Pass-through |
|
|
23
23
|
| `admin.example.com` | `account: { adminDomain }` | Account SPA | Pass-through |
|
|
24
|
+
| `www.example.com` | `apps: { <name>: { domain } }` | User-authored SPA | Pass-through |
|
|
24
25
|
| `quickback.example.com` | Auto-inferred | Everything | All |
|
|
25
26
|
|
|
26
27
|
### CMS Domain
|
|
@@ -35,6 +36,32 @@ Serves the Account SPA at root (`/`). API and auth routes pass through to the Wo
|
|
|
35
36
|
|
|
36
37
|
Identical behavior to the Account domain — serves the same Account SPA at root. The Account SPA's client-side router handles the `/admin` route, restricting access to users with the `admin` role.
|
|
37
38
|
|
|
39
|
+
### App Domains
|
|
40
|
+
|
|
41
|
+
Mount your own product SPAs on dedicated hostnames via the `apps` field. Each entry binds one or more hostnames to a directory under `src/apps/<name>/` and inherits the same API/auth pass-through behavior as the Account domain — so the SPA can hit `/api/v1/...` and `/auth/...` same-origin without CORS.
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
apps: {
|
|
45
|
+
www: {
|
|
46
|
+
domain: "www.example.com",
|
|
47
|
+
aliasDomains: ["example.com"], // apex serves the same SPA
|
|
48
|
+
},
|
|
49
|
+
marketing: {
|
|
50
|
+
domain: "marketing.example.com",
|
|
51
|
+
},
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
| Option | Required | Description |
|
|
56
|
+
|--------|----------|-------------|
|
|
57
|
+
| `domain` | Yes | Primary custom hostname served at root (`/`) |
|
|
58
|
+
| `aliasDomains` | No | Additional hostnames that serve the same SPA. Each gets its own `custom_domain = true` route. Common case: apex (`example.com`) alongside `www.example.com`. |
|
|
59
|
+
| `assetsDir` | No | Subdirectory under `src/apps/` to serve from. Defaults to the record key. Override only when the on-disk directory needs to differ from the URL-facing name. |
|
|
60
|
+
|
|
61
|
+
Drop the prebuilt SPA output at `quickback/apps/<name>/` — the source-apps passthrough copies it byte-for-byte into `src/apps/<name>/` on every compile. The compiler doesn't build the SPA; it just emits routing for whatever's already there. See [Output Structure](/compiler/config/output#source-apps-quickbackapps) for the passthrough rules.
|
|
62
|
+
|
|
63
|
+
The names `cms`, `account`, and `public` are reserved (they collide with compiler-emitted directories under `src/apps/`). Two app entries can't claim the same hostname, and an app's hostname can't collide with `cms.domain` / `account.domain` / `account.adminDomain`.
|
|
64
|
+
|
|
38
65
|
### Unified Domain
|
|
39
66
|
|
|
40
67
|
The compiler auto-infers a `quickback.{baseDomain}` domain from your configured custom domains. For example, if you have `cms.example.com`, it creates `quickback.example.com`.
|
|
@@ -68,11 +95,12 @@ export default {
|
|
|
68
95
|
name: "My App",
|
|
69
96
|
auth: { password: true, admin: true },
|
|
70
97
|
},
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
98
|
+
apps: {
|
|
99
|
+
www: {
|
|
100
|
+
domain: "www.example.com",
|
|
101
|
+
aliasDomains: ["example.com"],
|
|
102
|
+
},
|
|
103
|
+
},
|
|
76
104
|
providers: {
|
|
77
105
|
runtime: { name: "cloudflare", config: {
|
|
78
106
|
routes: [{ pattern: "api.example.com", custom_domain: true }],
|
|
@@ -82,6 +110,8 @@ export default {
|
|
|
82
110
|
};
|
|
83
111
|
```
|
|
84
112
|
|
|
113
|
+
`trustedOrigins` is optional here — every `cms.domain`, `account.domain`, `account.adminDomain`, and `apps[*].domain` (plus aliases) is automatically added. Declare `trustedOrigins` only when you need to allow an origin the compiler can't infer (e.g. a third-party domain).
|
|
114
|
+
|
|
85
115
|
This generates the following `wrangler.toml` routes:
|
|
86
116
|
|
|
87
117
|
```toml
|
|
@@ -90,18 +120,20 @@ routes = [
|
|
|
90
120
|
{ pattern = "cms.example.com", custom_domain = true },
|
|
91
121
|
{ pattern = "auth.example.com", custom_domain = true },
|
|
92
122
|
{ pattern = "admin.example.com", custom_domain = true },
|
|
123
|
+
{ pattern = "www.example.com", custom_domain = true },
|
|
124
|
+
{ pattern = "example.com", custom_domain = true },
|
|
93
125
|
{ pattern = "quickback.example.com", custom_domain = true }
|
|
94
126
|
]
|
|
95
127
|
```
|
|
96
128
|
|
|
97
129
|
## Cross-Subdomain Authentication
|
|
98
130
|
|
|
99
|
-
When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing:
|
|
131
|
+
When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com` + `www.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing. App hostnames (primary + aliases) are folded into the shared-parent detection alongside the CMS, Account, Admin, and top-level `domain` slots:
|
|
100
132
|
|
|
101
133
|
- Sets `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`
|
|
102
134
|
- Sets `sameSite: 'none'` and `secure: true` on auth cookies
|
|
103
135
|
|
|
104
|
-
This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com` and `
|
|
136
|
+
This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com`, `admin.example.com`, and `www.example.com` — no additional setup needed. Apex aliases (e.g. `example.com` listed under `aliasDomains`) are recognized as already being the parent — they don't break shared-parent equality.
|
|
105
137
|
|
|
106
138
|
> **Automatic Detection**
|
|
107
139
|
>
|
|
@@ -128,6 +160,8 @@ The compiler generates middleware that checks `new URL(c.req.url).hostname` on e
|
|
|
128
160
|
|
|
129
161
|
**Account/Admin domain** — API and auth routes (`/api/`, `/auth/`, `/admin/`, `/storage/`, `/health`) pass through to Hono handlers. All other paths are mapped to the `/account/` asset prefix and served with SPA fallback to `/account/index.html`.
|
|
130
162
|
|
|
163
|
+
**App domain** — Identical to Account: API/auth/admin/storage/health pass through, other paths map to `/<assetsDir>/` with SPA fallback. The multi-domain catchall (emitted when both CMS and Account are configured) explicitly skips app hostnames, so an API miss on an app host lands in `app.notFound` (404 JSON) instead of stray-serving a sibling SPA's HTML.
|
|
164
|
+
|
|
131
165
|
**Unified domain** — No hostname filtering. CMS is served at `/cms/`, Account at `/account/`. Root (`/`) redirects to `/cms/`. API routes work at their standard paths.
|
|
132
166
|
|
|
133
167
|
## Without Custom Domains
|
|
@@ -141,6 +175,32 @@ If you enable `cms` and `account` without custom domains, everything is served o
|
|
|
141
175
|
|
|
142
176
|
This is the simplest setup — no DNS configuration needed, no cross-subdomain cookies. Auth cookies work naturally because everything is same-origin.
|
|
143
177
|
|
|
178
|
+
## Preview Deploys
|
|
179
|
+
|
|
180
|
+
The same compiled bundle can be deployed to additional hostnames — preview environments, staging, per-PR URLs — without recompiling. Set the `EXTRA_APP_HOSTS` env var on the deploy target (a comma-separated list of hostnames) and the worker treats each one like an entry in `apps[*].domain`:
|
|
181
|
+
|
|
182
|
+
- Apps hostname middleware serves the SPA at root.
|
|
183
|
+
- CORS / Better Auth `trustedOrigins` trusts requests whose `Origin` hostname matches.
|
|
184
|
+
|
|
185
|
+
Empty or unset means no extension and zero behavior change for production.
|
|
186
|
+
|
|
187
|
+
```toml title="wrangler.preview.toml"
|
|
188
|
+
[vars]
|
|
189
|
+
EXTRA_APP_HOSTS = "app-preview.example.com,pr-42.example.com"
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
# Or set as a secret per deploy target
|
|
194
|
+
wrangler secret put EXTRA_APP_HOSTS --env preview
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends both the apps allowlist and the CORS allowlist.
|
|
198
|
+
|
|
199
|
+
> **Multi-app deploys**
|
|
200
|
+
>
|
|
201
|
+
> When more than one app is hostname-mounted, extras attach to the first registered apps middleware (Hono runs middleware in registration order and terminates on first match). If you need extras to route to a specific app in a multi-app deploy, set `apps[*].domain` directly and recompile rather than using this env var.
|
|
202
|
+
|
|
203
|
+
|
|
144
204
|
## See Also
|
|
145
205
|
|
|
146
206
|
- [Configuration](/compiler/config) — CMS and Account config options
|
|
@@ -212,6 +212,77 @@ export default defineConfig({
|
|
|
212
212
|
|
|
213
213
|
If `signature.required: true` and no key is available, compilation fails with a clear error message (or warning in `failMode: "warn"`).
|
|
214
214
|
|
|
215
|
+
## Hostname architecture (v0.33+)
|
|
216
|
+
|
|
217
|
+
A modern Quickback project runs on **one Cloudflare Worker** that serves multiple URL surfaces. By default, everything lives under a single unified backend hostname (auto-inferred as `quickback.{baseDomain}` from your other configured subdomains, or overridable via `config.domain`). For larger deployments, you can opt-in to **dedicated hostnames** for specific surfaces — they're additive aliases, never replacements.
|
|
218
|
+
|
|
219
|
+
### The unified backend contract
|
|
220
|
+
|
|
221
|
+
When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
|
|
222
|
+
|
|
223
|
+
- `/api/v1/*` — feature routes
|
|
224
|
+
- `/auth/v1/*` — Better Auth
|
|
225
|
+
- `/storage/*` — R2 file storage
|
|
226
|
+
- `/health`, `/openapi.json` — monitoring/discovery
|
|
227
|
+
- `/account/*`, `/cms/*` — bundled SPAs (when enabled)
|
|
228
|
+
- `/broadcast/v1/*` (realtime), `/mcp` (MCP), etc.
|
|
229
|
+
|
|
230
|
+
The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
|
|
231
|
+
|
|
232
|
+
This contract is forward-pointing: it gives a stable URL pattern for future management tooling — `https://quickback.{baseDomain}/...` will always reach a Quickback backend regardless of how the operator splits their surfaces.
|
|
233
|
+
|
|
234
|
+
### Dedicated hostnames (optional, additive)
|
|
235
|
+
|
|
236
|
+
For branding or operational separation, you can opt specific surfaces onto their own hostnames:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
{
|
|
240
|
+
// Bundled SPAs on their own hosts (already-shipped pattern):
|
|
241
|
+
cms: { domain: 'cms.example.com' },
|
|
242
|
+
account: { domain: 'account.example.com' },
|
|
243
|
+
|
|
244
|
+
// v0.33+ — backend surfaces on their own hosts:
|
|
245
|
+
auth: { domain: 'auth.example.com' },
|
|
246
|
+
api: { domain: 'api.example.com' },
|
|
247
|
+
|
|
248
|
+
// User SPAs (existing pattern):
|
|
249
|
+
apps: {
|
|
250
|
+
www: { domain: 'app.example.com' },
|
|
251
|
+
},
|
|
252
|
+
}
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
On a dedicated hostname, **the hostname IS the namespace** — the path drops the prefix that matches the hostname:
|
|
256
|
+
|
|
257
|
+
| URL on dedicated host | Internally rewritten to | Notes |
|
|
258
|
+
|---|---|---|
|
|
259
|
+
| `https://api.example.com/v1/users` | `/api/v1/users` | Worker-entry rewriter prepends `/api` |
|
|
260
|
+
| `https://auth.example.com/v1/sign-in/email` | `/auth/v1/sign-in/email` | Same shape with `/auth` |
|
|
261
|
+
| `https://api.example.com/api/v1/users` | (unchanged) | Long form also accepted |
|
|
262
|
+
| `https://api.example.com/auth/v1/sign-in` | **404** | Auth doesn't live on the API hostname |
|
|
263
|
+
| `https://api.example.com/health` | (unchanged) | Explicit exception — monitoring agents expect `/health` everywhere |
|
|
264
|
+
|
|
265
|
+
Dual-reach is preserved on the unified host:
|
|
266
|
+
|
|
267
|
+
| URL on unified host | Handler | Notes |
|
|
268
|
+
|---|---|---|
|
|
269
|
+
| `https://quickback.example.com/api/v1/users` | feature route | Works whether `api.domain` is set or not |
|
|
270
|
+
| `https://quickback.example.com/auth/v1/sign-in/email` | Better Auth | Works whether `auth.domain` is set or not |
|
|
271
|
+
| `https://quickback.example.com/v1/users` | **404** | Shortcut only applies on dedicated hostnames |
|
|
272
|
+
|
|
273
|
+
Each dedicated hostname also:
|
|
274
|
+
|
|
275
|
+
- Gets a `{ pattern, custom_domain: true }` route in `wrangler.toml` automatically
|
|
276
|
+
- Joins `trustedOrigins` for CORS
|
|
277
|
+
- Joins the cross-subdomain cookie inference (auto-enables `crossSubDomainCookies` when ≥2 same-parent subdomains are configured, so `auth.example.com` and `app.example.com` can share session cookies)
|
|
278
|
+
- Joins CSP `connect-src` so SPAs can fetch from it
|
|
279
|
+
|
|
280
|
+
### Why two URL shapes (Shape 1 vs Shape 2)
|
|
281
|
+
|
|
282
|
+
If you only want Better Auth to **advertise** itself on a different URL (e.g. so verification emails link to `auth.example.com` instead of the unified host), set the `BETTER_AUTH_URL` env var on the Worker — no code change required. BA generates outgoing URLs against that value. This is sufficient when the goal is branding email/OAuth callback URLs without changing where requests actually land.
|
|
283
|
+
|
|
284
|
+
`auth.domain` (Shape 1, above) is the heavier option: it binds an actual hostname to the Worker, configures CORS/cookies/CSP for it, and adds the path-shortcut rewriter. Use it when you want the dedicated hostname as a real ingress, not just a label.
|
|
285
|
+
|
|
215
286
|
## CMS Configuration
|
|
216
287
|
|
|
217
288
|
Embed the [Quickback CMS](/stack/cms) in your compiled Worker. The CMS reads your schema registry and renders a complete admin interface — zero UI code per table.
|
|
@@ -234,7 +305,7 @@ cms: { domain: "cms.example.com", sysadmin: true },
|
|
|
234
305
|
|--------|------|---------|-------------|
|
|
235
306
|
| `domain` | `string` | — | Custom domain for CMS. Adds a `custom_domain` route to `wrangler.toml`. |
|
|
236
307
|
| `access` | `"user" \| "admin"` | `"user"` | Controls who can access the CMS. When `"admin"`, only users with `user.role === "admin"` can enter — enforced at the Worker level (SPA shell, `/api/v1/schema`, and `custom_view` CRUD all return 403 to non-admins) and in the SPA. Also hides the CMS link in Account UI. See [CMS Connecting](/stack/cms/connecting) for the full enforcement model. |
|
|
237
|
-
| `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/
|
|
308
|
+
| `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/auth/v1/admin/list-organizations` endpoint (sibling of Better Auth's `/auth/v1/admin/list-users`, gated to sysadmin only), and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"admin"`. Off by default. See [`SYSADMIN` pseudo-role](/compiler/definitions/access#sysadmin--cross-tenant-db-admin-tier). |
|
|
238
309
|
|
|
239
310
|
### Sysadmin tier (`cms.sysadmin: true`)
|
|
240
311
|
|
|
@@ -242,9 +313,9 @@ Quickback's default model assumes every CMS user belongs to at least one organiz
|
|
|
242
313
|
|
|
243
314
|
`cms: { sysadmin: true }` introduces a separate role tier:
|
|
244
315
|
|
|
245
|
-
- **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"admin"` — admins keep org-scoped CMS access via the membership switcher; sysadmins get cross-tenant.
|
|
316
|
+
- **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"admin"` — admins keep org-scoped CMS access via the membership switcher; sysadmins get cross-tenant. The two roles are independent at the pseudo-role evaluator level: `ADMIN` admits `'admin'` only, `SYSADMIN` admits `'sysadmin'` only. Routes that need both write `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly.
|
|
246
317
|
- **Firewall**: every `buildFirewallConditions()` emits an `if (ctx.userRole === "sysadmin") return undefined` (or just the soft-delete predicate when present) at the top, so sysadmins see every tenant's rows. See [Firewall escape hatch](/compiler/definitions/firewall#sysadmin-escape-hatch).
|
|
247
|
-
- **Org listing**: a
|
|
318
|
+
- **Org listing**: a `GET /auth/v1/admin/list-organizations` endpoint selects directly from the auth-schema `organization` table — every row, every tenant. Sits under Better Auth's admin URL namespace (sibling of `/auth/v1/admin/list-users`) so the URL shape matches BA convention; the handler is Quickback-emitted and gated to `user.role === "sysadmin"` only. For the membership-bound caller's-orgs listing, use BA's own `/auth/v1/organization/list`.
|
|
248
319
|
- **CMS SPA**: when the user is a sysadmin, the header switcher loads from the cross-tenant endpoint, defaults to "All organizations" (which omits `?organizationId=` and reaches the firewall escape), and pins selected tenants via `?organizationId=` on every API call. Org admins keep the existing membership-based switcher.
|
|
249
320
|
- **CMS HTML gate**: admits `userRole === "sysadmin"` alongside `"admin"`. Org admins are not locked out — both roles can enter the CMS in `cms.access: "admin"` mode.
|
|
250
321
|
|
|
@@ -353,7 +353,7 @@ Notes:
|
|
|
353
353
|
|
|
354
354
|
### Source Apps (`quickback/apps/`)
|
|
355
355
|
|
|
356
|
-
For hand-authored TypeScript apps that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing.
|
|
356
|
+
For hand-authored TypeScript apps and prebuilt SPA bundles that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing. Bind a directory to a hostname via [`config.apps`](/compiler/config/domains#app-domains) — the compiler emits the matching Worker middleware automatically.
|
|
357
357
|
|
|
358
358
|
```
|
|
359
359
|
quickback/apps/ # Source — checked into your repo
|
|
@@ -4,11 +4,7 @@ Providers configure which services your compiled backend targets.
|
|
|
4
4
|
|
|
5
5
|
## Runtime Providers
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|----------|-------------|
|
|
9
|
-
| `cloudflare` | Cloudflare Workers (Hono) |
|
|
10
|
-
| `bun` | Bun runtime (Hono) |
|
|
11
|
-
| `node` | Node.js runtime (Hono) |
|
|
7
|
+
The Quickback Stack is **Cloudflare-only**. `cloudflare` is the single supported runtime.
|
|
12
8
|
|
|
13
9
|
```typescript
|
|
14
10
|
import { defineRuntime } from "@quickback/compiler";
|
|
@@ -63,13 +59,12 @@ providers: {
|
|
|
63
59
|
|
|
64
60
|
## Database Providers
|
|
65
61
|
|
|
62
|
+
Two databases are supported, both Cloudflare-native:
|
|
63
|
+
|
|
66
64
|
| Provider | Description |
|
|
67
65
|
|----------|-------------|
|
|
68
|
-
| `cloudflare-d1` | Cloudflare D1 (SQLite) |
|
|
69
|
-
| `
|
|
70
|
-
| `libsql` | LibSQL / Turso |
|
|
71
|
-
| `neon` | Neon (PostgreSQL) |
|
|
72
|
-
| `supabase` | Supabase (PostgreSQL) |
|
|
66
|
+
| `cloudflare-d1` | Cloudflare D1 (SQLite at the edge) |
|
|
67
|
+
| `neon` | Neon (PostgreSQL over Hyperdrive) |
|
|
73
68
|
|
|
74
69
|
```typescript
|
|
75
70
|
import { defineDatabase } from "@quickback/compiler";
|
|
@@ -235,8 +230,7 @@ See [Realtime](/stack/realtime) for the client-side connection flow and helper e
|
|
|
235
230
|
|
|
236
231
|
| Provider | Description |
|
|
237
232
|
|----------|-------------|
|
|
238
|
-
| `better-auth` | Better Auth with plugins |
|
|
239
|
-
| `supabase-auth` | Supabase Auth |
|
|
233
|
+
| `better-auth` | Better Auth with plugins (default) |
|
|
240
234
|
| `external` | External auth via Cloudflare service binding |
|
|
241
235
|
|
|
242
236
|
```typescript
|
|
@@ -31,7 +31,7 @@ export default defineConfig({
|
|
|
31
31
|
| `organizationId` columns | Required on resources | Not used |
|
|
32
32
|
| Role source | Org membership table | `user.role` field |
|
|
33
33
|
| Firewall scopes | `owner`, `organization`, `team`, `exception` | `owner`, `exception` only |
|
|
34
|
-
| Admin org endpoints | `/
|
|
34
|
+
| Admin org endpoints | Use Better Auth's `/auth/v1/organization/list` (caller's orgs) and `/auth/v1/admin/list-organizations` when `cms.sysadmin: true` (cross-tenant) | N/A (no org plugin) |
|
|
35
35
|
| `ctx.activeOrgId` | From session/JWT | Always `undefined` |
|
|
36
36
|
| `ctx.roles` | From org member role | From `user.role` |
|
|
37
37
|
|
|
@@ -107,36 +107,6 @@ For running remote migrations with `drizzle-kit`, set these in `.env`:
|
|
|
107
107
|
| `CLOUDFLARE_AUDIT_DATABASE_ID` | Security audit D1 database ID (unsafe cross-tenant actions) |
|
|
108
108
|
| `CLOUDFLARE_DATABASE_ID` | Database ID (single DB mode) |
|
|
109
109
|
|
|
110
|
-
## Bun Variables
|
|
111
|
-
|
|
112
|
-
Set these in a `.env` file in your project root:
|
|
113
|
-
|
|
114
|
-
| Variable | Description | Default |
|
|
115
|
-
|----------|-------------|---------|
|
|
116
|
-
| `NODE_ENV` | Runtime environment | `development` |
|
|
117
|
-
| `PORT` | Server port | `3000` |
|
|
118
|
-
| `BETTER_AUTH_SECRET` | Auth encryption secret | — (required) |
|
|
119
|
-
| `BETTER_AUTH_URL` | Public URL of your server | `http://localhost:3000` |
|
|
120
|
-
| `DATABASE_PATH` | Path to SQLite file | `./data/app.db` |
|
|
121
|
-
|
|
122
|
-
## Turso (LibSQL) Variables
|
|
123
|
-
|
|
124
|
-
In addition to the Bun variables above:
|
|
125
|
-
|
|
126
|
-
| Variable | Description | Default |
|
|
127
|
-
|----------|-------------|---------|
|
|
128
|
-
| `DATABASE_URL` | LibSQL connection URL | `file:./data/app.db` |
|
|
129
|
-
| `DATABASE_AUTH_TOKEN` | Turso auth token (required for remote) | — |
|
|
130
|
-
|
|
131
|
-
```bash
|
|
132
|
-
# Local development
|
|
133
|
-
DATABASE_URL=file:./data/app.db
|
|
134
|
-
|
|
135
|
-
# Production (Turso cloud)
|
|
136
|
-
DATABASE_URL=libsql://your-db-slug.turso.io
|
|
137
|
-
DATABASE_AUTH_TOKEN=eyJhbGciOi...
|
|
138
|
-
```
|
|
139
|
-
|
|
140
110
|
## Social Login Providers
|
|
141
111
|
|
|
142
112
|
When social login is configured in your auth provider:
|