@quickback-dev/cli 0.40.2 → 0.46.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/commands/claude.d.ts.map +1 -1
- package/dist/commands/claude.js +8 -0
- package/dist/commands/claude.js.map +1 -1
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +13 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/compile.test.js +26 -21
- package/dist/commands/compile.test.js.map +1 -1
- package/dist/commands/create.js +6 -9
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/login.js +0 -9
- package/dist/commands/login.js.map +1 -1
- package/dist/commands/start.d.ts.map +1 -1
- package/dist/commands/start.js +6 -7
- package/dist/commands/start.js.map +1 -1
- package/dist/commands/whoami.d.ts.map +1 -1
- package/dist/commands/whoami.js +0 -4
- package/dist/commands/whoami.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +21 -31
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +0 -12
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +0 -10
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +13 -8
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/auth.d.ts +0 -1
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/compiler-stubs.d.ts +12 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +18 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/file-loader.d.ts +14 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +63 -9
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/skill/SKILL.md +76 -6
- package/dist/skill/docs/changelog.md +217 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +1 -2
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +7 -8
- package/dist/skill/docs/compiler/config/agents.md +49 -1
- package/dist/skill/docs/compiler/config/auth.md +20 -5
- package/dist/skill/docs/compiler/config/security.md +46 -0
- package/dist/skill/docs/compiler/definitions/access.md +1 -1
- package/dist/skill/docs/compiler/definitions/actions.md +46 -4
- package/dist/skill/docs/compiler/definitions/scopes.md +11 -3
- package/dist/skill/docs/compiler/getting-started/full-example.md +5 -3
- package/dist/skill/docs/compiler/getting-started/index.md +7 -7
- package/dist/skill/docs/compiler/getting-started/patterns.md +39 -5
- package/dist/skill/docs/compiler/getting-started/template-blog.md +65 -44
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +4 -5
- package/dist/skill/docs/compiler/getting-started/template-empty.md +7 -1
- package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +23 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +4 -10
- package/dist/skill/docs/stack/account-ui/hooks.md +24 -1
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +0 -7
- package/dist/skill/docs/stack/auth/plugins/index.md +36 -39
- package/dist/templates/registry.d.ts +0 -12
- package/dist/templates/registry.d.ts.map +1 -1
- package/dist/templates/registry.js +0 -42
- package/dist/templates/registry.js.map +1 -1
- package/package.json +1 -1
- package/src/skill/SKILL.md +76 -6
- package/src/skill/docs/changelog.md +217 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +1 -2
- package/src/skill/docs/compiler/cloud-compiler/cli.md +7 -8
- package/src/skill/docs/compiler/config/agents.md +49 -1
- package/src/skill/docs/compiler/config/auth.md +20 -5
- package/src/skill/docs/compiler/config/security.md +46 -0
- package/src/skill/docs/compiler/definitions/access.md +1 -1
- package/src/skill/docs/compiler/definitions/actions.md +46 -4
- package/src/skill/docs/compiler/definitions/scopes.md +11 -3
- package/src/skill/docs/compiler/getting-started/full-example.md +5 -3
- package/src/skill/docs/compiler/getting-started/index.md +7 -7
- package/src/skill/docs/compiler/getting-started/patterns.md +39 -5
- package/src/skill/docs/compiler/getting-started/template-blog.md +65 -44
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +4 -5
- package/src/skill/docs/compiler/getting-started/template-empty.md +7 -1
- package/src/skill/docs/compiler/getting-started/templates.md +6 -6
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +23 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +4 -10
- package/src/skill/docs/stack/account-ui/hooks.md +24 -1
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +0 -7
- package/src/skill/docs/stack/auth/plugins/index.md +36 -39
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +0 -74
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +0 -155
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +0 -74
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +0 -155
|
@@ -1,5 +1,222 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.46.0 — June 11, 2026
|
|
4
|
+
|
|
5
|
+
### Breaking: "no organization context" responses unified on HTTP 403
|
|
6
|
+
|
|
7
|
+
Generated APIs used to answer the same semantic condition — *the caller has no
|
|
8
|
+
active organization context* — with two different statuses: `400 ORG_REQUIRED`
|
|
9
|
+
from the collection list guard and the create/PUT/batch org validation, but
|
|
10
|
+
`403 ACCESS_NO_ORG` from standalone actions and `403
|
|
11
|
+
ACCESS_TENANT_SCOPE_REQUIRED` from unsafe org-scoped actions. Clients and SDKs
|
|
12
|
+
had to special-case the split.
|
|
13
|
+
|
|
14
|
+
**Breaking** — recompile + redeploy required; every "no org context" denial is
|
|
15
|
+
now **403**:
|
|
16
|
+
|
|
17
|
+
- `GET /api/v1/<resource>` (and views) without an active org or
|
|
18
|
+
`?organizationId=` → `403 ORG_REQUIRED` (was 400).
|
|
19
|
+
- `POST /`, `PUT /:id`, `POST /batch`, `PUT /batch` without an active org →
|
|
20
|
+
`403 ORG_REQUIRED` (was 400).
|
|
21
|
+
- Standalone actions (`403 ACCESS_NO_ORG`) and unsafe org-scoped actions
|
|
22
|
+
(`403 ACCESS_TENANT_SCOPE_REQUIRED`) were already 403 and are unchanged.
|
|
23
|
+
|
|
24
|
+
Error **codes are unchanged** — `ORG_REQUIRED`, `ACCESS_NO_ORG`, and
|
|
25
|
+
`ACCESS_TENANT_SCOPE_REQUIRED` keep their identities, so clients that
|
|
26
|
+
discriminate on `code` need no changes. Only clients that branch on the raw
|
|
27
|
+
`400` status for these responses must update to `403`.
|
|
28
|
+
|
|
29
|
+
### Breaking: root-mounted actions lose their nested alias URLs
|
|
30
|
+
|
|
31
|
+
A standalone action whose declared `path:` lives outside its feature prefix
|
|
32
|
+
(e.g. `path: "/reports/orders"` in the `orders` feature) mounts at the root:
|
|
33
|
+
`/api/v1/reports/orders`. That root URL is the one the OpenAPI spec, the MCP
|
|
34
|
+
surface, and the operations manifest have always advertised — but the
|
|
35
|
+
generated per-feature routes file *also* carried an undocumented, fully-gated
|
|
36
|
+
copy at the nested `/api/v1/<feature><path>` URL (e.g.
|
|
37
|
+
`/api/v1/orders/reports/orders`).
|
|
38
|
+
|
|
39
|
+
**Breaking** — the nested alias is no longer emitted. One URL per operation:
|
|
40
|
+
a root-mounted action exists only at its advertised `/api/v1<path>` mount.
|
|
41
|
+
Anything calling the unadvertised nested URL gets a 404 after recompile +
|
|
42
|
+
redeploy; switch to the documented root URL. Actions declared *under* the
|
|
43
|
+
feature prefix are untouched, and a feature whose standalone actions are all
|
|
44
|
+
root-mounted no longer emits an (empty) feature actions routes file.
|
|
45
|
+
|
|
46
|
+
## v0.45.0 — June 9, 2026
|
|
47
|
+
|
|
48
|
+
### `auth.jwt.revocationCheck: 'kv'` — sub-TTL JWT revocation
|
|
49
|
+
|
|
50
|
+
The JWT fast-path trusts signed claims for their full lifetime — that's what
|
|
51
|
+
makes it a fast-path. Until now the only revocation bounds were the TTL
|
|
52
|
+
(plain claims) and the carry-forward cap (scope claims, v0.44.0). The
|
|
53
|
+
long-promised `'kv'` mode is now real on the **Cloudflare runtime**:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
auth: { jwt: { revocationCheck: 'kv' } }
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
- **Per-principal revocation timestamps, not per-token denylists.** A
|
|
60
|
+
revocation event writes "everything for this principal minted before now is
|
|
61
|
+
dead" to the project's **existing `KV` binding** (keys prefixed `qbrev:`) —
|
|
62
|
+
nothing extra to provision. Entries self-expire after the maximum token
|
|
63
|
+
lifetime, so the store never accumulates.
|
|
64
|
+
- **The bearer fast-path checks before trusting.** A verified token whose
|
|
65
|
+
`iat` (or `sct`, for the relationship-scope claim) predates the stored
|
|
66
|
+
timestamp is rejected and falls through to session auth, which re-checks
|
|
67
|
+
membership and re-mints — an active legitimate session recovers
|
|
68
|
+
transparently. Costs 2+ edge-cached KV reads per bearer verify; the
|
|
69
|
+
explicit trade the opt-in buys.
|
|
70
|
+
- **Written automatically where revocation actually happens:** org-member
|
|
71
|
+
removal and role change (Better Auth `organizationHooks`), and
|
|
72
|
+
UPDATE/DELETE of scope-conferring relationship rows — through the same
|
|
73
|
+
audit-wrapper write chokepoint Live Views uses, plus the single DELETE
|
|
74
|
+
route (which has the row in hand but no `.returning()`). Revoke-on-touch:
|
|
75
|
+
a false positive just forces a cheap re-prove.
|
|
76
|
+
- **User bans flip automatically.** The Better Auth admin plugin's ban lands
|
|
77
|
+
as a user-row update, so a generated `databaseHooks.user.update.after` hook
|
|
78
|
+
stamps the user-level revocation the moment `banned` flips — every
|
|
79
|
+
outstanding JWT dies on its next use, and the cookie/session path already
|
|
80
|
+
rejects banned sessions, completing the lockout. When outbound webhooks are
|
|
81
|
+
configured, the same hook emits a `user.banned` event so subscribed
|
|
82
|
+
endpoints are notified.
|
|
83
|
+
- **App-code helpers** for everything else: `src/lib/jwt-revocation.ts`
|
|
84
|
+
exports `revokeUserTokens` / `revokeMemberTokens` / `revokeScopeTokens`
|
|
85
|
+
(e.g. call `revokeUserTokens` from a custom revoke-all flow).
|
|
86
|
+
- **Fails open.** A KV outage degrades revocation to the TTL /
|
|
87
|
+
carry-forward-cap bound — it never locks every bearer out.
|
|
88
|
+
|
|
89
|
+
Bun/Node + `'kv'` fails at compile time with a clear message (the store rides
|
|
90
|
+
the Cloudflare KV binding; those runtimes own immediate-revoke via the
|
|
91
|
+
cookie/session path). Default remains `'none'`; without the flag the emitted
|
|
92
|
+
middleware is byte-identical to v0.44.0.
|
|
93
|
+
|
|
94
|
+
## v0.44.0 — June 9, 2026
|
|
95
|
+
|
|
96
|
+
### Scope carry-forward is now bounded (revocation fix)
|
|
97
|
+
|
|
98
|
+
The auth middleware's rolling refresh re-signs a verified `scope` claim on
|
|
99
|
+
every authed call without re-probing the relationship — that's what lets a
|
|
100
|
+
scoped session ride past the short JWT TTL with zero per-request DB cost. But
|
|
101
|
+
unbounded, it defeated the revocation model the docs promised: a removed
|
|
102
|
+
guest/staff who kept polling got a fresh TTL on every request, so "removal
|
|
103
|
+
takes effect within one TTL" only held for *idle* clients, and the refresh
|
|
104
|
+
also bypassed the ≤180s scope-token ceiling (it re-signed with the raw
|
|
105
|
+
`auth.jwt.expiresIn`).
|
|
106
|
+
|
|
107
|
+
Scope tokens now carry a proof timestamp (`sct`), stamped exclusively by the
|
|
108
|
+
proven mint sites (`POST /scope/v1/enter` and the namespace resolver, via the
|
|
109
|
+
shared mint helper). The rolling refresh:
|
|
110
|
+
|
|
111
|
+
- **refuses once the claim's proof is older than the carry-forward cap
|
|
112
|
+
(15 minutes)** — past it, the token expires within one TTL and the client
|
|
113
|
+
re-proves via `enter` or any minting namespace route, which won't re-mint a
|
|
114
|
+
revoked role. Worst-case post-revocation window for an active client:
|
|
115
|
+
**cap + one TTL** from the last real proof, instead of unbounded.
|
|
116
|
+
- **carries `sct` forward verbatim** — the refresh can never restart the
|
|
117
|
+
window without an actual relationship probe. Claims without `sct`
|
|
118
|
+
(pre-0.44 tokens) fail closed and simply stop refreshing.
|
|
119
|
+
- **signs through the same ≤180s ceiling as the mint sites** — an
|
|
120
|
+
`auth.jwt.expiresIn` above the ceiling no longer leaks into scope-bearing
|
|
121
|
+
tokens via the refresh path.
|
|
122
|
+
|
|
123
|
+
No client changes needed: tokens renew exactly as before inside the window,
|
|
124
|
+
and re-entering is the existing flow. For tables where even the capped window
|
|
125
|
+
is too wide, gate with a `via` arm (live relationship subquery per request)
|
|
126
|
+
instead of a bare `ctx.scope.<kind>` arm; immediate revocation
|
|
127
|
+
(`auth.jwt.revocationCheck: 'kv'`) remains on the roadmap.
|
|
128
|
+
|
|
129
|
+
## v0.43.0 — June 4, 2026
|
|
130
|
+
|
|
131
|
+
### Better Auth 1.6
|
|
132
|
+
|
|
133
|
+
Generated projects are now pinned to Better Auth **1.6**. The `agents.mcp.requireAuth` work in 0.42.0 surfaced a long-standing version drift: the compiler emitted `better-auth: ^1.5.0`, but `@better-auth/oauth-provider` resolves a tree that requires `@better-auth/core ^1.6.14` and imports `@better-auth/core/utils/host` + `/redirect-uri` — subpaths that only exist in 1.6.x. The result was a `wrangler deploy` that failed at bundle time with `Could not resolve …` and never uploaded.
|
|
134
|
+
|
|
135
|
+
This release aligns the **entire** Better Auth dependency set to a coherent 1.6.9 floor so npm resolves one consistent tree:
|
|
136
|
+
|
|
137
|
+
- `better-auth`, `@better-auth/drizzle-adapter`, `@better-auth/api-key`, `@better-auth/passkey`, `@better-auth/oauth-provider` → `^1.6.9` (generated projects, the baked Docker deps, and the bundled CMS/Account SPAs).
|
|
138
|
+
- Added an explicit `kysely ^0.28.16` pin: Better Auth 1.6's migrator imports `DEFAULT_MIGRATION_TABLE` / `DEFAULT_MIGRATION_LOCK_TABLE` from kysely but doesn't *declare* kysely, so the Worker bundle needs it pinned directly.
|
|
139
|
+
|
|
140
|
+
No code migration was required — Quickback already uses `@better-auth/oauth-provider` (not the now-deprecated OIDC Provider plugin), and emits no `freshAge`/SAML usage affected by 1.6's behavioral changes. Verified end to end: a `requireAuth` project and a normal project both `npm install` a clean 1.6.14 tree and bundle with `wrangler deploy --dry-run` with zero resolution errors.
|
|
141
|
+
|
|
142
|
+
### Larger migration histories no longer hit the upload ceiling
|
|
143
|
+
|
|
144
|
+
Long-lived projects accumulate one full-schema drizzle snapshot per migration, and the whole cumulative meta payload (snapshots + journals + `.sql`, across both the auth and features dirs) is re-sent on **every** compile — even a no-schema-change one. Projects with deep migration histories were hitting the compiler's `existingFiles` size limit and failing to compile, with no schema drift and nothing to fix on their end.
|
|
145
|
+
|
|
146
|
+
The server-side ceilings are raised so this is no longer the binding constraint:
|
|
147
|
+
|
|
148
|
+
- `existingFiles` payload: **4 MiB → 16 MiB**
|
|
149
|
+
- total request body: **8 MiB → 32 MiB** (kept above the per-category limits so it doesn't trip first)
|
|
150
|
+
|
|
151
|
+
This is enforced entirely on the compiler, so no CLI upgrade is needed — the new headroom applies as soon as `compiler.quickback.dev` is on this release.
|
|
152
|
+
|
|
153
|
+
### Custom response headers (`security.headers`)
|
|
154
|
+
|
|
155
|
+
The generated Worker emitted a fixed set of security headers (CSP, HSTS,
|
|
156
|
+
`X-Content-Type-Options`, …) with no supported way to add your own — teams that
|
|
157
|
+
wanted, say, an `X-Server-Version` build stamp on every response had to
|
|
158
|
+
post-patch the generated middleware after each compile.
|
|
159
|
+
|
|
160
|
+
New `security.headers` sets arbitrary response headers natively. Values are
|
|
161
|
+
static strings or templates interpolating per-deploy Worker env vars via the
|
|
162
|
+
`{{env.VAR_NAME}}` token:
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
security: {
|
|
166
|
+
headers: {
|
|
167
|
+
// Both vars must be set, or the header is omitted entirely.
|
|
168
|
+
'X-Server-Version': '{{env.SERVER_VERSION}}+{{env.SERVER_BUILD}}',
|
|
169
|
+
'X-Powered-By': 'Quickback',
|
|
170
|
+
},
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- **Omit-if-unset** — a header that references env vars is emitted only when
|
|
175
|
+
*every* referenced var is set (non-empty) at runtime. A Worker that forgot to
|
|
176
|
+
inject the var emits no header, never `X-Server-Version: undefined`. Static
|
|
177
|
+
headers are always emitted.
|
|
178
|
+
- The value is read from `c.env` per request, so it picks up whatever Worker
|
|
179
|
+
var is injected at deploy time — nothing is baked at compile time.
|
|
180
|
+
- **Managed headers are rejected** — names owned by a dedicated `security` field
|
|
181
|
+
(CSP, HSTS, `X-Frame-Options`, `Referrer-Policy`, …) error at compile so the
|
|
182
|
+
two emitters can't race. Malformed `{{env…}}` tokens error too, rather than
|
|
183
|
+
leaking literal braces into the wire header.
|
|
184
|
+
|
|
185
|
+
Survives a clean `quickback compile` with no post-processing. See
|
|
186
|
+
[Security Headers → Custom response headers](/compiler/config/security#custom-response-headers).
|
|
187
|
+
|
|
188
|
+
## v0.42.0 — June 4, 2026
|
|
189
|
+
|
|
190
|
+
### Interactive OAuth for the generated MCP server
|
|
191
|
+
|
|
192
|
+
MCP connectors (Claude, Cursor, …) could only connect to a generated `/mcp`
|
|
193
|
+
endpoint **anonymously** — they never launched a sign-in flow, so auth-gated
|
|
194
|
+
tools stayed invisible. The OAuth machinery was already present (Better Auth's
|
|
195
|
+
`oauth-provider` ships `/oauth2/authorize`, `/token`, `/register` + PKCE under
|
|
196
|
+
`/auth/v1`); the compiler just never let a connector discover or trigger it.
|
|
197
|
+
|
|
198
|
+
New `agents.mcp.requireAuth` makes the MCP surface authenticated-only:
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
agents: { mcp: { requireAuth: true } },
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
When enabled, the compiler:
|
|
205
|
+
|
|
206
|
+
- **Challenges unauthenticated `/mcp`** with `401` + `WWW-Authenticate: Bearer
|
|
207
|
+
resource_metadata="…"` ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) §5.1) — the signal connectors use to start OAuth.
|
|
208
|
+
- **Force-enables `oauthProvider` + `bearer`**, so `/oauth2/authorize`, `/token`,
|
|
209
|
+
and `/register` ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) dynamic client registration) exist with PKCE.
|
|
210
|
+
- **Delegates `/.well-known/oauth-authorization-server`** to Better Auth's real
|
|
211
|
+
metadata instead of a hand-rolled stub that advertised a non-existent
|
|
212
|
+
authorization endpoint.
|
|
213
|
+
- Adds the `<origin>/mcp` resource to `validAudiences`
|
|
214
|
+
([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)) so the connector's access token isn't rejected.
|
|
215
|
+
|
|
216
|
+
Login and consent are served by your Account SPA, so users authenticate with
|
|
217
|
+
whatever methods you already enabled. Default is unchanged (anonymous public
|
|
218
|
+
tools); set `requireAuth: true` for servers meant for authenticated users.
|
|
219
|
+
|
|
3
220
|
## v0.40.2 — June 3, 2026
|
|
4
221
|
|
|
5
222
|
### Passwordless plugins can no longer bypass the signup gate
|
|
@@ -40,8 +40,7 @@ Credentials are stored at `~/.quickback/credentials.json`:
|
|
|
40
40
|
"user": {
|
|
41
41
|
"id": "...",
|
|
42
42
|
"email": "paul@example.com",
|
|
43
|
-
"name": "Paul Stenhouse"
|
|
44
|
-
"tier": "free"
|
|
43
|
+
"name": "Paul Stenhouse"
|
|
45
44
|
},
|
|
46
45
|
"expiresAt": "2026-02-16T01:42:21.519Z",
|
|
47
46
|
"organization": {
|
|
@@ -22,7 +22,7 @@ quickback start
|
|
|
22
22
|
|
|
23
23
|
Interactive onboarding designed for new users. No flags required.
|
|
24
24
|
|
|
25
|
-
- Prompts for a template (
|
|
25
|
+
- Prompts for a template (`cloudflare`, `todos`, `blog`, `empty`)
|
|
26
26
|
- Prompts for a project name (defaults to the current directory's name if empty)
|
|
27
27
|
- Auto-detects whether to scaffold in-place or create a `./<name>/` subdirectory
|
|
28
28
|
- Defers login until just before the compile step — cancel at the auth prompt and the scaffold stays on disk, ready for `quickback compile` later
|
|
@@ -40,11 +40,11 @@ quickback create <template> <name>
|
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
**Templates:**
|
|
43
|
-
- `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold
|
|
44
|
-
- `todos` — Working todos example with masking + actions + a named view
|
|
45
|
-
- `blog` — Single-tenant blog, PUBLIC reads, admin writes
|
|
46
|
-
- `empty` — Cloudflare scaffold, no example features
|
|
47
|
-
- `saas` — Full B2B SaaS: orgs, R2 file storage, webhooks, split databases, realtime
|
|
43
|
+
- `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold
|
|
44
|
+
- `todos` — Working todos example with masking + actions + a named view
|
|
45
|
+
- `blog` — Single-tenant blog, PUBLIC reads, admin writes
|
|
46
|
+
- `empty` — Cloudflare scaffold, no example features
|
|
47
|
+
- `saas` — Full B2B SaaS: orgs, R2 file storage, webhooks, split databases, realtime
|
|
48
48
|
|
|
49
49
|
**Example:**
|
|
50
50
|
```bash
|
|
@@ -196,8 +196,7 @@ Credentials are stored at `~/.quickback/credentials.json`:
|
|
|
196
196
|
"user": {
|
|
197
197
|
"id": "...",
|
|
198
198
|
"email": "paul@example.com",
|
|
199
|
-
"name": "Paul Stenhouse"
|
|
200
|
-
"tier": "free"
|
|
199
|
+
"name": "Paul Stenhouse"
|
|
201
200
|
},
|
|
202
201
|
"expiresAt": "2026-02-16T01:42:21.519Z",
|
|
203
202
|
"organization": {
|
|
@@ -11,7 +11,7 @@ When `agents` is enabled (the default), the Worker serves:
|
|
|
11
11
|
| `GET /robots.txt` | AI-bot policy with the [Cloudflare Content Signals](https://developers.cloudflare.com/bots/concepts/content-signals/) preamble and explicit `Allow:` rules for GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, Applebot-Extended, Bytespider, MistralAI, Cohere, DuckAssist. |
|
|
12
12
|
| `GET /llms.txt` | Agent-facing summary of the API — project name, authentication, resource list, endpoint conventions — derived from your own config. |
|
|
13
13
|
| `GET /.well-known/oauth-protected-resource` | [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) metadata declaring this Worker as a protected resource. |
|
|
14
|
-
| `GET /.well-known/oauth-authorization-server` | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) metadata
|
|
14
|
+
| `GET /.well-known/oauth-authorization-server` | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) authorization-server metadata. When the `oauthProvider` plugin is enabled it **delegates to Better Auth's real OAuth 2.1 surface** (`/oauth2/authorize`, `/oauth2/token`, `/oauth2/register` dynamic client registration, PKCE); otherwise it advertises only the truthful token-mint subset. |
|
|
15
15
|
| `GET /.well-known/api-catalog` | [RFC 9727](https://datatracker.ietf.org/doc/html/rfc9727) catalog linking at `/openapi.json`. |
|
|
16
16
|
| `GET /.well-known/mcp.json` | MCP Server Card — discoverable metadata for the MCP server below. |
|
|
17
17
|
| `POST /mcp` | Auto-generated MCP-over-HTTP server. One tool per OpenAPI operation, JWT auth forwarded through the same middleware as the REST API. |
|
|
@@ -57,6 +57,19 @@ export default defineConfig({
|
|
|
57
57
|
});
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
+
`mcp` also accepts an object for an authenticated-only MCP surface:
|
|
61
|
+
|
|
62
|
+
```ts title="quickback.config.ts"
|
|
63
|
+
export default defineConfig({
|
|
64
|
+
// …
|
|
65
|
+
agents: {
|
|
66
|
+
mcp: { requireAuth: true }, // /mcp challenges anonymous callers → interactive OAuth
|
|
67
|
+
},
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
See [Interactive OAuth](#interactive-oauth-requireauth) below.
|
|
72
|
+
|
|
60
73
|
## The MCP server
|
|
61
74
|
|
|
62
75
|
### Tools
|
|
@@ -90,6 +103,41 @@ curl -X POST https://my-api.example.com/api/v1/token \
|
|
|
90
103
|
-H "Content-Type: application/json"
|
|
91
104
|
```
|
|
92
105
|
|
|
106
|
+
### Interactive OAuth (`requireAuth`)
|
|
107
|
+
|
|
108
|
+
Statically pasting a Bearer token works, but it isn't how an MCP connector wants to authenticate — it expects to **launch a sign-in flow**. By default `/mcp` serves an anonymous session (the access-filtered public tool list), and a connector that never sees an auth challenge never offers to sign in. Set `agents.mcp.requireAuth: true` to turn `/mcp` into an authenticated-only endpoint:
|
|
109
|
+
|
|
110
|
+
```ts title="quickback.config.ts"
|
|
111
|
+
export default defineConfig({
|
|
112
|
+
// …
|
|
113
|
+
agents: { mcp: { requireAuth: true } },
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
This does three things:
|
|
118
|
+
|
|
119
|
+
1. **Force-enables the `oauthProvider` + `bearer` Better Auth plugins** — so `/oauth2/authorize`, `/oauth2/token`, and `/oauth2/register` ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) dynamic client registration) exist for a connector to discover, with PKCE.
|
|
120
|
+
2. **Challenges unauthenticated `/mcp` requests** with `401` and a `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource"` header ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) §5.1). This is the signal MCP connectors use to start OAuth.
|
|
121
|
+
3. **Makes the root `/.well-known/oauth-authorization-server` doc delegate to Better Auth's real metadata**, so discovery resolves to working `/oauth2/*` endpoints instead of a hand-rolled stub.
|
|
122
|
+
|
|
123
|
+
The full handshake a connector runs:
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
POST /mcp (no token)
|
|
127
|
+
→ 401 + WWW-Authenticate: resource_metadata="…/.well-known/oauth-protected-resource"
|
|
128
|
+
GET /.well-known/oauth-protected-resource → authorization_servers: [<origin>]
|
|
129
|
+
GET /.well-known/oauth-authorization-server → authorize/token/register + PKCE
|
|
130
|
+
POST /oauth2/register → dynamic client registration
|
|
131
|
+
GET /oauth2/authorize?code_challenge=… → redirect to your Account login → consent
|
|
132
|
+
POST /oauth2/token (code + code_verifier) → access token
|
|
133
|
+
POST /mcp (Bearer access token) → authenticated tool list
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The login and consent screens are served by your [Account SPA](/stack/account-ui) (`ACCOUNT_URL/login`, `ACCOUNT_URL/consent`), so users sign in with whatever methods you already enabled (Google, GitHub, email, passkey). No connector-specific configuration is required — adding the server URL is enough.
|
|
137
|
+
|
|
138
|
+
> `requireAuth` removes anonymous public-tool access over `/mcp`. Use it when the MCP surface is meant for authenticated users; leave it off (the default) for servers that expose genuinely public tools.
|
|
139
|
+
|
|
140
|
+
|
|
93
141
|
### Connecting clients
|
|
94
142
|
|
|
95
143
|
**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
@@ -81,12 +81,27 @@ Default `'none'`.
|
|
|
81
81
|
|
|
82
82
|
| Value | Behavior | Cost per verify |
|
|
83
83
|
|---|---|---|
|
|
84
|
-
| `'none'` | No revocation check. Stolen tokens valid until TTL expires. Use a low `expiresIn` to bound the replay window. | 0 |
|
|
85
|
-
| `'kv'` | Fast-path
|
|
84
|
+
| `'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 |
|
|
85
|
+
| `'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) |
|
|
86
86
|
|
|
87
|
-
|
|
87
|
+
`'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.
|
|
88
88
|
|
|
89
|
-
|
|
89
|
+
A token is rejected when its mint timestamp (`iat`, or `sct` for the relationship-scope claim) predates the stored timestamp for any principal key it rides on:
|
|
90
|
+
|
|
91
|
+
| Key | Revokes | Written automatically on |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| `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). Call `revokeUserTokens` for custom flows (revoke-all, etc.) |
|
|
94
|
+
| `qbrev:member:<userId>:<orgId>` | the user's org-membership claims | member removal / role change (Better Auth `organizationHooks`) |
|
|
95
|
+
| `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) |
|
|
96
|
+
|
|
97
|
+
`src/lib/jwt-revocation.ts` exports `revokeUserTokens` / `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.
|
|
98
|
+
|
|
99
|
+
Semantics worth knowing:
|
|
100
|
+
|
|
101
|
+
- **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).
|
|
102
|
+
- **Fails open:** a missing binding or KV outage skips the check (logged) — revocation degrades to the TTL / carry-forward-cap bound rather than locking every bearer out.
|
|
103
|
+
- **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.
|
|
104
|
+
- **Coverage gap:** batch *hard* deletes don't return rows through the chokepoint; call `revokeScopeTokens` explicitly if you bulk-hard-delete conferring rows.
|
|
90
105
|
|
|
91
106
|
## Defaults preserve 0.10.13 behavior
|
|
92
107
|
|
|
@@ -106,7 +121,7 @@ Adding the `auth.jwt` block without setting any field is a no-op vs. the 0.10.13
|
|
|
106
121
|
- **B2C SaaS, mostly browser traffic:** keep defaults. The 180s TTL + auto-refresh model just works.
|
|
107
122
|
- **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.
|
|
108
123
|
- **CLI-heavy / long-running CI tokens:** `expiresIn: 3600` for one-hour bearer tokens. Pair with `issuer` / `audience` if multiple services consume the same JWT.
|
|
109
|
-
- **Need immediate revocation:**
|
|
124
|
+
- **Need immediate revocation:** set `revocationCheck: 'kv'` (Cloudflare runtime). Or drop TTL to ~30s — similar effect with bounded delay and zero KV reads.
|
|
110
125
|
|
|
111
126
|
## `auth.loginUrl` / `auth.profileUrl` — external sign-in for consumer Workers
|
|
112
127
|
|
|
@@ -225,6 +225,52 @@ security: {
|
|
|
225
225
|
|
|
226
226
|
The compiler encodes the wire syntax (which differs from CSP — values use `()`, not space-separated tokens, with bareword `self` and quoted URLs).
|
|
227
227
|
|
|
228
|
+
## Custom response headers
|
|
229
|
+
|
|
230
|
+
`security.headers` sets arbitrary response headers on every response, alongside the managed security headers. Keys are header names; values are static strings or templates that interpolate per-deploy Worker env vars via the `{{env.VAR_NAME}}` token.
|
|
231
|
+
|
|
232
|
+
```ts title="quickback.config.ts"
|
|
233
|
+
security: {
|
|
234
|
+
headers: {
|
|
235
|
+
// Stamp the deployed build identity. Read from Worker vars at runtime,
|
|
236
|
+
// so the value tracks whatever you inject at deploy time.
|
|
237
|
+
'X-Server-Version': '{{env.SERVER_VERSION}}+{{env.SERVER_BUILD}}',
|
|
238
|
+
|
|
239
|
+
// Static value — always emitted.
|
|
240
|
+
'X-Powered-By': 'Quickback',
|
|
241
|
+
},
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
The canonical use case is exposing a build/version identity on every response so clients (`curl -I`, mobile apps, dashboards) can read the running build without a body request — and so you can detect drift between what's deployed and what git/CF report.
|
|
246
|
+
|
|
247
|
+
### Omit-if-unset
|
|
248
|
+
|
|
249
|
+
A header whose value references env vars is emitted **only when every referenced var is set** (non-`undefined`, non-empty string) at runtime. A version header on a Worker that forgot to inject the var simply doesn't appear — never `X-Server-Version: undefined`. Static headers (no `{{env…}}`) are always emitted.
|
|
250
|
+
|
|
251
|
+
The value is read from `c.env` per request, so you don't declare these vars at compile time — inject them as Worker vars (`[vars]` in `wrangler.toml`, or `--var` at deploy) and the header picks them up.
|
|
252
|
+
|
|
253
|
+
### Generated middleware
|
|
254
|
+
|
|
255
|
+
For the config above, the compiler appends this to the security-headers middleware — no post-compile patching:
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
// Custom response headers (security.headers).
|
|
259
|
+
{
|
|
260
|
+
const v0 = (c.env as unknown as Record<string, string | undefined>)["SERVER_VERSION"];
|
|
261
|
+
const v1 = (c.env as unknown as Record<string, string | undefined>)["SERVER_BUILD"];
|
|
262
|
+
if (v0 != null && v0 !== '' && v1 != null && v1 !== '') {
|
|
263
|
+
c.header("X-Server-Version", `${v0}+${v1}`);
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
c.header("X-Powered-By", "Quickback");
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Rules
|
|
270
|
+
|
|
271
|
+
- **Header names** must be valid HTTP field tokens. Names already managed by a dedicated `security` field — `Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`, `X-Content-Type-Options`, `Cross-Origin-Opener-Policy`/`-Embedder-Policy`/`-Resource-Policy`, `Referrer-Policy`, `Permissions-Policy` — are rejected; use that field instead so the two emitters don't race.
|
|
272
|
+
- **Only `{{env.VAR_NAME}}`** interpolation is supported (`VAR_NAME` is a valid env-var identifier). A malformed token (`{{env.FOO}`, `{{ENV.FOO}}`) is a compile-time error rather than leaking literal braces into the wire header.
|
|
273
|
+
|
|
228
274
|
## Compile-time lint rules
|
|
229
275
|
|
|
230
276
|
The compiler walks the resolved config and emits warnings (or errors) for known footguns. Errors block compile; warnings print to stderr.
|
|
@@ -159,7 +159,7 @@ For org-scoped tables, `PUBLIC` routes still filter by organization. Since the u
|
|
|
159
159
|
GET /api/v1/listings?organizationId=org_abc123
|
|
160
160
|
```
|
|
161
161
|
|
|
162
|
-
The firewall WHERE clause is always enforced. If no `organizationId` is provided, the API returns a `
|
|
162
|
+
The firewall WHERE clause is always enforced. If no `organizationId` is provided, the API returns a `403` with code `ORG_REQUIRED`.
|
|
163
163
|
|
|
164
164
|
```typescript
|
|
165
165
|
// Public listing page — anyone can browse, but scoped to an org
|
|
@@ -517,7 +517,7 @@ Use `$ctx` to reference the current user's context:
|
|
|
517
517
|
access: {
|
|
518
518
|
record: {
|
|
519
519
|
ownerId: { equals: "$ctx.userId" },
|
|
520
|
-
|
|
520
|
+
organizationId: { equals: "$ctx.activeOrgId" }
|
|
521
521
|
}
|
|
522
522
|
}
|
|
523
523
|
```
|
|
@@ -790,7 +790,7 @@ import type { Auth } from "better-auth";
|
|
|
790
790
|
interface ActionExecutorParams {
|
|
791
791
|
db: DrizzleDB; // Scoped database (auto-applies org/owner/soft-delete filters)
|
|
792
792
|
unsafeDb?: DrizzleDB; // Unscoped database (only available when unsafe mode is enabled)
|
|
793
|
-
ctx: AppContext; // User context (userId, roles,
|
|
793
|
+
ctx: AppContext; // User context (userId, roles, activeOrgId, activeTeamId, userRole)
|
|
794
794
|
record?: TRecord; // The record (record-based only, undefined for standalone)
|
|
795
795
|
input: TInput; // Validated input from Zod schema
|
|
796
796
|
services: TServices; // Configured integrations (billing, notifications, etc.)
|
|
@@ -884,6 +884,45 @@ always reflects the real actor and the real moment.
|
|
|
884
884
|
the parameter is typed as optional. `whereTransition` extends `whereRecord`
|
|
885
885
|
with the transition's "from" precondition for transition actions.
|
|
886
886
|
|
|
887
|
+
#### Reaching Better Auth tables (`authDb`)
|
|
888
|
+
|
|
889
|
+
The scoped `db` only sees your feature tables. To read Better Auth tables —
|
|
890
|
+
users, organizations, members — use the auth database connection from the
|
|
891
|
+
Hono context plus the generated `lib/org-access.ts` helper:
|
|
892
|
+
|
|
893
|
+
```typescript
|
|
894
|
+
// features/projects/actions/assign.ts — validate a userId is an org member
|
|
895
|
+
import { z } from "zod";
|
|
896
|
+
import { eq } from "drizzle-orm";
|
|
897
|
+
import { ActionError } from "@quickback/compiler";
|
|
898
|
+
import { defineAction } from "../.quickback/define-action";
|
|
899
|
+
import { getOrgMemberRole } from "../../../lib/org-access";
|
|
900
|
+
import { projects } from "../projects";
|
|
901
|
+
|
|
902
|
+
export default defineAction({
|
|
903
|
+
description: "Assign a project to an org member",
|
|
904
|
+
input: z.object({ assigneeId: z.string() }),
|
|
905
|
+
access: { roles: ["member", "admin"] },
|
|
906
|
+
async execute({ db, record, input, ctx, c, whereRecord }) {
|
|
907
|
+
// getOrgMemberRole(authDb, userId, organizationId) → role string | null
|
|
908
|
+
const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activeOrgId!);
|
|
909
|
+
if (!role) {
|
|
910
|
+
throw new ActionError("Assignee is not a member of this organization", "NOT_A_MEMBER", 400);
|
|
911
|
+
}
|
|
912
|
+
const [updated] = await db
|
|
913
|
+
.update(projects)
|
|
914
|
+
.set({ assigneeId: input.assigneeId })
|
|
915
|
+
.where(whereRecord!(projects))
|
|
916
|
+
.returning();
|
|
917
|
+
return updated;
|
|
918
|
+
},
|
|
919
|
+
});
|
|
920
|
+
```
|
|
921
|
+
|
|
922
|
+
`c.get("authDb")` is the Drizzle connection to the auth database (in dual-DB
|
|
923
|
+
mode it's a separate D1 from your features). For richer queries, import the
|
|
924
|
+
auth schema tables from `../../../auth/schema` and query `authDb` directly.
|
|
925
|
+
|
|
887
926
|
## HTTP API Reference
|
|
888
927
|
|
|
889
928
|
### Request Format
|
|
@@ -953,7 +992,7 @@ async execute({ ctx, record, input, c }) {
|
|
|
953
992
|
**Option 2: Throw an ActionError**
|
|
954
993
|
|
|
955
994
|
```typescript
|
|
956
|
-
import { ActionError } from "@quickback/
|
|
995
|
+
import { ActionError } from "@quickback/compiler";
|
|
957
996
|
|
|
958
997
|
async execute({ ctx, record, input }) {
|
|
959
998
|
if (record.stage === 'hired') {
|
|
@@ -965,7 +1004,10 @@ async execute({ ctx, record, input }) {
|
|
|
965
1004
|
}
|
|
966
1005
|
```
|
|
967
1006
|
|
|
968
|
-
The `ActionError` constructor signature is `(message, code, statusCode, details?)`.
|
|
1007
|
+
The `ActionError` constructor signature is `(message, code, statusCode = 400, details?)`. The compile step rewrites the `@quickback/compiler` import to the generated runtime class (`src/lib/types.ts`), and the route handler catches it by name and returns `{ error, code, details }` with your `statusCode`.
|
|
1008
|
+
|
|
1009
|
+
> Do **not** throw Hono's `HTTPException` from an action — the route handler doesn't unwrap it, so it surfaces as an unhandled **500 ACTION_EXECUTION_FAILED**. Use `ActionError` (or return `c.json(...)` directly) for clean 4xx responses.
|
|
1010
|
+
|
|
969
1011
|
|
|
970
1012
|
## Protected Fields
|
|
971
1013
|
|
|
@@ -56,7 +56,7 @@ The server probes **every declared role** for the proposed instance (one DB touc
|
|
|
56
56
|
"scope": { "event": { "id": "evt_123", "roles": ["attendee", "shuttleDriver"], "shuttleId": "shA" } }
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
The client sends that JWT as `Authorization: Bearer …` on subsequent requests. The auth middleware verifies the signature and sets `ctx.scope` — **no DB**. The claim is carried forward on every authed call (rolling refresh)
|
|
59
|
+
The client sends that JWT as `Authorization: Bearer …` on subsequent requests. The auth middleware verifies the signature and sets `ctx.scope` — **no DB**. The claim is carried forward on every authed call (rolling refresh) for up to **15 minutes from the last actual relationship proof** — the mint stamps a proof timestamp (`sct`) that the refresh carries forward verbatim and checks against the carry-forward cap. Past the cap the refresh stops, the token expires within one TTL, and the client re-proves via `enter` (or any namespace route that mints) to restart the window.
|
|
60
60
|
|
|
61
61
|
> **Invariant:** the client only *proposes* the instance id (from the URL). The server proves membership before signing. No client-asserted scope is ever trusted.
|
|
62
62
|
|
|
@@ -311,13 +311,21 @@ forge a scope role — the guard, not the flag, is the gate.
|
|
|
311
311
|
|
|
312
312
|
### TTL and best-effort semantics
|
|
313
313
|
|
|
314
|
-
- **TTL is the scope-token TTL** — `auth.jwt.expiresIn` (default 180s), **clamped to a hard ≤180s ceiling** at the
|
|
314
|
+
- **TTL is the scope-token TTL** — `auth.jwt.expiresIn` (default 180s), **clamped to a hard ≤180s ceiling** at every signing site that emits a scope claim: both proven mints (`/scope/v1/enter`, the namespace resolver) *and* the middleware's rolling refresh. A longer-lived scope token would widen the post-revocation replay window past the spec bound, so the clamp is non-negotiable — an `auth.jwt.expiresIn` above the ceiling applies to plain tokens but never survives into a scope-bearing one.
|
|
315
315
|
- **The mint is gated by the same proven-relationship guard as the in-memory stamp.** It runs *after* the gate has granted access, reading the instance id from the proven path param (`:eventId`) — never from request input — so the minted `scope:<kind>:<role>` is backed by exactly the proof `/scope/v1/enter` requires. The token is **byte-identical** to one `/scope/v1/enter` would produce: same shared mint helper, same carry-forward of any *other* verified scope kinds already on the incoming token (the freshly-proven kind takes precedence; siblings survive the re-mint).
|
|
316
316
|
- **The mint is best-effort.** A mint failure (e.g. a missing signing secret) **never fails the request** — the in-memory stamp already authorized it; the caller simply doesn't receive a refreshed token on that response and can fall back to `/scope/v1/enter`.
|
|
317
317
|
|
|
318
318
|
## Revocation & TTL
|
|
319
319
|
|
|
320
|
-
The scope claim is trusted
|
|
320
|
+
The scope claim is trusted between proofs — it is never re-checked against the database while it rides. Two bounds keep that window finite:
|
|
321
|
+
|
|
322
|
+
- **The TTL** (default 180s, `auth.jwt.expiresIn`, clamped ≤180s on scope-bearing tokens) bounds an *idle* client: a token that stops being used dies within one TTL.
|
|
323
|
+
- **The carry-forward cap** (15 minutes) bounds an *active* client: the rolling refresh re-signs the claim on every authed call, but only while the claim's proof timestamp (`sct`, stamped exclusively by the proven mint sites) is younger than the cap. Past it the refresh refuses, the token expires, and the next `enter` (or namespace-route mint) re-probes the relationship — which won't re-mint a revoked role.
|
|
324
|
+
|
|
325
|
+
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:
|
|
326
|
+
|
|
327
|
+
- **`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](/compiler/config/auth).
|
|
328
|
+
- **`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.
|
|
321
329
|
|
|
322
330
|
## Reference
|
|
323
331
|
|
|
@@ -60,10 +60,12 @@ export default feature('candidates', {
|
|
|
60
60
|
// WRITE OPERATIONS
|
|
61
61
|
create: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
62
62
|
update: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
63
|
-
delete: { access: { roles: ['hiring-manager'] }, mode: '
|
|
63
|
+
delete: { access: { roles: ['hiring-manager'] }, mode: 'soft' },
|
|
64
64
|
});
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
+
> `mode: 'hard'` is also available, but hard deletes erase the row — so they require the security-audit pipeline. On D1 that means setting `auditDatabaseId` on the database provider config (the compiler errors with setup instructions if it's missing).
|
|
68
|
+
|
|
67
69
|
> Prefer the explicit two-export form (or interop with existing Drizzle schemas)? See [feature() — single-export sugar](/compiler/definitions/feature) and [Schema: choosing between `q` and Drizzle](/compiler/definitions/schema#choosing-between-q-and-drizzle). All forms compile identically; mix freely per file.
|
|
68
70
|
|
|
69
71
|
---
|
|
@@ -75,7 +77,7 @@ Run `quickback compile` and Quickback generates production-ready code.
|
|
|
75
77
|
### Security Helpers
|
|
76
78
|
|
|
77
79
|
```typescript title="src/features/candidates/candidates.resource.ts"
|
|
78
|
-
import { eq, and } from 'drizzle-orm';
|
|
80
|
+
import { eq, and, isNull } from 'drizzle-orm';
|
|
79
81
|
import { candidates } from './schema';
|
|
80
82
|
import type { AppContext } from '../../lib/types';
|
|
81
83
|
import { masks } from '../../lib/masks';
|
|
@@ -213,7 +215,7 @@ export function maskCandidates<T extends Record<string, any>>(
|
|
|
213
215
|
export const CRUD_ACCESS = {
|
|
214
216
|
create: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
215
217
|
update: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
216
|
-
delete: { access: { roles: ['hiring-manager'] }, mode: '
|
|
218
|
+
delete: { access: { roles: ['hiring-manager'] }, mode: 'soft' },
|
|
217
219
|
};
|
|
218
220
|
|
|
219
221
|
// Views configuration (read pipeline)
|
|
@@ -25,11 +25,11 @@ Both paths scaffold the same project:
|
|
|
25
25
|
- Working example feature with full security configuration (when you pick `todos`/`blog`/`saas`)
|
|
26
26
|
|
|
27
27
|
**Available templates:**
|
|
28
|
-
- `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold
|
|
29
|
-
- `todos` — Working CRUD example with masking + actions
|
|
30
|
-
- `blog` — Single-tenant blog, PUBLIC reads, admin writes
|
|
31
|
-
- `empty` — Cloudflare scaffold, no example features
|
|
32
|
-
- `saas` — Full B2B SaaS with orgs, R2 file storage, webhooks
|
|
28
|
+
- `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold
|
|
29
|
+
- `todos` — Working CRUD example with masking + actions
|
|
30
|
+
- `blog` — Single-tenant blog, PUBLIC reads, admin writes
|
|
31
|
+
- `empty` — Cloudflare scaffold, no example features
|
|
32
|
+
- `saas` — Full B2B SaaS with orgs, R2 file storage, webhooks
|
|
33
33
|
|
|
34
34
|
## File Structure
|
|
35
35
|
|
|
@@ -153,12 +153,12 @@ After `quickback compile` and `npm run dev`, your API is running locally. Open a
|
|
|
153
153
|
|
|
154
154
|
```bash
|
|
155
155
|
# 1. Create a user account
|
|
156
|
-
curl -X POST http://localhost:8787/
|
|
156
|
+
curl -X POST http://localhost:8787/auth/v1/sign-up/email \
|
|
157
157
|
-H "Content-Type: application/json" \
|
|
158
158
|
-d '{"email": "admin@example.com", "password": "securepassword123", "name": "Admin"}'
|
|
159
159
|
|
|
160
160
|
# 2. Sign in and get a session token
|
|
161
|
-
curl -X POST http://localhost:8787/
|
|
161
|
+
curl -X POST http://localhost:8787/auth/v1/sign-in/email \
|
|
162
162
|
-H "Content-Type: application/json" \
|
|
163
163
|
-d '{"email": "admin@example.com", "password": "securepassword123"}'
|
|
164
164
|
# → Response includes a session token in Set-Cookie header
|