@quickback-dev/cli 0.67.1 → 0.67.2
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/batch-operations.md +5 -0
- package/dist/skill/docs/api/errors.md +7 -4
- package/dist/skill/docs/configure/auth.md +26 -0
- package/dist/skill/docs/configure/index.md +28 -9
- package/dist/skill/docs/define/access.md +15 -2
- package/dist/skill/docs/define/authz-roles.md +1 -1
- package/dist/skill/docs/define/encryption.md +39 -7
- package/dist/skill/docs/define/firewall.md +6 -0
- package/dist/skill/docs/define/schema.md +31 -2
- package/dist/skill/docs/platform/auth/api-keys.md +77 -1
- package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/dist/skill/docs/platform/auth/plugins/index.md +33 -34
- package/dist/skill/docs/platform/auth/security.md +53 -6
- package/dist/skill/docs/platform/auth/using-auth.md +1 -1
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +2 -0
- package/dist/skill/docs/platform/storage/r2.md +2 -0
- package/dist/skill/docs/platform/storage/using-kv.md +6 -36
- package/dist/skill/docs/platform/webhooks/inbound.md +2 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +4 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +12 -8
- package/dist/skill/docs/ui/account/features/api-keys.md +2 -1
- package/dist/skill/docs/ui/account/features/index.md +7 -6
- package/dist/skill/docs/ui/account/features/passwordless.md +1 -1
- package/dist/skill/docs/ui/account/hooks.md +1 -1
- package/dist/skill/docs/ui/account/index.md +2 -2
- package/dist/skill/docs/ui/admin/actions.md +2 -1
- package/package.json +1 -1
- package/src/skill/docs/api/batch-operations.md +5 -0
- package/src/skill/docs/api/errors.md +7 -4
- package/src/skill/docs/configure/auth.md +26 -0
- package/src/skill/docs/configure/index.md +28 -9
- package/src/skill/docs/define/access.md +15 -2
- package/src/skill/docs/define/authz-roles.md +1 -1
- package/src/skill/docs/define/encryption.md +39 -7
- package/src/skill/docs/define/firewall.md +6 -0
- package/src/skill/docs/define/schema.md +31 -2
- package/src/skill/docs/platform/auth/api-keys.md +77 -1
- package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/src/skill/docs/platform/auth/plugins/index.md +33 -34
- package/src/skill/docs/platform/auth/security.md +53 -6
- package/src/skill/docs/platform/auth/using-auth.md +1 -1
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +2 -0
- package/src/skill/docs/platform/storage/r2.md +2 -0
- package/src/skill/docs/platform/storage/using-kv.md +6 -36
- package/src/skill/docs/platform/webhooks/inbound.md +2 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +4 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +12 -8
- package/src/skill/docs/ui/account/features/api-keys.md +2 -1
- package/src/skill/docs/ui/account/features/index.md +7 -6
- package/src/skill/docs/ui/account/features/passwordless.md +1 -1
- package/src/skill/docs/ui/account/hooks.md +1 -1
- package/src/skill/docs/ui/account/index.md +2 -2
- package/src/skill/docs/ui/admin/actions.md +2 -1
|
@@ -40,6 +40,8 @@ export default defineConfig({
|
|
|
40
40
|
- `POST /auth/v1/email-otp/send-verification-otp`
|
|
41
41
|
- `POST /auth/v1/email-otp/verify-otp`
|
|
42
42
|
|
|
43
|
+
Codes are stored hashed and expire after 300 seconds by default; set `plugins: { emailOtp: { expiresIn: 600 } }` to change it — the email states the configured lifetime.
|
|
44
|
+
|
|
43
45
|
**Email readiness check:**
|
|
44
46
|
|
|
45
47
|
Use this to show UI warnings when SES isn't configured.
|
|
@@ -67,11 +69,12 @@ auth: defineAuth("better-auth", {
|
|
|
67
69
|
}),
|
|
68
70
|
```
|
|
69
71
|
|
|
70
|
-
> `emailOtp.disableSignUp` **inherits
|
|
71
|
-
>
|
|
72
|
-
>
|
|
73
|
-
> `
|
|
74
|
-
>
|
|
72
|
+
> `emailOtp.disableSignUp` **inherits `emailAndPassword.disableSignUp: true`**, so
|
|
73
|
+
> the OTP path can't bypass a hard password-signup block. Set
|
|
74
|
+
> `emailOtp: { disableSignUp: false }` explicitly to opt the OTP path back open.
|
|
75
|
+
> `account.auth.signup: false` is different: it sets the invite-only
|
|
76
|
+
> [signup policy](/platform/auth/security#signup-policy), which covers every
|
|
77
|
+
> sign-in method and still admits invitees.
|
|
75
78
|
|
|
76
79
|
|
|
77
80
|
### SMS OTP (with AWS SNS)
|
|
@@ -125,19 +128,23 @@ Optional vars:
|
|
|
125
128
|
|
|
126
129
|
### Magic Links
|
|
127
130
|
|
|
128
|
-
Magic links provide passwordless authentication by
|
|
131
|
+
Magic links provide passwordless authentication by emailing a single-use sign-in link.
|
|
129
132
|
|
|
130
133
|
**Enable in config:**
|
|
131
134
|
|
|
132
135
|
```ts
|
|
133
136
|
auth: defineAuth("better-auth", {
|
|
134
|
-
plugins:
|
|
137
|
+
plugins: { magicLink: { expiresIn: 900 } }, // seconds; default 300
|
|
135
138
|
}),
|
|
136
139
|
```
|
|
137
140
|
|
|
138
141
|
**Endpoints:**
|
|
139
|
-
- `POST /auth/v1/magic-link
|
|
140
|
-
- `GET /auth/v1/magic-link/verify` -
|
|
142
|
+
- `POST /auth/v1/sign-in/magic-link` - Send the magic link email (`{ email, callbackURL? }`)
|
|
143
|
+
- `GET /auth/v1/magic-link/verify` - Spend the token, set the session, redirect to `callbackURL`
|
|
144
|
+
|
|
145
|
+
**The emailed link opens a confirm page.** Mail scanners fetch every link in a message, which would spend a single-use token before the recipient clicks. So the email links to `<ACCOUNT_URL>/magic-link?token=…` — the [Account UI](/ui/account/features/passwordless) confirm page — and only its **Continue signing in** button navigates to `/magic-link/verify`. If you serve your own frontend at `ACCOUNT_URL`, give it a `/magic-link` page that does the same: forward the query string to `/auth/v1/magic-link/verify` on a user click.
|
|
146
|
+
|
|
147
|
+
Tokens are stored hashed, and the email states the configured `expiresIn`.
|
|
141
148
|
|
|
142
149
|
**Disabling sign-up via magic link:**
|
|
143
150
|
|
|
@@ -154,31 +161,28 @@ auth: defineAuth("better-auth", {
|
|
|
154
161
|
}),
|
|
155
162
|
```
|
|
156
163
|
|
|
157
|
-
It inherits
|
|
158
|
-
`
|
|
159
|
-
|
|
164
|
+
It inherits `emailAndPassword.disableSignUp: true` the same way
|
|
165
|
+
`emailOtp.disableSignUp` does; set `magicLink: { disableSignUp: false }` to opt
|
|
166
|
+
it back open. The invite-only [signup policy](/platform/auth/security#signup-policy)
|
|
167
|
+
applies to magic links too.
|
|
160
168
|
|
|
161
|
-
**Email
|
|
169
|
+
**Email delivery:**
|
|
162
170
|
|
|
163
|
-
Magic link emails
|
|
164
|
-
|
|
165
|
-
- `APP_NAME` - Application name in email subject
|
|
166
|
-
- `APP_URL` - Base URL for magic link redirect
|
|
167
|
-
- `EMAIL_FROM` - Sender email address
|
|
168
|
-
- `EMAIL_FROM_NAME` - Sender display name
|
|
171
|
+
Magic link emails go through your configured `email.provider` — Cloudflare Email Sending by default, or AWS SES with the same variables as Email OTP (`APP_NAME`, `EMAIL_FROM`, `EMAIL_FROM_NAME`). `ACCOUNT_URL` sets where the confirm page lives.
|
|
169
172
|
|
|
170
173
|
**Frontend integration:**
|
|
171
174
|
|
|
172
175
|
```ts
|
|
173
|
-
// Request magic link
|
|
174
|
-
await fetch('/auth/v1/magic-link
|
|
176
|
+
// Request a magic link
|
|
177
|
+
await fetch('/auth/v1/sign-in/magic-link', {
|
|
175
178
|
method: 'POST',
|
|
176
179
|
headers: { 'Content-Type': 'application/json' },
|
|
177
|
-
|
|
180
|
+
credentials: 'include',
|
|
181
|
+
body: JSON.stringify({ email: 'user@yourdomain.com', callbackURL: 'https://app.yourdomain.com/' }),
|
|
178
182
|
});
|
|
179
183
|
|
|
180
|
-
//
|
|
181
|
-
//
|
|
184
|
+
// The user opens the link, lands on <ACCOUNT_URL>/magic-link, clicks
|
|
185
|
+
// "Continue signing in", and is redirected to callbackURL signed in.
|
|
182
186
|
```
|
|
183
187
|
|
|
184
188
|
### Passkeys
|
|
@@ -283,18 +287,13 @@ Static, long-lived credentials for cron jobs, scripts, and machine-to-machine in
|
|
|
283
287
|
|
|
284
288
|
**Authenticating requests:**
|
|
285
289
|
|
|
286
|
-
Pass the key as the `x-api-key` header
|
|
290
|
+
Pass the key as the `x-api-key` header, or a prefixed key as `Authorization: Bearer <key>` (query parameters are not accepted, so keys never land in access logs or `Referer`):
|
|
287
291
|
|
|
288
292
|
```bash
|
|
289
|
-
|
|
290
|
-
curl -H "x-api-key: ${KEY}" https://api.example.com/v1/jobs
|
|
291
|
-
|
|
292
|
-
# Query-param form (for clients that can't inject custom headers,
|
|
293
|
-
# e.g., claude.ai's MCP connector)
|
|
294
|
-
curl "https://api.example.com/v1/jobs?api_key=${KEY}"
|
|
293
|
+
curl -H "x-api-key: ${KEY}" https://api.example.com/api/v1/jobs
|
|
295
294
|
```
|
|
296
295
|
|
|
297
|
-
|
|
296
|
+
Sending `x-api-key` together with a session cookie or an `Authorization` header is a `400 AUTH_METHOD_CONFLICT`.
|
|
298
297
|
|
|
299
298
|
**Endpoints (managed by Better Auth):**
|
|
300
299
|
- `POST /auth/v1/api-key/create` — issue a new key (returns the secret once; store it)
|
|
@@ -303,7 +302,7 @@ The header takes precedence when both are present. The query-param form lands in
|
|
|
303
302
|
|
|
304
303
|
These need a real session (cookie or session-token bearer). Under `/auth/v1/*` a key authenticates only `GET /auth/v1/get-session`; every other Better Auth endpoint ignores `x-api-key`, so a leaked key cannot mint JWTs, manage keys, or act on organizations. See [API Keys](/platform/auth/api-keys).
|
|
305
304
|
|
|
306
|
-
Keys can carry organization context via `metadata.organizationId` — when set, the auth middleware looks up the user's role in that org and populates `ctx.roles` accordingly, so a single key inherits the same firewall + access scope as the user who created it.
|
|
305
|
+
Keys can carry organization context via `metadata.organizationId` — when set, the auth middleware looks up the user's role in that org and populates `ctx.roles` accordingly, so a single key inherits the same firewall + access scope as the user who created it. `metadata.scopes` narrows a key to named resources and read/write — see [API Keys → Scopes](/platform/auth/api-keys#scopes). New keys carry a project prefix (`plugins: { apiKey: { prefix } }`), a banned owner's keys stop working, and each key is rate limited.
|
|
307
306
|
|
|
308
307
|
### OAuth Provider (MCP-ready)
|
|
309
308
|
|
|
@@ -395,7 +394,7 @@ Consent management:
|
|
|
395
394
|
|
|
396
395
|
**Account SPA wiring:**
|
|
397
396
|
|
|
398
|
-
The compiled Account SPA already serves `/consent`. When `oauthProvider` is enabled, Better Auth
|
|
397
|
+
The compiled Account SPA already serves `/consent`. When `oauthProvider` is enabled, Better Auth sends unauthenticated users to `${ACCOUNT_URL}/login` and authenticated users to `${ACCOUNT_URL}/consent`. Both URLs carry the signed authorize query (`client_id`, `scope`, repeated `ba_param` keys, `sig`, and so on). The bundled consent screen fetches client metadata via `/oauth2/public-client`, then POSTs the page's query back to `/oauth2/consent` as `oauth_query`. The login page does the same on sign-in. The SPA router keeps that query verbatim, because any rewrite fails the signature check with `invalid_signature`.
|
|
399
398
|
|
|
400
399
|
**Token and tenant context:**
|
|
401
400
|
|
|
@@ -76,6 +76,53 @@ auth: defineAuth("better-auth", {
|
|
|
76
76
|
|
|
77
77
|
---
|
|
78
78
|
|
|
79
|
+
## Signup Policy
|
|
80
|
+
|
|
81
|
+
`signup` decides who may create an account. One server-side gate (Better Auth's `user.create.before`) enforces it on **every** creation path — email + password, email OTP, magic link, and social sign-in — so no sign-in method can be used to slip past it.
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
auth: defineAuth("better-auth", {
|
|
85
|
+
signup: { inviteOnly: true }, // invitations + admin-created only
|
|
86
|
+
// or: signup: { allowedEmailDomains: ["example.com"] } // that domain + invitations
|
|
87
|
+
})
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
| Always admitted | Why |
|
|
91
|
+
|-----------------|-----|
|
|
92
|
+
| Accounts created by an admin (`POST /auth/v1/admin/create-user`) | Operators provision users directly |
|
|
93
|
+
| An email with a **pending, unexpired** organization invitation | Invitees must be able to sign up |
|
|
94
|
+
| The deploy owner's first Cloudflare login | The brokered-deploy owner is promoted to `appmanager` on that login |
|
|
95
|
+
|
|
96
|
+
Everyone else gets `403` with code `SIGNUP_NOT_ALLOWED`. Existing users sign in as before — the gate runs only when an account would be created. `allowedEmailDomains` matches the exact domain (`example.com` admits `me@example.com`, not `me@sub.example.com`).
|
|
97
|
+
|
|
98
|
+
`account.auth.signup: false` is the shorthand for `inviteOnly: true`. The compile fails if you combine `inviteOnly` with `allowedEmailDomains` (allowed domains already admit invitations), or a restricted policy with the `upgradeAnonymous` plugin (it lets an anonymous user claim any email).
|
|
99
|
+
|
|
100
|
+
Invitation acceptance itself still needs the invitation ID from the email, so knowing an invited address isn't enough to join an organization. Pair a restricted policy with `emailVerification` if accounts must prove their email before use.
|
|
101
|
+
|
|
102
|
+
A per-method hard block is separate: `emailAndPassword.disableSignUp` and the `emailOtp` / `magicLink` `disableSignUp` options refuse new accounts on that method even for invitees.
|
|
103
|
+
|
|
104
|
+
## Account Linking
|
|
105
|
+
|
|
106
|
+
When someone signs in with a social provider and an account with the same email already exists, Better Auth links the two only if the provider verified the email (or is listed as trusted) **and** the existing account's email is verified. The second condition stops a pre-registered, unverified account from absorbing a real owner's Google sign-in. The compiler pins both conditions explicitly, so a future Better Auth default can't loosen them; the local-email condition is not configurable.
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
auth: defineAuth("better-auth", {
|
|
110
|
+
socialProviders: { google: { enabled: true } },
|
|
111
|
+
accountLinking: {
|
|
112
|
+
trustedProviders: ["google"], // trust Google's email even when it says unverified
|
|
113
|
+
// enabled: false, // never link implicitly; users link while signed in
|
|
114
|
+
},
|
|
115
|
+
})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`trustedProviders` entries must be enabled `socialProviders`; anything else fails the compile.
|
|
119
|
+
|
|
120
|
+
## Sign-In Tokens at Rest
|
|
121
|
+
|
|
122
|
+
Magic-link tokens and email OTP codes are stored **hashed** in the verification table (`storeToken: "hashed"`, `storeOTP: "hashed"`), so a leaked database row can't be replayed. Both lifetimes are emitted explicitly (default 300 seconds, `plugins.<name>.expiresIn` to change), and the emails state the same value.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
79
126
|
## Rate Limiting
|
|
80
127
|
|
|
81
128
|
Quickback includes per-IP rate limiting by default to protect against brute-force attacks and abuse.
|
|
@@ -194,25 +241,25 @@ Quickback supports three bearer-token flavors alongside the standard browser ses
|
|
|
194
241
|
| Session cookie | Browser SPAs (CMS, Account, your app) | Better Auth session lookup |
|
|
195
242
|
| Session-token bearer | API clients that grabbed `set-auth-token` | Better Auth `bearer` plugin |
|
|
196
243
|
| JWT bearer | API clients that mint at `GET /auth/v1/token` | In-worker JWT fast-path (no DB hit) |
|
|
197
|
-
| API-key bearer | Long-lived programmatic access | `apiKey` plugin / `x-api-key` header (never a query parameter) |
|
|
244
|
+
| API-key bearer | Long-lived programmatic access | `apiKey` plugin / `x-api-key` header, or a prefixed key as `Authorization: Bearer` (never a query parameter) |
|
|
198
245
|
|
|
199
246
|
These match Better Auth's own framing of bearer tokens as **an alternative to cookies, not a supplement** — a request uses one or the other.
|
|
200
247
|
|
|
201
|
-
###
|
|
248
|
+
### One transport per request
|
|
202
249
|
|
|
203
|
-
|
|
250
|
+
A request carries exactly one credential. Two or more of `Cookie`, `Authorization`, and `x-api-key` is a `400 AUTH_METHOD_CONFLICT` — no precedence rules, no silent override:
|
|
204
251
|
|
|
205
252
|
```
|
|
206
253
|
Request Resolved as
|
|
207
254
|
────────────────────────────────────── ─────────────
|
|
208
255
|
Cookie only cookie session
|
|
209
256
|
Authorization: Bearer <jwt> JWT claims
|
|
210
|
-
Authorization: Bearer <api-key> API-key owner
|
|
211
257
|
Authorization: Bearer <session-token> bearer session
|
|
212
|
-
|
|
258
|
+
x-api-key: <api-key> API-key owner (narrowed by its scopes)
|
|
259
|
+
Any two of the above 400 AUTH_METHOD_CONFLICT
|
|
213
260
|
```
|
|
214
261
|
|
|
215
|
-
This closes a class of silent-impersonation bugs where an ambient session cookie (multi-account browser tabs, a malicious extension, a misconfigured proxy injecting `Set-Cookie`) would otherwise override an explicit
|
|
262
|
+
This closes a class of silent-impersonation bugs where an ambient session cookie (multi-account browser tabs, a malicious extension, a misconfigured proxy injecting `Set-Cookie`) would otherwise override an explicit credential. The decision is made before `getSession()` runs, so it applies to every code path in the auth middleware.
|
|
216
263
|
|
|
217
264
|
The api-key and JWT bearers also short-circuit before cookie resolution via dedicated fast-paths — they never touch the database for session lookup. Only session-token bearers reach `getSession()`, where Better Auth's `bearer` plugin resolves the `Authorization` header.
|
|
218
265
|
|
|
@@ -13,7 +13,7 @@ Better Auth supports multiple sign-in methods:
|
|
|
13
13
|
|
|
14
14
|
## Session Handling
|
|
15
15
|
|
|
16
|
-
Sessions live in the **auth database
|
|
16
|
+
Sessions live in the **auth database**, and every session lookup reads it — the compiler does not configure Better Auth `secondaryStorage`, so a KV namespace does not cache sessions. To take session reads off the database hot path, enable the signed cookie cache (`session.cookieCache`), which trades revocation latency (capped by its `maxAge`) for fewer reads.
|
|
17
17
|
|
|
18
18
|
The generated auth middleware resolves the session once per request and hydrates a single Hono context variable, `ctx` — it does **not** set `session` or `user` variables:
|
|
19
19
|
|
|
@@ -230,6 +230,8 @@ The matching `ws_ticket` issuer is the same one the Broadcaster already uses at
|
|
|
230
230
|
|
|
231
231
|
Drop in [`Y-PartyServer`](https://github.com/cloudflare/partykit) when you need true concurrent text/document editing. It's a `Server` subclass that wraps Yjs's sync protocol; everything else above stays the same.
|
|
232
232
|
|
|
233
|
+
Add `y-partyserver` and `yjs` to `build.dependencies` alongside `partyserver`. The cloud compiler image ships all three — plus `y-prosemirror` and the `prosemirror-*` packages for rich-text docs — so hosted complete compiles can bundle-check the room.
|
|
234
|
+
|
|
233
235
|
```ts
|
|
234
236
|
import { YServer } from 'y-partyserver';
|
|
235
237
|
|
|
@@ -233,6 +233,8 @@ has no effect.
|
|
|
233
233
|
> `readRoles` are applied on every route that can reveal an object — downloads,
|
|
234
234
|
> `GET /object` listings, and `POST /url` lookups alike. Being a member of the
|
|
235
235
|
> owning organization is not sufficient on its own.
|
|
236
|
+
> Downloads and `HEAD` also require a live metadata row for every read scope;
|
|
237
|
+
> soft-deleted objects return `404` even if bytes remain in R2.
|
|
236
238
|
>
|
|
237
239
|
> - **Listing** (`GET /object`) returns only objects in buckets you may read.
|
|
238
240
|
> The filter is applied in the query, so `limit` and `offset` page over your
|
|
@@ -1,45 +1,15 @@
|
|
|
1
1
|
# Using KV
|
|
2
2
|
|
|
3
|
-
Cloudflare KV is
|
|
3
|
+
Cloudflare KV is a namespace your handlers can use for caching. The compiler itself keeps very little in it.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## What the compiler stores in KV
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- **JWT revocation stamps** — with [`auth.jwt.revocationCheck: 'kv'`](/configure/auth) the generated auth writes a timestamp when a user is banned or a membership is removed or changed, and the JWT fast path refuses tokens issued before it.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
// How sessions work internally (auto-generated)
|
|
11
|
-
// On login: session stored in KV
|
|
12
|
-
await kv.put(`session:${sessionToken}`, JSON.stringify(sessionData), {
|
|
13
|
-
expirationTtl: 60 * 60 * 24 * 7, // 7 days
|
|
14
|
-
});
|
|
15
|
-
|
|
16
|
-
// On each request: session retrieved from KV
|
|
17
|
-
const session = await kv.get(`session:${sessionToken}`, "json");
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
Sessions are automatically:
|
|
21
|
-
- **Created** on sign-in (email/password, passkey, magic link, etc.)
|
|
22
|
-
- **Validated** on every authenticated request via the `Authorization: Bearer <token>` header
|
|
23
|
-
- **Expired** after the configured TTL (default: 7 days)
|
|
24
|
-
- **Deleted** on sign-out
|
|
25
|
-
|
|
26
|
-
## Rate Limiting
|
|
27
|
-
|
|
28
|
-
KV powers the rate limiting middleware that protects auth endpoints:
|
|
29
|
-
|
|
30
|
-
```typescript
|
|
31
|
-
// Rate limit key structure (auto-generated)
|
|
32
|
-
// Key: ratelimit:{ip}:{endpoint}
|
|
33
|
-
// Value: request count
|
|
34
|
-
// TTL: rate limit window (e.g., 60 seconds)
|
|
35
|
-
const key = `ratelimit:${ip}:${endpoint}`;
|
|
36
|
-
const count = await kv.get(key);
|
|
37
|
-
if (count && parseInt(count) > limit) {
|
|
38
|
-
return c.json({ error: "Too many requests" }, 429);
|
|
39
|
-
}
|
|
40
|
-
```
|
|
9
|
+
## What is *not* in KV
|
|
41
10
|
|
|
42
|
-
|
|
11
|
+
- **Sessions** live in the auth database. The compiler does not configure Better Auth `secondaryStorage`; see [Session Handling](/platform/auth/using-auth#session-handling).
|
|
12
|
+
- **Auth rate-limit counters** live in the auth database on Cloudflare (`rateLimit.storage: "database"`, the default there). See [Auth Security](/platform/auth/security#counter-storage).
|
|
43
13
|
|
|
44
14
|
## Caching
|
|
45
15
|
|
|
@@ -376,7 +376,8 @@ export default defineAction({
|
|
|
376
376
|
|
|
377
377
|
// ctx.crypto is hydrated for authenticated requests only — a PUBLIC
|
|
378
378
|
// action reads an .encrypted() column through decryptValue directly.
|
|
379
|
-
const secret = await decryptValue(env, unsafeDb, conn.organizationId, conn.signingSecret
|
|
379
|
+
const secret = await decryptValue(env, unsafeDb, conn.organizationId, conn.signingSecret,
|
|
380
|
+
{ table: "connections", column: "signingSecret" });
|
|
380
381
|
// verify `rawBody` + the provider's signature headers with `secret`;
|
|
381
382
|
// throw a 401 ActionError on failure — BEFORE touching any tenant data.
|
|
382
383
|
|
|
@@ -35,6 +35,10 @@ The `/compile` endpoint requires either a session token (from `quickback login`)
|
|
|
35
35
|
|
|
36
36
|
The map uses project-root-relative paths and follows the same layout `quickback build` reads from disk: `quickback/quickback.config.ts`, `quickback/features/**`, `quickback/services/**`, `quickback/{lib,hooks,plugins,middlewares,email-templates}/**`, plus `quickback/drizzle/**/meta/**` and `wrangler.toml` for incremental builds.
|
|
37
37
|
|
|
38
|
+
Raw-files requests may contain at most 30,000 paths, with at most 32 path
|
|
39
|
+
segments per entry. Both compiler backends reject larger maps before organizing
|
|
40
|
+
the project.
|
|
41
|
+
|
|
38
42
|
Three constraints, all fail-closed:
|
|
39
43
|
|
|
40
44
|
- **The config must be fully static.** The compiler parses `quickback.config.ts` with a literals-only evaluator — it never executes user code. Object/array/string/number/boolean literals, substitution-free template literals, and the `define*` helper calls all work; variables, computed values, and imports-as-values are rejected with a 400 that names the offending construct and line.
|
|
@@ -150,18 +150,22 @@ reaches Wrangler first, apply the same fix above and rebuild Generated Backend
|
|
|
150
150
|
before Deploy.
|
|
151
151
|
|
|
152
152
|
The compile sandbox has no network and bundles against the compiler image's
|
|
153
|
-
own dependencies
|
|
154
|
-
[`build.dependencies`](/configure#custom-dependencies)
|
|
155
|
-
|
|
156
|
-
bundle check for those projects and says so in the compile warnings:
|
|
153
|
+
own dependencies. A dependency declared in
|
|
154
|
+
[`build.dependencies`](/configure#custom-dependencies) may not be available
|
|
155
|
+
there. In that case, a hosted complete compile fails before the bundle check:
|
|
157
156
|
|
|
158
157
|
```
|
|
159
|
-
|
|
160
|
-
compiler image:
|
|
158
|
+
Worker bundle check cannot run: build.dependencies not installed in the
|
|
159
|
+
compiler image: fast-xml-parser
|
|
161
160
|
```
|
|
162
161
|
|
|
163
|
-
The
|
|
164
|
-
|
|
162
|
+
The image preinstalls a set of [supported build
|
|
163
|
+
dependencies](/configure#custom-dependencies) — PartyServer, Yjs,
|
|
164
|
+
ProseMirror, `drizzle-zod`, and React Email among them. Type-only `@types/*`
|
|
165
|
+
packages never block the check. For any other package, build locally with it
|
|
166
|
+
installed or request that it be added to the compiler image. Validation
|
|
167
|
+
compiles (`complete=false`) still generate output without running the Worker
|
|
168
|
+
bundle check.
|
|
165
169
|
|
|
166
170
|
Store the Better Auth id as plain text:
|
|
167
171
|
|
|
@@ -9,11 +9,12 @@ API keys are a user credential. Manage them at `/api-keys`, linked from `/profil
|
|
|
9
9
|
- Scoped to an organization via `metadata.organizationId` so the key inherits your role in that tenant
|
|
10
10
|
- One organization: stamped automatically
|
|
11
11
|
- Several organizations: pick one when creating
|
|
12
|
+
- Optional **Scopes** — space-separated `read`, `write`, `<resource>:read`, `<resource>:write`. Empty means full access as your role; scopes only narrow it. Unknown scopes are rejected. See [Scopes](/platform/auth/api-keys#scopes)
|
|
12
13
|
|
|
13
14
|
## Managing Keys
|
|
14
15
|
|
|
15
16
|
- List every key you own (not filtered to the current org)
|
|
16
|
-
- See last-used timestamp
|
|
17
|
+
- See last-used timestamp, which organization the key is scoped to, and its scopes
|
|
17
18
|
- Revoke individual keys
|
|
18
19
|
|
|
19
20
|
`/$slug/api-keys` redirects here so old bookmarks still work.
|
|
@@ -355,14 +355,15 @@ Full-featured SaaS with organizations, teams, and admin panel.
|
|
|
355
355
|
|
|
356
356
|
### Invite-Only Platform
|
|
357
357
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
358
|
+
Set it on the server, not with a `VITE_*` flag — a flag only hides the signup screen:
|
|
359
|
+
|
|
360
|
+
```ts
|
|
361
|
+
account: {
|
|
362
|
+
auth: { signup: false, passkey: true, organizations: true, admin: true },
|
|
363
|
+
},
|
|
363
364
|
```
|
|
364
365
|
|
|
365
|
-
|
|
366
|
+
`account.auth.signup: false` sets [`signup.inviteOnly`](/platform/auth/security#signup-policy): only admin-created accounts and emails with a pending organization invitation can create an account, on every sign-in method. The SPA hides open signup; an invitee's invitation link still reaches `/signup`.
|
|
366
367
|
|
|
367
368
|
## Feature Detection
|
|
368
369
|
|
|
@@ -14,7 +14,7 @@ The sign-in email contains the six-digit code only — no magic-link companion.
|
|
|
14
14
|
|
|
15
15
|
## What about magic links?
|
|
16
16
|
|
|
17
|
-
Account UI does not
|
|
17
|
+
Account UI's sign-in screen does not request magic links — its passwordless flow is OTP. When the `magicLink` Better Auth plugin is enabled (see [Auth Plugins](/platform/auth/plugins#magic-links)) and your own UI requests a link, the emailed link opens Account UI's `/magic-link` page. Only the **Continue signing in** button there spends the single-use token, so a mail scanner that fetches the link can't burn it.
|
|
18
18
|
|
|
19
19
|
## Related
|
|
20
20
|
|
|
@@ -380,7 +380,7 @@ export default async (newSession, { authDb, authSchema }) => {
|
|
|
380
380
|
|
|
381
381
|
### Normalize and gate signup
|
|
382
382
|
|
|
383
|
-
`before-*` hooks can return `{ data: Partial<User> }` to mutate the row before insert. Throw to abort.
|
|
383
|
+
`before-*` hooks can return `{ data: Partial<User> }` to mutate the row before insert. Throw to abort. For invite-only or allowed-domain signup, use the built-in [signup policy](/platform/auth/security#signup-policy) instead — it runs before this hook on every sign-in method.
|
|
384
384
|
|
|
385
385
|
```ts title="quickback/hooks/before-user-create.ts"
|
|
386
386
|
export default async (user: { email: string; name?: string }) => {
|
|
@@ -26,7 +26,7 @@ User management dashboard — view all users, search, create accounts, ban/unban
|
|
|
26
26
|
|
|
27
27
|
## How to Enable
|
|
28
28
|
|
|
29
|
-
Add `account` to your `quickback.config.ts` and compile. The compiler
|
|
29
|
+
Add `account` to your `quickback.config.ts` and compile. The compiler copies the generic prebuilt Account bundle into your Worker; your project's settings reach it at serve time through the worker-injected `window.__QUICKBACK_RUNTIME` config.
|
|
30
30
|
|
|
31
31
|
```typescript title="quickback/quickback.config.ts"
|
|
32
32
|
export default {
|
|
@@ -97,7 +97,7 @@ When a flag is `false`, the corresponding routes **guard themselves at runtime**
|
|
|
97
97
|
|
|
98
98
|
## Features
|
|
99
99
|
|
|
100
|
-
- **Authentication** — Email/password, passkeys (WebAuthn), email OTP,
|
|
100
|
+
- **Authentication** — Email/password, passkeys (WebAuthn), email OTP, email verification, password reset, and the confirm page that magic-link emails open (`/magic-link`)
|
|
101
101
|
- **Account Management** — Profile editing, avatar upload, password changes, device/session management, account deletion
|
|
102
102
|
- **Connected Accounts** — Link Google and Cloudflare logins from `/connected-accounts` (linked from profile)
|
|
103
103
|
- **Organizations** — Multi-tenant org management with owner/admin/member roles, invitations, and org settings
|
|
@@ -65,7 +65,8 @@ The dialog generates the appropriate input control for each field:
|
|
|
65
65
|
| `number` | Number input | Step 0.01, supports decimals |
|
|
66
66
|
| `boolean` | Checkbox | With label text |
|
|
67
67
|
| `enum` | Text input | The allowed values are in `inputFields[].enum` |
|
|
68
|
-
| `array
|
|
68
|
+
| `array<object>` | JSON textarea | Validated as an array of objects before submission |
|
|
69
|
+
| Other `array<…>` | Text input | Comma-separated values, split on save |
|
|
69
70
|
|
|
70
71
|
The types come from the action's input JSON Schema — see
|
|
71
72
|
[ActionInputField](/ui/admin/schema-format#actioninputfield).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.67.
|
|
3
|
+
"version": "0.67.2",
|
|
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",
|
|
@@ -220,6 +220,11 @@ PUT /api/v1/{resource}/batch
|
|
|
220
220
|
|
|
221
221
|
Inserts new records or updates existing ones. Every record must include an `id` field.
|
|
222
222
|
|
|
223
|
+
When create and update access policies are configured, batch upsert requires
|
|
224
|
+
create access for the route. Existing records also receive the update access
|
|
225
|
+
check, including any record-level rule. A caller who can create but cannot
|
|
226
|
+
update may insert new IDs; existing IDs fail their update check.
|
|
227
|
+
|
|
223
228
|
**Note:** Batch upsert requires both `generateId: false` (user-provided IDs) in your database configuration and `guards: false` on the table. Explicitly enabling `crud.batchUpsert` without both settings is a compile error. Use `crud.batchUpdate` for guarded updates.
|
|
224
229
|
|
|
225
230
|
### Request
|
|
@@ -94,9 +94,9 @@ Missing or invalid authentication tokens.
|
|
|
94
94
|
| Code | Description |
|
|
95
95
|
|------|-------------|
|
|
96
96
|
| `AUTH_MISSING` | No Authorization header provided |
|
|
97
|
-
| `AUTH_INVALID_TOKEN` | Token is malformed or invalid — including a Quickback-minted JWT that no longer verifies (rotated key, tampered, revoked). Presented-and-bad is always `401`, never treated as no credential |
|
|
97
|
+
| `AUTH_INVALID_TOKEN` | Token is malformed or invalid — including a Quickback-minted JWT that no longer verifies (rotated key, tampered, revoked). Presented-and-bad is always `401`, never treated as no credential. An API key whose owner is banned answers with `details.reason: "owner_banned"`; one whose stored scopes are malformed, `"malformed_scopes"` |
|
|
98
98
|
| `AUTH_EXPIRED` | Token has expired |
|
|
99
|
-
| `AUTH_RATE_LIMITED` | Too many auth attempts |
|
|
99
|
+
| `AUTH_RATE_LIMITED` | Too many auth attempts, or an API key over its [per-key limit](/platform/auth/api-keys#rate-limit) (`429`) |
|
|
100
100
|
| `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
101
|
|
|
102
102
|
### Firewall (403)
|
|
@@ -189,6 +189,7 @@ Access violations return **403 Forbidden** when the user's role doesn't match th
|
|
|
189
189
|
| `ACCESS_CONDITION_FAILED` | Record-level access condition not met |
|
|
190
190
|
| `ACCESS_OWNERSHIP_REQUIRED` | User must own the record |
|
|
191
191
|
| `ACCESS_NO_ORG` | No active organization set |
|
|
192
|
+
| `ACCESS_KEY_SCOPE_REQUIRED` | A [scoped API key](/platform/auth/api-keys#scopes) does not cover this route and method. `details.required` lists the scope that would admit it (empty outside the API base, which scoped keys never reach); `details.current` is the key's scopes |
|
|
192
193
|
|
|
193
194
|
### Guards (400)
|
|
194
195
|
|
|
@@ -320,6 +321,7 @@ form can show the conflict inline. `details.column` is the first of them.
|
|
|
320
321
|
|------|--------|-------------|
|
|
321
322
|
| `DB_NOT_NULL_VIOLATION` | 400 | Required column was null at write time |
|
|
322
323
|
| `DB_UNIQUE_VIOLATION` | 409 | Unique constraint hit |
|
|
324
|
+
| `DB_RELATIONSHIP_MISMATCH` | 400 | A referenced row does not match the required parent column |
|
|
323
325
|
| `DB_INSERT_FAILED` | 500 | INSERT failed for an unrecognized reason |
|
|
324
326
|
| `DB_UPDATE_FAILED` | 500 | UPDATE failed for an unrecognized reason |
|
|
325
327
|
| `ENCRYPTION_UNREADABLE` | 422 | A stored [`.encrypted()`](/define/encryption) value will not decrypt |
|
|
@@ -327,8 +329,9 @@ form can show the conflict inline. `details.column` is the first of them.
|
|
|
327
329
|
The `details.column` field is only present when the driver's error message identified the offending column (SQLite/D1 do; some PG variants don't).
|
|
328
330
|
|
|
329
331
|
`ENCRYPTION_UNREADABLE` always carries `details: { table, column, id }` — the
|
|
330
|
-
row whose stored ciphertext is malformed
|
|
331
|
-
organization key
|
|
332
|
+
row whose stored ciphertext is malformed, was not written under the caller's
|
|
333
|
+
organization key, was copied from another column or table, or names a key
|
|
334
|
+
version the organization does not have. Rewriting the field repairs the row.
|
|
332
335
|
|
|
333
336
|
## Batch Errors
|
|
334
337
|
|
|
@@ -6,6 +6,7 @@ The top-level `auth` config block holds provider-agnostic auth knobs that affect
|
|
|
6
6
|
export default defineConfig({
|
|
7
7
|
// ...
|
|
8
8
|
auth: {
|
|
9
|
+
roles: ['bookkeeper'],
|
|
9
10
|
roleHierarchy: ['member', 'admin', 'owner'],
|
|
10
11
|
jwt: {
|
|
11
12
|
expiresIn: 60,
|
|
@@ -16,6 +17,31 @@ export default defineConfig({
|
|
|
16
17
|
});
|
|
17
18
|
```
|
|
18
19
|
|
|
20
|
+
## `auth.roles`
|
|
21
|
+
|
|
22
|
+
Declares exact role names that your authentication provider supplies and your
|
|
23
|
+
project intentionally uses. This is the acknowledgement mechanism for dynamic
|
|
24
|
+
provider roles: declared names do not produce `AUTHZ_UNKNOWN_ROLE_NAME` typo
|
|
25
|
+
warnings, while nearby misspellings still do.
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
auth: {
|
|
29
|
+
roles: ['bookkeeper'],
|
|
30
|
+
roleHierarchy: ['member', 'admin', 'owner'],
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`auth.roles` does not create privilege inheritance. Put a role in
|
|
35
|
+
`auth.roleHierarchy` only when it belongs in that lowest-to-highest ordering
|
|
36
|
+
and should participate in `role+` expansion.
|
|
37
|
+
|
|
38
|
+
With Quickback's generated Better Auth organization plugin, declared roles are
|
|
39
|
+
also registered as custom organization roles with member-equivalent Better Auth
|
|
40
|
+
permissions, so invitations and member-role updates can assign them. Other auth
|
|
41
|
+
providers must include the declared names in their authenticated role claims.
|
|
42
|
+
If you provide your own Better Auth organization-plugin `roles` or `ac`, that
|
|
43
|
+
explicit provider configuration wins and Quickback skips auto-registration.
|
|
44
|
+
|
|
19
45
|
## `auth.roleHierarchy`
|
|
20
46
|
|
|
21
47
|
Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to mean "this role and above". Documented in detail under [Access — Role hierarchy](/define/access#role-hierarchy).
|