@quickback-dev/cli 0.47.10 → 0.47.12

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.
@@ -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,74 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### MCP OAuth: split authorization-server / resource-server (multi-app SSO)
6
+
7
+ You can now run one canonical authorization server with many resource servers (each
8
+ hosting its own `/mcp`) over a shared auth DB:
9
+
10
+ - A resource server that sets `agents.mcp.requireAuth` now emits the full OAuth
11
+ access-token **verification** path on its own — previously the JWKS-verify block
12
+ only emitted when the separate `auth.config.oauth.enabled` flag was set, so a
13
+ requireAuth-only resource server fell back to HMAC + session and 401'd every valid
14
+ externally-issued bearer.
15
+ - Point a resource server at an external AS with `auth.config.oauth.issuerUrl`; the
16
+ middleware verifies incoming bearers against the shared JWKS (`iss`/`aud`/`exp` +
17
+ live-session binding).
18
+ - `auth.config.oauth.audiences` (an array) registers federated resource-server
19
+ audiences on the AS (RFC 8707). It now **unions** with the AS's own origin instead
20
+ of replacing it, so listing federated servers never drops the AS's own `/mcp`
21
+ audience. Also exposed on the plugin-form `oauthProvider.validAudiences`.
22
+
23
+ See [Agents → Split authorization server](/compiler/config/agents#split-authorization-server--resource-server-multi-app-sso).
24
+
25
+ ### Scaffold surfaces MCP/OAuth + secrets opt-ins
26
+
27
+ `quickback create` now seeds the generated `quickback.config.ts` with curated,
28
+ commented-out hints for the authenticated MCP server (`agents.mcp.requireAuth`), the
29
+ split-AS `oauth.issuerUrl`/`audiences`, and `bindings.secrets` — so these opt-ins are
30
+ discoverable in the config itself, not only in the docs.
31
+
32
+ ### Custom secrets via `bindings.secrets`
33
+
34
+ Declare a custom secret your feature/action code reads off `env` — name and
35
+ contract only, never the value:
36
+
37
+ ```ts
38
+ bindings: {
39
+ secrets: [
40
+ { name: "WEBHOOK_SIGNING_SECRET", description: "HMAC for webhook callbacks", required: true },
41
+ ],
42
+ }
43
+ ```
44
+
45
+ It's emitted into the generated `env.d.ts` `Env` interface so `env.<NAME>`
46
+ type-checks, and `required` secrets join the boot-time env guard — the worker
47
+ fails closed with `503 MISSING_ENV` if one is unset. The value is set
48
+ out-of-band (`wrangler secret put`); the schema rejects any inline value so a
49
+ real secret can never be committed. See
50
+ [Bindings → secrets](/compiler/config/bindings#secrets).
51
+
52
+ ### Auth: `resolve-email-context.ts` hook for per-recipient OTP context
53
+
54
+ Drop `quickback/hooks/resolve-email-context.ts` and the emailOTP send calls it
55
+ per recipient, spreading the returned object into your email templates — branded
56
+ palettes (organizer vs. attendee), plan tier, locale, etc. — without patching
57
+ generated output. Fail-open, with the Drizzle handle passed in. See
58
+ [Auth Hooks → Email context resolver](/stack/account-ui/hooks#email-context-resolver).
59
+
60
+ ### Codegen fixes
61
+
62
+ - **Schedules:** handler import paths are now rebased on relocation, so a cron
63
+ handler importing `../../features/...` resolves correctly from the generated
64
+ `src/lib/schedules.ts` instead of failing the worker build.
65
+ - **OAuth/MCP middleware:** the auth-schema tables are imported under aliased
66
+ names so a function-scoped `const session` can no longer shadow the `session`
67
+ table import — closes a temporal-dead-zone crash that silently 401'd every
68
+ OAuth/MCP bearer.
69
+ - **MCP route:** the large tool-data literal is split into a `mcp-tools.ts` data
70
+ module (suppressed) so it can't overrun `tsc`'s type-instantiation budget; the
71
+ `mcp.ts` route logic stays fully type-checked.
72
+
5
73
  ### Realtime: identity-gated Durable Object rooms (`roomIdEquals`)
6
74
 
7
75
  Per-user Durable Object entrypoints (gateway / presence / inbox) can now declare
@@ -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`:
@@ -1,6 +1,6 @@
1
1
  # Custom Bindings
2
2
 
3
- Quickback's compiler owns the D1/KV/R2/ASSETS/queue blocks it needs for its own features. Anything else your worker binds to — Cloudflare Email, an extra R2 bucket, a custom queue, a service binding, your own Durable Object, Workers AI, or non-secret `[vars]` — goes under the top-level `bindings` key:
3
+ Quickback's compiler owns the D1/KV/R2/ASSETS/queue blocks it needs for its own features. Anything else your worker binds to — Cloudflare Email, an extra R2 bucket, a custom queue, a service binding, your own Durable Object, Workers AI, non-secret `[vars]`, or a custom `secret` your code reads off `env` — goes under the top-level `bindings` key:
4
4
 
5
5
  ```ts
6
6
  import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback-dev/cli";
@@ -22,6 +22,9 @@ export default defineConfig({
22
22
  vars: {
23
23
  MAIL_SENDING_DOMAIN: "studio.example.com",
24
24
  },
25
+ secrets: [
26
+ { name: "MAIL_INBOUND_SECRET", description: "Verifies inbound mail webhooks", required: true },
27
+ ],
25
28
  },
26
29
  });
27
30
  ```
@@ -170,12 +173,48 @@ vars: {
170
173
  }
171
174
  ```
172
175
 
173
- Secrets do **not** go here. Use Wrangler's secret store instead:
176
+ Secrets do **not** go here. Declare them under [`secrets`](#secrets) (name only) and set the value with Wrangler's secret store:
174
177
 
175
178
  ```bash
176
179
  wrangler secret put MAIL_INBOUND_SECRET
177
180
  ```
178
181
 
182
+ ### `secrets`
183
+
184
+ Declares a custom secret your feature or action code reads off `env`. You record the **name and contract only** — the value is never stored in config, `wrangler.toml`, or git.
185
+
186
+ ```ts
187
+ secrets: [
188
+ {
189
+ name: "WEBHOOK_SIGNING_SECRET",
190
+ description: "HMAC secret for outbound webhook callbacks",
191
+ required: true,
192
+ },
193
+ { name: "PARTNER_API_KEY" }, // optional
194
+ ]
195
+ ```
196
+
197
+ Each declared secret:
198
+
199
+ - is emitted into the generated `env.d.ts` `Env` interface as an optional `WEBHOOK_SIGNING_SECRET?: string`, so `env.WEBHOOK_SIGNING_SECRET` type-checks in your code;
200
+ - when `required: true`, joins the **boot-time env guard** — the worker fails closed with a `503 MISSING_ENV` if the secret is unset, rather than 500ing on the first request that reads it (same posture as `BETTER_AUTH_SECRET`);
201
+ - surfaces its `description` and a `wrangler secret put <NAME>` hint in the generated type's JSDoc.
202
+
203
+ | Field | Type | |
204
+ | --- | --- | --- |
205
+ | `name` | `string` | Env var name. Letters, digits, underscores only — `SCREAMING_SNAKE_CASE` by convention. |
206
+ | `description` | `string?` | Human note shown in the JSDoc + secret-setup hint. |
207
+ | `required` | `boolean?` | Fail closed at boot if unset. Default `false`. |
208
+
209
+ Set the value out-of-band — it lands in Cloudflare's encrypted secret store:
210
+
211
+ ```bash
212
+ wrangler secret put WEBHOOK_SIGNING_SECRET
213
+ ```
214
+
215
+ > `secrets` records a **contract**, not a value. The schema rejects any inline value key, so a real secret can never be pasted into committed config. Use [`vars`](#vars) for non-secret values that are safe to commit.
216
+
217
+
179
218
  ### `ai`
180
219
 
181
220
  Emits a top-level `[ai]` block. Use this if you need Workers AI bound under a name different from Quickback's internal `AI`.
@@ -1,6 +1,6 @@
1
1
  # Auth Hooks
2
2
 
3
- Quickback discovers project-level auth hooks at `quickback/hooks/` and wires them into [Better Auth's `databaseHooks`](https://www.better-auth.com/docs/concepts/database#database-hooks). Use them for post-signup bootstrap, signup gating, and other lifecycle work.
3
+ Quickback discovers project-level auth hooks at `quickback/hooks/`. The `before-`/`after-` lifecycle hooks wire into [Better Auth's `databaseHooks`](https://www.better-auth.com/docs/concepts/database#database-hooks); the `resolve-*` hooks are trusted server resolvers called from generated middleware (OAuth) or the email send, not databaseHooks. Use them for post-signup bootstrap, signup gating, tenant resolution, and per-recipient email context.
4
4
 
5
5
  The classic case is multi-tenant: when `account.auth.organizations: true` is set, a freshly signed-up user has no `activeOrganizationId`, so every authenticated `/api/v1/*` returns `403 ORG_REQUIRED`. An `after-user-create` hook can auto-provision a personal workspace + member row so the next request just works.
6
6
 
@@ -13,6 +13,8 @@ quickback/
13
13
  before-user-create.ts
14
14
  after-session-create.ts
15
15
  after-admin-user-create.ts
16
+ resolve-oauth-context.ts
17
+ resolve-email-context.ts
16
18
  ```
17
19
 
18
20
  Each file has a single default export — an `async (entity, ctx) => ...` function. The filename determines which Better Auth event the hook fires on.
@@ -26,6 +28,7 @@ Each file has a single default export — an `async (entity, ctx) => ...` functi
26
28
  | `after-session-create.ts` | `databaseHooks.session.create.after` | `Session` | `void` |
27
29
  | `after-admin-user-create.ts` | `databaseHooks.user.create.after` (filtered) | `User` | `void` |
28
30
  | `resolve-oauth-context.ts` | OAuth bearer middleware | OAuth identity + session | Partial `AppContext` tenant fields |
31
+ | `resolve-email-context.ts` | emailOTP `sendVerificationOTP` | `{ email, type, name }` | Extra fields merged into the email template context |
29
32
 
30
33
  `after-admin-user-create.ts` is a **virtual event** — it wires into the same Better Auth `user.create.after` slot as the generic `after-user-create.ts`, but the compiler wraps the call in a runtime filter on the BA context path so it only fires when the row was created via the admin plugin's `POST /admin/create-user` endpoint. Use it for first-time-user provisioning (welcome email, default org assignment) without inspecting `_baCtx?.context?.path` by hand. The generic `after-user-create.ts` still runs for every signup, including admin-created ones.
31
34
 
@@ -53,6 +56,49 @@ The returned object is merged into the standard `AppContext`. The compiler
53
56
  always preserves the validated `authenticated`, `userId`, and `user` fields,
54
57
  so this hook cannot replace the OAuth identity.
55
58
 
59
+ ## Email context resolver
60
+
61
+ Better Auth routes OTP emails by **type** (`sign-in`, `email-verification`,
62
+ `forget-password`), not by audience, and a template only receives fixed
63
+ `appName` / `appUrl` / `supportEmail`. When you need **per-recipient** context —
64
+ a branded palette for organizers vs. attendees, a plan tier, a locale —
65
+ add `quickback/hooks/resolve-email-context.ts`. The emailOTP send calls it for
66
+ each recipient and **spreads the returned object into your email templates**.
67
+
68
+ ```ts title="quickback/hooks/resolve-email-context.ts"
69
+ export default async ({ email, type, name, db, schema, eq, and }) => {
70
+ // Is this recipient a member of any organization?
71
+ const [u] = await db.select({ id: schema.user.id })
72
+ .from(schema.user).where(eq(schema.user.email, email)).limit(1);
73
+ const isOrgMember = u
74
+ && (await db.select({ id: schema.member.id })
75
+ .from(schema.member).where(eq(schema.member.userId, u.id)).limit(1)).length > 0;
76
+
77
+ return { audience: isOrgMember ? "organizer" : "attendee" };
78
+ };
79
+ ```
80
+
81
+ Your [email template](/stack/auth/plugins/aws-ses#per-type-template-overrides) then reads the extra field:
82
+
83
+ ```ts title="quickback/email-templates/sign-in.ts"
84
+ export default ({ otp, appName, audience }) => ({
85
+ subject: `Your ${appName} code`,
86
+ html: renderOtp({ otp, theme: audience === "organizer" ? "eggplant" : "blue" }),
87
+ text: `Your code is ${otp}`,
88
+ });
89
+ ```
90
+
91
+ Notes:
92
+
93
+ - **Fail-open.** If the hook throws, the context falls back to `{}` and the OTP
94
+ still sends — a hook bug can never lock users out of sign-in.
95
+ - **Spread into user templates only.** The packaged default templates have a
96
+ fixed signature; convert a type to a [custom template](/stack/auth/plugins/aws-ses#per-type-template-overrides) to consume the extra context.
97
+ - `db`, `schema`, `eq`, and `and` are passed in (the same Drizzle handle Better
98
+ Auth uses) so you can look the recipient up without an import.
99
+ - This is **not** a Better Auth `databaseHook` — it's consumed only by the
100
+ emailOTP send, so it adds no signup/session latency.
101
+
56
102
  ## ctx shape
57
103
 
58
104
  Every hook receives `(entity, ctx)`:
@@ -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
  },