@quickback-dev/cli 0.60.8 → 0.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/dist/docs/content.d.ts +7 -0
  2. package/dist/docs/content.d.ts.map +1 -0
  3. package/dist/docs/content.js +737 -0
  4. package/dist/docs/content.js.map +1 -0
  5. package/dist/index.js +1 -1
  6. package/dist/lib/helpers.d.ts +39 -0
  7. package/dist/lib/helpers.d.ts.map +1 -0
  8. package/dist/lib/helpers.js +299 -0
  9. package/dist/lib/helpers.js.map +1 -0
  10. package/dist/lib/wrangler-resources.d.ts +1 -1
  11. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  12. package/dist/lib/wrangler-resources.js +12 -4
  13. package/dist/lib/wrangler-resources.js.map +1 -1
  14. package/dist/skill/docs/api/errors.md +1 -0
  15. package/dist/skill/docs/api/query-params.md +26 -0
  16. package/dist/skill/docs/changelog/index.md +79 -0
  17. package/dist/skill/docs/configure/auth.md +17 -12
  18. package/dist/skill/docs/configure/bindings.md +27 -0
  19. package/dist/skill/docs/configure/domains.md +1 -1
  20. package/dist/skill/docs/configure/index.md +5 -5
  21. package/dist/skill/docs/define/actions/index.md +18 -0
  22. package/dist/skill/docs/define/areas.md +90 -7
  23. package/dist/skill/docs/define/feature.md +88 -27
  24. package/dist/skill/docs/define/fga.md +10 -2
  25. package/dist/skill/docs/define/index.md +7 -1
  26. package/dist/skill/docs/define/scopes.md +1 -1
  27. package/dist/skill/docs/define/security.md +10 -0
  28. package/dist/skill/docs/define/transitions.md +11 -35
  29. package/dist/skill/docs/platform/auth/jwt-optimization.md +15 -3
  30. package/dist/skill/docs/platform/database/d1.md +17 -2
  31. package/dist/skill/docs/platform/database/neon.md +7 -0
  32. package/dist/skill/docs/platform/realtime/index.md +17 -0
  33. package/dist/skill/docs/platform/webhooks/outbound.md +31 -6
  34. package/dist/skill/docs/start/deploy-browser.md +36 -7
  35. package/dist/skill/docs/start/deploy-owner-access.md +11 -0
  36. package/dist/skill/docs/start/first-api.md +16 -0
  37. package/dist/skill/docs/ui/account/features/admin.md +29 -5
  38. package/dist/skill/docs/ui/account/features/index.md +22 -0
  39. package/dist/skill/docs/ui/admin/connecting.md +6 -4
  40. package/dist/skill/docs/ui/admin/index.md +49 -10
  41. package/dist/skill/docs/ui/admin/security.md +6 -7
  42. package/package.json +1 -1
  43. package/src/skill/docs/api/errors.md +1 -0
  44. package/src/skill/docs/api/query-params.md +26 -0
  45. package/src/skill/docs/changelog/index.md +79 -0
  46. package/src/skill/docs/configure/auth.md +17 -12
  47. package/src/skill/docs/configure/bindings.md +27 -0
  48. package/src/skill/docs/configure/domains.md +1 -1
  49. package/src/skill/docs/configure/index.md +5 -5
  50. package/src/skill/docs/define/actions/index.md +18 -0
  51. package/src/skill/docs/define/areas.md +90 -7
  52. package/src/skill/docs/define/feature.md +88 -27
  53. package/src/skill/docs/define/fga.md +10 -2
  54. package/src/skill/docs/define/index.md +7 -1
  55. package/src/skill/docs/define/scopes.md +1 -1
  56. package/src/skill/docs/define/security.md +10 -0
  57. package/src/skill/docs/define/transitions.md +11 -35
  58. package/src/skill/docs/platform/auth/jwt-optimization.md +15 -3
  59. package/src/skill/docs/platform/database/d1.md +17 -2
  60. package/src/skill/docs/platform/database/neon.md +7 -0
  61. package/src/skill/docs/platform/realtime/index.md +17 -0
  62. package/src/skill/docs/platform/webhooks/outbound.md +31 -6
  63. package/src/skill/docs/start/deploy-browser.md +36 -7
  64. package/src/skill/docs/start/deploy-owner-access.md +11 -0
  65. package/src/skill/docs/start/first-api.md +16 -0
  66. package/src/skill/docs/ui/account/features/admin.md +29 -5
  67. package/src/skill/docs/ui/account/features/index.md +22 -0
  68. package/src/skill/docs/ui/admin/connecting.md +6 -4
  69. package/src/skill/docs/ui/admin/index.md +49 -10
  70. package/src/skill/docs/ui/admin/security.md +6 -7
@@ -273,6 +273,9 @@ Beyond the five security layers, `defineTable` accepts a handful of declarative
273
273
  | Option | What it does | Full reference |
274
274
  |---|---|---|
275
275
  | `views` | Named column projections — `GET /resource/views/{name}` returns a subset of columns under its own access rule. | [Views](/define/views) |
276
+ | `transitions` | Guarded state changes — each entry generates a real `POST /resource/:id/{name}` action file, with guards, stamps, idempotency, `undo` inverses, and `onEnter` cascades. | [Transitions](/define/transitions) |
277
+ | `changesets` | An `owns` boundary — write the parent row and its owned relations in one atomic request, each op paying the child's own firewall, access, and guards. | [Changesets](/define/changesets) |
278
+ | `triggers` | `before`/`after` hooks on `insert`/`update`/`delete`, lowering either to a real SQL trigger in your migrations or to an application handler at the write chokepoint. | [Triggers](/define/triggers) |
276
279
  | `references` | Explicit FK target table for columns that don't follow the "Id"-stripped convention (e.g. `vendorId → contact`). | [CMS Schema Registry](/ui/admin/schema-registry) |
277
280
  | `displayColumn` | Column to use as the human-readable label in FK resolutions and CMS list views (auto-detected as `name`/`title`/`label` if not set). | [CMS Table Views](/ui/admin/table-views) |
278
281
  | `defaultSort` | Default sort order for CMS list rendering (`{ field, order: "asc" \| "desc" }`). | [CMS Table Views](/ui/admin/table-views) |
@@ -294,4 +297,7 @@ All options are optional — omit them and Quickback uses sensible defaults (aut
294
297
  6. [Rate Limit](/define/rate-limit) — Per-operation request caps
295
298
  7. [Views](/define/views) — Column-level security
296
299
  8. [Validation](/define/validation) — Field validation rules
297
- 9. [Actions](/define/actions) — Add custom business logic
300
+ 9. [Transitions](/define/transitions) — Guarded state changes, generated as real endpoints
301
+ 10. [Changesets](/define/changesets) — Atomic parent-plus-owned-relations writes
302
+ 11. [Triggers](/define/triggers) — Data rules and side-effects on write
303
+ 12. [Actions](/define/actions) — Custom business logic, for what the above can't express
@@ -635,7 +635,7 @@ The scope claim is trusted between proofs — it is never re-checked against the
635
635
 
636
636
  So removing a guest/staff row takes effect within **cap + one TTL** for a client that keeps polling, and within one TTL once it goes idle. Two ways to tighten that:
637
637
 
638
- - **`auth.jwt.revocationCheck: 'kv'`** (v0.45+, Cloudflare runtime) — sub-TTL revocation: updating or deleting a conferring relationship row stamps a revocation timestamp in KV, and the bearer fast-path rejects a carried scope claim whose proof (`sct`) predates it. See [auth config](/configure/auth).
638
+ - **`auth.jwt.revocationCheck: 'kv'`** (v0.45+, Cloudflare runtime) — sub-TTL revocation: updating or deleting a conferring relationship row stamps a revocation timestamp in KV, and the bearer fast-path rejects a carried scope claim whose proof (`sct`, with its millisecond companion `sctMs`) is at or before it — no same-second gap. Both halves of the proof time are carried forward verbatim by the rolling refresh; a refresh never substitutes its own mint time for proof time. The check fails closed — a scope claim whose revocation state can't be read is not trusted either. See [auth config](/configure/auth).
639
639
  - **`via` arms** — for tables where any caching is too wide, gate with a `via` arm instead of a bare `ctx.scope.<kind>` arm: `via` emits a live subquery against the relationship table on every request, immune to a stale claim entirely.
640
640
 
641
641
  ## Reference
@@ -94,6 +94,16 @@ omitted from the generated request schemas entirely, so a client cannot even sen
94
94
  caller's role. Use it for data the caller may legitimately address but should not read
95
95
  in full.
96
96
 
97
+ **State changes** — `protected: { status: ["publish", "cancel", "refund"] }` removes the
98
+ column from the PATCH schema and names the only doors to it. Each name is an action:
99
+ either a [transition](/define/transitions) the compiler generates from
100
+ `transitions: { publish: { field: "status", from: "draft", to: "live", access: {...} } }`,
101
+ or an [action file](/define/actions) you write when the change needs real logic — a
102
+ `refund` that calls Stripe, then sets the column. Both carry their own `access` rule and
103
+ appear in OpenAPI; the transition additionally gets row guards, stamps, and an `undo`
104
+ inverse for free. Declare the transition when the change is state plus stamps; write the
105
+ action when it is genuinely imperative. Either beats leaving the column freely writable.
106
+
97
107
  ## Advanced authorization
98
108
 
99
109
  When roles are not enough — when access depends on a *relationship* between the caller
@@ -3,43 +3,19 @@
3
3
  ## Overview
4
4
 
5
5
  Most state changes follow the same shape: check the row is in a legal state,
6
- flip a column, stamp who/when, maybe cascade. Before transitions v2 every one
7
- of those was a hand-written action file — a podcast app had **ten files that
8
- were byte-identical except the table name** (`publish.ts` / `revertToDraft.ts`
9
- across five entities), and an events app had eight near-identical
10
- check-in/check-out files.
6
+ flip a column, stamp who/when, maybe cascade. Declare that shape on the table
7
+ and the compiler generates the action files — including `undo` inverses and
8
+ `onEnter` cascades.
11
9
 
12
- Transitions v2 collapses both patterns:
10
+ Two declaration sites:
13
11
 
14
- - **Action-level extensions** on `defineAction({ transition })` — guards,
15
- stamps, idempotency, compiler-applied writes.
16
- - **Table-level `transitions`** on `defineTable` — the compiler *generates*
17
- the action files, including `undo` inverses and `onEnter` cascades.
12
+ - **Table-level `transitions`** on `defineTable` — the compiler generates the
13
+ actions. Start here.
14
+ - **Action-level `transition`** on `defineAction` — the same guards, stamps,
15
+ idempotency, and compiler-applied writes, for an action you are writing
16
+ anyway.
18
17
 
19
- ## The marquee example: 10 files → 2 lines each
20
-
21
- Before (×10 files across episodes/shows/seasons/collections/profiles):
22
-
23
- ```typescript
24
- // actions/episodes/publish.ts — and nine siblings like it
25
- import { z } from "zod";
26
- import { eq } from "drizzle-orm";
27
- import { defineAction, episodes } from "../../.quickback/define-action.episodes";
28
-
29
- export default defineAction({
30
- description: "Publish an episode",
31
- input: z.object({}),
32
- access: { roles: ["admin+"] },
33
- async execute({ db, record }) {
34
- const [updated] = await db.update(episodes)
35
- .set({ isPublished: true })
36
- .where(eq(episodes.id, record.id)).returning();
37
- return updated;
38
- },
39
- });
40
- ```
41
-
42
- After — on each entity's `defineTable`:
18
+ ## Two lines per state change
43
19
 
44
20
  ```typescript
45
21
  // features/podcast/episodes.ts
@@ -62,7 +38,7 @@ export default defineTable(episodes, {
62
38
  });
63
39
  ```
64
40
 
65
- The generated actions mount exactly where the hand-written files did
41
+ The generated actions mount exactly where an authored file would
66
42
  (`POST /episodes/:id/publish`, operationId `episodesPublish`, same MCP tool
67
43
  name), ride the same OpenAPI/security-contract pipeline, and delete cleanly:
68
44
  **an explicit `actions/<name>.ts` file always wins** (the compiler warns about
@@ -27,9 +27,12 @@ The JWT encodes everything needed for auth middleware:
27
27
  | `userRole` | Global user role (when admin panel is enabled) |
28
28
  | `email` | User email |
29
29
  | `name` | User display name |
30
- | `iat` | Issued-at timestamp |
30
+ | `iat` | Issued-at timestamp (unix **seconds**, the standard claim) |
31
+ | `iatMs` | Issued-at in epoch **milliseconds** — Quickback ordering metadata, not a standard claim. Same clock sample as `iat`, set by the signer only. Lets [revocation](#revocation--revocationcheck-kv) order a token against a marker written in the same second |
31
32
  | `exp` | Expiry — **180 seconds** (3 minutes) after `iat` by default; set via [`auth.jwt.expiresIn`](/configure/auth) |
32
33
 
34
+ Scope-bearing tokens also carry `sct` (proof timestamp, unix seconds) and its millisecond companion `sctMs` — see [Scopes](/define/scopes). Read `iat` / `sct` from external tooling; `iatMs` / `sctMs` exist only so revocation can break ties inside a second.
35
+
33
36
  ### Signing
34
37
 
35
38
  JWTs are signed with HMAC-SHA256 using your `BETTER_AUTH_SECRET` — the same secret you already set for Better Auth, so there is only one secret to manage.
@@ -113,7 +116,9 @@ auth: {
113
116
  },
114
117
  ```
115
118
 
116
- The fast-path then consults per-principal revocation timestamps in your project's existing `KV` binding (keys prefixed `qbrev:`, self-expiring) *before* trusting a token. A token is rejected when its mint timestamp (`iat`, or `sct` for the scope claim) predates the stored timestamp. Cost: 2+ edge-cached KV reads per bearer verify.
119
+ The fast-path then consults per-principal revocation timestamps in your project's existing `KV` binding (keys prefixed `qbrev:`, self-expiring) *before* trusting a token. A token is rejected when its mint timestamp (`iat`/`iatMs`, or `sct`/`sctMs` for the scope claim) is **at or before** the stored timestamp. Cost: 2+ edge-cached KV reads per bearer verify.
120
+
121
+ There is no same-second gap: markers are epoch milliseconds (written `m<ms>`, v0.61.0+), tokens carry millisecond companions, and the comparison denies a tie — so a token minted a few milliseconds *before* the revocation is rejected, while one legitimately re-minted *after* it in that same second is still accepted. Pre-v0.61.0 workers don't understand that marker format and read it as "not revoked" — don't roll back across the upgrade or share one KV namespace between versions; see [`revocationCheck`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy).
117
122
 
118
123
  Revocation stamps are written **automatically** on:
119
124
 
@@ -125,7 +130,14 @@ The generated `src/lib/jwt-revocation.ts` exports `revokeUserTokens`, `revokeMem
125
130
 
126
131
  > **Honest limits**
127
132
  >
128
- > The KV check revokes **per principal**, not per session; it **fails open** if KV is unreachable (degrading to the TTL bound rather than locking bearers out); and stamps propagate cross-PoP in roughly 60 seconds. A rejected token falls through to session auth, which re-checks membership and re-mints — an active legitimate session recovers transparently. For fail-closed semantics, use `expiresIn: 30` instead.
133
+ > The KV check revokes **per principal**, not per session, and stamps propagate cross-PoP in roughly 60 seconds — "immediate" means seconds, not instantaneous.
134
+ >
135
+ > It **fails closed** for bearer auth: if the KV binding is missing or the read fails, the bearer is *not* authenticated — a signature is all that is known about it — and the caller gets a retryable **`503 AUTH_REVOCATION_UNAVAILABLE`**. Recovery is a **separate cookie-only request**, not a fallback inside the same one: a request carrying `Authorization` has its cookie stripped before session auth (bearer is an alternative to the cookie, not a supplement), so during a KV outage every JWT-bearer request gets the 503 until the client retries on its session cookie. A *revoked* token behaves the same way, and a cookie request re-checks membership and re-mints transparently.
136
+
137
+
138
+ > **Operational consequence**
139
+ >
140
+ > Enabling `revocationCheck: 'kv'` ties bearer-token availability to KV. Alert on `AUTH_REVOCATION_UNAVAILABLE` — a sustained rate means the binding is gone (check that every deployment target declares it) or KV itself is degraded. If you want the TTL bound *without* that coupling, leave `revocationCheck` at `'none'` and set `expiresIn: 30`.
129
141
 
130
142
 
131
143
  Full knob-by-knob reference: [Auth & JWT config → `revocationCheck`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy).
@@ -164,8 +164,9 @@ export default defineConfig({
164
164
  },
165
165
  environments: {
166
166
  dev: {
167
+ // The Wrangler worker name. Required — never derived (see below).
168
+ name: "my-app-dev",
167
169
  domain: "api-dev.example.com",
168
- // `name` is optional — defaults to `${config.name}-${key}` ("my-app-dev")
169
170
  worker: {
170
171
  env: "dev",
171
172
  workersDev: true,
@@ -181,6 +182,8 @@ export default defineConfig({
181
182
  },
182
183
  },
183
184
  production: {
185
+ // An EXISTING project must restate the name it already deploys under.
186
+ name: "my-app",
184
187
  domain: "api.example.com",
185
188
  worker: {
186
189
  env: "production",
@@ -251,14 +254,26 @@ target:
251
254
  npm run deploy:dev # wrangler deploy --env dev
252
255
  npm run deploy:production # wrangler deploy --env production
253
256
 
254
- npm run db:migrate:dev:auth:remote # wrangler d1 migrations apply my-app-auth-dev --remote
257
+ npm run db:migrate:dev:auth:remote # …apply my-app-auth-dev --remote --env dev
255
258
  npm run db:migrate:dev:remote # fan-out over every declared role
256
259
  ```
257
260
 
261
+ Every migration script carries `--env`. With the top-level blocks suppressed,
262
+ a bare database name has no scope to resolve in and wrangler fails with
263
+ `Couldn't find a D1 DB with the name or binding '<name>'` — so a hand-run
264
+ `wrangler d1 migrations apply` needs the flag too.
265
+
258
266
  The contract fails closed:
259
267
 
260
268
  - Better Auth is required, and a logical `dev` target must exist (it is what
261
269
  `npm run dev` selects).
270
+ - Every target declares its own `name` — the Wrangler worker name — and no two
271
+ share one. Nothing is derived. The name is the deployed script's identity:
272
+ Durable Object namespaces and the `[[migrations]]` ledger belong to it, so a
273
+ derived default would let an existing project adopt `environments` and
274
+ silently deploy production as a *new* script, with every Durable Object
275
+ starting empty. **Migrating an existing project? Set the production target's
276
+ `name` to the name you already deploy under.**
262
277
  - Every D1 role the primary config declares — `auth`, `features`, plus `audit`,
263
278
  `webhooks`, and `files` when enabled — needs its own `databaseId` per
264
279
  environment. A missing role is a compile error, not a Worker that boots
@@ -112,6 +112,8 @@ export default defineConfig({
112
112
  },
113
113
  environments: {
114
114
  dev: {
115
+ // Wrangler worker name — required on every target, never derived.
116
+ name: "attend-v2-dev",
115
117
  branch: "dev",
116
118
  worker: {
117
119
  env: "dev",
@@ -140,6 +142,7 @@ export default defineConfig({
140
142
  },
141
143
  },
142
144
  prod: {
145
+ name: "attend-v2",
143
146
  branch: "production",
144
147
  worker: {
145
148
  env: "prod",
@@ -181,6 +184,10 @@ placeholder state.
181
184
  The environment contract is intentionally exact and fails closed:
182
185
 
183
186
  - `workersDev: true` and `previewUrls: false` must be explicit for each target.
187
+ - Each target declares its own `name` (the Wrangler worker name) and no two
188
+ share one. It is the deployed script's identity — Durable Object state and
189
+ the migration ledger belong to it — so it is never derived. An existing
190
+ project must restate the name it already deploys under.
184
191
  - The auth provider must currently be Better Auth. External auth needs a
185
192
  non-inheritable service binding, so it remains rejected until named targets
186
193
  can require an explicit per-environment service-binding override.
@@ -90,6 +90,23 @@ export default feature("applications", {
90
90
  > `access.roles` — it still compiles but should be migrated.)
91
91
 
92
92
 
93
+ Omitting it fails the compile:
94
+
95
+ ```text
96
+ Resource "conversations" enables realtime broadcasts but declares no audience.
97
+ A broadcast fans out to every subscriber in the room, so the audience is not
98
+ optional. Declare realtime.access: { roles: [...] } naming who may receive it
99
+ (use roles: ['PUBLIC'] to broadcast to everyone in the room, deliberately).
100
+ ```
101
+
102
+ **The audience is a second read surface, and it does not inherit `read.access`.**
103
+ Whatever gates the REST read must gate the broadcast too, or the live channel
104
+ publishes rows the REST route would have withheld — private messages being the
105
+ usual casualty. Copy the read rule across, and where the read is gated by a
106
+ relationship (participants of a conversation, accepted followers), use
107
+ `access: { authzRole: "<relationship-role>" }` here rather than falling back to
108
+ `roles: ["AUTHENTICATED"]`, which reaches every signed-in subscriber.
109
+
93
110
  And enable the realtime **transport** in your database config. This is a
94
111
  project-level switch that stands up the Broadcaster Durable Object + the
95
112
  connection route; it does **not** by itself make any resource broadcast
@@ -170,13 +170,38 @@ Endpoints are scoped by `userId` or `organizationId`. Users can only manage thei
170
170
 
171
171
  ### URL Validation (anti-SSRF)
172
172
 
173
- Registered URLs are validated at registration and again before each delivery attempt. The default policy rejects:
173
+ The destination policy lives in `src/lib/webhooks/url-policy.ts` and runs at **four** points: on register, on update, and again immediately before **each** test send and **each** queued delivery attempt. Re-checking before every send is the point — a name that was public when it was registered can be re-pointed afterwards.
174
+
175
+ The default policy rejects:
174
176
 
175
177
  - Any scheme other than `https:` (matches Stripe, GitHub, and Slack webhook conventions)
176
- - Loopback hosts (`localhost`, `127.0.0.1`, `::1`)
177
- - Cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`)
178
- - RFC 1918 private ranges (`10/8`, `172.16/12`, `192.168/16`), `169.254/16`, and `0.0.0.0/8`
179
- - Hosts ending in `.internal` or `.local`
178
+ - URLs carrying credentials (`https://user:pass@host/`)
179
+ - Loopback, private, and reserved **IPv4** literals: `0/8`, `10/8`, `100.64/10` (CGNAT), `127/8`, `169.254/16` (link-local + cloud metadata), `172.16/12`, `192.0.0/24`, `192.0.2/24`, `192.88.99/24`, `192.168/16`, `198.18/15`, `198.51.100/24`, `203.0.113/24`, `224/4` (multicast), `240/4` (reserved), and the broadcast address — in any notation the URL parser accepts, including octal and decimal
180
+ - The equivalent **IPv6** literals: `::`, `::1`, unique-local `fc00::/7`, link-local `fe80::/10`, site-local `fec0::/10`, multicast `ff00::/8`, documentation `2001:db8::/32` and `3fff::/20`, `2001::/23` (Teredo), `2002::/16` (6to4), `64:ff9b::/96` (NAT64), `100::/64`, and IPv4-mapped forms such as `[::ffff:127.0.0.1]`
181
+ - Internal names: `localhost`, `metadata.goog`, anything ending in `.localhost`, `.local`, `.internal`, or `.home.arpa`, and any single-label host (`http://intranet/`)
182
+
183
+ > **Host names are resolved, not just pattern-matched.** For any name that survives the checks above, the runtime resolves both **A and AAAA** records and rejects the destination if **any** answer is a non-public address. One private record among several public ones is enough to refuse the whole name — that is the case a literal-only check misses.
184
+
185
+
186
+ Resolution is fail-closed. If the resolver errors, times out, returns a malformed answer, or is unavailable, the destination is **not** contacted:
187
+
188
+ | Outcome | Register / update | Queued delivery |
189
+ |---------|-------------------|-----------------|
190
+ | All answers public | Accepted | Delivered |
191
+ | Any answer non-public | `400` | Terminal failure, no retry |
192
+ | No A/AAAA records (NXDOMAIN) | `400` | Terminal failure, no retry |
193
+ | Resolver error, timeout, or malformed answer | `503` | Failed **attempt**, retried with backoff |
194
+ | Answer larger than 32 records | `503` | Failed **attempt**, retried with backoff |
195
+
196
+ DNS is always resolved through a fixed trusted resolver — an endpoint never gets to nominate who answers for it. An answer of more than 32 records is refused rather than truncated: silently cutting the list would let a zone owner pad it with public records and hide a private one past the cut.
197
+
198
+ > **A resolver outage fails deliveries permanently, and it fails them all at once.** The three retries above elapse in seconds, so a DNS outage lasting longer than that exhausts them and marks every in-flight delivery `failed` — across every endpoint and every project on the same resolver. There is no outbound replay endpoint (`/webhooks/v1/inbound/events/:id/retry` covers inbound events only), so those deliveries are not recoverable; the source event has to be re-emitted.
199
+ >
200
+ > This is the deliberate cost of fail-closed: the runtime will not contact a destination it could not verify. It also means outbound webhook failures are **correlated** — a shared dependency, not independent per-endpoint faults. Alert on a spike in `failed` deliveries rather than on any single endpoint.
201
+
202
+
203
+ > **This validates the DNS answer, not the socket.** It is not connection pinning, so a deployment that attaches private egress (a VPC, a tunnel, a service binding) must **also** enforce a network-layer egress policy. Application-level DNS validation cannot close the gap between the answer it checked and the address the runtime later connects to.
204
+
180
205
 
181
206
  Plaintext `http:` is rejected by default. To allow `http:` (e.g. for a self-hosted dev environment without TLS), set `webhookAllowInsecure: true` on the database provider config:
182
207
 
@@ -193,7 +218,7 @@ providers: {
193
218
  }
194
219
  ```
195
220
 
196
- The other validation rules (private/loopback/metadata blocking) still apply when this flag is on.
221
+ `webhookAllowInsecure` relaxes the **scheme and nothing else**. Every address rule above — including DNS resolution and the fail-closed behaviour — still applies when the flag is on. There is no configuration that permits a private destination.
197
222
 
198
223
  ### Redirect Handling
199
224
 
@@ -69,7 +69,12 @@ Blocked, fail-closed at the compile phase — the deploy stops with the reason,
69
69
 
70
70
  ## Connecting your Cloudflare account
71
71
 
72
- 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).
72
+ Deploying takes two distinct grants, and the card labels them differently on purpose:
73
+
74
+ - **Continue with Cloudflare** signs you in to Quickback. Identity only — none of the deploy permissions below.
75
+ - **Grant deploy access** gives Quickback permission to deploy into your Cloudflare account — 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).
76
+
77
+ One click covers both: if you weren't signed in yet, sign-in chains straight into the deploy consent. First-time users see two Cloudflare screens back to back; after that, Cloudflare skips consent screens it has already approved, so re-authenticating is a ribbon of silent redirects.
73
78
 
74
79
  What's requested, and why:
75
80
 
@@ -85,7 +90,7 @@ What's requested, and why:
85
90
 
86
91
  Nothing broader is requested — no zone, DNS, billing, or account-management access.
87
92
 
88
- If you cancel at Cloudflare's consent screen — or Cloudflare ends the attempt for any other reason — you land back in Start with the card explaining what happened and a **Try Cloudflare again** button. Nothing is stored on a cancelled attempt, and a connection you already had is left untouched.
93
+ If you cancel at Cloudflare's consent screen — or Cloudflare ends the attempt for any other reason — you land back in Start with the card explaining what happened and a **Try again** button. Nothing is stored on a cancelled attempt, and a connection you already had is left untouched.
89
94
 
90
95
  ## Connection states and recovery
91
96
 
@@ -93,10 +98,10 @@ The deploy card is the whole connection UI: it reports the state of your Cloudfl
93
98
 
94
99
  | What you see | What happened | What to do |
95
100
  |---|---|---|
96
- | **Connect your Cloudflare account** | No connection stored | **Continue with Cloudflare** |
101
+ | "Grant Quickback permission to deploy…" | Signed in, but no deploy permission stored yet | **Grant deploy access** |
97
102
  | Masked email badge, green | Connected and healthy | Deploy |
98
- | "This connection expires in N minutes" | The access token is near the end of its life | Nothing yet — reconnect when it lapses |
99
- | Badge turns amber, "· reconnect" | Token expired, grant revoked in Cloudflare, or the connection was deleted | **Reconnect Cloudflare** — one consent, same connection record |
103
+ | Badge turns amber, "· reconnect" | Grant revoked in Cloudflare, or the connection was deleted (plain expiry never surfaces — tokens refresh server-side) | **Reconnect Cloudflare** — one consent, same connection record |
104
+ | "…also linked to a different Quickback login" | This Cloudflare account is connected under another Quickback account too — apps deployed there are listed there, not here | Nothing, unless an app you expected is missing: sign in with the Quickback account you deployed it from |
100
105
  | "This Cloudflare connection can't …" | The grant is missing a permission a deploy needs (an older connection, or a scope your OAuth client didn't allow) | **Reconnect Cloudflare** to grant the rest |
101
106
  | "This Cloudflare login isn't a member of any account" | The identity you connected belongs to no Cloudflare account | Create or join an account in the Cloudflare dashboard, then reconnect |
102
107
  | "Couldn't reach the deploy service…" | Transient failure talking to Quickback or Cloudflare | **Try again** |
@@ -114,6 +119,8 @@ Deploy is disabled while a reconnect is pending, so a deploy never starts on a c
114
119
 
115
120
  Connect a second Cloudflare login with **Connect another** and the card grows a login picker above the account picker. Start remembers which one you deployed with last and preselects it.
116
121
 
122
+ To make every Cloudflare login land on the **same** Quickback account (rather than each minting its own), link them under **Connected accounts** in the [Account UI](/ui/account) — after that, "Continue with Cloudflare" signs you in to that one account no matter which Cloudflare identity your dashboard is holding.
123
+
117
124
  ### Disconnecting vs. revoking
118
125
 
119
126
  Two different things, and you usually want both:
@@ -129,7 +136,9 @@ The OAuth token never reaches your browser, the chat model, or the compiler. It
129
136
  - bound to its connection record (the ciphertext is unusable if copied elsewhere);
130
137
  - decrypted only inside the API calls of an active deploy, then discarded.
131
138
 
132
- 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, and the card turns the next failed call into that same reconnect prompt. See [Connection states and recovery](#connection-states-and-recovery) for the full set.
139
+ The grant is standing permission carried by short-lived credentials. The token that can actually touch your account expires every hour; the deploy service refreshes it server-side, so expiry never reaches you as a prompt — a leaked working token goes stale within the hour either way. What persists is the sealed refresh token, which can only mint the next short-lived token.
140
+
141
+ Revoking in Cloudflare (**My Profile → Access Management → Connected Applications**) kills the whole chain immediately — the stored ciphertext becomes useless, and the card turns the next failed call into a reconnect prompt. See [Connection states and recovery](#connection-states-and-recovery) for the full set.
133
142
 
134
143
  ## Secrets on the deployed app
135
144
 
@@ -171,7 +180,27 @@ Your app answers at `https://<app-name>.<your-subdomain>.workers.dev`:
171
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 === "appmanager"`, which your first deploy seeds for you — see [Owner access](/start/deploy-owner-access).
172
181
  - `/health` reports status and whether email is configured.
173
182
 
174
- 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.
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.
184
+
185
+ That handover works because a successful deploy writes the real Cloudflare resource ids back into your `quickback.config.ts`:
186
+
187
+ ```ts title="quickback/quickback.config.ts"
188
+ database: {
189
+ name: "cloudflare-d1",
190
+ config: {
191
+ splitDatabases: true,
192
+ authBinding: "AUTH_DB",
193
+ featuresBinding: "DB",
194
+ authDatabaseId: "8f2c…", // written by the deploy
195
+ featuresDatabaseId: "b91e…", // written by the deploy
196
+ },
197
+ },
198
+ ```
199
+
200
+ Those ids identify the exact databases serving your app, so the download, the file tree, and any copy you hand to another tool all carry them. Without them `quickback deploy` can only match your resources by *name* — which silently creates a second, empty set if you deploy from a different Cloudflare login or rename the app.
201
+
202
+ > Keep those id keys when you edit the config. Deleting them points your next deploy at fresh, empty databases rather than the ones holding your data. If they do go missing, redeploying from Start writes them back.
203
+
175
204
 
176
205
  ## Not yet available
177
206
 
@@ -38,6 +38,17 @@ enforced exactly — there's no window in which a spent link claims again.
38
38
  the Account UI enabled, you land on `/account`; API-only apps sign in via
39
39
  `POST /auth/v1/sign-in/email`.
40
40
 
41
+ ## Signing up yourself doesn't make you an admin
42
+
43
+ `/account/signup` creates an ordinary user. It never sets
44
+ `role === "appmanager"`, so that account can't open `/cms/`. The claim link is
45
+ the only path to the first admin.
46
+
47
+ No confirmation email is sent, either — apps built from Start default to email
48
+ and password with verification off, because a `workers.dev` deploy has no
49
+ verified sending domain. If you're waiting on a signup email, nothing is
50
+ coming; open the claim link instead, or re-issue one from the deploy card.
51
+
41
52
  **Quickback is not your app's identity provider.** The claim link is a
42
53
  bootstrap window, not a login method: once claimed (or expired), your app has
43
54
  no runtime dependency on Quickback or the deploy broker for authentication.
@@ -436,3 +436,19 @@ POST /candidates
436
436
  3. **All layers work together** - Firewall -> Access -> Guards -> Masking
437
437
  4. **Code is readable and auditable** - no magic, just TypeScript
438
438
  5. **Type-safe from definition to API** - Drizzle schema drives everything
439
+
440
+ ## Keep going in the same file
441
+
442
+ Everything above is one config object, and it takes more keys than security and
443
+ CRUD. Each adds a real endpoint on the same pipeline, so reach for these before
444
+ writing a custom action:
445
+
446
+ - [`transitions`](/define/transitions) — a guarded state change (`publish`,
447
+ `approve`, `checkIn`) generated as `POST /candidates/:id/{name}`
448
+ - [`realtime`](/platform/realtime/using-realtime) — broadcast inserts, updates,
449
+ and deletes to subscribed clients
450
+ - [`triggers`](/define/triggers) — run a data rule or side-effect on every write
451
+ - [`owns`](/define/changesets) — write a parent row and its children atomically
452
+
453
+ The `views` you already declared are the same idea: a whole endpoint from a few
454
+ lines. See [the full option list](/define#other-resource-options).
@@ -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 users with `role: "admin"` on their Better Auth user record. Non-admin users are redirected away from `/admin`.
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
- To grant admin access to a user, use the Better Auth admin plugin:
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": "admin" }'
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: "admin" },
91
+ cms: { domain: "cms.example.com", access: "sysadmin" },
68
92
  ```
69
93
 
70
- With `access: "admin"`, callers outside the platform control-plane roles can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to `userRole: ["appmanager"]` (plus `sysadmin` when enabled). See [CMS Connecting](/ui/admin/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
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: "admin"` — only `user.role === "appmanager"` (the Better Auth platform control-plane tier) can reach `/cms/*`. When `cms.sysadmin: true`, `user.role === "sysadmin"` is also admitted. Other authenticated users are redirected to `/account/profile`. The gate is enforced at multiple layers:
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 gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
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 allow any authenticated user to access the CMS, opt out explicitly:
149
+ To let organization members in as well as sysadmins:
150
150
 
151
151
  ```typescript
152
- cms: { access: "user" }
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