@quickback-dev/cli 0.67.0 → 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.
Files changed (65) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/lib/file-loader.d.ts.map +1 -1
  3. package/dist/lib/file-loader.js +1 -0
  4. package/dist/lib/file-loader.js.map +1 -1
  5. package/dist/skill/docs/api/batch-operations.md +5 -0
  6. package/dist/skill/docs/api/crud.md +8 -0
  7. package/dist/skill/docs/api/errors.md +7 -4
  8. package/dist/skill/docs/api/openapi.md +1 -0
  9. package/dist/skill/docs/configure/auth.md +26 -0
  10. package/dist/skill/docs/configure/index.md +28 -9
  11. package/dist/skill/docs/configure/providers.md +12 -0
  12. package/dist/skill/docs/define/access.md +15 -2
  13. package/dist/skill/docs/define/actions/scoped-db.md +1 -0
  14. package/dist/skill/docs/define/authz-roles.md +1 -1
  15. package/dist/skill/docs/define/encryption.md +39 -7
  16. package/dist/skill/docs/define/firewall.md +6 -0
  17. package/dist/skill/docs/define/schema.md +31 -2
  18. package/dist/skill/docs/platform/auth/api-keys.md +77 -1
  19. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  20. package/dist/skill/docs/platform/auth/plugins/index.md +33 -34
  21. package/dist/skill/docs/platform/auth/security.md +53 -6
  22. package/dist/skill/docs/platform/auth/using-auth.md +1 -1
  23. package/dist/skill/docs/platform/realtime/partyserver-rooms.md +2 -0
  24. package/dist/skill/docs/platform/storage/r2.md +2 -0
  25. package/dist/skill/docs/platform/storage/using-kv.md +6 -36
  26. package/dist/skill/docs/platform/webhooks/inbound.md +2 -1
  27. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +4 -0
  28. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +12 -8
  29. package/dist/skill/docs/ui/account/features/api-keys.md +2 -1
  30. package/dist/skill/docs/ui/account/features/index.md +7 -6
  31. package/dist/skill/docs/ui/account/features/passwordless.md +1 -1
  32. package/dist/skill/docs/ui/account/hooks.md +50 -2
  33. package/dist/skill/docs/ui/account/index.md +2 -2
  34. package/dist/skill/docs/ui/admin/actions.md +2 -1
  35. package/package.json +1 -1
  36. package/src/skill/docs/api/batch-operations.md +5 -0
  37. package/src/skill/docs/api/crud.md +8 -0
  38. package/src/skill/docs/api/errors.md +7 -4
  39. package/src/skill/docs/api/openapi.md +1 -0
  40. package/src/skill/docs/configure/auth.md +26 -0
  41. package/src/skill/docs/configure/index.md +28 -9
  42. package/src/skill/docs/configure/providers.md +12 -0
  43. package/src/skill/docs/define/access.md +15 -2
  44. package/src/skill/docs/define/actions/scoped-db.md +1 -0
  45. package/src/skill/docs/define/authz-roles.md +1 -1
  46. package/src/skill/docs/define/encryption.md +39 -7
  47. package/src/skill/docs/define/firewall.md +6 -0
  48. package/src/skill/docs/define/schema.md +31 -2
  49. package/src/skill/docs/platform/auth/api-keys.md +77 -1
  50. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  51. package/src/skill/docs/platform/auth/plugins/index.md +33 -34
  52. package/src/skill/docs/platform/auth/security.md +53 -6
  53. package/src/skill/docs/platform/auth/using-auth.md +1 -1
  54. package/src/skill/docs/platform/realtime/partyserver-rooms.md +2 -0
  55. package/src/skill/docs/platform/storage/r2.md +2 -0
  56. package/src/skill/docs/platform/storage/using-kv.md +6 -36
  57. package/src/skill/docs/platform/webhooks/inbound.md +2 -1
  58. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +4 -0
  59. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +12 -8
  60. package/src/skill/docs/ui/account/features/api-keys.md +2 -1
  61. package/src/skill/docs/ui/account/features/index.md +7 -6
  62. package/src/skill/docs/ui/account/features/passwordless.md +1 -1
  63. package/src/skill/docs/ui/account/hooks.md +50 -2
  64. package/src/skill/docs/ui/account/index.md +2 -2
  65. package/src/skill/docs/ui/admin/actions.md +2 -1
@@ -573,6 +573,12 @@ Every generated write handler — `POST /`, `POST /batch`, `PATCH /:id`, `PATCH
573
573
 
574
574
  This closes a cross-tenant injection vector: even if an attacker knows a foreign tenant's row ID, they cannot attach a child record to it — at creation or by repointing an existing row later — and they cannot trigger a cross-tenant cascade delete. The check uses the target table's `buildXFirewallConditions(ctx)` helper, so it honors whatever firewall predicates the target declared (organization, owner, team, custom). FKs to tables with `{ exception: true }` get a plain existence check (still verifies the row exists, doesn't tenant-scope it). A [self-reference](/define/schema#self-references) (`parentId: q.text().references('self')`) is checked against the table's own firewall the same way.
575
575
 
576
+ Target visibility alone does not prove that two visible rows share a project or
577
+ other parent. For that invariant, opt into the schema-level
578
+ [`references(..., { match })`](/define/schema#match-a-referenced-rows-parent)
579
+ constraint. Database triggers also backstop action writes; clients should use
580
+ the API rather than writing directly to PostgreSQL.
581
+
576
582
  The check runs after guards but before the write, so it appears as `layer: "validation"` in error responses. Status code is `400`, not `404` — returning `404` would leak existence of out-of-scope rows.
577
583
 
578
584
  ### Pre-Record ID-Probe Defense
@@ -86,6 +86,35 @@ A few mechanics to know:
86
86
  - **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
87
87
  - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`, or `.references('self')` for a column pointing at another row of the same table (see [Self-references](#self-references)). An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path. `other` must be a **feature table in the same database**.
88
88
 
89
+ ### Match a referenced row's parent
90
+
91
+ An ordinary FK checks that its target exists and is visible. It does not infer
92
+ that two rows belong to the same project, event, or other parent. Declare that
93
+ rule on the FK when both rows must share one:
94
+
95
+ ```ts
96
+ stageId: q.text().optional().references(() => projectStages.id, {
97
+ match: { source: 'projectId', target: 'projectId' },
98
+ }),
99
+ ```
100
+
101
+ Here `source` names a column on this table and `target` names one on the
102
+ referenced table. If `stageId` is set, both values must be non-null and equal.
103
+ If `stageId` is null, the match is not required. The compiler rejects unknown
104
+ columns or an unresolved target table. This is opt-in: some visible records
105
+ may legitimately link across projects.
106
+
107
+ The compiler emits database triggers for inserts and updates of the source
108
+ row, and for changes to the target's parent column. Use the Quickback API for
109
+ client writes; the triggers backstop generated CRUD, batch writes, changesets,
110
+ and actions at the database boundary. Updating `projectId` while
111
+ leaving `stageId` unchanged still checks the resulting pair. A mismatch returns
112
+ `400 DB_RELATIONSHIP_MISMATCH` from generated write routes. Apply the generated
113
+ trigger migration before using the new rule; it validates future writes, so
114
+ check existing rows for mismatches before rollout. The ordinary target
115
+ [firewall check](/define/firewall#foreign-key-referential-checks) remains in
116
+ place for generated CRUD writes.
117
+
89
118
  > **Never FK Better Auth tables**
90
119
  >
91
120
  > `.references(() => users.id)` (or `user`, `organization`, `member`, `session`) on a feature column is illegal. Those tables live in `AUTH_DB`; your features live in `DB`. SQLite cannot FK across D1 databases, and drizzle-kit fails generating features migrations:
@@ -1131,7 +1160,7 @@ rows live in `AUTH_DB`, outside the feature database.
1131
1160
 
1132
1161
  ## Input Hints
1133
1162
 
1134
- Control how the CMS renders form inputs for specific columns. By default the CMS infers the control from the column itself — `q.timestamp()` → date-time picker, `q.date()` → date picker, `q.bool()` → checkbox, `q.int()` / `q.bigint()` / `q.smallint()` → number, `q.decimal()` → text (so the exact string is sent), `q.enum()` → select, `q.url()` → URL input, `q.json()` → textarea, and name patterns for plain text (`*Url`, `*Notes`, `email`). The registry carries the q column `kind`, so this works on SQLite too, where every timestamp is `text` at the SQL layer. The CMS has no editor for `.array()` columns yet. `inputHints` overrides the inference:
1163
+ Control how the CMS renders form inputs for specific columns. By default the CMS infers the control from the column itself — `q.timestamp()` → date-time picker, `q.date()` → date picker, `q.bool()` → checkbox, `q.int()` / `q.bigint()` / `q.smallint()` → number, `q.decimal()` → text (so the exact string is sent), `q.enum()` → select, `q.enum([...]).array()` → multiple checkboxes that send an array, `q.url()` → URL input, `q.json()` → textarea that validates and sends JSON, and name patterns for plain text (`*Url`, `*Notes`, `email`). The registry carries the q column `kind`, so this works on SQLite too, where every timestamp is `text` at the SQL layer. Other `.array()` columns do not yet have a dedicated CMS editor. `inputHints` overrides the inference except for enum arrays, which must retain an array value:
1135
1164
 
1136
1165
  {/* doc-compile: skip — one-key excerpt: the fence is the `inputHints` map only, with firewall/guards/crud already elided to `// ...`. This page's whole-file examples are the `feature()` and `q.table()`+`defineTable()` forms at the top, which the gate does compile. */}
1137
1166
  ```typescript
@@ -1153,7 +1182,7 @@ export default defineTable(jobs, {
1153
1182
  |------|-----------|
1154
1183
  | `richtext` | Rich text editor (tiptap) — bold, italic, headings, lists, links. Stores HTML. Lazy-loaded in edit mode, rendered as formatted HTML in view mode. |
1155
1184
  | `select` | Dropdown select (single value) |
1156
- | `multi-select` | Multi-value select |
1185
+ | `multi-select` | Falls back to the inferred control; enum arrays render as multiple checkboxes |
1157
1186
  | `radio` | Radio button group |
1158
1187
  | `checkbox` | Checkbox toggle |
1159
1188
  | `textarea` | Multi-line text input |
@@ -16,9 +16,85 @@ The compiler validates the key by calling the Quickback API's Better Auth `GET /
16
16
 
17
17
  ## What a key can reach
18
18
 
19
- In a generated project an `x-api-key` authenticates two things:
19
+ Send a key as `x-api-key: <key>`, or — for keys that carry the project prefix (every key created since prefixes were added) — as `Authorization: Bearer <key>`. Older unprefixed keys work only through `x-api-key`. Either way a key authenticates two things:
20
20
 
21
21
  - **Your API** (`/api/*`) — the auth middleware verifies the key and resolves its owner's role in the organization named by the key's `metadata.organizationId`.
22
22
  - **`GET /auth/v1/get-session`** — the one Better Auth endpoint where a key stands in for its owner's session (the key-validation "whoami").
23
23
 
24
24
  Every other Better Auth endpoint ignores the header and answers as for an unauthenticated caller: a key cannot mint an identity JWT (`GET /auth/v1/token`), list sessions, create or manage keys, change the user, register a passkey, or act on organizations. Those need a real session.
25
+
26
+ The generated MCP endpoint (`POST /mcp`) is bearer-only: it forwards `Authorization`, not `x-api-key`, to the routes its tools call. So an MCP client uses a prefixed key as `Authorization: Bearer <key>`. A scoped key may open `/mcp` (and list tools); each tool call re-enters the REST route it wraps, where the key's scopes are checked — a `tasks:read` key can call the list-tasks tool but gets `403 ACCESS_KEY_SCOPE_REQUIRED` from the create-task tool.
27
+
28
+ The prefix is what makes the Bearer form unambiguous: `plugins.apiKey.prefix` must end in `_` or `-` (Better Auth session tokens are alphanumeric, so they can never start with one) and must not start with `eyJ` (a JWT).
29
+
30
+ ## Scopes
31
+
32
+ By default a key carries its owner's **full** role in the organization it names. Give it `metadata.scopes` to narrow that — for an agent, a CI job, or an integration that only needs part of the API:
33
+
34
+ ```bash
35
+ curl -X POST https://api.example.com/auth/v1/api-key/create \
36
+ -H "Cookie: ${SESSION_COOKIE}" -H "Content-Type: application/json" \
37
+ -d '{"name":"reporting agent","metadata":{"organizationId":"org_123","scopes":["customers:read","deals:read"]}}'
38
+ ```
39
+
40
+ The [Account UI](/ui/account/features/api-keys) has a Scopes field for the same thing. The vocabulary is closed:
41
+
42
+ | Scope | Admits |
43
+ |-------|--------|
44
+ | `read` | `GET` / `HEAD` / `OPTIONS` on every route under `/api/v1` |
45
+ | `write` | Every other method under `/api/v1` — create, update, delete, batch, and non-`GET` actions |
46
+ | `<resource>:read` | Reads under `/api/v1/<resource>/` — list, get, views, `GET` actions |
47
+ | `<resource>:write` | Writes under `/api/v1/<resource>/` — including actions mounted there |
48
+
49
+ `<resource>` is the first path segment of a generated resource route (`customers` for `/api/v1/customers`). The method decides read vs write, so a `GET` action is a read. `write` does not imply `read`; list both if the key needs both. Routes outside a resource mount — area/namespace routes (`/api/v1/<scope>/:id/…`), root-mounted standalone actions, `/api/v1/schema` — are reachable only through the global `read` / `write`.
50
+
51
+ **Scopes narrow, they never widen.** The auth middleware checks the scope first; the route's own [Access](/define/access) and [Firewall](/define/firewall) then run with the owner's org role exactly as before. A `customers:write` key held by a `member` still cannot delete what `crud.delete.access` reserves for `admin`.
52
+
53
+ **Outside `/api/v1`, a scoped key is refused.** Storage, realtime tickets, webhooks, FGA, and public discovery routes answer a scoped key with `403`. `/auth/v1/*` is allowed — there the key is only the `get-session` whoami. Use an unscoped key or a session for those surfaces.
54
+
55
+ A denied request is a standard [Problem Details](/api/errors) `403`:
56
+
57
+ ```json
58
+ {
59
+ "type": "https://quickback.dev/problems/access-key-scope-required",
60
+ "title": "Access key scope required",
61
+ "status": 403,
62
+ "code": "ACCESS_KEY_SCOPE_REQUIRED",
63
+ "detail": "API key scope does not allow this request",
64
+ "layer": "access",
65
+ "details": { "required": ["customers:write"], "current": ["customers:read"] },
66
+ "hint": "Create a key with the \"customers:write\" scope (or omit scopes for a full-access key)"
67
+ }
68
+ ```
69
+
70
+ ### Validation
71
+
72
+ Scopes are checked when a key is created or updated (`POST /auth/v1/api-key/create`, `/api-key/update`). An unknown resource, an unknown verb, an empty list, or a non-array value fails with `400` and `code: "INVALID_API_KEY_SCOPES"`; nothing is normalized. A scope naming a resource that was later removed simply matches nothing. Stored scopes that are not an array of strings fail the key closed (`401 AUTH_INVALID_TOKEN`, `details.reason: "malformed_scopes"`).
73
+
74
+ ### Existing keys
75
+
76
+ A key with no `scopes` in its metadata is a full-role key, so every key created before scopes existed keeps working unchanged. Scopes live in `metadata`, which the owner can change through `/api-key/update`; replacing the metadata without `scopes` turns the key back into a full-role key. That is the owner's call — they can always create a full-role key anyway. Scopes protect against a leaked key, not against its owner.
77
+
78
+ Scopes are stored in metadata rather than Better Auth's `permissions` field because `permissions` is server-only: the Account UI and other session clients could not set it.
79
+
80
+ ## Key prefix
81
+
82
+ New keys start with a display prefix so they are recognisable in logs and secret scanners. It defaults to the project name, slugged (`my-app` → `my_app_…`). Override it with the object form of the plugin:
83
+
84
+ ```ts
85
+ auth: defineAuth("better-auth", {
86
+ plugins: {
87
+ apiKey: { prefix: "acme_live_" },
88
+ },
89
+ }),
90
+ ```
91
+
92
+ The prefix must be 1–32 characters of `A-Z a-z 0-9 _ -`; anything else fails the compile. It is display-only — Better Auth hashes the whole key — so keys created before the prefix existed keep verifying.
93
+
94
+ ## Banned owners
95
+
96
+ When the admin plugin bans a user, every API key they own stops working: the API answers `401 AUTH_INVALID_TOKEN` with `details.reason: "owner_banned"`, and `GET /auth/v1/get-session` refuses the key. A ban whose `banExpires` has passed no longer counts, matching the admin plugin. A deleted owner's keys stop working too.
97
+
98
+ ## Rate limit
99
+
100
+ Better Auth rate limits each key using the auth config's `rateLimit.window` (seconds) and `rateLimit.max` — 100 requests per 60 seconds by default. The limit is on unless that block sets `enabled: false`. Over the limit the API answers `429 AUTH_RATE_LIMITED`. The values are stamped on each key when it is created, so a change applies to new keys only.
@@ -128,4 +128,4 @@ When `fromOpenAPI: false`, the emitted call has `capabilities: []` and no proxy
128
128
 
129
129
  ## Why bearer-only?
130
130
 
131
- The MCP and agent surfaces are server-to-server by nature. Cookies on those surfaces add CSRF surface for no benefit (no browser callers), and `x-api-key` was the legacy `apiKey`-plugin path that fragments the auth model. Bearer is the one true channel here. If your project still wants API-key auth, configure the `apiKey` plugin to accept its key via `Authorization: Bearer` so everything stays one channel.
131
+ The MCP and agent surfaces are server-to-server by nature. Cookies on those surfaces add CSRF surface for no benefit (no browser callers), and `x-api-key` was the legacy `apiKey`-plugin path that fragments the auth model. Bearer is the one true channel here. API keys ride it too: a prefixed key sent as `Authorization: Bearer <key>` is recognised by the auth middleware, so an MCP client can authenticate with a (scoped) API key. See [API Keys](/platform/auth/api-keys#what-a-key-can-reach).
@@ -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 the global signup gate**: when
71
- > `account.auth.signup: false` (i.e. `emailAndPassword.disableSignUp: true`) is
72
- > set, the OTP plugin is gated automatically so it can't be used to bypass it. Set
73
- > `emailOtp: { disableSignUp: false }` explicitly to opt the OTP path back open
74
- > while password sign-up stays closed.
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 sending a unique login link to the user's email. When clicked, the link authenticates the user without requiring a password.
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: ["magicLink"],
137
+ plugins: { magicLink: { expiresIn: 900 } }, // seconds; default 300
135
138
  }),
136
139
  ```
137
140
 
138
141
  **Endpoints:**
139
- - `POST /auth/v1/magic-link/send` - Send magic link email
140
- - `GET /auth/v1/magic-link/verify` - Verify magic link token
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 the global signup gate the same way `emailOtp.disableSignUp` does:
158
- `account.auth.signup: false` gates the magic-link path automatically; set
159
- `magicLink: { disableSignUp: false }` to opt it back open.
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 customization:**
169
+ **Email delivery:**
162
170
 
163
- Magic link emails use the same AWS SES configuration as Email OTP. Customize the email template via environment variables:
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/send', {
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
- body: JSON.stringify({ email: 'user@yourdomain.com' })
180
+ credentials: 'include',
181
+ body: JSON.stringify({ email: 'user@yourdomain.com', callbackURL: 'https://app.yourdomain.com/' }),
178
182
  });
179
183
 
180
- // User clicks link in email, which redirects to your app
181
- // The token is verified automatically via the callback URL
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 (preferred) or as an `?api_key=` / `?key=` query parameter:
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
- # Header form (preferred — keys don't leak into access logs or Referer)
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
- The header takes precedence when both are present. The query-param form lands in nginx / Cloudflare access logs and `Referer` headers when the page navigates away — prefer headers whenever the client supports them.
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 redirects unauthenticated users to `${ACCOUNT_URL}/login?redirect=...` and authenticated users straight to `${ACCOUNT_URL}/consent?client_id=...&scope=...&oauth_query=...`. The bundled consent screen reads those params, fetches client metadata via `/oauth2/public-client`, and POSTs back to `/oauth2/consent`.
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
- ### Precedence: bearer always wins
248
+ ### One transport per request
202
249
 
203
- If a request carries both `Authorization` and `Cookie` headers, the bearer wins universally and the cookie is dropped before session resolution:
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
- Cookie + Authorization: Bearer <token> bearer wins, cookie ignored
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 bearer credential. The decision is made before `getSession()` runs, so it applies to every code path in the auth middleware.
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** — that is the source of truth. When your project uses the `cloudflare-kv` storage provider, the compiler wires that KV namespace up as Better Auth's `secondaryStorage`, which caches session lookups at the edge in front of the database. KV is a cache, not the store.
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 used by the Quickback Stack for session storage, caching, and rate limiting.
3
+ Cloudflare KV is a namespace your handlers can use for caching. The compiler itself keeps very little in it.
4
4
 
5
- ## Session Storage
5
+ ## What the compiler stores in KV
6
6
 
7
- Better Auth stores sessions in KV by default for fast edge-based lookups. This is auto-configured by the compiler — no setup needed.
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
- ```typescript
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
- See [Auth Security](/platform/auth/security) for rate limiting configuration options.
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, so anything you declare in
154
- [`build.dependencies`](/configure#custom-dependencies) is not installed there.
155
- Rather than fail on `Could not resolve "yjs"`, the compiler **skips** the
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
- Skipped the Worker bundle check — build.dependencies not installed in the
160
- compiler image: yjs, y-prosemirror
158
+ Worker bundle check cannot run: build.dependencies not installed in the
159
+ compiler image: fast-xml-parser
161
160
  ```
162
161
 
163
- The compile still succeeds and the generated output is unchanged; unresolved
164
- imports and missing named exports surface at `wrangler deploy` instead.
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 and which organization the key is scoped to
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
- ```bash
359
- VITE_ENABLE_SIGNUP=false
360
- VITE_ENABLE_PASSKEY=true
361
- VITE_ENABLE_ORGANIZATIONS=true
362
- VITE_ENABLE_ADMIN=true
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
- No public signup — users must be created by admin or invited to organizations.
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 offer a magic-link sign-in flow. The `magicLink` Better Auth plugin is still available at the API level (see [Auth Plugins](/platform/auth/plugins#magic-links)) for apps that build their own sign-in UI, but the bundled Account SPA is OTP-only by design.
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