@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,455 @@
|
|
|
1
|
+
# Authentication Security
|
|
2
|
+
|
|
3
|
+
Quickback enforces secure authentication defaults out of the box. This page explains how cookie security, rate limiting, and cross-domain authentication work, plus how to configure them for your use case.
|
|
4
|
+
|
|
5
|
+
## Cookie Security
|
|
6
|
+
|
|
7
|
+
Quickback sets secure cookie defaults to protect against CSRF, XSS, and man-in-the-middle attacks.
|
|
8
|
+
|
|
9
|
+
### Default Attributes
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
auth: defineAuth("better-auth", {
|
|
13
|
+
advanced: {
|
|
14
|
+
defaultCookieAttributes: {
|
|
15
|
+
sameSite: 'lax', // CSRF protection
|
|
16
|
+
secure: true, // HTTPS only
|
|
17
|
+
httpOnly: true, // No JavaScript access
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
})
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**What each attribute does:**
|
|
24
|
+
|
|
25
|
+
| Attribute | Value | Purpose |
|
|
26
|
+
|-----------|-------|---------|
|
|
27
|
+
| `sameSite` | `lax` | Blocks cookies on cross-site POST requests (CSRF protection) |
|
|
28
|
+
| `secure` | `true` | Cookies only sent over HTTPS (prevents interception) |
|
|
29
|
+
| `httpOnly` | `true` | JavaScript cannot access cookies via `document.cookie` (XSS mitigation) |
|
|
30
|
+
|
|
31
|
+
### SameSite Options
|
|
32
|
+
|
|
33
|
+
- **`lax` (recommended)**: Blocks cross-site POST requests but allows top-level navigation. Best balance of security and usability.
|
|
34
|
+
- **`strict`**: Blocks cookies on all cross-site requests. More secure but may break legitimate flows (e.g., returning from payment provider).
|
|
35
|
+
- **`none`**: Allows all cross-site requests. Required for cross-domain authentication (requires `secure: true`).
|
|
36
|
+
|
|
37
|
+
### Development Override
|
|
38
|
+
|
|
39
|
+
For local development over HTTP, you can relax the `secure` flag:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
auth: defineAuth("better-auth", {
|
|
43
|
+
advanced: {
|
|
44
|
+
defaultCookieAttributes: {
|
|
45
|
+
sameSite: 'lax',
|
|
46
|
+
secure: process.env.NODE_ENV === 'production',
|
|
47
|
+
httpOnly: true,
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
})
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**Warning**: Never use `secure: false` in production.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Rate Limiting
|
|
58
|
+
|
|
59
|
+
Quickback includes per-IP rate limiting by default to protect against brute-force attacks and abuse.
|
|
60
|
+
|
|
61
|
+
### How It Works
|
|
62
|
+
|
|
63
|
+
**Rate limits are applied per IP address**, not globally:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
┌─────────────────────────────────────────────────┐
|
|
67
|
+
│ IP: 192.168.1.1 │
|
|
68
|
+
│ Endpoint: /sign-in/email │
|
|
69
|
+
│ Limit: 10 requests per 60 seconds │
|
|
70
|
+
│ │
|
|
71
|
+
│ Request 1-10: ✅ Allowed │
|
|
72
|
+
│ Request 11: ❌ 429 Too Many Requests │
|
|
73
|
+
│ After 60s: Counter resets to 0 │
|
|
74
|
+
└─────────────────────────────────────────────────┘
|
|
75
|
+
|
|
76
|
+
┌─────────────────────────────────────────────────┐
|
|
77
|
+
│ IP: 192.168.1.2 (different IP) │
|
|
78
|
+
│ Endpoint: /sign-in/email │
|
|
79
|
+
│ Independent counter: Not affected by 1.1 │
|
|
80
|
+
│ Starts at 0 │
|
|
81
|
+
└─────────────────────────────────────────────────┘
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Default Configuration
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
auth: defineAuth("better-auth", {
|
|
88
|
+
rateLimit: {
|
|
89
|
+
enabled: true,
|
|
90
|
+
window: 60, // 60 second window
|
|
91
|
+
max: 100, // 100 requests per IP per window
|
|
92
|
+
customRules: {
|
|
93
|
+
"/sign-in/email": { window: 60, max: 10 },
|
|
94
|
+
"/sign-in/social": { window: 60, max: 10 },
|
|
95
|
+
"/device/init": { window: 60, max: 5 },
|
|
96
|
+
"/device/poll": { window: 60, max: 30 },
|
|
97
|
+
"/device/token": { window: 60, max: 10 },
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
})
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Custom Rules by Endpoint
|
|
104
|
+
|
|
105
|
+
Set different limits based on endpoint sensitivity:
|
|
106
|
+
|
|
107
|
+
| Endpoint Type | Recommended Limit | Reasoning |
|
|
108
|
+
|---------------|-------------------|-----------|
|
|
109
|
+
| Sign-in | 10/min per IP | Prevent credential stuffing |
|
|
110
|
+
| Device codes | 5/min per IP | Prevent device code enumeration |
|
|
111
|
+
| Token exchange | 10/min per IP | Prevent token brute-force |
|
|
112
|
+
| Polling | 30/min per IP | Allow reasonable polling (every 2s) |
|
|
113
|
+
| General API | 100/min per IP | Balance abuse prevention and usability |
|
|
114
|
+
|
|
115
|
+
### Why Per-IP?
|
|
116
|
+
|
|
117
|
+
✅ **Per-IP** (what Quickback uses):
|
|
118
|
+
- Prevents single attacker from brute-forcing
|
|
119
|
+
- Doesn't penalize legitimate users when one IP is malicious
|
|
120
|
+
- Standard for auth endpoints
|
|
121
|
+
|
|
122
|
+
❌ **Global total** (not used):
|
|
123
|
+
- Would allow distributed attacks to succeed
|
|
124
|
+
- One attacker with many IPs could exhaust the limit for everyone
|
|
125
|
+
- Not effective for security
|
|
126
|
+
|
|
127
|
+
### Disabling Rate Limiting
|
|
128
|
+
|
|
129
|
+
Not recommended, but you can disable for testing:
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
rateLimit: {
|
|
133
|
+
enabled: process.env.NODE_ENV === 'production',
|
|
134
|
+
window: 60,
|
|
135
|
+
max: 1000, // Higher limit for development
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Cross-Domain Authentication
|
|
142
|
+
|
|
143
|
+
For applications spanning multiple subdomains (e.g., `account.example.com`, `api.example.com`, `dashboard.example.com`), Quickback provides dual-layer security.
|
|
144
|
+
|
|
145
|
+
### The Problem
|
|
146
|
+
|
|
147
|
+
Browsers restrict cookies to exact domains by default. If your auth API is at `api.example.com`, cookies won't be sent to `dashboard.example.com`.
|
|
148
|
+
|
|
149
|
+
### The Solution: Dual-Layer Protection
|
|
150
|
+
|
|
151
|
+
Quickback uses two complementary security layers:
|
|
152
|
+
|
|
153
|
+
#### 1. Cookie Domain (Browser-Level)
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
auth: defineAuth("better-auth", {
|
|
157
|
+
advanced: {
|
|
158
|
+
crossSubDomainCookies: {
|
|
159
|
+
enabled: true,
|
|
160
|
+
domain: 'example.com' // All *.example.com can access cookies
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
})
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
**Behavior**: Allows ALL subdomains to access the cookie (browser limitation per RFC 6265)
|
|
167
|
+
- Cannot selectively allow only specific subdomains
|
|
168
|
+
- All-or-nothing: either exact domain only, or all subdomains
|
|
169
|
+
|
|
170
|
+
#### 2. Trusted Origins (Application-Level)
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
auth: defineAuth("better-auth", {
|
|
174
|
+
trustedOrigins: [
|
|
175
|
+
'https://account.example.com',
|
|
176
|
+
'https://api.example.com',
|
|
177
|
+
'https://dashboard.example.com'
|
|
178
|
+
]
|
|
179
|
+
})
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
**Behavior**: Better Auth validates request origins before processing auth operations
|
|
183
|
+
- Granular whitelist of allowed origins
|
|
184
|
+
- Blocks requests from untrusted subdomains even if they have the cookie
|
|
185
|
+
- Prevents CSRF and unauthorized auth operations
|
|
186
|
+
|
|
187
|
+
### Security Model
|
|
188
|
+
|
|
189
|
+
```
|
|
190
|
+
┌─────────────────────────────────────────────────┐
|
|
191
|
+
│ Subdomain: evil.example.com │
|
|
192
|
+
│ Has Cookie: ✓ (via crossSubDomainCookies) │
|
|
193
|
+
│ In trustedOrigins: ✗ │
|
|
194
|
+
│ Result: REQUEST BLOCKED by Better Auth │
|
|
195
|
+
└─────────────────────────────────────────────────┘
|
|
196
|
+
|
|
197
|
+
┌─────────────────────────────────────────────────┐
|
|
198
|
+
│ Subdomain: account.example.com │
|
|
199
|
+
│ Has Cookie: ✓ (via crossSubDomainCookies) │
|
|
200
|
+
│ In trustedOrigins: ✓ │
|
|
201
|
+
│ Result: REQUEST ALLOWED │
|
|
202
|
+
└─────────────────────────────────────────────────┘
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Full Cross-Domain Configuration
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
import { defineAuth, defineConfig, defineDatabase, defineRuntime } from "@quickback/compiler";
|
|
209
|
+
|
|
210
|
+
export default defineConfig({
|
|
211
|
+
name: "my-saas",
|
|
212
|
+
providers: {
|
|
213
|
+
runtime: defineRuntime("cloudflare"),
|
|
214
|
+
database: defineDatabase("cloudflare-d1", {
|
|
215
|
+
vars: {
|
|
216
|
+
ACCOUNT_URL: "https://account.example.com",
|
|
217
|
+
BETTER_AUTH_URL: "https://api.example.com",
|
|
218
|
+
}
|
|
219
|
+
}),
|
|
220
|
+
auth: defineAuth("better-auth", {
|
|
221
|
+
emailAndPassword: { enabled: true },
|
|
222
|
+
plugins: ["organization"],
|
|
223
|
+
|
|
224
|
+
// Trusted origins (granular whitelist)
|
|
225
|
+
trustedOrigins: [
|
|
226
|
+
"https://account.example.com",
|
|
227
|
+
"https://api.example.com",
|
|
228
|
+
"https://dashboard.example.com",
|
|
229
|
+
"http://localhost:3000", // Development
|
|
230
|
+
],
|
|
231
|
+
|
|
232
|
+
// Cookie configuration
|
|
233
|
+
advanced: {
|
|
234
|
+
crossSubDomainCookies: {
|
|
235
|
+
enabled: true,
|
|
236
|
+
domain: "example.com",
|
|
237
|
+
},
|
|
238
|
+
defaultCookieAttributes: {
|
|
239
|
+
secure: true,
|
|
240
|
+
sameSite: "none", // Required for cross-domain
|
|
241
|
+
httpOnly: true,
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
})
|
|
245
|
+
}
|
|
246
|
+
})
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
**Important**: When using `sameSite: "none"`, you must also set `secure: true`. This is required by browsers.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Environment Variables
|
|
254
|
+
|
|
255
|
+
Set these in your Cloudflare Workers environment or `.env` file:
|
|
256
|
+
|
|
257
|
+
### Required
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
# Better Auth secret (minimum 32 characters)
|
|
261
|
+
BETTER_AUTH_SECRET=your-secret-key-min-32-chars
|
|
262
|
+
|
|
263
|
+
# Base URL for Better Auth endpoints
|
|
264
|
+
BETTER_AUTH_URL=https://api.example.com
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### Optional (Cross-Domain)
|
|
268
|
+
|
|
269
|
+
```bash
|
|
270
|
+
# Enable cross-subdomain cookies
|
|
271
|
+
CROSS_SUBDOMAIN_COOKIES=true
|
|
272
|
+
COOKIE_DOMAIN=example.com
|
|
273
|
+
|
|
274
|
+
# Trusted origins (comma-separated)
|
|
275
|
+
TRUSTED_ORIGINS=https://account.example.com,https://api.example.com
|
|
276
|
+
|
|
277
|
+
# CORS allowed origins (typically matches trustedOrigins)
|
|
278
|
+
ALLOWED_ORIGINS=https://account.example.com,https://api.example.com
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### Setting Secrets with Wrangler
|
|
282
|
+
|
|
283
|
+
For sensitive values like `BETTER_AUTH_SECRET`:
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
wrangler secret put BETTER_AUTH_SECRET
|
|
287
|
+
# Paste your secret when prompted
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
For non-secret vars, add to `wrangler.toml`:
|
|
291
|
+
|
|
292
|
+
```toml
|
|
293
|
+
[vars]
|
|
294
|
+
BETTER_AUTH_URL = "https://api.example.com"
|
|
295
|
+
CROSS_SUBDOMAIN_COOKIES = "false"
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## Security Best Practices
|
|
301
|
+
|
|
302
|
+
### Single Domain (Recommended)
|
|
303
|
+
|
|
304
|
+
For most applications, use exact domain cookies:
|
|
305
|
+
|
|
306
|
+
```ts
|
|
307
|
+
auth: defineAuth("better-auth", {
|
|
308
|
+
trustedOrigins: ["https://app.example.com"],
|
|
309
|
+
advanced: {
|
|
310
|
+
crossSubDomainCookies: {
|
|
311
|
+
enabled: false // Default: exact domain only
|
|
312
|
+
},
|
|
313
|
+
defaultCookieAttributes: {
|
|
314
|
+
sameSite: 'lax',
|
|
315
|
+
secure: true,
|
|
316
|
+
httpOnly: true,
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
})
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
**Benefits**:
|
|
323
|
+
- Maximum security (smallest cookie scope)
|
|
324
|
+
- No cross-subdomain attack surface
|
|
325
|
+
- Simpler configuration
|
|
326
|
+
|
|
327
|
+
### Multi-Subdomain (When Needed)
|
|
328
|
+
|
|
329
|
+
Only enable cross-subdomain cookies if you need SSO across multiple subdomains:
|
|
330
|
+
|
|
331
|
+
```ts
|
|
332
|
+
auth: defineAuth("better-auth", {
|
|
333
|
+
trustedOrigins: [
|
|
334
|
+
"https://account.example.com",
|
|
335
|
+
"https://dashboard.example.com",
|
|
336
|
+
],
|
|
337
|
+
advanced: {
|
|
338
|
+
crossSubDomainCookies: {
|
|
339
|
+
enabled: true,
|
|
340
|
+
domain: "example.com",
|
|
341
|
+
},
|
|
342
|
+
defaultCookieAttributes: {
|
|
343
|
+
sameSite: 'none', // Required for cross-domain
|
|
344
|
+
secure: true,
|
|
345
|
+
httpOnly: true,
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
})
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
**Security requirements**:
|
|
352
|
+
- Trust all subdomains equally (any compromised subdomain can steal cookies)
|
|
353
|
+
- Use separate root domains for untrusted services
|
|
354
|
+
- Always set `trustedOrigins` for granular control
|
|
355
|
+
|
|
356
|
+
### CORS vs Trusted Origins
|
|
357
|
+
|
|
358
|
+
These serve different purposes and should typically match:
|
|
359
|
+
|
|
360
|
+
| Setting | Purpose |
|
|
361
|
+
|---------|---------|
|
|
362
|
+
| `ALLOWED_ORIGINS` (CORS) | Controls which origins can make credentialed requests |
|
|
363
|
+
| `trustedOrigins` (Better Auth) | Validates origins for auth operations + prevents open redirects |
|
|
364
|
+
|
|
365
|
+
**Example**:
|
|
366
|
+
|
|
367
|
+
```ts
|
|
368
|
+
database: defineDatabase("cloudflare-d1", {
|
|
369
|
+
vars: {
|
|
370
|
+
ALLOWED_ORIGINS: "https://account.example.com,https://api.example.com"
|
|
371
|
+
}
|
|
372
|
+
}),
|
|
373
|
+
auth: defineAuth("better-auth", {
|
|
374
|
+
trustedOrigins: [
|
|
375
|
+
"https://account.example.com",
|
|
376
|
+
"https://api.example.com"
|
|
377
|
+
]
|
|
378
|
+
})
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
### Checklist
|
|
382
|
+
|
|
383
|
+
Before deploying to production:
|
|
384
|
+
|
|
385
|
+
- [ ] `BETTER_AUTH_SECRET` is set (minimum 32 random characters)
|
|
386
|
+
- [ ] `secure: true` is enabled (HTTPS only)
|
|
387
|
+
- [ ] `httpOnly: true` is enabled (XSS protection)
|
|
388
|
+
- [ ] `sameSite: 'lax'` or `'strict'` unless cross-domain required
|
|
389
|
+
- [ ] `trustedOrigins` includes only your domains
|
|
390
|
+
- [ ] `ALLOWED_ORIGINS` matches `trustedOrigins`
|
|
391
|
+
- [ ] Rate limiting is enabled (`rateLimit.enabled: true`)
|
|
392
|
+
- [ ] Custom rate limits set for sensitive endpoints
|
|
393
|
+
|
|
394
|
+
---
|
|
395
|
+
|
|
396
|
+
## Deployment Considerations
|
|
397
|
+
|
|
398
|
+
### Behind Proxy/Load Balancer
|
|
399
|
+
|
|
400
|
+
If your app is behind a proxy, ensure IP address headers are trusted:
|
|
401
|
+
|
|
402
|
+
```ts
|
|
403
|
+
auth: defineAuth("better-auth", {
|
|
404
|
+
autoDetectIpAddress: true, // Uses X-Forwarded-For or CF-Connecting-IP
|
|
405
|
+
})
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
**Cloudflare Workers**: IP automatically available via `CF-Connecting-IP` header
|
|
409
|
+
|
|
410
|
+
**Other proxies**: Configure to trust `X-Forwarded-For` or `X-Real-IP`
|
|
411
|
+
|
|
412
|
+
### Multiple Environments
|
|
413
|
+
|
|
414
|
+
Use environment variables to configure different settings per environment:
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
auth: defineAuth("better-auth", {
|
|
418
|
+
trustedOrigins: process.env.TRUSTED_ORIGINS?.split(',') || [],
|
|
419
|
+
advanced: {
|
|
420
|
+
crossSubDomainCookies: {
|
|
421
|
+
enabled: process.env.CROSS_SUBDOMAIN_COOKIES === 'true',
|
|
422
|
+
domain: process.env.COOKIE_DOMAIN,
|
|
423
|
+
},
|
|
424
|
+
defaultCookieAttributes: {
|
|
425
|
+
sameSite: process.env.COOKIE_SAMESITE || 'lax',
|
|
426
|
+
secure: process.env.NODE_ENV === 'production',
|
|
427
|
+
httpOnly: true,
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
})
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
**Development** (`.dev.vars`):
|
|
434
|
+
```bash
|
|
435
|
+
TRUSTED_ORIGINS=http://localhost:3000,http://localhost:5173
|
|
436
|
+
CROSS_SUBDOMAIN_COOKIES=false
|
|
437
|
+
COOKIE_SAMESITE=lax
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
**Production** (Wrangler secrets):
|
|
441
|
+
```bash
|
|
442
|
+
TRUSTED_ORIGINS=https://account.example.com,https://api.example.com
|
|
443
|
+
CROSS_SUBDOMAIN_COOKIES=true
|
|
444
|
+
COOKIE_DOMAIN=example.com
|
|
445
|
+
COOKIE_SAMESITE=none
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
---
|
|
449
|
+
|
|
450
|
+
## Further Reading
|
|
451
|
+
|
|
452
|
+
- [Better Auth: Cookies Documentation](https://www.better-auth.com/docs/concepts/cookies)
|
|
453
|
+
- [Better Auth: Security Guide](https://www.better-auth.com/docs/reference/security)
|
|
454
|
+
- [OWASP: Cross-Site Request Forgery Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
|
|
455
|
+
- [MDN: SameSite Cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Using Auth
|
|
2
|
+
|
|
3
|
+
This page covers how to use Better Auth in your Quickback Stack application — sign-in flows, session management, and working with organization context.
|
|
4
|
+
|
|
5
|
+
## Sign-In Flows
|
|
6
|
+
|
|
7
|
+
Better Auth supports multiple sign-in methods:
|
|
8
|
+
|
|
9
|
+
- **Email/Password** — Traditional credential-based authentication
|
|
10
|
+
- **Email OTP** — One-time passwords sent via email
|
|
11
|
+
- **Magic Links** — Passwordless email links
|
|
12
|
+
- **Passkeys** — WebAuthn biometric/hardware key authentication
|
|
13
|
+
|
|
14
|
+
## Session Handling
|
|
15
|
+
|
|
16
|
+
Sessions are stored in Cloudflare KV for fast edge-based lookups.
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
// Access the current session in a Hono route
|
|
20
|
+
app.get('/api/me', async (c) => {
|
|
21
|
+
const session = c.get('session');
|
|
22
|
+
const user = c.get('user');
|
|
23
|
+
return c.json({ user, session });
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Organization Context
|
|
28
|
+
|
|
29
|
+
When organizations are enabled, the current organization is available in the request context:
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
const orgId = c.get('session')?.activeOrganizationId;
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Related
|
|
36
|
+
|
|
37
|
+
- [Auth Overview](/stack/auth) — Setup and configuration
|
|
38
|
+
- [Auth Plugins](/stack/auth/plugins) — Available plugins
|
|
39
|
+
- [Auth Security](/stack/auth/security) — Security best practices
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# Actions
|
|
2
|
+
|
|
3
|
+
Actions are custom operations defined in your feature files (e.g., `approve`, `void`, `post`, `applyPayment`). The CMS renders them as clickable buttons with auto-generated input forms — no UI code required.
|
|
4
|
+
|
|
5
|
+
## Where Actions Appear
|
|
6
|
+
|
|
7
|
+
Actions show up in two places:
|
|
8
|
+
|
|
9
|
+
### Row Action Menu (Table Mode)
|
|
10
|
+
|
|
11
|
+
In Table mode, the three-dot menu on each row includes a section for custom actions. Actions are separated from standard operations (view, edit, delete) by a divider.
|
|
12
|
+
|
|
13
|
+
### Action Bar (Detail View)
|
|
14
|
+
|
|
15
|
+
In the record detail view, an "Actions" card displays all available actions as buttons. Each button shows the action name, and hovering reveals the description as a tooltip.
|
|
16
|
+
|
|
17
|
+
## Action Dialog
|
|
18
|
+
|
|
19
|
+
Clicking an action opens a modal dialog with:
|
|
20
|
+
|
|
21
|
+
1. **Header** — Action name with an icon (lightning bolt for standard, warning triangle for destructive, download for file responses)
|
|
22
|
+
2. **Description** — The action's description text
|
|
23
|
+
3. **Side effects warning** — If the action has `sideEffects: "sync"`, an amber warning banner appears: "This action has synchronous side effects (e.g., GL entries)."
|
|
24
|
+
4. **Confirmation step** — If the action has `cms.confirm`, a confirmation message appears before the input form
|
|
25
|
+
5. **Input fields** — Auto-generated from the action's `inputFields` schema
|
|
26
|
+
6. **Execute button** — Submits the action. Shows "Executing..." while in progress.
|
|
27
|
+
7. **Cancel button** — Closes the dialog without executing
|
|
28
|
+
|
|
29
|
+
### Input Field Types
|
|
30
|
+
|
|
31
|
+
The dialog generates the appropriate input control for each field:
|
|
32
|
+
|
|
33
|
+
| Zod Type | Input Control | Notes |
|
|
34
|
+
|----------|--------------|-------|
|
|
35
|
+
| `string` | Text input | Free-text entry |
|
|
36
|
+
| `number` | Number input | Step 0.01, supports decimals |
|
|
37
|
+
| `boolean` | Checkbox | With label text |
|
|
38
|
+
| `array<string>` | Text input | Comma-separated values, split on save |
|
|
39
|
+
|
|
40
|
+
Required fields are marked with a red asterisk. Default values from the schema are pre-filled.
|
|
41
|
+
|
|
42
|
+
### Example
|
|
43
|
+
|
|
44
|
+
Given this action definition:
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
actions: {
|
|
48
|
+
applyPayment: {
|
|
49
|
+
description: "Apply a payment to this invoice",
|
|
50
|
+
input: 'z.object({ amount: z.number(), reference: z.string().optional() })',
|
|
51
|
+
access: {
|
|
52
|
+
roles: ['admin', 'owner'],
|
|
53
|
+
record: { status: { equals: 'posted' } },
|
|
54
|
+
},
|
|
55
|
+
sideEffects: "sync",
|
|
56
|
+
cms: {
|
|
57
|
+
label: "Apply Payment",
|
|
58
|
+
icon: "dollar-sign",
|
|
59
|
+
confirm: "This will create GL entries. Continue?",
|
|
60
|
+
category: "payments",
|
|
61
|
+
successMessage: "Payment applied successfully",
|
|
62
|
+
order: 1,
|
|
63
|
+
},
|
|
64
|
+
},
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The CMS renders a dialog with:
|
|
69
|
+
|
|
70
|
+
- A number input for `amount` (required)
|
|
71
|
+
- A text input for `reference` (optional)
|
|
72
|
+
- A sync side effects warning
|
|
73
|
+
- A confirmation step with the custom message
|
|
74
|
+
- Only visible to admins and owners
|
|
75
|
+
- Only visible on records where `status === "posted"`
|
|
76
|
+
|
|
77
|
+
## Access Filtering
|
|
78
|
+
|
|
79
|
+
Actions are filtered based on two criteria:
|
|
80
|
+
|
|
81
|
+
### Role Check
|
|
82
|
+
|
|
83
|
+
The action's `access.roles` array is compared against the current user's role. If the user's role is not in the list, the action is hidden.
|
|
84
|
+
|
|
85
|
+
### Record Condition
|
|
86
|
+
|
|
87
|
+
The action's `access.record` conditions are evaluated against the current record's data. Supported conditions:
|
|
88
|
+
|
|
89
|
+
| Operator | Example | Meaning |
|
|
90
|
+
|----------|---------|---------|
|
|
91
|
+
| `equals` | `{ status: { equals: 'pending' } }` | Field must equal value |
|
|
92
|
+
| `notEquals` | `{ status: { notEquals: 'void' } }` | Field must not equal value |
|
|
93
|
+
| `in` | `{ status: { in: ['pending', 'draft'] } }` | Field must be one of values |
|
|
94
|
+
|
|
95
|
+
All conditions must pass for the action to be visible. This means "approve" actions naturally disappear after a record is approved, and "void" actions only appear on voidable records.
|
|
96
|
+
|
|
97
|
+
## CMS Metadata
|
|
98
|
+
|
|
99
|
+
Actions can include an optional `cms` property for enhanced CMS rendering. Actions without `cms` render with default behavior.
|
|
100
|
+
|
|
101
|
+
| Property | Type | Default | Purpose |
|
|
102
|
+
|----------|------|---------|---------|
|
|
103
|
+
| `label` | `string` | camelCase split | Display name override |
|
|
104
|
+
| `icon` | `string` | `"zap"` | Lucide icon name |
|
|
105
|
+
| `confirm` | `string \| boolean` | `false` | `true` = generic confirm, string = custom message |
|
|
106
|
+
| `destructive` | `boolean` | `false` | Red styling + requires confirmation |
|
|
107
|
+
| `category` | `string` | none | Group actions under a header |
|
|
108
|
+
| `hidden` | `boolean` | `false` | Hide from CMS entirely (API-only actions) |
|
|
109
|
+
| `successMessage` | `string` | none | Toast message after success |
|
|
110
|
+
| `onSuccess` | `"refresh" \| "redirect:list" \| "close"` | `"refresh"` | Behavior after successful execution |
|
|
111
|
+
| `order` | `number` | `0` | Sort priority (lower = first) |
|
|
112
|
+
|
|
113
|
+
### Example with CMS metadata
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
// features/invoices/actions/post.ts
|
|
117
|
+
import { z } from "zod";
|
|
118
|
+
import { defineAction } from "../.quickback/define-action";
|
|
119
|
+
|
|
120
|
+
export default defineAction({
|
|
121
|
+
description: "Post this invoice to accounts receivable",
|
|
122
|
+
input: z.object({}),
|
|
123
|
+
access: { roles: ["owner", "admin"], record: { status: { equals: "draft" } } },
|
|
124
|
+
sideEffects: "sync",
|
|
125
|
+
cms: {
|
|
126
|
+
label: "Post Invoice",
|
|
127
|
+
icon: "send",
|
|
128
|
+
confirm: "This will post the invoice to AR and create GL entries. Continue?",
|
|
129
|
+
category: "lifecycle",
|
|
130
|
+
successMessage: "Invoice posted successfully",
|
|
131
|
+
onSuccess: "refresh",
|
|
132
|
+
order: 1,
|
|
133
|
+
},
|
|
134
|
+
async execute({ db, record }) {
|
|
135
|
+
// ... post invoice
|
|
136
|
+
return { ok: true };
|
|
137
|
+
},
|
|
138
|
+
});
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Hiding API-only actions
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
// features/invoices/actions/internal-recalc.ts
|
|
145
|
+
import { z } from "zod";
|
|
146
|
+
import { defineAction } from "../.quickback/define-action";
|
|
147
|
+
|
|
148
|
+
export default defineAction({
|
|
149
|
+
description: "Recalculate internal totals",
|
|
150
|
+
input: z.object({}),
|
|
151
|
+
access: { roles: ["owner"] },
|
|
152
|
+
cms: { hidden: true }, // Never shown in CMS
|
|
153
|
+
async execute({ db, record }) {
|
|
154
|
+
// ... recalc totals
|
|
155
|
+
return { ok: true };
|
|
156
|
+
},
|
|
157
|
+
});
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Destructive Actions
|
|
161
|
+
|
|
162
|
+
Actions are styled as destructive when either:
|
|
163
|
+
|
|
164
|
+
- The action's `cms.destructive` is `true`
|
|
165
|
+
- The action is named `void` or `delete` (legacy fallback)
|
|
166
|
+
|
|
167
|
+
Destructive actions receive:
|
|
168
|
+
|
|
169
|
+
- **Red text** in the row action menu
|
|
170
|
+
- **Warning triangle icon** (unless overridden by `cms.icon`)
|
|
171
|
+
- **Red execute button** in the dialog (using `bg-destructive` styling)
|
|
172
|
+
- **Automatic confirmation step** (unless `cms.confirm` is explicitly `false`)
|
|
173
|
+
|
|
174
|
+
This provides a visual cue that the action has permanent consequences.
|
|
175
|
+
|
|
176
|
+
## Standalone Actions
|
|
177
|
+
|
|
178
|
+
Actions with `path:` set are standalone — not tied to a specific record. They appear in a separate section and don't receive a `recordId` when executed. The CMS passes `null` as the record ID for standalone actions.
|
|
179
|
+
|
|
180
|
+
## File Response Actions
|
|
181
|
+
|
|
182
|
+
Actions with `responseType: "file"` show a download icon instead of the lightning bolt. When executed, the response is treated as a file download rather than a JSON result.
|
|
183
|
+
|
|
184
|
+
## Execution Flow
|
|
185
|
+
|
|
186
|
+
1. User clicks action in row menu or action bar
|
|
187
|
+
2. Dialog opens with description, inputs, and warnings
|
|
188
|
+
3. If `cms.confirm` is set, user sees confirmation step first
|
|
189
|
+
4. User fills in required fields
|
|
190
|
+
5. User clicks "Execute" (or "Confirm" after confirmation step)
|
|
191
|
+
6. CMS calls `client.executeAction(table, actionName, recordId, input)`
|
|
192
|
+
7. On success: `cms.successMessage` shown as toast (if set), then `cms.onSuccess` behavior
|
|
193
|
+
8. On error: error message displayed in dialog
|
|
194
|
+
|
|
195
|
+
## Next Steps
|
|
196
|
+
|
|
197
|
+
- **[Security](/stack/cms/security)** — Access conditions and role-based access
|
|
198
|
+
- **[Table Views](/stack/cms/table-views)** — Where actions appear in the UI
|
|
199
|
+
- **[Schema Format Reference](/stack/cms/schema-format)** — ActionMeta type definition
|