@quickback-dev/cli 0.60.9 → 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.
- package/dist/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +737 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/index.js +1 -1
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/skill/docs/api/errors.md +1 -0
- package/dist/skill/docs/api/query-params.md +26 -0
- package/dist/skill/docs/changelog/index.md +79 -0
- package/dist/skill/docs/configure/auth.md +17 -12
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +5 -5
- package/dist/skill/docs/define/actions/index.md +18 -0
- package/dist/skill/docs/define/areas.md +90 -7
- package/dist/skill/docs/define/feature.md +88 -27
- package/dist/skill/docs/define/index.md +7 -1
- package/dist/skill/docs/define/scopes.md +1 -1
- package/dist/skill/docs/define/security.md +10 -0
- package/dist/skill/docs/define/transitions.md +11 -35
- package/dist/skill/docs/platform/auth/jwt-optimization.md +15 -3
- package/dist/skill/docs/platform/database/d1.md +6 -1
- package/dist/skill/docs/platform/realtime/index.md +17 -0
- package/dist/skill/docs/platform/webhooks/outbound.md +31 -6
- package/dist/skill/docs/start/deploy-browser.md +15 -6
- package/dist/skill/docs/start/first-api.md +16 -0
- package/dist/skill/docs/ui/account/features/admin.md +29 -5
- package/dist/skill/docs/ui/account/features/index.md +22 -0
- package/dist/skill/docs/ui/admin/connecting.md +6 -4
- package/dist/skill/docs/ui/admin/index.md +49 -10
- package/dist/skill/docs/ui/admin/security.md +6 -7
- package/package.json +1 -1
- package/src/skill/docs/api/errors.md +1 -0
- package/src/skill/docs/api/query-params.md +26 -0
- package/src/skill/docs/changelog/index.md +79 -0
- package/src/skill/docs/configure/auth.md +17 -12
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +5 -5
- package/src/skill/docs/define/actions/index.md +18 -0
- package/src/skill/docs/define/areas.md +90 -7
- package/src/skill/docs/define/feature.md +88 -27
- package/src/skill/docs/define/index.md +7 -1
- package/src/skill/docs/define/scopes.md +1 -1
- package/src/skill/docs/define/security.md +10 -0
- package/src/skill/docs/define/transitions.md +11 -35
- package/src/skill/docs/platform/auth/jwt-optimization.md +15 -3
- package/src/skill/docs/platform/database/d1.md +6 -1
- package/src/skill/docs/platform/realtime/index.md +17 -0
- package/src/skill/docs/platform/webhooks/outbound.md +31 -6
- package/src/skill/docs/start/deploy-browser.md +15 -6
- package/src/skill/docs/start/first-api.md +16 -0
- package/src/skill/docs/ui/account/features/admin.md +29 -5
- package/src/skill/docs/ui/account/features/index.md +22 -0
- package/src/skill/docs/ui/admin/connecting.md +6 -4
- package/src/skill/docs/ui/admin/index.md +49 -10
- package/src/skill/docs/ui/admin/security.md +6 -7
|
@@ -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
|
-
|
|
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
|
-
-
|
|
177
|
-
-
|
|
178
|
-
-
|
|
179
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
|
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
|
-
|
|
|
99
|
-
|
|
|
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
|
-
|
|
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
|
|
|
@@ -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
|
|
46
|
+
The admin panel is restricted to platform roles on the Better Auth user record: **`appmanager`** (the control plane) and **`sysadmin`** (which adds cross-tenant data access on top). Everyone else is redirected away from `/admin`.
|
|
34
47
|
|
|
35
|
-
|
|
48
|
+
> **`role: "admin"` is not a platform role.** The compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`, so a user set to `"admin"` passed the UI guard and then got `403` from every admin API call — an operator who looked promoted and could not act. Removed in v0.62; migrate those rows to `"appmanager"`.
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
To grant operator access to a user:
|
|
36
52
|
|
|
37
53
|
```bash
|
|
38
54
|
curl -X POST https://api.example.com/auth/v1/admin/set-role \
|
|
39
55
|
-H "Authorization: Bearer $TOKEN" \
|
|
40
56
|
-H "Content-Type: application/json" \
|
|
41
|
-
-d '{ "userId": "user_123", "role": "
|
|
57
|
+
-d '{ "userId": "user_123", "role": "appmanager" }'
|
|
42
58
|
```
|
|
43
59
|
|
|
60
|
+
### Why creating an organization names an owner
|
|
61
|
+
|
|
62
|
+
Better Auth's `organization.create` seats whoever calls it. For an operator that is an escalation rather than a convenience: the membership it grants is tenant-data access — under `cms.access: "member"`, access to that organization's records — which is exactly what the `appmanager`/`sysadmin` split withholds.
|
|
63
|
+
|
|
64
|
+
So organization creation asks for an `ownerUserId`, seats that user, and never seats the caller. Self-serve creation (`POST /auth/v1/organization/create`) is closed by default for the same reason; a project that wants it sets `plugins.organization.allowUserToCreateOrganization: true`.
|
|
65
|
+
|
|
66
|
+
An operator who genuinely wants their own organization creates one naming themselves as owner — explicit, and visible in the audit trail rather than implied by whoever happened to make the call.
|
|
67
|
+
|
|
44
68
|
## Custom Admin Domain
|
|
45
69
|
|
|
46
70
|
Give the admin panel its own subdomain with `adminDomain`:
|
|
@@ -64,10 +88,10 @@ The admin domain serves the same Account SPA at root (`/`). The SPA's client-sid
|
|
|
64
88
|
When both CMS and Account UI are enabled, the admin panel's profile page shows a "Go to CMS" button. You can restrict this to admin users only:
|
|
65
89
|
|
|
66
90
|
```typescript
|
|
67
|
-
cms: { domain: "cms.example.com", access: "
|
|
91
|
+
cms: { domain: "cms.example.com", access: "sysadmin" },
|
|
68
92
|
```
|
|
69
93
|
|
|
70
|
-
With `access: "
|
|
94
|
+
With `access: "sysadmin"`, only the cross-tenant `sysadmin` tier reaches the CMS: the link is hidden in Account UI, `/api/v1/schema` returns `403`, and `custom_view` CRUD is locked to `userRole: ["sysadmin"]`. Note that an **appmanager does not get in** — `/account/admin` (this page) is the appmanager's surface, and the CMS is not. See [CMS access gate](/ui/admin#access-gate) for the full model.
|
|
71
95
|
|
|
72
96
|
## Related
|
|
73
97
|
|
|
@@ -179,6 +179,28 @@ VITE_ENABLE_GOOGLE_OAUTH=false # default: false
|
|
|
179
179
|
**Requirements:**
|
|
180
180
|
- Google OAuth credentials configured on the Better Auth side
|
|
181
181
|
|
|
182
|
+
### Cloudflare OAuth
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
VITE_ENABLE_CLOUDFLARE_OAUTH=false # default: false
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**When enabled:**
|
|
189
|
+
- "Continue with Cloudflare" button on the login and signup pages
|
|
190
|
+
- Cloudflare rows in the profile page's Connected Accounts card — unlike
|
|
191
|
+
Google, more than one Cloudflare identity can be linked to the same user
|
|
192
|
+
(**Connect another Cloudflare account**), and every linked identity signs
|
|
193
|
+
in to this user. Link work and personal Cloudflare logins here so each one
|
|
194
|
+
doesn't mint its own separate account.
|
|
195
|
+
|
|
196
|
+
**When disabled:**
|
|
197
|
+
- No Cloudflare sign-in button, no Connected Accounts rows
|
|
198
|
+
|
|
199
|
+
**Requirements:**
|
|
200
|
+
- `socialProviders.cloudflare.enabled` in the auth config (Cloudflare rides
|
|
201
|
+
the genericOAuth plugin, not a Better Auth built-in) and the
|
|
202
|
+
`AUTH_CLOUDFLARE_CLIENT_ID` / `AUTH_CLOUDFLARE_CLIENT_SECRET` secrets
|
|
203
|
+
|
|
182
204
|
## Account Management Features
|
|
183
205
|
|
|
184
206
|
### File Uploads
|
|
@@ -136,22 +136,24 @@ cms: { domain: "cms.example.com" }
|
|
|
136
136
|
|
|
137
137
|
This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `cms.example.com` point to the same Worker. The compiler auto-configures hostname-based routing and cross-subdomain cookies.
|
|
138
138
|
|
|
139
|
-
CMS access defaults to `access: "
|
|
139
|
+
CMS access defaults to `access: "sysadmin"` — only `user.role === "sysadmin"` (the cross-tenant data-plane tier) can use `/cms/*`. Set `access: "member"` to also admit anyone holding an organization membership. `user.role === "appmanager"` opens the CMS in neither mode: it is the control-plane tier and belongs at `/account/admin`. The gate is enforced at multiple layers:
|
|
140
140
|
|
|
141
141
|
- **Account UI** hides the "Go to CMS" button for callers outside those roles.
|
|
142
142
|
- **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-operator. A non-operator who types the CMS URL directly cannot load the app.
|
|
143
143
|
- **`/api/v1/schema`** returns `403 Platform operator access required` to callers outside those roles, so schema metadata can't be scraped by hitting the API directly.
|
|
144
144
|
- **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
|
|
145
|
-
- **In-SPA
|
|
145
|
+
- **In-SPA screen** — a signed-in caller who isn't admitted is served the shell and shown a screen naming what they'd need. There is no wrong-role redirect.
|
|
146
146
|
|
|
147
147
|
Your resource API endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
|
|
148
148
|
|
|
149
|
-
To
|
|
149
|
+
To let organization members in as well as sysadmins:
|
|
150
150
|
|
|
151
151
|
```typescript
|
|
152
|
-
cms: { access: "
|
|
152
|
+
cms: { access: "member" }
|
|
153
153
|
```
|
|
154
154
|
|
|
155
|
+
See [Access gate](/ui/admin#access-gate) for the full model — including why `appmanager` opens the CMS in neither mode.
|
|
156
|
+
|
|
155
157
|
See [Multi-Domain Architecture](/configure/domains) for details on multi-domain routing.
|
|
156
158
|
|
|
157
159
|
## Default Org Mode vs Pinned Organization Mode
|
|
@@ -112,22 +112,61 @@ cms: { domain: "cms.example.com" }
|
|
|
112
112
|
|
|
113
113
|
This adds a custom domain route to `wrangler.toml`. Both domains serve the same Worker — `api.example.com` for the API, `cms.example.com` for the CMS. The compiler also auto-infers a unified `quickback.example.com` domain where everything is available. See [Multi-Domain Architecture](/configure/domains).
|
|
114
114
|
|
|
115
|
-
### Access gate
|
|
115
|
+
### Access gate
|
|
116
116
|
|
|
117
|
-
|
|
117
|
+
`cms.access` answers one question: **can anyone in the organization hierarchy use the CMS, or only a platform sysadmin?**
|
|
118
118
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
119
|
+
| Value | Who gets in |
|
|
120
|
+
|-------|-------------|
|
|
121
|
+
| `"sysadmin"` (default) | Only `user.role === "sysadmin"` — the cross-tenant data-plane tier. They choose a tenant from the org picker. |
|
|
122
|
+
| `"member"` | The above, **plus** any caller holding a membership in an organization, scoped to that organization. |
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
cms: { access: "member" } // let organization members in
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
> **`user.role === "appmanager"` does not open the CMS in either mode.** appmanager is the *control plane* — users, organizations, and subscriptions at [`/account/admin`](/ui/account) — and deliberately holds no tenant-data powers. Keeping those separable is the entire point of the appmanager/sysadmin split. An appmanager who is also a member of an organization gets in as that member, on the membership, not on the platform role.
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
#### Where the gate actually lives
|
|
132
|
+
|
|
133
|
+
The CMS **shell** is served to any signed-in caller. Authorization is decided in the SPA, which renders a screen naming the caller's state and what to do about it — a signed-in user who can't get in is told why, instead of being silently bounced.
|
|
134
|
+
|
|
135
|
+
That is a deliberate trade: the old gate answered a wrong-role caller with a `302` so it couldn't be used to probe roles. The shell is a generic prebuilt bundle with no project data in it, and being unable to distinguish a permissions problem from a broken deploy cost more than the deniability was worth.
|
|
136
|
+
|
|
137
|
+
The gates that carry real data:
|
|
138
|
+
|
|
139
|
+
1. **`/api/v1/schema`** — the metadata endpoint. Admits `sysadmin`, plus any caller with a membership when `access: "member"`. Otherwise `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
|
|
140
|
+
2. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, org membership *or* sysadmin in `"member"` mode.
|
|
141
|
+
3. **Account UI link** — the "Go to CMS" button is hidden for callers who wouldn't get in.
|
|
123
142
|
|
|
124
143
|
Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
|
|
125
144
|
|
|
126
|
-
|
|
145
|
+
> **Breaking in v0.62.** `cms.access` was renamed from `"admin" | "user"`, and both old values meant something different: `"admin"` admitted `appmanager`, and `"user"` admitted *any* authenticated caller — including one belonging to no organization, who then reached a CMS with nothing in it. The old spellings are rejected at compile time rather than aliased, because aliasing would preserve the old behaviour under a familiar name. Migrate `"admin"` → `"sysadmin"`, `"user"` → `"member"`.
|
|
127
146
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
147
|
+
|
|
148
|
+
#### What a blocked caller actually sees
|
|
149
|
+
|
|
150
|
+
The shell is served to any signed-in caller, and the SPA resolves one of six states — each its own screen naming what is true and what to do next. Nothing redirects: a signed-in user bounced elsewhere cannot tell a permissions problem from a broken deploy.
|
|
151
|
+
|
|
152
|
+
| State | Screen |
|
|
153
|
+
|-------|--------|
|
|
154
|
+
| Not signed in | Redirect to sign-in (the one redirect that remains — it is where you were going anyway) |
|
|
155
|
+
| `sysadmin`, no tenant chosen | Tenant picker, filterable, with **All organizations** as a first-class choice |
|
|
156
|
+
| `sysadmin`, tenant chosen | The CMS, scoped to that tenant |
|
|
157
|
+
| `appmanager`, `access: "sysadmin"` | *"The CMS shows organization data"* → **Go to admin** |
|
|
158
|
+
| Anyone else, `access: "sysadmin"` | *"This CMS is restricted"* — names the config value that would admit them |
|
|
159
|
+
| `access: "member"`, no membership | *"You're not in any organization yet"* → **View invitations** (an appmanager gets **Go to admin** instead — telling them to ask an admin for an invite when they are the admin is a dead end) |
|
|
160
|
+
| `access: "member"`, one membership | Auto-selected; straight in |
|
|
161
|
+
| `access: "member"`, several | Membership picker |
|
|
162
|
+
|
|
163
|
+
The decision is a pure function (`resolveCmsAccess`), so the table above is tested rather than described.
|
|
164
|
+
|
|
165
|
+
Sysadmin scope lives in the browser and rides every request as `?organizationId=` — it is not part of the session, because a sysadmin holds no membership row for Better Auth to make active. Change it from the sidebar.
|
|
166
|
+
|
|
167
|
+
#### `access: "sysadmin"` without `cms.sysadmin`
|
|
168
|
+
|
|
169
|
+
A sysadmin can still pin a single tenant — `?organizationId=` cross-tenant addressing is admitted for sysadmins unconditionally. The **"All organizations"** unfiltered view is what needs the firewall escape that `cms.sysadmin: true` emits.
|
|
131
170
|
|
|
132
171
|
### Optional: Skip SPA rebuild
|
|
133
172
|
|
|
@@ -2,19 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
The CMS respects all four Quickback security layers. Every UI element — buttons, form fields, table columns, action menus — adapts based on the current user's role and the security rules defined in your feature files.
|
|
4
4
|
|
|
5
|
-
## CMS Access
|
|
5
|
+
## CMS Access
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
`cms.access` decides whether the CMS is for platform sysadmins only (`"sysadmin"`, the default) or for organization members too (`"member"`). `user.role === "appmanager"` opens it in neither mode — that tier is the control plane, not the data plane.
|
|
8
8
|
|
|
9
9
|
```typescript
|
|
10
|
-
cms: { access: "
|
|
10
|
+
cms: { access: "member" }
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
The shell is served to any signed-in caller so the SPA can explain who is and isn't admitted; the gates that carry data are:
|
|
14
14
|
|
|
15
|
-
1. **Account UI** — the "Go to CMS" button is hidden.
|
|
16
|
-
2.
|
|
17
|
-
3. **`/api/v1/schema`** — the CMS metadata endpoint returns `403` to callers outside those roles.
|
|
15
|
+
1. **Account UI** — the "Go to CMS" button is hidden for callers who wouldn't get in.
|
|
16
|
+
2. **`/api/v1/schema`** — the metadata endpoint returns `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
|
|
18
17
|
4. **`custom_view` routes** — the CMS-internal saved-views table uses `userRole: ["appmanager"]` (and, when `cms.sysadmin: true`, also admits `sysadmin`), so saved views can't be read or modified from outside the CMS by non-operator accounts.
|
|
19
18
|
5. **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
|
|
20
19
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.61.0",
|
|
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",
|
|
@@ -98,6 +98,7 @@ Missing or invalid authentication tokens.
|
|
|
98
98
|
| `AUTH_EXPIRED` | Token has expired |
|
|
99
99
|
| `AUTH_RATE_LIMITED` | Too many auth attempts |
|
|
100
100
|
| `AUTH_SESSION_REQUIRED` | The endpoint requires session (cookie) authentication — returned by `POST /api/v1/token` when called with a JWT, API key, or OAuth bearer, so a stolen or revoked token can't mint its own replacement |
|
|
101
|
+
| `AUTH_REVOCATION_UNAVAILABLE` | **503, retryable.** Only with [`revocationCheck: 'kv'`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy): the bearer's signature verified, but its revocation state could not be read (KV binding missing or unreachable), so it was not trusted. Retry, or authenticate with a session cookie |
|
|
101
102
|
|
|
102
103
|
### Firewall (403)
|
|
103
104
|
|
|
@@ -31,6 +31,27 @@ GET /api/v1/jobs?title.like=Engineer
|
|
|
31
31
|
GET /api/v1/jobs?department.in=Engineering,Design,Product
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
+
### Unknown filters are rejected, not ignored
|
|
35
|
+
|
|
36
|
+
A filter the handler cannot apply returns `400` (`VALIDATION_INVALID_INPUT`).
|
|
37
|
+
It is never dropped:
|
|
38
|
+
|
|
39
|
+
| Request | Result |
|
|
40
|
+
|---------|--------|
|
|
41
|
+
| `?guestId=g_1` where `guestId` isn't a column | `400` — `Unknown filter field "guestId"` |
|
|
42
|
+
| `?status=open` on a view whose `query.filterable` omits `status` | `400` — `Field "status" is not filterable on this view` |
|
|
43
|
+
| `?title.matches=x` (no such operator) | `400` — `Unknown filter operator "matches"` |
|
|
44
|
+
| `?ssn=123` where `ssn` is masked for your role | `400` — see [Masking](/define/masking) |
|
|
45
|
+
|
|
46
|
+
Silently dropping a predicate would return **every row the firewall allows**
|
|
47
|
+
while still reading as a scoped list — a typo'd or join-table field turns a
|
|
48
|
+
narrow query into a full dump. The same rule closes `?search=` and `?sort=`.
|
|
49
|
+
|
|
50
|
+
> Filtering on a relationship that lives in a join table is not a column filter.
|
|
51
|
+
> `GET /travel-bookings?guestId=...` cannot work when membership is
|
|
52
|
+
> `travel_booking_guests` — expose a view or an `include` for it instead.
|
|
53
|
+
|
|
54
|
+
|
|
34
55
|
## Pagination
|
|
35
56
|
|
|
36
57
|
| Parameter | Default | Description |
|
|
@@ -110,6 +131,11 @@ GET /api/v1/jobs?sort=title&order=asc
|
|
|
110
131
|
|
|
111
132
|
When the multi-sort format is detected (comma or `-` prefix), the `order` parameter is ignored.
|
|
112
133
|
|
|
134
|
+
A client-supplied `?sort=` naming an unknown column — or one outside a view's
|
|
135
|
+
`query.sortable` — returns `400`, for the same reason unknown filters do: rows
|
|
136
|
+
would come back in some other order that reads as the requested one. A view's
|
|
137
|
+
own `defaultSort` fallback is config, not caller input, and is never rejected.
|
|
138
|
+
|
|
113
139
|
## Field Selection
|
|
114
140
|
|
|
115
141
|
Select which columns to return using `?fields=`. Available on LIST and GET routes (not Views — they define their own field set).
|
|
@@ -8,6 +8,85 @@ 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
|
+
## v0.61.0 — August 12, 2026
|
|
12
|
+
|
|
13
|
+
### Security: JWT revocation now fails closed when KV is unreachable
|
|
14
|
+
|
|
15
|
+
**Affects projects using `auth.jwt.revocationCheck: 'kv'`** — including every
|
|
16
|
+
project with a `.sealed()` column, which force-enables it.
|
|
17
|
+
|
|
18
|
+
Setting `revocationCheck: 'kv'` asks the verifier to consult current security
|
|
19
|
+
state before trusting a signed bearer. It did the opposite under failure: a
|
|
20
|
+
missing `KV` binding, a failed read, or a corrupt entry all returned "not
|
|
21
|
+
revoked," so a token was accepted during exactly the outage that hid its
|
|
22
|
+
revocation. A banned user's bearer kept working for the rest of its TTL, and
|
|
23
|
+
the one signal that would have caught it was the thing that had broken.
|
|
24
|
+
|
|
25
|
+
The check now returns `active` / `revoked` / `unavailable`, and only `active`
|
|
26
|
+
authenticates the bearer. A corrupt stamp is `unavailable` too — it used to
|
|
27
|
+
parse as `NaN` and compare as "not revoked."
|
|
28
|
+
|
|
29
|
+
**What changes operationally.** A bearer whose revocation state can't be read
|
|
30
|
+
gets a retryable `503 AUTH_REVOCATION_UNAVAILABLE` ([RFC 9457](/api/errors))
|
|
31
|
+
instead of being let through. Recovery is a separate cookie-only request: a
|
|
32
|
+
request carrying `Authorization` has its cookie stripped before session auth,
|
|
33
|
+
so during a KV outage every JWT-bearer request gets the 503 until the client
|
|
34
|
+
retries on its session cookie. One reason-only log line per occurrence carries
|
|
35
|
+
the cause (`missing-binding` / `read-error`) with no token, claim, or KV key in
|
|
36
|
+
it — **alert on it.**
|
|
37
|
+
|
|
38
|
+
This ties bearer-token availability to KV. That is the trade the opt-in now
|
|
39
|
+
makes honestly, and it is the right way round: a revocation check that gives
|
|
40
|
+
up under load is worth nothing. If you want the TTL bound *without* the
|
|
41
|
+
coupling, leave `revocationCheck` at `'none'` and set `expiresIn: 30`.
|
|
42
|
+
|
|
43
|
+
Because the binding is now load-bearing, a project with named `environments`
|
|
44
|
+
must declare `bindings.kv` on **every** target — a compile error naming the
|
|
45
|
+
environment, rather than a 503 discovered after deploy.
|
|
46
|
+
|
|
47
|
+
`revocationCheck: 'none'` output is byte-identical. See
|
|
48
|
+
[`revocationCheck`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy).
|
|
49
|
+
|
|
50
|
+
### Security: revocation was off by one second
|
|
51
|
+
|
|
52
|
+
**Also affects projects using `auth.jwt.revocationCheck: 'kv'`.**
|
|
53
|
+
|
|
54
|
+
Revocation markers and token mint timestamps were both whole seconds, and the
|
|
55
|
+
check rejected only a token stamped *strictly before* the marker. A token
|
|
56
|
+
minted earlier in the same second as the revocation therefore compared **equal**
|
|
57
|
+
and survived — a sub-second hole in a mechanism whose whole promise is
|
|
58
|
+
"revoked within seconds." Whether an attacker landed in it was a coin flip on
|
|
59
|
+
clock alignment, not on anything defensible.
|
|
60
|
+
|
|
61
|
+
Markers are now epoch milliseconds, tokens carry millisecond companions
|
|
62
|
+
(`iatMs`, and `sctMs` for the relationship-scope proof), and the comparison
|
|
63
|
+
denies a tie. A token minted milliseconds before the revocation is rejected; one
|
|
64
|
+
legitimately re-minted *after* it in that same second is still accepted, which
|
|
65
|
+
is why simply flipping `<` to `<=` on seconds was not the fix.
|
|
66
|
+
|
|
67
|
+
`iat` and `sct` remain standards-compatible unix **seconds** for external
|
|
68
|
+
tooling — the millisecond claims are internal ordering metadata, set by the
|
|
69
|
+
signer from the same clock sample and never accepted from a caller.
|
|
70
|
+
|
|
71
|
+
**Rollout is conservative, not clever.** Marker format is read from an explicit
|
|
72
|
+
version marker, never guessed from magnitude. Where one side is from v0.60.4 or
|
|
73
|
+
earlier — an old token against a new marker, or any token against an old marker
|
|
74
|
+
— there is no sub-second information to compare, so the **entire marker second**
|
|
75
|
+
is revoked. That over-revocation is bounded (old tokens expire within their TTL,
|
|
76
|
+
old markers within the entry lifetime), and it costs the caller a `401` and a
|
|
77
|
+
re-authentication, exactly as any other rejected token does. No action is needed
|
|
78
|
+
upgrading forward.
|
|
79
|
+
|
|
80
|
+
**Do not straddle this release, though.** A worker from before v0.61.0 reads a
|
|
81
|
+
millisecond marker as `NaN` and concludes *not revoked* — it does not recognise
|
|
82
|
+
it as corrupt, so the fail-closed path added above never fires. Rolling back
|
|
83
|
+
across this release, or running two differently-versioned deploy targets against
|
|
84
|
+
one shared KV namespace, means every revocation written by the new version is
|
|
85
|
+
**silently unenforced** by the old one until the entry expires (~19 minutes at
|
|
86
|
+
default settings). Upgrade targets that share a namespace together. If you must
|
|
87
|
+
roll back, treat outstanding bearers as unrevoked for that window: lower
|
|
88
|
+
`expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
|
|
89
|
+
|
|
11
90
|
## v0.60.4 — August 4, 2026
|
|
12
91
|
|
|
13
92
|
### Fix: retired-path cleanup was inert in v0.60.1–v0.60.3
|
|
@@ -45,7 +45,7 @@ The short version, before the knob-by-knob detail:
|
|
|
45
45
|
- **Default: 180-second TTL, auto-refreshed.** Every authenticated call returns a fresh token via the `set-auth-token` header, so the low TTL is invisible to logged-in users. The worst-case window for a stolen or pre-revocation token is 3 minutes — and you can shrink it to 30 seconds with one config line.
|
|
46
46
|
- **Need revocation faster than the TTL?** Set [`revocationCheck: 'kv'`](#revocationcheck-none--kv--token-revocation-strategy). Revoked tokens are rejected within seconds; revocation stamps are written automatically on user ban, org-member removal, role change, and changes to scope-conferring relationship rows.
|
|
47
47
|
|
|
48
|
-
Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session)
|
|
48
|
+
Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling — and [tell us about your use case](https://github.com/kardoe/quickback/issues); an opaque-session mode is under consideration.
|
|
49
49
|
|
|
50
50
|
### Behavior recap
|
|
51
51
|
|
|
@@ -105,11 +105,11 @@ Default `'none'`.
|
|
|
105
105
|
| Value | Behavior | Cost per verify |
|
|
106
106
|
|---|---|---|
|
|
107
107
|
| `'none'` | No revocation check. Stolen / pre-revocation tokens valid until TTL expires (scope claims: until the carry-forward cap). Use a low `expiresIn` to bound the replay window. | 0 |
|
|
108
|
-
| `'kv'` | Fast-path checks per-principal revocation timestamps in the project's existing `KV` binding before trusting a verified token. | 2+ KV reads (~5-15ms, edge-cached) |
|
|
108
|
+
| `'kv'` | Fast-path checks per-principal revocation timestamps in the project's existing `KV` binding before trusting a verified token. Fails closed: an unreadable store means the bearer is not trusted. | 2+ KV reads (~5-15ms, edge-cached) |
|
|
109
109
|
|
|
110
110
|
`'kv'` (v0.45+, **Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
|
|
111
111
|
|
|
112
|
-
A token is rejected when its mint timestamp (`iat`, or `sct` for the relationship-scope claim)
|
|
112
|
+
A token is rejected when its mint timestamp (`iat`/`iatMs`, or `sct`/`sctMs` for the relationship-scope claim) is **at or before** the stored timestamp for any principal key it rides on:
|
|
113
113
|
|
|
114
114
|
| Key | Revokes | Written automatically on |
|
|
115
115
|
|---|---|---|
|
|
@@ -122,8 +122,12 @@ A token is rejected when its mint timestamp (`iat`, or `sct` for the relationshi
|
|
|
122
122
|
Semantics worth knowing:
|
|
123
123
|
|
|
124
124
|
- **Revoke-on-touch for scopes:** any update or delete of a conferring row stamps the revocation, without evaluating whether the change actually ended the relationship. A false positive just forces a cheap re-prove (`/scope/v1/enter` or a minting namespace route).
|
|
125
|
-
- **
|
|
125
|
+
- **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format version, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, 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. Tokens and markers written by v0.60.4 or earlier are handled **conservatively**: with no sub-second information on one side, the whole marker second is revoked. That over-revocation is bounded — the last old token expires within its TTL, and the last old marker within the entry lifetime. Like any rejected token it costs the caller a `401`, not a silent recovery: the bearer falls through unauthenticated (its cookie having been stripped, per the next bullet), and the client re-authenticates for a fresh token.
|
|
126
|
+
- **Do not straddle the v0.61.0 upgrade.** A worker from **before** v0.61.0 reads `m<ms>` markers as `NaN` and treats them as *no revocation at all* — not as a corrupt entry. So rolling back across this release, or pointing two differently-versioned deploy targets at one shared KV namespace, means every revocation written by the new version is **silently unenforced** by the old one until the entry expires (`ENTRY_TTL_SECONDS`, ~19 minutes at default settings). Upgrade all targets sharing a namespace together; if you must roll back, treat outstanding bearer tokens as unrevoked for that window — lower `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
|
|
127
|
+
- **Fails closed:** a missing binding, a failed read, or a corrupt entry means the token's revocation state is *unknown* — and an unknown bearer is not authenticated. The caller gets `503 AUTH_REVOCATION_UNAVAILABLE` (RFC 9457, retryable). Recovery is a **separate cookie-only request**: a request carrying `Authorization` has its cookie stripped before session auth, so within that one request there is nothing left to fall back to. Reads are never silently skipped, because the outage that hides a revocation is exactly the moment this check exists for.
|
|
128
|
+
- **Availability coupling:** the flip side of the above. Bearer-token auth now depends on KV being readable. Alert on `AUTH_REVOCATION_UNAVAILABLE`; a sustained rate means the binding is missing on some deployment target, or KV is degraded. Every named environment must declare `bindings.kv` — the compiler rejects a target that doesn't.
|
|
126
129
|
- **Eventual consistency:** KV propagates cross-PoP in ~60s. "Immediate" means seconds at the writing location, bounded-seconds globally — still far inside the 15-minute carry-forward cap that bounds revocation without this check.
|
|
130
|
+
- **Writes stay best-effort:** the *stamps* are written after the authorization change has already committed (the ban row, the removed membership, the deleted conferring row). A failed stamp does not fail that write — the DB state is the durable cut. It is only the *read* side that fails closed.
|
|
127
131
|
- **Coverage gap:** batch *hard* deletes don't return rows through the chokepoint; call `revokeScopeTokens` explicitly if you bulk-hard-delete conferring rows.
|
|
128
132
|
|
|
129
133
|
## Defaults when the JWT surface is enabled
|
|
@@ -145,34 +149,35 @@ missing field falls back to its hardcoded value:
|
|
|
145
149
|
- **B2C SaaS, mostly browser traffic:** keep defaults. The 180s TTL + auto-refresh model just works.
|
|
146
150
|
- **Pentest engagement / enterprise compliance:** set `expiresIn: 30`. Tokens stay invisible to logged-in users (auto-refreshed every authed call) but stolen-token windows shrink to 30s.
|
|
147
151
|
- **CLI-heavy / long-running CI tokens:** `expiresIn: 3600` for one-hour bearer tokens. Pair with `issuer` / `audience` if multiple services consume the same JWT.
|
|
148
|
-
- **Need immediate revocation:** set `revocationCheck: 'kv'` (Cloudflare runtime) — revoked tokens are rejected within seconds, and stamps are written automatically on user ban, member removal, role change, and scope-conferring row changes (see the [scope revocation notes](/define/scopes#revocation--ttl)). Or drop TTL to ~30s — similar effect with bounded delay
|
|
152
|
+
- **Need immediate revocation:** set `revocationCheck: 'kv'` (Cloudflare runtime) — revoked tokens are rejected within seconds, and stamps are written automatically on user ban, member removal, role change, and scope-conferring row changes (see the [scope revocation notes](/define/scopes#revocation--ttl)). It fails closed, so bearer auth then depends on KV being readable — declare `bindings.kv` on every environment and alert on `AUTH_REVOCATION_UNAVAILABLE`. Or drop TTL to ~30s — similar effect with bounded delay, zero KV reads, and no availability coupling.
|
|
149
153
|
|
|
150
|
-
## `auth.loginUrl`
|
|
154
|
+
## `auth.loginUrl` — external sign-in for consumer Workers
|
|
151
155
|
|
|
152
|
-
When a Quickback Worker doesn't host its own Account SPA — e.g. an internal-app mesh where one Worker on the parent domain owns identity (`auth.example.com`) and other Workers share cookies — the compiler-emitted CMS access
|
|
156
|
+
When a Quickback Worker doesn't host its own Account SPA — e.g. an internal-app mesh where one Worker on the parent domain owns identity (`auth.example.com`) and other Workers share cookies — the compiler-emitted CMS access gate needs to redirect unauthenticated visitors to the central sign-in surface, not the local `/account/login` (which doesn't exist there).
|
|
153
157
|
|
|
154
158
|
```ts title="quickback.config.ts"
|
|
155
159
|
export default defineConfig({
|
|
156
160
|
// ...
|
|
157
161
|
auth: {
|
|
158
162
|
loginUrl: 'https://auth.example.com/login',
|
|
159
|
-
profileUrl: 'https://auth.example.com/profile',
|
|
160
163
|
},
|
|
161
164
|
});
|
|
162
165
|
```
|
|
163
166
|
|
|
164
|
-
Both fields override compiler-emitted browser redirects in the CMS shell:
|
|
165
|
-
|
|
166
167
|
- **Unauthenticated visitor hits a CMS route** → `302 → <loginUrl>?redirect=<original-url>`
|
|
167
|
-
- **Authenticated user fails the `cms.access: 'admin'` platform-role check** → `302 → <profileUrl>`
|
|
168
168
|
|
|
169
169
|
The `?redirect=…` query param is preserved unchanged so the central sign-in surface can bounce the user back after authentication.
|
|
170
170
|
|
|
171
|
+
Signing in is the *only* thing the CMS gate redirects for. A signed-in caller who isn't admitted is served the CMS shell and shown a screen naming what they'd need — see [CMS access](/ui/admin#access-gate). There is no wrong-role redirect, and no `auth.profileUrl`.
|
|
172
|
+
|
|
173
|
+
> **Removed in v0.62:** `auth.profileUrl`. Its only consumer was the CMS wrong-role redirect. The config schema is strict, so a leftover `profileUrl` key now fails the compile — delete it.
|
|
174
|
+
|
|
175
|
+
|
|
171
176
|
### Resolution precedence
|
|
172
177
|
|
|
173
178
|
Most-specific wins:
|
|
174
179
|
|
|
175
|
-
1. Explicit `auth.loginUrl`
|
|
180
|
+
1. Explicit `auth.loginUrl` — the cookie-trusting consumer-Worker case (this section).
|
|
176
181
|
2. `https://<account.domain>/login` — inferred when this project hosts its own Account SPA on a custom domain.
|
|
177
182
|
3. `/account/login` — built-in fallback, when neither knob is set.
|
|
178
183
|
|