@quickback-dev/cli 0.47.11 → 0.47.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/dist/commands/create.js +25 -0
  2. package/dist/commands/create.js.map +1 -1
  3. package/dist/docs/content.js +5 -5
  4. package/dist/docs/content.js.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/lib/action-harvest.d.ts.map +1 -1
  7. package/dist/lib/action-harvest.js +110 -46
  8. package/dist/lib/action-harvest.js.map +1 -1
  9. package/dist/lib/action-harvest.test.js +97 -0
  10. package/dist/lib/action-harvest.test.js.map +1 -1
  11. package/dist/lib/api-client.d.ts.map +1 -1
  12. package/dist/lib/api-client.js +18 -1
  13. package/dist/lib/api-client.js.map +1 -1
  14. package/dist/skill/SKILL.md +46 -0
  15. package/dist/skill/docs/changelog.md +78 -0
  16. package/dist/skill/docs/compiler/config/agents.md +42 -1
  17. package/dist/skill/docs/compiler/definitions/scopes.md +140 -2
  18. package/dist/skill/docs/stack/auth/plugins/index.md +9 -1
  19. package/dist/skill/docs/stack/schedules/index.md +17 -0
  20. package/package.json +1 -1
  21. package/src/skill/SKILL.md +46 -0
  22. package/src/skill/docs/changelog.md +78 -0
  23. package/src/skill/docs/compiler/config/agents.md +42 -1
  24. package/src/skill/docs/compiler/definitions/scopes.md +140 -2
  25. package/src/skill/docs/stack/auth/plugins/index.md +9 -1
  26. package/src/skill/docs/stack/schedules/index.md +17 -0
  27. package/dist/codex/AGENTS.md +0 -290
  28. package/dist/commands/codex.d.ts +0 -16
  29. package/dist/commands/codex.d.ts.map +0 -1
  30. package/dist/commands/codex.js +0 -159
  31. package/dist/commands/codex.js.map +0 -1
  32. package/dist/commands/init.d.ts +0 -6
  33. package/dist/commands/init.d.ts.map +0 -1
  34. package/dist/commands/init.js +0 -405
  35. package/dist/commands/init.js.map +0 -1
  36. package/dist/lib/sweep-stale.d.ts +0 -25
  37. package/dist/lib/sweep-stale.d.ts.map +0 -1
  38. package/dist/lib/sweep-stale.js +0 -179
  39. package/dist/lib/sweep-stale.js.map +0 -1
  40. package/dist/lib/sweep-stale.test.d.ts +0 -2
  41. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  42. package/dist/lib/sweep-stale.test.js +0 -130
  43. package/dist/lib/sweep-stale.test.js.map +0 -1
@@ -2,6 +2,84 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Sessionless scope mint: `ctx.mintScope` + `subject: 'supplied' \| 'both'`
6
+
7
+ A scope can now be minted for a principal who has **no Better Auth account** — an
8
+ event attendee arriving by email + invite code, a kiosk/handout code, a partner
9
+ token. The action proves the relationship its own way and asks Quickback to mint
10
+ a disciplined scope token from the row it proved.
11
+
12
+ - **`authz.scopes.<kind>.roles.<role>.subject: 'user' \| 'supplied' \| 'both'`** (default `'user'`).
13
+ `'both'` makes the *same* `scope:event:attendee` reachable by a logged-in user
14
+ (via `/scope/v1/enter`) and a sessionless invite-holder (via `ctx.mintScope`) —
15
+ one firewall arm, one masking rule, both principals.
16
+ - **`ctx.mintScope({ via, subject })`** — hydrated on `ctx` in any action (including
17
+ PUBLIC) when a `supplied`/`both` role is declared. The action supplies only the
18
+ conferring row's **primary key**; Quickback reads the role, resource id,
19
+ sub-keys, and subject id **off that row** — never caller-asserted, so the role
20
+ can't be forged. Returns a **scope-only** JWT (no user identity): `ctx.userId`
21
+ stays undefined, so user/org/owner gates and the `AUTHENTICATED`/`USER`
22
+ pseudo-roles all fail closed; only `scope:<kind>:<role>` gates admit it.
23
+ - **`ctx.scope.<kind>.subjectId`** — a reserved claim carrying the proven subject
24
+ row's PK, populated on **both** proof paths. Scope an attendee's self-data
25
+ (travel, dietary, todos) with a single firewall arm
26
+ (`{ field: 'guestId', equals: 'ctx.scope.event.subjectId' }`) that serves both a
27
+ user-attendee and a sessionless one.
28
+ - **Realtime** — the ws-ticket authorizes a scope-only principal directly off its
29
+ proven `ctx.scope` claim, so accountless attendees join the same rooms with the
30
+ same scope role. The `where:` filter runs on the mint probe, so a cancelled row
31
+ confers nothing (revocation within one ≤180s mint cycle).
32
+
33
+ See [Scopes → Sessionless scope mint](/compiler/definitions/scopes#sessionless-scope-mint--ctxmintscope).
34
+
35
+ ### MCP OAuth: split authorization-server / resource-server (multi-app SSO)
36
+
37
+ You can now run one canonical authorization server with many resource servers (each
38
+ hosting its own `/mcp`) over a shared auth DB:
39
+
40
+ - A resource server that sets `agents.mcp.requireAuth` now emits the full OAuth
41
+ access-token **verification** path on its own — previously the JWKS-verify block
42
+ only emitted when the separate `auth.config.oauth.enabled` flag was set, so a
43
+ requireAuth-only resource server fell back to HMAC + session and 401'd every valid
44
+ externally-issued bearer.
45
+ - Point a resource server at an external AS with `auth.config.oauth.issuerUrl`; the
46
+ middleware verifies incoming bearers against the shared JWKS (`iss`/`aud`/`exp` +
47
+ live-session binding).
48
+ - `auth.config.oauth.audiences` (an array) registers federated resource-server
49
+ audiences on the AS (RFC 8707). It now **unions** with the AS's own origin instead
50
+ of replacing it, so listing federated servers never drops the AS's own `/mcp`
51
+ audience. Also exposed on the plugin-form `oauthProvider.validAudiences`.
52
+
53
+ See [Agents → Split authorization server](/compiler/config/agents#split-authorization-server--resource-server-multi-app-sso).
54
+
55
+ ### MCP tools: callable path params + typed input schemas
56
+
57
+ An action mounted under a path that carries a parameter — a namespace prefix like
58
+ `/scope/:scopeId/...`, or any `path:` with `:params` — now produces a fully
59
+ callable MCP tool:
60
+
61
+ - The mounted route's path params are extracted into the tool's `inputSchema`
62
+ (and `_pathParams`), so the model has a field to supply each one. Previously
63
+ only record-based actions emitted a param (the hard-coded `id`); a standalone
64
+ or namespace path param was absent from the schema, the URL resolved with an
65
+ empty segment, and the action was uncallable over MCP.
66
+ - Standalone routes are stored in Hono colon form (`:scopeId`); the OpenAPI spec
67
+ key (and therefore the tool's `_path`) is now normalized to brace form
68
+ (`{scopeId}`) so the runtime's brace-only path interpolation can fill it.
69
+
70
+ Action `input` schemas also lower to richer JSON Schema instead of a phantom
71
+ empty `{}`: `z.coerce.*`, `z.literal`, unions of literals, and **nested
72
+ `z.object`** (child keys stay nested) now emit their real types, so the model —
73
+ and the OpenAPI spec — see the actual field shapes. See
74
+ [Agents → MCP tools](/compiler/config/agents).
75
+
76
+ ### Scaffold surfaces MCP/OAuth + secrets opt-ins
77
+
78
+ `quickback create` now seeds the generated `quickback.config.ts` with curated,
79
+ commented-out hints for the authenticated MCP server (`agents.mcp.requireAuth`), the
80
+ split-AS `oauth.issuerUrl`/`audiences`, and `bindings.secrets` — so these opt-ins are
81
+ discoverable in the config itself, not only in the docs.
82
+
5
83
  ### Custom secrets via `bindings.secrets`
6
84
 
7
85
  Declare a custom secret your feature/action code reads off `env` — name and
@@ -74,7 +74,7 @@ See [Interactive OAuth](#interactive-oauth-requireauth) below.
74
74
 
75
75
  ### Tools
76
76
 
77
- Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a flat JSON Schema combining path params, query params, and the request body.
77
+ Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a JSON Schema combining the request body with every parameter in the operation's **mounted** path — including the `:params` contributed by a namespace prefix (e.g. `/scope/:scopeId/...`), so a standalone or namespace action is always callable, not just record-based ones. Nested `z.object` inputs are preserved as nested objects rather than flattened, so the model sees each field's real type.
78
78
 
79
79
  `tools/call` re-enters the same Hono app via `app.request(...)` — so **every existing middleware runs exactly as it would for a direct REST call**: authentication, firewall, access control, guards, masking. No bypass.
80
80
 
@@ -138,6 +138,47 @@ The login and consent screens are served by your [Account SPA](/stack/account-ui
138
138
  > `requireAuth` removes anonymous public-tool access over `/mcp`. Use it when the MCP surface is meant for authenticated users; leave it off (the default) for servers that expose genuinely public tools.
139
139
 
140
140
 
141
+ ### Split authorization server / resource server (multi-app SSO)
142
+
143
+ By default a Worker is both the authorization server (AS) and the resource server — it issues *and* verifies its own OAuth tokens. For multi-app SSO you can run **one canonical AS** and **many resource servers** (each hosting its own `/mcp`) that share a single auth database (the same D1, e.g. via `crossSubDomainCookies` on a shared parent domain). Two config fields wire it up — both under `auth.config.oauth`:
144
+
145
+ **On each resource server** — point discovery at the external AS and verify its tokens:
146
+
147
+ ```ts
148
+ auth: {
149
+ config: {
150
+ oauth: {
151
+ enabled: true,
152
+ issuerUrl: "https://auth.example.com/auth/v1", // the canonical AS
153
+ },
154
+ },
155
+ },
156
+ agents: { mcp: { requireAuth: true } },
157
+ ```
158
+
159
+ `issuerUrl` makes `/.well-known/oauth-protected-resource` advertise the AS (not this Worker), and the generated middleware verifies incoming `Bearer` access tokens against the **shared JWKS** (`iss` must equal `issuerUrl`, `aud` must equal this Worker's `/mcp`, plus `exp` + live-session binding). Because the auth DB is shared, the resource server reads the AS's signing keys and the session row directly — no cross-Worker HTTP call.
160
+
161
+ **On the authorization server** — register the resource audiences it may mint tokens for ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707) resource indicators):
162
+
163
+ ```ts
164
+ auth: {
165
+ config: {
166
+ oauth: {
167
+ enabled: true,
168
+ audiences: [
169
+ "https://crm.example.com/mcp",
170
+ "https://billing.example.com/mcp",
171
+ ],
172
+ },
173
+ },
174
+ },
175
+ ```
176
+
177
+ `audiences` is an array — list every federated resource server. The AS's own origin (and `/mcp`) is always included automatically, so you only list the *other* servers; a token requested with `resource=https://crm.example.com/mcp` is then minted with that audience instead of rejected.
178
+
179
+ > `agents.mcp.requireAuth` is the documented switch for an authenticated MCP server, and it now emits the full OAuth token-verification path on its own — a resource server needs only `requireAuth` + `oauth.issuerUrl`, not a separate `oauth.enabled` step.
180
+
181
+
141
182
  ### Connecting clients
142
183
 
143
184
  **Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
@@ -15,6 +15,8 @@ Reach for a scope when a principal must touch a bounded slice of an instance **w
15
15
 
16
16
  Each is *event-scoped* but a **distinct least-privilege role**. Org members are unaffected — they keep their normal tenant access.
17
17
 
18
+ Most scope principals are signed-in users who prove a relationship at [`/scope/v1/enter`](#2-enter-the-scope). But some have **no account at all** — an attendee who arrives by email + invite code, a kiosk/handout code, a partner token. For those, an action proves the principal its own way and [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) mints the same scope, no Better Auth user required.
19
+
18
20
  ## The model
19
21
 
20
22
  ### 1. Declare relationships + scopes
@@ -315,6 +317,131 @@ forge a scope role — the guard, not the flag, is the gate.
315
317
  - **The mint is gated by the same proven-relationship guard as the in-memory stamp.** It runs *after* the gate has granted access, reading the instance id from the proven path param (`:eventId`) — never from request input — so the minted `scope:<kind>:<role>` is backed by exactly the proof `/scope/v1/enter` requires. The token is **byte-identical** to one `/scope/v1/enter` would produce: same shared mint helper, same carry-forward of any *other* verified scope kinds already on the incoming token (the freshly-proven kind takes precedence; siblings survive the re-mint).
316
318
  - **The mint is best-effort.** A mint failure (e.g. a missing signing secret) **never fails the request** — the in-memory stamp already authorized it; the caller simply doesn't receive a refreshed token on that response and can fall back to `/scope/v1/enter`.
317
319
 
320
+ ## Sessionless scope mint — `ctx.mintScope`
321
+
322
+ `POST /scope/v1/enter` and the namespace resolver both prove the relationship by
323
+ **`ctx.userId`** — so they require a Better Auth account. But a legitimate
324
+ principal often has none: an **event attendee who arrives by email + invite
325
+ code**, holding an opaque session token you validate yourself, who must never
326
+ get a global account. The shape is general — magic links, kiosk/handout codes,
327
+ partner-issued API keys, expiring share links that need row-level scope.
328
+
329
+ For these, prove the relationship **your own way** inside an action, then ask
330
+ Quickback to mint a disciplined scope token from the row you proved.
331
+
332
+ ### 1. Opt the role into supplied-subject proof
333
+
334
+ Add `subject` to the scope role (default `'user'`):
335
+
336
+ ```typescript
337
+ authz: {
338
+ scopes: {
339
+ event: {
340
+ requestField: 'eventId',
341
+ roles: {
342
+ // 'both' → the SAME scope:event:attendee for a logged-in user
343
+ // (via /enter) AND a sessionless invite-holder (via ctx.mintScope).
344
+ attendee: { via: 'attendeeOf', subKeys: ['guestId'], subject: 'both' },
345
+ },
346
+ },
347
+ },
348
+ }
349
+ ```
350
+
351
+ - **`'user'`** (default) — `/scope/v1/enter` only, proven by `subject.column = ctx.userId`. Unchanged.
352
+ - **`'supplied'`** — sessionless only. `ctx.mintScope` mints it; `/enter` won't (there's no user to probe).
353
+ - **`'both'`** — either path. A user-attendee and a sessionless invite-attendee converge on **one** `scope:event:attendee` — one firewall arm, one masking rule, both principals.
354
+
355
+ This opt-in is the single fail-closed switch: without `'supplied'` or `'both'`, no relationship is mintable by a supplied id.
356
+
357
+ ### 2. Mint from the proven row
358
+
359
+ `ctx.mintScope` is hydrated on `ctx` in **any action** when a `subject:
360
+ 'supplied' | 'both'` role is declared (including **PUBLIC** actions — the
361
+ canonical caller has no token yet). The action proves the principal however it
362
+ likes, then hands Quickback **only the conferring row's primary key**:
363
+
364
+ ```typescript
365
+ // features/events/actions/enterEvent.ts
366
+ export default defineAction({
367
+ path: '/enter-event',
368
+ method: 'POST',
369
+ input: z.object({ code: z.string() }),
370
+ access: { roles: ['PUBLIC'] }, // unauthenticated entry
371
+ async execute({ ctx, input }) {
372
+ const guestRowId = await validateInviteCode(ctx, input.code); // YOUR proof, YOUR table
373
+ const { token } = await ctx.mintScope({ via: 'attendeeOf', subject: guestRowId });
374
+ return { token }; // client sends it as `Authorization: Bearer …` thereafter
375
+ },
376
+ });
377
+ ```
378
+
379
+ You assert **nothing** about the scope. Quickback re-reads the `attendeeOf` row
380
+ by primary key and takes the role, the resource id (`eventId`), the sub-keys,
381
+ and the subject id **off that row** — so a buggy or hostile action can't forge
382
+ `organizer`, can't pick a different event, and can't widen the slice. The only
383
+ thing delegated to you is *which row* — exactly the opaque-credential check that
384
+ has to be custom code.
385
+
386
+ | What you supply | What Quickback reads off the row |
387
+ |---|---|
388
+ | `via` (a declared `supplied`/`both` relationship) + `subject` (the `from`-row PK you proved) | the role, `id` (resource), sub-keys, and `subjectId` — none caller-asserted |
389
+
390
+ The `where:` filter runs on the mint probe exactly as at `/enter` — a cancelled
391
+ or pending row confers nothing, so flipping a guest's `status` revokes them
392
+ within one mint cycle (**≤180s**). Re-prove by calling `ctx.mintScope` again
393
+ (your own refresh endpoint does exactly that). The by-PK probe does **not** apply
394
+ the relationship's tenant firewall (a sessionless principal has no
395
+ `activeOrgId` yet — the proven row *is* what establishes scope), but matching by
396
+ primary key + the `where:` filter keeps it bounded and fail-closed.
397
+
398
+ ### 3. The scope-only token
399
+
400
+ `ctx.mintScope` signs a **scope-only** JWT — it carries the `scope` claim and
401
+ nothing else. There is **no user identity**: the auth middleware builds a context
402
+ with **`ctx.userId` undefined**, so every user-, org-, and owner-gated path
403
+ **fails closed automatically** (an owner firewall compares against `undefined`
404
+ → matches nothing; org-role gates see empty `ctx.roles`). The `AUTHENTICATED`
405
+ and `USER` pseudo-roles **exclude** a scope principal by design — it is
406
+ authenticated *as a scope*, not as "any signed-in user". Only
407
+ `scope:<kind>:<role>` gates and `ctx.scope.<kind>` firewall arms admit it.
408
+
409
+ Everything downstream — REST firewall, masking, scoped-role access, the realtime
410
+ ws-ticket — then treats the sessionless attendee **identically** to a
411
+ user-proven one. There is no new enforcement surface; the principal is just
412
+ `scope:event:attendee`.
413
+
414
+ ### `subjectId` — scoping to the person, not just the instance
415
+
416
+ A user-proven scope scopes self-data (an attendee's travel, dietary, todos) by
417
+ `ctx.userId`. A sessionless attendee has no `ctx.userId`, so the **proven
418
+ subject's identity rides in the claim** as a reserved **`subjectId`** — the
419
+ conferring row's primary key:
420
+
421
+ ```jsonc
422
+ "scope": { "event": { "id": "evt_123", "roles": ["attendee"], "subjectId": "gst_42" } }
423
+ ```
424
+
425
+ Scope self-data on it with one firewall arm:
426
+
427
+ ```typescript
428
+ { field: 'guestId', equals: 'ctx.scope.event.subjectId' }
429
+ ```
430
+
431
+ `subjectId` is populated on **both** proof paths — `/scope/v1/enter` projects
432
+ the matched row's PK too — so the arm above is **one arm that serves both** a
433
+ logged-in attendee and a sessionless one. (It is distinct from
434
+ `ctx.scope.event.id`, which is the *instance* — the event.)
435
+
436
+ ### Realtime
437
+
438
+ A scope-only token authorizes the realtime
439
+ [ws-ticket](/stack/realtime/durable-objects) directly off its proven
440
+ `ctx.scope` claim — no `ctx.userId` re-probe. The sessionless attendee joins the
441
+ same per-event rooms (and per-attendee rooms keyed on `subjectId`) as a
442
+ user-attendee, carrying the same scope role on the ticket. So the REST gate and
443
+ the socket gate stay identical for accountless principals too.
444
+
318
445
  ## Revocation & TTL
319
446
 
320
447
  The scope claim is trusted between proofs — it is never re-checked against the database while it rides. Two bounds keep that window finite:
@@ -331,17 +458,28 @@ So removing a guest/staff row takes effect within **cap + one TTL** for a client
331
458
 
332
459
  ```typescript
333
460
  // AppContext (generated lib/types.ts)
334
- ctx.scope?: Record<string, { id: string; roles?: string[]; [subKey: string]: string | string[] | undefined }>;
461
+ ctx.scope?: Record<string, { id: string; roles?: string[]; subjectId?: string; [subKey: string]: string | string[] | undefined }>;
335
462
 
336
463
  // authz.scopes.<kind>
337
464
  {
338
465
  requestField: string; // body field carrying the instance id
339
- roles: Record<string, { via: string; subKeys?: string[] }>; // 'col' → eq, 'col[]' → inArray
466
+ roles: Record<string, {
467
+ via: string;
468
+ subKeys?: string[]; // 'col' → eq, 'col[]' → inArray
469
+ subject?: 'user' | 'supplied' | 'both'; // who selects the conferring row (default 'user')
470
+ }>;
340
471
  }
472
+
473
+ // ctx.mintScope — present in actions when a `subject: 'supplied' | 'both'` role is declared
474
+ ctx.mintScope(opts: { via: string; subject: string; setAuthToken?: boolean }):
475
+ Promise<{ token: string; scope: { id: string; roles: string[]; subjectId?: string } }>;
341
476
  ```
342
477
 
343
478
  - `requestField` must equal every role-relationship's `resource.column`.
344
479
  - Each relationship's `from` table must exist and ship a generated firewall (it can't be `exception`).
345
480
  - A `subKeys` entry ending in `[]` is **set-valued** (lowers to `inArray`, minted as `string[]`); without the marker it's scalar (`eq`, minted as `string`).
481
+ - `subject` defaults to `'user'`. `'supplied'`/`'both'` enable [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) (sessionless mint); `'supplied'` is **not** mintable via `/scope/v1/enter`.
482
+ - `ctx.mintScope({ via, subject })` mints a **scope-only** token (no user identity, `ctx.userId` undefined) from the `from`-row whose PK is `subject` — reading the role, resource id, sub-keys, and `subjectId` off that row.
483
+ - `subjectId` is the conferring row's primary key, populated on **both** proof paths — scope self-data on `ctx.scope.<kind>.subjectId`.
346
484
  - `q.scope('<kind>')` auto-stamps the column from `ctx.scope.<kind>.id` on insert.
347
485
  - Generated route: `POST /scope/v1/enter` (mounted only when `authz.scopes` is declared).
@@ -342,6 +342,14 @@ plugins, protects `POST /mcp`, emits RFC 8414 and RFC 9728 discovery, and
342
342
  accepts the provider's JWKS-signed access tokens in the standard Quickback
343
343
  auth middleware.
344
344
 
345
+ `audiences` (RFC 8707 resource indicators) is **unioned** with this worker's own
346
+ origin + `/mcp` — you list only the *other* resource servers you mint tokens for,
347
+ never losing your own. To run a **split authorization-server / resource-server**
348
+ topology (one SSO AS, many `/mcp` resource servers sharing one auth DB), a resource
349
+ server sets `oauth.issuerUrl` to the AS and `agents.mcp.requireAuth: true` — it then
350
+ verifies AS-issued bearers against the shared JWKS. See
351
+ [Agents → Split authorization server](/compiler/config/agents#split-authorization-server--resource-server-multi-app-sso).
352
+
345
353
  The legacy plugin object remains available for provider-specific options:
346
354
 
347
355
  ```ts
@@ -352,7 +360,7 @@ auth: defineAuth("better-auth", {
352
360
  loginPage: "/login", // path on ACCOUNT_URL — default
353
361
  allowDynamicClientRegistration: true, // default
354
362
  allowUnauthenticatedClientRegistration: true, // default — MCP needs this
355
- validAudiences: ["https://api.example.com"], // optional — defaults to BETTER_AUTH_URL
363
+ validAudiences: ["https://crm.example.com/mcp"], // optional — unioned with this AS's own origin + /mcp
356
364
  scopes: ["openid", "profile", "email", "offline_access"],
357
365
  },
358
366
  },
@@ -7,6 +7,7 @@
7
7
  ```typescript
8
8
  // services/schedules/sweepDigests.ts
9
9
  import { defineSchedule } from "quickback";
10
+ import { runDigestSweep } from "../../features/comms/lib/digest-sweep";
10
11
 
11
12
  export default defineSchedule({
12
13
  name: "sweepDigests", // identifier + audit actor (system:cron-<name>)
@@ -20,6 +21,22 @@ export default defineSchedule({
20
21
 
21
22
  One file per schedule under `services/schedules/*.ts`. Files prefixed with `_` are ignored. `name` must be a valid camelCase identifier (it's used as a generated symbol and the audit actor).
22
23
 
24
+ ## Importing feature code
25
+
26
+ Schedule files live at `quickback/services/schedules/<name>.ts`, so imports are relative to **that** location. To reach a feature table, a feature `lib/` helper, or `db/`, climb up to the `quickback/` root first (`../../`):
27
+
28
+ ```typescript
29
+ // quickback/services/schedules/bookingReminders.ts
30
+ import { bookings } from "../../features/crm/bookings"; // a feature table
31
+ import { generateIcsInvite } from "../../features/crm/lib/ics-generate"; // a feature lib/ helper
32
+ import { runDigestSweep } from "../../lib/digest-sweep"; // a shared lib/ helper
33
+ ```
34
+
35
+ Two `../` — up from `services/schedules/` to `quickback/`, then down into `features/` (or `lib/`, `db/`). The compiler relocates the handler into the generated `src/lib/schedules.ts` and **rewrites these paths to resolve from there automatically** — you always write them relative to your own source file, exactly as your editor resolves them.
36
+
37
+ > A single `../features/…` is the common mistake — from `services/schedules/` that resolves to `services/features/…`, which doesn't exist (the compiler consumes `services/`; there is no `src/services/`). Use `../../features/…`.
38
+
39
+
23
40
  ## What the compiler emits
24
41
 
25
42
  1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.47.11",
3
+ "version": "0.47.13",
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",
@@ -56,6 +56,52 @@ Three concept files do most of the work:
56
56
 
57
57
  ---
58
58
 
59
+ ## What `quickback compile` regenerates (and what it never touches)
60
+
61
+ `quickback compile` is a **pure code generator**. It reads your `quickback/`
62
+ definitions, sends them to the compiler service, and writes output to disk. It does
63
+ **not** connect to, migrate, or read any database — that is a separate, explicit
64
+ deploy step.
65
+
66
+ Each compile rewrites two trees:
67
+
68
+ - **`src/`** — the entire generated worker (routes, middleware, auth, MCP server,
69
+ `env.d.ts`, etc.). Fully regenerated every run. Never hand-edit it; your changes
70
+ are overwritten — put custom code in `quickback/` (features, actions, hooks,
71
+ `quickback/lib/`) and recompile.
72
+ - **`quickback/drizzle/<db>/`** (`auth`, `features`, `webhooks`, `audit`, `files`) —
73
+ Drizzle migration `.sql` + meta snapshots. **Incremental**: the CLI loads your
74
+ existing committed meta and sends it along, and the compiler diffs it against the
75
+ current schema and emits only the migration(s) for what changed. With no prior
76
+ meta it emits fresh `CREATE TABLE`s; with meta, only the delta. **Commit
77
+ `quickback/drizzle/` to git** — it is the source of truth for "what schema the last
78
+ compile already knows about."
79
+
80
+ Compile does **not** apply migrations, touch D1/Neon, or mutate data.
81
+
82
+ ### How compile meets an already-migrated prod DB
83
+
84
+ Applying migrations is a distinct, **idempotent** step — `wrangler d1 migrations
85
+ apply <db> --remote` (the project's deploy script runs it for every DB before the
86
+ worker flip). D1's `d1_migrations` table records what's applied, so already-applied
87
+ migrations are no-ops and only pending ones run. The safe loop against a live prod
88
+ DB:
89
+
90
+ 1. Edit `quickback/` definitions.
91
+ 2. `quickback compile` → regenerates `src/` and **appends only the new migration(s)**
92
+ to `quickback/drizzle/` (diffed from your committed meta — it does not rewrite or
93
+ replay history).
94
+ 3. Deploy → apply pending migrations (no-op for any prod already has), **then**
95
+ `wrangler deploy` the worker, so schema moves ahead of or with the code.
96
+
97
+ Migrations are additive-only by convention, so a freshly compiled worker stays
98
+ compatible with the prod schema across the apply→deploy window. **Caveat:** if
99
+ `quickback/drizzle/` meta is not committed, the next compile can't see prior state
100
+ and regenerates full `CREATE TABLE`s — which then collide with the live DB. Keep the
101
+ meta in git.
102
+
103
+ ---
104
+
59
105
  ## The security model
60
106
 
61
107
  Every API request passes through four pillars (the "Definitions"):
@@ -2,6 +2,84 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Sessionless scope mint: `ctx.mintScope` + `subject: 'supplied' \| 'both'`
6
+
7
+ A scope can now be minted for a principal who has **no Better Auth account** — an
8
+ event attendee arriving by email + invite code, a kiosk/handout code, a partner
9
+ token. The action proves the relationship its own way and asks Quickback to mint
10
+ a disciplined scope token from the row it proved.
11
+
12
+ - **`authz.scopes.<kind>.roles.<role>.subject: 'user' \| 'supplied' \| 'both'`** (default `'user'`).
13
+ `'both'` makes the *same* `scope:event:attendee` reachable by a logged-in user
14
+ (via `/scope/v1/enter`) and a sessionless invite-holder (via `ctx.mintScope`) —
15
+ one firewall arm, one masking rule, both principals.
16
+ - **`ctx.mintScope({ via, subject })`** — hydrated on `ctx` in any action (including
17
+ PUBLIC) when a `supplied`/`both` role is declared. The action supplies only the
18
+ conferring row's **primary key**; Quickback reads the role, resource id,
19
+ sub-keys, and subject id **off that row** — never caller-asserted, so the role
20
+ can't be forged. Returns a **scope-only** JWT (no user identity): `ctx.userId`
21
+ stays undefined, so user/org/owner gates and the `AUTHENTICATED`/`USER`
22
+ pseudo-roles all fail closed; only `scope:<kind>:<role>` gates admit it.
23
+ - **`ctx.scope.<kind>.subjectId`** — a reserved claim carrying the proven subject
24
+ row's PK, populated on **both** proof paths. Scope an attendee's self-data
25
+ (travel, dietary, todos) with a single firewall arm
26
+ (`{ field: 'guestId', equals: 'ctx.scope.event.subjectId' }`) that serves both a
27
+ user-attendee and a sessionless one.
28
+ - **Realtime** — the ws-ticket authorizes a scope-only principal directly off its
29
+ proven `ctx.scope` claim, so accountless attendees join the same rooms with the
30
+ same scope role. The `where:` filter runs on the mint probe, so a cancelled row
31
+ confers nothing (revocation within one ≤180s mint cycle).
32
+
33
+ See [Scopes → Sessionless scope mint](/compiler/definitions/scopes#sessionless-scope-mint--ctxmintscope).
34
+
35
+ ### MCP OAuth: split authorization-server / resource-server (multi-app SSO)
36
+
37
+ You can now run one canonical authorization server with many resource servers (each
38
+ hosting its own `/mcp`) over a shared auth DB:
39
+
40
+ - A resource server that sets `agents.mcp.requireAuth` now emits the full OAuth
41
+ access-token **verification** path on its own — previously the JWKS-verify block
42
+ only emitted when the separate `auth.config.oauth.enabled` flag was set, so a
43
+ requireAuth-only resource server fell back to HMAC + session and 401'd every valid
44
+ externally-issued bearer.
45
+ - Point a resource server at an external AS with `auth.config.oauth.issuerUrl`; the
46
+ middleware verifies incoming bearers against the shared JWKS (`iss`/`aud`/`exp` +
47
+ live-session binding).
48
+ - `auth.config.oauth.audiences` (an array) registers federated resource-server
49
+ audiences on the AS (RFC 8707). It now **unions** with the AS's own origin instead
50
+ of replacing it, so listing federated servers never drops the AS's own `/mcp`
51
+ audience. Also exposed on the plugin-form `oauthProvider.validAudiences`.
52
+
53
+ See [Agents → Split authorization server](/compiler/config/agents#split-authorization-server--resource-server-multi-app-sso).
54
+
55
+ ### MCP tools: callable path params + typed input schemas
56
+
57
+ An action mounted under a path that carries a parameter — a namespace prefix like
58
+ `/scope/:scopeId/...`, or any `path:` with `:params` — now produces a fully
59
+ callable MCP tool:
60
+
61
+ - The mounted route's path params are extracted into the tool's `inputSchema`
62
+ (and `_pathParams`), so the model has a field to supply each one. Previously
63
+ only record-based actions emitted a param (the hard-coded `id`); a standalone
64
+ or namespace path param was absent from the schema, the URL resolved with an
65
+ empty segment, and the action was uncallable over MCP.
66
+ - Standalone routes are stored in Hono colon form (`:scopeId`); the OpenAPI spec
67
+ key (and therefore the tool's `_path`) is now normalized to brace form
68
+ (`{scopeId}`) so the runtime's brace-only path interpolation can fill it.
69
+
70
+ Action `input` schemas also lower to richer JSON Schema instead of a phantom
71
+ empty `{}`: `z.coerce.*`, `z.literal`, unions of literals, and **nested
72
+ `z.object`** (child keys stay nested) now emit their real types, so the model —
73
+ and the OpenAPI spec — see the actual field shapes. See
74
+ [Agents → MCP tools](/compiler/config/agents).
75
+
76
+ ### Scaffold surfaces MCP/OAuth + secrets opt-ins
77
+
78
+ `quickback create` now seeds the generated `quickback.config.ts` with curated,
79
+ commented-out hints for the authenticated MCP server (`agents.mcp.requireAuth`), the
80
+ split-AS `oauth.issuerUrl`/`audiences`, and `bindings.secrets` — so these opt-ins are
81
+ discoverable in the config itself, not only in the docs.
82
+
5
83
  ### Custom secrets via `bindings.secrets`
6
84
 
7
85
  Declare a custom secret your feature/action code reads off `env` — name and
@@ -74,7 +74,7 @@ See [Interactive OAuth](#interactive-oauth-requireauth) below.
74
74
 
75
75
  ### Tools
76
76
 
77
- Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a flat JSON Schema combining path params, query params, and the request body.
77
+ Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a JSON Schema combining the request body with every parameter in the operation's **mounted** path — including the `:params` contributed by a namespace prefix (e.g. `/scope/:scopeId/...`), so a standalone or namespace action is always callable, not just record-based ones. Nested `z.object` inputs are preserved as nested objects rather than flattened, so the model sees each field's real type.
78
78
 
79
79
  `tools/call` re-enters the same Hono app via `app.request(...)` — so **every existing middleware runs exactly as it would for a direct REST call**: authentication, firewall, access control, guards, masking. No bypass.
80
80
 
@@ -138,6 +138,47 @@ The login and consent screens are served by your [Account SPA](/stack/account-ui
138
138
  > `requireAuth` removes anonymous public-tool access over `/mcp`. Use it when the MCP surface is meant for authenticated users; leave it off (the default) for servers that expose genuinely public tools.
139
139
 
140
140
 
141
+ ### Split authorization server / resource server (multi-app SSO)
142
+
143
+ By default a Worker is both the authorization server (AS) and the resource server — it issues *and* verifies its own OAuth tokens. For multi-app SSO you can run **one canonical AS** and **many resource servers** (each hosting its own `/mcp`) that share a single auth database (the same D1, e.g. via `crossSubDomainCookies` on a shared parent domain). Two config fields wire it up — both under `auth.config.oauth`:
144
+
145
+ **On each resource server** — point discovery at the external AS and verify its tokens:
146
+
147
+ ```ts
148
+ auth: {
149
+ config: {
150
+ oauth: {
151
+ enabled: true,
152
+ issuerUrl: "https://auth.example.com/auth/v1", // the canonical AS
153
+ },
154
+ },
155
+ },
156
+ agents: { mcp: { requireAuth: true } },
157
+ ```
158
+
159
+ `issuerUrl` makes `/.well-known/oauth-protected-resource` advertise the AS (not this Worker), and the generated middleware verifies incoming `Bearer` access tokens against the **shared JWKS** (`iss` must equal `issuerUrl`, `aud` must equal this Worker's `/mcp`, plus `exp` + live-session binding). Because the auth DB is shared, the resource server reads the AS's signing keys and the session row directly — no cross-Worker HTTP call.
160
+
161
+ **On the authorization server** — register the resource audiences it may mint tokens for ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707) resource indicators):
162
+
163
+ ```ts
164
+ auth: {
165
+ config: {
166
+ oauth: {
167
+ enabled: true,
168
+ audiences: [
169
+ "https://crm.example.com/mcp",
170
+ "https://billing.example.com/mcp",
171
+ ],
172
+ },
173
+ },
174
+ },
175
+ ```
176
+
177
+ `audiences` is an array — list every federated resource server. The AS's own origin (and `/mcp`) is always included automatically, so you only list the *other* servers; a token requested with `resource=https://crm.example.com/mcp` is then minted with that audience instead of rejected.
178
+
179
+ > `agents.mcp.requireAuth` is the documented switch for an authenticated MCP server, and it now emits the full OAuth token-verification path on its own — a resource server needs only `requireAuth` + `oauth.issuerUrl`, not a separate `oauth.enabled` step.
180
+
181
+
141
182
  ### Connecting clients
142
183
 
143
184
  **Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`: