@quickback-dev/cli 0.67.3 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/dist/commands/login.d.ts +10 -3
  2. package/dist/commands/login.d.ts.map +1 -1
  3. package/dist/commands/login.js +20 -9
  4. package/dist/commands/login.js.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/lib/action-harvest.d.ts.map +1 -1
  7. package/dist/lib/action-harvest.js +56 -6
  8. package/dist/lib/action-harvest.js.map +1 -1
  9. package/dist/lib/auth.d.ts +2 -1
  10. package/dist/lib/auth.d.ts.map +1 -1
  11. package/dist/lib/auth.js +2 -1
  12. package/dist/lib/auth.js.map +1 -1
  13. package/dist/skill/docs/api/batch-operations.md +19 -4
  14. package/dist/skill/docs/api/errors.md +35 -2
  15. package/dist/skill/docs/configure/index.md +4 -1
  16. package/dist/skill/docs/configure/providers.md +1 -0
  17. package/dist/skill/docs/define/access.md +2 -0
  18. package/dist/skill/docs/define/actions/scoped-db.md +5 -3
  19. package/dist/skill/docs/define/feature.md +2 -0
  20. package/dist/skill/docs/define/schema.md +21 -4
  21. package/dist/skill/docs/define/triggers.md +3 -0
  22. package/dist/skill/docs/define/validation.md +28 -2
  23. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  24. package/dist/skill/docs/platform/auth/device-auth.md +16 -1
  25. package/dist/skill/docs/platform/auth/security.md +22 -7
  26. package/dist/skill/docs/platform/database/neon.md +9 -2
  27. package/dist/skill/docs/platform/database/planetscale-postgres.md +1 -0
  28. package/dist/skill/docs/platform/database/using-d1.md +32 -0
  29. package/dist/skill/docs/tooling/cli.md +6 -3
  30. package/dist/skill/docs/tooling/output.md +3 -1
  31. package/dist/skill/docs/ui/account/features/admin.md +9 -0
  32. package/dist/skill/docs/ui/admin/schema-format.md +3 -1
  33. package/package.json +1 -1
  34. package/src/skill/docs/api/batch-operations.md +19 -4
  35. package/src/skill/docs/api/errors.md +35 -2
  36. package/src/skill/docs/configure/index.md +4 -1
  37. package/src/skill/docs/configure/providers.md +1 -0
  38. package/src/skill/docs/define/access.md +2 -0
  39. package/src/skill/docs/define/actions/scoped-db.md +5 -3
  40. package/src/skill/docs/define/feature.md +2 -0
  41. package/src/skill/docs/define/schema.md +21 -4
  42. package/src/skill/docs/define/triggers.md +3 -0
  43. package/src/skill/docs/define/validation.md +28 -2
  44. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  45. package/src/skill/docs/platform/auth/device-auth.md +16 -1
  46. package/src/skill/docs/platform/auth/security.md +22 -7
  47. package/src/skill/docs/platform/database/neon.md +9 -2
  48. package/src/skill/docs/platform/database/planetscale-postgres.md +1 -0
  49. package/src/skill/docs/platform/database/using-d1.md +32 -0
  50. package/src/skill/docs/tooling/cli.md +6 -3
  51. package/src/skill/docs/tooling/output.md +3 -1
  52. package/src/skill/docs/ui/account/features/admin.md +9 -0
  53. package/src/skill/docs/ui/admin/schema-format.md +3 -1
@@ -27,7 +27,33 @@ If validation fails, the API returns a `400 Bad Request` with details about whic
27
27
 
28
28
  See [Actions](/define/actions) for the full action definition reference.
29
29
 
30
- > **Planned: Field-Level Validation**
30
+ ## Column Constraints
31
+
32
+ Field-level rules live on the column, not in a separate block. `q.text({ minLength, maxLength, pattern, email })`, `q.enum([...])`, `q.url({ maxLength })` and the numeric column types carry their constraints into the Zod schema of every generated create, update, and batch route, into the OpenAPI document, and into the CMS form. See [Schema](/define/schema#column-types) for the full list.
33
+
34
+ A raw Drizzle table (`sqliteTable` / `pgTable` wrapped in `defineTable`) has no column-level rules. Validate those in a [`triggers.beforeInsert` / `beforeUpdate`](/define/triggers) handler that throws, or convert the table to `q.table()`.
35
+
36
+ ```typescript
37
+ // features/agendaGroups/agendaGroups.ts
38
+ import { feature, q } from '@quickback/compiler';
39
+
40
+ export default feature('agendaGroups', {
41
+ columns: {
42
+ id: q.id(),
43
+ name: q.text({ maxLength: 200 }).required(),
44
+ selectionRule: q.enum(['one', 'multi']).default('one').required(),
45
+ organizationId: q.scope('organization'),
46
+ ...q.audit(),
47
+ ...q.softDelete(),
48
+ },
49
+ read: { access: { roles: ['member'] } },
50
+ create: { access: { roles: ['member'] } },
51
+ update: { access: { roles: ['member'] } },
52
+ delete: { access: { roles: ['member'] }, mode: 'soft' },
53
+ });
54
+ ```
55
+
56
+ > **There is no `validation:` key**
31
57
  >
32
- > Field-level validation rules in `defineTable()` (e.g., `minLength`, `maxLength`, `enum`) are planned for a future release. Today, use Zod schemas in actions for input validation, and rely on your Drizzle schema constraints (`.notNull()`, column types) for database-level enforcement.
58
+ > A top-level `validation: { field: { maxLength, enum } }` block on `defineTable()` is a compile error, as is any other key the compiler does not understand. Earlier compilers let unknown keys through silently, so a `validation:` block looked like it limited a field while the generated routes accepted anything. Move each rule onto its column.
33
59
 
@@ -97,4 +97,4 @@ When the admin plugin bans a user, every API key they own stops working: the API
97
97
 
98
98
  ## Rate limit
99
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.
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 always on. It counts per key, so `rateLimit.enabled: false` (which turns off the per-IP limiter) doesn't affect it. 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.
@@ -7,8 +7,23 @@ The Quickback CLI uses the [OAuth 2.0 Device Authorization Grant](https://datatr
7
7
  1. CLI requests a device code from the API
8
8
  2. User sees a code in the terminal (e.g., `AUL8-H93S`)
9
9
  3. User visits the approval URL and enters the code
10
- 4. CLI polls for approval and exchanges for a session token
10
+ 4. CLI polls `POST /auth/v1/device/token` until the code is approved; the response's `access_token` is a **signed** bearer token
11
+ 5. CLI calls `POST /cli/exchange` with that token to fetch user and session details
11
12
 
12
13
  This flow works in SSH sessions, containers, and WSL where browser redirects aren't possible.
13
14
 
15
+ ## Token signing
16
+
17
+ Better Auth's device-flow token endpoint creates a session and returns its raw session token. Quickback's generated auth config [requires signed bearer tokens](/platform/auth/security#requiresignature-true-is-the-secure-default), so a raw token would be unusable. When `deviceAuthorization` is enabled, the compiler emits an `after` hook on `/device/token` that signs `access_token` with `BETTER_AUTH_SECRET` before the response leaves Better Auth. The rest of the response (`token_type`, `expires_in`, `scope`) and the `Cache-Control: no-store` header are unchanged, and errors such as `authorization_pending` pass through as-is. The signing call comes from `better-call` (the same helper Better Auth's bearer plugin verifies with), so the generated `package.json` declares `better-call` at the exact version Better Auth depends on whenever `deviceAuthorization` is enabled.
18
+
19
+ The generated `POST /cli/exchange` route only **validates** a signed token. It doesn't sign anything:
20
+
21
+ | Request | Response |
22
+ |---------|----------|
23
+ | `Authorization: Bearer <signed token>` for a live session | `200` with `access_token` (the same signed token), `token_type`, `expires_in`, `session`, `user` |
24
+ | `Authorization: Bearer <unsigned token>` | `401 { "error": "invalid_token", "error_description": "A signed bearer token is required; the device-flow token endpoint already returns one." }` |
25
+ | Missing header, bad signature, or expired session | `401 invalid_token` |
26
+
27
+ `/cli/exchange` is reachable without authentication, so it must not sign tokens. If it did, anyone holding a raw session token from a database read, backup, or log could turn it into a working bearer token.
28
+
14
29
  See [CLI Reference](/tooling/cli#login) for usage details.
@@ -183,6 +183,19 @@ long-lived process — the default is `"memory"`.
183
183
  | `"database"` | Auth database (`rateLimit` table) | Cloudflare Workers (default there) |
184
184
  | `"memory"` | Process memory | Single long-lived process (bun / node default) |
185
185
 
186
+ The table exists whenever `storage` is `"database"`, even with `enabled: false`,
187
+ so switching the limiter off or back on needs no migration.
188
+
189
+ ### Client IP
190
+
191
+ Better Auth reads the client IP from `x-forwarded-for` by default, which a
192
+ Worker doesn't receive. Without an IP every caller shares one bucket per path,
193
+ and a single client could use up a sign-in limit for everyone. On Cloudflare
194
+ the compiler therefore emits
195
+ `advanced.ipAddress.ipAddressHeaders: ['cf-connecting-ip']`. Cloudflare sets
196
+ that header at the edge, and clients can't override it. Set
197
+ `advanced.ipAddress.ipAddressHeaders` yourself to use different headers.
198
+
186
199
  ### Built-in rules for every credential door
187
200
 
188
201
  The compiler always emits a per-route rule for **every** credential endpoint
@@ -220,16 +233,16 @@ Set an edge rate-limit binding as well for defence in depth
220
233
 
221
234
  ### Disabling Rate Limiting
222
235
 
223
- Not recommended, but you can disable for testing:
224
-
225
236
  ```ts
226
- rateLimit: {
227
- enabled: process.env.NODE_ENV === 'production',
228
- window: 60,
229
- max: 1000, // Higher limit for development
230
- }
237
+ rateLimit: { enabled: false }
231
238
  ```
232
239
 
240
+ The compiler emits `enabled: false` explicitly. Better Auth would otherwise
241
+ fall back to `enabled: isProduction`. Disabling makes sense when many real
242
+ users share one IP, such as everyone on an event venue's Wi-Fi. It turns off
243
+ only the per-IP limiter. The [per-key API key limit](/platform/auth/api-keys)
244
+ stays on.
245
+
233
246
  ---
234
247
 
235
248
  ## Bearer Tokens and Cookie Precedence
@@ -270,6 +283,7 @@ Quickback configures the Better Auth `bearer` plugin with `requireSignature: tru
270
283
  - The session token Better Auth emits via the `set-auth-token` response header is **signed server-side** with `BETTER_AUTH_SECRET`.
271
284
  - Unsigned bearer tokens are **rejected** at the plugin layer before any session lookup happens.
272
285
  - A session token leaked via a proxy access log, a browser dev-tools panel, or a misrouted `Referer` header **cannot** be replayed as a bearer token by an attacker — they would need the signing secret to forge a valid signature.
286
+ - With `deviceAuthorization` enabled, the device-flow token endpoint (`/device/token`) returns its session token **already signed**, and the generated `POST /cli/exchange` only validates signed tokens. No generated route signs a token a caller hands it (see [Device Authorization](/platform/auth/device-auth#token-signing)).
273
287
 
274
288
  Better Auth's own default for this option is `false`. Quickback overrides it on the secure side. JWT bearers and agent-auth bearers are independently signed and unaffected by this setting.
275
289
 
@@ -292,6 +306,7 @@ User-supplied options merge on top of the secure default, so any other [`bearer`
292
306
  | Threat | Mitigation |
293
307
  |--------|-----------|
294
308
  | Stolen session-token bearer replayed against the API | `requireSignature: true` blocks unsigned values |
309
+ | Raw session token (database read, backup, log) turned into a signed bearer by an endpoint that signs on request | `/device/token` signs at issue; `/cli/exchange` refuses unsigned tokens with 401 and never signs |
295
310
  | Browser extension injects a victim's session cookie into an attacker's bearer-authed API call | Cookie stripped when `Authorization` is present |
296
311
  | Multi-account user has cookies for two identities and uses bearer for the second | Bearer identity wins; no ambiguity in audit log |
297
312
  | MCP / agent flow exposed to ambient browser cookies | `/mcp` and agent-auth routes are bearer-only (cookies dropped entirely, see [Agent Auth](/platform/auth/plugins/agent-auth)) |
@@ -709,7 +709,10 @@ touched. See [the default index set](#the-default-index-set).
709
709
 
710
710
  ### Delegated principal RLS
711
711
 
712
- Delegated principals require Cloudflare + Neon Hyperdrive. Their proof hook
712
+ Delegated principals require Cloudflare + Postgres over Hyperdrive: Neon with
713
+ `connectionMode: "hyperdrive"`, or
714
+ [PlanetScale Postgres](/platform/database/planetscale-postgres), which emits the
715
+ same lookup policies and lanes. Their proof hook
713
716
  returns only a digest and receives no database handle. Quickback then runs one
714
717
  lookup under an internal lookup-only principal whose RLS policy admits only the
715
718
  configured table row matching `credentialDigest`, plus any configured active
@@ -1435,7 +1438,11 @@ source. A child table with no `crud` config soft-deletes by default, so
1435
1438
 
1436
1439
  Tables **with** `defineTable(...)` are unaffected — existing `sqliteTable`
1437
1440
  sources with a resource config still compile to the Postgres dialect
1438
- automatically.
1441
+ automatically. Managed audit timestamps declared in the SQLite shape
1442
+ (`createdAt` / `modifiedAt` / `deletedAt` as `text`) are emitted as
1443
+ `timestamptz`, like every other Postgres table — the audit wrapper and the RLS
1444
+ audit triggers both stamp timestamps, not strings. API responses carry the same
1445
+ ISO-8601 string as on D1.
1439
1446
 
1440
1447
  ## When to choose Neon vs D1
1441
1448
 
@@ -197,6 +197,7 @@ never silently-broken output:
197
197
  | Managed file storage (`managed: true`) | **supported** — metadata lives in a `files` schema of the same database; the file-serving Worker binds the same Hyperdrive config |
198
198
  | Better Auth `subscriptions` plugin | supported — `auth.subscriptions` in the same journal, service-role only ([Subscriptions](/platform/auth/plugins/subscriptions#where-the-table-lives)) |
199
199
  | Generated SQL triggers (`sql:`) | supported — PL/pgSQL bodies, `SECURITY INVOKER` (see [Triggers](/define/triggers)) |
200
+ | Delegated principals (`auth.principals`, `resource.databaseAccess`) | supported — the same lookup policy, `<table>_principal_scope` / `<table>_principal_fence` lanes and middleware as Neon Hyperdrive ([Delegated principal RLS](/platform/database/neon#delegated-principal-rls)) |
200
201
  | `webhooksDatabaseId` / `webhooksDatabaseName` | rejected — D1-only keys; webhook tables live in the `webhooks` schema of the same database |
201
202
  | `connectionMode` of `'http'` or `'websocket'` | rejected — no such driver for this provider |
202
203
 
@@ -33,6 +33,38 @@ Migrations are generated by the compiler using `drizzle-kit generate`. Apply the
33
33
  npx wrangler d1 migrations apply my-db
34
34
  ```
35
35
 
36
+ ## Backend stalls
37
+
38
+ D1 statements occasionally wait tens of seconds in Cloudflare's backend
39
+ queue (a noisy neighbour on the shared execution queue — not your workload),
40
+ and the D1 binding has no deadline or `AbortSignal` of its own. Because every
41
+ query runs through generated code, the deadline is a config option rather than
42
+ something you wrap by hand:
43
+
44
+ ```ts
45
+ database: defineDatabase("cloudflare-d1", {
46
+ queryTimeoutMs: 5000,
47
+ }),
48
+ ```
49
+
50
+ With it set, every D1 handle the compiler emits — the scoped `db`, the unsafe
51
+ `db`, the Better Auth adapter, cron / queue / email runners, the files and
52
+ audit databases — races each statement against the deadline:
53
+
54
+ | Statement | Response | Client should |
55
+ |-----------|----------|---------------|
56
+ | Read (`SELECT`, `WITH`, `EXPLAIN`, `PRAGMA`) | `503 DB_TIMEOUT` | Retry. The read had no side effects |
57
+ | Write (anything else, and any `batch` containing a write) | `500 DB_WRITE_OUTCOME_UNKNOWN` | Re-read the record, then decide. The statement was **not** cancelled on the backend and may still commit |
58
+
59
+ Each timeout also logs one structured line —
60
+ `{ level: "error", event: "DB_DEADLINE", binding, kind, ms, sql }` (SQL
61
+ truncated to 200 chars). Workers Logs indexes the JSON fields, so in the
62
+ dashboard or `wrangler tail --format json` filter on `event = "DB_DEADLINE"`
63
+ and group by `binding` / `kind` to track stalls over time. The response the
64
+ client saw carries the same `binding` in `details`. Unset, nothing changes: no wrapper is emitted and queries are
65
+ unbounded, as before. The option is D1-only; Postgres drivers carry their own
66
+ statement timeouts. `withSession()` handles pass through unbounded.
67
+
36
68
  ## Related
37
69
 
38
70
  - [D1 Setup](/platform/database/d1) — Bindings and wrangler config
@@ -312,9 +312,12 @@ Uses the [OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc
312
312
  1. The CLI requests a one-time device code from the Quickback API.
313
313
  2. A code is displayed in your terminal (e.g., `AUL8-H93S`).
314
314
  3. Your browser opens to the Quickback account page where you approve the code.
315
- 4. The CLI detects approval and exchanges it for a session token.
316
- 5. If you belong to one organization, it's auto-selected. If you have multiple, you choose one.
317
- 6. Credentials are stored locally.
315
+ 4. The CLI detects approval: the API's device-flow token endpoint (`POST /auth/v1/device/token`) returns a **signed** bearer token.
316
+ 5. The CLI sends that token to `POST /cli/exchange`, which validates it and returns your user and session details.
317
+ 6. If you belong to one organization, it's auto-selected. If you have multiple, you choose one.
318
+ 7. Credentials are stored locally.
319
+
320
+ The token endpoint signs the session token before returning it, so the token the CLI receives already works as a bearer token. `/cli/exchange` only validates tokens that are already signed. It refuses an unsigned token with `401 invalid_token` and never signs one. A raw session token, for example one read from the database or a log, therefore can't be turned into a working bearer token. That is the protection the `bearer` plugin's `requireSignature: true` default provides (see [Auth security](/platform/auth/security#requiresignature-true-is-the-secure-default)).
318
321
 
319
322
  ```
320
323
  $ quickback login
@@ -454,9 +454,11 @@ When the `deviceAuthorization` plugin is enabled:
454
454
  ```
455
455
  src/
456
456
  └── routes/
457
- └── cli-auth.ts # Device auth flow endpoints
457
+ └── cli.ts # POST /cli/exchange (validates a signed device-flow token)
458
458
  ```
459
459
 
460
+ `src/lib/auth.ts` also gets an `after` hook that signs the `/device/token` response's `access_token`. See [Device Authorization](/platform/auth/device-auth#token-signing).
461
+
460
462
  ## Database Schemas
461
463
 
462
464
  ### Dual Database Mode (D1 default)
@@ -48,6 +48,15 @@ The admin panel is restricted to platform roles on the Better Auth user record:
48
48
  > **`role: "admin"` is not a platform role.** By default the compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`. Migrate rows with `role: "admin"` to `"appmanager"`.
49
49
  >
50
50
  > A project that declares `plugins: { admin: { adminRoles, roles } }` gets **exactly** that: the declared `adminRoles` list and role → access-controller map are emitted verbatim (`appmanager: userAc` narrows the provisioning operator to no admin API at all; `adminRoles: ["sysadmin"]` keeps set-role / impersonate / ban for `sysadmin` only). The compiler never re-widens a declared role, and refuses a declaration it cannot honour.
51
+ >
52
+ > **`adminRoles` order is ascending privilege, and it is a ceiling.** `adminRoles[i]` is tier `i + 1`; every other role (`user`, project-custom roles) is tier 0. With the defaults, `appmanager` is 1 and `sysadmin` is 2; a comma-separated `role` ranks at its highest member. Better Auth's admin plugin alone lets any role holding `user:set-role` grant any role that exists, so the generated `src/lib/auth.ts` adds a `hooks.before` role ceiling that returns `403 ROLE_CEILING` when:
53
+ >
54
+ > - `set-role`, `create-user` or `update-user` requests a role ranked above the caller's.
55
+ > - `set-role`, `update-user`, `ban-user`, `remove-user`, `set-user-password`, `revoke-user-session(s)` or `impersonate-user` targets a user ranked above the caller.
56
+ >
57
+ > Equal tier is allowed, so an appmanager can still make another appmanager (the example below). Only a `sysadmin` can grant `sysadmin`.
58
+ >
59
+ > `set-organization-member` refuses to seat its caller with `403 OPERATOR_SELF_SEAT`: operators are never seated by their own control-plane calls.
51
60
 
52
61
 
53
62
  To grant operator access to a user:
@@ -430,9 +430,11 @@ interface ValidationRule {
430
430
  | `enum` | `q.enum([...])`, or `text(..., { enum: [...] })` in raw Drizzle — the CMS renders a select |
431
431
  | `url` | `q.url()` — the CMS renders a `url` input; the API accepts only absolute `http(s)` URLs (so not `""`, `javascript:` or `data:`) |
432
432
  | `maxLength` | `q.text({ maxLength })` / `q.url({ maxLength })` |
433
+ | `minLength` | `q.text({ minLength })` |
434
+ | `email` | `q.text({ email: true })` — the CMS renders an `email` input |
433
435
  | `integer` | `q.int()`, `q.bigint()`, `q.smallint()` — whole numbers only |
434
436
  | `min` / `max` | `q.bigint()` (±2^53−1, the JSON-safe range) and `q.smallint()` (−32768…32767), inclusive |
435
- | `pattern` | `q.decimal({ precision, scale })` — the regex source the decimal string must match |
437
+ | `pattern` | `q.text({ pattern: /re/ })` (regex source only; flags are not carried) and `q.decimal({ precision, scale })` — the regex source the value must match |
436
438
  | `minLength` / `email` | Only when the enforced Zod carries `.min(n)` / `.email()`; no q column kind emits them today |
437
439
 
438
440
  Columns with no constraints have no entry. Optional fields left blank in the CMS form are omitted from the request body rather than sent as `""` — the API accepts an optional field being absent, not empty.