@quickback-dev/cli 0.47.12 → 0.47.14
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/docs/content.js +5 -5
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +110 -46
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +97 -0
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +18 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/skill/docs/changelog.md +89 -0
- package/dist/skill/docs/compiler/config/agents.md +1 -1
- package/dist/skill/docs/compiler/definitions/access.md +2 -0
- package/dist/skill/docs/compiler/definitions/scopes.md +249 -2
- package/dist/skill/docs/stack/schedules/index.md +17 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +89 -0
- package/src/skill/docs/compiler/config/agents.md +1 -1
- package/src/skill/docs/compiler/definitions/access.md +2 -0
- package/src/skill/docs/compiler/definitions/scopes.md +249 -2
- package/src/skill/docs/stack/schedules/index.md +17 -0
- package/dist/codex/AGENTS.md +0 -290
- 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/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/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 +0 -2
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.test.js +0 -130
- package/dist/lib/sweep-stale.test.js.map +0 -1
|
@@ -2,6 +2,74 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
### `acceptScope`: one namespaced handler for the user AND the sessionless principal
|
|
6
|
+
|
|
7
|
+
A project-level namespace can now **accept an already-minted scope claim as
|
|
8
|
+
proof of entry** — the inverse of `mintScope`. Set
|
|
9
|
+
**`authz.namespaces.<ns>.acceptScope: '<kind>'`** and the hoisted resolver gains
|
|
10
|
+
a fast-path: a scope-only principal (`ctx.scopePrincipal`, no `ctx.userId`)
|
|
11
|
+
carrying a verified `ctx.scope.<kind>` claim proves entry by that claim, without
|
|
12
|
+
a DB relationship probe. One `/event/:eventId/*` handler then serves **both** the
|
|
13
|
+
Better-Auth user and the sessionless invite-principal — retiring the parallel
|
|
14
|
+
PUBLIC `/attendee/*` twin.
|
|
15
|
+
|
|
16
|
+
- **Named-string only** — the kind is always explicit; a bare `true` is a type
|
|
17
|
+
error. Default absent → the resolver never admits a scope principal (fail-closed).
|
|
18
|
+
- **Two locks, compile-enforced** — `acceptScope` opts the namespace in, **and**
|
|
19
|
+
at least one relationship lane must confer a `<kind>` role declared
|
|
20
|
+
`subject: 'supplied' \| 'both'`. A `subject: 'user'` role emits no accept arm;
|
|
21
|
+
a kind whose every conferring lane is user-only is a **compile error**, not a
|
|
22
|
+
dead fast-path. The kind must be declared and its `requestField` must equal the
|
|
23
|
+
prefix's first `:param`.
|
|
24
|
+
- **Forging-safe** — the claim is verified (never caller-asserted), the kind is
|
|
25
|
+
read by name (not an any-key loop), the instance is pinned twice
|
|
26
|
+
(`entry.id === :param` in the gate + `eq(loads.pk, :param)` in hydration), and
|
|
27
|
+
each accept arm is one exact `(role, lane)` pair. New proof source, zero new
|
|
28
|
+
enforcement surface — firewall, masking, `access`, and scoped-db read the same
|
|
29
|
+
`ctx.scope` they read for a userId caller.
|
|
30
|
+
- **Composes with `mintScope`** — a userId caller still gets a rolling re-mint;
|
|
31
|
+
a scope principal's verified claim is preserved (not re-stamped) so its
|
|
32
|
+
`subjectId` / sub-keys survive.
|
|
33
|
+
- **Realtime shares the same acceptance** — the `ws-ticket` route now proves a
|
|
34
|
+
scope principal through the *same* emitter as the REST gate
|
|
35
|
+
(`emitScopeAcceptance`), so the two surfaces can't drift. Bringing the ws-ticket
|
|
36
|
+
path onto it tightened it to the named-kind read + supplied-reachable role
|
|
37
|
+
filter, closing an any-kind cross-kind match. `q-events` ships a `vendor` scope
|
|
38
|
+
role (`subject: 'both'`) + logistics-only view demonstrating the sessionless
|
|
39
|
+
supplier end-to-end.
|
|
40
|
+
|
|
41
|
+
See [Scopes → `acceptScope`](/compiler/definitions/scopes#acceptscope--accept-an-incoming-scope-claim-as-proof-of-entry).
|
|
42
|
+
|
|
43
|
+
### Sessionless scope mint: `ctx.mintScope` + `subject: 'supplied' \| 'both'`
|
|
44
|
+
|
|
45
|
+
A scope can now be minted for a principal who has **no Better Auth account** — an
|
|
46
|
+
event attendee arriving by email + invite code, a kiosk/handout code, a partner
|
|
47
|
+
token. The action proves the relationship its own way and asks Quickback to mint
|
|
48
|
+
a disciplined scope token from the row it proved.
|
|
49
|
+
|
|
50
|
+
- **`authz.scopes.<kind>.roles.<role>.subject: 'user' \| 'supplied' \| 'both'`** (default `'user'`).
|
|
51
|
+
`'both'` makes the *same* `scope:event:attendee` reachable by a logged-in user
|
|
52
|
+
(via `/scope/v1/enter`) and a sessionless invite-holder (via `ctx.mintScope`) —
|
|
53
|
+
one firewall arm, one masking rule, both principals.
|
|
54
|
+
- **`ctx.mintScope({ via, subject })`** — hydrated on `ctx` in any action (including
|
|
55
|
+
PUBLIC) when a `supplied`/`both` role is declared. The action supplies only the
|
|
56
|
+
conferring row's **primary key**; Quickback reads the role, resource id,
|
|
57
|
+
sub-keys, and subject id **off that row** — never caller-asserted, so the role
|
|
58
|
+
can't be forged. Returns a **scope-only** JWT (no user identity): `ctx.userId`
|
|
59
|
+
stays undefined, so user/org/owner gates and the `AUTHENTICATED`/`USER`
|
|
60
|
+
pseudo-roles all fail closed; only `scope:<kind>:<role>` gates admit it.
|
|
61
|
+
- **`ctx.scope.<kind>.subjectId`** — a reserved claim carrying the proven subject
|
|
62
|
+
row's PK, populated on **both** proof paths. Scope an attendee's self-data
|
|
63
|
+
(travel, dietary, todos) with a single firewall arm
|
|
64
|
+
(`{ field: 'guestId', equals: 'ctx.scope.event.subjectId' }`) that serves both a
|
|
65
|
+
user-attendee and a sessionless one.
|
|
66
|
+
- **Realtime** — the ws-ticket authorizes a scope-only principal directly off its
|
|
67
|
+
proven `ctx.scope` claim, so accountless attendees join the same rooms with the
|
|
68
|
+
same scope role. The `where:` filter runs on the mint probe, so a cancelled row
|
|
69
|
+
confers nothing (revocation within one ≤180s mint cycle).
|
|
70
|
+
|
|
71
|
+
See [Scopes → Sessionless scope mint](/compiler/definitions/scopes#sessionless-scope-mint--ctxmintscope).
|
|
72
|
+
|
|
5
73
|
### MCP OAuth: split authorization-server / resource-server (multi-app SSO)
|
|
6
74
|
|
|
7
75
|
You can now run one canonical authorization server with many resource servers (each
|
|
@@ -22,6 +90,27 @@ hosting its own `/mcp`) over a shared auth DB:
|
|
|
22
90
|
|
|
23
91
|
See [Agents → Split authorization server](/compiler/config/agents#split-authorization-server--resource-server-multi-app-sso).
|
|
24
92
|
|
|
93
|
+
### MCP tools: callable path params + typed input schemas
|
|
94
|
+
|
|
95
|
+
An action mounted under a path that carries a parameter — a namespace prefix like
|
|
96
|
+
`/scope/:scopeId/...`, or any `path:` with `:params` — now produces a fully
|
|
97
|
+
callable MCP tool:
|
|
98
|
+
|
|
99
|
+
- The mounted route's path params are extracted into the tool's `inputSchema`
|
|
100
|
+
(and `_pathParams`), so the model has a field to supply each one. Previously
|
|
101
|
+
only record-based actions emitted a param (the hard-coded `id`); a standalone
|
|
102
|
+
or namespace path param was absent from the schema, the URL resolved with an
|
|
103
|
+
empty segment, and the action was uncallable over MCP.
|
|
104
|
+
- Standalone routes are stored in Hono colon form (`:scopeId`); the OpenAPI spec
|
|
105
|
+
key (and therefore the tool's `_path`) is now normalized to brace form
|
|
106
|
+
(`{scopeId}`) so the runtime's brace-only path interpolation can fill it.
|
|
107
|
+
|
|
108
|
+
Action `input` schemas also lower to richer JSON Schema instead of a phantom
|
|
109
|
+
empty `{}`: `z.coerce.*`, `z.literal`, unions of literals, and **nested
|
|
110
|
+
`z.object`** (child keys stay nested) now emit their real types, so the model —
|
|
111
|
+
and the OpenAPI spec — see the actual field shapes. See
|
|
112
|
+
[Agents → MCP tools](/compiler/config/agents).
|
|
113
|
+
|
|
25
114
|
### Scaffold surfaces MCP/OAuth + secrets opt-ins
|
|
26
115
|
|
|
27
116
|
`quickback create` now seeds the generated `quickback.config.ts` with curated,
|
|
@@ -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
|
|
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
|
|
|
@@ -723,6 +723,8 @@ Both bulk-grant lanes piggyback on the namespace's relationship lane(s) for hydr
|
|
|
723
723
|
|
|
724
724
|
When a request misses every lane, the 403 deny payload lists every authorization path the caller could have taken — relationship names, role names, and `"team-membership"` for `{ team: true }` lanes — so a developer debugging an unexpected 403 sees the full surface they need to satisfy.
|
|
725
725
|
|
|
726
|
+
A namespace can also fold the scope machinery into this same gate: `mintScope: true` **mints** a scope token on a matched userId lane, and `acceptScope: '<kind>'` **accepts** an already-minted scope claim as proof of entry — one handler under the prefix serves both a Better-Auth user and a sessionless scope principal. See [Scopes → `acceptScope`](/compiler/definitions/scopes#acceptscope--accept-an-incoming-scope-claim-as-proof-of-entry).
|
|
727
|
+
|
|
726
728
|
### Discovery is path-prefix-only
|
|
727
729
|
|
|
728
730
|
Actions opt in by matching `path:` against a declared namespace prefix. There's no `namespace: 'foo'` field on `defineAction` — the path string is the discoverable surface, consistent with how `path:` already determines an action's URL.
|
|
@@ -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,240 @@ 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
|
+
## `acceptScope` — accept an incoming scope claim as proof of entry
|
|
321
|
+
|
|
322
|
+
`mintScope` is the resolver *minting* a scope claim after a `ctx.userId` lane
|
|
323
|
+
matches. **`acceptScope: '<kind>'` is the inverse: it lets the same resolver
|
|
324
|
+
*accept* an already-minted `ctx.scope.<kind>` claim as its own proof** — so one
|
|
325
|
+
`/event/:eventId/*` handler serves **both** the Better-Auth user (userId
|
|
326
|
+
relationship probe) **and** the sessionless scope principal (verified scope
|
|
327
|
+
JWT, no account). It's the exact fast-path the realtime
|
|
328
|
+
[ws-ticket](/stack/realtime/durable-objects) already has, ported to REST.
|
|
329
|
+
|
|
330
|
+
Without it, every scope-principal-facing namespaced action needs a **parallel
|
|
331
|
+
PUBLIC twin** (a separate handler with a hand-rolled `requireScope` check and
|
|
332
|
+
raw DB writes that bypass scoped-db) — double the surface, and "someone forgot
|
|
333
|
+
the twin" becomes a standing bug class. `acceptScope` retires the twin.
|
|
334
|
+
|
|
335
|
+
```typescript
|
|
336
|
+
// quickback.config.ts
|
|
337
|
+
authz: {
|
|
338
|
+
relationships: {
|
|
339
|
+
inspectorOf: {
|
|
340
|
+
from: 'site_inspectors',
|
|
341
|
+
subject: { column: 'inspectorUserId', equals: 'ctx.userId' },
|
|
342
|
+
resource: { column: 'locationId' },
|
|
343
|
+
where: { status: 'active' },
|
|
344
|
+
loads: 'locations',
|
|
345
|
+
exposeAs: 'location',
|
|
346
|
+
},
|
|
347
|
+
},
|
|
348
|
+
scopes: {
|
|
349
|
+
location: {
|
|
350
|
+
requestField: 'locationId',
|
|
351
|
+
roles: {
|
|
352
|
+
// supplied-reachable: a signed-in user AND a sessionless principal
|
|
353
|
+
// converge on ONE scope:location:inspector.
|
|
354
|
+
inspector: { via: 'inspectorOf', subKeys: ['inspectorId'], subject: 'both' },
|
|
355
|
+
},
|
|
356
|
+
},
|
|
357
|
+
},
|
|
358
|
+
namespaces: {
|
|
359
|
+
locationScope: {
|
|
360
|
+
prefix: '/location/:locationId',
|
|
361
|
+
via: ['inspectorOf'],
|
|
362
|
+
acceptScope: 'location', // ← honor an incoming ctx.scope.location claim
|
|
363
|
+
// mintScope: true, // ← compose freely: a userId caller also re-mints
|
|
364
|
+
},
|
|
365
|
+
},
|
|
366
|
+
}
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
A sessionless principal that already minted a token (via
|
|
370
|
+
[`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) or `/scope/v1/enter`)
|
|
371
|
+
then hits the namespaced action directly, no second round-trip:
|
|
372
|
+
|
|
373
|
+
```http
|
|
374
|
+
GET /api/v1/location/loc_42/summary
|
|
375
|
+
Authorization: Bearer <scope-only-jwt carrying scope.location = { id: 'loc_42', roles: ['inspector'] }>
|
|
376
|
+
|
|
377
|
+
200 OK
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
The resolver reads `ctx.scope.location`, confirms its `id` equals the `:locationId`
|
|
381
|
+
param, sees the `inspector` role a supplied-reachable lane confers, and admits
|
|
382
|
+
the request — no `ctx.userId`, no DB relationship probe. `ctx.location` is
|
|
383
|
+
hydrated through its own firewall exactly as it is for the userId caller.
|
|
384
|
+
|
|
385
|
+
### Two locks (both required, fail-closed)
|
|
386
|
+
|
|
387
|
+
`acceptScope` is **named-string only** — always the explicit kind, never a bare
|
|
388
|
+
`true` (there's no inference from the `:param`). Default absent → the resolver
|
|
389
|
+
**never** admits a scope principal (unchanged behavior). Beyond naming the kind,
|
|
390
|
+
the compiler enforces a second lock:
|
|
391
|
+
|
|
392
|
+
1. **`acceptScope: '<kind>'`** opts *this namespace's* REST surface in, **and**
|
|
393
|
+
2. at least one relationship lane of the namespace confers a `<kind>` role
|
|
394
|
+
declared **`subject: 'supplied' | 'both'`** (supplied-reachable).
|
|
395
|
+
|
|
396
|
+
A `subject: 'user'` role can be *minted* or *refreshed* by the namespace but can
|
|
397
|
+
**never be accepted** from a token — a user-only role must be proven by a live
|
|
398
|
+
`ctx.userId` probe. If `acceptScope` names a kind whose every conferring lane is
|
|
399
|
+
`subject: 'user'`, the **compiler errors** rather than emit a dead fast-path.
|
|
400
|
+
The compiler also checks the kind is declared and its `requestField` equals the
|
|
401
|
+
prefix's first `:param`.
|
|
402
|
+
|
|
403
|
+
### Forging safety
|
|
404
|
+
|
|
405
|
+
A scope principal can't use `acceptScope` to reach anything its token doesn't
|
|
406
|
+
already authorize:
|
|
407
|
+
|
|
408
|
+
- **The claim is verified, not asserted** — `ctx.scope` is populated only from a
|
|
409
|
+
JWT the auth middleware verified; the action can't write it.
|
|
410
|
+
- **Named kind, not any-kind** — the fast-path reads `ctx.scope['<kind>']` for
|
|
411
|
+
the declared kind (stricter than the ws-ticket's any-key loop); a colliding
|
|
412
|
+
foreign-kind id can't open the gate.
|
|
413
|
+
- **Instance pinned twice** — `entry.id === :param` in the gate, *and*
|
|
414
|
+
`eq(loads.pk, :param)` in hydration. The principal enters exactly the instance
|
|
415
|
+
its claim proved.
|
|
416
|
+
- **Role → lane is exact and supplied-restricted** — each accept arm is one
|
|
417
|
+
`(role, lane)` pair with `subject !== 'user'`; an `inspector` claim matches
|
|
418
|
+
`inspectorOf`, never a sibling lane.
|
|
419
|
+
- **No new enforcement surface** — firewall, masking, `access` arms, and
|
|
420
|
+
scoped-db all read the same `ctx.scope` / `ctx.activeOrgId` they read for a
|
|
421
|
+
userId caller. New proof source, zero new enforcement surface.
|
|
422
|
+
|
|
423
|
+
The tenant (`ctx.activeOrgId`) is sourced from the pinned-loaded resource
|
|
424
|
+
(`ctx.<exposeAs>.organizationId`) — parity with the userId caller, not a new
|
|
425
|
+
grant. Fine-grained "own rows only" stays the resource author's job via a
|
|
426
|
+
firewall arm on `ctx.scope.<kind>.subjectId`, the **same** arm that already
|
|
427
|
+
serves the userId principal.
|
|
428
|
+
|
|
429
|
+
## Sessionless scope mint — `ctx.mintScope`
|
|
430
|
+
|
|
431
|
+
`POST /scope/v1/enter` and the namespace resolver both prove the relationship by
|
|
432
|
+
**`ctx.userId`** — so they require a Better Auth account. But a legitimate
|
|
433
|
+
principal often has none: an **event attendee who arrives by email + invite
|
|
434
|
+
code**, holding an opaque session token you validate yourself, who must never
|
|
435
|
+
get a global account. The shape is general — magic links, kiosk/handout codes,
|
|
436
|
+
partner-issued API keys, expiring share links that need row-level scope.
|
|
437
|
+
|
|
438
|
+
For these, prove the relationship **your own way** inside an action, then ask
|
|
439
|
+
Quickback to mint a disciplined scope token from the row you proved.
|
|
440
|
+
|
|
441
|
+
### 1. Opt the role into supplied-subject proof
|
|
442
|
+
|
|
443
|
+
Add `subject` to the scope role (default `'user'`):
|
|
444
|
+
|
|
445
|
+
```typescript
|
|
446
|
+
authz: {
|
|
447
|
+
scopes: {
|
|
448
|
+
event: {
|
|
449
|
+
requestField: 'eventId',
|
|
450
|
+
roles: {
|
|
451
|
+
// 'both' → the SAME scope:event:attendee for a logged-in user
|
|
452
|
+
// (via /enter) AND a sessionless invite-holder (via ctx.mintScope).
|
|
453
|
+
attendee: { via: 'attendeeOf', subKeys: ['guestId'], subject: 'both' },
|
|
454
|
+
},
|
|
455
|
+
},
|
|
456
|
+
},
|
|
457
|
+
}
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
- **`'user'`** (default) — `/scope/v1/enter` only, proven by `subject.column = ctx.userId`. Unchanged.
|
|
461
|
+
- **`'supplied'`** — sessionless only. `ctx.mintScope` mints it; `/enter` won't (there's no user to probe).
|
|
462
|
+
- **`'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.
|
|
463
|
+
|
|
464
|
+
This opt-in is the single fail-closed switch: without `'supplied'` or `'both'`, no relationship is mintable by a supplied id.
|
|
465
|
+
|
|
466
|
+
### 2. Mint from the proven row
|
|
467
|
+
|
|
468
|
+
`ctx.mintScope` is hydrated on `ctx` in **any action** when a `subject:
|
|
469
|
+
'supplied' | 'both'` role is declared (including **PUBLIC** actions — the
|
|
470
|
+
canonical caller has no token yet). The action proves the principal however it
|
|
471
|
+
likes, then hands Quickback **only the conferring row's primary key**:
|
|
472
|
+
|
|
473
|
+
```typescript
|
|
474
|
+
// features/events/actions/enterEvent.ts
|
|
475
|
+
export default defineAction({
|
|
476
|
+
path: '/enter-event',
|
|
477
|
+
method: 'POST',
|
|
478
|
+
input: z.object({ code: z.string() }),
|
|
479
|
+
access: { roles: ['PUBLIC'] }, // unauthenticated entry
|
|
480
|
+
async execute({ ctx, input }) {
|
|
481
|
+
const guestRowId = await validateInviteCode(ctx, input.code); // YOUR proof, YOUR table
|
|
482
|
+
const { token } = await ctx.mintScope({ via: 'attendeeOf', subject: guestRowId });
|
|
483
|
+
return { token }; // client sends it as `Authorization: Bearer …` thereafter
|
|
484
|
+
},
|
|
485
|
+
});
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
You assert **nothing** about the scope. Quickback re-reads the `attendeeOf` row
|
|
489
|
+
by primary key and takes the role, the resource id (`eventId`), the sub-keys,
|
|
490
|
+
and the subject id **off that row** — so a buggy or hostile action can't forge
|
|
491
|
+
`organizer`, can't pick a different event, and can't widen the slice. The only
|
|
492
|
+
thing delegated to you is *which row* — exactly the opaque-credential check that
|
|
493
|
+
has to be custom code.
|
|
494
|
+
|
|
495
|
+
| What you supply | What Quickback reads off the row |
|
|
496
|
+
|---|---|
|
|
497
|
+
| `via` (a declared `supplied`/`both` relationship) + `subject` (the `from`-row PK you proved) | the role, `id` (resource), sub-keys, and `subjectId` — none caller-asserted |
|
|
498
|
+
|
|
499
|
+
The `where:` filter runs on the mint probe exactly as at `/enter` — a cancelled
|
|
500
|
+
or pending row confers nothing, so flipping a guest's `status` revokes them
|
|
501
|
+
within one mint cycle (**≤180s**). Re-prove by calling `ctx.mintScope` again
|
|
502
|
+
(your own refresh endpoint does exactly that). The by-PK probe does **not** apply
|
|
503
|
+
the relationship's tenant firewall (a sessionless principal has no
|
|
504
|
+
`activeOrgId` yet — the proven row *is* what establishes scope), but matching by
|
|
505
|
+
primary key + the `where:` filter keeps it bounded and fail-closed.
|
|
506
|
+
|
|
507
|
+
### 3. The scope-only token
|
|
508
|
+
|
|
509
|
+
`ctx.mintScope` signs a **scope-only** JWT — it carries the `scope` claim and
|
|
510
|
+
nothing else. There is **no user identity**: the auth middleware builds a context
|
|
511
|
+
with **`ctx.userId` undefined**, so every user-, org-, and owner-gated path
|
|
512
|
+
**fails closed automatically** (an owner firewall compares against `undefined`
|
|
513
|
+
→ matches nothing; org-role gates see empty `ctx.roles`). The `AUTHENTICATED`
|
|
514
|
+
and `USER` pseudo-roles **exclude** a scope principal by design — it is
|
|
515
|
+
authenticated *as a scope*, not as "any signed-in user". Only
|
|
516
|
+
`scope:<kind>:<role>` gates and `ctx.scope.<kind>` firewall arms admit it.
|
|
517
|
+
|
|
518
|
+
Everything downstream — REST firewall, masking, scoped-role access, the realtime
|
|
519
|
+
ws-ticket — then treats the sessionless attendee **identically** to a
|
|
520
|
+
user-proven one. There is no new enforcement surface; the principal is just
|
|
521
|
+
`scope:event:attendee`.
|
|
522
|
+
|
|
523
|
+
### `subjectId` — scoping to the person, not just the instance
|
|
524
|
+
|
|
525
|
+
A user-proven scope scopes self-data (an attendee's travel, dietary, todos) by
|
|
526
|
+
`ctx.userId`. A sessionless attendee has no `ctx.userId`, so the **proven
|
|
527
|
+
subject's identity rides in the claim** as a reserved **`subjectId`** — the
|
|
528
|
+
conferring row's primary key:
|
|
529
|
+
|
|
530
|
+
```jsonc
|
|
531
|
+
"scope": { "event": { "id": "evt_123", "roles": ["attendee"], "subjectId": "gst_42" } }
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
Scope self-data on it with one firewall arm:
|
|
535
|
+
|
|
536
|
+
```typescript
|
|
537
|
+
{ field: 'guestId', equals: 'ctx.scope.event.subjectId' }
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
`subjectId` is populated on **both** proof paths — `/scope/v1/enter` projects
|
|
541
|
+
the matched row's PK too — so the arm above is **one arm that serves both** a
|
|
542
|
+
logged-in attendee and a sessionless one. (It is distinct from
|
|
543
|
+
`ctx.scope.event.id`, which is the *instance* — the event.)
|
|
544
|
+
|
|
545
|
+
### Realtime
|
|
546
|
+
|
|
547
|
+
A scope-only token authorizes the realtime
|
|
548
|
+
[ws-ticket](/stack/realtime/durable-objects) directly off its proven
|
|
549
|
+
`ctx.scope` claim — no `ctx.userId` re-probe. The sessionless attendee joins the
|
|
550
|
+
same per-event rooms (and per-attendee rooms keyed on `subjectId`) as a
|
|
551
|
+
user-attendee, carrying the same scope role on the ticket. So the REST gate and
|
|
552
|
+
the socket gate stay identical for accountless principals too.
|
|
553
|
+
|
|
318
554
|
## Revocation & TTL
|
|
319
555
|
|
|
320
556
|
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 +567,28 @@ So removing a guest/staff row takes effect within **cap + one TTL** for a client
|
|
|
331
567
|
|
|
332
568
|
```typescript
|
|
333
569
|
// AppContext (generated lib/types.ts)
|
|
334
|
-
ctx.scope?: Record<string, { id: string; roles?: string[]; [subKey: string]: string | string[] | undefined }>;
|
|
570
|
+
ctx.scope?: Record<string, { id: string; roles?: string[]; subjectId?: string; [subKey: string]: string | string[] | undefined }>;
|
|
335
571
|
|
|
336
572
|
// authz.scopes.<kind>
|
|
337
573
|
{
|
|
338
574
|
requestField: string; // body field carrying the instance id
|
|
339
|
-
roles: Record<string, {
|
|
575
|
+
roles: Record<string, {
|
|
576
|
+
via: string;
|
|
577
|
+
subKeys?: string[]; // 'col' → eq, 'col[]' → inArray
|
|
578
|
+
subject?: 'user' | 'supplied' | 'both'; // who selects the conferring row (default 'user')
|
|
579
|
+
}>;
|
|
340
580
|
}
|
|
581
|
+
|
|
582
|
+
// ctx.mintScope — present in actions when a `subject: 'supplied' | 'both'` role is declared
|
|
583
|
+
ctx.mintScope(opts: { via: string; subject: string; setAuthToken?: boolean }):
|
|
584
|
+
Promise<{ token: string; scope: { id: string; roles: string[]; subjectId?: string } }>;
|
|
341
585
|
```
|
|
342
586
|
|
|
343
587
|
- `requestField` must equal every role-relationship's `resource.column`.
|
|
344
588
|
- Each relationship's `from` table must exist and ship a generated firewall (it can't be `exception`).
|
|
345
589
|
- A `subKeys` entry ending in `[]` is **set-valued** (lowers to `inArray`, minted as `string[]`); without the marker it's scalar (`eq`, minted as `string`).
|
|
590
|
+
- `subject` defaults to `'user'`. `'supplied'`/`'both'` enable [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) (sessionless mint); `'supplied'` is **not** mintable via `/scope/v1/enter`.
|
|
591
|
+
- `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.
|
|
592
|
+
- `subjectId` is the conferring row's primary key, populated on **both** proof paths — scope self-data on `ctx.scope.<kind>.subjectId`.
|
|
346
593
|
- `q.scope('<kind>')` auto-stamps the column from `ctx.scope.<kind>.id` on insert.
|
|
347
594
|
- Generated route: `POST /scope/v1/enter` (mounted only when `authz.scopes` is declared).
|
|
@@ -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.
|
|
3
|
+
"version": "0.47.14",
|
|
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",
|
|
@@ -2,6 +2,74 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
### `acceptScope`: one namespaced handler for the user AND the sessionless principal
|
|
6
|
+
|
|
7
|
+
A project-level namespace can now **accept an already-minted scope claim as
|
|
8
|
+
proof of entry** — the inverse of `mintScope`. Set
|
|
9
|
+
**`authz.namespaces.<ns>.acceptScope: '<kind>'`** and the hoisted resolver gains
|
|
10
|
+
a fast-path: a scope-only principal (`ctx.scopePrincipal`, no `ctx.userId`)
|
|
11
|
+
carrying a verified `ctx.scope.<kind>` claim proves entry by that claim, without
|
|
12
|
+
a DB relationship probe. One `/event/:eventId/*` handler then serves **both** the
|
|
13
|
+
Better-Auth user and the sessionless invite-principal — retiring the parallel
|
|
14
|
+
PUBLIC `/attendee/*` twin.
|
|
15
|
+
|
|
16
|
+
- **Named-string only** — the kind is always explicit; a bare `true` is a type
|
|
17
|
+
error. Default absent → the resolver never admits a scope principal (fail-closed).
|
|
18
|
+
- **Two locks, compile-enforced** — `acceptScope` opts the namespace in, **and**
|
|
19
|
+
at least one relationship lane must confer a `<kind>` role declared
|
|
20
|
+
`subject: 'supplied' \| 'both'`. A `subject: 'user'` role emits no accept arm;
|
|
21
|
+
a kind whose every conferring lane is user-only is a **compile error**, not a
|
|
22
|
+
dead fast-path. The kind must be declared and its `requestField` must equal the
|
|
23
|
+
prefix's first `:param`.
|
|
24
|
+
- **Forging-safe** — the claim is verified (never caller-asserted), the kind is
|
|
25
|
+
read by name (not an any-key loop), the instance is pinned twice
|
|
26
|
+
(`entry.id === :param` in the gate + `eq(loads.pk, :param)` in hydration), and
|
|
27
|
+
each accept arm is one exact `(role, lane)` pair. New proof source, zero new
|
|
28
|
+
enforcement surface — firewall, masking, `access`, and scoped-db read the same
|
|
29
|
+
`ctx.scope` they read for a userId caller.
|
|
30
|
+
- **Composes with `mintScope`** — a userId caller still gets a rolling re-mint;
|
|
31
|
+
a scope principal's verified claim is preserved (not re-stamped) so its
|
|
32
|
+
`subjectId` / sub-keys survive.
|
|
33
|
+
- **Realtime shares the same acceptance** — the `ws-ticket` route now proves a
|
|
34
|
+
scope principal through the *same* emitter as the REST gate
|
|
35
|
+
(`emitScopeAcceptance`), so the two surfaces can't drift. Bringing the ws-ticket
|
|
36
|
+
path onto it tightened it to the named-kind read + supplied-reachable role
|
|
37
|
+
filter, closing an any-kind cross-kind match. `q-events` ships a `vendor` scope
|
|
38
|
+
role (`subject: 'both'`) + logistics-only view demonstrating the sessionless
|
|
39
|
+
supplier end-to-end.
|
|
40
|
+
|
|
41
|
+
See [Scopes → `acceptScope`](/compiler/definitions/scopes#acceptscope--accept-an-incoming-scope-claim-as-proof-of-entry).
|
|
42
|
+
|
|
43
|
+
### Sessionless scope mint: `ctx.mintScope` + `subject: 'supplied' \| 'both'`
|
|
44
|
+
|
|
45
|
+
A scope can now be minted for a principal who has **no Better Auth account** — an
|
|
46
|
+
event attendee arriving by email + invite code, a kiosk/handout code, a partner
|
|
47
|
+
token. The action proves the relationship its own way and asks Quickback to mint
|
|
48
|
+
a disciplined scope token from the row it proved.
|
|
49
|
+
|
|
50
|
+
- **`authz.scopes.<kind>.roles.<role>.subject: 'user' \| 'supplied' \| 'both'`** (default `'user'`).
|
|
51
|
+
`'both'` makes the *same* `scope:event:attendee` reachable by a logged-in user
|
|
52
|
+
(via `/scope/v1/enter`) and a sessionless invite-holder (via `ctx.mintScope`) —
|
|
53
|
+
one firewall arm, one masking rule, both principals.
|
|
54
|
+
- **`ctx.mintScope({ via, subject })`** — hydrated on `ctx` in any action (including
|
|
55
|
+
PUBLIC) when a `supplied`/`both` role is declared. The action supplies only the
|
|
56
|
+
conferring row's **primary key**; Quickback reads the role, resource id,
|
|
57
|
+
sub-keys, and subject id **off that row** — never caller-asserted, so the role
|
|
58
|
+
can't be forged. Returns a **scope-only** JWT (no user identity): `ctx.userId`
|
|
59
|
+
stays undefined, so user/org/owner gates and the `AUTHENTICATED`/`USER`
|
|
60
|
+
pseudo-roles all fail closed; only `scope:<kind>:<role>` gates admit it.
|
|
61
|
+
- **`ctx.scope.<kind>.subjectId`** — a reserved claim carrying the proven subject
|
|
62
|
+
row's PK, populated on **both** proof paths. Scope an attendee's self-data
|
|
63
|
+
(travel, dietary, todos) with a single firewall arm
|
|
64
|
+
(`{ field: 'guestId', equals: 'ctx.scope.event.subjectId' }`) that serves both a
|
|
65
|
+
user-attendee and a sessionless one.
|
|
66
|
+
- **Realtime** — the ws-ticket authorizes a scope-only principal directly off its
|
|
67
|
+
proven `ctx.scope` claim, so accountless attendees join the same rooms with the
|
|
68
|
+
same scope role. The `where:` filter runs on the mint probe, so a cancelled row
|
|
69
|
+
confers nothing (revocation within one ≤180s mint cycle).
|
|
70
|
+
|
|
71
|
+
See [Scopes → Sessionless scope mint](/compiler/definitions/scopes#sessionless-scope-mint--ctxmintscope).
|
|
72
|
+
|
|
5
73
|
### MCP OAuth: split authorization-server / resource-server (multi-app SSO)
|
|
6
74
|
|
|
7
75
|
You can now run one canonical authorization server with many resource servers (each
|
|
@@ -22,6 +90,27 @@ hosting its own `/mcp`) over a shared auth DB:
|
|
|
22
90
|
|
|
23
91
|
See [Agents → Split authorization server](/compiler/config/agents#split-authorization-server--resource-server-multi-app-sso).
|
|
24
92
|
|
|
93
|
+
### MCP tools: callable path params + typed input schemas
|
|
94
|
+
|
|
95
|
+
An action mounted under a path that carries a parameter — a namespace prefix like
|
|
96
|
+
`/scope/:scopeId/...`, or any `path:` with `:params` — now produces a fully
|
|
97
|
+
callable MCP tool:
|
|
98
|
+
|
|
99
|
+
- The mounted route's path params are extracted into the tool's `inputSchema`
|
|
100
|
+
(and `_pathParams`), so the model has a field to supply each one. Previously
|
|
101
|
+
only record-based actions emitted a param (the hard-coded `id`); a standalone
|
|
102
|
+
or namespace path param was absent from the schema, the URL resolved with an
|
|
103
|
+
empty segment, and the action was uncallable over MCP.
|
|
104
|
+
- Standalone routes are stored in Hono colon form (`:scopeId`); the OpenAPI spec
|
|
105
|
+
key (and therefore the tool's `_path`) is now normalized to brace form
|
|
106
|
+
(`{scopeId}`) so the runtime's brace-only path interpolation can fill it.
|
|
107
|
+
|
|
108
|
+
Action `input` schemas also lower to richer JSON Schema instead of a phantom
|
|
109
|
+
empty `{}`: `z.coerce.*`, `z.literal`, unions of literals, and **nested
|
|
110
|
+
`z.object`** (child keys stay nested) now emit their real types, so the model —
|
|
111
|
+
and the OpenAPI spec — see the actual field shapes. See
|
|
112
|
+
[Agents → MCP tools](/compiler/config/agents).
|
|
113
|
+
|
|
25
114
|
### Scaffold surfaces MCP/OAuth + secrets opt-ins
|
|
26
115
|
|
|
27
116
|
`quickback create` now seeds the generated `quickback.config.ts` with curated,
|
|
@@ -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
|
|
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
|
|
|
@@ -723,6 +723,8 @@ Both bulk-grant lanes piggyback on the namespace's relationship lane(s) for hydr
|
|
|
723
723
|
|
|
724
724
|
When a request misses every lane, the 403 deny payload lists every authorization path the caller could have taken — relationship names, role names, and `"team-membership"` for `{ team: true }` lanes — so a developer debugging an unexpected 403 sees the full surface they need to satisfy.
|
|
725
725
|
|
|
726
|
+
A namespace can also fold the scope machinery into this same gate: `mintScope: true` **mints** a scope token on a matched userId lane, and `acceptScope: '<kind>'` **accepts** an already-minted scope claim as proof of entry — one handler under the prefix serves both a Better-Auth user and a sessionless scope principal. See [Scopes → `acceptScope`](/compiler/definitions/scopes#acceptscope--accept-an-incoming-scope-claim-as-proof-of-entry).
|
|
727
|
+
|
|
726
728
|
### Discovery is path-prefix-only
|
|
727
729
|
|
|
728
730
|
Actions opt in by matching `path:` against a declared namespace prefix. There's no `namespace: 'foo'` field on `defineAction` — the path string is the discoverable surface, consistent with how `path:` already determines an action's URL.
|