@quickback-dev/cli 0.10.15 → 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.
Files changed (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. 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)