@quickback-dev/cli 0.10.16 → 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,155 @@
|
|
|
1
|
+
# Upgrade Anonymous Plugin
|
|
2
|
+
|
|
3
|
+
`@quickback-dev/better-auth-upgrade-anonymous` provides a single endpoint to convert anonymous users into full authenticated users. It flips the `isAnonymous` flag, optionally updates email and name, and refreshes the session — no re-authentication required.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @quickback-dev/better-auth-upgrade-anonymous
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Configuration
|
|
12
|
+
|
|
13
|
+
Enable both the `anonymous` and `upgradeAnonymous` plugins:
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
auth: defineAuth("better-auth", {
|
|
17
|
+
plugins: ["anonymous", "upgradeAnonymous"],
|
|
18
|
+
})
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The plugin accepts optional configuration:
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
import { upgradeAnonymous } from "@quickback-dev/better-auth-upgrade-anonymous";
|
|
25
|
+
|
|
26
|
+
upgradeAnonymous({
|
|
27
|
+
emailConfigured: true, // Whether email delivery is available
|
|
28
|
+
requireEmailVerification: true, // Whether to require email verification
|
|
29
|
+
})
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
| Option | Default | Description |
|
|
33
|
+
|--------|---------|-------------|
|
|
34
|
+
| `emailConfigured` | `false` | When `true` and an email is provided, `emailVerified` is set based on `requireEmailVerification` |
|
|
35
|
+
| `requireEmailVerification` | `true` | When `true`, provided emails are marked unverified (requiring OTP). When `false`, emails are marked verified immediately |
|
|
36
|
+
|
|
37
|
+
> **Quickback Compiler**
|
|
38
|
+
>
|
|
39
|
+
> When using the Quickback compiler, these options are set automatically based on your SES environment variables. You don't need to configure them manually.
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
## Endpoint
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
POST /auth/v1/upgrade-anonymous
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Flow
|
|
49
|
+
|
|
50
|
+
1. Validates the user's session (returns `401` if not authenticated)
|
|
51
|
+
2. Checks if the user is already upgraded (returns success immediately if so)
|
|
52
|
+
3. If an email is provided, checks for duplicates (returns `400` if email is taken)
|
|
53
|
+
4. Updates `isAnonymous` to `false`, plus optional `email`, `name`, and `emailVerified` fields
|
|
54
|
+
5. Refreshes the session cookie with the updated user object
|
|
55
|
+
6. Returns the updated user, session, and `verificationRequired` flag
|
|
56
|
+
|
|
57
|
+
### Request
|
|
58
|
+
|
|
59
|
+
The body is optional. When provided, it accepts:
|
|
60
|
+
|
|
61
|
+
| Field | Type | Description |
|
|
62
|
+
|-------|------|-------------|
|
|
63
|
+
| `email` | `string` (email) | Optional. Real email to replace the anonymous placeholder |
|
|
64
|
+
| `name` | `string` | Optional. User's display name |
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Minimal — just upgrade, no email/name
|
|
68
|
+
curl -X POST https://api.example.com/auth/v1/upgrade-anonymous \
|
|
69
|
+
-H "Cookie: better-auth.session_token=..."
|
|
70
|
+
|
|
71
|
+
# With email and name
|
|
72
|
+
curl -X POST https://api.example.com/auth/v1/upgrade-anonymous \
|
|
73
|
+
-H "Cookie: better-auth.session_token=..." \
|
|
74
|
+
-H "Content-Type: application/json" \
|
|
75
|
+
-d '{"email": "jane@example.com", "name": "Jane"}'
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Response
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"success": true,
|
|
83
|
+
"verificationRequired": true,
|
|
84
|
+
"user": {
|
|
85
|
+
"id": "usr_abc123",
|
|
86
|
+
"email": "jane@example.com",
|
|
87
|
+
"isAnonymous": false
|
|
88
|
+
},
|
|
89
|
+
"session": {
|
|
90
|
+
"id": "sess_xyz",
|
|
91
|
+
"userId": "usr_abc123"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The `verificationRequired` field is `true` when all three conditions are met:
|
|
97
|
+
- An email was provided in the request body
|
|
98
|
+
- `emailConfigured` is `true` in plugin config
|
|
99
|
+
- `requireEmailVerification` is `true` in plugin config
|
|
100
|
+
|
|
101
|
+
When `verificationRequired` is `true`, the frontend should send a verification OTP and redirect the user to verify their email.
|
|
102
|
+
|
|
103
|
+
## How It Works
|
|
104
|
+
|
|
105
|
+
The plugin is designed to be flexible:
|
|
106
|
+
|
|
107
|
+
- **Minimal by default** — With no body, only changes `isAnonymous` from `true` to `false`
|
|
108
|
+
- **Optional email/name** — Can update email and name in the same request
|
|
109
|
+
- **Duplicate protection** — Rejects emails already associated with another account
|
|
110
|
+
- **Verification-aware** — Returns `verificationRequired` so the frontend knows whether to trigger OTP
|
|
111
|
+
- **Session preserved** — Same session ID, no re-authentication needed
|
|
112
|
+
- **Idempotent** — Calling on an already-upgraded user returns success immediately
|
|
113
|
+
|
|
114
|
+
## Typical Flows
|
|
115
|
+
|
|
116
|
+
### Passkey Signup (no email)
|
|
117
|
+
|
|
118
|
+
1. User creates anonymous session
|
|
119
|
+
2. User registers a passkey
|
|
120
|
+
3. App calls `POST /auth/v1/upgrade-anonymous` with no body
|
|
121
|
+
4. User is now a full user with passkey auth — no email on file
|
|
122
|
+
|
|
123
|
+
### Passkey Signup (with email)
|
|
124
|
+
|
|
125
|
+
1. User creates anonymous session
|
|
126
|
+
2. User registers a passkey
|
|
127
|
+
3. User optionally enters email/name on the email collection step
|
|
128
|
+
4. App calls `POST /auth/v1/upgrade-anonymous` with `{ email, name }`
|
|
129
|
+
5. If `verificationRequired`: app sends OTP, user verifies, then redirects to dashboard
|
|
130
|
+
6. Otherwise: user goes straight to dashboard
|
|
131
|
+
|
|
132
|
+
### Email Signup
|
|
133
|
+
|
|
134
|
+
1. User starts as anonymous (created via Better Auth's `anonymous` plugin)
|
|
135
|
+
2. User provides email/password through your UI (via combo auth or signup)
|
|
136
|
+
3. Your app calls `POST /auth/v1/upgrade-anonymous`
|
|
137
|
+
4. User is now a full user with the same ID and all their data intact
|
|
138
|
+
|
|
139
|
+
### Client Plugin
|
|
140
|
+
|
|
141
|
+
```typescript
|
|
142
|
+
import { upgradeAnonymousClient } from "@quickback-dev/better-auth-upgrade-anonymous/client";
|
|
143
|
+
|
|
144
|
+
const authClient = createAuthClient({
|
|
145
|
+
plugins: [upgradeAnonymousClient()],
|
|
146
|
+
});
|
|
147
|
+
|
|
148
|
+
// Upgrade the current anonymous user
|
|
149
|
+
await authClient.upgradeAnonymous();
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## See Also
|
|
153
|
+
|
|
154
|
+
- [Combo Auth Plugin](/stack/auth/plugins/combo-auth) — Combined magic link + OTP for collecting credentials
|
|
155
|
+
- [Auth Configuration](/compiler/config/providers) — Configuring auth plugins
|
|
@@ -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
|