@quickback-dev/cli 0.70.43 → 0.70.45
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/index.js +1 -1
- package/dist/skill/docs/api/caching.md +5 -2
- package/dist/skill/docs/configure/agents.md +6 -1
- package/dist/skill/docs/configure/auth.md +3 -1
- package/dist/skill/docs/configure/domains.md +14 -1
- package/dist/skill/docs/platform/auth/jwt-optimization.md +3 -0
- package/package.json +7 -7
- package/src/skill/docs/api/caching.md +5 -2
- package/src/skill/docs/configure/agents.md +6 -1
- package/src/skill/docs/configure/auth.md +3 -1
- package/src/skill/docs/configure/domains.md +14 -1
- package/src/skill/docs/platform/auth/jwt-optimization.md +3 -0
package/dist/index.js
CHANGED
|
@@ -46,10 +46,13 @@ When ETags are enabled, GET responses include:
|
|
|
46
46
|
```
|
|
47
47
|
Content-Type: application/json
|
|
48
48
|
ETag: W/"a1b2c3d4e5f60718"
|
|
49
|
-
Cache-Control: no-cache
|
|
49
|
+
Cache-Control: private, no-cache
|
|
50
|
+
Vary: Authorization, Cookie
|
|
50
51
|
```
|
|
51
52
|
|
|
52
|
-
`Cache-Control: no-cache` means the browser
|
|
53
|
+
`Cache-Control: private, no-cache` means the browser **must revalidate** on every request, but can use its cached copy if the ETag matches, and no shared cache may store the response. This is the correct behavior for authenticated APIs — data is always fresh, but unchanged responses avoid re-transfer.
|
|
54
|
+
|
|
55
|
+
Every other JSON response produced under a cookie or bearer token (writes, actions, auth, admin) is sent with `Cache-Control: private, no-store` unless the route sets its own policy, and always carries `Vary: Authorization, Cookie`, so a proxy can never serve one user's body to another.
|
|
53
56
|
|
|
54
57
|
## Client usage
|
|
55
58
|
|
|
@@ -64,13 +64,18 @@ export default defineConfig({
|
|
|
64
64
|
export default defineConfig({
|
|
65
65
|
// …
|
|
66
66
|
agents: {
|
|
67
|
-
mcp: {
|
|
67
|
+
mcp: {
|
|
68
|
+
requireAuth: true, // /mcp challenges anonymous callers → interactive OAuth
|
|
69
|
+
exposeAuthTools: false, // default — Better Auth endpoints are not catalogued as tools
|
|
70
|
+
},
|
|
68
71
|
},
|
|
69
72
|
});
|
|
70
73
|
```
|
|
71
74
|
|
|
72
75
|
See [Interactive OAuth](#interactive-oauth-requireauth) below.
|
|
73
76
|
|
|
77
|
+
`exposeAuthTools` controls whether the Better Auth surface (`auth__*`, `auth_admin__*`, `auth_api_keys__*`, `auth_passkeys__*`, …) appears in the tool catalogue. It is off by default: an agent authenticates through OAuth and should not be offered credential minting (API keys), passkey enrolment, impersonation or password changes as callable tools. The REST endpoints themselves are unaffected, and the access filter below still applies when you opt in.
|
|
78
|
+
|
|
74
79
|
## The MCP server
|
|
75
80
|
|
|
76
81
|
### Tools
|
|
@@ -162,11 +162,13 @@ A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's
|
|
|
162
162
|
|
|
163
163
|
| Key | Revokes | Written automatically on |
|
|
164
164
|
|---|---|---|
|
|
165
|
-
| `qbrev:sid:<sessionId>` | every JWT minted from one Better Auth session (tokens carry the minting session as `sid` — including scope tokens from `/scope/v1/enter`, namespace mints and their refreshes) | `
|
|
165
|
+
| `qbrev:sid:<sessionId>` | every JWT minted from one Better Auth session (tokens carry the minting session as `sid` — including scope tokens from `/scope/v1/enter`, namespace mints and their refreshes) | **every session deletion**, via `databaseHooks.session.delete.before`: `sign-out`, `revoke-session(s)`, `revoke-other-sessions`, password reset (`/reset-password` and `/email-otp/reset-password` — `revokeSessionsOnPasswordReset` is on by default), `delete-user`, the admin plugin's `/admin/revoke-user-session(s)` and `/admin/stop-impersonating`, and any adapter-level session delete from your own code — a lost device's token dies with its session while the user's other devices keep theirs |
|
|
166
166
|
| `qbrev:user:<userId>` | every JWT for the user | user ban (`databaseHooks.user.update.after` — flipping `banned` stamps the key and, when outbound webhooks are enabled, emits a `user.banned` event); `revoke-sessions`, `revoke-other-sessions`, `change-password` with `revokeOtherSessions`, and `delete-user` (endpoint hooks); the **target** (`body.userId`) of the admin plugin's `/admin/set-role`, `/admin/remove-user`, `/admin/update-user`, and `/admin/revoke-user-sessions`; and every [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound) write. Call `revokeUserTokens` for custom flows |
|
|
167
167
|
| `qbrev:member:<userId>:<orgId>` | the user's org-membership claims | member removal / role change (Better Auth `organizationHooks`) |
|
|
168
168
|
| `qbrev:scope:<userId>:<kind>:<id>` | the user's carried scope claim | UPDATE/DELETE of a scope-conferring relationship row (audit-wrapper chokepoint + the single DELETE route) |
|
|
169
169
|
|
|
170
|
+
Separately from revocation, every mint clamps `exp` to the session's own `expiresAt`, so a JWT can never outlive the session it came from.
|
|
171
|
+
|
|
170
172
|
`src/lib/jwt-revocation.ts` exports `revokeUserTokens` / `revokeSessionTokens` / `revokeMemberTokens` / `revokeScopeTokens` for explicit calls from actions. A rejected token falls through to session auth, which re-checks membership and re-mints — an active legitimate session recovers transparently.
|
|
171
173
|
|
|
172
174
|
Semantics worth knowing:
|
|
@@ -278,12 +278,25 @@ Every environment runs the *same* compiled Worker, so hostname-sensitive behavio
|
|
|
278
278
|
|
|
279
279
|
Each target's `BETTER_AUTH_URL` also defaults to the hostname it claims (unified → auth → API → UI), so a dev deploy authenticates against its own origin instead of production's. Setting `worker.vars.BETTER_AUTH_URL` explicitly still wins.
|
|
280
280
|
|
|
281
|
+
## Host allowlist
|
|
282
|
+
|
|
283
|
+
A Worker is also reachable at `<name>.<account>.workers.dev` (each environment must set `workersDev: true`), which would put the whole API on an origin the config never named — outside your custom-domain TLS policy, WAF rules, and CSP origins. So the generated worker answers only on hostnames the config claims: every generated route (`domain`, `api.domain`, `auth.domain`, `cms.domain`, `account.domain`, `account.adminDomain`, `apps.*` domains and aliases, explicit `providers.runtime.config.routes`) plus every hostname a named environment claims under `environments.<name>.domains`. Any other host gets `404 NOT_FOUND` before routing:
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
curl https://my-api.my-account.workers.dev/health # → 404 {"code":"NOT_FOUND","layer":"route","host":"…"}
|
|
287
|
+
curl https://api.example.com/health # → 200
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
The gate is extended at runtime, without a recompile, by loopback hosts (`wrangler dev`), the `BETTER_AUTH_URL` host, and every entry in `EXTRA_APP_HOSTS` (below). A wildcard route host (`*.example.com`) is a suffix match. A project with no custom hostnames at all is workers.dev-only by design and has no gate. Durable Objects, queues and cron handlers are not affected — only the `fetch` entry.
|
|
291
|
+
|
|
281
292
|
## Preview Deploys
|
|
282
293
|
|
|
283
294
|
The same compiled bundle can be deployed to additional hostnames — preview environments, staging, per-PR URLs — without recompiling. Set the `EXTRA_APP_HOSTS` env var on the deploy target (a comma-separated list of hostnames) and the worker treats each one like an entry in `apps[*].domain`:
|
|
284
295
|
|
|
296
|
+
- The host allowlist admits the hostname.
|
|
285
297
|
- Apps hostname middleware serves the SPA at root.
|
|
286
|
-
- CORS trusts requests whose `Origin` hostname matches
|
|
298
|
+
- CORS trusts requests whose `Origin` hostname matches — over `https://` only
|
|
299
|
+
(plain `http://` is accepted for loopback hosts, for local development).
|
|
287
300
|
- Better Auth's own origin check (independent of CORS) trusts each hostname as
|
|
288
301
|
an `https://` origin — an entry with an explicit scheme is used verbatim.
|
|
289
302
|
|
|
@@ -124,6 +124,7 @@ There is no same-second gap: markers are epoch milliseconds (written `m<ms>`), t
|
|
|
124
124
|
|
|
125
125
|
Revocation stamps are written **automatically** on:
|
|
126
126
|
|
|
127
|
+
- every session deletion — sign-out, `revoke-session(s)`, `revoke-other-sessions`, password reset (token and email-OTP flows), `delete-user`, the admin plugin's `revoke-user-session(s)` and `stop-impersonating`, and any project code that deletes a session row through the Better Auth adapter. The stamp is written from `databaseHooks.session.delete.before`, so it fires once per deleted row on every path, present and future
|
|
127
128
|
- user ban
|
|
128
129
|
- the target of the admin plugin's `/admin/set-role`, `/admin/remove-user`, `/admin/update-user`, and `/admin/revoke-user-sessions`
|
|
129
130
|
- every [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound) write (ban, role change, account deletion)
|
|
@@ -132,6 +133,8 @@ Revocation stamps are written **automatically** on:
|
|
|
132
133
|
|
|
133
134
|
The generated `src/lib/jwt-revocation.ts` exports `revokeUserTokens`, `revokeMemberTokens`, and `revokeScopeTokens` for explicit calls from your own action code.
|
|
134
135
|
|
|
136
|
+
Independently of revocation, a JWT **never outlives the session it was minted from**: both the session-path mint (`set-auth-token`) and `GET /auth/v1/token` clamp `exp` to `min(now + expiresIn, session.expiresAt)`. A token minted in the last minutes of a session expires with it instead of running the full TTL.
|
|
137
|
+
|
|
135
138
|
> **Honest limits**
|
|
136
139
|
>
|
|
137
140
|
> The KV check revokes **per principal**, not per session, and stamps propagate cross-PoP in roughly 60 seconds — "immediate" means seconds, not instantaneous.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.70.
|
|
3
|
+
"version": "0.70.45",
|
|
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",
|
|
@@ -46,22 +46,22 @@
|
|
|
46
46
|
"bundle:examples": "npx tsx scripts/bundle-examples.ts"
|
|
47
47
|
},
|
|
48
48
|
"dependencies": {
|
|
49
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
50
|
-
"zod": "^3.25.76",
|
|
49
|
+
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
51
50
|
"esbuild": "^0.27.2",
|
|
52
51
|
"ora": "^9.0.0",
|
|
53
52
|
"picocolors": "^1.0.0",
|
|
54
|
-
"prompts": "^2.4.2"
|
|
53
|
+
"prompts": "^2.4.2",
|
|
54
|
+
"zod": "^4.6.7"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@quickback-dev/schema-engine": "workspace:*",
|
|
58
58
|
"@types/node": "^22.7.5",
|
|
59
59
|
"@types/prompts": "^2.4.9",
|
|
60
60
|
"bun-types": "^1.3.5",
|
|
61
|
-
"tsx": "^4.19.0",
|
|
62
|
-
"typescript": "^5.9.0",
|
|
63
61
|
"drizzle-kit": "0.31.10",
|
|
64
|
-
"drizzle-orm": "0.45.2"
|
|
62
|
+
"drizzle-orm": "0.45.2",
|
|
63
|
+
"tsx": "^4.19.0",
|
|
64
|
+
"typescript": "^5.9.0"
|
|
65
65
|
},
|
|
66
66
|
"peerDependencies": {
|
|
67
67
|
"typescript": ">=5.0.0 <7"
|
|
@@ -46,10 +46,13 @@ When ETags are enabled, GET responses include:
|
|
|
46
46
|
```
|
|
47
47
|
Content-Type: application/json
|
|
48
48
|
ETag: W/"a1b2c3d4e5f60718"
|
|
49
|
-
Cache-Control: no-cache
|
|
49
|
+
Cache-Control: private, no-cache
|
|
50
|
+
Vary: Authorization, Cookie
|
|
50
51
|
```
|
|
51
52
|
|
|
52
|
-
`Cache-Control: no-cache` means the browser
|
|
53
|
+
`Cache-Control: private, no-cache` means the browser **must revalidate** on every request, but can use its cached copy if the ETag matches, and no shared cache may store the response. This is the correct behavior for authenticated APIs — data is always fresh, but unchanged responses avoid re-transfer.
|
|
54
|
+
|
|
55
|
+
Every other JSON response produced under a cookie or bearer token (writes, actions, auth, admin) is sent with `Cache-Control: private, no-store` unless the route sets its own policy, and always carries `Vary: Authorization, Cookie`, so a proxy can never serve one user's body to another.
|
|
53
56
|
|
|
54
57
|
## Client usage
|
|
55
58
|
|
|
@@ -64,13 +64,18 @@ export default defineConfig({
|
|
|
64
64
|
export default defineConfig({
|
|
65
65
|
// …
|
|
66
66
|
agents: {
|
|
67
|
-
mcp: {
|
|
67
|
+
mcp: {
|
|
68
|
+
requireAuth: true, // /mcp challenges anonymous callers → interactive OAuth
|
|
69
|
+
exposeAuthTools: false, // default — Better Auth endpoints are not catalogued as tools
|
|
70
|
+
},
|
|
68
71
|
},
|
|
69
72
|
});
|
|
70
73
|
```
|
|
71
74
|
|
|
72
75
|
See [Interactive OAuth](#interactive-oauth-requireauth) below.
|
|
73
76
|
|
|
77
|
+
`exposeAuthTools` controls whether the Better Auth surface (`auth__*`, `auth_admin__*`, `auth_api_keys__*`, `auth_passkeys__*`, …) appears in the tool catalogue. It is off by default: an agent authenticates through OAuth and should not be offered credential minting (API keys), passkey enrolment, impersonation or password changes as callable tools. The REST endpoints themselves are unaffected, and the access filter below still applies when you opt in.
|
|
78
|
+
|
|
74
79
|
## The MCP server
|
|
75
80
|
|
|
76
81
|
### Tools
|
|
@@ -162,11 +162,13 @@ A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's
|
|
|
162
162
|
|
|
163
163
|
| Key | Revokes | Written automatically on |
|
|
164
164
|
|---|---|---|
|
|
165
|
-
| `qbrev:sid:<sessionId>` | every JWT minted from one Better Auth session (tokens carry the minting session as `sid` — including scope tokens from `/scope/v1/enter`, namespace mints and their refreshes) | `
|
|
165
|
+
| `qbrev:sid:<sessionId>` | every JWT minted from one Better Auth session (tokens carry the minting session as `sid` — including scope tokens from `/scope/v1/enter`, namespace mints and their refreshes) | **every session deletion**, via `databaseHooks.session.delete.before`: `sign-out`, `revoke-session(s)`, `revoke-other-sessions`, password reset (`/reset-password` and `/email-otp/reset-password` — `revokeSessionsOnPasswordReset` is on by default), `delete-user`, the admin plugin's `/admin/revoke-user-session(s)` and `/admin/stop-impersonating`, and any adapter-level session delete from your own code — a lost device's token dies with its session while the user's other devices keep theirs |
|
|
166
166
|
| `qbrev:user:<userId>` | every JWT for the user | user ban (`databaseHooks.user.update.after` — flipping `banned` stamps the key and, when outbound webhooks are enabled, emits a `user.banned` event); `revoke-sessions`, `revoke-other-sessions`, `change-password` with `revokeOtherSessions`, and `delete-user` (endpoint hooks); the **target** (`body.userId`) of the admin plugin's `/admin/set-role`, `/admin/remove-user`, `/admin/update-user`, and `/admin/revoke-user-sessions`; and every [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound) write. Call `revokeUserTokens` for custom flows |
|
|
167
167
|
| `qbrev:member:<userId>:<orgId>` | the user's org-membership claims | member removal / role change (Better Auth `organizationHooks`) |
|
|
168
168
|
| `qbrev:scope:<userId>:<kind>:<id>` | the user's carried scope claim | UPDATE/DELETE of a scope-conferring relationship row (audit-wrapper chokepoint + the single DELETE route) |
|
|
169
169
|
|
|
170
|
+
Separately from revocation, every mint clamps `exp` to the session's own `expiresAt`, so a JWT can never outlive the session it came from.
|
|
171
|
+
|
|
170
172
|
`src/lib/jwt-revocation.ts` exports `revokeUserTokens` / `revokeSessionTokens` / `revokeMemberTokens` / `revokeScopeTokens` for explicit calls from actions. A rejected token falls through to session auth, which re-checks membership and re-mints — an active legitimate session recovers transparently.
|
|
171
173
|
|
|
172
174
|
Semantics worth knowing:
|
|
@@ -278,12 +278,25 @@ Every environment runs the *same* compiled Worker, so hostname-sensitive behavio
|
|
|
278
278
|
|
|
279
279
|
Each target's `BETTER_AUTH_URL` also defaults to the hostname it claims (unified → auth → API → UI), so a dev deploy authenticates against its own origin instead of production's. Setting `worker.vars.BETTER_AUTH_URL` explicitly still wins.
|
|
280
280
|
|
|
281
|
+
## Host allowlist
|
|
282
|
+
|
|
283
|
+
A Worker is also reachable at `<name>.<account>.workers.dev` (each environment must set `workersDev: true`), which would put the whole API on an origin the config never named — outside your custom-domain TLS policy, WAF rules, and CSP origins. So the generated worker answers only on hostnames the config claims: every generated route (`domain`, `api.domain`, `auth.domain`, `cms.domain`, `account.domain`, `account.adminDomain`, `apps.*` domains and aliases, explicit `providers.runtime.config.routes`) plus every hostname a named environment claims under `environments.<name>.domains`. Any other host gets `404 NOT_FOUND` before routing:
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
curl https://my-api.my-account.workers.dev/health # → 404 {"code":"NOT_FOUND","layer":"route","host":"…"}
|
|
287
|
+
curl https://api.example.com/health # → 200
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
The gate is extended at runtime, without a recompile, by loopback hosts (`wrangler dev`), the `BETTER_AUTH_URL` host, and every entry in `EXTRA_APP_HOSTS` (below). A wildcard route host (`*.example.com`) is a suffix match. A project with no custom hostnames at all is workers.dev-only by design and has no gate. Durable Objects, queues and cron handlers are not affected — only the `fetch` entry.
|
|
291
|
+
|
|
281
292
|
## Preview Deploys
|
|
282
293
|
|
|
283
294
|
The same compiled bundle can be deployed to additional hostnames — preview environments, staging, per-PR URLs — without recompiling. Set the `EXTRA_APP_HOSTS` env var on the deploy target (a comma-separated list of hostnames) and the worker treats each one like an entry in `apps[*].domain`:
|
|
284
295
|
|
|
296
|
+
- The host allowlist admits the hostname.
|
|
285
297
|
- Apps hostname middleware serves the SPA at root.
|
|
286
|
-
- CORS trusts requests whose `Origin` hostname matches
|
|
298
|
+
- CORS trusts requests whose `Origin` hostname matches — over `https://` only
|
|
299
|
+
(plain `http://` is accepted for loopback hosts, for local development).
|
|
287
300
|
- Better Auth's own origin check (independent of CORS) trusts each hostname as
|
|
288
301
|
an `https://` origin — an entry with an explicit scheme is used verbatim.
|
|
289
302
|
|
|
@@ -124,6 +124,7 @@ There is no same-second gap: markers are epoch milliseconds (written `m<ms>`), t
|
|
|
124
124
|
|
|
125
125
|
Revocation stamps are written **automatically** on:
|
|
126
126
|
|
|
127
|
+
- every session deletion — sign-out, `revoke-session(s)`, `revoke-other-sessions`, password reset (token and email-OTP flows), `delete-user`, the admin plugin's `revoke-user-session(s)` and `stop-impersonating`, and any project code that deletes a session row through the Better Auth adapter. The stamp is written from `databaseHooks.session.delete.before`, so it fires once per deleted row on every path, present and future
|
|
127
128
|
- user ban
|
|
128
129
|
- the target of the admin plugin's `/admin/set-role`, `/admin/remove-user`, `/admin/update-user`, and `/admin/revoke-user-sessions`
|
|
129
130
|
- every [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound) write (ban, role change, account deletion)
|
|
@@ -132,6 +133,8 @@ Revocation stamps are written **automatically** on:
|
|
|
132
133
|
|
|
133
134
|
The generated `src/lib/jwt-revocation.ts` exports `revokeUserTokens`, `revokeMemberTokens`, and `revokeScopeTokens` for explicit calls from your own action code.
|
|
134
135
|
|
|
136
|
+
Independently of revocation, a JWT **never outlives the session it was minted from**: both the session-path mint (`set-auth-token`) and `GET /auth/v1/token` clamp `exp` to `min(now + expiresIn, session.expiresAt)`. A token minted in the last minutes of a session expires with it instead of running the full TTL.
|
|
137
|
+
|
|
135
138
|
> **Honest limits**
|
|
136
139
|
>
|
|
137
140
|
> The KV check revokes **per principal**, not per session, and stamps propagate cross-PoP in roughly 60 seconds — "immediate" means seconds, not instantaneous.
|