@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,245 @@
|
|
|
1
|
+
# JWT Optimization
|
|
2
|
+
|
|
3
|
+
Quickback automatically optimizes authenticated API requests using JWT tokens. After the first request (which uses session cookies), subsequent requests skip the database entirely by sending a signed JWT that encodes the full auth context.
|
|
4
|
+
|
|
5
|
+
## How It Works
|
|
6
|
+
|
|
7
|
+
### Request Flow
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
First request (no JWT cached):
|
|
11
|
+
Browser → Cookie auth → 2 DB queries → Response + set-auth-token header
|
|
12
|
+
Browser caches JWT in localStorage
|
|
13
|
+
|
|
14
|
+
Subsequent requests (JWT cached):
|
|
15
|
+
Browser → Bearer JWT → Signature check only → Response (0 DB queries)
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### What's in the JWT
|
|
19
|
+
|
|
20
|
+
The JWT encodes everything needed for auth middleware:
|
|
21
|
+
|
|
22
|
+
| Claim | Description |
|
|
23
|
+
|-------|-------------|
|
|
24
|
+
| `sub` | User ID |
|
|
25
|
+
| `orgId` | Active organization ID |
|
|
26
|
+
| `role` | Organization membership role (`owner`, `admin`, `member`) |
|
|
27
|
+
| `userRole` | Global user role (when admin panel is enabled) |
|
|
28
|
+
| `email` | User email |
|
|
29
|
+
| `name` | User display name |
|
|
30
|
+
| `iat` | Issued-at timestamp |
|
|
31
|
+
| `exp` | Expiry (15 minutes from issue) |
|
|
32
|
+
|
|
33
|
+
### Signing
|
|
34
|
+
|
|
35
|
+
JWTs are signed with HMAC-SHA256 using your `BETTER_AUTH_SECRET`. No additional configuration is needed — this uses the same secret you already set for Better Auth.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Server-Side Validation
|
|
40
|
+
|
|
41
|
+
**Every authenticated API request is validated server-side before it reaches your handler.** There is no "trust the client" shortcut — the middleware runs full signature verification on each request.
|
|
42
|
+
|
|
43
|
+
Validation steps (in generated `src/middleware/auth.ts`):
|
|
44
|
+
|
|
45
|
+
1. Extract the `Authorization: Bearer <token>` header
|
|
46
|
+
2. Call `verifyJwt(token, BETTER_AUTH_SECRET)` from `src/lib/jwt.ts`
|
|
47
|
+
3. Decode header + payload, recompute the HMAC-SHA256 signature, and compare via `crypto.subtle.verify()` (constant-time — no timing-attack surface)
|
|
48
|
+
4. Check `exp` against the current time
|
|
49
|
+
5. On success: hydrate `AppContext` from claims (`sub`, `orgId`, `role`, `userRole`, `email`, `name`) — no DB query
|
|
50
|
+
6. On failure (bad signature, expired, malformed): **silently fall back** to Better Auth's session cookie auth; if that succeeds, mint a fresh JWT and return it in the `set-auth-token` response header
|
|
51
|
+
|
|
52
|
+
The Files worker (R2 uploads) performs the same verification using the shared secret — no network round-trip to the auth API for file operations.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Token Lifecycle
|
|
57
|
+
|
|
58
|
+
### Automatic Minting
|
|
59
|
+
|
|
60
|
+
When a request arrives without a JWT (or with an expired one), the auth middleware:
|
|
61
|
+
|
|
62
|
+
1. Authenticates via session cookie (existing Better Auth flow)
|
|
63
|
+
2. Signs a JWT with the full auth context
|
|
64
|
+
3. Returns it in the `set-auth-token` response header
|
|
65
|
+
|
|
66
|
+
The Quickback API client (`quickback-client.ts`) automatically captures this header and stores the JWT in `localStorage`.
|
|
67
|
+
|
|
68
|
+
### Re-minting on Org Switch
|
|
69
|
+
|
|
70
|
+
When a user switches organizations, the JWT must be re-minted because `orgId` and `role` change. The auth UI handles this automatically:
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
// This happens automatically in the org switcher
|
|
74
|
+
await authClient.organization.setActive({ organizationSlug: slug });
|
|
75
|
+
|
|
76
|
+
// Fetch fresh JWT with new org context
|
|
77
|
+
const res = await fetch('/api/v1/token', {
|
|
78
|
+
method: 'POST',
|
|
79
|
+
credentials: 'include',
|
|
80
|
+
});
|
|
81
|
+
const { token } = await res.json();
|
|
82
|
+
localStorage.setItem('bearer_token', token);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Invalidation on Role Changes
|
|
86
|
+
|
|
87
|
+
When an admin changes a user's role or removes them from an organization, the server broadcasts an `auth:token-invalidated` event via WebSocket. The client automatically clears the cached JWT, forcing the next request to fall back to session auth and mint a fresh token.
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
Admin changes user role
|
|
91
|
+
→ databaseHooks fires on member update
|
|
92
|
+
→ Broadcasts auth:token-invalidated via realtime
|
|
93
|
+
→ Client clears localStorage JWT
|
|
94
|
+
→ Next request uses session cookie → gets fresh JWT
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Expiry
|
|
98
|
+
|
|
99
|
+
JWTs expire after 15 minutes. This is a safety net — in practice, JWTs are re-minted well before expiry through the `set-auth-token` response header on session-fallback requests.
|
|
100
|
+
|
|
101
|
+
When a JWT expires or is invalid:
|
|
102
|
+
1. The middleware silently falls back to session cookie auth
|
|
103
|
+
2. A fresh JWT is minted and returned in the response header
|
|
104
|
+
3. The client stores the new JWT for subsequent requests
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Token Endpoint
|
|
109
|
+
|
|
110
|
+
`POST /api/v1/token` mints a fresh JWT from the current session. This endpoint goes through normal auth middleware, so the user must have a valid session cookie.
|
|
111
|
+
|
|
112
|
+
**Request:**
|
|
113
|
+
```bash
|
|
114
|
+
curl -X POST https://your-api.example.com/api/v1/token \
|
|
115
|
+
-H "Content-Type: application/json" \
|
|
116
|
+
--cookie "better-auth.session_token=..."
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
**Response:**
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"token": "eyJhbGciOiJIUzI1NiJ9..."
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Use this endpoint after operations that change auth context (like switching organizations) to get a JWT that reflects the new state.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Client Integration
|
|
131
|
+
|
|
132
|
+
### Quickback API Client
|
|
133
|
+
|
|
134
|
+
The `quickback-client.ts` API client handles JWT auth automatically:
|
|
135
|
+
|
|
136
|
+
- **Sends** the cached JWT as `Authorization: Bearer <token>` on every request
|
|
137
|
+
- **Captures** refreshed JWTs from `set-auth-token` response headers
|
|
138
|
+
- **Clears** the JWT on `401` responses (falls back to session cookie)
|
|
139
|
+
|
|
140
|
+
No additional client configuration is needed.
|
|
141
|
+
|
|
142
|
+
### Custom API Calls
|
|
143
|
+
|
|
144
|
+
If you make direct `fetch()` calls to your API (outside the Quickback client), include the JWT:
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
const jwt = localStorage.getItem('bearer_token');
|
|
148
|
+
|
|
149
|
+
const res = await fetch('https://your-api.example.com/api/v1/things', {
|
|
150
|
+
headers: {
|
|
151
|
+
'Authorization': `Bearer ${jwt}`,
|
|
152
|
+
'Content-Type': 'application/json',
|
|
153
|
+
},
|
|
154
|
+
credentials: 'include', // Fallback to session cookie if no JWT
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
// Capture refreshed token
|
|
158
|
+
const newToken = res.headers.get('set-auth-token');
|
|
159
|
+
if (newToken) {
|
|
160
|
+
localStorage.setItem('bearer_token', newToken);
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Sign Out
|
|
165
|
+
|
|
166
|
+
Clear the JWT on sign-out to prevent stale tokens:
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
localStorage.removeItem('bearer_token');
|
|
170
|
+
await authClient.signOut();
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Security
|
|
176
|
+
|
|
177
|
+
### Threat Model
|
|
178
|
+
|
|
179
|
+
| Threat | Mitigation |
|
|
180
|
+
|--------|------------|
|
|
181
|
+
| Token theft (XSS) | 15-minute expiry limits exposure window. `httpOnly` cookies protect the session. |
|
|
182
|
+
| Token replay | Short expiry + `set-auth-token` rotation on session fallback |
|
|
183
|
+
| Stale permissions | WebSocket `auth:token-invalidated` broadcast on role changes |
|
|
184
|
+
| Token forgery | HMAC-SHA256 signature verified with `BETTER_AUTH_SECRET` |
|
|
185
|
+
| Timing attacks | `crypto.subtle.verify()` provides constant-time comparison |
|
|
186
|
+
|
|
187
|
+
### Key Points
|
|
188
|
+
|
|
189
|
+
- JWTs are a **performance optimization**, not a replacement for session auth
|
|
190
|
+
- Session cookies remain the source of truth — JWTs are derived from them
|
|
191
|
+
- If a JWT is lost, stolen, or cleared, the system gracefully falls back to cookie auth
|
|
192
|
+
- No additional secrets or configuration needed — uses your existing `BETTER_AUTH_SECRET`
|
|
193
|
+
- The JWT contains no sensitive data beyond what's already in the auth context
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Files Worker
|
|
198
|
+
|
|
199
|
+
The files worker (for Cloudflare R2 file uploads) also supports JWT authentication. When a request includes a JWT `Authorization` header, the worker verifies it directly instead of calling back to the auth API — eliminating a network round-trip for file operations.
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## Relation to Better Auth's JWT Plugin
|
|
204
|
+
|
|
205
|
+
Quickback's JWT fast-path (documented above) is a **custom HMAC-SHA256 implementation**, separate from Better Auth's [`jwt` plugin](https://www.better-auth.com/docs/plugins/jwt). The distinction matters if you're comparing options.
|
|
206
|
+
|
|
207
|
+
### What Quickback ships by default
|
|
208
|
+
|
|
209
|
+
- Custom HMAC-SHA256 JWTs minted by the compiled API at `POST /api/v1/token`
|
|
210
|
+
- Payload includes `sub`, `orgId`, `role`, `userRole`, `email`, `name` — everything the middleware needs to reconstruct `AppContext` with zero DB queries
|
|
211
|
+
- Signed with `BETTER_AUTH_SECRET`
|
|
212
|
+
- Used by the generated auth middleware as a fast-path ahead of `getSession()`
|
|
213
|
+
|
|
214
|
+
### What Better Auth's JWT plugin gives you (opt-in)
|
|
215
|
+
|
|
216
|
+
Enable it with `plugins: ["jwt"]` in your auth config:
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
auth: defineAuth("better-auth", {
|
|
220
|
+
plugins: ["jwt"],
|
|
221
|
+
}),
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
You get:
|
|
225
|
+
- JWKS endpoint at `/auth/v1/jwks` for asymmetric public-key verification by external services
|
|
226
|
+
- BA's own `/auth/v1/token` endpoint (asymmetric-signed, EdDSA by default)
|
|
227
|
+
- Standard OIDC-style claims via BA's `definePayload` hook
|
|
228
|
+
|
|
229
|
+
### Why Quickback doesn't use BA's plugin internally
|
|
230
|
+
|
|
231
|
+
Better Auth's `definePayload` hook only receives `{ user }`. It cannot embed the active organization context (`orgId`, org-member `role`) that Quickback's Firewall and Access layers need. Without that context in the JWT, the middleware would have to do a DB lookup per request — defeating the whole point of the fast-path.
|
|
232
|
+
|
|
233
|
+
### When to enable BA's JWT plugin anyway
|
|
234
|
+
|
|
235
|
+
Turn it on if **external services** need to verify tokens without sharing `BETTER_AUTH_SECRET` — e.g. a third-party worker that wants to confirm a user's identity via JWKS. The BA-issued tokens won't have Quickback's org context, so they're useful for identity assertions, not for hitting the Quickback API directly.
|
|
236
|
+
|
|
237
|
+
Enabling BA's plugin does **not** change how the compiled API authenticates requests — the middleware keeps using the custom HMAC JWT regardless.
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Related
|
|
242
|
+
|
|
243
|
+
- [Auth Overview](/stack/auth) — Setup and configuration
|
|
244
|
+
- [Auth Security](/stack/auth/security) — Cookie security, rate limiting, CORS
|
|
245
|
+
- [API Keys](/stack/auth/api-keys) — Programmatic API access
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# AWS SES Plugin
|
|
2
|
+
|
|
3
|
+
`@quickback-dev/better-auth-aws-ses` is a Better Auth plugin that sends transactional emails via AWS SES. It handles AWS Signature V4 signing, HTML/text email templates, and rate limiting — designed to work in Cloudflare Workers (no Node.js `aws-sdk` dependency).
|
|
4
|
+
|
|
5
|
+
> **Cloudflare Email is the default.** As of the Cloudflare Email Sending public beta, the zero-config `send_email` binding is Quickback's default transport for Cloudflare deploys — no API keys, no SES setup. See [Email Configuration](/compiler/config#email-configuration). Use AWS SES when you need it (non-Cloudflare runtimes, existing SES infra, or specific deliverability/compliance requirements).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @quickback-dev/better-auth-aws-ses
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
This plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
|
|
14
|
+
|
|
15
|
+
## Email Types
|
|
16
|
+
|
|
17
|
+
The plugin handles 8 email types:
|
|
18
|
+
|
|
19
|
+
| Endpoint | When Sent |
|
|
20
|
+
|----------|-----------|
|
|
21
|
+
| `/ses/send-verification` | Signup email verification |
|
|
22
|
+
| `/ses/send-password-reset` | Password reset request |
|
|
23
|
+
| `/ses/send-magic-link` | Passwordless sign-in link |
|
|
24
|
+
| `/ses/send-otp` | One-time password code |
|
|
25
|
+
| `/ses/send-welcome` | Post-signup welcome email |
|
|
26
|
+
| `/ses/send-organization-invitation` | Team/org invite with role |
|
|
27
|
+
| Combo auth | Magic link + OTP in a single email |
|
|
28
|
+
| Delete account | Account deletion confirmation |
|
|
29
|
+
|
|
30
|
+
### Combo Auth Mode
|
|
31
|
+
|
|
32
|
+
When `useComboAuthEmail: true` is set, the plugin sends a single email that includes both a magic link button and an OTP code. Users can choose either method to authenticate.
|
|
33
|
+
|
|
34
|
+
## AWS Signature V4
|
|
35
|
+
|
|
36
|
+
The plugin signs requests to SES using AWS Signature V4 with the Web Crypto API (`crypto.subtle`), making it compatible with Cloudflare Workers without any AWS SDK dependency.
|
|
37
|
+
|
|
38
|
+
## Templates
|
|
39
|
+
|
|
40
|
+
Each email type has both HTML and plain text templates. Templates include:
|
|
41
|
+
|
|
42
|
+
- Responsive HTML layout with MSO (Microsoft Outlook) support
|
|
43
|
+
- Security warning banners for sensitive operations
|
|
44
|
+
- Fallback plain text versions for all email clients
|
|
45
|
+
- XSS prevention via HTML escaping and URL sanitization
|
|
46
|
+
|
|
47
|
+
## Configuration
|
|
48
|
+
|
|
49
|
+
### Server Plugin
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import { awsSESPlugin } from "@quickback-dev/better-auth-aws-ses";
|
|
53
|
+
|
|
54
|
+
const auth = betterAuth({
|
|
55
|
+
plugins: [
|
|
56
|
+
awsSESPlugin({
|
|
57
|
+
region: env.AWS_SES_REGION,
|
|
58
|
+
accessKeyId: env.AWS_ACCESS_KEY_ID,
|
|
59
|
+
secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
|
|
60
|
+
fromEmail: env.EMAIL_FROM,
|
|
61
|
+
fromName: env.EMAIL_FROM_NAME || "My App",
|
|
62
|
+
replyTo: env.EMAIL_REPLY_TO,
|
|
63
|
+
appName: env.APP_NAME || "My App",
|
|
64
|
+
appUrl: env.APP_URL,
|
|
65
|
+
useComboAuthEmail: true, // Optional: combine magic link + OTP
|
|
66
|
+
}),
|
|
67
|
+
],
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Client Plugin
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
import { awsSESClientPlugin } from "@quickback-dev/better-auth-aws-ses/client";
|
|
75
|
+
|
|
76
|
+
const authClient = createAuthClient({
|
|
77
|
+
plugins: [awsSESClientPlugin()],
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Required Environment Variables
|
|
82
|
+
|
|
83
|
+
| Variable | Description |
|
|
84
|
+
|----------|-------------|
|
|
85
|
+
| `AWS_ACCESS_KEY_ID` | AWS access key (use Wrangler secrets) |
|
|
86
|
+
| `AWS_SECRET_ACCESS_KEY` | AWS secret key (use Wrangler secrets) |
|
|
87
|
+
| `AWS_SES_REGION` | SES region (e.g., `us-east-2`) |
|
|
88
|
+
| `EMAIL_FROM` | Sender email address (must be SES-verified) |
|
|
89
|
+
|
|
90
|
+
## Optional Variables
|
|
91
|
+
|
|
92
|
+
| Variable | Description |
|
|
93
|
+
|----------|-------------|
|
|
94
|
+
| `EMAIL_FROM_NAME` | Sender display name |
|
|
95
|
+
| `EMAIL_REPLY_TO` | Reply-to address (defaults to `EMAIL_FROM`) |
|
|
96
|
+
| `APP_NAME` | Application name shown in email templates |
|
|
97
|
+
| `APP_URL` | Application URL for links in emails |
|
|
98
|
+
| `BETTER_AUTH_URL` | Auth API URL (for verification/reset links) |
|
|
99
|
+
|
|
100
|
+
## Rate Limiting
|
|
101
|
+
|
|
102
|
+
The plugin includes basic in-memory rate limiting per recipient:
|
|
103
|
+
|
|
104
|
+
- Configurable hourly and daily limits
|
|
105
|
+
- Per-recipient tracking
|
|
106
|
+
- For production, consider using an external store (Redis, KV)
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
awsSESPlugin({
|
|
110
|
+
// ...
|
|
111
|
+
rateLimit: {
|
|
112
|
+
maxEmailsPerHour: 10,
|
|
113
|
+
maxEmailsPerDay: 50,
|
|
114
|
+
},
|
|
115
|
+
})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Error Handling
|
|
119
|
+
|
|
120
|
+
- Email failures return `false` (don't throw) — signup/login flows continue even if email delivery fails
|
|
121
|
+
- Invalid or placeholder AWS credentials are detected at startup
|
|
122
|
+
- Detailed console logging for debugging delivery issues
|
|
123
|
+
|
|
124
|
+
## See Also
|
|
125
|
+
|
|
126
|
+
- [Combo Auth Plugin](/stack/auth/plugins/combo-auth) — Combined magic link + OTP authentication
|
|
127
|
+
- [Auth Configuration](/compiler/config/providers) — Configuring auth plugins
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Combo Auth Plugin
|
|
2
|
+
|
|
3
|
+
`@quickback-dev/better-auth-combo-auth` provides a combined authentication flow that sends both a magic link and an OTP code in a single email. Users can click the link (one-click) or enter the 6-digit OTP code — whichever is more convenient.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @quickback-dev/better-auth-combo-auth
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Server Setup
|
|
12
|
+
|
|
13
|
+
Add the plugin to your Better Auth configuration:
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { betterAuth } from "better-auth";
|
|
17
|
+
import { comboAuth } from "@quickback-dev/better-auth-combo-auth";
|
|
18
|
+
|
|
19
|
+
export const auth = betterAuth({
|
|
20
|
+
plugins: [
|
|
21
|
+
comboAuth({
|
|
22
|
+
sendComboAuth: async ({ email, otp, url }) => {
|
|
23
|
+
// Send email with both the magic link (url) and OTP code (otp)
|
|
24
|
+
await sendEmail({
|
|
25
|
+
to: email,
|
|
26
|
+
subject: "Sign in to My App",
|
|
27
|
+
html: `
|
|
28
|
+
<p>Click the link below to sign in:</p>
|
|
29
|
+
<a href="${url}">Sign in to My App</a>
|
|
30
|
+
<p>Or enter this code: <strong>${otp}</strong></p>
|
|
31
|
+
`,
|
|
32
|
+
});
|
|
33
|
+
},
|
|
34
|
+
}),
|
|
35
|
+
],
|
|
36
|
+
});
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Client Usage
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
import { createAuthClient } from "better-auth/client";
|
|
43
|
+
import { comboAuthClient } from "@quickback-dev/better-auth-combo-auth/client";
|
|
44
|
+
|
|
45
|
+
const authClient = createAuthClient({
|
|
46
|
+
plugins: [comboAuthClient()],
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
// Request authentication — sends email with link + OTP
|
|
50
|
+
await authClient.signIn.comboAuth({
|
|
51
|
+
email: "user@example.com",
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
// Verify with OTP code (if user enters it manually)
|
|
55
|
+
await authClient.signIn.comboAuth({
|
|
56
|
+
email: "user@example.com",
|
|
57
|
+
otp: "123456",
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## How It Works
|
|
62
|
+
|
|
63
|
+
1. User enters their email and requests sign-in
|
|
64
|
+
2. A single email is sent containing both a magic link and a 6-digit OTP
|
|
65
|
+
3. **Option A:** User clicks the magic link — authenticated immediately
|
|
66
|
+
4. **Option B:** User enters the OTP code — authenticated after verification
|
|
67
|
+
|
|
68
|
+
This provides the best of both worlds: convenience of magic links with the reliability of OTP codes (useful when magic links don't work well, e.g., opening email on a different device).
|
|
69
|
+
|
|
70
|
+
## See Also
|
|
71
|
+
|
|
72
|
+
- [Auth Plugins](/stack/auth/plugins) — All authentication plugin options
|
|
73
|
+
- [Upgrade Anonymous](/stack/auth/plugins/upgrade-anonymous) — Convert anonymous sessions to full accounts
|
|
74
|
+
- [AWS SES](/stack/auth/plugins/aws-ses) — Email delivery for auth flows
|