@quickback-dev/cli 0.14.2 → 0.16.1
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/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +12 -7
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/copy-public-assets.d.ts +34 -0
- package/dist/lib/copy-public-assets.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.js +118 -0
- package/dist/lib/copy-public-assets.js.map +1 -0
- package/dist/lib/copy-public-assets.test.d.ts +2 -0
- package/dist/lib/copy-public-assets.test.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.test.js +151 -0
- package/dist/lib/copy-public-assets.test.js.map +1 -0
- package/dist/skill/docs/changelog.md +256 -0
- package/dist/skill/docs/compiler/config/index.md +18 -0
- package/dist/skill/docs/compiler/config/output.md +34 -0
- package/dist/skill/docs/compiler/definitions/access.md +17 -3
- package/dist/skill/docs/compiler/definitions/firewall.md +27 -0
- package/dist/skill/docs/compiler/definitions/schema.md +9 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +84 -2
- package/dist/skill/docs/stack/auth/plugins/agent-auth.md +131 -0
- package/dist/skill/docs/stack/realtime/partyserver-rooms.md +10 -2
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +256 -0
- package/src/skill/docs/compiler/config/index.md +18 -0
- package/src/skill/docs/compiler/config/output.md +34 -0
- package/src/skill/docs/compiler/definitions/access.md +17 -3
- package/src/skill/docs/compiler/definitions/firewall.md +27 -0
- package/src/skill/docs/compiler/definitions/schema.md +9 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +84 -2
- package/src/skill/docs/stack/auth/plugins/agent-auth.md +131 -0
- package/src/skill/docs/stack/realtime/partyserver-rooms.md +10 -2
|
@@ -159,6 +159,33 @@ When the `firewall:` block is omitted, the compiler scans the schema for known s
|
|
|
159
159
|
|
|
160
160
|
So `firewall: [{ exception: true }]` on the default configuration returns `isNull(<table>.deletedAt)` from `buildFirewallConditions()` — no tenant filter, soft-delete filter still applied.
|
|
161
161
|
|
|
162
|
+
## Sysadmin Escape Hatch
|
|
163
|
+
|
|
164
|
+
When `cms: { sysadmin: true }` is set on the project (introduced in v0.15.0), every `buildFirewallConditions()` emits a runtime branch that drops tenant scopes for `ctx.userRole === 'sysadmin'` callers while keeping the soft-delete predicate:
|
|
165
|
+
|
|
166
|
+
```typescript
|
|
167
|
+
// Generated for an org-scoped table when cms.sysadmin: true
|
|
168
|
+
export function buildFirewallConditions(ctx: AppContext): SQL | undefined {
|
|
169
|
+
if (ctx.userRole === 'sysadmin') {
|
|
170
|
+
return isNull(invoices.deletedAt); // tenant predicate dropped, soft-delete kept
|
|
171
|
+
}
|
|
172
|
+
return and(
|
|
173
|
+
eq(invoices.organizationId, ctx.activeOrgId!),
|
|
174
|
+
isNull(invoices.deletedAt),
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The escape branch is **only** emitted when:
|
|
180
|
+
|
|
181
|
+
- `cms.sysadmin: true` is set on the project config
|
|
182
|
+
- The table has at least one tenant-scope predicate (org / owner / team / `via:` relationship). Tables with no tenant scopes already return what a sysadmin would see, so the runtime check would be dead code.
|
|
183
|
+
- The firewall does not declare `{ exception: true }` (no tenant scopes to drop).
|
|
184
|
+
|
|
185
|
+
**Sysadmin is distinct from admin.** `userRole === 'admin'` callers still go through the firewall normally — only `userRole === 'sysadmin'` triggers the bypass. Admins keep their existing universal-bypass at the *access* layer (cross-org reads on per-record routes via `?organizationId=`), but the firewall's row predicate remains in force. Sysadmin is opt-in, configured per-project, and intended for the cross-tenant CMS DB-admin tier — see [CMS Configuration](/compiler/config#cms-configuration).
|
|
186
|
+
|
|
187
|
+
If your project doesn't set `cms.sysadmin: true`, the escape branch is never emitted and the role value is functionally inert.
|
|
188
|
+
|
|
162
189
|
## Common Patterns
|
|
163
190
|
|
|
164
191
|
```typescript
|
|
@@ -309,6 +309,15 @@ These internal tables still participate in the database schema and migrations
|
|
|
309
309
|
|
|
310
310
|
The compiler automatically injects the four **[audit fields](#audit-fields)** (`createdAt`/`createdBy`/`modifiedAt`/`modifiedBy`), the soft-delete pair (`deletedAt`/`deletedBy`, when soft delete is enabled), and **`organizationId`** into child/junction tables when the parent feature is org-scoped. This ensures cascade soft deletes and scoped queries work correctly without manual column definitions.
|
|
311
311
|
|
|
312
|
+
> **`id` is currently NOT auto-injected — declare it yourself**
|
|
313
|
+
>
|
|
314
|
+
> Unlike audit fields, the `id` column is your responsibility today. The CRUD/action route generators, FK probing, access checks, and OpenAPI emission all assume every queryable table has a single string-typed `id` column. Tables that omit it — or use a non-`id` single PK (`userId.primaryKey()`) or a compound `primaryKey({ columns: [...] })` constraint — parse fine but produce broken generated code downstream.
|
|
315
|
+
>
|
|
316
|
+
> Use `q.id()` (preferred) or `id: text("id").primaryKey()` / `id: integer("id").primaryKey({ autoIncrement: true })` on every table that participates in routes. For internal tables marked `// @quickback-internal`, the constraint doesn't apply.
|
|
317
|
+
>
|
|
318
|
+
> This asymmetry is being closed in **v0.14.8** — `injectIdField` will run unconditionally alongside audit injection, including on junction tables. See the [v0.14.7 changelog](/docs/changelog#coming-next--id-field-auto-injection-v0148) for the migration plan.
|
|
319
|
+
|
|
320
|
+
|
|
312
321
|
## Audit Fields
|
|
313
322
|
|
|
314
323
|
Quickback adds four audit columns to **every table** (including child/junction tables without `defineTable`) — never declare them in your schemas:
|
|
@@ -17,7 +17,7 @@ The generated API returns structured error responses with consistent fields acro
|
|
|
17
17
|
|
|
18
18
|
## Error Response Format
|
|
19
19
|
|
|
20
|
-
All errors use a flat structure with contextual fields:
|
|
20
|
+
All errors use a flat structure with contextual fields. Every structured error response also carries a `request` block with the HTTP method, URL, request ID, and a redacted+truncated copy of the request body — enough to triage or hand the response to an LLM agent without grepping logs:
|
|
21
21
|
|
|
22
22
|
```json
|
|
23
23
|
{
|
|
@@ -28,7 +28,13 @@ All errors use a flat structure with contextual fields:
|
|
|
28
28
|
"required": ["hiring-manager"],
|
|
29
29
|
"current": ["interviewer"]
|
|
30
30
|
},
|
|
31
|
-
"hint": "Contact an administrator to grant necessary permissions"
|
|
31
|
+
"hint": "Contact an administrator to grant necessary permissions",
|
|
32
|
+
"request": {
|
|
33
|
+
"method": "POST",
|
|
34
|
+
"url": "/api/v1/candidates/cnd_01H.../advance",
|
|
35
|
+
"body": "{\"stage\":\"offer\"}",
|
|
36
|
+
"requestId": "0c4f2c9e-..."
|
|
37
|
+
}
|
|
32
38
|
}
|
|
33
39
|
```
|
|
34
40
|
|
|
@@ -39,6 +45,7 @@ All errors use a flat structure with contextual fields:
|
|
|
39
45
|
| `code` | string | Machine-readable error code |
|
|
40
46
|
| `details` | object | Layer-specific context (optional) |
|
|
41
47
|
| `hint` | string | Actionable guidance for resolution (optional) |
|
|
48
|
+
| `request` | object | Method, URL, redacted body, and request ID. Auto-attached by the runtime so the error body is self-contained — bodies are capped at 4 KB and well-known sensitive keys (`password`, `token`, `secret`, `apiKey`, `otp`, `code`, `authorization`, …) are replaced with `"[REDACTED]"` |
|
|
42
49
|
|
|
43
50
|
## Errors by Security Layer
|
|
44
51
|
|
|
@@ -222,3 +229,78 @@ Batch operations can return:
|
|
|
222
229
|
| `BATCH_SIZE_EXCEEDED` | Too many records in a single request |
|
|
223
230
|
| `BATCH_ATOMIC_FAILED` | Atomic batch failed, all changes rolled back |
|
|
224
231
|
| `BATCH_MISSING_IDS` | Batch update/delete missing required IDs |
|
|
232
|
+
|
|
233
|
+
## Action Failures (500)
|
|
234
|
+
|
|
235
|
+
When an action's `execute()` body throws something that isn't a known
|
|
236
|
+
transition / state / FK / constraint failure (e.g. a `TypeError`, a
|
|
237
|
+
fetch timeout, a third-party API error), the route returns
|
|
238
|
+
`ACTION_EXECUTION_FAILED`. The body forwards as much of the underlying
|
|
239
|
+
error as is safe to expose: error class name, message, cause-chain
|
|
240
|
+
message, and the top three stack frames with absolute paths sanitized
|
|
241
|
+
to basename + line number.
|
|
242
|
+
|
|
243
|
+
```json
|
|
244
|
+
{
|
|
245
|
+
"error": "Cannot read properties of undefined (reading 'getXmlFragment')",
|
|
246
|
+
"layer": "action",
|
|
247
|
+
"code": "ACTION_EXECUTION_FAILED",
|
|
248
|
+
"details": {
|
|
249
|
+
"name": "TypeError",
|
|
250
|
+
"frames": [
|
|
251
|
+
"at updateContent (notebooks.ts:142:31)",
|
|
252
|
+
"at execute (actions.ts:88:7)"
|
|
253
|
+
]
|
|
254
|
+
},
|
|
255
|
+
"hint": "The action handler threw an unhandled error. Check server logs for the underlying cause.",
|
|
256
|
+
"request": {
|
|
257
|
+
"method": "POST",
|
|
258
|
+
"url": "/api/v1/notebooks/nb_123/updateContent",
|
|
259
|
+
"body": "{\"content\":\"...\"}",
|
|
260
|
+
"requestId": "0c4f2c9e-..."
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
## Internal Errors (500)
|
|
266
|
+
|
|
267
|
+
Uncaught throws that escape every route handler land in the global
|
|
268
|
+
`onError` and return `INTERNAL_ERROR`. The body carries the same
|
|
269
|
+
underlying-error context as `ACTION_EXECUTION_FAILED`: `name`, `cause`,
|
|
270
|
+
sanitized `frames`, and the request block.
|
|
271
|
+
|
|
272
|
+
```json
|
|
273
|
+
{
|
|
274
|
+
"error": "Connection terminated unexpectedly",
|
|
275
|
+
"layer": "database",
|
|
276
|
+
"code": "INTERNAL_ERROR",
|
|
277
|
+
"details": {
|
|
278
|
+
"name": "Error",
|
|
279
|
+
"cause": "ECONNRESET",
|
|
280
|
+
"frames": ["at query (db.ts:54:12)"]
|
|
281
|
+
},
|
|
282
|
+
"hint": "Uncaught error during request handling. Look up the requestId in server logs for the full stack trace, or set EXPOSE_ERROR_STACK=1 to include it inline.",
|
|
283
|
+
"requestId": "0c4f2c9e-...",
|
|
284
|
+
"request": {
|
|
285
|
+
"method": "GET",
|
|
286
|
+
"url": "/api/v1/jobs",
|
|
287
|
+
"requestId": "0c4f2c9e-..."
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### Exposing the full stack
|
|
293
|
+
|
|
294
|
+
By default the response body only carries the top three sanitized
|
|
295
|
+
frames — full stack traces stay server-side so the worker bundle's
|
|
296
|
+
on-disk layout doesn't leak to API clients. To include the full stack
|
|
297
|
+
in the response (useful in dev / staging), set `EXPOSE_ERROR_STACK=1`
|
|
298
|
+
on the worker (`wrangler.toml` `[vars]`, or `wrangler secret put`):
|
|
299
|
+
|
|
300
|
+
```toml
|
|
301
|
+
[vars]
|
|
302
|
+
EXPOSE_ERROR_STACK = "1"
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
When set, both the global 500 and `ACTION_EXECUTION_FAILED` bodies
|
|
306
|
+
gain a `details.stack` field with the unsanitized stack trace.
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# Agent Auth Plugin
|
|
2
|
+
|
|
3
|
+
`@better-auth/agent-auth` is the official server implementation of the [Agent Auth Protocol](https://agentauthprotocol.com). When you enable it, your Quickback worker becomes an Agent Auth provider: AI agents can register, request scoped capability grants from a real user, get approved through device-authorization or CIBA, and then call your API with short-lived signed JWTs.
|
|
4
|
+
|
|
5
|
+
> The upstream `@better-auth/agent-auth` package is in heavy development and not yet stable. The Quickback integration pins a specific version and exposes a deliberately small surface for v1 — see "Limitations" at the bottom.
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
## What gets enabled
|
|
9
|
+
|
|
10
|
+
Adding `agentAuth` to your auth config force-enables two more plugins:
|
|
11
|
+
|
|
12
|
+
| Plugin | Why |
|
|
13
|
+
|--------|-----|
|
|
14
|
+
| `bearer` | Lets clients send Better Auth session tokens via `Authorization: Bearer …` instead of cookies. The agent surface is bearer-only. |
|
|
15
|
+
| `oauthProvider` | OAuth 2.1 + OIDC provider so MCP clients can register, get tokens, and call your API as a real user. Replaces the deprecated `mcp` plugin. |
|
|
16
|
+
|
|
17
|
+
There's no useful Agent Auth deployment without these — the compiler auto-adds them so you don't trip over a confusing runtime error.
|
|
18
|
+
|
|
19
|
+
The full Bearer matrix on the agent surface (everything reached through `/mcp` and the agent-auth REST projection):
|
|
20
|
+
|
|
21
|
+
| Bearer flavor | Resolved by | Identity |
|
|
22
|
+
|---------------|-------------|----------|
|
|
23
|
+
| BA session token | `bearer` plugin | The signed-in user |
|
|
24
|
+
| OAuth access token | `oauthProvider` plugin | The user who consented at OAuth time |
|
|
25
|
+
| Agent JWT | `@better-auth/agent-auth` | The agent (acting on behalf of its bound user) |
|
|
26
|
+
|
|
27
|
+
Cookie auth is **not** forwarded into `/mcp` — bearer is the only channel, and CSRF surface is zero.
|
|
28
|
+
|
|
29
|
+
## Configuration
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
import { defineAuth, defineConfig, defineDatabase, defineRuntime } from "@quickback/compiler";
|
|
33
|
+
|
|
34
|
+
export default defineConfig({
|
|
35
|
+
name: "acme-api",
|
|
36
|
+
providers: {
|
|
37
|
+
runtime: defineRuntime("cloudflare"),
|
|
38
|
+
database: defineDatabase("cloudflare-d1"),
|
|
39
|
+
auth: defineAuth("better-auth", {
|
|
40
|
+
emailAndPassword: { enabled: true },
|
|
41
|
+
plugins: {
|
|
42
|
+
agentAuth: {
|
|
43
|
+
providerName: "Acme",
|
|
44
|
+
providerDescription: "Acme APIs for AI agents.",
|
|
45
|
+
modes: ["delegated", "autonomous"],
|
|
46
|
+
defaultHostCapabilities: ["GET", "HEAD"],
|
|
47
|
+
},
|
|
48
|
+
},
|
|
49
|
+
}),
|
|
50
|
+
},
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The plain-flag form is also valid — use it when you don't need to override any defaults:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
auth: defineAuth("better-auth", {
|
|
58
|
+
plugins: ["agentAuth"],
|
|
59
|
+
})
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Options
|
|
63
|
+
|
|
64
|
+
| Option | Type | Default | Notes |
|
|
65
|
+
|--------|------|---------|-------|
|
|
66
|
+
| `providerName` | `string` | `env.APP_NAME` | Shown in the discovery doc and in the approval UI. |
|
|
67
|
+
| `providerDescription` | `string` | `"Agent-callable API powered by Quickback."` | Free-form description in `/.well-known/agent-configuration`. |
|
|
68
|
+
| `modes` | `("delegated" \| "autonomous")[]` | `["delegated", "autonomous"]` | Supported agent modes. |
|
|
69
|
+
| `defaultHostCapabilities` | `string[]` \| `true` | `["GET", "HEAD"]` | Capabilities auto-granted to a newly registered host. |
|
|
70
|
+
|
|
71
|
+
Most of the underlying plugin's surface (capability list, `onExecute`, custom approval-method resolver, `onEvent` audit hook) isn't projected through the compiler in v1 — see "Limitations".
|
|
72
|
+
|
|
73
|
+
## Routes
|
|
74
|
+
|
|
75
|
+
When the plugin is enabled the compiler emits:
|
|
76
|
+
|
|
77
|
+
- `GET /.well-known/agent-configuration` — discovery document with issuer, endpoints, supported modes, default location.
|
|
78
|
+
- All of the plugin's own endpoints, mounted by Better Auth under `/auth/v1/agent/*`.
|
|
79
|
+
|
|
80
|
+
The Account SPA gets a new route at `/agents/approve` for device-code approval. The plugin's `deviceAuthorizationPage` is automatically pinned at `${ACCOUNT_URL}/agents/approve`.
|
|
81
|
+
|
|
82
|
+
## Approval flow
|
|
83
|
+
|
|
84
|
+
1. The agent calls `/auth/v1/agent/register` to create itself, then requests a capability grant.
|
|
85
|
+
2. The user enters the device code at `${ACCOUNT_URL}/agents/approve` (or follows the deep-link the agent showed them).
|
|
86
|
+
3. The Account SPA fetches the pending request, shows the agent name + provider name + the capabilities being requested, with a "Step-up" badge on any capability whose `approvalStrength` is `"webauthn"`.
|
|
87
|
+
4. User clicks **Authorize** (or **Deny**). Approval grants the capabilities; denial leaves the request pending.
|
|
88
|
+
5. The agent polls or receives the token via the configured method, then calls capabilities with `Authorization: Bearer <agent-jwt>`.
|
|
89
|
+
|
|
90
|
+
You revoke an agent at any time from your account settings (or directly via the BA admin API).
|
|
91
|
+
|
|
92
|
+
## Schema
|
|
93
|
+
|
|
94
|
+
The plugin adds tables for `agent`, `host`, `grant`, and `approval`. They're created automatically by `auth migrate` / `auth generate` — no manual Drizzle work needed.
|
|
95
|
+
|
|
96
|
+
## OpenAPI capability projection (default on)
|
|
97
|
+
|
|
98
|
+
When `agentAuth` is enabled, the compiler emits `src/lib/openapi-spec.ts` (the project's full OpenAPI spec inlined as a const) and wires `createFromOpenAPI(openapiSpec, { ... })` into the `agentAuth(...)` call. Every operation with an `operationId` becomes a capability. No manual capability list required.
|
|
99
|
+
|
|
100
|
+
**How requests flow:**
|
|
101
|
+
|
|
102
|
+
1. Agent calls `POST /capability/execute` with its agent JWT.
|
|
103
|
+
2. The plugin verifies JWT + grant + constraints, then runs `onExecute`.
|
|
104
|
+
3. `onExecute` (the plugin's built-in proxy) makes a self-fetch to the worker's own URL (`env.BETTER_AUTH_URL`).
|
|
105
|
+
4. `resolveHeaders` mints a Better Auth JWT with `sub: agentSession.user.id` so the inner request looks like an authenticated user call.
|
|
106
|
+
5. The worker's JWT fast-path picks it up, populates `ctx`, and the full firewall + access + masking pipeline runs.
|
|
107
|
+
|
|
108
|
+
**Default approval strength:** GET → `"session"`, POST/PUT/PATCH/DELETE → `"webauthn"`. Override with the `approvalStrength` option.
|
|
109
|
+
|
|
110
|
+
**To opt out** and wire capabilities by hand:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
auth: defineAuth("better-auth", {
|
|
114
|
+
plugins: {
|
|
115
|
+
agentAuth: { fromOpenAPI: false },
|
|
116
|
+
},
|
|
117
|
+
})
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
When `fromOpenAPI: false`, the emitted call has `capabilities: []` and no proxy — you write the capability list + `onExecute` in your own `lib/auth.ts` overrides.
|
|
121
|
+
|
|
122
|
+
## Limitations (v1)
|
|
123
|
+
|
|
124
|
+
- **WebAuthn step-up isn't wired in the approval UI yet.** Capabilities tagged `approvalStrength: "webauthn"` show a Step-up badge but the actual escalation call isn't made — the upstream API for that escalation is still settling. Until it lands, those capabilities will fail server-side regardless of approval.
|
|
125
|
+
- **No CLI helpers for listing / revoking agents.** Use the BA admin API directly.
|
|
126
|
+
- **Self-fetch on Cloudflare Workers** adds one subrequest per capability call (~50ms). For typical agent traffic this is fine; for very high-frequency agents consider pinning a custom `onExecute` that uses `app.request()` for in-process routing.
|
|
127
|
+
- **`@better-auth/agent-auth` 0.4.5 ships ESM-only exports** without a `require` condition. The compiler image patches the package's `package.json` at install time so the Better Auth CLI's `auth generate` step (jiti / CJS) can resolve it. Remove the patch in the Dockerfile when upstream ships proper exports.
|
|
128
|
+
|
|
129
|
+
## Why bearer-only?
|
|
130
|
+
|
|
131
|
+
The MCP and agent surfaces are server-to-server by nature. Cookies on those surfaces add CSRF surface for no benefit (no browser callers), and `x-api-key` was the legacy `apiKey`-plugin path that fragments the auth model. Bearer is the one true channel here. If your project still wants API-key auth, configure the `apiKey` plugin to accept its key via `Authorization: Bearer` so everything stays one channel.
|
|
@@ -148,6 +148,13 @@ bindings: {
|
|
|
148
148
|
},
|
|
149
149
|
},
|
|
150
150
|
|
|
151
|
+
// Multi-table feature: pin the gate to a specific table so the
|
|
152
|
+
// firewall + id query is unambiguous (v0.16.1+).
|
|
153
|
+
{
|
|
154
|
+
name: 'NotepadInteractions', className: 'NotepadInteractions', from: 'lib/NotepadInteractions',
|
|
155
|
+
access: { resource: { feature: 'interactions', table: 'interactions' } },
|
|
156
|
+
},
|
|
157
|
+
|
|
151
158
|
// Genuinely public room (no auth, no row lookup) — opt out explicitly.
|
|
152
159
|
{ name: 'PublicLobby', className: 'PublicLobby', from: 'lib/PublicLobby',
|
|
153
160
|
access: 'public' },
|
|
@@ -158,11 +165,12 @@ bindings: {
|
|
|
158
165
|
What the compiler emits:
|
|
159
166
|
|
|
160
167
|
- **`access: { resource: 'chats' }`** — `app.use('/realtime/chat/*', …)` that 401s anonymous, parses the URL segment as a row id, queries `chats` with the resource's `buildFirewallConditions(ctx)` and `eq(chats.id, rowId)`, and 403s when the row is invisible to the caller (out-of-org, soft-deleted, etc.). The DO's `onLoad` / `onConnect` then runs only for rows the user can already read.
|
|
161
|
-
-
|
|
168
|
+
- **`access: { resource: { feature, table } }`** — same gate, but the schema import + firewall alias are keyed off the pinned `table` instead of the feature name. Required when a feature owns more than one resourceful table; the access gate emit can't pick which table's firewall to query otherwise.
|
|
169
|
+
- **Multi-resource form** — same gate but with a regex parser dispatching to per-kind firewall lookups. Unknown kinds 400 at the gate. Each `resources[kind].resource` accepts either form (string shorthand or `{ feature, table }`).
|
|
162
170
|
- **`access: 'public'`** — `app.use('/realtime/<kebab>/*', …)` that just passes through. Use for anonymous game lobbies / public collab pads where the room itself is the unit of access.
|
|
163
171
|
- **No `access` declared** — falls through to the catchall `/realtime/*` gate that just checks `ctx.authenticated`. (v0.11.1 behavior.)
|
|
164
172
|
|
|
165
|
-
Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade.
|
|
173
|
+
Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table.
|
|
166
174
|
|
|
167
175
|
### Hand-written mount with `onBeforeConnect`
|
|
168
176
|
|