@quickback-dev/cli 0.39.1 → 0.40.2

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.
@@ -3,7 +3,7 @@
3
3
  export const DOCS = {
4
4
  "changelog": {
5
5
  "title": "Changelog",
6
- "content": "## v0.39.0 — June 2, 2026\n\nMedia and large-binary uploads are now first-class. Instead of streaming file\nbytes through your Worker — which hits the request-body cap and burns Worker\nCPU/duration — an action mints a short-lived **presigned URL** and the client\nuploads the bytes **directly to R2**. The Worker only signs; it never sits in\nthe data path. This is the supported way to author image/video/document upload\nendpoints, and it survives every `quickback compile` with no generated-file\npatching.\n\nRequires R2 file storage (`defineFileStorage(\"cloudflare-r2\", …)`).\n\n### `ctx.storage` — sign uploads from any action\n\nWhen R2 file storage is configured, every `defineAction` execute receives a\ntyped `storage` signer. Your action runs all the usual security layers (auth,\nroles, org/relationship scope), computes a tenant-scoped key, hands the client\nan upload URL, and stores the key in **your own table** — no separate metadata\nsystem required:\n\n```ts\nexport default defineAction({\n path: \"/event/:eventId/media/upload-file-binary\",\n method: \"POST\",\n input: z.object({ filename: z.string(), contentType: z.string() }),\n access: { roles: [\"admin\", \"member\", \"scope:event:attendee\"] },\n async execute({ input, ctx, c, db, storage }) {\n const eventId = c.req.param(\"eventId\");\n const key = `org/${ctx.activeOrgId}/event/${eventId}/${crypto.randomUUID()}-${input.filename}`;\n const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });\n await db.insert(images).values({ key, eventId });\n return { uploadUrl: upload.url, key, headers: upload.headers, expiresAt: upload.expiresAt };\n },\n});\n```\n\n`storage` exposes `signPutUrl(key, { contentType?, expiresIn? })` (returns\n`{ url, method, headers, key, expiresAt }`) and\n`signGetUrl(key, { expiresIn?, downloadFilename? })` (returns a presigned GET\nURL). Construction is zero-cost — actions that never touch `storage` pay\nnothing.\n\n### Managed presign + confirm endpoints\n\nFor the zero-config path, the built-in storage API now exposes a presigned\nupload alongside the existing through-Worker upload:\n\n- `POST /storage/v1/presign/:bucket/*path` — runs the bucket's auth/role/scope\n checks, validates the declared `contentType` + `size` against bucket limits,\n records a pending object row, and returns `{ id, key, uploadUrl, method,\n headers, expiresAt }`\n- `POST /storage/v1/confirm/:bucket/*path` — reconciles the recorded size and\n etag against what actually landed in R2 (`HEAD`)\n\n### Setup: R2 API token\n\nPresigning uses R2's S3 API, which needs an **R2 API token** — the Workers R2\nbinding cannot presign on its own. Set three secrets:\n\n```bash\nwrangler secret put R2_ACCOUNT_ID\nwrangler secret put R2_ACCESS_KEY_ID\nwrangler secret put R2_SECRET_ACCESS_KEY\n```\n\n`aws4fetch` is added to the generated `package.json` automatically, and the R2\npresign secrets are added to the generated `Env` type. If you pass `contentType`\nto `signPutUrl`, the client must replay exactly that `Content-Type` header on\nthe `PUT`.\n\n### No raw-body action flag\n\nStreaming a raw binary request body through an action is intentionally **not**\nsupported. Presigning delivers the same result — large files, no body cap —\nwithout poking a hole in the body-parsing layer, so JSON actions and the ~1 MiB\nJSON cap stay intact for every other route.\n\n### Storage routes hardened\n\nEnabling R2 file storage previously exposed several latent type errors in the\ngenerated `/storage/v1/*` routes (dead references from an old multipart\nrefactor, JSON-string role columns treated as arrays, a few undefined\nvariables). The full storage surface now type-checks cleanly when file storage\nis configured.\n\n## v0.38.1 — May 26, 2026\n\nCustom action handlers get the same typed ergonomics as generated CRUD paths:\ntyped Cloudflare bindings on `env`, a first-class typed `realtime` helper when\nrealtime is enabled, and no more `createRealtime(...)` boilerplate inside every\naction just to emit an explicit broadcast.\n\n### Neon compile output and local recompile state are now stable\n\nThe Neon + Cloudflare path now emits a correct runtime/output surface instead\nof leaking SQLite-era state.\n\n- `wrangler.toml` no longer emits a stray `[[d1_databases]]` block for Neon\n projects\n- repeated local Neon compiles now upload and sync the root PostgreSQL Drizzle\n state correctly, so `drizzle-kit` can report \"No schema changes\" instead of\n regenerating duplicate `0000_*.sql` files\n- stale root Drizzle migrations from earlier bad compiles are pruned during the\n compile/sync path\n\n### Shared-target namespace hydration now works for bulk-grant lanes\n\nBulk-grant namespace callers (`{ roles: [...] }`, `{ team: true }`) now inherit\nthe namespace's shared hydration target when every relationship lane points at\nthe same resource load shape.\n\nThat fixes the case where a namespace like:\n\n```ts\nvia: ['attendeeOf', 'organizerOf', { roles: ['admin', 'owner'] }]\n```\n\nwould authorize an org admin through the bulk lane but leave `ctx.event`\nundefined, even though the sibling relationship lanes all hydrated the same\n`events` row.\n\nRuntime behavior is now split cleanly:\n\n- **Shared target** — if all hydrating lanes share the same `loads`,\n `exposeAs`, and resource key, hydration runs unconditionally after the gate\n passes, so bulk callers get the same `ctx.<exposeAs>` as relationship callers\n- **Distinct targets** — if lanes hydrate different tables / keys / ctx slots,\n hydration stays per-matched-lane to avoid cross-table false 404s\n\nStandalone action typing now matches that runtime behavior too: shared-target\nhydration remains non-optional, while distinct-target multi-lane hydration stays\noptional.\n\n### Platform role split: `appmanager` for control-plane, `sysadmin` for cross-tenant\n\nQuickback no longer treats `user.role === \"admin\"` as the platform-wide role.\nThe control-plane role is now `user.role === \"appmanager\"` (CMS shell, Better\nAuth admin endpoints, support tooling), while `user.role === \"sysadmin\"`\nremains the only true cross-tenant data-plane tier.\n\nThis also retires the `ADMIN` pseudo-role. Any `roles: [\"ADMIN\"]` usage now\nfails the compile with migration guidance:\n\n- `userRole: [\"appmanager\"]` for platform control-plane access\n- `roles: [\"admin\"]` for org-membership admin access\n- `roles: [\"SYSADMIN\"]` for true cross-tenant access\n\nRuntime behavior now matches that split end-to-end:\n\n- Better Auth's admin plugin is generated with `adminRoles: [\"appmanager\", \"sysadmin\"]`\n- CMS / OpenAPI / auth-admin surfaces gate on `appmanager` (and admit\n `sysadmin` where appropriate)\n- unsafe cross-tenant actions and tenant-bypass helpers require `sysadmin` only\n\n### Typed `env` + injected `realtime` in action handlers\n\nThe generated `<feature>/.quickback/define-action.ts` helper now types action\n`env` from the project's runtime bindings surface instead of `any`, so custom\nbindings like R2 buckets, queues, Durable Objects, auth env vars, and split DB\nbindings no longer need `(env as any)` casts inside action handlers.\n\nWhen realtime is enabled in config, action handlers also receive a typed\n`realtime` helper directly in `execute(...)`. It exposes the same\n`insert/update/delete/broadcast` methods as `createRealtime(env)`, but without\nthe extra import or hand-rolled factory call in every custom action.\n\nThis is a DX-only change. The auto-broadcast boundary is unchanged: generated\nCRUD routes still broadcast automatically, while custom action writes still\nbroadcast explicitly.\n\n### `generateId: \"cuid\"` docs now reflect the split runtime/schema behavior\n\nQuickback's `cuid` strategy is now documented as the split path it actually is:\ncompiler-managed schema auto-injection keeps the `createId()` call site but may\nback it with a file-local `crypto.randomUUID()` polyfill, while import-capable\nruntime paths still emit real `createId()` usage.\n\nThat matters most for `compiler.injectId` and other schema-emission paths that\nrun in sandboxes where project `node_modules` are not visible. The generated\nschema can safely keep:\n\n```ts\nid: text(\"id\").primaryKey().$defaultFn(() => createId())\n```\n\nwhile satisfying the reference via:\n\n```ts\nconst createId = () => crypto.randomUUID();\n```\n\ninstead of importing `@paralleldrive/cuid2` inside the schema-generation\nenvironment.\n\n**Important nuance:** this is not a guarantee that every generated id is a true\ncuid2 string. Auto-injected schema paths may produce UUID-shaped strings\nthrough the polyfill, while runtime paths that can import helpers may still use\nreal `createId()`. If you need strict cuid2 shape everywhere, explicitly import\n`createId` from `@paralleldrive/cuid2` in the authored schema file; the\ncompiler preserves that import and skips the polyfill.\n\n## v0.38.0 — May 26, 2026\n\n**Per-matched-lane authorization** for multi-lane namespaces — across both the\nREST scope refresh/mint and the realtime ws-ticket. A namespace gated by several\n`via:` lanes (attendees *or* organizers *or* contractors *or* org admins) now\nconfers the scope role of **whichever lane the caller actually matched**, instead\nof suppressing the grant. This retires the v0.37.0 single-conferring-lane\nlimitation.\n\n### Scope refresh & `mintScope` — per matched lane\n\nA **multi-lane `via:`** now refreshes and mints the matched lane's role:\n`attendeeOf` → `scope.event.roles = ['attendee']`, `organizerOf` → `['organizer']`.\nThe resolver records which lane opened the gate (first-match-wins), so a caller\ncan only ever carry the role they proved this request. A **bulk-grant lane**\n(`{ roles: [...] }` / `{ team: true }`) still confers **no** scope role — it\nauthorizes via the caller's org role, with nothing to stamp. Previously any\nmulti-lane / bulk / mixed `via:` suppressed the stamp and mint entirely; that\nrestriction is lifted. See [Scopes](/compiler/definitions/scopes#mintscope-mint-the-scope-token-from-the-namespace-resolver).\n\n### Namespace-backed ws-ticket — realtime, per matched lane\n\n`realtime.wsTicket` accepts a **`namespace`** reference, so the\n`/broadcast/v1/ws-ticket` route authorizes through that namespace's full\nmulti-lane `via:` and issues a per-matched-lane WebSocket ticket — the socket\ngate and the REST gate stay identical, from a single source of truth.\n\n```typescript\nrealtime: {\n wsTicket: { namespace: \"eventScope\", requestField: \"eventId\", scopeTable: \"events\" },\n},\n```\n\nAn attendee gets an `attendee` ticket, an organizer an `organizer` ticket, and an\norg admin who reaches the room through the bulk lane now gets a ticket scoped to\ntheir org/membership roles — closing the gap where the single-`role` form `403`'d\na legitimate admin and left their realtime socket dead.\n\n**Tenant-bound, fail-closed.** Before minting, the route loads the `scopeTable`\nrow through *its own firewall*, so a ticket can only target a room whose resource\nresolves under the caller's tenant — an org-A admin requesting an org-B `eventId`\ngets `403`, never a cross-tenant socket. Because the room *is* the data (no\nfirewall sits between a ticket and a Durable Object room), the compiler **rejects\nat build time** a namespace-backed `wsTicket` whose `scopeTable` isn't\ntenant-scoped (`firewall: { exception: true }` or a literal-only firewall with no\norg/owner/team isolation). See\n[Realtime tickets](/stack/realtime/durable-objects#namespace-backed-tickets-per-matched-lane).\n\n## v0.37.0 — May 26, 2026\n\nThe **authz-as-compile-target** roadmap ships. Your authorization model —\nrelationships, named permissions, FK-traversal arrows, scope axes — compiles\ninto one normalized policy IR, lowers to SQL `WHERE` clauses / signed claims /\nguards, and is checked by a static analyzer before a single route is emitted.\nThis release lands milestones M0.1, M0.3, M1, M2, and M4, plus §5.3 namespace\nscope-minting.\n\n### Named permissions (`authz.permissions`) — M1\n\nA `via:` arm references **one** relationship. When the *same* grant rule recurs\nacross resources — \"organizer **or** confirmed attendee\" — name it **once**\nunder `authz.permissions` as a boolean expression and reference it everywhere\nwith a `{ permission }` firewall arm.\n\n```typescript\nauthz: {\n permissions: {\n 'event:view': { anyOf: ['organizerOf', 'attendeeOf'] },\n 'org:admin': { anyOf: [{ role: 'admin' }, { role: 'owner' }] },\n },\n}\n// then on a resource:\n// firewall: [ { field: 'eventId', permission: 'event:view' } ]\n```\n\n`anyOf` lowers to an OR of relationship subqueries, `allOf` to an AND, and a\n`{ permissionRef }` inlines another permission's arms — byte-identical to\nwriting the `via:` arms by hand. The full DSL (`anyOf` / `allOf` / `not`, bare\nstrings, and the object-leaf escape hatch) is accepted so configs stay\nforward-compatible; a firewall enforces the **SQL-pushable** subset (claim-site\nleaves like `{ role }` / `{ scopeRole }` and `not` over a SQL site are rejected\nat compile time — gate those on `access` instead). See\n[Permissions](/compiler/definitions/permissions).\n\n### FK-traversal arrows (`authz.arrows`) — M2\n\nAn **arrow** inherits authority across a foreign key: *\"you can see this row\nbecause you administer the organization it belongs to\"*, or *\"because you\ncontrol an ancestor in the tree.\"* Declare an FK hop, reference it from a\npermission as `{ arrowRef, permission }`, and it lowers to SQL.\n\n```typescript\nauthz: {\n arrows: {\n eventOrg: { from: 'event', fk: 'organizationId', to: 'organization' },\n folderTree: { from: 'folder', fk: 'parentId', to: 'folder', recursive: true },\n },\n permissions: {\n 'event:view': { anyOf: ['organizerOf', { arrowRef: 'eventOrg', permission: 'org:admin' }] },\n 'folder:read': { anyOf: [{ arrowRef: 'folderTree', permission: 'org:admin' }] },\n },\n}\n```\n\nA single hop lowers to an FK-hop subquery; a self-referential hop\n(`folder.parentId -> folder`) lowers to a **bounded `WITH RECURSIVE` CTE**\n(default depth 8, override per-arrow with `maxDepth` or per-permission with\n`permissionMaxDepth`). The seed and **every walked row** are re-constrained to\nthe caller's active-org claim, an absent claim fails closed (`1 = 0`), and the\nidentifiers are compile-time constants while the claim binds as a parameter —\nso an arrow is never an injection surface. An `unbounded: true` arrow with no\nclaim path is a hard compile error. Valid on both D1 and Neon. See\n[Arrows](/compiler/definitions/arrows).\n\n### Compile-time authz analyzer + diagnostics — M4\n\nThe compiler now projects your whole authorization model into a single policy\nIR and runs static checks over it, reporting on the existing\n**`[quickback:authz]`** console channel with stable, greppable codes:\n\n- `AUTHZ_EMPTY_PERMISSION` — a permission that can never be satisfied (e.g. `allOf(a, not(a))`).\n- `AUTHZ_SHADOWED_ARM` — an `anyOf` arm subsumed by a broader sibling.\n- `AUTHZ_UNREACHABLE_ROLE` / `AUTHZ_UNREACHABLE_VIEW` — dead scope config.\n- `AUTHZ_NOT_OVER_RESOURCE` — a `not` over a SQL site (the null-trap).\n- `AUTHZ_PUSHDOWN_COST` — an `info` report of each permission's subquery count and recursive-CTE depth.\n- `AUTHZ_CAPABILITY_CEILING` — **error** — a resource grants a `scope:<kind>:<role>` read beyond its `grants` profile.\n\nChecks are **warn-by-default, compile-continues** (so a new check never breaks\nan existing build on upgrade); set **`QUICKBACK_AUTHZ_STRICT=true`** to promote\nevery warning to a hard error. The analyzer is compile-time only — a defect in\na check downgrades to a single warning in the default path and can never take\ndown an otherwise-valid compile. See\n[Diagnostics](/compiler/definitions/diagnostics).\n\n### Aggregate-only views — M0.1\n\nA view can return a rollup and **nothing else** — no `data[]`, no per-row field\nselection — via `aggregateOnly: true`, with an optional `kMin` k-anonymity floor\nthat suppresses the aggregate below a threshold. This is what lets an F&B vendor\nread dietary **counts** for an event with zero attendee rows. See\n[Views](/compiler/definitions/views).\n\n### Scope leftovers — M0.3\n\nThe relationship-scope surface gains three pieces:\n\n- **Namespace scope-claim refresh** — a namespace gating `/event/:eventId/*` on a single conferring relationship lane refreshes `ctx.scope.<kind>` in memory for the request, so an attendee hitting an action under the prefix gets the scoped role stamped without a separate `/scope/v1/enter` round-trip.\n- **`q.scope()` autofill** — `q.scope('event')` auto-stamps a column from the verified scope claim (`ctx.scope.event.id`) on insert, the same way `q.scope('organization')` stamps the tenant column. Insert-only and null-safe; it adds no read-time `WHERE`.\n- **Set-valued sub-keys** — a `subKeys` entry ending in `[]` (e.g. `'shuttleId[]'`) projects **every** matched relationship row's value into the claim as a `string[]`, and the matching firewall arm is rewritten to an `inArray` row-slice (a driver covering multiple buses). An absent claim lowers to `inArray(col, [])` — a clean deny.\n\nSee [Scopes & capability grants](/compiler/definitions/scopes).\n\n### Namespace scope-minting (`mintScope`) — §5.3\n\nA namespace can now MINT a persisted scope JWT from its resolver. Set\n**`mintScope: true`** and, on a successful relationship probe, the resolver\nreturns a scope token via `set-auth-token` — so a native client hitting\n`/event/:eventId/*` carries the scoped role forward **without** calling\n`/scope/v1/enter`.\n\n```typescript\nauthz: {\n namespaces: {\n eventScope: { prefix: '/event/:eventId', via: ['attendeeOf'], mintScope: true },\n },\n}\n```\n\nThe mint fires **only** when `via:` confers exactly one scope role\nunambiguously (a single conferring relationship lane); a multi-lane,\nbulk-grant, or asymmetric `via:` **suppresses** the mint (fail-closed — those\ncallers use `/scope/v1/enter`). The token reuses the shared mint helper (TTL\nclamped to ≤180s, sibling scope kinds carried forward) and the mint is\n**best-effort** — a mint failure never fails the request, since the in-memory\nstamp already authorized it. Opt-in per namespace; defaults to `false`. See\n[Scopes — `mintScope`](/compiler/definitions/scopes#mintscope-mint-the-scope-token-from-the-namespace-resolver).\n\n> **Gotcha:** a namespace emits its resolver — and thus the refresh and the\n> mint — **only** when at least one *standalone* action's `path:` falls under\n> the prefix. A namespace containing only record-based actions (which mount\n> under their resource's CRUD routes, not the prefix) is **inert**. Add a\n> standalone action like `eventHome` at `/event/:eventId/home`. See\n> [Scopes — the resolver gotcha](/compiler/definitions/scopes#gotcha-a-namespace-only-emits-its-resolver-when-it-claims-a-standalone-action).\n\n## v0.36.3 — May 25, 2026\n\n### Fix: `/auth/v1/*` handler forwards `executionCtx` so OTP emails actually send\n\nThe generated `createAuth(env, cf?, executionCtx?)` schedules the fire-and-forget\nverification-OTP send through `executionCtx.waitUntil(...)` — Better Auth advises\n**not** awaiting the send so its latency doesn't leak into auth response timing.\nThat only works when `executionCtx` is passed. The composed Cloudflare worker\nindex emitted a **bare** `createAuth(c.env)` at the `app.all('/auth/v1/*')`\nhandler, so on Cloudflare the unawaited SES/SNS send was cancelled the moment the\nhandler returned — `send-verification-otp` returned 200 but no email went out.\n\nThe handler now threads `createAuth(c.env, c.req.raw.cf as any, c.executionCtx)`,\nmatching the action call-sites (`record-based`, `standalone`, `core/helpers`) and\nthe `getSession` call now passes the `cf` binding. (The earlier waitUntil fix had\nonly patched the legacy `providers/runtime` index emitter, not this composed one —\nthe two had drifted.) Recompile + redeploy to pick it up.\n\n## v0.36.2 — May 25, 2026\n\nTwo firewall fixes uncovered in a relationship-scoped (event-attendee) project:\nscoped reads stopped hiding rows behind a misclassified soft-delete column, and\nthe list route stopped rejecting org-optional callers before the firewall ran.\n\n### Fix: a firewall `isNull` predicate on a non-`deletedAt` column no longer globalizes as soft-delete\n\nThe scoped `db` wrapper used by actions enforces soft-delete by injecting\n`isNull(<col>)` into reads. It built its list of soft-delete columns by treating\n**any** firewall `{ field, isNull: true }` predicate as a project-wide soft-delete\nmarker — so an `isNull` predicate on a foreign-key column (e.g.\n`{ field: 'agendaItemId', isNull: true }`) was broadcast to **every** table that\nmerely had an `agendaItemId` column, rewriting scoped reads to\n`agenda_item_id IS NULL`. Real rows (non-null FK) became invisible, so an action\nthat read-before-write saw \"no row,\" attempted an insert, and 500'd on the\n`(agenda_item_id, guest_id)` unique constraint.\n\nOnly `deletedAt` — the column the compiler injects into every table — now enters\nthe project-global soft-delete list. A custom `isNull` predicate is still enforced\n**per-table** by that table's firewall (route layer); it is simply no longer\nbroadcast across the whole schema. This mirrors the v0.28 fix that made custom\nowner columns per-table rather than global.\n\n### Fix: list route no longer hard-requires an org when the firewall makes org optional\n\nThe generated CRUD **list** route emits an `ORG_REQUIRED` 400 (with a sysadmin\nescape) before the firewall runs. It fired whenever an org scope appeared\n**anywhere** in the firewall — including when org is just one arm of an `any:`\ngroup. So after the relationship-scope migration made a firewall org-optional\n(`any: [ { organizationId = ctx.activeOrgId }, { …via relationship } ]`), a\nplain-JWT caller with no `activeOrgId` (e.g. an event attendee scoped by\nrelationship) got an instant 400 — the org-optional firewall that would have\nscoped them correctly never even ran.\n\nThe gate now keys off org **mandatoriness** (`firewallRequiresOrg`): it fires\nonly when an org claim is genuinely required — a top-level (implicit-AND) or\n`all`-nested org predicate. When org is one arm of an `any:` group, the list\nroute skips the 400 and lets the null-safe firewall scope the caller: the org\narm drops when `activeOrgId` is absent, sibling arms (relationship/owner) bind,\nand `anyGuarded` denies (`1 = 0`) when every arm drops — so a no-org caller sees\nexactly what the declared policy grants, never an unbounded cross-tenant read.\n`?organizationId=` cross-tenant addressing and the sysadmin escape are unchanged,\nand a plain org-scoped resource (no `any:` group) keeps the `ORG_REQUIRED` gate\nbyte-for-byte. Write paths (create / put / batch) still require an org so new\nrows are always stamped with a tenant.\n\n## v0.36.1 — May 25, 2026\n\nRelationship-derived **scoped roles** — request-scoped authorization minted from\na verified relationship into a short-lived JWT.\n\n### `authz.scopes` — scoped roles via a relationship probe\n\nA new `authz.scopes` block turns a declared relationship into a request-scoped\nrole. Key the scope by a request field and back each role with a relationship:\n\n```ts\nauthz: {\n relationships: {\n attendeeOf: {\n from: 'guests',\n subject: { column: 'userId', equals: 'ctx.userId' },\n resource: { column: 'eventId' },\n where: { status: 'confirmed' },\n },\n },\n scopes: {\n event: {\n requestField: 'eventId',\n roles: { attendee: { via: 'attendeeOf' } }, // shorthand: attendee: 'attendeeOf'\n },\n },\n}\n```\n\nThe compiler emits a `/scope/v1/enter` route that probes the relationship for the\ncaller (\"is this user a confirmed guest of `eventId`?\") and, on success, mints a\nshort-lived JWT carrying the verified scope. The auth middleware reads that claim\ninto `ctx.scope.<kind>` (e.g. `ctx.scope.event`).\n\nScoped roles then work everywhere roles do — `read.access`, view access,\n`masking.show`, action access — as `scope:<kind>:<role>`, and the firewall can\nscope rows by the verified id:\n\n```ts\nread: { access: { roles: ['admin', 'member', 'scope:event:attendee'] } },\nmasking: { email: { type: 'email', show: { roles: ['admin', 'scope:event:organizer'] } } },\nfirewall: { any: [\n { field: 'organizationId', equals: 'ctx.activeOrgId' },\n { field: 'eventId', equals: 'ctx.scope.event' },\n] },\n```\n\nSo an attendee who \"enters\" an event reads that event's guest list — the `eventId`\nfirewall arm matches their verified scope — with no org-membership role, and\n`email` stays masked unless they hold `scope:event:organizer`.\n\n### Scoped-role name sugar\n\nWrite the bare role name and the compiler lowers it to canonical\n`scope:<kind>:<role>` when it resolves uniquely:\n\n```ts\naccess: { roles: ['attendee'] } // → scope:event:attendee\n```\n\nReserved names (`admin`, `member`, `owner`), pseudo-roles, and anything declared\nin `authz.roles` are never rewritten. A bare name that's ambiguous across scopes\nis a compile error pointing you to the explicit `scope:<kind>:<role>` form.\n\n## v0.36.0 — May 25, 2026\n\nProject-wide `id` generation now applies to every write path, action `db` is\ntyped on Cloudflare D1, and realtime rooms can be gated on a unique non-PK column.\n\n### `id` default moves to the column (`$defaultFn`)\n\nThe configured `generateId` strategy now lands on the `id` column itself —\n`id: text(\"id\").primaryKey().$defaultFn(() => createId())` — not just inside the\nauto-CRUD route handler. Previously a table with an explicit `text(\"id\").primaryKey()`\nkept a bare PK, so a hand-written action doing `db.insert(...).values({…})` got no\n`id` and failed at runtime with a `NOT NULL` 500 — invisible to `tsc` because the\nscoped `db` was `any`. The injector (which already did this for tables with no\ndeclared PK) now also appends the strategy's `$defaultFn` to an explicit `id` PK.\n`generateId: false` (client-supplied ids) and `serial`/integer PKs are left\nuntouched; the rewrite is idempotent. `$inferInsert` now marks `id` optional.\n\n### Action `db` is typed on Cloudflare D1\n\nThe scoped `db` passed to custom actions is no longer `any`. On D1 projects the\nper-feature `define-action` helper types it as a Drizzle client whose\n`.insert().values()` makes the org/owner/team scope columns optional (the runtime\nfills them from context), while every other column you declared stays required —\nso `tsc` catches a forgotten column, typos, and wrong types, and query results\ncome back typed. Neon/Postgres keep `db: any` for now.\n\n`ctx.userId` is also narrowed to `string` (not `string | undefined`) in actions\nwhose `access` requires authentication — so a trusted write like\n`db.insert(t).values({ ownerId: ctx.userId })` type-checks without a cast.\nActions reachable anonymously (a `PUBLIC` arm, including inside `or`/`and`) keep\n`ctx.userId` optional.\n\n### `access.resource` gains an optional `key`\n\nThe per-room authorization gate (`bindings.durableObjects[].access`) always\nmatched the WebSocket roomId against the backing table's primary key —\n`eq(table.id, rowId)`. Rooms addressed by a different unique column had no way\nto use it: a Yjs collaborative editor keyed by `event_pages.yjsRoomId`\n(`ns.idFromName(row.yjsRoomId)`) would never match on `id`, so projects dropped\nthe `access` block and hand-rolled enforcement in `onConnect` — or, more often,\nshipped no row-level check at all, leaving the room reachable by any\nauthenticated user who could guess a room id.\n\nThe long form now accepts `key`:\n\n```ts\naccess: { resource: { feature: 'event-pages', table: 'eventPages', key: 'yjsRoomId' } }\n```\n\nThe gate emits `eq(table.<key>, rowId)` against the named column. `key` defaults\nto `'id'`, so every existing pin is byte-for-byte unchanged, and it also works\ninside each `resources[kind].resource` of the multi-resource form. The compiler\nvalidates the column exists against the pinned table's schema at compile time.\n\nThe \"multi-table feature is ambiguous\" compile error now points at all three\nescapes — the long-form pin, the `key` option for non-id rooms, and declaring\nthe table's firewall with a `via:` relationship so membership gating runs in the\ngate with no hand-written `onConnect`. See\n[PartyServer rooms → per-room authorization](/stack/realtime/partyserver-rooms).\n\n## v0.35.0 — May 25, 2026\n\nNew **FGA pillar** — OpenFGA / Google Zanzibar Relationship-Based Access\nControl (ReBAC), compiled into your Worker. Plus a public-sharing surface\n(type-bound public access + signed share links) built on it.\n\n### Relationship-based access control (`authz.fga`)\n\nRole-based access and one-hop relationship joins can't express *graph-shaped*\npermissions: an `editor` who is automatically a `viewer`, a document that\ninherits viewers from its folder, a `team#member` group grant, or a per-record\nassignment that doesn't require a global role. The new `authz.fga` block adds a\ntrue ReBAC engine modeled on [OpenFGA](https://openfga.dev):\n\n- **Model** — declare object types, relations, and userset rewrites in the\n OpenFGA modeling DSL (`or` / `and` / `but not`, `[user:*]` public access,\n `[team#member]` usersets, `viewer from parent` tuple-to-userset). The compiler\n parses and semantically validates it at compile time — dangling type or\n relation references fail the compile loudly.\n- **Tuples** — stored in a compiler-owned, organization-scoped `fga_tuples`\n table the compiler emits and migrates. A Check never reads another tenant's\n tuples.\n- **Check engine** — resolved entirely inside the Worker (no external auth\n service): direct tuples, type-bound public access, userset subjects, computed\n usersets, tuple-to-userset, request-scoped contextual tuples, with cycle\n detection and a depth cap.\n- **`ctx.fga`** — `check` / `listObjects` / `expand` / `write` / `read`,\n org-scoped, available in every action and handler.\n- **`access: { fga: { relation, object } }`** — a new declarative access arm.\n The compiler fetches the record and emits an inline, fail-closed\n `ctx.fga.check('user:' + ctx.userId, relation, object)` gate (`object` is a\n `job:{id}` template over the record's columns).\n- **Collection-level FGA filtering** — an `fga` arm on `read.access` (or a named\n view) now filters the collection `GET /`, not just `GET /:id`. The compiler\n resolves the caller's authorized object ids via the engine's `ListObjects` and\n injects an `inArray(id, …)` into the list query, so pagination, `total`, and\n `hasMore` stay correct. Supported shapes are bare `{ fga }`,\n `or:[{ roles }, { fga }]`, and `and:[{ roles }, { fga }]`; deeper nesting is a\n compile error. The authorized set is bounded by `authz.fga.listObjects.maxIds`\n (default 1000) — past the cap the request fails with a hard 422\n (`FGA_LIST_TOO_LARGE`) pointing to `POST /fga/v1/list-objects` for paginated\n enumeration.\n- **REST API** — an OpenFGA-compatible surface at `/api/v1/fga/v1`\n (`check`, `list-objects`, `expand`, `read`, `write`), tenant-scoped; writes\n gated by `authz.fga.writeRoles` (default `['admin']`).\n\n### Public sharing\n\n`authz.fga.sharing` turns the FGA engine into a public-sharing mechanism:\n\n- **Type-bound public access** — a model relation listing `user:*` becomes\n shareable-to-everyone by writing one tuple.\n- **Signed share links** — `POST /api/v1/fga/v1/share` mints an HMAC-signed,\n opaque token for one `(object, relation)` grant; `GET /share/v1/:token` is a\n **public, unauthenticated** route that verifies the token and returns a\n configured public projection of the object (it leaks nothing beyond that\n object + relation).\n- **Share URL** — both a dedicated route (`/share/v1/:token`, always mounted)\n and an optional vanity base URL (`share.<your-domain>`, added to your runtime\n routes) are supported.\n\n### q-recruit showcase\n\nThe recruitment example now models `organization → job → application/interview`\nwith FGA: a `recruiter` is automatically a `viewer` and `can_manage` of a job,\napplications inherit viewers from their job, and a job can be made publicly\nshareable. New `assign-recruiter` and `make-public` actions demonstrate\n`ctx.fga.write`, and `jobs.update` gates on `{ or: [{ roles }, { fga }] }`.\n\n## v0.34.1 — May 24, 2026\n\nPatch fixing a silent-skip bug in drizzle migration emission, plus a new\nCLI subcommand for inspecting and repairing migration-state drift.\n\n### Compiler now fails loud on drizzle migration state drift\n\nWhen `quickback/drizzle/<dialect>/meta/_journal.json` fell out of sync\nwith the on-disk `.sql` files — typically because someone hand-rolled a\nmigration without a journal bump, or because a prior compile collided\nwith an existing tag — drizzle-kit's diff base became stale and it\nsilently skipped emission. The compile reported success, no new `.sql`\nwas written for newly defined tables, and the next `wrangler deploy`\nshipped a Worker that 500'd on every request touching those tables.\n\nThe compiler now runs a precheck before any drizzle-kit invocation and\nrefuses to compile when it detects any of:\n\n- `.sql` files on disk with no matching entry in `_journal.json`\n- journal entries that reference missing `.sql` files\n- non-sequential `idx` values in `_journal.json`\n- two `.sql` files sharing the same `idx`\n- (for `auth/` and `features/` only) journal entries with no matching\n `<idx>_snapshot.json` — drizzle-kit needs the snapshot as a diff base\n\nSnapshot/journal drift that the previous `console.warn` only logged\nserver-side is now propagated to the CLI and printed under\n\"Compilation warnings\".\n\n### New `quickback migrations doctor` CLI command\n\nTwo modes:\n\n```bash\nquickback migrations doctor # diagnose\nquickback migrations doctor --rebuild-journal # repair\n```\n\nDiagnose walks `quickback/drizzle/{auth,features,files,webhooks,audit}/`,\nprints a per-dir table (`.sql files`, `journal entries`, `snapshots`),\nand flags every drift kind the compiler precheck enforces. Repair\nrewrites `_journal.json` from on-disk `.sql` filenames in sorted order —\nthis is the recovery recipe users were applying by hand. Snapshot drift\non drizzle-kit dirs (`auth/`, `features/`) can only be repaired by\nrunning `drizzle-kit introspect` against the live DB; the doctor prints\nthe exact command.\n\n### Upgrade path for projects in the broken state\n\nProjects with existing drift will get a clear error message and an\nexplicit fix command on the next compile against v0.34.1:\n\n```\n✖ Drizzle migration state is inconsistent — refusing to compile.\n Causes:\n - quickback/drizzle/features: 7 .sql file(s) have no matching journal entry: ...\n Fixes:\n - Run `quickback migrations doctor` to diagnose, then\n `quickback migrations doctor --rebuild-journal` to repair.\n```\n\nNo action needed for projects whose journals are already in sync.\n\n## v0.34.0 — May 23, 2026\n\nCustomizable email-OTP templates and a dedicated admin-create-user hook\n— closes a longstanding gap where projects on `email.provider: 'aws-ses'`\nhad to live with the generic \"Your password reset code is ...\" copy for\nadmin-bootstrapped accounts.\n\n### Per-type email-OTP template overrides\n\nDrop a `.ts` file at `quickback/email-templates/<name>.ts` that\ndefault-exports `(input) => ({ subject, html, text })`, then reference\nit from the new `plugins.emailOtp.templates` map. Missing keys fall\nthrough to the package defaults from `@quickback-dev/better-auth-aws-ses`\n— this is purely additive; existing `emailOtp: true` projects emit the\nsame code they did before.\n\n```ts title=\"quickback/quickback.config.ts\"\ndefineAuth(\"better-auth\", {\n plugins: {\n emailOtp: {\n templates: {\n 'forget-password': './email-templates/forget-password',\n 'welcome': './email-templates/welcome',\n },\n },\n },\n});\n```\n\n```ts title=\"quickback/email-templates/welcome.ts\"\nexport default function welcome({ otp, name, appName, appUrl }) {\n const greeting = name ? `Hi ${name},` : 'Hi,';\n return {\n subject: `Welcome to ${appName} — set your password`,\n html: `<h1>Welcome to ${appName}</h1><p>${greeting} use this code: <b>${otp}</b></p>`,\n text: `${greeting}\\n\\nYour ${appName} code: ${otp}`,\n };\n}\n```\n\nRecognized keys: `'sign-in' | 'email-verification' | 'forget-password' |\n'welcome'`. The first three map 1:1 to Better Auth's emailOTP `type`\nenum.\n\n### Synthetic `welcome` routing — credential-row lookup\n\n`'welcome'` has no native Better Auth OTP type. When configured, the\ngenerated `sendVerificationOTP` callback queries the `account` table\nfor a `credential`-provider row for the recipient *before* rendering;\nif the user has none (typical of an admin-plugin-created account\nwithout a password), the send is rerouted through the welcome\ntemplate. Without a welcome template, those sends fall through to\n`forget-password` — same behavior as before. DB-error path fails open\nto the normal forget-password flow so a transient failure can't\ndeadlock the password-reset surface.\n\nProvider scope: overrides are only honored on `email.provider:\n'aws-ses'`. The Cloudflare Email path uses the helper's own template\npipeline and ignores the new config.\n\n### New recognized hook: `after-admin-user-create.ts`\n\nA virtual event that wires into the same Better Auth\n`databaseHooks.user.create.after` slot as the generic\n`after-user-create.ts`, but the generator gates the call on\n`_baCtx?.context?.path` matching `/admin/create-user` so it only fires\nwhen the row came from the admin plugin's create-user endpoint. Use it\nfor first-time-user provisioning (welcome email, default org\nassignment, audit-log writes) without inspecting the BA context by\nhand. The generic `after-user-create.ts` still runs for every signup,\nincluding admin-created ones; the two coexist in a single merged\n`after:` handler.\n\n```\nquickback/hooks/\n after-user-create.ts # every signup\n after-admin-user-create.ts # admin-plugin /admin/create-user only\n```\n\n### File transport mirrors existing slots\n\nThe new `quickback/email-templates/` directory follows the same\npattern as `quickback/plugins/`, `quickback/hooks/`, and\n`quickback/lib/`: the CLI walks the folder and uploads each `.ts` file\nin a new `projectEmailTemplates` field on the compile request; the\nbetter-auth provider stages referenced files into\n`src/email-templates/<name>.ts` and emits default imports in\n`src/lib/auth.ts`. Files not referenced by any template entry are\nignored — the CLI uploads the whole directory; the compiler picks only\nwhat's needed. A relative path pointing at a file the CLI never\nshipped fails compile fast with a \"place the file at … and rerun\"\nhint.\n\nSee [AWS SES Plugin → Per-Type Template Overrides](/stack/auth/plugins/aws-ses#per-type-template-overrides)\nand [Account UI → Hooks](/stack/account-ui/hooks#recognized-events).\n\n## v0.33.6 — May 22, 2026\n\nTwo compiler-side fixes for the queue-consumer / embedding surface and one\nschema-emission bug that blocked `generateId: 'cuid'` projects.\n\n### Schema-emitted `createId()` now ships with a polyfill (no missing import)\n\nWhen `providers.database.config.generateId` is set to `'cuid'`, the audit-\nfield injector emits an id column like\n`id: text('id').primaryKey().$defaultFn(() => createId())`. Previously the\nschema source referenced `createId` but no import landed, so `tsc` on the\ngenerated project failed with `Cannot find name 'createId'`. Recurring\nbug — every recompile re-emitted the broken file (the \"do not edit\"\nbanner doesn't protect from regeneration).\n\nFix: the injector now prepends a top-of-file polyfill backed by\n`crypto.randomUUID()` — a Workers / Node 19+ / Bun global — instead of\ntrying to import `@paralleldrive/cuid2`. The package isn't bundled by\nQuickback (per the [hooks doc](/stack/account-ui/hooks)'s \"stick to\nbuilt-ins\" guidance) and the schema-gen sandbox can't resolve project\nnode_modules anyway, so the polyfill is the only path that works\nout-of-the-box.\n\n```ts title=\"Generated schema header (cuid strategy)\"\n\n// Polyfill — Quickback compiler does not ship @paralleldrive/cuid2 in\n// generated projects, and the schema-gen sandbox can't see node_modules.\n// crypto.randomUUID() is a Workers / Node 19+ / Bun global.\nconst createId = () => crypto.randomUUID();\n\nexport const widgets = sqliteTable('widgets', {\n id: text('id').primaryKey().$defaultFn(() => createId()),\n // ...\n});\n```\n\nIf you want real cuid2 strings (collision-resistant, shorter than UUIDs)\nyou can still install `@paralleldrive/cuid2` and add the import yourself —\nthe injector honours an existing import and skips the polyfill.\n\n### queue-consumer.ts header reflects what the file actually does\n\nBefore v0.33.6 the generated `src/queue-consumer.ts` always carried the\npreamble:\n\n```\n* Queue Consumer for Embedding Jobs & Custom Queue Handlers\n*\n* Processes embedding jobs asynchronously using Workers AI and Vectorize.\n* Also supports custom queue handlers defined in services/queues/.\n```\n\n— even on projects with zero embedding features. Users on\ncustom-queue-only deployments would search for `EMBEDDINGS_QUEUE` /\nVectorize bindings that wrangler.toml correctly didn't emit, wasting\ndiagnostic time.\n\nThe preamble now reflects the actual surface:\n\n| `hasEmbeddings` | `hasCustomHandlers` | Header |\n|---|---|---|\n| ✓ | ✓ | \"Queue Consumer for Embedding Jobs & Custom Queue Handlers\" |\n| ✓ | — | \"Queue Consumer for Embedding Jobs\" |\n| — | ✓ | \"Queue Consumer for Custom Queue Handlers\" + explicit \"No embedding bindings (EMBEDDINGS_QUEUE / Vectorize / AI) are referenced\" |\n| — | — | \"Queue Consumer Stub\" (additionalQueues with no handler yet) |\n\n### Symmetric embedding detection prevents silent drift\n\nThe wrangler.toml emit path (`EMBEDDINGS_QUEUE` producer/consumer\ndeclaration) and the queue-consumer.ts emit path (embedding handler code)\npreviously used two different functions to detect \"this project has\nembeddings\": `hasEmbeddingsConfig` checked both `feature.resource.\nembeddings` and `feature.tables[].resource.embeddings`;\n`extractEmbeddingFeatures` only iterated the tables array. A feature\nshape with feature-level embeddings sugar but no populated tables would\nland in the wrangler binding while NOT landing in the consumer file\n— silent drift.\n\n`hasEmbeddingsConfig` is now defined as\n`extractEmbeddingFeatures(...).length > 0`. The two stay in lock-step\nby construction. `extractEmbeddingFeatures` now reads from both shapes\n(tables-level when present, feature-level otherwise).\n\n## v0.33.5 — May 22, 2026\n\nTwo structural fixes that resolve recurring classes of bug for projects with\ninteger primary keys and for projects whose audit columns drift between\nschema and database.\n\n### URL `:id` params coerce to Number when the PK column is integer\n\nPer-id CRUD handlers (`GET /:id`, `PATCH /:id`, `DELETE /:id`, `PUT /:id`)\nextracted the URL param as a string and passed it straight into\n`eq(table.id, id)`. For resources with `integer().primaryKey()` columns —\ntriggered either by `generateId: 'serial'` on the database config or by\nimported legacy schemas — every per-id route raised a downstream tsc\ntype error (integer ≠ string). One production project reported 249 such\nerrors across 30+ generated `*.routes.ts` files.\n\nGenerated handlers for integer-PK resources now emit:\n\n```ts\nconst __idRaw = c.req.param('id');\nconst id = Number(__idRaw);\nif (!Number.isInteger(id)) {\n return c.json(ValidationErrors.invalidInput([{\n path: ['id'],\n message: `Expected integer, got \"${__idRaw}\"`,\n code: 'invalid_type',\n }]), 400);\n}\n```\n\nText-PK resources (the default and the recommended path) are unchanged.\n\nA soft-deprecation warning now fires at compile time when\n`providers.database.config.generateId === 'serial'` is set, nudging new\nprojects toward text-PK strategies (`'cuid'`, `'uuid'`, `'prefixed'`, or\nthe default). Existing serial-PK projects keep working.\n\n### Audit-field injection now runs for every dialect\n\nThe compiler auto-injects `created_at`, `modified_at`, `created_by`, and\n`modified_by` columns into every feature table, and the scoped-db\nruntime auto-fills them on insert. Until v0.33.5, the early injection\nstep in `parseCompilerInput` was gated on `targetDialect ===\n'postgresql'`. SQLite/D1 projects fell back to a later injection inside\n`generateFeature`, which only fired when `feature.tables.length > 0` —\nfeatures arriving without a populated tables array (raw-drizzle shapes,\ncertain legacy migration tables) silently skipped audit injection.\n\nSymptom: schemas claimed the columns existed (so the scoped-db proxy\ntried to fill them on insert), but the database table didn't have them.\nInserts failed with \"column doesn't exist.\" Users reported this for the\n`user_preferences` table and, earlier, for `chat_reads` (the\n`0028_chat_reads_id_column.sql` incident).\n\nThe early injection now runs for all dialects. `injectAuditFields` is\nalready idempotent, so the subsequent per-target injections in\n`compilePureSQLTarget` and `feature-generator.ts` are no-ops when the\ncolumns are already present. Net: every feature's schema source has\naudit columns by the time drizzle-kit reads it, regardless of dialect\nor feature shape.\n\nUpgrade path: recompile against v0.33.5, commit the generated migration\nthat adds the missing audit columns, then `wrangler d1 migrations apply`.\n\n## v0.33.4 — May 21, 2026\n\nPatch fixes covering upgrade-path bugs and OpenAPI spec/route divergence. No\nnew features or breaking changes.\n\n### OpenAPI emits CRUD endpoints only when the route emitter registers them\n\nThe OpenAPI emitter previously advertised `GET /`, `POST /`, `GET /:id`,\n`PATCH /:id`, `DELETE /:id`, and the corresponding `/batch` operations on\nevery resource, regardless of which CRUD verbs were actually declared.\nClients generated from `openapi.json` then issued requests that fell\nthrough to `ROUTE_NOT_FOUND` from the firewall layer — a silent contract\nbreak for anyone whose code path was driven by openapi-typescript or\nsimilar codegen.\n\nEach gate now mirrors the route emitter exactly. A resource that only\ndeclares `read + create + delete` (no `update`) gets no PATCH operations\nin the spec. A write-only sink (`create` only, no `read`) gets no GET\noperations. Same for batch variants — `POST /batch` only when\n`crud.create` is set, `DELETE /batch` only when `crud.delete` is set,\netc.\n\nIf your generated client was calling these spurious endpoints, those\ncalls were already failing at runtime; this just removes them from the\nspec.\n\n### Legacy D1 audit-timestamp migrations rewritten in place\n\nCompilers ≤ v0.33.1 emitted\n`DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))` for audit columns\n(`created_at`, `modified_at`, etc.). Cloudflare D1 rejects this in\n`ALTER TABLE ADD COLUMN` with `SQLITE_ERROR [code: 7500] \"Cannot add a\ncolumn with non-constant default\"`. v0.33.2 stopped emitting the\nnon-constant form, but pending unapplied legacy migration files on\nupgrading projects still poisoned `wrangler d1 migrations apply` and\nleft the deploy stuck.\n\nThe D1 migration safety pass now retrofits these files in place,\nreplacing the strftime expression with the same `'1970-01-01T00:00:00.000Z'`\nconstant v0.33.2+ uses. The compile-time warning lists the affected\ncolumns:\n\n```\n⚠ D1 helper adjusted features migrations for Cloudflare D1 safety:\n 0004_early_dracula.sql [rewrote=applied_at,created_at,modified_at]\n```\n\nUpgrade path: recompile against v0.33.4, commit the rewritten SQL, then\n`wrangler d1 migrations apply` proceeds.\n\n### D1 helper warning is now actionable\n\nThe same migration safety pass auto-prepends `PRAGMA defer_foreign_keys\n= on` to every drizzle table-rebuild migration — required on D1\nbecause it doesn't honour `PRAGMA foreign_keys=OFF/ON` mid-migration the\nway SQLite does. The pass used to surface this insertion as a warning\non every recompile, training users to ignore the warning entirely.\n\nThe PRAGMA is still inserted (it has to be), but no longer fires the\nwarning. Stripped Better Auth cleanup, reordered child-first DROPs, and\nthe new `rewrote=…` annotation above still warn — those are cases where\na human should look.\n\n### Reference: `account.appUrl` / `account.tenantPattern`\n\nv0.33's redesigned dashboard org-card uses two new optional fields on\nthe `account` config to deep-link into the tenant's own app:\n\n```ts\n// quickback.config.ts\naccount: {\n // …existing fields\n appUrl: 'https://app.example.com',\n tenantPattern: '/{slug}',\n}\n```\n\nBoth are typed in the config schema and baked into the Account SPA at\nbuild time as `VITE_QUICKBACK_APP_URL` and `VITE_TENANT_URL_PATTERN`.\nWithout them, the dashboard falls back to a single-target card that\nlinks to the account org-settings page (legacy v0.32 behaviour). Adding\nthem enables the two-zone layout with the external deep-link affordance.\n\n(No code change in v0.33.4 — the fields shipped with v0.33.0 but weren't\ncalled out in the changelog.)\n\n## v0.33.0 — May 21, 2026\n\n### Dedicated hostnames for `/auth/v1/*` and `/api/v1/*` (Shape 1)\n\nTwo new optional overrides let you carve specific backend surfaces onto dedicated hostnames, served by the same Worker:\n\n```ts\n// quickback.config.ts\nauth: { domain: 'auth.example.com' }, // /auth/v1/* lives here too\napi: { domain: 'api.example.com' }, // /api/v1/* lives here too\n```\n\nOn the dedicated hostname, the hostname IS the namespace — `/v1/*` is a shortcut that the Worker-entry rewriter prepends with `/auth` or `/api` before route matching. So `https://api.example.com/v1/users` reaches the same handler as `https://quickback.example.com/api/v1/users`. Both forms work; the long form is also accepted on the dedicated host. Non-matching paths return a JSON 404 (\"Not found on api.domain — this hostname serves /api/v1/* and the /v1/* shortcut only\") — each hostname stays dedicated to its surface. `/health` and `/openapi.json` are explicit exceptions because monitoring/discovery agents expect them everywhere.\n\nBoth new domains:\n- Get a `{ pattern, custom_domain: true }` route in `wrangler.toml`\n- Join `trustedOrigins` (CORS allowlist)\n- Join the cross-subdomain cookie inference (auto-enables `crossSubDomainCookies` when ≥2 same-parent subdomains are configured)\n- Join CSP `connect-src` so SPAs can fetch from them\n\n**Dual-reach:** all routes remain reachable at the unified backend host (see below) regardless of which dedicated hostnames are configured. The dedicated hostnames are aliases, never replacements.\n\n### `quickback.{baseDomain}` codified as the always-present unified backend\n\nThe compiler has always auto-inferred a `quickback.{baseDomain}` hostname when any subdomain is configured. v0.33 promotes this from inferred fallback to **load-bearing contract**:\n\n- The unified backend hostname is GUARANTEED to exist when any custom subdomain (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`) is set.\n- Every compiler-emitted backend route (api, auth, storage, health, openapi, realtime, mcp, bundled SPAs, sysadmin endpoints) is reachable at the unified host, always.\n- Per-surface domain overrides are additive (Shape 1) — they create more hostnames, never remove routes from the unified host.\n\nThis is forward-pointing: the future management layer can rely on a single discovery URL pattern (`https://quickback.{baseDomain}/...`) to find any backend regardless of how the operator split their surfaces onto subdomains.\n\nInference also extends to consider `auth.domain` and `api.domain` as domain sources, so a project configuring only one of them still derives `quickback.{baseDomain}` automatically. Explicit `config.domain` still wins over inference.\n\n### `compiler.routes` config block (scaffold — partial)\n\nOptional path-prefix overrides for compiler-emitted system routes:\n\n```ts\ncompiler: {\n routes: {\n storage: '/files', // default '/storage'\n broadcast: '/realtime', // default '/broadcast/v1'\n mcp: '/agent', // default '/mcp'\n health: '/_health', // default '/health'\n openapi: '/openapi.yaml', // default '/openapi.json'\n },\n}\n```\n\n**Status:** the config is validated and reaches the reserved-prefix registry (so SPA pass-through and compile-time collision detection already honor overrides), but the per-section route emitters still hardcode the defaults. Setting a non-default value today will produce a misconfigured Worker — the registry knows the new path but the actual `app.route('/storage/v1', …)` mount uses the old one. **Don't set these in production yet.** Per-section emit wiring lands in a follow-up.\n\n`/api/v1/` and `/auth/v1/` are NOT configurable here — those are deep contracts touched by feature emitters, OpenAPI generation, generated clients, and BA's own basePath. The Shape 1 hostname overrides above are the supported way to relocate them.\n\n## v0.32.0 — May 21, 2026\n\n### Single-origin path-routed architecture\n\nA modern Quickback project now runs on **one Cloudflare Worker behind one custom domain**, with the bundled Account and CMS SPAs path-mounted at `/account/` and `/cms/`, system routes at `/api/`, `/auth/`, `/storage/`, and the user's own SPAs anywhere else they want. No cross-subdomain cookies, zero CORS preflights, no separate `api.`/`account.`/`cms.` subdomains required:\n\n```ts\n// quickback.config.ts\napps: { www: { domain: 'app.example.com' } }, // user's root SPA\naccount: true, // bundled at /account/\ncms: true, // bundled at /cms/\n// /api/, /auth/, /storage/, /openapi.json, /health all live here too\n```\n\nThe bug that previously broke this shape: when a hostname-mounted root SPA was configured (`apps.www.domain`), its middleware swallowed every path that wasn't in a hardcoded list (`/api/`, `/auth/`, `/admin/`, `/storage/`, `/health`). Requests to `/account/profile` got remapped to `/www/account/profile`, 404'd, then SPA-fallback'd to the wrong SPA. v0.32 introduces a **reserved-prefix registry** (`resolveReservedPrefixes` in `apps/compiler/src/generators/core/reserved-prefixes.ts`) as the single source of truth for what every catchall middleware must pass through:\n\n- **System** (always present): `/api/`, `/auth/`, `/storage/`, `/health`, `/openapi.json`\n- **Conditional** (only when feature is on): `/account/` (when `account: true`), `/cms/` (when `cms: true`), `/broadcast/v1/` (realtime), `/mcp` (MCP server)\n- **User-contributed**: every `apps.<name>.path` for path-mounted apps\n\nPath-mounted apps that collide with a system or bundled-SPA reservation throw a compile-time error naming both owners. `apps.api = { path: '/api' }` errors clearly instead of silently hijacking feature routes at runtime.\n\n### Admin URL namespace migration: `/admin/v1/*` → `/auth/v1/admin/*`\n\nQuickback's legacy admin tier emitted three things under `/admin/v1/*`:\n\n1. A role-admit middleware that admitted both `'admin'` and `'sysadmin'` — contradicting the pseudo-role evaluator's strict-independence model (`ADMIN` admits `'admin'` only; `SYSADMIN` admits `'sysadmin'` only).\n2. `GET /admin/v1/organizations` — a thin proxy to Better Auth's own `/auth/v1/organization/list`.\n3. `GET /admin/v1/sysadmin/organizations` — cross-tenant org listing, sysadmin-only.\n\nIn v0.32, the first two are **removed** and the third **renames** to `GET /auth/v1/admin/list-organizations`. The new path sits under Better Auth's admin URL namespace (sibling of `/auth/v1/admin/list-users`, `/auth/v1/admin/ban-user`, etc.), follows BA's verb-noun convention, and keeps its sysadmin-only gate inside the handler — Quickback-emitted, not BA-mounted.\n\nWhat this enables: `/admin/*` is no longer a reserved system prefix. Projects can mount their own admin SPA via `apps.admin = { path: '/admin' }` without colliding with anything.\n\nWhat changes for callers:\n- The bundled CMS SPA's sysadmin org switcher is updated in lockstep (no migration needed for projects using the SPA as-is).\n- External callers of `/admin/v1/organizations` should migrate to BA's `/auth/v1/organization/list` (same behavior — caller's memberships).\n- External callers of `/admin/v1/sysadmin/organizations` should migrate to `/auth/v1/admin/list-organizations`.\n- Features that previously relied on the \"admit both admin AND sysadmin\" middleware should declare `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly on each route.\n\nThe `ADMIN_ROUTE_FEATURES` carve-out in the compiler is also removed — feature routes always mount at `/api/v1/<feature>`, and admin-only behavior is enforced by per-operation `access: { roles: ['ADMIN'] }` at the resource level.\n\n### Two compiler bug fixes\n\n- **Soft-delete index callback parameter bug.** The auto-index injector emitted hardcoded `t.<col>` references regardless of the existing extras callback's parameter name. When a user (or upstream transform) wrote `(table3) => ({ … })`, the appended composite-index entries referenced `t.organizationId, t.deletedAt` — `t` undefined inside the arrow scope, `ReferenceError` at module load. Fixed in `apps/compiler/src/utils/auto-indexes.ts` by capturing and reusing the callback's parameter name.\n- **Reserved-word action filename collision.** Action discovery walks `actions/*.ts` and emits `import <name> from './actions/<name>'`. A user filename of `import.ts`, `delete.ts`, `await.ts`, `export.ts`, etc. produced `import import from './actions/import';` — a SyntaxError on module load. Fixed in `apps/compiler/src/codegen/discovered-actions.ts` by aliasing reserved-word and invalid-identifier filenames to `__action_<sanitized>` bindings while preserving the public action key (route emitters use bracket notation, so reserved-word keys are fine in the lookup map).\n\n## v0.29.0 — May 19, 2026\n\n### Opt-in `id` auto-injection (`compiler.injectId: 'auto'`)\n\nQuickback's generated CRUD routes, FK extractor, relationship resolver, and `/:id` mount points all assume every feature table has an `id` primary key column. Authoring a table without one — common when porting an existing schema, or when a domain genuinely uses a compound or non-`id` PK — produced silent failures: routes that 404, batch operations that targeted the wrong rows, FK lookups that returned empty.\n\nv0.29 adds an opt-in flag that auto-injects an `id` column into every feature table that doesn't already declare one. Same mechanism as the existing `createdAt`/`modifiedAt` injection — early-pass, idempotent, dialect-aware.\n\n```ts\n// quickback.config.ts\ncompiler: {\n injectId: 'auto', // off by default; opt in per project\n}\n```\n\nWhen `'auto'`:\n- Tables with no `.primaryKey()` declared get `id: text(\"id\").primaryKey().$defaultFn(() => createId())` (or the matching shape for `dbConfig.generateId` — `serial`, `uuid`, `prefixed`).\n- Tables that already declare an `id` column (in any shape) are no-op — the injector is idempotent.\n- Tables with a `.primaryKey()` on a non-`id` column raise a clear compile error that names the offending column and points at the v0.30 follow-up which will rewrite custom PKs to unique indexes automatically. v0.29 surfaces the conflict; v0.30 fixes it.\n\nDefault stays `false` so existing projects don't get migration churn. Opt in when you want to lean on every-table-has-id semantics across your schema.\n\n### Why this is opt-in (and what v0.30 changes)\n\nThe \"every table has `id`\" assumption is load-bearing across 68+ sites in the compiler — every CRUD emitter, the FK regex (`.references(() => target.id)`), the relationship resolver hydration block, the `/:id` route mounts. v0.29 only injects the column; v0.30 will close the remaining gaps:\n\n- FK extraction migrates from `.id` regex to schema-aware metadata lookup, so tables with non-`id` PKs participate in FK display + relationship resolution.\n- The PK→unique-index rewrite lands — tables with explicit non-`id` PKs auto-keep their uniqueness as a constraint while gaining the auto-injected `id`.\n- The flag flips to default-on; opting out becomes the rare path.\n\nv0.29 ships the foundation so projects can opt in today without waiting for the full structural pass.\n\n## v0.28.0 — May 19, 2026\n\n### INTERNAL pseudo-role: server-only schemas, unforgeable from HTTP\n\nv0.27 had five pseudo-roles — `PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN` — and one structural gap: there was no way to mark a schema as \"the server enumerates this; no user-facing route should ever read across tenants.\" Push subscriptions, personal access tokens, OAuth tokens, broadcast job tables — anywhere the server needs full visibility but users should only see their own row. The workaround was `firewall: { exception: true }` plus an out-of-band convention, which left auth on the schema looking incidental.\n\nv0.28 adds **`INTERNAL`** as the sixth pseudo-role. Schemas with `roles: ['INTERNAL']` are reachable only by `AppContext` values where `ctx.internal === true` — a flag the HTTP auth middleware **never** sets. No session, JWT, header, query parameter, or body field populates it. The flag is reserved for compiler-emitted server-internal entry points (queue consumers, cron workers, server-side helpers that bypass HTTP entirely).\n\n```ts\n// features/comms/push-subscriptions.ts\nexport default defineTable(push_subscriptions, {\n firewall: [{ field: 'ownerId', equals: 'ctx.userId' }],\n // User reads their own subscriptions via the standard CRUD route.\n read: { access: { roles: ['USER'] } },\n // Server enumerates ALL subscriptions for a broadcast — INTERNAL only.\n crud: {\n delete: { access: { roles: ['INTERNAL'] } },\n },\n});\n```\n\nThe split-surface pattern is the recommended shape: a user-facing access node uses `USER` / `AUTHENTICATED` / a real role; a server-only access node uses `INTERNAL`. Mixing INTERNAL with a user-facing pseudo-role on the **same** access node is a compile error — it almost always means the developer is confused about which side of the trust boundary they're on. The error names the cohabiting markers explicitly and points at the fix (split into separate access blocks).\n\nThe runtime stamping (queue consumer ctx, cron worker ctx) lands in a follow-up; v0.28 ships the declarative surface so projects can mark schemas accurately today. Until the stamping ships, server-internal code uses `unsafeDb` to enumerate INTERNAL surfaces — the security guarantee is in place because no HTTP-derived context can ever carry `ctx.internal === true`.\n\n### Reserved-name fix: SYSADMIN and INTERNAL added to ALWAYS_RESERVED\n\n`SYSADMIN` was previously omitted from the `ALWAYS_RESERVED` set in `authz-schema.ts`. The runtime validator rejected `roles: ['SYSADMIN']` when `cms.sysadmin: true` wasn't set, but the **shadow-declaration path** — user code writing `authz.roles.SYSADMIN: { roles: [...] }` to silently change the pseudo-role's meaning — wasn't blocked. v0.28 closes that gap by adding both `SYSADMIN` and `INTERNAL` to the unconditionally-reserved set.\n\n### Per-table OWNER_SCOPE_RULES: explicit owner predicates no longer over-scope\n\nWhen a user declared a non-canonical owner predicate on one table — e.g. `firewall: [{ field: 'linkedUserId', equals: 'ctx.userId' }]` — that column got promoted into the **project-global** `OWNER_SCOPE_RULES` list. Any other table in the project that happened to have a `linkedUserId` column (even as a plain FK reference, not for scoping) had the same `WHERE linkedUserId = ctx.userId` injected on every read, update, and delete. Silent over-scoping that surfaced only when a query returned the wrong rows.\n\nv0.28 narrows the global list to the **canonical owner column** — the one matching `authDefaults.owner.column` (default `ownerId`). Explicit predicates on custom-named columns are honored on their declaring table via that table's own `buildFirewallConditions` helper, but stay per-table. Reads on other tables with the same column name are unaffected.\n\n```ts\n// Before v0.28: linkedUserId on `comments` ALSO got the WHERE\n// because `event_organizers` declared an explicit owner predicate.\nexport default defineTable(event_organizers, {\n firewall: [{ field: 'linkedUserId', equals: 'ctx.userId' }],\n});\nexport default defineTable(comments, {\n // comments.linkedUserId is just an FK reference; we don't want it scoped.\n firewall: [{ field: 'eventId', equals: 'ctx.activeOrgId' }],\n});\n```\n\nIn v0.28, `event_organizers` queries get the per-table `linkedUserId = ctx.userId` predicate as before; `comments` queries are no longer mis-scoped.\n\nIf you genuinely want the same column to scope multiple tables (rare), declare the explicit firewall predicate on each table. The implicit \"every table with this column gets scoped\" behavior was the bug — explicit-per-table is the cure.\n\n## v0.27.0 — May 19, 2026\n\n### Narrow `ctx.<exposeAs>` typing for namespace-scoped actions\n\nSince v0.23 the namespace middleware has hydrated `ctx.<exposeAs>` with the loaded resource row before each action runs. The static type of that field stayed `any` — runtime safety was solid, but autocomplete and typo-catching were missed opportunities.\n\nv0.27 ships the second half: one **per-namespace `defineAction` helper** emitted alongside the standard one. Importing from the narrowed helper retypes `ctx.<exposeAs>` inside `execute({ ctx })` to the loaded row's `$inferSelect` shape. Nothing about discovery, routing, or runtime behavior changes — this is purely TypeScript ergonomics.\n\n```ts title=\"features/feeds/actions/feed-moments.ts\"\n// Before — ctx.event is `any`\n\n// After — ctx.event is `typeof events.$inferSelect`\n\nexport default defineAction({\n path: '/event/:eventId/feed-moments',\n method: 'POST',\n input: z.object({ body: z.string() }),\n access: { roles: ['attendee'] },\n async execute({ ctx, input }) {\n ctx.event.id // ✓ string, autocomplete works\n ctx.event.startsAt // ✓ Date\n ctx.event.idd // ✗ TS2339 — typo caught at compile time\n },\n});\n```\n\n#### Where the file lives\n\nThe compiler emits one narrowed helper per `(feature, namespace)` pair where the feature owns at least one action whose `path:` falls under the namespace prefix. Filename is `define-action.<kebab(namespaceName)>.ts` (`eventScope` → `define-action.event-scope.ts`), sibling to the standard `define-action.ts`:\n\n```text\nsrc/features/feeds/.quickback/\n├── define-action.ts # generic — standard fallback\n└── define-action.event-scope.ts # ctx.event narrowed\n```\n\nA feature contributing to multiple namespaces gets one helper per namespace. Each action picks the import that matches its path.\n\n#### Opt-in, no breaking change\n\nActions that keep their existing `import { defineAction } from '../.quickback/define-action'` continue to compile unchanged. The `AppContext` index signature still admits `ctx.event` at type `any`; runtime hydration is unaffected. Flip imports per action at your own pace.\n\n#### Compile-time advisory\n\nWhen `quickback compile` sees a namespace-scoped action still importing the generic helper, it logs a one-line `[quickback:typing]` advisory pointing at the narrowed path:\n\n```text\n[quickback:typing] action \"feedMoments\" in feature \"feeds\" lives under\n namespace \"eventScope\" — switch its import to\n `../.quickback/define-action.event-scope` for narrow ctx.<exposeAs> typing.\n (Runtime behavior is unchanged; the narrowed helper only refines TS types.)\n```\n\nNon-blocking — same family as `[quickback:authz]`.\n\n#### Side fix\n\nRepaired a latent off-by-one in the inlined `AppContext` import path that landed in the v0.26 helper prelude but hadn't been exercised against a recompiled project yet (`\"../../lib/types\"` → `\"../../../lib/types\"`). New compiles produce a helper whose `AppContext` import actually resolves.\n\n#### Out of scope\n\nNon-namespace standalone actions with relationship-based access keep their existing `(ctx.event as typeof events.$inferSelect)` body cast. Same per-relationship helper pattern would apply if the demand surfaces — defer until requested.\n\n## v0.26.0 — May 19, 2026\n\n### Bulk-grant namespace lanes: org admins and team members in one line\n\nv0.25 widened `via:` to accept an array of relationship lanes — attendeeOf OR organizerOf, first match wins. That covers per-row authorization paths. v0.26 adds the missing piece: **bulk-grant lanes** for the \"you work here, so you see everything in your scope\" case. Org admins, team members, and other tenant-scoped staff no longer need a per-event relationship row to be authorized for a namespace.\n\n```ts\nauthz: {\n namespaces: {\n eventScope: {\n prefix: '/event/:eventId',\n via: [\n 'attendeeOf', // per-event relationship\n 'organizerOf', // per-event relationship\n { roles: ['admin', 'owner'] }, // org-role bulk grant\n { team: true }, // active-team-membership bulk grant\n ],\n },\n },\n}\n```\n\nLanes resolve in declaration order, first match wins. Per-row relationships and bulk-grant guards compose freely.\n\n#### What each bulk-grant lane does\n\n- **`{ roles: [...] }`** — passes when the caller's BA org-role for the namespace's loaded resource includes any listed role. The check is in-memory and short-circuits the relationship loop entirely. The loads-table firewall (scoped by `ctx.activeOrgId`) does the tenant isolation; this lane just adds the role precondition on top.\n- **`{ team: true }`** — passes when `ctx.activeTeamId` is set. The loads-table firewall (which scopes by team for team-scoped tables) does the actual `events.teamId === ctx.activeTeamId` match during hydration. If the firewall returns no row, the request gets a contextual 404 explaining the row isn't visible to the current session — same ambiguous-by-design phrasing the firewall has always used to prevent cross-tenant ID probing.\n\n#### Why this matters\n\nUntil v0.26, the only way to authorize an org admin for a namespace was to write `access.or: [{ via: 'attendeeOf' }, { roles: ['admin', 'owner'] }]` on every individual action under it. That OR-arm shim worked but defeated the purpose of namespaces — the whole point of hoisting the gate was to write the auth rule once. Now you do.\n\n#### Rich deny payloads\n\nThe 403 response when every lane misses lists every path the caller could have taken — relationship names, role names, and `\"team-membership\"` for `{ team: true }` lanes — in the `required` field. A developer hitting an unexpected 403 sees the full set of authorization options they need to satisfy, not a generic \"Insufficient permissions\" wall.\n\nThe 404 from hydration (when the loads-table firewall filters the request out) now includes a hint explaining that the row may exist out of scope, and a `details` field with the resource name and key, so a developer working in their own environment has enough to debug.\n\n#### Compile-time guards\n\n- **Pure bulk-grant namespaces** (no relationship lane at all) are accepted as long as `loads:` + `exposeAs:` are declared directly on the namespace. With at least one relationship lane present, those fields are inherited from the relationship — declare them on the namespace itself only when no relationship lane is available to anchor hydration.\n- **Heterogeneous `loads:` between relationship lanes is rejected** — `ctx.<exposeAs>` must always hydrate the same table regardless of which lane matched.\n- **`namespace.loads` that disagrees with the inherited value is rejected** with a clear \"drop one or align the other\" message.\n\n## v0.25.0 — May 19, 2026\n\n### Multi-lane namespace gates: more than one way to be authorized\n\nv0.24 lets you hoist a namespace gate to the project level via `authz.namespaces.<name>.via: 'attendeeOf'` — one relationship-resolver middleware running once per request for every action under `/event/:eventId/*`. That works when there's exactly one way to be authorized for the resource. It breaks the moment you have **two**: an attendee row and a per-event organizer row, say. The shim today is to OR the second check inside every individual action's `access` block, which puts you back to writing the gate over and over.\n\nv0.25 widens `via:` to accept an array of relationship lanes. The middleware tries each in declaration order, and the first one whose subject row matches authorizes the request and hydrates `ctx.<exposeAs>`.\n\n```ts\nauthz: {\n relationships: {\n attendeeOf: {\n from: 'guests',\n subject: { column: 'linkedUserId', equals: 'ctx.userId' },\n resource: { column: 'eventId' },\n where: { status: 'confirmed' },\n loads: 'events',\n exposeAs: 'event',\n },\n // Per-event named organizers. The subject can be a user OUTSIDE\n // the event's organization — e.g. a freelance event manager.\n organizerOf: {\n from: 'eventOrganizers',\n subject: { column: 'linkedUserId', equals: 'ctx.userId' },\n resource: { column: 'eventId' },\n loads: 'events',\n exposeAs: 'event',\n },\n },\n namespaces: {\n eventScope: {\n prefix: '/event/:eventId',\n via: ['attendeeOf', 'organizerOf'], // first match wins\n },\n },\n}\n```\n\nThe thing this actually unlocks isn't \"two checks instead of one.\" It's **per-event grants for users outside the owning organization** — external co-organizers, freelance event managers, partner staff. They don't need a `member` row in the event's org; they just need a row in `event_organizers` for that specific event. The horizontal axis (org / team membership) stays for \"staff at this company\"; the new vertical axis (per-event relationships) handles \"specifically connected to this event,\" regardless of payroll.\n\n#### Backward compatible\n\nThe string form keeps working — `via: 'attendeeOf'` is sugar for `via: ['attendeeOf']`. No existing namespaces break; opt into multi-lane by switching to the array form when you actually need it.\n\n#### Compile-time guards\n\nThe validator rejects three things at parse time:\n\n- **Undeclared lane names** — every entry in the array must resolve to an `authz.relationships[*]` declaration.\n- **Lanes that disagree on `loads:` or `exposeAs:`** — if attendeeOf loads `events` as `ctx.event` and organizerOf loads `agendaItems` as `ctx.agendaItem`, downstream handlers can't predict what's in `ctx.<exposeAs>`. Lanes in one namespace must hydrate the same shape.\n- **Empty arrays** — at least one lane is required (otherwise the namespace gate is meaningless).\n\n#### Follow-up: v0.26 bulk-grant lanes (shipped same day — see above)\n\nThe full 4-lane shape adds heterogeneous `via:` arrays accepting `{ roles: ['admin', 'owner'] }` and `{ team: true }` entries, so org admins and team members get the gate without writing relationship rows. v0.25 was the foundation; [v0.26](#v0260--may-19-2026) lifted the existing per-action `access.or: [..., { roles: [...] }]` shim into the namespace and landed same-day.\n\n## v0.24.0 — May 19, 2026\n\n### Cross-feature namespaces: one hoisted gate, many features\n\nv0.23 shipped `defineTable({ namespace: { prefix, via } })` — a hoisted relationship-resolver middleware that gates every standalone action in *one feature's* Hono app. That covers the 95% case where a domain concept (events) and the actions under it all live in the same feature directory.\n\nv0.24 lifts the namespace to the project level so it can span multiple features. A new `authz.namespaces` block on `quickback.config.ts` declares a path-prefix gate that any feature's standalone action can participate in by matching the prefix in its `path:`. One synthetic routes file, one resolver mount, one relationship match per request — regardless of how many feature directories contribute actions.\n\n```ts\n// quickback.config.ts\nauthz: {\n relationships: {\n attendeeOf: {\n from: 'guests',\n subject: { column: 'userId', equals: 'ctx.userId' },\n resource: { column: 'eventId' },\n loads: 'events',\n exposeAs: 'event',\n },\n },\n namespaces: {\n eventScope: { prefix: '/event/:eventId', via: 'attendeeOf' },\n },\n}\n\n// features/feeds/actions/feed-moments.ts (cross-feature)\nexport default defineAction({\n path: '/event/:eventId/feed-moments',\n method: 'POST',\n // No gate boilerplate. ctx.event is typed.\n});\n\n// features/rsvp/actions/respond.ts (different feature, same namespace)\nexport default defineAction({\n path: '/event/:eventId/respond',\n method: 'POST',\n});\n```\n\nThe compiler emits one `src/routes/__namespace-event-scope.routes.ts` mounted at `/api/v1/event/:eventId/*`. The file imports each contributing feature's `actions` map under a distinct alias (`feedsActions`, `rsvpActions`), runs the `attendeeOf` resolver once per request at the head of the file, and dispatches to the matching action handler.\n\n#### Discovery is path-prefix-only\n\nNo new `namespace: 'eventScope'` field on `defineAction`. Actions opt in by matching `path:` against a declared namespace prefix — same model the table-level v0.23 form uses, just lifted to the project level. This means actions move in/out of the namespace based on their path strings, which is the simplest discovery story and matches today's convention (filenames and paths are already the discoverable surface).\n\n#### Source-feature stays the action's home for metadata\n\nOpenAPI tags, MCP tool grouping, and CMS form discovery continue to bucket each action under its source feature. Only the *runtime routes file* moves to the synthetic location — the feed-moments action is still tagged \"feeds\" in OpenAPI, the response shape doesn't change, and your generated SDK reads identically. The URL conveys the namespace membership without forcing every layer of the compiler to re-anchor the action.\n\n#### Worker-root mount order\n\nSynthetic namespace routes files register at priority `20` — ahead of per-feature mounts (priority `0`/`10`). `sortRoutesBySpecificity` keeps the order stable, and the namespace prefix's path parameter makes it sort more specific than `/api/v1/<feature>` anyway, so the middleware fires first for every request under its prefix.\n\n#### Compile-time guardrails\n\nThe same v0.23 invariants apply at the project level, with two additions:\n\n- **`via:` must point at a declared `authz.relationships[*]` entry**, and that relationship must declare `loads + exposeAs` — without `loads` there's nothing for the middleware to hydrate, and a namespace that only gates without hydrating is indistinguishable from a per-action access rule.\n- **`prefix:` must contain at least one `:param` segment** — middleware runs before input parsing, so the relationship key comes from `c.req.param()`.\n- **Same-name conflict** between `defineTable({ namespace })` and `authz.namespaces.<sameName>` is rejected. Pick one declaration site.\n- **Ambiguous prefixes** like `/a/:x` and `/a/:y` (same shape, different `:param` names) error at compile time. Strict super/sub-set relationships (e.g. `/event/:e` and `/event/:e/admin`) are fine — the harvester routes each action to the longest matching prefix.\n- **Unused namespace warning** emits `[quickback:authz]` when no standalone action's path matches a declared prefix. Not a hard error — the namespace may be staged ahead of the actions.\n\n#### Picking the right declaration site\n\nThe table-level v0.23 form is now the **single-feature shorthand**. The project-level v0.24 form is **canonical for cross-feature**.\n\n- **Use `defineTable({ namespace })`** when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it; nothing to add to `quickback.config.ts`.\n- **Use `authz.namespaces`** when the namespace spans features. The declaration sits next to your `authz.relationships` and `authz.roles` — the canonical home for cross-cutting authz config.\n\nThe two forms can't coexist for the same namespace name. If a v0.23 table-level namespace is starting to attract cross-feature actions, lift it to `authz.namespaces` — same shape, just at the project level, and the matching paths in other features will join automatically.\n\n#### Migration\n\nZero breaking changes. Nothing in v0.23 needs to change for v0.24 to land. The new field is opt-in; existing projects pick it up the moment they declare an `authz.namespaces` entry.\n\nThe harvester runs after Zod schema validation but before route generation, so unused or misconfigured namespaces surface immediately as errors or warnings rather than as silently-broken routes.\n\n#### Fixes shipped alongside\n\nThe first two were load-bearing for v0.23 namespaces to actually work — projects upgrading from a pre-fix v0.23 will see crashes/compile errors disappear on the v0.24 recompile.\n\n- **No more dual emission of namespace-claimed standalone routes.** Pre-fix, an action with a cross-feature path like `/event/:eventId/agenda/list-my-agenda` emitted into both `src/index.ts` (without the namespace resolver) and the synthetic file (with it). The plain root copy in `src/index.ts` won every URL match and `ctx.<exposeAs>` was never hydrated — every request 500'd with `Cannot read properties of undefined (reading 'id')`. `extractStandaloneActions` now skips namespace-claimed actions; the synthetic namespace file is the sole emission.\n- **Stripped-path validator no longer rejects namespace-claimed actions.** The synthetic file mounts at `/api/v1${namespace.prefix}` and strips the prefix from each action's local path. The per-action relationship-resolver was validating the *stripped* path for `:eventId`, finding nothing, and rejecting every namespace-mounted action with \"action's surface exposes neither a path parameter ':eventId' nor an input field 'eventId'\". `planRelationshipResolver` now receives the namespace's `via` and skips its surface-key check entirely — the hoisted middleware is the single source of truth.\n- **Broadcaster DO migration tag consistent across `realtime.mode`.** Inline-mode emission was already going through `qb-do-${className}` + `new_sqlite_classes`. Separate-mode was still hardcoded `tag = \"v1\"` + `new_classes`, so flipping `realtime: { mode }` produced different migration tags for the same DO class and tripped CF error 10074 (\"class already depended on\") on cross-mode deploys. Both modes now emit `tag = \"qb-do-Broadcaster\"` + `new_sqlite_classes`.\n- **Batch handler id arrays type-derive from the input parser.** Pre-fix, `validIds`, `recordMap`, and `validEntries` in bulk-delete / bulk-update / bulk-upsert were hardcoded `string[]` / `Map<string, any>` even when the table's PK column was `integer(\"id\")` — 274× TS2769 in projects mixing string and integer PKs. Handlers now declare `type IdT = typeof ids[number]` (or `typeof records[number]['id']`) and use it for the local id types. Strings stay strings, integers stay integers, no emitter knowledge of the PK column type required.\n- **`ctx` in action handlers is now `AppContext`, not `any`.** Both `StandaloneExecuteParams.ctx` and `RecordExecuteParams.ctx` in the generated `<feature>/.quickback/define-action.ts` are typed `AppContext`. AppContext keeps its `[key: string]: any` index signature so hydrated namespace keys (`ctx.event`, `ctx.<exposeAs>`) stay accessible without TS2339; named fields (`userId`, `activeOrgId`, `roles`, `authenticated`, `user`) get autocomplete and type-checking. Cleared ~49× TS2339 in generated projects.\n- **`c.get('ctx') as AppContext` in every emitted route handler.** Pre-fix, `const ctx = c.get('ctx')` returned `any`, so `ctx.roles?.some(r => …)` left the callback parameter implicitly `any` — 16× TS7006. Now `ctx.roles` is `string[] | undefined`, `r` is `string`, no callback annotation needed.\n\n#### Deferred (tracked, not blocking)\n\n- Per-namespace narrow typing of `ctx.<exposeAs>` (so `ctx.event` resolves to `typeof events.$inferSelect` instead of `any`). The compiler emits a typed cast at the `execute()` call site in the routes file today, which type-checks the call but not the handler body. Full narrow typing requires per-namespace helper emission (one `define-action.<namespace>.ts` per namespace, or a generic param threading through the action config). Tracked separately.\n\n---\n\n## v0.23.0 — May 19, 2026\n\n### Authz relationships: compile-time guarantees, less boilerplate, hoisted middleware\n\nThis release closes the gap between what `authz.relationships` *promised* in v0.19 and what it actually enforced. Every documented invariant is now a real compile-time check; every per-action ergonomic friction has a fix. Net effect: relationship-based authorization feels native — declare the relationship once, use the role anywhere, the compiler does the wiring.\n\n#### Compile-time guarantees (the authz `firewall` parity)\n\nThe org/owner/team firewall has always been compile-time-checked: a routed resource without a scope fails the compile, full stop. As of this release, `authz.relationships` carries the same guarantees:\n\n- **Bad `via:` names fail at parse time.** A typo in a firewall predicate (`firewall: [{ field: 'eventId', via: 'guestOff' }]`) used to surface deep inside the firewall generator after most validation had passed. It's now caught alongside the `authz.roles` `via:` validation, same layer, same error format.\n- **Relationship-from tables can't opt out.** The doc at `define/types/authz.ts:73-74` always said a relationship `from:` table with `firewall: { exception: true }` \"refuses to compile\" — that's now enforced. Without this check, every `via:` subquery that pivots through an exception-marked table loses tenant isolation and can return rows from other tenants.\n- **`allowResourceMigration` is now mandatory** when the relationship's `resource.column` is on a writable update endpoint. A guest doing `PATCH /messages/:id { eventId: <other-event-id> }` to migrate a row out of their access scope used to slip past the runtime — it now fails compile with a three-option remediation (set the flag, mark the column immutable, or drop it from the guards.updatable allowlist).\n- **`via: string[]` in firewall predicates.** \"Member of attendees OR speakers\" no longer requires inventing a composite role just to use it once in a firewall — `firewall: [{ field: 'eventId', via: ['attendeeOf', 'speakerOf'] }]` lowers to an OR-combined subquery.\n\n#### Less boilerplate: auto-derivation + realtime resolver\n\n- **`resource.column` auto-derives from FKs.** Omit it and the compiler scans the relationship's `from:` table for foreign-key columns, drops the `subject.column`, and picks the remaining FK. One match → auto; zero or many → error with the candidate list. Pattern mirrors the existing firewall auto-detection.\n- **`realtime.requiredRoles` accepts authz roles.** Previously a relationship-role in `realtime.requiredRoles` fell through with a misleading \"unknown role\" error. The compiler now flattens declared authz roles into their composing Better Auth roles before the realtime ticket-handshake sees them. Relationship-only roles (no static BA fallback) emit a `[quickback:authz]` warning and fail-close at handshake — the row-stream firewall continues to enforce the relationship dimension on the data side.\n\n#### Record-based actions can finally use relationship-roles\n\nThe v0.19 fail-closed hardening had an unintended side effect: a record-based action with `access: { roles: ['attendee'] }` (where `attendee` was a relationship-role) 403'd every caller, including the legitimate ones. The runtime helper couldn't evaluate `relationship:` arms, so it fail-closed correctly — but the inline match expression that *would* evaluate the relationship was never wired up for record-based actions.\n\nThis release routes record-based actions with relationship arms through the same inline access generator the resource CRUD path already uses. `roles: ['attendee']` on `/applications/:id/recap` now actually checks whether the caller is an attendee, with the loaded record in scope. Non-relationship access trees keep the runtime path unchanged.\n\n#### Typed `ctx.<exposeAs>` in action handlers\n\nWhen a relationship declares `loads: 'events', exposeAs: 'event'`, the runtime hydrates `ctx.event` with the loaded row — but the static type was always `any`, so handlers had to write `const event = ctx.event as typeof events.$inferSelect`. As of this release, when an action's access references **exactly one** relationship with `loads + exposeAs`, the compiler emits the cast for you at the execute() call site. Handlers read `ctx.event` with the right shape; no per-handler boilerplate.\n\nMulti-arm OR actions (referencing two relationships with hydration) keep the `any` shape — we can't statically know which arm matched.\n\n#### New: `defineNamespace` — one mount, one resolver, many actions\n\nThe marquee Wave 3 change. Today's pattern for \"five standalone actions under `/event/:eventId/*` all gated by `attendeeOf`\" requires writing the same inline relationship resolver in each action — and pays the resolver cost (one subquery, one row-load) on every request, multiplied by N actions. The new `namespace` field on `defineTable` hoists the resolver into a single Hono middleware mount:\n\n```ts\n// features/events/events.ts\nexport default defineTable(events, {\n firewall: [...],\n crud: { ... },\n namespace: {\n prefix: '/event/:eventId', // absolute URL path the mount covers\n via: 'attendeeOf', // relationship gate\n },\n});\n\n// features/events/actions/post-announcement.ts\nexport default defineAction({\n path: '/event/:eventId/announcements',\n method: 'POST',\n // No relationship-gate boilerplate. ctx.event is typed\n // `typeof events.$inferSelect` inside execute().\n});\n```\n\nThe compiler:\n1. Emits one `app.use('/:eventId/*', async (c, next) => { /* relationship resolver */; await next(); })` at the head of the feature's standalone-routes file (path-prefix stripping handles the feature mount).\n2. Skips the inline relationship resolver in every per-action handler under the prefix — the middleware already ran it.\n3. Hydrates `ctx.event` once per request and threads the typed cast into every namespace action's execute() call.\n\n**Validation guardrails:**\n- `namespace.via` must point at a declared `authz.relationships[*]` entry.\n- The referenced relationship must declare `loads + exposeAs` — without `loads` there's nothing for the middleware to hydrate, and the namespace gate would be indistinguishable from a per-action access rule.\n- `namespace.prefix` must contain at least one `:param` segment — the middleware reads the relationship key from `c.req.param()`, not from request body (body parsing hasn't run at middleware time).\n\n**Scope (v1):**\n- Namespace lives within a single feature's Hono `app`; cross-feature shared namespaces are deferred to v2.\n- One namespace per `defineTable` declaration; multiple namespaces in a feature mount as siblings.\n- For namespace actions whose access references additional relationships beyond the namespace's via, the inline resolver still fires for those — namespace handles only its own.\n\n#### Migration\n\nNothing in v0.20 → v0.23 breaks existing code that compiles cleanly. The new errors fire only against patterns that were already latent bugs:\n\n- A `via:` typo that previously surfaced as a deep codegen error now surfaces at parse time, same message.\n- A `firewall: { exception: true }` on a relationship-from table now errors; this configuration was always documented as unsupported.\n- A relationship's `resource.column` writable on the resource's UPDATE endpoint now errors unless `allowResourceMigration: true` is set; previously this was a runtime escape hatch.\n- Record-based actions with `roles: ['<relationship-role>']` previously 403'd every caller; they now work as the v0.19 docs originally promised.\n\n#### Why this matters\n\nAuthz relationships are how Quickback expresses \"the caller is allowed to touch this resource because of a row in *that* table\" — guest-of-event, member-of-organization, scorer-of-interview. Until now, the feature worked but had sharp edges: typos surfaced late, the documented exception-not-allowed constraint wasn't enforced, and the namespace pattern (which most apps with nested resources end up wanting) required repeating the same gate in every action. This release brings authz to parity with the org/owner/team firewall: declare it once, the compiler enforces it everywhere, the runtime emits exactly one query per request.\n\n---\n\n## v0.22.0 — May 19, 2026\n\n### Quickback Stack is Cloudflare-only: one runtime, two databases, one auth provider\n\nWe've focused the platform on the stack we actually believe in: **Cloudflare Workers + Hono + Better Auth**, with **Cloudflare D1** or **Neon** as the database. Providers and modes that targeted non-Cloudflare backends are gone. The result is a smaller concept set, fewer footguns, and clearer docs.\n\n#### What's been removed\n\n- **Runtimes**: `bun` and `supabase-edge` are no longer supported. The only runtime is `cloudflare`. Local development for compiled projects has always used `wrangler dev` — that's unchanged.\n- **Databases**: `supabase`, `libsql`, `better-sqlite3`, `bun-sqlite` are removed. Use `cloudflare-d1` for SQLite at the edge or `neon` for PostgreSQL via Hyperdrive.\n- **Auth providers**: `supabase-auth` is removed. `better-auth` is the default; `external` (Cloudflare service binding) remains for advanced setups.\n- **Template**: `template: 'nextjs'` is removed from the public config type. It was never fully implemented. The only template is `'hono'`. If you need a Next.js frontend, bring it as a separate deploy and call the Quickback API, or drop a static export into the `apps:` mount.\n- **Quickback for Supabase RLS** product line is retired. The compiler no longer emits Supabase Row Level Security policies. The `/products/quickback-supabase-rls/` and `/for/supabase-users/` pages have been removed from the marketing site, and the `compiler/targets/supabase-rls/` docs section has been deleted.\n\n#### Account UI: one delivery mode\n\nThe standalone `quickback-better-auth-account-ui` npm package has been **deprecated** and the upstream GitHub repo (`Kardoe-com/quickback-better-auth-account-ui`) has been **archived**. Account UI is now exclusively delivered the way 99% of projects already use it: the compiler builds it from source and bundles it into your Worker.\n\n- `account: { domain: 'auth.example.com', ... }` in `quickback.config.ts` — that's the entire integration story.\n- The compiler builds the SPA inside Docker with your branding and feature flags baked in, emits hostname-based routing, and wires cross-subdomain cookies automatically.\n- The three standalone delivery-mode docs (`stack/account-ui/standalone`, `library-usage`, `worker`) are removed; the remaining pages explain the compiler-bundled flow.\n\nIf you previously deployed the standalone Account UI Worker against a Quickback backend, switch to `account: { domain }` in the config — same end result, one less deploy.\n\n#### `VITE_AUTH_ROUTE` hardcoded to Quickback\n\nThe `VITE_AUTH_ROUTE` env var (which used to switch between `quickback` and `better-auth` routing dialects) is gone. The auth-client always uses Quickback's namespaced routes (`/auth/v1`, `/api/v1`, `/storage/v1`). Generic Better Auth backends are no longer a supported target. Removing the var also closes a known footgun where setting the wrong value silently 404'd every auth call.\n\n#### New: every config option is now discoverable\n\nWhen you bootstrap a project, the kitchen-sink marker block in `quickback.config.ts` lists every option Quickback supports — with descriptions and sensible defaults — commented out for you to copy above the marker as needed. Three top-level options were missing from this discovery surface and are now included:\n\n- **`apps`** — mount your own prebuilt SPA on its own hostname (`apps: { www: { domain: 'www.example.com', aliasDomains: ['example.com'] } }`). Drop the build at `quickback/apps/<name>/` and the compiler serves it from your Worker alongside the API. Reserved names: `cms`, `account`, `public`.\n- **`security`** — HTTP security headers (CSP, COOP, COEP, HSTS, Referrer-Policy, Permissions-Policy, X-Frame-Options). Set `security: false` to suppress everything; defaults are sensible for the embedded SPAs.\n- **`authz`** — relationship-based authorization roles. Declare joins between the caller and a resource column, then bind role names to those joins for use in `access: { roles: [...] }`.\n\n#### Migration\n\nProjects that compile cleanly against v0.21 and use any of these providers will hit a clear error at compile time:\n\n```\nUnknown database provider: \"supabase\". Available: cloudflare-d1, neon\n```\n\nTo migrate:\n\n1. **From Supabase**: switch `providers.database` to `cloudflare-d1` or `neon`, and `providers.auth` to `better-auth`. Your `defineTable()` definitions transfer as-is; the security DSL (firewall, access, guards, masking) compiles to Better Auth + Drizzle queries instead of RLS policies.\n2. **From Bun runtime / `bun-sqlite`**: switch `providers.runtime` to `cloudflare` and `providers.database` to `cloudflare-d1`. Local dev becomes `wrangler dev`.\n3. **From libsql / Turso**: switch to `cloudflare-d1` or `neon`. Both run natively from Cloudflare Workers via the right binding.\n4. **From `template: 'nextjs'`**: deploy Next.js separately and call the Quickback API, or drop a static export into `apps:`.\n\n#### Why this matters\n\nThe Quickback Stack is the Supabase alternative for Cloudflare. Every Quickback project ships a Hono API, an Account SPA, a CMS SPA, optional realtime/storage/queues — all built from one config and bundled into one Worker. Keeping that promise focused is more valuable than supporting deployment targets that don't share the runtime.\n\n---\n\n## v0.21.0 — May 19, 2026\n\n### Auto-firewall column swap: `ownerId` is now canonical on feature tables, `userId` warns\n\nThe compiler's default auto-firewall column for feature tables flips from `userId` to `ownerId`. This closes a long-standing footgun where a `userId` column meaning \"a user this row references\" (a member, a contact, an invitee) got silently clobbered with `ctx.userId` on insert, because the wrapper matched purely on column name across every table in the project.\n\n**What changed in the compiler**\n\n- `BETTER_AUTH_DEFAULTS.owner.column`: `'userId'` → `'ownerId'`. Schemas with an `ownerId` column auto-resolve to `firewall: [{ field: 'ownerId', equals: 'ctx.userId' }]` and have `ownerId` auto-stamped on insert.\n- The generated `OWNER_SCOPE_RULES` in `src/lib/scoped-db.ts` is seeded with `ownerId` instead of `userId`. Schemas that don't explicitly name `userId` in a `firewall:` block no longer trigger the global `userId`-stamping rule — the most common collision goes away without renames.\n- A new compile-time warning fires when a feature table carries both an auto-resolved isolation column AND a `userId` column. The warning recommends renaming the column to `linkedUserId` (or similar) if it's informational, or declaring `firewall: [{ field: 'userId', equals: 'ctx.userId' }]` if it really is the access boundary on that table.\n- The targeted compile-time error for \"the only candidate column is `userId`\" now points users at `ownerId` and the explicit-firewall escape hatch. The previous error wording (which assumed `ownerId` was business-logic) is removed.\n\n**What stayed the same**\n\n- Better Auth's own internal tables (`session`, `account`, `member`, `passkey`, `subscriptions`) still use `userId` by convention. They aren't feature tables and don't pass through the auto-firewall.\n- Explicit `firewall: [{ field: 'userId', equals: 'ctx.userId' }]` declarations continue to work and are still recognized as the \"owner\" pattern in the generated comment header.\n- The `USER` pseudo-role validator behaviour is unchanged; only the error-message wording flips to lead with `ownerId` and list `userId` as the explicit fallback.\n- Audit-wrapper (`createdBy` / `modifiedBy`) behavior is untouched.\n\n**Migration**\n\nProjects that auto-firewalled on a `userId` column will see a hard error on next compile telling them which table is affected, with two suggested fixes:\n\n1. **Recommended**: rename the column to `ownerId` in the schema. Cleanest semantics — readers immediately understand the column is access-control.\n2. **Explicit firewall**: keep the `userId` column and add `firewall: [{ field: 'userId', equals: 'ctx.userId' }]` to the resource. The auto-stamping and auto-scoping still happen; you've just opted in by name.\n\nProjects that have a `userId` column meaning \"a user this row references\" no longer need the `linkedUserId` rename workaround — auto-stamping won't touch the column unless you name it in a firewall block. The new warning makes this audit-discoverable.\n\n**Caveat (deferred)**: explicit `firewall: { owner: { column: 'X' } }` declarations still populate the project-global `OWNER_SCOPE_RULES` list, so a hand-named owner column on one resource will still match by name on every other table that happens to have a column called `X`. A future release will make scope-rule resolution per-table rather than project-global. The warning text calls this out so callers know what to expect.\n\n---\n\n## v0.20.0 — May 19, 2026\n\n### CMS + Account SPAs: shadcn base-ui migration, central Tailwind config\n\nBoth first-party SPAs are now on the shadcn **base-ui** variants (`@base-ui/react`) instead of the Radix-based primitives, applied via shadcn preset **`bdvxIkMq`** (style `base-mira`, `baseColor: zinc`, `iconLibrary: remixicon`, Inter Variable font). The migration also collapses the previously duplicated per-SPA theme + `components.json` into a single source at `packages/ui/`.\n\n#### Single source of truth in `packages/ui/`\n\nBoth SPAs were independently declaring the same `@theme` / `:root` / `.dark` token blocks in their own `app.css`, and each had its own `components.json` pointing at non-existent local component directories. That's gone:\n\n- `packages/ui/styles/theme.css` — the only place tokens live. Includes the base-mira palette, sidebar + chart tokens, and the Inter font import.\n- `packages/ui/components.json` — the only shadcn config in the repo. Future `pnpm dlx shadcn@latest add <name>` runs from `packages/ui/`.\n- `packages/cms/app/app.css` and `packages/account/app/app.css` reduce to two imports plus SPA-specific layers (CMS keeps its AG Grid + richtext-display overrides). `packages/{cms,account}/components.json` deleted.\n\n#### Components, icons, deps\n\n- All 22 shadcn primitives regenerated against `@base-ui/react` (`@radix-ui/*` removed everywhere). `Drawer` stays on `vaul` — base-ui has no Drawer primitive.\n- Icons migrated from `lucide-react` to `@remixicon/react` line variants across ~100 source files (`Plus → RiAddLine`, `ChevronDown → RiArrowDownSLine`, `X → RiCloseLine`, etc.). `lucide-react` removed from all `package.json` + `deps-spa-*` files.\n- `pnpm.overrides` pin `@types/react ^19.2.0` workspace-wide to resolve the duplicate-React-types conflict introduced by `@base-ui/react`'s bundled type peer.\n- Per-SPA deps and the Docker build mirrors (`apps/compiler/deps-spa-{cms,account}-package.json`) both gain `@base-ui/react`, `@remixicon/react`, `@fontsource-variable/inter`, and bump `shadcn` to `^4.7.0`.\n\n#### Backwards-compat `asChild` shim\n\nBase-ui replaces Radix's `asChild` boolean with a `render={\n</Button>\n```\n\n`ResponsiveModal` survived the migration unchanged — it composes the higher-level Dialog + Drawer wrappers (preserved public API), not the underlying primitives.\n\n#### Caller-side API changes worth noting\n\nBase-ui ships some real behavioural changes the Radix variants didn't:\n\n- `<Select onValueChange>` now receives `(value: string | null, eventDetails) => void` (was `(value: string) => void`). Existing `Dispatch<SetStateAction<string>>` setters reject `null` — wrap callbacks defensively: `onValueChange={(v) => v != null && setX(v)}`.\n- `<DropdownMenuContent forceMount>` removed (base-ui has no `forceMount`). Use base-ui's `keepMounted` on the Popup/Positioner if you need to preserve unmounted state.\n- Component sub-names shifted (`Dialog.Content` → `Dialog.Popup`, `Dialog.Overlay` → `Dialog.Backdrop`). Data attributes are now `data-open` / `data-closed` (no more `data-state=\"open\"`).\n\n#### Adding a new primitive after this release\n\n```bash\ncd packages/ui\npnpm dlx shadcn@latest add <component> --overwrite --yes\n# Sweep generated `@/` imports to relative paths — the SPAs' vite-tsconfig-paths\n# plugin doesn't see packages/ui's @/* mapping at bundle time:\nsed -i.bak \\\n -e 's|\"@/lib/utils\"|\"../lib/utils\"|g' \\\n -e 's|\"@/components/|\"./|g' \\\n -e 's|\"@/hooks/|\"../hooks/|g' \\\n components/<component>.tsx && rm components/<component>.tsx.bak\n```\n\nIf the new primitive pulls in fresh deps, mirror them into `apps/compiler/deps-spa-{cms,account}-package.json` per the SPA build pipeline or Docker SPA builds will fail.\n\n---\n\n## v0.18.1 — May 18, 2026\n\n### Account SPA — teams, active-team picker, permission-aware UI\n\nThe Account SPA's organization surface is now feature-parity with Better Auth's `organization` plugin for the basic team workflow, and replaces the long-standing hardcoded `role === 'owner' || 'admin'` checks with `checkRolePermission` so projects that ship custom roles get a UI that respects them.\n\n#### Teams (opt-in)\n\nWhen the BA config enables teams — `organization({ teams: { enabled: true } })` — the compiler emits `VITE_ENABLE_ORG_TEAMS=true` and the Account SPA exposes a Teams tab on each organization:\n\n- **Teams index** (`/$slug/teams`) — splits into \"Your teams\" (from `listUserTeams`) and \"Other teams\" so non-admins land on what's relevant. Create / rename / delete from the list, gated on `team:create` / `team:update` / `team:delete`.\n- **Team detail** (`/$slug/teams/$teamId`) — member roster with add / remove, joining `listTeamMembers` against the org's full member list for display.\n- **Active-team picker** in the org header — calls `setActiveTeam` and exposes the choice via `OrganizationContext.activeTeamId` so downstream routes (and the BA `session.activeTeamId` server-side) stay in sync.\n- **Team-aware invites** — `InviteMemberDialog` shows an optional team picker when teams are on and forwards `teamId` to `inviteMember`, so accepting the invite drops the new member straight into the right team.\n\nTeams are loaded once by the `$slug` layout (`listTeams` + `listUserTeams`) and exposed via `OrganizationContext.teams` / `userTeamIds` / `refreshTeams`, so individual team routes don't re-fetch the list.\n\n#### Permission-aware UI via `checkRolePermission`\n\n`OrganizationContext.isOwnerOrAdmin` is gone. Routes now read `can(resource, action)` from context, which delegates to `authClient.organization.checkRolePermission` — synchronous, no roundtrip, and aware of any custom roles registered via the BA `ac` option. Multi-role users (BA stores multiple roles comma-separated) are handled by checking each role; the action is allowed if any role grants it.\n\nMigrated sites:\n\n- `$slug.tsx` tab gates → `can('invitation', 'create')`, `can('organization', 'update')`\n- `members.tsx` action menu → `can('member', 'update' | 'delete')`; the owner-hierarchy guard (non-owners can't touch owner-role members) is preserved as a client-side mirror of BA's server enforcement\n- `invitations.tsx` → `can('invitation', 'create' | 'cancel')` gates the Invite button, resend, and cancel separately\n- `settings.tsx` → `can('organization', 'update')` for the form, `can('organization', 'delete')` for the danger zone (was owner-only)\n- `teams.tsx` / `teams.$teamId.tsx` → `can('team', 'create' | 'update' | 'delete')`\n\nProjects on the default three-role hierarchy see no behaviour change; projects that defined `admin`/`member` overrides via BA's access-control API now get a UI that matches what the server will actually authorize.\n\n#### Editable slug + metadata on organization settings\n\nThe `$slug/settings.tsx` form now edits two more `organization.update` fields:\n\n- **URL slug** — full debounced `checkSlug` flow (mirroring the create-org form); on rename, the SPA navigates to `/${newSlug}/settings` and the layout re-fetches with the new slug.\n- **Metadata** — single `Record<string, any> | null` JSON textarea, parsed on submit with inline error messaging. Empty clears the field.\n\nSlug rename is non-breaking for the SPA itself, but every external link / bookmark that references the old slug becomes a 404 — the form warns about this before saving.\n\n#### Auth client wiring\n\nWhen `VITE_ENABLE_ORG_TEAMS=true`, the SPA's `organizationClient(...)` is instantiated with `teams: { enabled: true }` so the team APIs are typed end-to-end. When the flag is off, team methods aren't surfaced — and the Teams tab is hidden — keeping the bundle and UI honest about what the server actually supports.\n\n---\n\n## v0.18.0 — May 17, 2026\n\n### `config.apps` — mount user-authored SPAs on dedicated hostnames\n\nThe compiler now generates per-hostname Worker middleware for arbitrary user SPAs alongside the built-in CMS and Account UIs. Previously the only way to host a product app next to a Quickback API was a second Worker; `config.apps` brings the full stack — API, account, and product UI — onto one deployment with same-origin auth.\n\n```ts\napps: {\n www: {\n domain: \"www.example.com\",\n aliasDomains: [\"example.com\"], // apex serves the same SPA\n },\n}\n```\n\nEach entry binds one or more hostnames to a directory under `src/apps/<name>/` and inherits the Account-domain pass-through behavior — `/api/`, `/auth/`, `/admin/`, `/storage/`, and `/health` route to Hono so the SPA fetches its API without CORS. The compiler:\n\n- emits a `custom_domain = true` route in `wrangler.toml` for the primary hostname and every alias\n- adds each hostname to Better Auth's `TRUSTED_ORIGINS` (when `trustedOrigins` is left unset)\n- widens the CSP `connect-src` to cover the SPA-baked origins\n- folds the new hostnames into shared-parent detection for `crossSubDomainCookies`\n\nDrop the prebuilt SPA bundle at `quickback/apps/<name>/` — the existing source-apps passthrough copies it byte-for-byte into `src/apps/<name>/`. The compiler doesn't build the SPA; it only emits routing for whatever's already there. The names `cms`, `account`, and `public` are reserved; hostname collisions with `cms.domain` / `account.domain` / `account.adminDomain` or between two `apps[*]` entries fail at compile time.\n\nWhen `cms` and `account` are both configured, the multi-domain catchall now explicitly skips app hostnames — an API miss on an app host returns the standard 404 JSON via `app.notFound` instead of stray-serving a sibling SPA's HTML shell.\n\n### Cross-subdomain cookie inference handles apex aliases\n\nThe shared-parent detection that drives `advanced.crossSubDomainCookies` previously reduced any hostname by stripping the leftmost label — `'example.com'` collapsed to `'com'`, which broke equality against sibling subdomains. Apex hostnames (exactly two dot-segments) are now treated as already being the parent, so apex aliases (`example.com` listed alongside `www.example.com`) coexist cleanly with `auth.example.com` / `cms.example.com` and the compiler still emits `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`.\n\n---\n\n## v0.17.2 — May 15, 2026\n\n### `customPlugins` escape hatch on `defineAuth(\"better-auth\", …)`\n\nThe Better Auth provider now accepts `customPlugins` alongside the named-plugin registry — a path to ship third-party plugins (`@better-auth-kit/audit`, …), unregistered built-ins, or one-off project-local plugins without forking the compiler.\n\nEach entry is an explicit import descriptor:\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: { passkey: true, organization: true },\n customPlugins: [\n // (1) Project-local plugin file at quickback/plugins/long-session.ts\n { from: \"./plugins/long-session\", export: \"longSessionPlugin\" },\n // (2) Third-party npm package\n {\n from: \"@better-auth-kit/audit\",\n export: \"auditPlugin\",\n args: { events: [\"sign-in\"] },\n dependencies: { \"@better-auth-kit/audit\": \"^1.0.0\" },\n },\n ],\n}),\n```\n\n`from` is either a relative path under `./plugins/` (the CLI auto-uploads matching files from `quickback/plugins/`; the compiler copies them into `src/plugins/<name>.ts` and rewrites the emitted import) or a bare npm specifier (emitted verbatim; declare `dependencies` so the package lands in the generated `package.json`). Omit `args` to emit the symbol uncalled (plugin instance); provide `args` to emit a JSON-serialized factory call.\n\nThe descriptor is validated with Zod — typos in `from`/`export`, paths that escape `./plugins/`, and references to files the CLI didn't ship all fail at compile time with a targeted message.\n\n---\n\n## v0.17.1 — May 14, 2026\n\n### `quickback start` — interactive onboarding\n\n```bash\nmkdir my-app && cd my-app\nnpx @quickback-dev/cli start\n```\n\n`start` walks new users through template selection, scaffolds the project on disk, and only prompts for an account when it's ready to compile. Cancelling at the login prompt leaves the scaffold intact — sign in and run `quickback compile` whenever you're ready.\n\nThe same deferred-auth flow applies to `quickback create`. Scaffolding and (optional) Cloudflare D1 setup run before authentication, so you can preview the project on disk before committing to an account.\n\n### Named views on the free tier\n\nThe `todos` template now ships a `dashboard` named view, exposing a projected response at `GET /api/v1/todos/views/dashboard`. Named views support per-view access rules and per-view field selection while inheriting the table's firewall and masking — the canonical way to ship list-view payloads that are cheaper to fetch and easier to cache than a full collection read.\n\n### `quickback init` removed\n\nFolded into `start` and `create`. The legacy command name prints a deprecation notice pointing at its replacements.\n\n### Minor\n\n- `quickback whoami` reads the stored tier from your credentials.\n- Pro upsell copy in `quickback login` is shown only when the server returns an explicit free-tier subscription.\n- Bare scaffolds (`cloudflare`, `empty`) report accurately when there are no features to generate migrations for.\n\n---\n\n## v0.16.10 — May 14, 2026\n\n### D1-specific safety pass on generated migrations\n\nThe `cloudflare-d1` provider now runs a post-generation pass over every Drizzle migration directory (auth, features, webhooks, audit) before the compile finishes. Better Auth cleanup for retired managed tables is stripped from raw `DROP TABLE` statements. Drop-only cleanup migrations are reordered child-first when foreign-key dependencies require it. Every generated D1 migration directory is replayed against SQLite during compile, so a D1-breaking migration fails at compile time rather than at `wrangler d1 migrations apply`.\n\n---\n\n## v0.16.9 — May 13, 2026\n\n### Resource-scoped realtime tickets\n\n`providers.database.config.realtime` accepts an object form for projects whose WebSocket subscribers aren't org members:\n\n```ts\nrealtime: {\n wsTicket: {\n role: \"attendee\",\n requestField: \"eventId\",\n scopeTable: \"events\",\n },\n}\n```\n\nThe generated `/broadcast/v1/ws-ticket` route authenticates the caller, evaluates the declared relationship role against the request, and mints a short-lived WebSocket ticket scoped to the resolved resource. `realtime: true` continues to enable the org-scoped broadcaster.\n\n### Unified broadcast targeting\n\nThe realtime helper and Broadcaster now route by `scopeKey || organizationId || userId`. String targets remain shorthand for `organizationId`; explicit targets can scope a broadcast to a resource or a single user:\n\n```ts\nawait realtime.broadcast(\"event-page-updated\", payload, { scopeKey: \"events:evt_123\" });\nawait realtime.broadcast(\"dm\", payload, { userId: recipientId });\n```\n\nWebSocket tickets are Quickback-minted (signed with `BETTER_AUTH_SECRET`), not Better Auth tokens — Better Auth remains the front-door auth check; Quickback signs the upgrade ticket after authorization succeeds.\n\n---\n\n## v0.16.8 — May 13, 2026\n\n### One auth transport per request\n\nGenerated middleware treats `Cookie`, `Authorization: Bearer`, and `x-api-key` as distinct auth methods and rejects mixed requests with `400 AUTH_METHOD_CONFLICT`. Query-string API keys (`?api_key=` / `?key=`) are no longer accepted. Machine-to-machine auth is explicit; precedence rules between transports are gone.\n\n### Cookie-backed CSRF gate\n\nGenerated apps now block cross-site `POST` / `PUT` / `PATCH` / `DELETE` requests from cookie-relying callers. The middleware skips explicit `Authorization` clients, requires a trusted `Origin` or `Referer`, and blocks `Sec-Fetch-Site: cross-site`. This matters most for cross-subdomain session setups where `SameSite=None` is intentional.\n\n### First-class Wrangler observability\n\n`providers.runtime.config.observability` now supports nested `logs` / `traces` blocks for `headSamplingRate`, `destinations`, `persist`, and `logs.invocationLogs`, emitting matching `[observability]`, `[observability.logs]`, and `[observability.traces]` TOML.\n\n---\n\n## v0.16.7 — May 12, 2026\n\n### Bearer wins over cookie\n\nA request carrying both `Authorization` and a session `Cookie` resolves entirely from the bearer; the cookie is dropped before `getSession()` runs. All three Bearer flavors (API key, JWT, session-token) now behave consistently — no more silent cookie precedence on session-token bearers.\n\n### Bearer plugin defaults to `requireSignature: true`\n\nBetter Auth's `bearer` plugin defaults to unsigned tokens; Quickback now emits `bearer({ requireSignature: true })`. Tokens emitted in the CORS-exposed `set-auth-token` header are server-signed with `BETTER_AUTH_SECRET` and verified on every request. Projects that genuinely need unsigned bearers can override via `providers.auth.config.plugins.bearer`.\n\nSee [Authentication Security → Bearer Tokens and Cookie Precedence](/stack/auth/security#bearer-tokens-and-cookie-precedence).\n\n---\n\n## v0.16.5 — May 12, 2026\n\n### Flat write DSL\n\nResource write operations are now declared at the table level alongside `read`, replacing the nested `crud` block:\n\n```ts\ndefineTable(customers, {\n read: { ... },\n create: { access: { roles: [\"admin\"] } },\n update: { access: { roles: [\"admin\"] } },\n delete: { access: { roles: [\"admin\"] }, mode: \"soft\" },\n upsert: { access: { roles: [\"admin\"] } },\n guards: { ... },\n});\n```\n\n`crud` and top-level `put` still compile as deprecated compatibility aliases. Mixed usage on the same resource is rejected. `schema-registry.json` emits both shapes during the transition.\n\n### CMS placement for multi-table feature actions\n\nStandalone actions on multi-table features have an explicit placement model:\n\n- `cms.placement: \"feature\"` shows the action on every table toolbar in the feature\n- `cms.placement: \"tables\"` with `cms.tables` scopes it to specific tables\n- `cms.hidden: true` keeps it API-only\n\nFeature-root standalone actions are emitted under a new `featureActions` bucket in `schema-registry.json`. Ambiguous multi-table standalone actions without placement compile with a warning.\n\n### `openapi.types` accepts a string array\n\nOne compile can write the generated types file to multiple locations, keeping colocated SPA clients in sync:\n\n```ts\nopenapi: { types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'] }\n```\n\n### Stable artifact ordering\n\nGenerated route files and `schema-registry.json` are emitted in a stable order across runs. Identical logical input produces identical artifacts.\n\n---\n\n## v0.16.4 — May 12, 2026\n\n### Drizzle snapshot integrity\n\nDrizzle metadata files (`<n>_snapshot.json`) are no longer stamped with a Quickback warning key. The warning is now journal-only. Projects whose snapshots were corrupted by an earlier release self-heal on the next compile — the stripped header is removed during staging and the rewritten snapshot is clean.\n\n### `account.auth.*` drives the server, not just the SPA\n\nThe Account UI's auth flags (`signup`, `password`, `passkey`, `emailOTP`, `emailVerification`) now configure the Better Auth server alongside the SPA bundle. A normalizer maps them into the server config:\n\n- `signup → emailAndPassword.disableSignUp` (inverted)\n- `password → emailAndPassword.enabled`\n- `emailVerification → emailAndPassword.requireEmailVerification`\n- `passkey` / `emailOTP` → plugin additions\n\nThe SPA's `VITE_ENABLE_*` flags are derived from the same canonicalized server config, so the bundle and the server cannot drift. Two new flags ride along: `VITE_ENABLE_API_KEYS` and `VITE_ENABLE_MAGIC_LINK`.\n\n**Breaking** for projects that implicitly relied on the SPA-only behaviour: `account.auth.signup: false` now actually disables `POST /auth/v1/sign-up/email` on the server. Set `providers.auth.config.emailAndPassword.disableSignUp: false` explicitly to keep server signup open while hiding the SPA screen.\n\n---\n\n## v0.16.3 — May 9, 2026\n\n### Standalone action mount order\n\nFeature-level standalone action routers now register before sibling CRUD routers when both mount at the exact same prefix. A literal path like `GET /api/v1/records/today-bundle` resolves to the standalone handler instead of falling through to `GET /:id` and treating `\"today-bundle\"` as a record ID.\n\n---\n\n## v0.16.1 — May 9, 2026\n\n### Cloudflare ASSETS canonicalization\n\nWorker SPA fallbacks now request `/<dir>/` instead of `/<dir>/index.html`. Cloudflare's static-assets binding rewrites `/index.html` requests as 307 redirects to the trailing-slash path under the default `html_handling=auto-trailing-slash`, which previously caused redirect loops in SPA fallback handlers. Affects CMS, Account, admin, and the multi-domain catchall.\n\n### `account.customLogin`\n\nSet `account: { customLogin: true }` to drop a project-branded sign-in page in front of the bundled SPA. Place the page at `quickback/public/account/login/index.html` (as a directory) and the existing public passthrough serves it. The route registers before the `/account/*` SPA catch-all so the static handler wins; everything else under `/account/` continues to route through the bundled SPA.\n\n### Project-level realtime defaults\n\n`providers.database.config.realtime: true` now treats every resource as realtime-enabled by default. Per-resource `realtime: { enabled: false }` still wins.\n\n### Compile-time validators\n\nTwo new compile-time errors over silent runtime failures:\n\n- `AUTHENTICATED` + org-scoped firewall is rejected. The combination silently returned empty lists to sign-in-only callers who lacked an active org; the validator names three valid resolutions (drop the org scope, use `USER`, or split the route).\n- `createRealtime` imports without `realtime: true` enabled in the config are rejected at compile.\n\n### Drizzle metadata hardening\n\nDrizzle journal files carry a \"do not edit\" header. The compiler warns when the journal entry count exceeds the snapshot file count (typically the trace of a hand-deleted snapshot).\n\n### Minor\n\n- `SYSADMIN` is now recognised by the standalone-action org gate's pseudo-role matcher.\n- Apex `/` and `/account/login` get fallback redirects to `auth.loginUrl` when neither bundled SPA is enabled.\n- Record-based action URLs are kebab-case to match the OpenAPI spec (e.g. `/api/v1/widgets/:id/send-invite`).\n\n---\n\n## v0.16.0 — May 9, 2026\n\n### Agent Auth Protocol\n\nQuickback ships a server implementation of the [Agent Auth Protocol](https://agentauthprotocol.com) via `@better-auth/agent-auth`. Enable with `auth.plugins.agentAuth: true` and the compiler emits the full agent-auth surface: discovery at `/.well-known/agent-configuration`, capability projection from the project's OpenAPI spec, a device-authorization approval page in the Account SPA at `/agents/approve`, and the four agent-auth tables added to the auth schema automatically.\n\n**OpenAPI capability projection runs by default.** Every operation with an `operationId` becomes an agent capability. Default `approvalStrength` map: `GET → \"session\"`, `POST/PUT/PATCH/DELETE → \"webauthn\"`. The proxy `onExecute` makes a self-fetch with a Better Auth JWT minted for the agent session, so the inner request hits the existing JWT fast-path and runs the full firewall + access + masking pipeline. Opt out of OpenAPI projection with `agentAuth: { fromOpenAPI: false }` and wire `capabilities` + `onExecute` by hand.\n\n### Bearer-only on `/mcp` and the agent-auth surface\n\n`/mcp` forwards only `Authorization: Bearer …` into the inner request. Cookie and `x-api-key` forwarding are removed. Three Bearer flavors land on the same header — Better Auth session token (via the `bearer` plugin), OAuth access token (via OAuth Provider), and agent JWT (via `@better-auth/agent-auth`).\n\n### Auth DSL gains first-class plugin entries\n\n`bearer`, `oauthProvider`, and `agentAuth` are now typed entries in both the array-form union and the `BetterAuthPlugins` interface, with their own options shapes (`OAuthProviderOptions`, `AgentAuthOptions`). Existing `as any` casts can come out.\n\nAuto-enable rule: turning on `agentAuth` force-adds `bearer` + `oauthProvider`. No useful agent-auth deployment ships without those two.\n\n### `queue-consumer.ts` gating\n\nThe queue consumer is emitted when any of the following are true: embeddings are configured, queue handlers exist under `services/queues/*`, or `additionalQueues` is declared. Previously the third case left projects with a wrangler binding pointing at a missing handler.\n\n---\n\n## v0.15.0 — May 7, 2026\n\n### Sysadmin tier for the CMS\n\nA new opt-in `cms: { sysadmin: true }` flag turns the CMS into a cross-tenant DB-admin tool gated by `user.role === 'sysadmin'`. Distinct from the Better Auth `'admin'` plugin role, so user-management powers and DB-admin powers stay decoupled. Off by default.\n\nWhen enabled, the compiler emits a `SYSADMIN` pseudo-role (a fifth marker alongside `PUBLIC` / `AUTHENTICATED` / `USER` / `ADMIN`), a firewall escape hatch that drops tenant scopes for sysadmins while preserving soft-delete, a true cross-tenant `/admin/v1/sysadmin/organizations` endpoint, and a relaxed cross-tenant guard for list routes.\n\nThe CMS SPA gains a two-mode design: org admins keep the existing membership-based switcher, sysadmins get an \"All organizations\" selector that pins tenants via `?organizationId=` on every API call.\n\n### Durable Object `[[migrations]]` order is preserved\n\nCloudflare's migration list is append-only. The compiler now reads your existing `wrangler.toml` (when present) and emits auto-generated DO `[[migrations]]` blocks in two phases: deployed entries first (preserving order), net-new entries appended last. Reordering DOs in the config array no longer reshuffles deployed migrations.\n\n### `quickback/public/` — static-asset passthrough\n\nAnything dropped under `quickback/public/` is copied verbatim into `src/apps/` on every compile and served by the wrangler `[assets]` binding. Use for favicons, `robots.txt`, OG images, `.well-known/` files, marketing PDFs — anything that needs to ride past the compiler as bytes.\n\n- Optional. Missing folder is a no-op.\n- Stale-cleaned. Files removed from `quickback/public/` disappear on the next compile.\n- Hidden entries (`.DS_Store`, dotfiles) are skipped.\n- Collisions with compiler-emitted manifest paths fail the compile loudly.\n\n### Minor\n\n- Standalone-action wrapper skips the org gate when the access tree references any pseudo-role.\n- Queue handler emit no longer drops the `queue` export when there are no embeddings.\n\n---\n\n## v0.14.7 — May 7, 2026\n\n### Codegen fixes for projects with non-`id` primary keys and DO-only features\n\nFour surgical fixes to the generated output:\n\n- Duplicate table imports in relationship-role routes are deduplicated.\n- `db` references in single-record and bulk action handlers now resolve correctly during pre-fetch.\n- PartyServer auth gates pass the in-scope `db` handle into firewall calls.\n- Durable-object-only features keep their `lib/` files in the output.\n\n### `emailOtp` + AWS SES is OTP-only\n\n`auth.emailOtp` with the AWS SES email provider no longer auto-wires the magic-link companion. Mail-client URL prefetching can burn the one-time code before the human sees it; the Account SPA's `/email-otp` route is the single canonical entry point. Projects that explicitly want the magic-link arm can wire `sendVerificationOTP` directly.\n\n---\n\n## v0.14.6 — May 7, 2026\n\n### MCP transport correctness\n\nFour fixes to the MCP-over-HTTP path:\n\n- `tools/call` URLs are no longer double-prefixed for action tools.\n- Auth middleware accepts API keys via `Authorization: Bearer` in addition to `x-api-key` and query parameters — the channel MCP clients use exclusively.\n- `auth.roleHierarchy` is expanded for runtime role checks across api-key, JWT, and session auth paths. A higher role inherits the privileges of every lower role.\n- Team-scoped firewall predicates degrade gracefully when no team is active (org scoping continues to apply; team scoping is optional).\n\n---\n\n## v0.14.5 — May 7, 2026\n\n### MCP environment threading\n\nThe generated MCP server's `tools/call` dispatch threads `env` and `executionCtx` into the inner request, so action tools that touch Cloudflare bindings (D1, KV, R2, Queues) no longer crash with `undefined` env access.\n\n---\n\n## v0.14.4 — May 7, 2026\n\n### `via:` firewall predicates pull required imports\n\nThe relationship-role generator emits `inArray` and `sql` imports when the firewall has any `via:` predicate, and `buildFirewallConditions` accepts `(ctx, db)` so the relationship subquery has a Drizzle client to evaluate against. Every CRUD and action call site passes `db` through automatically.\n\n---\n\n## v0.14.3 — May 7, 2026\n\n### Relationship-role table re-exports\n\nGenerated `<table>.resource.ts` files now re-export their Drizzle table binding. Cross-feature relationship subqueries that import the binding from the resource file (rather than the schema) resolve correctly.\n\n---\n\n## v0.14.2 — May 7, 2026\n\n### Historical DO `[[migrations]]` are preserved\n\nA new `bindings.durableObjectMigrations` config slot carries forward `deleted_classes`, `renamed_classes`, and `transferred_classes` lifecycle entries across recompiles. Cloudflare's migration list is append-only; entries declared here are emitted first in `wrangler.toml`, then auto-generated current-class entries follow:\n\n```ts\nbindings: {\n durableObjects: [{ name: 'NOTEPAD', className: 'Notepad', from: 'lib/Notepad' }],\n durableObjectMigrations: [\n { tag: 'qb-do-deleted-legacy-notes-2026-05-05', deletedClasses: ['LegacyNotes'] },\n ],\n}\n```\n\nAll four lifecycle shapes are supported. User-declared entries can override auto-emit by reusing the same tag.\n\n---\n\n## v0.14.1 — May 7, 2026\n\n### Bulk action variants in `openapi.json`\n\nRecord-based actions with `bulkVariant: true` are now emitted as sibling operations in the OpenAPI spec, with the documented `{ ids, input, failFast? }` request shape, 200/207/400 responses, and a separate `<Resource><Action>Bulk` `operationId` so typed-client codegen distinguishes single from bulk.\n\n### Cross-tenant \"my events\" patterns\n\nThe access docs now include a worked example for the cross-tenant aggregation pattern (e.g. `GET /my-events` returning resources across all tenants a caller is invited to). See [Access → Cross-tenant dashboards](/compiler/definitions/access#cross-tenant-my-events-dashboards-are-not-this).\n\n---\n\n## v0.14.0 — May 7, 2026\n\n### Relationship-based authorization\n\nRoles can now be bound to a domain-table membership (\"user is a confirmed guest of this event\") rather than an org membership or a pseudo-role. Declare the relationship once and reference it from `firewall:` or `access.roles:`:\n\n```ts\nauthz: {\n relationships: {\n guestOf: {\n from: 'event_guests',\n subject: { column: 'userId', equals: 'ctx.userId' },\n resource: { column: 'eventId' },\n where: { status: 'confirmed' },\n },\n },\n roles: {\n guest: { via: 'guestOf' },\n eventStaff: { or: [{ via: 'guestOf' }, { roles: ['admin', 'owner'] }] },\n },\n}\n\n// features/sessions/sessions.ts\nfirewall: [\n { field: 'organizationId', equals: 'ctx.activeOrgId' },\n { field: 'eventId', via: 'guestOf' },\n],\nread: { access: { roles: ['admin', 'member', 'guest'] } },\ncreate: { access: { roles: ['admin', 'guest'] } },\nupdate: { access: { roles: ['admin'] } },\n```\n\nThe compiler emits an inline Drizzle subquery against the relationship table and AND-composes it as the outermost firewall clause. The relationship table's own firewall (tenant scope, soft-delete) is honored inside the subquery; cross-tenant grants are impossible because the resource's tenant filter sits outermost.\n\nSupported surfaces: row-level scoping via `firewall: [{ field, via }]`, role gates on writes and reads, view access. Masking and action access reject relationship-roles at compile time with pointers to the working pattern (gate the row at the firewall layer, gate the role at the access layer).\n\nCross-tenant aggregation dashboards aren't solved by relationship-roles — the tenant firewall remains the outermost AND. For that pattern, use a user-scoped firewall or function-form access on a dedicated route.\n\nSee [Firewall → Relationship-based scoping](/compiler/definitions/firewall#relationship-based-scoping-via) and [Access → Relationship-based authorization](/compiler/definitions/access#relationship-based-authorization).\n\n### Bulk variants on record-based actions\n\n`defineAction({ bulkVariant: true })` emits `POST /:resource/batch/{action}` alongside the per-record route. The bulk handler loops the same access + transition + execute pipeline over a `{ ids, input, failFast? }` body:\n\n```ts\nexport default defineAction({\n description: \"Move an application forward in the pipeline.\",\n input: z.object({ nextStatus: z.enum([\"screening\", \"interview\", \"offer\"]) }),\n access: { roles: [\"owner\", \"admin\"] },\n bulkVariant: true,\n transition: { field: \"status\", via: \"nextStatus\", fromTo: { /* ... */ } },\n async execute({ db, record, input, whereTransition }) {\n // exact same body — runs once per id\n },\n});\n```\n\nPer-record outcomes return as 207 Multi-Status. `failFast: true` aborts on the first failure and wraps the loop in `db.transaction()` on tx-supporting providers; D1 fails fast without rollback. Max 100 IDs per request. Rejected on standalone actions and `unsafe` actions.\n\n### Aggregations on read views\n\nRead views can declare pre-computed metrics that surface alongside the row payload:\n\n```ts\nread: {\n views: {\n pipeline: {\n fields: [\"id\", \"jobId\", \"candidateId\", \"status\", \"appliedAt\"],\n aggregations: {\n totalApplications: { fn: \"count\" },\n byStatus: { fn: \"groupBy\", field: \"status\" },\n },\n },\n },\n}\n```\n\nAggregations run over the same firewalled, filtered set as the row query; pagination is intentionally ignored. Supported functions: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `groupBy`. See [Views → Aggregations](/compiler/definitions/views#aggregations).\n\n---\n\n## v0.13.5 — May 6, 2026\n\n### Object-form `auth.plugins` config is honored\n\nThe documented `plugins: { oauthProvider: {...} }`, `plugins: { organization: { teams: { enabled: true } } }` shapes now flow through the compiler unchanged. Per-plugin options reach the generated `auth.ts` as written.\n\n### `roles: [\"PUBLIC\"]` allowed on writes and actions\n\n`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access on every access node — reads, writes, views, and actions. The runtime trusts the marker; row-level safety comes from firewall, masking, and the action's own validation. `PUBLIC` actions continue to receive mandatory audit logging.\n\nCommon pattern: pair `roles: [\"PUBLIC\"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.\n\n---\n\n## v0.12.0 — May 5, 2026\n\n### Per-room authorization for PartyServer\n\n`bindings.durableObjects[].access` declares a path-scoped gate that runs the declared resource's firewall and `read.access` pipeline before the WebSocket upgrade:\n\n```ts\ndurableObjects: [\n // Single-resource: roomId IS the chat row id.\n { name: 'Chat', className: 'Chat', from: 'lib/Chat',\n access: { resource: 'chats' } },\n\n // Multi-resource: regex dispatches kind → resource.\n { name: 'Notepad', className: 'Notepad', from: 'lib/Notepad',\n access: {\n roomId: { pattern: '^(day-note|interaction|record):([A-Za-z0-9_-]+)$', kindGroup: 1, idGroup: 2 },\n resources: {\n 'day-note': { resource: 'day-notes' },\n 'interaction': { resource: 'interactions' },\n 'record': { resource: 'records' },\n },\n } },\n\n // Anonymous lobbies / public pads: explicit opt-out.\n { name: 'PublicLobby', className: 'PublicLobby', from: 'lib/PublicLobby',\n access: 'public' },\n]\n```\n\nThe gate 401s unauthenticated callers, 403s when the firewall hides the row, 404s when the row is missing. Resource references are validated against feature names at compile time. See [PartyServer Rooms → Per-room authorization](/stack/realtime/partyserver-rooms#per-room-authorization-via-access-v012).\n\n---\n\n## v0.11.1 — May 5, 2026\n\n### PartyServer auto-mount is secure by default\n\nThe `/realtime/*` auto-mount now wraps `partyserverMiddleware` in an auth check. Unauthenticated upgrades return 401; the four auth mechanisms (session cookie, JWT bearer, `x-api-key` header, query parameter) all unlock connections. Per-room access remains the `Server` class's responsibility in `onConnect`.\n\n---\n\n## v0.11.0 — May 5, 2026\n\n### OAuth Provider (MCP-ready)\n\nQuickback can act as a standards-compliant OAuth 2.1 + OIDC authorization server via [`@better-auth/oauth-provider`](https://better-auth.com/docs/plugins/oauth-provider). Enable with `plugins: [\"oauthProvider\"]`. The compiler auto-includes Better Auth's `jwt` plugin and the Account SPA gains a `/consent` page for the standard authorization-code flow.\n\nThis replaces Better Auth's deprecated `mcp` plugin and gives every MCP client (Cursor, Claude Desktop, claude.ai connectors, custom tooling) RFC 7591 dynamic client registration plus the discovery documents they need to bootstrap. See [Auth Plugins → OAuth Provider](/stack/auth/plugins#oauth-provider-mcp-ready).\n\n### API keys via query parameter\n\nThe auth middleware now accepts API keys as `?api_key=…` or `?key=…` query parameters. The `x-api-key` header takes precedence when both are sent. Prefer the header whenever the client supports it — query parameters land in access logs and `Referer` headers.\n\n### PartyServer rooms + realtime URL split\n\nThe realtime URL space is reorganized so names match what each primitive does:\n\n- **`/realtime/v1/*` → `/broadcast/v1/*`** — the org-wide Broadcaster moves to its semantically accurate prefix.\n- **`/realtime/<binding>/<room-id>`** — new mount for [PartyServer](/stack/realtime/partyserver-rooms) rooms. Per-room Durable Objects with presence and lifecycle hooks. Auto-mounted whenever a project declares any in-worker DO.\n\n**Breaking** — recompile + redeploy required:\n\n- `REALTIME_URL` env var renamed to `BROADCAST_URL`.\n- SPA helpers `getRealtimeWsUrl()` / `getRealtimeTicketUrl()` renamed to `getBroadcastWsUrl()` / `getBroadcastTicketUrl()`.\n- `appConfig.routes.api.realtime` renamed to `appConfig.routes.api.broadcast`.\n\n`partyserver`, `partysocket`, and `hono-party` are pre-installed in the compiler image; collab projects compile without an extra `npm install` step.\n\n---\n\n## v0.10.20 — May 4, 2026\n\n### In-worker Durable Objects\n\n`bindings.durableObjects[].from` flips a DO binding into in-worker mode and emits the export, the `[[migrations]]` block, and the `CloudflareBindings` type all together:\n\n```ts\ndurableObjects: [{\n name: \"ITEM_STREAM\",\n className: \"ItemStream\",\n from: \"features/loops/lib/ItemStream\",\n}]\n```\n\nDO class files live under `quickback/lib/` or `quickback/features/<feature>/lib/` — both copy verbatim into the generated `src/` tree on every compile. `from` and `scriptName` are mutually exclusive; cross-worker DOs (`scriptName` set) skip the re-export and migration block.\n\n`migrationTag` (default `qb-do-${className}`) is stable across regenerations and must never be removed or renamed once deployed. `useSqlite` defaults to `true`. See [Bindings → Durable Objects](/compiler/config/bindings#durableobjects).\n\n---\n\n## v0.10.18 — May 2, 2026\n\n### `experimentalRemote` — share deployed D1 with `wrangler dev`\n\nPer-binding `experimental_remote = true` lets `wrangler dev` read/write deployed D1 for selected bindings:\n\n```ts\nproviders: {\n database: defineDatabase(\"cloudflare-d1\", {\n splitDatabases: true,\n experimentalRemote: { auth: true, features: false },\n }),\n}\n```\n\nUseful for \"share prod auth in dev, keep feature writes sandboxed.\" Off by default.\n\n### Google OAuth + signup ToS\n\nThe Account SPA wires Google OAuth end-to-end when configured under `auth.config.socialProviders.google.enabled`. The signup flow gains a Terms-of-Service checkbox gate (configurable via the Account SPA branding).\n\n### CLI compile auth gate\n\n`quickback compile` now requires authentication for cloud-compiler runs. Device-flow `?redirect=` parameters are standardized across the login + signup pages so a user clicking \"Create one\" no longer loses their return URL.\n\n---\n\n## v0.10.15–v0.10.17 — May 2, 2026\n\n### CSP auto-config\n\nWhen `security.csp` is set, the compiler widens directives additively based on the project's enabled features:\n\n| Trigger | Auto-added | Directive |\n|---|---|---|\n| `cms: true` OR `account: true` | `'unsafe-inline'`, `https://fonts.googleapis.com` | `styleSrc` |\n| `cms: true` OR `account: true` | `https://fonts.gstatic.com` | `fontSrc` |\n| `csp` set (always) | `@trustedOrigins` | `connectSrc` |\n| Bundled SPA enabled | SPA-baked API origin (`config.domain`, `quickback.{baseDomain}`, `cms.domain`, `account.domain`) | `connectSrc` |\n\nAnything you already wrote stays — auto-config never removes or overrides. Each applied addition is logged to stderr. Opt out with `security: { cspAutoConfig: false }`.\n\nMost projects can write the minimal:\n\n```ts\nsecurity: {\n csp: {\n defaultSrc: ['@self'],\n scriptSrc: ['@self'],\n objectSrc: ['@none'],\n upgradeInsecureRequests: true,\n },\n}\n```\n\n…and the compiler fills in font hosts, trusted origins, and SPA-baked URLs.\n\nWhen a target directive is missing, auto-config scaffolds it from `default-src` baseline rather than widening `default-src` itself — CSP3 fall-back semantics would otherwise leak the addition to every directive that falls back to `default-src`.\n\n---\n\n## v0.10.14 — May 1, 2026\n\n### `auth.jwt` config\n\nThe bearer-token JWT used by the auth fast-path is configurable. Tune `expiresIn` to bound the post-revocation replay window without affecting browser SPAs (which auto-refresh on every authed call):\n\n```ts\nauth: {\n jwt: {\n expiresIn: 30,\n issuer: 'my-api',\n audience: 'partner-svc',\n secretEnv: 'CUSTOM_JWT_SECRET',\n },\n}\n```\n\n### Admin MCP endpoints filtered\n\nBetter Auth admin endpoints (`/admin/list-users`, `/admin/ban-user`, etc.) now carry `x-access: { userRole: ['admin'] }` in the generated OpenAPI spec. The MCP `tools/list` access-filter drops them for non-admin callers.\n\n### Declarative `security` config\n\nEvery security response header (`Content-Security-Policy`, COOP, COEP, CORP, HSTS, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`) is configurable from `quickback.config.ts`. `@`-prefixed sentinels (`@self`, `@none`, `@unsafe-inline`, `@trustedOrigins`, etc.) replace awkward `\"'self'\"` quoting.\n\nThe compiler lints the resolved config for known footguns: `@unsafe-inline` in `script-src`, wildcard sources, missing `default-src`, HSTS preload-list misconfiguration.\n\n### HSTS skipped on localhost\n\nGenerated middleware skips `Strict-Transport-Security` when the request hostname is `localhost`, `127.0.0.1`, or `*.localhost`. Without this gate, `wrangler dev` would pin a developer's browser to HTTPS across every project on that machine.\n\n---\n\n## v0.10.13 — May 1, 2026\n\n### Clickjacking defence on every Worker\n\nEvery Worker emits `Content-Security-Policy: frame-ancestors 'self' <TRUSTED_ORIGINS…>` and `X-Frame-Options: SAMEORIGIN` on every response. The CSP allowlist is sourced from the same `TRUSTED_ORIGINS` constant that gates CORS.\n\n---\n\n## v0.10.11 — May 1, 2026\n\n### MCP `tools/list` is access-filtered\n\nEach MCP tool now carries sanitised access metadata. `tools/list` filters against the caller's `ctx`: unauthenticated callers see only `PUBLIC` tools, authenticated callers see only role-gated tools they pass.\n\n- Wildcard CORS removed from the MCP endpoint.\n- Unauthenticated `GET /mcp` no longer enumerates tool names.\n- Internal flavor text is removed; `annotations.destructiveHint` and `_unsafe` remain — those are the spec-correct signals for clients.\n\n`tools/call` continues to re-enter the Hono app and run every middleware (auth, firewall, access, guards, masking), so hiding a tool from list never weakens the underlying gate.\n\n---\n\n## v0.10.10 — April 29, 2026\n\n### Reserved keys in `access.record` are rejected\n\n`access.record` is a flat field map evaluated as implicit AND between entries — keys must be column names. The compiler now rejects reserved keys (`and`, `or`, `roles`, `userRole`) inside `record` with migration guidance pointing at the working pattern (top-level siblings with their own `record:` blocks).\n\n---\n\n## v0.10.8 — April 29, 2026\n\n### Audit logging on Postgres targets\n\n`audit_events` previously only existed on `cloudflare-d1`. The audit table now lives in a dedicated `audit` schema (`drizzle.pgSchema('audit')`) on Postgres targets. The `hasSecurityAudit` gate accepts D1 or any PG dialect; `auditDatabaseId` remains a D1-only requirement.\n\n### `auditDatabaseId` is a compile-time requirement\n\nProjects with unsafe or `PUBLIC` actions that previously produced a placeholder `database_id = \"local-audit\"` in production now fail at compile time with the exact `wrangler d1 create <project>-audit` command and the config key where the returned ID goes.\n\n### Action input → OpenAPI / MCP\n\n`defineAction({ input: z.object({...}) })` schemas flow into the OpenAPI `requestBody` and the MCP tool's `inputSchema.properties`. Simple `z.object` shapes are extracted at compile time; discriminated unions, refinements, recursive schemas, and bare-identifier references run through Zod's native `z.toJSONSchema()` for full-fidelity output.\n\n### OpenAPI fidelity\n\n- Response schemas emit `required[]` for every non-nullable column.\n- `text(_, { enum: [...] })` columns emit as closed `{ type: \"string\", enum: [...] }`.\n- `id` claims `format: \"uuid\"` only when the project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators emit plain `{ type: \"string\" }`.\n\n### Minor\n\n- Auto-mask predicate verifies the resolved owner column exists before emitting an `or: 'owner'` clause; falls back to roles-only with a warning otherwise.\n- Generated CRUD errors emit canonical `QuickbackErrorCode` enum values (`DB_NOT_NULL_VIOLATION`, `DB_UNIQUE_VIOLATION`, etc.) so generated SDKs can exhaustively switch on `code`. See [API errors](/compiler/targets/hono-api/using-the-api/errors#database).\n\n---\n\n## DSL: one file per action, multi-table per feature\n\n### One file per action\n\nAction authoring is one file per action under `<feature>/actions/<name>.ts`. The filename is the action name and the URL segment:\n\n```typescript\n// features/applications/actions/advance.ts\n\nexport default defineAction({\n description: \"Move an application forward in the pipeline\",\n input: z.object({ nextStatus: z.enum([\"screening\", \"interview\", \"offer\"]) }),\n access: { roles: [\"owner\", \"admin\"] },\n transition: {\n field: \"status\",\n via: \"nextStatus\",\n fromTo: { applied: [\"screening\"], screening: [\"interview\"], interview: [\"offer\"] },\n },\n async execute({ db, record, input, auditFields, whereTransition }) { /* … */ },\n});\n```\n\n`defineAction` is imported from a generated per-feature helper at `<feature>/.quickback/define-action.ts` — `record`, `input`, and audit fields are typed without manual annotations.\n\n**Discovery rules:**\n- `actions/<name>.ts` binds to the feature's primary table.\n- `actions/<table>/<name>.ts` binds to the sibling table file.\n- Setting `path:` makes the action standalone (custom URL, no record fetch).\n- Tableless features require every action to be standalone.\n\n**Retired** (rejected at load time with migration guidance): `actions.ts` (bundled multi-action file), `_feature.ts`, `handlers/` directory + `handler:` string ref, `defineActions(table, {…})`, colocated `defineActions` inside table files, `standalone: true` flag, `*-actions.ts` / `*.actions.ts` filename patterns.\n\nSee [Actions docs](/compiler/definitions/actions).\n\n### Multi-table actions per feature\n\nOne feature directory can own actions on multiple tables. Three discovery modes:\n\n- **Colocated** (canonical) — `<table>.ts` containing both `defineTable` and `defineActions(<table>, …)`. One file per entity.\n- **`actions.ts`** — single primary-table actions file at feature root.\n- **`actions/<table>.ts`** — per-table action files for strict schema/behavior separation.\n\nPlus a universal `_feature.ts` slot for non-table-bound feature-level actions and shared Zod schemas.\n\nAction names are unique per `(bindTable, name)` pair. Sibling-bound `actions/episodes/publish.ts` and `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish` and compile cleanly.\n\n---\n\n## Firewall: named-scope shape\n\nThe named-scope firewall shape is a co-equal user-facing input alongside the predicate array:\n\n```typescript\nfirewall: { organization: { column: 'tenant_id' } } // named-scope (compact)\nfirewall: { owner: { column: 'account_user_id' } }\nfirewall: { exception: true }\nfirewall: [\n { field: 'organizationId', equals: 'ctx.activeOrgId' },\n { field: 'deletedAt', isNull: true },\n] // predicate array (explicit)\n```\n\nPick the form that reads better — named-scope for the common one-line case, predicate array when you need custom `in`-lists or non-scope predicates.\n\n**Auto-detection synonyms.** When `firewall:` is omitted, the compiler scans the schema for an isolation column. The org-scope list accepts `organizationId`, `organisationId`, `orgId`, `organization`, `organisation`, `org` (American + British). User-scope accepts `userId`.\n\n**`ownerId` is a targeted error signal.** When a table carries `ownerId` but no isolation column and no explicit `firewall:`, the compiler raises a specific error — `ownerId` is business-logic ownership, not access control. Use `userId` for access control, declare an explicit `firewall:`, or add a separate isolation column.\n\n---\n\n## v0.10.0 — April 26, 2026\n\n### `q.scope()` — single-declaration tenant scoping\n\n`q.scope(kind)` replaces the three-place pattern (column declaration + firewall predicate + ownership-guard) with one column:\n\n```typescript\ncolumns: {\n organizationId: q.scope('organization'), // → ctx.activeOrgId\n ownerId: q.scope('owner'), // → ctx.userId\n teamId: q.scope('team'), // → ctx.activeTeamId\n}\n```\n\n`q.scope()` columns auto-derive the firewall predicate, register with the guards layer as `systemManaged` (client input rejected), and auto-populate from `ctx` on create / upsert. The systemManaged extension generalises beyond `q.scope()`: any firewall predicate whose `equals` references `ctx.*` registers its `field` automatically.\n\nSee [`q.scope()`](/compiler/definitions/schema#qscope--tenant-scope-columns).\n\n### `masking[col].query.roles` — unified filter / sort / search gate\n\nThe three legacy per-capability flags (`filterable`, `searchable`, `sortable`) are replaced by a single `query.roles` allowlist:\n\n```typescript\nmasking: {\n email: {\n type: 'email',\n show: { roles: ['admin'] },\n query: { roles: ['admin'] }, // defaults to show.roles when omitted\n },\n}\n```\n\nA view's own `query.{filterable,searchable,sortable}` allowlist is the opt-in for higher-privileged roles; the existing intersection validator gates it at compile time.\n\n**Breaking:** `masking[col].filterable / .searchable / .sortable` is rejected at compile time with a migration hint. Replace with `query.roles` (or delete the flags — `query` defaults to `show.roles`).\n\n---\n\n## v0.9.0 — April 25, 2026\n\n### Unified `read:` pipeline\n\nThe read side of every resource has its own block — `read:` — that owns the collection-level `GET /` endpoint, single-record `GET /:id`, and named view projections.\n\n**Breaking changes** (compile-time errors with migration hints):\n\n- `crud.list` → `read.access` (plus `read.pageSize` / `read.maxPageSize`)\n- `crud.get` → `read.access` (single-record GET inherits automatically)\n- Top-level `views: {...}` → `read.views: {...}`\n- `crud.list.fields` / `crud.get.fields` → declare a named view under `read.views` and call `/views/{name}`\n\n### Pre-record access ordering\n\nHandlers on `/:id` run a role-only access check before the firewall query. A caller without a matching role gets 403 before the database is touched. This closes the 404-vs-403 ID-probe channel — an unauthorized caller can no longer distinguish \"row exists in another tenant\" from \"row doesn't exist.\" See [Access evaluation order](/compiler/definitions/access#evaluation-order).\n\n### Transactional batch operations\n\nBatch endpoints expose `failFast` and a `meta.transactional` response field. On tx-supporting providers (postgres, supabase, neon, libsql, better-sqlite3, bun-sqlite), `failFast: true` wraps the per-record loop in `db.transaction(...)` so any failure rolls back the entire batch. On Cloudflare D1 (no `db.transaction`), `failFast: true` stops on the first error but prior writes stay committed.\n\nEmbedding queue messages and realtime broadcasts emit after the transaction commits — rolled-back batches produce no orphan jobs.\n\nSee [Batch Operations → Transactional semantics](/compiler/targets/hono-api/using-the-api/batch-operations#transactional-semantics).\n\n---\n\n## v0.8.7 — April 17, 2026\n\n### Hono CVE bump\n\nHono is bumped to `^4.12.14` across the monorepo, the compiler Docker image's pre-installed deps, and every generator path that emits Hono into compiled projects. Older ranges covered the vulnerable window. Recompile to pick up the fix in your generated project's `package.json`.\n\n### Cloudflare Email Sending in public beta\n\nQuickback defaults to the Workers `send_email` binding for Cloudflare deploys. Cloudflare Email Sending has graduated to public beta — production-ready with zero-config. AWS SES remains a fully supported opt-in (`email.provider: 'aws-ses'`) for non-Cloudflare runtimes. See [Email Configuration](/compiler/config#email-configuration).\n\n### Dependency sweep\n\n`wrangler@^4.83.0`, `drizzle-orm@^0.45.2`, `drizzle-kit@^0.31.10`, `zod@^4.3.6`, `@cloudflare/workers-types@^4.20260417.1`.\n\n---\n\n## v0.8.5 — April 15, 2026\n\n### `userRole` access primitive\n\nA new `userRole?: string[]` field in the declarative `Access` config evaluates against `ctx.userRole` (the Better Auth admin-plugin `user.role` column). Distinct from `roles`, which matches `ctx.roles` (org membership).\n\n```typescript\n// Org owner OR platform admin\naccess: { or: [{ roles: ['owner'] }, { userRole: ['admin'] }] }\n\n// Platform admins see SSNs across every org\nmasking: { ssn: { type: 'ssn', show: { userRole: ['admin'] } } }\n```\n\n`userRole` works everywhere `Access` is accepted — CRUD, actions, views, masking, and inside `or` / `and` combinators. See [Access → userRole vs roles](/compiler/definitions/access#userrole-vs-roles).\n\n### CMS admin gate enforced server-side\n\n`cms: { access: \"admin\" }` previously only hid the CMS link in Account UI and rendered an \"Access Denied\" screen inside the SPA. Server-side enforcement now applies at every CMS-facing surface: the SPA shell, `/api/v1/schema`, and `custom_view` CRUD.\n\n### Better Auth 1.5 + `@cloudflare/workers-types` compatibility\n\nGenerated API code typechecks against the new versions. The org-member role-change broadcast hook is emitted via `organizationHooks.afterUpdateMemberRole` (the supported shape after the 1.5 deprecation of `databaseHooks.member.update.after`). `REALTIME_URL` and `ACCESS_TOKEN` are always emitted as optional bindings when the organization plugin is active.\n\n---\n\n## v0.8.4 — April 14, 2026\n\n### `generateId: \"short\"` strategy\n\nA compact ID option for tables where short, shareable codes matter more than collision resistance at scale:\n\n```typescript\nproviders: {\n database: defineDatabase(\"cloudflare-d1\", { generateId: \"short\" }),\n}\n```\n\nGenerates 6-character alphanumeric IDs (e.g. `a3F9xK`) using nanoid's `customAlphabet` with the full 62-char alphabet (`0-9A-Za-z`). Requires the `nanoid` package.\n\n**When to use:** room codes, invite links, share URLs, ephemeral records.\n\n**When not to use:** high-volume tables. 62^6 ≈ 56.8B combinations means ~238K rows before a 50% collision probability. For large tables stick with `\"uuid\"`, `\"cuid\"`, or `\"prefixed\"`. See [Providers → ID Generation Options](/compiler/config/providers#id-generation-options).\n\n---\n\n## v0.8.2 — April 11, 2026\n\n### Catch-all `VITE_QUICKBACK_URL`\n\nA single Quickback origin can be set in place of four separate URL env vars:\n\n```bash\nVITE_QUICKBACK_URL=https://secure.example.com\n```\n\n| Individual var (explicit) | Fallback when unset |\n|---|---|\n| `VITE_QUICKBACK_API_URL` | `${VITE_QUICKBACK_URL}` |\n| `VITE_QUICKBACK_ACCOUNT_URL` | `${VITE_QUICKBACK_URL}/account` |\n| `VITE_QUICKBACK_CMS_URL` | `${VITE_QUICKBACK_URL}/cms` |\n\n`VITE_QUICKBACK_APP_URL` stays independent — it points at the tenant's own frontend. Non-breaking; individual vars take precedence when set. Library users can set `__QUICKBACK_URL__` on `globalThis`. See [Environment Variables](/stack/account-ui/environment-variables).\n\n---\n\n## v0.8.1 — April 9, 2026\n\n### Role hierarchy with `+` suffix\n\nDefine a hierarchy and use `+` to mean \"this role and above\":\n\n```typescript\nauth: { roleHierarchy: ['member', 'admin', 'owner'] }\n\ncrud: {\n list: { access: { roles: [\"member+\"] } }, // member, admin, owner\n create: { access: { roles: [\"admin+\"] } }, // admin, owner\n delete: { access: { roles: [\"owner\"] } }, // owner only\n}\n```\n\nRoles are expanded at compile time. No `+` = exact match. See [Access → Role Hierarchy](/compiler/definitions/access#role-hierarchy).\n\n---\n\n## v0.8.0 — April 9, 2026\n\n### Breaking: VITE URL environment variables namespaced\n\nAll Quickback-generated URL environment variables are namespaced under `VITE_QUICKBACK_*` to avoid collisions with other Vite projects.\n\n| Old | New |\n|-----|-----|\n| `VITE_API_URL` | `VITE_QUICKBACK_API_URL` |\n| `VITE_ACCOUNT_URL` | `VITE_QUICKBACK_ACCOUNT_URL` |\n| `VITE_APP_URL` | `VITE_QUICKBACK_APP_URL` |\n| `VITE_CMS_URL` | `VITE_QUICKBACK_CMS_URL` |\n\nNon-URL variables are unchanged (`VITE_ENABLE_*`, branding vars, `VITE_STRIPE_PUBLISHABLE_KEY`).\n\n**Action required:**\n- Compiled projects: re-run `quickback compile`.\n- Standalone deploys: update `.env`, `.env.production`, and `wrangler.toml` files manually.\n- Library users: `__QUICKBACK_API_URL__` / `__QUICKBACK_APP_URL__` globals are unchanged.\n\n### CMS access control\n\n`cms.access: \"admin\"` enforces access at the CMS level, not just link visibility. Non-admin users (`user.role !== \"admin\"`) see an \"Access Denied\" screen with a sign-out button.\n\n---\n\n## v0.5.11 — February 24, 2026\n\n### Mandatory unsafe action audit trail\n\nStructured `unsafe` config (`unsafe: { reason, adminOnly, crossTenant, targetScope }`). Cross-tenant unsafe actions require Better Auth authentication plus platform admin role (`ctx.userRole === \"admin\"`). Mandatory audit logging on success, denial, and error paths. Cloudflare output includes `AUDIT_DB` wiring, `drizzle.audit.config.ts`, and `db:migrate:audit:*` scripts when unsafe actions are present.\n\nCompile-time raw SQL guard for actions and handlers (`allowRawSql: true` required per action).\n\n### Security contract report artifacts\n\nGenerated security contract artifacts: `reports/security-contracts.report.json`, `reports/security-contracts.report.sig.json`. Config-driven signing controls (`compiler.securityContracts.report.signature.*`). Missing required signing keys fail loudly with explicit remediation.\n\n### Headless Drizzle rename hints\n\n`compiler.migrations.renames` configuration for CI/CD environments where Drizzle's interactive rename prompts block compilation. See [Configuration](/compiler/config).\n\n### Minor\n\n- Email OTP magic links work correctly.\n- Auth is required for all API routes when running locally.\n- Single-file multi-table exports alongside `defineTable()` produce a clear error.\n\n---\n\n## v0.5.8 — February 14, 2026\n\n### Quickback CMS\n\nA schema-driven admin panel that connects to your generated API. The compiler now outputs a JSON schema registry consumed by the CMS at runtime. Firewall error modes (`reveal` for 403 with details, `hide` for opaque 404) are configurable per resource for security-sensitive deployments.\n\n---\n\n## v0.5.7 — February 12, 2026\n\n### Scoped database for actions\n\nActions receive a security-scoped database instead of a raw Drizzle instance. The compiler generates a proxy wrapper that automatically enforces org isolation, owner filtering, and soft-delete visibility — the same protections that CRUD routes have always had.\n\nDuck-typed column detection at runtime:\n\n| Column Detected | SELECT / UPDATE / DELETE | INSERT |\n|---|---|---|\n| `organizationId` | Adds `WHERE organizationId = ?` | Auto-injects `organizationId` from context |\n| `ownerId` | Adds `WHERE ownerId = ?` | Auto-injects `ownerId` from context |\n| `deletedAt` | Adds `WHERE deletedAt IS NULL` | — |\n\nEvery action is secure by default — no manual `WHERE` clauses needed.\n\nActions that intentionally need to bypass security (admin reports, cross-org queries, migrations) can declare `unsafe: true` to receive a raw, unscoped database handle via `rawDb`:\n\n```typescript\ndefineActions(analytics, {\n globalReport: {\n unsafe: true,\n execute: async ({ db, rawDb, ctx, input }) => {\n // db → still scoped (safety net)\n // rawDb → bypasses all security filters\n const allOrgs = await rawDb.select().from(organizations);\n },\n },\n});\n```\n\nWithout `unsafe: true`, `rawDb` is `undefined`. See [Actions](/compiler/definitions/actions).\n\n### Cascading soft delete\n\nSoft-deleting a parent record automatically cascades to child and junction tables within the same feature. The compiler detects foreign key references at build time and generates cascade `UPDATE` statements.\n\nRules:\n- Applies to soft delete only. Hard delete relies on database-level `ON DELETE CASCADE`.\n- Cascades within the same feature only — cross-feature references are not affected.\n- Child tables must have `deletedAt` / `deletedBy` columns (auto-added by the compiler).\n\nSee [Actions API → Cascading Soft Delete](/compiler/targets/hono-api/using-the-api/actions-api#cascading-soft-delete).\n\n### Advanced query parameters\n\nNew capabilities for all list endpoints:\n\n- **Field selection** — `?fields=id,name,status`\n- **Multi-sort** — `?sort=status:asc,createdAt:desc`\n- **Total count** — `?count=true` returns total matching records in `X-Total-Count`\n- **Full-text search** — `?search=keyword` searches across all text columns\n\nSee [Query Parameters](/compiler/targets/hono-api/using-the-api/query-params).\n\n---\n\n## v0.5.5 — February 5, 2026\n\n### OpenAPI spec generation\n\nGenerated APIs include a full OpenAPI specification at `/openapi.json`. Better Auth endpoints are included in the spec.\n\n### Better Auth plugins\n\nPublished `@quickback-dev/better-auth-upgrade-anonymous` (post-passkey email collection flow), `@quickback-dev/better-auth-combo-auth` (combined email + password + OTP), and `@quickback-dev/better-auth-aws-ses` (AWS SES email provider).\n\n### Security headers\n\nGlobal error handler prevents leaking internal error details. Security headers middleware (CSP, HSTS, X-Frame-Options, X-Content-Type-Options). `BETTER_AUTH_SECRET` properly passed to generated config.\n\n---\n\n## v0.5.4 — January 30, 2026\n\n### Account UI\n\nPre-built authentication UI deployed as Cloudflare Workers. Sessions, organizations, passkeys, passwordless, admin panel, API keys. Dual-mode: standalone (degit template) or embedded with Quickback projects.\n\n### Webhook system\n\nInbound webhook endpoints with signature verification. Outbound webhooks via Cloudflare Queues with automatic retries. Configurable per-feature webhook events.\n\n### Realtime & vector search\n\nDurable Objects + WebSocket realtime subscriptions. Vector embeddings via Cloudflare Vectorize. KV and R2 storage integrations.\n\n---\n\n## v0.5.0 — January 2026\n\n### Initial release\n\n- **Quickback Compiler** — TypeScript-first backend compiler.\n- **Four security pillars** — Firewall, Access, Guards, Masking.\n- **`defineTable()`** — schema + security configuration in a single file.\n- **Templates** — Cloudflare Workers, B2B SaaS.\n- **Cloud compiler** — remote compilation via `compiler.quickback.dev`.\n- **CLI** — `quickback create`, `quickback compile`.\n- **Better Auth integration** — organizations, roles, sessions.\n- **Drizzle ORM** — schema-first with automatic migrations.\n- **Cloudflare D1** — split database support (auth + features)."
6
+ "content": "## v0.40.2 — June 3, 2026\n\n### Passwordless plugins can no longer bypass the signup gate\n\nBetter Auth's `emailOtp` and `magicLink` plugins auto-create an account when a\ncode/link is verified for an unknown email — and that path is independent of\n`emailAndPassword.disableSignUp`. As a result, `account.auth.signup: false`\nclosed `POST /auth/v1/sign-up/email` but left OTP / magic-link verification as an\nopen back-door for account creation.\n\nThe compiler now emits each plugin's own `disableSignUp` flag, and new\nper-plugin options expose it directly:\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: {\n emailOtp: { disableSignUp: true }, // OTP sign-in only; unknown emails rejected\n magicLink: { disableSignUp: true }, // same for magic links\n },\n}),\n```\n\nBoth default to following the global gate: setting `account.auth.signup: false`\n(→ `emailAndPassword.disableSignUp: true`) now also gates the OTP and magic-link\npaths automatically. Set `{ disableSignUp: false }` on a plugin explicitly to\nkeep its sign-up open while password sign-up stays closed.\n\n## v0.40.1 — June 2, 2026\n\n- The generated `wrangler.toml` and `Env` type now emit the `ASSETS` binding\n type for projects that mount SPAs (CMS / Account), so handler code that\n references `c.env.ASSETS` typechecks.\n- Compiler Docker builds preserve their layer cache across rebuilds, cutting\n local recompile time.\n\n## v0.40.0 — June 2, 2026\n\nR2 file storage is now **presign-only by default**. Adding\n`defineFileStorage(\"cloudflare-r2\")` emits just the `ctx.storage` signer — no\nFILES_DB database, no `/storage/v1/*` endpoints, no files worker. You sign\npresigned URLs against a bucket and store references in your own table. The\nturnkey managed subsystem is still available, now behind `managed: true`.\n\nThis decouples the lightweight primitive from the heavyweight subsystem so you\ncan add uploads without standing up a metadata database you don't use.\n\n### Presign-only by default; managed is opt-in\n\n```ts\n// Presign-only (default) — ctx.storage against a bucket, nothing else\ndefineFileStorage(\"cloudflare-r2\", { bucketName: \"my-app-media\" })\n\n// Managed subsystem — FILES_DB + /storage/v1/* + files worker\ndefineFileStorage(\"cloudflare-r2\", { managed: true })\n```\n\n- New projects can omit `bucketName` — it defaults to `<project>-media`, so\n setup is one `wrangler r2 bucket create` plus the R2 API-token secrets.\n- Existing projects set `bucketName` to a bucket they already have. Presign-only\n emits **no** R2 bucket binding and **no** FILES_DB binding — nothing to\n provision, nothing to migrate.\n\n### Per-call bucket + custom secret names\n\n```ts\n// Sign against a different bucket than the configured default\nawait storage.signPutUrl(key, { bucket: \"my-app-public\", contentType });\n```\n\nIf your project already stores R2 credentials under different env-var names,\nmap them so the signer reads yours:\n\n```ts\ndefineFileStorage(\"cloudflare-r2\", {\n bucketName: \"my-app-media\",\n presign: { accountIdEnv: \"CF_ACCOUNT_ID\", accessKeyIdEnv: \"S3_KEY\", secretAccessKeyEnv: \"S3_SECRET\" },\n})\n```\n\n### Fixes\n\n- `maxFileSize` now accepts a human string (`\"100mb\"`, `\"5gb\"`) as well as a\n number of bytes — previously a string emitted invalid TypeScript.\n- Presign-only no longer emits a stray `FILES_DB` `[[d1_databases]]` block (with\n an invalid `database_id = \"local-files\"`) into `wrangler.toml`, which would\n have made `wrangler deploy` reject the worker.\n\n## v0.39.1 — June 2, 2026\n\nDeduplicate colliding OpenAPI `operationId`s. The auto-generated list id\n`list\n</Button>\n```\n\n`ResponsiveModal` survived the migration unchanged — it composes the higher-level Dialog + Drawer wrappers (preserved public API), not the underlying primitives.\n\n#### Caller-side API changes worth noting\n\nBase-ui ships some real behavioural changes the Radix variants didn't:\n\n- `<Select onValueChange>` now receives `(value: string | null, eventDetails) => void` (was `(value: string) => void`). Existing `Dispatch<SetStateAction<string>>` setters reject `null` — wrap callbacks defensively: `onValueChange={(v) => v != null && setX(v)}`.\n- `<DropdownMenuContent forceMount>` removed (base-ui has no `forceMount`). Use base-ui's `keepMounted` on the Popup/Positioner if you need to preserve unmounted state.\n- Component sub-names shifted (`Dialog.Content` → `Dialog.Popup`, `Dialog.Overlay` → `Dialog.Backdrop`). Data attributes are now `data-open` / `data-closed` (no more `data-state=\"open\"`).\n\n#### Adding a new primitive after this release\n\n```bash\ncd packages/ui\npnpm dlx shadcn@latest add <component> --overwrite --yes\n# Sweep generated `@/` imports to relative paths — the SPAs' vite-tsconfig-paths\n# plugin doesn't see packages/ui's @/* mapping at bundle time:\nsed -i.bak \\\n -e 's|\"@/lib/utils\"|\"../lib/utils\"|g' \\\n -e 's|\"@/components/|\"./|g' \\\n -e 's|\"@/hooks/|\"../hooks/|g' \\\n components/<component>.tsx && rm components/<component>.tsx.bak\n```\n\nIf the new primitive pulls in fresh deps, mirror them into `apps/compiler/deps-spa-{cms,account}-package.json` per the SPA build pipeline or Docker SPA builds will fail.\n\n---\n\n## v0.18.1 — May 18, 2026\n\n### Account SPA — teams, active-team picker, permission-aware UI\n\nThe Account SPA's organization surface is now feature-parity with Better Auth's `organization` plugin for the basic team workflow, and replaces the long-standing hardcoded `role === 'owner' || 'admin'` checks with `checkRolePermission` so projects that ship custom roles get a UI that respects them.\n\n#### Teams (opt-in)\n\nWhen the BA config enables teams — `organization({ teams: { enabled: true } })` — the compiler emits `VITE_ENABLE_ORG_TEAMS=true` and the Account SPA exposes a Teams tab on each organization:\n\n- **Teams index** (`/$slug/teams`) — splits into \"Your teams\" (from `listUserTeams`) and \"Other teams\" so non-admins land on what's relevant. Create / rename / delete from the list, gated on `team:create` / `team:update` / `team:delete`.\n- **Team detail** (`/$slug/teams/$teamId`) — member roster with add / remove, joining `listTeamMembers` against the org's full member list for display.\n- **Active-team picker** in the org header — calls `setActiveTeam` and exposes the choice via `OrganizationContext.activeTeamId` so downstream routes (and the BA `session.activeTeamId` server-side) stay in sync.\n- **Team-aware invites** — `InviteMemberDialog` shows an optional team picker when teams are on and forwards `teamId` to `inviteMember`, so accepting the invite drops the new member straight into the right team.\n\nTeams are loaded once by the `$slug` layout (`listTeams` + `listUserTeams`) and exposed via `OrganizationContext.teams` / `userTeamIds` / `refreshTeams`, so individual team routes don't re-fetch the list.\n\n#### Permission-aware UI via `checkRolePermission`\n\n`OrganizationContext.isOwnerOrAdmin` is gone. Routes now read `can(resource, action)` from context, which delegates to `authClient.organization.checkRolePermission` — synchronous, no roundtrip, and aware of any custom roles registered via the BA `ac` option. Multi-role users (BA stores multiple roles comma-separated) are handled by checking each role; the action is allowed if any role grants it.\n\nMigrated sites:\n\n- `$slug.tsx` tab gates → `can('invitation', 'create')`, `can('organization', 'update')`\n- `members.tsx` action menu → `can('member', 'update' | 'delete')`; the owner-hierarchy guard (non-owners can't touch owner-role members) is preserved as a client-side mirror of BA's server enforcement\n- `invitations.tsx` → `can('invitation', 'create' | 'cancel')` gates the Invite button, resend, and cancel separately\n- `settings.tsx` → `can('organization', 'update')` for the form, `can('organization', 'delete')` for the danger zone (was owner-only)\n- `teams.tsx` / `teams.$teamId.tsx` → `can('team', 'create' | 'update' | 'delete')`\n\nProjects on the default three-role hierarchy see no behaviour change; projects that defined `admin`/`member` overrides via BA's access-control API now get a UI that matches what the server will actually authorize.\n\n#### Editable slug + metadata on organization settings\n\nThe `$slug/settings.tsx` form now edits two more `organization.update` fields:\n\n- **URL slug** — full debounced `checkSlug` flow (mirroring the create-org form); on rename, the SPA navigates to `/${newSlug}/settings` and the layout re-fetches with the new slug.\n- **Metadata** — single `Record<string, any> | null` JSON textarea, parsed on submit with inline error messaging. Empty clears the field.\n\nSlug rename is non-breaking for the SPA itself, but every external link / bookmark that references the old slug becomes a 404 — the form warns about this before saving.\n\n#### Auth client wiring\n\nWhen `VITE_ENABLE_ORG_TEAMS=true`, the SPA's `organizationClient(...)` is instantiated with `teams: { enabled: true }` so the team APIs are typed end-to-end. When the flag is off, team methods aren't surfaced — and the Teams tab is hidden — keeping the bundle and UI honest about what the server actually supports.\n\n---\n\n## v0.18.0 — May 17, 2026\n\n### `config.apps` — mount user-authored SPAs on dedicated hostnames\n\nThe compiler now generates per-hostname Worker middleware for arbitrary user SPAs alongside the built-in CMS and Account UIs. Previously the only way to host a product app next to a Quickback API was a second Worker; `config.apps` brings the full stack — API, account, and product UI — onto one deployment with same-origin auth.\n\n```ts\napps: {\n www: {\n domain: \"www.example.com\",\n aliasDomains: [\"example.com\"], // apex serves the same SPA\n },\n}\n```\n\nEach entry binds one or more hostnames to a directory under `src/apps/<name>/` and inherits the Account-domain pass-through behavior — `/api/`, `/auth/`, `/admin/`, `/storage/`, and `/health` route to Hono so the SPA fetches its API without CORS. The compiler:\n\n- emits a `custom_domain = true` route in `wrangler.toml` for the primary hostname and every alias\n- adds each hostname to Better Auth's `TRUSTED_ORIGINS` (when `trustedOrigins` is left unset)\n- widens the CSP `connect-src` to cover the SPA-baked origins\n- folds the new hostnames into shared-parent detection for `crossSubDomainCookies`\n\nDrop the prebuilt SPA bundle at `quickback/apps/<name>/` — the existing source-apps passthrough copies it byte-for-byte into `src/apps/<name>/`. The compiler doesn't build the SPA; it only emits routing for whatever's already there. The names `cms`, `account`, and `public` are reserved; hostname collisions with `cms.domain` / `account.domain` / `account.adminDomain` or between two `apps[*]` entries fail at compile time.\n\nWhen `cms` and `account` are both configured, the multi-domain catchall now explicitly skips app hostnames — an API miss on an app host returns the standard 404 JSON via `app.notFound` instead of stray-serving a sibling SPA's HTML shell.\n\n### Cross-subdomain cookie inference handles apex aliases\n\nThe shared-parent detection that drives `advanced.crossSubDomainCookies` previously reduced any hostname by stripping the leftmost label — `'example.com'` collapsed to `'com'`, which broke equality against sibling subdomains. Apex hostnames (exactly two dot-segments) are now treated as already being the parent, so apex aliases (`example.com` listed alongside `www.example.com`) coexist cleanly with `auth.example.com` / `cms.example.com` and the compiler still emits `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`.\n\n---\n\n## v0.17.2 — May 15, 2026\n\n### `customPlugins` escape hatch on `defineAuth(\"better-auth\", …)`\n\nThe Better Auth provider now accepts `customPlugins` alongside the named-plugin registry — a path to ship third-party plugins (`@better-auth-kit/audit`, …), unregistered built-ins, or one-off project-local plugins without forking the compiler.\n\nEach entry is an explicit import descriptor:\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: { passkey: true, organization: true },\n customPlugins: [\n // (1) Project-local plugin file at quickback/plugins/long-session.ts\n { from: \"./plugins/long-session\", export: \"longSessionPlugin\" },\n // (2) Third-party npm package\n {\n from: \"@better-auth-kit/audit\",\n export: \"auditPlugin\",\n args: { events: [\"sign-in\"] },\n dependencies: { \"@better-auth-kit/audit\": \"^1.0.0\" },\n },\n ],\n}),\n```\n\n`from` is either a relative path under `./plugins/` (the CLI auto-uploads matching files from `quickback/plugins/`; the compiler copies them into `src/plugins/<name>.ts` and rewrites the emitted import) or a bare npm specifier (emitted verbatim; declare `dependencies` so the package lands in the generated `package.json`). Omit `args` to emit the symbol uncalled (plugin instance); provide `args` to emit a JSON-serialized factory call.\n\nThe descriptor is validated with Zod — typos in `from`/`export`, paths that escape `./plugins/`, and references to files the CLI didn't ship all fail at compile time with a targeted message.\n\n---\n\n## v0.17.1 — May 14, 2026\n\n### `quickback start` — interactive onboarding\n\n```bash\nmkdir my-app && cd my-app\nnpx @quickback-dev/cli start\n```\n\n`start` walks new users through template selection, scaffolds the project on disk, and only prompts for an account when it's ready to compile. Cancelling at the login prompt leaves the scaffold intact — sign in and run `quickback compile` whenever you're ready.\n\nThe same deferred-auth flow applies to `quickback create`. Scaffolding and (optional) Cloudflare D1 setup run before authentication, so you can preview the project on disk before committing to an account.\n\n### Named views on the free tier\n\nThe `todos` template now ships a `dashboard` named view, exposing a projected response at `GET /api/v1/todos/views/dashboard`. Named views support per-view access rules and per-view field selection while inheriting the table's firewall and masking — the canonical way to ship list-view payloads that are cheaper to fetch and easier to cache than a full collection read.\n\n### `quickback init` removed\n\nFolded into `start` and `create`. The legacy command name prints a deprecation notice pointing at its replacements.\n\n### Minor\n\n- `quickback whoami` reads the stored tier from your credentials.\n- Pro upsell copy in `quickback login` is shown only when the server returns an explicit free-tier subscription.\n- Bare scaffolds (`cloudflare`, `empty`) report accurately when there are no features to generate migrations for.\n\n---\n\n## v0.16.10 — May 14, 2026\n\n### D1-specific safety pass on generated migrations\n\nThe `cloudflare-d1` provider now runs a post-generation pass over every Drizzle migration directory (auth, features, webhooks, audit) before the compile finishes. Better Auth cleanup for retired managed tables is stripped from raw `DROP TABLE` statements. Drop-only cleanup migrations are reordered child-first when foreign-key dependencies require it. Every generated D1 migration directory is replayed against SQLite during compile, so a D1-breaking migration fails at compile time rather than at `wrangler d1 migrations apply`.\n\n---\n\n## v0.16.9 — May 13, 2026\n\n### Resource-scoped realtime tickets\n\n`providers.database.config.realtime` accepts an object form for projects whose WebSocket subscribers aren't org members:\n\n```ts\nrealtime: {\n wsTicket: {\n role: \"attendee\",\n requestField: \"eventId\",\n scopeTable: \"events\",\n },\n}\n```\n\nThe generated `/broadcast/v1/ws-ticket` route authenticates the caller, evaluates the declared relationship role against the request, and mints a short-lived WebSocket ticket scoped to the resolved resource. `realtime: true` continues to enable the org-scoped broadcaster.\n\n### Unified broadcast targeting\n\nThe realtime helper and Broadcaster now route by `scopeKey || organizationId || userId`. String targets remain shorthand for `organizationId`; explicit targets can scope a broadcast to a resource or a single user:\n\n```ts\nawait realtime.broadcast(\"event-page-updated\", payload, { scopeKey: \"events:evt_123\" });\nawait realtime.broadcast(\"dm\", payload, { userId: recipientId });\n```\n\nWebSocket tickets are Quickback-minted (signed with `BETTER_AUTH_SECRET`), not Better Auth tokens — Better Auth remains the front-door auth check; Quickback signs the upgrade ticket after authorization succeeds.\n\n---\n\n## v0.16.8 — May 13, 2026\n\n### One auth transport per request\n\nGenerated middleware treats `Cookie`, `Authorization: Bearer`, and `x-api-key` as distinct auth methods and rejects mixed requests with `400 AUTH_METHOD_CONFLICT`. Query-string API keys (`?api_key=` / `?key=`) are no longer accepted. Machine-to-machine auth is explicit; precedence rules between transports are gone.\n\n### Cookie-backed CSRF gate\n\nGenerated apps now block cross-site `POST` / `PUT` / `PATCH` / `DELETE` requests from cookie-relying callers. The middleware skips explicit `Authorization` clients, requires a trusted `Origin` or `Referer`, and blocks `Sec-Fetch-Site: cross-site`. This matters most for cross-subdomain session setups where `SameSite=None` is intentional.\n\n### First-class Wrangler observability\n\n`providers.runtime.config.observability` now supports nested `logs` / `traces` blocks for `headSamplingRate`, `destinations`, `persist`, and `logs.invocationLogs`, emitting matching `[observability]`, `[observability.logs]`, and `[observability.traces]` TOML.\n\n---\n\n## v0.16.7 — May 12, 2026\n\n### Bearer wins over cookie\n\nA request carrying both `Authorization` and a session `Cookie` resolves entirely from the bearer; the cookie is dropped before `getSession()` runs. All three Bearer flavors (API key, JWT, session-token) now behave consistently — no more silent cookie precedence on session-token bearers.\n\n### Bearer plugin defaults to `requireSignature: true`\n\nBetter Auth's `bearer` plugin defaults to unsigned tokens; Quickback now emits `bearer({ requireSignature: true })`. Tokens emitted in the CORS-exposed `set-auth-token` header are server-signed with `BETTER_AUTH_SECRET` and verified on every request. Projects that genuinely need unsigned bearers can override via `providers.auth.config.plugins.bearer`.\n\nSee [Authentication Security → Bearer Tokens and Cookie Precedence](/stack/auth/security#bearer-tokens-and-cookie-precedence).\n\n---\n\n## v0.16.5 — May 12, 2026\n\n### Flat write DSL\n\nResource write operations are now declared at the table level alongside `read`, replacing the nested `crud` block:\n\n```ts\ndefineTable(customers, {\n read: { ... },\n create: { access: { roles: [\"admin\"] } },\n update: { access: { roles: [\"admin\"] } },\n delete: { access: { roles: [\"admin\"] }, mode: \"soft\" },\n upsert: { access: { roles: [\"admin\"] } },\n guards: { ... },\n});\n```\n\n`crud` and top-level `put` still compile as deprecated compatibility aliases. Mixed usage on the same resource is rejected. `schema-registry.json` emits both shapes during the transition.\n\n### CMS placement for multi-table feature actions\n\nStandalone actions on multi-table features have an explicit placement model:\n\n- `cms.placement: \"feature\"` shows the action on every table toolbar in the feature\n- `cms.placement: \"tables\"` with `cms.tables` scopes it to specific tables\n- `cms.hidden: true` keeps it API-only\n\nFeature-root standalone actions are emitted under a new `featureActions` bucket in `schema-registry.json`. Ambiguous multi-table standalone actions without placement compile with a warning.\n\n### `openapi.types` accepts a string array\n\nOne compile can write the generated types file to multiple locations, keeping colocated SPA clients in sync:\n\n```ts\nopenapi: { types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'] }\n```\n\n### Stable artifact ordering\n\nGenerated route files and `schema-registry.json` are emitted in a stable order across runs. Identical logical input produces identical artifacts.\n\n---\n\n## v0.16.4 — May 12, 2026\n\n### Drizzle snapshot integrity\n\nDrizzle metadata files (`<n>_snapshot.json`) are no longer stamped with a Quickback warning key. The warning is now journal-only. Projects whose snapshots were corrupted by an earlier release self-heal on the next compile — the stripped header is removed during staging and the rewritten snapshot is clean.\n\n### `account.auth.*` drives the server, not just the SPA\n\nThe Account UI's auth flags (`signup`, `password`, `passkey`, `emailOTP`, `emailVerification`) now configure the Better Auth server alongside the SPA bundle. A normalizer maps them into the server config:\n\n- `signup → emailAndPassword.disableSignUp` (inverted)\n- `password → emailAndPassword.enabled`\n- `emailVerification → emailAndPassword.requireEmailVerification`\n- `passkey` / `emailOTP` → plugin additions\n\nThe SPA's `VITE_ENABLE_*` flags are derived from the same canonicalized server config, so the bundle and the server cannot drift. Two new flags ride along: `VITE_ENABLE_API_KEYS` and `VITE_ENABLE_MAGIC_LINK`.\n\n**Breaking** for projects that implicitly relied on the SPA-only behaviour: `account.auth.signup: false` now actually disables `POST /auth/v1/sign-up/email` on the server. Set `providers.auth.config.emailAndPassword.disableSignUp: false` explicitly to keep server signup open while hiding the SPA screen.\n\n---\n\n## v0.16.3 — May 9, 2026\n\n### Standalone action mount order\n\nFeature-level standalone action routers now register before sibling CRUD routers when both mount at the exact same prefix. A literal path like `GET /api/v1/records/today-bundle` resolves to the standalone handler instead of falling through to `GET /:id` and treating `\"today-bundle\"` as a record ID.\n\n---\n\n## v0.16.1 — May 9, 2026\n\n### Cloudflare ASSETS canonicalization\n\nWorker SPA fallbacks now request `/<dir>/` instead of `/<dir>/index.html`. Cloudflare's static-assets binding rewrites `/index.html` requests as 307 redirects to the trailing-slash path under the default `html_handling=auto-trailing-slash`, which previously caused redirect loops in SPA fallback handlers. Affects CMS, Account, admin, and the multi-domain catchall.\n\n### `account.customLogin`\n\nSet `account: { customLogin: true }` to drop a project-branded sign-in page in front of the bundled SPA. Place the page at `quickback/public/account/login/index.html` (as a directory) and the existing public passthrough serves it. The route registers before the `/account/*` SPA catch-all so the static handler wins; everything else under `/account/` continues to route through the bundled SPA.\n\n### Project-level realtime defaults\n\n`providers.database.config.realtime: true` now treats every resource as realtime-enabled by default. Per-resource `realtime: { enabled: false }` still wins.\n\n### Compile-time validators\n\nTwo new compile-time errors over silent runtime failures:\n\n- `AUTHENTICATED` + org-scoped firewall is rejected. The combination silently returned empty lists to sign-in-only callers who lacked an active org; the validator names three valid resolutions (drop the org scope, use `USER`, or split the route).\n- `createRealtime` imports without `realtime: true` enabled in the config are rejected at compile.\n\n### Drizzle metadata hardening\n\nDrizzle journal files carry a \"do not edit\" header. The compiler warns when the journal entry count exceeds the snapshot file count (typically the trace of a hand-deleted snapshot).\n\n### Minor\n\n- `SYSADMIN` is now recognised by the standalone-action org gate's pseudo-role matcher.\n- Apex `/` and `/account/login` get fallback redirects to `auth.loginUrl` when neither bundled SPA is enabled.\n- Record-based action URLs are kebab-case to match the OpenAPI spec (e.g. `/api/v1/widgets/:id/send-invite`).\n\n---\n\n## v0.16.0 — May 9, 2026\n\n### Agent Auth Protocol\n\nQuickback ships a server implementation of the [Agent Auth Protocol](https://agentauthprotocol.com) via `@better-auth/agent-auth`. Enable with `auth.plugins.agentAuth: true` and the compiler emits the full agent-auth surface: discovery at `/.well-known/agent-configuration`, capability projection from the project's OpenAPI spec, a device-authorization approval page in the Account SPA at `/agents/approve`, and the four agent-auth tables added to the auth schema automatically.\n\n**OpenAPI capability projection runs by default.** Every operation with an `operationId` becomes an agent capability. Default `approvalStrength` map: `GET → \"session\"`, `POST/PUT/PATCH/DELETE → \"webauthn\"`. The proxy `onExecute` makes a self-fetch with a Better Auth JWT minted for the agent session, so the inner request hits the existing JWT fast-path and runs the full firewall + access + masking pipeline. Opt out of OpenAPI projection with `agentAuth: { fromOpenAPI: false }` and wire `capabilities` + `onExecute` by hand.\n\n### Bearer-only on `/mcp` and the agent-auth surface\n\n`/mcp` forwards only `Authorization: Bearer …` into the inner request. Cookie and `x-api-key` forwarding are removed. Three Bearer flavors land on the same header — Better Auth session token (via the `bearer` plugin), OAuth access token (via OAuth Provider), and agent JWT (via `@better-auth/agent-auth`).\n\n### Auth DSL gains first-class plugin entries\n\n`bearer`, `oauthProvider`, and `agentAuth` are now typed entries in both the array-form union and the `BetterAuthPlugins` interface, with their own options shapes (`OAuthProviderOptions`, `AgentAuthOptions`). Existing `as any` casts can come out.\n\nAuto-enable rule: turning on `agentAuth` force-adds `bearer` + `oauthProvider`. No useful agent-auth deployment ships without those two.\n\n### `queue-consumer.ts` gating\n\nThe queue consumer is emitted when any of the following are true: embeddings are configured, queue handlers exist under `services/queues/*`, or `additionalQueues` is declared. Previously the third case left projects with a wrangler binding pointing at a missing handler.\n\n---\n\n## v0.15.0 — May 7, 2026\n\n### Sysadmin tier for the CMS\n\nA new opt-in `cms: { sysadmin: true }` flag turns the CMS into a cross-tenant DB-admin tool gated by `user.role === 'sysadmin'`. Distinct from the Better Auth `'admin'` plugin role, so user-management powers and DB-admin powers stay decoupled. Off by default.\n\nWhen enabled, the compiler emits a `SYSADMIN` pseudo-role (a fifth marker alongside `PUBLIC` / `AUTHENTICATED` / `USER` / `ADMIN`), a firewall escape hatch that drops tenant scopes for sysadmins while preserving soft-delete, a true cross-tenant `/admin/v1/sysadmin/organizations` endpoint, and a relaxed cross-tenant guard for list routes.\n\nThe CMS SPA gains a two-mode design: org admins keep the existing membership-based switcher, sysadmins get an \"All organizations\" selector that pins tenants via `?organizationId=` on every API call.\n\n### Durable Object `[[migrations]]` order is preserved\n\nCloudflare's migration list is append-only. The compiler now reads your existing `wrangler.toml` (when present) and emits auto-generated DO `[[migrations]]` blocks in two phases: deployed entries first (preserving order), net-new entries appended last. Reordering DOs in the config array no longer reshuffles deployed migrations.\n\n### `quickback/public/` — static-asset passthrough\n\nAnything dropped under `quickback/public/` is copied verbatim into `src/apps/` on every compile and served by the wrangler `[assets]` binding. Use for favicons, `robots.txt`, OG images, `.well-known/` files, marketing PDFs — anything that needs to ride past the compiler as bytes.\n\n- Optional. Missing folder is a no-op.\n- Stale-cleaned. Files removed from `quickback/public/` disappear on the next compile.\n- Hidden entries (`.DS_Store`, dotfiles) are skipped.\n- Collisions with compiler-emitted manifest paths fail the compile loudly.\n\n### Minor\n\n- Standalone-action wrapper skips the org gate when the access tree references any pseudo-role.\n- Queue handler emit no longer drops the `queue` export when there are no embeddings.\n\n---\n\n## v0.14.7 — May 7, 2026\n\n### Codegen fixes for projects with non-`id` primary keys and DO-only features\n\nFour surgical fixes to the generated output:\n\n- Duplicate table imports in relationship-role routes are deduplicated.\n- `db` references in single-record and bulk action handlers now resolve correctly during pre-fetch.\n- PartyServer auth gates pass the in-scope `db` handle into firewall calls.\n- Durable-object-only features keep their `lib/` files in the output.\n\n### `emailOtp` + AWS SES is OTP-only\n\n`auth.emailOtp` with the AWS SES email provider no longer auto-wires the magic-link companion. Mail-client URL prefetching can burn the one-time code before the human sees it; the Account SPA's `/email-otp` route is the single canonical entry point. Projects that explicitly want the magic-link arm can wire `sendVerificationOTP` directly.\n\n---\n\n## v0.14.6 — May 7, 2026\n\n### MCP transport correctness\n\nFour fixes to the MCP-over-HTTP path:\n\n- `tools/call` URLs are no longer double-prefixed for action tools.\n- Auth middleware accepts API keys via `Authorization: Bearer` in addition to `x-api-key` and query parameters — the channel MCP clients use exclusively.\n- `auth.roleHierarchy` is expanded for runtime role checks across api-key, JWT, and session auth paths. A higher role inherits the privileges of every lower role.\n- Team-scoped firewall predicates degrade gracefully when no team is active (org scoping continues to apply; team scoping is optional).\n\n---\n\n## v0.14.5 — May 7, 2026\n\n### MCP environment threading\n\nThe generated MCP server's `tools/call` dispatch threads `env` and `executionCtx` into the inner request, so action tools that touch Cloudflare bindings (D1, KV, R2, Queues) no longer crash with `undefined` env access.\n\n---\n\n## v0.14.4 — May 7, 2026\n\n### `via:` firewall predicates pull required imports\n\nThe relationship-role generator emits `inArray` and `sql` imports when the firewall has any `via:` predicate, and `buildFirewallConditions` accepts `(ctx, db)` so the relationship subquery has a Drizzle client to evaluate against. Every CRUD and action call site passes `db` through automatically.\n\n---\n\n## v0.14.3 — May 7, 2026\n\n### Relationship-role table re-exports\n\nGenerated `<table>.resource.ts` files now re-export their Drizzle table binding. Cross-feature relationship subqueries that import the binding from the resource file (rather than the schema) resolve correctly.\n\n---\n\n## v0.14.2 — May 7, 2026\n\n### Historical DO `[[migrations]]` are preserved\n\nA new `bindings.durableObjectMigrations` config slot carries forward `deleted_classes`, `renamed_classes`, and `transferred_classes` lifecycle entries across recompiles. Cloudflare's migration list is append-only; entries declared here are emitted first in `wrangler.toml`, then auto-generated current-class entries follow:\n\n```ts\nbindings: {\n durableObjects: [{ name: 'NOTEPAD', className: 'Notepad', from: 'lib/Notepad' }],\n durableObjectMigrations: [\n { tag: 'qb-do-deleted-legacy-notes-2026-05-05', deletedClasses: ['LegacyNotes'] },\n ],\n}\n```\n\nAll four lifecycle shapes are supported. User-declared entries can override auto-emit by reusing the same tag.\n\n---\n\n## v0.14.1 — May 7, 2026\n\n### Bulk action variants in `openapi.json`\n\nRecord-based actions with `bulkVariant: true` are now emitted as sibling operations in the OpenAPI spec, with the documented `{ ids, input, failFast? }` request shape, 200/207/400 responses, and a separate `<Resource><Action>Bulk` `operationId` so typed-client codegen distinguishes single from bulk.\n\n### Cross-tenant \"my events\" patterns\n\nThe access docs now include a worked example for the cross-tenant aggregation pattern (e.g. `GET /my-events` returning resources across all tenants a caller is invited to). See [Access → Cross-tenant dashboards](/compiler/definitions/access#cross-tenant-my-events-dashboards-are-not-this).\n\n---\n\n## v0.14.0 — May 7, 2026\n\n### Relationship-based authorization\n\nRoles can now be bound to a domain-table membership (\"user is a confirmed guest of this event\") rather than an org membership or a pseudo-role. Declare the relationship once and reference it from `firewall:` or `access.roles:`:\n\n```ts\nauthz: {\n relationships: {\n guestOf: {\n from: 'event_guests',\n subject: { column: 'userId', equals: 'ctx.userId' },\n resource: { column: 'eventId' },\n where: { status: 'confirmed' },\n },\n },\n roles: {\n guest: { via: 'guestOf' },\n eventStaff: { or: [{ via: 'guestOf' }, { roles: ['admin', 'owner'] }] },\n },\n}\n\n// features/sessions/sessions.ts\nfirewall: [\n { field: 'organizationId', equals: 'ctx.activeOrgId' },\n { field: 'eventId', via: 'guestOf' },\n],\nread: { access: { roles: ['admin', 'member', 'guest'] } },\ncreate: { access: { roles: ['admin', 'guest'] } },\nupdate: { access: { roles: ['admin'] } },\n```\n\nThe compiler emits an inline Drizzle subquery against the relationship table and AND-composes it as the outermost firewall clause. The relationship table's own firewall (tenant scope, soft-delete) is honored inside the subquery; cross-tenant grants are impossible because the resource's tenant filter sits outermost.\n\nSupported surfaces: row-level scoping via `firewall: [{ field, via }]`, role gates on writes and reads, view access. Masking and action access reject relationship-roles at compile time with pointers to the working pattern (gate the row at the firewall layer, gate the role at the access layer).\n\nCross-tenant aggregation dashboards aren't solved by relationship-roles — the tenant firewall remains the outermost AND. For that pattern, use a user-scoped firewall or function-form access on a dedicated route.\n\nSee [Firewall → Relationship-based scoping](/compiler/definitions/firewall#relationship-based-scoping-via) and [Access → Relationship-based authorization](/compiler/definitions/access#relationship-based-authorization).\n\n### Bulk variants on record-based actions\n\n`defineAction({ bulkVariant: true })` emits `POST /:resource/batch/{action}` alongside the per-record route. The bulk handler loops the same access + transition + execute pipeline over a `{ ids, input, failFast? }` body:\n\n```ts\nexport default defineAction({\n description: \"Move an application forward in the pipeline.\",\n input: z.object({ nextStatus: z.enum([\"screening\", \"interview\", \"offer\"]) }),\n access: { roles: [\"owner\", \"admin\"] },\n bulkVariant: true,\n transition: { field: \"status\", via: \"nextStatus\", fromTo: { /* ... */ } },\n async execute({ db, record, input, whereTransition }) {\n // exact same body — runs once per id\n },\n});\n```\n\nPer-record outcomes return as 207 Multi-Status. `failFast: true` aborts on the first failure and wraps the loop in `db.transaction()` on tx-supporting providers; D1 fails fast without rollback. Max 100 IDs per request. Rejected on standalone actions and `unsafe` actions.\n\n### Aggregations on read views\n\nRead views can declare pre-computed metrics that surface alongside the row payload:\n\n```ts\nread: {\n views: {\n pipeline: {\n fields: [\"id\", \"jobId\", \"candidateId\", \"status\", \"appliedAt\"],\n aggregations: {\n totalApplications: { fn: \"count\" },\n byStatus: { fn: \"groupBy\", field: \"status\" },\n },\n },\n },\n}\n```\n\nAggregations run over the same firewalled, filtered set as the row query; pagination is intentionally ignored. Supported functions: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `groupBy`. See [Views → Aggregations](/compiler/definitions/views#aggregations).\n\n---\n\n## v0.13.5 — May 6, 2026\n\n### Object-form `auth.plugins` config is honored\n\nThe documented `plugins: { oauthProvider: {...} }`, `plugins: { organization: { teams: { enabled: true } } }` shapes now flow through the compiler unchanged. Per-plugin options reach the generated `auth.ts` as written.\n\n### `roles: [\"PUBLIC\"]` allowed on writes and actions\n\n`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access on every access node — reads, writes, views, and actions. The runtime trusts the marker; row-level safety comes from firewall, masking, and the action's own validation. `PUBLIC` actions continue to receive mandatory audit logging.\n\nCommon pattern: pair `roles: [\"PUBLIC\"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.\n\n---\n\n## v0.12.0 — May 5, 2026\n\n### Per-room authorization for PartyServer\n\n`bindings.durableObjects[].access` declares a path-scoped gate that runs the declared resource's firewall and `read.access` pipeline before the WebSocket upgrade:\n\n```ts\ndurableObjects: [\n // Single-resource: roomId IS the chat row id.\n { name: 'Chat', className: 'Chat', from: 'lib/Chat',\n access: { resource: 'chats' } },\n\n // Multi-resource: regex dispatches kind → resource.\n { name: 'Notepad', className: 'Notepad', from: 'lib/Notepad',\n access: {\n roomId: { pattern: '^(day-note|interaction|record):([A-Za-z0-9_-]+)$', kindGroup: 1, idGroup: 2 },\n resources: {\n 'day-note': { resource: 'day-notes' },\n 'interaction': { resource: 'interactions' },\n 'record': { resource: 'records' },\n },\n } },\n\n // Anonymous lobbies / public pads: explicit opt-out.\n { name: 'PublicLobby', className: 'PublicLobby', from: 'lib/PublicLobby',\n access: 'public' },\n]\n```\n\nThe gate 401s unauthenticated callers, 403s when the firewall hides the row, 404s when the row is missing. Resource references are validated against feature names at compile time. See [PartyServer Rooms → Per-room authorization](/stack/realtime/partyserver-rooms#per-room-authorization-via-access-v012).\n\n---\n\n## v0.11.1 — May 5, 2026\n\n### PartyServer auto-mount is secure by default\n\nThe `/realtime/*` auto-mount now wraps `partyserverMiddleware` in an auth check. Unauthenticated upgrades return 401; the four auth mechanisms (session cookie, JWT bearer, `x-api-key` header, query parameter) all unlock connections. Per-room access remains the `Server` class's responsibility in `onConnect`.\n\n---\n\n## v0.11.0 — May 5, 2026\n\n### OAuth Provider (MCP-ready)\n\nQuickback can act as a standards-compliant OAuth 2.1 + OIDC authorization server via [`@better-auth/oauth-provider`](https://better-auth.com/docs/plugins/oauth-provider). Enable with `plugins: [\"oauthProvider\"]`. The compiler auto-includes Better Auth's `jwt` plugin and the Account SPA gains a `/consent` page for the standard authorization-code flow.\n\nThis replaces Better Auth's deprecated `mcp` plugin and gives every MCP client (Cursor, Claude Desktop, claude.ai connectors, custom tooling) RFC 7591 dynamic client registration plus the discovery documents they need to bootstrap. See [Auth Plugins → OAuth Provider](/stack/auth/plugins#oauth-provider-mcp-ready).\n\n### API keys via query parameter\n\nThe auth middleware now accepts API keys as `?api_key=…` or `?key=…` query parameters. The `x-api-key` header takes precedence when both are sent. Prefer the header whenever the client supports it — query parameters land in access logs and `Referer` headers.\n\n### PartyServer rooms + realtime URL split\n\nThe realtime URL space is reorganized so names match what each primitive does:\n\n- **`/realtime/v1/*` → `/broadcast/v1/*`** — the org-wide Broadcaster moves to its semantically accurate prefix.\n- **`/realtime/<binding>/<room-id>`** — new mount for [PartyServer](/stack/realtime/partyserver-rooms) rooms. Per-room Durable Objects with presence and lifecycle hooks. Auto-mounted whenever a project declares any in-worker DO.\n\n**Breaking** — recompile + redeploy required:\n\n- `REALTIME_URL` env var renamed to `BROADCAST_URL`.\n- SPA helpers `getRealtimeWsUrl()` / `getRealtimeTicketUrl()` renamed to `getBroadcastWsUrl()` / `getBroadcastTicketUrl()`.\n- `appConfig.routes.api.realtime` renamed to `appConfig.routes.api.broadcast`.\n\n`partyserver`, `partysocket`, and `hono-party` are pre-installed in the compiler image; collab projects compile without an extra `npm install` step.\n\n---\n\n## v0.10.20 — May 4, 2026\n\n### In-worker Durable Objects\n\n`bindings.durableObjects[].from` flips a DO binding into in-worker mode and emits the export, the `[[migrations]]` block, and the `CloudflareBindings` type all together:\n\n```ts\ndurableObjects: [{\n name: \"ITEM_STREAM\",\n className: \"ItemStream\",\n from: \"features/loops/lib/ItemStream\",\n}]\n```\n\nDO class files live under `quickback/lib/` or `quickback/features/<feature>/lib/` — both copy verbatim into the generated `src/` tree on every compile. `from` and `scriptName` are mutually exclusive; cross-worker DOs (`scriptName` set) skip the re-export and migration block.\n\n`migrationTag` (default `qb-do-${className}`) is stable across regenerations and must never be removed or renamed once deployed. `useSqlite` defaults to `true`. See [Bindings → Durable Objects](/compiler/config/bindings#durableobjects).\n\n---\n\n## v0.10.18 — May 2, 2026\n\n### `experimentalRemote` — share deployed D1 with `wrangler dev`\n\nPer-binding `experimental_remote = true` lets `wrangler dev` read/write deployed D1 for selected bindings:\n\n```ts\nproviders: {\n database: defineDatabase(\"cloudflare-d1\", {\n splitDatabases: true,\n experimentalRemote: { auth: true, features: false },\n }),\n}\n```\n\nUseful for \"share prod auth in dev, keep feature writes sandboxed.\" Off by default.\n\n### Google OAuth + signup ToS\n\nThe Account SPA wires Google OAuth end-to-end when configured under `auth.config.socialProviders.google.enabled`. The signup flow gains a Terms-of-Service checkbox gate (configurable via the Account SPA branding).\n\n### CLI compile auth gate\n\n`quickback compile` now requires authentication for cloud-compiler runs. Device-flow `?redirect=` parameters are standardized across the login + signup pages so a user clicking \"Create one\" no longer loses their return URL.\n\n---\n\n## v0.10.15–v0.10.17 — May 2, 2026\n\n### CSP auto-config\n\nWhen `security.csp` is set, the compiler widens directives additively based on the project's enabled features:\n\n| Trigger | Auto-added | Directive |\n|---|---|---|\n| `cms: true` OR `account: true` | `'unsafe-inline'`, `https://fonts.googleapis.com` | `styleSrc` |\n| `cms: true` OR `account: true` | `https://fonts.gstatic.com` | `fontSrc` |\n| `csp` set (always) | `@trustedOrigins` | `connectSrc` |\n| Bundled SPA enabled | SPA-baked API origin (`config.domain`, `quickback.{baseDomain}`, `cms.domain`, `account.domain`) | `connectSrc` |\n\nAnything you already wrote stays — auto-config never removes or overrides. Each applied addition is logged to stderr. Opt out with `security: { cspAutoConfig: false }`.\n\nMost projects can write the minimal:\n\n```ts\nsecurity: {\n csp: {\n defaultSrc: ['@self'],\n scriptSrc: ['@self'],\n objectSrc: ['@none'],\n upgradeInsecureRequests: true,\n },\n}\n```\n\n…and the compiler fills in font hosts, trusted origins, and SPA-baked URLs.\n\nWhen a target directive is missing, auto-config scaffolds it from `default-src` baseline rather than widening `default-src` itself — CSP3 fall-back semantics would otherwise leak the addition to every directive that falls back to `default-src`.\n\n---\n\n## v0.10.14 — May 1, 2026\n\n### `auth.jwt` config\n\nThe bearer-token JWT used by the auth fast-path is configurable. Tune `expiresIn` to bound the post-revocation replay window without affecting browser SPAs (which auto-refresh on every authed call):\n\n```ts\nauth: {\n jwt: {\n expiresIn: 30,\n issuer: 'my-api',\n audience: 'partner-svc',\n secretEnv: 'CUSTOM_JWT_SECRET',\n },\n}\n```\n\n### Admin MCP endpoints filtered\n\nBetter Auth admin endpoints (`/admin/list-users`, `/admin/ban-user`, etc.) now carry `x-access: { userRole: ['admin'] }` in the generated OpenAPI spec. The MCP `tools/list` access-filter drops them for non-admin callers.\n\n### Declarative `security` config\n\nEvery security response header (`Content-Security-Policy`, COOP, COEP, CORP, HSTS, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`) is configurable from `quickback.config.ts`. `@`-prefixed sentinels (`@self`, `@none`, `@unsafe-inline`, `@trustedOrigins`, etc.) replace awkward `\"'self'\"` quoting.\n\nThe compiler lints the resolved config for known footguns: `@unsafe-inline` in `script-src`, wildcard sources, missing `default-src`, HSTS preload-list misconfiguration.\n\n### HSTS skipped on localhost\n\nGenerated middleware skips `Strict-Transport-Security` when the request hostname is `localhost`, `127.0.0.1`, or `*.localhost`. Without this gate, `wrangler dev` would pin a developer's browser to HTTPS across every project on that machine.\n\n---\n\n## v0.10.13 — May 1, 2026\n\n### Clickjacking defence on every Worker\n\nEvery Worker emits `Content-Security-Policy: frame-ancestors 'self' <TRUSTED_ORIGINS…>` and `X-Frame-Options: SAMEORIGIN` on every response. The CSP allowlist is sourced from the same `TRUSTED_ORIGINS` constant that gates CORS.\n\n---\n\n## v0.10.11 — May 1, 2026\n\n### MCP `tools/list` is access-filtered\n\nEach MCP tool now carries sanitised access metadata. `tools/list` filters against the caller's `ctx`: unauthenticated callers see only `PUBLIC` tools, authenticated callers see only role-gated tools they pass.\n\n- Wildcard CORS removed from the MCP endpoint.\n- Unauthenticated `GET /mcp` no longer enumerates tool names.\n- Internal flavor text is removed; `annotations.destructiveHint` and `_unsafe` remain — those are the spec-correct signals for clients.\n\n`tools/call` continues to re-enter the Hono app and run every middleware (auth, firewall, access, guards, masking), so hiding a tool from list never weakens the underlying gate.\n\n---\n\n## v0.10.10 — April 29, 2026\n\n### Reserved keys in `access.record` are rejected\n\n`access.record` is a flat field map evaluated as implicit AND between entries — keys must be column names. The compiler now rejects reserved keys (`and`, `or`, `roles`, `userRole`) inside `record` with migration guidance pointing at the working pattern (top-level siblings with their own `record:` blocks).\n\n---\n\n## v0.10.8 — April 29, 2026\n\n### Audit logging on Postgres targets\n\n`audit_events` previously only existed on `cloudflare-d1`. The audit table now lives in a dedicated `audit` schema (`drizzle.pgSchema('audit')`) on Postgres targets. The `hasSecurityAudit` gate accepts D1 or any PG dialect; `auditDatabaseId` remains a D1-only requirement.\n\n### `auditDatabaseId` is a compile-time requirement\n\nProjects with unsafe or `PUBLIC` actions that previously produced a placeholder `database_id = \"local-audit\"` in production now fail at compile time with the exact `wrangler d1 create <project>-audit` command and the config key where the returned ID goes.\n\n### Action input → OpenAPI / MCP\n\n`defineAction({ input: z.object({...}) })` schemas flow into the OpenAPI `requestBody` and the MCP tool's `inputSchema.properties`. Simple `z.object` shapes are extracted at compile time; discriminated unions, refinements, recursive schemas, and bare-identifier references run through Zod's native `z.toJSONSchema()` for full-fidelity output.\n\n### OpenAPI fidelity\n\n- Response schemas emit `required[]` for every non-nullable column.\n- `text(_, { enum: [...] })` columns emit as closed `{ type: \"string\", enum: [...] }`.\n- `id` claims `format: \"uuid\"` only when the project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators emit plain `{ type: \"string\" }`.\n\n### Minor\n\n- Auto-mask predicate verifies the resolved owner column exists before emitting an `or: 'owner'` clause; falls back to roles-only with a warning otherwise.\n- Generated CRUD errors emit canonical `QuickbackErrorCode` enum values (`DB_NOT_NULL_VIOLATION`, `DB_UNIQUE_VIOLATION`, etc.) so generated SDKs can exhaustively switch on `code`. See [API errors](/compiler/targets/hono-api/using-the-api/errors#database).\n\n---\n\n## DSL: one file per action, multi-table per feature\n\n### One file per action\n\nAction authoring is one file per action under `<feature>/actions/<name>.ts`. The filename is the action name and the URL segment:\n\n```typescript\n// features/applications/actions/advance.ts\n\nexport default defineAction({\n description: \"Move an application forward in the pipeline\",\n input: z.object({ nextStatus: z.enum([\"screening\", \"interview\", \"offer\"]) }),\n access: { roles: [\"owner\", \"admin\"] },\n transition: {\n field: \"status\",\n via: \"nextStatus\",\n fromTo: { applied: [\"screening\"], screening: [\"interview\"], interview: [\"offer\"] },\n },\n async execute({ db, record, input, auditFields, whereTransition }) { /* … */ },\n});\n```\n\n`defineAction` is imported from a generated per-feature helper at `<feature>/.quickback/define-action.ts` — `record`, `input`, and audit fields are typed without manual annotations.\n\n**Discovery rules:**\n- `actions/<name>.ts` binds to the feature's primary table.\n- `actions/<table>/<name>.ts` binds to the sibling table file.\n- Setting `path:` makes the action standalone (custom URL, no record fetch).\n- Tableless features require every action to be standalone.\n\n**Retired** (rejected at load time with migration guidance): `actions.ts` (bundled multi-action file), `_feature.ts`, `handlers/` directory + `handler:` string ref, `defineActions(table, {…})`, colocated `defineActions` inside table files, `standalone: true` flag, `*-actions.ts` / `*.actions.ts` filename patterns.\n\nSee [Actions docs](/compiler/definitions/actions).\n\n### Multi-table actions per feature\n\nOne feature directory can own actions on multiple tables. Three discovery modes:\n\n- **Colocated** (canonical) — `<table>.ts` containing both `defineTable` and `defineActions(<table>, …)`. One file per entity.\n- **`actions.ts`** — single primary-table actions file at feature root.\n- **`actions/<table>.ts`** — per-table action files for strict schema/behavior separation.\n\nPlus a universal `_feature.ts` slot for non-table-bound feature-level actions and shared Zod schemas.\n\nAction names are unique per `(bindTable, name)` pair. Sibling-bound `actions/episodes/publish.ts` and `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish` and compile cleanly.\n\n---\n\n## Firewall: named-scope shape\n\nThe named-scope firewall shape is a co-equal user-facing input alongside the predicate array:\n\n```typescript\nfirewall: { organization: { column: 'tenant_id' } } // named-scope (compact)\nfirewall: { owner: { column: 'account_user_id' } }\nfirewall: { exception: true }\nfirewall: [\n { field: 'organizationId', equals: 'ctx.activeOrgId' },\n { field: 'deletedAt', isNull: true },\n] // predicate array (explicit)\n```\n\nPick the form that reads better — named-scope for the common one-line case, predicate array when you need custom `in`-lists or non-scope predicates.\n\n**Auto-detection synonyms.** When `firewall:` is omitted, the compiler scans the schema for an isolation column. The org-scope list accepts `organizationId`, `organisationId`, `orgId`, `organization`, `organisation`, `org` (American + British). User-scope accepts `userId`.\n\n**`ownerId` is a targeted error signal.** When a table carries `ownerId` but no isolation column and no explicit `firewall:`, the compiler raises a specific error — `ownerId` is business-logic ownership, not access control. Use `userId` for access control, declare an explicit `firewall:`, or add a separate isolation column.\n\n---\n\n## v0.10.0 — April 26, 2026\n\n### `q.scope()` — single-declaration tenant scoping\n\n`q.scope(kind)` replaces the three-place pattern (column declaration + firewall predicate + ownership-guard) with one column:\n\n```typescript\ncolumns: {\n organizationId: q.scope('organization'), // → ctx.activeOrgId\n ownerId: q.scope('owner'), // → ctx.userId\n teamId: q.scope('team'), // → ctx.activeTeamId\n}\n```\n\n`q.scope()` columns auto-derive the firewall predicate, register with the guards layer as `systemManaged` (client input rejected), and auto-populate from `ctx` on create / upsert. The systemManaged extension generalises beyond `q.scope()`: any firewall predicate whose `equals` references `ctx.*` registers its `field` automatically.\n\nSee [`q.scope()`](/compiler/definitions/schema#qscope--tenant-scope-columns).\n\n### `masking[col].query.roles` — unified filter / sort / search gate\n\nThe three legacy per-capability flags (`filterable`, `searchable`, `sortable`) are replaced by a single `query.roles` allowlist:\n\n```typescript\nmasking: {\n email: {\n type: 'email',\n show: { roles: ['admin'] },\n query: { roles: ['admin'] }, // defaults to show.roles when omitted\n },\n}\n```\n\nA view's own `query.{filterable,searchable,sortable}` allowlist is the opt-in for higher-privileged roles; the existing intersection validator gates it at compile time.\n\n**Breaking:** `masking[col].filterable / .searchable / .sortable` is rejected at compile time with a migration hint. Replace with `query.roles` (or delete the flags — `query` defaults to `show.roles`).\n\n---\n\n## v0.9.0 — April 25, 2026\n\n### Unified `read:` pipeline\n\nThe read side of every resource has its own block — `read:` — that owns the collection-level `GET /` endpoint, single-record `GET /:id`, and named view projections.\n\n**Breaking changes** (compile-time errors with migration hints):\n\n- `crud.list` → `read.access` (plus `read.pageSize` / `read.maxPageSize`)\n- `crud.get` → `read.access` (single-record GET inherits automatically)\n- Top-level `views: {...}` → `read.views: {...}`\n- `crud.list.fields` / `crud.get.fields` → declare a named view under `read.views` and call `/views/{name}`\n\n### Pre-record access ordering\n\nHandlers on `/:id` run a role-only access check before the firewall query. A caller without a matching role gets 403 before the database is touched. This closes the 404-vs-403 ID-probe channel — an unauthorized caller can no longer distinguish \"row exists in another tenant\" from \"row doesn't exist.\" See [Access evaluation order](/compiler/definitions/access#evaluation-order).\n\n### Transactional batch operations\n\nBatch endpoints expose `failFast` and a `meta.transactional` response field. On tx-supporting providers (postgres, supabase, neon, libsql, better-sqlite3, bun-sqlite), `failFast: true` wraps the per-record loop in `db.transaction(...)` so any failure rolls back the entire batch. On Cloudflare D1 (no `db.transaction`), `failFast: true` stops on the first error but prior writes stay committed.\n\nEmbedding queue messages and realtime broadcasts emit after the transaction commits — rolled-back batches produce no orphan jobs.\n\nSee [Batch Operations → Transactional semantics](/compiler/targets/hono-api/using-the-api/batch-operations#transactional-semantics).\n\n---\n\n## v0.8.7 — April 17, 2026\n\n### Hono CVE bump\n\nHono is bumped to `^4.12.14` across the monorepo, the compiler Docker image's pre-installed deps, and every generator path that emits Hono into compiled projects. Older ranges covered the vulnerable window. Recompile to pick up the fix in your generated project's `package.json`.\n\n### Cloudflare Email Sending in public beta\n\nQuickback defaults to the Workers `send_email` binding for Cloudflare deploys. Cloudflare Email Sending has graduated to public beta — production-ready with zero-config. AWS SES remains a fully supported opt-in (`email.provider: 'aws-ses'`) for non-Cloudflare runtimes. See [Email Configuration](/compiler/config#email-configuration).\n\n### Dependency sweep\n\n`wrangler@^4.83.0`, `drizzle-orm@^0.45.2`, `drizzle-kit@^0.31.10`, `zod@^4.3.6`, `@cloudflare/workers-types@^4.20260417.1`.\n\n---\n\n## v0.8.5 — April 15, 2026\n\n### `userRole` access primitive\n\nA new `userRole?: string[]` field in the declarative `Access` config evaluates against `ctx.userRole` (the Better Auth admin-plugin `user.role` column). Distinct from `roles`, which matches `ctx.roles` (org membership).\n\n```typescript\n// Org owner OR platform admin\naccess: { or: [{ roles: ['owner'] }, { userRole: ['admin'] }] }\n\n// Platform admins see SSNs across every org\nmasking: { ssn: { type: 'ssn', show: { userRole: ['admin'] } } }\n```\n\n`userRole` works everywhere `Access` is accepted — CRUD, actions, views, masking, and inside `or` / `and` combinators. See [Access → userRole vs roles](/compiler/definitions/access#userrole-vs-roles).\n\n### CMS admin gate enforced server-side\n\n`cms: { access: \"admin\" }` previously only hid the CMS link in Account UI and rendered an \"Access Denied\" screen inside the SPA. Server-side enforcement now applies at every CMS-facing surface: the SPA shell, `/api/v1/schema`, and `custom_view` CRUD.\n\n### Better Auth 1.5 + `@cloudflare/workers-types` compatibility\n\nGenerated API code typechecks against the new versions. The org-member role-change broadcast hook is emitted via `organizationHooks.afterUpdateMemberRole` (the supported shape after the 1.5 deprecation of `databaseHooks.member.update.after`). `REALTIME_URL` and `ACCESS_TOKEN` are always emitted as optional bindings when the organization plugin is active.\n\n---\n\n## v0.8.4 — April 14, 2026\n\n### `generateId: \"short\"` strategy\n\nA compact ID option for tables where short, shareable codes matter more than collision resistance at scale:\n\n```typescript\nproviders: {\n database: defineDatabase(\"cloudflare-d1\", { generateId: \"short\" }),\n}\n```\n\nGenerates 6-character alphanumeric IDs (e.g. `a3F9xK`) using nanoid's `customAlphabet` with the full 62-char alphabet (`0-9A-Za-z`). Requires the `nanoid` package.\n\n**When to use:** room codes, invite links, share URLs, ephemeral records.\n\n**When not to use:** high-volume tables. 62^6 ≈ 56.8B combinations means ~238K rows before a 50% collision probability. For large tables stick with `\"uuid\"`, `\"cuid\"`, or `\"prefixed\"`. See [Providers → ID Generation Options](/compiler/config/providers#id-generation-options).\n\n---\n\n## v0.8.2 — April 11, 2026\n\n### Catch-all `VITE_QUICKBACK_URL`\n\nA single Quickback origin can be set in place of four separate URL env vars:\n\n```bash\nVITE_QUICKBACK_URL=https://secure.example.com\n```\n\n| Individual var (explicit) | Fallback when unset |\n|---|---|\n| `VITE_QUICKBACK_API_URL` | `${VITE_QUICKBACK_URL}` |\n| `VITE_QUICKBACK_ACCOUNT_URL` | `${VITE_QUICKBACK_URL}/account` |\n| `VITE_QUICKBACK_CMS_URL` | `${VITE_QUICKBACK_URL}/cms` |\n\n`VITE_QUICKBACK_APP_URL` stays independent — it points at the tenant's own frontend. Non-breaking; individual vars take precedence when set. Library users can set `__QUICKBACK_URL__` on `globalThis`. See [Environment Variables](/stack/account-ui/environment-variables).\n\n---\n\n## v0.8.1 — April 9, 2026\n\n### Role hierarchy with `+` suffix\n\nDefine a hierarchy and use `+` to mean \"this role and above\":\n\n```typescript\nauth: { roleHierarchy: ['member', 'admin', 'owner'] }\n\ncrud: {\n list: { access: { roles: [\"member+\"] } }, // member, admin, owner\n create: { access: { roles: [\"admin+\"] } }, // admin, owner\n delete: { access: { roles: [\"owner\"] } }, // owner only\n}\n```\n\nRoles are expanded at compile time. No `+` = exact match. See [Access → Role Hierarchy](/compiler/definitions/access#role-hierarchy).\n\n---\n\n## v0.8.0 — April 9, 2026\n\n### Breaking: VITE URL environment variables namespaced\n\nAll Quickback-generated URL environment variables are namespaced under `VITE_QUICKBACK_*` to avoid collisions with other Vite projects.\n\n| Old | New |\n|-----|-----|\n| `VITE_API_URL` | `VITE_QUICKBACK_API_URL` |\n| `VITE_ACCOUNT_URL` | `VITE_QUICKBACK_ACCOUNT_URL` |\n| `VITE_APP_URL` | `VITE_QUICKBACK_APP_URL` |\n| `VITE_CMS_URL` | `VITE_QUICKBACK_CMS_URL` |\n\nNon-URL variables are unchanged (`VITE_ENABLE_*`, branding vars, `VITE_STRIPE_PUBLISHABLE_KEY`).\n\n**Action required:**\n- Compiled projects: re-run `quickback compile`.\n- Standalone deploys: update `.env`, `.env.production`, and `wrangler.toml` files manually.\n- Library users: `__QUICKBACK_API_URL__` / `__QUICKBACK_APP_URL__` globals are unchanged.\n\n### CMS access control\n\n`cms.access: \"admin\"` enforces access at the CMS level, not just link visibility. Non-admin users (`user.role !== \"admin\"`) see an \"Access Denied\" screen with a sign-out button.\n\n---\n\n## v0.5.11 — February 24, 2026\n\n### Mandatory unsafe action audit trail\n\nStructured `unsafe` config (`unsafe: { reason, adminOnly, crossTenant, targetScope }`). Cross-tenant unsafe actions require Better Auth authentication plus platform admin role (`ctx.userRole === \"admin\"`). Mandatory audit logging on success, denial, and error paths. Cloudflare output includes `AUDIT_DB` wiring, `drizzle.audit.config.ts`, and `db:migrate:audit:*` scripts when unsafe actions are present.\n\nCompile-time raw SQL guard for actions and handlers (`allowRawSql: true` required per action).\n\n### Security contract report artifacts\n\nGenerated security contract artifacts: `reports/security-contracts.report.json`, `reports/security-contracts.report.sig.json`. Config-driven signing controls (`compiler.securityContracts.report.signature.*`). Missing required signing keys fail loudly with explicit remediation.\n\n### Headless Drizzle rename hints\n\n`compiler.migrations.renames` configuration for CI/CD environments where Drizzle's interactive rename prompts block compilation. See [Configuration](/compiler/config).\n\n### Minor\n\n- Email OTP magic links work correctly.\n- Auth is required for all API routes when running locally.\n- Single-file multi-table exports alongside `defineTable()` produce a clear error.\n\n---\n\n## v0.5.8 — February 14, 2026\n\n### Quickback CMS\n\nA schema-driven admin panel that connects to your generated API. The compiler now outputs a JSON schema registry consumed by the CMS at runtime. Firewall error modes (`reveal` for 403 with details, `hide` for opaque 404) are configurable per resource for security-sensitive deployments.\n\n---\n\n## v0.5.7 — February 12, 2026\n\n### Scoped database for actions\n\nActions receive a security-scoped database instead of a raw Drizzle instance. The compiler generates a proxy wrapper that automatically enforces org isolation, owner filtering, and soft-delete visibility — the same protections that CRUD routes have always had.\n\nDuck-typed column detection at runtime:\n\n| Column Detected | SELECT / UPDATE / DELETE | INSERT |\n|---|---|---|\n| `organizationId` | Adds `WHERE organizationId = ?` | Auto-injects `organizationId` from context |\n| `ownerId` | Adds `WHERE ownerId = ?` | Auto-injects `ownerId` from context |\n| `deletedAt` | Adds `WHERE deletedAt IS NULL` | — |\n\nEvery action is secure by default — no manual `WHERE` clauses needed.\n\nActions that intentionally need to bypass security (admin reports, cross-org queries, migrations) can declare `unsafe: true` to receive a raw, unscoped database handle via `rawDb`:\n\n```typescript\ndefineActions(analytics, {\n globalReport: {\n unsafe: true,\n execute: async ({ db, rawDb, ctx, input }) => {\n // db → still scoped (safety net)\n // rawDb → bypasses all security filters\n const allOrgs = await rawDb.select().from(organizations);\n },\n },\n});\n```\n\nWithout `unsafe: true`, `rawDb` is `undefined`. See [Actions](/compiler/definitions/actions).\n\n### Cascading soft delete\n\nSoft-deleting a parent record automatically cascades to child and junction tables within the same feature. The compiler detects foreign key references at build time and generates cascade `UPDATE` statements.\n\nRules:\n- Applies to soft delete only. Hard delete relies on database-level `ON DELETE CASCADE`.\n- Cascades within the same feature only — cross-feature references are not affected.\n- Child tables must have `deletedAt` / `deletedBy` columns (auto-added by the compiler).\n\nSee [Actions API → Cascading Soft Delete](/compiler/targets/hono-api/using-the-api/actions-api#cascading-soft-delete).\n\n### Advanced query parameters\n\nNew capabilities for all list endpoints:\n\n- **Field selection** — `?fields=id,name,status`\n- **Multi-sort** — `?sort=status:asc,createdAt:desc`\n- **Total count** — `?count=true` returns total matching records in `X-Total-Count`\n- **Full-text search** — `?search=keyword` searches across all text columns\n\nSee [Query Parameters](/compiler/targets/hono-api/using-the-api/query-params).\n\n---\n\n## v0.5.5 — February 5, 2026\n\n### OpenAPI spec generation\n\nGenerated APIs include a full OpenAPI specification at `/openapi.json`. Better Auth endpoints are included in the spec.\n\n### Better Auth plugins\n\nPublished `@quickback-dev/better-auth-upgrade-anonymous` (post-passkey email collection flow), `@quickback-dev/better-auth-combo-auth` (combined email + password + OTP), and `@quickback-dev/better-auth-aws-ses` (AWS SES email provider).\n\n### Security headers\n\nGlobal error handler prevents leaking internal error details. Security headers middleware (CSP, HSTS, X-Frame-Options, X-Content-Type-Options). `BETTER_AUTH_SECRET` properly passed to generated config.\n\n---\n\n## v0.5.4 — January 30, 2026\n\n### Account UI\n\nPre-built authentication UI deployed as Cloudflare Workers. Sessions, organizations, passkeys, passwordless, admin panel, API keys. Dual-mode: standalone (degit template) or embedded with Quickback projects.\n\n### Webhook system\n\nInbound webhook endpoints with signature verification. Outbound webhooks via Cloudflare Queues with automatic retries. Configurable per-feature webhook events.\n\n### Realtime & vector search\n\nDurable Objects + WebSocket realtime subscriptions. Vector embeddings via Cloudflare Vectorize. KV and R2 storage integrations.\n\n---\n\n## v0.5.0 — January 2026\n\n### Initial release\n\n- **Quickback Compiler** — TypeScript-first backend compiler.\n- **Four security pillars** — Firewall, Access, Guards, Masking.\n- **`defineTable()`** — schema + security configuration in a single file.\n- **Templates** — Cloudflare Workers, B2B SaaS.\n- **Cloud compiler** — remote compilation via `compiler.quickback.dev`.\n- **CLI** — `quickback create`, `quickback compile`.\n- **Better Auth integration** — organizations, roles, sessions.\n- **Drizzle ORM** — schema-first with automatic migrations.\n- **Cloudflare D1** — split database support (auth + features)."
7
7
  },
8
8
  "compiler/claude-code-skill": {
9
9
  "title": "AI Developer Tools",
@@ -343,7 +343,7 @@ export const DOCS = {
343
343
  },
344
344
  "stack/auth/plugins": {
345
345
  "title": "Auth Plugins",
346
- "content": "Quickback ships with a curated set of Better Auth plugins and helper wiring so your auth stack is production-ready by default. Enable these in `quickback.config.ts` under `providers.auth`.\n\n## Available Plugins\n\n### Email OTP (with AWS SES)\n\nQuickback wires the Better Auth Email OTP flow to AWS SES. When `emailOtp` is enabled, the compiler emits the SES plugin and combo-auth email flow (magic link + OTP).\n\n**Enable in config:**\n\n```ts\n\nexport default defineConfig({\n name: \"quickback-api\",\n providers: {\n runtime: defineRuntime(\"cloudflare\"),\n database: defineDatabase(\"cloudflare-d1\", {\n vars: {\n AWS_SES_REGION: \"us-east-2\",\n EMAIL_FROM: \"noreply@yourdomain.com\",\n EMAIL_FROM_NAME: \"Your App | Account Services\",\n APP_NAME: \"Your App\",\n APP_URL: \"https://account.yourdomain.com\",\n BETTER_AUTH_URL: \"https://api.yourdomain.com\",\n },\n }),\n auth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: [\"emailOtp\"],\n }),\n },\n});\n```\n\n**Endpoints:**\n- `POST /auth/v1/email-otp/send-verification-otp`\n- `POST /auth/v1/email-otp/verify-otp`\n\n**Email readiness check:**\n\nUse this to show UI warnings when SES isn't configured.\n\n- `GET /api/v1/system/email-status`\n- Response: `{ \"emailConfigured\": true|false }`\n\n### Upgrade Anonymous\n\nAdds a first-class endpoint to convert an anonymous user into a full user. This flips `isAnonymous` to `false` and refreshes the session cache immediately.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: [\"anonymous\", \"upgradeAnonymous\"],\n}),\n```\n\n**Endpoint:**\n- `POST /auth/v1/upgrade-anonymous`\n\n**Note:** If you send `Content-Type: application/json`, include a body (an empty `{}` is fine). This avoids request parsing errors in some clients.\n\n### SMS OTP (with AWS SNS)\n\nWhen `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via [`@quickback-dev/better-auth-aws-sns`](/stack/auth/plugins/aws-sns). The plugin adds `phoneNumber` / `phoneNumberVerified` columns to the user table, handles OTP generation + storage + verify-attempt limits, and exposes endpoints for phone-only sign-in, phone+password sign-in, and password reset via SMS.\n\n**Enable in config:**\n\n```ts\nexport default defineConfig({\n name: \"my-app\",\n sms: {\n provider: \"aws-sns\",\n region: \"us-east-1\",\n },\n providers: {\n runtime: defineRuntime(\"cloudflare\"),\n database: defineDatabase(\"cloudflare-d1\"),\n auth: defineAuth(\"better-auth\", {\n plugins: { phoneNumber: true },\n }),\n },\n});\n```\n\n**Endpoints (managed by Better Auth):**\n- `POST /auth/v1/phone-number/send-otp`\n- `POST /auth/v1/phone-number/verify`\n- `POST /auth/v1/sign-in/phone-number`\n- `POST /auth/v1/phone-number/request-password-reset`\n- `POST /auth/v1/phone-number/reset-password`\n\n**Why use SMS:** corporate email gateways frequently break transactional auth emails (link rewriting, click-tracking, MITM scanners). SMS is the most reliable channel for a six-digit code that has to land in under a minute. See the [AWS SNS plugin page](/stack/auth/plugins/aws-sns) for IAM, 10DLC registration, and sender-ID details.\n\n### AWS SES Plugin\n\nThis is a Quickback-provided Better Auth plugin for Email OTP and other transactional emails. It handles SES signing and delivery over the Web Crypto API so it runs in Cloudflare Workers without the AWS SDK. It is wired up only when you opt in via `email.provider: 'aws-ses'` — the default transport is Cloudflare Email Sending (`send_email` binding).\n\nRequired vars (only when `email.provider: 'aws-ses'` is set; use Wrangler secrets for credentials):\n- `AWS_ACCESS_KEY_ID` (secret)\n- `AWS_SECRET_ACCESS_KEY` (secret)\n- `AWS_SES_REGION`\n- `EMAIL_FROM`\n\nOptional vars:\n- `EMAIL_FROM_NAME`\n- `EMAIL_REPLY_TO` - Reply-to address for emails (defaults to `EMAIL_FROM`)\n- `APP_NAME`\n- `APP_URL`\n- `BETTER_AUTH_URL`\n\n### Magic Links\n\nMagic links provide passwordless authentication by sending a unique login link to the user's email. When clicked, the link authenticates the user without requiring a password.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"magicLink\"],\n}),\n```\n\n**Endpoints:**\n- `POST /auth/v1/magic-link/send` - Send magic link email\n- `GET /auth/v1/magic-link/verify` - Verify magic link token\n\n**Email customization:**\n\nMagic link emails use the same AWS SES configuration as Email OTP. Customize the email template via environment variables:\n\n- `APP_NAME` - Application name in email subject\n- `APP_URL` - Base URL for magic link redirect\n- `EMAIL_FROM` - Sender email address\n- `EMAIL_FROM_NAME` - Sender display name\n\n**Frontend integration:**\n\n```ts\n// Request magic link\nawait fetch('/auth/v1/magic-link/send', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ email: 'user@yourdomain.com' })\n});\n\n// User clicks link in email, which redirects to your app\n// The token is verified automatically via the callback URL\n```\n\n### Passkeys\n\nPasskeys provide passwordless authentication using WebAuthn/FIDO2. Users authenticate with biometrics (fingerprint, face) or device PIN instead of passwords.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"passkey\"],\n}),\n```\n\n**Required environment variable:**\n- `ACCOUNT_URL` - Your account/frontend URL (used as the relying party origin for WebAuthn)\n\n**Endpoints:**\n- `POST /auth/v1/passkey/register/options` - Get registration challenge\n- `POST /auth/v1/passkey/register/verify` - Complete registration\n- `POST /auth/v1/passkey/authenticate/options` - Get authentication challenge\n- `POST /auth/v1/passkey/authenticate/verify` - Complete authentication\n- `GET /auth/v1/passkey/list-user-passkeys` - List user's registered passkeys\n- `POST /auth/v1/passkey/delete-passkey` - Delete a registered passkey\n\n**Browser support:**\n\nPasskeys are supported in all modern browsers:\n- Chrome 67+\n- Safari 14+\n- Firefox 60+\n- Edge 79+\n\n**Registration flow:**\n\n```ts\n// 1. Get registration options\nconst optionsRes = await fetch('/auth/v1/passkey/register/options', {\n method: 'POST',\n credentials: 'include'\n});\nconst options = await optionsRes.json();\n\n// 2. Create credential using WebAuthn API\nconst credential = await navigator.credentials.create({\n publicKey: options\n});\n\n// 3. Send credential to server\nawait fetch('/auth/v1/passkey/register/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n credentials: 'include',\n body: JSON.stringify(credential)\n});\n```\n\n**Authentication flow:**\n\n```ts\n// 1. Get authentication options\nconst optionsRes = await fetch('/auth/v1/passkey/authenticate/options', {\n method: 'POST'\n});\nconst options = await optionsRes.json();\n\n// 2. Get credential using WebAuthn API\nconst credential = await navigator.credentials.get({\n publicKey: options\n});\n\n// 3. Verify credential\nawait fetch('/auth/v1/passkey/authenticate/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n credentials: 'include',\n body: JSON.stringify(credential)\n});\n```\n\n### JWT Plugin\n\nBetter Auth's JWT plugin adds asymmetric-signed tokens and a JWKS endpoint for external services that need to verify user identity without sharing a shared secret.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"jwt\"],\n}),\n```\n\n**Endpoints:**\n- `GET /auth/v1/jwks` — public keys for verifying BA-issued tokens\n- `POST /auth/v1/token` — mint an asymmetric-signed JWT from the current session\n\n**When to enable:** you have external services (non-Quickback workers, third-party integrations) that need to verify a user's identity via JWKS without holding `BETTER_AUTH_SECRET`. The BA-issued tokens won't carry Quickback's `orgId`/`role` claims, so they're for identity, not API access.\n\n### API Keys\n\nStatic, long-lived credentials for cron jobs, scripts, and machine-to-machine integrations. Better Auth's `apiKey` plugin is auto-included when you enable the organizations feature, so no explicit config is required for the standard B2B SaaS shape.\n\n**Authenticating requests:**\n\nPass the key as the `x-api-key` header (preferred) or as an `?api_key=` / `?key=` query parameter:\n\n```bash\n# Header form (preferred — keys don't leak into access logs or Referer)\ncurl -H \"x-api-key: ${KEY}\" https://api.example.com/v1/jobs\n\n# Query-param form (for clients that can't inject custom headers,\n# e.g., claude.ai's MCP connector)\ncurl \"https://api.example.com/v1/jobs?api_key=${KEY}\"\n```\n\nThe header takes precedence when both are present. The query-param form lands in nginx / Cloudflare access logs and `Referer` headers when the page navigates away — prefer headers whenever the client supports them.\n\n**Endpoints (managed by Better Auth):**\n- `POST /auth/v1/api-key/create` — issue a new key (returns the secret once; store it)\n- `GET /auth/v1/api-key/list` — list keys for the current user\n- `POST /auth/v1/api-key/delete` — revoke a key\n\nKeys can carry organization context via `metadata.organizationId` — when set, the auth middleware looks up the user's role in that org and populates `ctx.roles` accordingly, so a single key inherits the same firewall + access scope as the user who created it.\n\n### OAuth Provider (MCP-ready)\n\nTurns your Quickback worker into a standards-compliant OAuth 2.1 + OIDC authorization server. The plugin ships RFC 7591 dynamic client registration plus the well-known discovery documents an MCP client needs to bootstrap itself, so every future MCP client (Cursor, Claude Desktop, Cowork, custom integrations) Just Works without bespoke per-client header injection.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"oauthProvider\"],\n}),\n```\n\nThe compiler auto-includes Better Auth's `jwt` plugin alongside `oauthProvider` — `@better-auth/oauth-provider` delegates access-token signing to it, and schema generation fails without it.\n\n**Custom configuration** (object form):\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: {\n oauthProvider: {\n consentPage: \"/consent\", // path on ACCOUNT_URL — default\n loginPage: \"/login\", // path on ACCOUNT_URL — default\n allowDynamicClientRegistration: true, // default\n allowUnauthenticatedClientRegistration: true, // default — MCP needs this\n validAudiences: [\"https://api.example.com\"], // optional — defaults to BETTER_AUTH_URL\n scopes: [\"openid\", \"profile\", \"email\", \"offline_access\"],\n },\n },\n}),\n```\n\n**Endpoints:**\n\nDiscovery (public, no auth):\n- `GET /.well-known/oauth-authorization-server` — RFC 8414 metadata\n- `GET /.well-known/oauth-protected-resource` — MCP resource metadata\n- `GET /.well-known/openid-configuration` — OIDC discovery\n\nAuthorization flow:\n- `POST /oauth2/register` — RFC 7591 dynamic client registration\n- `POST /oauth2/authorize` — start auth code flow\n- `POST /oauth2/token` — exchange code or refresh for access token\n- `POST /oauth2/consent` — accept/deny (called by the consent page)\n- `POST /oauth2/introspect` — RFC 7662 token validity check\n- `POST /oauth2/revoke` — RFC 7009 token revocation\n- `GET /oauth2/userinfo` — OIDC user info (requires `openid` scope)\n\nClient management (authenticated):\n- `GET /oauth2/get-clients`, `GET /oauth2/get-client?client_id=`, `GET /oauth2/public-client?client_id=`\n- `POST /oauth2/create-client`, `POST /oauth2/update-client`, `POST /oauth2/delete-client`\n- `POST /oauth2/client/rotate-secret`\n\nConsent management:\n- `GET /oauth2/get-consents`, `GET /oauth2/get-consent?id=`\n- `POST /oauth2/update-consent`, `POST /oauth2/delete-consent`\n\n**Account SPA wiring:**\n\nThe compiled Account SPA already serves `/consent`. When `oauthProvider` is enabled, Better Auth redirects unauthenticated users to `${ACCOUNT_URL}/login?redirect=...` and authenticated users straight to `${ACCOUNT_URL}/consent?client_id=...&scope=...&oauth_query=...`. The bundled consent screen reads those params, fetches client metadata via `/oauth2/public-client`, and POSTs back to `/oauth2/consent`.\n\n**Verifying tokens in your own Workers / route handlers:**\n\nIssued tokens are JWTs by default — verify them locally without a DB hit:\n\n```ts\n\nconst serverClient = createAuthClient({\n plugins: [oauthProviderResourceClient(auth)],\n});\n\nconst token = req.headers.get(\"authorization\")?.replace(\"Bearer \", \"\");\nconst payload = await serverClient.verifyAccessToken(token, {\n verifyOptions: { issuer: env.BETTER_AUTH_URL, audience: env.BETTER_AUTH_URL },\n});\n// payload.sub → userId, payload.scope → granted scopes\n```\n\n**Why this and not the deprecated `mcp` plugin?**\n\nBetter Auth's older `better-auth/plugins/mcp` is being deprecated in favour of `@better-auth/oauth-provider`. The new package is a full OAuth 2.1 server (the MCP plugin only exposed a subset), supports dynamic registration that MCP clients now require, and lets you scope/revoke per-client.\n\nKeep `apiKey` enabled alongside it — server-to-server flows (cron, scripts) want a static key; OAuth is for interactive clients.\n\n### Custom plugins (escape hatch)\n\nThe named plugins above cover the curated set Quickback ships first-class wiring for. For anything else — third-party packages (`@better-auth-kit/audit`, …), Better Auth built-ins outside the registry, or project-local plugins — use `customPlugins`.\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: { passkey: true, organization: true },\n customPlugins: [\n // (1) Project-local plugin file at quickback/plugins/long-session.ts\n { from: \"./plugins/long-session\", export: \"longSessionPlugin\" },\n // (2) Third-party npm package\n {\n from: \"@better-auth-kit/audit\",\n export: \"auditPlugin\",\n args: { events: [\"sign-in\"] },\n dependencies: { \"@better-auth-kit/audit\": \"^1.0.0\" },\n },\n ],\n}),\n```\n\nEach entry in `customPlugins` is an explicit import descriptor. The compiler runs each through Zod, then emits an `import { <export> } from \"<from>\"` line in the generated `src/lib/auth.ts` and appends the call (or bare symbol) to the `plugins: [...]` array — after the named plugins, in declared order.\n\n#### `from`\n\n- **Relative path** (must start with `./` or `../`, must resolve under `./plugins/`): refers to a file you author in `quickback/plugins/`. The CLI auto-discovers `quickback/plugins/**/*.ts` and ships matching files; the compiler copies the source into the generated output at `src/plugins/<name>.ts` and rewrites the emitted import path. Files in `quickback/plugins/` that aren't referenced by any descriptor are uploaded but ignored — the compiler picks only what's needed.\n- **Bare specifier** (any value not starting with `./` or `../`): treated as an npm import, emitted verbatim. Combine with `dependencies` so the package lands in the generated `package.json`.\n\n#### `export`\n\nThe named export to import. Must be a valid JS identifier (e.g. `longSessionPlugin`, `auditPlugin`). Use the symbol's source name from the file or package — Quickback emits the import as-is.\n\n#### `args` (optional)\n\n- **Omitted** → emits the symbol uncalled (`plugins: [..., longSessionPlugin]`). Use this when your export is already a `BetterAuthPlugin` instance.\n- **Provided** → emits a factory call with JSON-serialized args (`plugins: [..., auditPlugin({\"events\":[\"sign-in\"]})]`). The value must be JSON-serializable; functions and other non-serializable values fail at compile time. (The user config crosses an HTTP boundary as JSON, so this constraint exists by construction.)\n\n#### `dependencies` (optional)\n\n`Record<string, string>` of npm packages and version specs. Merged into the generated `package.json` alongside the named-plugin deps. Only meaningful for bare-specifier `from` — relative-path entries don't need to declare anything.\n\n#### Project-local plugin shape\n\nA plugin file in `quickback/plugins/` is plain Better Auth — the compiler doesn't transform it. Author it like any other BA plugin and let TypeScript check it against the `BetterAuthPlugin` type:\n\n```ts\n// quickback/plugins/long-session.ts\n\nexport const longSessionPlugin = {\n id: \"long-session\",\n databaseHooks: {\n session: {\n create: {\n before: async (session) => ({\n data: {\n ...session,\n // 5-year session for an event-app use case\n expiresAt: new Date(Date.now() + 5 * 365 * 24 * 60 * 60 * 1000),\n },\n }),\n },\n },\n },\n} satisfies BetterAuthPlugin;\n```\n\n#### Out of scope\n\n- **No schema generation.** If your plugin needs database tables, declare them as a Quickback feature — the compiler does not run schema introspection on custom plugins.\n- **No conditional inclusion.** Every entry in `customPlugins` is always emitted. Gate environment-specific plugins inside the plugin file itself.\n- **No name collision check against the named registry.** Duplicate registration is a Better Auth runtime concern, not a compile-time one — don't reach for `customPlugins` to override a named plugin's options; use the object form on `plugins` instead.\n\n## Where This Runs\n\nAll Better Auth plugin routes are served under your auth base path:\n\n```\n/auth/v1/*\n```"
346
+ "content": "Quickback ships with a curated set of Better Auth plugins and helper wiring so your auth stack is production-ready by default. Enable these in `quickback.config.ts` under `providers.auth`.\n\n## Available Plugins\n\n### Email OTP (with AWS SES)\n\nQuickback wires the Better Auth Email OTP flow to AWS SES. When `emailOtp` is enabled, the compiler emits the SES plugin and combo-auth email flow (magic link + OTP).\n\n**Enable in config:**\n\n```ts\n\nexport default defineConfig({\n name: \"quickback-api\",\n providers: {\n runtime: defineRuntime(\"cloudflare\"),\n database: defineDatabase(\"cloudflare-d1\", {\n vars: {\n AWS_SES_REGION: \"us-east-2\",\n EMAIL_FROM: \"noreply@yourdomain.com\",\n EMAIL_FROM_NAME: \"Your App | Account Services\",\n APP_NAME: \"Your App\",\n APP_URL: \"https://account.yourdomain.com\",\n BETTER_AUTH_URL: \"https://api.yourdomain.com\",\n },\n }),\n auth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: [\"emailOtp\"],\n }),\n },\n});\n```\n\n**Endpoints:**\n- `POST /auth/v1/email-otp/send-verification-otp`\n- `POST /auth/v1/email-otp/verify-otp`\n\n**Email readiness check:**\n\nUse this to show UI warnings when SES isn't configured.\n\n- `GET /api/v1/system/email-status`\n- Response: `{ \"emailConfigured\": true|false }`\n\n**Disabling sign-up via OTP:**\n\nBy default the Email OTP plugin **auto-creates an account** when a code is\nverified for an unknown email — verifying an OTP doubles as registration. This\nis a separate code path from `emailAndPassword.disableSignUp` (which only gates\n`POST /auth/v1/sign-up/email`), so disabling password sign-up alone does *not*\nclose the OTP path.\n\nTo make OTP sign-in only (existing users can sign in; unknown emails are\nrejected instead of registered), use the object form:\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: {\n emailOtp: { disableSignUp: true },\n },\n}),\n```\n\n### Upgrade Anonymous\n\nAdds a first-class endpoint to convert an anonymous user into a full user. This flips `isAnonymous` to `false` and refreshes the session cache immediately.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: [\"anonymous\", \"upgradeAnonymous\"],\n}),\n```\n\n**Endpoint:**\n- `POST /auth/v1/upgrade-anonymous`\n\n**Note:** If you send `Content-Type: application/json`, include a body (an empty `{}` is fine). This avoids request parsing errors in some clients.\n\n### SMS OTP (with AWS SNS)\n\nWhen `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via [`@quickback-dev/better-auth-aws-sns`](/stack/auth/plugins/aws-sns). The plugin adds `phoneNumber` / `phoneNumberVerified` columns to the user table, handles OTP generation + storage + verify-attempt limits, and exposes endpoints for phone-only sign-in, phone+password sign-in, and password reset via SMS.\n\n**Enable in config:**\n\n```ts\nexport default defineConfig({\n name: \"my-app\",\n sms: {\n provider: \"aws-sns\",\n region: \"us-east-1\",\n },\n providers: {\n runtime: defineRuntime(\"cloudflare\"),\n database: defineDatabase(\"cloudflare-d1\"),\n auth: defineAuth(\"better-auth\", {\n plugins: { phoneNumber: true },\n }),\n },\n});\n```\n\n**Endpoints (managed by Better Auth):**\n- `POST /auth/v1/phone-number/send-otp`\n- `POST /auth/v1/phone-number/verify`\n- `POST /auth/v1/sign-in/phone-number`\n- `POST /auth/v1/phone-number/request-password-reset`\n- `POST /auth/v1/phone-number/reset-password`\n\n**Why use SMS:** corporate email gateways frequently break transactional auth emails (link rewriting, click-tracking, MITM scanners). SMS is the most reliable channel for a six-digit code that has to land in under a minute. See the [AWS SNS plugin page](/stack/auth/plugins/aws-sns) for IAM, 10DLC registration, and sender-ID details.\n\n### AWS SES Plugin\n\nThis is a Quickback-provided Better Auth plugin for Email OTP and other transactional emails. It handles SES signing and delivery over the Web Crypto API so it runs in Cloudflare Workers without the AWS SDK. It is wired up only when you opt in via `email.provider: 'aws-ses'` — the default transport is Cloudflare Email Sending (`send_email` binding).\n\nRequired vars (only when `email.provider: 'aws-ses'` is set; use Wrangler secrets for credentials):\n- `AWS_ACCESS_KEY_ID` (secret)\n- `AWS_SECRET_ACCESS_KEY` (secret)\n- `AWS_SES_REGION`\n- `EMAIL_FROM`\n\nOptional vars:\n- `EMAIL_FROM_NAME`\n- `EMAIL_REPLY_TO` - Reply-to address for emails (defaults to `EMAIL_FROM`)\n- `APP_NAME`\n- `APP_URL`\n- `BETTER_AUTH_URL`\n\n### Magic Links\n\nMagic links provide passwordless authentication by sending a unique login link to the user's email. When clicked, the link authenticates the user without requiring a password.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"magicLink\"],\n}),\n```\n\n**Endpoints:**\n- `POST /auth/v1/magic-link/send` - Send magic link email\n- `GET /auth/v1/magic-link/verify` - Verify magic link token\n\n**Disabling sign-up via magic link:**\n\nLike Email OTP, the magic-link plugin **auto-creates an account** when a link is\nverified for an unknown email, on a code path independent of\n`emailAndPassword.disableSignUp`. Gate it with the object form:\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: {\n magicLink: { disableSignUp: true }, // sign-in only; unknown emails rejected\n },\n}),\n```\n\nIt inherits the global signup gate the same way `emailOtp.disableSignUp` does:\n`account.auth.signup: false` gates the magic-link path automatically; set\n`magicLink: { disableSignUp: false }` to opt it back open.\n\n**Email customization:**\n\nMagic link emails use the same AWS SES configuration as Email OTP. Customize the email template via environment variables:\n\n- `APP_NAME` - Application name in email subject\n- `APP_URL` - Base URL for magic link redirect\n- `EMAIL_FROM` - Sender email address\n- `EMAIL_FROM_NAME` - Sender display name\n\n**Frontend integration:**\n\n```ts\n// Request magic link\nawait fetch('/auth/v1/magic-link/send', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ email: 'user@yourdomain.com' })\n});\n\n// User clicks link in email, which redirects to your app\n// The token is verified automatically via the callback URL\n```\n\n### Passkeys\n\nPasskeys provide passwordless authentication using WebAuthn/FIDO2. Users authenticate with biometrics (fingerprint, face) or device PIN instead of passwords.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"passkey\"],\n}),\n```\n\n**Required environment variable:**\n- `ACCOUNT_URL` - Your account/frontend URL (used as the relying party origin for WebAuthn)\n\n**Endpoints:**\n- `POST /auth/v1/passkey/register/options` - Get registration challenge\n- `POST /auth/v1/passkey/register/verify` - Complete registration\n- `POST /auth/v1/passkey/authenticate/options` - Get authentication challenge\n- `POST /auth/v1/passkey/authenticate/verify` - Complete authentication\n- `GET /auth/v1/passkey/list-user-passkeys` - List user's registered passkeys\n- `POST /auth/v1/passkey/delete-passkey` - Delete a registered passkey\n\n**Browser support:**\n\nPasskeys are supported in all modern browsers:\n- Chrome 67+\n- Safari 14+\n- Firefox 60+\n- Edge 79+\n\n**Registration flow:**\n\n```ts\n// 1. Get registration options\nconst optionsRes = await fetch('/auth/v1/passkey/register/options', {\n method: 'POST',\n credentials: 'include'\n});\nconst options = await optionsRes.json();\n\n// 2. Create credential using WebAuthn API\nconst credential = await navigator.credentials.create({\n publicKey: options\n});\n\n// 3. Send credential to server\nawait fetch('/auth/v1/passkey/register/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n credentials: 'include',\n body: JSON.stringify(credential)\n});\n```\n\n**Authentication flow:**\n\n```ts\n// 1. Get authentication options\nconst optionsRes = await fetch('/auth/v1/passkey/authenticate/options', {\n method: 'POST'\n});\nconst options = await optionsRes.json();\n\n// 2. Get credential using WebAuthn API\nconst credential = await navigator.credentials.get({\n publicKey: options\n});\n\n// 3. Verify credential\nawait fetch('/auth/v1/passkey/authenticate/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n credentials: 'include',\n body: JSON.stringify(credential)\n});\n```\n\n### JWT Plugin\n\nBetter Auth's JWT plugin adds asymmetric-signed tokens and a JWKS endpoint for external services that need to verify user identity without sharing a shared secret.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"jwt\"],\n}),\n```\n\n**Endpoints:**\n- `GET /auth/v1/jwks` — public keys for verifying BA-issued tokens\n- `POST /auth/v1/token` — mint an asymmetric-signed JWT from the current session\n\n**When to enable:** you have external services (non-Quickback workers, third-party integrations) that need to verify a user's identity via JWKS without holding `BETTER_AUTH_SECRET`. The BA-issued tokens won't carry Quickback's `orgId`/`role` claims, so they're for identity, not API access.\n\n### API Keys\n\nStatic, long-lived credentials for cron jobs, scripts, and machine-to-machine integrations. Better Auth's `apiKey` plugin is auto-included when you enable the organizations feature, so no explicit config is required for the standard B2B SaaS shape.\n\n**Authenticating requests:**\n\nPass the key as the `x-api-key` header (preferred) or as an `?api_key=` / `?key=` query parameter:\n\n```bash\n# Header form (preferred — keys don't leak into access logs or Referer)\ncurl -H \"x-api-key: ${KEY}\" https://api.example.com/v1/jobs\n\n# Query-param form (for clients that can't inject custom headers,\n# e.g., claude.ai's MCP connector)\ncurl \"https://api.example.com/v1/jobs?api_key=${KEY}\"\n```\n\nThe header takes precedence when both are present. The query-param form lands in nginx / Cloudflare access logs and `Referer` headers when the page navigates away — prefer headers whenever the client supports them.\n\n**Endpoints (managed by Better Auth):**\n- `POST /auth/v1/api-key/create` — issue a new key (returns the secret once; store it)\n- `GET /auth/v1/api-key/list` — list keys for the current user\n- `POST /auth/v1/api-key/delete` — revoke a key\n\nKeys can carry organization context via `metadata.organizationId` — when set, the auth middleware looks up the user's role in that org and populates `ctx.roles` accordingly, so a single key inherits the same firewall + access scope as the user who created it.\n\n### OAuth Provider (MCP-ready)\n\nTurns your Quickback worker into a standards-compliant OAuth 2.1 + OIDC authorization server. The plugin ships RFC 7591 dynamic client registration plus the well-known discovery documents an MCP client needs to bootstrap itself, so every future MCP client (Cursor, Claude Desktop, Cowork, custom integrations) Just Works without bespoke per-client header injection.\n\n**Enable in config:**\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: [\"oauthProvider\"],\n}),\n```\n\nThe compiler auto-includes Better Auth's `jwt` plugin alongside `oauthProvider` — `@better-auth/oauth-provider` delegates access-token signing to it, and schema generation fails without it.\n\n**Custom configuration** (object form):\n\n```ts\nauth: defineAuth(\"better-auth\", {\n plugins: {\n oauthProvider: {\n consentPage: \"/consent\", // path on ACCOUNT_URL — default\n loginPage: \"/login\", // path on ACCOUNT_URL — default\n allowDynamicClientRegistration: true, // default\n allowUnauthenticatedClientRegistration: true, // default — MCP needs this\n validAudiences: [\"https://api.example.com\"], // optional — defaults to BETTER_AUTH_URL\n scopes: [\"openid\", \"profile\", \"email\", \"offline_access\"],\n },\n },\n}),\n```\n\n**Endpoints:**\n\nDiscovery (public, no auth):\n- `GET /.well-known/oauth-authorization-server` — RFC 8414 metadata\n- `GET /.well-known/oauth-protected-resource` — MCP resource metadata\n- `GET /.well-known/openid-configuration` — OIDC discovery\n\nAuthorization flow:\n- `POST /oauth2/register` — RFC 7591 dynamic client registration\n- `POST /oauth2/authorize` — start auth code flow\n- `POST /oauth2/token` — exchange code or refresh for access token\n- `POST /oauth2/consent` — accept/deny (called by the consent page)\n- `POST /oauth2/introspect` — RFC 7662 token validity check\n- `POST /oauth2/revoke` — RFC 7009 token revocation\n- `GET /oauth2/userinfo` — OIDC user info (requires `openid` scope)\n\nClient management (authenticated):\n- `GET /oauth2/get-clients`, `GET /oauth2/get-client?client_id=`, `GET /oauth2/public-client?client_id=`\n- `POST /oauth2/create-client`, `POST /oauth2/update-client`, `POST /oauth2/delete-client`\n- `POST /oauth2/client/rotate-secret`\n\nConsent management:\n- `GET /oauth2/get-consents`, `GET /oauth2/get-consent?id=`\n- `POST /oauth2/update-consent`, `POST /oauth2/delete-consent`\n\n**Account SPA wiring:**\n\nThe compiled Account SPA already serves `/consent`. When `oauthProvider` is enabled, Better Auth redirects unauthenticated users to `${ACCOUNT_URL}/login?redirect=...` and authenticated users straight to `${ACCOUNT_URL}/consent?client_id=...&scope=...&oauth_query=...`. The bundled consent screen reads those params, fetches client metadata via `/oauth2/public-client`, and POSTs back to `/oauth2/consent`.\n\n**Verifying tokens in your own Workers / route handlers:**\n\nIssued tokens are JWTs by default — verify them locally without a DB hit:\n\n```ts\n\nconst serverClient = createAuthClient({\n plugins: [oauthProviderResourceClient(auth)],\n});\n\nconst token = req.headers.get(\"authorization\")?.replace(\"Bearer \", \"\");\nconst payload = await serverClient.verifyAccessToken(token, {\n verifyOptions: { issuer: env.BETTER_AUTH_URL, audience: env.BETTER_AUTH_URL },\n});\n// payload.sub → userId, payload.scope → granted scopes\n```\n\n**Why this and not the deprecated `mcp` plugin?**\n\nBetter Auth's older `better-auth/plugins/mcp` is being deprecated in favour of `@better-auth/oauth-provider`. The new package is a full OAuth 2.1 server (the MCP plugin only exposed a subset), supports dynamic registration that MCP clients now require, and lets you scope/revoke per-client.\n\nKeep `apiKey` enabled alongside it — server-to-server flows (cron, scripts) want a static key; OAuth is for interactive clients.\n\n### Custom plugins (escape hatch)\n\nThe named plugins above cover the curated set Quickback ships first-class wiring for. For anything else — third-party packages (`@better-auth-kit/audit`, …), Better Auth built-ins outside the registry, or project-local plugins — use `customPlugins`.\n\n```ts\nauth: defineAuth(\"better-auth\", {\n emailAndPassword: { enabled: true },\n plugins: { passkey: true, organization: true },\n customPlugins: [\n // (1) Project-local plugin file at quickback/plugins/long-session.ts\n { from: \"./plugins/long-session\", export: \"longSessionPlugin\" },\n // (2) Third-party npm package\n {\n from: \"@better-auth-kit/audit\",\n export: \"auditPlugin\",\n args: { events: [\"sign-in\"] },\n dependencies: { \"@better-auth-kit/audit\": \"^1.0.0\" },\n },\n ],\n}),\n```\n\nEach entry in `customPlugins` is an explicit import descriptor. The compiler runs each through Zod, then emits an `import { <export> } from \"<from>\"` line in the generated `src/lib/auth.ts` and appends the call (or bare symbol) to the `plugins: [...]` array — after the named plugins, in declared order.\n\n#### `from`\n\n- **Relative path** (must start with `./` or `../`, must resolve under `./plugins/`): refers to a file you author in `quickback/plugins/`. The CLI auto-discovers `quickback/plugins/**/*.ts` and ships matching files; the compiler copies the source into the generated output at `src/plugins/<name>.ts` and rewrites the emitted import path. Files in `quickback/plugins/` that aren't referenced by any descriptor are uploaded but ignored — the compiler picks only what's needed.\n- **Bare specifier** (any value not starting with `./` or `../`): treated as an npm import, emitted verbatim. Combine with `dependencies` so the package lands in the generated `package.json`.\n\n#### `export`\n\nThe named export to import. Must be a valid JS identifier (e.g. `longSessionPlugin`, `auditPlugin`). Use the symbol's source name from the file or package — Quickback emits the import as-is.\n\n#### `args` (optional)\n\n- **Omitted** → emits the symbol uncalled (`plugins: [..., longSessionPlugin]`). Use this when your export is already a `BetterAuthPlugin` instance.\n- **Provided** → emits a factory call with JSON-serialized args (`plugins: [..., auditPlugin({\"events\":[\"sign-in\"]})]`). The value must be JSON-serializable; functions and other non-serializable values fail at compile time. (The user config crosses an HTTP boundary as JSON, so this constraint exists by construction.)\n\n#### `dependencies` (optional)\n\n`Record<string, string>` of npm packages and version specs. Merged into the generated `package.json` alongside the named-plugin deps. Only meaningful for bare-specifier `from` — relative-path entries don't need to declare anything.\n\n#### Project-local plugin shape\n\nA plugin file in `quickback/plugins/` is plain Better Auth — the compiler doesn't transform it. Author it like any other BA plugin and let TypeScript check it against the `BetterAuthPlugin` type:\n\n```ts\n// quickback/plugins/long-session.ts\n\nexport const longSessionPlugin = {\n id: \"long-session\",\n databaseHooks: {\n session: {\n create: {\n before: async (session) => ({\n data: {\n ...session,\n // 5-year session for an event-app use case\n expiresAt: new Date(Date.now() + 5 * 365 * 24 * 60 * 60 * 1000),\n },\n }),\n },\n },\n },\n} satisfies BetterAuthPlugin;\n```\n\n#### Out of scope\n\n- **No schema generation.** If your plugin needs database tables, declare them as a Quickback feature — the compiler does not run schema introspection on custom plugins.\n- **No conditional inclusion.** Every entry in `customPlugins` is always emitted. Gate environment-specific plugins inside the plugin file itself.\n- **No name collision check against the named registry.** Duplicate registration is a Better Auth runtime concern, not a compile-time one — don't reach for `customPlugins` to override a named plugin's options; use the object form on `plugins` instead.\n\n## Where This Runs\n\nAll Better Auth plugin routes are served under your auth base path:\n\n```\n/auth/v1/*\n```"
347
347
  },
348
348
  "stack/auth/plugins/upgrade-anonymous": {
349
349
  "title": "Upgrade Anonymous Plugin",
@@ -451,7 +451,7 @@ export const DOCS = {
451
451
  },
452
452
  "stack/storage/r2": {
453
453
  "title": "File Storage (R2)",
454
- "content": "Quickback provides built-in file storage using Cloudflare R2, with role-based access control and a dedicated files worker for serving.\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ Your Application │\n│ │\n│ Upload/Manage Files Serve Files │\n│ ───────────────────── ────────────── │\n│ api.yourdomain.com files.yourdomain.com │\n│ /storage/v1/* /* │\n│ │\n│ ┌─────────────────────┐ ┌─────────────────────┐ │\n│ │ API Worker │ │ Files Worker │ │\n│ │ │ │ │ │\n│ │ POST /bucket │ │ GET /public/* │ │\n│ │ GET /bucket │ │ → No auth │ │\n│ │ POST /object/* │ │ │ │\n│ │ DELETE /object/* │ │ GET /* │ │\n│ │ │ │ → Session + RBAC │ │\n│ └──────────┬──────────┘ └──────────┬──────────┘ │\n│ │ │ │\n│ └───────────┬───────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────┐ │\n│ │ R2 Bucket │ │\n│ │ quickback-files │ │\n│ └─────────────────────┘ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n## Enabling File Storage\n\nAdd the `fileStorage` provider to your `quickback.config.ts`:\n\n```typescript\nexport default {\n name: 'my-app',\n providers: {\n runtime: { name: 'cloudflare' },\n database: { name: 'cloudflare-d1' },\n auth: { name: 'better-auth' },\n fileStorage: {\n name: 'cloudflare-r2',\n config: {\n binding: 'R2_BUCKET',\n bucketName: 'my-app-files',\n filesBinding: 'FILES_DB',\n maxFileSize: 10 * 1024 * 1024, // 10MB\n allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],\n },\n },\n },\n};\n```\n\n## API Endpoints\n\n### Storage API (api.yourdomain.com/storage/v1)\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/bucket` | Create a bucket |\n| GET | `/bucket` | List buckets |\n| GET | `/bucket/:name` | Get bucket info |\n| DELETE | `/bucket/:name` | Delete bucket (must be empty) |\n| POST | `/object/:bucket/*path` | Upload file (bytes through the Worker) |\n| POST | `/presign/:bucket/*path` | **Presigned upload URL (bytes direct to R2)** |\n| POST | `/confirm/:bucket/*path` | Confirm a presigned upload (reconcile size + etag) |\n| GET | `/object/:bucket/*path` | Download file |\n| HEAD | `/object/:bucket/*path` | Get file metadata |\n| DELETE | `/object/:bucket/*path` | Delete file (soft delete) |\n| GET | `/object` | List objects |\n| POST | `/url` | Get file URL for serving |\n\n### Files Worker (files.yourdomain.com)\n\n| Method | Path | Auth Required |\n|--------|------|---------------|\n| GET/HEAD | `/public/*` | No |\n| GET/HEAD | `/*` | Yes (session + RBAC) |\n\n## Buckets\n\nBuckets organize files and define access control policies.\n\n### Creating a Bucket\n\n```bash\nPOST /storage/v1/bucket\n{\n \"name\": \"avatars\",\n \"readScope\": \"organization\",\n \"writeScope\": \"organization\",\n \"readRoles\": [\"admin\", \"member\"],\n \"writeRoles\": [\"admin\"],\n \"deleteRoles\": [\"admin\"]\n}\n```\n\n### Scope Options\n\n| Scope | Read Behavior | Write Behavior |\n|-------|---------------|----------------|\n| `public` | Anyone can read | N/A |\n| `organization` | Org members only | Org members only |\n| `user` | Owner only | Owner only |\n\n### Role-Based Access\n\nYou can restrict operations to specific roles:\n\n```json\n{\n \"readRoles\": [\"admin\", \"member\"],\n \"writeRoles\": [\"admin\", \"editor\"],\n \"deleteRoles\": [\"admin\"]\n}\n```\n\nAn empty array `[]` means no role restriction (all authenticated users).\n\n## Uploading Files\n\n```bash\nPOST /storage/v1/object/avatars/profile.jpg\nContent-Type: image/jpeg\nContent-Length: 12345\n\n<binary data>\n```\n\nResponse:\n```json\n{\n \"id\": \"obj_123\",\n \"key\": \"org_abc/avatars/profile.jpg\",\n \"bucket\": \"avatars\",\n \"name\": \"profile.jpg\",\n \"size\": 12345,\n \"mimeType\": \"image/jpeg\",\n \"readScope\": \"organization\"\n}\n```\n\n## Presigned uploads (recommended)\n\nStreaming bytes through the Worker (`POST /object`) is fine for small files, but\nit puts every byte on the Worker's request path — subject to the body-size cap,\nand billed as Worker CPU/duration. For media (video, audio, large PDFs), use a\n**presigned URL**: the Worker runs all the access checks and hands back a\nshort-lived URL the client uploads to **directly**. The bytes never touch your\nWorker.\n\n```bash\n# 1. Ask the API to sign an upload URL (auth + bucket + role checks run here)\ncurl -X POST https://api.example.com/storage/v1/presign/videos/clip.mp4 \\\n -H \"Authorization: Bearer <token>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"contentType\": \"video/mp4\", \"size\": 73400320 }'\n\n# Response:\n# {\n# \"id\": \"obj_abc\",\n# \"key\": \"org_abc/videos/clip.mp4\",\n# \"uploadUrl\": \"https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...\",\n# \"method\": \"PUT\",\n# \"headers\": { \"Content-Type\": \"video/mp4\" },\n# \"expiresAt\": \"2026-06-02T12:10:00.000Z\"\n# }\n\n# 2. Upload the bytes straight to R2 (replay the returned headers verbatim)\ncurl -X PUT \"<uploadUrl>\" -H \"Content-Type: video/mp4\" --data-binary @clip.mp4\n\n# 3. Confirm — reconciles the recorded size + etag against what actually landed\ncurl -X POST https://api.example.com/storage/v1/confirm/videos/clip.mp4 \\\n -H \"Authorization: Bearer <token>\"\n```\n\n### Required secrets\n\nPresigning uses R2's S3-compatible API, which needs an **R2 API token** — the\nWorkers bucket binding alone cannot presign. Create a token in the Cloudflare\ndashboard (R2 → Manage API Tokens) and set:\n\n```bash\nwrangler secret put R2_ACCOUNT_ID # your Cloudflare account id\nwrangler secret put R2_ACCESS_KEY_ID # R2 API token access key id\nwrangler secret put R2_SECRET_ACCESS_KEY # R2 API token secret\n# Optional: wrangler secret put R2_S3_ENDPOINT # override the derived endpoint\n```\n\n### Signing from your own action\n\nThe same signer is exposed as `ctx.storage` inside any\n[`defineAction`](/compiler/definitions/actions) — so you can author an upload endpoint that\nruns your own access rules (org, team, relationship/scoped roles) and stores the\nkey in **your own table**, instead of the generic `buckets`/`objects` metadata:\n\n```typescript\nexport default defineAction({\n path: '/event/:eventId/media/sign-upload',\n method: 'POST',\n input: z.object({ filename: z.string(), contentType: z.string() }),\n access: { roles: ['admin', 'member', 'scope:event:attendee'] },\n async execute({ input, ctx, db, storage }) {\n // Tenant-scoped key — secure by construction\n const key = `org/${ctx.activeOrgId}/event/${input.eventId}/${crypto.randomUUID()}-${input.filename}`;\n const upload = await storage.signPutUrl(key, {\n contentType: input.contentType,\n expiresIn: 600,\n });\n await db.insert(images).values({ key, eventId: input.eventId /* … */ });\n return { uploadUrl: upload.url, key, headers: upload.headers };\n },\n});\n```\n\n`storage` exposes:\n\n| Method | Returns | Use |\n|--------|---------|-----|\n| `signPutUrl(key, { contentType?, expiresIn? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 |\n| `signGetUrl(key, { expiresIn?, downloadFilename? })` | `string` | Client downloads directly from R2 |\n\nThis is the supported replacement for streaming a raw binary body through an\naction — the JSON body parser and its ~1 MiB cap stay on for every other route.\n\n## Serving Files\n\n### Public Files\n\nFiles in buckets with `readScope: \"public\"` are stored with a `public/` prefix:\n\n```\nhttps://files.yourdomain.com/public/org_abc/avatars/logo.png\n```\n\nNo authentication required.\n\n### Private Files\n\nPrivate files require a valid Better Auth session cookie:\n\n```\nhttps://files.yourdomain.com/org_abc/documents/report.pdf\n```\n\nThe files worker:\n1. Validates the session token\n2. Checks the user's organization matches\n3. Verifies role permissions (if `readRoles` configured)\n4. Serves the file or returns 403\n\n## Generated Files\n\nWhen file storage is configured, the compiler generates:\n\n| File | Purpose |\n|------|---------|\n| `src/storage/routes.ts` | Storage API routes (upload, presign, confirm, download) |\n| `src/storage/presign.ts` | R2 presigned-URL signer (`createPresigner`, backs `ctx.storage`) |\n| `src/files/schema.ts` | Files database schema (buckets, objects) |\n| `cloudflare-workers/files/index.ts` | Files worker for serving |\n| `cloudflare-workers/files/wrangler.toml` | Files worker config |\n\nThe compiler also adds [`aws4fetch`](https://github.com/mhart/aws4fetch) to your\n`package.json` (used by the presigner) and the R2 presign secrets to your\ngenerated `CloudflareBindings` type.\n\n## Deployment\n\nAfter compiling:\n\n1. **Create the R2 bucket:**\n ```bash\n wrangler r2 bucket create my-app-files\n ```\n\n2. **Create the files database:**\n ```bash\n wrangler d1 create my-app-files\n ```\n\n3. **Run migrations:**\n ```bash\n wrangler d1 migrations apply my-app-files --local\n wrangler d1 migrations apply my-app-files --remote\n ```\n\n4. **Deploy the API:**\n ```bash\n wrangler deploy\n ```\n\n5. **Deploy the files worker:**\n ```bash\n cd cloudflare-workers/files\n wrangler deploy\n ```\n\n6. **Set the R2 presign secrets** (only if you use presigned uploads — see\n [Presigned uploads](#presigned-uploads-recommended)):\n ```bash\n wrangler secret put R2_ACCOUNT_ID\n wrangler secret put R2_ACCESS_KEY_ID\n wrangler secret put R2_SECRET_ACCESS_KEY\n ```\n\n## Configuration Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `binding` | `string` | `R2_BUCKET` | R2 bucket binding name |\n| `bucketName` | `string` | Required | R2 bucket name |\n| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding |\n| `maxFileSize` | `number` | 10MB | Max upload size in bytes |\n| `allowedTypes` | `string[]` | Images only | Allowed MIME types |\n| `publicDomain` | `string` | - | Custom domain for files worker |\n\n## Security Model\n\n- **Upload security**: Enforced by API worker (auth middleware, org check, role check)\n- **Serve security**: Enforced by files worker (session validation, metadata RBAC)\n- **Soft deletes**: Files are marked deleted in metadata but retained in R2\n- **Tenant isolation**: All files are prefixed with organization ID"
454
+ "content": "Quickback provides built-in file storage using Cloudflare R2.\n\n## Two modes\n\n`defineFileStorage(\"cloudflare-r2\")` has two modes:\n\n- **Presign-only (default)** — emits just the `ctx.storage` signer (presigned\n PUT/GET URLs straight to R2). **No new D1, no `/storage/v1/*` endpoints, no\n files worker.** You compute keys and store file references in your own table.\n This is the recommended path for most apps and the lightest way to add\n uploads — see [Presigned uploads](#presigned-uploads-recommended).\n- **Managed (`managed: true`)** — adds the turnkey subsystem on top: a FILES_DB\n metadata database (buckets + objects), the `/storage/v1/*` upload/download/\n manage endpoints, and a public files worker for serving. Opt in only when you\n want buckets/objects handled for you instead of bringing your own media table.\n\n```ts\n// Presign-only (default) — ctx.storage against a bucket, nothing else\ndefineFileStorage(\"cloudflare-r2\", { bucketName: \"my-app-media\" })\n\n// Managed subsystem — adds FILES_DB + /storage/v1/* + files worker\ndefineFileStorage(\"cloudflare-r2\", { managed: true, bucketName: \"my-app-files\" })\n```\n\nNew projects can omit `bucketName` — it defaults to `<project>-media`, so the\nonly setup is `wrangler r2 bucket create <name>` once plus the R2 API-token\nsecrets. Existing projects set `bucketName` to a bucket they already have.\n\nThe sections below document the **managed** subsystem; for the default\npresign-only path jump to [Presigned uploads](#presigned-uploads-recommended).\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ Your Application │\n│ │\n│ Upload/Manage Files Serve Files │\n│ ───────────────────── ────────────── │\n│ api.yourdomain.com files.yourdomain.com │\n│ /storage/v1/* /* │\n│ │\n│ ┌─────────────────────┐ ┌─────────────────────┐ │\n│ │ API Worker │ │ Files Worker │ │\n│ │ │ │ │ │\n│ │ POST /bucket │ │ GET /public/* │ │\n│ │ GET /bucket │ │ → No auth │ │\n│ │ POST /object/* │ │ │ │\n│ │ DELETE /object/* │ │ GET /* │ │\n│ │ │ │ → Session + RBAC │ │\n│ └──────────┬──────────┘ └──────────┬──────────┘ │\n│ │ │ │\n│ └───────────┬───────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────┐ │\n│ │ R2 Bucket │ │\n│ │ quickback-files │ │\n│ └─────────────────────┘ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n## Enabling File Storage\n\nAdd the `fileStorage` provider to your `quickback.config.ts`:\n\n```typescript\nexport default {\n name: 'my-app',\n providers: {\n runtime: { name: 'cloudflare' },\n database: { name: 'cloudflare-d1' },\n auth: { name: 'better-auth' },\n fileStorage: {\n name: 'cloudflare-r2',\n config: {\n binding: 'R2_BUCKET',\n bucketName: 'my-app-files',\n filesBinding: 'FILES_DB',\n maxFileSize: 10 * 1024 * 1024, // 10MB\n allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],\n },\n },\n },\n};\n```\n\n## API Endpoints\n\n### Storage API (api.yourdomain.com/storage/v1)\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/bucket` | Create a bucket |\n| GET | `/bucket` | List buckets |\n| GET | `/bucket/:name` | Get bucket info |\n| DELETE | `/bucket/:name` | Delete bucket (must be empty) |\n| POST | `/object/:bucket/*path` | Upload file (bytes through the Worker) |\n| POST | `/presign/:bucket/*path` | **Presigned upload URL (bytes direct to R2)** |\n| POST | `/confirm/:bucket/*path` | Confirm a presigned upload (reconcile size + etag) |\n| GET | `/object/:bucket/*path` | Download file |\n| HEAD | `/object/:bucket/*path` | Get file metadata |\n| DELETE | `/object/:bucket/*path` | Delete file (soft delete) |\n| GET | `/object` | List objects |\n| POST | `/url` | Get file URL for serving |\n\n### Files Worker (files.yourdomain.com)\n\n| Method | Path | Auth Required |\n|--------|------|---------------|\n| GET/HEAD | `/public/*` | No |\n| GET/HEAD | `/*` | Yes (session + RBAC) |\n\n## Buckets\n\nBuckets organize files and define access control policies.\n\n### Creating a Bucket\n\n```bash\nPOST /storage/v1/bucket\n{\n \"name\": \"avatars\",\n \"readScope\": \"organization\",\n \"writeScope\": \"organization\",\n \"readRoles\": [\"admin\", \"member\"],\n \"writeRoles\": [\"admin\"],\n \"deleteRoles\": [\"admin\"]\n}\n```\n\n### Scope Options\n\n| Scope | Read Behavior | Write Behavior |\n|-------|---------------|----------------|\n| `public` | Anyone can read | N/A |\n| `organization` | Org members only | Org members only |\n| `user` | Owner only | Owner only |\n\n### Role-Based Access\n\nYou can restrict operations to specific roles:\n\n```json\n{\n \"readRoles\": [\"admin\", \"member\"],\n \"writeRoles\": [\"admin\", \"editor\"],\n \"deleteRoles\": [\"admin\"]\n}\n```\n\nAn empty array `[]` means no role restriction (all authenticated users).\n\n## Uploading Files\n\n```bash\nPOST /storage/v1/object/avatars/profile.jpg\nContent-Type: image/jpeg\nContent-Length: 12345\n\n<binary data>\n```\n\nResponse:\n```json\n{\n \"id\": \"obj_123\",\n \"key\": \"org_abc/avatars/profile.jpg\",\n \"bucket\": \"avatars\",\n \"name\": \"profile.jpg\",\n \"size\": 12345,\n \"mimeType\": \"image/jpeg\",\n \"readScope\": \"organization\"\n}\n```\n\n## Presigned uploads (recommended)\n\nStreaming bytes through the Worker (`POST /object`) is fine for small files, but\nit puts every byte on the Worker's request path — subject to the body-size cap,\nand billed as Worker CPU/duration. For media (video, audio, large PDFs), use a\n**presigned URL**: the Worker runs all the access checks and hands back a\nshort-lived URL the client uploads to **directly**. The bytes never touch your\nWorker.\n\n```bash\n# 1. Ask the API to sign an upload URL (auth + bucket + role checks run here)\ncurl -X POST https://api.example.com/storage/v1/presign/videos/clip.mp4 \\\n -H \"Authorization: Bearer <token>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"contentType\": \"video/mp4\", \"size\": 73400320 }'\n\n# Response:\n# {\n# \"id\": \"obj_abc\",\n# \"key\": \"org_abc/videos/clip.mp4\",\n# \"uploadUrl\": \"https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...\",\n# \"method\": \"PUT\",\n# \"headers\": { \"Content-Type\": \"video/mp4\" },\n# \"expiresAt\": \"2026-06-02T12:10:00.000Z\"\n# }\n\n# 2. Upload the bytes straight to R2 (replay the returned headers verbatim)\ncurl -X PUT \"<uploadUrl>\" -H \"Content-Type: video/mp4\" --data-binary @clip.mp4\n\n# 3. Confirm — reconciles the recorded size + etag against what actually landed\ncurl -X POST https://api.example.com/storage/v1/confirm/videos/clip.mp4 \\\n -H \"Authorization: Bearer <token>\"\n```\n\n### Required secrets\n\nPresigning uses R2's S3-compatible API, which needs an **R2 API token** — the\nWorkers bucket binding alone cannot presign. Create a token in the Cloudflare\ndashboard (R2 → Manage API Tokens) and set:\n\n```bash\nwrangler secret put R2_ACCOUNT_ID # your Cloudflare account id\nwrangler secret put R2_ACCESS_KEY_ID # R2 API token access key id\nwrangler secret put R2_SECRET_ACCESS_KEY # R2 API token secret\n# Optional: wrangler secret put R2_S3_ENDPOINT # override the derived endpoint\n```\n\n### Signing from your own action\n\nThe same signer is exposed as `ctx.storage` inside any\n[`defineAction`](/compiler/definitions/actions) — so you can author an upload endpoint that\nruns your own access rules (org, team, relationship/scoped roles) and stores the\nkey in **your own table**, instead of the generic `buckets`/`objects` metadata:\n\n```typescript\nexport default defineAction({\n path: '/event/:eventId/media/sign-upload',\n method: 'POST',\n input: z.object({ filename: z.string(), contentType: z.string() }),\n access: { roles: ['admin', 'member', 'scope:event:attendee'] },\n async execute({ input, ctx, db, storage }) {\n // Tenant-scoped key — secure by construction\n const key = `org/${ctx.activeOrgId}/event/${input.eventId}/${crypto.randomUUID()}-${input.filename}`;\n const upload = await storage.signPutUrl(key, {\n contentType: input.contentType,\n expiresIn: 600,\n });\n await db.insert(images).values({ key, eventId: input.eventId /* … */ });\n return { uploadUrl: upload.url, key, headers: upload.headers };\n },\n});\n```\n\n`storage` exposes:\n\n| Method | Returns | Use |\n|--------|---------|-----|\n| `signPutUrl(key, { contentType?, expiresIn? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 |\n| `signGetUrl(key, { expiresIn?, downloadFilename? })` | `string` | Client downloads directly from R2 |\n\nThis is the supported replacement for streaming a raw binary body through an\naction — the JSON body parser and its ~1 MiB cap stay on for every other route.\n\n## Serving Files\n\n### Public Files\n\nFiles in buckets with `readScope: \"public\"` are stored with a `public/` prefix:\n\n```\nhttps://files.yourdomain.com/public/org_abc/avatars/logo.png\n```\n\nNo authentication required.\n\n### Private Files\n\nPrivate files require a valid Better Auth session cookie:\n\n```\nhttps://files.yourdomain.com/org_abc/documents/report.pdf\n```\n\nThe files worker:\n1. Validates the session token\n2. Checks the user's organization matches\n3. Verifies role permissions (if `readRoles` configured)\n4. Serves the file or returns 403\n\n## Generated Files\n\nWhen file storage is configured, the compiler generates:\n\n| File | Purpose |\n|------|---------|\n| `src/storage/routes.ts` | Storage API routes (upload, presign, confirm, download) |\n| `src/storage/presign.ts` | R2 presigned-URL signer (`createPresigner`, backs `ctx.storage`) |\n| `src/files/schema.ts` | Files database schema (buckets, objects) |\n| `cloudflare-workers/files/index.ts` | Files worker for serving |\n| `cloudflare-workers/files/wrangler.toml` | Files worker config |\n\nThe compiler also adds [`aws4fetch`](https://github.com/mhart/aws4fetch) to your\n`package.json` (used by the presigner) and the R2 presign secrets to your\ngenerated `CloudflareBindings` type.\n\n## Deployment\n\nAfter compiling:\n\n1. **Create the R2 bucket:**\n ```bash\n wrangler r2 bucket create my-app-files\n ```\n\n2. **Create the files database:**\n ```bash\n wrangler d1 create my-app-files\n ```\n\n3. **Run migrations:**\n ```bash\n wrangler d1 migrations apply my-app-files --local\n wrangler d1 migrations apply my-app-files --remote\n ```\n\n4. **Deploy the API:**\n ```bash\n wrangler deploy\n ```\n\n5. **Deploy the files worker:**\n ```bash\n cd cloudflare-workers/files\n wrangler deploy\n ```\n\n6. **Set the R2 presign secrets** (only if you use presigned uploads — see\n [Presigned uploads](#presigned-uploads-recommended)):\n ```bash\n wrangler secret put R2_ACCOUNT_ID\n wrangler secret put R2_ACCESS_KEY_ID\n wrangler secret put R2_SECRET_ACCESS_KEY\n ```\n\n## Configuration Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `managed` | `boolean` | `false` | Opt into the FILES_DB subsystem + `/storage/v1/*` + files worker. Off = presign-only. |\n| `bucketName` | `string` | `<project>-media` | R2 bucket the signer targets (override per-call with `signPutUrl(key, { bucket })`) |\n| `presign` | `object` | - | Env-var name overrides: `{ accountIdEnv, accessKeyIdEnv, secretAccessKeyEnv, endpointEnv }` |\n| `binding` | `string` | `R2_BUCKET` | R2 bucket binding name (managed mode) |\n| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding (managed mode) |\n| `maxFileSize` | `number \\| string` | 10MB | Max upload size — bytes or `\"100mb\"` (managed mode) |\n| `allowedTypes` | `string[]` | Images only | Allowed MIME types (managed mode) |\n| `publicDomain` | `string` | - | Custom domain for files worker (managed mode) |\n\n## Security Model\n\n- **Upload security**: Enforced by API worker (auth middleware, org check, role check)\n- **Serve security**: Enforced by files worker (session validation, metadata RBAC)\n- **Soft deletes**: Files are marked deleted in metadata but retained in R2\n- **Tenant isolation**: All files are prefixed with organization ID"
455
455
  },
456
456
  "stack/storage/using-kv": {
457
457
  "title": "Using KV",
@@ -459,7 +459,7 @@ export const DOCS = {
459
459
  },
460
460
  "stack/storage/using-r2": {
461
461
  "title": "Using R2",
462
- "content": "Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.\n\n## Upload Flow\n\nThe generated API provides a two-step **presigned** upload — the file bytes go\ndirectly to R2 and never stream through your Worker:\n\n1. **Request a presigned URL** — Client calls `/storage/v1/presign/...`; the\n Worker runs auth + bucket + role checks and returns a time-limited URL\n2. **Upload directly to R2** — Client `PUT`s the bytes to R2 (bypasses your Worker)\n3. **Confirm** — `/storage/v1/confirm/...` reconciles the recorded size + etag\n\n```bash\n# 1. Request a presigned upload URL\ncurl -X POST https://api.example.com/storage/v1/presign/documents/report.pdf \\\n -H \"Authorization: Bearer <token>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"contentType\": \"application/pdf\", \"size\": 248000 }'\n\n# Response:\n# {\n# \"id\": \"obj_abc123\",\n# \"key\": \"org_abc/documents/report.pdf\",\n# \"uploadUrl\": \"https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...\",\n# \"method\": \"PUT\",\n# \"headers\": { \"Content-Type\": \"application/pdf\" },\n# \"expiresAt\": \"2026-06-02T12:10:00.000Z\"\n# }\n\n# 2. Upload directly to R2 using the presigned URL (replay the returned headers)\ncurl -X PUT \"<uploadUrl>\" \\\n -H \"Content-Type: application/pdf\" \\\n --data-binary @report.pdf\n\n# 3. Confirm the upload\ncurl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \\\n -H \"Authorization: Bearer <token>\"\n```\n\nPresigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,\nand `R2_SECRET_ACCESS_KEY` secrets. See [R2 Setup → Presigned uploads](/stack/storage/r2#presigned-uploads-recommended).\n\nFor uploads that should land in **your own table** (with your own access rules),\nsign the URL from inside a `defineAction` via `ctx.storage` — see\n[Signing from your own action](/stack/storage/r2#signing-from-your-own-action).\n\n## Download Flow\n\nFiles are served through your Worker with security checks applied:\n\n```bash\n# Download a file (auth + firewall enforced)\ncurl https://api.example.com/api/v1/files/file_abc123/download \\\n -H \"Authorization: Bearer <token>\"\n```\n\nThe download endpoint:\n1. Validates the user's session\n2. Checks firewall — the file must belong to the user's organization\n3. Checks access — the user must have the required role\n4. Streams the file from R2\n\n## Role-Based Access\n\nFile access respects the same security layers as your API:\n\n- **Firewall** — Users can only access files belonging to their organization\n- **Access** — Role-based download permissions\n\n## See Also\n\n- [R2 Setup](/stack/storage/r2) — Bucket creation, wrangler bindings, and configuration\n- [Avatars](/stack/account-ui/features/avatars) — Avatar upload UI integration"
462
+ "content": "Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.\n\nBy default `defineFileStorage(\"cloudflare-r2\")` is **presign-only**: you get the\n`ctx.storage` signer and nothing else. The `/storage/v1/*` endpoints shown\nfurther down only exist in the [managed subsystem](/stack/storage/r2#two-modes)\n(`managed: true`).\n\n## Upload Flow (default — `ctx.storage`)\n\nWrite a normal `defineAction` that signs a presigned URL and stores the key in\n**your own table**. Bytes go directly to R2 — the Worker only signs.\n\n```ts\nexport default defineAction({\n path: \"/media/sign-upload\",\n method: \"POST\",\n input: z.object({ filename: z.string(), contentType: z.string() }),\n access: { roles: [\"member\"] },\n async execute({ input, ctx, db, storage }) {\n const key = `org/${ctx.activeOrgId}/${crypto.randomUUID()}-${input.filename}`;\n const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });\n await db.insert(media).values({ key /* … */ });\n return { uploadUrl: upload.url, key, headers: upload.headers };\n },\n});\n```\n\n```bash\n# 1. Ask your action for a signed URL (your auth/roles run here)\ncurl -X POST https://api.example.com/api/v1/media/sign-upload \\\n -H \"Authorization: Bearer <token>\" -H \"Content-Type: application/json\" \\\n -d '{ \"filename\": \"report.pdf\", \"contentType\": \"application/pdf\" }'\n# → { \"uploadUrl\": \"https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...\", \"key\": \"...\", \"headers\": { \"Content-Type\": \"application/pdf\" } }\n\n# 2. Upload the bytes straight to R2 (replay the returned headers)\ncurl -X PUT \"<uploadUrl>\" -H \"Content-Type: application/pdf\" --data-binary @report.pdf\n```\n\n`storage.signPutUrl(key, { contentType?, expiresIn?, bucket? })` returns\n`{ url, method, headers, key, expiresAt }`; `storage.signGetUrl(key, { expiresIn?, downloadFilename?, bucket? })`\nreturns a presigned GET URL. Pass `bucket` to target a bucket other than the\nconfigured default.\n\nPresigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,\nand `R2_SECRET_ACCESS_KEY` secrets. See [R2 Setup → Presigned uploads](/stack/storage/r2#presigned-uploads-recommended).\n\n## Upload Flow (managed mode — `/storage/v1/*`)\n\nWith `managed: true`, the generated API also exposes turnkey presigned\nendpoints backed by the FILES_DB metadata system:\n\n```bash\n# 1. Request a presigned upload URL\ncurl -X POST https://api.example.com/storage/v1/presign/documents/report.pdf \\\n -H \"Authorization: Bearer <token>\" -H \"Content-Type: application/json\" \\\n -d '{ \"contentType\": \"application/pdf\", \"size\": 248000 }'\n# → { \"id\": \"obj_abc\", \"key\": \"...\", \"uploadUrl\": \"...\", \"headers\": {...}, \"expiresAt\": \"...\" }\n\n# 2. Upload directly to R2\ncurl -X PUT \"<uploadUrl>\" -H \"Content-Type: application/pdf\" --data-binary @report.pdf\n\n# 3. Confirm (reconciles size + etag)\ncurl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \\\n -H \"Authorization: Bearer <token>\"\n```\n\n## Download Flow\n\nIn **presign-only** mode, mint a short-lived download URL with\n`storage.signGetUrl(key, { downloadFilename })` from your action and hand it to\nthe client — the bytes come straight from R2.\n\nIn **managed** mode, files are also served through the worker with security\nchecks applied:\n\n```bash\n# Download a file (auth + firewall enforced)\ncurl https://api.example.com/api/v1/files/file_abc123/download \\\n -H \"Authorization: Bearer <token>\"\n```\n\nThe download endpoint:\n1. Validates the user's session\n2. Checks firewall — the file must belong to the user's organization\n3. Checks access — the user must have the required role\n4. Streams the file from R2\n\n## Role-Based Access\n\nFile access respects the same security layers as your API:\n\n- **Firewall** — Users can only access files belonging to their organization\n- **Access** — Role-based download permissions\n\n## See Also\n\n- [R2 Setup](/stack/storage/r2) — Bucket creation, wrangler bindings, and configuration\n- [Avatars](/stack/account-ui/features/avatars) — Avatar upload UI integration"
463
463
  },
464
464
  "stack/vector/embeddings": {
465
465
  "title": "Automatic Embeddings",