@quickback-dev/cli 0.10.16 → 0.10.20
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.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +6 -6
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1192 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +67 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1192 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +228 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +67 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- package/src/skill/docs/stack/webhooks/outbound.md +281 -0
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# Guards - Field Modification Rules
|
|
2
|
+
|
|
3
|
+
Control which fields can be modified in CREATE vs UPDATE operations.
|
|
4
|
+
|
|
5
|
+
## Basic Usage
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
// features/applications/applications.ts
|
|
9
|
+
import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
|
|
10
|
+
import { defineTable } from '@quickback/compiler';
|
|
11
|
+
|
|
12
|
+
export const applications = sqliteTable('applications', {
|
|
13
|
+
id: text('id').primaryKey(),
|
|
14
|
+
candidateId: text('candidate_id').notNull(),
|
|
15
|
+
jobId: text('job_id').notNull(),
|
|
16
|
+
stage: text('stage').notNull().default('applied'),
|
|
17
|
+
appliedAt: text('applied_at').notNull(),
|
|
18
|
+
notes: text('notes'),
|
|
19
|
+
organizationId: text('organization_id').notNull(),
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
export default defineTable(applications, {
|
|
23
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
24
|
+
guards: {
|
|
25
|
+
createable: ["candidateId", "jobId", "notes"],
|
|
26
|
+
updatable: ["notes"],
|
|
27
|
+
protected: {
|
|
28
|
+
stage: ["advance-stage", "reject"],
|
|
29
|
+
},
|
|
30
|
+
immutable: ["appliedAt", "candidateId", "jobId"],
|
|
31
|
+
},
|
|
32
|
+
crud: {
|
|
33
|
+
// ...
|
|
34
|
+
},
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Configuration Options
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
guards: {
|
|
42
|
+
// Fields allowed on CREATE
|
|
43
|
+
createable?: string[];
|
|
44
|
+
|
|
45
|
+
// Fields allowed on UPDATE/PATCH
|
|
46
|
+
updatable?: string[];
|
|
47
|
+
|
|
48
|
+
// Fields only modifiable via specific actions
|
|
49
|
+
protected?: Record<string, string[]>;
|
|
50
|
+
|
|
51
|
+
// Fields set on CREATE, never modified after
|
|
52
|
+
immutable?: string[];
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## How It Works
|
|
57
|
+
|
|
58
|
+
| List | What it controls |
|
|
59
|
+
|------|------------------|
|
|
60
|
+
| `createable` | Fields allowed in create (POST) request body |
|
|
61
|
+
| `updatable` | Fields allowed in update (PATCH) request body |
|
|
62
|
+
| `protected` | Fields blocked from CRUD, only modifiable via named actions |
|
|
63
|
+
| `immutable` | Fields allowed on create, blocked on all updates |
|
|
64
|
+
|
|
65
|
+
**Combining lists:**
|
|
66
|
+
|
|
67
|
+
- `createable` + `updatable` - Most fields go in both (can set on create AND modify later)
|
|
68
|
+
- `createable` only - Field is set once, cannot be changed via update
|
|
69
|
+
- `protected` - Don't also list in `createable` or `updatable` (they're mutually exclusive)
|
|
70
|
+
- `immutable` - Don't also list in `updatable` (contradiction)
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
guards: {
|
|
74
|
+
createable: ["candidateId", "jobId", "notes", "source"],
|
|
75
|
+
updatable: ["notes"],
|
|
76
|
+
// "candidateId", "jobId" are only in createable = set once, can't change via update
|
|
77
|
+
protected: {
|
|
78
|
+
stage: ["advance-stage", "reject"], // NOT in createable/updatable
|
|
79
|
+
},
|
|
80
|
+
immutable: ["appliedAt"], // NOT in updatable
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**If a field is not listed anywhere, it cannot be set by the client.**
|
|
85
|
+
|
|
86
|
+
## System-Managed Fields (Always Protected)
|
|
87
|
+
|
|
88
|
+
`GUARDS_CONFIG.systemManaged` rejects any field in this set from client input — even with `guards: false`. The set always includes the audit fields:
|
|
89
|
+
|
|
90
|
+
- `createdAt`, `createdBy`
|
|
91
|
+
- `modifiedAt`, `modifiedBy`
|
|
92
|
+
- `deletedAt`, `deletedBy`
|
|
93
|
+
|
|
94
|
+
It also extends with **scope columns** — any firewall predicate whose `equals` references `ctx.*` adds its `field` to systemManaged. Most commonly this comes from `q.scope()`:
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
columns: {
|
|
98
|
+
organizationId: q.scope('organization'), // → adds 'organizationId' to systemManaged
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The same applies to a hand-rolled firewall:
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
firewall: [
|
|
106
|
+
{ field: 'tenantId', equals: 'ctx.activeOrgId' }, // → systemManaged
|
|
107
|
+
{ field: 'workspaceId', equals: 'ctx.activeWorkspaceId' }, // → systemManaged
|
|
108
|
+
{ field: 'status', equals: 'active' }, // literal, NOT added
|
|
109
|
+
]
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The semantic rule is "if the firewall says this column's value comes from the request context, the client cannot submit it." The value is auto-populated on create / upsert from `ctx`.
|
|
113
|
+
|
|
114
|
+
## Example
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
guards: {
|
|
118
|
+
createable: ["candidateId", "jobId", "notes"],
|
|
119
|
+
updatable: ["notes"],
|
|
120
|
+
protected: {
|
|
121
|
+
stage: ["advance-stage", "reject"], // Only these actions can modify stage
|
|
122
|
+
},
|
|
123
|
+
immutable: ["appliedAt", "candidateId", "jobId"],
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Disabling Guards
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
guards: false // Only system fields protected
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
When `guards: false` is set, all user-defined fields become writable via CRUD operations. This is useful for:
|
|
134
|
+
- External sync scenarios where you need full field control
|
|
135
|
+
- Batch upsert operations where field restrictions would be limiting
|
|
136
|
+
- Simple tables where field-level protection isn't needed
|
|
137
|
+
|
|
138
|
+
## PUT/Upsert with External IDs
|
|
139
|
+
|
|
140
|
+
When you disable guards AND use client-provided IDs, you unlock PUT (upsert) operations. This is designed for **syncing data from external systems**.
|
|
141
|
+
|
|
142
|
+
### Requirements for PUT
|
|
143
|
+
|
|
144
|
+
1. `generateId: false` in database config (client provides IDs)
|
|
145
|
+
2. `guards: false` in resource definition
|
|
146
|
+
|
|
147
|
+
### How PUT Works
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
PUT /resource/:id
|
|
151
|
+
├── Record exists? → UPDATE (replace all fields)
|
|
152
|
+
└── Record missing? → CREATE with provided ID
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Database Config
|
|
156
|
+
|
|
157
|
+
```typescript
|
|
158
|
+
// quickback.config.ts
|
|
159
|
+
export default {
|
|
160
|
+
database: {
|
|
161
|
+
generateId: false, // Client provides IDs (enables PUT)
|
|
162
|
+
// Other options: 'uuid' | 'cuid' | 'nanoid' | 'short' | 'prefixed' | 'serial'
|
|
163
|
+
}
|
|
164
|
+
};
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Table Definition
|
|
168
|
+
|
|
169
|
+
```typescript
|
|
170
|
+
// features/integrations/ats-imports.ts
|
|
171
|
+
export default defineTable(atsImports, {
|
|
172
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
173
|
+
guards: false, // Disables field restrictions
|
|
174
|
+
crud: {
|
|
175
|
+
put: {
|
|
176
|
+
access: { roles: ['hiring-manager', 'sync-service'] }
|
|
177
|
+
}
|
|
178
|
+
},
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## What's Still Protected with guards: false
|
|
183
|
+
|
|
184
|
+
Even with `guards: false`, system-managed fields are ALWAYS protected. This includes:
|
|
185
|
+
|
|
186
|
+
- `createdAt`, `createdBy` — set on INSERT only
|
|
187
|
+
- `modifiedAt`, `modifiedBy` — auto-updated
|
|
188
|
+
- `deletedAt`, `deletedBy` — set on soft delete
|
|
189
|
+
- Any column declared via `q.scope()` (or any firewall predicate using `equals: 'ctx.*'`) — auto-populated from request context
|
|
190
|
+
|
|
191
|
+
So `guards: false` only opens up user-defined business fields. Tenant scope and audit fields stay locked down regardless.
|
|
192
|
+
|
|
193
|
+
## Ownership Auto-Population
|
|
194
|
+
|
|
195
|
+
When PUT creates a new record, ownership fields are auto-set from context:
|
|
196
|
+
|
|
197
|
+
```typescript
|
|
198
|
+
// Client sends: PUT /ats-imports/ext-123 { candidateName: "Jane Doe" }
|
|
199
|
+
// Server creates:
|
|
200
|
+
{
|
|
201
|
+
id: "ext-123", // Client-provided
|
|
202
|
+
candidateName: "Jane Doe", // Client-provided
|
|
203
|
+
organizationId: ctx.activeOrgId, // Auto-set from firewall
|
|
204
|
+
createdAt: now, // Auto-set
|
|
205
|
+
createdBy: ctx.userId, // Auto-set
|
|
206
|
+
modifiedAt: now, // Auto-set
|
|
207
|
+
modifiedBy: ctx.userId, // Auto-set
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Use Cases for PUT/External IDs
|
|
212
|
+
|
|
213
|
+
| Use Case | Why PUT? |
|
|
214
|
+
|----------|----------|
|
|
215
|
+
| External API sync | External system controls the ID |
|
|
216
|
+
| Webhook handlers | Events come with their own IDs |
|
|
217
|
+
| Data migration | Preserve IDs from source system |
|
|
218
|
+
| Idempotent updates | Safe to retry (no duplicate creates) |
|
|
219
|
+
| Bulk upsert | Create or update in one operation |
|
|
220
|
+
|
|
221
|
+
## ID Generation Options
|
|
222
|
+
|
|
223
|
+
| `generateId` | PUT Available? | Notes |
|
|
224
|
+
|--------------|----------------|-------|
|
|
225
|
+
| `'uuid'` | No | Server generates UUID |
|
|
226
|
+
| `'cuid'` | No | Server generates CUID |
|
|
227
|
+
| `'nanoid'` | No | Server generates nanoid |
|
|
228
|
+
| `'short'` | No | Server generates 6-char alphanumeric ID (e.g. `a3F9xK`) |
|
|
229
|
+
| `'prefixed'` | No | Server generates prefixed ID (e.g. `room_abc123`) |
|
|
230
|
+
| `'serial'` | No | Database auto-increments |
|
|
231
|
+
| `false` | Yes (if guards: false) | Client provides ID |
|
|
232
|
+
|
|
233
|
+
## Compile-Time Validation
|
|
234
|
+
|
|
235
|
+
The Quickback compiler validates your guards configuration and will error if:
|
|
236
|
+
|
|
237
|
+
1. **Field in both `createable` and `protected`** - A field cannot be both client-writable on create and action-only
|
|
238
|
+
2. **Field in both `updatable` and `protected`** - A field cannot be both client-writable on update and action-only
|
|
239
|
+
3. **Field in both `updatable` and `immutable`** - Contradictory: immutable fields cannot be updated
|
|
240
|
+
4. **Field in `protected` doesn't exist in schema** - Referenced field must exist in the table
|
|
241
|
+
5. **Field in `createable`/`updatable`/`immutable` doesn't exist in schema** - All referenced fields must exist
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# Definitions Overview
|
|
2
|
+
|
|
3
|
+
Before diving into specific features, let's understand how Quickback's pieces connect. This page gives you the mental model for everything that follows.
|
|
4
|
+
|
|
5
|
+
## The Big Picture
|
|
6
|
+
|
|
7
|
+
Quickback is a **backend compiler**. You write definition files, and Quickback compiles them into a production-ready API.
|
|
8
|
+
|
|
9
|
+
1. **You write definitions** - Table files with schema and security config using `defineTable`
|
|
10
|
+
2. **Quickback compiles them** - Analyzes your definitions at build time
|
|
11
|
+
3. **You get a production API** - `GET /jobs`, `POST /jobs`, `PATCH /jobs/:id`, `DELETE /jobs/:id`, batch operations, plus custom actions
|
|
12
|
+
|
|
13
|
+
## File Structure
|
|
14
|
+
|
|
15
|
+
Your definitions live in a `quickback/features/` folder organized by feature:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
my-app/
|
|
19
|
+
├── quickback/
|
|
20
|
+
│ ├── quickback.config.ts # Compiler configuration
|
|
21
|
+
│ └── features/
|
|
22
|
+
│ └── {feature-name}/
|
|
23
|
+
│ ├── candidates.ts # Table + config (defineTable)
|
|
24
|
+
│ ├── applications.ts # Secondary table + config
|
|
25
|
+
│ ├── interview-scores.ts # Internal table (no routes)
|
|
26
|
+
│ ├── actions.ts # Custom actions (optional)
|
|
27
|
+
│ └── handlers/ # Action handlers (optional)
|
|
28
|
+
│ └── advance-stage.ts
|
|
29
|
+
├── src/ # Generated code (output)
|
|
30
|
+
└── package.json
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**Table files** use `defineTable` to combine schema and security config:
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
// features/candidates/candidates.ts
|
|
37
|
+
import { sqliteTable, text } from "drizzle-orm/sqlite-core";
|
|
38
|
+
import { defineTable } from "@quickback/compiler";
|
|
39
|
+
|
|
40
|
+
export const candidates = sqliteTable("candidates", {
|
|
41
|
+
id: text("id").primaryKey(),
|
|
42
|
+
organizationId: text("organization_id").notNull(),
|
|
43
|
+
name: text("name").notNull(),
|
|
44
|
+
email: text("email").notNull(),
|
|
45
|
+
phone: text("phone"),
|
|
46
|
+
source: text("source"),
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
export default defineTable(candidates, {
|
|
50
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
51
|
+
guards: {
|
|
52
|
+
createable: ["name", "email", "phone", "source"],
|
|
53
|
+
updatable: ["name", "phone"],
|
|
54
|
+
},
|
|
55
|
+
masking: {
|
|
56
|
+
email: { type: 'email', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
|
|
57
|
+
phone: { type: 'phone', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
|
|
58
|
+
},
|
|
59
|
+
read: {
|
|
60
|
+
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
61
|
+
},
|
|
62
|
+
crud: {
|
|
63
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
64
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
65
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
66
|
+
},
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
export type Candidate = typeof candidates.$inferSelect;
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**Key points:**
|
|
73
|
+
- Tables with `export default defineTable(...)` → CRUD routes generated
|
|
74
|
+
- Tables without default export → internal/junction tables (no routes)
|
|
75
|
+
- Route path derived from filename: `applications.ts` → `/api/v1/applications`
|
|
76
|
+
|
|
77
|
+
> **1 Resource = 1 Security Boundary**
|
|
78
|
+
>
|
|
79
|
+
> Each `defineTable()` defines its own complete security boundary — its own firewall (who sees the data), access rules (role requirements), guards (field validation), and masking (redaction). These are compiled into a single resource file that wraps all CRUD routes for that table.
|
|
80
|
+
>
|
|
81
|
+
> A table **without** `defineTable()` is a supporting table — used internally by actions or handlers, but never exposed as its own API endpoint. See [Internal Tables](/compiler/definitions/schema#internal-tables-no-routes) for details.
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
## The Four Security Layers
|
|
85
|
+
|
|
86
|
+
Every API request passes through four security layers, in order:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
Request → Firewall → Access → Guards → Masking → Response
|
|
90
|
+
│ │ │ │
|
|
91
|
+
│ │ │ └── Hide sensitive fields
|
|
92
|
+
│ │ └── Block field modifications
|
|
93
|
+
│ └── Check roles & conditions
|
|
94
|
+
└── Isolate data by owner/org/team
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
> **Security Applies Everywhere**
|
|
98
|
+
>
|
|
99
|
+
> These security layers protect both **API responses** and **Realtime broadcasts**. When you enable [Realtime](/stack/realtime/durable-objects), the same masking rules apply to WebSocket messages - ensuring users only see data they're authorized to view.
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
### 1. Firewall (Data Isolation)
|
|
103
|
+
|
|
104
|
+
The firewall controls **which records** a user can see. It automatically adds WHERE clauses to every query based on your schema columns:
|
|
105
|
+
|
|
106
|
+
| Column in Schema | What happens |
|
|
107
|
+
|------------------|--------------|
|
|
108
|
+
| `organization_id` | Data isolated by organization |
|
|
109
|
+
| `user_id` | Data isolated by user (personal data) |
|
|
110
|
+
|
|
111
|
+
No manual configuration needed - Quickback applies smart rules based on your schema.
|
|
112
|
+
|
|
113
|
+
[Learn more about Firewall →](/compiler/definitions/firewall)
|
|
114
|
+
|
|
115
|
+
### 2. Access (CRUD Permissions)
|
|
116
|
+
|
|
117
|
+
Access controls **which operations** a user can perform. It checks roles and record conditions. Reads (`GET /` and `GET /:id`) live under `read:`; writes live under `crud:`.
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
read: {
|
|
121
|
+
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
122
|
+
},
|
|
123
|
+
crud: {
|
|
124
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
125
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
126
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
[Learn more about Access →](/compiler/definitions/access)
|
|
131
|
+
|
|
132
|
+
### 3. Guards (Field Modification Rules)
|
|
133
|
+
|
|
134
|
+
Guards control **which fields** can be modified in each operation.
|
|
135
|
+
|
|
136
|
+
| Guard Type | What it means |
|
|
137
|
+
|------------|---------------|
|
|
138
|
+
| `createable` | Fields that can be set when creating |
|
|
139
|
+
| `updatable` | Fields that can be changed when updating |
|
|
140
|
+
| `protected` | Fields that can only be changed via specific actions |
|
|
141
|
+
| `immutable` | Fields that can never be changed after creation |
|
|
142
|
+
|
|
143
|
+
[Learn more about Guards →](/compiler/definitions/guards)
|
|
144
|
+
|
|
145
|
+
### 4. Masking (Data Redaction)
|
|
146
|
+
|
|
147
|
+
Masking hides sensitive fields from users who shouldn't see them.
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
masking: {
|
|
151
|
+
email: { type: 'email' }, // Shows: j***@e******.com
|
|
152
|
+
phone: { type: 'phone' }, // Shows: ******4567
|
|
153
|
+
salary: { type: 'redact' }, // Shows: [REDACTED]
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
[Learn more about Masking →](/compiler/definitions/masking)
|
|
158
|
+
|
|
159
|
+
## How They Work Together
|
|
160
|
+
|
|
161
|
+
**Scenario:** An interviewer requests `GET /candidates/cnd_123`
|
|
162
|
+
|
|
163
|
+
1. **Firewall** checks: Is candidate `cnd_123` in the user's organization?
|
|
164
|
+
- Yes → Continue
|
|
165
|
+
- No → 404 Not Found (as if it doesn't exist)
|
|
166
|
+
|
|
167
|
+
2. **Access** checks: Can interviewers perform GET?
|
|
168
|
+
- Yes → Continue
|
|
169
|
+
- No → 403 Forbidden
|
|
170
|
+
|
|
171
|
+
3. **Guards** don't apply to GET (they're for writes)
|
|
172
|
+
|
|
173
|
+
4. **Masking** applies: User is an `interviewer`, not `recruiter` or `hiring-manager`
|
|
174
|
+
- Email: `jane@company.com` → `j***@c******.com`
|
|
175
|
+
- Phone: `555-123-4567` → `******4567`
|
|
176
|
+
|
|
177
|
+
5. **Response** sent with masked data
|
|
178
|
+
|
|
179
|
+
## Locked Down by Default
|
|
180
|
+
|
|
181
|
+
Quickback is **secure by default**. Nothing is accessible until you explicitly allow it.
|
|
182
|
+
|
|
183
|
+
| Layer | Default | What you must do |
|
|
184
|
+
|-------|---------|------------------|
|
|
185
|
+
| Firewall | AUTO | Auto-detects from `organization_id`/`user_id` columns. Only configure for exceptions. |
|
|
186
|
+
| Access | DENIED | Explicitly define `access` rules with roles |
|
|
187
|
+
| Guards | LOCKED | Explicitly list `createable`, `updatable` fields |
|
|
188
|
+
| Actions | BLOCKED | Explicitly define `access` for each action |
|
|
189
|
+
|
|
190
|
+
**You must deliberately open each door.** This prevents accidental data exposure.
|
|
191
|
+
|
|
192
|
+
## Other Resource Options
|
|
193
|
+
|
|
194
|
+
Beyond the four security layers, `defineTable` accepts a handful of declarative hints that shape the generated API and the CMS without touching your security posture.
|
|
195
|
+
|
|
196
|
+
| Option | What it does | Full reference |
|
|
197
|
+
|---|---|---|
|
|
198
|
+
| `views` | Named column projections — `GET /resource/views/{name}` returns a subset of columns under its own access rule. | [Views](/compiler/definitions/views) |
|
|
199
|
+
| `references` | Explicit FK target table for columns that don't follow the "Id"-stripped convention (e.g. `vendorId → contact`). | [CMS Schema Registry](/stack/cms/schema-registry) |
|
|
200
|
+
| `displayColumn` | Column to use as the human-readable label in FK resolutions and CMS list views (auto-detected as `name`/`title`/`label` if not set). | [CMS Table Views](/stack/cms/table-views) |
|
|
201
|
+
| `defaultSort` | Default sort order for CMS list rendering (`{ field, order: "asc" \| "desc" }`). | [CMS Table Views](/stack/cms/table-views) |
|
|
202
|
+
| `inputHints` | Per-column CMS input type: `select`, `richtext`, `textarea`, `lookup`, `currency`, etc. Pure CMS hint, no runtime effect. | [CMS Record Layouts](/stack/cms/record-layouts) |
|
|
203
|
+
| `layouts` | Named record-page layouts — group fields into sections (collapsed, multi-column). Falls back to auto-grouping if unset. | [CMS Record Layouts](/stack/cms/record-layouts) |
|
|
204
|
+
| `embeddings` | Auto-generate vector embeddings for specified fields on insert/update. | [Stack → Embeddings](/stack/vector/using-embeddings) |
|
|
205
|
+
| `realtime` | Per-table broadcast config (`enabled`, `onInsert`, `onUpdate`, `onDelete`, `requiredRoles`, `fields`). | [Stack → Realtime](/stack/realtime/using-realtime) |
|
|
206
|
+
| `path` | Override the route base path (defaults to feature name). | — |
|
|
207
|
+
|
|
208
|
+
All options are optional — omit them and Quickback uses sensible defaults (auto-detected display column, auto-grouped layout, no embeddings, no realtime).
|
|
209
|
+
|
|
210
|
+
## Next Steps
|
|
211
|
+
|
|
212
|
+
1. [Database Schema](/compiler/definitions/schema) — Define your tables
|
|
213
|
+
2. [Firewall](/compiler/definitions/firewall) — Set up data isolation
|
|
214
|
+
3. [Access](/compiler/definitions/access) — Configure CRUD permissions
|
|
215
|
+
4. [Guards](/compiler/definitions/guards) — Control field modifications
|
|
216
|
+
5. [Masking](/compiler/definitions/masking) — Hide sensitive data
|
|
217
|
+
6. [Views](/compiler/definitions/views) — Column-level security
|
|
218
|
+
7. [Validation](/compiler/definitions/validation) — Field validation rules
|
|
219
|
+
8. [Actions](/compiler/definitions/actions) — Add custom business logic
|