@cosmicdrift/kumiko-framework 0.413.1 → 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 (463) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +63 -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/managed-pages.md +90 -1
  18. package/agents/examples/pwa-shell.md +210 -0
  19. package/agents/examples/rate-limiting.md +3 -3
  20. package/agents/examples/record-detail-layout.md +1537 -67
  21. package/agents/examples/workflow-engine.md +16 -12
  22. package/agents/examples.md +1 -0
  23. package/agents/features-index.md +4 -2
  24. package/agents/features.md +22 -7
  25. package/agents/widgets.md +19 -1
  26. package/dist/api/api-constants.d.ts +1 -0
  27. package/dist/api/api-constants.js +4 -0
  28. package/dist/api/auth-middleware.js +4 -3
  29. package/dist/api/auth-routes-shared.js +2 -1
  30. package/dist/api/entity-read-access.d.ts +1 -0
  31. package/dist/api/entity-read-access.js +18 -0
  32. package/dist/api/export/export-route.d.ts +6 -1
  33. package/dist/api/export/export-route.js +27 -1
  34. package/dist/api/export/export-rows.js +19 -3
  35. package/dist/api/routes.d.ts +2 -0
  36. package/dist/api/routes.js +9 -1
  37. package/dist/api/server-extra-routes.js +2 -1
  38. package/dist/api/server-feature-http-routes.d.ts +9 -0
  39. package/dist/api/server-feature-http-routes.js +109 -0
  40. package/dist/api/server-middleware.js +2 -19
  41. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  42. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  43. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  44. package/dist/api/server-rate-limit-wiring.js +37 -0
  45. package/dist/api/server-routes.d.ts +4 -12
  46. package/dist/api/server-routes.js +12 -171
  47. package/dist/api/server-schema-route.d.ts +3 -0
  48. package/dist/api/server-schema-route.js +58 -0
  49. package/dist/api/server-wiring.js +2 -37
  50. package/dist/api/server.js +3 -1
  51. package/dist/compliance/override-schema.js +5 -5
  52. package/dist/compliance/sub-processors.js +10 -1
  53. package/dist/crypto/index.d.ts +1 -1
  54. package/dist/crypto/index.js +1 -1
  55. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  56. package/dist/crypto/pii-field-encryption.js +16 -1
  57. package/dist/db/apply-entity-event.js +4 -0
  58. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  59. package/dist/db/bun-sql-connection-codes.js +7 -0
  60. package/dist/db/collect-table-metas.js +4 -1
  61. package/dist/db/config-seed.js +1 -1
  62. package/dist/db/derived-field-sql.js +15 -13
  63. package/dist/db/derived-related-sql.d.ts +2 -2
  64. package/dist/db/derived-related-sql.js +4 -2
  65. package/dist/db/dialect.d.ts +3 -0
  66. package/dist/db/dialect.js +1 -3
  67. package/dist/db/driver-row-coercion.js +2 -2
  68. package/dist/db/driver-value-preparation.js +1 -1
  69. package/dist/db/eagerload.js +15 -12
  70. package/dist/db/entity-table-meta.d.ts +2 -0
  71. package/dist/db/entity-table-meta.js +7 -0
  72. package/dist/db/event-store-executor-context.js +13 -8
  73. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  74. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  75. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  76. package/dist/db/event-store-executor-read-filter.js +28 -11
  77. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  78. package/dist/db/event-store-executor-read-search.js +6 -6
  79. package/dist/db/event-store-executor-read-sort.js +3 -3
  80. package/dist/db/event-store-executor-read-where.js +14 -5
  81. package/dist/db/event-store-executor-read.js +7 -7
  82. package/dist/db/event-store-executor-write.js +50 -95
  83. package/dist/db/executor-managed-tables.js +4 -1
  84. package/dist/db/index.d.ts +4 -2
  85. package/dist/db/index.js +4 -2
  86. package/dist/db/known-table-names.d.ts +1 -0
  87. package/dist/db/known-table-names.js +7 -5
  88. package/dist/db/list-aggregate-labels.d.ts +1 -0
  89. package/dist/db/list-aggregate-labels.js +9 -1
  90. package/dist/db/migrate-generator.js +23 -4
  91. package/dist/db/migrate-rls-diff.d.ts +1 -0
  92. package/dist/db/migrate-rls-diff.js +15 -1
  93. package/dist/db/migrate-runner.js +2 -2
  94. package/dist/db/money.d.ts +1 -1
  95. package/dist/db/money.js +1 -4
  96. package/dist/db/parent-ref-clause.d.ts +6 -2
  97. package/dist/db/parent-ref-clause.js +76 -23
  98. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  99. package/dist/db/parent-ref-global-hosts.js +47 -0
  100. package/dist/db/production-schema-command-hint.d.ts +1 -0
  101. package/dist/db/production-schema-command-hint.js +3 -0
  102. package/dist/db/queries/backfill-pii.js +55 -29
  103. package/dist/db/queries/ddl.js +13 -2
  104. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  105. package/dist/db/queries/event-store-open-streams.js +33 -0
  106. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  107. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  108. package/dist/db/queries/event-store.js +0 -1
  109. package/dist/db/queries/raw-sql.js +0 -1
  110. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  111. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  112. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  113. package/dist/db/queries/rls-boot-catalog.js +13 -8
  114. package/dist/db/queries/rls-shape.d.ts +2 -1
  115. package/dist/db/queries/rls-shape.js +10 -0
  116. package/dist/db/queries/session-advisory-lock.js +2 -1
  117. package/dist/db/queries/test-stack.js +7 -7
  118. package/dist/db/query.js +16 -11
  119. package/dist/db/rebuild-marker.js +11 -2
  120. package/dist/db/render-rls-ddl.d.ts +2 -0
  121. package/dist/db/render-rls-ddl.js +16 -11
  122. package/dist/db/replay-migration-sql.js +1 -1
  123. package/dist/db/row-level-security-boot-check.js +18 -5
  124. package/dist/db/row-level-security-connection.js +25 -12
  125. package/dist/db/row-level-security-scope.d.ts +2 -1
  126. package/dist/db/row-level-security-scope.js +9 -5
  127. package/dist/db/sql-identifier.d.ts +1 -0
  128. package/dist/db/sql-identifier.js +3 -0
  129. package/dist/db/system-tenant-read-db.d.ts +5 -0
  130. package/dist/db/system-tenant-read-db.js +28 -0
  131. package/dist/db/table-builder.d.ts +3 -1
  132. package/dist/db/table-builder.js +18 -8
  133. package/dist/db/table-info.d.ts +1 -2
  134. package/dist/db/table-introspection.d.ts +3 -0
  135. package/dist/db/table-introspection.js +6 -0
  136. package/dist/db/table-push.d.ts +1 -0
  137. package/dist/db/table-push.js +7 -1
  138. package/dist/db/tenant-db-runner.d.ts +3 -0
  139. package/dist/db/tenant-db-runner.js +19 -1
  140. package/dist/db/transaction-serialization.d.ts +1 -0
  141. package/dist/db/transaction-serialization.js +20 -3
  142. package/dist/db/where-clause.js +11 -2
  143. package/dist/db/write-ownership-failures.d.ts +25 -0
  144. package/dist/db/write-ownership-failures.js +82 -0
  145. package/dist/engine/boot-validator/boot-check.js +7 -1
  146. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  147. package/dist/engine/boot-validator/boot-phases.js +3 -2
  148. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  149. package/dist/engine/boot-validator/boot-rules.js +4 -0
  150. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  151. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  152. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  153. package/dist/engine/boot-validator/config-deps.js +0 -28
  154. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  155. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  156. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  157. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  158. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  160. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  162. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  163. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  164. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  165. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  166. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  167. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  168. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  169. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  170. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  171. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  173. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  174. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  177. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  178. package/dist/engine/boot-validator/list-table-options.js +15 -1
  179. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  180. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  181. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  182. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  183. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  184. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  185. package/dist/engine/boot-validator/ownership.js +10 -1
  186. package/dist/engine/boot-validator/parent-ref.js +87 -50
  187. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  188. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  189. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  190. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  191. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  192. package/dist/engine/boot-validator/query-refs.js +24 -1
  193. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  194. package/dist/engine/boot-validator/row-decoration.js +16 -0
  195. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  197. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  199. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  200. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  202. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  203. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  209. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  211. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  212. package/dist/engine/boot-validator/screens-lists.js +19 -3
  213. package/dist/engine/boot-validator/screens.js +1 -1
  214. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  215. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  216. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  217. package/dist/engine/boot-validator/zod-shape.js +19 -1
  218. package/dist/engine/build-app-schema.js +4 -0
  219. package/dist/engine/config-helpers.d.ts +1 -2
  220. package/dist/engine/config-helpers.js +6 -7
  221. package/dist/engine/define-feature.js +1 -0
  222. package/dist/engine/define-handler.d.ts +1 -0
  223. package/dist/engine/define-handler.js +4 -2
  224. package/dist/engine/definition-violations.js +2 -2
  225. package/dist/engine/entity-handlers.js +3 -8
  226. package/dist/engine/entity-list-runtime-options.js +9 -8
  227. package/dist/engine/factories.d.ts +2 -0
  228. package/dist/engine/feature-config-events-jobs.js +1 -0
  229. package/dist/engine/feature-entity-handlers.js +5 -2
  230. package/dist/engine/field-access.d.ts +1 -1
  231. package/dist/engine/field-access.js +7 -10
  232. package/dist/engine/find-entity.js +3 -3
  233. package/dist/engine/form-derivations.js +3 -3
  234. package/dist/engine/index.d.ts +3 -3
  235. package/dist/engine/index.js +2 -2
  236. package/dist/engine/named-filter-roles.d.ts +3 -0
  237. package/dist/engine/named-filter-roles.js +23 -0
  238. package/dist/engine/pipeline.js +0 -1
  239. package/dist/engine/project-app-schema-for-roles.js +17 -2
  240. package/dist/engine/qualified-name.js +0 -1
  241. package/dist/engine/registry-facade.js +1 -2
  242. package/dist/engine/registry-state.d.ts +1 -1
  243. package/dist/engine/registry-state.js +5 -2
  244. package/dist/engine/registry-validate.js +2 -1
  245. package/dist/engine/resolve-named-list-filters.js +5 -2
  246. package/dist/engine/schema-builder.js +6 -10
  247. package/dist/engine/screen-helpers.d.ts +12 -0
  248. package/dist/engine/screen-helpers.js +17 -1
  249. package/dist/engine/soft-delete-cleanup.js +1 -5
  250. package/dist/engine/state-machine.js +0 -1
  251. package/dist/engine/steps/_database-clock.d.ts +2 -0
  252. package/dist/engine/steps/_database-clock.js +6 -0
  253. package/dist/engine/steps/compute.js +1 -1
  254. package/dist/engine/steps/retry.js +5 -1
  255. package/dist/engine/steps/return.js +0 -1
  256. package/dist/engine/steps/wait-for-event.js +2 -1
  257. package/dist/engine/steps/wait.js +2 -1
  258. package/dist/engine/system-user.d.ts +2 -2
  259. package/dist/engine/system-user.js +2 -2
  260. package/dist/engine/types/handlers.d.ts +1 -1
  261. package/dist/engine/types/handlers.js +1 -1
  262. package/dist/engine/types/screen.d.ts +1 -1
  263. package/dist/engine/types/screen.js +1 -1
  264. package/dist/engine/webhook-contracts.d.ts +2 -3
  265. package/dist/engine/webhook-contracts.js +2 -25
  266. package/dist/engine/webhook-events.js +48 -29
  267. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  268. package/dist/engine/webhook-payload-strictness.js +53 -0
  269. package/dist/env/_zod-introspect.d.ts +1 -0
  270. package/dist/env/dry-run.d.ts +1 -1
  271. package/dist/env/dry-run.js +1 -1
  272. package/dist/env/field-meta.d.ts +4 -0
  273. package/dist/env/field-meta.js +67 -0
  274. package/dist/env/field-rules.d.ts +9 -0
  275. package/dist/env/field-rules.js +46 -0
  276. package/dist/env/index.d.ts +3 -3
  277. package/dist/env/index.js +16 -71
  278. package/dist/env/internals.d.ts +3 -0
  279. package/dist/env/internals.js +1 -2
  280. package/dist/env/required-env.d.ts +3 -1
  281. package/dist/env/required-env.js +5 -2
  282. package/dist/errors/serialize.js +2 -2
  283. package/dist/errors/write-error-info.js +0 -2
  284. package/dist/es-ops/operations-schema.js +18 -7
  285. package/dist/event-store/admin-api.js +3 -3
  286. package/dist/event-store/event-store.js +0 -3
  287. package/dist/event-store/index.d.ts +1 -0
  288. package/dist/event-store/index.js +1 -0
  289. package/dist/event-store/transfer.js +1 -1
  290. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  291. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  292. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  293. package/dist/files/bind-pending-file-refs.js +54 -27
  294. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  295. package/dist/files/create-file-ref.d.ts +4 -1
  296. package/dist/files/create-file-ref.js +14 -3
  297. package/dist/files/default-file-guard.js +4 -1
  298. package/dist/files/file-claim.d.ts +6 -0
  299. package/dist/files/file-claim.js +17 -0
  300. package/dist/files/file-field-slots.d.ts +2 -0
  301. package/dist/files/file-field-slots.js +28 -0
  302. package/dist/files/file-ref-entity.d.ts +3 -0
  303. package/dist/files/file-ref-entity.js +2 -0
  304. package/dist/files/file-ref-table.d.ts +3 -0
  305. package/dist/files/file-routes.d.ts +4 -1
  306. package/dist/files/file-routes.js +80 -16
  307. package/dist/files/in-memory-provider.d.ts +1 -1
  308. package/dist/files/in-memory-provider.js +2 -1
  309. package/dist/files/index.d.ts +1 -1
  310. package/dist/files/index.js +1 -1
  311. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  312. package/dist/files/invalid-file-ref-error.js +15 -0
  313. package/dist/files/local-provider.js +9 -2
  314. package/dist/files/provider-resolver.js +1 -1
  315. package/dist/files/rebind-file-ref.d.ts +3 -2
  316. package/dist/files/rebind-file-ref.js +24 -18
  317. package/dist/files/resolve-file-handles.d.ts +13 -0
  318. package/dist/files/resolve-file-handles.js +57 -0
  319. package/dist/files/storage-tracking.d.ts +1 -1
  320. package/dist/files/storage-tracking.js +5 -2
  321. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  322. package/dist/files/types.d.ts +4 -0
  323. package/dist/files/types.js +10 -0
  324. package/dist/files/upload-field-resolution.d.ts +1 -0
  325. package/dist/files/upload-field-resolution.js +16 -2
  326. package/dist/files/upload-ledger.js +1 -1
  327. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  328. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  329. package/dist/i18n/required-surface-keys.js +19 -4
  330. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  331. package/dist/internal/boot-rule-table-expectations.js +29 -0
  332. package/dist/internal/row-level-security.d.ts +1 -0
  333. package/dist/internal/row-level-security.js +1 -0
  334. package/dist/internal/testing.d.ts +1 -0
  335. package/dist/internal/testing.js +1 -0
  336. package/dist/jobs/index.d.ts +1 -0
  337. package/dist/jobs/index.js +1 -0
  338. package/dist/jobs/job-load-events.d.ts +10 -0
  339. package/dist/jobs/job-load-events.js +12 -0
  340. package/dist/jobs/job-runner-context.js +6 -158
  341. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  342. package/dist/jobs/job-runner-dispatch.js +57 -0
  343. package/dist/jobs/job-runner-event-triggers.js +18 -9
  344. package/dist/jobs/job-runner-execution.js +2 -2
  345. package/dist/jobs/job-runner-facets.d.ts +48 -0
  346. package/dist/jobs/job-runner-facets.js +156 -0
  347. package/dist/jobs/job-runner-gates.js +19 -11
  348. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  349. package/dist/jobs/job-runner-helpers.js +18 -3
  350. package/dist/jobs/job-runner-scope.d.ts +1 -0
  351. package/dist/jobs/job-runner-scope.js +2 -0
  352. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  353. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  354. package/dist/jobs/job-runner.js +31 -70
  355. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  356. package/dist/jobs/obliterate-job-queues.js +23 -0
  357. package/dist/lifecycle/lifecycle.js +1 -1
  358. package/dist/migrations/event-header-scrub.d.ts +11 -0
  359. package/dist/migrations/event-header-scrub.js +33 -0
  360. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  361. package/dist/migrations/event-payload-scrub.js +36 -4
  362. package/dist/migrations/index.d.ts +1 -0
  363. package/dist/migrations/index.js +2 -0
  364. package/dist/migrations/kumiko-drift.d.ts +5 -2
  365. package/dist/migrations/kumiko-drift.js +51 -14
  366. package/dist/migrations/pending-rebuilds.js +4 -5
  367. package/dist/observability/sensitive-filter.js +0 -12
  368. package/dist/pipeline/aggregate-type-removal.js +17 -4
  369. package/dist/pipeline/context-services.d.ts +2 -0
  370. package/dist/pipeline/context-services.js +5 -2
  371. package/dist/pipeline/dispatch-batch.js +4 -3
  372. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  373. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  374. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  375. package/dist/pipeline/dispatch-nested-write.js +119 -0
  376. package/dist/pipeline/dispatch-query.js +10 -3
  377. package/dist/pipeline/dispatch-scope.js +4 -3
  378. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  379. package/dist/pipeline/dispatch-shared.js +6 -38
  380. package/dist/pipeline/dispatch-write.d.ts +0 -1
  381. package/dist/pipeline/dispatch-write.js +3 -302
  382. package/dist/pipeline/dispatcher-utils.js +6 -0
  383. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  384. package/dist/pipeline/effective-system-scope.js +22 -0
  385. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  386. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  387. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  388. package/dist/pipeline/event-dispatcher.js +6 -7
  389. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  390. package/dist/pipeline/handler-context-auth.js +3 -4
  391. package/dist/pipeline/handler-context-db.js +11 -4
  392. package/dist/pipeline/handler-context-dispatch.js +2 -2
  393. package/dist/pipeline/handler-context-events.d.ts +8 -3
  394. package/dist/pipeline/handler-context-events.js +20 -65
  395. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  396. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  397. package/dist/pipeline/handler-context-notify.js +2 -0
  398. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  399. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  400. package/dist/pipeline/handler-context-projection.js +39 -0
  401. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  402. package/dist/pipeline/handler-context-scope.js +14 -2
  403. package/dist/pipeline/index.d.ts +1 -1
  404. package/dist/pipeline/index.js +1 -1
  405. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  406. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  407. package/dist/pipeline/member-reader.js +4 -2
  408. package/dist/pipeline/msp-rebuild.js +1 -1
  409. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  410. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  411. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  412. package/dist/pipeline/projection-rebuild.js +16 -7
  413. package/dist/pipeline/projection-state.js +4 -6
  414. package/dist/pipeline/system-hooks.js +36 -6
  415. package/dist/pipeline/write-result-masking.js +31 -3
  416. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  417. package/dist/pipeline/write-transition-guard.js +95 -0
  418. package/dist/schema-cli/shared.d.ts +2 -0
  419. package/dist/schema-cli/shared.js +4 -2
  420. package/dist/schema-cli/validate-command.js +43 -28
  421. package/dist/search/meilisearch-adapter.js +14 -9
  422. package/dist/search/reindex-entity.d.ts +2 -0
  423. package/dist/search/reindex-entity.js +32 -4
  424. package/dist/search/reindex-tenants-search.js +20 -4
  425. package/dist/time/tz-context.js +1 -1
  426. package/dist/ui-types/card-column-roles.d.ts +4 -0
  427. package/dist/ui-types/card-column-roles.js +6 -3
  428. package/dist/ui-types/index.d.ts +2 -2
  429. package/dist/ui-types/index.js +1 -1
  430. package/dist/utils/ids.js +0 -1
  431. package/dist/utils/index.d.ts +1 -0
  432. package/dist/utils/index.js +1 -0
  433. package/dist/utils/return-path-limit.d.ts +1 -0
  434. package/dist/utils/return-path-limit.js +1 -0
  435. package/package.json +5 -3
  436. package/presets/biome-app.json +39 -21
  437. package/presets/biome-plugins/admin-api.grit +10 -0
  438. package/presets/biome-plugins/error-reasons.grit +53 -0
  439. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  440. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  441. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  442. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  443. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  444. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  445. package/presets/biome-plugins/no-date-api.grit +9 -0
  446. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  447. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  448. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  449. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  450. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  451. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  452. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  453. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  454. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  455. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  456. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  457. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  458. package/presets/biome-plugins/test-title.grit +20 -0
  459. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  460. package/presets/biome-rules.json +465 -0
  461. package/src/changes.json +309 -0
  462. package/dist/engine/minor-units.d.ts +0 -2
  463. package/dist/engine/minor-units.js +0 -8
@@ -1,35 +1,40 @@
1
- import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
1
+ import { isUuid, parseFileHandle } from "@cosmicdrift/kumiko-types/identifiers";
2
2
  import { isAnonymousSessionUser } from "../engine/system-user.js";
3
3
  import { FrameworkReasons, InternalError, reraiseAsKumikoError, UnprocessableError, } from "../errors/index.js";
4
4
  import { getFileRefExecutor } from "./create-file-ref.js";
5
+ import { fileClaimMatches } from "./file-claim.js";
5
6
  import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
6
7
  import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
8
+ import { invalidFileRefError } from "./invalid-file-ref-error.js";
7
9
  import { loadFileRefRows } from "./load-save-file-refs.js";
8
10
  import { validateFile } from "./types.js";
9
11
  import { resolveAttachedField } from "./upload-field-resolution.js";
10
12
  export { fileRefIdsOf } from "./file-field-slots.js";
11
- function isPendingUploadFor(row, entityName, fieldName, user) {
12
- // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart.
13
- if (isAnonymousSessionUser(user))
14
- return false;
15
- return (row["entityId"] === null &&
16
- row["entityType"] === entityName &&
17
- row["fieldName"] === fieldName &&
18
- row["insertedById"] === user.id);
13
+ function isPendingUploadFor(row, entityName, fieldName) {
14
+ return (row["entityId"] === null && row["entityType"] === entityName && row["fieldName"] === fieldName);
15
+ }
16
+ // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart:
17
+ // an anonymous upload is owned by whoever holds its claim, never by user id.
18
+ export function isOwnUpload(row, user) {
19
+ return !isAnonymousSessionUser(user) && row["insertedById"] === user.id;
19
20
  }
20
21
  function streamVersionOf(row) {
21
22
  return typeof row["version"] === "number" ? row["version"] : undefined;
22
23
  }
23
24
  async function bindPendingRow(args) {
24
- const { row, fileRefId, entityName, fieldName, entityId, bindTo, user, db } = args;
25
- if (!isPendingUploadFor(row, entityName, fieldName, user))
25
+ const { row, fileRefId, entityName, fieldName, entityId, bindTo, user, db, claimed } = args;
26
+ if (!isPendingUploadFor(row, entityName, fieldName))
27
+ return { kind: "not-pending" };
28
+ if (!claimed && !isOwnUpload(row, user))
26
29
  return { kind: "not-pending" };
27
30
  const bound = await getFileRefExecutor().update({
28
31
  id: fileRefId,
29
32
  version: streamVersionOf(row),
30
- changes: bindTo === undefined
31
- ? { entityId }
32
- : { entityId, entityType: bindTo.entityName, fieldName: bindTo.fieldName },
33
+ changes: {
34
+ entityId,
35
+ ...(bindTo !== undefined && { entityType: bindTo.entityName, fieldName: bindTo.fieldName }),
36
+ ...(claimed && { claimHash: null }),
37
+ },
33
38
  }, user, db);
34
39
  return bound.isSuccess ? { kind: "bound" } : { kind: "failed", error: bound.error };
35
40
  }
@@ -46,6 +51,7 @@ export async function bindPendingFileRefs(args) {
46
51
  if (result.entityName === undefined)
47
52
  return;
48
53
  const entityName = result.entityName;
54
+ const claimedFileRefIds = new Set(result.claimedFileRefIds);
49
55
  const entity = registry.getEntity(entityName);
50
56
  // skip: saves of unregistered aggregates (custom executors) declare no file fields
51
57
  if (entity === undefined)
@@ -62,6 +68,7 @@ export async function bindPendingFileRefs(args) {
62
68
  const row = fileRefRows.get(fileRefId);
63
69
  if (row === undefined)
64
70
  continue;
71
+ const claimed = claimedFileRefIds.has(fileRefId);
65
72
  const outcome = await bindPendingRow({
66
73
  row,
67
74
  fileRefId,
@@ -70,27 +77,41 @@ export async function bindPendingFileRefs(args) {
70
77
  entityId: String(result.id),
71
78
  user,
72
79
  db,
80
+ claimed,
73
81
  });
82
+ // A proven claim must end in a bind; staying silent would store the id of a file that
83
+ // remains pending with a live claim.
84
+ if (claimed && outcome.kind === "not-pending")
85
+ throw invalidFileRefError(fieldName);
74
86
  if (outcome.kind === "failed")
75
87
  throw reraiseAsKumikoError(outcome.error);
76
88
  }
77
89
  }
78
90
  }
91
+ // `fileRefId` is a bare id (the caller must own the upload) or a handle (the claim must match).
79
92
  async function loadPendingRow(lookup) {
80
93
  const { fileRefId, entityName, fieldName, user, db } = lookup;
81
- if (!isUuid(fileRefId))
94
+ const handle = parseFileHandle(fileRefId);
95
+ const id = handle?.id ?? fileRefId;
96
+ if (!isUuid(id))
82
97
  return undefined;
83
- const row = (await loadFileRefRows(db, [fileRefId], user.tenantId)).get(fileRefId);
84
- return row !== undefined && isPendingUploadFor(row, entityName, fieldName, user)
85
- ? row
86
- : undefined;
98
+ const row = (await loadFileRefRows(db, [id], user.tenantId)).get(id);
99
+ if (row === undefined || !isPendingUploadFor(row, entityName, fieldName))
100
+ return undefined;
101
+ if (handle !== null) {
102
+ return fileClaimMatches(row["claimHash"], handle.claim)
103
+ ? { id, row, claimed: true }
104
+ : undefined;
105
+ }
106
+ return isOwnUpload(row, user) ? { id, row, claimed: false } : undefined;
87
107
  }
88
108
  // fileName is left out on purpose: it is personal data and may be encrypted; read it through
89
109
  // the fileRef executor's detail when it is needed.
90
110
  export async function loadPendingFileRef(lookup) {
91
- const row = await loadPendingRow(lookup);
92
- if (row === undefined)
111
+ const pending = await loadPendingRow(lookup);
112
+ if (pending === undefined)
93
113
  return undefined;
114
+ const { row } = pending;
94
115
  const { storageKey, mimeType, size } = row;
95
116
  const version = streamVersionOf(row);
96
117
  if (typeof storageKey !== "string" ||
@@ -99,7 +120,7 @@ export async function loadPendingFileRef(lookup) {
99
120
  version === undefined) {
100
121
  return undefined;
101
122
  }
102
- return { id: lookup.fileRefId, storageKey, mimeType, size, version };
123
+ return { id: pending.id, storageKey, mimeType, size, version };
103
124
  }
104
125
  // The pending upload was checked against the form field it came in through; a different target
105
126
  // field may be stricter. Metadata only (bytes are not re-read): the extension comes from the
@@ -134,7 +155,8 @@ export function assertRowFitsFileField(row, fieldDef) {
134
155
  const CONCURRENT_BIND_ERROR_CODES = ["version_conflict", "unique_violation"];
135
156
  /**
136
157
  * Binds one of the caller's own pending uploads to a record from a custom handler, with the
137
- * same ownership predicate as the save pipeline. Anonymous callers never own an upload.
158
+ * same ownership predicate as the save pipeline. Anonymous callers never own an upload by user
159
+ * id: they pass the handle from the upload response as `fileRefId`.
138
160
  *
139
161
  * The helper checks the upload, not the target: the caller must already be authorized to write
140
162
  * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
@@ -149,13 +171,18 @@ const CONCURRENT_BIND_ERROR_CODES = ["version_conflict", "unique_violation"];
149
171
  * winner has committed); anything else throws.
150
172
  */
151
173
  export async function bindPendingFileRef(args) {
152
- const row = await loadPendingRow(args);
174
+ const pending = await loadPendingRow(args);
153
175
  // Without a stream version the update would run unversioned and could overwrite a concurrent bind.
154
- if (row === undefined || streamVersionOf(row) === undefined)
176
+ if (pending === undefined || streamVersionOf(pending.row) === undefined)
155
177
  return "not-pending";
156
178
  if (args.bindTo !== undefined)
157
- assertRowFitsBindTarget(args.registry, args.bindTo, row);
158
- const outcome = await bindPendingRow({ ...args, row });
179
+ assertRowFitsBindTarget(args.registry, args.bindTo, pending.row);
180
+ const outcome = await bindPendingRow({
181
+ ...args,
182
+ fileRefId: pending.id,
183
+ row: pending.row,
184
+ claimed: pending.claimed,
185
+ });
159
186
  switch (outcome.kind) {
160
187
  case "bound":
161
188
  return "bound";
@@ -1,3 +1,4 @@
1
+ import { parseFileHandle } from "@cosmicdrift/kumiko-types/identifiers";
1
2
  import { FrameworkReasons, InternalError, reraiseAsKumikoError, UnprocessableError, writeFailure, } from "../errors/index.js";
2
3
  import { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.js";
3
4
  import { getFileRefExecutor } from "./create-file-ref.js";
@@ -33,11 +34,11 @@ export async function copyPendingFileRefsToTenant(args) {
33
34
  if (pending === undefined)
34
35
  return fileNotPending(fileRefId);
35
36
  // Read through the executor so an encrypted file name arrives as plain text.
36
- const detail = await executor.detail({ id: fileRefId }, source.user, source.db);
37
+ const detail = await executor.detail({ id: pending.id }, source.user, source.db);
37
38
  if (detail === null)
38
39
  return fileNotPending(fileRefId);
39
40
  uploads.push({
40
- id: fileRefId,
41
+ id: pending.id,
41
42
  storageKey: pending.storageKey,
42
43
  mimeType: pending.mimeType,
43
44
  fileName: detail.fileName,
@@ -83,5 +84,8 @@ async function bindInPlace(source, target, fileIds) {
83
84
  if (outcome !== "bound")
84
85
  return fileNotPending(fileRefId);
85
86
  }
86
- return { isSuccess: true, data: fileIds };
87
+ return {
88
+ isSuccess: true,
89
+ data: fileIds.map((fileRefId) => parseFileHandle(fileRefId)?.id ?? fileRefId),
90
+ };
87
91
  }
@@ -14,6 +14,7 @@ declare function buildFileRefExecutor(): import("@cosmicdrift/kumiko-types/event
14
14
  readonly isDeleted?: boolean | undefined;
15
15
  readonly deletedAt?: Temporal.Instant | null | undefined;
16
16
  readonly deletedById?: string | null | undefined;
17
+ readonly claimHash: string | null;
17
18
  readonly entityId: string | null;
18
19
  readonly entityType: string | null;
19
20
  readonly fieldName: string | null;
@@ -73,6 +74,8 @@ export type UploadBytesOutcome = {
73
74
  export type StoreFileOutcome = {
74
75
  readonly kind: "created";
75
76
  readonly fileRef: CreatedFileRef;
77
+ /** `<id>.<claim>`, only for anonymous uploads: the one proof of owning the pending file. */
78
+ readonly handle?: string;
76
79
  } | {
77
80
  readonly kind: "rejected";
78
81
  readonly error: string;
@@ -83,7 +86,7 @@ export type StoreFileOutcome = {
83
86
  readonly failure: WriteFailure;
84
87
  };
85
88
  export declare function writeAcceptedFileBytes(deps: Pick<StoreFileDeps, "user" | "registry" | "attachTargets" | "defaultMaxUploadSize" | "writeBytes">, input: StoreFileInput): Promise<UploadBytesOutcome>;
86
- export declare function createFileRefRow(deps: Pick<StoreFileDeps, "user" | "tenantDb">, uploaded: UploadedFileBytes): Promise<{
89
+ export declare function createFileRefRow(deps: Pick<StoreFileDeps, "user" | "tenantDb">, uploaded: UploadedFileBytes, claimHash?: string): Promise<{
87
90
  readonly fileRef: CreatedFileRef;
88
91
  } | {
89
92
  readonly failure: WriteFailure;
@@ -1,7 +1,10 @@
1
+ import { formatFileHandle } from "@cosmicdrift/kumiko-types/identifiers";
1
2
  import { createEventStoreExecutor } from "../db/event-store-executor.js";
2
3
  import { runInOwnTransaction } from "../db/tenant-db-scoped-rebind.js";
4
+ import { isAnonymousSessionUser } from "../engine/system-user.js";
3
5
  import { InternalError } from "../errors/index.js";
4
6
  import { generateId } from "../utils/index.js";
7
+ import { generateFileClaim } from "./file-claim.js";
5
8
  import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
6
9
  import { fileRefsTable } from "./file-ref-table.js";
7
10
  import { resolveContentType } from "./resolve-content-type.js";
@@ -124,7 +127,7 @@ export async function writeAcceptedFileBytes(deps, input) {
124
127
  }
125
128
  // Row step: id is explicit so the response + storageKey stay consistent; tenantId, insertedAt and
126
129
  // insertedById are set by applyEntityEvent from the event metadata.
127
- export async function createFileRefRow(deps, uploaded) {
130
+ export async function createFileRefRow(deps, uploaded, claimHash) {
128
131
  const fileRefId = generateId();
129
132
  const result = await getFileRefExecutor().create({
130
133
  id: fileRefId,
@@ -135,6 +138,7 @@ export async function createFileRefRow(deps, uploaded) {
135
138
  entityType: uploaded.entityType ?? null,
136
139
  entityId: uploaded.entityId ?? null,
137
140
  fieldName: uploaded.fieldName ?? null,
141
+ ...(claimHash !== undefined && { claimHash }),
138
142
  }, deps.user, deps.tenantDb);
139
143
  if (!result.isSuccess)
140
144
  return { failure: result };
@@ -172,10 +176,11 @@ export async function storeFileAsFileRef(deps, input) {
172
176
  // skip: the create failure is the error worth reporting; the leftover bytes stay in storage.
173
177
  }
174
178
  };
179
+ const claim = isAnonymousSessionUser(deps.user) ? generateFileClaim() : undefined;
175
180
  const createRow = async (rowDb) => {
176
181
  if (await deps.isAttachTargetLocked?.(rowDb))
177
182
  throw new AttachTargetLockedError();
178
- return createFileRefRow({ user: deps.user, tenantDb: rowDb }, upload.uploaded);
183
+ return createFileRefRow({ user: deps.user, tenantDb: rowDb }, upload.uploaded, claim?.claimHash);
179
184
  };
180
185
  let row;
181
186
  try {
@@ -193,5 +198,11 @@ export async function storeFileAsFileRef(deps, input) {
193
198
  await deleteUploadedBytes();
194
199
  return { kind: "failed", failure: row.failure };
195
200
  }
196
- return { kind: "created", fileRef: row.fileRef };
201
+ return {
202
+ kind: "created",
203
+ fileRef: row.fileRef,
204
+ ...(claim !== undefined && {
205
+ handle: formatFileHandle({ id: row.fileRef.id, claim: claim.claim }),
206
+ }),
207
+ };
197
208
  }
@@ -1,4 +1,4 @@
1
- import { SYSTEM_USER_ID } from "../engine/system-user.js";
1
+ import { isAnonymousSessionUser, SYSTEM_USER_ID } from "../engine/system-user.js";
2
2
  export const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
3
3
  // Default guard: on attached files, allow the uploader or a privileged role,
4
4
  // and for reads also everyone who may read the record. Delete stays with the
@@ -8,6 +8,9 @@ export const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
8
8
  // record can ever claim.
9
9
  export function createDefaultGuard(privilegedRoles, canReadRecord, unclaimedUploadReaders, recordOnlyEntityTypes) {
10
10
  return async ({ fileRef, user, operation }) => {
11
+ // Every anonymous visitor shares one user id, so insertedById proves no ownership for them.
12
+ if (isAnonymousSessionUser(user))
13
+ return "deny";
11
14
  if (fileRef.insertedById === user.id)
12
15
  return "allow";
13
16
  const isRecordOnly = fileRef.entityType !== null && recordOnlyEntityTypes.has(fileRef.entityType);
@@ -0,0 +1,6 @@
1
+ /** `claimHash` is what the fileRef row stores; the claim itself only ever leaves in the upload response. */
2
+ export declare function generateFileClaim(): {
3
+ readonly claim: string;
4
+ readonly claimHash: string;
5
+ };
6
+ export declare function fileClaimMatches(storedClaimHash: unknown, claim: string): boolean;
@@ -0,0 +1,17 @@
1
+ import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
2
+ const FILE_CLAIM_BYTES = 32;
3
+ function hashFileClaim(claim) {
4
+ return createHash("sha256").update(claim).digest();
5
+ }
6
+ /** `claimHash` is what the fileRef row stores; the claim itself only ever leaves in the upload response. */
7
+ export function generateFileClaim() {
8
+ const claim = randomBytes(FILE_CLAIM_BYTES).toString("base64url");
9
+ return { claim, claimHash: hashFileClaim(claim).toString("hex") };
10
+ }
11
+ export function fileClaimMatches(storedClaimHash, claim) {
12
+ if (typeof storedClaimHash !== "string")
13
+ return false;
14
+ const stored = Buffer.from(storedClaimHash, "hex");
15
+ const presented = hashFileClaim(claim);
16
+ return stored.length === presented.length && timingSafeEqual(stored, presented);
17
+ }
@@ -5,6 +5,8 @@ export declare function isFileSubField(sub: EmbeddedSubFieldDef): sub is Embedde
5
5
  export declare function holdsFileRefs(def: FieldDefinition | undefined): boolean;
6
6
  /** FileRef ids a field value names. `file_refs.fieldName` stays the top-level field, never the sub-field. */
7
7
  export declare function fileRefIdsInField(def: FieldDefinition | undefined, value: unknown): string[];
8
+ /** The field value with every string in a file slot replaced by `map(entry)`; other values pass through. */
9
+ export declare function mapFileRefSlots(def: FieldDefinition | undefined, value: unknown, map: (entry: string) => string): unknown;
8
10
  /** FileRef ids per file sub-field of an embedded field value, pooled over all rows. */
9
11
  export declare function fileRefIdsBySubField(def: FieldDefinition | undefined, value: unknown): ReadonlyMap<string, readonly string[]>;
10
12
  export declare function resolveFileSubField(def: FieldDefinition | undefined, subField: string): EmbeddedFileSubFieldDef | undefined;
@@ -34,6 +34,34 @@ export function fileRefIdsInField(def, value) {
34
34
  const rows = Array.isArray(value) ? value : [value];
35
35
  return rows.flatMap((row) => isPlainObject(row) ? subNames.flatMap((name) => fileRefIdsOf(row[name])) : []);
36
36
  }
37
+ /** The field value with every string in a file slot replaced by `map(entry)`; other values pass through. */
38
+ export function mapFileRefSlots(def, value, map) {
39
+ const mapSlot = (slot) => {
40
+ if (typeof slot === "string")
41
+ return map(slot);
42
+ return Array.isArray(slot)
43
+ ? slot.map((entry) => (typeof entry === "string" ? map(entry) : entry))
44
+ : slot;
45
+ };
46
+ if (def === undefined)
47
+ return value;
48
+ if (isFileField(def))
49
+ return mapSlot(value);
50
+ if (def.type !== "embedded")
51
+ return value;
52
+ const subNames = fileSubFieldNames(def);
53
+ const mapRow = (row) => {
54
+ if (!isPlainObject(row))
55
+ return row;
56
+ const mapped = { ...row };
57
+ for (const name of subNames) {
58
+ if (name in mapped)
59
+ mapped[name] = mapSlot(mapped[name]);
60
+ }
61
+ return mapped;
62
+ };
63
+ return Array.isArray(value) ? value.map(mapRow) : mapRow(value);
64
+ }
37
65
  /** FileRef ids per file sub-field of an embedded field value, pooled over all rows. */
38
66
  export function fileRefIdsBySubField(def, value) {
39
67
  const bySubField = new Map();
@@ -31,4 +31,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
31
31
  readonly fieldName: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
32
32
  required: false;
33
33
  };
34
+ readonly claimHash: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
35
+ required: false;
36
+ };
34
37
  }, "tenant">;
@@ -29,5 +29,7 @@ export const fileRefEntity = createEntity({
29
29
  entityType: createTextField({ personal: false, reason: "technical_reference" }),
30
30
  entityId: createTextField({ personal: false, reason: "technical_reference" }),
31
31
  fieldName: createTextField({ personal: false, reason: "technical_reference" }),
32
+ // sha256 of the claim that proves ownership of an anonymous pending upload; never the claim.
33
+ claimHash: createTextField({ personal: false, reason: "technical_reference" }),
32
34
  },
33
35
  });
@@ -30,4 +30,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
30
30
  readonly fieldName: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
31
31
  required: false;
32
32
  };
33
+ readonly claimHash: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
34
+ required: false;
35
+ };
33
36
  }, "tenant">>;
@@ -1,6 +1,7 @@
1
1
  import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
2
2
  import type { WriteErrorInfo } from "@cosmicdrift/kumiko-types/write-error-info-types";
3
3
  import { Hono } from "hono";
4
+ import { type ClientIpResolver } from "../api/client-ip.ts";
4
5
  import type { DbConnection } from "../db/connection.ts";
5
6
  import { type Registry, type SessionUser, type TenantId } from "../engine/types/index.ts";
6
7
  import type { FileProviderResolver } from "./provider-resolver.ts";
@@ -31,7 +32,8 @@ export type FileAccessGuard = (args: {
31
32
  }) => FileAccessDecision | Promise<FileAccessDecision>;
32
33
  export type FileRoutesOptions = {
33
34
  readonly db: DbConnection;
34
- readonly metaBatchRateLimitResolver?: RateLimitResolver;
35
+ readonly rateLimitResolver?: RateLimitResolver;
36
+ readonly clientIpResolver?: ClientIpResolver;
35
37
  readonly resolveProvider: FileProviderResolver;
36
38
  readonly registry?: Registry;
37
39
  readonly maxUploadSize?: string;
@@ -41,6 +43,7 @@ export type FileRoutesOptions = {
41
43
  readonly canReadRecord?: RecordReadCheck;
42
44
  readonly canWriteRecord?: RecordWriteCheck;
43
45
  };
46
+ export declare const ANONYMOUS_UPLOADS_PER_WINDOW = 20;
44
47
  export declare function resolveMaxUploadBodyBytes(options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">): number;
45
48
  export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "unclaimedUploadReaders" | "maxUploadSize">;
46
49
  export declare function configuredMaxUploadBytes(registry: Registry): number | undefined;
@@ -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;