@quickback-dev/cli 0.70.43 → 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 +5 -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 +79 -2
- package/dist/skill/docs/configure/auth.md +10 -2
- 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 +14 -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 +16 -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 +7 -7
- 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 +5 -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 +79 -2
- package/src/skill/docs/configure/auth.md +10 -2
- 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 +14 -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 +16 -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
|
@@ -131,6 +131,10 @@ interface Access {
|
|
|
131
131
|
// user.role column — independent of org membership. See userRole below.
|
|
132
132
|
userRole?: string[];
|
|
133
133
|
|
|
134
|
+
// How the request authenticated (OR logic). Matched against ctx.authMethod.
|
|
135
|
+
// The one gate a sysadmin does not bypass. See authMethod below.
|
|
136
|
+
authMethod?: Array<'session' | 'jwt' | 'api-key' | 'oauth' | 'principal' | 'cloudflare-access' | 'link'>;
|
|
137
|
+
|
|
134
138
|
// Record-level conditions
|
|
135
139
|
record?: {
|
|
136
140
|
[field: string]: FieldCondition;
|
|
@@ -207,6 +211,34 @@ The action's `db` is scoped to the target's organization and every call is
|
|
|
207
211
|
audited against that tenant. `operator:` is only legal on a `userRole`-only
|
|
208
212
|
access lane.
|
|
209
213
|
|
|
214
|
+
### `authMethod`
|
|
215
|
+
|
|
216
|
+
`authMethod` gates on **how** the caller authenticated, from `ctx.authMethod`:
|
|
217
|
+
`'session'` (cookie), `'jwt'`, `'api-key'`, `'oauth'`, `'principal'`
|
|
218
|
+
(delegated), `'cloudflare-access'`, `'link'`. OR logic within the list; AND
|
|
219
|
+
with the other gates on the same node.
|
|
220
|
+
|
|
221
|
+
{/* doc-compile: skip — access fragment */}
|
|
222
|
+
```ts
|
|
223
|
+
// Platform operators, and only through Cloudflare Access: a sysadmin's
|
|
224
|
+
// session cookie is refused here.
|
|
225
|
+
access: { userRole: ['sysadmin'], authMethod: ['cloudflare-access'] },
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
It is the one gate `sysadmin` does not bypass. Every other rule admits a
|
|
229
|
+
sysadmin outright; an `authMethod` list is checked for them too, on every
|
|
230
|
+
arm it appears in (`or` needs one arm whose method matches, `and` needs all).
|
|
231
|
+
A failed `authMethod` reports as a role failure (403 `ACCESS_ROLE_REQUIRED`).
|
|
232
|
+
An empty list is a compile error like any empty gate. On a collection read,
|
|
233
|
+
an arm whose method does not match contributes no rows. MCP tools whose only
|
|
234
|
+
lanes exclude `'oauth'` are hidden from `tools/list`, since MCP callers
|
|
235
|
+
authenticate with OAuth.
|
|
236
|
+
|
|
237
|
+
Use it with the [operator lane](/define/actions/scoped-db#operator-lane-operator):
|
|
238
|
+
`access: { userRole: ['sysadmin'], authMethod: ['cloudflare-access'] }` plus
|
|
239
|
+
`operator: { target }` is the shape for authored tenant lifecycle actions when
|
|
240
|
+
the generated routes are off (`tenancy.operator.http: false`).
|
|
241
|
+
|
|
210
242
|
`userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"`, `"appmanager"`, and `"sysadmin"`). If you've added custom user-table roles via Better Auth, list them explicitly.
|
|
211
243
|
|
|
212
244
|
### Pseudo-roles
|
|
@@ -378,7 +410,7 @@ read: { access: { roles: ["SYSADMIN"] } }
|
|
|
378
410
|
|
|
379
411
|
`SYSADMIN` is distinct from `userRole: ["appmanager"]`. Appmanager is the platform control-plane tier (CMS shell, Better Auth admin surfaces, support tooling); sysadmin is the cross-tenant data-plane tier. The one place sysadmin gets implicit extra powers is **the firewall escape hatch**: when `cms.sysadmin: true`, every `buildFirewallConditions` emits an `if (ctx.userRole === 'sysadmin') return undefined;` (or just the soft-delete predicate when present) at the top — so sysadmins see every tenant's rows, not just their own org's. That escape hatch does NOT fire for `userRole === 'appmanager'`; appmanagers still go through the firewall like everyone else.
|
|
380
412
|
|
|
381
|
-
This separation exists so Better Auth admin-plugin powers (user management, impersonation, org creation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'appmanager'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/configure#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant
|
|
413
|
+
This separation exists so Better Auth admin-plugin powers (user management, impersonation, org creation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'appmanager'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/configure#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `GET /api/v1/operator/organizations` endpoint, and the SPA's "All organizations" sentinel.
|
|
382
414
|
|
|
383
415
|
The boundary is enforced, not just conventional. Better Auth's admin plugin on its own lets any role holding `user:set-role` grant any role that exists, so the compiler emits a role-ceiling `hooks.before` entry (`enforceAdminRoleCeiling` in `src/lib/auth.ts`): an appmanager cannot assign `sysadmin` — to itself or anyone — nor ban, remove, reset the password of, or revoke the sessions of a sysadmin. Those calls return `403 ROLE_CEILING`. Tiers follow the admin plugin's `adminRoles` order, lowest privilege first; see [Account admin → Access Control](/ui/account/features/admin#access-control).
|
|
384
416
|
|
|
@@ -158,6 +158,15 @@ application or database logic. A schema **derived** from a table enumerates
|
|
|
158
158
|
nothing under that substitution — see
|
|
159
159
|
[Declaring action outputs](#declaring-action-outputs).
|
|
160
160
|
|
|
161
|
+
Workers runtime built-ins (`cloudflare:workers`, `cloudflare:sockets`,
|
|
162
|
+
`cloudflare:email`, and every other `cloudflare:*` module) exist only inside
|
|
163
|
+
workerd, so the harvest replaces them with an inert stub. `DurableObject`,
|
|
164
|
+
`WorkerEntrypoint`, `WorkflowEntrypoint`, and `RpcTarget` are empty classes,
|
|
165
|
+
`env` is an empty object, and any other named import is an empty class. An
|
|
166
|
+
action can therefore import a library such as partyserver, which subclasses
|
|
167
|
+
`DurableObject` at module load. The generated Worker imports the real modules.
|
|
168
|
+
Any other import that cannot be resolved still fails the harvest.
|
|
169
|
+
|
|
161
170
|
### Declaring action outputs
|
|
162
171
|
|
|
163
172
|
`output:` is optional, and omitting it degrades quietly: the operation's
|
|
@@ -306,6 +315,111 @@ action keeps the older behaviour — its result is masked as one row of the
|
|
|
306
315
|
bound table when that table has masking rules, and anything else is returned
|
|
307
316
|
as-is.
|
|
308
317
|
|
|
318
|
+
### Paginated actions (`pagination`)
|
|
319
|
+
|
|
320
|
+
A collection read gets keyset pagination from the compiler; an action that
|
|
321
|
+
lists rows used to hand-roll its own cursor, and a timestamp-only boundary
|
|
322
|
+
skips rows that share the timestamp. Declare the pagination instead and the
|
|
323
|
+
route hands `execute` a `page` helper over the action's scoped `db`:
|
|
324
|
+
|
|
325
|
+
```typescript title="quickback/features/messages/actions/list.ts"
|
|
326
|
+
import { z } from "zod";
|
|
327
|
+
import { eq } from "drizzle-orm";
|
|
328
|
+
import { defineAction, messages, page, pageInput, row } from "../.quickback/define-action";
|
|
329
|
+
|
|
330
|
+
export default defineAction({
|
|
331
|
+
description: "Messages in a conversation, newest first.",
|
|
332
|
+
path: "/messages/list",
|
|
333
|
+
method: "GET",
|
|
334
|
+
input: pageInput({ conversationId: z.string() }),
|
|
335
|
+
output: page(row(messages)),
|
|
336
|
+
pagination: {
|
|
337
|
+
table: "messages",
|
|
338
|
+
sorts: { recent: ["-createdAt", "id"], oldest: ["createdAt", "id"] },
|
|
339
|
+
limit: { default: 50, max: 200 },
|
|
340
|
+
},
|
|
341
|
+
access: { roles: ["owner", "admin", "member"] },
|
|
342
|
+
async execute({ page, input }) {
|
|
343
|
+
return page!.query(messages, { where: eq(messages.conversationId, input.conversationId) });
|
|
344
|
+
},
|
|
345
|
+
});
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
The result is the collection-read envelope — `{ data, pagination: { count,
|
|
349
|
+
pageSize, hasMore, nextCursor, sort } }` — and the request carries the same
|
|
350
|
+
parameter names: `limit`, `starting_after` and `sort`. See
|
|
351
|
+
[Paginated actions](/api/actions#paginated-actions) for the wire contract
|
|
352
|
+
and errors. When the table masks columns, add
|
|
353
|
+
`outputMask: { table: "messages", path: "data" }` so each row in the page is
|
|
354
|
+
masked for the caller like a CRUD read.
|
|
355
|
+
|
|
356
|
+
- **`table`** names the base table paged over (a record-based action may
|
|
357
|
+
omit it and page its bound table). One table, no joins: the helper composes
|
|
358
|
+
the caller's `where` with the table's firewall and soft-delete filter
|
|
359
|
+
through the scoped `db`; it never replaces them.
|
|
360
|
+
- **`sorts`** are named: `'column'` ascending, `'-column'` descending, first
|
|
361
|
+
key first. Every key must be a declared, **non-null** column of an
|
|
362
|
+
orderable kind, and the key set must contain a **unique tuple** — the
|
|
363
|
+
primary key, a `.unique()` column, or every column of a non-partial
|
|
364
|
+
table-level `unique` — so the order is total and a boundary is
|
|
365
|
+
unambiguous. The compiler refuses anything else; it never assumes a column
|
|
366
|
+
called `id` is unique. A raw Drizzle table (`sqliteTable` / `pgTable`) is
|
|
367
|
+
read from its source: `.primaryKey()`, `.unique()` and `.notNull()` count
|
|
368
|
+
wherever they sit in the column chain, nothing else does.
|
|
369
|
+
- **`defaultSort`** (default: the first sort) applies when the request names
|
|
370
|
+
none; **`limit`** bounds the page size (`{ default: 50, max: 100 }`, the
|
|
371
|
+
CRUD defaults — a larger request is clamped, never rejected).
|
|
372
|
+
- **`cursorAliases`** (optional, e.g. `['before']`) names legacy request
|
|
373
|
+
fields that carry the cursor for an action whose released clients paged by
|
|
374
|
+
hand before it adopted `pagination:`. An alias is read only when
|
|
375
|
+
`starting_after` / `cursor` are absent and is left out of the cursor's
|
|
376
|
+
query context, so a `nextCursor` echoed under the old name is accepted.
|
|
377
|
+
Declare the field in `pageInput({...})` so a POST body keeps it. The helper
|
|
378
|
+
validates whatever arrives as a cursor of this action; a legacy value
|
|
379
|
+
(an ISO timestamp, say) is `page.cursor` for the action to recognise and
|
|
380
|
+
translate into its own boundary predicate before it calls `page.keyset`.
|
|
381
|
+
- **Masked sort keys.** A keyset cursor spells the boundary row's sort values
|
|
382
|
+
out, so a sort over a [masked](/define/masking) column is allowed only
|
|
383
|
+
when every role the action admits is in that column's `show.roles`
|
|
384
|
+
(hierarchy-expanded). A pseudo-role (`PUBLIC`, …), a function-form access
|
|
385
|
+
or an empty `show.roles` cannot be proven and is a compile error. The route
|
|
386
|
+
re-checks per request and answers `403 PAGINATION_SORT_NOT_VISIBLE` for a
|
|
387
|
+
caller who may not see a key.
|
|
388
|
+
|
|
389
|
+
`pageInput(fields)` is `z.object({ ...fields, limit, starting_after, sort })`,
|
|
390
|
+
and `page(item, extra?)` is the envelope schema — declare both so the
|
|
391
|
+
parameters and the response are validated, typed and published in OpenAPI,
|
|
392
|
+
MCP and `quickback.gen.ts`. Without `pageInput()` a GET action still reads
|
|
393
|
+
the parameters from the query string, but a POST body loses them to Zod's
|
|
394
|
+
unknown-key stripping. Without `output`, the compiler publishes the envelope
|
|
395
|
+
over the paged table's component.
|
|
396
|
+
|
|
397
|
+
`page` offers:
|
|
398
|
+
|
|
399
|
+
- `page.query(table, { where?, select?, sort? })` — one page. A `select`
|
|
400
|
+
projection may omit the sort keys: they are fetched under reserved names
|
|
401
|
+
for the cursor and stripped before the response.
|
|
402
|
+
- `page.keyset(table, sort?)`, `page.orderBy(table, sort?)` and
|
|
403
|
+
`page.finish(rows, sort?)` — the validated boundary predicate, the ORDER BY
|
|
404
|
+
terms and the `limit + 1` finish, for a query you author yourself over the
|
|
405
|
+
same table (a running total beside the page, say). They do not make a join
|
|
406
|
+
or a merged feed correct; the sort must still be a total order over the
|
|
407
|
+
rows you return.
|
|
408
|
+
- `page.limit`, `page.sort`, `page.cursor` — the resolved request values.
|
|
409
|
+
|
|
410
|
+
Cursors are versioned, opaque and bound to the action, table, sort and
|
|
411
|
+
input they were minted for; a cursor from another query, a truncated or
|
|
412
|
+
forged one, or one of the wrong shape is a typed `400` rather than a silent
|
|
413
|
+
restart at page one. They are encoded, not encrypted, and never authorize:
|
|
414
|
+
every page re-runs access, firewall and masking. Mutable sorts drift — a
|
|
415
|
+
row inserted or updated between two requests may be seen twice or missed.
|
|
416
|
+
Pagination makes no snapshot, replay or reconnect promise; that is what
|
|
417
|
+
[realtime](/platform/realtime) change feeds are for.
|
|
418
|
+
|
|
419
|
+
`pagination` cannot be combined with `bulkVariant` or a `stream` / `file`
|
|
420
|
+
response. V1 is forward-only over a single base table with non-null keys;
|
|
421
|
+
backward paging, nullable keys, joins and totals are not offered.
|
|
422
|
+
|
|
309
423
|
### Configuration Options
|
|
310
424
|
|
|
311
425
|
| Option | Required | Description |
|
|
@@ -317,11 +431,13 @@ as-is.
|
|
|
317
431
|
| `access` | Yes | Access control (roles, record conditions, or function), or input-conditioned `arms` — see [Arms conditioned on input](/define/actions/access#arms-conditioned-on-input-accessarms) |
|
|
318
432
|
| `execute` | Yes | Inline async arrow function (`async (ctx) => { … }`) |
|
|
319
433
|
| `path` | Standalone only | Custom route path. Presence of `path` makes the action standalone. |
|
|
434
|
+
| `legacy` | No | Standalone, namespace-claimed only. `{ path, deprecated, sunset, instance? }` keeps the action's pre-claim path serving as a deprecated forward to its namespace path, for org members only; `instance: { table, field }` reads the instance from a row. See [Keeping the old URL](/define/areas#keeping-the-old-url-legacy) |
|
|
320
435
|
| `method` | No | HTTP method: GET, POST, PUT, PATCH, DELETE (default: POST). GET actions parse `input` from query params; all other methods parse from the JSON body. See [GET vs POST for input](#get-vs-post-for-input). |
|
|
321
436
|
| `responseType` | No | Response format: json, stream, file (default: json) |
|
|
322
437
|
| `sideEffects` | No | Hint for AI tools: `'sync'`, `'async'`, or `'fire-and-forget'` |
|
|
323
438
|
| `allowRawSql` | No | Explicit compile-time opt-in for raw SQL in execute code |
|
|
324
|
-
| `
|
|
439
|
+
| `edge` | No | `true`: a standalone action under a tenant namespace prefix runs on the edge Worker (database-per-tenant only). See [Edge namespace actions](/configure/tenant-databases#edge-namespace-actions) |
|
|
440
|
+
| `unsafe` | No | Unsafe raw DB mode. Object config (`reason`, `adminOnly`, `crossTenant`, `targetScope`, `authWrites`). `authWrites: true` turns unsafe mode on, permits direct writes to Better Auth tables, requires `reason`, and writes a security audit row on every call; pair it with `crossTenant: false` unless the action is sysadmin-only — see [`ACTION_AUTH_DB_WRITE`](/define/diagnostics#action_auth_db_write). |
|
|
325
441
|
| `transition` | No | State-machine policy enforcing the from/to pair. Lives on a record-based action, or on a standalone action paired with a `record:` binding. See [Transitions](/define/transitions) |
|
|
326
442
|
| `refs` | No | Scoped foreign-key inputs: load + firewall + 404 before `execute`, with `many`, `where`/`unmet`, and `ownedVia`. See [Refs](#refs-scoped-foreign-key-inputs) |
|
|
327
443
|
| `record` | Standalone only | Feature-area transition adapter binding: `{ table, idFrom: "path.<param>", matchScope? }`. Binds + firewalls the record a `transition` operates on from a proven route param. See [Feature-area transition adapter](#feature-area-transition-adapter) |
|
|
@@ -334,6 +450,7 @@ as-is.
|
|
|
334
450
|
| `requires` | No | A JSON key that must hold before `execute` runs, else 403 `ENTITLEMENT_REQUIRED`: `{ flag: '<key>' }` or `{ json: { column, key, truthy: true \| equals } }`, optionally `from: '<ref as>'`. See [JSON key writes and requires](#json-key-writes-and-requires) |
|
|
335
451
|
| `operator` | Standalone only | Operator lane: `{ target: { table, by: 'input.<field>', includeDeleted? } }` on a `userRole`-only action. Loads the target cross-tenant (404 when absent or soft-deleted), scopes `db` to its organization, passes the row as `target`, and audits every call against that tenant. Mutually exclusive with `unsafe`. See [Operator lane](/define/actions/scoped-db#operator-lane-operator) |
|
|
336
452
|
| `outputMask` | No | `'source'` or `{ table, path? }`. Masks the rows the action returns with that table's masking rules for the caller — see [Masking action output](#masking-action-output-outputmask) |
|
|
453
|
+
| `pagination` | No | `{ table?, sorts, defaultSort?, limit?, cursorAliases? }`. Declared keyset pagination over one base table; injects `page` into `execute` and publishes the page parameters + envelope — see [Paginated actions](#paginated-actions-pagination) |
|
|
337
454
|
|
|
338
455
|
`execute` must be an `async (ctx) => { … }` arrow function. `async function`
|
|
339
456
|
declarations and non-async forms are rejected at parse time.
|
|
@@ -140,11 +140,14 @@ export default defineAction({
|
|
|
140
140
|
string.
|
|
141
141
|
|
|
142
142
|
One more source of claims is the route itself. An action under an
|
|
143
|
-
[`authz.namespaces`](/define/areas#narrow-ctxexposeas-typing) prefix
|
|
144
|
-
|
|
145
|
-
|
|
143
|
+
[`authz.namespaces`](/define/areas#narrow-ctxexposeas-typing) prefix whose
|
|
144
|
+
lanes are all bulk-grant lanes (`{ roles }`, `{ team }`) only admits callers
|
|
145
|
+
carrying their own org, so every lane carries the org claim. Import that
|
|
146
146
|
namespace's `define-action.<namespace>` helper and the gate credits it; the
|
|
147
|
-
generic `define-action` helper cannot see the namespace and stays strict.
|
|
147
|
+
generic `define-action` helper cannot see the namespace and stays strict. A
|
|
148
|
+
relationship lane never confers the org claim: the gate does not derive
|
|
149
|
+
`ctx.activeOrgId` from the proven row, because an org arm means org
|
|
150
|
+
membership.
|
|
148
151
|
|
|
149
152
|
Not gated at the type level: joins (`leftJoin(t)` and friends) and `$count` —
|
|
150
153
|
both still go through the runtime firewall rules above (`$count` is scoped;
|
|
@@ -397,8 +400,10 @@ intentional, declare `unsafe: { reason: "…" }` so it is audited (or
|
|
|
397
400
|
`firewall: { exception: true }` for a deliberately unscoped action). To adopt
|
|
398
401
|
the check on an existing project, `compiler.securityContracts.failMode: "warn"`
|
|
399
402
|
downgrades it to a warning. Writes to Better Auth tables are a separate error,
|
|
400
|
-
`ACTION_AUTH_DB_WRITE`, that `unsafe` does not silence
|
|
401
|
-
|
|
403
|
+
`ACTION_AUTH_DB_WRITE`, that plain `unsafe` does not silence: only
|
|
404
|
+
`unsafe: { reason: "…", crossTenant: false, authWrites: true }` does. Call `auth.api.*` instead
|
|
405
|
+
where Better Auth has an endpoint. See
|
|
406
|
+
[Diagnostics → `ACTION_AUTH_DB_WRITE`](/define/diagnostics#action_auth_db_write).
|
|
402
407
|
|
|
403
408
|
Use object form for explicit policy and mandatory audit metadata:
|
|
404
409
|
|
|
@@ -431,7 +436,11 @@ Unsafe cross-tenant actions are generated with:
|
|
|
431
436
|
|
|
432
437
|
- Better Auth authentication required (no unauthenticated path)
|
|
433
438
|
- sysadmin gate (`ctx.userRole === "sysadmin"`)
|
|
434
|
-
- mandatory audit logging on deny/success/error
|
|
439
|
+
- mandatory audit logging on deny/success/error — an `error` row's `errorMessage` never carries bound values ([redacted](/api/errors#bound-values-never-leave-the-database): SQL and constraint names stay, the values do not)
|
|
440
|
+
|
|
441
|
+
A same-tenant unsafe action (`crossTenant: false`) gets no sysadmin gate and
|
|
442
|
+
writes no audit row — unless it declares `authWrites: true`, which adds the
|
|
443
|
+
mandatory audit log (with its `reason`) and nothing else.
|
|
435
444
|
|
|
436
445
|
**Provider note (Neon, PlanetScale Postgres):** `unsafeDb` is the
|
|
437
446
|
service-role handle (`createServiceDb`, wrapped by the audit writer) for
|
|
@@ -454,12 +463,25 @@ request-scoped service-role boundary.
|
|
|
454
463
|
|
|
455
464
|
Without unsafe mode, `unsafeDb` is `undefined` in the executor params.
|
|
456
465
|
|
|
466
|
+
### Credential doors (server grants)
|
|
467
|
+
|
|
468
|
+
A `PUBLIC` action that turns an application credential (a printed handout code, a legacy pass) into an instance-bound grant has no caller principal: the scoped `db` and the audited `unsafeDb` both refuse its writes, because the audit wrapper stamps the writer from `ctx.userId` and fails closed without one. Such a door:
|
|
469
|
+
|
|
470
|
+
- declares `unsafe: { reason: '…', crossTenant: false }` (no sysadmin gate; every call is audited) and reads and consumes its own credential row through the unwrapped features handle, `createDb(env.DB)` from `src/db`;
|
|
471
|
+
- never reads `ctx.userId`, a cookie or a bearer: the user it links and grants comes only from the tenant read of the credential's subject;
|
|
472
|
+
- consumes the credential with one conditional write (`UPDATE … WHERE id = ? AND revoked_at IS NULL AND expires_at > ? RETURNING id`) only **after** `issueScopeGrant` returned, and returns the grant only if exactly one row came back (else `discardScopeGrant`);
|
|
473
|
+
- answers with `Cache-Control: no-store`.
|
|
474
|
+
|
|
475
|
+
The tenant side (reading the subject, linking it, admitting it) goes through `readScopeGrantSubject`, `linkScopeGrantSubject` and `issueScopeGrant`, never through raw tenant-table access from the edge. The order, the outcome classes and the squatting guard are in [Server-issued grants](/define/scopes#server-issued-grants-issuescopegrant).
|
|
476
|
+
|
|
457
477
|
### Operator lane: `operator:`
|
|
458
478
|
|
|
459
479
|
A platform operator acting on **one** tenant — set a customer's plan, fix an
|
|
460
480
|
event's status, seed an organization — is not a cross-tenant query. Declare the
|
|
461
481
|
target instead of reaching for `unsafe`:
|
|
462
482
|
|
|
483
|
+
For tenant lifecycle mutations on a Durable Object tenancy (archive, restore, purge, …) call `runTenantOperatorOperation` from `lib/tenants` inside the action: it adds the state-machine check, confirmation, begin/outcome audit rows and operation id the generated operator routes have ([Lifecycle operations](/configure/tenant-databases#lifecycle-operations)).
|
|
484
|
+
|
|
463
485
|
{/* doc-compile: skip — the `operator:` block is the point and it names `events`, a sibling table the fence does not declare; the gate compiles each fence as an isolated project. The whole project, with a runtime check of the audit row, compiles in `tests/output-matrix/fixtures/operator-lane`. */}
|
|
464
486
|
```ts
|
|
465
487
|
// features/events/actions/setEventStatus.ts
|
|
@@ -501,12 +523,13 @@ error. A failed audit write fails the request (500 `ACCESS_AUDIT_LOG_FAILED`).
|
|
|
501
523
|
| `actorUserId` / `actorOrgId` | the operator and their own active org |
|
|
502
524
|
| `metadata.operator` | `{ targetTable, targetId }` |
|
|
503
525
|
| `metadata.input` | the action input, with every key named like a masked, `.encrypted()`, `.sealed()` or vault-ref column in the project replaced by `"[REDACTED]"` |
|
|
526
|
+
| `errorCode` / `errorMessage` | on `error` rows: the thrown error's code and message, with bound values redacted — the SQL, constraint and column names stay ([details](/api/errors#bound-values-never-leave-the-database)) |
|
|
504
527
|
|
|
505
528
|
The return value is never stored.
|
|
506
529
|
|
|
507
530
|
The compiler refuses:
|
|
508
531
|
|
|
509
|
-
- `operator` without a `userRole`-only access lane — `access: { userRole: [...] }` and nothing else (no `roles`, `or`, `principals`).
|
|
532
|
+
- `operator` without a `userRole`-only access lane — `access: { userRole: [...] }`, optionally with `authMethod`, and nothing else (no `roles`, `or`, `principals`).
|
|
510
533
|
- `operator` together with `unsafe`, `anchor`, `record` or `firewall` — one or the other.
|
|
511
534
|
- `operator` on a record action (no `path:`) or under an `authz.namespaces` prefix.
|
|
512
535
|
- `target.by` that is not `input.<field>` of a required field in an inline `z.object` input.
|
|
@@ -747,6 +770,7 @@ interface ActionExecutorParams {
|
|
|
747
770
|
auth: Auth; // Better Auth instance — call auth.api.getSession(...) etc. Lazy on Cloudflare.
|
|
748
771
|
whereRecord?: (table) => SQL; // Pre-built WHERE: firewall + soft-delete + eq(table.id, record.id). Record-based actions only.
|
|
749
772
|
whereTransition?: (table) => SQL; // whereRecord plus the transition's "from" precondition. Transition actions only.
|
|
773
|
+
page?: QbActionPage; // Keyset page helper over the scoped db. Only when the action declares `pagination:` — see Paginated actions.
|
|
750
774
|
}
|
|
751
775
|
```
|
|
752
776
|
|
|
@@ -248,6 +248,147 @@ Two constraints fall out of the same split:
|
|
|
248
248
|
Scoping the collection itself — "don't list conversations I'm not in" — is
|
|
249
249
|
[firewall](/define/firewall) work on the table, not area work.
|
|
250
250
|
|
|
251
|
+
### Claimed tables are pinned to the URL instance
|
|
252
|
+
|
|
253
|
+
A table under the prefix is confined to the instance in the URL, for every lane. The instance
|
|
254
|
+
column `C` is the one column a firewall arm binds to the namespace's instance —
|
|
255
|
+
`ctx.scope.<kind>`, `ctx.scope.<kind>.id` or `ctx.<exposeAs>.id` (`eventId` below). After
|
|
256
|
+
admission the gate stamps the `:param`, and the table's firewall ANDs `C = <param>` into every
|
|
257
|
+
query. An org member on the `{ roles }` lane gets the same instance a relationship lane gets:
|
|
258
|
+
|
|
259
|
+
```
|
|
260
|
+
GET /api/v1/event/A/locations → event A's rows only (no ?eventId= needed)
|
|
261
|
+
GET /api/v1/event/A/locations/<A2 row> → 403 FIREWALL_NOT_FOUND
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
The pin covers:
|
|
265
|
+
|
|
266
|
+
- the list, `/views/:name`, `?total`, `?search` and aggregations;
|
|
267
|
+
- `GET`, `PATCH` and `DELETE /:id`, the batches, and `PUT /:id`;
|
|
268
|
+
- record-bound actions, changesets, and the firewall check on writes;
|
|
269
|
+
- every namespace action's scoped `db` read of the table.
|
|
270
|
+
|
|
271
|
+
`?C=` on the list still works as a filter, and is redundant: `?C=A2` under `/event/A` returns an
|
|
272
|
+
empty list.
|
|
273
|
+
|
|
274
|
+
**Creates take `C` from the URL.** `POST /`, each `POST /batch` record, the insert branch of
|
|
275
|
+
`PUT /:id` and `PUT /batch`, and changeset inserts stamp `C` from the URL. A body may still send
|
|
276
|
+
`C` if it equals the URL instance; any other value answers `400 INSTANCE_MISMATCH`. A batch checks
|
|
277
|
+
every record before it writes, so one disagreeing record refuses the whole batch. `C` stays
|
|
278
|
+
system-managed on `PATCH`, so a row never moves between instances.
|
|
279
|
+
|
|
280
|
+
A namespace action is not auto-stamped: an insert into another instance's `C` is refused by the
|
|
281
|
+
firewall check (`403 FIREWALL_WRITE_DENIED`). Set `C` from `ctx.<exposeAs>.id`.
|
|
282
|
+
|
|
283
|
+
What is **not** pinned: callers outside the namespace's routes — queue and cron handlers, root
|
|
284
|
+
actions, tenant jobs, the relationship probe, and `edge: true` namespace actions. They keep the
|
|
285
|
+
table's own firewall.
|
|
286
|
+
|
|
287
|
+
The compile warns `CLAIMED_TABLE_UNPINNED` when a claimed table has no instance arm, or more than
|
|
288
|
+
one, and `CLAIMED_INSTANCE_COLUMN_NULLABLE` when `C` is nullable (rows with `C IS NULL` become
|
|
289
|
+
unreachable through the namespace). See [Schema and config codes](/define/diagnostics#schema-and-config-codes).
|
|
290
|
+
|
|
291
|
+
### Keeping the old URL: `legacy`
|
|
292
|
+
|
|
293
|
+
Claiming a table moves it. `path: '/event/:eventId/locations'` mounts the router behind the
|
|
294
|
+
gate and drops `/api/v1/locations` in the same build, so every caller of the old URL gets
|
|
295
|
+
`404`. Shipped mobile builds and cached web bundles keep calling it.
|
|
296
|
+
|
|
297
|
+
Set `legacy` to keep the old URL serving as a deprecated forward:
|
|
298
|
+
|
|
299
|
+
{/* doc-compile: skip — excerpt of a claimed table; columns and the namespace are elided */}
|
|
300
|
+
```ts
|
|
301
|
+
export default defineTable(locations, {
|
|
302
|
+
path: '/event/:eventId/locations',
|
|
303
|
+
legacy: { deprecated: '2026-11-02', sunset: '2027-01-31' }, // path defaults to '/locations'
|
|
304
|
+
firewall: [{ any: [
|
|
305
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
306
|
+
{ field: 'eventId', equals: 'ctx.scope.event' },
|
|
307
|
+
] }],
|
|
308
|
+
// …
|
|
309
|
+
});
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
Each legacy route resolves one instance, rewrites the URL to the namespace route, and
|
|
313
|
+
dispatches to it **in-process**: no redirect, no second auth pass. The namespace gate,
|
|
314
|
+
firewall, access, guards and masking run exactly as at the new URL, so the forward is never
|
|
315
|
+
wider than the route it forwards to.
|
|
316
|
+
|
|
317
|
+
**Org members only.** The forward refuses, before any read, a caller with no active
|
|
318
|
+
organization, an instance-bound OAuth token, a scope-only principal, and (database per tenant)
|
|
319
|
+
a caller whose active organization is not the tenant: `403 LEGACY_ORG_REQUIRED`. Those callers
|
|
320
|
+
never had the old URL. They keep the new one through their relationship lane.
|
|
321
|
+
|
|
322
|
+
**One instance per request.** The instance column `C` is the column a firewall arm binds to
|
|
323
|
+
the namespace's scope kind (`ctx.scope.<kind>`, `ctx.scope.<kind>.id` or `ctx.<exposeAs>.id`):
|
|
324
|
+
`eventId` above.
|
|
325
|
+
|
|
326
|
+
| Legacy route | Instance from |
|
|
327
|
+
|---|---|
|
|
328
|
+
| `GET /`, `GET /views/:name` | Exactly one plain `?C=`. It is removed from the forwarded URL (the successor is [pinned](#claimed-tables-are-pinned-to-the-url-instance)); every other parameter is forwarded unchanged. |
|
|
329
|
+
| `POST /` | The JSON body's `C`. A disagreeing `?C=` is `400 LEGACY_INSTANCE_MISMATCH`. |
|
|
330
|
+
| `POST /batch` | Every `records[i].C`, all equal. |
|
|
331
|
+
| `/:id`, `/:id/<action>` | The row, read through the table's firewall with the organization arm only. |
|
|
332
|
+
| `PUT /:id` | The row; for a new id, the body's `C`. |
|
|
333
|
+
| `PATCH /batch`, `PUT /batch` | The rows of `records[].id`, plus the body `C` of records with no row. |
|
|
334
|
+
| `DELETE /batch`, `POST /batch/<action>` | The rows of `ids`. |
|
|
335
|
+
|
|
336
|
+
The resolved id must match `^[A-Za-z0-9._~-]{1,256}$` (`.` and `..` refused) and must name an
|
|
337
|
+
instance of the caller's own organization, read through the instance table's organization
|
|
338
|
+
firewall. Otherwise the answer is the gate's `403 ACCESS_ROLE_REQUIRED`, so a legacy URL never
|
|
339
|
+
reaches another organization's instance through a relationship.
|
|
340
|
+
|
|
341
|
+
What the forward narrows, deliberately:
|
|
342
|
+
|
|
343
|
+
- A collection that names no instance: `400 LEGACY_INSTANCE_REQUIRED` (it used to list the whole
|
|
344
|
+
organization).
|
|
345
|
+
- A batch spanning instances: `400 LEGACY_INSTANCE_MISMATCH`.
|
|
346
|
+
- Another organization's instance: `403` (it used to return an empty list).
|
|
347
|
+
|
|
348
|
+
Grep your shipped clients for the old path before claiming a table, and confirm every call names
|
|
349
|
+
the instance.
|
|
350
|
+
|
|
351
|
+
**Headers.** Every response from a legacy route carries `Deprecation: @<epoch>` (RFC 9745),
|
|
352
|
+
`Sunset: <date>` (RFC 8594) and `Link: <successor>; rel="successor-version"`. The link is the
|
|
353
|
+
concrete URL, or the template when the forward refused before it resolved an instance. CORS
|
|
354
|
+
exposes all three. Each call also logs one line from the Worker that serves it — route, successor
|
|
355
|
+
template, status, and the first 120 characters of the `User-Agent`, no ids — so you can count old
|
|
356
|
+
builds before you retire the mount:
|
|
357
|
+
|
|
358
|
+
```json
|
|
359
|
+
{"level":"info","event":"quickback.legacy_forward","route":"POST /api/v1/locations/update","successor":"/api/v1/event/{eventId}/locations/update","status":200,"ua":"AttendVIP/5.2 (iOS 18)"}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
**Moved actions.** A standalone action whose `path:` moved under the prefix declares its old path:
|
|
363
|
+
|
|
364
|
+
{/* doc-compile: skip — excerpt of an action file; input and execute are elided */}
|
|
365
|
+
```ts
|
|
366
|
+
export default defineAction({
|
|
367
|
+
path: '/event/:eventId/locations/update',
|
|
368
|
+
legacy: {
|
|
369
|
+
path: '/locations/update',
|
|
370
|
+
deprecated: '2026-11-02',
|
|
371
|
+
sunset: '2027-01-31',
|
|
372
|
+
instance: { table: 'locations', field: 'id' }, // the body's id names a locations row
|
|
373
|
+
},
|
|
374
|
+
// …
|
|
375
|
+
});
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
Without `instance`, the instance is the body field (query field for `GET`) named after the
|
|
379
|
+
prefix's `:param`. With `{ table, field }`, the input `field` is a row id of `table` (a table the
|
|
380
|
+
same namespace claims), and the forward reads that row's instance column.
|
|
381
|
+
|
|
382
|
+
**Retiring.** Remove `legacy`. The next build drops the mount, its OpenAPI operations and its
|
|
383
|
+
access-manifest entries. Passing the `sunset` date changes nothing at runtime; the compile warns
|
|
384
|
+
`LEGACY_PAST_SUNSET` and keeps serving, so retirement is always a deploy you can see in the
|
|
385
|
+
manifest diff. Per-resource API-key scopes (`locations:read`) keep naming the legacy base while
|
|
386
|
+
the mount exists and match nothing once it is removed.
|
|
387
|
+
|
|
388
|
+
The compile fails closed on every misuse — no namespace claims the table, no `{ roles }` lane,
|
|
389
|
+
no organization arm, no instance column, a colliding path, a bad date. See
|
|
390
|
+
[Legacy forward codes](/define/diagnostics#legacy-forward-codes).
|
|
391
|
+
|
|
251
392
|
## Nested areas
|
|
252
393
|
|
|
253
394
|
Areas nest to arbitrary depth. A nested area may declare additional **vocabulary** freely. A
|
|
@@ -307,6 +448,8 @@ When several standalone actions share a path prefix and the same relationship ga
|
|
|
307
448
|
|
|
308
449
|
Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware before the action's `execute()` runs. With the [per-namespace helper](#narrow-ctxexposeas-typing), that field is also statically typed as the loaded row.
|
|
309
450
|
|
|
451
|
+
Tables whose `path:` sits under the prefix are claimed too, and [pinned to the URL instance](#claimed-tables-are-pinned-to-the-url-instance) for every lane.
|
|
452
|
+
|
|
310
453
|
### When to use roles vs. relationships
|
|
311
454
|
|
|
312
455
|
A user is authorized for a row when **any** of the following is true:
|
|
@@ -559,7 +702,7 @@ Project-level only:
|
|
|
559
702
|
Inside a namespace action's `execute()`:
|
|
560
703
|
|
|
561
704
|
- `ctx.<exposeAs>` is populated by the middleware with the loaded resource row. Statically `any` by default — narrowed to `typeof <loadsTable>.$inferSelect` when the action's import points at the per-namespace helper (see [below](#narrow-ctxexposeas-typing-v027)).
|
|
562
|
-
-
|
|
705
|
+
- Nothing is stamped from the matched relationship row: an org or team firewall arm means membership, so a relationship caller (an attendee) keeps no active organization or team and reaches rows through the arms that name it — `ctx.<exposeAs>` and `ctx.scope.<kind>`. See [Relationships](/define/relationships#standalone-actions-surface-keys-and-loads--exposeas).
|
|
563
706
|
- The action's own `access:` block (additional roles, userRole, record predicates, OTHER relationship arms) still runs after the namespace gate — namespace handles entry, per-action gates further.
|
|
564
707
|
|
|
565
708
|
### Narrow `ctx.<exposeAs>` typing
|
|
@@ -568,7 +711,7 @@ The namespace middleware hydrates `ctx.<exposeAs>` at runtime. The static type o
|
|
|
568
711
|
|
|
569
712
|
The compiler emits one **per-namespace `defineAction` helper** alongside the standard `<feature>/.quickback/define-action.ts`. Importing from the narrowed helper retypes `ctx.<exposeAs>` inside `execute({ ctx })` to the loaded row's `$inferSelect` shape. Runtime behavior, action discovery, and the `path:` namespace match are identical.
|
|
570
713
|
|
|
571
|
-
The narrowed helper also knows what the namespace gate did before `execute` ran.
|
|
714
|
+
The narrowed helper also knows what the namespace gate did before `execute` ran. A namespace whose lanes are all bulk-grant lanes (`{ roles }`, `{ team }`) admits only callers carrying their own org, so its helper credits every access lane the org claim in the [scoped `db` type gate](/define/actions/scoped-db#caught-at-compile-time). A namespace with a relationship lane does not: the relationship caller has no active organization, so a `roles: ['member+', 'scope:event:attendee']` action under `/event/:eventId` that reads an org-only table is a `tsc` error — at runtime the attendee would get `403 FIREWALL_CLAIM_MISSING`. Read such tables through an arm that names the attendee (`{ field: 'eventId', equals: 'ctx.scope.event' }` beside the org arm), or pin by `ctx.event.organizationId` yourself.
|
|
572
715
|
|
|
573
716
|
```ts title="features/feeds/actions/feedMoments.ts"
|
|
574
717
|
// One-line flip per namespace-scoped action:
|