@quickback-dev/cli 0.40.2 → 0.46.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/claude.d.ts.map +1 -1
- package/dist/commands/claude.js +8 -0
- package/dist/commands/claude.js.map +1 -1
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +13 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/compile.test.js +26 -21
- package/dist/commands/compile.test.js.map +1 -1
- package/dist/commands/create.js +6 -9
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/login.js +0 -9
- package/dist/commands/login.js.map +1 -1
- package/dist/commands/start.d.ts.map +1 -1
- package/dist/commands/start.js +6 -7
- package/dist/commands/start.js.map +1 -1
- package/dist/commands/whoami.d.ts.map +1 -1
- package/dist/commands/whoami.js +0 -4
- package/dist/commands/whoami.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +21 -31
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +0 -12
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +0 -10
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +13 -8
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/auth.d.ts +0 -1
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/compiler-stubs.d.ts +12 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +18 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/file-loader.d.ts +14 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +63 -9
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/skill/SKILL.md +76 -6
- package/dist/skill/docs/changelog.md +217 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +1 -2
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +7 -8
- package/dist/skill/docs/compiler/config/agents.md +49 -1
- package/dist/skill/docs/compiler/config/auth.md +20 -5
- package/dist/skill/docs/compiler/config/security.md +46 -0
- package/dist/skill/docs/compiler/definitions/access.md +1 -1
- package/dist/skill/docs/compiler/definitions/actions.md +46 -4
- package/dist/skill/docs/compiler/definitions/scopes.md +11 -3
- package/dist/skill/docs/compiler/getting-started/full-example.md +5 -3
- package/dist/skill/docs/compiler/getting-started/index.md +7 -7
- package/dist/skill/docs/compiler/getting-started/patterns.md +39 -5
- package/dist/skill/docs/compiler/getting-started/template-blog.md +65 -44
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +4 -5
- package/dist/skill/docs/compiler/getting-started/template-empty.md +7 -1
- package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +23 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +4 -10
- package/dist/skill/docs/stack/account-ui/hooks.md +24 -1
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +0 -7
- package/dist/skill/docs/stack/auth/plugins/index.md +36 -39
- package/dist/templates/registry.d.ts +0 -12
- package/dist/templates/registry.d.ts.map +1 -1
- package/dist/templates/registry.js +0 -42
- package/dist/templates/registry.js.map +1 -1
- package/package.json +1 -1
- package/src/skill/SKILL.md +76 -6
- package/src/skill/docs/changelog.md +217 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +1 -2
- package/src/skill/docs/compiler/cloud-compiler/cli.md +7 -8
- package/src/skill/docs/compiler/config/agents.md +49 -1
- package/src/skill/docs/compiler/config/auth.md +20 -5
- package/src/skill/docs/compiler/config/security.md +46 -0
- package/src/skill/docs/compiler/definitions/access.md +1 -1
- package/src/skill/docs/compiler/definitions/actions.md +46 -4
- package/src/skill/docs/compiler/definitions/scopes.md +11 -3
- package/src/skill/docs/compiler/getting-started/full-example.md +5 -3
- package/src/skill/docs/compiler/getting-started/index.md +7 -7
- package/src/skill/docs/compiler/getting-started/patterns.md +39 -5
- package/src/skill/docs/compiler/getting-started/template-blog.md +65 -44
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +4 -5
- package/src/skill/docs/compiler/getting-started/template-empty.md +7 -1
- package/src/skill/docs/compiler/getting-started/templates.md +6 -6
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +23 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +4 -10
- package/src/skill/docs/stack/account-ui/hooks.md +24 -1
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +0 -7
- package/src/skill/docs/stack/auth/plugins/index.md +36 -39
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +0 -74
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +0 -155
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +0 -74
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +0 -155
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback provides pre-configured templates to get you started quickly. Each template combines a runtime, database, and auth provider into a working project.
|
|
4
4
|
|
|
5
|
-
The fastest way to start is `quickback start` — an interactive picker that asks for a template + project name and scaffolds in the current directory if it's empty, otherwise creates a subfolder.
|
|
5
|
+
The fastest way to start is `quickback start` — an interactive picker that asks for a template + project name and scaffolds in the current directory if it's empty, otherwise creates a subfolder. The picker offers `cloudflare`, `todos`, `blog`, and `empty`; every template (including `saas`) is available scriptably via `quickback create <template> <name>`.
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
# Interactive (recommended for first-time use)
|
|
@@ -12,7 +12,7 @@ npx @quickback-dev/cli start
|
|
|
12
12
|
|
|
13
13
|
## Available Templates
|
|
14
14
|
|
|
15
|
-
### Multi-tenant scaffolds
|
|
15
|
+
### Multi-tenant scaffolds
|
|
16
16
|
|
|
17
17
|
Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member` / `admin` / `owner` role hierarchy wired in.
|
|
18
18
|
|
|
@@ -23,7 +23,7 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
|
|
|
23
23
|
|
|
24
24
|
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
|
|
25
25
|
|
|
26
|
-
### Fixed-org starter
|
|
26
|
+
### Fixed-org starter
|
|
27
27
|
|
|
28
28
|
| Template | Includes | Command |
|
|
29
29
|
|----------|----------|---------|
|
|
@@ -31,7 +31,7 @@ The **todos** template is the recommended first read — it exercises every secu
|
|
|
31
31
|
|
|
32
32
|
The **blog** template uses [pinned organization mode](/compiler/config/single-tenant) and scaffolds `features.pinnedOrganizationId: "org_replace_me"`.
|
|
33
33
|
|
|
34
|
-
### Empty scaffold
|
|
34
|
+
### Empty scaffold
|
|
35
35
|
|
|
36
36
|
| Template | Includes | Command |
|
|
37
37
|
|----------|----------|---------|
|
|
@@ -39,7 +39,7 @@ The **blog** template uses [pinned organization mode](/compiler/config/single-te
|
|
|
39
39
|
|
|
40
40
|
The empty template creates the project structure with `quickback.config.ts` only. Add your first feature by creating a file under `quickback/features/<name>/<name>.ts` exporting `defineTable(...)` — there is no separate `init` step.
|
|
41
41
|
|
|
42
|
-
### B2B SaaS
|
|
42
|
+
### B2B SaaS
|
|
43
43
|
|
|
44
44
|
| Template | Includes | Command |
|
|
45
45
|
|----------|----------|---------|
|
|
@@ -80,7 +80,7 @@ Best for personal sites, blogs, or any app that only needs one organization at r
|
|
|
80
80
|
|
|
81
81
|
Best when you know exactly what you want to build. Gets you the project structure and config without any opinionated features.
|
|
82
82
|
|
|
83
|
-
### SaaS
|
|
83
|
+
### SaaS
|
|
84
84
|
|
|
85
85
|
Best for production B2B work. Adds R2 file uploads, outbound webhooks (with retry/dedupe), split auth/features/webhooks databases, realtime broadcast, and named views.
|
|
86
86
|
|
|
@@ -204,3 +204,26 @@ Or enable the in-project browser via the [`docs` config option](#interactive-api
|
|
|
204
204
|
}
|
|
205
205
|
}
|
|
206
206
|
```
|
|
207
|
+
|
|
208
|
+
## Operations manifest
|
|
209
|
+
|
|
210
|
+
Alongside the spec, every compile writes `reports/operations.manifest.json` — a
|
|
211
|
+
stable, machine-readable index of the full route surface (resource, action,
|
|
212
|
+
view, and auth routes):
|
|
213
|
+
|
|
214
|
+
```json
|
|
215
|
+
[
|
|
216
|
+
{ "operationId": "listCustomers", "method": "GET", "path": "/api/v1/customers", "auth": "session", "feature": "customers", "kind": "crud" }
|
|
217
|
+
]
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
The manifest is a public contract: entries are sorted by `operationId`, carry
|
|
221
|
+
no timestamps, and the shape is extend-only — new fields may be added, existing
|
|
222
|
+
ones won't change meaning. `operationId`s are stable across compiles for the
|
|
223
|
+
same configuration, which makes the manifest the recommended integration point
|
|
224
|
+
for agent/MCP tooling, route inventories, and diff-based change review.
|
|
225
|
+
|
|
226
|
+
A sibling artifact, `reports/conformance.manifest.json`, enumerates the
|
|
227
|
+
expected authorization outcome for every route × principal class (derived from
|
|
228
|
+
the same compiler model that emits the enforcement code). The compiler's own CI
|
|
229
|
+
executes it against a running build on every change.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Passwordless Authentication
|
|
2
2
|
|
|
3
|
-
Account UI supports passwordless authentication via email OTP
|
|
3
|
+
Account UI supports passwordless authentication via email OTP.
|
|
4
4
|
|
|
5
5
|
## Email OTP
|
|
6
6
|
|
|
@@ -10,17 +10,11 @@ When `ENABLE_EMAIL_OTP=true`:
|
|
|
10
10
|
- A one-time password is sent via email
|
|
11
11
|
- User enters the OTP code to authenticate
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
The sign-in email contains the six-digit code only — no magic-link companion. Mail-client URL prefetching burns single-use links, so a code the user types is the reliable path.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
## What about magic links?
|
|
16
16
|
|
|
17
|
-
-
|
|
18
|
-
- A login link is sent via email
|
|
19
|
-
- Clicking the link authenticates the user
|
|
20
|
-
|
|
21
|
-
## Combo Auth
|
|
22
|
-
|
|
23
|
-
When both are enabled, Account UI uses the `@quickback-dev/better-auth-combo-auth` plugin to combine them into a single flow — the email contains both a clickable link and a code.
|
|
17
|
+
Account UI does not offer a magic-link sign-in flow. The `magicLink` Better Auth plugin is still available at the API level (see [Auth Plugins](/stack/auth/plugins#magic-links)) for apps that build their own sign-in UI, but the bundled Account SPA is OTP-only by design.
|
|
24
18
|
|
|
25
19
|
## Related
|
|
26
20
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback discovers project-level auth hooks at `quickback/hooks/` and wires them into [Better Auth's `databaseHooks`](https://www.better-auth.com/docs/concepts/database#database-hooks). Use them for post-signup bootstrap, signup gating, and other lifecycle work.
|
|
4
4
|
|
|
5
|
-
The classic case is multi-tenant: when `account.auth.organizations: true` is set, a freshly signed-up user has no `activeOrganizationId`, so every authenticated `/api/v1/*` returns `
|
|
5
|
+
The classic case is multi-tenant: when `account.auth.organizations: true` is set, a freshly signed-up user has no `activeOrganizationId`, so every authenticated `/api/v1/*` returns `403 ORG_REQUIRED`. An `after-user-create` hook can auto-provision a personal workspace + member row so the next request just works.
|
|
6
6
|
|
|
7
7
|
## Folder layout
|
|
8
8
|
|
|
@@ -25,11 +25,34 @@ Each file has a single default export — an `async (entity, ctx) => ...` functi
|
|
|
25
25
|
| `after-user-create.ts` | `databaseHooks.user.create.after` | `User` | `void` |
|
|
26
26
|
| `after-session-create.ts` | `databaseHooks.session.create.after` | `Session` | `void` |
|
|
27
27
|
| `after-admin-user-create.ts` | `databaseHooks.user.create.after` (filtered) | `User` | `void` |
|
|
28
|
+
| `resolve-oauth-context.ts` | OAuth bearer middleware | OAuth identity + session | Partial `AppContext` tenant fields |
|
|
28
29
|
|
|
29
30
|
`after-admin-user-create.ts` is a **virtual event** — it wires into the same Better Auth `user.create.after` slot as the generic `after-user-create.ts`, but the compiler wraps the call in a runtime filter on the BA context path so it only fires when the row was created via the admin plugin's `POST /admin/create-user` endpoint. Use it for first-time-user provisioning (welcome email, default org assignment) without inspecting `_baCtx?.context?.path` by hand. The generic `after-user-create.ts` still runs for every signup, including admin-created ones.
|
|
30
31
|
|
|
31
32
|
Filenames outside this set are a hard compile-time error so a typo never silently disables a hook. Add events by extending [`apps/compiler/src/parser/hooks.ts`](https://github.com/paulstenhouse/quickback-compiler) (and the matching CLI mirror).
|
|
32
33
|
|
|
34
|
+
## OAuth context resolver
|
|
35
|
+
|
|
36
|
+
First-class MCP OAuth validates the access token and live Better Auth session
|
|
37
|
+
before calling `quickback/hooks/resolve-oauth-context.ts`. Use this trusted
|
|
38
|
+
server hook when tenant selection cannot be derived solely from the session's
|
|
39
|
+
active organization.
|
|
40
|
+
|
|
41
|
+
```ts title="quickback/hooks/resolve-oauth-context.ts"
|
|
42
|
+
export default async ({ token, session, user, context }, { authDb, authSchema, env }) => {
|
|
43
|
+
return {
|
|
44
|
+
activeOrgId: session.activeOrganizationId ?? null,
|
|
45
|
+
activeTeamId: session.activeTeamId ?? null,
|
|
46
|
+
tenantId: session.activeOrganizationId ?? null,
|
|
47
|
+
roles: context.roles,
|
|
48
|
+
};
|
|
49
|
+
};
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The returned object is merged into the standard `AppContext`. The compiler
|
|
53
|
+
always preserves the validated `authenticated`, `userId`, and `user` fields,
|
|
54
|
+
so this hook cannot replace the OAuth identity.
|
|
55
|
+
|
|
33
56
|
## ctx shape
|
|
34
57
|
|
|
35
58
|
Every hook receives `(entity, ctx)`:
|
|
@@ -24,13 +24,8 @@ The plugin handles 8 email types:
|
|
|
24
24
|
| `/ses/send-otp` | One-time password code |
|
|
25
25
|
| `/ses/send-welcome` | Post-signup welcome email |
|
|
26
26
|
| `/ses/send-organization-invitation` | Team/org invite with role |
|
|
27
|
-
| Combo auth | Magic link + OTP in a single email |
|
|
28
27
|
| Delete account | Account deletion confirmation |
|
|
29
28
|
|
|
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
29
|
## AWS Signature V4
|
|
35
30
|
|
|
36
31
|
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.
|
|
@@ -122,7 +117,6 @@ const auth = betterAuth({
|
|
|
122
117
|
replyTo: env.EMAIL_REPLY_TO,
|
|
123
118
|
appName: env.APP_NAME || "My App",
|
|
124
119
|
appUrl: env.APP_URL,
|
|
125
|
-
useComboAuthEmail: true, // Optional: combine magic link + OTP
|
|
126
120
|
}),
|
|
127
121
|
],
|
|
128
122
|
});
|
|
@@ -183,5 +177,4 @@ awsSESPlugin({
|
|
|
183
177
|
|
|
184
178
|
## See Also
|
|
185
179
|
|
|
186
|
-
- [Combo Auth Plugin](/stack/auth/plugins/combo-auth) — Combined magic link + OTP authentication
|
|
187
180
|
- [Auth Configuration](/compiler/config/providers) — Configuring auth plugins
|
|
@@ -6,7 +6,7 @@ Quickback ships with a curated set of Better Auth plugins and helper wiring so y
|
|
|
6
6
|
|
|
7
7
|
### Email OTP (with AWS SES)
|
|
8
8
|
|
|
9
|
-
Quickback wires the Better Auth Email OTP flow to
|
|
9
|
+
Quickback wires the Better Auth Email OTP flow to your email provider. When `emailOtp` is enabled, the compiler emits an OTP-only sign-in email — a six-digit code, no magic-link companion.
|
|
10
10
|
|
|
11
11
|
**Enable in config:**
|
|
12
12
|
|
|
@@ -73,24 +73,6 @@ auth: defineAuth("better-auth", {
|
|
|
73
73
|
> while password sign-up stays closed.
|
|
74
74
|
|
|
75
75
|
|
|
76
|
-
### Upgrade Anonymous
|
|
77
|
-
|
|
78
|
-
Adds a first-class endpoint to convert an anonymous user into a full user. This flips `isAnonymous` to `false` and refreshes the session cache immediately.
|
|
79
|
-
|
|
80
|
-
**Enable in config:**
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
auth: defineAuth("better-auth", {
|
|
84
|
-
emailAndPassword: { enabled: true },
|
|
85
|
-
plugins: ["anonymous", "upgradeAnonymous"],
|
|
86
|
-
}),
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
**Endpoint:**
|
|
90
|
-
- `POST /auth/v1/upgrade-anonymous`
|
|
91
|
-
|
|
92
|
-
**Note:** If you send `Content-Type: application/json`, include a body (an empty `{}` is fine). This avoids request parsing errors in some clients.
|
|
93
|
-
|
|
94
76
|
### SMS OTP (with AWS SNS)
|
|
95
77
|
|
|
96
78
|
When `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via [`@quickback-dev/better-auth-aws-sns`](/stack/auth/plugins/aws-sns). The plugin adds `phoneNumber` / `phoneNumberVerified` columns to the user table, handles OTP generation + storage + verify-attempt limits, and exposes endpoints for phone-only sign-in, phone+password sign-in, and password reset via SMS.
|
|
@@ -331,13 +313,36 @@ Turns your Quickback worker into a standards-compliant OAuth 2.1 + OIDC authoriz
|
|
|
331
313
|
|
|
332
314
|
```ts
|
|
333
315
|
auth: defineAuth("better-auth", {
|
|
334
|
-
|
|
316
|
+
oauth: {
|
|
317
|
+
enabled: true,
|
|
318
|
+
issuerUrl: {
|
|
319
|
+
env: "OAUTH_ISSUER_URL",
|
|
320
|
+
fallback: "http://localhost:8787/auth/v1",
|
|
321
|
+
},
|
|
322
|
+
loginPage: {
|
|
323
|
+
env: "OAUTH_LOGIN_URL",
|
|
324
|
+
fallback: "http://localhost:8787/account/login",
|
|
325
|
+
},
|
|
326
|
+
consentPage: {
|
|
327
|
+
env: "OAUTH_CONSENT_URL",
|
|
328
|
+
fallback: "http://localhost:8787/account/consent",
|
|
329
|
+
},
|
|
330
|
+
scopes: ["openid", "profile", "email", "offline_access"],
|
|
331
|
+
audiences: [
|
|
332
|
+
{ env: "OAUTH_API_AUDIENCE", fallback: "http://localhost:8787" },
|
|
333
|
+
{ env: "OAUTH_MCP_AUDIENCE", fallback: "http://localhost:8787/mcp" },
|
|
334
|
+
],
|
|
335
|
+
allowDynamicClientRegistration: true,
|
|
336
|
+
},
|
|
335
337
|
}),
|
|
336
338
|
```
|
|
337
339
|
|
|
338
|
-
The compiler auto-includes Better Auth's `
|
|
340
|
+
The compiler auto-includes Better Auth's `oauthProvider`, `jwt`, and bearer
|
|
341
|
+
plugins, protects `POST /mcp`, emits RFC 8414 and RFC 9728 discovery, and
|
|
342
|
+
accepts the provider's JWKS-signed access tokens in the standard Quickback
|
|
343
|
+
auth middleware.
|
|
339
344
|
|
|
340
|
-
|
|
345
|
+
The legacy plugin object remains available for provider-specific options:
|
|
341
346
|
|
|
342
347
|
```ts
|
|
343
348
|
auth: defineAuth("better-auth", {
|
|
@@ -358,6 +363,7 @@ auth: defineAuth("better-auth", {
|
|
|
358
363
|
|
|
359
364
|
Discovery (public, no auth):
|
|
360
365
|
- `GET /.well-known/oauth-authorization-server` — RFC 8414 metadata
|
|
366
|
+
- `GET /.well-known/oauth-authorization-server/auth/v1` — RFC 8414 path-insert discovery
|
|
361
367
|
- `GET /.well-known/oauth-protected-resource` — MCP resource metadata
|
|
362
368
|
- `GET /.well-known/openid-configuration` — OIDC discovery
|
|
363
369
|
|
|
@@ -383,25 +389,16 @@ Consent management:
|
|
|
383
389
|
|
|
384
390
|
The compiled Account SPA already serves `/consent`. When `oauthProvider` is enabled, Better Auth redirects unauthenticated users to `${ACCOUNT_URL}/login?redirect=...` and authenticated users straight to `${ACCOUNT_URL}/consent?client_id=...&scope=...&oauth_query=...`. The bundled consent screen reads those params, fetches client metadata via `/oauth2/public-client`, and POSTs back to `/oauth2/consent`.
|
|
385
391
|
|
|
386
|
-
**
|
|
392
|
+
**Token and tenant context:**
|
|
387
393
|
|
|
388
|
-
|
|
394
|
+
Generated middleware validates the provider JWKS, canonical issuer, configured
|
|
395
|
+
audience, expiration, subject, and backing Better Auth session. It then builds
|
|
396
|
+
the same `AppContext` used by session and Quickback JWT authentication.
|
|
397
|
+
Organization membership and role hierarchy are resolved automatically.
|
|
389
398
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
import { auth } from "./auth";
|
|
394
|
-
|
|
395
|
-
const serverClient = createAuthClient({
|
|
396
|
-
plugins: [oauthProviderResourceClient(auth)],
|
|
397
|
-
});
|
|
398
|
-
|
|
399
|
-
const token = req.headers.get("authorization")?.replace("Bearer ", "");
|
|
400
|
-
const payload = await serverClient.verifyAccessToken(token, {
|
|
401
|
-
verifyOptions: { issuer: env.BETTER_AUTH_URL, audience: env.BETTER_AUTH_URL },
|
|
402
|
-
});
|
|
403
|
-
// payload.sub → userId, payload.scope → granted scopes
|
|
404
|
-
```
|
|
399
|
+
For application-specific tenant selection, add
|
|
400
|
+
`quickback/hooks/resolve-oauth-context.ts`; see
|
|
401
|
+
[Auth Hooks](/stack/account-ui/hooks#oauth-context-resolver).
|
|
405
402
|
|
|
406
403
|
**Why this and not the deprecated `mcp` plugin?**
|
|
407
404
|
|
|
@@ -2,10 +2,7 @@
|
|
|
2
2
|
* Template Registry
|
|
3
3
|
*
|
|
4
4
|
* Defines available project templates for quickback create command.
|
|
5
|
-
* The server is the source of truth for templates and tiers.
|
|
6
|
-
* This local registry serves as a fallback when offline.
|
|
7
5
|
*/
|
|
8
|
-
import { type TemplateInfo } from '../lib/api-client.js';
|
|
9
6
|
export interface TemplateDefinition {
|
|
10
7
|
name: string;
|
|
11
8
|
description: string;
|
|
@@ -16,16 +13,7 @@ export interface TemplateDefinition {
|
|
|
16
13
|
includes: string[];
|
|
17
14
|
preset: string;
|
|
18
15
|
requiresCloudflare: boolean;
|
|
19
|
-
tier: 'free' | 'pro';
|
|
20
16
|
}
|
|
21
|
-
/**
|
|
22
|
-
* Fetch templates from server (with caching)
|
|
23
|
-
*/
|
|
24
|
-
export declare function fetchServerTemplates(): Promise<Record<string, TemplateInfo>>;
|
|
25
|
-
/**
|
|
26
|
-
* Check if a template requires pro tier
|
|
27
|
-
*/
|
|
28
|
-
export declare function isProTemplate(templateName: string): Promise<boolean>;
|
|
29
17
|
export declare const TEMPLATE_REGISTRY: Record<string, TemplateDefinition>;
|
|
30
18
|
export declare const TEMPLATE_ALIASES: Record<string, string>;
|
|
31
19
|
export declare function getTemplate(nameOrAlias: string): TemplateDefinition | undefined;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;IAC/C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;CAC/B;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CA4DhE,CAAC;AAKF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAQnD,CAAC;AAEF,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAG/E;AAED,wBAAgB,aAAa,IAAI,kBAAkB,EAAE,CAEpD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEpD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAgB3C"}
|
|
@@ -2,44 +2,8 @@
|
|
|
2
2
|
* Template Registry
|
|
3
3
|
*
|
|
4
4
|
* Defines available project templates for quickback create command.
|
|
5
|
-
* The server is the source of truth for templates and tiers.
|
|
6
|
-
* This local registry serves as a fallback when offline.
|
|
7
5
|
*/
|
|
8
|
-
import { fetchTemplates } from '../lib/api-client.js';
|
|
9
|
-
// Cache for server templates
|
|
10
|
-
let serverTemplatesCache = null;
|
|
11
|
-
/**
|
|
12
|
-
* Fetch templates from server (with caching)
|
|
13
|
-
*/
|
|
14
|
-
export async function fetchServerTemplates() {
|
|
15
|
-
if (serverTemplatesCache) {
|
|
16
|
-
return serverTemplatesCache;
|
|
17
|
-
}
|
|
18
|
-
try {
|
|
19
|
-
serverTemplatesCache = await fetchTemplates();
|
|
20
|
-
return serverTemplatesCache;
|
|
21
|
-
}
|
|
22
|
-
catch {
|
|
23
|
-
// Fallback to local registry
|
|
24
|
-
return {};
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
|
-
/**
|
|
28
|
-
* Check if a template requires pro tier
|
|
29
|
-
*/
|
|
30
|
-
export async function isProTemplate(templateName) {
|
|
31
|
-
const serverTemplates = await fetchServerTemplates();
|
|
32
|
-
const resolved = TEMPLATE_ALIASES[templateName] || templateName;
|
|
33
|
-
// Check server first
|
|
34
|
-
if (serverTemplates[resolved]) {
|
|
35
|
-
return serverTemplates[resolved].tier === 'pro';
|
|
36
|
-
}
|
|
37
|
-
// Fallback to local
|
|
38
|
-
const local = TEMPLATE_REGISTRY[resolved];
|
|
39
|
-
return local?.tier === 'pro';
|
|
40
|
-
}
|
|
41
6
|
export const TEMPLATE_REGISTRY = {
|
|
42
|
-
// Free tier templates
|
|
43
7
|
"betterauth-d1-cloudflare": {
|
|
44
8
|
name: "Better Auth + D1 + Cloudflare",
|
|
45
9
|
description: "Authentication with Better Auth, D1 database, deployed to Cloudflare Workers — bare scaffold, add your own features",
|
|
@@ -50,7 +14,6 @@ export const TEMPLATE_REGISTRY = {
|
|
|
50
14
|
includes: ["betterauth", "d1", "hono", "drizzle"],
|
|
51
15
|
preset: "cloudflare",
|
|
52
16
|
requiresCloudflare: true,
|
|
53
|
-
tier: "free",
|
|
54
17
|
},
|
|
55
18
|
"todos-cloudflare": {
|
|
56
19
|
name: "Todos Example (Cloudflare)",
|
|
@@ -62,11 +25,9 @@ export const TEMPLATE_REGISTRY = {
|
|
|
62
25
|
includes: ["betterauth", "d1", "hono", "drizzle"],
|
|
63
26
|
preset: "cloudflare",
|
|
64
27
|
requiresCloudflare: true,
|
|
65
|
-
tier: "free",
|
|
66
28
|
},
|
|
67
29
|
// bun template hidden — see apps/compiler/src/providers/runtime/providers/bun/README.md
|
|
68
30
|
// → "Known Issues" for the list of generator drift bugs blocking it.
|
|
69
|
-
// Pro tier templates
|
|
70
31
|
"b2bsaas-cloudflare": {
|
|
71
32
|
name: "B2B SaaS Starter",
|
|
72
33
|
description: "Full B2B SaaS with auth, organizations, file storage (R2), webhooks, and views",
|
|
@@ -77,7 +38,6 @@ export const TEMPLATE_REGISTRY = {
|
|
|
77
38
|
includes: ["betterauth", "organizations", "d1", "r2", "files", "webhooks", "hono", "drizzle"],
|
|
78
39
|
preset: "cloudflare",
|
|
79
40
|
requiresCloudflare: true,
|
|
80
|
-
tier: "pro",
|
|
81
41
|
},
|
|
82
42
|
// api-minimal-bun also hidden alongside the other bun templates.
|
|
83
43
|
"blog-cloudflare": {
|
|
@@ -90,7 +50,6 @@ export const TEMPLATE_REGISTRY = {
|
|
|
90
50
|
includes: ["betterauth", "d1", "hono", "drizzle"],
|
|
91
51
|
preset: "blog",
|
|
92
52
|
requiresCloudflare: true,
|
|
93
|
-
tier: "free",
|
|
94
53
|
},
|
|
95
54
|
"empty-cloudflare": {
|
|
96
55
|
name: "Empty Scaffold (Cloudflare)",
|
|
@@ -102,7 +61,6 @@ export const TEMPLATE_REGISTRY = {
|
|
|
102
61
|
includes: ["betterauth", "d1", "hono", "drizzle"],
|
|
103
62
|
preset: "cloudflare",
|
|
104
63
|
requiresCloudflare: true,
|
|
105
|
-
tier: "free",
|
|
106
64
|
},
|
|
107
65
|
// empty-bun also hidden alongside the other bun templates.
|
|
108
66
|
};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.46.0",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
package/src/skill/SKILL.md
CHANGED
|
@@ -153,6 +153,7 @@ Before flagging "missing X", check whether a default already covers it:
|
|
|
153
153
|
- **Firewall auto-derived** for tables with a single isolation column (e.g., `organizationId` only).
|
|
154
154
|
- **Soft-delete cascade** reaches cross-feature children with each child's own firewall AND-merged.
|
|
155
155
|
- **Reserved keys in `access.record`.** `and`, `or`, `roles`, `userRole` are rejected inside `record:` at compile time — those go on the parent access node.
|
|
156
|
+
- **Soft-delete × `unique()` footgun.** A soft-deleted row still occupies its unique index — deleting a unique junction row (e.g. a membership pair) then re-creating it fails the constraint, because the old row is only flagged `deletedAt`, not removed. For re-creatable unique rows, either use `delete.mode: 'hard'` (needs the audit DB on D1) or drop the unique constraint and enforce uniqueness in an action.
|
|
156
157
|
|
|
157
158
|
---
|
|
158
159
|
|
|
@@ -162,10 +163,36 @@ The action context's `db` is a Drizzle wrapper that:
|
|
|
162
163
|
|
|
163
164
|
- **Does** auto-AND the resource's firewall WHERE clause into every `select` / `update` / `delete`.
|
|
164
165
|
- **Does** route soft-delete `delete()` calls to a `deletedAt` / `deletedBy` UPDATE.
|
|
165
|
-
- **Does
|
|
166
|
+
- **Does** auto-populate scope columns on `insert`: any `q.scope()` column (and firewall-declared org/owner/team columns) is filled from ctx — `organizationId` ← `ctx.activeOrgId`, `ownerId` ← `ctx.userId`, etc. Audit fields (`createdAt`/`createdBy`/`modifiedAt`/`modifiedBy`) are hard-stamped by the audit wrapper; caller-supplied values for them are dropped.
|
|
167
|
+
- **Does NOT** fill ordinary business columns — anything that isn't a scope or audit column is exactly what you pass to `.values({...})`.
|
|
166
168
|
|
|
167
169
|
For unscoped writes (cross-tenant support, platform admin), use the `unsafe:` object form on the action — it forces an audit reason and gates on platform admin role.
|
|
168
170
|
|
|
171
|
+
## Error handling in actions
|
|
172
|
+
|
|
173
|
+
To return a clean 4xx from an action, throw `ActionError` — the route handler catches it by name and returns `{ error, code, details }` with your status:
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
import { ActionError } from "@quickback/compiler"; // rewritten at compile to the generated src/lib/types
|
|
177
|
+
|
|
178
|
+
throw new ActionError("Not enough balance", "INSUFFICIENT_FUNDS", 400, { available: record.balance });
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Constructor: `(message, code, statusCode = 400, details?)`. Do **NOT** throw Hono's `HTTPException` — it isn't unwrapped and surfaces as a 500 `ACTION_EXECUTION_FAILED`. Returning `c.json({...}, 400)` directly also works (the executor receives `c`).
|
|
182
|
+
|
|
183
|
+
## Reaching auth tables (org members, users) from actions
|
|
184
|
+
|
|
185
|
+
The scoped `db` only sees feature tables. For "is this userId a member of the caller's org?" (assignee-style features), use the Hono context's auth DB plus the generated helper:
|
|
186
|
+
|
|
187
|
+
```ts
|
|
188
|
+
import { getOrgMemberRole } from "../../../lib/org-access";
|
|
189
|
+
|
|
190
|
+
const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activeOrgId!);
|
|
191
|
+
if (!role) throw new ActionError("Not a member of this organization", "NOT_A_MEMBER", 400);
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`c.get("authDb")` is the Drizzle connection to the Better Auth database (a separate D1 in dual-DB mode). For richer queries import tables from `../../../auth/schema`. The `ctx` fields are `userId`, `roles` (org-member roles), `activeOrgId`, `activeTeamId`, `userRole` — there is no `ctx.orgId`.
|
|
195
|
+
|
|
169
196
|
---
|
|
170
197
|
|
|
171
198
|
## Quickback CLI (commands the user runs)
|
|
@@ -178,13 +205,46 @@ quickback login # authenticate via browser device flow
|
|
|
178
205
|
|
|
179
206
|
The CLI calls `compiler.quickback.dev` by default. Override with `QUICKBACK_API_URL=http://localhost:3000` for self-hosted compilation.
|
|
180
207
|
|
|
181
|
-
|
|
208
|
+
If you have shell access (e.g. Claude Code), run these commands directly — `quickback compile` is interactive-safe and prompts for login in the browser. In environments without a shell, surface the commands to the user as instructions instead.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## Local smoke testing (wrangler dev)
|
|
213
|
+
|
|
214
|
+
Three things block a working local loop that aren't obvious from the docs:
|
|
215
|
+
|
|
216
|
+
1. **`BETTER_AUTH_SECRET` must be in `.dev.vars`.** The worker refuses to serve with an explicit `503 MISSING_ENV` without it. Create `.dev.vars` next to `wrangler.toml`: `BETTER_AUTH_SECRET=<any long random string>`.
|
|
217
|
+
2. **Auth cookies are Secure + origin-checked.** When testing with curl, capture the `Set-Cookie` from sign-in and pass it back manually, AND send a trusted `Origin:` header (e.g. `Origin: http://localhost:8787`) on auth POSTs or Better Auth's CSRF check rejects them.
|
|
218
|
+
3. **Set an active organization before minting a JWT.** `POST /api/v1/token` exchanges the session for a JWT; if the session has no active org, the token carries no org roles and every org-scoped endpoint 403s. Call `POST /auth/v1/organization/set-active` (body: `{"organizationId": "..."}`) first.
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
# sign up → sign in (capture cookie) → set active org → mint JWT → call API
|
|
222
|
+
curl -X POST http://localhost:8787/auth/v1/sign-up/email -H "Content-Type: application/json" \
|
|
223
|
+
-H "Origin: http://localhost:8787" -d '{"email":"a@b.co","password":"password123","name":"A"}'
|
|
224
|
+
curl -i -X POST http://localhost:8787/auth/v1/sign-in/email -H "Content-Type: application/json" \
|
|
225
|
+
-H "Origin: http://localhost:8787" -d '{"email":"a@b.co","password":"password123"}'
|
|
226
|
+
# → copy better-auth.session_token from Set-Cookie into $COOKIE
|
|
227
|
+
curl -X POST http://localhost:8787/auth/v1/organization/set-active -H "Content-Type: application/json" \
|
|
228
|
+
-H "Origin: http://localhost:8787" -H "Cookie: $COOKIE" -d '{"organizationId":"<org-id>"}'
|
|
229
|
+
curl -X POST http://localhost:8787/api/v1/token -H "Cookie: $COOKIE"
|
|
230
|
+
```
|
|
182
231
|
|
|
183
232
|
---
|
|
184
233
|
|
|
185
234
|
## Looking up details
|
|
186
235
|
|
|
187
|
-
|
|
236
|
+
Two ways to pull reference material on demand; the skill body above is intentionally just orientation.
|
|
237
|
+
|
|
238
|
+
**Primary: the CLI docs command** (works wherever the CLI is installed):
|
|
239
|
+
|
|
240
|
+
```bash
|
|
241
|
+
quickback docs # topic index
|
|
242
|
+
quickback docs compiler/definitions/firewall # full topic page
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Always pass the **full path** (`compiler/definitions/actions`, not `actions`) — short names error as ambiguous when more than one topic matches.
|
|
246
|
+
|
|
247
|
+
**Secondary: bundled markdown files.** If a `docs/` directory exists alongside this `SKILL.md` (installed by `quickback claude install` / present in the skill package):
|
|
188
248
|
|
|
189
249
|
```
|
|
190
250
|
Glob: docs/**/*.md # discover topics
|
|
@@ -192,7 +252,9 @@ Read: docs/compiler/definitions/firewall.md
|
|
|
192
252
|
Grep: "deletedAt" docs/ # search across the whole docs tree
|
|
193
253
|
```
|
|
194
254
|
|
|
195
|
-
|
|
255
|
+
If `docs/` is missing from your installed copy, fall back to `quickback docs <topic>` — don't go hunting for the files.
|
|
256
|
+
|
|
257
|
+
The path layout mirrors the public docs site (https://docs.quickback.dev). Open any topic file for the authoritative reference.
|
|
196
258
|
|
|
197
259
|
**Compiler — definitions** (`docs/compiler/definitions/<topic>.md`)
|
|
198
260
|
- `schema` — column types, `q.text/int/bool/uuid/timestamp/json/scope/...`, FKs, indexes
|
|
@@ -203,17 +265,23 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
203
265
|
- `masking` — types, `show:`, search/filter gating, auto-detection
|
|
204
266
|
- `read` — `read.access`, `read.views`, `read.query`, pagination + filtering
|
|
205
267
|
- `views` — named projections with column-level access
|
|
206
|
-
- `actions` — record-based vs standalone, transitions, `unsafe:`, `whereRecord(table)`
|
|
268
|
+
- `actions` — record-based vs standalone, transitions, `unsafe:`, `whereRecord(table)`, `ActionError`, `authDb`
|
|
207
269
|
- `validation` — minLength, max, enum, pattern, email
|
|
208
270
|
- `concepts` — secure-by-default, defense in depth, request flow
|
|
271
|
+
- `scopes` — relationship-derived scopes (`ctx.scope.*`), scoped roles, JWT claims
|
|
272
|
+
- `permissions` — named `authz.permissions`, Policy IR, `{ permission: ... }` arms
|
|
273
|
+
- `arrows` — arrow (`->`) traversals in authz expressions, recursive relations
|
|
274
|
+
- `fga` — OpenFGA/Zanzibar ReBAC: `authz.fga` model, `ctx.fga`, sharing
|
|
275
|
+
- `diagnostics` — `[quickback:authz]` compile warnings, static analysis
|
|
209
276
|
|
|
210
277
|
**Compiler — config** (`docs/compiler/config/<topic>.md`)
|
|
211
278
|
- `providers` — runtime / database / auth provider selection
|
|
279
|
+
- `auth` — `account.auth.*`, role hierarchy, plugin toggles
|
|
212
280
|
- `variables` — env vars, secrets
|
|
213
281
|
- `bindings` — extra Cloudflare bindings (queues, R2, etc.)
|
|
214
282
|
- `output` — `build.outputDir`, custom dependencies
|
|
215
283
|
- `domains` — multi-domain hostname routing (CMS / account / admin)
|
|
216
|
-
- `
|
|
284
|
+
- `security` — security-related project config
|
|
217
285
|
- `single-tenant` — pinned organization mode and migration away from removed `organizations: false`
|
|
218
286
|
- `agents` — robots.txt, llms.txt, MCP, OAuth discovery
|
|
219
287
|
|
|
@@ -230,6 +298,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
230
298
|
**Getting started** (`docs/compiler/getting-started/<topic>.md`)
|
|
231
299
|
- `templates` — full template list
|
|
232
300
|
- `template-cloudflare` — recommended starting point
|
|
301
|
+
- `template-blog` / `template-empty` — pinned-org blog and bare-config starts
|
|
233
302
|
- `full-example` — top-to-bottom walkthrough
|
|
234
303
|
- `hand-crafted` — building from `template-empty`
|
|
235
304
|
- `patterns` — common multi-tenant / hierarchical / public patterns
|
|
@@ -239,6 +308,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
239
308
|
- `authentication` — login flow, API keys, sessions
|
|
240
309
|
- `endpoints` — POST /compile, GET /templates, GET /health
|
|
241
310
|
- `local-compiler` — running the compiler locally in Docker
|
|
311
|
+
- `troubleshooting` — compile/auth failure modes
|
|
242
312
|
|
|
243
313
|
**Other** — `docs/changelog.md`, `docs/compiler/claude-code-skill.md`
|
|
244
314
|
|