@quickback-dev/cli 0.72.9 → 0.72.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +8 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/db-explain.d.ts +67 -0
  5. package/dist/commands/db-explain.d.ts.map +1 -0
  6. package/dist/commands/db-explain.js +141 -0
  7. package/dist/commands/db-explain.js.map +1 -0
  8. package/dist/commands/db-export.d.ts +34 -0
  9. package/dist/commands/db-export.d.ts.map +1 -0
  10. package/dist/commands/db-export.js +250 -0
  11. package/dist/commands/db-export.js.map +1 -0
  12. package/dist/commands/db-insights.d.ts +60 -0
  13. package/dist/commands/db-insights.d.ts.map +1 -0
  14. package/dist/commands/db-insights.js +106 -0
  15. package/dist/commands/db-insights.js.map +1 -0
  16. package/dist/commands/db-recovery.d.ts +98 -0
  17. package/dist/commands/db-recovery.d.ts.map +1 -0
  18. package/dist/commands/db-recovery.js +558 -0
  19. package/dist/commands/db-recovery.js.map +1 -0
  20. package/dist/commands/db-target.d.ts +27 -0
  21. package/dist/commands/db-target.d.ts.map +1 -0
  22. package/dist/commands/db-target.js +83 -0
  23. package/dist/commands/db-target.js.map +1 -0
  24. package/dist/commands/db.d.ts +3 -0
  25. package/dist/commands/db.d.ts.map +1 -0
  26. package/dist/commands/db.js +43 -0
  27. package/dist/commands/db.js.map +1 -0
  28. package/dist/commands/effects.d.ts +8 -0
  29. package/dist/commands/effects.d.ts.map +1 -0
  30. package/dist/commands/effects.js +48 -0
  31. package/dist/commands/effects.js.map +1 -0
  32. package/dist/commands/platform-budget.d.ts +143 -0
  33. package/dist/commands/platform-budget.d.ts.map +1 -0
  34. package/dist/commands/platform-budget.js +619 -0
  35. package/dist/commands/platform-budget.js.map +1 -0
  36. package/dist/commands/preview.d.ts +57 -0
  37. package/dist/commands/preview.d.ts.map +1 -0
  38. package/dist/commands/preview.js +268 -0
  39. package/dist/commands/preview.js.map +1 -0
  40. package/dist/commands/search.d.ts +20 -0
  41. package/dist/commands/search.d.ts.map +1 -0
  42. package/dist/commands/search.js +133 -0
  43. package/dist/commands/search.js.map +1 -0
  44. package/dist/index.js +35 -1
  45. package/dist/index.js.map +1 -1
  46. package/dist/lib/api-client.d.ts +4 -0
  47. package/dist/lib/api-client.d.ts.map +1 -1
  48. package/dist/lib/api-client.js.map +1 -1
  49. package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
  50. package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
  51. package/dist/lib/cloudflare-spend-policies.js +289 -0
  52. package/dist/lib/cloudflare-spend-policies.js.map +1 -0
  53. package/dist/lib/compiler-stubs.d.ts +2 -0
  54. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  55. package/dist/lib/compiler-stubs.js +2 -0
  56. package/dist/lib/compiler-stubs.js.map +1 -1
  57. package/dist/lib/d1-fingerprint.d.ts +8 -0
  58. package/dist/lib/d1-fingerprint.d.ts.map +1 -0
  59. package/dist/lib/d1-fingerprint.js +113 -0
  60. package/dist/lib/d1-fingerprint.js.map +1 -0
  61. package/dist/lib/file-loader.d.ts +12 -0
  62. package/dist/lib/file-loader.d.ts.map +1 -1
  63. package/dist/lib/file-loader.js +27 -1
  64. package/dist/lib/file-loader.js.map +1 -1
  65. package/dist/lib/migrations/plan.js +3 -0
  66. package/dist/lib/migrations/plan.js.map +1 -1
  67. package/dist/lib/migrations/postprocessors/index.d.ts +6 -5
  68. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  69. package/dist/lib/migrations/postprocessors/index.js +24 -12
  70. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  71. package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
  72. package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
  73. package/dist/lib/migrations/postprocessors/search.js +160 -0
  74. package/dist/lib/migrations/postprocessors/search.js.map +1 -0
  75. package/dist/lib/migrations/prior-state.d.ts +7 -0
  76. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  77. package/dist/lib/migrations/prior-state.js +3 -0
  78. package/dist/lib/migrations/prior-state.js.map +1 -1
  79. package/dist/lib/migrations/types.d.ts +1 -1
  80. package/dist/lib/migrations/types.d.ts.map +1 -1
  81. package/dist/lib/migrations/types.js +1 -0
  82. package/dist/lib/migrations/types.js.map +1 -1
  83. package/dist/lib/preview-lifecycle.d.ts +139 -0
  84. package/dist/lib/preview-lifecycle.d.ts.map +1 -0
  85. package/dist/lib/preview-lifecycle.js +429 -0
  86. package/dist/lib/preview-lifecycle.js.map +1 -0
  87. package/dist/lib/preview.d.ts +146 -0
  88. package/dist/lib/preview.d.ts.map +1 -0
  89. package/dist/lib/preview.js +417 -0
  90. package/dist/lib/preview.js.map +1 -0
  91. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  92. package/dist/lib/wrangler-resources.js +4 -2
  93. package/dist/lib/wrangler-resources.js.map +1 -1
  94. package/dist/skill/SKILL.md +9 -3
  95. package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
  96. package/dist/skill/docs/api/batch-operations.md +19 -0
  97. package/dist/skill/docs/api/caching.md +17 -0
  98. package/dist/skill/docs/api/crud.md +9 -0
  99. package/dist/skill/docs/api/errors.md +31 -2
  100. package/dist/skill/docs/api/query-params.md +6 -0
  101. package/dist/skill/docs/changelog/index.md +1 -0
  102. package/dist/skill/docs/configure/agents.md +1 -1
  103. package/dist/skill/docs/configure/bindings.md +177 -1
  104. package/dist/skill/docs/configure/cloudflare-access.md +43 -0
  105. package/dist/skill/docs/configure/domains.md +1 -1
  106. package/dist/skill/docs/configure/providers.md +5 -0
  107. package/dist/skill/docs/configure/tenant-databases.md +627 -14
  108. package/dist/skill/docs/define/access.md +26 -0
  109. package/dist/skill/docs/define/actions/defining.md +7 -1
  110. package/dist/skill/docs/define/actions/index.md +5 -0
  111. package/dist/skill/docs/define/actions/scoped-db.md +127 -1
  112. package/dist/skill/docs/define/authoring-basics.md +92 -0
  113. package/dist/skill/docs/define/changesets.md +8 -0
  114. package/dist/skill/docs/define/encryption.md +48 -2
  115. package/dist/skill/docs/define/feature.md +17 -2
  116. package/dist/skill/docs/define/guards.md +11 -3
  117. package/dist/skill/docs/define/index.md +1 -1
  118. package/dist/skill/docs/define/invariants.md +321 -0
  119. package/dist/skill/docs/define/issue-tracker-example.md +225 -0
  120. package/dist/skill/docs/define/masking.md +3 -3
  121. package/dist/skill/docs/define/rate-limit.md +63 -22
  122. package/dist/skill/docs/define/read.md +332 -5
  123. package/dist/skill/docs/define/relationships.md +10 -0
  124. package/dist/skill/docs/define/schema.md +137 -10
  125. package/dist/skill/docs/define/scopes.md +1 -0
  126. package/dist/skill/docs/define/transitions.md +9 -0
  127. package/dist/skill/docs/define/triggers.md +127 -1
  128. package/dist/skill/docs/platform/api-contract/index.md +35 -4
  129. package/dist/skill/docs/platform/auth/api-keys.md +26 -3
  130. package/dist/skill/docs/platform/auth/index.md +5 -2
  131. package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
  132. package/dist/skill/docs/platform/database/d1.md +73 -1
  133. package/dist/skill/docs/platform/database/durable-effects.md +224 -0
  134. package/dist/skill/docs/platform/database/read-replication.md +9 -0
  135. package/dist/skill/docs/platform/database/recovery.md +292 -0
  136. package/dist/skill/docs/platform/database/using-d1.md +152 -2
  137. package/dist/skill/docs/platform/index.md +1 -0
  138. package/dist/skill/docs/platform/operations/budgets.md +224 -0
  139. package/dist/skill/docs/platform/queues/handlers.md +1 -0
  140. package/dist/skill/docs/platform/queues/index.md +18 -0
  141. package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
  142. package/dist/skill/docs/platform/storage/using-r2.md +13 -0
  143. package/dist/skill/docs/platform/vector/embeddings.md +28 -4
  144. package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
  145. package/dist/skill/docs/platform/workflows/index.md +385 -0
  146. package/dist/skill/docs/start/deploy-browser.md +51 -0
  147. package/dist/skill/docs/start/deploy.md +97 -1
  148. package/dist/skill/docs/tooling/cli.md +117 -0
  149. package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
  150. package/dist/skill/docs/ui/account/customization.md +4 -0
  151. package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
  152. package/package.json +1 -1
  153. package/src/skill/SKILL.md +9 -3
  154. package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
  155. package/src/skill/docs/api/batch-operations.md +19 -0
  156. package/src/skill/docs/api/caching.md +17 -0
  157. package/src/skill/docs/api/crud.md +9 -0
  158. package/src/skill/docs/api/errors.md +31 -2
  159. package/src/skill/docs/api/query-params.md +6 -0
  160. package/src/skill/docs/changelog/index.md +1 -0
  161. package/src/skill/docs/configure/agents.md +1 -1
  162. package/src/skill/docs/configure/bindings.md +177 -1
  163. package/src/skill/docs/configure/cloudflare-access.md +43 -0
  164. package/src/skill/docs/configure/domains.md +1 -1
  165. package/src/skill/docs/configure/providers.md +5 -0
  166. package/src/skill/docs/configure/tenant-databases.md +627 -14
  167. package/src/skill/docs/define/access.md +26 -0
  168. package/src/skill/docs/define/actions/defining.md +7 -1
  169. package/src/skill/docs/define/actions/index.md +5 -0
  170. package/src/skill/docs/define/actions/scoped-db.md +127 -1
  171. package/src/skill/docs/define/authoring-basics.md +92 -0
  172. package/src/skill/docs/define/changesets.md +8 -0
  173. package/src/skill/docs/define/encryption.md +48 -2
  174. package/src/skill/docs/define/feature.md +17 -2
  175. package/src/skill/docs/define/guards.md +11 -3
  176. package/src/skill/docs/define/index.md +1 -1
  177. package/src/skill/docs/define/invariants.md +321 -0
  178. package/src/skill/docs/define/issue-tracker-example.md +225 -0
  179. package/src/skill/docs/define/masking.md +3 -3
  180. package/src/skill/docs/define/rate-limit.md +63 -22
  181. package/src/skill/docs/define/read.md +332 -5
  182. package/src/skill/docs/define/relationships.md +10 -0
  183. package/src/skill/docs/define/schema.md +137 -10
  184. package/src/skill/docs/define/scopes.md +1 -0
  185. package/src/skill/docs/define/transitions.md +9 -0
  186. package/src/skill/docs/define/triggers.md +127 -1
  187. package/src/skill/docs/platform/api-contract/index.md +35 -4
  188. package/src/skill/docs/platform/auth/api-keys.md +26 -3
  189. package/src/skill/docs/platform/auth/index.md +5 -2
  190. package/src/skill/docs/platform/auth/plugins/index.md +1 -1
  191. package/src/skill/docs/platform/database/d1.md +73 -1
  192. package/src/skill/docs/platform/database/durable-effects.md +224 -0
  193. package/src/skill/docs/platform/database/read-replication.md +9 -0
  194. package/src/skill/docs/platform/database/recovery.md +292 -0
  195. package/src/skill/docs/platform/database/using-d1.md +152 -2
  196. package/src/skill/docs/platform/index.md +1 -0
  197. package/src/skill/docs/platform/operations/budgets.md +224 -0
  198. package/src/skill/docs/platform/queues/handlers.md +1 -0
  199. package/src/skill/docs/platform/queues/index.md +18 -0
  200. package/src/skill/docs/platform/realtime/table-changes.md +1 -0
  201. package/src/skill/docs/platform/storage/using-r2.md +13 -0
  202. package/src/skill/docs/platform/vector/embeddings.md +28 -4
  203. package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
  204. package/src/skill/docs/platform/workflows/index.md +385 -0
  205. package/src/skill/docs/start/deploy-browser.md +51 -0
  206. package/src/skill/docs/start/deploy.md +97 -1
  207. package/src/skill/docs/tooling/cli.md +117 -0
  208. package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
  209. package/src/skill/docs/ui/account/customization.md +4 -0
  210. package/src/skill/docs/ui/admin/record-layouts.md +3 -3
@@ -38,7 +38,7 @@ Every binding declared here is also typed on `env` — the generated `Cloudflare
38
38
  | `sendEmail` | `SendEmail` |
39
39
  | `r2Buckets` | `R2Bucket` |
40
40
  | `queueProducers` | `Queue` |
41
- | `services` | `Fetcher` |
41
+ | `services` | `Fetcher`, or `Service<Entrypoint>` with an explicit `rpc` contract |
42
42
  | `durableObjects` | `DurableObjectNamespace` |
43
43
  | `ai` | `Ai` |
44
44
  | `vars` | `string` / `number` / `boolean`, from the value |
@@ -108,6 +108,91 @@ services: [
108
108
  ]
109
109
  ```
110
110
 
111
+ ### Typed service RPC
112
+
113
+ Opt in to a local contract for a sibling Worker's RPC methods:
114
+
115
+ ```ts
116
+ services: [
117
+ {
118
+ binding: "CATALOG",
119
+ service: "catalog-dev",
120
+ entrypoint: "CatalogRpc",
121
+ rpc: { from: "lib/contracts/catalog", export: "CatalogContract" },
122
+ },
123
+ ]
124
+ ```
125
+
126
+ `rpc.from` is an extensionless module in generated `src/` coordinates:
127
+ `lib/...` or `features/<feature>/lib/...`. Author it under the corresponding
128
+ `quickback/` directory. Absolute paths, `./`, traversal, URLs, extensions and
129
+ `node_modules` segments are refused. A local contract module may re-export a
130
+ type from a dependency explicitly declared by the project. Quickback never
131
+ loads a contract module to discover RPC methods, fetches a remote contract,
132
+ or reads a provider's source from outside the project.
133
+
134
+ `rpc.export` names the exported **WorkerEntrypoint subclass type**, not an
135
+ arbitrary structural interface. It is independent of `entrypoint`, which
136
+ names the deployed provider's export. For example, a shared contract module
137
+ can use `export type { CatalogRpc as CatalogContract } from "../CatalogRpc"`.
138
+ The generated environment uses
139
+ `Service<import("./lib/contracts/catalog").CatalogContract>`. Cloudflare's
140
+ [`Service` type](https://developers.cloudflare.com/workers/runtime-apis/rpc/typescript/)
141
+ checks method names, arguments and results, and makes synchronous provider
142
+ methods asynchronous for callers. Plain fetch bindings remain `Fetcher`;
143
+ existing projects need no migration.
144
+
145
+ Both generated compilation and `quickback check` check this contract. Missing
146
+ modules or exports, and unbranded structural contracts, fail typechecking even
147
+ when `skipLibCheck` is enabled. The contract import is type-only and adds no
148
+ provider code to the consumer's runtime bundle.
149
+
150
+ With named environments, declare services in
151
+ `environments.<key>.worker.bindings.services` for the edge Worker or
152
+ `environments.<key>.tenantWorker.services` for the tenant Worker. Every
153
+ occurrence of a binding in a given Worker role must have the same `rpc`
154
+ contract, or all must omit `rpc`. Target script names and remote entrypoint
155
+ names can differ. A binding missing from any target is optional in that role's
156
+ shared environment type. Edge and tenant roles may have different contracts;
157
+ tenant action helpers expose tenant services, not edge services. Existing
158
+ cross-target service restrictions still apply.
159
+
160
+ ### `serviceEntrypoints`
161
+
162
+ To provide RPC from a Quickback **edge Worker**, declare named authored exports:
163
+
164
+ ```ts
165
+ serviceEntrypoints: [
166
+ { name: "CatalogRpc", from: "lib/CatalogRpc" },
167
+ ]
168
+ ```
169
+
170
+ Author `CatalogRpc` as an exported class extending `WorkerEntrypoint` from
171
+ `cloudflare:workers` at `quickback/lib/CatalogRpc.ts`. The compiler emits
172
+ `export { CatalogRpc } from './lib/CatalogRpc'` in `src/index.ts`. The same
173
+ path restrictions as `rpc.from` apply. Duplicate names, framework entrypoint
174
+ names, `default`, and collisions with Durable Object class exports are refused.
175
+ This declaration creates **no HTTP route**, tenant Worker export, or DO migration.
176
+
177
+ > RPC types grant no authorization. Calls to an authored entrypoint do not run
178
+ > Quickback's HTTP authentication middleware, resource Access/Firewall checks,
179
+ > host allowlist or HTTP required-secret guard. The provider must validate its
180
+ > own credentials, required configuration, caller permissions and inputs before
181
+ > accessing data. A caller-supplied `userId` or organization ID is not proof of
182
+ > identity or authority. No credentials, user identity or service URLs are
183
+ > inferred from a contract.
184
+
185
+
186
+ Coordinate provider and consumer contract versions. Types check local source;
187
+ they cannot prove that the deployed target implements that source. Prefer
188
+ backward-compatible methods during rollout. Renaming an exported entrypoint
189
+ requires updating the provider and consumer configuration; it is not an
190
+ automatic remote migration.
191
+
192
+ Custom service bindings and `serviceEntrypoints` remain unsupported by brokered
193
+ deployment. Use the CLI to build and `wrangler deploy` to deploy each Worker,
194
+ with the provider available before the consumer calls it.
195
+
111
196
  ### `durableObjects`
112
197
 
113
198
  Emits `[[durable_objects.bindings]]` for app-owned Durable Objects. Don't use this for Quickback's built-in `BROADCASTER` realtime DO — that one is compiler-owned.
@@ -359,3 +444,94 @@ allowed — only a name pointing at two *different* things is rejected.
359
444
 
360
445
  - [Environment Variables](/configure/variables) — the non-secret `[vars]` / secret split
361
446
  - [Providers](/configure/providers) — runtime / database / auth selection
447
+
448
+ ## Durable Object code updates and retries
449
+
450
+ This opt-in policy belongs to `providers.runtime.config.durableObjects`, not
451
+ an individual binding. It requires the Cloudflare runtime and the generated
452
+ project's Wrangler / `@cloudflare/workers-types` pins. Omit it and the
453
+ generated code and configuration are unchanged.
454
+
455
+ ```ts
456
+ import { defineRuntime } from "@quickback/compiler";
457
+
458
+ const runtime = defineRuntime("cloudflare", {
459
+ durableObjects: {
460
+ codeUpdateStrategy: { mode: "deferred", maxDelaySeconds: 60 },
461
+ retry: { maxRetries: 1, timeoutMs: 2000 },
462
+ },
463
+ });
464
+ ```
465
+
466
+ Unknown keys, an `immediate` strategy with a delay, and out-of-range values
467
+ are compile errors.
468
+
469
+ ### `codeUpdateStrategy`
470
+
471
+ Emits `durable_objects.code_update_strategy` once in each generated Worker's
472
+ config. It applies to **all classes that Worker exports**, including
473
+ exports-based lifecycle declarations. A cross-worker binding follows its
474
+ exporting Worker's strategy. Choose `immediate` without a delay, or `deferred`
475
+ with an optional `maxDelaySeconds` from 0–86400 at millisecond precision.
476
+ Omission uses Cloudflare's deferred 300-second default on the next deployment.
477
+ Deferral is best effort; keep protocols compatible across versions. This
478
+ setting is neither a storage migration nor a no-downtime guarantee. The
479
+ brokered deploy rejects an explicit strategy (and `retry`); deploy with Wrangler. See
480
+ Cloudflare's
481
+ [code-update policy](https://developers.cloudflare.com/durable-objects/deployments/durable-objects-code-updates/).
482
+
483
+ ### `retry`
484
+
485
+ Selects **native-only retries for the stubs Quickback creates** in that
486
+ Worker: realtime `Broadcaster` publish and read stubs (not the WebSocket upgrade, a stream the platform never replays), tenant forwarding, commands, jobs and
487
+ tenant control stubs. Optional `maxRetries` is an integer from 0–10;
488
+ `timeoutMs` is an integer from 500–60000. An empty object selects platform
489
+ defaults. See Cloudflare's
490
+ [automatic retries](https://developers.cloudflare.com/durable-objects/best-practices/automatic-retries/).
491
+
492
+ There is exactly one retry layer per call:
493
+
494
+ - **Without `retry`**, Quickback keeps its existing selective application
495
+ retries: one retry on a fresh stub after a reset or retryable error, only
496
+ for tenant `GET`/`HEAD` forwarding, read-mode commands, result jobs and
497
+ realtime publishes and sequence reads. The platform's default transport
498
+ retries still apply underneath.
499
+ - **With `retry`**, those application retries are skipped. The stub carries
500
+ your budget and the platform alone decides what to retry. A failure after a
501
+ method started is retried only for methods marked safe to run again — so a
502
+ tenant `GET` that loses its object mid-request now returns an error instead
503
+ of a second attempt. `maxRetries: 0` still disables the application retry.
504
+
505
+ Only `Broadcaster.readSurfaceSeq` and `QuickbackTenant.report` are marked safe
506
+ to run again. Both only read stored state. The mark follows the policy of the
507
+ Worker that exports the class; the budget follows the Worker that calls it.
508
+ Publishes, `fetch`, tenant `handle`/`command`, jobs, restores, hooks and alarms
509
+ stay unmarked, so the platform never replays them after they may have started.
510
+ This is not a deduplication mechanism for authored side effects. Tenant,
511
+ principal, admission, protocol-version and restore checks run on every
512
+ attempt. User errors, overload and HTTP error responses never trigger a retry.
513
+ The retry horizon does not cancel the first attempt, so realtime publish and
514
+ read deadlines stay in place.
515
+
516
+ Custom Durable Object methods and stubs your own code creates are yours: the
517
+ compiler neither marks nor wraps them. The compiler reserves the
518
+ `__QB_DO_RETRY_POLICY` var that carries the budget; declaring it as a var,
519
+ secret or binding is a compile error.
520
+
521
+ ### Named targets and rollback
522
+
523
+ The runtime policy is the default for every generated Worker. Set
524
+ `environments.<target>.worker.durableObjects` or
525
+ `environments.<target>.tenantWorker.durableObjects` to override one Worker for
526
+ that target — the edge and tenant Workers resolve independently. Members
527
+ replace whole: overriding `retry` keeps the default `codeUpdateStrategy` but
528
+ replaces the entire retry object, not individual keys. A target-only `retry`
529
+ leaves the other targets on the application-retry path. The separately
530
+ generated broadcast Worker (`realtime.mode: 'separate'`) uses the top-level
531
+ runtime policy.
532
+
533
+ Roll back by removing the policy at every level, recompiling, and deploying the
534
+ affected Workers. Removing a target override alone restores the runtime
535
+ default. The code-update strategy is sent with every deployment; it does not
536
+ persist from a previous version. Object identities, exports and storage
537
+ migrations are unchanged.
@@ -189,3 +189,46 @@ Anything else gets **403 `CSRF_ORIGIN_REJECTED`**. Service-token requests skip t
189
189
  2. Copy its **Application Audience (AUD) tag** into `aud`.
190
190
  3. Set `teamDomain` to your team domain, `<team>.cloudflareaccess.com`.
191
191
  4. For machines, create a service token and add a **Service Auth** policy. Then map its Client ID in `serviceTokens`.
192
+
193
+ ## Native browser applications (opt in)
194
+
195
+ Set `browser: true` on an Access application and set `features.pinnedOrganizationId` to an existing organization. This mode is for a custom browser application whose employees authenticate through Access alone. The Account SPA still uses Better Auth session APIs; use an Access-aware custom account/team surface with the existing roster and `ctx.auth` operations. Nothing changes for applications without `browser: true`.
196
+
197
+ ```ts title="quickback.config.ts"
198
+ export default defineConfig({
199
+ // Keep your existing Cloudflare + D1 + Better Auth providers.
200
+ features: { organizations: true, pinnedOrganizationId: 'org_studio' },
201
+ auth: {
202
+ cloudflareAccess: {
203
+ teamDomain: { env: 'CF_ACCESS_TEAM' },
204
+ aud: { env: 'CF_ACCESS_AUD' },
205
+ hosts: ['studio.example.com'],
206
+ roles: ['user'],
207
+ browser: true,
208
+ excludePaths: ['/auth/v1/oauth2/token', '/auth/v1/oauth2/register', '/mcp', '/.well-known'],
209
+ },
210
+ },
211
+ });
212
+ ```
213
+
214
+ The native browser lane requires HTTPS, an existing verified, nonbanned user, and live membership in the pinned organization. Mapped service tokens cannot create a browser identity in this mode. No users or memberships are automatically provisioned. `roles` remains the platform user-role admission list; data permissions still come from organization membership.
215
+
216
+ `GET /api/v1/auth/context` returns a no-store projection: `authMethod`, `identityType`, safe `user` fields (`id`, `email`, `name`), `organization` (`id`, `name`, `slug`, `role`), `browser` (`id`, `expiresAt` in Unix seconds), and `logoutUrl`. It never returns an assertion or a session credential. Use this endpoint instead of Better Auth's `get-session` and organization selection APIs. Pinned mode needs no organization switcher.
217
+
218
+ The Worker creates a real Better Auth session, binds it to the verified Access user, policy and organization, and keeps its credential inside an encrypted, Secure, HttpOnly, host-only browser cookie. That cookie cannot authenticate any request on its own. Every native request revalidates the Access assertion, user and membership, and checks the session store. Verified Access browser activity refreshes a live session according to Better Auth's configured update-age policy; connector bearer traffic cannot refresh that browser session. A revoked session is refused; a subsequent fresh browser binding requires another Access-authenticated request. `ctx.authMethod` stays `cloudflare-access`; `ctx.browser` proves the human browser context, with its real `id` also available as `ctx.sessionId`. `ctx.browser.expiresAt` is bounded by both the assertion and session expiry. Do not replace these checks with a client-provided user or session ID.
219
+
220
+ Actions may combine their existing organization-role rules with `authMethod: ['cloudflare-access']`. In browser mode the lane refuses service tokens; outside browser mode that auth method alone is not a human-only rule. Retain row firewalls and use `ctx.auth` for organization-bound member operations. Encryption uses the existing authenticated-context middleware. Realtime tickets carry the verified absolute authorization expiry into the existing socket lease cap; renewal requires fresh admission. App membership removal takes effect on the next request/renewal, while an existing socket remains bounded by its authorization lease/expiry. Access or IdP policy revocation follows the Access application's own session policy and is not instantaneous app revocation.
221
+
222
+ ### OAuth without a second app login
223
+
224
+ Browser mode narrowly bridges `GET`/`HEAD /auth/v1/oauth2/authorize`, `GET`/`HEAD /auth/v1/oauth2/public-client` and `POST /auth/v1/oauth2/consent` to the provider's existing authorization engine with the verified internal session. Existing client, redirect, PKCE, consent, audience, scope and refresh/revocation validation still applies. Other Better Auth session, password and token-mint routes remain refused inside the scope. Internal session cookies and token headers from authorization responses are not exposed to the browser.
225
+
226
+ Noninteractive code exchange/refresh, discovery, DCR and MCP clients must run outside the Access scope. `excludePaths` is an explicit list of path-prefix exceptions to this application's Access lane, with the same segment-boundary matching as `paths`. It requires `browser: true`; it is not an authentication grant: ordinary route authentication and signature checks still run. Configure the edge's Access applications/policies to match these exceptions too. Never exclude an entire browser API or add cookie/bearer fallback on a protected path. For an endpoint used by both browsers and OAuth clients, give the browser a separate protected route that reuses the same domain implementation, or use a separate integration hostname.
227
+
228
+ `POST /api/v1/auth/logout` revokes the internal session and clears the binding cookie, then returns `{ url: '/cdn-cgi/access/logout' }`. Clear application/query/storage caches before navigating there. Existing ordinary OAuth grants tied to that session can no longer refresh. A user, membership or Access identity change must also clear client caches; do not persist data keyed only by organization.
229
+
230
+ ### Custom Worker entrypoints
231
+
232
+ If an authored Worker returns documents before calling the generated app, protect those responses too. The generated `src/lib/cloudflare-access-browser.ts` exports `authenticateAccessBrowserRequest(request, env, executionCtx?)`, returning `{ context, headers }`. It uses the same configured application selection, verifier, live user/membership lookup and browser binding. Forward its `Set-Cookie` response headers. On a typed refusal forward `error.status`/`error.code` and any clearing cookie in `error.headers`; never fall back to a session. The helper refuses excluded paths and unconfigured applications. It is emitted as a disabled compatibility stub when browser mode is off so an authored entrypoint can import it behind a feature flag.
233
+
234
+ Generated APIs already perform this check in middleware; do not authenticate them twice in a wrapper. Do not copy the helper's private credentials, return the full context as JSON, or hand-parse Access headers in application code. Only the context endpoint's documented projection is suitable for the browser.
@@ -247,7 +247,7 @@ Each `domains` key maps 1:1 to a top-level source:
247
247
 
248
248
  When the project generates exactly **one** hostname, `domain: "api-dev.attend.vip"` is accepted as shorthand for the single role.
249
249
 
250
- Named MCP server hosts are not `domains` keys: `agents.mcp.servers.<key>.publicUrl` is itself keyed by environment (`{ production: "https://mcp.attend.vip/guest", dev: "https://mcp-dev.attend.vip/guest" }`), and each host is appended to that target's `routes`. The compiler also stamps `QUICKBACK_ENVIRONMENT = "<name>"` into each target's vars so the shared bundle knows which public URL is its own. A host claimed by another target fails the compile, like any other duplicate hostname.
250
+ Named MCP server hosts are not `domains` keys: `agents.mcp.servers.<key>.publicUrl` is itself keyed by environment (`{ production: "https://mcp.attend.vip/guest", dev: "https://mcp-dev.attend.vip/guest" }`), and each host is appended to that target's `routes`. The compiler also stamps `QUICKBACK_ENVIRONMENT = "<name>"` into each target's vars so the shared bundle knows which public URL is its own (it does the same whenever the `apiKey` plugin is on — [API keys](/platform/auth/api-keys#key-prefix) pick their `live_` / `<environment>_` segment from it). A host claimed by another target fails the compile, like any other duplicate hostname.
251
251
 
252
252
  `domains: 'none'` marks a workers.dev-only target. It emits `routes = []` rather than omitting the block, so inheritance cannot hand that target a sibling's custom domain.
253
253
 
@@ -20,6 +20,7 @@ providers: {
20
20
  |--------|------|-------------|
21
21
  | `accountId` | `string` | Emits top-level `account_id` in `wrangler.toml`. 32 lowercase hex characters, or the compile fails. A named target in another account sets `environments.<name>.accountId` — see [A target in another Cloudflare account](/platform/database/d1#a-target-in-another-cloudflare-account-accountid). |
22
22
  | `compatibilityDate` | `string` | Emits Cloudflare `compatibility_date` in `wrangler.toml`. |
23
+ | `durableObjects` | `object` | Opt-in Worker-wide code-update strategy and bounded native retries. Defaults for edge/tenant Workers, with per-target overrides. See [Durable Object policy](/configure/bindings#durable-object-code-updates-and-retries). |
23
24
  | `placement.mode` | `"smart" \| "standard"` | Emits Cloudflare's `[placement]` block. Mutually exclusive with `placement.region`. |
24
25
  | `placement.region` | `string` | Placement hint, `"<cloud>:<region>"` (e.g. `"aws:us-east-2"`): runs the Worker next to a single-region database instead of next to the user. Set it to your Postgres region. Any other `placement` key is a compile error. Named environments emit it per target; override with `environments.<name>.worker.placement`. |
25
26
  | `observability.enabled` | `boolean` | Emits top-level Workers Logs persistence under `[observability]`. |
@@ -33,6 +34,7 @@ providers: {
33
34
  | `observability.traces.destinations` | `string[]` | Named trace export destinations configured in Cloudflare. |
34
35
  | `observability.traces.headSamplingRate` | `number` | Workers Traces sample rate from `0` to `1`. |
35
36
  | `observability.traces.persist` | `boolean` | Keeps exported traces in the Cloudflare dashboard. |
37
+ | `limits.cpuMs` | `number` | Emits Wrangler `limits.cpu_ms`: the CPU time one invocation may use, a whole number from `1` to `300000`. Named environments restate it per target. Omit it to keep the platform default. It caps runaway work per request. It is not an account spending limit; see [Account spend policies](/platform/operations/budgets). |
36
38
  | `routes` | `{ pattern, custom_domain? }[]` | Custom domain routes for the generated Worker. |
37
39
 
38
40
  ```typescript
@@ -111,7 +113,10 @@ single Postgres database with no bindings or split mode (see
111
113
  | `usePlurals` | `boolean` | `false` (`true` on Neon / PlanetScale Postgres) | Pluralize auth table names (e.g. `user` vs `users`). The default differs by provider — porting a D1 project to Postgres, set `usePlurals: false` explicitly to keep its table names |
112
114
  | `splitDatabases` | `boolean` | `true` | Separate auth and features databases (D1 only) |
113
115
  | `queryTimeoutMs` | `number` | — | Per-statement deadline for every D1 query the generated code runs (CRUD, actions, the auth adapter, cron/queue/email runners, files, audit). Unset = no deadline. D1 only — the Postgres drivers have their own timeout options. Past the deadline a read answers `503 DB_TIMEOUT` and a write `500 DB_WRITE_OUTCOME_UNKNOWN`; see [Backend stalls](/platform/database/using-d1#backend-stalls) and [Database errors](/api/errors#database-constraint-errors). The statement is **not** cancelled on the backend |
116
+ | `diagnostics` | `{ sampleRate, slowMs, rowsReadWarning }` | — | Sampled `D1_QUERY` cost events (privacy-safe fingerprints, no SQL text or values) plus `reports/d1-query-catalog.json` for `quickback db explain` / `db insights`. All three fields required; `sampleRate` 0–1. D1 only. See [Sampled query diagnostics](/platform/database/using-d1#sampled-query-diagnostics) |
114
117
  | `readReplication` | `boolean \| { header?: string }` | — | Run each request's feature `db` on a D1 session so regional read replicas can serve it. `GET`/`HEAD` continue the client's session from the bookmark header (default `x-d1-bookmark`) or start `first-unconstrained`; other methods start `first-primary`. The response echoes the bookmark. D1 only; auth/audit/webhooks and cron/queue/email runners stay on the primary. Enable replication on the database itself in the Cloudflare dashboard — see [Read replication](/platform/database/read-replication) |
118
+ | `durableEffects` | `{ enabled: boolean; maxAttempts?: number; sweepCron?: string; workflowQueue?: string }` | — | Record queue effects in the same D1 batch as the writes (`db.batch(writes, { effects })`) and deliver them at least once through a leased dispatcher, consumer admission and the `QB_CONTROL` operational-control Durable Object. D1 + Cloudflare only; requires a configured queue. Required by [Workflows](/platform/workflows); `workflowQueue` names the queue for workflow intents when there is more than one. See [Durable effects](/platform/database/durable-effects) |
119
+ | `readCache` | `{ enabled: boolean }` | — | Deploy the user-scoped [Workers Cache](/define/read#workers-cache): a private `QuickbackReadCache` entrypoint with Workers Cache on (the gateway stays uncached), the `QB_CONTROL` operational-control Durable Object (kept for deployments that already carry its class; the read path never calls it), and the `_quickback_data_epoch` table: every write batch on the features binding also mints a fresh [data epoch](/define/read#the-data-epoch) token, which keeps cached reads correct across D1 restores. Refused alongside user Durable Objects, service entrypoints or a tenant Durable Object, which get the raw `env`. Resources opt in with `read.cache: { engine: "workers", scope: "user", ttlSeconds }`; enabling it with no opted-in resource is a compile error. D1 + Cloudflare + Better Auth only |
115
120
  | `authBinding` | `string` | `"AUTH_DB"` | Binding name for auth database |
116
121
  | `featuresBinding` | `string` | `"DB"` | Binding name for features database |
117
122
  | `databaseId` | `string` | — | D1 database ID for the features database (used in generated wrangler.toml) |