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