@quickback-dev/cli 0.10.15 → 0.10.20

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 (249) 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.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -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
@@ -0,0 +1,455 @@
1
+ # Authentication Security
2
+
3
+ Quickback enforces secure authentication defaults out of the box. This page explains how cookie security, rate limiting, and cross-domain authentication work, plus how to configure them for your use case.
4
+
5
+ ## Cookie Security
6
+
7
+ Quickback sets secure cookie defaults to protect against CSRF, XSS, and man-in-the-middle attacks.
8
+
9
+ ### Default Attributes
10
+
11
+ ```ts
12
+ auth: defineAuth("better-auth", {
13
+ advanced: {
14
+ defaultCookieAttributes: {
15
+ sameSite: 'lax', // CSRF protection
16
+ secure: true, // HTTPS only
17
+ httpOnly: true, // No JavaScript access
18
+ }
19
+ }
20
+ })
21
+ ```
22
+
23
+ **What each attribute does:**
24
+
25
+ | Attribute | Value | Purpose |
26
+ |-----------|-------|---------|
27
+ | `sameSite` | `lax` | Blocks cookies on cross-site POST requests (CSRF protection) |
28
+ | `secure` | `true` | Cookies only sent over HTTPS (prevents interception) |
29
+ | `httpOnly` | `true` | JavaScript cannot access cookies via `document.cookie` (XSS mitigation) |
30
+
31
+ ### SameSite Options
32
+
33
+ - **`lax` (recommended)**: Blocks cross-site POST requests but allows top-level navigation. Best balance of security and usability.
34
+ - **`strict`**: Blocks cookies on all cross-site requests. More secure but may break legitimate flows (e.g., returning from payment provider).
35
+ - **`none`**: Allows all cross-site requests. Required for cross-domain authentication (requires `secure: true`).
36
+
37
+ ### Development Override
38
+
39
+ For local development over HTTP, you can relax the `secure` flag:
40
+
41
+ ```ts
42
+ auth: defineAuth("better-auth", {
43
+ advanced: {
44
+ defaultCookieAttributes: {
45
+ sameSite: 'lax',
46
+ secure: process.env.NODE_ENV === 'production',
47
+ httpOnly: true,
48
+ }
49
+ }
50
+ })
51
+ ```
52
+
53
+ **Warning**: Never use `secure: false` in production.
54
+
55
+ ---
56
+
57
+ ## Rate Limiting
58
+
59
+ Quickback includes per-IP rate limiting by default to protect against brute-force attacks and abuse.
60
+
61
+ ### How It Works
62
+
63
+ **Rate limits are applied per IP address**, not globally:
64
+
65
+ ```
66
+ ┌─────────────────────────────────────────────────┐
67
+ │ IP: 192.168.1.1 │
68
+ │ Endpoint: /sign-in/email │
69
+ │ Limit: 10 requests per 60 seconds │
70
+ │ │
71
+ │ Request 1-10: ✅ Allowed │
72
+ │ Request 11: ❌ 429 Too Many Requests │
73
+ │ After 60s: Counter resets to 0 │
74
+ └─────────────────────────────────────────────────┘
75
+
76
+ ┌─────────────────────────────────────────────────┐
77
+ │ IP: 192.168.1.2 (different IP) │
78
+ │ Endpoint: /sign-in/email │
79
+ │ Independent counter: Not affected by 1.1 │
80
+ │ Starts at 0 │
81
+ └─────────────────────────────────────────────────┘
82
+ ```
83
+
84
+ ### Default Configuration
85
+
86
+ ```ts
87
+ auth: defineAuth("better-auth", {
88
+ rateLimit: {
89
+ enabled: true,
90
+ window: 60, // 60 second window
91
+ max: 100, // 100 requests per IP per window
92
+ customRules: {
93
+ "/sign-in/email": { window: 60, max: 10 },
94
+ "/sign-in/social": { window: 60, max: 10 },
95
+ "/device/init": { window: 60, max: 5 },
96
+ "/device/poll": { window: 60, max: 30 },
97
+ "/device/token": { window: 60, max: 10 },
98
+ }
99
+ }
100
+ })
101
+ ```
102
+
103
+ ### Custom Rules by Endpoint
104
+
105
+ Set different limits based on endpoint sensitivity:
106
+
107
+ | Endpoint Type | Recommended Limit | Reasoning |
108
+ |---------------|-------------------|-----------|
109
+ | Sign-in | 10/min per IP | Prevent credential stuffing |
110
+ | Device codes | 5/min per IP | Prevent device code enumeration |
111
+ | Token exchange | 10/min per IP | Prevent token brute-force |
112
+ | Polling | 30/min per IP | Allow reasonable polling (every 2s) |
113
+ | General API | 100/min per IP | Balance abuse prevention and usability |
114
+
115
+ ### Why Per-IP?
116
+
117
+ ✅ **Per-IP** (what Quickback uses):
118
+ - Prevents single attacker from brute-forcing
119
+ - Doesn't penalize legitimate users when one IP is malicious
120
+ - Standard for auth endpoints
121
+
122
+ ❌ **Global total** (not used):
123
+ - Would allow distributed attacks to succeed
124
+ - One attacker with many IPs could exhaust the limit for everyone
125
+ - Not effective for security
126
+
127
+ ### Disabling Rate Limiting
128
+
129
+ Not recommended, but you can disable for testing:
130
+
131
+ ```ts
132
+ rateLimit: {
133
+ enabled: process.env.NODE_ENV === 'production',
134
+ window: 60,
135
+ max: 1000, // Higher limit for development
136
+ }
137
+ ```
138
+
139
+ ---
140
+
141
+ ## Cross-Domain Authentication
142
+
143
+ For applications spanning multiple subdomains (e.g., `account.example.com`, `api.example.com`, `dashboard.example.com`), Quickback provides dual-layer security.
144
+
145
+ ### The Problem
146
+
147
+ Browsers restrict cookies to exact domains by default. If your auth API is at `api.example.com`, cookies won't be sent to `dashboard.example.com`.
148
+
149
+ ### The Solution: Dual-Layer Protection
150
+
151
+ Quickback uses two complementary security layers:
152
+
153
+ #### 1. Cookie Domain (Browser-Level)
154
+
155
+ ```ts
156
+ auth: defineAuth("better-auth", {
157
+ advanced: {
158
+ crossSubDomainCookies: {
159
+ enabled: true,
160
+ domain: 'example.com' // All *.example.com can access cookies
161
+ }
162
+ }
163
+ })
164
+ ```
165
+
166
+ **Behavior**: Allows ALL subdomains to access the cookie (browser limitation per RFC 6265)
167
+ - Cannot selectively allow only specific subdomains
168
+ - All-or-nothing: either exact domain only, or all subdomains
169
+
170
+ #### 2. Trusted Origins (Application-Level)
171
+
172
+ ```ts
173
+ auth: defineAuth("better-auth", {
174
+ trustedOrigins: [
175
+ 'https://account.example.com',
176
+ 'https://api.example.com',
177
+ 'https://dashboard.example.com'
178
+ ]
179
+ })
180
+ ```
181
+
182
+ **Behavior**: Better Auth validates request origins before processing auth operations
183
+ - Granular whitelist of allowed origins
184
+ - Blocks requests from untrusted subdomains even if they have the cookie
185
+ - Prevents CSRF and unauthorized auth operations
186
+
187
+ ### Security Model
188
+
189
+ ```
190
+ ┌─────────────────────────────────────────────────┐
191
+ │ Subdomain: evil.example.com │
192
+ │ Has Cookie: ✓ (via crossSubDomainCookies) │
193
+ │ In trustedOrigins: ✗ │
194
+ │ Result: REQUEST BLOCKED by Better Auth │
195
+ └─────────────────────────────────────────────────┘
196
+
197
+ ┌─────────────────────────────────────────────────┐
198
+ │ Subdomain: account.example.com │
199
+ │ Has Cookie: ✓ (via crossSubDomainCookies) │
200
+ │ In trustedOrigins: ✓ │
201
+ │ Result: REQUEST ALLOWED │
202
+ └─────────────────────────────────────────────────┘
203
+ ```
204
+
205
+ ### Full Cross-Domain Configuration
206
+
207
+ ```ts
208
+ import { defineAuth, defineConfig, defineDatabase, defineRuntime } from "@quickback/compiler";
209
+
210
+ export default defineConfig({
211
+ name: "my-saas",
212
+ providers: {
213
+ runtime: defineRuntime("cloudflare"),
214
+ database: defineDatabase("cloudflare-d1", {
215
+ vars: {
216
+ ACCOUNT_URL: "https://account.example.com",
217
+ BETTER_AUTH_URL: "https://api.example.com",
218
+ }
219
+ }),
220
+ auth: defineAuth("better-auth", {
221
+ emailAndPassword: { enabled: true },
222
+ plugins: ["organization"],
223
+
224
+ // Trusted origins (granular whitelist)
225
+ trustedOrigins: [
226
+ "https://account.example.com",
227
+ "https://api.example.com",
228
+ "https://dashboard.example.com",
229
+ "http://localhost:3000", // Development
230
+ ],
231
+
232
+ // Cookie configuration
233
+ advanced: {
234
+ crossSubDomainCookies: {
235
+ enabled: true,
236
+ domain: "example.com",
237
+ },
238
+ defaultCookieAttributes: {
239
+ secure: true,
240
+ sameSite: "none", // Required for cross-domain
241
+ httpOnly: true,
242
+ }
243
+ }
244
+ })
245
+ }
246
+ })
247
+ ```
248
+
249
+ **Important**: When using `sameSite: "none"`, you must also set `secure: true`. This is required by browsers.
250
+
251
+ ---
252
+
253
+ ## Environment Variables
254
+
255
+ Set these in your Cloudflare Workers environment or `.env` file:
256
+
257
+ ### Required
258
+
259
+ ```bash
260
+ # Better Auth secret (minimum 32 characters)
261
+ BETTER_AUTH_SECRET=your-secret-key-min-32-chars
262
+
263
+ # Base URL for Better Auth endpoints
264
+ BETTER_AUTH_URL=https://api.example.com
265
+ ```
266
+
267
+ ### Optional (Cross-Domain)
268
+
269
+ ```bash
270
+ # Enable cross-subdomain cookies
271
+ CROSS_SUBDOMAIN_COOKIES=true
272
+ COOKIE_DOMAIN=example.com
273
+
274
+ # Trusted origins (comma-separated)
275
+ TRUSTED_ORIGINS=https://account.example.com,https://api.example.com
276
+
277
+ # CORS allowed origins (typically matches trustedOrigins)
278
+ ALLOWED_ORIGINS=https://account.example.com,https://api.example.com
279
+ ```
280
+
281
+ ### Setting Secrets with Wrangler
282
+
283
+ For sensitive values like `BETTER_AUTH_SECRET`:
284
+
285
+ ```bash
286
+ wrangler secret put BETTER_AUTH_SECRET
287
+ # Paste your secret when prompted
288
+ ```
289
+
290
+ For non-secret vars, add to `wrangler.toml`:
291
+
292
+ ```toml
293
+ [vars]
294
+ BETTER_AUTH_URL = "https://api.example.com"
295
+ CROSS_SUBDOMAIN_COOKIES = "false"
296
+ ```
297
+
298
+ ---
299
+
300
+ ## Security Best Practices
301
+
302
+ ### Single Domain (Recommended)
303
+
304
+ For most applications, use exact domain cookies:
305
+
306
+ ```ts
307
+ auth: defineAuth("better-auth", {
308
+ trustedOrigins: ["https://app.example.com"],
309
+ advanced: {
310
+ crossSubDomainCookies: {
311
+ enabled: false // Default: exact domain only
312
+ },
313
+ defaultCookieAttributes: {
314
+ sameSite: 'lax',
315
+ secure: true,
316
+ httpOnly: true,
317
+ }
318
+ }
319
+ })
320
+ ```
321
+
322
+ **Benefits**:
323
+ - Maximum security (smallest cookie scope)
324
+ - No cross-subdomain attack surface
325
+ - Simpler configuration
326
+
327
+ ### Multi-Subdomain (When Needed)
328
+
329
+ Only enable cross-subdomain cookies if you need SSO across multiple subdomains:
330
+
331
+ ```ts
332
+ auth: defineAuth("better-auth", {
333
+ trustedOrigins: [
334
+ "https://account.example.com",
335
+ "https://dashboard.example.com",
336
+ ],
337
+ advanced: {
338
+ crossSubDomainCookies: {
339
+ enabled: true,
340
+ domain: "example.com",
341
+ },
342
+ defaultCookieAttributes: {
343
+ sameSite: 'none', // Required for cross-domain
344
+ secure: true,
345
+ httpOnly: true,
346
+ }
347
+ }
348
+ })
349
+ ```
350
+
351
+ **Security requirements**:
352
+ - Trust all subdomains equally (any compromised subdomain can steal cookies)
353
+ - Use separate root domains for untrusted services
354
+ - Always set `trustedOrigins` for granular control
355
+
356
+ ### CORS vs Trusted Origins
357
+
358
+ These serve different purposes and should typically match:
359
+
360
+ | Setting | Purpose |
361
+ |---------|---------|
362
+ | `ALLOWED_ORIGINS` (CORS) | Controls which origins can make credentialed requests |
363
+ | `trustedOrigins` (Better Auth) | Validates origins for auth operations + prevents open redirects |
364
+
365
+ **Example**:
366
+
367
+ ```ts
368
+ database: defineDatabase("cloudflare-d1", {
369
+ vars: {
370
+ ALLOWED_ORIGINS: "https://account.example.com,https://api.example.com"
371
+ }
372
+ }),
373
+ auth: defineAuth("better-auth", {
374
+ trustedOrigins: [
375
+ "https://account.example.com",
376
+ "https://api.example.com"
377
+ ]
378
+ })
379
+ ```
380
+
381
+ ### Checklist
382
+
383
+ Before deploying to production:
384
+
385
+ - [ ] `BETTER_AUTH_SECRET` is set (minimum 32 random characters)
386
+ - [ ] `secure: true` is enabled (HTTPS only)
387
+ - [ ] `httpOnly: true` is enabled (XSS protection)
388
+ - [ ] `sameSite: 'lax'` or `'strict'` unless cross-domain required
389
+ - [ ] `trustedOrigins` includes only your domains
390
+ - [ ] `ALLOWED_ORIGINS` matches `trustedOrigins`
391
+ - [ ] Rate limiting is enabled (`rateLimit.enabled: true`)
392
+ - [ ] Custom rate limits set for sensitive endpoints
393
+
394
+ ---
395
+
396
+ ## Deployment Considerations
397
+
398
+ ### Behind Proxy/Load Balancer
399
+
400
+ If your app is behind a proxy, ensure IP address headers are trusted:
401
+
402
+ ```ts
403
+ auth: defineAuth("better-auth", {
404
+ autoDetectIpAddress: true, // Uses X-Forwarded-For or CF-Connecting-IP
405
+ })
406
+ ```
407
+
408
+ **Cloudflare Workers**: IP automatically available via `CF-Connecting-IP` header
409
+
410
+ **Other proxies**: Configure to trust `X-Forwarded-For` or `X-Real-IP`
411
+
412
+ ### Multiple Environments
413
+
414
+ Use environment variables to configure different settings per environment:
415
+
416
+ ```ts
417
+ auth: defineAuth("better-auth", {
418
+ trustedOrigins: process.env.TRUSTED_ORIGINS?.split(',') || [],
419
+ advanced: {
420
+ crossSubDomainCookies: {
421
+ enabled: process.env.CROSS_SUBDOMAIN_COOKIES === 'true',
422
+ domain: process.env.COOKIE_DOMAIN,
423
+ },
424
+ defaultCookieAttributes: {
425
+ sameSite: process.env.COOKIE_SAMESITE || 'lax',
426
+ secure: process.env.NODE_ENV === 'production',
427
+ httpOnly: true,
428
+ }
429
+ }
430
+ })
431
+ ```
432
+
433
+ **Development** (`.dev.vars`):
434
+ ```bash
435
+ TRUSTED_ORIGINS=http://localhost:3000,http://localhost:5173
436
+ CROSS_SUBDOMAIN_COOKIES=false
437
+ COOKIE_SAMESITE=lax
438
+ ```
439
+
440
+ **Production** (Wrangler secrets):
441
+ ```bash
442
+ TRUSTED_ORIGINS=https://account.example.com,https://api.example.com
443
+ CROSS_SUBDOMAIN_COOKIES=true
444
+ COOKIE_DOMAIN=example.com
445
+ COOKIE_SAMESITE=none
446
+ ```
447
+
448
+ ---
449
+
450
+ ## Further Reading
451
+
452
+ - [Better Auth: Cookies Documentation](https://www.better-auth.com/docs/concepts/cookies)
453
+ - [Better Auth: Security Guide](https://www.better-auth.com/docs/reference/security)
454
+ - [OWASP: Cross-Site Request Forgery Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
455
+ - [MDN: SameSite Cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
@@ -0,0 +1,39 @@
1
+ # Using Auth
2
+
3
+ This page covers how to use Better Auth in your Quickback Stack application — sign-in flows, session management, and working with organization context.
4
+
5
+ ## Sign-In Flows
6
+
7
+ Better Auth supports multiple sign-in methods:
8
+
9
+ - **Email/Password** — Traditional credential-based authentication
10
+ - **Email OTP** — One-time passwords sent via email
11
+ - **Magic Links** — Passwordless email links
12
+ - **Passkeys** — WebAuthn biometric/hardware key authentication
13
+
14
+ ## Session Handling
15
+
16
+ Sessions are stored in Cloudflare KV for fast edge-based lookups.
17
+
18
+ ```typescript
19
+ // Access the current session in a Hono route
20
+ app.get('/api/me', async (c) => {
21
+ const session = c.get('session');
22
+ const user = c.get('user');
23
+ return c.json({ user, session });
24
+ });
25
+ ```
26
+
27
+ ## Organization Context
28
+
29
+ When organizations are enabled, the current organization is available in the request context:
30
+
31
+ ```typescript
32
+ const orgId = c.get('session')?.activeOrganizationId;
33
+ ```
34
+
35
+ ## Related
36
+
37
+ - [Auth Overview](/stack/auth) — Setup and configuration
38
+ - [Auth Plugins](/stack/auth/plugins) — Available plugins
39
+ - [Auth Security](/stack/auth/security) — Security best practices