@quickback-dev/cli 0.72.6 → 0.72.8

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 (47) hide show
  1. package/dist/commands/migrations-baseline.d.ts +2 -0
  2. package/dist/commands/migrations-baseline.d.ts.map +1 -0
  3. package/dist/commands/migrations-baseline.js +29 -0
  4. package/dist/commands/migrations-baseline.js.map +1 -0
  5. package/dist/commands/migrations.d.ts.map +1 -1
  6. package/dist/commands/migrations.js +16 -9
  7. package/dist/commands/migrations.js.map +1 -1
  8. package/dist/index.js +2 -2
  9. package/dist/lib/migrations/baseline.d.ts +26 -0
  10. package/dist/lib/migrations/baseline.d.ts.map +1 -0
  11. package/dist/lib/migrations/baseline.js +258 -0
  12. package/dist/lib/migrations/baseline.js.map +1 -0
  13. package/dist/lib/migrations/sqlite-baseline-worker.d.ts +3 -0
  14. package/dist/lib/migrations/sqlite-baseline-worker.d.ts.map +1 -0
  15. package/dist/lib/migrations/sqlite-baseline-worker.js +86 -0
  16. package/dist/lib/migrations/sqlite-baseline-worker.js.map +1 -0
  17. package/dist/skill/docs/api/actions.md +37 -1
  18. package/dist/skill/docs/api/openapi.md +2 -0
  19. package/dist/skill/docs/api/views.md +5 -1
  20. package/dist/skill/docs/changelog/index.md +29 -0
  21. package/dist/skill/docs/configure/agents.md +16 -0
  22. package/dist/skill/docs/define/access.md +2 -0
  23. package/dist/skill/docs/define/encryption.md +1 -1
  24. package/dist/skill/docs/define/scopes.md +1 -1
  25. package/dist/skill/docs/define/views.md +8 -0
  26. package/dist/skill/docs/platform/auth/index.md +10 -1
  27. package/dist/skill/docs/platform/auth/security.md +16 -0
  28. package/dist/skill/docs/platform/database/schema-baselines.md +86 -0
  29. package/dist/skill/docs/tooling/cli.md +13 -0
  30. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -0
  31. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +19 -1
  32. package/package.json +1 -1
  33. package/src/skill/docs/api/actions.md +37 -1
  34. package/src/skill/docs/api/openapi.md +2 -0
  35. package/src/skill/docs/api/views.md +5 -1
  36. package/src/skill/docs/changelog/index.md +29 -0
  37. package/src/skill/docs/configure/agents.md +16 -0
  38. package/src/skill/docs/define/access.md +2 -0
  39. package/src/skill/docs/define/encryption.md +1 -1
  40. package/src/skill/docs/define/scopes.md +1 -1
  41. package/src/skill/docs/define/views.md +8 -0
  42. package/src/skill/docs/platform/auth/index.md +10 -1
  43. package/src/skill/docs/platform/auth/security.md +16 -0
  44. package/src/skill/docs/platform/database/schema-baselines.md +86 -0
  45. package/src/skill/docs/tooling/cli.md +13 -0
  46. package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -0
  47. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +19 -1
@@ -84,8 +84,12 @@ Opting in exposes auth tools only to callers that authenticated to `/mcp` with a
84
84
 
85
85
  Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a JSON Schema combining the request body with every parameter in the operation's **mounted** path — including the `:params` contributed by a namespace prefix (e.g. `/scope/:scopeId/...`), so a standalone or namespace action is always callable, not just record-based ones. Nested `z.object` inputs are preserved as nested objects rather than flattened, so the model sees each field's real type.
86
86
 
87
+ List and view tools take the same query arguments as the REST endpoint: `limit`, `offset`, `sort`, `order`, and on the collection read also `starting_after`, `ending_before`, `total`, `fields`, `search` and the column filters. See [Query parameters](/api/query-params).
88
+
87
89
  `tools/call` re-enters the same Hono app via `app.request(...)` — so **every existing middleware runs exactly as it would for a direct REST call**: authentication, firewall, access control, guards, masking. No bypass.
88
90
 
91
+ A [`PUBLIC`](/define/access) read on an org-scoped table takes an `organizationId` argument: an anonymous agent passes it to name the organization whose public rows it wants, and gets `ORG_REQUIRED` without it. It is forwarded as `?organizationId=`, the same as a REST call. Tools for authenticated-only operations don't have it; those act in the caller's active organization.
92
+
89
93
  Path and query arguments go into the URL; the rest become the JSON body. A `POST`, `PUT` or `PATCH` tool always sends a JSON body, even when the operation has no body fields (an action with `input: z.object({})` and only path params is sent `{}`), so it passes the same body validation as a REST call. A `DELETE` tool sends a JSON body only when the operation declares body fields (batch delete sends `{ ids, options }`); single-record `DELETE` and `GET` tools send no body.
90
94
 
91
95
  ### Access-filtered `tools/list`
@@ -154,6 +158,18 @@ The access tokens it issues carry the OAuth issuer (`BETTER_AUTH_URL` + `/auth/v
154
158
 
155
159
  The middleware accepts these tokens only while their Better Auth session (`sid`) is live, and builds the user's context from it — but **not the session's organization**. A token whose audience is a scope kind's resource is the other lane: confined to one instance, no session — see [Instance-bound OAuth tokens](/define/scopes#instance-bound-oauth-tokens).
156
160
 
161
+ #### Grant lifetime
162
+
163
+ An ordinary grant lives and dies with the sign-in session it was issued under. The token endpoint and the middleware apply the same check — the session row exists, belongs to the user and has not expired — so they cannot disagree:
164
+
165
+ - **Use.** The middleware refuses an access token whose session has ended.
166
+ - **Refresh.** `POST /oauth2/token` with `grant_type=refresh_token` fails with `400 invalid_grant` once the session has ended, and deletes the refresh tokens issued under it. The connector gets a clean signal to sign in again instead of a token that every request rejects. (Better Auth makes this check at the code exchange but not at refresh; the generated `oauthProvider` extension adds it.)
167
+ - **A connector in use keeps its session live.** Each successful refresh slides the session the way Better Auth's own `/get-session` does: by `session.expiresIn`, at most once per `session.updateAge`. A grant therefore does not end `session.expiresIn` after consent just because the user never reopened the browser. A session that has already lapsed or been deleted is never revived, `session.disableSessionRefresh` turns the slide off, and an impersonation session is never extended.
168
+
169
+ Everything that ends the session ends the grant at both endpoints: sign-out, sign-out-everywhere, a password change or reset that revokes sessions, an admin revoking the user's sessions, a ban, and deleting the user. Revoking the refresh token (`POST /oauth2/revoke`) and removing the user's membership in the consented workspace end it too. An unused grant ends when its refresh token expires (`refreshTokenExpiresIn`, 30 days by default) or its session lapses, whichever comes first.
170
+
171
+ `plugins.oauthProvider.extensions` is generated for this check; setting it is an error. Add your own extension from a custom plugin with `extendOAuthProvider()`.
172
+
157
173
  #### Workspace-bound tokens
158
174
 
159
175
  With the organization plugin on, an ordinary OAuth token is bound to the workspace the user **consented in**, following Better Auth's own `postLogin.consentReferenceId` pattern:
@@ -284,6 +284,8 @@ GET /api/v1/listings?organizationId=org_abc123
284
284
 
285
285
  The firewall WHERE clause is always enforced. If no `organizationId` is provided, the API returns a `403` with code `ORG_REQUIRED`.
286
286
 
287
+ The parameter is part of the published contract. Every `PUBLIC` route on an org-scoped table that reads it — the collection, `GET /:id`, named views, and a `PUBLIC` `update` / `delete` / `PUT /:id` — declares an optional `organizationId` query parameter in the [OpenAPI spec](/api/openapi), so the generated types, the client SDK and the matching [MCP tool](/configure/agents#tools) can all send it. Authenticated-only routes don't declare it, and neither do `PUBLIC` routes on owner-scoped or unscoped tables: there is no tenant to name. A signed-in caller acts in their active organization; passing a different `organizationId` is a `403 CROSS_TENANT_FORBIDDEN`.
288
+
287
289
  `?organizationId=` is an account/public addressing surface. A request using a
288
290
  configured delegated principal cannot use it to acquire account organization
289
291
  authority: the generated route returns `403 CROSS_TENANT_FORBIDDEN` and never
@@ -143,7 +143,7 @@ The keys never move into the object:
143
143
  - Values at rest look the same (`qbenc:2:<keyVersion>:…`, bound to organization + table + column), but a tenant ciphertext does not open with the edge DEK, and an edge ciphertext does not open in the object.
144
144
  - Rotation is the envelope tier's. [`rotateOrgDataKey`](#rotating-an-organizations-dek) starts a new tenant key version and retired versions keep reading; [`rewrapOrgDataKeys`](#rotating-encryption_kek) changes nothing the object sees; deleting the organization's `org_data_keys` row shreds its tenant values too. Warm edge isolates hand out the previous key set for up to five minutes after a rotation; a value sealed under the new version in that window reads as `ENCRYPTION_UNREADABLE` from such an isolate until its cache refreshes.
145
145
  - **Fail closed.** Tenant schedules, tenant jobs and alarms run without a forwarded request and carry no key: a write to an encrypted column there throws before any row is written, and nothing opens a value. Write and open encrypted tenant columns from actions and routes.
146
- - Tenant feature files that import `lib/encryption` or `lib/secrets` are re-pointed at the tenant runtime. A shared `quickback/lib` helper that still reaches either from tenant code fails the build (`TENANCY_EDGE_IMPORT_IN_TENANT`), like `lib/realtime`.
146
+ - Tenant feature files that import `lib/encryption` or `lib/secrets` are re-pointed at the tenant runtime. A shared `quickback/lib` helper that still reaches either from tenant code fails the build (`TENANCY_EDGE_IMPORT_IN_TENANT`), like `lib/realtime`. Platform tables with encrypted columns are unaffected: the edge keeps sealing and opening them with the organization DEK, and the tenant Worker never runs their files.
147
147
 
148
148
  ### Moving an existing plaintext column to `q.secret()`
149
149
 
@@ -945,7 +945,7 @@ The namespace gate re-proves the relationship on every request, as it does for a
945
945
  > A claimed table's [legacy forward](/define/areas#keeping-the-old-url-legacy) does not widen this: it refuses an instance-bound token and every caller without an active organization (`403 LEGACY_ORG_REQUIRED`), and it only forwards into an instance of the caller's own organization.
946
946
 
947
947
 
948
- Ordinary OAuth tokens (MCP clients, audience = origin or `/mcp`) are unchanged: they still need a live session and get the user's full context.
948
+ Ordinary OAuth tokens (MCP clients, audience = origin or `/mcp`) are unchanged: they still need a live session — at use and at every refresh, see [Grant lifetime](/configure/agents#grant-lifetime) — and get the user's full context.
949
949
 
950
950
  ### Revoke one instance
951
951
 
@@ -208,6 +208,14 @@ read: {
208
208
  }
209
209
  ```
210
210
 
211
+ A view can be `PUBLIC` while the rest of the resource stays members-only. On an org-scoped table an anonymous caller names the organization with `?organizationId=`; without it the view returns `403 ORG_REQUIRED`:
212
+
213
+ ```bash
214
+ GET /api/v1/jobs/views/careers?organizationId=org_abc123
215
+ ```
216
+
217
+ The view's OpenAPI operation and MCP tool declare `organizationId` for this case. See [`PUBLIC`](/define/access).
218
+
211
219
  ### Masking
212
220
 
213
221
  Masking rules are applied to the returned fields. If a view includes a masked field like `email`, the masking rules still apply:
@@ -70,7 +70,7 @@ role. Better Auth's own API is the gate for its tables.
70
70
  ## Compiler-managed auth versions and upgrades
71
71
 
72
72
  The compiler pins Better Auth, its schema CLI, and the generated companion
73
- packages to **1.7.3**. Recompile and install the emitted dependencies together;
73
+ packages to **1.7.17**. Recompile and install the emitted dependencies together;
74
74
  remove older Better Auth overrides from `build.dependencies`. An incompatible
75
75
  override is rejected because it would run a different auth version from the
76
76
  one that generated your schema.
@@ -81,6 +81,15 @@ migration history stays on your machine. Apply the newly generated auth
81
81
  migration before starting the updated Worker. Existing migration SQL is
82
82
  preserved.
83
83
 
84
+ This release includes the upstream fixes for Magic Link/OAuth account takeover,
85
+ OAuth Proxy account takeover, and concurrent PostgreSQL rate-limit bypasses.
86
+ Upgrade every deployment sharing verification storage or OAuth Proxy flows
87
+ together, including preview and development deployments. Request fresh Magic
88
+ Links and restart pending OAuth/SAML sign-in and account-linking flows after
89
+ the upgrade: state issued by older versions may no longer complete. These
90
+ security fixes do not themselves require a database schema migration; projects
91
+ upgrading from older auth schemas should still apply any emitted migrations.
92
+
84
93
  ### Upgrading from 1.6
85
94
 
86
95
  The upgrade adds the current JWT/OAuth schema, including JWKS `alg`/`crv` and
@@ -346,6 +346,22 @@ auth: defineAuth("better-auth", {
346
346
  - Cannot selectively allow only specific subdomains
347
347
  - All-or-nothing: either exact domain only, or all subdomains
348
348
 
349
+ #### Cookie prefix
350
+
351
+ Better Auth names its cookies `<prefix>.session_token`, and the prefix is `better-auth` unless you change it:
352
+
353
+ ```ts
354
+ auth: defineAuth("better-auth", {
355
+ advanced: {
356
+ cookiePrefix: 'kindling' // cookies become kindling.session_token, …
357
+ }
358
+ })
359
+ ```
360
+
361
+ Set it when two separate Better Auth deployments live under one domain and either of them shares its cookie across subdomains. Say `auth.example.com` shares a cookie on `example.com` and a second, unrelated deployment runs at `id.team.example.com`. A browser sends both cookies to the second host, the names are the same, and which session the server reads depends on cookie order. A different prefix on one of them keeps the two apart.
362
+
363
+ Apps that share one session must use the same prefix: an identity service and every app that reads its session cookie. The prefix may contain letters, digits, `-` and `_`. Changing it on a live app signs everyone out, because the old cookie is no longer read.
364
+
349
365
  #### 2. Trusted Origins (Application-Level)
350
366
 
351
367
  ```ts
@@ -0,0 +1,86 @@
1
+ # Schema Baselines
2
+
3
+ `quickback migrations baseline` replaces a long **D1/SQLite schema history**
4
+ with a compact baseline. It uses the project's pinned `drizzle-kit@0.31.10`
5
+ and requires Node.js 22.13 or newer for the isolated SQLite replay. The rest
6
+ of the CLI retains its existing Node requirement.
7
+
8
+ ```bash
9
+ quickback migrations baseline --database features # preview; migration files unchanged
10
+ quickback migrations baseline --database features --write # explicit local cutover
11
+ quickback migrations baseline --database auth --write # separate history/database
12
+ ```
13
+
14
+ This first version supports `auth` and `features` histories with SQLite v6
15
+ Drizzle snapshots and Wrangler's default `d1_migrations` ledger. It does not
16
+ support PostgreSQL, tenant Durable Objects, custom/broker-managed migration ledgers, virtual
17
+ tables, or histories that attach databases/load extensions. It refuses unknown
18
+ arguments, broken journals, missing SQL, broken snapshot chains and symlinks.
19
+ No command here connects to a database or invokes Wrangler. Use the standard
20
+ Wrangler D1 migration runner for adoption; broker-managed deployment ledgers
21
+ require a separate adoption protocol and are not supported.
22
+
23
+ ## What is compacted
24
+
25
+ The command replays the SQL history in an isolated in-memory SQLite process,
26
+ validates the final snapshot through Drizzle, and checks its table, column,
27
+ foreign-key and index contracts. It exports the final tables, indexes, views,
28
+ triggers, migration seed rows (including blobs and large integers), and
29
+ AUTOINCREMENT sequences. Seed expressions such as random ids or timestamps are
30
+ materialized at preparation time; the SQL filename addresses those actual bytes. Replaying the proposed baseline must reproduce that
31
+ state exactly and pass foreign-key checks.
32
+
33
+ The result is one `0000_quickback_baseline_<digest>.sql` and a rooted snapshot
34
+ and journal. A compiler-owned trigger document, when present, remains as a
35
+ second SQL migration under its content hash. This preserves trigger deduplication
36
+ and later trigger removal; concatenating old SQL would not do that. Custom
37
+ triggers remain in the schema baseline, after the seed inserts.
38
+
39
+ `--write` uses the same project migration lock as builds, rechecks the source
40
+ inventory, stages the complete tree, and keeps the original tree byte-for-byte
41
+ under `quickback/.archives/migration-baselines/<database>/<digest>/`. It writes
42
+ reviewable `manifest.json` and `adopt.sql` under
43
+ `quickback/baselines/<database>/<digest>/`. Commit the baseline and review
44
+ artifacts. Keep the archive until every deployed database has crossed over;
45
+ standard Quickback ignores `.archives/`. An ordinary write failure restores
46
+ the original tree. If the process or machine dies during the rename cutover,
47
+ recover the original tree from that archive before another build or deploy.
48
+
49
+ This is an explicit replacement path. Normal `quickback build` remains additive
50
+ and never rewrites applied migrations. `meta/_baseline.json` retains retired
51
+ ledger names so a later rebaseline can recognize previously adopted databases.
52
+
53
+ ## Fresh versus existing databases
54
+
55
+ **Fresh databases:** apply the compact SQL files normally with Wrangler. Each
56
+ migration is applied in a transaction; the schema baseline defers foreign keys
57
+ while inserting its seed rows. A baseline is a schema bootstrap, not an export
58
+ of production rows or encrypted integration secrets.
59
+
60
+ **Existing databases:** do not run the baseline's CREATE statements against them.
61
+
62
+ 1. Back up each target and stop deployment jobs that could apply migrations.
63
+ 2. Using the original history, apply every pending migration up to the cutoff.
64
+ 3. Prepare and review the baseline locally. Rebuild the project and inspect the
65
+ next Drizzle migration; an unchanged schema should produce none.
66
+ 4. Test `adopt.sql` against a populated local copy or disposable staging target.
67
+ 5. Execute the reviewed `adopt.sql` on each matching existing D1 database **before**
68
+ running normal migration application with the compacted files.
69
+ 6. Apply subsequent migrations and test the application. Repeat independently
70
+ for auth/features and every environment.
71
+
72
+ The adoption SQL performs a single atomic INSERT into `d1_migrations`. It
73
+ requires every source migration name, permits only known retired/baseline names,
74
+ and checks the exact schema catalog, including triggers and indexes. A mismatch
75
+ raises a malformed-JSON error and records **no** baseline names. Equivalent
76
+ schemas with different SQL text are deliberately refused; investigate instead
77
+ of bypassing the guard. A repeat adoption inserts no duplicate names. Old ledger
78
+ rows are retained, and application tables/rows are never changed by adoption.
79
+ The generated statement is limited to a conservative 64 KiB; larger statements
80
+ refuse preparation rather than produce an unchecked cutover.
81
+
82
+ Do not edit the manifest or adoption guard to silence a mismatch. Missing history
83
+ must be recovered from a trusted archive or deployment artifact, not invented.
84
+ A new baseline changes which migration filenames are pending on an existing
85
+ DB, so deploying compacted files without the adoption step will attempt to
86
+ recreate tables.
@@ -355,6 +355,19 @@ also writes `.dev.vars.example` with every declared secret, for local
355
355
  `wrangler dev`. Neon and PlanetScale keep their own template, and any declared
356
356
  secret it lacks is appended to it.
357
357
 
358
+ ### Compact D1 Schema Migrations
359
+
360
+ ```bash
361
+ quickback migrations baseline --database features
362
+ quickback migrations baseline --database features --write
363
+ ```
364
+
365
+ Preview by default. `--write` stages a compact Drizzle baseline, preserves the
366
+ original history, and writes guarded adoption SQL for existing databases.
367
+ Supports D1 auth/features histories; requires Node 22.13+ and the pinned
368
+ Drizzle version. Read [Schema Baselines](/platform/database/schema-baselines)
369
+ before deploying compacted files to an existing database.
370
+
358
371
  ### Run Data Migrations
359
372
 
360
373
  ```bash
@@ -30,6 +30,8 @@ The API key takes precedence over stored credentials from `quickback login`.
30
30
 
31
31
  The compiler-cloud worker validates authentication by forwarding your credentials to the Quickback API's Better Auth `GET /auth/v1/get-session` endpoint via a [Cloudflare service binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/). This resolves both session tokens (from `quickback login`) and API keys (from `QUICKBACK_API_KEY`, sent as `x-api-key` — `get-session` is the only Better Auth endpoint that accepts a key in place of a session).
32
32
 
33
+ A valid session is enough for a validation compile. A complete compile also needs the account behind it — the session's user, or the API key's owner — to be non-anonymous with a verified email, and it counts toward a daily per-account limit. See [Who can run which compile](/tooling/cloud-compiler/endpoints#who-can-run-which-compile).
34
+
33
35
  ## Credential Storage
34
36
 
35
37
  Credentials are stored at `~/.quickback/credentials.json`:
@@ -19,6 +19,24 @@ The cloud compiler API is hosted at `https://compiler.quickback.dev`
19
19
 
20
20
  The `/compile` endpoint requires either a session token (from `quickback login`) or an API key (via `QUICKBACK_API_KEY` header). See [Authentication](/tooling/cloud-compiler/authentication) for details.
21
21
 
22
+ ### Who can run which compile
23
+
24
+ | Compile | Who |
25
+ |---------|-----|
26
+ | Validation (`?complete=false`) | Any session, including an anonymous one. [Start](https://start.quickback.dev) runs them for signed-out visitors through its own server-side token. |
27
+ | Complete (`?complete=true`, the default) | A Quickback account that is **not anonymous** and has a **verified email**, within a per-account daily limit. |
28
+
29
+ A complete compile that is refused answers with a JSON body carrying `error`, `code` and `hint`:
30
+
31
+ | Status | `code` | Meaning |
32
+ |--------|--------|---------|
33
+ | 403 | `ANONYMOUS_SESSION` | Anonymous sessions run validation compiles only. Create an account and run `quickback login`. |
34
+ | 403 | `EMAIL_NOT_VERIFIED` | Verify your email address first. |
35
+ | 403 | `BUILDER_ACCESS_REQUIRED` | Complete compiles are limited to approved accounts while access is in private beta. |
36
+ | 429 | `COMPILE_QUOTA_EXCEEDED` | The account used its complete compiles for the day. `Retry-After` gives the seconds until the limit resets at 00:00 UTC. |
37
+
38
+ Every admitted complete compile that counts toward the limit carries `X-Quickback-Compile-Quota-Limit` and `X-Quickback-Compile-Quota-Remaining`. A compile that never ran (all compiler instances busy, `503 COMPILER_BUSY`) does not count. Validation compiles are never limited this way.
39
+
22
40
  ## Raw-files mode (`POST /compile`)
23
41
 
24
42
  `/compile` normally expects the parsed `CompilerInput` the CLI assembles client-side. Thin clients (agents, web builders, CI without the CLI) can instead send the project sources verbatim and let the compiler organize them server-side:
@@ -61,7 +79,7 @@ without producing a runtime writes exactly the tagged files from a
61
79
 
62
80
  ## Edge validation backend
63
81
 
64
- Validation compiles (`POST /compile?complete=false`) may be served by an edge Worker instead of the compiler container. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.
82
+ Validation compiles (`POST /compile?complete=false`) are served by an edge Worker instead of the compiler container. The edge Worker has no public URL of its own; `compiler.quickback.dev` checks auth and then forwards to it. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.
65
83
 
66
84
  The response header `X-Quickback-Compile-Backend` says which backend answered:
67
85