@cosmicdrift/kumiko-framework 0.413.0 → 0.414.0

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 (467) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +64 -13
  4. package/agents/api/framework-event-store.md +14 -0
  5. package/agents/api/framework-ui-types.md +149 -21
  6. package/agents/api/renderer-web.md +93 -9
  7. package/agents/api/testing-helpers.md +3 -2
  8. package/agents/api/testing-stack.md +3 -0
  9. package/agents/api/types.md +205 -14
  10. package/agents/api.md +7 -7
  11. package/agents/boot-rules.md +63 -9
  12. package/agents/examples/api-docs.md +2 -6
  13. package/agents/examples/auth-mfa.md +57 -10
  14. package/agents/examples/chat-channels.md +2 -0
  15. package/agents/examples/currencies-global.md +1 -0
  16. package/agents/examples/env-composition.md +7 -11
  17. package/agents/examples/helpdesk.md +15 -8
  18. package/agents/examples/managed-pages.md +90 -1
  19. package/agents/examples/pwa-shell.md +210 -0
  20. package/agents/examples/rate-limiting.md +3 -3
  21. package/agents/examples/record-detail-layout.md +1537 -67
  22. package/agents/examples/workflow-engine.md +16 -12
  23. package/agents/examples.md +1 -0
  24. package/agents/features-index.md +4 -2
  25. package/agents/features.md +22 -7
  26. package/agents/widgets.md +19 -1
  27. package/dist/api/api-constants.d.ts +1 -0
  28. package/dist/api/api-constants.js +4 -0
  29. package/dist/api/auth-middleware.js +4 -3
  30. package/dist/api/auth-routes-shared.js +2 -1
  31. package/dist/api/entity-read-access.d.ts +1 -0
  32. package/dist/api/entity-read-access.js +18 -0
  33. package/dist/api/export/export-route.d.ts +6 -1
  34. package/dist/api/export/export-route.js +27 -1
  35. package/dist/api/export/export-rows.js +19 -3
  36. package/dist/api/routes.d.ts +2 -0
  37. package/dist/api/routes.js +9 -1
  38. package/dist/api/server-extra-routes.js +2 -1
  39. package/dist/api/server-feature-http-routes.d.ts +9 -0
  40. package/dist/api/server-feature-http-routes.js +109 -0
  41. package/dist/api/server-middleware.js +2 -19
  42. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  43. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  44. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  45. package/dist/api/server-rate-limit-wiring.js +37 -0
  46. package/dist/api/server-routes.d.ts +4 -12
  47. package/dist/api/server-routes.js +12 -171
  48. package/dist/api/server-schema-route.d.ts +3 -0
  49. package/dist/api/server-schema-route.js +58 -0
  50. package/dist/api/server-wiring.js +2 -37
  51. package/dist/api/server.js +3 -1
  52. package/dist/compliance/override-schema.js +5 -5
  53. package/dist/compliance/sub-processors.js +10 -1
  54. package/dist/crypto/index.d.ts +1 -1
  55. package/dist/crypto/index.js +1 -1
  56. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  57. package/dist/crypto/pii-field-encryption.js +16 -1
  58. package/dist/db/apply-entity-event.js +4 -0
  59. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  60. package/dist/db/bun-sql-connection-codes.js +7 -0
  61. package/dist/db/collect-table-metas.js +4 -1
  62. package/dist/db/config-seed.js +1 -1
  63. package/dist/db/derived-field-sql.js +15 -13
  64. package/dist/db/derived-related-sql.d.ts +2 -2
  65. package/dist/db/derived-related-sql.js +4 -2
  66. package/dist/db/dialect.d.ts +3 -0
  67. package/dist/db/dialect.js +1 -3
  68. package/dist/db/driver-row-coercion.js +2 -2
  69. package/dist/db/driver-value-preparation.js +1 -1
  70. package/dist/db/eagerload.js +15 -12
  71. package/dist/db/entity-table-meta.d.ts +2 -0
  72. package/dist/db/entity-table-meta.js +7 -0
  73. package/dist/db/event-store-executor-context.js +13 -8
  74. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  75. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  76. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  77. package/dist/db/event-store-executor-read-filter.js +28 -11
  78. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  79. package/dist/db/event-store-executor-read-search.js +6 -6
  80. package/dist/db/event-store-executor-read-sort.js +3 -3
  81. package/dist/db/event-store-executor-read-where.js +14 -5
  82. package/dist/db/event-store-executor-read.js +7 -7
  83. package/dist/db/event-store-executor-write.js +50 -95
  84. package/dist/db/executor-managed-tables.js +4 -1
  85. package/dist/db/index.d.ts +4 -2
  86. package/dist/db/index.js +4 -2
  87. package/dist/db/known-table-names.d.ts +1 -0
  88. package/dist/db/known-table-names.js +7 -5
  89. package/dist/db/list-aggregate-labels.d.ts +1 -0
  90. package/dist/db/list-aggregate-labels.js +9 -1
  91. package/dist/db/migrate-generator.js +23 -4
  92. package/dist/db/migrate-rls-diff.d.ts +1 -0
  93. package/dist/db/migrate-rls-diff.js +15 -1
  94. package/dist/db/migrate-runner.js +2 -2
  95. package/dist/db/money.d.ts +1 -1
  96. package/dist/db/money.js +1 -4
  97. package/dist/db/parent-ref-clause.d.ts +6 -2
  98. package/dist/db/parent-ref-clause.js +76 -23
  99. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  100. package/dist/db/parent-ref-global-hosts.js +47 -0
  101. package/dist/db/production-schema-command-hint.d.ts +1 -0
  102. package/dist/db/production-schema-command-hint.js +3 -0
  103. package/dist/db/queries/backfill-pii.js +55 -29
  104. package/dist/db/queries/ddl.js +13 -2
  105. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  106. package/dist/db/queries/event-store-open-streams.js +33 -0
  107. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  108. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  109. package/dist/db/queries/event-store.js +0 -1
  110. package/dist/db/queries/raw-sql.js +0 -1
  111. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  112. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  113. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  114. package/dist/db/queries/rls-boot-catalog.js +13 -8
  115. package/dist/db/queries/rls-shape.d.ts +2 -1
  116. package/dist/db/queries/rls-shape.js +10 -0
  117. package/dist/db/queries/session-advisory-lock.js +2 -1
  118. package/dist/db/queries/test-stack.js +7 -7
  119. package/dist/db/query.js +16 -11
  120. package/dist/db/rebuild-marker.js +11 -2
  121. package/dist/db/render-rls-ddl.d.ts +2 -0
  122. package/dist/db/render-rls-ddl.js +16 -11
  123. package/dist/db/replay-migration-sql.js +1 -1
  124. package/dist/db/row-level-security-boot-check.js +18 -5
  125. package/dist/db/row-level-security-connection.js +25 -12
  126. package/dist/db/row-level-security-scope.d.ts +2 -1
  127. package/dist/db/row-level-security-scope.js +9 -5
  128. package/dist/db/sql-identifier.d.ts +1 -0
  129. package/dist/db/sql-identifier.js +3 -0
  130. package/dist/db/system-tenant-read-db.d.ts +5 -0
  131. package/dist/db/system-tenant-read-db.js +28 -0
  132. package/dist/db/table-builder.d.ts +3 -1
  133. package/dist/db/table-builder.js +18 -8
  134. package/dist/db/table-info.d.ts +1 -2
  135. package/dist/db/table-introspection.d.ts +3 -0
  136. package/dist/db/table-introspection.js +6 -0
  137. package/dist/db/table-push.d.ts +1 -0
  138. package/dist/db/table-push.js +7 -1
  139. package/dist/db/tenant-db-runner.d.ts +3 -0
  140. package/dist/db/tenant-db-runner.js +19 -1
  141. package/dist/db/transaction-serialization.d.ts +1 -0
  142. package/dist/db/transaction-serialization.js +20 -3
  143. package/dist/db/where-clause.js +11 -2
  144. package/dist/db/write-ownership-failures.d.ts +25 -0
  145. package/dist/db/write-ownership-failures.js +82 -0
  146. package/dist/engine/boot-validator/boot-check.js +7 -1
  147. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  148. package/dist/engine/boot-validator/boot-phases.js +3 -2
  149. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  150. package/dist/engine/boot-validator/boot-rules.js +4 -0
  151. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  152. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  153. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  154. package/dist/engine/boot-validator/config-deps.js +0 -28
  155. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  156. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  157. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  158. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  160. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  162. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  163. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  164. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  165. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  166. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  167. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  168. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  169. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  170. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  171. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  173. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  174. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  177. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  178. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  179. package/dist/engine/boot-validator/list-table-options.js +15 -1
  180. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  181. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  182. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  183. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  184. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  185. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  186. package/dist/engine/boot-validator/ownership.js +10 -1
  187. package/dist/engine/boot-validator/parent-ref.js +87 -50
  188. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  189. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  190. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  191. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  192. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  193. package/dist/engine/boot-validator/query-refs.js +24 -1
  194. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  195. package/dist/engine/boot-validator/row-decoration.js +16 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  197. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  199. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  200. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  202. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  203. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  209. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  211. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  212. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  213. package/dist/engine/boot-validator/screens-lists.js +19 -3
  214. package/dist/engine/boot-validator/screens.js +1 -1
  215. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  216. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  217. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  218. package/dist/engine/boot-validator/zod-shape.js +19 -1
  219. package/dist/engine/build-app-schema.js +4 -0
  220. package/dist/engine/config-helpers.d.ts +1 -2
  221. package/dist/engine/config-helpers.js +6 -7
  222. package/dist/engine/define-feature.js +1 -0
  223. package/dist/engine/define-handler.d.ts +1 -0
  224. package/dist/engine/define-handler.js +4 -2
  225. package/dist/engine/definition-violations.js +2 -2
  226. package/dist/engine/entity-handlers.js +3 -8
  227. package/dist/engine/entity-list-runtime-options.js +9 -8
  228. package/dist/engine/factories.d.ts +2 -0
  229. package/dist/engine/feature-config-events-jobs.js +1 -0
  230. package/dist/engine/feature-entity-handlers.js +5 -2
  231. package/dist/engine/field-access.d.ts +1 -1
  232. package/dist/engine/field-access.js +7 -10
  233. package/dist/engine/find-entity.js +3 -3
  234. package/dist/engine/form-derivations.js +3 -3
  235. package/dist/engine/index.d.ts +3 -3
  236. package/dist/engine/index.js +2 -2
  237. package/dist/engine/named-filter-roles.d.ts +3 -0
  238. package/dist/engine/named-filter-roles.js +23 -0
  239. package/dist/engine/pipeline.js +0 -1
  240. package/dist/engine/project-app-schema-for-roles.js +17 -2
  241. package/dist/engine/qualified-name.js +0 -1
  242. package/dist/engine/registry-facade.js +1 -2
  243. package/dist/engine/registry-state.d.ts +1 -1
  244. package/dist/engine/registry-state.js +5 -2
  245. package/dist/engine/registry-validate.d.ts +1 -0
  246. package/dist/engine/registry-validate.js +9 -1
  247. package/dist/engine/registry.js +2 -1
  248. package/dist/engine/resolve-named-list-filters.js +5 -2
  249. package/dist/engine/schema-builder.js +6 -10
  250. package/dist/engine/screen-helpers.d.ts +12 -0
  251. package/dist/engine/screen-helpers.js +17 -1
  252. package/dist/engine/soft-delete-cleanup.js +5 -8
  253. package/dist/engine/state-machine.js +0 -1
  254. package/dist/engine/steps/_database-clock.d.ts +2 -0
  255. package/dist/engine/steps/_database-clock.js +6 -0
  256. package/dist/engine/steps/compute.js +1 -1
  257. package/dist/engine/steps/retry.js +5 -1
  258. package/dist/engine/steps/return.js +0 -1
  259. package/dist/engine/steps/wait-for-event.js +2 -1
  260. package/dist/engine/steps/wait.js +2 -1
  261. package/dist/engine/system-user.d.ts +2 -2
  262. package/dist/engine/system-user.js +2 -2
  263. package/dist/engine/types/handlers.d.ts +1 -1
  264. package/dist/engine/types/handlers.js +1 -1
  265. package/dist/engine/types/screen.d.ts +1 -1
  266. package/dist/engine/types/screen.js +1 -1
  267. package/dist/engine/webhook-contracts.d.ts +2 -3
  268. package/dist/engine/webhook-contracts.js +2 -25
  269. package/dist/engine/webhook-events.js +48 -29
  270. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  271. package/dist/engine/webhook-payload-strictness.js +53 -0
  272. package/dist/env/_zod-introspect.d.ts +1 -0
  273. package/dist/env/dry-run.d.ts +1 -1
  274. package/dist/env/dry-run.js +1 -1
  275. package/dist/env/field-meta.d.ts +4 -0
  276. package/dist/env/field-meta.js +67 -0
  277. package/dist/env/field-rules.d.ts +9 -0
  278. package/dist/env/field-rules.js +46 -0
  279. package/dist/env/index.d.ts +3 -3
  280. package/dist/env/index.js +16 -71
  281. package/dist/env/internals.d.ts +3 -0
  282. package/dist/env/internals.js +1 -2
  283. package/dist/env/required-env.d.ts +3 -1
  284. package/dist/env/required-env.js +5 -2
  285. package/dist/errors/serialize.js +2 -2
  286. package/dist/errors/write-error-info.js +0 -2
  287. package/dist/es-ops/operations-schema.js +18 -7
  288. package/dist/event-store/admin-api.js +3 -3
  289. package/dist/event-store/event-store.js +0 -3
  290. package/dist/event-store/index.d.ts +1 -0
  291. package/dist/event-store/index.js +1 -0
  292. package/dist/event-store/transfer.js +1 -1
  293. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  294. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  295. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  296. package/dist/files/bind-pending-file-refs.js +54 -27
  297. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  298. package/dist/files/create-file-ref.d.ts +4 -1
  299. package/dist/files/create-file-ref.js +14 -3
  300. package/dist/files/default-file-guard.js +4 -1
  301. package/dist/files/feature.js +1 -0
  302. package/dist/files/file-claim.d.ts +6 -0
  303. package/dist/files/file-claim.js +17 -0
  304. package/dist/files/file-field-slots.d.ts +2 -0
  305. package/dist/files/file-field-slots.js +28 -0
  306. package/dist/files/file-ref-entity.d.ts +3 -0
  307. package/dist/files/file-ref-entity.js +2 -0
  308. package/dist/files/file-ref-table.d.ts +3 -0
  309. package/dist/files/file-routes.d.ts +4 -1
  310. package/dist/files/file-routes.js +80 -16
  311. package/dist/files/in-memory-provider.d.ts +1 -1
  312. package/dist/files/in-memory-provider.js +2 -1
  313. package/dist/files/index.d.ts +1 -1
  314. package/dist/files/index.js +1 -1
  315. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  316. package/dist/files/invalid-file-ref-error.js +15 -0
  317. package/dist/files/local-provider.js +9 -2
  318. package/dist/files/provider-resolver.js +1 -1
  319. package/dist/files/rebind-file-ref.d.ts +3 -2
  320. package/dist/files/rebind-file-ref.js +24 -18
  321. package/dist/files/resolve-file-handles.d.ts +13 -0
  322. package/dist/files/resolve-file-handles.js +57 -0
  323. package/dist/files/storage-tracking.d.ts +1 -1
  324. package/dist/files/storage-tracking.js +5 -2
  325. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  326. package/dist/files/types.d.ts +4 -0
  327. package/dist/files/types.js +10 -0
  328. package/dist/files/upload-field-resolution.d.ts +1 -0
  329. package/dist/files/upload-field-resolution.js +16 -2
  330. package/dist/files/upload-ledger.js +1 -1
  331. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  332. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  333. package/dist/i18n/required-surface-keys.js +19 -4
  334. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  335. package/dist/internal/boot-rule-table-expectations.js +29 -0
  336. package/dist/internal/row-level-security.d.ts +1 -0
  337. package/dist/internal/row-level-security.js +1 -0
  338. package/dist/internal/testing.d.ts +1 -0
  339. package/dist/internal/testing.js +1 -0
  340. package/dist/jobs/index.d.ts +1 -0
  341. package/dist/jobs/index.js +1 -0
  342. package/dist/jobs/job-load-events.d.ts +10 -0
  343. package/dist/jobs/job-load-events.js +12 -0
  344. package/dist/jobs/job-runner-context.js +6 -158
  345. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  346. package/dist/jobs/job-runner-dispatch.js +57 -0
  347. package/dist/jobs/job-runner-event-triggers.js +18 -9
  348. package/dist/jobs/job-runner-execution.js +2 -2
  349. package/dist/jobs/job-runner-facets.d.ts +48 -0
  350. package/dist/jobs/job-runner-facets.js +156 -0
  351. package/dist/jobs/job-runner-gates.js +24 -12
  352. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  353. package/dist/jobs/job-runner-helpers.js +18 -3
  354. package/dist/jobs/job-runner-scope.d.ts +1 -0
  355. package/dist/jobs/job-runner-scope.js +2 -0
  356. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  357. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  358. package/dist/jobs/job-runner.js +31 -70
  359. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  360. package/dist/jobs/obliterate-job-queues.js +23 -0
  361. package/dist/lifecycle/lifecycle.js +1 -1
  362. package/dist/migrations/event-header-scrub.d.ts +11 -0
  363. package/dist/migrations/event-header-scrub.js +33 -0
  364. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  365. package/dist/migrations/event-payload-scrub.js +36 -4
  366. package/dist/migrations/index.d.ts +1 -0
  367. package/dist/migrations/index.js +2 -0
  368. package/dist/migrations/kumiko-drift.d.ts +5 -2
  369. package/dist/migrations/kumiko-drift.js +51 -14
  370. package/dist/migrations/pending-rebuilds.js +4 -5
  371. package/dist/observability/sensitive-filter.js +0 -12
  372. package/dist/pipeline/aggregate-type-removal.js +17 -4
  373. package/dist/pipeline/context-services.d.ts +2 -0
  374. package/dist/pipeline/context-services.js +5 -2
  375. package/dist/pipeline/dispatch-batch.js +4 -3
  376. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  377. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  378. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  379. package/dist/pipeline/dispatch-nested-write.js +119 -0
  380. package/dist/pipeline/dispatch-query.js +10 -3
  381. package/dist/pipeline/dispatch-scope.js +4 -3
  382. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  383. package/dist/pipeline/dispatch-shared.js +6 -38
  384. package/dist/pipeline/dispatch-write.d.ts +0 -1
  385. package/dist/pipeline/dispatch-write.js +3 -302
  386. package/dist/pipeline/dispatcher-utils.js +6 -0
  387. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  388. package/dist/pipeline/effective-system-scope.js +22 -0
  389. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  390. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  391. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  392. package/dist/pipeline/event-dispatcher.js +6 -7
  393. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  394. package/dist/pipeline/handler-context-auth.js +3 -4
  395. package/dist/pipeline/handler-context-db.js +11 -4
  396. package/dist/pipeline/handler-context-dispatch.js +2 -2
  397. package/dist/pipeline/handler-context-events.d.ts +8 -3
  398. package/dist/pipeline/handler-context-events.js +20 -65
  399. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  400. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  401. package/dist/pipeline/handler-context-notify.js +2 -0
  402. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  403. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  404. package/dist/pipeline/handler-context-projection.js +39 -0
  405. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  406. package/dist/pipeline/handler-context-scope.js +14 -2
  407. package/dist/pipeline/index.d.ts +1 -1
  408. package/dist/pipeline/index.js +1 -1
  409. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  410. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  411. package/dist/pipeline/member-reader.js +4 -2
  412. package/dist/pipeline/msp-rebuild.js +1 -1
  413. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  414. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  415. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  416. package/dist/pipeline/projection-rebuild.js +16 -7
  417. package/dist/pipeline/projection-state.js +4 -6
  418. package/dist/pipeline/system-hooks.js +36 -6
  419. package/dist/pipeline/write-result-masking.js +31 -3
  420. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  421. package/dist/pipeline/write-transition-guard.js +95 -0
  422. package/dist/schema-cli/shared.d.ts +2 -0
  423. package/dist/schema-cli/shared.js +4 -2
  424. package/dist/schema-cli/validate-command.js +43 -28
  425. package/dist/search/meilisearch-adapter.js +14 -9
  426. package/dist/search/reindex-entity.d.ts +2 -0
  427. package/dist/search/reindex-entity.js +32 -4
  428. package/dist/search/reindex-tenants-search.js +20 -4
  429. package/dist/time/tz-context.js +1 -1
  430. package/dist/ui-types/card-column-roles.d.ts +4 -0
  431. package/dist/ui-types/card-column-roles.js +6 -3
  432. package/dist/ui-types/index.d.ts +2 -2
  433. package/dist/ui-types/index.js +1 -1
  434. package/dist/utils/ids.js +0 -1
  435. package/dist/utils/index.d.ts +1 -0
  436. package/dist/utils/index.js +1 -0
  437. package/dist/utils/return-path-limit.d.ts +1 -0
  438. package/dist/utils/return-path-limit.js +1 -0
  439. package/package.json +5 -3
  440. package/presets/biome-app.json +39 -21
  441. package/presets/biome-plugins/admin-api.grit +10 -0
  442. package/presets/biome-plugins/error-reasons.grit +53 -0
  443. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  444. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  445. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  446. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  447. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  448. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  449. package/presets/biome-plugins/no-date-api.grit +9 -0
  450. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  451. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  452. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  453. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  454. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  455. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  456. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  457. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  458. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  459. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  460. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  461. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  462. package/presets/biome-plugins/test-title.grit +20 -0
  463. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  464. package/presets/biome-rules.json +465 -0
  465. package/src/changes.json +309 -0
  466. package/dist/engine/minor-units.d.ts +0 -2
  467. package/dist/engine/minor-units.js +0 -8
@@ -2,12 +2,14 @@ import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
2
2
  import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
3
3
  import { Hono } from "hono";
4
4
  import { bodyLimit } from "hono/body-limit";
5
- import { getUser } from "../api/auth-middleware.js";
5
+ import { getStaleCredentialCode, getUser } from "../api/auth-middleware.js";
6
+ import { clientIpSourceFromHonoContext } from "../api/client-ip.js";
6
7
  import { requestContext } from "../api/request-context.js";
7
8
  import { ROLES } from "../auth/roles.js";
8
9
  import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/index.js";
9
10
  import { selectMany } from "../db/query.js";
10
11
  import { runInRowLevelSecurityScope, tenantRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
12
+ import { systemTenantReadDb } from "../db/system-tenant-read-db.js";
11
13
  import { createProjectingTenantDb } from "../db/tenant-db.js";
12
14
  import { createDerivativesContext, resolveRenderer } from "../derivatives/derivatives-context.js";
13
15
  import { resolveFieldVariant } from "../derivatives/index.js";
@@ -27,7 +29,7 @@ import { collectRecordOnlyFileEntityTypes } from "./record-only-file-entity-type
27
29
  import { isStoredRecordLocked, RecordWriteDecisions, } from "./record-write-check.js";
28
30
  import { neutralFileNameForMimeType } from "./resolve-content-type.js";
29
31
  import { parseMaxSize, resolveServedContentType } from "./types.js";
30
- import { isAnonymousPendingUploadAllowed, registryHasAnonymousUploadField, } from "./upload-field-resolution.js";
32
+ import { isAnonymousPendingUploadAllowed, registryHasAnonymousUploadField, resolveMaxAnonymousUploadBytes, } from "./upload-field-resolution.js";
31
33
  import { withUploadLedger } from "./upload-ledger.js";
32
34
  // Exactly the httpStatus values declared by KumikoError subclasses across packages/*.
33
35
  const ERROR_STATUSES = [400, 401, 403, 404, 409, 422, 429, 500, 503, 504];
@@ -35,9 +37,12 @@ export function deleteFailureResponseFor(error) {
35
37
  const status = isOneOf(ERROR_STATUSES, error.httpStatus) ? error.httpStatus : 500;
36
38
  return { status, code: status === 404 ? "not_found" : error.code };
37
39
  }
38
- // 401 (not 403) lets the client tell a revoked or expired session from a missing permission.
40
+ // 401 (not 403) lets the client tell a missing sign-in from a missing permission. Only a visitor
41
+ // whose stale session cookie was downgraded gets the session-ended code; a visitor who never
42
+ // signed in must not be sent to the "session ended" banner.
39
43
  function unauthenticatedUploadResponse(c) {
40
- return c.json({ error: "unauthenticated: sign in to upload files", code: "unauthenticated" }, 401);
44
+ const code = getStaleCredentialCode(c) === undefined ? "sign_in_required" : "unauthenticated";
45
+ return c.json({ error: "unauthenticated: sign in to upload files", code }, 401);
41
46
  }
42
47
  // 15 minutes — long enough for a download to start, short enough that a
43
48
  // leaked URL (e.g. from a browser history screenshot) isn't a long-lived
@@ -46,6 +51,8 @@ const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
46
51
  const MAX_BATCH_META_IDS = 100;
47
52
  const META_BATCH_IDS_PER_WINDOW = 1_000;
48
53
  const META_BATCH_WINDOW_SECONDS = 60;
54
+ export const ANONYMOUS_UPLOADS_PER_WINDOW = 20;
55
+ const ANONYMOUS_UPLOAD_WINDOW_SECONDS = 60;
49
56
  // Each detail() read decrypts through the KMS pool; a bounded chunk keeps one batch from hogging it.
50
57
  const BATCH_META_CONCURRENCY = 10;
51
58
  // Multipart framing plus the small entityType/entityId/fieldName parts
@@ -97,15 +104,19 @@ function canReadSystemTenantFile(user, fileTenantId) {
97
104
  return fileTenantId === SYSTEM_TENANT_ID && user.roles.includes(ROLES.SystemAdmin);
98
105
  }
99
106
  export function createFileRoutes(options) {
100
- const { db, metaBatchRateLimitResolver } = options;
107
+ const { db, rateLimitResolver, clientIpResolver } = options;
101
108
  const reportMetaBatchLimiterFailOpen = createFailOpenReporter("files-meta-batch");
109
+ const reportAnonymousUploadLimiterFailOpen = createFailOpenReporter("files-upload-anon");
102
110
  // Plain resolvers (not built via withFileProviderResolver) get the ledger on the route's own root connection.
103
111
  const resolveProvider = options.resolveProvider.uploadLedgerFor
104
112
  ? options.resolveProvider
105
113
  : withUploadLedger(options.resolveProvider, db);
106
114
  const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
107
- const guard = options.accessGuard ??
115
+ const configuredGuard = options.accessGuard ??
108
116
  createDefaultGuard(privilegedRoles, options.canReadRecord, options.unclaimedUploadReaders ?? [], options.registry ? collectRecordOnlyFileEntityTypes(options.registry) : new Set());
117
+ // Anonymous visitors share one user id and own no file by it; the check precedes an app's
118
+ // accessGuard so a custom guard cannot reopen reads or deletes between visitors.
119
+ const guard = (args) => isAnonymousSessionUser(args.user) ? "deny" : configuredGuard(args);
109
120
  const executor = getFileRefExecutor();
110
121
  const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
111
122
  const api = new Hono();
@@ -154,12 +165,46 @@ export function createFileRoutes(options) {
154
165
  }
155
166
  // Runs before parseBody buffers the request below: checks Content-Length
156
167
  // upfront, counts chunked bodies while streaming.
168
+ const requestTooLarge = (c) => c.json({ error: "request_too_large: request body exceeds the maximum allowed upload size" }, 413);
157
169
  const uploadBodyLimit = bodyLimit({
158
170
  maxSize: resolveMaxUploadBodyBytes(options),
159
- onError: (c) => c.json({ error: "request_too_large: request body exceeds the maximum allowed upload size" }, 413),
171
+ onError: requestTooLarge,
160
172
  });
173
+ // Anonymous callers are capped by the opted-in fields alone, not by the largest field of the app.
174
+ const anonymousUploadBodyLimit = bodyLimit({
175
+ maxSize: resolveMaxAnonymousUploadBytes(options.registry, options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE) + MULTIPART_OVERHEAD_MARGIN_BYTES,
176
+ onError: requestTooLarge,
177
+ });
178
+ // Without an opted-in field the handler answers 401 before reading any body, so an anonymous
179
+ // caller must get that 401 and not the 413 of a cap that only exists for opted-in uploads.
180
+ const anonymousUploadAllowed = registryHasAnonymousUploadField(options.registry);
181
+ const bodyLimitForCaller = (c, next) => {
182
+ if (!isAnonymousSessionUser(getUser(c)))
183
+ return uploadBodyLimit(c, next);
184
+ return anonymousUploadAllowed ? anonymousUploadBodyLimit(c, next) : next();
185
+ };
186
+ async function chargeAnonymousUpload(c) {
187
+ if (!rateLimitResolver || !clientIpResolver)
188
+ return undefined;
189
+ const ip = clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
190
+ if (!ip)
191
+ return undefined;
192
+ const bucket = `files-upload-anon:${ip}`;
193
+ try {
194
+ const decision = await rateLimitResolver.check(bucket, {
195
+ limit: ANONYMOUS_UPLOADS_PER_WINDOW,
196
+ windowSeconds: ANONYMOUS_UPLOAD_WINDOW_SECONDS,
197
+ });
198
+ if (!decision.allowed)
199
+ return respondRateLimited(c, decision, bucket);
200
+ }
201
+ catch (e) {
202
+ reportAnonymousUploadLimiterFailOpen(e);
203
+ }
204
+ return undefined;
205
+ }
161
206
  // POST /files — multipart upload.
162
- api.post("/files", uploadBodyLimit, async (c) => {
207
+ api.post("/files", bodyLimitForCaller, async (c) => {
163
208
  const user = getUser(c);
164
209
  const isAnonymous = isAnonymousSessionUser(user);
165
210
  // 401 (not 403) lets the client tell an ended session apart. Without any opted-in field
@@ -167,6 +212,11 @@ export function createFileRoutes(options) {
167
212
  if (isAnonymous && !registryHasAnonymousUploadField(options.registry)) {
168
213
  return unauthenticatedUploadResponse(c);
169
214
  }
215
+ if (isAnonymous) {
216
+ const limited = await chargeAnonymousUpload(c);
217
+ if (limited)
218
+ return limited;
219
+ }
170
220
  const body = await c.req.parseBody();
171
221
  const file = body["file"];
172
222
  const entityType = typeof body["entityType"] === "string" ? body["entityType"] : undefined;
@@ -190,7 +240,9 @@ export function createFileRoutes(options) {
190
240
  }
191
241
  // Ahead of the record check below, which would answer 404/403 for the entity half.
192
242
  if (actionForm !== undefined && (entityType !== undefined || entityId !== undefined)) {
193
- return c.json({ error: "invalid_action_form: actionForm cannot be combined with entityType or entityId" }, 400);
243
+ return c.json({
244
+ error: "invalid_action_form: actionForm cannot be combined with entityType or entityId",
245
+ }, 400);
194
246
  }
195
247
  // Before any bytes are written, like the record check below. An unresolvable screen falls
196
248
  // through to storeFileAsFileRef, which answers 400; a known one must be submittable by the
@@ -221,6 +273,10 @@ export function createFileRoutes(options) {
221
273
  return c.json({ error: "forbidden: no write access to this record" }, 403);
222
274
  case RecordWriteDecisions.locked:
223
275
  return c.json({ error: "record_locked: the record is locked" }, 409);
276
+ default: {
277
+ const exhaustiveCheck = decision;
278
+ return exhaustiveCheck;
279
+ }
224
280
  }
225
281
  }
226
282
  const data = new Uint8Array(await file.arrayBuffer());
@@ -258,7 +314,9 @@ export function createFileRoutes(options) {
258
314
  }
259
315
  if (outcome.kind === "failed")
260
316
  return c.json({ error: "upload_failed" }, 500);
261
- return c.json(outcome.fileRef, 201);
317
+ return c.json(outcome.handle === undefined
318
+ ? outcome.fileRef
319
+ : { ...outcome.fileRef, handle: outcome.handle }, 201);
262
320
  });
263
321
  // GET /files/meta?ids=a,b,c — meta of many files in one request (list/card
264
322
  // cells otherwise fire one request per row). Unreadable and unknown ids are
@@ -266,13 +324,15 @@ export function createFileRoutes(options) {
266
324
  // Registered before /files/:id so "meta" is never taken for an id.
267
325
  api.get("/files/meta", async (c) => {
268
326
  const user = getUser(c);
327
+ if (isAnonymousSessionUser(user))
328
+ return c.json({ error: "not_found" }, 404);
269
329
  const ids = [...new Set((c.req.query("ids") ?? "").split(",").filter((id) => isUuid(id)))];
270
330
  if (ids.length > MAX_BATCH_META_IDS)
271
331
  return c.json({ error: "too_many_ids" }, 400);
272
- if (metaBatchRateLimitResolver && ids.length > 0) {
332
+ if (rateLimitResolver && ids.length > 0) {
273
333
  const bucket = `files-meta:${user.tenantId}:${user.id}`;
274
334
  try {
275
- const decision = await metaBatchRateLimitResolver.check(bucket, {
335
+ const decision = await rateLimitResolver.check(bucket, {
276
336
  limit: META_BATCH_IDS_PER_WINDOW,
277
337
  windowSeconds: META_BATCH_WINDOW_SECONDS,
278
338
  cost: ids.length,
@@ -472,7 +532,11 @@ export function createFileRoutes(options) {
472
532
  // id shape before it hits the UUID column.
473
533
  if (!isUuid(id))
474
534
  return null;
475
- const row = await executor.detail({ id }, user, tenantDbFor(user.tenantId));
535
+ // file_refs has no system read policy: the system tenant's rows are read in the system tenant's own scope.
536
+ const row = (await executor.detail({ id }, user, tenantDbFor(user.tenantId))) ??
537
+ (canReadSystemTenantFile(user, SYSTEM_TENANT_ID)
538
+ ? await executor.detail({ id }, user, tenantDbFor(SYSTEM_TENANT_ID))
539
+ : null);
476
540
  if (!row)
477
541
  return null;
478
542
  const fileRef = row; // @cast-boundary db-row (decrypted via executor.detail)
@@ -506,9 +570,9 @@ export function createFileRoutes(options) {
506
570
  const own = await loadFileForTenant(id, user.tenantId);
507
571
  if (own || !canReadSystemTenantFile(user, SYSTEM_TENANT_ID))
508
572
  return own;
509
- return loadFileForTenant(id, SYSTEM_TENANT_ID);
573
+ return loadFileForTenant(id, SYSTEM_TENANT_ID, systemTenantReadDb(db));
510
574
  }
511
- async function loadFileForTenant(id, tenantId) {
575
+ async function loadFileForTenant(id, tenantId, readDb = db) {
512
576
  // fileRefsTable.id is a UUID column — a malformed id must fail here, not
513
577
  // at Postgres (22P02 poisons the pooled connection). 404, not
514
578
  // 400: an authenticated caller sending a bad id must see the same
@@ -517,7 +581,7 @@ export function createFileRoutes(options) {
517
581
  return null;
518
582
  // isDeleted:false — soft-deleted (trashed) rows stay recoverable but must
519
583
  // never surface to reads/guards.
520
- const [row] = await selectMany(db, fileRefsTable, { id, tenantId, isDeleted: false });
584
+ const [row] = await selectMany(readDb, fileRefsTable, { id, tenantId, isDeleted: false });
521
585
  return row ?? null; // @cast-boundary db-row
522
586
  }
523
587
  return api;
@@ -1,4 +1,4 @@
1
- import type { FileStorageProvider } from "./types.ts";
1
+ import { type FileStorageProvider } from "./types.ts";
2
2
  export type InMemoryFileProvider = FileStorageProvider & {
3
3
  keys(): readonly string[];
4
4
  mimeTypeOf(key: string): string | undefined;
@@ -3,6 +3,7 @@
3
3
  //
4
4
  // Factored out of test-files so any package can opt in (samples, downstream
5
5
  // feature tests) without re-inventing a Map-backed mock.
6
+ import { FileObjectMissingError } from "./types.js";
6
7
  export function createInMemoryFileProvider() {
7
8
  const store = new Map();
8
9
  return {
@@ -31,7 +32,7 @@ export function createInMemoryFileProvider() {
31
32
  async read(key) {
32
33
  const entry = store.get(key);
33
34
  if (!entry)
34
- throw new Error(`in-memory file not found: ${key}`);
35
+ throw new FileObjectMissingError(key, `in-memory file not found: ${key}`);
35
36
  return new Uint8Array(entry.data);
36
37
  },
37
38
  readStream(key) {
@@ -26,7 +26,7 @@ export type { FileRefOwner, RebindFileRefContext, RebindFileRefOutcome, } from "
26
26
  export { rebindFileRef } from "./rebind-file-ref.ts";
27
27
  export { filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.ts";
28
28
  export type { FileStorageProvider, SignedUrlOptions, } from "./types.ts";
29
- export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.ts";
29
+ export { assertSafeStorageKey, buildStorageKey, FileObjectMissingError, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.ts";
30
30
  export { fileUploadLedgerTable, withUploadLedger, } from "./upload-ledger.ts";
31
31
  export type { ZipEntry } from "./zip-stream.ts";
32
32
  export { createZipStream } from "./zip-stream.ts";
@@ -18,6 +18,6 @@ export { createLocalProvider } from "./local-provider.js";
18
18
  export { createFileProviderForTenant, isFileProviderPlugin, } from "./provider-resolver.js";
19
19
  export { rebindFileRef } from "./rebind-file-ref.js";
20
20
  export { filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
21
- export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.js";
21
+ export { assertSafeStorageKey, buildStorageKey, FileObjectMissingError, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.js";
22
22
  export { fileUploadLedgerTable, withUploadLedger, } from "./upload-ledger.js";
23
23
  export { createZipStream } from "./zip-stream.js";
@@ -0,0 +1,2 @@
1
+ import { ValidationError } from "../errors/index.ts";
2
+ export declare function invalidFileRefError(fieldName: string): ValidationError;
@@ -0,0 +1,15 @@
1
+ import { ValidationError } from "../errors/index.js";
2
+ // One error for every way a file field can name a ref the writer may not use (missing, foreign
3
+ // tenant, another record's file, someone else's pending upload, wrong claim), so the cause
4
+ // cannot be probed.
5
+ export function invalidFileRefError(fieldName) {
6
+ return new ValidationError({
7
+ fields: [
8
+ {
9
+ path: fieldName,
10
+ code: "invalid_element",
11
+ i18nKey: "errors.validation.invalid_element",
12
+ },
13
+ ],
14
+ });
15
+ }
@@ -3,7 +3,7 @@ import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "n
3
3
  import { dirname, join, relative, resolve, sep } from "node:path";
4
4
  import { pipeline } from "node:stream/promises";
5
5
  import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
6
- import { assertSafeStorageKey } from "./types.js";
6
+ import { assertSafeStorageKey, FileObjectMissingError } from "./types.js";
7
7
  // Local-filesystem backend — intended for dev + tests. Production deploys
8
8
  // pick an object-store provider (S3/R2/…). mimeType is ignored here; the
9
9
  // filesystem tracks no metadata beyond what the caller stores on FileRef.
@@ -55,7 +55,14 @@ export function createLocalProvider(basePath) {
55
55
  },
56
56
  async read(key) {
57
57
  const filePath = resolveContainedPath(key);
58
- return readFile(filePath);
58
+ try {
59
+ return await readFile(filePath);
60
+ }
61
+ catch (e) {
62
+ if (errorCodeOf(e) === "ENOENT")
63
+ throw new FileObjectMissingError(key);
64
+ throw e;
65
+ }
59
66
  },
60
67
  readStream(key) {
61
68
  // node:fs createReadStream is an AsyncIterable<Buffer>; Buffer extends Uint8Array. This
@@ -98,7 +98,7 @@ export function makeFileProviderResolver(deps) {
98
98
  deps.cacheSync?.onResync(() => cache.clear());
99
99
  const resolveProvider = (tenantId) => {
100
100
  const cached = cache.get(tenantId);
101
- if (cached)
101
+ if (cached !== undefined)
102
102
  return cached;
103
103
  const built = (async () => {
104
104
  if (!deps.registry || !deps.configAccessorFactory || !deps.db) {
@@ -18,12 +18,13 @@ export type RebindFileRefOutcome = "rebound" | "not-found" | "moved" | "version-
18
18
  * file uploaded elsewhere (an upload record, a mail attachment). Server code only; pending uploads
19
19
  * go through bindPendingFileRef.
20
20
  *
21
- * Only files of the caller's tenant are found ("not-found" otherwise, as for unknown ids). The
21
+ * Only files of the caller's tenant that the caller may read are found ("not-found" otherwise,
22
+ * as for unknown ids; the system user reads every file of its tenant). The
22
23
  * file must still sit at `from`; "moved" means it does not (any more), for example because a
23
24
  * parallel rebind took it first. A file already at `to` answers "rebound" without a write. The
24
25
  * target must be a registered file field whose accept/maxSize the file fits (InternalError /
25
26
  * UnprocessableError). Unless the caller is the framework system user, the caller must be able
26
- * to read the file and to write both the source record and field (it must not be locked, and an
27
+ * to write both the source record and field (it must not be locked, and an
27
28
  * entity without update handler leaves the move to the system user) and the target record and
28
29
  * field (AccessDeniedError, RecordLockedError); the system user skips these checks, and only the
29
30
  * target record has to exist (NotFoundError). The update is checked against the file's stream
@@ -52,6 +52,15 @@ async function loadRow(ctx, fileRefId) {
52
52
  version,
53
53
  };
54
54
  }
55
+ function callerCheckContextOf(ctx) {
56
+ const { dispatch } = ctx;
57
+ if (dispatch === undefined) {
58
+ throw new InternalError({
59
+ message: "rebindFileRef: a caller other than the system user needs ctx.dispatch.query",
60
+ });
61
+ }
62
+ return { ...ctx, dispatch };
63
+ }
55
64
  function isOwnedBy(fileRef, owner) {
56
65
  return (fileRef.entityType === owner.entityType &&
57
66
  fileRef.entityId === owner.entityId &&
@@ -67,14 +76,10 @@ async function lockSourceRow(ctx, from) {
67
76
  return;
68
77
  await selectRowForUpdateById(tenantDbRunner(ctx.db), tableName, from.entityId);
69
78
  }
70
- // A caller other than the system job must be able to read the file today and must be able to
71
- // write both records as a save of them would: the source it takes the file from (unlocked, and
72
- // with an update handler the caller passes; without one only the system job may move the file),
73
- // and the target field it puts the file into.
74
- async function assertCallerMayMove(ctx, fileRef, from, to) {
75
- if (!(await canCallerReadFileRef(ctx, fileRef))) {
76
- throw new AccessDeniedError({ message: `rebindFileRef: file ${fileRef.id} is not readable` });
77
- }
79
+ // A caller other than the system job must be able to write both records as a save of them would:
80
+ // the source it takes the file from (unlocked, and with an update handler the caller passes;
81
+ // without one only the system job may move the file), and the target field it puts the file into.
82
+ async function assertCallerMayMove(ctx, from, to) {
78
83
  const canWriteRecord = createRecordWriteCheck({
79
84
  registry: ctx.registry,
80
85
  canReadRecord: createRecordReadCheck(ctx.registry, (qn, payload) => ctx.dispatch.query(qn, payload)),
@@ -118,12 +123,13 @@ async function assertTargetRecordExists(ctx, to) {
118
123
  * file uploaded elsewhere (an upload record, a mail attachment). Server code only; pending uploads
119
124
  * go through bindPendingFileRef.
120
125
  *
121
- * Only files of the caller's tenant are found ("not-found" otherwise, as for unknown ids). The
126
+ * Only files of the caller's tenant that the caller may read are found ("not-found" otherwise,
127
+ * as for unknown ids; the system user reads every file of its tenant). The
122
128
  * file must still sit at `from`; "moved" means it does not (any more), for example because a
123
129
  * parallel rebind took it first. A file already at `to` answers "rebound" without a write. The
124
130
  * target must be a registered file field whose accept/maxSize the file fits (InternalError /
125
131
  * UnprocessableError). Unless the caller is the framework system user, the caller must be able
126
- * to read the file and to write both the source record and field (it must not be locked, and an
132
+ * to write both the source record and field (it must not be locked, and an
127
133
  * entity without update handler leaves the move to the system user) and the target record and
128
134
  * field (AccessDeniedError, RecordLockedError); the system user skips these checks, and only the
129
135
  * target record has to exist (NotFoundError). The update is checked against the file's stream
@@ -140,22 +146,22 @@ export async function rebindFileRef(ctx, args) {
140
146
  if (loaded === undefined)
141
147
  return "not-found";
142
148
  const { fileRef, version } = loaded;
149
+ const callerCheck = isFrameworkSystemUser(ctx.user) ? undefined : callerCheckContextOf(ctx);
150
+ // Before the ownership short-circuits: "moved" and "rebound" would tell a caller who may not
151
+ // read the file that it exists and where it sits.
152
+ if (callerCheck !== undefined && !(await canCallerReadFileRef(callerCheck, fileRef))) {
153
+ return "not-found";
154
+ }
143
155
  if (isOwnedBy(fileRef, to))
144
156
  return "rebound";
145
157
  if (!isOwnedBy(fileRef, from))
146
158
  return "moved";
147
159
  assertRowFitsBindTarget(ctx.registry, { entityName: to.entityType, fieldName: to.fieldName }, fileRef);
148
- if (isFrameworkSystemUser(ctx.user)) {
160
+ if (callerCheck === undefined) {
149
161
  await assertTargetRecordExists(ctx, to);
150
162
  }
151
163
  else {
152
- const { dispatch } = ctx;
153
- if (dispatch === undefined) {
154
- throw new InternalError({
155
- message: "rebindFileRef: a caller other than the system user needs ctx.dispatch.query",
156
- });
157
- }
158
- await assertCallerMayMove({ ...ctx, dispatch }, fileRef, from, to);
164
+ await assertCallerMayMove(callerCheck, from, to);
159
165
  }
160
166
  const moved = await getFileRefExecutor().update({
161
167
  id: fileRefId,
@@ -0,0 +1,13 @@
1
+ import type { FieldDefinition } from "@cosmicdrift/kumiko-types/fields";
2
+ import type { TenantDb } from "../db/tenant-db.ts";
3
+ import type { SessionUser } from "../engine/types/index.ts";
4
+ import { type WriteFailure } from "../errors/index.ts";
5
+ export type ResolvedFileHandles = {
6
+ readonly values: Readonly<Record<string, unknown>>;
7
+ readonly claimedFileRefIds: readonly string[];
8
+ } | {
9
+ readonly failure: WriteFailure;
10
+ };
11
+ export declare function resolveFileHandles({ fields }: {
12
+ readonly fields: Readonly<Record<string, FieldDefinition>>;
13
+ }, entityName: string, values: Readonly<Record<string, unknown>>, db: TenantDb, user: Pick<SessionUser, "tenantId">): Promise<ResolvedFileHandles>;
@@ -0,0 +1,57 @@
1
+ import { parseFileHandle } from "@cosmicdrift/kumiko-types/identifiers";
2
+ import { writeFailure } from "../errors/index.js";
3
+ import { fileClaimMatches } from "./file-claim.js";
4
+ import { holdsFileRefs, mapFileRefSlots } from "./file-field-slots.js";
5
+ import { invalidFileRefError } from "./invalid-file-ref-error.js";
6
+ function handlesNamedBy(fields, values) {
7
+ const found = [];
8
+ for (const [fieldName, fieldDef] of Object.entries(fields)) {
9
+ if (!holdsFileRefs(fieldDef) || !(fieldName in values))
10
+ continue;
11
+ mapFileRefSlots(fieldDef, values[fieldName], (entry) => {
12
+ const handle = parseFileHandle(entry);
13
+ if (handle !== null)
14
+ found.push({ fieldName, ...handle });
15
+ return entry;
16
+ });
17
+ }
18
+ return found;
19
+ }
20
+ // Swaps every file handle a write names for the bare fileRef id after checking its claim, so
21
+ // neither the claim nor the handle reaches a hook, the event or the table. A handle only proves
22
+ // ownership of a pending upload; a pending row with a wrong claim, a missing row or one of
23
+ // another tenant, or an upload made for another field fails like an unknown id. A bound row passes through as its bare id.
24
+ export async function resolveFileHandles({ fields }, entityName, values, db, user) {
25
+ const handles = handlesNamedBy(fields, values);
26
+ // skip: without handles there is nothing to resolve and no row to read
27
+ if (handles.length === 0)
28
+ return { values, claimedFileRefIds: [] };
29
+ // Loaded on demand: file_refs is built from an entity definition that needs the engine, which
30
+ // imports the executor this module is part of.
31
+ const { loadFileRefRows } = await import("./load-save-file-refs.js");
32
+ const rows = await loadFileRefRows(db, [...new Set(handles.map((h) => h.id))], user.tenantId);
33
+ const claimedFileRefIds = new Set();
34
+ for (const handle of handles) {
35
+ const row = rows.get(handle.id);
36
+ if (row === undefined)
37
+ return { failure: writeFailure(invalidFileRefError(handle.fieldName)) };
38
+ // A bound row needs no claim: the handle is just resubmitted next to its record, and
39
+ // assertFileRefsBelongToTenant judges it like a bare id (same record passes, another fails).
40
+ if (row["entityId"] !== null && row["entityId"] !== undefined)
41
+ continue;
42
+ // The claim is bound to the field the upload came in through: a handle issued for one field
43
+ // must not carry the file into another entity or field.
44
+ const isIssuedForThisField = row["entityType"] === entityName && row["fieldName"] === handle.fieldName;
45
+ if (!isIssuedForThisField || !fileClaimMatches(row["claimHash"], handle.claim)) {
46
+ return { failure: writeFailure(invalidFileRefError(handle.fieldName)) };
47
+ }
48
+ claimedFileRefIds.add(handle.id);
49
+ }
50
+ const resolved = { ...values };
51
+ for (const [fieldName, fieldDef] of Object.entries(fields)) {
52
+ if (!holdsFileRefs(fieldDef) || !(fieldName in values))
53
+ continue;
54
+ resolved[fieldName] = mapFileRefSlots(fieldDef, values[fieldName], (entry) => parseFileHandle(entry)?.id ?? entry);
55
+ }
56
+ return { values: resolved, claimedFileRefIds: [...claimedFileRefIds] };
57
+ }
@@ -7,7 +7,7 @@ export declare function fileRefStorageDelta(event: {
7
7
  readonly bytes: number;
8
8
  readonly files: number;
9
9
  } | null;
10
- export declare const tenantStorageUsageTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
10
+ export declare const tenantStorageUsageTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
11
11
  export declare const filesStorageTrackingFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
12
12
  readonly exports: void;
13
13
  };
@@ -15,6 +15,7 @@ import { entityEventName } from "../db/index.js";
15
15
  import { toPostgresArrayLiteral } from "../db/queries/postgres-array-literal.js";
16
16
  import { executeRawQueryRead } from "../db/queries/raw-sql.js";
17
17
  import { incrementCounter } from "../db/query.js";
18
+ import { withExecutorManagedWrites } from "../db/tenant-db.js";
18
19
  import { defineFeature, qn, toKebab } from "../engine/index.js";
19
20
  import { selectConsumerCursorForUpdate } from "../pipeline/event-dispatcher-delivery.js";
20
21
  import { SHARED_INSTANCE_SENTINEL } from "../pipeline/index.js";
@@ -169,14 +170,16 @@ export async function transferTenantStorageUsage(args) {
169
170
  // skip: the moved fileRefs carry no applied storage share
170
171
  if (bytes === 0 && files === 0)
171
172
  return;
173
+ // read_* tables take writes only through an executor-managed runner, like the MSP apply above.
174
+ const managed = withExecutorManagedWrites(db);
172
175
  // Source: insert-values stay 0/0 (same guard as the DELETED handler above)
173
176
  // — the row this subtracts from is expected to already exist (the MSP
174
177
  // already applied the create against it), and if it somehow doesn't, this
175
178
  // must not conjure a negative balance out of thin air.
176
- await incrementCounter(db, tenantStorageUsageTable, { tenantId: sourceTenantId, totalBytes: 0, fileCount: 0 }, { totalBytes: -bytes, fileCount: -files }, { set: { lastUpdatedAt: sql `now()` } });
179
+ await incrementCounter(managed, tenantStorageUsageTable, { tenantId: sourceTenantId, totalBytes: 0, fileCount: 0 }, { totalBytes: -bytes, fileCount: -files }, { set: { lastUpdatedAt: sql `now()` } });
177
180
  // Destination: insert-values ARE the transferred amount (same as CREATED/
178
181
  // RESTORED above) — a tenant claiming its first-ever fileRef must start
179
182
  // its counter row at the transferred total, not at 0 with an increment
180
183
  // that only fires once a row already exists.
181
- await incrementCounter(db, tenantStorageUsageTable, { tenantId: destinationTenantId, totalBytes: bytes, fileCount: files }, { totalBytes: bytes, fileCount: files }, { set: { lastUpdatedAt: sql `now()` } });
184
+ await incrementCounter(managed, tenantStorageUsageTable, { tenantId: destinationTenantId, totalBytes: bytes, fileCount: files }, { totalBytes: bytes, fileCount: files }, { set: { lastUpdatedAt: sql `now()` } });
182
185
  }
@@ -3,10 +3,11 @@ import { createSystemUser, SYSTEM_USER_ID } from "../engine/system-user.js";
3
3
  import { getFileRefExecutor } from "./create-file-ref.js";
4
4
  import { fileRefsTable } from "./file-ref-table.js";
5
5
  export const STALE_PENDING_FILE_REF_SWEEP_BATCH = 500;
6
- // A pending upload names its target field (entityType set) but no record yet. Uploads without a
7
- // target field (inbox, dropzone) and files the system generated are kept on purpose.
6
+ // A pending upload names its target field (entityType set, filtered in SQL) but no record yet.
7
+ // Uploads without a target field (inbox, dropzone) and files the system generated are kept on
8
+ // purpose. The system filter stays in memory: SQL `<>` would also drop rows with a NULL inserter.
8
9
  function isStalePendingUpload(row) {
9
- return row.entityType !== null && row.insertedById !== SYSTEM_USER_ID;
10
+ return row.insertedById !== SYSTEM_USER_ID;
10
11
  }
11
12
  // Soft-deletes pending uploads whose record never came, through the fileRef executor, so the
12
13
  // soft-delete cleanup later removes their bytes like those of any deleted file.
@@ -21,6 +22,7 @@ export async function sweepStalePendingFileRefs(args) {
21
22
  for (;;) {
22
23
  const rows = await selectMany(db, fileRefsTable, {
23
24
  entityId: null,
25
+ entityType: { ne: null },
24
26
  isDeleted: false,
25
27
  insertedAt: { lt: cutoff },
26
28
  ...(cursor !== undefined && { id: { gt: cursor } }),
@@ -35,7 +37,11 @@ export async function sweepStalePendingFileRefs(args) {
35
37
  return swept;
36
38
  cursor = lastRow.id;
37
39
  for (const row of rows.filter(isStalePendingUpload)) {
38
- const removed = await executor.delete({ id: row.id }, user, db);
40
+ // A form save may bind the upload after the page was read; the delete then fails instead of
41
+ // soft-deleting a file a record now references.
42
+ const removed = await executor.delete({ id: row.id }, user, db, {
43
+ expect: { entityId: null, isDeleted: false },
44
+ });
39
45
  if (removed.isSuccess) {
40
46
  swept++;
41
47
  continue;
@@ -6,6 +6,10 @@ export type FileMetadata = {
6
6
  readonly size: number;
7
7
  };
8
8
  export type { FileStorageProvider, SignedUrlOptions, WriteStreamOptions, } from "@cosmicdrift/kumiko-types/file-storage-provider-types";
9
+ export declare class FileObjectMissingError extends Error {
10
+ readonly storageKey: string;
11
+ constructor(storageKey: string, message?: string);
12
+ }
9
13
  export type FileValidationOptions = {
10
14
  /** "10mb"-style string or a byte count. */
11
15
  readonly maxSize?: string | number | undefined;
@@ -2,6 +2,16 @@ import { readZipEntryNames } from "./zip-entry-names.js";
2
2
  // Lives here (not in file-ref-entity.ts) so engine code can name the entity without importing
3
3
  // a module that calls createEntity at load time.
4
4
  export const FILE_REF_ENTITY_NAME = "fileRef";
5
+ // Providers throw this when read() finds no object for a key, so callers can tell a permanently
6
+ // missing object from transient storage errors.
7
+ export class FileObjectMissingError extends Error {
8
+ storageKey;
9
+ constructor(storageKey, message = `file object not found: ${storageKey}`) {
10
+ super(message);
11
+ this.storageKey = storageKey;
12
+ this.name = "FileObjectMissingError";
13
+ }
14
+ }
5
15
  export function parseMaxSize(maxSize) {
6
16
  const match = maxSize.match(/^(\d+)(kb|mb|gb)$/i);
7
17
  if (!match)
@@ -24,4 +24,5 @@ type UploadFieldResolution = AttachedFieldResolution | {
24
24
  export declare function resolveUploadField(registry: Registry | undefined, input: UploadTarget, attachTargets: AttachTargets | undefined): UploadFieldResolution;
25
25
  export declare function registryHasAnonymousUploadField(registry: Registry | undefined): boolean;
26
26
  export declare function isAnonymousPendingUploadAllowed(registry: Registry | undefined, target: UploadTarget): boolean;
27
+ export declare function resolveMaxAnonymousUploadBytes(registry: Registry | undefined, defaultMaxSize: string): number;
27
28
  export {};
@@ -1,6 +1,7 @@
1
1
  import { isFileField } from "../engine/field-helpers.js";
2
2
  import { isActionFormScreenQn, resolveActionFormFileField } from "./action-form-upload.js";
3
3
  import { resolveFileSubField } from "./file-field-slots.js";
4
+ import { parseMaxSize } from "./types.js";
4
5
  function findAttachEntity(registry, entityType, attachTargets) {
5
6
  return (registry?.getEntity(entityType) ??
6
7
  (attachTargets === "entities-and-read-models"
@@ -84,8 +85,8 @@ export function registryHasAnonymousUploadField(registry) {
84
85
  anonymousUploadRegistries.set(registry, found);
85
86
  return found;
86
87
  }
87
- // Anonymous visitors share one user id and cannot bind, so only an opted-in field's
88
- // pending upload (no record, no action form) is allowed.
88
+ // Anonymous uploads stay pending (no record, no action form) and only into an opted-in field;
89
+ // the upload response hands the visitor the claim handle that later binds the file.
89
90
  export function isAnonymousPendingUploadAllowed(registry, target) {
90
91
  if (target.entityId !== undefined || target.actionForm !== undefined)
91
92
  return false;
@@ -94,3 +95,16 @@ export function isAnonymousPendingUploadAllowed(registry, target) {
94
95
  isFileField(resolution.fieldDef) &&
95
96
  resolution.fieldDef.anonymousUpload === true);
96
97
  }
98
+ // The anonymous body cap: the largest opted-in field, not the registry-wide largest, so a
99
+ // visitor cannot make the server buffer a body only an authenticated field would accept.
100
+ export function resolveMaxAnonymousUploadBytes(registry, defaultMaxSize) {
101
+ let maxBytes = 0;
102
+ for (const entity of registry?.getAllEntities().values() ?? []) {
103
+ for (const fieldDef of Object.values(entity.fields)) {
104
+ if (isFileField(fieldDef) && fieldDef.anonymousUpload === true) {
105
+ maxBytes = Math.max(maxBytes, parseMaxSize(fieldDef.maxSize ?? defaultMaxSize));
106
+ }
107
+ }
108
+ }
109
+ return maxBytes;
110
+ }