@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,78 @@
|
|
|
1
|
+
# Endpoints
|
|
2
|
+
|
|
3
|
+
The cloud compiler API is hosted at `https://compiler.quickback.dev`.
|
|
4
|
+
|
|
5
|
+
## Public (No Auth)
|
|
6
|
+
|
|
7
|
+
| Endpoint | Method | Description |
|
|
8
|
+
|----------|--------|-------------|
|
|
9
|
+
| `/health` | GET | Health check |
|
|
10
|
+
| `/templates` | GET | List available templates |
|
|
11
|
+
|
|
12
|
+
## Authenticated
|
|
13
|
+
|
|
14
|
+
| Endpoint | Method | Description |
|
|
15
|
+
|----------|--------|-------------|
|
|
16
|
+
| `/compile` | POST | Compile definitions into backend files |
|
|
17
|
+
|
|
18
|
+
The `/compile` endpoint requires either a session token (from `quickback login`) or an API key (via `QUICKBACK_API_KEY` header). See [Authentication](/compiler/cloud-compiler/authentication) for details.
|
|
19
|
+
|
|
20
|
+
## Environment Variables
|
|
21
|
+
|
|
22
|
+
| Variable | Description |
|
|
23
|
+
|----------|-------------|
|
|
24
|
+
| `QUICKBACK_API_KEY` | API key for authentication (alternative to `quickback login`) |
|
|
25
|
+
| `QUICKBACK_API_URL` | Override compiler API URL (default: `https://compiler.quickback.dev`) |
|
|
26
|
+
|
|
27
|
+
### Custom Compiler URL
|
|
28
|
+
|
|
29
|
+
Point the CLI to a different compiler (local or custom):
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
QUICKBACK_API_URL=http://localhost:3020 quickback compile
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
See [Local Compiler](/compiler/cloud-compiler/local-compiler) for running the compiler locally with Docker.
|
|
36
|
+
|
|
37
|
+
## Streaming Protocol (`POST /compile`)
|
|
38
|
+
|
|
39
|
+
By default `/compile` returns a single JSON response. If the request includes `Accept: text/event-stream`, the compiler upgrades to Server-Sent Events so the CLI can render progress while the build runs.
|
|
40
|
+
|
|
41
|
+
There are two stream protocol versions, negotiated via the `X-Quickback-Stream` request header:
|
|
42
|
+
|
|
43
|
+
| Header | Protocol | Behavior |
|
|
44
|
+
|--------|----------|----------|
|
|
45
|
+
| _(absent)_ | **v1** | Sends `progress` events during the build, then a single `result` event with the entire compilation payload (config, generated files, drizzle output, SPA bundles, etc.) JSON-encoded as one frame. |
|
|
46
|
+
| `X-Quickback-Stream: v2` | **v2 (chunked)** | Sends `progress` events during the build, then a `meta` event with the file count, then one `file` event per generated file, then a final `done` event with metadata, commands, and warnings. |
|
|
47
|
+
|
|
48
|
+
The server echoes the chosen version back as the response `X-Quickback-Stream` header so the CLI knows which framing to parse.
|
|
49
|
+
|
|
50
|
+
### Why v2
|
|
51
|
+
|
|
52
|
+
Multi-megabyte SPA bundles (CMS + Account, with sourcemaps) take long enough to `JSON.stringify` that the v1 single-frame `result` event blocks Cloudflare's container event loop. Two things break: Docker's `HEALTHCHECK` fails, and the CLI's 120-second connection timeout fires before the body flushes. v2 emits files one at a time and yields back to the event loop every 10 files (`setImmediate`), keeping `/health` responsive and TCP backpressure alive.
|
|
53
|
+
|
|
54
|
+
The `@quickback-dev/cli` v0.10.x and later send `X-Quickback-Stream: v2` automatically. v1 is preserved for older clients.
|
|
55
|
+
|
|
56
|
+
### Event shapes (v2)
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
event: progress
|
|
60
|
+
data: { "stage": "vite-cms", "message": "..." }
|
|
61
|
+
|
|
62
|
+
event: meta
|
|
63
|
+
data: { "fileCount": 412, "version": "0.10.3" }
|
|
64
|
+
|
|
65
|
+
event: file
|
|
66
|
+
data: { "path": "src/...", "content": "...", ... }
|
|
67
|
+
…
|
|
68
|
+
|
|
69
|
+
event: done
|
|
70
|
+
data: { "meta": {...}, "commands": [...], "warnings": [...] }
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
On failure, an `error` event is emitted in either protocol:
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
event: error
|
|
77
|
+
data: { "error": "Compilation failed", "code": "...", "message": "..." }
|
|
78
|
+
```
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Cloud Compiler
|
|
2
|
+
|
|
3
|
+
Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI uses it to turn your definitions into a complete backend.
|
|
4
|
+
|
|
5
|
+
## How It Works
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
┌──────────────┐ ┌──────────────────────┐
|
|
9
|
+
│ quickback │ POST │ compiler.quickback │
|
|
10
|
+
│ CLI │────────▶│ .dev/compile │
|
|
11
|
+
│ │ │ │
|
|
12
|
+
│ Sends: │ │ Returns: │
|
|
13
|
+
│ - config │ │ - Hono routes │
|
|
14
|
+
│ - features │◀────────│ - Drizzle migrations │
|
|
15
|
+
│ - meta │ │ - TypeScript SDK │
|
|
16
|
+
└──────────────┘ └──────────────────────┘
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
1. The CLI reads your `quickback.config.ts` and feature definitions.
|
|
20
|
+
2. It sends them to the cloud compiler as a JSON payload.
|
|
21
|
+
3. The compiler generates all backend files (routes, migrations, SDK, OpenAPI spec).
|
|
22
|
+
4. The CLI writes the generated files to your project.
|
|
23
|
+
|
|
24
|
+
## Quick Start
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# 1. Install the CLI
|
|
28
|
+
npm install -g @quickback-dev/cli
|
|
29
|
+
|
|
30
|
+
# 2. Create a project
|
|
31
|
+
quickback create cloudflare my-app
|
|
32
|
+
cd my-app
|
|
33
|
+
|
|
34
|
+
# 3. Log in
|
|
35
|
+
quickback login
|
|
36
|
+
|
|
37
|
+
# 4. Compile
|
|
38
|
+
quickback compile
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Existing Databases
|
|
42
|
+
|
|
43
|
+
When recompiling an existing project, the CLI automatically sends your Drizzle meta files so the compiler generates **incremental** migrations instead of fresh `CREATE TABLE` statements.
|
|
44
|
+
|
|
45
|
+
Meta files are loaded from `<project>/quickback/drizzle/` only — Quickback owns this state and never reads from a project-root `drizzle/` folder:
|
|
46
|
+
- `quickback/drizzle/auth/meta/`
|
|
47
|
+
- `quickback/drizzle/features/meta/`
|
|
48
|
+
- `quickback/drizzle/files/meta/`
|
|
49
|
+
- `quickback/drizzle/webhooks/meta/`
|
|
50
|
+
- `quickback/drizzle/audit/meta/`
|
|
51
|
+
- `quickback/drizzle/meta/` (single-database mode)
|
|
52
|
+
|
|
53
|
+
Migration and report artifacts are written to the `quickback/` state directory:
|
|
54
|
+
- `quickback/drizzle/...` for Drizzle migration SQL/meta artifacts
|
|
55
|
+
- `quickback/reports/...` for security contract report artifacts
|
|
56
|
+
|
|
57
|
+
No extra configuration needed — the CLI handles this automatically.
|
|
58
|
+
|
|
59
|
+
## Next Steps
|
|
60
|
+
|
|
61
|
+
- [CLI Reference](/compiler/cloud-compiler/cli) — All CLI commands
|
|
62
|
+
- [Authentication](/compiler/cloud-compiler/authentication) — Login flow and API keys
|
|
63
|
+
- [Endpoints](/compiler/cloud-compiler/endpoints) — Compiler API reference
|
|
64
|
+
- [Troubleshooting](/compiler/cloud-compiler/troubleshooting) — Common issues
|
|
65
|
+
- [Local Compiler](/compiler/cloud-compiler/local-compiler) — Run the compiler locally
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Local Compiler
|
|
2
|
+
|
|
3
|
+
Run the Quickback compiler locally using Docker. The local compiler uses the exact same Docker image as the cloud compiler, ensuring identical behavior — including SPA builds with correct environment variables.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- Docker Desktop installed and running
|
|
8
|
+
- Quickback monorepo cloned locally
|
|
9
|
+
- Authenticated via `quickback login`
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
From the monorepo root:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
cd apps/compiler-local && bash dev.sh
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
This will:
|
|
20
|
+
1. Ensure Docker Desktop is running
|
|
21
|
+
2. Stop any existing compiler container
|
|
22
|
+
3. Build the Docker image from `apps/compiler/Dockerfile`
|
|
23
|
+
4. Run it on port 3000
|
|
24
|
+
|
|
25
|
+
### Custom Port
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
bash dev.sh 3001
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Compiling a Project
|
|
32
|
+
|
|
33
|
+
Point the CLI to your local compiler:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
QUICKBACK_API_URL=http://localhost:3000 quickback compile
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Or export it for the session:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
export QUICKBACK_API_URL=http://localhost:3000
|
|
43
|
+
quickback compile
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Authentication is always required. Run `quickback login` first if you haven't already.
|
|
47
|
+
|
|
48
|
+
## Manual Build & Run
|
|
49
|
+
|
|
50
|
+
You can also build and run the Docker image directly from the monorepo root:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
# Build
|
|
54
|
+
docker build -t quickback-compiler -f apps/compiler/Dockerfile .
|
|
55
|
+
|
|
56
|
+
# Run
|
|
57
|
+
docker run --rm -p 3000:3000 quickback-compiler
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Verify
|
|
61
|
+
|
|
62
|
+
Check the compiler is running:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
curl http://localhost:3000/health
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## How It Works
|
|
69
|
+
|
|
70
|
+
The Docker image includes:
|
|
71
|
+
- Pre-installed dependencies for compiled projects (`/deps/node_modules`)
|
|
72
|
+
- CMS and Account SPA source code (`/spa/cms/`, `/spa/account/`)
|
|
73
|
+
- Pre-installed SPA dependencies (`/spa-deps/cms/`, `/spa-deps/account/`)
|
|
74
|
+
|
|
75
|
+
When compiling a project with `cms: true` or `account: true`, the compiler builds the SPAs from source inside the container with the correct Vite environment variables (e.g., `VITE_QUICKBACK_API_URL`, `VITE_QUICKBACK_ACCOUNT_URL`). This ensures each project gets properly configured SPA assets without manual intervention.
|
|
76
|
+
|
|
77
|
+
## Deploying to Cloud
|
|
78
|
+
|
|
79
|
+
After making changes to the compiler, deploy to `compiler.quickback.dev`:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
cd apps/compiler-cloud && bash deploy.sh
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Troubleshooting
|
|
86
|
+
|
|
87
|
+
### Container not starting
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
docker logs quickback-compiler-local
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Port already in use
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
# Find what's using the port
|
|
97
|
+
lsof -i :3000
|
|
98
|
+
|
|
99
|
+
# Use a different port
|
|
100
|
+
bash dev.sh 3001
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Docker out of disk space
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
docker system prune -af
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### SPA build warnings
|
|
110
|
+
|
|
111
|
+
If you see SPA build warnings during compilation, ensure the SPA dependency files are up to date:
|
|
112
|
+
- `apps/compiler/deps-spa-cms-package.json`
|
|
113
|
+
- `apps/compiler/deps-spa-account-package.json`
|
|
114
|
+
|
|
115
|
+
These must include all dependencies from `packages/cms/package.json` and `packages/account/package.json` respectively.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
## 401 Unauthorized
|
|
4
|
+
|
|
5
|
+
Your session may have expired (sessions last 7 days). Re-authenticate:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
quickback logout
|
|
9
|
+
quickback login
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Compilation timeout
|
|
13
|
+
|
|
14
|
+
Large projects may take longer to compile. The cloud compiler uses [Cloudflare Containers](https://developers.cloudflare.com/containers/) to run compilation in isolated environments. If you hit timeouts, try [running the compiler locally](/compiler/cloud-compiler/local-compiler).
|
|
15
|
+
|
|
16
|
+
## "Command not found: quickback"
|
|
17
|
+
|
|
18
|
+
Make sure the CLI is installed globally:
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g @quickback-dev/cli
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Or use npx:
|
|
24
|
+
```bash
|
|
25
|
+
npx @quickback-dev/cli create cloudflare my-app
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Compile errors
|
|
29
|
+
|
|
30
|
+
1. Check your `quickback.config.ts` exists and is valid
|
|
31
|
+
2. Ensure all tables in `quickback/features/` have valid exports
|
|
32
|
+
3. Run `quickback compile` with `--verbose` for detailed output
|
|
33
|
+
|
|
34
|
+
## Drizzle rename prompts in CI/headless compile
|
|
35
|
+
|
|
36
|
+
If compilation fails with an interactive Drizzle message like:
|
|
37
|
+
|
|
38
|
+
- `drizzle-kit requested interactive rename input, but Quickback compile is running headless`
|
|
39
|
+
- `Missing rename hint for table/column ...`
|
|
40
|
+
|
|
41
|
+
then add explicit rename hints in `quickback.config.ts`:
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
export default defineConfig({
|
|
45
|
+
// ...
|
|
46
|
+
compiler: {
|
|
47
|
+
migrations: {
|
|
48
|
+
renames: {
|
|
49
|
+
tables: {
|
|
50
|
+
events_v2: "events",
|
|
51
|
+
},
|
|
52
|
+
columns: {
|
|
53
|
+
events: {
|
|
54
|
+
summary_text: "summary",
|
|
55
|
+
},
|
|
56
|
+
},
|
|
57
|
+
},
|
|
58
|
+
},
|
|
59
|
+
},
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`tables` and `columns` mappings are always `new_name -> old_name`.
|
|
64
|
+
|
|
65
|
+
If a hint is missing, compile now fails loudly with the exact key path to add, for example:
|
|
66
|
+
|
|
67
|
+
- `Expected hint key: compiler.migrations.renames.tables["events_v2"]`
|
|
68
|
+
- `Expected hint key: compiler.migrations.renames.columns["events"]["summary_text"]`
|
|
69
|
+
|
|
70
|
+
## "Could not load organizations"
|
|
71
|
+
|
|
72
|
+
This can happen if your session token expired or if the API is temporarily unavailable. Re-login:
|
|
73
|
+
```bash
|
|
74
|
+
quickback logout
|
|
75
|
+
quickback login
|
|
76
|
+
```
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# AI Agent Readiness
|
|
2
|
+
|
|
3
|
+
Every compiled Quickback Worker advertises itself to AI agents and MCP clients — no user wiring required. One config flag controls the whole discovery surface.
|
|
4
|
+
|
|
5
|
+
## What the compiler generates
|
|
6
|
+
|
|
7
|
+
When `agents` is enabled (the default), the Worker serves:
|
|
8
|
+
|
|
9
|
+
| Route | What it is |
|
|
10
|
+
|-------|-----------|
|
|
11
|
+
| `GET /robots.txt` | AI-bot policy with the [Cloudflare Content Signals](https://developers.cloudflare.com/bots/concepts/content-signals/) preamble and explicit `Allow:` rules for GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, Applebot-Extended, Bytespider, MistralAI, Cohere, DuckAssist. |
|
|
12
|
+
| `GET /llms.txt` | Agent-facing summary of the API — project name, authentication, resource list, endpoint conventions — derived from your own config. |
|
|
13
|
+
| `GET /.well-known/oauth-protected-resource` | [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) metadata declaring this Worker as a protected resource. |
|
|
14
|
+
| `GET /.well-known/oauth-authorization-server` | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) metadata pointing at the sign-in and token endpoints. |
|
|
15
|
+
| `GET /.well-known/api-catalog` | [RFC 9727](https://datatracker.ietf.org/doc/html/rfc9727) catalog linking at `/openapi.json`. |
|
|
16
|
+
| `GET /.well-known/mcp.json` | MCP Server Card — discoverable metadata for the MCP server below. |
|
|
17
|
+
| `POST /mcp` | Auto-generated MCP-over-HTTP server. One tool per OpenAPI operation, JWT auth forwarded through the same middleware as the REST API. |
|
|
18
|
+
|
|
19
|
+
## Default behavior
|
|
20
|
+
|
|
21
|
+
```ts title="quickback.config.ts"
|
|
22
|
+
import { defineConfig } from '@quickback/compiler';
|
|
23
|
+
|
|
24
|
+
export default defineConfig({
|
|
25
|
+
name: 'my-api',
|
|
26
|
+
// …
|
|
27
|
+
// agents: true is the default — no need to write it.
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Run `quickback compile` and every endpoint above ships in the Worker.
|
|
32
|
+
|
|
33
|
+
## Opting out
|
|
34
|
+
|
|
35
|
+
```ts title="quickback.config.ts"
|
|
36
|
+
export default defineConfig({
|
|
37
|
+
// …
|
|
38
|
+
agents: false, // disables everything
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Fine-grained control
|
|
43
|
+
|
|
44
|
+
Pass an object to toggle individual surfaces:
|
|
45
|
+
|
|
46
|
+
```ts title="quickback.config.ts"
|
|
47
|
+
export default defineConfig({
|
|
48
|
+
// …
|
|
49
|
+
agents: {
|
|
50
|
+
robotsTxt: true, // default
|
|
51
|
+
llmsTxt: true, // default
|
|
52
|
+
mcp: true, // default
|
|
53
|
+
oauthDiscovery: true, // default
|
|
54
|
+
apiCatalog: true, // default
|
|
55
|
+
allowAiCrawlers: true, // default — flip to false to Disallow in robots.txt
|
|
56
|
+
},
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## The MCP server
|
|
61
|
+
|
|
62
|
+
### Tools
|
|
63
|
+
|
|
64
|
+
Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a flat JSON Schema combining path params, query params, and the request body.
|
|
65
|
+
|
|
66
|
+
`tools/call` re-enters the same Hono app via `app.request(...)` — so **every existing middleware runs exactly as it would for a direct REST call**: authentication, firewall, access control, guards, masking. No bypass.
|
|
67
|
+
|
|
68
|
+
### Access-filtered `tools/list`
|
|
69
|
+
|
|
70
|
+
`tools/list` only returns tools the calling identity could actually invoke. Each generated tool entry carries the operation's access metadata (`roles`, `userRole`, `or` / `and` combinators) and `tools/list` filters against `ctx` before responding:
|
|
71
|
+
|
|
72
|
+
- **Unauthenticated callers** see only tools whose access declares the `PUBLIC` pseudo-role, or operations that have no security requirement at all (e.g. sign-in / sign-up).
|
|
73
|
+
- **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Admin-only endpoints don't appear for non-admins.
|
|
74
|
+
- **Function-form access** (escape hatch) is opaque at list time — surfaced to any authenticated caller, then evaluated for real on `tools/call`.
|
|
75
|
+
- **Record predicates** are dropped from the list-time check (no record yet) and applied normally on the actual call.
|
|
76
|
+
|
|
77
|
+
This is recon-mitigation, not a security boundary. Hiding a tool from the list never weakens the underlying gate — `tools/call` still runs the full middleware chain and rejects unauthorized invocations the same way a direct REST call would.
|
|
78
|
+
|
|
79
|
+
The unauthenticated `GET /mcp` discovery payload returns server info only; it does **not** enumerate tool names. Inventory is exclusively available via the access-filtered `tools/list`.
|
|
80
|
+
|
|
81
|
+
### Authentication
|
|
82
|
+
|
|
83
|
+
MCP clients pass their credentials through the standard `Authorization: Bearer <jwt>` header. The generated MCP handler forwards the header verbatim into the internal request, and the same JWT middleware that guards `/api/v1/*` validates it.
|
|
84
|
+
|
|
85
|
+
Mint a JWT from an authenticated session:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
curl -X POST https://my-api.example.com/api/v1/token \
|
|
89
|
+
-H "Cookie: better-auth.session_token=..." \
|
|
90
|
+
-H "Content-Type: application/json"
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Connecting clients
|
|
94
|
+
|
|
95
|
+
**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"mcpServers": {
|
|
100
|
+
"my-api": {
|
|
101
|
+
"url": "https://my-api.example.com/mcp",
|
|
102
|
+
"headers": {
|
|
103
|
+
"Authorization": "Bearer <jwt>"
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Cursor** — use the same config shape under `.cursor/mcp.json`.
|
|
111
|
+
|
|
112
|
+
**Quick sanity check with curl:**
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
# List available tools
|
|
116
|
+
curl -X POST https://my-api.example.com/mcp \
|
|
117
|
+
-H "Authorization: Bearer $JWT" \
|
|
118
|
+
-H "Content-Type: application/json" \
|
|
119
|
+
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
|
|
120
|
+
|
|
121
|
+
# Call a tool
|
|
122
|
+
curl -X POST https://my-api.example.com/mcp \
|
|
123
|
+
-H "Authorization: Bearer $JWT" \
|
|
124
|
+
-H "Content-Type: application/json" \
|
|
125
|
+
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"listCustomers","arguments":{"limit":10}}}'
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Transport
|
|
129
|
+
|
|
130
|
+
The server speaks the **Streamable HTTP** MCP transport — JSON-RPC 2.0 over `POST`. A plain `GET /mcp` returns the server info document for sanity checks.
|
|
131
|
+
|
|
132
|
+
The MCP route does **not** emit its own CORS headers. The Worker's existing `cors()` middleware applies uniformly, so browser-origin access is governed by the same allowlist as the rest of the API (`auth.trustedOrigins` + the deploy origin). Server-to-server clients (Claude Desktop, Cursor, MCP Inspector) connect with a Bearer token and don't need browser CORS at all. If you want a browser-based MCP client (ChatGPT, Claude.ai) to connect cross-origin, add its origin to `auth.trustedOrigins` like any other web client.
|
|
133
|
+
|
|
134
|
+
## Verification
|
|
135
|
+
|
|
136
|
+
After you deploy, scan both the REST and MCP surfaces:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
# Agent-readiness scan (external)
|
|
140
|
+
open https://isitagentready.com/?url=https://my-api.example.com
|
|
141
|
+
|
|
142
|
+
# MCP Inspector (official tool)
|
|
143
|
+
npx @modelcontextprotocol/inspector https://my-api.example.com/mcp
|
|
144
|
+
```
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Auth & JWT
|
|
2
|
+
|
|
3
|
+
The top-level `auth` config block holds provider-agnostic auth knobs that affect how Quickback emits the auth middleware, JWT helpers, and access-rule expansion.
|
|
4
|
+
|
|
5
|
+
```ts title="quickback.config.ts"
|
|
6
|
+
export default defineConfig({
|
|
7
|
+
// ...
|
|
8
|
+
auth: {
|
|
9
|
+
roleHierarchy: ['member', 'admin', 'owner'],
|
|
10
|
+
jwt: {
|
|
11
|
+
expiresIn: 60,
|
|
12
|
+
issuer: 'my-api',
|
|
13
|
+
// audience, secretEnv, algorithm, revocationCheck...
|
|
14
|
+
},
|
|
15
|
+
},
|
|
16
|
+
});
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## `auth.roleHierarchy`
|
|
20
|
+
|
|
21
|
+
Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to mean "this role and above". Documented in detail under [Access — Role hierarchy](/compiler/definitions/access#role-hierarchy).
|
|
22
|
+
|
|
23
|
+
## `auth.jwt` — JWT bearer-token fast-path
|
|
24
|
+
|
|
25
|
+
Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
|
|
26
|
+
|
|
27
|
+
### Behavior recap
|
|
28
|
+
|
|
29
|
+
1. The browser SPA gets a JWT via the `set-auth-token` response header on every authenticated call.
|
|
30
|
+
2. On subsequent requests the SPA sends `Authorization: Bearer <jwt>`.
|
|
31
|
+
3. The auth middleware's **fast-path** verifies the signature only — no DB query, no session lookup. `AppContext` is reconstructed from JWT claims.
|
|
32
|
+
4. If verification fails (or no JWT is present), the middleware falls back to session auth.
|
|
33
|
+
5. After successful session auth, a fresh JWT is minted and returned via `set-auth-token`. The cycle continues.
|
|
34
|
+
|
|
35
|
+
The fast-path is intentionally stateless: it trusts the claims for the full TTL. **Stolen or pre-revocation tokens are valid until they expire.** That's the trade-off the fast-path makes — and the reason `expiresIn` is the most-tuned knob below.
|
|
36
|
+
|
|
37
|
+
### `expiresIn?: number` — TTL in seconds
|
|
38
|
+
|
|
39
|
+
Default `180` (3 minutes).
|
|
40
|
+
|
|
41
|
+
Lowering this shrinks the worst-case window where a stolen / pre-revocation token still works. Browser SPAs auto-refresh via `set-auth-token` on every authed call, so a low TTL is invisible to logged-in users; only stale server-to-server bearer tokens feel it.
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
auth: { jwt: { expiresIn: 30 } } // 30s — tight post-revocation window
|
|
45
|
+
auth: { jwt: { expiresIn: 3600 } } // 1h — longer-lived tokens for CLI / CI
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### `issuer?: string` — `iss` claim
|
|
49
|
+
|
|
50
|
+
Default omitted.
|
|
51
|
+
|
|
52
|
+
Set this when other services need to distinguish JWTs minted by this Worker from other issuers. The compiler bakes the issuer into both the mint side (added to claims) and the verify side (rejects tokens with mismatched `iss`).
|
|
53
|
+
|
|
54
|
+
### `audience?: string` — `aud` claim
|
|
55
|
+
|
|
56
|
+
Default omitted.
|
|
57
|
+
|
|
58
|
+
Set this when this Worker's JWTs are consumed by a sibling service that should reject tokens minted for a different audience. Same mint-and-verify treatment as `issuer`.
|
|
59
|
+
|
|
60
|
+
### `secretEnv?: string` — signing secret env var
|
|
61
|
+
|
|
62
|
+
Default `'BETTER_AUTH_SECRET'`.
|
|
63
|
+
|
|
64
|
+
Override this if you want JWT signing isolated from the Better Auth secret (e.g. rotating one without invalidating the other).
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
auth: { jwt: { secretEnv: 'CUSTOM_JWT_SECRET' } }
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The compiler emits `c.env.CUSTOM_JWT_SECRET` (or `process.env.CUSTOM_JWT_SECRET` on Bun/Node) in the auth middleware's verify and mint sites and the `/api/v1/token` endpoint.
|
|
71
|
+
|
|
72
|
+
> **Note:** the files-worker (separate Worker for R2 access) still reads `BETTER_AUTH_SECRET` directly. If you override `secretEnv`, set both env vars to the same value or the files worker's JWT verification will fall back to DB session lookup. Threading `secretEnv` through the files worker is on the roadmap.
|
|
73
|
+
|
|
74
|
+
### `algorithm?: 'HS256'`
|
|
75
|
+
|
|
76
|
+
Only `HS256` is supported in 0.10.14. `RS256` (asymmetric, public-key verify / private-key sign) is on the roadmap.
|
|
77
|
+
|
|
78
|
+
### `revocationCheck?: 'none' | 'kv'` — token revocation strategy
|
|
79
|
+
|
|
80
|
+
Default `'none'`.
|
|
81
|
+
|
|
82
|
+
| Value | Behavior | Cost per verify |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| `'none'` | No revocation check. Stolen tokens valid until TTL expires. Use a low `expiresIn` to bound the replay window. | 0 |
|
|
85
|
+
| `'kv'` | Fast-path consults a denylist KV namespace before accepting the token. Banning a user / revoking sessions writes the user's `sub` to the denylist. | 1 KV read (~5-15ms, edge-cached) |
|
|
86
|
+
|
|
87
|
+
The `'kv'` path keeps the fast-path stateless against the auth DB (still 0 D1 queries) — KV reads on Workers are an order of magnitude cheaper than a D1 round trip *and* give sub-second revocation.
|
|
88
|
+
|
|
89
|
+
> **`'kv'` is deferred to 0.10.15.** Setting `'kv'` in 0.10.14 errors at compile time so the migration path is explicit; the schema accepts it now so users can author their final config today.
|
|
90
|
+
|
|
91
|
+
## Defaults preserve 0.10.13 behavior
|
|
92
|
+
|
|
93
|
+
Adding the `auth.jwt` block without setting any field is a no-op vs. the 0.10.13 baseline. Each missing field falls back to its hardcoded value:
|
|
94
|
+
|
|
95
|
+
| Field | Default |
|
|
96
|
+
|---|---|
|
|
97
|
+
| `expiresIn` | 180 |
|
|
98
|
+
| `issuer` | omitted |
|
|
99
|
+
| `audience` | omitted |
|
|
100
|
+
| `secretEnv` | `'BETTER_AUTH_SECRET'` |
|
|
101
|
+
| `algorithm` | `'HS256'` |
|
|
102
|
+
| `revocationCheck` | `'none'` |
|
|
103
|
+
|
|
104
|
+
## Tuning recommendations
|
|
105
|
+
|
|
106
|
+
- **B2C SaaS, mostly browser traffic:** keep defaults. The 180s TTL + auto-refresh model just works.
|
|
107
|
+
- **Pentest engagement / enterprise compliance:** set `expiresIn: 30`. Tokens stay invisible to logged-in users (auto-refreshed every authed call) but stolen-token windows shrink to 30s.
|
|
108
|
+
- **CLI-heavy / long-running CI tokens:** `expiresIn: 3600` for one-hour bearer tokens. Pair with `issuer` / `audience` if multiple services consume the same JWT.
|
|
109
|
+
- **Need immediate revocation:** wait for 0.10.15's `revocationCheck: 'kv'`. Or, today, drop TTL to ~30s — same effect with bounded delay.
|