@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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +15 -10
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1225 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +73 -0
- package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1225 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +340 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +73 -0
- package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- 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
|