@quickback-dev/cli 0.66.25 → 0.67.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 (49) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +4 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/index.js.map +1 -1
  6. package/dist/lib/api-client.d.ts +2 -0
  7. package/dist/lib/api-client.d.ts.map +1 -1
  8. package/dist/lib/api-client.js.map +1 -1
  9. package/dist/skill/docs/api/actions.md +1 -1
  10. package/dist/skill/docs/api/errors.md +9 -6
  11. package/dist/skill/docs/api/typescript.md +3 -1
  12. package/dist/skill/docs/configure/providers.md +3 -0
  13. package/dist/skill/docs/define/access.md +12 -1
  14. package/dist/skill/docs/define/actions/scoped-db.md +79 -4
  15. package/dist/skill/docs/define/areas.md +3 -1
  16. package/dist/skill/docs/define/arrows.md +70 -9
  17. package/dist/skill/docs/define/fga.md +4 -2
  18. package/dist/skill/docs/define/firewall.md +6 -3
  19. package/dist/skill/docs/define/permissions.md +1 -1
  20. package/dist/skill/docs/define/schema.md +1 -1
  21. package/dist/skill/docs/define/scopes.md +1 -1
  22. package/dist/skill/docs/define/triggers.md +13 -1
  23. package/dist/skill/docs/platform/auth/plugins/subscriptions.md +23 -1
  24. package/dist/skill/docs/platform/auth/security.md +23 -1
  25. package/dist/skill/docs/platform/database/neon.md +3 -1
  26. package/dist/skill/docs/platform/push/index.md +1 -1
  27. package/dist/skill/docs/ui/account/features/admin.md +29 -0
  28. package/dist/skill/docs/ui/account/features/sessions.md +2 -0
  29. package/package.json +1 -1
  30. package/src/skill/docs/api/actions.md +1 -1
  31. package/src/skill/docs/api/errors.md +9 -6
  32. package/src/skill/docs/api/typescript.md +3 -1
  33. package/src/skill/docs/configure/providers.md +3 -0
  34. package/src/skill/docs/define/access.md +12 -1
  35. package/src/skill/docs/define/actions/scoped-db.md +79 -4
  36. package/src/skill/docs/define/areas.md +3 -1
  37. package/src/skill/docs/define/arrows.md +70 -9
  38. package/src/skill/docs/define/fga.md +4 -2
  39. package/src/skill/docs/define/firewall.md +6 -3
  40. package/src/skill/docs/define/permissions.md +1 -1
  41. package/src/skill/docs/define/schema.md +1 -1
  42. package/src/skill/docs/define/scopes.md +1 -1
  43. package/src/skill/docs/define/triggers.md +13 -1
  44. package/src/skill/docs/platform/auth/plugins/subscriptions.md +23 -1
  45. package/src/skill/docs/platform/auth/security.md +23 -1
  46. package/src/skill/docs/platform/database/neon.md +3 -1
  47. package/src/skill/docs/platform/push/index.md +1 -1
  48. package/src/skill/docs/ui/account/features/admin.md +29 -0
  49. package/src/skill/docs/ui/account/features/sessions.md +2 -0
@@ -105,7 +105,7 @@ A few mechanics to know:
105
105
  > `authz.relationships` `subject: { column: 'userId', equals: 'ctx.userId' }` does not need, and must not create, a SQL FK. See [Relationships](/define/relationships). To query Better Auth tables, use `c.get("authDb")` from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
106
106
 
107
107
 
108
- - **Indexes and constraints:** column-level `.index()` / `.unique()` / `.check(expr)`, or table-level `indexes` / `unique` / `check` as a third arg to `q.table(name, cols, { indexes, unique, check })`. With `feature()`, pass `indexes`, `unique` and `check` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts. See [Constraints](#constraints--check-and-unique).
108
+ - **Indexes and constraints:** column-level `.index()` / `.unique()` / `.check(expr)`, or table-level `indexes` / `unique` / `check` as a third arg to `q.table(name, cols, { indexes, unique, check })`. With `feature()`, pass `indexes`, `unique` and `check` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts. In the two-export form they go on `q.table`; on `defineTable(...)` they are a compile error, because they describe the table, not the resource. See [Constraints](#constraints--check-and-unique).
109
109
 
110
110
  ### Column Types
111
111
 
@@ -349,7 +349,7 @@ so it can only ever carry the role the caller actually proved this request.
349
349
  - A **bulk-grant lane** (`{ roles: [...] }` or `{ team: true }`) mints **no** scope role — it opens the gate via the caller's org role without proving a relationship. The gate passes; the caller carries their org role, not a minted scope role.
350
350
  - **The org claim is only ever signed beside a membership role.** Every mint site — `/scope/v1/enter`, the namespace resolver, `/api/v1/token` — writes `orgId` into the token only when a membership `role` accompanies it, and the auth middleware ignores an `orgId` claim that arrives without a `role`. A relationship-promoted tenant (the in-request `ctx.activeOrgId` stamped from the proven row so the firewall resolves) is never persisted as a bare tenant grant.
351
351
  - **`/scope/v1/enter` drops the org claims for a foreign-tenant instance.** When the relationship's `from` table carries an organization column, the enter route reads it off the proven row (the same row the probe already fetched — no extra query) and compares it with `ctx.activeOrgId`. A mismatch — an org-B member entering an org-A event — mints the token **without** `orgId` / `role`: a relationship-only principal, exactly the state the namespace resolver gives the same caller. The caller keeps their org seat for org-B requests by using their session or a plain `/api/v1/token`; the scope token is for the scope. A `from` table with no organization column (a global reference relationship) leaves the claim untouched.
352
- - **Every mint tenant-binds the instance.** A relationship row is matched without tenant scoping (a cross-tenant attendee has no `activeOrgId`), so the row alone can't prove which tenant's instance it names. When the relationship's `from` table carries an organization column, every site that mints from a relationship row — `/scope/v1/enter`, [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope), and this namespace resolver (the in-memory stamp **and** the `mintScope` token) — also loads the **instance** row, through its own firewall with tenant scopes stripped so soft-delete still applies, and grants the role only when the instance's organization equals the proving row's. A row created in org B naming org A's event proves nothing about org A and grants nothing; a deleted instance grants nothing. (The namespace gate itself still passes on the proven row; the caller just carries no scope for the foreign instance.) The instance table is the target of the relationship's `resource.column` foreign key, or — when that column isn't a declared FK — the one table whose firewall pins its primary key to `ctx.scope.<kind>` (`{ field: 'id', equals: 'ctx.scope.event' }`). If neither resolves, the compiler warns: declare the FK so the instance can be bound. A `from` table with no organization column has no tenant to compare, so it gets no binding.
352
+ - **Every mint tenant-binds the instance.** A relationship row is matched without tenant scoping (a cross-tenant attendee has no `activeOrgId`), so the row alone can't prove which tenant's instance it names. When the relationship's `from` table carries an organization column, every site that mints from a relationship row — `/scope/v1/enter`, [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope), and this namespace resolver (the in-memory stamp **and** the `mintScope` token) — also loads the **instance** row, through its own firewall with tenant scopes stripped so soft-delete still applies, and grants the role only when the instance's organization equals the proving row's. A row created in org B naming org A's event proves nothing about org A and grants nothing; a deleted instance grants nothing. (The namespace gate itself still passes on the proven row; the caller just carries no scope for the foreign instance.) The instance table is `authz.scopes.<kind>.instance` when declared (`instance: 'events'`), else the target of the relationship's `resource.column` foreign key, else the one table whose firewall pins its primary key to `ctx.scope.<kind>` (`{ field: 'id', equals: 'ctx.scope.event' }`). Several such tables is a compile error naming them — set `instance`. If nothing resolves, the compiler warns: set `instance` (or declare the FK) so the instance can be bound. A `from` table with no organization column has no tenant to compare, so it gets no binding.
353
353
 
354
354
  ### The bulk-grant lane is tenant-bound
355
355
 
@@ -239,7 +239,11 @@ an [action](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
239
239
  into the write payload, or throw to reject — the write never executes and
240
240
  the request gets a structured `TRIGGER_REJECTED` (422) error. Audit
241
241
  fields (`createdBy`, `modifiedAt`, …) are re-stamped after hooks run and
242
- cannot be forged.
242
+ cannot be forged. A `before*` hook gets `values`, the pending write, and
243
+ never the stored row: nothing is read before the write. Destructuring `row`
244
+ or `old` in one is a compile error. To derive a column from the stored row
245
+ on update, use a Postgres `sql:` trigger, where `NEW."col"` is the whole row
246
+ with the update applied.
243
247
  - **`after*` hooks run once per affected row and are awaited** before the
244
248
  write's promise resolves. They may be `async`. A throw surfaces as
245
249
  `TRIGGER_AFTER_FAILED` (500) with `details.committed: true` — the row was
@@ -298,6 +302,14 @@ write path, use the `sql:` lane and reject with `RAISE(ABORT, ...)` (D1) or
298
302
  > `scheduled()` handler + `wrangler.toml` triggers. This note is only about
299
303
  > the table-trigger `handler:` lane not firing inside them.
300
304
 
305
+ ## Columns a `beforeInsert` trigger fills
306
+
307
+ An action's `db.insert(table).values(...)` doesn't have to supply a column a
308
+ `beforeInsert` trigger assigns. The compiler makes that column optional in the
309
+ insert type when a `sql:` body assigns it (`NEW."project_id" := …`) or a
310
+ `handler:` returns it as a key (`{ number: … }`). The column's
311
+ `.required()` stays in the schema, so it is still `NOT NULL` in the table.
312
+
301
313
  ## Choosing a lane
302
314
 
303
315
  | Need | Use |
@@ -306,7 +306,29 @@ export default defineTable(projects, {
306
306
  });
307
307
  ```
308
308
 
309
- To enforce a limit, read `limits` from `GET /subscriptions/me` (or query the subscriptions table directly in an action) and compare it against a count before creating the row. Enforcement is yours to write until tier-aware access rules land; the plugin's job is to make the caller's current tier and its limits available.
309
+ To enforce a limit, read `limits` from `GET /subscriptions/me` (or query the subscriptions table directly in an action) and compare it against a count before creating the row. Enforcement is yours to write; the plugin's job is to make the caller's current tier and its limits available.
310
+
311
+ ### `seats` is the one key the compiler enforces
312
+
313
+ `seats` is reserved: it is memberships per organization, and the compiler enforces it on Better Auth's own seating routes. When the organization plugin is on, the generated auth wires three `organizationHooks` that read the organization's effective subscription and refuse with `403 SEAT_LIMIT_REACHED` when the cap would be exceeded:
314
+
315
+ | Route | Counted against the cap |
316
+ |-------|-------------------------|
317
+ | Create invitation | Current members **plus** pending, unexpired invitations |
318
+ | Accept invitation | Current members |
319
+ | Add member (server-side) | Current members |
320
+
321
+ ```ts
322
+ tiers: {
323
+ solo: { name: 'Solo', limits: { seats: 1 } },
324
+ team: { name: 'Team', priceId: 'price_team', limits: { seats: 10 } },
325
+ enterprise: { name: 'Enterprise', priceId: 'price_ent', limits: { seats: -1 } },
326
+ }
327
+ ```
328
+
329
+ No `seats` key, or a negative value, means unlimited. A subscription that has stopped granting (see [which statuses grant](#which-statuses-grant) and the [expiry bound](#expiry-is-the-second-bound)) counts as the base tier, so a lapsed team plan falls back to the base tier's `seats`. Existing members are never removed by a downgrade; the cap only stops new seating.
330
+
331
+ Two paths are outside Better Auth's routes and therefore outside this check: memberships you insert yourself from `quickback/hooks/after-user-create.ts` (domain auto-join, personal orgs) and direct database writes. The generated `src/plugins/subscriptions/index.ts` exports `seatsAvailable(env, organizationId)` for the first case. The count-then-insert is not transactional, so two acceptances racing for the last seat can both land.
310
332
 
311
333
  ## Local development
312
334
 
@@ -54,6 +54,28 @@ auth: defineAuth("better-auth", {
54
54
 
55
55
  ---
56
56
 
57
+ ## Session Freshness and Password Reset
58
+
59
+ Two Better Auth session controls are emitted with stricter values than the library's own defaults:
60
+
61
+ | Setting | Quickback default | Better Auth default | Override |
62
+ |---------|-------------------|---------------------|----------|
63
+ | `session.freshAge` | 15 minutes | 24 hours | `session.freshAgeInHours` |
64
+ | `emailAndPassword.revokeSessionsOnPasswordReset` | `true` | `false` | `emailAndPassword.revokeSessionsOnPasswordReset: false` |
65
+
66
+ **Freshness** gates the sensitive account operations (`change-password`, `delete-user`, `change-email` confirmation): a session older than `freshAge` has to sign in again first. Better Auth's 24-hour window lets a day-old session on a shared machine delete the account; 15 minutes is the "full, valid login session" an assessor expects.
67
+
68
+ **Reset revocation** terminates every other session the moment a password is reset through the forgot-password flow. That is the point at which someone holding the old password should lose the sessions they opened with it. Password *change* from the Account UI already sends `revokeOtherSessions: true`; direct API callers pass that flag themselves.
69
+
70
+ ```ts
71
+ auth: defineAuth("better-auth", {
72
+ session: { freshAgeInHours: 1 }, // loosen to an hour
73
+ emailAndPassword: { enabled: true, revokeSessionsOnPasswordReset: false }, // keep other sessions
74
+ })
75
+ ```
76
+
77
+ ---
78
+
57
79
  ## Rate Limiting
58
80
 
59
81
  Quickback includes per-IP rate limiting by default to protect against brute-force attacks and abuse.
@@ -172,7 +194,7 @@ Quickback supports three bearer-token flavors alongside the standard browser ses
172
194
  | Session cookie | Browser SPAs (CMS, Account, your app) | Better Auth session lookup |
173
195
  | Session-token bearer | API clients that grabbed `set-auth-token` | Better Auth `bearer` plugin |
174
196
  | JWT bearer | API clients that mint at `GET /auth/v1/token` | In-worker JWT fast-path (no DB hit) |
175
- | API-key bearer | Long-lived programmatic access | `apiKey` plugin / `x-api-key` / `?api_key=` |
197
+ | API-key bearer | Long-lived programmatic access | `apiKey` plugin / `x-api-key` header (never a query parameter) |
176
198
 
177
199
  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.
178
200
 
@@ -908,7 +908,9 @@ from the relationship table under its own policy.
908
908
  — exactly where the API applies the same binding.
909
909
  - **Permissions.** A `{ permission }` arm expands as the API expands it; arrow
910
910
  hops become `qb_arrow_…` helpers (recursive arrows are a `maxDepth`-bounded
911
- closure that re-checks the tenant on every row), called by the API too.
911
+ closure that re-checks the tenant on every row; a relation-backed arrow keeps
912
+ the hop's rows whose FK is in the relationship's `qb_rel_…` set), called by
913
+ the API too.
912
914
  - **Still API-only.** Literal status filters (a conjunct would refuse
913
915
  status-changing updates, because PostgreSQL checks an UPDATE's new row against
914
916
  the read policy) and claims the Worker never writes into the transaction —
@@ -55,7 +55,7 @@ With `push.defaultSchema: true`, the compiler injects a hardened, owner-scoped `
55
55
 
56
56
  - **INTERNAL-only reads** — the crypto fields (`endpoint`, `p256dh`, `auth`) never leave the worker via any HTTP path. A `views.mine` projection exposes only `id`, `userAgent`, `lastSeenAt`, `createdAt` for "Your devices" UIs.
57
57
  - **Owner firewall** — `owner_id` is auto-stamped on create; user A can never read or delete user B's subscription.
58
- - **Create-time validation** — the endpoint must be `https:` (the worker POSTs VAPID-signed requests at that URL, so an arbitrary endpoint is an SSRF primitive), `p256dh` must decode to a 65-byte uncompressed P-256 point, and `auth` to a 16-byte secret. The `https:` check is not the whole SSRF story: at send time the push sender additionally rejects any endpoint whose host resolves to a private, link-local, loopback, `localhost`, or `.internal` address. Together — **https + a non-public-host block** — this narrows the SSRF surface; treat it as defense-in-depth, not a guarantee that SSRF is impossible.
58
+ - **Create-time validation** — the endpoint must be `https:` (the worker POSTs VAPID-signed requests at that URL, so an arbitrary endpoint is an SSRF primitive), `p256dh` must decode to a 65-byte uncompressed P-256 point, and `auth` to a 16-byte secret. The `https:` check is not the whole SSRF story: at send time the push sender runs the endpoint through the same destination policy as [outbound webhooks](/platform/webhooks/outbound) (`src/lib/webhooks/url-policy.ts`): every IANA special-purpose IPv4/IPv6 range (loopback, link-local and the cloud metadata address, RFC 1918, CGNAT, IPv4-mapped, ULA, NAT64, 6to4, Teredo), plus `localhost`, `.local`, `.internal`, `.home.arpa` and single-label names. Unlike webhooks it does **not** resolve DNS, so a public hostname that resolves to a private address is not caught. Together — **https + the destination policy** — this narrows the SSRF surface; treat it as defense-in-depth, not a guarantee that SSRF is impossible.
59
59
  - **Proven identity tags** — a `tags` column is stamped **server-side** from `ctx`: `user:<id>`, and — only when the request carries a scoped token — `scope:<kind>:<subject>` plus one `scope:<kind>:<instance>#<role>` per scope role the verified claim grants (the same dialect realtime tickets use). Client-supplied tags are ignored: they drive fan-out targeting. **Org roles are never stamped** — a device is user-owned, and org audiences are resolved from live membership at send time; see [Targeting](#targeting).
60
60
  - **Rate limit + cap** — creates are limited to 10/minute per caller, and only the newest 10 live subscriptions per user are kept (older rows are soft-deleted, so a user's new device always works).
61
61
 
@@ -67,6 +67,35 @@ So organization creation asks for an `ownerUserId`, seats that user, and never s
67
67
 
68
68
  An operator who genuinely wants their own organization creates one naming themselves as owner — explicit, and visible in the audit trail rather than implied by whoever happened to make the call.
69
69
 
70
+ ## Requiring a second factor
71
+
72
+ Operator accounts are the highest-value targets in a deployment, and CASA / ASVS require multi-factor authentication on every administrative interface. `operatorMfa` enforces it:
73
+
74
+ ```ts title="quickback.config.ts"
75
+ providers: {
76
+ auth: defineAuth("better-auth", {
77
+ operatorMfa: true,
78
+ plugins: ["passkey", "admin"],
79
+ }),
80
+ },
81
+ ```
82
+
83
+ With it on, an `appmanager` or `sysadmin` whose session was **not** established by a passkey assertion or a two-factor verification is treated as a plain `user` for that request. Every operator surface refuses with `403 MFA_REQUIRED`: the CMS and `/api/v1/schema`, the `/auth/v1/admin/*` operator routes, Better Auth's own admin endpoints (`list-users`, `set-role`, `ban-user`), and the sysadmin cross-tenant bypass. The Account UI keeps working, so the enrolment path is short:
84
+
85
+ 1. Sign in with a password (or magic link / OTP) as usual.
86
+ 2. Register a passkey at `/account/passkeys/setup`.
87
+ 3. Sign out, then sign back in **with the passkey**.
88
+
89
+ How it works: the compiler adds a `session.amr` column (RFC 8176, *Authentication Methods Reference*) and a `session.create.before` hook that stamps `passkey` when the session comes from `/passkey/verify-authentication` and `mfa` when it comes from `/two-factor/verify-*`. Nothing else sets it, and it is not client-settable. The auth middleware reads it on the session lane and copies it into the JWT fast-path claims, so bearer callers are gated identically.
90
+
91
+ Things to know:
92
+
93
+ - **Requires `passkey` or `twoFactor`.** The compile fails otherwise: without a second factor to enrol, every operator would be locked out.
94
+ - **Passkey sign-in only.** A user who has a passkey but signs in with a password is not MFA'd; the session has to be created by the passkey assertion.
95
+ - **Two-factor "trust this device"** skips the verify endpoint, so a trusted-device sign-in does not count. Operators should not use it.
96
+ - **API keys never satisfy it.** An operator's API key is a single factor; operator routes reject it with `MFA_REQUIRED`.
97
+ - **Existing projects** get a new `amr` column on the auth `session` table on the next compile; apply the generated auth migration before deploying.
98
+
70
99
  ## Custom Admin Domain
71
100
 
72
101
  Give the admin panel its own subdomain with `adminDomain`:
@@ -14,6 +14,8 @@ Users can see all devices where they're currently logged in, including:
14
14
 
15
15
  Users can revoke any session except their current one. This immediately invalidates the session token.
16
16
 
17
+ Two events revoke other sessions without a click: changing the password from the profile page (the UI sends `revokeOtherSessions: true`), and resetting it through the forgot-password flow (the server default `revokeSessionsOnPasswordReset: true`, see [Session Freshness and Password Reset](/platform/auth/security#session-freshness-and-password-reset)).
18
+
17
19
  ## Related
18
20
 
19
21
  - [Environment Variables](/ui/account/environment-variables)