@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,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
@@ -0,0 +1,199 @@
1
+ # Actions
2
+
3
+ Actions are custom operations defined in your feature files (e.g., `approve`, `void`, `post`, `applyPayment`). The CMS renders them as clickable buttons with auto-generated input forms — no UI code required.
4
+
5
+ ## Where Actions Appear
6
+
7
+ Actions show up in two places:
8
+
9
+ ### Row Action Menu (Table Mode)
10
+
11
+ In Table mode, the three-dot menu on each row includes a section for custom actions. Actions are separated from standard operations (view, edit, delete) by a divider.
12
+
13
+ ### Action Bar (Detail View)
14
+
15
+ In the record detail view, an "Actions" card displays all available actions as buttons. Each button shows the action name, and hovering reveals the description as a tooltip.
16
+
17
+ ## Action Dialog
18
+
19
+ Clicking an action opens a modal dialog with:
20
+
21
+ 1. **Header** — Action name with an icon (lightning bolt for standard, warning triangle for destructive, download for file responses)
22
+ 2. **Description** — The action's description text
23
+ 3. **Side effects warning** — If the action has `sideEffects: "sync"`, an amber warning banner appears: "This action has synchronous side effects (e.g., GL entries)."
24
+ 4. **Confirmation step** — If the action has `cms.confirm`, a confirmation message appears before the input form
25
+ 5. **Input fields** — Auto-generated from the action's `inputFields` schema
26
+ 6. **Execute button** — Submits the action. Shows "Executing..." while in progress.
27
+ 7. **Cancel button** — Closes the dialog without executing
28
+
29
+ ### Input Field Types
30
+
31
+ The dialog generates the appropriate input control for each field:
32
+
33
+ | Zod Type | Input Control | Notes |
34
+ |----------|--------------|-------|
35
+ | `string` | Text input | Free-text entry |
36
+ | `number` | Number input | Step 0.01, supports decimals |
37
+ | `boolean` | Checkbox | With label text |
38
+ | `array<string>` | Text input | Comma-separated values, split on save |
39
+
40
+ Required fields are marked with a red asterisk. Default values from the schema are pre-filled.
41
+
42
+ ### Example
43
+
44
+ Given this action definition:
45
+
46
+ ```typescript
47
+ actions: {
48
+ applyPayment: {
49
+ description: "Apply a payment to this invoice",
50
+ input: 'z.object({ amount: z.number(), reference: z.string().optional() })',
51
+ access: {
52
+ roles: ['admin', 'owner'],
53
+ record: { status: { equals: 'posted' } },
54
+ },
55
+ sideEffects: "sync",
56
+ cms: {
57
+ label: "Apply Payment",
58
+ icon: "dollar-sign",
59
+ confirm: "This will create GL entries. Continue?",
60
+ category: "payments",
61
+ successMessage: "Payment applied successfully",
62
+ order: 1,
63
+ },
64
+ },
65
+ }
66
+ ```
67
+
68
+ The CMS renders a dialog with:
69
+
70
+ - A number input for `amount` (required)
71
+ - A text input for `reference` (optional)
72
+ - A sync side effects warning
73
+ - A confirmation step with the custom message
74
+ - Only visible to admins and owners
75
+ - Only visible on records where `status === "posted"`
76
+
77
+ ## Access Filtering
78
+
79
+ Actions are filtered based on two criteria:
80
+
81
+ ### Role Check
82
+
83
+ The action's `access.roles` array is compared against the current user's role. If the user's role is not in the list, the action is hidden.
84
+
85
+ ### Record Condition
86
+
87
+ The action's `access.record` conditions are evaluated against the current record's data. Supported conditions:
88
+
89
+ | Operator | Example | Meaning |
90
+ |----------|---------|---------|
91
+ | `equals` | `{ status: { equals: 'pending' } }` | Field must equal value |
92
+ | `notEquals` | `{ status: { notEquals: 'void' } }` | Field must not equal value |
93
+ | `in` | `{ status: { in: ['pending', 'draft'] } }` | Field must be one of values |
94
+
95
+ All conditions must pass for the action to be visible. This means "approve" actions naturally disappear after a record is approved, and "void" actions only appear on voidable records.
96
+
97
+ ## CMS Metadata
98
+
99
+ Actions can include an optional `cms` property for enhanced CMS rendering. Actions without `cms` render with default behavior.
100
+
101
+ | Property | Type | Default | Purpose |
102
+ |----------|------|---------|---------|
103
+ | `label` | `string` | camelCase split | Display name override |
104
+ | `icon` | `string` | `"zap"` | Lucide icon name |
105
+ | `confirm` | `string \| boolean` | `false` | `true` = generic confirm, string = custom message |
106
+ | `destructive` | `boolean` | `false` | Red styling + requires confirmation |
107
+ | `category` | `string` | none | Group actions under a header |
108
+ | `hidden` | `boolean` | `false` | Hide from CMS entirely (API-only actions) |
109
+ | `successMessage` | `string` | none | Toast message after success |
110
+ | `onSuccess` | `"refresh" \| "redirect:list" \| "close"` | `"refresh"` | Behavior after successful execution |
111
+ | `order` | `number` | `0` | Sort priority (lower = first) |
112
+
113
+ ### Example with CMS metadata
114
+
115
+ ```typescript
116
+ // features/invoices/actions/post.ts
117
+ import { z } from "zod";
118
+ import { defineAction } from "../.quickback/define-action";
119
+
120
+ export default defineAction({
121
+ description: "Post this invoice to accounts receivable",
122
+ input: z.object({}),
123
+ access: { roles: ["owner", "admin"], record: { status: { equals: "draft" } } },
124
+ sideEffects: "sync",
125
+ cms: {
126
+ label: "Post Invoice",
127
+ icon: "send",
128
+ confirm: "This will post the invoice to AR and create GL entries. Continue?",
129
+ category: "lifecycle",
130
+ successMessage: "Invoice posted successfully",
131
+ onSuccess: "refresh",
132
+ order: 1,
133
+ },
134
+ async execute({ db, record }) {
135
+ // ... post invoice
136
+ return { ok: true };
137
+ },
138
+ });
139
+ ```
140
+
141
+ ### Hiding API-only actions
142
+
143
+ ```typescript
144
+ // features/invoices/actions/internal-recalc.ts
145
+ import { z } from "zod";
146
+ import { defineAction } from "../.quickback/define-action";
147
+
148
+ export default defineAction({
149
+ description: "Recalculate internal totals",
150
+ input: z.object({}),
151
+ access: { roles: ["owner"] },
152
+ cms: { hidden: true }, // Never shown in CMS
153
+ async execute({ db, record }) {
154
+ // ... recalc totals
155
+ return { ok: true };
156
+ },
157
+ });
158
+ ```
159
+
160
+ ## Destructive Actions
161
+
162
+ Actions are styled as destructive when either:
163
+
164
+ - The action's `cms.destructive` is `true`
165
+ - The action is named `void` or `delete` (legacy fallback)
166
+
167
+ Destructive actions receive:
168
+
169
+ - **Red text** in the row action menu
170
+ - **Warning triangle icon** (unless overridden by `cms.icon`)
171
+ - **Red execute button** in the dialog (using `bg-destructive` styling)
172
+ - **Automatic confirmation step** (unless `cms.confirm` is explicitly `false`)
173
+
174
+ This provides a visual cue that the action has permanent consequences.
175
+
176
+ ## Standalone Actions
177
+
178
+ Actions with `path:` set are standalone — not tied to a specific record. They appear in a separate section and don't receive a `recordId` when executed. The CMS passes `null` as the record ID for standalone actions.
179
+
180
+ ## File Response Actions
181
+
182
+ Actions with `responseType: "file"` show a download icon instead of the lightning bolt. When executed, the response is treated as a file download rather than a JSON result.
183
+
184
+ ## Execution Flow
185
+
186
+ 1. User clicks action in row menu or action bar
187
+ 2. Dialog opens with description, inputs, and warnings
188
+ 3. If `cms.confirm` is set, user sees confirmation step first
189
+ 4. User fills in required fields
190
+ 5. User clicks "Execute" (or "Confirm" after confirmation step)
191
+ 6. CMS calls `client.executeAction(table, actionName, recordId, input)`
192
+ 7. On success: `cms.successMessage` shown as toast (if set), then `cms.onSuccess` behavior
193
+ 8. On error: error message displayed in dialog
194
+
195
+ ## Next Steps
196
+
197
+ - **[Security](/stack/cms/security)** — Access conditions and role-based access
198
+ - **[Table Views](/stack/cms/table-views)** — Where actions appear in the UI
199
+ - **[Schema Format Reference](/stack/cms/schema-format)** — ActionMeta type definition