@quickback-dev/cli 0.16.4 → 0.17.1
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/README.md +7 -3
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +12 -48
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/create.d.ts +20 -0
- package/dist/commands/create.d.ts.map +1 -1
- package/dist/commands/create.js +216 -151
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/login.d.ts +4 -2
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/login.js +25 -17
- package/dist/commands/login.js.map +1 -1
- package/dist/commands/start.d.ts +20 -0
- package/dist/commands/start.d.ts.map +1 -0
- package/dist/commands/start.js +163 -0
- package/dist/commands/start.js.map +1 -0
- package/dist/commands/whoami.d.ts.map +1 -1
- package/dist/commands/whoami.js +5 -4
- package/dist/commands/whoami.js.map +1 -1
- package/dist/docs/content.js +37 -37
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +27 -10
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.js +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +15 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/auth.d.ts +39 -3
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js +57 -3
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/drizzle-meta-routing.test.js +16 -3
- package/dist/lib/drizzle-meta-routing.test.js.map +1 -1
- package/dist/lib/file-loader.d.ts +6 -4
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +30 -27
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +16 -7
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +145 -0
- package/dist/skill/docs/compiler/config/providers.md +87 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +5 -11
- package/dist/skill/docs/compiler/definitions/access.md +43 -57
- package/dist/skill/docs/compiler/definitions/feature.md +7 -11
- package/dist/skill/docs/compiler/definitions/firewall.md +2 -4
- package/dist/skill/docs/compiler/definitions/guards.md +16 -18
- package/dist/skill/docs/compiler/definitions/index.md +10 -14
- package/dist/skill/docs/compiler/definitions/masking.md +6 -6
- package/dist/skill/docs/compiler/definitions/read.md +6 -11
- package/dist/skill/docs/compiler/definitions/schema.md +19 -17
- package/dist/skill/docs/compiler/definitions/views.md +3 -5
- package/dist/skill/docs/compiler/getting-started/full-example.md +6 -8
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
- package/dist/skill/docs/compiler/getting-started/index.md +23 -20
- package/dist/skill/docs/compiler/getting-started/patterns.md +19 -31
- package/dist/skill/docs/compiler/getting-started/template-blog.md +6 -10
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
- package/dist/skill/docs/compiler/getting-started/template-empty.md +3 -5
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
- package/dist/skill/docs/compiler/troubleshooting.md +10 -0
- package/dist/skill/docs/stack/auth/security.md +69 -0
- package/dist/skill/docs/stack/cms/actions.md +28 -0
- package/dist/skill/docs/stack/cms/connecting.md +2 -2
- package/dist/skill/docs/stack/cms/index.md +2 -2
- package/dist/skill/docs/stack/cms/record-layouts.md +19 -19
- package/dist/skill/docs/stack/cms/schema-format.md +33 -3
- package/dist/skill/docs/stack/cms/schema-registry.md +22 -2
- package/dist/skill/docs/stack/cms/security.md +10 -12
- package/dist/skill/docs/stack/cms/table-views.md +1 -1
- package/dist/skill/docs/stack/realtime/durable-objects.md +46 -5
- package/dist/skill/docs/stack/realtime/index.md +20 -3
- package/dist/skill/docs/stack/realtime/using-realtime.md +8 -6
- package/dist/skill/docs/stack/vector/embeddings.md +7 -6
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +183 -2
- package/src/skill/docs/compiler/config/index.md +13 -11
- package/src/skill/docs/compiler/config/providers.md +87 -0
- package/src/skill/docs/compiler/config/single-tenant.md +5 -11
- package/src/skill/docs/compiler/definitions/access.md +43 -57
- package/src/skill/docs/compiler/definitions/feature.md +7 -11
- package/src/skill/docs/compiler/definitions/firewall.md +2 -4
- package/src/skill/docs/compiler/definitions/guards.md +16 -18
- package/src/skill/docs/compiler/definitions/index.md +10 -14
- package/src/skill/docs/compiler/definitions/masking.md +6 -6
- package/src/skill/docs/compiler/definitions/read.md +6 -11
- package/src/skill/docs/compiler/definitions/schema.md +18 -18
- package/src/skill/docs/compiler/definitions/views.md +3 -5
- package/src/skill/docs/compiler/getting-started/full-example.md +6 -8
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
- package/src/skill/docs/compiler/getting-started/index.md +23 -20
- package/src/skill/docs/compiler/getting-started/patterns.md +19 -31
- package/src/skill/docs/compiler/getting-started/template-blog.md +6 -10
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
- package/src/skill/docs/compiler/getting-started/template-empty.md +3 -5
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
- package/src/skill/docs/compiler/troubleshooting.md +10 -0
- package/src/skill/docs/stack/auth/security.md +69 -0
- package/src/skill/docs/stack/cms/actions.md +28 -0
- package/src/skill/docs/stack/cms/connecting.md +2 -2
- package/src/skill/docs/stack/cms/index.md +2 -2
- package/src/skill/docs/stack/cms/record-layouts.md +19 -19
- package/src/skill/docs/stack/cms/schema-format.md +33 -3
- package/src/skill/docs/stack/cms/schema-registry.md +22 -2
- package/src/skill/docs/stack/cms/security.md +10 -12
- package/src/skill/docs/stack/cms/table-views.md +1 -1
- package/src/skill/docs/stack/realtime/durable-objects.md +46 -5
- package/src/skill/docs/stack/realtime/index.md +20 -3
- package/src/skill/docs/stack/realtime/using-realtime.md +8 -6
- package/src/skill/docs/stack/vector/embeddings.md +7 -6
|
@@ -84,11 +84,9 @@ export default defineTable(products, {
|
|
|
84
84
|
read: {
|
|
85
85
|
access: { roles: ["member+"] },
|
|
86
86
|
},
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
91
|
-
},
|
|
87
|
+
create: { access: { roles: ["member+"] } },
|
|
88
|
+
update: { access: { roles: ["member+"] } },
|
|
89
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
92
90
|
});
|
|
93
91
|
```
|
|
94
92
|
|
|
@@ -1,22 +1,22 @@
|
|
|
1
1
|
# Batch Operations
|
|
2
2
|
|
|
3
|
-
Batch operations let you create, update, or delete multiple records in a single request. They are **auto-enabled** when the corresponding
|
|
3
|
+
Batch operations let you create, update, upsert, or delete multiple records in a single request. They are **auto-enabled** when the corresponding write operation exists in your definition.
|
|
4
4
|
|
|
5
5
|
## Available Endpoints
|
|
6
6
|
|
|
7
7
|
| Endpoint | Method | Auto-enabled When |
|
|
8
8
|
|----------|--------|-------------------|
|
|
9
|
-
| `/{resource}/batch` | `POST` | `
|
|
10
|
-
| `/{resource}/batch` | `PATCH` | `
|
|
11
|
-
| `/{resource}/batch` | `DELETE` | `
|
|
12
|
-
| `/{resource}/batch` | `PUT` | `
|
|
9
|
+
| `/{resource}/batch` | `POST` | `create` exists |
|
|
10
|
+
| `/{resource}/batch` | `PATCH` | `update` exists |
|
|
11
|
+
| `/{resource}/batch` | `DELETE` | `delete` exists |
|
|
12
|
+
| `/{resource}/batch` | `PUT` | `upsert` exists |
|
|
13
13
|
|
|
14
14
|
To disable a batch operation, set it to `false` in your definition:
|
|
15
15
|
|
|
16
16
|
```typescript
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
create: {
|
|
18
|
+
access: { roles: ['hiring-manager'] },
|
|
19
|
+
batch: false, // Disable batch create
|
|
20
20
|
}
|
|
21
21
|
```
|
|
22
22
|
|
|
@@ -309,33 +309,39 @@ The default maximum batch size is **100 records**. Requests exceeding the limit
|
|
|
309
309
|
|
|
310
310
|
## Configuration
|
|
311
311
|
|
|
312
|
-
Batch operations inherit access control from their corresponding
|
|
312
|
+
Batch operations inherit access control from their corresponding write operation. You can override per-batch settings:
|
|
313
313
|
|
|
314
314
|
```typescript
|
|
315
315
|
export default defineTable(applications, {
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
batchCreate: {
|
|
323
|
-
access: { roles: ['hiring-manager'] }, // More restrictive than single create
|
|
324
|
-
maxBatchSize: 50, // Default: 100
|
|
325
|
-
allowFailFast: true, // Default: true
|
|
316
|
+
create: {
|
|
317
|
+
access: { roles: ['hiring-manager', 'recruiter'] },
|
|
318
|
+
batch: {
|
|
319
|
+
access: { roles: ['hiring-manager'] }, // More restrictive than single create
|
|
320
|
+
maxBatchSize: 50, // Default: 100
|
|
321
|
+
allowFailFast: true, // Default: true
|
|
326
322
|
},
|
|
327
|
-
|
|
323
|
+
},
|
|
324
|
+
update: {
|
|
325
|
+
access: { roles: ['hiring-manager', 'recruiter'] },
|
|
326
|
+
batch: {
|
|
328
327
|
maxBatchSize: 100,
|
|
329
328
|
allowFailFast: true,
|
|
330
329
|
},
|
|
331
|
-
|
|
330
|
+
},
|
|
331
|
+
delete: {
|
|
332
|
+
access: { roles: ['hiring-manager'] },
|
|
333
|
+
mode: 'soft',
|
|
334
|
+
batch: {
|
|
332
335
|
access: { roles: ['hiring-manager'] },
|
|
333
336
|
maxBatchSize: 100,
|
|
334
337
|
allowFailFast: true,
|
|
335
338
|
},
|
|
339
|
+
},
|
|
336
340
|
|
|
337
|
-
|
|
338
|
-
|
|
341
|
+
// Disable only batch upsert
|
|
342
|
+
upsert: {
|
|
343
|
+
access: { roles: ['hiring-manager'] },
|
|
344
|
+
batch: false,
|
|
339
345
|
},
|
|
340
346
|
});
|
|
341
347
|
```
|
|
@@ -580,30 +580,28 @@ All batch operation errors include:
|
|
|
580
580
|
|
|
581
581
|
#### Configuration
|
|
582
582
|
|
|
583
|
-
Batch operations are **auto-enabled** when corresponding
|
|
583
|
+
Batch operations are **auto-enabled** when corresponding write operations exist:
|
|
584
584
|
|
|
585
585
|
```typescript
|
|
586
586
|
// Auto-enabled - no configuration needed
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
// batchCreate and batchUpdate automatically available
|
|
591
|
-
}
|
|
587
|
+
create: { access: { roles: ['recruiter'] } },
|
|
588
|
+
update: { access: { roles: ['recruiter'] } }
|
|
589
|
+
// create.batch and update.batch automatically available
|
|
592
590
|
|
|
593
591
|
// Customize batch operations
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
592
|
+
create: {
|
|
593
|
+
access: { roles: ['recruiter'] },
|
|
594
|
+
batch: {
|
|
597
595
|
access: { roles: ['hiring-manager'] }, // Different access rules
|
|
598
|
-
maxBatchSize: 50,
|
|
599
|
-
allowFailFast: false
|
|
596
|
+
maxBatchSize: 50, // Lower limit
|
|
597
|
+
allowFailFast: false // Disable failFast mode
|
|
600
598
|
}
|
|
601
599
|
}
|
|
602
600
|
|
|
603
601
|
// Disable batch operations
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
602
|
+
create: {
|
|
603
|
+
access: { roles: ['recruiter'] },
|
|
604
|
+
batch: false // Explicitly disable
|
|
607
605
|
}
|
|
608
606
|
```
|
|
609
607
|
|
|
@@ -140,18 +140,21 @@ const { data, error } = await client.GET('/api/v1/jobs', { params: { query: { li
|
|
|
140
140
|
| `true` (default) | Write `api-types.gen.ts` to the project root |
|
|
141
141
|
| `false` | Don't emit the types file |
|
|
142
142
|
| `"src/lib/api-types.ts"` | Custom output path (relative to project root) |
|
|
143
|
+
| `["api-types.gen.ts", "apps/web/src/lib/api-types.gen.ts"]` | Write the same generated types to multiple paths in one compile |
|
|
143
144
|
|
|
144
145
|
```typescript
|
|
145
146
|
// quickback.config.ts
|
|
146
147
|
export default defineConfig({
|
|
147
148
|
// ...
|
|
148
149
|
openapi: {
|
|
149
|
-
types: 'src/lib/api-types.gen.ts',
|
|
150
|
+
types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'],
|
|
150
151
|
},
|
|
151
152
|
});
|
|
152
153
|
```
|
|
153
154
|
|
|
154
|
-
The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. Skipped automatically when `openapi.generate` is `false`.
|
|
155
|
+
The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback compile` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
|
|
156
|
+
|
|
157
|
+
The bundled Quickback CMS and Account SPAs do not import `api-types.gen.ts`. CMS is driven by `schema-registry.json`, and Account uses Better Auth plus small hand-written fetch helpers. Use `openapi.types` for your own colocated client apps.
|
|
155
158
|
|
|
156
159
|
### External viewer
|
|
157
160
|
|
|
@@ -42,15 +42,13 @@ GET /api/v1/jobs?department.in=Engineering,Design,Product
|
|
|
42
42
|
GET /api/v1/jobs?limit=25&offset=50
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
The default `limit` can be configured per-resource in your definition:
|
|
45
|
+
The default `limit` can be configured per-resource in your `read` definition:
|
|
46
46
|
|
|
47
47
|
```typescript
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
maxPageSize: 100, // Maximum allowed limit
|
|
53
|
-
},
|
|
48
|
+
read: {
|
|
49
|
+
access: { roles: ["recruiter"] },
|
|
50
|
+
pageSize: 25, // Default limit
|
|
51
|
+
maxPageSize: 100, // Maximum allowed limit
|
|
54
52
|
},
|
|
55
53
|
```
|
|
56
54
|
|
|
@@ -65,6 +65,16 @@ To clean up, you'd need to manually create a migration.
|
|
|
65
65
|
|
|
66
66
|
If compilation fails with `drizzle-kit requested interactive rename input`, add explicit rename hints in your config. See [Drizzle rename prompts](/compiler/cloud-compiler/troubleshooting#drizzle-rename-prompts-in-ciheadless-compile).
|
|
67
67
|
|
|
68
|
+
### Cloudflare D1 destructive migrations
|
|
69
|
+
|
|
70
|
+
Quickback now adds a D1-specific safety pass around Drizzle-generated migrations for the `cloudflare-d1` provider:
|
|
71
|
+
|
|
72
|
+
1. **Better Auth cleanup** for retired managed tables is stripped instead of shipped as raw `DROP TABLE` SQL.
|
|
73
|
+
2. **Drop-only cleanup migrations** are reordered child-first when foreign keys require it.
|
|
74
|
+
3. **All D1 migration directories** generated by the compiler are replayed against SQLite during compile, so a D1-breaking migration fails before deploy.
|
|
75
|
+
|
|
76
|
+
If `quickback compile` now fails with a D1 replay error, treat that as a real migration problem instead of a deploy-time surprise. The generated SQL needs manual intervention or a schema change that Drizzle can express more safely.
|
|
77
|
+
|
|
68
78
|
## Runtime Issues
|
|
69
79
|
|
|
70
80
|
### 401 on all requests
|
|
@@ -138,6 +138,75 @@ rateLimit: {
|
|
|
138
138
|
|
|
139
139
|
---
|
|
140
140
|
|
|
141
|
+
## Bearer Tokens and Cookie Precedence
|
|
142
|
+
|
|
143
|
+
Quickback supports three bearer-token flavors alongside the standard browser session cookie:
|
|
144
|
+
|
|
145
|
+
| Credential | Used by | Resolved by |
|
|
146
|
+
|------------|---------|-------------|
|
|
147
|
+
| Session cookie | Browser SPAs (CMS, Account, your app) | Better Auth session lookup |
|
|
148
|
+
| Session-token bearer | API clients that grabbed `set-auth-token` | Better Auth `bearer` plugin |
|
|
149
|
+
| JWT bearer | API clients that hit `/api/v1/token` | In-worker JWT fast-path (no DB hit) |
|
|
150
|
+
| API-key bearer | Long-lived programmatic access | `apiKey` plugin / `x-api-key` / `?api_key=` |
|
|
151
|
+
|
|
152
|
+
These match Better Auth's own framing of bearer tokens as **an alternative to cookies, not a supplement** — a request uses one or the other.
|
|
153
|
+
|
|
154
|
+
### Precedence: bearer always wins
|
|
155
|
+
|
|
156
|
+
If a request carries both `Authorization` and `Cookie` headers, the bearer wins universally and the cookie is dropped before session resolution:
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
Request Resolved as
|
|
160
|
+
────────────────────────────────────── ─────────────
|
|
161
|
+
Cookie only cookie session
|
|
162
|
+
Authorization: Bearer <jwt> JWT claims
|
|
163
|
+
Authorization: Bearer <api-key> API-key owner
|
|
164
|
+
Authorization: Bearer <session-token> bearer session
|
|
165
|
+
Cookie + Authorization: Bearer <token> bearer wins, cookie ignored
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
This closes a class of silent-impersonation bugs where an ambient session cookie (multi-account browser tabs, a malicious extension, a misconfigured proxy injecting `Set-Cookie`) would otherwise override an explicit bearer credential. The decision is made before `getSession()` runs, so it applies to every code path in the auth middleware.
|
|
169
|
+
|
|
170
|
+
The api-key and JWT bearers also short-circuit before cookie resolution via dedicated fast-paths — they never touch the database for session lookup. Only session-token bearers reach `getSession()`, where Better Auth's `bearer` plugin resolves the `Authorization` header.
|
|
171
|
+
|
|
172
|
+
### `requireSignature: true` is the secure default
|
|
173
|
+
|
|
174
|
+
Quickback configures the Better Auth `bearer` plugin with `requireSignature: true` by default. This means:
|
|
175
|
+
|
|
176
|
+
- The session token Better Auth emits via the `set-auth-token` response header is **signed server-side** with `BETTER_AUTH_SECRET`.
|
|
177
|
+
- Unsigned bearer tokens are **rejected** at the plugin layer before any session lookup happens.
|
|
178
|
+
- A session token leaked via a proxy access log, a browser dev-tools panel, or a misrouted `Referer` header **cannot** be replayed as a bearer token by an attacker — they would need the signing secret to forge a valid signature.
|
|
179
|
+
|
|
180
|
+
Better Auth's own default for this option is `false`. Quickback overrides it on the secure side. JWT bearers and agent-auth bearers are independently signed and unaffected by this setting.
|
|
181
|
+
|
|
182
|
+
### Overriding the default
|
|
183
|
+
|
|
184
|
+
If a project genuinely needs unsigned bearers (e.g., a closed loopback service where signing is redundant), pass an explicit object:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
auth: defineAuth("better-auth", {
|
|
188
|
+
plugins: {
|
|
189
|
+
bearer: { requireSignature: false },
|
|
190
|
+
},
|
|
191
|
+
})
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
User-supplied options merge on top of the secure default, so any other [`bearer` plugin option](https://better-auth.com/docs/plugins/bearer) can be passed the same way.
|
|
195
|
+
|
|
196
|
+
### Threat model and trade-offs
|
|
197
|
+
|
|
198
|
+
| Threat | Mitigation |
|
|
199
|
+
|--------|-----------|
|
|
200
|
+
| Stolen session-token bearer replayed against the API | `requireSignature: true` blocks unsigned values |
|
|
201
|
+
| Browser extension injects a victim's session cookie into an attacker's bearer-authed API call | Cookie stripped when `Authorization` is present |
|
|
202
|
+
| Multi-account user has cookies for two identities and uses bearer for the second | Bearer identity wins; no ambiguity in audit log |
|
|
203
|
+
| MCP / agent flow exposed to ambient browser cookies | `/mcp` and agent-auth routes are bearer-only (cookies dropped entirely, see [Agent Auth](/stack/auth/plugins/agent-auth)) |
|
|
204
|
+
| Alg-confusion / forged JWT (alg=none, HS384, RS256) | Verifier pins HS256; signature math rejects all non-matching algs uniformly with 401 |
|
|
205
|
+
|
|
206
|
+
For a deeper walkthrough of the bearer flow itself, see the upstream [Better Auth bearer plugin docs](https://better-auth.com/docs/plugins/bearer).
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
141
210
|
## Cross-Domain Authentication
|
|
142
211
|
|
|
143
212
|
For applications spanning multiple subdomains (e.g., `account.example.com`, `api.example.com`, `dashboard.example.com`), Quickback provides dual-layer security.
|
|
@@ -106,6 +106,8 @@ Actions can include an optional `cms` property for enhanced CMS rendering. Actio
|
|
|
106
106
|
| `destructive` | `boolean` | `false` | Red styling + requires confirmation |
|
|
107
107
|
| `category` | `string` | none | Group actions under a header |
|
|
108
108
|
| `hidden` | `boolean` | `false` | Hide from CMS entirely (API-only actions) |
|
|
109
|
+
| `placement` | `"feature" \| "tables"` | none | Where standalone actions appear in multi-table features |
|
|
110
|
+
| `tables` | `string[]` | none | Explicit table list when `placement` is `"tables"` |
|
|
109
111
|
| `successMessage` | `string` | none | Toast message after success |
|
|
110
112
|
| `onSuccess` | `"refresh" \| "redirect:list" \| "close"` | `"refresh"` | Behavior after successful execution |
|
|
111
113
|
| `order` | `number` | `0` | Sort priority (lower = first) |
|
|
@@ -177,6 +179,32 @@ This provides a visual cue that the action has permanent consequences.
|
|
|
177
179
|
|
|
178
180
|
Actions with `path:` set are standalone — not tied to a specific record. They appear in a separate section and don't receive a `recordId` when executed. The CMS passes `null` as the record ID for standalone actions.
|
|
179
181
|
|
|
182
|
+
### Placement in Multi-Table Features
|
|
183
|
+
|
|
184
|
+
When a standalone action belongs to a feature with multiple tables, the CMS needs to know where to render it.
|
|
185
|
+
|
|
186
|
+
- Use `cms.placement: "feature"` to show the action in the table toolbar for every table in that feature.
|
|
187
|
+
- Use `cms.placement: "tables"` with `cms.tables` to show it only on specific tables.
|
|
188
|
+
- Use `cms.hidden: true` to keep it API-only.
|
|
189
|
+
|
|
190
|
+
Single-table features and clearly table-scoped standalone paths are inferred automatically. Feature-root standalone actions in multi-table features should set placement explicitly.
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
defineAction({
|
|
194
|
+
path: "/chat/post-message",
|
|
195
|
+
method: "POST",
|
|
196
|
+
access: { roles: ["member"] },
|
|
197
|
+
cms: {
|
|
198
|
+
label: "Post Message",
|
|
199
|
+
placement: "tables",
|
|
200
|
+
tables: ["chatChannels", "chatMessages"],
|
|
201
|
+
},
|
|
202
|
+
async execute() {
|
|
203
|
+
return { ok: true };
|
|
204
|
+
},
|
|
205
|
+
});
|
|
206
|
+
```
|
|
207
|
+
|
|
180
208
|
## File Response Actions
|
|
181
209
|
|
|
182
210
|
Actions with `responseType: "file"` show a download icon instead of the lightning bolt. When executed, the response is treated as a file download rather than a JSON result.
|
|
@@ -155,10 +155,10 @@ CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the B
|
|
|
155
155
|
- **Account UI** hides the "Go to CMS" button for non-admins.
|
|
156
156
|
- **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-admin. A non-admin who types the CMS URL directly cannot load the app.
|
|
157
157
|
- **`/api/v1/schema`** returns `403 Admin access required` to non-admin callers, so schema metadata can't be scraped by hitting the API directly.
|
|
158
|
-
- **`custom_view`
|
|
158
|
+
- **`custom_view` routes** are gated on `userRole: ["admin"]` rather than org membership, so saved views can't be listed or modified without admin rights.
|
|
159
159
|
- **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
|
|
160
160
|
|
|
161
|
-
Your resource
|
|
161
|
+
Your resource API endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
|
|
162
162
|
|
|
163
163
|
To allow any authenticated user to access the CMS, opt out explicitly:
|
|
164
164
|
|
|
@@ -116,9 +116,9 @@ CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the u
|
|
|
116
116
|
1. **Account UI link** — the "Go to CMS" button is hidden for non-admins.
|
|
117
117
|
2. **CMS SPA shell** — the Worker returns `403 Admin access required` before serving `index.html` to a non-admin. Unauthenticated requests are redirected to the login page.
|
|
118
118
|
3. **`/api/v1/schema`** — the CMS metadata endpoint checks `ctx.userRole === "admin"` and returns `403` otherwise.
|
|
119
|
-
4. **`custom_view`
|
|
119
|
+
4. **`custom_view` routes** — the CMS-internal saved-views table is gated on `userRole: ["admin"]` (see the [`userRole` access primitive](/compiler/definitions/access#userrole)) rather than org membership.
|
|
120
120
|
|
|
121
|
-
Your resource
|
|
121
|
+
Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
|
|
122
122
|
|
|
123
123
|
To allow any authenticated user, opt out explicitly:
|
|
124
124
|
|
|
@@ -14,7 +14,9 @@ Add a `layouts` property to your `defineTable()` config:
|
|
|
14
14
|
```typescript
|
|
15
15
|
export default defineTable(contacts, {
|
|
16
16
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
17
|
-
|
|
17
|
+
create: { /* ... */ },
|
|
18
|
+
update: { /* ... */ },
|
|
19
|
+
delete: { /* ... */ },
|
|
18
20
|
layouts: {
|
|
19
21
|
default: {
|
|
20
22
|
sections: [
|
|
@@ -106,26 +108,24 @@ export default defineTable(customView, {
|
|
|
106
108
|
read: {
|
|
107
109
|
access: { roles: ["owner", "admin", "member"] },
|
|
108
110
|
},
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
]
|
|
117
|
-
}
|
|
118
|
-
},
|
|
119
|
-
delete: {
|
|
120
|
-
access: {
|
|
121
|
-
or: [
|
|
122
|
-
{ roles: ["owner", "admin"] },
|
|
123
|
-
{ roles: ["member"], record: { createdBy: { equals: "$userId" } } }
|
|
124
|
-
]
|
|
125
|
-
},
|
|
126
|
-
mode: "hard"
|
|
111
|
+
create: { access: { roles: ["owner", "admin", "member"] } },
|
|
112
|
+
update: {
|
|
113
|
+
access: {
|
|
114
|
+
or: [
|
|
115
|
+
{ roles: ["owner", "admin"] },
|
|
116
|
+
{ roles: ["member"], record: { createdBy: { equals: "$userId" } } }
|
|
117
|
+
]
|
|
127
118
|
}
|
|
128
119
|
},
|
|
120
|
+
delete: {
|
|
121
|
+
access: {
|
|
122
|
+
or: [
|
|
123
|
+
{ roles: ["owner", "admin"] },
|
|
124
|
+
{ roles: ["member"], record: { createdBy: { equals: "$userId" } } }
|
|
125
|
+
]
|
|
126
|
+
},
|
|
127
|
+
mode: "hard"
|
|
128
|
+
},
|
|
129
129
|
guards: {
|
|
130
130
|
createable: ["tableName", "name", "description", "layoutConfig", "isShared"],
|
|
131
131
|
updatable: ["name", "description", "layoutConfig", "isShared"]
|
|
@@ -15,6 +15,7 @@ interface SchemaRegistry {
|
|
|
15
15
|
features: Record<string, string[]>;
|
|
16
16
|
tables: Record<string, TableMeta>;
|
|
17
17
|
tablesByFeature: Record<string, string[]>;
|
|
18
|
+
featureActions: Record<string, ActionMeta[]>;
|
|
18
19
|
pages: Record<string, PageMeta>;
|
|
19
20
|
pagesByFeature: Record<string, string[]>;
|
|
20
21
|
}
|
|
@@ -29,6 +30,7 @@ interface SchemaRegistry {
|
|
|
29
30
|
| `features` | Map of feature name to array of source file names |
|
|
30
31
|
| `tables` | Map of camelCase table name to full table metadata |
|
|
31
32
|
| `tablesByFeature` | Map of feature name to array of table names in that feature |
|
|
33
|
+
| `featureActions` | Map of feature name to standalone actions not attached to one table |
|
|
32
34
|
| `pages` | Map of page slug to full page metadata |
|
|
33
35
|
| `pagesByFeature` | Map of feature name to array of page slugs in that feature |
|
|
34
36
|
|
|
@@ -44,6 +46,10 @@ interface TableMeta {
|
|
|
44
46
|
columns: ColumnMeta[];
|
|
45
47
|
firewall: Record<string, unknown>;
|
|
46
48
|
crud: Record<string, CrudConfig>;
|
|
49
|
+
create?: WriteOperationConfig | false;
|
|
50
|
+
update?: WriteOperationConfig | false;
|
|
51
|
+
delete?: WriteOperationConfig | false;
|
|
52
|
+
upsert?: WriteOperationConfig | false;
|
|
47
53
|
guards: GuardsConfig;
|
|
48
54
|
masking: Record<string, MaskingRule>;
|
|
49
55
|
views: Record<string, ViewConfig>;
|
|
@@ -64,12 +70,13 @@ interface TableMeta {
|
|
|
64
70
|
| `feature` | Parent feature name (e.g., `"accounting"`) |
|
|
65
71
|
| `columns` | Ordered array of column metadata |
|
|
66
72
|
| `firewall` | Tenant isolation config (organization, owner, softDelete, exception) |
|
|
67
|
-
| `crud` |
|
|
73
|
+
| `crud` | Legacy normalized write config kept for backwards compatibility |
|
|
74
|
+
| `create` / `update` / `delete` / `upsert` | Flat write-operation aliases mirroring the authored `defineTable(...)` DSL |
|
|
68
75
|
| `guards` | Field-level create/update/immutable/protected rules |
|
|
69
76
|
| `masking` | Per-field masking rules keyed by column name |
|
|
70
77
|
| `views` | Named column projections keyed by view name |
|
|
71
78
|
| `validation` | Per-field validation rules keyed by column name |
|
|
72
|
-
| `actions` | Array of action definitions
|
|
79
|
+
| `actions` | Array of action definitions scoped to this table |
|
|
73
80
|
| `displayColumn` | Column used as human-readable label (auto-detected or explicit) |
|
|
74
81
|
| `defaultSort` | Default sort for CMS table list view (e.g., `{ field: "createdAt", order: "desc" }`) |
|
|
75
82
|
| `inputHints` | Map of column name to preferred CMS input type (e.g., `"richtext"`, `"select"`, `"textarea"`, `"checkbox"`) |
|
|
@@ -114,6 +121,15 @@ interface CrudConfig {
|
|
|
114
121
|
mode?: string;
|
|
115
122
|
}
|
|
116
123
|
|
|
124
|
+
interface WriteOperationConfig extends CrudConfig {
|
|
125
|
+
defaults?: Record<string, unknown>;
|
|
126
|
+
computed?: Record<string, unknown>;
|
|
127
|
+
fields?: string[];
|
|
128
|
+
maxBatchSize?: number;
|
|
129
|
+
allowFailFast?: boolean;
|
|
130
|
+
batch?: false | Record<string, unknown>;
|
|
131
|
+
}
|
|
132
|
+
|
|
117
133
|
interface AccessRule {
|
|
118
134
|
roles?: string[];
|
|
119
135
|
or?: Array<{
|
|
@@ -130,6 +146,9 @@ interface AccessRule {
|
|
|
130
146
|
| `access.or` | Alternative access conditions (any must match) |
|
|
131
147
|
| `access.record` | Record-level conditions for access |
|
|
132
148
|
| `mode` | Operation mode (e.g., `"batch"` for bulk create) |
|
|
149
|
+
| `defaults` / `computed` | Create-time defaults and computed field metadata |
|
|
150
|
+
| `maxBatchSize` / `allowFailFast` | Batch-write controls when the config describes a batch operation |
|
|
151
|
+
| `batch` | Nested batch config for the flat `create` / `update` / `delete` / `upsert` aliases |
|
|
133
152
|
|
|
134
153
|
## GuardsConfig
|
|
135
154
|
|
|
@@ -179,6 +198,8 @@ interface CmsConfig {
|
|
|
179
198
|
destructive?: boolean;
|
|
180
199
|
category?: string;
|
|
181
200
|
hidden?: boolean;
|
|
201
|
+
placement?: 'feature' | 'tables';
|
|
202
|
+
tables?: string[];
|
|
182
203
|
successMessage?: string;
|
|
183
204
|
onSuccess?: 'refresh' | 'redirect:list' | 'close';
|
|
184
205
|
order?: number;
|
|
@@ -204,7 +225,16 @@ interface ActionInputField {
|
|
|
204
225
|
| `method` | HTTP method (defaults to POST) |
|
|
205
226
|
| `responseType` | `"file"` for download responses |
|
|
206
227
|
| `sideEffects` | `"sync"` for actions with synchronous side effects |
|
|
207
|
-
| `cms` | Optional CMS rendering metadata (label, icon, confirm, destructive, category, hidden, successMessage, onSuccess, order) |
|
|
228
|
+
| `cms` | Optional CMS rendering metadata (label, icon, confirm, destructive, category, hidden, placement, tables, successMessage, onSuccess, order) |
|
|
229
|
+
|
|
230
|
+
### CmsConfig placement rules
|
|
231
|
+
|
|
232
|
+
`placement` is only relevant for standalone actions in multi-table features:
|
|
233
|
+
|
|
234
|
+
- `"feature"` shows the action in the toolbar for every table in the feature.
|
|
235
|
+
- `"tables"` shows the action only for the tables listed in `tables`.
|
|
236
|
+
|
|
237
|
+
If the action is already unambiguously table-scoped, the compiler can infer placement and `placement` is optional.
|
|
208
238
|
|
|
209
239
|
### ActionInputField
|
|
210
240
|
|
|
@@ -28,6 +28,7 @@ The top-level structure of `schema-registry.json`:
|
|
|
28
28
|
"features": { ... },
|
|
29
29
|
"tables": { ... },
|
|
30
30
|
"tablesByFeature": { ... },
|
|
31
|
+
"featureActions": { ... },
|
|
31
32
|
"pages": { ... },
|
|
32
33
|
"pagesByFeature": { ... }
|
|
33
34
|
}
|
|
@@ -42,6 +43,7 @@ The top-level structure of `schema-registry.json`:
|
|
|
42
43
|
| `features` | `Record<string, string[]>` | Feature name to file list mapping |
|
|
43
44
|
| `tables` | `Record<string, TableMeta>` | Table name to full metadata |
|
|
44
45
|
| `tablesByFeature` | `Record<string, string[]>` | Feature name to table name list |
|
|
46
|
+
| `featureActions` | `Record<string, ActionMeta[]>` | Feature name to standalone actions not owned by one table |
|
|
45
47
|
| `pages` | `Record<string, PageMeta>` | Page slug to full page metadata |
|
|
46
48
|
| `pagesByFeature` | `Record<string, string[]>` | Feature name to page slug list |
|
|
47
49
|
|
|
@@ -56,7 +58,11 @@ interface TableMeta {
|
|
|
56
58
|
feature: string; // Parent feature name
|
|
57
59
|
columns: ColumnMeta[]; // All columns including audit fields
|
|
58
60
|
firewall: Record<string, unknown>; // Tenant isolation config
|
|
59
|
-
crud: Record<string, CrudConfig>; //
|
|
61
|
+
crud: Record<string, CrudConfig>; // Legacy normalized write surface
|
|
62
|
+
create?: WriteOperationConfig | false; // Flat create config
|
|
63
|
+
update?: WriteOperationConfig | false; // Flat update config
|
|
64
|
+
delete?: WriteOperationConfig | false; // Flat delete config
|
|
65
|
+
upsert?: WriteOperationConfig | false; // Flat upsert config
|
|
60
66
|
guards: {
|
|
61
67
|
createable: string[]; // Fields allowed on create
|
|
62
68
|
updatable: string[]; // Fields allowed on update
|
|
@@ -66,12 +72,26 @@ interface TableMeta {
|
|
|
66
72
|
masking: Record<string, MaskingRule>; // Per-field masking rules
|
|
67
73
|
views: Record<string, ViewConfig>; // Named column projections
|
|
68
74
|
validation: Record<string, ValidationRule>; // Per-field validation
|
|
69
|
-
actions: ActionMeta[]; //
|
|
75
|
+
actions: ActionMeta[]; // Table-scoped actions for this table
|
|
70
76
|
displayColumn?: string; // Human-readable label column
|
|
71
77
|
internal?: boolean; // Hidden from CMS sidebar when true
|
|
72
78
|
}
|
|
73
79
|
```
|
|
74
80
|
|
|
81
|
+
`create`, `update`, `delete`, and `upsert` mirror the preferred flat DSL from `defineTable(...)`. The legacy `crud` block is still emitted for backwards compatibility with older consumers.
|
|
82
|
+
|
|
83
|
+
## Feature Actions
|
|
84
|
+
|
|
85
|
+
Standalone actions do not always belong to a single table. When an action is attached to a multi-table feature root, the compiler emits it under `featureActions[featureName]` instead of duplicating it across every table.
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
interface SchemaRegistry {
|
|
89
|
+
featureActions: Record<string, ActionMeta[]>;
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The CMS uses `featureActions` for toolbar-style actions that apply to the feature as a whole. Use `cms.placement` on standalone actions to control whether they show for the whole feature or only selected tables.
|
|
94
|
+
|
|
75
95
|
> **Internal Tables**
|
|
76
96
|
>
|
|
77
97
|
> Tables without a `defineTable()` resource config are marked `internal: true` and hidden from the CMS sidebar. These are typically join tables or system tables.
|
|
@@ -15,10 +15,10 @@ Under the default `access: "admin"`, the compiler emits server-side gates on eve
|
|
|
15
15
|
1. **Account UI** — the "Go to CMS" button is hidden.
|
|
16
16
|
2. **CMS SPA shell** — the Worker checks `ctx.userRole === "admin"` before serving `index.html`. Unauthenticated requests are redirected to login; authenticated non-admins get `403 Admin access required`.
|
|
17
17
|
3. **`/api/v1/schema`** — the CMS metadata endpoint returns `403` to non-admins.
|
|
18
|
-
4. **`custom_view`
|
|
18
|
+
4. **`custom_view` routes** — the CMS-internal saved-views table uses `userRole: ["admin"]` (see [`userRole`](/compiler/definitions/access#userrole-vs-roles)), so saved views can't be read or modified from outside the CMS by non-admin accounts.
|
|
19
19
|
5. **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
|
|
20
20
|
|
|
21
|
-
Your resource
|
|
21
|
+
Your resource API endpoints keep whatever `read`, `create`, `update`, `delete`, or `upsert` access rules you defined — they're the app's data API and unaffected by the CMS gate.
|
|
22
22
|
|
|
23
23
|
## The Four Layers
|
|
24
24
|
|
|
@@ -27,7 +27,7 @@ Quickback enforces security through four complementary layers:
|
|
|
27
27
|
| Layer | Purpose | CMS Behavior |
|
|
28
28
|
|-------|---------|-------------|
|
|
29
29
|
| **Firewall** | Tenant isolation (org-scoped data) | Handled server-side. CMS cannot bypass it. |
|
|
30
|
-
| **
|
|
30
|
+
| **Operation Access** | Per-operation role requirements | Buttons hidden when role lacks permission |
|
|
31
31
|
| **Guards** | Field-level create/update control | Form fields enabled/disabled per guard rules |
|
|
32
32
|
| **Masking** | Sensitive field redaction | Masked values with lock icons per role |
|
|
33
33
|
|
|
@@ -36,20 +36,18 @@ Quickback enforces security through four complementary layers:
|
|
|
36
36
|
The CMS header includes a **role switcher** (in demo mode) or reads the user's actual role from their organization membership (in live mode). The three roles are:
|
|
37
37
|
|
|
38
38
|
- **owner** — Full access to all operations and data
|
|
39
|
-
- **admin** — Elevated access, typically all
|
|
39
|
+
- **admin** — Elevated access, typically all write operations and most actions
|
|
40
40
|
- **member** — Standard access with restrictions on sensitive data and destructive actions
|
|
41
41
|
|
|
42
|
-
###
|
|
42
|
+
### Operation Button Visibility
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
Create, edit, and delete buttons are shown or hidden based on the current role's access:
|
|
45
45
|
|
|
46
46
|
```typescript
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
delete: { access: { roles: ['owner'] } },
|
|
52
|
-
}
|
|
47
|
+
read: { access: { roles: ['member', 'admin', 'owner'] } },
|
|
48
|
+
create: { access: { roles: ['admin', 'owner'] } },
|
|
49
|
+
update: { access: { roles: ['admin', 'owner'] } },
|
|
50
|
+
delete: { access: { roles: ['owner'] } },
|
|
53
51
|
```
|
|
54
52
|
|
|
55
53
|
With the config above:
|
|
@@ -25,7 +25,7 @@ The three-dot menu on each row provides:
|
|
|
25
25
|
| Custom actions | Filtered by role + record state | Run actions like approve, void, post |
|
|
26
26
|
| Delete | When role has `delete` access | Delete with confirmation |
|
|
27
27
|
|
|
28
|
-
Actions are filtered by the current role's
|
|
28
|
+
Actions are filtered by the current role's write permissions and the action's access conditions. For example, an "approve" action that requires `status === "pending"` only appears on pending records.
|
|
29
29
|
|
|
30
30
|
## Data Table Mode
|
|
31
31
|
|