@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,245 @@
1
+ # JWT Optimization
2
+
3
+ Quickback automatically optimizes authenticated API requests using JWT tokens. After the first request (which uses session cookies), subsequent requests skip the database entirely by sending a signed JWT that encodes the full auth context.
4
+
5
+ ## How It Works
6
+
7
+ ### Request Flow
8
+
9
+ ```
10
+ First request (no JWT cached):
11
+ Browser → Cookie auth → 2 DB queries → Response + set-auth-token header
12
+ Browser caches JWT in localStorage
13
+
14
+ Subsequent requests (JWT cached):
15
+ Browser → Bearer JWT → Signature check only → Response (0 DB queries)
16
+ ```
17
+
18
+ ### What's in the JWT
19
+
20
+ The JWT encodes everything needed for auth middleware:
21
+
22
+ | Claim | Description |
23
+ |-------|-------------|
24
+ | `sub` | User ID |
25
+ | `orgId` | Active organization ID |
26
+ | `role` | Organization membership role (`owner`, `admin`, `member`) |
27
+ | `userRole` | Global user role (when admin panel is enabled) |
28
+ | `email` | User email |
29
+ | `name` | User display name |
30
+ | `iat` | Issued-at timestamp |
31
+ | `exp` | Expiry (15 minutes from issue) |
32
+
33
+ ### Signing
34
+
35
+ JWTs are signed with HMAC-SHA256 using your `BETTER_AUTH_SECRET`. No additional configuration is needed — this uses the same secret you already set for Better Auth.
36
+
37
+ ---
38
+
39
+ ## Server-Side Validation
40
+
41
+ **Every authenticated API request is validated server-side before it reaches your handler.** There is no "trust the client" shortcut — the middleware runs full signature verification on each request.
42
+
43
+ Validation steps (in generated `src/middleware/auth.ts`):
44
+
45
+ 1. Extract the `Authorization: Bearer <token>` header
46
+ 2. Call `verifyJwt(token, BETTER_AUTH_SECRET)` from `src/lib/jwt.ts`
47
+ 3. Decode header + payload, recompute the HMAC-SHA256 signature, and compare via `crypto.subtle.verify()` (constant-time — no timing-attack surface)
48
+ 4. Check `exp` against the current time
49
+ 5. On success: hydrate `AppContext` from claims (`sub`, `orgId`, `role`, `userRole`, `email`, `name`) — no DB query
50
+ 6. On failure (bad signature, expired, malformed): **silently fall back** to Better Auth's session cookie auth; if that succeeds, mint a fresh JWT and return it in the `set-auth-token` response header
51
+
52
+ The Files worker (R2 uploads) performs the same verification using the shared secret — no network round-trip to the auth API for file operations.
53
+
54
+ ---
55
+
56
+ ## Token Lifecycle
57
+
58
+ ### Automatic Minting
59
+
60
+ When a request arrives without a JWT (or with an expired one), the auth middleware:
61
+
62
+ 1. Authenticates via session cookie (existing Better Auth flow)
63
+ 2. Signs a JWT with the full auth context
64
+ 3. Returns it in the `set-auth-token` response header
65
+
66
+ The Quickback API client (`quickback-client.ts`) automatically captures this header and stores the JWT in `localStorage`.
67
+
68
+ ### Re-minting on Org Switch
69
+
70
+ When a user switches organizations, the JWT must be re-minted because `orgId` and `role` change. The auth UI handles this automatically:
71
+
72
+ ```typescript
73
+ // This happens automatically in the org switcher
74
+ await authClient.organization.setActive({ organizationSlug: slug });
75
+
76
+ // Fetch fresh JWT with new org context
77
+ const res = await fetch('/api/v1/token', {
78
+ method: 'POST',
79
+ credentials: 'include',
80
+ });
81
+ const { token } = await res.json();
82
+ localStorage.setItem('bearer_token', token);
83
+ ```
84
+
85
+ ### Invalidation on Role Changes
86
+
87
+ When an admin changes a user's role or removes them from an organization, the server broadcasts an `auth:token-invalidated` event via WebSocket. The client automatically clears the cached JWT, forcing the next request to fall back to session auth and mint a fresh token.
88
+
89
+ ```
90
+ Admin changes user role
91
+ → databaseHooks fires on member update
92
+ → Broadcasts auth:token-invalidated via realtime
93
+ → Client clears localStorage JWT
94
+ → Next request uses session cookie → gets fresh JWT
95
+ ```
96
+
97
+ ### Expiry
98
+
99
+ JWTs expire after 15 minutes. This is a safety net — in practice, JWTs are re-minted well before expiry through the `set-auth-token` response header on session-fallback requests.
100
+
101
+ When a JWT expires or is invalid:
102
+ 1. The middleware silently falls back to session cookie auth
103
+ 2. A fresh JWT is minted and returned in the response header
104
+ 3. The client stores the new JWT for subsequent requests
105
+
106
+ ---
107
+
108
+ ## Token Endpoint
109
+
110
+ `POST /api/v1/token` mints a fresh JWT from the current session. This endpoint goes through normal auth middleware, so the user must have a valid session cookie.
111
+
112
+ **Request:**
113
+ ```bash
114
+ curl -X POST https://your-api.example.com/api/v1/token \
115
+ -H "Content-Type: application/json" \
116
+ --cookie "better-auth.session_token=..."
117
+ ```
118
+
119
+ **Response:**
120
+ ```json
121
+ {
122
+ "token": "eyJhbGciOiJIUzI1NiJ9..."
123
+ }
124
+ ```
125
+
126
+ Use this endpoint after operations that change auth context (like switching organizations) to get a JWT that reflects the new state.
127
+
128
+ ---
129
+
130
+ ## Client Integration
131
+
132
+ ### Quickback API Client
133
+
134
+ The `quickback-client.ts` API client handles JWT auth automatically:
135
+
136
+ - **Sends** the cached JWT as `Authorization: Bearer <token>` on every request
137
+ - **Captures** refreshed JWTs from `set-auth-token` response headers
138
+ - **Clears** the JWT on `401` responses (falls back to session cookie)
139
+
140
+ No additional client configuration is needed.
141
+
142
+ ### Custom API Calls
143
+
144
+ If you make direct `fetch()` calls to your API (outside the Quickback client), include the JWT:
145
+
146
+ ```typescript
147
+ const jwt = localStorage.getItem('bearer_token');
148
+
149
+ const res = await fetch('https://your-api.example.com/api/v1/things', {
150
+ headers: {
151
+ 'Authorization': `Bearer ${jwt}`,
152
+ 'Content-Type': 'application/json',
153
+ },
154
+ credentials: 'include', // Fallback to session cookie if no JWT
155
+ });
156
+
157
+ // Capture refreshed token
158
+ const newToken = res.headers.get('set-auth-token');
159
+ if (newToken) {
160
+ localStorage.setItem('bearer_token', newToken);
161
+ }
162
+ ```
163
+
164
+ ### Sign Out
165
+
166
+ Clear the JWT on sign-out to prevent stale tokens:
167
+
168
+ ```typescript
169
+ localStorage.removeItem('bearer_token');
170
+ await authClient.signOut();
171
+ ```
172
+
173
+ ---
174
+
175
+ ## Security
176
+
177
+ ### Threat Model
178
+
179
+ | Threat | Mitigation |
180
+ |--------|------------|
181
+ | Token theft (XSS) | 15-minute expiry limits exposure window. `httpOnly` cookies protect the session. |
182
+ | Token replay | Short expiry + `set-auth-token` rotation on session fallback |
183
+ | Stale permissions | WebSocket `auth:token-invalidated` broadcast on role changes |
184
+ | Token forgery | HMAC-SHA256 signature verified with `BETTER_AUTH_SECRET` |
185
+ | Timing attacks | `crypto.subtle.verify()` provides constant-time comparison |
186
+
187
+ ### Key Points
188
+
189
+ - JWTs are a **performance optimization**, not a replacement for session auth
190
+ - Session cookies remain the source of truth — JWTs are derived from them
191
+ - If a JWT is lost, stolen, or cleared, the system gracefully falls back to cookie auth
192
+ - No additional secrets or configuration needed — uses your existing `BETTER_AUTH_SECRET`
193
+ - The JWT contains no sensitive data beyond what's already in the auth context
194
+
195
+ ---
196
+
197
+ ## Files Worker
198
+
199
+ The files worker (for Cloudflare R2 file uploads) also supports JWT authentication. When a request includes a JWT `Authorization` header, the worker verifies it directly instead of calling back to the auth API — eliminating a network round-trip for file operations.
200
+
201
+ ---
202
+
203
+ ## Relation to Better Auth's JWT Plugin
204
+
205
+ Quickback's JWT fast-path (documented above) is a **custom HMAC-SHA256 implementation**, separate from Better Auth's [`jwt` plugin](https://www.better-auth.com/docs/plugins/jwt). The distinction matters if you're comparing options.
206
+
207
+ ### What Quickback ships by default
208
+
209
+ - Custom HMAC-SHA256 JWTs minted by the compiled API at `POST /api/v1/token`
210
+ - Payload includes `sub`, `orgId`, `role`, `userRole`, `email`, `name` — everything the middleware needs to reconstruct `AppContext` with zero DB queries
211
+ - Signed with `BETTER_AUTH_SECRET`
212
+ - Used by the generated auth middleware as a fast-path ahead of `getSession()`
213
+
214
+ ### What Better Auth's JWT plugin gives you (opt-in)
215
+
216
+ Enable it with `plugins: ["jwt"]` in your auth config:
217
+
218
+ ```ts
219
+ auth: defineAuth("better-auth", {
220
+ plugins: ["jwt"],
221
+ }),
222
+ ```
223
+
224
+ You get:
225
+ - JWKS endpoint at `/auth/v1/jwks` for asymmetric public-key verification by external services
226
+ - BA's own `/auth/v1/token` endpoint (asymmetric-signed, EdDSA by default)
227
+ - Standard OIDC-style claims via BA's `definePayload` hook
228
+
229
+ ### Why Quickback doesn't use BA's plugin internally
230
+
231
+ Better Auth's `definePayload` hook only receives `{ user }`. It cannot embed the active organization context (`orgId`, org-member `role`) that Quickback's Firewall and Access layers need. Without that context in the JWT, the middleware would have to do a DB lookup per request — defeating the whole point of the fast-path.
232
+
233
+ ### When to enable BA's JWT plugin anyway
234
+
235
+ Turn it on if **external services** need to verify tokens without sharing `BETTER_AUTH_SECRET` — e.g. a third-party worker that wants to confirm a user's identity via JWKS. The BA-issued tokens won't have Quickback's org context, so they're useful for identity assertions, not for hitting the Quickback API directly.
236
+
237
+ Enabling BA's plugin does **not** change how the compiled API authenticates requests — the middleware keeps using the custom HMAC JWT regardless.
238
+
239
+ ---
240
+
241
+ ## Related
242
+
243
+ - [Auth Overview](/stack/auth) — Setup and configuration
244
+ - [Auth Security](/stack/auth/security) — Cookie security, rate limiting, CORS
245
+ - [API Keys](/stack/auth/api-keys) — Programmatic API access
@@ -0,0 +1,127 @@
1
+ # AWS SES Plugin
2
+
3
+ `@quickback-dev/better-auth-aws-ses` is a Better Auth plugin that sends transactional emails via AWS SES. It handles AWS Signature V4 signing, HTML/text email templates, and rate limiting — designed to work in Cloudflare Workers (no Node.js `aws-sdk` dependency).
4
+
5
+ > **Cloudflare Email is the default.** As of the Cloudflare Email Sending public beta, the zero-config `send_email` binding is Quickback's default transport for Cloudflare deploys — no API keys, no SES setup. See [Email Configuration](/compiler/config#email-configuration). Use AWS SES when you need it (non-Cloudflare runtimes, existing SES infra, or specific deliverability/compliance requirements).
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install @quickback-dev/better-auth-aws-ses
11
+ ```
12
+
13
+ This plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
14
+
15
+ ## Email Types
16
+
17
+ The plugin handles 8 email types:
18
+
19
+ | Endpoint | When Sent |
20
+ |----------|-----------|
21
+ | `/ses/send-verification` | Signup email verification |
22
+ | `/ses/send-password-reset` | Password reset request |
23
+ | `/ses/send-magic-link` | Passwordless sign-in link |
24
+ | `/ses/send-otp` | One-time password code |
25
+ | `/ses/send-welcome` | Post-signup welcome email |
26
+ | `/ses/send-organization-invitation` | Team/org invite with role |
27
+ | Combo auth | Magic link + OTP in a single email |
28
+ | Delete account | Account deletion confirmation |
29
+
30
+ ### Combo Auth Mode
31
+
32
+ When `useComboAuthEmail: true` is set, the plugin sends a single email that includes both a magic link button and an OTP code. Users can choose either method to authenticate.
33
+
34
+ ## AWS Signature V4
35
+
36
+ The plugin signs requests to SES using AWS Signature V4 with the Web Crypto API (`crypto.subtle`), making it compatible with Cloudflare Workers without any AWS SDK dependency.
37
+
38
+ ## Templates
39
+
40
+ Each email type has both HTML and plain text templates. Templates include:
41
+
42
+ - Responsive HTML layout with MSO (Microsoft Outlook) support
43
+ - Security warning banners for sensitive operations
44
+ - Fallback plain text versions for all email clients
45
+ - XSS prevention via HTML escaping and URL sanitization
46
+
47
+ ## Configuration
48
+
49
+ ### Server Plugin
50
+
51
+ ```typescript
52
+ import { awsSESPlugin } from "@quickback-dev/better-auth-aws-ses";
53
+
54
+ const auth = betterAuth({
55
+ plugins: [
56
+ awsSESPlugin({
57
+ region: env.AWS_SES_REGION,
58
+ accessKeyId: env.AWS_ACCESS_KEY_ID,
59
+ secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
60
+ fromEmail: env.EMAIL_FROM,
61
+ fromName: env.EMAIL_FROM_NAME || "My App",
62
+ replyTo: env.EMAIL_REPLY_TO,
63
+ appName: env.APP_NAME || "My App",
64
+ appUrl: env.APP_URL,
65
+ useComboAuthEmail: true, // Optional: combine magic link + OTP
66
+ }),
67
+ ],
68
+ });
69
+ ```
70
+
71
+ ### Client Plugin
72
+
73
+ ```typescript
74
+ import { awsSESClientPlugin } from "@quickback-dev/better-auth-aws-ses/client";
75
+
76
+ const authClient = createAuthClient({
77
+ plugins: [awsSESClientPlugin()],
78
+ });
79
+ ```
80
+
81
+ ## Required Environment Variables
82
+
83
+ | Variable | Description |
84
+ |----------|-------------|
85
+ | `AWS_ACCESS_KEY_ID` | AWS access key (use Wrangler secrets) |
86
+ | `AWS_SECRET_ACCESS_KEY` | AWS secret key (use Wrangler secrets) |
87
+ | `AWS_SES_REGION` | SES region (e.g., `us-east-2`) |
88
+ | `EMAIL_FROM` | Sender email address (must be SES-verified) |
89
+
90
+ ## Optional Variables
91
+
92
+ | Variable | Description |
93
+ |----------|-------------|
94
+ | `EMAIL_FROM_NAME` | Sender display name |
95
+ | `EMAIL_REPLY_TO` | Reply-to address (defaults to `EMAIL_FROM`) |
96
+ | `APP_NAME` | Application name shown in email templates |
97
+ | `APP_URL` | Application URL for links in emails |
98
+ | `BETTER_AUTH_URL` | Auth API URL (for verification/reset links) |
99
+
100
+ ## Rate Limiting
101
+
102
+ The plugin includes basic in-memory rate limiting per recipient:
103
+
104
+ - Configurable hourly and daily limits
105
+ - Per-recipient tracking
106
+ - For production, consider using an external store (Redis, KV)
107
+
108
+ ```typescript
109
+ awsSESPlugin({
110
+ // ...
111
+ rateLimit: {
112
+ maxEmailsPerHour: 10,
113
+ maxEmailsPerDay: 50,
114
+ },
115
+ })
116
+ ```
117
+
118
+ ## Error Handling
119
+
120
+ - Email failures return `false` (don't throw) — signup/login flows continue even if email delivery fails
121
+ - Invalid or placeholder AWS credentials are detected at startup
122
+ - Detailed console logging for debugging delivery issues
123
+
124
+ ## See Also
125
+
126
+ - [Combo Auth Plugin](/stack/auth/plugins/combo-auth) — Combined magic link + OTP authentication
127
+ - [Auth Configuration](/compiler/config/providers) — Configuring auth plugins
@@ -0,0 +1,74 @@
1
+ # Combo Auth Plugin
2
+
3
+ `@quickback-dev/better-auth-combo-auth` provides a combined authentication flow that sends both a magic link and an OTP code in a single email. Users can click the link (one-click) or enter the 6-digit OTP code — whichever is more convenient.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @quickback-dev/better-auth-combo-auth
9
+ ```
10
+
11
+ ## Server Setup
12
+
13
+ Add the plugin to your Better Auth configuration:
14
+
15
+ ```typescript
16
+ import { betterAuth } from "better-auth";
17
+ import { comboAuth } from "@quickback-dev/better-auth-combo-auth";
18
+
19
+ export const auth = betterAuth({
20
+ plugins: [
21
+ comboAuth({
22
+ sendComboAuth: async ({ email, otp, url }) => {
23
+ // Send email with both the magic link (url) and OTP code (otp)
24
+ await sendEmail({
25
+ to: email,
26
+ subject: "Sign in to My App",
27
+ html: `
28
+ <p>Click the link below to sign in:</p>
29
+ <a href="${url}">Sign in to My App</a>
30
+ <p>Or enter this code: <strong>${otp}</strong></p>
31
+ `,
32
+ });
33
+ },
34
+ }),
35
+ ],
36
+ });
37
+ ```
38
+
39
+ ## Client Usage
40
+
41
+ ```typescript
42
+ import { createAuthClient } from "better-auth/client";
43
+ import { comboAuthClient } from "@quickback-dev/better-auth-combo-auth/client";
44
+
45
+ const authClient = createAuthClient({
46
+ plugins: [comboAuthClient()],
47
+ });
48
+
49
+ // Request authentication — sends email with link + OTP
50
+ await authClient.signIn.comboAuth({
51
+ email: "user@example.com",
52
+ });
53
+
54
+ // Verify with OTP code (if user enters it manually)
55
+ await authClient.signIn.comboAuth({
56
+ email: "user@example.com",
57
+ otp: "123456",
58
+ });
59
+ ```
60
+
61
+ ## How It Works
62
+
63
+ 1. User enters their email and requests sign-in
64
+ 2. A single email is sent containing both a magic link and a 6-digit OTP
65
+ 3. **Option A:** User clicks the magic link — authenticated immediately
66
+ 4. **Option B:** User enters the OTP code — authenticated after verification
67
+
68
+ This provides the best of both worlds: convenience of magic links with the reliability of OTP codes (useful when magic links don't work well, e.g., opening email on a different device).
69
+
70
+ ## See Also
71
+
72
+ - [Auth Plugins](/stack/auth/plugins) — All authentication plugin options
73
+ - [Upgrade Anonymous](/stack/auth/plugins/upgrade-anonymous) — Convert anonymous sessions to full accounts
74
+ - [AWS SES](/stack/auth/plugins/aws-ses) — Email delivery for auth flows