@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,232 @@
1
+ # File Storage (R2)
2
+
3
+ Quickback provides built-in file storage using Cloudflare R2, with role-based access control and a dedicated files worker for serving.
4
+
5
+ ## Architecture
6
+
7
+ ```
8
+ ┌─────────────────────────────────────────────────────────────────────┐
9
+ │ Your Application │
10
+ │ │
11
+ │ Upload/Manage Files Serve Files │
12
+ │ ───────────────────── ────────────── │
13
+ │ api.yourdomain.com files.yourdomain.com │
14
+ │ /storage/v1/* /* │
15
+ │ │
16
+ │ ┌─────────────────────┐ ┌─────────────────────┐ │
17
+ │ │ API Worker │ │ Files Worker │ │
18
+ │ │ │ │ │ │
19
+ │ │ POST /bucket │ │ GET /public/* │ │
20
+ │ │ GET /bucket │ │ → No auth │ │
21
+ │ │ POST /object/* │ │ │ │
22
+ │ │ DELETE /object/* │ │ GET /* │ │
23
+ │ │ │ │ → Session + RBAC │ │
24
+ │ └──────────┬──────────┘ └──────────┬──────────┘ │
25
+ │ │ │ │
26
+ │ └───────────┬───────────────────┘ │
27
+ │ │ │
28
+ │ ▼ │
29
+ │ ┌─────────────────────┐ │
30
+ │ │ R2 Bucket │ │
31
+ │ │ quickback-files │ │
32
+ │ └─────────────────────┘ │
33
+ └─────────────────────────────────────────────────────────────────────┘
34
+ ```
35
+
36
+ ## Enabling File Storage
37
+
38
+ Add the `fileStorage` provider to your `quickback.config.ts`:
39
+
40
+ ```typescript
41
+ export default {
42
+ name: 'my-app',
43
+ providers: {
44
+ runtime: { name: 'cloudflare' },
45
+ database: { name: 'cloudflare-d1' },
46
+ auth: { name: 'better-auth' },
47
+ fileStorage: {
48
+ name: 'cloudflare-r2',
49
+ config: {
50
+ binding: 'R2_BUCKET',
51
+ bucketName: 'my-app-files',
52
+ filesBinding: 'FILES_DB',
53
+ maxFileSize: 10 * 1024 * 1024, // 10MB
54
+ allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
55
+ },
56
+ },
57
+ },
58
+ };
59
+ ```
60
+
61
+ ## API Endpoints
62
+
63
+ ### Storage API (api.yourdomain.com/storage/v1)
64
+
65
+ | Method | Endpoint | Description |
66
+ |--------|----------|-------------|
67
+ | POST | `/bucket` | Create a bucket |
68
+ | GET | `/bucket` | List buckets |
69
+ | GET | `/bucket/:name` | Get bucket info |
70
+ | DELETE | `/bucket/:name` | Delete bucket (must be empty) |
71
+ | POST | `/object/:bucket/*path` | Upload file |
72
+ | GET | `/object/:bucket/*path` | Download file |
73
+ | HEAD | `/object/:bucket/*path` | Get file metadata |
74
+ | DELETE | `/object/:bucket/*path` | Delete file (soft delete) |
75
+ | GET | `/object` | List objects |
76
+ | POST | `/url` | Get file URL for serving |
77
+
78
+ ### Files Worker (files.yourdomain.com)
79
+
80
+ | Method | Path | Auth Required |
81
+ |--------|------|---------------|
82
+ | GET/HEAD | `/public/*` | No |
83
+ | GET/HEAD | `/*` | Yes (session + RBAC) |
84
+
85
+ ## Buckets
86
+
87
+ Buckets organize files and define access control policies.
88
+
89
+ ### Creating a Bucket
90
+
91
+ ```bash
92
+ POST /storage/v1/bucket
93
+ {
94
+ "name": "avatars",
95
+ "readScope": "organization",
96
+ "writeScope": "organization",
97
+ "readRoles": ["admin", "member"],
98
+ "writeRoles": ["admin"],
99
+ "deleteRoles": ["admin"]
100
+ }
101
+ ```
102
+
103
+ ### Scope Options
104
+
105
+ | Scope | Read Behavior | Write Behavior |
106
+ |-------|---------------|----------------|
107
+ | `public` | Anyone can read | N/A |
108
+ | `organization` | Org members only | Org members only |
109
+ | `user` | Owner only | Owner only |
110
+
111
+ ### Role-Based Access
112
+
113
+ You can restrict operations to specific roles:
114
+
115
+ ```json
116
+ {
117
+ "readRoles": ["admin", "member"],
118
+ "writeRoles": ["admin", "editor"],
119
+ "deleteRoles": ["admin"]
120
+ }
121
+ ```
122
+
123
+ An empty array `[]` means no role restriction (all authenticated users).
124
+
125
+ ## Uploading Files
126
+
127
+ ```bash
128
+ POST /storage/v1/object/avatars/profile.jpg
129
+ Content-Type: image/jpeg
130
+ Content-Length: 12345
131
+
132
+ <binary data>
133
+ ```
134
+
135
+ Response:
136
+ ```json
137
+ {
138
+ "id": "obj_123",
139
+ "key": "org_abc/avatars/profile.jpg",
140
+ "bucket": "avatars",
141
+ "name": "profile.jpg",
142
+ "size": 12345,
143
+ "mimeType": "image/jpeg",
144
+ "readScope": "organization"
145
+ }
146
+ ```
147
+
148
+ ## Serving Files
149
+
150
+ ### Public Files
151
+
152
+ Files in buckets with `readScope: "public"` are stored with a `public/` prefix:
153
+
154
+ ```
155
+ https://files.yourdomain.com/public/org_abc/avatars/logo.png
156
+ ```
157
+
158
+ No authentication required.
159
+
160
+ ### Private Files
161
+
162
+ Private files require a valid Better Auth session cookie:
163
+
164
+ ```
165
+ https://files.yourdomain.com/org_abc/documents/report.pdf
166
+ ```
167
+
168
+ The files worker:
169
+ 1. Validates the session token
170
+ 2. Checks the user's organization matches
171
+ 3. Verifies role permissions (if `readRoles` configured)
172
+ 4. Serves the file or returns 403
173
+
174
+ ## Generated Files
175
+
176
+ When file storage is configured, the compiler generates:
177
+
178
+ | File | Purpose |
179
+ |------|---------|
180
+ | `src/routes/storage.ts` | Storage API routes |
181
+ | `src/files.ts` | Files database schema (buckets, objects) |
182
+ | `cloudflare-workers/files/index.ts` | Files worker for serving |
183
+ | `cloudflare-workers/files/wrangler.toml` | Files worker config |
184
+
185
+ ## Deployment
186
+
187
+ After compiling:
188
+
189
+ 1. **Create the R2 bucket:**
190
+ ```bash
191
+ wrangler r2 bucket create my-app-files
192
+ ```
193
+
194
+ 2. **Create the files database:**
195
+ ```bash
196
+ wrangler d1 create my-app-files
197
+ ```
198
+
199
+ 3. **Run migrations:**
200
+ ```bash
201
+ wrangler d1 migrations apply my-app-files --local
202
+ wrangler d1 migrations apply my-app-files --remote
203
+ ```
204
+
205
+ 4. **Deploy the API:**
206
+ ```bash
207
+ wrangler deploy
208
+ ```
209
+
210
+ 5. **Deploy the files worker:**
211
+ ```bash
212
+ cd cloudflare-workers/files
213
+ wrangler deploy
214
+ ```
215
+
216
+ ## Configuration Reference
217
+
218
+ | Option | Type | Default | Description |
219
+ |--------|------|---------|-------------|
220
+ | `binding` | `string` | `R2_BUCKET` | R2 bucket binding name |
221
+ | `bucketName` | `string` | Required | R2 bucket name |
222
+ | `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding |
223
+ | `maxFileSize` | `number` | 10MB | Max upload size in bytes |
224
+ | `allowedTypes` | `string[]` | Images only | Allowed MIME types |
225
+ | `publicDomain` | `string` | - | Custom domain for files worker |
226
+
227
+ ## Security Model
228
+
229
+ - **Upload security**: Enforced by API worker (auth middleware, org check, role check)
230
+ - **Serve security**: Enforced by files worker (session validation, metadata RBAC)
231
+ - **Soft deletes**: Files are marked deleted in metadata but retained in R2
232
+ - **Tenant isolation**: All files are prefixed with organization ID
@@ -0,0 +1,70 @@
1
+ # Using KV
2
+
3
+ Cloudflare KV is used by the Quickback Stack for session storage, caching, and rate limiting.
4
+
5
+ ## Session Storage
6
+
7
+ Better Auth stores sessions in KV by default for fast edge-based lookups. This is auto-configured by the compiler — no setup needed.
8
+
9
+ ```typescript
10
+ // How sessions work internally (auto-generated)
11
+ // On login: session stored in KV
12
+ await kv.put(`session:${sessionToken}`, JSON.stringify(sessionData), {
13
+ expirationTtl: 60 * 60 * 24 * 7, // 7 days
14
+ });
15
+
16
+ // On each request: session retrieved from KV
17
+ const session = await kv.get(`session:${sessionToken}`, "json");
18
+ ```
19
+
20
+ Sessions are automatically:
21
+ - **Created** on sign-in (email/password, passkey, magic link, etc.)
22
+ - **Validated** on every authenticated request via the `Authorization: Bearer <token>` header
23
+ - **Expired** after the configured TTL (default: 7 days)
24
+ - **Deleted** on sign-out
25
+
26
+ ## Rate Limiting
27
+
28
+ KV powers the rate limiting middleware that protects auth endpoints:
29
+
30
+ ```typescript
31
+ // Rate limit key structure (auto-generated)
32
+ // Key: ratelimit:{ip}:{endpoint}
33
+ // Value: request count
34
+ // TTL: rate limit window (e.g., 60 seconds)
35
+ const key = `ratelimit:${ip}:${endpoint}`;
36
+ const count = await kv.get(key);
37
+ if (count && parseInt(count) > limit) {
38
+ return c.json({ error: "Too many requests" }, 429);
39
+ }
40
+ ```
41
+
42
+ See [Auth Security](/stack/auth/security) for rate limiting configuration options.
43
+
44
+ ## Caching
45
+
46
+ You can use KV in custom action handlers for caching frequently accessed data:
47
+
48
+ ```typescript
49
+ // In an action handler
50
+ execute: async ({ db, ctx }) => {
51
+ const kv = ctx.env.KV;
52
+
53
+ // Check cache first
54
+ const cached = await kv.get("expensive-query-result", "json");
55
+ if (cached) return cached;
56
+
57
+ // Compute and cache
58
+ const result = await db.select().from(analytics);
59
+ await kv.put("expensive-query-result", JSON.stringify(result), {
60
+ expirationTtl: 300, // 5 minutes
61
+ });
62
+
63
+ return result;
64
+ }
65
+ ```
66
+
67
+ ## See Also
68
+
69
+ - [KV Setup](/stack/storage/kv) — Namespace creation and wrangler bindings
70
+ - [Auth Security](/stack/auth/security) — Rate limiting and cookie security configuration
@@ -0,0 +1,55 @@
1
+ # Using R2
2
+
3
+ Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.
4
+
5
+ ## Upload Flow
6
+
7
+ The generated API provides a two-step upload process:
8
+
9
+ 1. **Request a presigned URL** — Client calls the upload endpoint to get a time-limited URL
10
+ 2. **Upload directly to R2** — Client uploads the file directly to R2 (bypasses your Worker)
11
+ 3. **Store the reference** — The API records the file metadata in D1
12
+
13
+ ```bash
14
+ # 1. Request presigned upload URL
15
+ curl -X POST https://api.example.com/api/v1/files/upload \
16
+ -H "Authorization: Bearer <token>" \
17
+ -H "Content-Type: application/json" \
18
+ -d '{"filename": "report.pdf", "contentType": "application/pdf"}'
19
+
20
+ # Response:
21
+ # { "uploadUrl": "https://bucket.r2.cloudflarestorage.com/...", "fileId": "file_abc123" }
22
+
23
+ # 2. Upload directly to R2 using the presigned URL
24
+ curl -X PUT "<uploadUrl>" \
25
+ -H "Content-Type: application/pdf" \
26
+ --data-binary @report.pdf
27
+ ```
28
+
29
+ ## Download Flow
30
+
31
+ Files are served through your Worker with security checks applied:
32
+
33
+ ```bash
34
+ # Download a file (auth + firewall enforced)
35
+ curl https://api.example.com/api/v1/files/file_abc123/download \
36
+ -H "Authorization: Bearer <token>"
37
+ ```
38
+
39
+ The download endpoint:
40
+ 1. Validates the user's session
41
+ 2. Checks firewall — the file must belong to the user's organization
42
+ 3. Checks access — the user must have the required role
43
+ 4. Streams the file from R2
44
+
45
+ ## Role-Based Access
46
+
47
+ File access respects the same security layers as your API:
48
+
49
+ - **Firewall** — Users can only access files belonging to their organization
50
+ - **Access** — Role-based download permissions
51
+
52
+ ## See Also
53
+
54
+ - [R2 Setup](/stack/storage/r2) — Bucket creation, wrangler bindings, and configuration
55
+ - [Avatars](/stack/account-ui/features/avatars) — Avatar upload UI integration