@quickback-dev/cli 0.10.15 → 0.10.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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.js +6 -6
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +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 +1192 -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 +228 -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 +67 -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 +1192 -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 +228 -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 +67 -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,255 @@
|
|
|
1
|
+
# Security Headers
|
|
2
|
+
|
|
3
|
+
Every compiled Quickback Worker sets a baseline of security response-headers on every response: HSTS, `X-Content-Type-Options: nosniff`, a clickjacking CSP (`frame-ancestors 'self' …TRUSTED_ORIGINS`), `X-Frame-Options: SAMEORIGIN`, `Referrer-Policy`, and `Permissions-Policy`. Adding the `security` block lets you override individual headers, ship a fuller Content-Security-Policy, or suppress them all if an upstream gateway handles headers.
|
|
4
|
+
|
|
5
|
+
## Default behavior
|
|
6
|
+
|
|
7
|
+
Omit `security` entirely → the baseline above. No config change needed for clickjacking + HSTS protection.
|
|
8
|
+
|
|
9
|
+
```ts title="quickback.config.ts"
|
|
10
|
+
import { defineConfig } from '@quickback/compiler';
|
|
11
|
+
|
|
12
|
+
export default defineConfig({
|
|
13
|
+
name: 'my-api',
|
|
14
|
+
// ...
|
|
15
|
+
// security defaults are applied automatically.
|
|
16
|
+
});
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Suppress every security header
|
|
20
|
+
|
|
21
|
+
For Workers fronted by a gateway that owns headers:
|
|
22
|
+
|
|
23
|
+
```ts title="quickback.config.ts"
|
|
24
|
+
export default defineConfig({
|
|
25
|
+
// ...
|
|
26
|
+
security: false,
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The compiler emits a no-op middleware comment so the route table still lines up with the rest of the generated code, but no `c.header(...)` calls fire.
|
|
31
|
+
|
|
32
|
+
## Per-header overrides
|
|
33
|
+
|
|
34
|
+
Each field on the `security` block accepts either a typed value or `false` to suppress that specific header. Defaults still apply for fields you don't set.
|
|
35
|
+
|
|
36
|
+
```ts title="quickback.config.ts"
|
|
37
|
+
export default defineConfig({
|
|
38
|
+
// ...
|
|
39
|
+
security: {
|
|
40
|
+
// Suppress just CSP — keeps HSTS, referrer, permissions, etc.
|
|
41
|
+
csp: false,
|
|
42
|
+
|
|
43
|
+
// Or override individual fields:
|
|
44
|
+
coop: 'same-origin',
|
|
45
|
+
coep: 'credentialless',
|
|
46
|
+
referrerPolicy: 'no-referrer',
|
|
47
|
+
permissionsPolicy: { geolocation: [], microphone: [], camera: [], payment: [] },
|
|
48
|
+
hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
|
|
49
|
+
},
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Content Security Policy
|
|
54
|
+
|
|
55
|
+
`security.csp` accepts a typed object. Each `*Src` field is an array of source expressions. The compiler accepts both the `@`-prefixed sentinels (idiomatic, type-safe) and CSP wire-form keywords (`"'self'"`, `"'unsafe-inline'"`); both normalize to the same output.
|
|
56
|
+
|
|
57
|
+
### Sentinels
|
|
58
|
+
|
|
59
|
+
| Sentinel | Wire form | Notes |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `@self` | `'self'` | Same-origin. |
|
|
62
|
+
| `@none` | `'none'` | Empty-set keyword. |
|
|
63
|
+
| `@unsafe-inline` | `'unsafe-inline'` | Allows inline scripts/styles — defeats most XSS mitigation when used in `script-src`. |
|
|
64
|
+
| `@unsafe-eval` | `'unsafe-eval'` | Allows `eval()` and friends. |
|
|
65
|
+
| `@trustedOrigins` | The `…TRUSTED_ORIGINS` constant at runtime | Resolves to `auth.trustedOrigins` as configured in `quickback.config.ts`. |
|
|
66
|
+
| `@nonce` | `'nonce-…'` per request | Reserved for the per-request nonce middleware shipping in 0.10.15. Using this in 0.10.14 is a compile-time error. |
|
|
67
|
+
|
|
68
|
+
Unknown `@…` tokens are rejected at compile rather than silently stringified into the wire CSP.
|
|
69
|
+
|
|
70
|
+
### Example: paste-in CSP for a Quickback SPA project
|
|
71
|
+
|
|
72
|
+
The bundled CMS and Account SPAs load Google Fonts cross-origin, so the strict `'self'`-only CSP would white-screen them on load. This config is a known-working starting point for Quickback projects with the bundled SPAs:
|
|
73
|
+
|
|
74
|
+
```ts title="quickback.config.ts"
|
|
75
|
+
export default defineConfig({
|
|
76
|
+
// ...
|
|
77
|
+
security: {
|
|
78
|
+
csp: {
|
|
79
|
+
defaultSrc: ['@self'],
|
|
80
|
+
// Tailwind dynamic styles + bundled Google Fonts CSS need
|
|
81
|
+
// unsafe-inline + the gstatic / googleapis hosts. Tightening
|
|
82
|
+
// styles to nonces ships in 0.10.15.
|
|
83
|
+
styleSrc: ['@self', '@unsafe-inline', 'https://fonts.googleapis.com'],
|
|
84
|
+
scriptSrc: ['@self'],
|
|
85
|
+
fontSrc: ['@self', 'data:', 'https://fonts.gstatic.com'],
|
|
86
|
+
imgSrc: ['@self', 'data:', 'blob:', 'https:'],
|
|
87
|
+
connectSrc: ['@self', '@trustedOrigins'],
|
|
88
|
+
frameAncestors: ['@self', '@trustedOrigins'],
|
|
89
|
+
formAction: ['@self'],
|
|
90
|
+
baseUri: ['@self'],
|
|
91
|
+
objectSrc: ['@none'],
|
|
92
|
+
upgradeInsecureRequests: true,
|
|
93
|
+
},
|
|
94
|
+
},
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Troubleshooting CSP violations
|
|
99
|
+
|
|
100
|
+
If the browser console shows CSP errors after enabling `security.csp`, match the directive named in the error against this table — it maps the failure mode back to the directive that needs widening.
|
|
101
|
+
|
|
102
|
+
| Console error | Directive | Why it happens | Fix |
|
|
103
|
+
|---|---|---|---|
|
|
104
|
+
| `Loading the stylesheet 'https://fonts.googleapis.com/...' violates 'style-src ...'` | `styleSrc` | Bundled CMS/Account SPAs `<link>` to Google Fonts CSS. | Add `'https://fonts.googleapis.com'` to `styleSrc`. |
|
|
105
|
+
| `Refused to load the font 'https://fonts.gstatic.com/...' because it violates 'font-src ...'` | `fontSrc` | The CSS file from googleapis loads `.woff2` files from gstatic. | Add `'https://fonts.gstatic.com'` to `fontSrc`. |
|
|
106
|
+
| `Connecting to 'https://api.your-domain/...' violates 'connect-src 'self''` | `connectSrc` | API on a sibling subdomain (e.g. SPA on `app.example.com`, API on `api.example.com`) — `'self'` only covers exact origin. | Use `connectSrc: ['@self', '@trustedOrigins']` so the same allowlist `cors()` enforces gets reused. |
|
|
107
|
+
| `Refused to apply inline style because it violates 'style-src ...'` | `styleSrc` | TanStack Router / Tailwind's `style="..."` attributes are inline. | Add `'@unsafe-inline'` to `styleSrc` until 0.10.15 ships per-request nonces. |
|
|
108
|
+
| `Refused to load the image '...' because it violates 'img-src ...'` | `imgSrc` | User-uploaded avatars / R2-hosted assets / `data:` URIs from blob previews. | Widen `imgSrc` to `['@self', 'data:', 'blob:', 'https:']` (or list specific hosts). |
|
|
109
|
+
| `Refused to connect to 'wss://...' because it violates 'connect-src ...'` | `connectSrc` | Realtime / Durable Object WebSockets. | The `@trustedOrigins` sentinel covers HTTPS only — add the explicit `wss://` origin if your DO lives elsewhere. |
|
|
110
|
+
|
|
111
|
+
The general rule: `'self'` means *exact origin* (scheme + host + port). Anything cross-origin needs an explicit host or the `@trustedOrigins` sentinel. The [paste-in recipe above](#example-paste-in-csp-for-a-quickback-spa-project) is a known-good baseline for a stock Quickback project — start there and tighten, rather than starting from `'self'`-only and chasing console errors.
|
|
112
|
+
|
|
113
|
+
### Auto-derivations
|
|
114
|
+
|
|
115
|
+
The compiler applies these so config stays minimal:
|
|
116
|
+
|
|
117
|
+
- **`csp.frameAncestors` defaults to `['@self', '@trustedOrigins']`** when `csp` is set but `frameAncestors` is omitted. Same allowlist as CORS.
|
|
118
|
+
- **`X-Frame-Options` derives from `csp.frameAncestors`** (`['@none']` → `DENY`, contains `@self` → `SAMEORIGIN`, otherwise omitted — XFO can't represent arbitrary origins so CSP becomes the truth there). Override with `security.frameOptions`.
|
|
119
|
+
- **`corp: 'same-origin'` is auto-emitted when `coep` is set.** `require-corp` without CORP breaks the ASSETS binding fetches on Cloudflare; the compiler couples them so users don't have to remember.
|
|
120
|
+
|
|
121
|
+
### CSP auto-config (0.10.15+)
|
|
122
|
+
|
|
123
|
+
When you opt into a `csp` object, the compiler additively widens directives based on which Quickback features your project has enabled. **Additive** means anything you already wrote stays; we only push values that aren't already present.
|
|
124
|
+
|
|
125
|
+
| Trigger | Auto-added | To directive | Why |
|
|
126
|
+
|---|---|---|---|
|
|
127
|
+
| `cms: true` OR `account: true` | `'unsafe-inline'` | `styleSrc` | Tailwind / TanStack Router emit inline `style=` attributes |
|
|
128
|
+
| `cms: true` OR `account: true` | `https://fonts.googleapis.com` | `styleSrc` | Bundled SPAs `<link>` to Google Fonts CSS |
|
|
129
|
+
| `cms: true` OR `account: true` | `https://fonts.gstatic.com` | `fontSrc` | The googleapis CSS loads `.woff2` from gstatic |
|
|
130
|
+
| `csp` set (always) | `@trustedOrigins` | `connectSrc` | XHR/fetch must reach the same allowlist `cors()` permits — covers cross-subdomain APIs without re-listing them |
|
|
131
|
+
| `cms: true` OR `account: true` | `https://${domain}` for each `cms.domain` / `account.domain` / `domain` / inferred unified domain | `connectSrc` | The Vite bundle hardcodes `VITE_QUICKBACK_API_URL` at compile time, so the SPA fetches that exact URL even when the page is served from a different origin (e.g. localhost dev hitting prod-baked SPA). Emitted with the host's first letter capitalised (`https://Api.example.com`) so `wrangler dev`'s response-header rewrite can't mangle it — see [the `wrangler dev` note below](#why-the-spa-baked-origin-shows-up-capitalised-in-csp). |
|
|
132
|
+
|
|
133
|
+
**Scaffold rule:** if you set `defaultSrc` but omit the target directive (e.g. you wrote `defaultSrc: ['@self']` and nothing for `connectSrc`), auto-config creates the new directive seeded with your `defaultSrc` values plus the addition. `defaultSrc` itself stays clean. So `defaultSrc: ['@self']` + auto-config produces:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
default-src 'self'
|
|
137
|
+
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com
|
|
138
|
+
font-src 'self' https://fonts.gstatic.com
|
|
139
|
+
connect-src 'self' @trustedOrigins https://api.your-app.com
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened with style-only or connect-only hosts — that would let those hosts also reach `script-src` / `img-src` / `media-src` via fall-back, which is wider than the bundled SPA actually needs. (This rule changed in 0.10.17 — earlier versions incorrectly pushed additions into defaultSrc.)
|
|
143
|
+
|
|
144
|
+
**Visibility:** every applied addition prints to stderr at compile time — one line per addition with the directive, value, and reason. No silent magic. Loop's compile output now looks like:
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
[security] auto-added 'unsafe-inline' to csp.styleSrc — account: true → bundled Account SPA → inline style attributes from Tailwind / TanStack Router
|
|
148
|
+
[security] auto-added https://fonts.googleapis.com to csp.styleSrc — account: true → bundled Account SPA → loads Google Fonts CSS cross-origin
|
|
149
|
+
[security] auto-added https://fonts.gstatic.com to csp.fontSrc — account: true → bundled Account SPA → woff2 font files served from gstatic.com
|
|
150
|
+
[security] auto-added @trustedOrigins to csp.connectSrc — CORS-trusted origins must be reachable from XHR/fetch (matches cors() allowlist)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**Opt-out:** `security: { cspAutoConfig: false, csp: { ... } }` for projects fronted by a CDN that injects its own CSP, or teams that want strict from-scratch control. With auto-config off, every value above must be authored by hand.
|
|
154
|
+
|
|
155
|
+
#### Why the SPA-baked origin shows up capitalised in CSP
|
|
156
|
+
|
|
157
|
+
Projects with `domain: "..."` + bundled CMS / Account SPAs will see `connect-src 'self' https://Api.example.com …` in their served CSP — note the capital `A`. That's deliberate (added in 0.10.19) and works around a `wrangler dev` quirk, not a typo on our end.
|
|
158
|
+
|
|
159
|
+
`wrangler dev` rewrites the configured `custom_domain` host string in **every** response header value (Location, Content-Security-Policy, X-…) to the local hostname, with a case-sensitive substring matcher. Without the case-shift, the served CSP becomes `connect-src 'self' https://localhost:8787 …` and the bundled SPA's hardcoded `VITE_QUICKBACK_API_URL` fetches get blocked because the prod URL no longer appears in the allowlist.
|
|
160
|
+
|
|
161
|
+
CSP host-source matching is ASCII case-insensitive per CSP3 (`Matching Source Expressions`), so browsers treat `https://Api.example.com` as identical to `https://api.example.com` for the purpose of CSP checks. Wrangler's matcher is case-sensitive, so the capitalised form slips past the rewrite and survives into the served header. End result: the SPA's lowercase fetch target matches the capitalised CSP entry, auth round-trips work in dev, and prod CSP behaviour is unchanged (browsers don't care).
|
|
162
|
+
|
|
163
|
+
If wrangler ever fixes the response-header rewrite, the capitalised form remains a valid CSP entry — no follow-up needed.
|
|
164
|
+
|
|
165
|
+
With auto-config on, the [paste-in recipe above](#example-paste-in-csp-for-a-quickback-spa-project) becomes much shorter — most users only need:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
security: {
|
|
169
|
+
csp: {
|
|
170
|
+
defaultSrc: ['@self'],
|
|
171
|
+
scriptSrc: ['@self'],
|
|
172
|
+
imgSrc: ['@self', 'data:', 'blob:', 'https:'],
|
|
173
|
+
objectSrc: ['@none'],
|
|
174
|
+
upgradeInsecureRequests: true,
|
|
175
|
+
},
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The compiler fills in the SPA-specific font hosts, inline-style allowance, and trusted-origin connect rules from the project's own feature flags.
|
|
180
|
+
|
|
181
|
+
## Cross-origin window/embedder isolation
|
|
182
|
+
|
|
183
|
+
```ts title="quickback.config.ts"
|
|
184
|
+
security: {
|
|
185
|
+
coop: 'same-origin', // Defends against window.opener back-references from popups.
|
|
186
|
+
coep: 'credentialless', // Required for SharedArrayBuffer / cross-origin isolation.
|
|
187
|
+
// corp auto-emits as 'same-origin' here.
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## HSTS
|
|
192
|
+
|
|
193
|
+
Default: `max-age=31536000; includeSubDomains; preload` (HSTS preload-list eligible).
|
|
194
|
+
|
|
195
|
+
```ts title="quickback.config.ts"
|
|
196
|
+
security: {
|
|
197
|
+
hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
The generated middleware automatically suppresses HSTS on `localhost`, `127.0.0.1`, and `*.localhost` regardless of this config. Without that gate, `wrangler dev` would pin the developer's browser to HTTPS for `maxAge` seconds, which is observable across every project on that machine.
|
|
202
|
+
|
|
203
|
+
To submit to the [HSTS preload list](https://hstspreload.org), you need:
|
|
204
|
+
|
|
205
|
+
- `maxAge` ≥ 31536000 (one year)
|
|
206
|
+
- `includeSubDomains: true`
|
|
207
|
+
- `preload: true`
|
|
208
|
+
|
|
209
|
+
The compiler warns at compile time if `preload: true` without the other two — the preload list rejects either anyway.
|
|
210
|
+
|
|
211
|
+
## Permissions Policy
|
|
212
|
+
|
|
213
|
+
Map of feature name → list of allowed origins.
|
|
214
|
+
|
|
215
|
+
```ts title="quickback.config.ts"
|
|
216
|
+
security: {
|
|
217
|
+
permissionsPolicy: {
|
|
218
|
+
geolocation: [], // disabled for everyone
|
|
219
|
+
microphone: ['self'], // allowed only on own origin
|
|
220
|
+
camera: ['self', 'https://meet.example.com'],
|
|
221
|
+
payment: [],
|
|
222
|
+
},
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
The compiler encodes the wire syntax (which differs from CSP — values use `()`, not space-separated tokens, with bareword `self` and quoted URLs).
|
|
227
|
+
|
|
228
|
+
## Compile-time lint rules
|
|
229
|
+
|
|
230
|
+
The compiler walks the resolved config and emits warnings (or errors) for known footguns. Errors block compile; warnings print to stderr.
|
|
231
|
+
|
|
232
|
+
| Code | Severity | Trigger |
|
|
233
|
+
|---|---|---|
|
|
234
|
+
| `csp/nonce-not-yet-supported` | error | `@nonce` sentinel used in 0.10.14. Per-request nonce middleware ships in 0.10.15. |
|
|
235
|
+
| `csp/unsafe-inline-with-nonce` | error | `@unsafe-inline` and `@nonce` in the same directive (CSP3 silently ignores `unsafe-inline` when nonce is present). |
|
|
236
|
+
| `csp/empty-resolved-directive` | error | `*Src` array contains only `@trustedOrigins` and `auth.trustedOrigins` is empty — would emit a directive Chrome reads as `'none'`. |
|
|
237
|
+
| `csp/unsafe-inline-script` | warn | `@unsafe-inline` in `scriptSrc` defeats most XSS mitigations. |
|
|
238
|
+
| `csp/open-source` | warn | Wildcard `*` or scheme-only `https:` / `http:` in any `*-src`. |
|
|
239
|
+
| `csp/unsafe-eval-with-data` | warn | `@unsafe-eval` combined with any `data:` source — trivial bypass. |
|
|
240
|
+
| `csp/missing-default-src` | warn | Other `*-src` set without `defaultSrc`. |
|
|
241
|
+
| `csp/upgrade-with-http` | warn | `upgradeInsecureRequests: true` plus an `http://` source elsewhere. |
|
|
242
|
+
| `csp/report-uri-only` | warn | `reportUri` set without `reportTo` (deprecated CSP2 path). |
|
|
243
|
+
| `hsts/preload-needs-long-max-age` | warn | `preload: true` with `maxAge < 31536000`. |
|
|
244
|
+
| `hsts/preload-needs-include-subdomains` | warn | `preload: true` without `includeSubDomains`. |
|
|
245
|
+
|
|
246
|
+
## Verification
|
|
247
|
+
|
|
248
|
+
Spin up the deployed Worker (or `wrangler dev`) and check the response headers:
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
curl -sI https://my-api.example.com/health \
|
|
252
|
+
| grep -E '^(content-security-policy|x-frame-options|strict-transport-security|cross-origin-opener-policy|cross-origin-embedder-policy|cross-origin-resource-policy|referrer-policy|permissions-policy):'
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Use [securityheaders.com](https://securityheaders.com) for an external grade — Quickback's defaults are A on the baseline and A+ once a fuller `csp` is configured.
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Single-Tenant Mode
|
|
2
|
+
|
|
3
|
+
Single-tenant mode disables the Better Auth organization plugin, removing the `organizationId` requirement from your API. This is ideal for personal sites, blogs, admin panels, or any app with a single tenant.
|
|
4
|
+
|
|
5
|
+
## Enabling Single-Tenant Mode
|
|
6
|
+
|
|
7
|
+
Set `features.organizations` to `false` in your config:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
11
|
+
|
|
12
|
+
export default defineConfig({
|
|
13
|
+
name: "my-site",
|
|
14
|
+
template: "hono",
|
|
15
|
+
features: {
|
|
16
|
+
organizations: false,
|
|
17
|
+
},
|
|
18
|
+
providers: {
|
|
19
|
+
runtime: defineRuntime("cloudflare"),
|
|
20
|
+
database: defineDatabase("cloudflare-d1"),
|
|
21
|
+
auth: defineAuth("better-auth"),
|
|
22
|
+
},
|
|
23
|
+
});
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## What Changes
|
|
27
|
+
|
|
28
|
+
| Aspect | Multi-Tenant (default) | Single-Tenant |
|
|
29
|
+
|--------|----------------------|---------------|
|
|
30
|
+
| Organization plugin | Enabled | Disabled |
|
|
31
|
+
| `organizationId` columns | Required on resources | Not used |
|
|
32
|
+
| Role source | Org membership table | `user.role` field |
|
|
33
|
+
| Firewall scopes | `owner`, `organization`, `team`, `exception` | `owner`, `exception` only |
|
|
34
|
+
| Admin org endpoints | `/admin/v1/organizations` generated | Skipped |
|
|
35
|
+
| `ctx.activeOrgId` | From session/JWT | Always `undefined` |
|
|
36
|
+
| `ctx.roles` | From org member role | From `user.role` |
|
|
37
|
+
|
|
38
|
+
## Firewall Configuration
|
|
39
|
+
|
|
40
|
+
In single-tenant mode, resources use either **owner** scope (user-scoped data) or **exception** (public/system data):
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
// User-scoped data (requires authentication)
|
|
44
|
+
export default defineTable(posts, {
|
|
45
|
+
firewall: [{ field: 'ownerId', equals: 'ctx.userId' }],
|
|
46
|
+
read: {
|
|
47
|
+
access: { roles: ['user', 'admin'] },
|
|
48
|
+
},
|
|
49
|
+
crud: {
|
|
50
|
+
create: { access: { roles: ['admin'] } },
|
|
51
|
+
},
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
// Public data (no ownership filtering)
|
|
55
|
+
export default defineTable(pages, {
|
|
56
|
+
firewall: [{ exception: true }],
|
|
57
|
+
read: {
|
|
58
|
+
access: { roles: ['PUBLIC'] },
|
|
59
|
+
},
|
|
60
|
+
crud: {
|
|
61
|
+
create: { access: { roles: ['admin'] } },
|
|
62
|
+
update: { access: { roles: ['admin'] } },
|
|
63
|
+
delete: { access: { roles: ['admin'] } },
|
|
64
|
+
},
|
|
65
|
+
});
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
> Using `q.scope('organization')` / `q.scope('team')` (or any firewall predicate referencing `ctx.activeOrgId` / `ctx.activeTeamId`) with `organizations: false` will cause a compile error. These scopes require the organization plugin.
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
## Public Routes
|
|
72
|
+
|
|
73
|
+
Use the `PUBLIC` role to expose routes without authentication. This works the same as in multi-tenant mode:
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
read: {
|
|
77
|
+
access: { roles: ['PUBLIC'] }, // GET / and GET /:id — no auth required
|
|
78
|
+
},
|
|
79
|
+
crud: {
|
|
80
|
+
create: { access: { roles: ['admin'] } }, // Admin only
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Role-Based Access
|
|
85
|
+
|
|
86
|
+
Roles come from the `user.role` field (managed by Better Auth's [admin plugin](https://www.better-auth.com/docs/plugins/admin)).
|
|
87
|
+
|
|
88
|
+
> In single-tenant mode `ctx.roles` mirrors `user.role`, so `roles: ["admin"]` and `userRole: ["admin"]` behave the same. Prefer [`userRole`](/compiler/definitions/access#userrole-vs-roles) — it documents intent and keeps the gate correct if you later enable multi-tenant.
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
| Role | Description |
|
|
93
|
+
|------|-------------|
|
|
94
|
+
| `admin` | Full access, set via Better Auth admin plugin |
|
|
95
|
+
| `user` | Default role for authenticated users |
|
|
96
|
+
| `PUBLIC` | Unauthenticated access (special keyword) |
|
|
97
|
+
|
|
98
|
+
```typescript
|
|
99
|
+
// Admin-only action
|
|
100
|
+
export default defineActions({
|
|
101
|
+
publish: {
|
|
102
|
+
access: { roles: ['admin'] },
|
|
103
|
+
execute: async ({ ctx, db }) => {
|
|
104
|
+
// ctx.userRole === 'admin'
|
|
105
|
+
// ctx.roles === ['admin']
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
});
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Consuming the API
|
|
112
|
+
|
|
113
|
+
Since single-tenant mode produces a JSON API, pair it with any frontend framework:
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
// Astro, Next.js, SvelteKit, etc.
|
|
117
|
+
const posts = await fetch('https://api.mysite.com/api/v1/posts').then(r => r.json());
|
|
118
|
+
|
|
119
|
+
// Admin operations require authentication
|
|
120
|
+
const res = await fetch('https://api.mysite.com/api/v1/posts', {
|
|
121
|
+
method: 'POST',
|
|
122
|
+
headers: {
|
|
123
|
+
'Authorization': `Bearer ${token}`,
|
|
124
|
+
'Content-Type': 'application/json',
|
|
125
|
+
},
|
|
126
|
+
body: JSON.stringify({ title: 'New Post', content: '...' }),
|
|
127
|
+
});
|
|
128
|
+
```
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# Environment Variables
|
|
2
|
+
|
|
3
|
+
## CLI Environment Variables
|
|
4
|
+
|
|
5
|
+
These variables configure the Quickback CLI itself.
|
|
6
|
+
|
|
7
|
+
| Variable | Description | Default |
|
|
8
|
+
|----------|-------------|---------|
|
|
9
|
+
| `QUICKBACK_API_URL` | Compiler API endpoint | `https://compiler.quickback.dev` |
|
|
10
|
+
| `QUICKBACK_API_KEY` | API key for headless authentication (CI/CD) | — |
|
|
11
|
+
| `QUICKBACK_AUTH_URL` | Auth server URL (custom deployments) | — |
|
|
12
|
+
|
|
13
|
+
### Authentication
|
|
14
|
+
|
|
15
|
+
The CLI authenticates via two methods:
|
|
16
|
+
|
|
17
|
+
1. **Interactive login** — `quickback login` stores credentials in `~/.quickback/credentials.json`
|
|
18
|
+
2. **API key** — Set `QUICKBACK_API_KEY` for CI/CD environments
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# Use the cloud compiler (default)
|
|
22
|
+
quickback compile
|
|
23
|
+
|
|
24
|
+
# Use a local compiler instance
|
|
25
|
+
QUICKBACK_API_URL=http://localhost:3000 quickback compile
|
|
26
|
+
|
|
27
|
+
# CI/CD with API key
|
|
28
|
+
QUICKBACK_API_KEY=qb_key_... quickback compile
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Compiler Service Variables
|
|
32
|
+
|
|
33
|
+
These variables are used by the compiler service/runtime itself.
|
|
34
|
+
|
|
35
|
+
| Variable | Description | Default |
|
|
36
|
+
|----------|-------------|---------|
|
|
37
|
+
| `QUICKBACK_SECURITY_REPORT_SIGNING_KEY` | HMAC key for signing `security-contracts.report.json` artifacts | — |
|
|
38
|
+
|
|
39
|
+
When `compiler.securityContracts.report.signature.required` is `true`, this variable (or `signature.key`) must be set or compile fails.
|
|
40
|
+
|
|
41
|
+
## Cloudflare Variables
|
|
42
|
+
|
|
43
|
+
### Wrangler Bindings
|
|
44
|
+
|
|
45
|
+
These are configured as bindings in `wrangler.toml`, not environment variables. The compiler generates them automatically.
|
|
46
|
+
|
|
47
|
+
| Binding | Type | Description |
|
|
48
|
+
|---------|------|-------------|
|
|
49
|
+
| `AUTH_DB` | D1 Database | Better Auth tables (dual mode) |
|
|
50
|
+
| `DB` | D1 Database | Feature tables (dual mode) |
|
|
51
|
+
| `DATABASE` | D1 Database | All tables (single DB mode) |
|
|
52
|
+
| `KV` | KV Namespace | Key-value storage |
|
|
53
|
+
| `R2_BUCKET` | R2 Bucket | File storage (if configured) |
|
|
54
|
+
| `AI` | Workers AI | Embedding generation (if configured) |
|
|
55
|
+
| `VECTORIZE` | Vectorize | Vector similarity search (if configured) |
|
|
56
|
+
| `EMBEDDINGS_QUEUE` | Queue | Async embedding jobs (if configured) |
|
|
57
|
+
| `WEBHOOKS_DB` | D1 Database | Webhook events (if configured) |
|
|
58
|
+
| `WEBHOOKS_QUEUE` | Queue | Webhook delivery (if configured) |
|
|
59
|
+
| `FILES_DB` | D1 Database | File metadata (if R2 configured) |
|
|
60
|
+
| `BROADCASTER` | Durable Object | Realtime Broadcaster DO (if configured) |
|
|
61
|
+
| `EMAIL` | send_email | Cloudflare Email Service (if email configured) |
|
|
62
|
+
|
|
63
|
+
### Worker Variables
|
|
64
|
+
|
|
65
|
+
Set these in `wrangler.toml` under `[vars]` or in the Cloudflare dashboard:
|
|
66
|
+
|
|
67
|
+
| Variable | Description | Required |
|
|
68
|
+
|----------|-------------|----------|
|
|
69
|
+
| `BETTER_AUTH_URL` | Public URL of your auth endpoint | Yes |
|
|
70
|
+
| `APP_NAME` | Application name (used in emails) | No |
|
|
71
|
+
|
|
72
|
+
### Email (Cloudflare Email Service — default)
|
|
73
|
+
|
|
74
|
+
Uses the Cloudflare `send_email` binding. No API keys needed — the binding is configured automatically in `wrangler.toml`.
|
|
75
|
+
|
|
76
|
+
| Variable | Description | Where |
|
|
77
|
+
|----------|-------------|-------|
|
|
78
|
+
| `EMAIL_FROM` | Sender email address | `[vars]` |
|
|
79
|
+
| `EMAIL_FROM_NAME` | Sender display name | `[vars]` |
|
|
80
|
+
| `APP_NAME` | Application name (used in templates) | `[vars]` |
|
|
81
|
+
|
|
82
|
+
The `EMAIL` binding is added to `wrangler.toml` automatically when using the `emailOtp` plugin.
|
|
83
|
+
|
|
84
|
+
### Email (AWS SES)
|
|
85
|
+
|
|
86
|
+
Required when using `email: { provider: 'aws-ses' }`:
|
|
87
|
+
|
|
88
|
+
| Variable | Description |
|
|
89
|
+
|----------|-------------|
|
|
90
|
+
| `AWS_ACCESS_KEY_ID` | AWS access key |
|
|
91
|
+
| `AWS_SECRET_ACCESS_KEY` | AWS secret key |
|
|
92
|
+
| `AWS_SES_REGION` | SES region (e.g., `us-east-2`) |
|
|
93
|
+
| `EMAIL_FROM` | Sender email address |
|
|
94
|
+
| `EMAIL_FROM_NAME` | Sender display name |
|
|
95
|
+
| `EMAIL_REPLY_TO` | Reply-to address |
|
|
96
|
+
|
|
97
|
+
### Drizzle Kit (Migrations)
|
|
98
|
+
|
|
99
|
+
For running remote migrations with `drizzle-kit`, set these in `.env`:
|
|
100
|
+
|
|
101
|
+
| Variable | Description |
|
|
102
|
+
|----------|-------------|
|
|
103
|
+
| `CLOUDFLARE_ACCOUNT_ID` | Your Cloudflare account ID |
|
|
104
|
+
| `CLOUDFLARE_API_TOKEN` | API token with D1 permissions |
|
|
105
|
+
| `CLOUDFLARE_AUTH_DATABASE_ID` | Auth D1 database ID (dual mode) |
|
|
106
|
+
| `CLOUDFLARE_FEATURES_DATABASE_ID` | Features D1 database ID (dual mode) |
|
|
107
|
+
| `CLOUDFLARE_AUDIT_DATABASE_ID` | Security audit D1 database ID (unsafe cross-tenant actions) |
|
|
108
|
+
| `CLOUDFLARE_DATABASE_ID` | Database ID (single DB mode) |
|
|
109
|
+
|
|
110
|
+
## Bun Variables
|
|
111
|
+
|
|
112
|
+
Set these in a `.env` file in your project root:
|
|
113
|
+
|
|
114
|
+
| Variable | Description | Default |
|
|
115
|
+
|----------|-------------|---------|
|
|
116
|
+
| `NODE_ENV` | Runtime environment | `development` |
|
|
117
|
+
| `PORT` | Server port | `3000` |
|
|
118
|
+
| `BETTER_AUTH_SECRET` | Auth encryption secret | — (required) |
|
|
119
|
+
| `BETTER_AUTH_URL` | Public URL of your server | `http://localhost:3000` |
|
|
120
|
+
| `DATABASE_PATH` | Path to SQLite file | `./data/app.db` |
|
|
121
|
+
|
|
122
|
+
## Turso (LibSQL) Variables
|
|
123
|
+
|
|
124
|
+
In addition to the Bun variables above:
|
|
125
|
+
|
|
126
|
+
| Variable | Description | Default |
|
|
127
|
+
|----------|-------------|---------|
|
|
128
|
+
| `DATABASE_URL` | LibSQL connection URL | `file:./data/app.db` |
|
|
129
|
+
| `DATABASE_AUTH_TOKEN` | Turso auth token (required for remote) | — |
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
# Local development
|
|
133
|
+
DATABASE_URL=file:./data/app.db
|
|
134
|
+
|
|
135
|
+
# Production (Turso cloud)
|
|
136
|
+
DATABASE_URL=libsql://your-db-slug.turso.io
|
|
137
|
+
DATABASE_AUTH_TOKEN=eyJhbGciOi...
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Social Login Providers
|
|
141
|
+
|
|
142
|
+
When social login is configured in your auth provider:
|
|
143
|
+
|
|
144
|
+
| Variable | Description |
|
|
145
|
+
|----------|-------------|
|
|
146
|
+
| `GOOGLE_CLIENT_ID` | Google OAuth client ID |
|
|
147
|
+
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
|
|
148
|
+
| `GITHUB_CLIENT_ID` | GitHub OAuth client ID |
|
|
149
|
+
| `GITHUB_CLIENT_SECRET` | GitHub OAuth client secret |
|
|
150
|
+
| `DISCORD_CLIENT_ID` | Discord OAuth client ID |
|
|
151
|
+
| `DISCORD_CLIENT_SECRET` | Discord OAuth client secret |
|
|
152
|
+
|
|
153
|
+
## See Also
|
|
154
|
+
|
|
155
|
+
- [Output Structure](/compiler/config/output) — Generated file structure
|
|
156
|
+
- [Providers](/compiler/config/providers) — Provider configuration reference
|
|
157
|
+
- [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Cloudflare setup guide
|