@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.
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,241 @@
1
+ # Masking - Field Redaction
2
+
3
+ Hide sensitive data from unauthorized users while showing it to those with permission.
4
+
5
+ ## Automatic Masking (Secure by Default)
6
+
7
+ Quickback automatically applies masking to columns that match sensitive naming patterns. This ensures a high security posture even if you don't explicitly configure masking.
8
+
9
+ ### Sensitive Keywords & Default Masks
10
+
11
+ | Pattern | Default Mask | Description |
12
+ | :--- | :--- | :--- |
13
+ | `email` | `email` | p***@e******.com |
14
+ | `phone`, `mobile`, `fax` | `phone` | ******4567 |
15
+ | `ssn`, `socialsecurity`, `nationalid` | `ssn` | *****6789 |
16
+ | `creditcard`, `cc`, `cardnumber`, `cvv` | `creditCard` | ************1234 |
17
+ | `iban` | `redact` | [REDACTED] |
18
+ | `password`, `secret`, `token`, `apikey`, `privatekey` | `redact` | [REDACTED] |
19
+ | `accesstoken`, `refreshtoken`, `clientsecret`, `signingsecret`, `bearer` | `redact` | [REDACTED] |
20
+ | `stripe`, `webhook` | `redact` | [REDACTED] |
21
+
22
+ > **Smart Pattern Matching**
23
+ >
24
+ > Auto-masking also matches suffixes like `workEmail`, `homePhone`, `apiSecret`, `stripeApiKey`, `webhookSecret`, `customerStripe`, or `orderWebhook`.
25
+
26
+
27
+ ### Build-Time Alerts
28
+
29
+ If the compiler auto-detects a sensitive column that you haven't explicitly configured, it will emit a warning:
30
+
31
+ ```bash
32
+ [Warning] Auto-masking enabled for sensitive column "users.email". Explicitly configure masking to silence this warning.
33
+ ```
34
+
35
+ To silence this warning or change the behavior, simply define the field explicitly in your `masking` configuration. Explicit configurations always take precedence over auto-detected defaults.
36
+
37
+ #### Tables without an owner column
38
+
39
+ The default auto-mask predicate is `show: { or: 'owner', roles: ['admin'] }` — admins always see the value, the row's owner sees their own. If the table has no owner column at all (no `userId` / `ownerId` and no `q.scope('owner')`), the compiler drops the `owner` clause and emits a second warning so the rule is still safe but transparent:
40
+
41
+ ```bash
42
+ [Warning] Auto-masking on "people.email" requested owner OR-show, but "people"
43
+ has no "ownerId" column. Falling back to roles-only (roles: ["admin"]).
44
+ Declare `masking: { email: { show: { roles: [...] } } }` explicitly to
45
+ silence this and pick a real predicate.
46
+ ```
47
+
48
+ This is a real behavioral signal, not boilerplate — the auto-detector can't tell whether the table is "ownerless on purpose" (e.g. a shared lookup table) or "should have an owner column but was authored without one." Declare the predicate explicitly to silence the warning and lock in the intent.
49
+
50
+ ### Overriding Defaults
51
+
52
+ If you want to show a sensitive field to everyone (disable masking) or use a different rule, define it explicitly in the `resource.masking` block:
53
+
54
+ ```typescript
55
+ export default defineTable(candidates, {
56
+ masking: {
57
+ // Show email to everyone (overrides auto-masking)
58
+ email: { type: 'email', show: { roles: ['everyone'] } },
59
+
60
+ // Silence warning but keep secure (recruiter and above only)
61
+ phone: { type: 'phone', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } }
62
+ }
63
+ });
64
+ ```
65
+
66
+ ## Basic Usage
67
+
68
+ ```typescript
69
+ // features/candidates/candidates.ts
70
+ import { feature, q } from '@quickback/compiler';
71
+
72
+ export default feature('candidates', {
73
+ columns: {
74
+ id: q.id(),
75
+ name: q.text().required(),
76
+ email: q.text().required(),
77
+ phone: q.text().optional(),
78
+ resumeUrl: q.text().optional(),
79
+ organizationId: q.scope('organization'),
80
+ },
81
+ guards: { createable: ["name", "email", "phone", "resumeUrl"], updatable: ["name", "phone"] },
82
+ masking: {
83
+ email: { type: 'email', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
84
+ phone: { type: 'phone', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
85
+ },
86
+ read: { access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] } },
87
+ crud: { /* ... */ },
88
+ });
89
+ ```
90
+
91
+ ## Built-in Mask Types
92
+
93
+ | Type | Example Input | Masked Output |
94
+ |------|---------------|---------------|
95
+ | `'email'` | `john@yourdomain.com` | `j***@y*********.com` |
96
+ | `'phone'` | `555-123-4567` | `******4567` |
97
+ | `'ssn'` | `123-45-6789` | `*****6789` |
98
+ | `'creditCard'` | `4111111111111111` | `************1111` |
99
+ | `'name'` | `John Smith` | `J*** S****` |
100
+ | `'redact'` | `anything` | `[REDACTED]` |
101
+ | `'custom'` | (your logic) | (your output) |
102
+
103
+ ## Configuration
104
+
105
+ ```typescript
106
+ masking: {
107
+ // Basic masking - everyone sees masked value
108
+ phone: { type: 'phone' },
109
+
110
+ // Show unmasked to specific roles
111
+ email: {
112
+ type: 'email',
113
+ show: { roles: ['hiring-manager', 'recruiter'] }
114
+ },
115
+
116
+ // Show unmasked to owner (createdBy === ctx.userId)
117
+ resumeUrl: {
118
+ type: 'redact',
119
+ show: { or: 'owner' }
120
+ },
121
+
122
+ // Custom mask function
123
+ externalProfileUrl: {
124
+ type: 'custom',
125
+ mask: (value) => value.slice(0, 4) + '...' + value.slice(-4),
126
+ show: { roles: ['recruiter'] }
127
+ },
128
+ }
129
+ ```
130
+
131
+ ## Show Conditions
132
+
133
+ ```typescript
134
+ show: {
135
+ roles?: string[]; // Unmasked if user has any of these roles
136
+ or?: 'owner'; // Unmasked if user is the record owner
137
+ }
138
+ ```
139
+
140
+ The `'owner'` condition compares against the owner column declared via `q.scope('owner')` (or auto-detected from a `userId` / `ownerId` column). If no owner scope is present, it falls back to `createdBy`.
141
+
142
+ ## Query Gate (filter / sort / search)
143
+
144
+ Masking has a second concern beyond hiding values in the response: a non-admin caller could enumerate masked PII via the query string — e.g. `?filter=email:like:%@target.com` — and infer presence even when the response payload is redacted. The `query` allowlist closes this:
145
+
146
+ ```typescript
147
+ masking: {
148
+ email: {
149
+ type: 'email',
150
+ show: { roles: ['admin'] },
151
+ // Optional — defaults to show.roles when omitted
152
+ query: { roles: ['admin'] },
153
+ },
154
+ }
155
+ ```
156
+
157
+ `query` is a single role gate that covers `?filter`, `?sort`, and `?search` uniformly. When omitted, it inherits from `show.roles` — "if you can see it, you can query it" — which is the right shape for almost all PII.
158
+
159
+ A view can opt back in for a higher-privileged role pair by listing the column in its own `query.{filterable,searchable,sortable}` allowlist. The compiler validates at build time that the view's access roles intersect the masking `query.roles` (or `show.roles` when `query` is omitted), so the opt-in can never reach a caller who'd see the value masked.
160
+
161
+ ```typescript
162
+ masking: {
163
+ email: { type: 'email', show: { roles: ['admin'] } },
164
+ // query: defaults to show.roles → ['admin']
165
+ },
166
+ read: {
167
+ views: {
168
+ pipeline: {
169
+ fields: ['id', 'name'],
170
+ access: { roles: ['member', 'admin'] },
171
+ query: {
172
+ searchable: ['name'], // email NOT listed → not searchable on this view
173
+ },
174
+ },
175
+ full: {
176
+ fields: ['id', 'name', 'email'],
177
+ access: { roles: ['admin'] },
178
+ query: {
179
+ filterable: ['email'], // ✓ admin satisfies email's query gate
180
+ searchable: ['name', 'email'],
181
+ },
182
+ },
183
+ },
184
+ },
185
+ ```
186
+
187
+ `query` replaces the legacy per-capability flags (`filterable`, `searchable`, `sortable`). Setting any of those is rejected at compile time with a migration hint.
188
+
189
+ ## Complete Example
190
+
191
+ ```typescript
192
+ // features/candidates/candidates.ts
193
+ import { feature, q } from '@quickback/compiler';
194
+
195
+ export default feature('candidates', {
196
+ columns: {
197
+ id: q.id(),
198
+ name: q.text().required().filterable('like').searchable(),
199
+ email: q.text().required().filterable('eq').searchable(),
200
+ phone: q.text().optional().filterable('eq'),
201
+ resumeUrl: q.text().optional(),
202
+ organizationId: q.scope('organization'),
203
+ },
204
+ guards: {
205
+ createable: ['name', 'email', 'phone', 'resumeUrl'],
206
+ updatable: ['name', 'phone'],
207
+ },
208
+ masking: {
209
+ email: { type: 'email', show: { roles: ['admin+'] } },
210
+ phone: { type: 'phone', show: { roles: ['admin+'] } },
211
+ resumeUrl: {
212
+ type: 'custom',
213
+ mask: () => '[RESUME LINK HIDDEN]',
214
+ show: { roles: ['admin+'] },
215
+ },
216
+ },
217
+ read: {
218
+ access: { roles: ['member+'] },
219
+ views: {
220
+ pipeline: {
221
+ fields: ['id', 'name'],
222
+ access: { roles: ['member+'] },
223
+ query: { searchable: ['name'] },
224
+ },
225
+ full: {
226
+ fields: ['id', 'name', 'email', 'phone', 'resumeUrl'],
227
+ access: { roles: ['admin+'] },
228
+ query: {
229
+ filterable: ['email', 'phone'],
230
+ searchable: ['name', 'email'],
231
+ },
232
+ },
233
+ },
234
+ },
235
+ crud: {
236
+ create: { access: { roles: ['admin+'] } },
237
+ update: { access: { roles: ['admin+'] } },
238
+ delete: { access: { roles: ['owner'] }, mode: 'soft' },
239
+ },
240
+ });
241
+ ```
@@ -0,0 +1,220 @@
1
+ # Read - Unified Read Pipeline
2
+
3
+ The `read` block owns the read side of every resource: the collection-level
4
+ `GET /` endpoint, single-record `GET /:id`, and named view projections. It
5
+ replaces the legacy `crud.list` and `crud.get` shapes — those are rejected
6
+ at compile time in DSL v2.
7
+
8
+ ## Basic Usage
9
+
10
+ ```typescript
11
+ // features/customers/customers.ts
12
+ import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
13
+ import { defineTable } from '@quickback/compiler';
14
+
15
+ export const customers = sqliteTable('customers', {
16
+ id: text('id').primaryKey(),
17
+ name: text('name').notNull(),
18
+ email: text('email').notNull(),
19
+ ssn: text('ssn'),
20
+ status: text('status').notNull(),
21
+ organizationId: text('organization_id').notNull(),
22
+ });
23
+
24
+ export default defineTable(customers, {
25
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
26
+ masking: {
27
+ ssn: { type: 'ssn', show: { roles: ['admin'] } },
28
+ },
29
+ read: {
30
+ access: { roles: ['member', 'admin'] },
31
+ views: {
32
+ summary: {
33
+ fields: ['id', 'name', 'status'],
34
+ access: { roles: ['member', 'admin'] },
35
+ },
36
+ full: {
37
+ fields: ['id', 'name', 'email', 'ssn', 'status'],
38
+ access: { roles: ['admin'] },
39
+ },
40
+ },
41
+ },
42
+ crud: {
43
+ create: { access: { roles: ['admin'] } },
44
+ update: { access: { roles: ['admin'] } },
45
+ delete: { access: { roles: ['admin'] }, mode: 'soft' },
46
+ },
47
+ });
48
+ ```
49
+
50
+ ## What `read` Owns
51
+
52
+ | Endpoint | Gate |
53
+ |----------|------|
54
+ | `GET /api/v1/{resource}` | `read.access` |
55
+ | `GET /api/v1/{resource}/:id` | `read.access` |
56
+ | `GET /api/v1/{resource}?view={name}` | `read.views[name].access` (falls back to `read.access`) |
57
+ | `GET /api/v1/{resource}/views/{name}` | Same — explicit path form of the `?view=` dispatch |
58
+
59
+ Single-record `GET /:id` inherits `read.access` automatically — there's no
60
+ separate `read.get` block. If you need different access for single records,
61
+ use record-level conditions on `read.access`:
62
+
63
+ ```typescript
64
+ read: {
65
+ access: {
66
+ or: [
67
+ { roles: ['admin'] },
68
+ { roles: ['member'], record: { ownerId: { equals: '$ctx.userId' } } },
69
+ ],
70
+ },
71
+ }
72
+ ```
73
+
74
+ ## Configuration Options
75
+
76
+ ```typescript
77
+ interface ReadConfig {
78
+ // Role/condition gate for collection reads, single-record reads, and the
79
+ // default view fallback.
80
+ access?: Access;
81
+
82
+ // Optional read-side firewall override. If omitted, the resource-level
83
+ // `firewall` block is used (the common case).
84
+ firewall?: FirewallConfig;
85
+
86
+ // Pagination defaults for collection reads.
87
+ pageSize?: number; // Default page size (default: 50)
88
+ maxPageSize?: number; // Hard cap (default: 100)
89
+
90
+ // Named field projections. Each view has its own access and field list.
91
+ views?: {
92
+ [viewName: string]: ViewConfig;
93
+ };
94
+ }
95
+
96
+ interface ViewConfig {
97
+ fields: string[]; // Columns returned by this view
98
+ access?: Access; // Per-view access (falls back to read.access)
99
+ pageSize?: number;
100
+ maxPageSize?: number;
101
+ }
102
+ ```
103
+
104
+ ## Access Ordering on `/:id`
105
+
106
+ Single-record `GET /:id` evaluates checks in this order to close the
107
+ 404-vs-403 ID-probe channel:
108
+
109
+ 1. **Auth gate** — 401 if unauthenticated
110
+ 2. **Pre-record access** — role-only check (skips `access.record` predicates)
111
+ 3. **Firewall query** — `WHERE` clause filters by ownership
112
+ 4. **Post-record access** — full check including record-level predicates
113
+ 5. **Masking** — applied to the response
114
+
115
+ An unauthorized caller without a matching role gets 403 from step 2 before
116
+ the database is touched, so they can't distinguish "row exists in another
117
+ tenant" from "row doesn't exist." A caller with the right role but the wrong
118
+ tenant gets the firewall's configured response (403 by default; see
119
+ [`firewallErrorMode: 'hide'`](/compiler/definitions/firewall) for an opaque
120
+ 404 instead).
121
+
122
+ Function-form access is opaque to the pre-check (it always passes there) and
123
+ is fully evaluated post-record, so `access: async (ctx, record) => ...`
124
+ still works as before.
125
+
126
+ ## Views Under `read.views`
127
+
128
+ Views are named field projections — Column Level Security. They live under
129
+ `read.views` (not at the resource top level). See
130
+ [Views](/compiler/definitions/views) for the full feature reference.
131
+
132
+ ```typescript
133
+ read: {
134
+ access: { roles: ['member', 'admin'] },
135
+ views: {
136
+ public: {
137
+ fields: ['id', 'title', 'status'],
138
+ access: { roles: ['PUBLIC'] },
139
+ },
140
+ internal: {
141
+ fields: ['id', 'title', 'status', 'salaryMin', 'salaryMax'],
142
+ access: { roles: ['admin'] },
143
+ },
144
+ },
145
+ }
146
+ ```
147
+
148
+ Both endpoint shapes are emitted automatically:
149
+
150
+ - Query-string dispatch: `GET /api/v1/jobs?view=internal`
151
+ - Explicit path: `GET /api/v1/jobs/views/internal`
152
+
153
+ ## Migrating from `crud.list` / `crud.get`
154
+
155
+ DSL v2 rejects both at compile time. The migration is mechanical:
156
+
157
+ | Before (DSL v1) | After (DSL v2) |
158
+ |---|---|
159
+ | `crud.list.access` | `read.access` |
160
+ | `crud.list.pageSize` | `read.pageSize` |
161
+ | `crud.list.maxPageSize` | `read.maxPageSize` |
162
+ | `crud.list.fields: [...]` | Move to a named view under `read.views` |
163
+ | `crud.get.access` | `read.access` (or record-level conditions) |
164
+ | `crud.get.fields: [...]` | Move to a named view; clients call `?view=...` |
165
+ | Top-level `views: {...}` | `read.views: {...}` |
166
+
167
+ Example before/after:
168
+
169
+ ```typescript
170
+ // Before — DSL v1
171
+ crud: {
172
+ list: {
173
+ access: { roles: ['member'] },
174
+ pageSize: 25,
175
+ },
176
+ get: {
177
+ access: { roles: ['member'] },
178
+ fields: ['id', 'name', 'status'], // per-field projection
179
+ },
180
+ create: { access: { roles: ['admin'] } },
181
+ }
182
+
183
+ // After — DSL v2
184
+ read: {
185
+ access: { roles: ['member'] },
186
+ pageSize: 25,
187
+ views: {
188
+ summary: {
189
+ fields: ['id', 'name', 'status'],
190
+ access: { roles: ['member'] },
191
+ },
192
+ },
193
+ }
194
+ crud: {
195
+ create: { access: { roles: ['admin'] } },
196
+ }
197
+ ```
198
+
199
+ Clients that previously hit `GET /:id` to retrieve only summary fields now
200
+ call `GET /:id?view=summary`.
201
+
202
+ ## Read-Only Resources
203
+
204
+ A resource that exposes only reads is valid with an empty `crud` block (or
205
+ no `crud` block at all):
206
+
207
+ ```typescript
208
+ export default defineTable(balanceSnapshots, {
209
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
210
+ read: { access: { roles: ['member', 'admin'] } },
211
+ // no crud — no writes
212
+ });
213
+ ```
214
+
215
+ ## See Also
216
+
217
+ - [Views](/compiler/definitions/views) — Full reference for named projections
218
+ - [Access](/compiler/definitions/access) — Roles, record conditions, and combinators
219
+ - [Firewall](/compiler/definitions/firewall) — Tenant scoping and `firewallErrorMode`
220
+ - [Views API](/compiler/targets/hono-api/using-the-api/views-api) — Calling views from clients