@quickback-dev/cli 0.40.2 → 0.47.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 +22 -32
- 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 +278 -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/diagnostics.md +88 -57
- 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 +278 -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/diagnostics.md +88 -57
- 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/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts +0 -2
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.test.js +0 -130
- package/dist/lib/sweep-stale.test.js.map +0 -1
- 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
|
Quick recipes for common scenarios. Each pattern shows the complete `defineTable` configuration.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Team-Wide Read, Manager-Only Write
|
|
6
6
|
|
|
7
7
|
A job board where all team members can browse open positions but only hiring managers can create or edit jobs:
|
|
8
8
|
|
|
@@ -95,16 +95,18 @@ export const interviewScores = sqliteTable("interview_scores", {
|
|
|
95
95
|
|
|
96
96
|
```typescript
|
|
97
97
|
// quickback/features/applications/actions.ts — uses the internal table
|
|
98
|
+
import { z } from "zod";
|
|
98
99
|
import { defineActions } from "@quickback/compiler";
|
|
99
100
|
import { applications } from "./applications";
|
|
100
101
|
import { interviewScores } from "./interview-scores";
|
|
101
102
|
|
|
102
103
|
export default defineActions(applications, {
|
|
104
|
+
// No `path:` → record-based action, mounted at POST /applications/:id/submitScore
|
|
103
105
|
submitScore: {
|
|
104
|
-
type: "record",
|
|
105
106
|
input: z.object({ score: z.number().min(1).max(5), feedback: z.string() }),
|
|
106
107
|
access: { roles: ["owner", "hiring-manager", "interviewer"] },
|
|
107
108
|
execute: async ({ db, record, input, ctx }) => {
|
|
109
|
+
// The scoped db auto-injects organizationId (and audit fields) on insert.
|
|
108
110
|
await db.insert(interviewScores).values({
|
|
109
111
|
applicationId: record.id,
|
|
110
112
|
interviewerId: ctx.userId,
|
|
@@ -117,6 +119,39 @@ export default defineActions(applications, {
|
|
|
117
119
|
});
|
|
118
120
|
```
|
|
119
121
|
|
|
122
|
+
## Referencing Users / Org Members (Assignees)
|
|
123
|
+
|
|
124
|
+
Assignee-style features need to validate that a submitted `userId` is actually a member of the caller's organization. The scoped `db` only sees feature tables — reach the Better Auth tables via `c.get("authDb")` and the generated `getOrgMemberRole` helper:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
// quickback/features/projects/actions/assign.ts
|
|
128
|
+
import { z } from "zod";
|
|
129
|
+
import { ActionError } from "@quickback/compiler";
|
|
130
|
+
import { defineAction } from "../.quickback/define-action";
|
|
131
|
+
import { getOrgMemberRole } from "../../../lib/org-access";
|
|
132
|
+
import { projects } from "../projects";
|
|
133
|
+
|
|
134
|
+
export default defineAction({
|
|
135
|
+
description: "Assign a project to an org member",
|
|
136
|
+
input: z.object({ assigneeId: z.string() }),
|
|
137
|
+
access: { roles: ["member+"] },
|
|
138
|
+
async execute({ db, record, input, ctx, c, whereRecord }) {
|
|
139
|
+
const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activeOrgId!);
|
|
140
|
+
if (!role) {
|
|
141
|
+
throw new ActionError("Assignee is not a member of this organization", "NOT_A_MEMBER", 400);
|
|
142
|
+
}
|
|
143
|
+
const [updated] = await db
|
|
144
|
+
.update(projects)
|
|
145
|
+
.set({ assigneeId: input.assigneeId })
|
|
146
|
+
.where(whereRecord!(projects))
|
|
147
|
+
.returning();
|
|
148
|
+
return updated;
|
|
149
|
+
},
|
|
150
|
+
});
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Store the assignee as a plain text column (e.g. `assigneeId: q.text().optional()`) — don't name it `userId`, which the firewall validator treats as an ownership column on feature tables.
|
|
154
|
+
|
|
120
155
|
## Admin-Only Status Field
|
|
121
156
|
|
|
122
157
|
A field that only hiring managers can modify, but everyone can see:
|
|
@@ -126,8 +161,8 @@ export default defineTable(applications, {
|
|
|
126
161
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
127
162
|
guards: {
|
|
128
163
|
createable: ["candidateId", "jobId", "notes"],
|
|
129
|
-
updatable: ["notes"],
|
|
130
|
-
protected: ["
|
|
164
|
+
updatable: ["notes"], // Recruiters can only update notes
|
|
165
|
+
protected: { stage: ["advanceStage"] }, // Stage only changes via the named action
|
|
131
166
|
},
|
|
132
167
|
read: {
|
|
133
168
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
@@ -144,7 +179,6 @@ Then create an action that hiring managers use to change stage:
|
|
|
144
179
|
// quickback/features/applications/actions.ts
|
|
145
180
|
export default defineActions(applications, {
|
|
146
181
|
advanceStage: {
|
|
147
|
-
type: "record",
|
|
148
182
|
input: z.object({ stage: z.enum(["applied", "screening", "interview", "offer", "hired", "rejected"]) }),
|
|
149
183
|
access: { roles: ["hiring-manager"] },
|
|
150
184
|
execute: async ({ db, record, input }) => {
|
|
@@ -20,7 +20,9 @@ my-site/
|
|
|
20
20
|
│ └── features/
|
|
21
21
|
│ └── posts/
|
|
22
22
|
│ ├── posts.ts # Schema + security (defineTable)
|
|
23
|
-
│ └── actions
|
|
23
|
+
│ └── actions/
|
|
24
|
+
│ ├── publish.ts # Publish action
|
|
25
|
+
│ └── unpublish.ts # Unpublish action
|
|
24
26
|
├── src/ # Compiled output (generated)
|
|
25
27
|
├── package.json
|
|
26
28
|
├── tsconfig.json
|
|
@@ -68,22 +70,31 @@ export const posts = sqliteTable("posts", {
|
|
|
68
70
|
excerpt: text("excerpt"),
|
|
69
71
|
status: text("status").notNull().default("draft"),
|
|
70
72
|
publishedAt: text("published_at"),
|
|
71
|
-
|
|
73
|
+
|
|
74
|
+
// Author tracking only — this is metadata, not access control.
|
|
75
|
+
// Named "authorId" (not "userId") so the firewall validator does NOT
|
|
76
|
+
// enter user-scoped RLS mode. Reads are gated by PUBLIC; writes by the
|
|
77
|
+
// admin access check below.
|
|
78
|
+
authorId: text("author_id").notNull(),
|
|
72
79
|
});
|
|
73
80
|
|
|
74
81
|
export default defineTable(posts, {
|
|
75
|
-
firewall
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
82
|
+
// PUBLIC reads — no isolation predicate at the firewall layer.
|
|
83
|
+
// Anonymous viewers have no ctx.userId, so a userId/orgId WHERE clause
|
|
84
|
+
// would gate every row out. softDelete keeps deleted posts hidden.
|
|
85
|
+
firewall: {
|
|
86
|
+
softDelete: {},
|
|
87
|
+
},
|
|
79
88
|
guards: {
|
|
80
89
|
createable: ["title", "slug", "content", "excerpt", "status", "publishedAt"],
|
|
81
90
|
updatable: ["title", "slug", "content", "excerpt", "status", "publishedAt"],
|
|
82
|
-
immutable: ["id", "
|
|
91
|
+
immutable: ["id", "authorId"],
|
|
83
92
|
},
|
|
84
93
|
read: {
|
|
85
94
|
access: { roles: ["PUBLIC"] },
|
|
86
95
|
},
|
|
96
|
+
// "admin" = org-membership admin role, resolved from membership in
|
|
97
|
+
// the pinned organization (features.pinnedOrganizationId).
|
|
87
98
|
create: { access: { roles: ["admin"] } },
|
|
88
99
|
update: { access: { roles: ["admin"] } },
|
|
89
100
|
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
@@ -91,42 +102,44 @@ export default defineTable(posts, {
|
|
|
91
102
|
```
|
|
92
103
|
|
|
93
104
|
- **`PUBLIC`** role on `read.access` means no authentication required for `GET /` and `GET /:id`
|
|
94
|
-
- **`admin`**
|
|
95
|
-
- **`
|
|
105
|
+
- **`admin`** is the org-membership admin role — an authenticated user whose membership in the pinned organization has `role: "admin"` (or above). For platform-wide roles stored on `user.role`, use `userRole: [...]` instead — see [Pinned Organization Mode](/compiler/config/single-tenant)
|
|
106
|
+
- **`authorId`** is plain metadata recording who wrote the post — it is deliberately *not* a firewall scope, because an owner predicate would hide every post from anonymous readers
|
|
96
107
|
- **`softDelete`** marks posts as deleted rather than removing them from the database
|
|
97
108
|
|
|
98
|
-
### Post Actions (actions.ts)
|
|
109
|
+
### Post Actions (actions/publish.ts, actions/unpublish.ts)
|
|
99
110
|
|
|
100
|
-
The template
|
|
111
|
+
The template scaffolds one file per action under `features/posts/actions/`. Each is a `defineAction` with a record-level access condition and an `execute` handler:
|
|
101
112
|
|
|
102
113
|
```typescript
|
|
103
|
-
|
|
104
|
-
import {
|
|
105
|
-
import {
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
},
|
|
115
|
-
sideEffects: "sync",
|
|
114
|
+
// quickback/features/posts/actions/publish.ts
|
|
115
|
+
import { z } from "zod";
|
|
116
|
+
import { eq } from "drizzle-orm";
|
|
117
|
+
import { defineAction } from "../.quickback/define-action";
|
|
118
|
+
import { posts } from "../posts";
|
|
119
|
+
|
|
120
|
+
export default defineAction({
|
|
121
|
+
description: "Publish a draft post",
|
|
122
|
+
input: z.object({}),
|
|
123
|
+
access: {
|
|
124
|
+
roles: ["admin"],
|
|
125
|
+
record: { status: { equals: "draft" } },
|
|
116
126
|
},
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
127
|
+
sideEffects: "sync",
|
|
128
|
+
async execute({ db, record }) {
|
|
129
|
+
const [updated] = await db
|
|
130
|
+
.update(posts)
|
|
131
|
+
.set({
|
|
132
|
+
status: "published",
|
|
133
|
+
publishedAt: new Date().toISOString(),
|
|
134
|
+
})
|
|
135
|
+
.where(eq(posts.id, record.id))
|
|
136
|
+
.returning();
|
|
137
|
+
return updated;
|
|
125
138
|
},
|
|
126
139
|
});
|
|
127
140
|
```
|
|
128
141
|
|
|
129
|
-
These actions are admin-only and include record-level
|
|
142
|
+
`unpublish.ts` is the mirror image — it requires `status: "published"` and reverts the post to draft. These actions are admin-only and include record-level access conditions: you can only publish drafts and unpublish published posts.
|
|
130
143
|
|
|
131
144
|
## Setup Steps
|
|
132
145
|
|
|
@@ -148,21 +161,27 @@ quickback login
|
|
|
148
161
|
quickback compile
|
|
149
162
|
```
|
|
150
163
|
|
|
151
|
-
### 4. Create D1
|
|
164
|
+
### 4. Create D1 Databases
|
|
152
165
|
|
|
153
|
-
|
|
166
|
+
Like every D1 project, the blog template uses dual database mode by default — separate databases for auth and application data:
|
|
154
167
|
|
|
155
168
|
```bash
|
|
156
|
-
npx wrangler d1 create my-site
|
|
169
|
+
npx wrangler d1 create my-site-auth
|
|
170
|
+
npx wrangler d1 create my-site-features
|
|
157
171
|
```
|
|
158
172
|
|
|
159
|
-
Copy the database
|
|
173
|
+
Copy the database IDs from the output and update your `wrangler.toml`:
|
|
160
174
|
|
|
161
175
|
```toml
|
|
176
|
+
[[d1_databases]]
|
|
177
|
+
binding = "AUTH_DB"
|
|
178
|
+
database_name = "my-site-auth"
|
|
179
|
+
database_id = "paste-auth-id-here"
|
|
180
|
+
|
|
162
181
|
[[d1_databases]]
|
|
163
182
|
binding = "DB"
|
|
164
|
-
database_name = "my-site"
|
|
165
|
-
database_id = "paste-id-here"
|
|
183
|
+
database_name = "my-site-features"
|
|
184
|
+
database_id = "paste-features-id-here"
|
|
166
185
|
```
|
|
167
186
|
|
|
168
187
|
### 5. Run Migrations (Local)
|
|
@@ -200,8 +219,8 @@ curl -X POST http://localhost:8787/api/v1/posts \
|
|
|
200
219
|
-H "Content-Type: application/json" \
|
|
201
220
|
-d '{"title": "Hello World", "slug": "hello-world", "content": "..."}'
|
|
202
221
|
|
|
203
|
-
# Publish a post (admin only)
|
|
204
|
-
curl -X POST http://localhost:8787/api/v1/posts/post-id/
|
|
222
|
+
# Publish a post (admin only) — record actions mount at /:id/{actionName}
|
|
223
|
+
curl -X POST http://localhost:8787/api/v1/posts/post-id/publish \
|
|
205
224
|
-H "Authorization: Bearer $TOKEN"
|
|
206
225
|
```
|
|
207
226
|
|
|
@@ -238,17 +257,19 @@ export const pages = sqliteTable("pages", {
|
|
|
238
257
|
title: text("title").notNull(),
|
|
239
258
|
slug: text("slug").notNull().unique(),
|
|
240
259
|
content: text("content"),
|
|
241
|
-
|
|
260
|
+
authorId: text("author_id").notNull(),
|
|
242
261
|
});
|
|
243
262
|
|
|
244
263
|
export default defineTable(pages, {
|
|
245
|
-
firewall
|
|
264
|
+
// PUBLIC reads need an open firewall — an owner predicate would hide
|
|
265
|
+
// every row from anonymous visitors. softDelete still hides deletions.
|
|
266
|
+
firewall: { softDelete: {} },
|
|
246
267
|
read: {
|
|
247
268
|
access: { roles: ["PUBLIC"] },
|
|
248
269
|
},
|
|
249
270
|
create: { access: { roles: ["admin"] } },
|
|
250
271
|
update: { access: { roles: ["admin"] } },
|
|
251
|
-
delete: { access: { roles: ["admin"] } },
|
|
272
|
+
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
252
273
|
});
|
|
253
274
|
```
|
|
254
275
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
The Cloudflare template creates a production-ready backend running on Cloudflare Workers with D1 (SQLite at the edge), KV storage, and Better Auth.
|
|
4
4
|
|
|
5
|
-
`cloudflare` is a **bare scaffold** — multi-tenant orgs + auth + DB are wired in, but there are no example features. Add your own feature files under `quickback/features/`. If you want a working example to read first, use the [todos template](/compiler/getting-started/templates#multi-tenant-scaffolds
|
|
5
|
+
`cloudflare` is a **bare scaffold** — multi-tenant orgs + auth + DB are wired in, but there are no example features. Add your own feature files under `quickback/features/`. If you want a working example to read first, use the [todos template](/compiler/getting-started/templates#multi-tenant-scaffolds) — same providers, but with a complete `todos` feature ready to extend.
|
|
6
6
|
|
|
7
7
|
## Create the Project
|
|
8
8
|
|
|
@@ -43,9 +43,6 @@ my-app/
|
|
|
43
43
|
export default {
|
|
44
44
|
name: "my-app",
|
|
45
45
|
template: "hono",
|
|
46
|
-
features: {
|
|
47
|
-
organizations: true,
|
|
48
|
-
},
|
|
49
46
|
auth: {
|
|
50
47
|
// Use "role+" in access rules to mean "this role and above".
|
|
51
48
|
// e.g. roles: ["member+"] expands to ["member", "admin", "owner"].
|
|
@@ -62,9 +59,11 @@ export default {
|
|
|
62
59
|
};
|
|
63
60
|
```
|
|
64
61
|
|
|
62
|
+
Multi-tenant organizations are on by default — no flag needed. To build a single-tenant app instead, set `organizations: false` on the database provider config.
|
|
63
|
+
|
|
65
64
|
### Adding your first feature
|
|
66
65
|
|
|
67
|
-
Create a file at `quickback/features/<name>/<name>.ts` and export a `defineTable(...)` default. The shape used by the `todos` template makes a good starting point — see [todos.ts in the template registry](/compiler/getting-started/templates#multi-tenant-scaffolds
|
|
66
|
+
Create a file at `quickback/features/<name>/<name>.ts` and export a `defineTable(...)` default. The shape used by the `todos` template makes a good starting point — see [todos.ts in the template registry](/compiler/getting-started/templates#multi-tenant-scaffolds) for a full multi-tenant example with masking, actions, and a named view.
|
|
68
67
|
|
|
69
68
|
```typescript
|
|
70
69
|
// quickback/features/posts/posts.ts
|
|
@@ -33,6 +33,12 @@ my-app/
|
|
|
33
33
|
export default {
|
|
34
34
|
name: "my-app",
|
|
35
35
|
template: "hono",
|
|
36
|
+
auth: {
|
|
37
|
+
// Role hierarchy: lowest → highest privilege.
|
|
38
|
+
// Use "role+" in access rules to mean "this role and above".
|
|
39
|
+
// e.g. roles: ["member+"] expands to ["member", "admin", "owner"].
|
|
40
|
+
roleHierarchy: ["member", "admin", "owner"],
|
|
41
|
+
},
|
|
36
42
|
providers: {
|
|
37
43
|
runtime: { name: "cloudflare", config: {} },
|
|
38
44
|
database: {
|
|
@@ -96,7 +102,7 @@ quickback compile
|
|
|
96
102
|
|
|
97
103
|
## Setup Steps
|
|
98
104
|
|
|
99
|
-
Follow the same setup steps as the [Cloudflare template](/compiler/getting-started/template-cloudflare#setup-steps).
|
|
105
|
+
Follow the same setup steps as the [Cloudflare template](/compiler/getting-started/template-cloudflare#setup-steps). Compiling with zero features works (you get an auth-only API); add feature files as you go and recompile.
|
|
100
106
|
|
|
101
107
|
## Next Steps
|
|
102
108
|
|
|
@@ -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
|
|