@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.
Files changed (107) hide show
  1. package/dist/commands/claude.d.ts.map +1 -1
  2. package/dist/commands/claude.js +8 -0
  3. package/dist/commands/claude.js.map +1 -1
  4. package/dist/commands/compile.d.ts.map +1 -1
  5. package/dist/commands/compile.js +13 -2
  6. package/dist/commands/compile.js.map +1 -1
  7. package/dist/commands/compile.test.js +26 -21
  8. package/dist/commands/compile.test.js.map +1 -1
  9. package/dist/commands/create.js +6 -9
  10. package/dist/commands/create.js.map +1 -1
  11. package/dist/commands/login.d.ts.map +1 -1
  12. package/dist/commands/login.js +0 -9
  13. package/dist/commands/login.js.map +1 -1
  14. package/dist/commands/start.d.ts.map +1 -1
  15. package/dist/commands/start.js +6 -7
  16. package/dist/commands/start.js.map +1 -1
  17. package/dist/commands/whoami.d.ts.map +1 -1
  18. package/dist/commands/whoami.js +0 -4
  19. package/dist/commands/whoami.js.map +1 -1
  20. package/dist/docs/content.d.ts.map +1 -1
  21. package/dist/docs/content.js +22 -32
  22. package/dist/docs/content.js.map +1 -1
  23. package/dist/index.js +1 -1
  24. package/dist/lib/api-client.d.ts +0 -12
  25. package/dist/lib/api-client.d.ts.map +1 -1
  26. package/dist/lib/api-client.js +0 -10
  27. package/dist/lib/api-client.js.map +1 -1
  28. package/dist/lib/api-client.test.js +13 -8
  29. package/dist/lib/api-client.test.js.map +1 -1
  30. package/dist/lib/auth.d.ts +0 -1
  31. package/dist/lib/auth.d.ts.map +1 -1
  32. package/dist/lib/auth.js.map +1 -1
  33. package/dist/lib/compiler-stubs.d.ts +12 -0
  34. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  35. package/dist/lib/compiler-stubs.js +18 -0
  36. package/dist/lib/compiler-stubs.js.map +1 -1
  37. package/dist/lib/file-loader.d.ts +14 -0
  38. package/dist/lib/file-loader.d.ts.map +1 -1
  39. package/dist/lib/file-loader.js +63 -9
  40. package/dist/lib/file-loader.js.map +1 -1
  41. package/dist/skill/SKILL.md +76 -6
  42. package/dist/skill/docs/changelog.md +278 -0
  43. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +1 -2
  44. package/dist/skill/docs/compiler/cloud-compiler/cli.md +7 -8
  45. package/dist/skill/docs/compiler/config/agents.md +49 -1
  46. package/dist/skill/docs/compiler/config/auth.md +20 -5
  47. package/dist/skill/docs/compiler/config/security.md +46 -0
  48. package/dist/skill/docs/compiler/definitions/access.md +1 -1
  49. package/dist/skill/docs/compiler/definitions/actions.md +46 -4
  50. package/dist/skill/docs/compiler/definitions/diagnostics.md +88 -57
  51. package/dist/skill/docs/compiler/definitions/scopes.md +11 -3
  52. package/dist/skill/docs/compiler/getting-started/full-example.md +5 -3
  53. package/dist/skill/docs/compiler/getting-started/index.md +7 -7
  54. package/dist/skill/docs/compiler/getting-started/patterns.md +39 -5
  55. package/dist/skill/docs/compiler/getting-started/template-blog.md +65 -44
  56. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +4 -5
  57. package/dist/skill/docs/compiler/getting-started/template-empty.md +7 -1
  58. package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +23 -0
  60. package/dist/skill/docs/stack/account-ui/features/passwordless.md +4 -10
  61. package/dist/skill/docs/stack/account-ui/hooks.md +24 -1
  62. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +0 -7
  63. package/dist/skill/docs/stack/auth/plugins/index.md +36 -39
  64. package/dist/templates/registry.d.ts +0 -12
  65. package/dist/templates/registry.d.ts.map +1 -1
  66. package/dist/templates/registry.js +0 -42
  67. package/dist/templates/registry.js.map +1 -1
  68. package/package.json +1 -1
  69. package/src/skill/SKILL.md +76 -6
  70. package/src/skill/docs/changelog.md +278 -0
  71. package/src/skill/docs/compiler/cloud-compiler/authentication.md +1 -2
  72. package/src/skill/docs/compiler/cloud-compiler/cli.md +7 -8
  73. package/src/skill/docs/compiler/config/agents.md +49 -1
  74. package/src/skill/docs/compiler/config/auth.md +20 -5
  75. package/src/skill/docs/compiler/config/security.md +46 -0
  76. package/src/skill/docs/compiler/definitions/access.md +1 -1
  77. package/src/skill/docs/compiler/definitions/actions.md +46 -4
  78. package/src/skill/docs/compiler/definitions/diagnostics.md +88 -57
  79. package/src/skill/docs/compiler/definitions/scopes.md +11 -3
  80. package/src/skill/docs/compiler/getting-started/full-example.md +5 -3
  81. package/src/skill/docs/compiler/getting-started/index.md +7 -7
  82. package/src/skill/docs/compiler/getting-started/patterns.md +39 -5
  83. package/src/skill/docs/compiler/getting-started/template-blog.md +65 -44
  84. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +4 -5
  85. package/src/skill/docs/compiler/getting-started/template-empty.md +7 -1
  86. package/src/skill/docs/compiler/getting-started/templates.md +6 -6
  87. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +23 -0
  88. package/src/skill/docs/stack/account-ui/features/passwordless.md +4 -10
  89. package/src/skill/docs/stack/account-ui/hooks.md +24 -1
  90. package/src/skill/docs/stack/auth/plugins/aws-ses.md +0 -7
  91. package/src/skill/docs/stack/auth/plugins/index.md +36 -39
  92. package/dist/commands/init.d.ts +0 -6
  93. package/dist/commands/init.d.ts.map +0 -1
  94. package/dist/commands/init.js +0 -405
  95. package/dist/commands/init.js.map +0 -1
  96. package/dist/lib/sweep-stale.d.ts +0 -25
  97. package/dist/lib/sweep-stale.d.ts.map +0 -1
  98. package/dist/lib/sweep-stale.js +0 -179
  99. package/dist/lib/sweep-stale.js.map +0 -1
  100. package/dist/lib/sweep-stale.test.d.ts +0 -2
  101. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  102. package/dist/lib/sweep-stale.test.js +0 -130
  103. package/dist/lib/sweep-stale.test.js.map +0 -1
  104. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +0 -74
  105. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +0 -155
  106. package/src/skill/docs/stack/auth/plugins/combo-auth.md +0 -74
  107. 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
- ## Public Read, Authenticated Write
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"], // Recruiters can only update notes
130
- protected: ["stage"], // Stage can only be changed via actions
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.ts # Publish/unpublish 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
- ownerId: text("owner_id").notNull(),
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
- { field: 'ownerId', equals: 'ctx.userId' },
77
- { field: 'deletedAt', isNull: true },
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", "ownerId"],
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`** role on `create`, `update`, and `delete` requires an authenticated user with `member.role === "admin"` in the pinned organization
95
- - **`owner`** firewall scope tracks who created each post via `ownerId`
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 includes publish/unpublish actions with guard conditions:
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
- import { posts } from './posts';
104
- import { defineActions } from '@quickback/compiler';
105
- import { z } from 'zod';
106
-
107
- export default defineActions(posts, {
108
- publish: {
109
- description: "Publish a draft post",
110
- input: z.object({}),
111
- guard: {
112
- roles: ["admin"],
113
- record: { status: { equals: "draft" } },
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
- unpublish: {
118
- description: "Revert a published post to draft",
119
- input: z.object({}),
120
- guard: {
121
- roles: ["admin"],
122
- record: { status: { equals: "published" } },
123
- },
124
- sideEffects: "sync",
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 guards — you can only publish drafts and unpublish published posts.
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 Database
164
+ ### 4. Create D1 Databases
152
165
 
153
- The blog template uses a single D1 database (no split databases):
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 ID from the output and update your `wrangler.toml`:
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/actions/publish \
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
- ownerId: text("owner_id").notNull(),
260
+ authorId: text("author_id").notNull(),
242
261
  });
243
262
 
244
263
  export default defineTable(pages, {
245
- firewall: [{ field: 'ownerId', equals: 'ctx.userId' }],
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-free) — same providers, but with a complete `todos` feature ready to extend.
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-free) for a full multi-tenant example with masking, actions, and a named view.
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). The only difference is you'll need to add at least one feature before compiling.
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. Every template below can be reached either via `start`'s picker (free tier) or scriptably via `quickback create <template> <name>`.
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 (free)
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 (free)
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 (free)
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 (Pro)
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 (Pro)
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 and magic links.
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
- ## Magic Links
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
- When `ENABLE_MAGIC_LINK=true`:
15
+ ## What about magic links?
16
16
 
17
- - Users enter their email address
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 `400 ORG_REQUIRED`. An `after-user-create` hook can auto-provision a personal workspace + member row so the next request just works.
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 AWS SES. When `emailOtp` is enabled, the compiler emits the SES plugin and combo-auth email flow (magic link + OTP).
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
- plugins: ["oauthProvider"],
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 `jwt` plugin alongside `oauthProvider` — `@better-auth/oauth-provider` delegates access-token signing to it, and schema generation fails without it.
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
- **Custom configuration** (object form):
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
- **Verifying tokens in your own Workers / route handlers:**
392
+ **Token and tenant context:**
387
393
 
388
- Issued tokens are JWTs by default — verify them locally without a DB hit:
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
- ```ts
391
- import { createAuthClient } from "better-auth/client";
392
- import { oauthProviderResourceClient } from "@better-auth/oauth-provider/resource-client";
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
 
@@ -1,6 +0,0 @@
1
- interface InitOptions {
2
- path?: string;
3
- }
4
- export declare function init(options?: InitOptions): Promise<void>;
5
- export {};
6
- //# sourceMappingURL=init.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAIA,UAAU,WAAW;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA2Z/D"}