@quickback-dev/cli 0.10.2 → 0.10.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts +9 -1
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +44 -13
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +22 -0
- package/dist/commands/init.js.map +1 -1
- package/dist/cursor/quickback.mdc +24 -13
- package/dist/docs/content.js +11 -11
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +15 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +31 -2
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +58 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/config-sync.d.ts +55 -0
- package/dist/lib/config-sync.d.ts.map +1 -0
- package/dist/lib/config-sync.js +207 -0
- package/dist/lib/config-sync.js.map +1 -0
- package/dist/lib/config-sync.test.d.ts +2 -0
- package/dist/lib/config-sync.test.d.ts.map +1 -0
- package/dist/lib/config-sync.test.js +151 -0
- package/dist/lib/config-sync.test.js.map +1 -0
- package/dist/lib/prepare-output.d.ts +31 -0
- package/dist/lib/prepare-output.d.ts.map +1 -0
- package/dist/lib/prepare-output.js +95 -0
- package/dist/lib/prepare-output.js.map +1 -0
- package/dist/lib/prepare-output.test.d.ts +2 -0
- package/dist/lib/prepare-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-output.test.js +105 -0
- package/dist/lib/prepare-output.test.js.map +1 -0
- package/dist/lib/sweep-stale.d.ts +25 -0
- package/dist/lib/sweep-stale.d.ts.map +1 -0
- package/dist/lib/sweep-stale.js +179 -0
- package/dist/lib/sweep-stale.js.map +1 -0
- package/dist/lib/sweep-stale.test.d.ts +2 -0
- package/dist/lib/sweep-stale.test.d.ts.map +1 -0
- package/dist/lib/sweep-stale.test.js +130 -0
- package/dist/lib/sweep-stale.test.js.map +1 -0
- package/dist/skill/SKILL.md +245 -52
- package/dist/skill/agents/quickback-specialist/AGENT.md +42 -36
- package/package.json +1 -1
- package/src/cursor/quickback.mdc +24 -13
- package/src/skill/SKILL.md +245 -52
- package/src/skill/agents/quickback-specialist/AGENT.md +42 -36
|
@@ -55,47 +55,45 @@ Detect the database dialect from `quickback.config.ts`:
|
|
|
55
55
|
- Cloudflare D1 / SQLite: Use `sqliteTable`, `text`, `integer` from `drizzle-orm/sqlite-core`
|
|
56
56
|
- Supabase / PostgreSQL: Use `pgTable`, `text`, `boolean`, `timestamp` from `drizzle-orm/pg-core`
|
|
57
57
|
|
|
58
|
-
### Table Definition Pattern
|
|
58
|
+
### Table Definition Pattern (recommended: `feature()` + `q.scope()`)
|
|
59
59
|
|
|
60
60
|
```typescript
|
|
61
|
-
import {
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
});
|
|
71
|
-
|
|
72
|
-
export default defineTable(todos, {
|
|
73
|
-
firewall: {
|
|
74
|
-
organization: {}, // Auto-detects 'organizationId' column
|
|
75
|
-
owner: {}, // Auto-detects 'userId' column
|
|
61
|
+
import { feature, q } from "@quickback/compiler";
|
|
62
|
+
|
|
63
|
+
export default feature("todos", {
|
|
64
|
+
columns: {
|
|
65
|
+
id: q.id(),
|
|
66
|
+
title: q.text().required(),
|
|
67
|
+
completed: q.bool().default(false),
|
|
68
|
+
ownerId: q.scope("owner"), // → ctx.userId, auto-firewalled, auto-populated
|
|
69
|
+
organizationId: q.scope("organization"), // → ctx.activeOrgId, same
|
|
76
70
|
},
|
|
71
|
+
// firewall block omitted — q.scope() auto-derives:
|
|
72
|
+
// [{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
73
|
+
// { field: 'ownerId', equals: 'ctx.userId' },
|
|
74
|
+
// { field: 'deletedAt', isNull: true }]
|
|
75
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
77
76
|
crud: {
|
|
78
|
-
list: { access: { roles: ["member", "admin"] } },
|
|
79
|
-
get: { access: { roles: ["member", "admin"] } },
|
|
80
77
|
create: { access: { roles: ["member", "admin"] } },
|
|
81
78
|
update: { access: { roles: ["admin"] } },
|
|
82
79
|
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
83
80
|
},
|
|
84
81
|
guards: {
|
|
85
82
|
createable: ["title", "completed"],
|
|
86
|
-
updatable:
|
|
87
|
-
},
|
|
88
|
-
masking: {
|
|
89
|
-
userId: { type: "redact", show: { roles: ["admin"] } },
|
|
83
|
+
updatable: ["title", "completed"],
|
|
90
84
|
},
|
|
91
85
|
});
|
|
92
86
|
```
|
|
93
87
|
|
|
88
|
+
For Drizzle interop (bringing forward existing schemas), use `sqliteTable` + `defineTable` and rely on auto-detection by column name (`organizationId`, `userId`, `ownerId`, `teamId`).
|
|
89
|
+
|
|
94
90
|
### Actions Pattern
|
|
95
91
|
|
|
92
|
+
Per-action permissions live under `access:` (same shape as resource-level access). Use `whereRecord(table)` for protected-field writes — it AND-merges firewall + soft-delete + the record id in one expression.
|
|
93
|
+
|
|
96
94
|
```typescript
|
|
97
95
|
// quickback/features/todos/actions.ts
|
|
98
|
-
import
|
|
96
|
+
import todos from './todos'; // default import: feature() exports
|
|
99
97
|
import { defineActions } from '@quickback/compiler';
|
|
100
98
|
import { z } from 'zod';
|
|
101
99
|
|
|
@@ -105,18 +103,22 @@ export default defineActions(todos, {
|
|
|
105
103
|
input: z.object({
|
|
106
104
|
completedAt: z.string().datetime().optional(),
|
|
107
105
|
}),
|
|
108
|
-
|
|
106
|
+
access: {
|
|
109
107
|
roles: ["member", "admin"],
|
|
110
108
|
record: { completed: { equals: false } },
|
|
111
109
|
},
|
|
112
|
-
execute: async ({ db, record,
|
|
113
|
-
await db.update(todos)
|
|
110
|
+
execute: async ({ db, record, whereRecord, auditFields }) => {
|
|
111
|
+
await db.update(todos)
|
|
112
|
+
.set({ completed: true, modifiedAt: auditFields.modifiedAt })
|
|
113
|
+
.where(whereRecord!(todos));
|
|
114
114
|
return { success: true };
|
|
115
115
|
},
|
|
116
116
|
},
|
|
117
117
|
});
|
|
118
118
|
```
|
|
119
119
|
|
|
120
|
+
For state-machine fields (status, lifecycle), add `transition: { field, via|to, fromTo }` so the runtime enforces the from→to pair and returns 409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE` on illegal transitions. For cross-tenant or platform-level work, use `unsafe: { reason, adminOnly, crossTenant, targetScope }` (object form is required for new code — auto-injects audit logging).
|
|
121
|
+
|
|
120
122
|
## Security Principles
|
|
121
123
|
|
|
122
124
|
1. **Secure by default** - Nothing is accessible until explicitly opened
|
|
@@ -128,17 +130,21 @@ export default defineActions(todos, {
|
|
|
128
130
|
|
|
129
131
|
### Multi-tenant resource
|
|
130
132
|
```typescript
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
133
|
+
// Auto-derived if organizationId is the only isolation column in the schema —
|
|
134
|
+
// you can omit `firewall:` entirely. Equivalent explicit form:
|
|
135
|
+
firewall: [
|
|
136
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
137
|
+
{ field: 'deletedAt', isNull: true },
|
|
138
|
+
]
|
|
134
139
|
```
|
|
135
140
|
|
|
136
|
-
### Owner-scoped
|
|
141
|
+
### Owner-scoped, org-aware
|
|
137
142
|
```typescript
|
|
138
|
-
firewall:
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
}
|
|
143
|
+
firewall: [
|
|
144
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
145
|
+
{ field: 'ownerId', equals: 'ctx.userId' },
|
|
146
|
+
{ field: 'deletedAt', isNull: true },
|
|
147
|
+
]
|
|
142
148
|
```
|
|
143
149
|
|
|
144
150
|
### Workflow with protected status
|
|
@@ -182,7 +188,7 @@ chat: {
|
|
|
182
188
|
method: "POST",
|
|
183
189
|
responseType: "stream",
|
|
184
190
|
input: z.object({ message: z.string() }),
|
|
185
|
-
|
|
191
|
+
access: { roles: ["member"] },
|
|
186
192
|
handler: "./handlers/chat",
|
|
187
193
|
}
|
|
188
194
|
```
|
|
@@ -200,7 +206,7 @@ export default defineActions(null, {
|
|
|
200
206
|
method: "GET",
|
|
201
207
|
description: "Health check endpoint",
|
|
202
208
|
input: z.object({}),
|
|
203
|
-
|
|
209
|
+
access: { roles: ["member", "admin"] },
|
|
204
210
|
handler: "./handlers/health-check",
|
|
205
211
|
},
|
|
206
212
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.4",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
package/src/cursor/quickback.mdc
CHANGED
|
@@ -63,10 +63,13 @@ export const todos = sqliteTable("todos", {
|
|
|
63
63
|
});
|
|
64
64
|
|
|
65
65
|
export default defineTable(todos, {
|
|
66
|
-
firewall:
|
|
66
|
+
firewall: [
|
|
67
|
+
{ field: "organizationId", equals: "ctx.activeOrgId" },
|
|
68
|
+
{ field: "userId", equals: "ctx.userId" },
|
|
69
|
+
{ field: "deletedAt", isNull: true },
|
|
70
|
+
],
|
|
71
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
67
72
|
crud: {
|
|
68
|
-
list: { access: { roles: ["member", "admin"] } },
|
|
69
|
-
get: { access: { roles: ["member", "admin"] } },
|
|
70
73
|
create: { access: { roles: ["member", "admin"] } },
|
|
71
74
|
update: { access: { roles: ["admin"] } },
|
|
72
75
|
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
@@ -87,25 +90,30 @@ Every request passes through: `Request → Firewall → Access → Guards → Da
|
|
|
87
90
|
|
|
88
91
|
### 1. Firewall — Data Isolation
|
|
89
92
|
|
|
90
|
-
Auto WHERE clauses for tenant isolation:
|
|
93
|
+
Auto WHERE clauses for tenant isolation. Predicates are AND'd:
|
|
91
94
|
|
|
92
95
|
```typescript
|
|
93
|
-
firewall:
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
96
|
+
firewall: [
|
|
97
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' }, // WHERE organizationId = ctx.activeOrgId
|
|
98
|
+
{ field: 'ownerId', equals: 'ctx.userId' }, // AND ownerId = ctx.userId
|
|
99
|
+
{ field: 'teamId', equals: 'ctx.activeTeamId' }, // AND teamId = ctx.activeTeamId
|
|
100
|
+
{ field: 'deletedAt', isNull: true }, // AND deletedAt IS NULL
|
|
101
|
+
]
|
|
102
|
+
|
|
103
|
+
// Public/system resources opt out of tenant scoping (soft-delete still applied):
|
|
104
|
+
firewall: [{ exception: true }]
|
|
100
105
|
```
|
|
101
106
|
|
|
107
|
+
Auto-derived when omitted: scans the schema for `organizationId` / `ownerId` / `teamId` and emits matching predicates. Two or more isolation columns → declare explicitly.
|
|
108
|
+
|
|
102
109
|
### 2. Access — Permission Checks
|
|
103
110
|
|
|
104
|
-
Role-based and record-based (deny by default)
|
|
111
|
+
Role-based and record-based (deny by default). Reads (`GET /` and `GET /:id`) gate via `read.access`; mutations gate via `crud.{create,update,delete}.access`.
|
|
105
112
|
|
|
106
113
|
```typescript
|
|
114
|
+
read: { access: { roles: ['member'] } }, // gates GET / and GET /:id
|
|
107
115
|
crud: {
|
|
108
|
-
|
|
116
|
+
create: { access: { roles: ['admin'] } },
|
|
109
117
|
update: {
|
|
110
118
|
access: {
|
|
111
119
|
or: [
|
|
@@ -114,9 +122,12 @@ crud: {
|
|
|
114
122
|
],
|
|
115
123
|
},
|
|
116
124
|
},
|
|
125
|
+
delete: { access: { roles: ['admin'] } },
|
|
117
126
|
}
|
|
118
127
|
```
|
|
119
128
|
|
|
129
|
+
> **DSL v2:** `crud.list` and `crud.get` are rejected at compile time. Move them to `read.access`.
|
|
130
|
+
|
|
120
131
|
Operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
|
|
121
132
|
Context: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.roles`
|
|
122
133
|
|
package/src/skill/SKILL.md
CHANGED
|
@@ -115,6 +115,38 @@ export default defineConfig({
|
|
|
115
115
|
|
|
116
116
|
Minimal: `account: true` enables with all defaults. `account: { build: false }` skips rebuild on subsequent compiles.
|
|
117
117
|
|
|
118
|
+
### Discoverable options block
|
|
119
|
+
|
|
120
|
+
After the first compile, the file gets a managed comment block bracketed by `// [quickback:options-start]` … `// [quickback:options-end]`. Every option Quickback supports is listed there as a commented-out line. To enable one, lift the line **above** the start sentinel and uncomment — Quickback notices and drops it from the managed block on the next compile to avoid duplicates. Anything outside the sentinels is yours and never touched. Skip with `quickback compile --no-sync-config`.
|
|
121
|
+
|
|
122
|
+
### Custom bindings (`config.bindings`)
|
|
123
|
+
|
|
124
|
+
Declare additional Cloudflare bindings that flow into `wrangler.toml`. The compiler also auto-wires the `[[send_email]] EMAIL` binding, the `cloudflare-email.ts` helper, and Better Auth's `sendResetPassword` / `sendVerificationEmail` / `sendInvitationEmail` callbacks for any auth surface that needs mail (`emailAndPassword.enabled` OR the `emailOtp` / `magicLink` / `organization` plugins) — you don't need to add `bindings.sendEmail` by hand for the standard cases.
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
export default defineConfig({
|
|
128
|
+
// ...
|
|
129
|
+
bindings: {
|
|
130
|
+
kv: [{ binding: 'CACHE', id: '...' }],
|
|
131
|
+
r2: [{ binding: 'UPLOADS', bucketName: 'my-uploads' }],
|
|
132
|
+
queues: {
|
|
133
|
+
producers: [{ binding: 'JOBS', queue: 'jobs' }],
|
|
134
|
+
consumers: [{ queue: 'jobs', maxBatchSize: 10 }],
|
|
135
|
+
},
|
|
136
|
+
durableObjects: [{ binding: 'CHAT', className: 'ChatRoom' }],
|
|
137
|
+
vars: { FEATURE_X: 'true' },
|
|
138
|
+
},
|
|
139
|
+
});
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### CMS access default
|
|
143
|
+
|
|
144
|
+
`cms: true` defaults to `access: 'admin'` — only users with `user.role === 'admin'` can enter the CMS. Non-admins are redirected to `/account/profile`. Override with `cms: { access: 'user' }` to open the CMS to all authenticated users.
|
|
145
|
+
|
|
146
|
+
### Account fileUploads
|
|
147
|
+
|
|
148
|
+
`account.fileUploads: true` shows the avatar upload UI on the profile page. Defaults to `false`; enabling it requires R2 configured for storage.
|
|
149
|
+
|
|
118
150
|
## Compile Output and State Artifacts
|
|
119
151
|
|
|
120
152
|
- Runtime code stays in `build.outputDir` (e.g. `src/`, `wrangler.toml`, `package.json`)
|
|
@@ -152,15 +184,17 @@ export default feature("todos", {
|
|
|
152
184
|
columns: {
|
|
153
185
|
id: q.id(),
|
|
154
186
|
title: q.text().required(),
|
|
155
|
-
description: q.text().optional(),
|
|
187
|
+
description: q.text({ maxLength: 1000 }).optional(),
|
|
156
188
|
completed: q.bool().default(false),
|
|
157
|
-
|
|
158
|
-
organizationId: q.
|
|
189
|
+
ownerId: q.scope("owner"), // → ctx.userId, auto-firewalled, auto-populated
|
|
190
|
+
organizationId: q.scope("organization"), // → ctx.activeOrgId, same
|
|
159
191
|
},
|
|
160
|
-
firewall
|
|
192
|
+
// firewall block omitted — q.scope() auto-derives:
|
|
193
|
+
// [{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
194
|
+
// { field: 'ownerId', equals: 'ctx.userId' },
|
|
195
|
+
// { field: 'deletedAt', isNull: true }]
|
|
196
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
161
197
|
crud: {
|
|
162
|
-
list: { access: { roles: ["member", "admin"] } },
|
|
163
|
-
get: { access: { roles: ["member", "admin"] } },
|
|
164
198
|
create: { access: { roles: ["member", "admin"] } },
|
|
165
199
|
update: { access: { roles: ["admin"] } },
|
|
166
200
|
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
@@ -169,16 +203,53 @@ export default feature("todos", {
|
|
|
169
203
|
createable: ["title", "description", "completed"],
|
|
170
204
|
updatable: ["title", "description", "completed"],
|
|
171
205
|
},
|
|
172
|
-
masking: {
|
|
173
|
-
userId: { type: "redact", show: { roles: ["admin"] } },
|
|
174
|
-
},
|
|
175
206
|
});
|
|
176
207
|
```
|
|
177
208
|
|
|
178
|
-
**q DSL quick reference:** column names default to snake_case of the JS key (`organizationId` → `organization_id`). `q.id()` emits a cuid2 primary key. Chainable modifiers: `.required()` / `.optional()` / `.default(v)` / `.unique()` / `.index()` / `.references(() => other.id, { onDelete: 'cascade' })`.
|
|
179
|
-
|
|
180
209
|
The `feature()` form is compile-time sugar — the compiler expands it to `q.table()` + `defineTable()` internally. Use whichever reads best for the file.
|
|
181
210
|
|
|
211
|
+
### q DSL — column types
|
|
212
|
+
|
|
213
|
+
Column names default to snake_case of the JS key (`organizationId` → `organization_id`). Override with the positional name string or the `sqlName` option.
|
|
214
|
+
|
|
215
|
+
| Builder | SQL | Zod | Notes |
|
|
216
|
+
|---|---|---|---|
|
|
217
|
+
| `q.id()` | `text('id').primaryKey()` | `z.string()` | cuid2 by default; ID style follows `database.generateId` |
|
|
218
|
+
| `q.text(name?)` / `q.text({ sqlName?, maxLength? })` | `text(...)` | `z.string()` (`.max(n)` if `maxLength`) | options form adds zod max-length only — SQL stays unconstrained |
|
|
219
|
+
| `q.url({ sqlName?, maxLength? })` | `text(...)` | `z.string().url()` | rejects `javascript:` / `data:` / non-URL strings at the API edge |
|
|
220
|
+
| `q.int(name?)` | `integer(...)` | `z.number().int()` | |
|
|
221
|
+
| `q.bool(name?)` | `boolean(...)` (sqlite: integer mode) | `z.boolean()` | |
|
|
222
|
+
| `q.uuid(name?)` | `uuid(...)` (sqlite: text) | `z.string().uuid()` | |
|
|
223
|
+
| `q.timestamp(name?)` | `timestamp(...)` (sqlite: text ISO) | `z.coerce.date()` | |
|
|
224
|
+
| `q.json(zodType?)` | `jsonb(...)` (sqlite: text mode) | `z.unknown()` or your zod | pass a zod schema for typed JSON |
|
|
225
|
+
| `q.enum(['a','b'])` | `text(..., { enum })` | `z.enum([...])` | |
|
|
226
|
+
| `q.scope(kind)` | `text(...).notNull()` | `z.string()` | tenant-scope column — see Firewall |
|
|
227
|
+
|
|
228
|
+
**Chainable modifiers:** `.required()` / `.optional()` / `.default(v)` / `.unique()` / `.index()` / `.filterable(false)` / `.searchable(false)` / `.references(() => other.id, { onDelete: 'cascade' })`.
|
|
229
|
+
|
|
230
|
+
`.filterable(false)` and `.searchable(false)` are capability opt-outs — every text column is filter/search-eligible by default; chain `false` to remove a column from `?<col>=` filters or the `?search=` OR'd LIKE scan. Masked columns are always excluded from `?search` regardless (see Masking).
|
|
231
|
+
|
|
232
|
+
### Composite indexes & uniques on `feature()`
|
|
233
|
+
|
|
234
|
+
Single-column indexes go on the column (`q.text().index()`). Composite ones go at the top level — the sugar forwards them into the same `q.table` opts:
|
|
235
|
+
|
|
236
|
+
```typescript
|
|
237
|
+
export default feature("memberships", {
|
|
238
|
+
columns: { userId: q.scope("owner"), organizationId: q.scope("organization"), role: q.text() },
|
|
239
|
+
indexes: [{ name: "memberships_user_org_idx", columns: ["userId", "organizationId"] }],
|
|
240
|
+
unique: [{ columns: ["userId", "organizationId"] }],
|
|
241
|
+
// ... read / crud / guards
|
|
242
|
+
});
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
**Auto-indexes:** the compiler emits the indexes you'd otherwise author by hand. Don't pre-declare these — they'll be deduped:
|
|
246
|
+
|
|
247
|
+
| Trigger | Index emitted |
|
|
248
|
+
|---|---|
|
|
249
|
+
| Tenant col (`organizationId` / `userId`) + `deletedAt` | composite `(<isolation>, deletedAt)` |
|
|
250
|
+
| Any FK (`.references(...)`) | single-col `(<fk>)` (D1/SQLite don't auto-index FKs) |
|
|
251
|
+
| Any column in a view's `read.query.sortable` | single-col `(<col>)` |
|
|
252
|
+
|
|
182
253
|
### Example: same todos using the two-export form
|
|
183
254
|
|
|
184
255
|
```typescript
|
|
@@ -188,14 +259,15 @@ export const todos = q.table("todos", {
|
|
|
188
259
|
id: q.id(),
|
|
189
260
|
title: q.text().required(),
|
|
190
261
|
completed: q.bool().default(false),
|
|
191
|
-
|
|
192
|
-
organizationId: q.
|
|
262
|
+
ownerId: q.scope("owner"),
|
|
263
|
+
organizationId: q.scope("organization"),
|
|
193
264
|
});
|
|
194
265
|
|
|
195
266
|
export default defineTable(todos, {
|
|
196
|
-
firewall
|
|
197
|
-
|
|
198
|
-
|
|
267
|
+
// firewall auto-derived from q.scope() — same as the feature() example
|
|
268
|
+
read: { /* same as above */ },
|
|
269
|
+
crud: { /* same as above */ },
|
|
270
|
+
guards: { /* same as above */ },
|
|
199
271
|
});
|
|
200
272
|
|
|
201
273
|
export type Todo = typeof todos.$infer;
|
|
@@ -203,6 +275,8 @@ export type Todo = typeof todos.$infer;
|
|
|
203
275
|
|
|
204
276
|
### Example: same todos with Drizzle (for interop)
|
|
205
277
|
|
|
278
|
+
When bringing forward existing Drizzle code, declare a regular column. Auto-detection by **name** (`organizationId`, `ownerId`, `teamId`, `userId`) still picks it up — `q.scope()` semantics (auto-firewall, systemManaged, auto-populate) apply because they key off the firewall predicate, not the column DSL.
|
|
279
|
+
|
|
206
280
|
```typescript
|
|
207
281
|
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
|
|
208
282
|
import { defineTable } from "@quickback/compiler";
|
|
@@ -216,9 +290,10 @@ export const todos = sqliteTable("todos", {
|
|
|
216
290
|
});
|
|
217
291
|
|
|
218
292
|
export default defineTable(todos, {
|
|
219
|
-
firewall
|
|
220
|
-
|
|
221
|
-
|
|
293
|
+
// firewall auto-derived from column names; declare explicitly only if names don't match
|
|
294
|
+
read: { /* same as above */ },
|
|
295
|
+
crud: { /* same as above */ },
|
|
296
|
+
guards: { /* same as above */ },
|
|
222
297
|
});
|
|
223
298
|
```
|
|
224
299
|
|
|
@@ -328,45 +403,82 @@ Request → Firewall → Access → Guards → Database → Masking → Response
|
|
|
328
403
|
|
|
329
404
|
### 1. Firewall — Data Isolation
|
|
330
405
|
|
|
331
|
-
Compiles WHERE clauses to isolate data by ownership.
|
|
406
|
+
Compiles WHERE clauses to isolate data by ownership. Predicates are AND'd together.
|
|
407
|
+
|
|
408
|
+
```typescript
|
|
409
|
+
firewall: [
|
|
410
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' }, // WHERE organizationId = ctx.activeOrgId
|
|
411
|
+
{ field: 'ownerId', equals: 'ctx.userId' }, // AND ownerId = ctx.userId
|
|
412
|
+
{ field: 'teamId', equals: 'ctx.activeTeamId' }, // AND teamId = ctx.activeTeamId
|
|
413
|
+
{ field: 'deletedAt', isNull: true }, // AND deletedAt IS NULL (soft-delete filter)
|
|
414
|
+
]
|
|
415
|
+
|
|
416
|
+
// Public/system resources opt out of tenant scoping (soft-delete still applied):
|
|
417
|
+
firewall: [{ exception: true }]
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
**Recommended: declare scope columns with `q.scope()`** — auto-derives the firewall predicate AND marks the column `systemManaged` (rejected from client input) AND auto-populates from ctx on insert/upsert. Zero ambiguity in the source:
|
|
332
421
|
|
|
333
422
|
```typescript
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
owner
|
|
337
|
-
team
|
|
338
|
-
softDelete: {}, // AND deletedAt IS NULL
|
|
339
|
-
exception: true, // No filtering (public resources)
|
|
423
|
+
columns: {
|
|
424
|
+
organizationId: q.scope("organization"), // → ctx.activeOrgId
|
|
425
|
+
ownerId: q.scope("owner"), // → ctx.userId
|
|
426
|
+
teamId: q.scope("team"), // → ctx.activeTeamId
|
|
340
427
|
}
|
|
341
428
|
```
|
|
342
429
|
|
|
343
|
-
Auto-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
430
|
+
**Auto-derivation by name** (Drizzle interop, when the `firewall:` block is omitted): the compiler scans column names and emits the same predicates.
|
|
431
|
+
|
|
432
|
+
| Column name in schema | Predicate emitted |
|
|
433
|
+
|---|---|
|
|
434
|
+
| `organizationId` / `organisationId` | `{ field: '...', equals: 'ctx.activeOrgId' }` |
|
|
435
|
+
| `userId` (or `ownerId`) | `{ field: '...', equals: 'ctx.userId' }` |
|
|
436
|
+
| `teamId` | `{ field: 'teamId', equals: 'ctx.activeTeamId' }` |
|
|
437
|
+
| `deletedAt` (always present via audit injection) | `{ field: 'deletedAt', isNull: true }` |
|
|
438
|
+
|
|
439
|
+
- Exactly one isolation column → auto-derived.
|
|
440
|
+
- Two or more → compile-time error; declare `firewall: [...]` explicitly OR use `q.scope()` to lock semantics in the source.
|
|
441
|
+
- Zero columns AND no PUBLIC route → compile-time error ("missing isolation column").
|
|
347
442
|
|
|
348
|
-
|
|
443
|
+
**Custom column / context source**: just write the predicate explicitly.
|
|
349
444
|
|
|
350
445
|
```typescript
|
|
351
|
-
firewall:
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
},
|
|
356
|
-
}
|
|
446
|
+
firewall: [
|
|
447
|
+
{ field: 'tenantId', equals: 'ctx.activeOrgId' },
|
|
448
|
+
{ field: 'status', in: ['active', 'pending'] }, // literal value, not ctx-derived
|
|
449
|
+
]
|
|
357
450
|
```
|
|
358
451
|
|
|
359
|
-
|
|
452
|
+
**Predicate operators**: `equals` (column = ctx.* or literal), `isNull: true` (column IS NULL), `in: [...]` (column IN ...), `{ exception: true }` (opt out of tenant scoping).
|
|
360
453
|
|
|
361
454
|
### 2. Access — Permission Checks
|
|
362
455
|
|
|
363
456
|
Role-based and record-based access control. Deny by default.
|
|
364
457
|
|
|
458
|
+
DSL v2 separates **reads** (collection + per-id GET) from **mutations**. The unified `read` block owns `GET /` AND `GET /:id` AND views; mutations live under `crud.create/update/delete`.
|
|
459
|
+
|
|
365
460
|
```typescript
|
|
461
|
+
read: {
|
|
462
|
+
access: { roles: ['member+'] }, // gates GET / and GET /:id
|
|
463
|
+
query: {
|
|
464
|
+
sortable: ['createdAt', 'status'], // ?sort= allowlist (defaults to all cols)
|
|
465
|
+
searchable: ['title', 'body'], // ?search= OR'd LIKE allowlist
|
|
466
|
+
filterable: ['status', 'priority'], // ?<col>= allowlist
|
|
467
|
+
},
|
|
468
|
+
views: {
|
|
469
|
+
summary: {
|
|
470
|
+
fields: ['id', 'title', 'status'],
|
|
471
|
+
access: { roles: ['member+'] },
|
|
472
|
+
query: { sortable: ['title'] }, // per-view overrides allowed
|
|
473
|
+
},
|
|
474
|
+
full: {
|
|
475
|
+
fields: ['id', 'title', 'status', 'body', 'internalNotes'],
|
|
476
|
+
access: { roles: ['admin+'] },
|
|
477
|
+
},
|
|
478
|
+
},
|
|
479
|
+
},
|
|
366
480
|
crud: {
|
|
367
|
-
|
|
368
|
-
get: { access: { roles: ['member+'] } },
|
|
369
|
-
create: { access: { roles: ['admin+'] } }, // admin, owner
|
|
481
|
+
create: { access: { roles: ['admin+'] } },
|
|
370
482
|
update: {
|
|
371
483
|
access: {
|
|
372
484
|
or: [
|
|
@@ -375,10 +487,18 @@ crud: {
|
|
|
375
487
|
],
|
|
376
488
|
},
|
|
377
489
|
},
|
|
378
|
-
delete: { access: { roles: ['owner'] } },
|
|
490
|
+
delete: { access: { roles: ['owner'] } },
|
|
379
491
|
}
|
|
380
492
|
```
|
|
381
493
|
|
|
494
|
+
**Generated read endpoints:**
|
|
495
|
+
- `GET /api/v1/{resource}` — gated by `read.access`
|
|
496
|
+
- `GET /api/v1/{resource}/:id` — gated by `read.access` (single-record GET inherits)
|
|
497
|
+
- `GET /api/v1/{resource}?view=summary` — view dispatch under `?view=`
|
|
498
|
+
- `GET /api/v1/{resource}/views/summary` — explicit view path
|
|
499
|
+
|
|
500
|
+
> **DSL v2 migration:** `crud.list` and `crud.get` are rejected at compile time. Move them to `read.access`. A bare `crud: { list: {} }` becomes `read: {}`.
|
|
501
|
+
|
|
382
502
|
**Role hierarchy**: Configure `auth.roleHierarchy` in your config (e.g., `['member', 'admin', 'owner']`) and use the `+` suffix to mean "this role and above". `"member+"` expands to `["member", "admin", "owner"]` at compile time. Roles without `+` are exact matches.
|
|
383
503
|
|
|
384
504
|
Record condition operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
|
|
@@ -415,6 +535,8 @@ Mask types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
|
|
|
415
535
|
|
|
416
536
|
Auto-detection warns on unmasked sensitive columns (`email`, `phone`, `ssn`, `password`, etc.).
|
|
417
537
|
|
|
538
|
+
**Search/filter gating.** Masked columns are dropped from `?search` by default — letting an unauthorized caller substring-search a masked SSN trivially leaks digit positions. To re-enable search on a masked column for callers who *can* see it unmasked, list it under a view's `read.query.searchable`. The compiler validates the intersection at compile time.
|
|
539
|
+
|
|
418
540
|
---
|
|
419
541
|
|
|
420
542
|
## Views — Column-Level Security
|
|
@@ -541,20 +663,24 @@ Docs: `quickback docs account-ui` | https://docs.quickback.dev/account-ui
|
|
|
541
663
|
|
|
542
664
|
## Actions — Custom Business Logic
|
|
543
665
|
|
|
544
|
-
Defined in a separate `actions.ts` file using `defineActions()`.
|
|
666
|
+
Defined in a separate `actions.ts` file using `defineActions()`. Per-action permissions live under `access:` (same shape as resource-level access).
|
|
545
667
|
|
|
546
668
|
```typescript
|
|
547
|
-
import
|
|
669
|
+
import todos from './todos'; // default import: feature() exports
|
|
670
|
+
// import { todos } from './todos'; // named import: two-export form
|
|
548
671
|
import { defineActions } from '@quickback/compiler';
|
|
672
|
+
import { q } from '../../lib/q'; // generated namespace; same as drizzle-orm
|
|
549
673
|
import { z } from 'zod';
|
|
550
674
|
|
|
551
675
|
export default defineActions(todos, {
|
|
552
676
|
complete: {
|
|
553
677
|
description: "Mark todo as complete",
|
|
554
678
|
input: z.object({ completedAt: z.string().datetime().optional() }),
|
|
555
|
-
|
|
556
|
-
execute: async ({ db, record,
|
|
557
|
-
await db.update(todos)
|
|
679
|
+
access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
|
|
680
|
+
execute: async ({ db, record, whereRecord, auditFields }) => {
|
|
681
|
+
await db.update(todos)
|
|
682
|
+
.set({ completed: true, modifiedAt: auditFields.modifiedAt })
|
|
683
|
+
.where(whereRecord!(todos)); // firewall + soft-delete + id, in one
|
|
558
684
|
return { success: true };
|
|
559
685
|
},
|
|
560
686
|
sideEffects: "sync",
|
|
@@ -562,16 +688,83 @@ export default defineActions(todos, {
|
|
|
562
688
|
archive: {
|
|
563
689
|
description: "Archive a todo",
|
|
564
690
|
input: z.object({}),
|
|
565
|
-
|
|
691
|
+
access: { roles: ["admin"] },
|
|
566
692
|
handler: "./handlers/archive",
|
|
567
693
|
},
|
|
568
694
|
});
|
|
569
695
|
```
|
|
570
696
|
|
|
571
|
-
**Record-based** (default): `POST /api/v1/{resource}/:id/{action}`
|
|
572
|
-
**Standalone**: `standalone: true`, custom `path` and `method
|
|
697
|
+
**Record-based** (default): `POST /api/v1/{resource}/:id/{action}` — record is loaded, firewall + access checks run, then `execute` is called with `record`, `whereRecord`, scoped `db`.
|
|
698
|
+
**Standalone**: `standalone: true`, custom `path` and `method`. No record context, no firewall preload.
|
|
699
|
+
|
|
700
|
+
Action options: `standalone`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget), `transition`, `unsafe`, `allowRawSql`.
|
|
701
|
+
|
|
702
|
+
### `whereRecord(table)` — explicit, scope-safe WHERE
|
|
703
|
+
|
|
704
|
+
In record-based actions, `whereRecord(table)` returns a Drizzle expression that AND-merges the resource's firewall + soft-delete + `eq(table.id, record.id)`. Use it for protected-field writes — even if a future refactor swaps `db` for an unscoped client, the WHERE stays explicit. `whereRecord` is `undefined` for standalone actions.
|
|
705
|
+
|
|
706
|
+
### `transition` — state-machine policy on protected fields
|
|
707
|
+
|
|
708
|
+
For protected fields that follow a state machine (status, lifecycle, fulfilment), enforce the *from/to pair*, not just the current state. Without `transition`, an `advance` action whose access allows `status in ['applied', 'screening']` will happily run `applied → offer` (a skip) or `screening → applied` (a regression).
|
|
709
|
+
|
|
710
|
+
```typescript
|
|
711
|
+
advance: {
|
|
712
|
+
description: "Move application forward",
|
|
713
|
+
input: z.object({ nextStatus: z.enum(['screening', 'interview', 'offer']) }),
|
|
714
|
+
access: { roles: ['owner', 'admin'] },
|
|
715
|
+
transition: {
|
|
716
|
+
field: 'status',
|
|
717
|
+
via: 'nextStatus', // read target from input.nextStatus
|
|
718
|
+
fromTo: {
|
|
719
|
+
applied: ['screening'],
|
|
720
|
+
screening: ['interview'],
|
|
721
|
+
interview: ['offer'],
|
|
722
|
+
},
|
|
723
|
+
},
|
|
724
|
+
handler: './handlers/advance',
|
|
725
|
+
},
|
|
726
|
+
hire: {
|
|
727
|
+
input: z.object({}),
|
|
728
|
+
access: { roles: ['owner'] },
|
|
729
|
+
transition: {
|
|
730
|
+
field: 'status',
|
|
731
|
+
to: 'hired', // fixed target — same value every call
|
|
732
|
+
fromTo: { offer: ['hired'] },
|
|
733
|
+
},
|
|
734
|
+
handler: './handlers/hire',
|
|
735
|
+
},
|
|
736
|
+
```
|
|
737
|
+
|
|
738
|
+
Exactly one of `via` or `to` must be provided. On a bad transition the runtime returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** with `field`, `current`, `target`, `allowedTargets`. The same 409 fires when a plain `access.record` precondition fails (was 403 before — splitting it lets clients tell *"you can't do this"* from *"you can't do this **yet**"*).
|
|
739
|
+
|
|
740
|
+
### `unsafe` — bypass scoped DB filters (object form, with mandatory audit)
|
|
741
|
+
|
|
742
|
+
For platform-level support / cross-tenant operations, opt out of the scoped DB. The object form is required for new code — it makes the policy explicit and forces an audit reason:
|
|
743
|
+
|
|
744
|
+
```typescript
|
|
745
|
+
adminReport: {
|
|
746
|
+
description: "Cross-org hiring report",
|
|
747
|
+
unsafe: {
|
|
748
|
+
reason: "Support investigation for enterprise customer",
|
|
749
|
+
adminOnly: true, // default true — gates on ctx.userRole === 'admin'
|
|
750
|
+
crossTenant: true, // default true — bypasses firewall
|
|
751
|
+
targetScope: 'all', // 'all' | 'organization'
|
|
752
|
+
},
|
|
753
|
+
input: z.object({ startDate: z.string() }),
|
|
754
|
+
access: { roles: ['owner'] },
|
|
755
|
+
execute: async ({ db, unsafeDb, ctx, input }) => {
|
|
756
|
+
// db is still scoped (safety net for accidental writes)
|
|
757
|
+
// unsafeDb bypasses scoped filters
|
|
758
|
+
return await unsafeDb.select().from(applications);
|
|
759
|
+
},
|
|
760
|
+
},
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
Generated runtime auto-injects: Better Auth required, platform admin gate, mandatory audit logging on deny/success/error. Without unsafe mode, `unsafeDb` is `undefined`. Legacy `unsafe: true` still works but object form is preferred.
|
|
764
|
+
|
|
765
|
+
### Soft-delete cascade (cross-feature)
|
|
573
766
|
|
|
574
|
-
|
|
767
|
+
When a parent is soft-deleted, every child table that holds an FK to it — both **same-feature** and **cross-feature** children — receives the same `deletedAt` / `deletedBy` stamp. The cascade UPDATE always AND-merges the child's own firewall, so a delete in one tenant never reaches a child row in another tenant. FKs declared with `onDelete: 'cascade'` or `'set null'` participate; FKs without `onDelete` are cascaded for backwards compat.
|
|
575
768
|
|
|
576
769
|
### Actions-Only Features
|
|
577
770
|
|
|
@@ -589,7 +782,7 @@ export default defineActions(null, {
|
|
|
589
782
|
method: "GET",
|
|
590
783
|
description: "Health check endpoint",
|
|
591
784
|
input: z.object({}),
|
|
592
|
-
|
|
785
|
+
access: { roles: ["member", "admin"] },
|
|
593
786
|
handler: "./handlers/health-check",
|
|
594
787
|
},
|
|
595
788
|
});
|