@quickback-dev/cli 0.16.0 → 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.
@@ -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
- - **Multi-resource form** — same gate but with a regex parser dispatching to per-kind firewall lookups. Unknown kinds 400 at the gate.
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