@quickback-dev/cli 0.10.16 → 0.11.0

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 (253) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +15 -10
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/skill/SKILL.md +142 -1051
  10. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  11. package/dist/skill/docs/changelog.md +1225 -0
  12. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  17. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  18. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  19. package/dist/skill/docs/compiler/config/agents.md +144 -0
  20. package/dist/skill/docs/compiler/config/auth.md +109 -0
  21. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  22. package/dist/skill/docs/compiler/config/domains.md +149 -0
  23. package/dist/skill/docs/compiler/config/index.md +419 -0
  24. package/dist/skill/docs/compiler/config/output.md +338 -0
  25. package/dist/skill/docs/compiler/config/providers.md +248 -0
  26. package/dist/skill/docs/compiler/config/security.md +255 -0
  27. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  28. package/dist/skill/docs/compiler/config/variables.md +157 -0
  29. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  30. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  31. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  32. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  33. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  34. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  36. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  37. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  38. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  39. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  40. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  41. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  42. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  43. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  44. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  45. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  46. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  47. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  48. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  49. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  50. package/dist/skill/docs/compiler/index.md +85 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  64. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  65. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  66. package/dist/skill/docs/compiler/targets/index.md +47 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  69. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  70. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  71. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  72. package/dist/skill/docs/index.md +77 -0
  73. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  74. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  75. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  76. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  77. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  78. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  79. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  80. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  81. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  82. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  83. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  84. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  85. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  86. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  87. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  88. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  89. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  90. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  91. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  92. package/dist/skill/docs/stack/auth/index.md +64 -0
  93. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  94. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  95. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  96. package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
  97. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  98. package/dist/skill/docs/stack/auth/security.md +455 -0
  99. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  100. package/dist/skill/docs/stack/cms/actions.md +199 -0
  101. package/dist/skill/docs/stack/cms/components.md +479 -0
  102. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  103. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  104. package/dist/skill/docs/stack/cms/index.md +158 -0
  105. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  106. package/dist/skill/docs/stack/cms/pages.md +275 -0
  107. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  108. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  109. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  110. package/dist/skill/docs/stack/cms/security.md +203 -0
  111. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  112. package/dist/skill/docs/stack/index.md +65 -0
  113. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  114. package/dist/skill/docs/stack/queues/index.md +56 -0
  115. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  116. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  117. package/dist/skill/docs/stack/realtime/index.md +73 -0
  118. package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  119. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  120. package/dist/skill/docs/stack/storage/index.md +17 -0
  121. package/dist/skill/docs/stack/storage/kv.md +204 -0
  122. package/dist/skill/docs/stack/storage/r2.md +232 -0
  123. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  124. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  125. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  126. package/dist/skill/docs/stack/vector/index.md +44 -0
  127. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  128. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  129. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  130. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  131. package/package.json +1 -1
  132. package/src/skill/SKILL.md +142 -1051
  133. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  134. package/src/skill/docs/changelog.md +1225 -0
  135. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  136. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  137. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  138. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  139. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  140. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  141. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  142. package/src/skill/docs/compiler/config/agents.md +144 -0
  143. package/src/skill/docs/compiler/config/auth.md +109 -0
  144. package/src/skill/docs/compiler/config/bindings.md +176 -0
  145. package/src/skill/docs/compiler/config/domains.md +149 -0
  146. package/src/skill/docs/compiler/config/index.md +419 -0
  147. package/src/skill/docs/compiler/config/output.md +338 -0
  148. package/src/skill/docs/compiler/config/providers.md +248 -0
  149. package/src/skill/docs/compiler/config/security.md +255 -0
  150. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  151. package/src/skill/docs/compiler/config/variables.md +157 -0
  152. package/src/skill/docs/compiler/definitions/access.md +445 -0
  153. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  154. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  155. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  156. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  157. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  158. package/src/skill/docs/compiler/definitions/index.md +219 -0
  159. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  160. package/src/skill/docs/compiler/definitions/read.md +220 -0
  161. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  162. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  163. package/src/skill/docs/compiler/definitions/views.md +292 -0
  164. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  165. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  166. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  167. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  168. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  169. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  170. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  171. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  172. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  173. package/src/skill/docs/compiler/index.md +85 -0
  174. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  176. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  177. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  178. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  179. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  186. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  187. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  188. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  189. package/src/skill/docs/compiler/targets/index.md +47 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  191. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  192. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  193. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  194. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  195. package/src/skill/docs/index.md +77 -0
  196. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  197. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  198. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  199. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  200. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  201. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  202. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  203. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  204. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  205. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  206. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  207. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  208. package/src/skill/docs/stack/account-ui/index.md +147 -0
  209. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  210. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  211. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  212. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  213. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  214. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  215. package/src/skill/docs/stack/auth/index.md +64 -0
  216. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  217. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  218. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  219. package/src/skill/docs/stack/auth/plugins/index.md +340 -0
  220. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  221. package/src/skill/docs/stack/auth/security.md +455 -0
  222. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  223. package/src/skill/docs/stack/cms/actions.md +199 -0
  224. package/src/skill/docs/stack/cms/components.md +479 -0
  225. package/src/skill/docs/stack/cms/connecting.md +199 -0
  226. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  227. package/src/skill/docs/stack/cms/index.md +158 -0
  228. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  229. package/src/skill/docs/stack/cms/pages.md +275 -0
  230. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  231. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  232. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  233. package/src/skill/docs/stack/cms/security.md +203 -0
  234. package/src/skill/docs/stack/cms/table-views.md +142 -0
  235. package/src/skill/docs/stack/index.md +65 -0
  236. package/src/skill/docs/stack/queues/handlers.md +317 -0
  237. package/src/skill/docs/stack/queues/index.md +56 -0
  238. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  239. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  240. package/src/skill/docs/stack/realtime/index.md +73 -0
  241. package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  242. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  243. package/src/skill/docs/stack/storage/index.md +17 -0
  244. package/src/skill/docs/stack/storage/kv.md +204 -0
  245. package/src/skill/docs/stack/storage/r2.md +232 -0
  246. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  247. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  248. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  249. package/src/skill/docs/stack/vector/index.md +44 -0
  250. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  251. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  252. package/src/skill/docs/stack/webhooks/index.md +36 -0
  253. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,340 @@
1
+ # Auth Plugins
2
+
3
+ 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`.
4
+
5
+ ## Available Plugins
6
+
7
+ ### Email OTP (with AWS SES)
8
+
9
+ Quickback 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).
10
+
11
+ **Enable in config:**
12
+
13
+ ```ts
14
+ import { defineAuth, defineConfig, defineDatabase, defineRuntime, defineStorage } from "@quickback/compiler";
15
+
16
+ export default defineConfig({
17
+ name: "quickback-api",
18
+ providers: {
19
+ runtime: defineRuntime("cloudflare"),
20
+ database: defineDatabase("cloudflare-d1", {
21
+ vars: {
22
+ AWS_SES_REGION: "us-east-2",
23
+ EMAIL_FROM: "noreply@yourdomain.com",
24
+ EMAIL_FROM_NAME: "Your App | Account Services",
25
+ APP_NAME: "Your App",
26
+ APP_URL: "https://account.yourdomain.com",
27
+ BETTER_AUTH_URL: "https://api.yourdomain.com",
28
+ },
29
+ }),
30
+ auth: defineAuth("better-auth", {
31
+ emailAndPassword: { enabled: true },
32
+ plugins: ["emailOtp"],
33
+ }),
34
+ },
35
+ });
36
+ ```
37
+
38
+ **Endpoints:**
39
+ - `POST /auth/v1/email-otp/send-verification-otp`
40
+ - `POST /auth/v1/email-otp/verify-otp`
41
+
42
+ **Email readiness check:**
43
+
44
+ Use this to show UI warnings when SES isn't configured.
45
+
46
+ - `GET /api/v1/system/email-status`
47
+ - Response: `{ "emailConfigured": true|false }`
48
+
49
+ ### Upgrade Anonymous
50
+
51
+ Adds a first-class endpoint to convert an anonymous user into a full user. This flips `isAnonymous` to `false` and refreshes the session cache immediately.
52
+
53
+ **Enable in config:**
54
+
55
+ ```ts
56
+ auth: defineAuth("better-auth", {
57
+ emailAndPassword: { enabled: true },
58
+ plugins: ["anonymous", "upgradeAnonymous"],
59
+ }),
60
+ ```
61
+
62
+ **Endpoint:**
63
+ - `POST /auth/v1/upgrade-anonymous`
64
+
65
+ **Note:** If you send `Content-Type: application/json`, include a body (an empty `{}` is fine). This avoids request parsing errors in some clients.
66
+
67
+ ### AWS SES Plugin
68
+
69
+ This 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).
70
+
71
+ Required vars (only when `email.provider: 'aws-ses'` is set; use Wrangler secrets for credentials):
72
+ - `AWS_ACCESS_KEY_ID` (secret)
73
+ - `AWS_SECRET_ACCESS_KEY` (secret)
74
+ - `AWS_SES_REGION`
75
+ - `EMAIL_FROM`
76
+
77
+ Optional vars:
78
+ - `EMAIL_FROM_NAME`
79
+ - `EMAIL_REPLY_TO` - Reply-to address for emails (defaults to `EMAIL_FROM`)
80
+ - `APP_NAME`
81
+ - `APP_URL`
82
+ - `BETTER_AUTH_URL`
83
+
84
+ ### Magic Links
85
+
86
+ Magic 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.
87
+
88
+ **Enable in config:**
89
+
90
+ ```ts
91
+ auth: defineAuth("better-auth", {
92
+ plugins: ["magicLink"],
93
+ }),
94
+ ```
95
+
96
+ **Endpoints:**
97
+ - `POST /auth/v1/magic-link/send` - Send magic link email
98
+ - `GET /auth/v1/magic-link/verify` - Verify magic link token
99
+
100
+ **Email customization:**
101
+
102
+ Magic link emails use the same AWS SES configuration as Email OTP. Customize the email template via environment variables:
103
+
104
+ - `APP_NAME` - Application name in email subject
105
+ - `APP_URL` - Base URL for magic link redirect
106
+ - `EMAIL_FROM` - Sender email address
107
+ - `EMAIL_FROM_NAME` - Sender display name
108
+
109
+ **Frontend integration:**
110
+
111
+ ```ts
112
+ // Request magic link
113
+ await fetch('/auth/v1/magic-link/send', {
114
+ method: 'POST',
115
+ headers: { 'Content-Type': 'application/json' },
116
+ body: JSON.stringify({ email: 'user@yourdomain.com' })
117
+ });
118
+
119
+ // User clicks link in email, which redirects to your app
120
+ // The token is verified automatically via the callback URL
121
+ ```
122
+
123
+ ### Passkeys
124
+
125
+ Passkeys provide passwordless authentication using WebAuthn/FIDO2. Users authenticate with biometrics (fingerprint, face) or device PIN instead of passwords.
126
+
127
+ **Enable in config:**
128
+
129
+ ```ts
130
+ auth: defineAuth("better-auth", {
131
+ plugins: ["passkey"],
132
+ }),
133
+ ```
134
+
135
+ **Required environment variable:**
136
+ - `ACCOUNT_URL` - Your account/frontend URL (used as the relying party origin for WebAuthn)
137
+
138
+ **Endpoints:**
139
+ - `POST /auth/v1/passkey/register/options` - Get registration challenge
140
+ - `POST /auth/v1/passkey/register/verify` - Complete registration
141
+ - `POST /auth/v1/passkey/authenticate/options` - Get authentication challenge
142
+ - `POST /auth/v1/passkey/authenticate/verify` - Complete authentication
143
+ - `GET /auth/v1/passkey/list-user-passkeys` - List user's registered passkeys
144
+ - `POST /auth/v1/passkey/delete-passkey` - Delete a registered passkey
145
+
146
+ **Browser support:**
147
+
148
+ Passkeys are supported in all modern browsers:
149
+ - Chrome 67+
150
+ - Safari 14+
151
+ - Firefox 60+
152
+ - Edge 79+
153
+
154
+ **Registration flow:**
155
+
156
+ ```ts
157
+ // 1. Get registration options
158
+ const optionsRes = await fetch('/auth/v1/passkey/register/options', {
159
+ method: 'POST',
160
+ credentials: 'include'
161
+ });
162
+ const options = await optionsRes.json();
163
+
164
+ // 2. Create credential using WebAuthn API
165
+ const credential = await navigator.credentials.create({
166
+ publicKey: options
167
+ });
168
+
169
+ // 3. Send credential to server
170
+ await fetch('/auth/v1/passkey/register/verify', {
171
+ method: 'POST',
172
+ headers: { 'Content-Type': 'application/json' },
173
+ credentials: 'include',
174
+ body: JSON.stringify(credential)
175
+ });
176
+ ```
177
+
178
+ **Authentication flow:**
179
+
180
+ ```ts
181
+ // 1. Get authentication options
182
+ const optionsRes = await fetch('/auth/v1/passkey/authenticate/options', {
183
+ method: 'POST'
184
+ });
185
+ const options = await optionsRes.json();
186
+
187
+ // 2. Get credential using WebAuthn API
188
+ const credential = await navigator.credentials.get({
189
+ publicKey: options
190
+ });
191
+
192
+ // 3. Verify credential
193
+ await fetch('/auth/v1/passkey/authenticate/verify', {
194
+ method: 'POST',
195
+ headers: { 'Content-Type': 'application/json' },
196
+ credentials: 'include',
197
+ body: JSON.stringify(credential)
198
+ });
199
+ ```
200
+
201
+ ### JWT Plugin
202
+
203
+ Better 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.
204
+
205
+ **Enable in config:**
206
+
207
+ ```ts
208
+ auth: defineAuth("better-auth", {
209
+ plugins: ["jwt"],
210
+ }),
211
+ ```
212
+
213
+ **Endpoints:**
214
+ - `GET /auth/v1/jwks` — public keys for verifying BA-issued tokens
215
+ - `POST /auth/v1/token` — mint an asymmetric-signed JWT from the current session
216
+
217
+ > This is **separate from** Quickback's built-in JWT fast-path. Quickback's middleware already validates a custom HMAC-SHA256 JWT (with embedded org context) on every request — enabling the BA plugin does **not** change how the compiled API authenticates. See [JWT Optimization → Relation to Better Auth's JWT Plugin](/stack/auth/jwt-optimization#relation-to-better-auths-jwt-plugin) for the full comparison and when to use each.
218
+
219
+
220
+ **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.
221
+
222
+ ### API Keys
223
+
224
+ Static, 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.
225
+
226
+ **Authenticating requests:**
227
+
228
+ Pass the key as the `x-api-key` header (preferred) or as an `?api_key=` / `?key=` query parameter:
229
+
230
+ ```bash
231
+ # Header form (preferred — keys don't leak into access logs or Referer)
232
+ curl -H "x-api-key: ${KEY}" https://api.example.com/v1/jobs
233
+
234
+ # Query-param form (for clients that can't inject custom headers,
235
+ # e.g., claude.ai's MCP connector)
236
+ curl "https://api.example.com/v1/jobs?api_key=${KEY}"
237
+ ```
238
+
239
+ The 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.
240
+
241
+ **Endpoints (managed by Better Auth):**
242
+ - `POST /auth/v1/api-key/create` — issue a new key (returns the secret once; store it)
243
+ - `GET /auth/v1/api-key/list` — list keys for the current user
244
+ - `POST /auth/v1/api-key/delete` — revoke a key
245
+
246
+ Keys 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.
247
+
248
+ ### OAuth Provider (MCP-ready)
249
+
250
+ Turns 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.
251
+
252
+ **Enable in config:**
253
+
254
+ ```ts
255
+ auth: defineAuth("better-auth", {
256
+ plugins: ["oauthProvider"],
257
+ }),
258
+ ```
259
+
260
+ The 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.
261
+
262
+ **Custom configuration** (object form):
263
+
264
+ ```ts
265
+ auth: defineAuth("better-auth", {
266
+ plugins: {
267
+ oauthProvider: {
268
+ consentPage: "/consent", // path on ACCOUNT_URL — default
269
+ loginPage: "/login", // path on ACCOUNT_URL — default
270
+ allowDynamicClientRegistration: true, // default
271
+ allowUnauthenticatedClientRegistration: true, // default — MCP needs this
272
+ validAudiences: ["https://api.example.com"], // optional — defaults to BETTER_AUTH_URL
273
+ scopes: ["openid", "profile", "email", "offline_access"],
274
+ },
275
+ },
276
+ }),
277
+ ```
278
+
279
+ **Endpoints:**
280
+
281
+ Discovery (public, no auth):
282
+ - `GET /.well-known/oauth-authorization-server` — RFC 8414 metadata
283
+ - `GET /.well-known/oauth-protected-resource` — MCP resource metadata
284
+ - `GET /.well-known/openid-configuration` — OIDC discovery
285
+
286
+ Authorization flow:
287
+ - `POST /oauth2/register` — RFC 7591 dynamic client registration
288
+ - `POST /oauth2/authorize` — start auth code flow
289
+ - `POST /oauth2/token` — exchange code or refresh for access token
290
+ - `POST /oauth2/consent` — accept/deny (called by the consent page)
291
+ - `POST /oauth2/introspect` — RFC 7662 token validity check
292
+ - `POST /oauth2/revoke` — RFC 7009 token revocation
293
+ - `GET /oauth2/userinfo` — OIDC user info (requires `openid` scope)
294
+
295
+ Client management (authenticated):
296
+ - `GET /oauth2/get-clients`, `GET /oauth2/get-client?client_id=`, `GET /oauth2/public-client?client_id=`
297
+ - `POST /oauth2/create-client`, `POST /oauth2/update-client`, `POST /oauth2/delete-client`
298
+ - `POST /oauth2/client/rotate-secret`
299
+
300
+ Consent management:
301
+ - `GET /oauth2/get-consents`, `GET /oauth2/get-consent?id=`
302
+ - `POST /oauth2/update-consent`, `POST /oauth2/delete-consent`
303
+
304
+ **Account SPA wiring:**
305
+
306
+ The 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`.
307
+
308
+ **Verifying tokens in your own Workers / route handlers:**
309
+
310
+ Issued tokens are JWTs by default — verify them locally without a DB hit:
311
+
312
+ ```ts
313
+ import { createAuthClient } from "better-auth/client";
314
+ import { oauthProviderResourceClient } from "@better-auth/oauth-provider/resource-client";
315
+ import { auth } from "./auth";
316
+
317
+ const serverClient = createAuthClient({
318
+ plugins: [oauthProviderResourceClient(auth)],
319
+ });
320
+
321
+ const token = req.headers.get("authorization")?.replace("Bearer ", "");
322
+ const payload = await serverClient.verifyAccessToken(token, {
323
+ verifyOptions: { issuer: env.BETTER_AUTH_URL, audience: env.BETTER_AUTH_URL },
324
+ });
325
+ // payload.sub → userId, payload.scope → granted scopes
326
+ ```
327
+
328
+ **Why this and not the deprecated `mcp` plugin?**
329
+
330
+ Better 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.
331
+
332
+ Keep `apiKey` enabled alongside it — server-to-server flows (cron, scripts) want a static key; OAuth is for interactive clients.
333
+
334
+ ## Where This Runs
335
+
336
+ All Better Auth plugin routes are served under your auth base path:
337
+
338
+ ```
339
+ /auth/v1/*
340
+ ```
@@ -0,0 +1,155 @@
1
+ # Upgrade Anonymous Plugin
2
+
3
+ `@quickback-dev/better-auth-upgrade-anonymous` provides a single endpoint to convert anonymous users into full authenticated users. It flips the `isAnonymous` flag, optionally updates email and name, and refreshes the session — no re-authentication required.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @quickback-dev/better-auth-upgrade-anonymous
9
+ ```
10
+
11
+ ## Configuration
12
+
13
+ Enable both the `anonymous` and `upgradeAnonymous` plugins:
14
+
15
+ ```typescript
16
+ auth: defineAuth("better-auth", {
17
+ plugins: ["anonymous", "upgradeAnonymous"],
18
+ })
19
+ ```
20
+
21
+ The plugin accepts optional configuration:
22
+
23
+ ```typescript
24
+ import { upgradeAnonymous } from "@quickback-dev/better-auth-upgrade-anonymous";
25
+
26
+ upgradeAnonymous({
27
+ emailConfigured: true, // Whether email delivery is available
28
+ requireEmailVerification: true, // Whether to require email verification
29
+ })
30
+ ```
31
+
32
+ | Option | Default | Description |
33
+ |--------|---------|-------------|
34
+ | `emailConfigured` | `false` | When `true` and an email is provided, `emailVerified` is set based on `requireEmailVerification` |
35
+ | `requireEmailVerification` | `true` | When `true`, provided emails are marked unverified (requiring OTP). When `false`, emails are marked verified immediately |
36
+
37
+ > **Quickback Compiler**
38
+ >
39
+ > When using the Quickback compiler, these options are set automatically based on your SES environment variables. You don't need to configure them manually.
40
+
41
+
42
+ ## Endpoint
43
+
44
+ ```
45
+ POST /auth/v1/upgrade-anonymous
46
+ ```
47
+
48
+ ### Flow
49
+
50
+ 1. Validates the user's session (returns `401` if not authenticated)
51
+ 2. Checks if the user is already upgraded (returns success immediately if so)
52
+ 3. If an email is provided, checks for duplicates (returns `400` if email is taken)
53
+ 4. Updates `isAnonymous` to `false`, plus optional `email`, `name`, and `emailVerified` fields
54
+ 5. Refreshes the session cookie with the updated user object
55
+ 6. Returns the updated user, session, and `verificationRequired` flag
56
+
57
+ ### Request
58
+
59
+ The body is optional. When provided, it accepts:
60
+
61
+ | Field | Type | Description |
62
+ |-------|------|-------------|
63
+ | `email` | `string` (email) | Optional. Real email to replace the anonymous placeholder |
64
+ | `name` | `string` | Optional. User's display name |
65
+
66
+ ```bash
67
+ # Minimal — just upgrade, no email/name
68
+ curl -X POST https://api.example.com/auth/v1/upgrade-anonymous \
69
+ -H "Cookie: better-auth.session_token=..."
70
+
71
+ # With email and name
72
+ curl -X POST https://api.example.com/auth/v1/upgrade-anonymous \
73
+ -H "Cookie: better-auth.session_token=..." \
74
+ -H "Content-Type: application/json" \
75
+ -d '{"email": "jane@example.com", "name": "Jane"}'
76
+ ```
77
+
78
+ ### Response
79
+
80
+ ```json
81
+ {
82
+ "success": true,
83
+ "verificationRequired": true,
84
+ "user": {
85
+ "id": "usr_abc123",
86
+ "email": "jane@example.com",
87
+ "isAnonymous": false
88
+ },
89
+ "session": {
90
+ "id": "sess_xyz",
91
+ "userId": "usr_abc123"
92
+ }
93
+ }
94
+ ```
95
+
96
+ The `verificationRequired` field is `true` when all three conditions are met:
97
+ - An email was provided in the request body
98
+ - `emailConfigured` is `true` in plugin config
99
+ - `requireEmailVerification` is `true` in plugin config
100
+
101
+ When `verificationRequired` is `true`, the frontend should send a verification OTP and redirect the user to verify their email.
102
+
103
+ ## How It Works
104
+
105
+ The plugin is designed to be flexible:
106
+
107
+ - **Minimal by default** — With no body, only changes `isAnonymous` from `true` to `false`
108
+ - **Optional email/name** — Can update email and name in the same request
109
+ - **Duplicate protection** — Rejects emails already associated with another account
110
+ - **Verification-aware** — Returns `verificationRequired` so the frontend knows whether to trigger OTP
111
+ - **Session preserved** — Same session ID, no re-authentication needed
112
+ - **Idempotent** — Calling on an already-upgraded user returns success immediately
113
+
114
+ ## Typical Flows
115
+
116
+ ### Passkey Signup (no email)
117
+
118
+ 1. User creates anonymous session
119
+ 2. User registers a passkey
120
+ 3. App calls `POST /auth/v1/upgrade-anonymous` with no body
121
+ 4. User is now a full user with passkey auth — no email on file
122
+
123
+ ### Passkey Signup (with email)
124
+
125
+ 1. User creates anonymous session
126
+ 2. User registers a passkey
127
+ 3. User optionally enters email/name on the email collection step
128
+ 4. App calls `POST /auth/v1/upgrade-anonymous` with `{ email, name }`
129
+ 5. If `verificationRequired`: app sends OTP, user verifies, then redirects to dashboard
130
+ 6. Otherwise: user goes straight to dashboard
131
+
132
+ ### Email Signup
133
+
134
+ 1. User starts as anonymous (created via Better Auth's `anonymous` plugin)
135
+ 2. User provides email/password through your UI (via combo auth or signup)
136
+ 3. Your app calls `POST /auth/v1/upgrade-anonymous`
137
+ 4. User is now a full user with the same ID and all their data intact
138
+
139
+ ### Client Plugin
140
+
141
+ ```typescript
142
+ import { upgradeAnonymousClient } from "@quickback-dev/better-auth-upgrade-anonymous/client";
143
+
144
+ const authClient = createAuthClient({
145
+ plugins: [upgradeAnonymousClient()],
146
+ });
147
+
148
+ // Upgrade the current anonymous user
149
+ await authClient.upgradeAnonymous();
150
+ ```
151
+
152
+ ## See Also
153
+
154
+ - [Combo Auth Plugin](/stack/auth/plugins/combo-auth) — Combined magic link + OTP for collecting credentials
155
+ - [Auth Configuration](/compiler/config/providers) — Configuring auth plugins