@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,445 @@
|
|
|
1
|
+
# Access - Role & Condition-Based Access Control
|
|
2
|
+
|
|
3
|
+
Define who can perform CRUD operations and under what conditions.
|
|
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(),
|
|
17
|
+
notes: text('notes'),
|
|
18
|
+
organizationId: text('organization_id').notNull(),
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
export default defineTable(applications, {
|
|
22
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
23
|
+
guards: { createable: ["candidateId", "jobId", "notes"], updatable: ["notes"] },
|
|
24
|
+
read: {
|
|
25
|
+
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
26
|
+
},
|
|
27
|
+
crud: {
|
|
28
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
29
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
30
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
31
|
+
},
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Role Hierarchy
|
|
36
|
+
|
|
37
|
+
If your project uses a tiered role system (e.g., `member` < `admin` < `owner`), you can define a hierarchy in your config and use the `+` suffix to mean "this role and above":
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
// quickback.config.ts
|
|
41
|
+
export default defineConfig({
|
|
42
|
+
name: "my-app",
|
|
43
|
+
auth: {
|
|
44
|
+
roleHierarchy: ['member', 'admin', 'owner'], // lowest → highest
|
|
45
|
+
},
|
|
46
|
+
// ...
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Then in your resource definitions:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
read: { access: { roles: ["member+"] } }, // member, admin, owner
|
|
54
|
+
crud: {
|
|
55
|
+
create: { access: { roles: ["admin+"] } }, // admin, owner
|
|
56
|
+
delete: { access: { roles: ["owner"] } }, // owner only (no +)
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The `+` suffix expands at compile time — `"member+"` becomes `["member", "admin", "owner"]` in the generated code. You can mix hierarchical and exact roles: `roles: ["member+", "finance"]` expands to `["member", "admin", "owner", "finance"]`.
|
|
61
|
+
|
|
62
|
+
- Roles without `+` are exact matches (no expansion)
|
|
63
|
+
- Pseudo-roles (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`) cannot use the `+` suffix — they're terminal markers
|
|
64
|
+
- Using `+` with a role not in the hierarchy throws a compile error
|
|
65
|
+
- Using `+` without configuring `auth.roleHierarchy` throws a compile error
|
|
66
|
+
|
|
67
|
+
## Configuration Options
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
interface Access {
|
|
71
|
+
// Org-membership roles (OR logic — user needs at least one)
|
|
72
|
+
// Matched against ctx.roles. Use "role+" suffix for hierarchy expansion.
|
|
73
|
+
roles?: string[];
|
|
74
|
+
|
|
75
|
+
// User-table role (OR logic). Matched against ctx.userRole from the
|
|
76
|
+
// user.role column — independent of org membership. See userRole below.
|
|
77
|
+
userRole?: string[];
|
|
78
|
+
|
|
79
|
+
// Record-level conditions
|
|
80
|
+
record?: {
|
|
81
|
+
[field: string]: FieldCondition;
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
// Combinators
|
|
85
|
+
or?: Access[];
|
|
86
|
+
and?: Access[];
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## `userRole` vs `roles`
|
|
91
|
+
|
|
92
|
+
`roles` and `userRole` check **two different fields** and are often confused — get this wrong and you'll grant access too broadly.
|
|
93
|
+
|
|
94
|
+
| Primitive | Checks | Source | Example values |
|
|
95
|
+
|-----------|--------|--------|----------------|
|
|
96
|
+
| `roles` | `ctx.roles` | Org membership (multi-tenant) or single-tenant mirror of `user.role` | `"owner"`, `"admin"`, `"member"` |
|
|
97
|
+
| `userRole` | `ctx.userRole` | The `user.role` column (Better Auth admin plugin) | `"user"`, `"admin"` |
|
|
98
|
+
|
|
99
|
+
In multi-tenant mode, **`roles: ["admin"]` means "org admin" — not a platform-wide admin.** An org-admin of Acme Corp has no elevated rights across other orgs. If you want to let Better Auth system admins through regardless of org membership (e.g., for support/ops), use `userRole: ["admin"]`.
|
|
100
|
+
|
|
101
|
+
In single-tenant mode (`features.organizations: false`), `ctx.roles` mirrors `user.role`, so `roles: ["admin"]` and `userRole: ["admin"]` behave the same. Using `userRole` in single-tenant code is still preferred — it documents intent and keeps the gate correct if you later enable orgs.
|
|
102
|
+
|
|
103
|
+
### When to use `userRole`
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
// Platform admin can see SSNs on every customer record, regardless of org
|
|
107
|
+
masking: {
|
|
108
|
+
ssn: { type: 'ssn', show: { userRole: ['admin'] } },
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// Support staff (user.role === 'admin') OR the org owner can refund
|
|
112
|
+
access: {
|
|
113
|
+
or: [
|
|
114
|
+
{ userRole: ['admin'] },
|
|
115
|
+
{ roles: ['owner'] },
|
|
116
|
+
],
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// CMS-internal resource: only platform admins
|
|
120
|
+
read: { access: { userRole: ['admin'] } },
|
|
121
|
+
crud: {
|
|
122
|
+
create: { access: { userRole: ['admin'] } },
|
|
123
|
+
update: { access: { userRole: ['admin'] } },
|
|
124
|
+
delete: { access: { userRole: ['admin'] } },
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
When `roles` and `userRole` both appear in a single `Access` node, they're combined with AND — the user must satisfy both. Use `or:` to express "one or the other".
|
|
129
|
+
|
|
130
|
+
`userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"` and `"admin"`). If you've added custom user-table roles via Better Auth, list them explicitly.
|
|
131
|
+
|
|
132
|
+
### Pseudo-roles
|
|
133
|
+
|
|
134
|
+
Quickback ships four UPPERCASE role markers that are **not backed by a Better Auth role column** — they're system-level shortcuts handled directly by the compiler. The casing carries the boundary: UPPERCASE = pseudo-role (no plugin context required), lowercase = real role from a plugin's table (e.g. `members.role` from the org plugin).
|
|
135
|
+
|
|
136
|
+
| Role | Auth gate | Compile-time requirement | Runtime check |
|
|
137
|
+
|------|-----------|-------------------------|---------------|
|
|
138
|
+
| `PUBLIC` | bypassed | **read-only** — rejected on `crud.create`/`update`/`delete` and on actions | always passes (auth skipped) |
|
|
139
|
+
| `AUTHENTICATED` | required | none | `ctx.authenticated === true` |
|
|
140
|
+
| `USER` | required | resource firewall **must** scope by `userId` | `ctx.authenticated` AND (`ctx.userRole` is unset OR `ctx.userRole === "user"`) |
|
|
141
|
+
| `ADMIN` | required | Better Auth admin plugin **must** be enabled | `ctx.authenticated && ctx.userRole === "admin"` |
|
|
142
|
+
|
|
143
|
+
You can mix pseudo-roles with real roles in the same list — they're OR'd together.
|
|
144
|
+
|
|
145
|
+
#### `PUBLIC` — unauthenticated access
|
|
146
|
+
|
|
147
|
+
Use `roles: ["PUBLIC"]` for public-facing endpoints like contact forms, public listings, or webhooks. Skips both the auth gate and the role check.
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
access: { roles: ["PUBLIC"] }
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**Important:**
|
|
154
|
+
- `PUBLIC` skips authentication and role checks — anyone can call the endpoint
|
|
155
|
+
- **`PUBLIC` is read-only.** It's allowed on `read.access`, `crud.list`, `crud.get`, and `read.views.*`, but **rejected at compile time** on `crud.create`, `crud.update`, `crud.delete`, and on actions. Anonymous writes are almost always a misconfiguration (vibe-coded `/comments` POST endpoints, runaway forms). If you genuinely need an anonymous write surface — public form submission, webhook ingest — declare a custom action that does its own auth (signed payload, captcha, HMAC) and use `firewall: { exception: true }` on the resource.
|
|
156
|
+
- **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
|
|
157
|
+
- Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
|
|
158
|
+
- The wildcard `"*"` is **not supported** — using it throws a compile-time error
|
|
159
|
+
- Tables with no isolation columns and any `PUBLIC` route do not require `firewall: [{ exception: true }]`
|
|
160
|
+
|
|
161
|
+
For org-scoped tables, `PUBLIC` routes still filter by organization. Since the user isn't authenticated, the organization ID must be passed as a query parameter:
|
|
162
|
+
|
|
163
|
+
```
|
|
164
|
+
GET /api/v1/listings?organizationId=org_abc123
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
The firewall WHERE clause is always enforced. If no `organizationId` is provided, the API returns a `400` with code `ORG_REQUIRED`.
|
|
168
|
+
|
|
169
|
+
```typescript
|
|
170
|
+
// Public listing page — anyone can browse, but scoped to an org
|
|
171
|
+
export default defineTable(listings, {
|
|
172
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
173
|
+
read: { access: { roles: ["PUBLIC"] } }, // Public browsing + detail
|
|
174
|
+
crud: {
|
|
175
|
+
create: { access: { roles: ["admin", "member"] } }, // Auth required to create
|
|
176
|
+
},
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
#### `AUTHENTICATED` — any signed-in user
|
|
181
|
+
|
|
182
|
+
Use `roles: ["AUTHENTICATED"]` for endpoints that any logged-in user can hit, regardless of role or org membership. No plugin context required.
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
// Public events feed — any signed-in user can list/read; anonymous gets 401
|
|
186
|
+
read: { access: { roles: ["AUTHENTICATED"] } }
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
#### `USER` — per-user records
|
|
190
|
+
|
|
191
|
+
Use `roles: ["USER"]` for resources where each user only sees their own records. **Requires the firewall to scope by `userId`** — the role marker is the access half of the pair, the firewall is the row-filter half.
|
|
192
|
+
|
|
193
|
+
```typescript
|
|
194
|
+
// "My todos" — each caller sees only their own rows
|
|
195
|
+
export default defineTable(todos, {
|
|
196
|
+
firewall: [{ field: 'userId', equals: 'ctx.userId' }],
|
|
197
|
+
read: { access: { roles: ["USER"] } },
|
|
198
|
+
crud: {
|
|
199
|
+
create: { access: { roles: ["USER"] } },
|
|
200
|
+
update: { access: { roles: ["USER"] } },
|
|
201
|
+
delete: { access: { roles: ["USER"] } },
|
|
202
|
+
},
|
|
203
|
+
});
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
If you forget the `userId` firewall predicate, the compiler throws:
|
|
207
|
+
|
|
208
|
+
> `roles: ["USER"]` requires the resource to be scoped per-user. Add a `userId` column (auto-scoped) or an explicit owner predicate. If you want any signed-in user to read all records, use `roles: ["AUTHENTICATED"]` instead.
|
|
209
|
+
|
|
210
|
+
When the Better Auth admin plugin is enabled, `USER` matches `user.role === "user"` specifically — admins are excluded and should use `["USER", "ADMIN"]` if the same route should serve both.
|
|
211
|
+
|
|
212
|
+
#### `ADMIN` — Better Auth admin-plugin admins
|
|
213
|
+
|
|
214
|
+
Use `roles: ["ADMIN"]` for system-administrator endpoints. **Requires the Better Auth admin plugin** so `user.role` exists. Compiles to `ctx.userRole === "admin"`.
|
|
215
|
+
|
|
216
|
+
```typescript
|
|
217
|
+
// Platform-admin-only audit log
|
|
218
|
+
read: { access: { roles: ["ADMIN"] } }
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Without the admin plugin you get a compile error pointing you to either enable the plugin or use lowercase `roles: ["admin"]` (the org-membership admin role).
|
|
222
|
+
|
|
223
|
+
#### Mixing pseudo-roles with real roles
|
|
224
|
+
|
|
225
|
+
Pseudo-roles and lowercase real roles compose with OR:
|
|
226
|
+
|
|
227
|
+
```typescript
|
|
228
|
+
// Record owner OR a system admin can read
|
|
229
|
+
read: { access: { roles: ["USER", "ADMIN"] } }
|
|
230
|
+
|
|
231
|
+
// Org owner OR system admin
|
|
232
|
+
delete: { access: { roles: ["owner", "ADMIN"] } }
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
> Note: today, an `ADMIN` match still goes through the `userId` firewall scope on USER-scoped resources — admins see only records they own on those routes. Use `firewall: { exception: true }` on a separate admin-only route if you need cross-user visibility.
|
|
236
|
+
|
|
237
|
+
#### Quick reference
|
|
238
|
+
|
|
239
|
+
```typescript
|
|
240
|
+
// Unauthenticated public
|
|
241
|
+
access: { roles: ["PUBLIC"] }
|
|
242
|
+
|
|
243
|
+
// Any signed-in user, no scoping
|
|
244
|
+
access: { roles: ["AUTHENTICATED"] }
|
|
245
|
+
|
|
246
|
+
// Per-user records (requires userId firewall scope)
|
|
247
|
+
access: { roles: ["USER"] }
|
|
248
|
+
|
|
249
|
+
// System admin (requires admin plugin)
|
|
250
|
+
access: { roles: ["ADMIN"] }
|
|
251
|
+
|
|
252
|
+
// Org-membership roles with hierarchy expansion
|
|
253
|
+
access: { roles: ["member+"] } // expands to ["member", "admin", "owner"]
|
|
254
|
+
access: { roles: ["admin+"] } // expands to ["admin", "owner"]
|
|
255
|
+
access: { roles: ["admin"] } // exact match (no expansion)
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
```typescript
|
|
259
|
+
// Field conditions - value can be string | number | boolean
|
|
260
|
+
type FieldCondition =
|
|
261
|
+
| { equals: value | '$ctx.userId' | '$ctx.activeOrgId' }
|
|
262
|
+
| { notEquals: value }
|
|
263
|
+
| { in: value[] }
|
|
264
|
+
| { notIn: value[] }
|
|
265
|
+
| { lessThan: number }
|
|
266
|
+
| { greaterThan: number }
|
|
267
|
+
| { lessThanOrEqual: number }
|
|
268
|
+
| { greaterThanOrEqual: number };
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
## Read & CRUD Configuration
|
|
272
|
+
|
|
273
|
+
Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under `crud:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.
|
|
274
|
+
|
|
275
|
+
```typescript
|
|
276
|
+
read: {
|
|
277
|
+
// LIST + GET - GET /resource and GET /resource/:id
|
|
278
|
+
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
279
|
+
pageSize: 25, // Default page size
|
|
280
|
+
maxPageSize: 100, // Client can't exceed this
|
|
281
|
+
views: { // Per-view field projections
|
|
282
|
+
summary: {
|
|
283
|
+
fields: ['id', 'candidateId', 'jobId', 'stage'],
|
|
284
|
+
access: { roles: ["interviewer"] },
|
|
285
|
+
},
|
|
286
|
+
},
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
crud: {
|
|
290
|
+
// CREATE - POST /resource
|
|
291
|
+
create: {
|
|
292
|
+
access: { roles: ["owner", "hiring-manager", "recruiter"] },
|
|
293
|
+
defaults: { // Default values for new records
|
|
294
|
+
stage: 'applied',
|
|
295
|
+
},
|
|
296
|
+
},
|
|
297
|
+
|
|
298
|
+
// UPDATE - PATCH /resource/:id
|
|
299
|
+
update: {
|
|
300
|
+
access: {
|
|
301
|
+
or: [
|
|
302
|
+
{ roles: ["hiring-manager", "recruiter"] },
|
|
303
|
+
{ roles: ["interviewer"], record: { stage: { equals: "interview" } } }
|
|
304
|
+
]
|
|
305
|
+
},
|
|
306
|
+
},
|
|
307
|
+
|
|
308
|
+
// DELETE - DELETE /resource/:id
|
|
309
|
+
delete: {
|
|
310
|
+
access: { roles: ["owner", "hiring-manager"] },
|
|
311
|
+
mode: "soft", // 'soft' (default) or 'hard'
|
|
312
|
+
},
|
|
313
|
+
|
|
314
|
+
// PUT - PUT /resource/:id (only when generateId: false + guards: false)
|
|
315
|
+
put: {
|
|
316
|
+
access: { roles: ["hiring-manager", "sync-service"] },
|
|
317
|
+
},
|
|
318
|
+
}
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
## Evaluation Order
|
|
322
|
+
|
|
323
|
+
Generated `/:id` and batch handlers evaluate access in this fixed order:
|
|
324
|
+
|
|
325
|
+
1. **Auth gate** — 401 if unauthenticated
|
|
326
|
+
2. **Pre-record access** — role-only check (skips `access.record` predicates)
|
|
327
|
+
3. **Firewall query** — `WHERE` clause filters by ownership
|
|
328
|
+
4. **Post-record access** — full check including record-level predicates
|
|
329
|
+
5. **Masking** — applied to the response
|
|
330
|
+
|
|
331
|
+
Step 2 closes the 404-vs-403 ID-probe channel: an unauthorized caller without
|
|
332
|
+
a matching role gets 403 before the database is touched, so they can't tell
|
|
333
|
+
apart "row exists out-of-scope" from "row doesn't exist." A caller with the
|
|
334
|
+
right role but the wrong tenant gets 403 by default (firewall reveals via
|
|
335
|
+
the access layer); set
|
|
336
|
+
[`firewallErrorMode: 'hide'`](/compiler/definitions/firewall) to return an
|
|
337
|
+
opaque 404 instead.
|
|
338
|
+
|
|
339
|
+
Function-form access (`access: async (ctx, record) => ...`) is opaque to
|
|
340
|
+
the pre-record phase and always passes there; it's fully evaluated post-record.
|
|
341
|
+
|
|
342
|
+
## List Filtering (Query Parameters)
|
|
343
|
+
|
|
344
|
+
The LIST endpoint automatically supports filtering via query params:
|
|
345
|
+
|
|
346
|
+
```
|
|
347
|
+
GET /jobs?status=open # Exact match
|
|
348
|
+
GET /jobs?salaryMin.gt=50000 # Greater than
|
|
349
|
+
GET /jobs?salaryMin.gte=50000 # Greater than or equal
|
|
350
|
+
GET /jobs?salaryMax.lt=200000 # Less than
|
|
351
|
+
GET /jobs?salaryMax.lte=200000 # Less than or equal
|
|
352
|
+
GET /jobs?status.ne=closed # Not equal
|
|
353
|
+
GET /jobs?title.like=Engineer # Pattern match (LIKE %value%)
|
|
354
|
+
GET /jobs?status.in=open,draft # IN clause
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
| Operator | Query Param | SQL Equivalent |
|
|
358
|
+
|----------|-------------|----------------|
|
|
359
|
+
| Equals | `?field=value` | `WHERE field = value` |
|
|
360
|
+
| Not equals | `?field.ne=value` | `WHERE field != value` |
|
|
361
|
+
| Greater than | `?field.gt=value` | `WHERE field > value` |
|
|
362
|
+
| Greater or equal | `?field.gte=value` | `WHERE field >= value` |
|
|
363
|
+
| Less than | `?field.lt=value` | `WHERE field < value` |
|
|
364
|
+
| Less or equal | `?field.lte=value` | `WHERE field <= value` |
|
|
365
|
+
| Pattern match | `?field.like=value` | `WHERE field LIKE '%value%'` |
|
|
366
|
+
| In list | `?field.in=a,b,c` | `WHERE field IN ('a','b','c')` |
|
|
367
|
+
|
|
368
|
+
## Sorting & Pagination
|
|
369
|
+
|
|
370
|
+
```
|
|
371
|
+
GET /jobs?sort=createdAt&order=desc # Sort by field
|
|
372
|
+
GET /jobs?limit=25&offset=50 # Pagination
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
- **Default limit**: 50
|
|
376
|
+
- **Max limit**: 100 (or `maxPageSize` if configured)
|
|
377
|
+
- **Default order**: `asc`
|
|
378
|
+
|
|
379
|
+
## Delete Modes
|
|
380
|
+
|
|
381
|
+
```typescript
|
|
382
|
+
delete: {
|
|
383
|
+
access: { roles: ["owner", "hiring-manager"] },
|
|
384
|
+
mode: "soft", // Sets deletedAt/deletedBy, record stays in DB
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
delete: {
|
|
388
|
+
access: { roles: ["owner", "hiring-manager"] },
|
|
389
|
+
mode: "hard", // Permanent deletion from database
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
## Context Variables
|
|
394
|
+
|
|
395
|
+
Use `$ctx.` prefix to reference context values in conditions:
|
|
396
|
+
|
|
397
|
+
```typescript
|
|
398
|
+
// User can only view their own records
|
|
399
|
+
access: {
|
|
400
|
+
record: { userId: { equals: "$ctx.userId" } }
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
// Nested path support for complex context objects
|
|
404
|
+
access: {
|
|
405
|
+
record: { ownerId: { equals: "$ctx.user.id" } }
|
|
406
|
+
}
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
### AppContext Reference
|
|
410
|
+
|
|
411
|
+
| Property | Type | Description |
|
|
412
|
+
|----------|------|-------------|
|
|
413
|
+
| `$ctx.userId` | `string` | Current authenticated user's ID |
|
|
414
|
+
| `$ctx.activeOrgId` | `string` | User's active organization ID |
|
|
415
|
+
| `$ctx.activeTeamId` | `string \| null` | User's active team ID (if applicable) |
|
|
416
|
+
| `$ctx.roles` | `string[]` | User's roles in current context |
|
|
417
|
+
| `$ctx.isAnonymous` | `boolean` | Whether user is anonymous |
|
|
418
|
+
| `$ctx.user` | `object` | Full user object from auth provider |
|
|
419
|
+
| `$ctx.user.id` | `string` | User ID (nested path example) |
|
|
420
|
+
| `$ctx.user.email` | `string` | User's email address |
|
|
421
|
+
| `$ctx.{property}` | `any` | Any custom context property |
|
|
422
|
+
|
|
423
|
+
## Function-Based Access
|
|
424
|
+
|
|
425
|
+
For complex access logic that can't be expressed declaratively, use a function:
|
|
426
|
+
|
|
427
|
+
```typescript
|
|
428
|
+
crud: {
|
|
429
|
+
update: {
|
|
430
|
+
access: async (ctx, record) => {
|
|
431
|
+
// Custom logic - return true to allow, false to deny
|
|
432
|
+
if (ctx.roles.includes('admin')) return true;
|
|
433
|
+
if (record.ownerId === ctx.userId) return true;
|
|
434
|
+
|
|
435
|
+
// Check custom business logic
|
|
436
|
+
const membership = await checkTeamMembership(ctx.userId, record.teamId);
|
|
437
|
+
return membership.canEdit;
|
|
438
|
+
}
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
Function access receives:
|
|
444
|
+
- `ctx`: The full AppContext object
|
|
445
|
+
- `record`: The record being accessed (for get/update/delete operations)
|