@quickback-dev/cli 0.67.1 → 0.67.3

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 (57) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/lib/action-harvest.d.ts.map +1 -1
  3. package/dist/lib/action-harvest.js +16 -3
  4. package/dist/lib/action-harvest.js.map +1 -1
  5. package/dist/skill/docs/api/batch-operations.md +5 -0
  6. package/dist/skill/docs/api/errors.md +7 -4
  7. package/dist/skill/docs/configure/auth.md +26 -0
  8. package/dist/skill/docs/configure/index.md +28 -9
  9. package/dist/skill/docs/define/access.md +15 -2
  10. package/dist/skill/docs/define/authz-roles.md +1 -1
  11. package/dist/skill/docs/define/encryption.md +39 -7
  12. package/dist/skill/docs/define/firewall.md +6 -0
  13. package/dist/skill/docs/define/schema.md +31 -2
  14. package/dist/skill/docs/platform/auth/api-keys.md +77 -1
  15. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  16. package/dist/skill/docs/platform/auth/plugins/index.md +33 -34
  17. package/dist/skill/docs/platform/auth/security.md +53 -6
  18. package/dist/skill/docs/platform/auth/using-auth.md +1 -1
  19. package/dist/skill/docs/platform/realtime/partyserver-rooms.md +2 -0
  20. package/dist/skill/docs/platform/storage/r2.md +2 -0
  21. package/dist/skill/docs/platform/storage/using-kv.md +6 -36
  22. package/dist/skill/docs/platform/webhooks/inbound.md +2 -1
  23. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +4 -0
  24. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +12 -8
  25. package/dist/skill/docs/ui/account/features/api-keys.md +2 -1
  26. package/dist/skill/docs/ui/account/features/index.md +7 -6
  27. package/dist/skill/docs/ui/account/features/passwordless.md +1 -1
  28. package/dist/skill/docs/ui/account/hooks.md +1 -1
  29. package/dist/skill/docs/ui/account/index.md +2 -2
  30. package/dist/skill/docs/ui/admin/actions.md +2 -1
  31. package/package.json +1 -1
  32. package/src/skill/docs/api/batch-operations.md +5 -0
  33. package/src/skill/docs/api/errors.md +7 -4
  34. package/src/skill/docs/configure/auth.md +26 -0
  35. package/src/skill/docs/configure/index.md +28 -9
  36. package/src/skill/docs/define/access.md +15 -2
  37. package/src/skill/docs/define/authz-roles.md +1 -1
  38. package/src/skill/docs/define/encryption.md +39 -7
  39. package/src/skill/docs/define/firewall.md +6 -0
  40. package/src/skill/docs/define/schema.md +31 -2
  41. package/src/skill/docs/platform/auth/api-keys.md +77 -1
  42. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  43. package/src/skill/docs/platform/auth/plugins/index.md +33 -34
  44. package/src/skill/docs/platform/auth/security.md +53 -6
  45. package/src/skill/docs/platform/auth/using-auth.md +1 -1
  46. package/src/skill/docs/platform/realtime/partyserver-rooms.md +2 -0
  47. package/src/skill/docs/platform/storage/r2.md +2 -0
  48. package/src/skill/docs/platform/storage/using-kv.md +6 -36
  49. package/src/skill/docs/platform/webhooks/inbound.md +2 -1
  50. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +4 -0
  51. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +12 -8
  52. package/src/skill/docs/ui/account/features/api-keys.md +2 -1
  53. package/src/skill/docs/ui/account/features/index.md +7 -6
  54. package/src/skill/docs/ui/account/features/passwordless.md +1 -1
  55. package/src/skill/docs/ui/account/hooks.md +1 -1
  56. package/src/skill/docs/ui/account/index.md +2 -2
  57. package/src/skill/docs/ui/admin/actions.md +2 -1
@@ -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
 
@@ -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 builds the SPA from source with your project-specific settings baked in and bundles it into your Worker.
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, magic links, email verification, password reset
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<…>` | Text input | Comma-separated values, split on save |
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).