@quickback-dev/cli 0.70.45 → 0.72.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +10 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +7 -1
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +6 -5
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +6 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -1
- package/dist/lib/access-manifest-diff.js +10 -0
- package/dist/lib/access-manifest-diff.js.map +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +36 -0
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +13 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +4 -0
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/file-loader.d.ts +22 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +80 -18
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.js +9 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +10 -0
- package/dist/lib/harness.d.ts.map +1 -1
- package/dist/lib/harness.js +31 -0
- package/dist/lib/harness.js.map +1 -1
- package/dist/lib/migrations/executor.js +5 -1
- package/dist/lib/migrations/executor.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +23 -2
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +13 -1
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +33 -2
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +2 -2
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +3 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +14 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +29 -7
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/docs/api/actions.md +73 -2
- package/dist/skill/docs/api/batch-operations.md +2 -0
- package/dist/skill/docs/api/caching.md +2 -2
- package/dist/skill/docs/api/crud.md +13 -0
- package/dist/skill/docs/api/errors.md +111 -10
- package/dist/skill/docs/api/index.md +24 -0
- package/dist/skill/docs/api/openapi.md +8 -0
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/configure/agents.md +73 -1
- package/dist/skill/docs/configure/auth.md +7 -1
- package/dist/skill/docs/configure/bindings.md +55 -0
- package/dist/skill/docs/configure/cloudflare-access.md +191 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +4 -2
- package/dist/skill/docs/configure/providers.md +2 -1
- package/dist/skill/docs/configure/tenancy.md +3 -0
- package/dist/skill/docs/configure/tenant-databases.md +2407 -0
- package/dist/skill/docs/define/access.md +33 -1
- package/dist/skill/docs/define/actions/defining.md +118 -1
- package/dist/skill/docs/define/actions/scoped-db.md +32 -8
- package/dist/skill/docs/define/areas.md +145 -2
- package/dist/skill/docs/define/diagnostics.md +160 -21
- package/dist/skill/docs/define/encryption.md +13 -2
- package/dist/skill/docs/define/fga.md +320 -42
- package/dist/skill/docs/define/firewall.md +4 -0
- package/dist/skill/docs/define/index.md +1 -0
- package/dist/skill/docs/define/read.md +39 -0
- package/dist/skill/docs/define/relationships.md +30 -12
- package/dist/skill/docs/define/schema.md +2 -0
- package/dist/skill/docs/define/scopes.md +393 -9
- package/dist/skill/docs/define/sealed-protocol.md +67 -12
- package/dist/skill/docs/define/transitions.md +4 -1
- package/dist/skill/docs/define/triggers.md +55 -1
- package/dist/skill/docs/platform/api-contract/index.md +4 -2
- package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/dist/skill/docs/platform/auth/using-auth.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +112 -3
- package/dist/skill/docs/platform/database/data-migrations.md +3 -1
- package/dist/skill/docs/platform/database/neon.md +10 -2
- package/dist/skill/docs/platform/queues/handlers.md +48 -16
- package/dist/skill/docs/platform/queues/using-queues.md +16 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/dist/skill/docs/platform/realtime/index.md +9 -6
- package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/r2.md +10 -1
- package/dist/skill/docs/platform/storage/using-r2.md +42 -1
- package/dist/skill/docs/tooling/output.md +9 -2
- package/dist/skill/docs/ui/account/features/admin.md +5 -3
- package/dist/skill/docs/ui/account/hooks.md +9 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +73 -2
- package/src/skill/docs/api/batch-operations.md +2 -0
- package/src/skill/docs/api/caching.md +2 -2
- package/src/skill/docs/api/crud.md +13 -0
- package/src/skill/docs/api/errors.md +111 -10
- package/src/skill/docs/api/index.md +24 -0
- package/src/skill/docs/api/openapi.md +8 -0
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/configure/agents.md +73 -1
- package/src/skill/docs/configure/auth.md +7 -1
- package/src/skill/docs/configure/bindings.md +55 -0
- package/src/skill/docs/configure/cloudflare-access.md +191 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +4 -2
- package/src/skill/docs/configure/providers.md +2 -1
- package/src/skill/docs/configure/tenancy.md +3 -0
- package/src/skill/docs/configure/tenant-databases.md +2407 -0
- package/src/skill/docs/define/access.md +33 -1
- package/src/skill/docs/define/actions/defining.md +118 -1
- package/src/skill/docs/define/actions/scoped-db.md +32 -8
- package/src/skill/docs/define/areas.md +145 -2
- package/src/skill/docs/define/diagnostics.md +160 -21
- package/src/skill/docs/define/encryption.md +13 -2
- package/src/skill/docs/define/fga.md +320 -42
- package/src/skill/docs/define/firewall.md +4 -0
- package/src/skill/docs/define/index.md +1 -0
- package/src/skill/docs/define/read.md +39 -0
- package/src/skill/docs/define/relationships.md +30 -12
- package/src/skill/docs/define/schema.md +2 -0
- package/src/skill/docs/define/scopes.md +393 -9
- package/src/skill/docs/define/sealed-protocol.md +67 -12
- package/src/skill/docs/define/transitions.md +4 -1
- package/src/skill/docs/define/triggers.md +55 -1
- package/src/skill/docs/platform/api-contract/index.md +4 -2
- package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/src/skill/docs/platform/auth/using-auth.md +1 -1
- package/src/skill/docs/platform/database/d1.md +112 -3
- package/src/skill/docs/platform/database/data-migrations.md +3 -1
- package/src/skill/docs/platform/database/neon.md +10 -2
- package/src/skill/docs/platform/queues/handlers.md +48 -16
- package/src/skill/docs/platform/queues/using-queues.md +16 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/src/skill/docs/platform/realtime/index.md +9 -6
- package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/r2.md +10 -1
- package/src/skill/docs/platform/storage/using-r2.md +42 -1
- package/src/skill/docs/tooling/output.md +9 -2
- package/src/skill/docs/ui/account/features/admin.md +5 -3
- package/src/skill/docs/ui/account/hooks.md +9 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/dist/codex/AGENTS.md +0 -290
- package/dist/commands/build.test.d.ts.map +0 -1
- package/dist/commands/codex.d.ts +0 -16
- package/dist/commands/codex.d.ts.map +0 -1
- package/dist/commands/codex.js +0 -159
- package/dist/commands/codex.js.map +0 -1
- package/dist/commands/compile.d.ts +0 -62
- package/dist/commands/compile.d.ts.map +0 -1
- package/dist/commands/compile.js +0 -830
- package/dist/commands/compile.js.map +0 -1
- package/dist/commands/compile.test.d.ts.map +0 -1
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/commands/migrate.test.d.ts.map +0 -1
- package/dist/commands/migrations.test.d.ts.map +0 -1
- package/dist/commands/push.test.d.ts.map +0 -1
- package/dist/commands/schema.test.d.ts.map +0 -1
- package/dist/docs/content.d.ts +0 -7
- package/dist/docs/content.d.ts.map +0 -1
- package/dist/docs/content.js +0 -672
- package/dist/docs/content.js.map +0 -1
- package/dist/docs/index.test.d.ts.map +0 -1
- package/dist/lib/action-harvest.test.d.ts.map +0 -1
- package/dist/lib/api-client.test.d.ts.map +0 -1
- package/dist/lib/artifact-routing.test.d.ts.map +0 -1
- package/dist/lib/auth.test.d.ts.map +0 -1
- package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
- package/dist/lib/compiler-floor.test.d.ts.map +0 -1
- package/dist/lib/config-id-splice.test.d.ts.map +0 -1
- package/dist/lib/config-sync.test.d.ts.map +0 -1
- package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
- package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
- package/dist/lib/file-loader.test.d.ts.map +0 -1
- package/dist/lib/file-writer.test.d.ts.map +0 -1
- package/dist/lib/helpers.d.ts +0 -39
- package/dist/lib/helpers.d.ts.map +0 -1
- package/dist/lib/helpers.js +0 -299
- package/dist/lib/helpers.js.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
- package/dist/lib/migrations/executor.test.d.ts.map +0 -1
- package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
- package/dist/lib/migrations/lock.test.d.ts.map +0 -1
- package/dist/lib/migrations/paths.test.d.ts.map +0 -1
- package/dist/lib/migrations/plan.test.d.ts.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/staging.test.d.ts.map +0 -1
- package/dist/lib/neon-canary.test.d.ts.map +0 -1
- package/dist/lib/neon-target.test.d.ts.map +0 -1
- package/dist/lib/neon.test.d.ts.map +0 -1
- package/dist/lib/prepare-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
- package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
- package/dist/lib/shell.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
|
@@ -36,7 +36,7 @@ When `auth.admin` is `false` (the default), the admin surface does not exist for
|
|
|
36
36
|
- **Create an organization** — you name the **owner**; the operator creating it is deliberately not seated (see below)
|
|
37
37
|
- **Seat, re-role and remove members** — manage a tenant's roster without joining it
|
|
38
38
|
|
|
39
|
-
These run on `/auth/v1/admin
|
|
39
|
+
These run on `/api/v1/operator/organizations` (under `/auth/v1/admin/*` before 0.72; see [Moved routes](/api#moved-routes-072)), emitted by Quickback because Better Auth's organization plugin cannot serve them: every one of its endpoints resolves through the *caller's* membership, and an operator administers organizations it does not belong to. Put them behind [Cloudflare Access](/configure/cloudflare-access#the-operator-plane) with one path rule.
|
|
40
40
|
|
|
41
41
|
> **Users sign themselves up.** Self-serve signup stays on — a new account simply has no organization, and lands on a screen saying so until someone invites or seats them. What operators control is *organizations*, not accounts.
|
|
42
42
|
|
|
@@ -56,7 +56,7 @@ The admin panel is restricted to platform roles on the Better Auth user record:
|
|
|
56
56
|
>
|
|
57
57
|
> Equal tier is allowed, so an appmanager can still make another appmanager (the example below). Only a `sysadmin` can grant `sysadmin`.
|
|
58
58
|
>
|
|
59
|
-
>
|
|
59
|
+
> Seating a member (`PUT /api/v1/operator/organizations/:id/members/:userId`) refuses to seat its caller with `403 OPERATOR_SELF_SEAT`: operators are never seated by their own control-plane calls.
|
|
60
60
|
|
|
61
61
|
|
|
62
62
|
To grant operator access to a user:
|
|
@@ -89,7 +89,7 @@ providers: {
|
|
|
89
89
|
},
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
-
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 `/
|
|
92
|
+
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 `/api/v1/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:
|
|
93
93
|
|
|
94
94
|
1. Sign in with a password (or magic link / OTP) as usual.
|
|
95
95
|
2. Register a passkey at `/account/passkeys/setup`.
|
|
@@ -97,6 +97,8 @@ With it on, an `appmanager` or `sysadmin` whose session was **not** established
|
|
|
97
97
|
|
|
98
98
|
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.
|
|
99
99
|
|
|
100
|
+
Cloudflare Access is recommended additionally for `/api/v1/operator`. It does not replace `operatorMfa`: Better Auth admin endpoints and the other operator powers still need the application second factor. Configuring Access with `operatorMfa` off emits a compile warning.
|
|
101
|
+
|
|
100
102
|
Things to know:
|
|
101
103
|
|
|
102
104
|
- **Requires `passkey` or `twoFactor`.** The compile fails otherwise: without a second factor to enrol, every operator would be locked out.
|
|
@@ -142,6 +142,10 @@ before calling `quickback/hooks/resolve-oauth-context.ts`. Use this trusted
|
|
|
142
142
|
server hook when tenant selection cannot be derived solely from the session's
|
|
143
143
|
active organization.
|
|
144
144
|
|
|
145
|
+
It never runs for an [instance-bound token](/define/scopes#instance-bound-oauth-tokens)
|
|
146
|
+
(audience = a scope kind's resource): that principal is confined to one
|
|
147
|
+
instance and gets no tenant context.
|
|
148
|
+
|
|
145
149
|
```ts title="quickback/hooks/resolve-oauth-context.ts"
|
|
146
150
|
import type { OAuthContextResolver } from '@quickback/compiler';
|
|
147
151
|
|
|
@@ -328,7 +332,7 @@ type HookCtx = {
|
|
|
328
332
|
};
|
|
329
333
|
```
|
|
330
334
|
|
|
331
|
-
`authDb` is the
|
|
335
|
+
`authDb` is the Drizzle connection to the auth DB. Read through it freely; for writes, prefer Better Auth's API (`auth.api.*`; `ctx.auth` in actions), which runs Better Auth's own hooks and revokes sessions. A direct insert, update, or delete on a Better Auth table is flagged [`ACTION_AUTH_DB_WRITE`](/define/diagnostics#action_auth_db_write) — in `hooks/` as a **warning**, never a compile error. Where no endpoint fits, such as the server-side org create below (see the [CSRF caveat](#csrf-caveat-server-side-org-create)), keep the write and mark it with `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>`. `authSchema` is the namespace export of the generated auth schema module; destructure the tables you need.
|
|
332
336
|
|
|
333
337
|
This injection is unique to account hooks. Actions reach AUTH_DB via `c.get("authDb")` ([Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb)). Trigger handlers on a table file get neither — use `ctx` for the acting user, and do not import `../../auth/schema` from the table file.
|
|
334
338
|
|
|
@@ -393,6 +397,7 @@ export default async (user, { authDb, authSchema }) => {
|
|
|
393
397
|
.where(eq(organization.id, orgId));
|
|
394
398
|
if (existing.length > 0) return;
|
|
395
399
|
|
|
400
|
+
// quickback-allow ACTION_AUTH_DB_WRITE: server-side org create has no Origin for auth.api.createOrganization
|
|
396
401
|
await authDb.insert(organization).values({
|
|
397
402
|
id: orgId,
|
|
398
403
|
name: `${user.name ?? 'Personal'} Workspace`,
|
|
@@ -400,6 +405,7 @@ export default async (user, { authDb, authSchema }) => {
|
|
|
400
405
|
createdAt: new Date(),
|
|
401
406
|
});
|
|
402
407
|
|
|
408
|
+
// quickback-allow ACTION_AUTH_DB_WRITE: membership for the org created above, same reason
|
|
403
409
|
await authDb.insert(member).values({
|
|
404
410
|
id: crypto.randomUUID(),
|
|
405
411
|
userId: user.id,
|
|
@@ -430,6 +436,7 @@ export default async (newSession, { authDb, authSchema }) => {
|
|
|
430
436
|
|
|
431
437
|
if (memberships.length === 0) return;
|
|
432
438
|
|
|
439
|
+
// quickback-allow ACTION_AUTH_DB_WRITE: setActiveOrganization needs a request; this hook has none
|
|
433
440
|
await authDb
|
|
434
441
|
.update(session)
|
|
435
442
|
.set({ activeOrganizationId: memberships[0].organizationId })
|
|
@@ -458,7 +465,7 @@ The compiler-generated wrapper merges your `data` onto the original entity, so y
|
|
|
458
465
|
|
|
459
466
|
`POST /auth/v1/organization/create` (and Better Auth's `auth.api.createOrganization(...)` server helper) require an `Origin` header. A hook running inside `databaseHooks.user.create.after` is server-side — there is no incoming request, so no `Origin`. Calling those APIs from a hook may also validate `Origin` internally and reject.
|
|
460
467
|
|
|
461
|
-
**
|
|
468
|
+
**Here, direct Drizzle writes via `authDb` are the working path.** Mark each with `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>` so the warning records why. Treat the org/member tables as your source of truth and let the SPA call the BA API for user-initiated org creation.
|
|
462
469
|
|
|
463
470
|
## Generated output
|
|
464
471
|
|
|
@@ -217,7 +217,7 @@ The shell is served to any signed-in caller, and the SPA resolves one of six sta
|
|
|
217
217
|
| State | Screen |
|
|
218
218
|
|-------|--------|
|
|
219
219
|
| Not signed in | Redirect to sign-in (the one redirect that remains — it is where you were going anyway) |
|
|
220
|
-
| `sysadmin`, no tenant chosen | Tenant picker, filterable, with **All organizations** as a first-class choice |
|
|
220
|
+
| `sysadmin`, no tenant chosen | Tenant picker (from `GET /api/v1/operator/organizations`), filterable, with **All organizations** as a first-class choice |
|
|
221
221
|
| `sysadmin`, tenant chosen | The CMS, scoped to that tenant |
|
|
222
222
|
| `appmanager`, `access: "sysadmin"` | *"The CMS shows organization data"* → **Go to admin** |
|
|
223
223
|
| Anyone else, `access: "sysadmin"` | *"This CMS is restricted"* — names the config value that would admit them |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.72.2",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -327,6 +327,77 @@ When validation fails you get an RFC 9457 Problem Details document
|
|
|
327
327
|
Malformed JSON returns `INVALID_JSON` (400); a body over the 1 MiB cap returns
|
|
328
328
|
`PAYLOAD_TOO_LARGE` (413).
|
|
329
329
|
|
|
330
|
+
## Paginated actions
|
|
331
|
+
|
|
332
|
+
An action that declares [`pagination`](/define/actions/defining#paginated-actions-pagination)
|
|
333
|
+
reads the collection-read parameter names and answers the collection-read
|
|
334
|
+
envelope. Forward only; one base table.
|
|
335
|
+
|
|
336
|
+
### Request
|
|
337
|
+
|
|
338
|
+
| Parameter | Default | Description |
|
|
339
|
+
|-----------|---------|-------------|
|
|
340
|
+
| `limit` | the declared default (`50`) | Page size, clamped to `[1, max]` (`100` unless declared) |
|
|
341
|
+
| `starting_after` | — | `pagination.nextCursor` of the previous page. Omit for the first page |
|
|
342
|
+
| `sort` | the declared default | One of the action's named sorts |
|
|
343
|
+
|
|
344
|
+
A GET action reads them from the query string; any other method from the
|
|
345
|
+
JSON body (declare them with `pageInput()` so the body schema keeps them).
|
|
346
|
+
The action's own fields travel beside them and are part of the cursor's
|
|
347
|
+
context.
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
GET /api/v1/messages/list?conversationId=c_123&limit=50
|
|
351
|
+
GET /api/v1/messages/list?conversationId=c_123&limit=50&starting_after=eyJ2IjoyLCJjIjoi…
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
### Response
|
|
355
|
+
|
|
356
|
+
```json
|
|
357
|
+
{
|
|
358
|
+
"data": [ /* rows, masked for the caller */ ],
|
|
359
|
+
"pagination": {
|
|
360
|
+
"count": 50,
|
|
361
|
+
"pageSize": 50,
|
|
362
|
+
"hasMore": true,
|
|
363
|
+
"nextCursor": "eyJ2IjoyLCJjIjoi…",
|
|
364
|
+
"sort": "recent"
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
- `count` — rows on this page; `pageSize` — the resolved limit
|
|
370
|
+
- `hasMore` — from a `limit + 1` probe, so a final page that exactly fills
|
|
371
|
+
the limit reports `false`
|
|
372
|
+
- `nextCursor` — pass back as `starting_after`; `null` on the final page
|
|
373
|
+
- `sort` — the named sort the page was produced under
|
|
374
|
+
|
|
375
|
+
An action may return domain fields beside `data` and `pagination`; a
|
|
376
|
+
non-paginated action's response is unchanged.
|
|
377
|
+
|
|
378
|
+
### Cursors
|
|
379
|
+
|
|
380
|
+
A cursor is opaque and versioned. It carries the boundary row's sort-key
|
|
381
|
+
values and a hash of the action, table, sort and input it was minted for —
|
|
382
|
+
it is encoded, not encrypted, and it never authorizes: every page re-runs
|
|
383
|
+
access, the table firewall, soft-delete filtering and masking, so a cursor
|
|
384
|
+
from another caller or tenant yields that caller's own rows, nothing more.
|
|
385
|
+
A sort over a masked column is only offered to callers who may see it.
|
|
386
|
+
|
|
387
|
+
Validation failures are RFC 9457 problems, never a silent restart at page one:
|
|
388
|
+
|
|
389
|
+
| Status | `code` | When |
|
|
390
|
+
|--------|--------|------|
|
|
391
|
+
| `400` | `PAGINATION_INVALID_CURSOR` | Malformed, truncated, over 2048 characters, wrong version, wrong number of values, or a value of the wrong type |
|
|
392
|
+
| `400` | `PAGINATION_CURSOR_MISMATCH` | A cursor minted for another action, table, sort or input |
|
|
393
|
+
| `400` | `PAGINATION_INVALID_SORT` | `sort` is not one of the action's named sorts |
|
|
394
|
+
| `403` | `PAGINATION_SORT_NOT_VISIBLE` | A sort key is masked for this caller |
|
|
395
|
+
|
|
396
|
+
Pages are not a snapshot. A row inserted, updated or deleted between two
|
|
397
|
+
requests can shift the boundary: under a mutable sort a row may appear twice
|
|
398
|
+
or be missed. Reconnect checkpoints and change history are a
|
|
399
|
+
[realtime](/platform/realtime) concern, not a pagination one.
|
|
400
|
+
|
|
330
401
|
## Response Types
|
|
331
402
|
|
|
332
403
|
Actions support three response types:
|
|
@@ -466,9 +537,9 @@ await db.update(applications).set({ deletedAt: now, modifiedAt: now })
|
|
|
466
537
|
|
|
467
538
|
| Status | Description |
|
|
468
539
|
|--------|-------------|
|
|
469
|
-
| `400` | Invalid input / validation error (also `GUARD_FIELD_PROTECTED` for direct protected-field writes) |
|
|
540
|
+
| `400` | Invalid input / validation error (also `GUARD_FIELD_PROTECTED` for direct protected-field writes; `PAGINATION_INVALID_CURSOR`, `PAGINATION_CURSOR_MISMATCH`, `PAGINATION_INVALID_SORT` on [paginated actions](#paginated-actions)) |
|
|
470
541
|
| `401` | Not authenticated |
|
|
471
|
-
| `403` | Access role check failed (`ACCESS_ROLE_REQUIRED`) |
|
|
542
|
+
| `403` | Access role check failed (`ACCESS_ROLE_REQUIRED`); a masked sort key on a paginated action (`PAGINATION_SORT_NOT_VISIBLE`) |
|
|
472
543
|
| `404` | Record not found (record-based actions) |
|
|
473
544
|
| `409` | Record is in the wrong state for this action — `access.record` predicate or `transition` policy failed (`ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`) |
|
|
474
545
|
| `500` | Handler execution error |
|
|
@@ -314,9 +314,11 @@ transport with Neon's hyperdrive mode.
|
|
|
314
314
|
| Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
|
|
315
315
|
|----------|----------|-----------|----------------------|----------|
|
|
316
316
|
| `PATCH /batch` (update) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
|
|
317
|
+
| `PATCH /batch` (update) | [tenant table](/configure/tenant-databases) (`tenancy.isolation: 'durable-object'`) | `true` | `true` | `ctx.storage.transaction()` in the organization's Durable Object wraps the loop. Any failure rolls back ALL writes in the batch. |
|
|
317
318
|
| `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
|
|
318
319
|
| `PATCH /batch` (update) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Fail-fast loop without rollback — the driver has no `db.transaction`. Records before the failure stay committed. |
|
|
319
320
|
| `PUT /batch` (upsert) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
|
|
321
|
+
| `PUT /batch` (upsert) | [tenant table](/configure/tenant-databases) | `true` | `true` | Bulk insert + per-record update share one Durable Object transaction. |
|
|
320
322
|
| `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
|
|
321
323
|
| `POST /batch` (create) | (any) | (any) | `true` | One bulk `INSERT` — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
|
|
322
324
|
| `DELETE /batch` | (any) | (any) | `true` | One bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
|
|
@@ -47,12 +47,12 @@ When ETags are enabled, GET responses include:
|
|
|
47
47
|
Content-Type: application/json
|
|
48
48
|
ETag: W/"a1b2c3d4e5f60718"
|
|
49
49
|
Cache-Control: private, no-cache
|
|
50
|
-
Vary: Authorization, Cookie
|
|
50
|
+
Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
`Cache-Control: private, no-cache` means the browser **must revalidate** on every request, but can use its cached copy if the ETag matches, and no shared cache may store the response. This is the correct behavior for authenticated APIs — data is always fresh, but unchanged responses avoid re-transfer.
|
|
54
54
|
|
|
55
|
-
Every other JSON response produced under a cookie
|
|
55
|
+
Every other JSON response produced under a cookie, bearer token, or [Cloudflare Access](/configure/cloudflare-access) assertion (writes, actions, auth, admin) is sent with `Cache-Control: private, no-store` unless the route sets its own policy, and always carries `Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion`, so a proxy can never serve one user's body to another.
|
|
56
56
|
|
|
57
57
|
## Client usage
|
|
58
58
|
|
|
@@ -55,6 +55,13 @@ For a resource named `jobs`, Quickback generates:
|
|
|
55
55
|
| `PUT` | `/jobs/:id` | Upsert a record (requires config) |
|
|
56
56
|
| `PUT` | `/jobs/batch` | Batch upsert multiple records (requires config) |
|
|
57
57
|
|
|
58
|
+
A table a namespace claims mounts these under the namespace prefix
|
|
59
|
+
(`/event/:eventId/jobs`), and every row they read or write is confined to the instance in the URL
|
|
60
|
+
(see [Claimed tables are pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance)). With [`legacy`](/define/areas#keeping-the-old-url-legacy) it also keeps
|
|
61
|
+
each one at its pre-claim base (`/jobs`, `/jobs/:id`, …) as a deprecated forward: same method, same
|
|
62
|
+
body, one instance per request, org members only, with `Deprecation`, `Sunset` and `Link` response
|
|
63
|
+
headers.
|
|
64
|
+
|
|
58
65
|
## Replace a generated verb with an action
|
|
59
66
|
|
|
60
67
|
Map `create`, `update`, or `delete` to a named action when the public URL
|
|
@@ -225,6 +232,11 @@ columns may be omitted or sent as `null`. An empty string is **not** a blank —
|
|
|
225
232
|
`""` is validated like any other value (so it fails `q.url()`, `q.enum()`, and
|
|
226
233
|
`q.int()`).
|
|
227
234
|
|
|
235
|
+
On a table a namespace claims, the instance column (`eventId` under
|
|
236
|
+
`/event/:eventId/jobs`) is stamped from the URL. Omit it; a body value must
|
|
237
|
+
equal the URL instance or the create answers `400 INSTANCE_MISMATCH`. The same
|
|
238
|
+
rule applies to each `POST /batch` record and to the insert branch of `PUT`.
|
|
239
|
+
|
|
228
240
|
### Client-supplied IDs (optimistic updates)
|
|
229
241
|
|
|
230
242
|
Set `allowClientIds: true` on the database config to let `POST /` and
|
|
@@ -373,6 +385,7 @@ wrapper:
|
|
|
373
385
|
| Status | Description |
|
|
374
386
|
|--------|-------------|
|
|
375
387
|
| `400` | Invalid field or missing required field |
|
|
388
|
+
| `400` | `INSTANCE_MISMATCH` — on a claimed table, the body's instance column names another instance than the URL |
|
|
376
389
|
| `403` | User lacks permission to create records |
|
|
377
390
|
| `409` | Client-supplied `id` (with `allowClientIds: true`) already exists |
|
|
378
391
|
| `409` | `IDEMPOTENCY_ROW_CONFLICT` — a [row token](#row-token-idempotency) or client id already belongs to a different record |
|
|
@@ -198,6 +198,7 @@ Access violations return **403 Forbidden** when the user's role doesn't match th
|
|
|
198
198
|
| `ACCESS_OWNERSHIP_REQUIRED` | User must own the record |
|
|
199
199
|
| `ACCESS_NO_ORG` | No active organization set |
|
|
200
200
|
| `ACCESS_KEY_SCOPE_REQUIRED` | A [scoped API key](/platform/auth/api-keys#scopes) does not cover this route and method. `details.required` lists the scope that would admit it (empty outside the API base, which scoped keys never reach); `details.current` is the key's scopes |
|
|
201
|
+
| `ACCESS_DENIED` | A token bound to one instance was used for another (namespace, tenant and realtime ticket routes), or the caller's credential does not admit an operator surface |
|
|
201
202
|
| `ENTITLEMENT_REQUIRED` | An action's [`requires:`](/define/actions/defining#json-key-writes-and-requires) JSON key did not hold for the record. `details: { column, key }`. Checked before `execute` |
|
|
202
203
|
| `ACCESS_NO_ARM` | The action declares [`access.arms`](/define/actions/access#arms-conditioned-on-input-accessarms) and no arm's `when` matches the validated input |
|
|
203
204
|
|
|
@@ -361,9 +362,11 @@ reports these `DB_*` codes per id, or as the `failFast` response), bulk
|
|
|
361
362
|
actions, and changesets.
|
|
362
363
|
|
|
363
364
|
`DB_INSERT_FAILED`, `DB_UPDATE_FAILED` and `DB_DELETE_FAILED` are the fallback
|
|
364
|
-
for a failure that matches no known constraint. The
|
|
365
|
+
for a failure that matches no known constraint. The driver message (D1 or
|
|
365
366
|
Postgres text, which can name tables, columns, and SQL fragments) is always
|
|
366
|
-
logged with `console.error
|
|
367
|
+
logged with `console.error` — with bound values redacted (see
|
|
368
|
+
[Bound values never leave the database](#bound-values-never-leave-the-database))
|
|
369
|
+
— and the production body carries no `details`:
|
|
367
370
|
|
|
368
371
|
```json
|
|
369
372
|
{
|
|
@@ -374,14 +377,110 @@ logged with `console.error`, and the production body carries no `details`:
|
|
|
374
377
|
}
|
|
375
378
|
```
|
|
376
379
|
|
|
377
|
-
The
|
|
380
|
+
The (redacted) message appears as `details.reason` only when the worker runs with
|
|
378
381
|
[`EXPOSE_ERROR_STACK`](#exposing-error-details-in-dev--staging) set.
|
|
379
382
|
|
|
383
|
+
### Bound values never leave the database
|
|
384
|
+
|
|
385
|
+
A database error can carry the row it was writing: drizzle reports every driver
|
|
386
|
+
failure as `Failed query: <sql>` followed by `params: <values>`, and Postgres
|
|
387
|
+
inlines values into its own text (`Key (email)=(…) already exists`,
|
|
388
|
+
`Failing row contains (…)`). Every place the generated API records an error —
|
|
389
|
+
`console.error` in CRUD, batch, changeset and action catches, the global
|
|
390
|
+
`onError`, queue consumers, webhook event and delivery rows, `afterCommit`
|
|
391
|
+
failures, the `error_message` column of `audit_events`, and the
|
|
392
|
+
`EXPOSE_ERROR_STACK` bodies, and Better Auth's own logger (the generated
|
|
393
|
+
`betterAuth({ logger })`, which covers endpoint failures and the database
|
|
394
|
+
adapter) — passes it through `redactError` in the generated `src/lib/errors.ts`
|
|
395
|
+
first. Only the values are removed:
|
|
396
|
+
|
|
397
|
+
| Driver text | Logged / stored as |
|
|
398
|
+
|---|---|
|
|
399
|
+
| `Failed query: insert into "account" ("id", "user_id", "password") values (?, ?, ?)`<br/>`params: acc_1,usr_1,$argon2id$…` | `Failed query: insert into "account" ("id", "user_id", "password") values (?, ?, ?)`<br/>`params: [string(5), string(5), string(97)]` |
|
|
400
|
+
| `UNIQUE constraint failed: account.user_id` (D1, libsql) | unchanged |
|
|
401
|
+
| `duplicate key value violates unique constraint "users_email_key"`, `detail: Key (email)=(x@y.com) already exists.` (Postgres) | message unchanged; `detail: Key (email)=(<redacted>) already exists.` |
|
|
402
|
+
| `Failing row contains (r1, x@y.com, …)` | `Failing row contains (<redacted>)` |
|
|
403
|
+
| `invalid input syntax for type uuid: "…"` | `invalid input syntax for type uuid: "<redacted>"` |
|
|
404
|
+
| `Key (lower(email::text))=(…)` (expression index), `conflicts with existing key (…)=(…)` (exclusion constraint) | `=(<redacted>)` |
|
|
405
|
+
| `value "…" is out of range for type integer`, `date/time field value out of range: "…"`, `malformed array literal: "…"`, `Token "…" is invalid.` | the quoted literal becomes `"<redacted>"`; quoted constraint, relation, column and table names stay |
|
|
406
|
+
|
|
407
|
+
The SQL with its placeholders, table, column and constraint names, the driver
|
|
408
|
+
code (`SQLITE_CONSTRAINT_UNIQUE`, `23505`), the parameter count and each
|
|
409
|
+
parameter's type and length stay, so the log line still tells you which
|
|
410
|
+
statement failed and why; the `requestId` correlates it with the response,
|
|
411
|
+
and the global error log line also carries the driver `code` and `causeCode`.
|
|
412
|
+
Driver text past 16 KB is cut and marked `[truncated]`, so a hostile value can't
|
|
413
|
+
make redaction slow.
|
|
414
|
+
Classification is unaffected — the `DB_*` codes above are computed from the
|
|
415
|
+
original error. Your own code can call `redactError(error)` from
|
|
416
|
+
`src/lib/errors` before logging a caught error.
|
|
417
|
+
|
|
380
418
|
`ENCRYPTION_UNREADABLE` always carries `details: { table, column, id }` — the
|
|
381
419
|
row whose stored ciphertext is malformed, was not written under the caller's
|
|
382
420
|
organization key, was copied from another column or table, or names a key
|
|
383
421
|
version the organization does not have. Rewriting the field repairs the row.
|
|
384
422
|
|
|
423
|
+
### Legacy forwards
|
|
424
|
+
|
|
425
|
+
A [legacy forward](/define/areas#keeping-the-old-url-legacy) answers these itself, before it
|
|
426
|
+
dispatches; every other response is the successor route's. Each carries the `Deprecation`,
|
|
427
|
+
`Sunset` and `Link` headers.
|
|
428
|
+
|
|
429
|
+
| Code | Status | Meaning |
|
|
430
|
+
|------|--------|---------|
|
|
431
|
+
| `LEGACY_ORG_REQUIRED` | 403 | The caller has no active organization, is an instance-bound OAuth token or a scope-only principal, or (database per tenant) its active organization is not the tenant. Call the successor URL in `Link`. |
|
|
432
|
+
| `LEGACY_INSTANCE_REQUIRED` | 400 | The request names no instance: no `?C=` (or a repeated / `?C.<op>=` one) on a collection, no `C` in the body, or an id that is not a valid instance id. |
|
|
433
|
+
| `LEGACY_INSTANCE_MISMATCH` | 400 | The request names more than one instance (a batch spanning instances, or a body `C` that disagrees with `?C=`). |
|
|
434
|
+
|
|
435
|
+
An instance outside the caller's organization answers the namespace gate's
|
|
436
|
+
`403 ACCESS_ROLE_REQUIRED`; a row outside it answers the table's firewall miss
|
|
437
|
+
(`403 FIREWALL_NOT_FOUND`, or `404` with `firewallErrorMode: 'hide'`).
|
|
438
|
+
|
|
439
|
+
### Claimed tables
|
|
440
|
+
|
|
441
|
+
A table a namespace claims is [pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance).
|
|
442
|
+
|
|
443
|
+
| Code | Status | Meaning |
|
|
444
|
+
|------|--------|---------|
|
|
445
|
+
| `INSTANCE_MISMATCH` | 400 | A create body (or a batch record) sends the instance column with a value other than the instance in the URL. `layer: "validation"`, `details: { field, param }` (plus `index` for a batch record). Omit the column: it is taken from the URL. |
|
|
446
|
+
|
|
447
|
+
### Tenancy (database per tenant)
|
|
448
|
+
|
|
449
|
+
With `tenancy.isolation: 'durable-object'`, responses about an organization's own database carry `layer: "tenancy"` and one of these codes. See [Database per Tenant](/configure/tenant-databases).
|
|
450
|
+
|
|
451
|
+
| Code | Meaning |
|
|
452
|
+
|------|---------|
|
|
453
|
+
| `TENANT_REQUIRED` | The route reads an organization's own database but the request names no organization (or names an invalid id) |
|
|
454
|
+
| `TENANT_MISMATCH` | The principal does not belong to the tenant object it reached |
|
|
455
|
+
| `TENANT_SCOPE_MISMATCH` | A scope claim names a different tenant than the request |
|
|
456
|
+
| `TENANT_AMBIGUOUS` | The instance resolves to more than one organization; set an active organization |
|
|
457
|
+
| `TENANT_UNAVAILABLE` | The organization database or directory is unavailable; retry (`Retry-After`) |
|
|
458
|
+
| `TENANT_OVERLOADED` | The organization database is overloaded; retry after `Retry-After` |
|
|
459
|
+
| `TENANT_DEPTH_EXCEEDED` | Subrequest depth limit exceeded calling the organization database (508) |
|
|
460
|
+
| `TENANT_ADMISSION_UNAVAILABLE` | Scope admission could not be checked right now; retry |
|
|
461
|
+
| `TENANT_LOOKUP_UNAVAILABLE` | The tenant lookup index could not be read; retry |
|
|
462
|
+
| `TENANT_LOOKUP_PENDING` | The instance is not indexed to a tenant yet; retry |
|
|
463
|
+
| `TENANT_NOT_PROVISIONED` | The organization has no tenant database registered (operator routes other than archive refuse it) |
|
|
464
|
+
| `TENANT_ARCHIVED` | The organization is archived (423); an operator can unarchive it |
|
|
465
|
+
| `TENANT_PURGED` | The organization's data was purged (410) |
|
|
466
|
+
| `TENANT_MIGRATION_FAILED` | The organization database failed to migrate (503); `details` names the migration |
|
|
467
|
+
| `TENANT_JURISDICTION_MISMATCH` | The registry row was written under another jurisdiction |
|
|
468
|
+
| `TENANT_RPC_VERSION_MISMATCH` | The edge and tenant Workers disagree on the RPC contract; deploy the tenant Worker first |
|
|
469
|
+
| `TENANT_AUTHORIZATION_EPOCH_CHANGED` | A restore advanced the tenant's authorization epoch; credentials issued before it are refused |
|
|
470
|
+
| `TENANT_RESTORE_PENDING` | A restore is pending or unreconciled; sync or cancel it first |
|
|
471
|
+
| `TENANT_RESTORE_TOO_LARGE` | Operator restore: the dump exceeds the restore limit (413) |
|
|
472
|
+
| `TENANT_OPERATION_FAILED` | Operator route refused or failed (409); `detail` says why |
|
|
473
|
+
| `TENANT_COMMAND_INVALID` | A tenant command request failed its schema |
|
|
474
|
+
| `TENANT_COMMAND_FINGERPRINT_MISMATCH` | A tenant command was compiled against a different contract |
|
|
475
|
+
| `TENANT_COMMAND_REPLY_INVALID` | The tenant object answered a command with a malformed reply |
|
|
476
|
+
| `TENANT_JOB_INVALID` | A tenant job message is invalid |
|
|
477
|
+
| `TENANT_JOB_CALL_ONLY` | A result job was delivered instead of called (callTenantJob) |
|
|
478
|
+
| `TENANT_JOB_FAILED` | A called tenant job failed |
|
|
479
|
+
| `TENANT_JOB_REPLY_INVALID` | The tenant object answered a job call with a malformed reply |
|
|
480
|
+
| `TENANT_JOB_RESULT_INVALID` | A tenant job result is not serializable |
|
|
481
|
+
| `TENANT_JOB_RESULT_TOO_LARGE` | A tenant job result exceeds the size limit |
|
|
482
|
+
| `TENANT_TABLE_ON_EDGE` | Edge code queried a tenant table (500, a compile-placement bug) |
|
|
483
|
+
|
|
385
484
|
## Batch Errors
|
|
386
485
|
|
|
387
486
|
Batch operations can return:
|
|
@@ -465,7 +564,7 @@ fetch timeout, a third-party API error), the route returns
|
|
|
465
564
|
`ACTION_EXECUTION_FAILED`. The production body is generic: it carries
|
|
466
565
|
only the error class name in `details.name` (so callers can branch on
|
|
467
566
|
e.g. `TypeError` vs a fetch timeout) — never the underlying message,
|
|
468
|
-
cause, or stack frames. The
|
|
567
|
+
cause, or stack frames. The error is logged server-side with bound database values redacted.
|
|
469
568
|
|
|
470
569
|
```json
|
|
471
570
|
{
|
|
@@ -489,8 +588,8 @@ cause, or stack frames. The raw error is always logged server-side.
|
|
|
489
588
|
|
|
490
589
|
Uncaught throws that escape every route handler land in the global
|
|
491
590
|
`onError` and return `INTERNAL_ERROR`. Same contract: the production
|
|
492
|
-
body is generic, and the
|
|
493
|
-
logged via `console.error` keyed by the `requestId` in the body — so
|
|
591
|
+
body is generic, and the error (message, cause chain, stack), with bound
|
|
592
|
+
database values redacted, is logged via `console.error` keyed by the `requestId` in the body — so
|
|
494
593
|
the response → log correlation is one grep.
|
|
495
594
|
|
|
496
595
|
```json
|
|
@@ -525,11 +624,13 @@ When set, the global 500 and `ACTION_EXECUTION_FAILED` bodies forward
|
|
|
525
624
|
the underlying error message plus `details.cause` (cause-chain
|
|
526
625
|
message), `details.frames` (top three stack frames with absolute paths
|
|
527
626
|
sanitized to basename + line number), and `details.stack` (the full
|
|
528
|
-
unsanitized stack trace). The same switch adds `details.reason` (the
|
|
627
|
+
unsanitized stack trace). The same switch adds `details.reason` (the
|
|
529
628
|
error message) to the database fallbacks (`DB_INSERT_FAILED`,
|
|
530
629
|
`DB_UPDATE_FAILED`, `DB_DELETE_FAILED`), `ACCESS_AUDIT_LOG_FAILED`, the
|
|
531
|
-
`INTERNAL_ERROR` bodies of the auth handler
|
|
532
|
-
routes, and uses the
|
|
630
|
+
`INTERNAL_ERROR` bodies of the auth handler, operator `/admin/*` routes,
|
|
631
|
+
and storage upload, presign, and confirm routes, and uses the redacted message as the `TRIGGER_AFTER_FAILED` error text.
|
|
533
632
|
Without it, none of those bodies carry anything derived from the thrown
|
|
534
|
-
error.
|
|
633
|
+
error. With it, they still never carry a bound value — the message, cause and
|
|
634
|
+
stack go through the same [redaction](#bound-values-never-leave-the-database)
|
|
635
|
+
as the server log. `1` and `true` turn it on; any other value leaves it off. Leave it
|
|
535
636
|
unset in production.
|
|
@@ -33,6 +33,30 @@ For each resource with `export default defineTable(...)`:
|
|
|
33
33
|
| `PATCH` | `/api/v1/{resource}/batch` | Batch update |
|
|
34
34
|
| `DELETE` | `/api/v1/{resource}/batch` | Batch delete |
|
|
35
35
|
|
|
36
|
+
## Moved routes (0.72)
|
|
37
|
+
|
|
38
|
+
Better Auth owns `/auth/v1/*`. Quickback's own routes there moved under the API base in 0.72 (plan 031 Q7), so a Better Auth upgrade or plugin cannot collide with them and a Cloudflare Access path rule can cover the operator plane in one prefix. The prefix follows `contract.routes` (`/api/v2/…` on v2).
|
|
39
|
+
|
|
40
|
+
| Before 0.72 | Since 0.72 | Emitted when |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `GET /auth/v1/admin/list-organizations` | `GET /api/v1/operator/organizations` | `cms.sysadmin` or `account.auth.admin` |
|
|
43
|
+
| `GET /auth/v1/admin/get-organization?organizationId=:id` | `GET /api/v1/operator/organizations/:id` | same |
|
|
44
|
+
| `POST /auth/v1/admin/create-organization` | `POST /api/v1/operator/organizations` | same |
|
|
45
|
+
| `POST /auth/v1/admin/set-organization-member` `{ organizationId, userId, role }` | `PUT /api/v1/operator/organizations/:id/members/:userId` `{ role }` | same |
|
|
46
|
+
| `POST /auth/v1/admin/remove-organization-member` `{ organizationId, userId }` | `DELETE /api/v1/operator/organizations/:id/members/:userId` | same |
|
|
47
|
+
| `GET /auth/v1/organization/roster` | `GET /api/v1/organization/roster` | `auth.organizationRoster` |
|
|
48
|
+
| `GET /auth/v1/ses/status` | `GET /api/v1/auth/email-status` | always |
|
|
49
|
+
|
|
50
|
+
Response bodies are unchanged. The old paths keep working through 0.72.x and are removed in 0.73.0:
|
|
51
|
+
|
|
52
|
+
- The old `GET`s answer `308 Permanent Redirect` to the new path (the query string is kept; `get-organization?organizationId=X` redirects to `/operator/organizations/X`).
|
|
53
|
+
- The old `POST`s cannot redirect, because two of them changed verb. They run the same handler as the new route.
|
|
54
|
+
- Both add `Deprecation: true` and `Link: <new path>; rel="successor-version"`, and the Worker logs `[quickback] deprecated route <method> <path>` once per isolate per path. Grep your logs for it before upgrading to 0.73.
|
|
55
|
+
|
|
56
|
+
The bundled CMS and Account SPAs call the new paths. The OpenAPI document lists `GET /api/v1/auth/email-status` (operationId `getEmailStatus`, marked `x-quickback-auth-surface`, so like every auth endpoint it stays out of the MCP catalogue unless `agents.mcp.exposeAuthTools` is on, where the tool `auth__sesStatus` is now `auth__getEmailStatus`); the aliases are not advertised. A feature or table that would mount over one of these routes (`/api/v1/operator`, `/api/v1/auth`, `/api/v1/organization` with the roster on) is a compile error.
|
|
57
|
+
|
|
58
|
+
`ses/status` note: after 0.73.0, an `aws-ses` project's vendored Better Auth plugin answers `/auth/v1/ses/status` itself, with a different body (`provider: 'aws-ses'`, plus `region` and `fromEmail`). Use `email-status`.
|
|
59
|
+
|
|
36
60
|
## Guides
|
|
37
61
|
|
|
38
62
|
- [CRUD Endpoints](/api/crud) — Detailed CRUD endpoint reference
|
|
@@ -24,6 +24,14 @@ The generated spec documents every route the compiler produces:
|
|
|
24
24
|
- Actions (including standalone actions)
|
|
25
25
|
- Auth routes (`/api/auth/**`)
|
|
26
26
|
- Storage and webhook routes (when configured)
|
|
27
|
+
- [Legacy forwards](/define/areas#keeping-the-old-url-legacy) of namespace-claimed tables and actions, as `deprecated: true` operations
|
|
28
|
+
|
|
29
|
+
A legacy operation is its successor's operation at the old path: operationId `<successor>Legacy`,
|
|
30
|
+
the successor's path params dropped, a required `?C=` query param on collections, the
|
|
31
|
+
`Deprecation` / `Sunset` / `Link` response headers, and
|
|
32
|
+
`x-quickback-legacy-forward: { successor, successorPath, deprecated, sunset, instance }`. The
|
|
33
|
+
`LEGACY_*` codes join the `Error.code` enum. Generated clients see `@deprecated`. The MCP tool list
|
|
34
|
+
and the generated client SDK skip legacy operations: new code targets the successor.
|
|
27
35
|
|
|
28
36
|
Each endpoint includes request/response schemas derived from your Drizzle column types, access control metadata, and error responses.
|
|
29
37
|
|
|
@@ -102,6 +102,12 @@ currently wired into the emitted route.
|
|
|
102
102
|
|
|
103
103
|
There is no `limit` or `offset` member in `pagination`.
|
|
104
104
|
|
|
105
|
+
Custom actions that declare [`pagination`](/define/actions/defining#paginated-actions-pagination)
|
|
106
|
+
answer the same envelope (`data` + `pagination` with `count`, `pageSize`,
|
|
107
|
+
`hasMore`, `nextCursor`, `sort`) and read the same `limit` / `starting_after`
|
|
108
|
+
names, forward-only and with strictly validated cursors — see
|
|
109
|
+
[Paginated actions](/api/actions#paginated-actions).
|
|
110
|
+
|
|
105
111
|
## Sorting
|
|
106
112
|
|
|
107
113
|
Sort by one or more fields. Use the `-` prefix for descending order.
|
|
@@ -76,6 +76,8 @@ See [Interactive OAuth](#interactive-oauth-requireauth) below.
|
|
|
76
76
|
|
|
77
77
|
`exposeAuthTools` controls whether the Better Auth surface (`auth__*`, `auth_admin__*`, `auth_api_keys__*`, `auth_passkeys__*`, …) appears in the tool catalogue. It is off by default: an agent authenticates through OAuth and should not be offered credential minting (API keys), passkey enrolment, impersonation or password changes as callable tools. The REST endpoints themselves are unaffected, and the access filter below still applies when you opt in.
|
|
78
78
|
|
|
79
|
+
Opting in exposes auth tools only to callers that authenticated to `/mcp` with a Better Auth session token. Auth tools dispatch to `/auth/v1/…`, where Better Auth's `bearer` plugin rejects OAuth access tokens, JWTs, and API keys with a 401. For any other caller, non-public auth tools are missing from `tools/list` and `tools/call` returns `isError` without dispatching. Public auth tools (sign-up, sign-in, forgot-password) work for every caller. An MCP client connected through OAuth therefore sees no session-gated auth tools.
|
|
80
|
+
|
|
79
81
|
## The MCP server
|
|
80
82
|
|
|
81
83
|
### Tools
|
|
@@ -150,6 +152,8 @@ This does three things:
|
|
|
150
152
|
|
|
151
153
|
The access tokens it issues carry the OAuth issuer (`BETTER_AUTH_URL` + `/auth/v1`, or `oauth.issuerUrl`) and the requested resource as audience — exactly what the generated middleware verifies — with or without `auth.jwt` and without needing `oauth.enabled`.
|
|
152
154
|
|
|
155
|
+
The middleware accepts these tokens only while their Better Auth session (`sid`) is live, and builds the user's full context from it. 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
|
+
|
|
153
157
|
The full handshake a connector runs:
|
|
154
158
|
|
|
155
159
|
```text
|
|
@@ -251,7 +255,8 @@ export default defineConfig({
|
|
|
251
255
|
| `tools.include` | One of `include` / `groups` | Exact tool names, as the default `/mcp` server lists them (`<group>__<operationId>`). |
|
|
252
256
|
| `tools.groups` | One of `include` / `groups` | Every tool whose name starts with `<group>__`. |
|
|
253
257
|
| `tools.exclude` | No | Tool names removed after `include` and `groups`. |
|
|
254
|
-
| `tools.overrides` | No | Per-tool `title` / `description` shown by this server only. Keys must be selected tools. |
|
|
258
|
+
| `tools.overrides` | No | Per-tool `title` / `description` shown by this server only, and `ui` — the [MCP App](#mcp-apps) view the tool renders with. Keys must be selected tools. |
|
|
259
|
+
| `resources` | No | [MCP App](#mcp-apps) views this server serves, keyed by `ui://` URI. |
|
|
255
260
|
| `name` | No | Server title (`serverInfo.title`). Defaults to `<project> (<key> MCP)`; `serverInfo.name` is `<project>-<key>`. |
|
|
256
261
|
| `instructions` | No | Returned from `initialize` as the server's `instructions`. |
|
|
257
262
|
| `requireAuth` | No | Challenge anonymous callers with `401`. Defaults to `agents.mcp.requireAuth`. Setting it on any server force-enables `oauthProvider` + `bearer`, without changing the default `/mcp` challenge. |
|
|
@@ -268,6 +273,73 @@ The selection is fixed at compile time. A tool name or group the generated API d
|
|
|
268
273
|
|
|
269
274
|
The default `/mcp` is unchanged — same tools, same challenge, same documents.
|
|
270
275
|
|
|
276
|
+
### MCP Apps
|
|
277
|
+
|
|
278
|
+
A named server can serve [MCP Apps](https://github.com/modelcontextprotocol/ext-apps). An MCP App is an interactive HTML view that the host (Claude, for example) renders in a sandboxed iframe when a tool runs. Declare each view under `resources`, keyed by its `ui://` URI. Then point tools at it with `tools.overrides.<tool>.ui`:
|
|
279
|
+
|
|
280
|
+
```ts title="quickback.config.ts"
|
|
281
|
+
export default defineConfig({
|
|
282
|
+
// …
|
|
283
|
+
agents: {
|
|
284
|
+
mcp: {
|
|
285
|
+
servers: {
|
|
286
|
+
items: {
|
|
287
|
+
path: "/items/mcp",
|
|
288
|
+
resources: {
|
|
289
|
+
"ui://items/board": {
|
|
290
|
+
file: "./mcp-ui/items-board.html", // quickback/mcp-ui/items-board.html
|
|
291
|
+
name: "Items board",
|
|
292
|
+
description: "Kanban view of your items.",
|
|
293
|
+
csp: { connectDomains: ["https://api.example.com"] },
|
|
294
|
+
prefersBorder: true,
|
|
295
|
+
},
|
|
296
|
+
},
|
|
297
|
+
tools: {
|
|
298
|
+
include: ["items__listItems", "items__moveItem"],
|
|
299
|
+
overrides: {
|
|
300
|
+
items__listItems: { ui: "ui://items/board" },
|
|
301
|
+
// Callable by the view, hidden from the model.
|
|
302
|
+
items__moveItem: { ui: { resource: "ui://items/board", visibility: ["app"] } },
|
|
303
|
+
},
|
|
304
|
+
},
|
|
305
|
+
},
|
|
306
|
+
},
|
|
307
|
+
},
|
|
308
|
+
},
|
|
309
|
+
});
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
| Resource option | Required | Description |
|
|
313
|
+
|-----------------|----------|-------------|
|
|
314
|
+
| `file` | Yes | An `.html` file under `quickback/mcp-ui/`, written `./mcp-ui/<name>.html`. |
|
|
315
|
+
| `name` | No | Name in `resources/list`. Defaults to the URI. |
|
|
316
|
+
| `description` | No | Description in `resources/list`. |
|
|
317
|
+
| `csp` | No | `{ connectDomains?, resourceDomains?, frameDomains?, baseUriDomains? }`, each a list of origins the view may reach. If omitted, the host applies its most restrictive policy. |
|
|
318
|
+
| `permissions` | No | Any of `"camera"`, `"microphone"`, `"geolocation"`, `"clipboardWrite"`. |
|
|
319
|
+
| `domain` | No | A dedicated sandbox origin for the view (host-specific format). |
|
|
320
|
+
| `prefersBorder` | No | Ask the host to draw a border around the view. |
|
|
321
|
+
|
|
322
|
+
`csp`, `permissions`, `domain` and `prefersBorder` are passed through verbatim as the resource's `_meta.ui`. A tool's `ui` is a URI, or `{ resource, visibility }`. `visibility` lists who may call the tool: `"model"`, `"app"`, or both (the default).
|
|
323
|
+
|
|
324
|
+
The view must be **one self-contained HTML file**, with scripts and styles inlined (for example with `vite-plugin-singlefile`). The host loads it from `resources/read`, not from a URL, so relative asset paths do not resolve, and assets from other origins need their hosts in `csp.resourceDomains`. `quickback build` uploads every `.html` file under `quickback/mcp-ui/`. Only the files a server references are baked into the Worker.
|
|
325
|
+
|
|
326
|
+
A server with `resources` also gets:
|
|
327
|
+
|
|
328
|
+
- **`resources/list` and `resources/read`.** Each view is served as `text/html;profile=mcp-app` with its `_meta.ui`. An unknown URI returns `-32002 Resource not found`. `resources/templates/list` returns an empty list.
|
|
329
|
+
- **Capabilities in `initialize`.** The response adds `resources` and the `io.modelcontextprotocol/ui` extension marker.
|
|
330
|
+
- **`_meta.ui` on the tools that use a view.** It is set as `{ resourceUri, visibility? }`, next to the existing `quickback.dev/*` keys.
|
|
331
|
+
- **`structuredContent` on those tools' results** when the response body is a JSON object. The view reads its data from `structuredContent`. Other tools return text content only, as before.
|
|
332
|
+
|
|
333
|
+
The views sit behind the same `requireAuth` challenge as the server's tools. A view is static app code: every piece of data it shows still comes from a `tools/call` through the full security pipeline. Servers without `resources`, and the default `/mcp`, are unchanged: they still answer `resources/*` with `Method not found`.
|
|
334
|
+
|
|
335
|
+
These fail the compile:
|
|
336
|
+
|
|
337
|
+
- a URI that isn't `ui://…`
|
|
338
|
+
- a `file` outside `quickback/mcp-ui/`, or one that wasn't shipped
|
|
339
|
+
- a view over 1 MiB, or more than 4 MiB of views in the whole project
|
|
340
|
+
- a tool `ui` naming an undeclared resource
|
|
341
|
+
- a resource that no tool references
|
|
342
|
+
|
|
271
343
|
> An access token minted for a named server is accepted anywhere this Worker accepts its own OAuth tokens, exactly like a `/mcp` token: the curated list decides what the model is offered, not what the token can reach. Every call still runs the full security pipeline.
|
|
272
344
|
|
|
273
345
|
|
|
@@ -109,6 +109,8 @@ auth: { jwt: { expiresIn: 30 } } // 30s — tight post-revocation window
|
|
|
109
109
|
auth: { jwt: { expiresIn: 3600 } } // 1h — longer-lived tokens for CLI / CI
|
|
110
110
|
```
|
|
111
111
|
|
|
112
|
+
Above one day (`expiresIn > 86400`) without [`revocationCheck: 'kv'`](#revocationcheck-none--kv--token-revocation-strategy) is a compile **warning**: nothing can revoke such a token before it expires.
|
|
113
|
+
|
|
112
114
|
### `issuer?: string` — `iss` claim
|
|
113
115
|
|
|
114
116
|
Default `quickback:<project name>` — a compile-time constant, so every worker that verifies (API, files) and the plugin's `GET /auth/v1/token` agree without any env plumbing.
|
|
@@ -203,7 +205,11 @@ missing field falls back to its hardcoded value:
|
|
|
203
205
|
|
|
204
206
|
## `auth.organizationRoster` — members read on the JWT
|
|
205
207
|
|
|
206
|
-
`auth: { organizationRoster: { access: { roles: ['member'] } } }` emits `GET /
|
|
208
|
+
`auth: { organizationRoster: { access: { roles: ['member'] } } }` emits `GET /api/v1/organization/roster` (under `/auth/v1` before 0.72; the old path 308s until 0.73.0), the active organization's members (`id`, `name`, `email`, `image`, `role`). Better Auth's `list-members` needs a session; this works on the JWT bearer. See [Listing organization members](/platform/auth/using-auth#listing-organization-members).
|
|
209
|
+
|
|
210
|
+
## `auth.cloudflareAccess` — Cloudflare Access in front of routes
|
|
211
|
+
|
|
212
|
+
Verifies the `Cf-Access-Jwt-Assertion` header and maps the Access identity (email, groups, service token) to a Better Auth user and role. Inside its scope it is the only credential. See [Cloudflare Access](/configure/cloudflare-access).
|
|
207
213
|
|
|
208
214
|
## `auth.claims` — link rows to the account that verifies their email
|
|
209
215
|
|