@terreno/api 57.2.0 → 57.4.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 (472) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +23 -10
  2. package/README.md +23 -7
  3. package/dist/actions.js +19 -7
  4. package/dist/adminTypes.d.ts +7 -0
  5. package/dist/adminTypes.js +6 -1
  6. package/dist/api.d.ts +14 -0
  7. package/dist/api.js +111 -60
  8. package/dist/audit/auditApp.d.ts +30 -0
  9. package/dist/audit/auditApp.js +155 -0
  10. package/dist/audit/auditEventModel.d.ts +29 -0
  11. package/dist/audit/auditEventModel.js +102 -0
  12. package/dist/audit/cloudTasksEnqueue.d.ts +32 -0
  13. package/dist/audit/cloudTasksEnqueue.js +162 -0
  14. package/dist/audit/diff.d.ts +10 -0
  15. package/dist/audit/diff.js +230 -0
  16. package/dist/audit/processQueue.d.ts +6 -0
  17. package/dist/audit/processQueue.js +101 -0
  18. package/dist/audit/rbacSink.d.ts +2 -0
  19. package/dist/audit/rbacSink.js +82 -0
  20. package/dist/audit/record.d.ts +56 -0
  21. package/dist/audit/record.js +373 -0
  22. package/dist/auth.d.ts +23 -10
  23. package/dist/auth.js +97 -32
  24. package/dist/authRecovery.d.ts +5 -0
  25. package/dist/authRecovery.js +350 -0
  26. package/dist/authTokens.d.ts +8 -0
  27. package/dist/authTokens.js +162 -0
  28. package/dist/betterAuth.d.ts +39 -0
  29. package/dist/betterAuthApp.d.ts +4 -0
  30. package/dist/betterAuthApp.js +26 -8
  31. package/dist/betterAuthSetup.d.ts +44 -2
  32. package/dist/betterAuthSetup.js +288 -18
  33. package/dist/collectionRegistry.d.ts +40 -0
  34. package/dist/collectionRegistry.js +97 -0
  35. package/dist/configurationApp.d.ts +11 -2
  36. package/dist/configurationApp.js +2 -4
  37. package/dist/docLoader.js +35 -6
  38. package/dist/expressServer.d.ts +26 -3
  39. package/dist/expressServer.js +79 -11
  40. package/dist/index.d.ts +42 -1
  41. package/dist/index.js +84 -2
  42. package/dist/mcp/auth.d.ts +1 -0
  43. package/dist/mcp/auth.js +47 -25
  44. package/dist/mcp/handlers.d.ts +1 -1
  45. package/dist/mcp/handlers.js +67 -233
  46. package/dist/mcp/query.d.ts +2 -15
  47. package/dist/mcp/query.js +8 -8
  48. package/dist/mcp/registry.d.ts +1 -5
  49. package/dist/mcp/registry.js +31 -20
  50. package/dist/mcp/schemaGenerator.d.ts +2 -7
  51. package/dist/mcp/schemaGenerator.js +41 -116
  52. package/dist/mcp/server.d.ts +1 -0
  53. package/dist/mcp/server.js +1 -0
  54. package/dist/mcp/serviceTokens.d.ts +16 -0
  55. package/dist/mcp/serviceTokens.js +345 -0
  56. package/dist/mcp/types.d.ts +2 -2
  57. package/dist/migrations/fixtures/all-down/20260910120000-one.d.ts +4 -0
  58. package/dist/migrations/fixtures/all-down/20260910120000-one.js +49 -0
  59. package/dist/migrations/fixtures/all-down/20260910120001-two.d.ts +4 -0
  60. package/dist/migrations/fixtures/all-down/20260910120001-two.js +49 -0
  61. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.d.ts +3 -0
  62. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.js +45 -0
  63. package/dist/migrations/fixtures/bad-name/not-a-migration.d.ts +3 -0
  64. package/dist/migrations/fixtures/bad-name/not-a-migration.js +45 -0
  65. package/dist/migrations/fixtures/missing-up/20260910120000-noup.d.ts +2 -0
  66. package/dist/migrations/fixtures/missing-up/20260910120000-noup.js +5 -0
  67. package/dist/migrations/fixtures/valid/20260910120000-alpha.d.ts +3 -0
  68. package/dist/migrations/fixtures/valid/20260910120000-alpha.js +45 -0
  69. package/dist/migrations/fixtures/valid/20260910120001-beta.d.ts +4 -0
  70. package/dist/migrations/fixtures/valid/20260910120001-beta.js +49 -0
  71. package/dist/migrations/generate.d.ts +17 -0
  72. package/dist/migrations/generate.js +277 -0
  73. package/dist/migrations/load.d.ts +20 -0
  74. package/dist/migrations/load.js +236 -0
  75. package/dist/migrations/lock.d.ts +13 -0
  76. package/dist/migrations/lock.js +145 -0
  77. package/dist/migrations/runner.d.ts +42 -0
  78. package/dist/migrations/runner.js +503 -0
  79. package/dist/migrations/schemaCatalog.d.ts +44 -0
  80. package/dist/migrations/schemaCatalog.js +326 -0
  81. package/dist/migrations/types.d.ts +87 -0
  82. package/dist/migrations/types.js +7 -0
  83. package/dist/models/mcpServiceToken.d.ts +3 -0
  84. package/dist/models/mcpServiceToken.js +208 -0
  85. package/dist/models/notification.d.ts +2 -0
  86. package/dist/models/notification.js +62 -0
  87. package/dist/models/notificationPreference.d.ts +2 -0
  88. package/dist/models/notificationPreference.js +49 -0
  89. package/dist/notifications/notificationService.d.ts +40 -0
  90. package/dist/notifications/notificationService.js +323 -0
  91. package/dist/notifications/notificationsApp.d.ts +18 -0
  92. package/dist/notifications/notificationsApp.js +250 -0
  93. package/dist/notifications/notificationsBeforeSend.d.ts +14 -0
  94. package/dist/notifications/notificationsBeforeSend.js +77 -0
  95. package/dist/openApi.d.ts +1 -7
  96. package/dist/openApi.js +7 -6
  97. package/dist/openApiBuilder.d.ts +19 -7
  98. package/dist/openApiBuilder.js +61 -8
  99. package/dist/openApiCompat.js +1 -1
  100. package/dist/openApiValidator.d.ts +13 -1
  101. package/dist/openApiValidator.js +200 -38
  102. package/dist/orgs/orgContext.d.ts +23 -0
  103. package/dist/orgs/orgContext.js +198 -0
  104. package/dist/orgs/orgPermissions.d.ts +4 -0
  105. package/dist/orgs/orgPermissions.js +77 -0
  106. package/dist/orgs/orgPlugin.d.ts +13 -0
  107. package/dist/orgs/orgPlugin.js +84 -0
  108. package/dist/orgs/organizationModel.d.ts +13 -0
  109. package/dist/orgs/organizationModel.js +301 -0
  110. package/dist/orgs/organizationSettings.d.ts +19 -0
  111. package/dist/orgs/organizationSettings.js +120 -0
  112. package/dist/orgs/orgsApp.d.ts +28 -0
  113. package/dist/orgs/orgsApp.js +678 -0
  114. package/dist/permissions.d.ts +7 -13
  115. package/dist/permissions.js +8 -31
  116. package/dist/plugins.d.ts +14 -1
  117. package/dist/plugins.js +17 -6
  118. package/dist/populate.d.ts +2 -2
  119. package/dist/populate.js +47 -42
  120. package/dist/rateLimit/applyTrustProxy.d.ts +3 -0
  121. package/dist/rateLimit/applyTrustProxy.js +17 -0
  122. package/dist/rateLimit/createStore.d.ts +2 -0
  123. package/dist/rateLimit/createStore.js +28 -0
  124. package/dist/rateLimit/memoryStore.d.ts +2 -0
  125. package/dist/rateLimit/memoryStore.js +108 -0
  126. package/dist/rateLimit/middleware.d.ts +3 -0
  127. package/dist/rateLimit/middleware.js +109 -0
  128. package/dist/rateLimit/mongoStore.d.ts +4 -0
  129. package/dist/rateLimit/mongoStore.js +123 -0
  130. package/dist/rateLimit/policies.d.ts +10 -0
  131. package/dist/rateLimit/policies.js +149 -0
  132. package/dist/rateLimit/redisStore.d.ts +4 -0
  133. package/dist/rateLimit/redisStore.js +156 -0
  134. package/dist/rateLimit/types.d.ts +54 -0
  135. package/dist/rateLimit/types.js +9 -0
  136. package/dist/rbac/access.js +35 -14
  137. package/dist/rbac/assertAllowed.d.ts +9 -0
  138. package/dist/rbac/assertAllowed.js +182 -0
  139. package/dist/rbac/membershipOrgAdminSource.d.ts +6 -0
  140. package/dist/rbac/membershipOrgAdminSource.js +122 -0
  141. package/dist/rbac/modelRouterAccess.d.ts +4 -0
  142. package/dist/rbac/modelRouterAccess.js +11 -4
  143. package/dist/rbac/permissionUtils.js +3 -2
  144. package/dist/rbac/resolve.js +65 -35
  145. package/dist/rbac/roleModel.d.ts +2 -5
  146. package/dist/rbac/roleModel.js +18 -4
  147. package/dist/rbac/routes.js +15 -6
  148. package/dist/rbac/statements.d.ts +10 -1
  149. package/dist/rbac/statements.js +19 -2
  150. package/dist/rbac/types.d.ts +5 -0
  151. package/dist/realtime/changeStreamWatcher.d.ts +10 -4
  152. package/dist/realtime/changeStreamWatcher.js +110 -64
  153. package/dist/realtime/deprecation.d.ts +13 -0
  154. package/dist/realtime/deprecation.js +33 -0
  155. package/dist/realtime/realtimeApp.d.ts +2 -1
  156. package/dist/realtime/realtimeApp.js +11 -11
  157. package/dist/realtime/registry.d.ts +0 -31
  158. package/dist/realtime/registry.js +44 -31
  159. package/dist/realtime/socketAuth.d.ts +5 -5
  160. package/dist/realtime/socketAuth.js +11 -1
  161. package/dist/realtime/socketUser.d.ts +5 -1
  162. package/dist/realtime/types.d.ts +14 -4
  163. package/dist/schemaMetadata.d.ts +56 -0
  164. package/dist/schemaMetadata.js +524 -0
  165. package/dist/seedRunner.d.ts +88 -0
  166. package/dist/seedRunner.js +627 -0
  167. package/dist/sync/adminBroadcastScope.d.ts +40 -0
  168. package/dist/sync/adminBroadcastScope.js +194 -0
  169. package/dist/sync/adminWindowAccess.d.ts +13 -0
  170. package/dist/sync/adminWindowAccess.js +96 -0
  171. package/dist/sync/adminWindowMutation.d.ts +88 -0
  172. package/dist/sync/adminWindowMutation.js +247 -0
  173. package/dist/sync/executors.d.ts +19 -3
  174. package/dist/sync/executors.js +194 -165
  175. package/dist/sync/loadHarness.js +28 -19
  176. package/dist/sync/models.js +26 -24
  177. package/dist/sync/mutationHandler.d.ts +14 -2
  178. package/dist/sync/mutationHandler.js +201 -76
  179. package/dist/sync/registrationSideEffects.d.ts +35 -0
  180. package/dist/sync/registrationSideEffects.js +151 -0
  181. package/dist/sync/registry.d.ts +2 -52
  182. package/dist/sync/registry.js +42 -187
  183. package/dist/sync/routes.d.ts +13 -0
  184. package/dist/sync/routes.js +116 -58
  185. package/dist/sync/scripts/compactTombstones.js +0 -2
  186. package/dist/sync/socketHandlers.d.ts +8 -2
  187. package/dist/sync/socketHandlers.js +144 -50
  188. package/dist/sync/streams.d.ts +2 -0
  189. package/dist/sync/streams.js +7 -1
  190. package/dist/sync/syncApp.d.ts +4 -3
  191. package/dist/sync/syncApp.js +5 -4
  192. package/dist/sync/syncBatch.d.ts +5 -2
  193. package/dist/sync/syncBatch.js +7 -6
  194. package/dist/sync/syncSeqPlugin.d.ts +1 -1
  195. package/dist/sync/syncSeqPlugin.js +20 -16
  196. package/dist/sync/types.d.ts +18 -0
  197. package/dist/terrenoApp.d.ts +48 -5
  198. package/dist/terrenoApp.js +157 -72
  199. package/dist/tests/createTestData.d.ts +1 -3
  200. package/dist/tests/createTestData.js +3 -5
  201. package/dist/tests/models.d.ts +3 -0
  202. package/dist/tests/models.js +15 -2
  203. package/dist/tests/testHelper.d.ts +0 -5
  204. package/dist/tests/testHelper.js +2 -9
  205. package/dist/types/authToken.d.ts +33 -0
  206. package/dist/types/authToken.js +2 -0
  207. package/dist/types/mcpServiceToken.d.ts +41 -0
  208. package/dist/types/mcpServiceToken.js +2 -0
  209. package/dist/types/membership.d.ts +23 -0
  210. package/dist/types/membership.js +2 -0
  211. package/dist/types/notification.d.ts +28 -0
  212. package/dist/types/notification.js +2 -0
  213. package/dist/types/notificationPreference.d.ts +20 -0
  214. package/dist/types/notificationPreference.js +2 -0
  215. package/dist/types/organization.d.ts +36 -0
  216. package/dist/types/organization.js +2 -0
  217. package/dist/webhooks/headerValue.d.ts +2 -0
  218. package/dist/webhooks/headerValue.js +14 -0
  219. package/dist/webhooks/idempotency/memoryStore.d.ts +10 -0
  220. package/dist/webhooks/idempotency/memoryStore.js +65 -0
  221. package/dist/webhooks/idempotency/mongoStore.d.ts +4 -0
  222. package/dist/webhooks/idempotency/mongoStore.js +150 -0
  223. package/dist/webhooks/idempotency/webhookReceipt.d.ts +17 -0
  224. package/dist/webhooks/idempotency/webhookReceipt.js +39 -0
  225. package/dist/webhooks/rawBody.d.ts +15 -0
  226. package/dist/webhooks/rawBody.js +23 -0
  227. package/dist/webhooks/timingSafeEqual.d.ts +4 -0
  228. package/dist/webhooks/timingSafeEqual.js +17 -0
  229. package/dist/webhooks/verifiers/hmac.d.ts +15 -0
  230. package/dist/webhooks/verifiers/hmac.js +49 -0
  231. package/dist/webhooks/verifiers/sendgrid.d.ts +10 -0
  232. package/dist/webhooks/verifiers/sendgrid.js +56 -0
  233. package/dist/webhooks/verifiers/stripe.d.ts +9 -0
  234. package/dist/webhooks/verifiers/stripe.js +99 -0
  235. package/dist/webhooks/verifiers/twilio.d.ts +9 -0
  236. package/dist/webhooks/verifiers/twilio.js +112 -0
  237. package/dist/webhooks/webhooksApp.d.ts +33 -0
  238. package/dist/webhooks/webhooksApp.js +195 -0
  239. package/package.json +32 -27
  240. package/src/__snapshots__/openApi.test.ts.snap +444 -36
  241. package/src/__snapshots__/openApiBuilder.test.ts.snap +24 -24
  242. package/src/__snapshots__/schemaMetadata.test.ts.snap +196 -0
  243. package/src/actions.ts +20 -13
  244. package/src/adminModelRouter.test.ts +133 -0
  245. package/src/adminTypes.ts +8 -0
  246. package/src/api.arrayOperations.test.ts +43 -31
  247. package/src/api.hooks.test.ts +38 -29
  248. package/src/api.query.test.ts +31 -31
  249. package/src/api.test.ts +133 -97
  250. package/src/api.ts +84 -27
  251. package/src/audit/auditApp.test.ts +243 -0
  252. package/src/audit/auditApp.ts +139 -0
  253. package/src/audit/auditEventModel.ts +156 -0
  254. package/src/audit/auditRouter.test.ts +456 -0
  255. package/src/audit/cloudTasksEnqueue.test.ts +124 -0
  256. package/src/audit/cloudTasksEnqueue.ts +104 -0
  257. package/src/audit/diff.ts +163 -0
  258. package/src/audit/processQueue.ts +69 -0
  259. package/src/audit/rbacSink.test.ts +86 -0
  260. package/src/audit/rbacSink.ts +42 -0
  261. package/src/audit/record.test.ts +402 -0
  262. package/src/audit/record.ts +328 -0
  263. package/src/auth.test.ts +108 -52
  264. package/src/auth.ts +98 -29
  265. package/src/authRecovery.test.ts +281 -0
  266. package/src/authRecovery.ts +279 -0
  267. package/src/authTokens.test.ts +94 -0
  268. package/src/authTokens.ts +118 -0
  269. package/src/authVerification.test.ts +293 -0
  270. package/src/betterAuth.ts +31 -0
  271. package/src/betterAuthApp.test.ts +1 -0
  272. package/src/betterAuthApp.ts +27 -9
  273. package/src/betterAuthSetup.test.ts +595 -38
  274. package/src/betterAuthSetup.ts +261 -5
  275. package/src/collectionRegistry.test.ts +164 -0
  276. package/src/collectionRegistry.ts +135 -0
  277. package/src/configurationApp.ts +13 -7
  278. package/src/docLoader.test.ts +45 -1
  279. package/src/docLoader.ts +37 -6
  280. package/src/express.d.ts +3 -0
  281. package/src/expressServer.test.ts +180 -68
  282. package/src/expressServer.ts +75 -19
  283. package/src/githubAuth.test.ts +60 -55
  284. package/src/index.ts +127 -0
  285. package/src/mcp/auth.test.ts +47 -0
  286. package/src/mcp/auth.ts +32 -11
  287. package/src/mcp/handlers.test.ts +275 -0
  288. package/src/mcp/handlers.ts +45 -172
  289. package/src/mcp/integration.test.ts +59 -9
  290. package/src/mcp/query.ts +5 -7
  291. package/src/mcp/registry.ts +29 -20
  292. package/src/mcp/schemaGenerator.test.ts +8 -0
  293. package/src/mcp/schemaGenerator.ts +49 -131
  294. package/src/mcp/server.ts +2 -0
  295. package/src/mcp/serviceTokens.test.ts +330 -0
  296. package/src/mcp/serviceTokens.ts +307 -0
  297. package/src/mcp/toolGenerator.test.ts +82 -1
  298. package/src/mcp/types.ts +2 -6
  299. package/src/migrations/cli.test.ts +376 -0
  300. package/src/migrations/cli.ts +283 -0
  301. package/src/migrations/fixtures/all-down/20260910120000-one.ts +6 -0
  302. package/src/migrations/fixtures/all-down/20260910120001-two.ts +6 -0
  303. package/src/migrations/fixtures/bad-id/20260910120000-mismatch.ts +4 -0
  304. package/src/migrations/fixtures/bad-name/not-a-migration.ts +4 -0
  305. package/src/migrations/fixtures/missing-up/20260910120000-noup.ts +2 -0
  306. package/src/migrations/fixtures/valid/20260910120000-alpha.ts +4 -0
  307. package/src/migrations/fixtures/valid/20260910120001-beta.ts +6 -0
  308. package/src/migrations/generate.test.ts +333 -0
  309. package/src/migrations/generate.ts +216 -0
  310. package/src/migrations/load.test.ts +103 -0
  311. package/src/migrations/load.ts +124 -0
  312. package/src/migrations/lock.test.ts +133 -0
  313. package/src/migrations/lock.ts +118 -0
  314. package/src/migrations/runner.test.ts +504 -0
  315. package/src/migrations/runner.ts +358 -0
  316. package/src/migrations/schemaCatalog.test.ts +159 -0
  317. package/src/migrations/schemaCatalog.ts +262 -0
  318. package/src/migrations/types.ts +94 -0
  319. package/src/models/mcpServiceToken.test.ts +129 -0
  320. package/src/models/mcpServiceToken.ts +158 -0
  321. package/src/models/notification.ts +68 -0
  322. package/src/models/notificationPreference.ts +62 -0
  323. package/src/notifications/notificationService.ts +254 -0
  324. package/src/notifications/notificationsApp.test.ts +505 -0
  325. package/src/notifications/notificationsApp.ts +200 -0
  326. package/src/notifications/notificationsBeforeSend.ts +51 -0
  327. package/src/openApi.test.ts +80 -65
  328. package/src/openApi.ts +2 -1
  329. package/src/openApiBuilder.test.ts +95 -7
  330. package/src/openApiBuilder.ts +60 -12
  331. package/src/openApiCompat.ts +1 -1
  332. package/src/openApiValidator.test.ts +270 -56
  333. package/src/openApiValidator.ts +219 -36
  334. package/src/orgs/orgAccessOptIn.test.ts +87 -0
  335. package/src/orgs/orgContext.test.ts +259 -0
  336. package/src/orgs/orgContext.ts +151 -0
  337. package/src/orgs/orgPermissions.test.ts +105 -0
  338. package/src/orgs/orgPermissions.ts +40 -0
  339. package/src/orgs/orgPlugin.test.ts +130 -0
  340. package/src/orgs/orgPlugin.ts +70 -0
  341. package/src/orgs/orgRbac.test.ts +267 -0
  342. package/src/orgs/orgSecurityDefects.test.ts +415 -0
  343. package/src/orgs/organizationModel.test.ts +205 -0
  344. package/src/orgs/organizationModel.ts +257 -0
  345. package/src/orgs/organizationSettings.test.ts +113 -0
  346. package/src/orgs/organizationSettings.ts +126 -0
  347. package/src/orgs/orgsApp.test.ts +382 -0
  348. package/src/orgs/orgsApp.ts +563 -0
  349. package/src/permissions.test.ts +62 -36
  350. package/src/permissions.ts +8 -30
  351. package/src/plugins.test.ts +14 -0
  352. package/src/plugins.ts +34 -9
  353. package/src/populate.test.ts +34 -0
  354. package/src/populate.ts +40 -29
  355. package/src/rateLimit/applyTrustProxy.ts +17 -0
  356. package/src/rateLimit/createStore.ts +25 -0
  357. package/src/rateLimit/memoryStore.ts +40 -0
  358. package/src/rateLimit/middleware.ts +79 -0
  359. package/src/rateLimit/mongoStore.test.ts +80 -0
  360. package/src/rateLimit/mongoStore.ts +77 -0
  361. package/src/rateLimit/policies.ts +130 -0
  362. package/src/rateLimit/rateLimit.test.ts +328 -0
  363. package/src/rateLimit/redisStore.ioredis.test.ts +29 -0
  364. package/src/rateLimit/redisStore.test.ts +114 -0
  365. package/src/rateLimit/redisStore.ts +86 -0
  366. package/src/rateLimit/types.ts +64 -0
  367. package/src/rbac/access.ts +16 -4
  368. package/src/rbac/assertAllowed.test.ts +325 -0
  369. package/src/rbac/assertAllowed.ts +157 -0
  370. package/src/rbac/backfillAdmins.test.ts +124 -0
  371. package/src/rbac/fieldViews.test.ts +89 -0
  372. package/src/rbac/membershipOrgAdminSource.ts +59 -0
  373. package/src/rbac/modelRouterAccess.test.ts +126 -0
  374. package/src/rbac/modelRouterAccess.ts +8 -2
  375. package/src/rbac/permissionUtils.test.ts +26 -5
  376. package/src/rbac/permissionUtils.ts +3 -2
  377. package/src/rbac/realtimeAccess.test.ts +109 -1
  378. package/src/rbac/resolve.test.ts +34 -2
  379. package/src/rbac/resolve.ts +31 -11
  380. package/src/rbac/roleManager.test.ts +169 -0
  381. package/src/rbac/roleModel.test.ts +34 -1
  382. package/src/rbac/roleModel.ts +17 -1
  383. package/src/rbac/routes.test.ts +233 -0
  384. package/src/rbac/routes.ts +16 -6
  385. package/src/rbac/statements.test.ts +19 -0
  386. package/src/rbac/statements.ts +19 -1
  387. package/src/rbac/types.ts +5 -0
  388. package/src/realtime/changeStreamWatcher.ts +73 -33
  389. package/src/realtime/deprecation.test.ts +60 -0
  390. package/src/realtime/deprecation.ts +33 -0
  391. package/src/realtime/realtime.test.ts +365 -189
  392. package/src/realtime/realtimeApp.ts +11 -11
  393. package/src/realtime/realtimeAppSetup.test.ts +32 -5
  394. package/src/realtime/registry.ts +48 -42
  395. package/src/realtime/sessionRevalidation.test.ts +57 -44
  396. package/src/realtime/socketAuth.test.ts +75 -23
  397. package/src/realtime/socketAuth.ts +17 -6
  398. package/src/realtime/socketUser.ts +5 -3
  399. package/src/realtime/types.ts +14 -4
  400. package/src/schemaMetadata.test.ts +419 -0
  401. package/src/schemaMetadata.ts +593 -0
  402. package/src/scrubAdminFields.test.ts +105 -0
  403. package/src/seedRunner.test.ts +591 -0
  404. package/src/seedRunner.ts +464 -0
  405. package/src/sync/adminBroadcastConfig.test.ts +96 -0
  406. package/src/sync/adminBroadcastScope.test.ts +155 -0
  407. package/src/sync/adminBroadcastScope.ts +123 -0
  408. package/src/sync/adminWindowAccess.test.ts +57 -0
  409. package/src/sync/adminWindowAccess.ts +32 -0
  410. package/src/sync/adminWindowMutation.test.ts +450 -0
  411. package/src/sync/adminWindowMutation.ts +283 -0
  412. package/src/sync/docMatchesMutationData.test.ts +16 -0
  413. package/src/sync/ensureSyncIndexes.test.ts +54 -15
  414. package/src/sync/executors.test.ts +40 -0
  415. package/src/sync/executors.ts +57 -18
  416. package/src/sync/integration.test.ts +15 -7
  417. package/src/sync/loadHarness.ts +28 -19
  418. package/src/sync/models.ts +32 -18
  419. package/src/sync/mutationHandler.test.ts +293 -17
  420. package/src/sync/mutationHandler.ts +180 -36
  421. package/src/sync/registrationSideEffects.test.ts +126 -0
  422. package/src/sync/registrationSideEffects.ts +131 -0
  423. package/src/sync/registry.ts +49 -171
  424. package/src/sync/routes.ts +55 -10
  425. package/src/sync/scripts/compactTombstones.ts +0 -2
  426. package/src/sync/sessionRevalidationIntegration.test.ts +12 -11
  427. package/src/sync/socketHandlers.ts +154 -58
  428. package/src/sync/streams.ts +6 -0
  429. package/src/sync/sync.test.ts +28 -25
  430. package/src/sync/syncApp.ts +5 -4
  431. package/src/sync/syncBatch.ts +10 -4
  432. package/src/sync/syncFrontier.test.ts +17 -15
  433. package/src/sync/syncPhaseC.test.ts +54 -43
  434. package/src/sync/syncRoutes.test.ts +347 -38
  435. package/src/sync/syncSeqPlugin.ts +66 -44
  436. package/src/sync/syncSocket.test.ts +341 -81
  437. package/src/sync/types.ts +20 -0
  438. package/src/terrenoApp.mcpServiceTokens.test.ts +173 -0
  439. package/src/terrenoApp.migrations.test.ts +114 -0
  440. package/src/terrenoApp.test.ts +41 -0
  441. package/src/terrenoApp.ts +181 -46
  442. package/src/tests/createTestData.ts +2 -2
  443. package/src/tests/models.ts +24 -3
  444. package/src/tests/testHelper.ts +1 -7
  445. package/src/types/authToken.ts +41 -0
  446. package/src/types/mcpServiceToken.ts +48 -0
  447. package/src/types/membership.ts +48 -0
  448. package/src/types/notification.ts +34 -0
  449. package/src/types/notificationPreference.ts +28 -0
  450. package/src/types/organization.ts +49 -0
  451. package/src/webhooks/headerValue.test.ts +22 -0
  452. package/src/webhooks/headerValue.ts +12 -0
  453. package/src/webhooks/idempotency/memoryStore.ts +34 -0
  454. package/src/webhooks/idempotency/mongoStore.test.ts +274 -0
  455. package/src/webhooks/idempotency/mongoStore.ts +83 -0
  456. package/src/webhooks/idempotency/webhookReceipt.ts +67 -0
  457. package/src/webhooks/rawBody.test.ts +107 -0
  458. package/src/webhooks/rawBody.ts +24 -0
  459. package/src/webhooks/timingSafeEqual.ts +16 -0
  460. package/src/webhooks/verifiers/hmac.test.ts +110 -0
  461. package/src/webhooks/verifiers/hmac.ts +54 -0
  462. package/src/webhooks/verifiers/providerVerifiers.test.ts +388 -0
  463. package/src/webhooks/verifiers/sendgrid.ts +59 -0
  464. package/src/webhooks/verifiers/stripe.ts +67 -0
  465. package/src/webhooks/verifiers/twilio.ts +69 -0
  466. package/src/webhooks/webhooksApp.test.ts +221 -0
  467. package/src/webhooks/webhooksApp.ts +144 -0
  468. package/tsconfig.json +1 -1
  469. package/tsconfig.typedoc.json +2 -1
  470. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.d.ts +0 -2
  471. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
  472. package/src/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
@@ -10,10 +10,12 @@ import {mongodbAdapter} from "better-auth/adapters/mongodb";
10
10
  import {toNodeHandler} from "better-auth/node";
11
11
  import {bearer} from "better-auth/plugins";
12
12
  import type {Application, NextFunction, Request, Response} from "express";
13
+ import type {Db} from "mongodb";
13
14
  import mongoose from "mongoose";
14
- import type {UserModel} from "./auth";
15
+ import {type HasSetPassword, setPasswordForUser, type UserModel} from "./auth";
15
16
  import type {BetterAuthConfig, BetterAuthSessionData, BetterAuthUser} from "./betterAuth";
16
17
  import {APIError} from "./errors";
18
+ import type {AuthRecoveryMail} from "./expressServer";
17
19
  import {logger} from "./logger";
18
20
  import {findOneOrNoneFor} from "./plugins";
19
21
  import {updateRequestContextFromRequest} from "./requestContext";
@@ -28,9 +30,7 @@ export type BetterAuthInstance = ReturnType<typeof betterAuth>;
28
30
  */
29
31
  // Minimal shape we use from the MongoDB native client returned by mongoose connection
30
32
  export interface MongoClientLike {
31
- // noExplicitAny: the MongoDB driver Db type is opaque to this layer; it is passed straight to better-auth's adapter
32
- // biome-ignore lint/suspicious/noExplicitAny: the MongoDB driver Db type is opaque to this layer; it is passed straight to better-auth's adapter
33
- db: () => any;
33
+ db: () => Db;
34
34
  }
35
35
 
36
36
  export interface CreateBetterAuthOptions {
@@ -39,6 +39,103 @@ export interface CreateBetterAuthOptions {
39
39
  userModel?: UserModel;
40
40
  }
41
41
 
42
+ const FALLBACK_AUTH_MAIL = {
43
+ resetPassword: {
44
+ html: '<p><a href="{{resetUrl}}">Reset your password</a></p>',
45
+ subject: "Reset your password",
46
+ text: "Reset your password using this link: {{resetUrl}}",
47
+ },
48
+ verifyEmail: {
49
+ html: '<p><a href="{{verifyUrl}}">Verify your email</a></p>',
50
+ subject: "Verify your email",
51
+ text: "Verify your email using this link: {{verifyUrl}}",
52
+ },
53
+ } as const;
54
+
55
+ const interpolateMail = (value: string, data: Record<string, string>): string =>
56
+ value.replace(/{{\s*([A-Za-z0-9_]+)\s*}}/g, (_match: string, key: string): string => {
57
+ return data[key] ?? "";
58
+ });
59
+
60
+ const fallbackRenderAuthMail = ({
61
+ publicAppUrl,
62
+ templateId,
63
+ token,
64
+ templates,
65
+ }: {
66
+ publicAppUrl: string;
67
+ templateId: "resetPassword" | "verifyEmail";
68
+ token: string;
69
+ templates?: BetterAuthConfig["authMailTemplates"];
70
+ }): {html?: string; subject: string; text?: string} => {
71
+ const template = templates?.[templateId] ?? FALLBACK_AUTH_MAIL[templateId];
72
+ const base = publicAppUrl.replace(/\/$/, "");
73
+ const resetUrl = `${base}/resetPassword?token=${encodeURIComponent(token)}`;
74
+ const verifyUrl = `${base}/verifyEmail?token=${encodeURIComponent(token)}`;
75
+ const data = {publicAppUrl: base, resetUrl, token, verifyUrl};
76
+ return {
77
+ html: template.html === undefined ? undefined : interpolateMail(template.html, data),
78
+ subject: interpolateMail(template.subject, data),
79
+ text: template.text === undefined ? undefined : interpolateMail(template.text, data),
80
+ };
81
+ };
82
+
83
+ export const createBetterAuthEmailHooks = (config: BetterAuthConfig) => {
84
+ if (!config.sendMail) {
85
+ return undefined;
86
+ }
87
+ const sendMail = config.sendMail;
88
+ const deliver = async (
89
+ templateId: "resetPassword" | "verifyEmail",
90
+ user: {email: string},
91
+ token: string
92
+ ): Promise<void> => {
93
+ const publicAppUrl = config.publicAppUrl ?? "";
94
+ if (!publicAppUrl) {
95
+ logger.error("[auth] publicAppUrl is required to send Better Auth recovery mail");
96
+ throw new APIError({
97
+ status: 501,
98
+ title: "publicAppUrl is required to send recovery mail",
99
+ });
100
+ }
101
+ const rendered = (config.renderAuthMail ?? fallbackRenderAuthMail)({
102
+ publicAppUrl,
103
+ templateId,
104
+ templates: config.authMailTemplates,
105
+ token,
106
+ });
107
+ const message: AuthRecoveryMail = {
108
+ html: rendered.html,
109
+ subject: rendered.subject,
110
+ text: rendered.text ?? "",
111
+ to: user.email,
112
+ };
113
+ await sendMail(message);
114
+ };
115
+ return {
116
+ sendResetPassword: async ({
117
+ token,
118
+ user,
119
+ }: {
120
+ token: string;
121
+ url: string;
122
+ user: {email: string};
123
+ }): Promise<void> => {
124
+ await deliver("resetPassword", user, token);
125
+ },
126
+ sendVerificationEmail: async ({
127
+ token,
128
+ user,
129
+ }: {
130
+ token: string;
131
+ url: string;
132
+ user: {email: string};
133
+ }): Promise<void> => {
134
+ await deliver("verifyEmail", user, token);
135
+ },
136
+ };
137
+ };
138
+
42
139
  /**
43
140
  * Creates a Better Auth instance with MongoDB adapter.
44
141
  */
@@ -86,6 +183,9 @@ export const createBetterAuth = (options: CreateBetterAuthOptions): BetterAuthIn
86
183
  };
87
184
  }
88
185
 
186
+ const emailHooks = createBetterAuthEmailHooks(config);
187
+ const userModel = options.userModel;
188
+
89
189
  const auth = betterAuth({
90
190
  advanced: config.crossDomainCookies
91
191
  ? {
@@ -101,13 +201,34 @@ export const createBetterAuth = (options: CreateBetterAuthOptions): BetterAuthIn
101
201
  database: mongodbAdapter(mongoClient.db()),
102
202
  emailAndPassword: {
103
203
  enabled: true,
204
+ revokeSessionsOnPasswordReset: true,
205
+ ...(emailHooks ? {sendResetPassword: emailHooks.sendResetPassword} : {}),
206
+ ...(userModel
207
+ ? {
208
+ onPasswordReset: async (
209
+ {user}: {user: {email?: string; id?: string}},
210
+ request?: PasswordResetRequestLike
211
+ ): Promise<void> => {
212
+ await applyBetterAuthPasswordResetToJwt(userModel, user, request);
213
+ },
214
+ }
215
+ : {}),
104
216
  },
217
+ ...(emailHooks
218
+ ? {
219
+ emailVerification: {
220
+ sendOnSignUp: true,
221
+ sendVerificationEmail: emailHooks.sendVerificationEmail,
222
+ },
223
+ }
224
+ : {}),
105
225
  // The bearer plugin lets clients authenticate with `Authorization: Bearer <sessionToken>`
106
226
  // instead of the signed session cookie. Required for cross-origin/native clients and for
107
227
  // websocket handshakes (RealtimeApp's Better Auth socket validator forwards the handshake
108
228
  // token as a bearer header) — without it, a raw session token cannot be validated and
109
229
  // socket auth silently fails (the sync client shows perpetually "offline").
110
230
  plugins: [bearer()],
231
+ rateLimit: config.disableRateLimit ? {enabled: false} : undefined,
111
232
  secret,
112
233
  session: {
113
234
  cookieCache: {
@@ -125,6 +246,141 @@ export const createBetterAuth = (options: CreateBetterAuthOptions): BetterAuthIn
125
246
  return auth as unknown as BetterAuthInstance;
126
247
  };
127
248
 
249
+ interface BetterAuthCredentialAccount {
250
+ providerId?: string;
251
+ }
252
+
253
+ interface BetterAuthUserLookup {
254
+ user?: {id?: string};
255
+ }
256
+
257
+ interface BetterAuthPasswordResetContext {
258
+ internalAdapter: {
259
+ createAccount: (account: {
260
+ accountId: string;
261
+ password: string;
262
+ providerId: string;
263
+ userId: string;
264
+ }) => Promise<unknown>;
265
+ deleteUserSessions: (userId: string) => Promise<unknown>;
266
+ findAccounts: (userId: string) => Promise<BetterAuthCredentialAccount[]>;
267
+ findUserByEmail: (email: string) => Promise<BetterAuthUserLookup | null>;
268
+ findUserById: (userId: string) => Promise<{id?: string} | null>;
269
+ updatePassword: (userId: string, password: string) => Promise<unknown>;
270
+ };
271
+ password: {hash: (password: string) => Promise<string>};
272
+ }
273
+
274
+ /**
275
+ * After JWT `POST /auth/resetPassword`, update the Better Auth credential hash
276
+ * (when that user exists) and delete Better Auth sessions so a dual-enrolled
277
+ * account cannot keep the old password or stolen sessions.
278
+ */
279
+ export const applyJwtPasswordResetToBetterAuth = async (
280
+ auth: BetterAuthInstance,
281
+ user: {betterAuthId?: string; email?: string},
282
+ password: string
283
+ ): Promise<void> => {
284
+ const ctx = (await auth.$context) as BetterAuthPasswordResetContext;
285
+ let betterAuthUserId = typeof user.betterAuthId === "string" ? user.betterAuthId : "";
286
+ if (!betterAuthUserId && typeof user.email === "string" && user.email.length > 0) {
287
+ const found = await ctx.internalAdapter.findUserByEmail(user.email);
288
+ betterAuthUserId = found?.user?.id ?? "";
289
+ }
290
+ if (!betterAuthUserId) {
291
+ const byId = user.betterAuthId
292
+ ? await ctx.internalAdapter.findUserById(user.betterAuthId)
293
+ : null;
294
+ betterAuthUserId = byId?.id ?? "";
295
+ }
296
+ if (!betterAuthUserId) {
297
+ return;
298
+ }
299
+ const hashedPassword = await ctx.password.hash(password);
300
+ const accounts = await ctx.internalAdapter.findAccounts(betterAuthUserId);
301
+ const hasCredential = accounts.some((account) => account.providerId === "credential");
302
+ if (hasCredential) {
303
+ await ctx.internalAdapter.updatePassword(betterAuthUserId, hashedPassword);
304
+ } else {
305
+ await ctx.internalAdapter.createAccount({
306
+ accountId: betterAuthUserId,
307
+ password: hashedPassword,
308
+ providerId: "credential",
309
+ userId: betterAuthUserId,
310
+ });
311
+ }
312
+ await ctx.internalAdapter.deleteUserSessions(betterAuthUserId);
313
+ };
314
+
315
+ interface PasswordResetRequestLike {
316
+ body?: unknown;
317
+ clone?: () => {json: () => Promise<unknown>};
318
+ }
319
+
320
+ const passwordFromUnknown = (value: unknown): string => {
321
+ if (!value || typeof value !== "object") {
322
+ return "";
323
+ }
324
+ const record = value as Record<string, unknown>;
325
+ const candidate = record.newPassword ?? record.password;
326
+ if (typeof candidate !== "string") {
327
+ return "";
328
+ }
329
+ return candidate;
330
+ };
331
+
332
+ export const readPasswordFromBetterAuthResetRequest = async (
333
+ request: PasswordResetRequestLike | undefined
334
+ ): Promise<string> => {
335
+ if (!request) {
336
+ return "";
337
+ }
338
+ const attached = passwordFromUnknown(request.body);
339
+ if (attached.length > 0) {
340
+ return attached;
341
+ }
342
+ if (typeof request.clone !== "function") {
343
+ return "";
344
+ }
345
+ try {
346
+ return passwordFromUnknown(await request.clone().json());
347
+ } catch {
348
+ return "";
349
+ }
350
+ };
351
+
352
+ /**
353
+ * After Better Auth password reset, update the JWT/passport hash and bump
354
+ * `tokenEpoch` so a dual-enrolled account cannot keep the old password or
355
+ * outstanding refresh tokens.
356
+ */
357
+ export const applyBetterAuthPasswordResetToJwt = async (
358
+ userModel: UserModel,
359
+ betterAuthUser: {email?: string; id?: string},
360
+ request: PasswordResetRequestLike | undefined
361
+ ): Promise<void> => {
362
+ const betterAuthId = typeof betterAuthUser.id === "string" ? betterAuthUser.id : "";
363
+ const email = typeof betterAuthUser.email === "string" ? betterAuthUser.email : "";
364
+ let appUser = betterAuthId ? await findOneOrNoneFor(userModel, {betterAuthId} as never) : null;
365
+ if (!appUser && email.length > 0) {
366
+ appUser = await findOneOrNoneFor(userModel, {email} as never);
367
+ }
368
+ if (!appUser) {
369
+ return;
370
+ }
371
+ const password = await readPasswordFromBetterAuthResetRequest(request);
372
+ if (!password) {
373
+ logger.error("[auth] Better Auth password reset did not include a password to sync to JWT");
374
+ throw new APIError({
375
+ status: 500,
376
+ title: "Password reset could not sync to JWT credentials",
377
+ });
378
+ }
379
+ await setPasswordForUser(appUser as unknown as HasSetPassword, password);
380
+ appUser.tokenEpoch = (appUser.tokenEpoch ?? 0) + 1;
381
+ await appUser.save();
382
+ };
383
+
128
384
  /**
129
385
  * Creates Express middleware that extracts the Better Auth session
130
386
  * and populates req.user with the application User model.
@@ -246,7 +502,7 @@ export const syncBetterAuthUser = async (
246
502
  betterAuthId: betterAuthUser.id,
247
503
  email: betterAuthUser.email,
248
504
  name: betterAuthUser.name || betterAuthUser.email.split("@")[0],
249
- oauthProvider: oauthProvider || null,
505
+ ...(oauthProvider ? {oauthProvider} : {}),
250
506
  });
251
507
  await newUser.save();
252
508
  logger.info(`Created new user from Better Auth: ${newUser.id}`);
@@ -0,0 +1,164 @@
1
+ import {beforeEach, describe, expect, it} from "bun:test";
2
+ import {model, Schema} from "mongoose";
3
+ import {
4
+ clearCollectionRegistry,
5
+ getCollection,
6
+ listCollections,
7
+ registerCollection,
8
+ replaceCollectionOptions,
9
+ } from "./collectionRegistry";
10
+ import {clearMCPRegistry, getMCPRegistry} from "./mcp/registry";
11
+ import {Permissions} from "./permissions";
12
+ import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "./plugins";
13
+ import {trackSyncIndexCreation} from "./sync/registrationSideEffects";
14
+ import {clearSyncRegistry, getSyncRegistry, registerSync} from "./sync/registry";
15
+ import {syncPlugin} from "./sync/syncSeqPlugin";
16
+ import {FoodModel} from "./tests";
17
+
18
+ interface CatalogTodo extends IsDeleted {
19
+ _id: string;
20
+ ownerId: string;
21
+ title: string;
22
+ _syncSeq?: number;
23
+ }
24
+
25
+ const catalogTodoSchema = new Schema<CatalogTodo>({
26
+ ownerId: {description: "The owner", type: String},
27
+ title: {description: "The title", required: true, type: String},
28
+ });
29
+ catalogTodoSchema.plugin(isDeletedPlugin);
30
+ catalogTodoSchema.plugin(createdUpdatedPlugin);
31
+ catalogTodoSchema.plugin(syncPlugin);
32
+ const CatalogTodoModel = model<CatalogTodo>("CatalogTodo", catalogTodoSchema);
33
+
34
+ const syncOptions = {
35
+ permissions: {
36
+ create: [Permissions.IsAuthenticated],
37
+ delete: [Permissions.IsAuthenticated],
38
+ list: [Permissions.IsAuthenticated],
39
+ read: [Permissions.IsAuthenticated],
40
+ update: [Permissions.IsAuthenticated],
41
+ },
42
+ sync: {scope: {type: "owner"}},
43
+ } as const;
44
+
45
+ const baseOptions = {
46
+ permissions: {
47
+ create: [Permissions.IsAny],
48
+ delete: [Permissions.IsAny],
49
+ list: [Permissions.IsAny],
50
+ read: [Permissions.IsAny],
51
+ update: [Permissions.IsAny],
52
+ },
53
+ };
54
+
55
+ describe("CollectionRegistry", () => {
56
+ beforeEach(() => {
57
+ clearCollectionRegistry();
58
+ });
59
+
60
+ it("stores one catalog record per route path on registerCollection", () => {
61
+ registerCollection({
62
+ model: FoodModel,
63
+ options: baseOptions,
64
+ routePath: "/food",
65
+ });
66
+
67
+ const record = getCollection("/food");
68
+ expect(record?.routePath).toBe("/food");
69
+ expect(record?.model).toBe(FoodModel);
70
+ expect(record?.options).toBe(baseOptions);
71
+ expect(listCollections()).toHaveLength(1);
72
+ });
73
+
74
+ it("replaceCollectionOptions updates options for a registered path", () => {
75
+ registerCollection({
76
+ model: FoodModel,
77
+ options: baseOptions,
78
+ routePath: "/food",
79
+ });
80
+ const updatedOptions = {
81
+ ...baseOptions,
82
+ permissions: {...baseOptions.permissions, list: [Permissions.IsAuthenticated]},
83
+ };
84
+ replaceCollectionOptions("/food", updatedOptions);
85
+
86
+ expect(getCollection("/food")?.options).toBe(updatedOptions);
87
+ });
88
+
89
+ it("replaceCollectionOptions no-ops when the route path is unknown", () => {
90
+ registerCollection({
91
+ model: FoodModel,
92
+ options: baseOptions,
93
+ routePath: "/food",
94
+ });
95
+ const originalOptions = getCollection("/food")?.options;
96
+ replaceCollectionOptions("/missing", {
97
+ permissions: {},
98
+ } as never);
99
+
100
+ expect(getCollection("/food")?.options).toBe(originalOptions);
101
+ });
102
+
103
+ it("replaceCollectionOptions updates MCP registry views with the same options object", () => {
104
+ clearMCPRegistry();
105
+ registerCollection({
106
+ model: FoodModel,
107
+ options: {...baseOptions, mcp: {methods: ["list"]}},
108
+ routePath: "/food",
109
+ });
110
+ const updatedOptions = {
111
+ ...baseOptions,
112
+ mcp: {methods: ["read"]},
113
+ } as typeof baseOptions & {mcp: {methods: ["read"]}};
114
+ replaceCollectionOptions("/food", updatedOptions);
115
+
116
+ expect(getCollection("/food")?.options).toBe(updatedOptions);
117
+ expect(getMCPRegistry()[0]?.options).toBe(updatedOptions);
118
+ });
119
+
120
+ it("replaceCollectionOptions updates sync registry views with the same options object", () => {
121
+ clearSyncRegistry();
122
+ registerSync({
123
+ config: {scope: {type: "owner"}},
124
+ model: CatalogTodoModel,
125
+ options: syncOptions,
126
+ routePath: "/catalogTodos",
127
+ });
128
+ const updatedOptions = {
129
+ ...syncOptions,
130
+ permissions: {...syncOptions.permissions, list: [Permissions.IsAny]},
131
+ };
132
+ replaceCollectionOptions("/catalogTodos", updatedOptions);
133
+
134
+ expect(getCollection("/catalogTodos")?.options).toBe(updatedOptions);
135
+ expect(getSyncRegistry()[0]?.options).toBe(updatedOptions);
136
+ });
137
+
138
+ it("treats re-registering the same model at the same route path as a no-op", () => {
139
+ clearSyncRegistry();
140
+ registerSync({
141
+ config: {scope: {type: "owner"}},
142
+ model: CatalogTodoModel,
143
+ options: syncOptions,
144
+ routePath: "/catalogTodos",
145
+ });
146
+ registerSync({
147
+ config: {scope: {type: "owner"}},
148
+ model: CatalogTodoModel,
149
+ options: syncOptions,
150
+ routePath: "/catalogTodos",
151
+ });
152
+ expect(getSyncRegistry()).toHaveLength(1);
153
+ });
154
+
155
+ it("clearCollectionRegistry resets deferred sync index tasks", async () => {
156
+ clearCollectionRegistry();
157
+ trackSyncIndexCreation(async () => {
158
+ throw new Error("should not run");
159
+ });
160
+ clearCollectionRegistry();
161
+ const {ensureSyncIndexes} = await import("./sync/registrationSideEffects");
162
+ await expect(ensureSyncIndexes()).resolves.toBeUndefined();
163
+ });
164
+ });
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Process-global catalog of modelRouter collections, keyed by routePath
3
+ * (e.g. `/todos`). MCP, realtime, and Sync read this Map instead of each
4
+ * keeping their own list. `modelRouter` is the writer; surface `register*`
5
+ * / `update*` / `clear*` helpers are wrappers around this module.
6
+ *
7
+ * TerrenoApp later injects `accessControl` into options. That patch goes
8
+ * through replaceCollectionOptions so all three surfaces see one options
9
+ * object. Surface flags stay sticky (OR) so a later replace cannot drop
10
+ * mcp/realtime/sync once enabled. First-time sync enable still runs schema
11
+ * and index guards in registrationSideEffects — not here — so catalog
12
+ * writes stay a Map update.
13
+ */
14
+ import type {Model} from "mongoose";
15
+
16
+ import type {ModelRouterOptions} from "./api";
17
+ import {APIError} from "./errors";
18
+ import {
19
+ applySyncRegistrationSideEffects,
20
+ clearSyncIndexCreationTasks,
21
+ } from "./sync/registrationSideEffects";
22
+ import type {SyncConfig} from "./sync/types";
23
+
24
+ const withAdminBroadcastDefault = (config: SyncConfig): SyncConfig => ({
25
+ ...config,
26
+ adminBroadcast: config.adminBroadcast === true,
27
+ });
28
+
29
+ /** Store `adminBroadcast: false` when the host omitted the flag (default). */
30
+ const applyAdminBroadcastDefault = (options: ModelRouterOptions<unknown>): void => {
31
+ if (!options.sync) {
32
+ return;
33
+ }
34
+ options.sync = withAdminBroadcastDefault(options.sync);
35
+ };
36
+
37
+ interface CollectionSurfaces {
38
+ mcp: boolean;
39
+ realtime: boolean;
40
+ sync: boolean;
41
+ }
42
+
43
+ export interface CollectionRecord {
44
+ model: Model<unknown>;
45
+ options: ModelRouterOptions<unknown>;
46
+ routePath: string;
47
+ surfaces: CollectionSurfaces;
48
+ }
49
+
50
+ const collectionRegistry = new Map<string, CollectionRecord>();
51
+
52
+ /** OR new option flags onto existing ones so a patch cannot disable a surface. */
53
+ const deriveSurfaces = (
54
+ options: ModelRouterOptions<unknown>,
55
+ existing?: CollectionSurfaces
56
+ ): CollectionSurfaces => ({
57
+ mcp: Boolean(options.mcp) || (existing?.mcp ?? false),
58
+ realtime: Boolean(options.realtime) || (existing?.realtime ?? false),
59
+ sync: Boolean(options.sync) || (existing?.sync ?? false),
60
+ });
61
+
62
+ /** Insert or merge a collection. First sync enable runs schema/index guards. */
63
+ export const registerCollection = <T>({
64
+ model,
65
+ options,
66
+ routePath,
67
+ }: {
68
+ model: Model<T>;
69
+ options: ModelRouterOptions<T>;
70
+ routePath: string;
71
+ }): void => {
72
+ applyAdminBroadcastDefault(options as ModelRouterOptions<unknown>);
73
+ const existing = collectionRegistry.get(routePath);
74
+ const wasSyncEnabled = existing?.surfaces.sync ?? false;
75
+
76
+ if (options.sync && wasSyncEnabled) {
77
+ if (existing?.model.modelName === model.modelName) {
78
+ return;
79
+ }
80
+ const collectionTag = routePath.replace(/^\//, "");
81
+ throw new APIError({
82
+ status: 500,
83
+ title:
84
+ `Sync collection tag "${collectionTag}" is already registered (routePath ${routePath}). ` +
85
+ "Each synced model must have a unique route path.",
86
+ });
87
+ }
88
+
89
+ if (options.sync && !wasSyncEnabled) {
90
+ applySyncRegistrationSideEffects({
91
+ config: options.sync,
92
+ existingSyncEntries: listCollections()
93
+ .filter((record) => record.surfaces.sync)
94
+ .map((record) => ({
95
+ collectionTag: record.routePath.replace(/^\//, ""),
96
+ modelName: record.model.modelName,
97
+ })),
98
+ model,
99
+ options,
100
+ routePath,
101
+ });
102
+ }
103
+
104
+ collectionRegistry.set(routePath, {
105
+ model: model as unknown as Model<unknown>,
106
+ options: options as ModelRouterOptions<unknown>,
107
+ routePath,
108
+ surfaces: deriveSurfaces(options as ModelRouterOptions<unknown>, existing?.surfaces),
109
+ });
110
+ };
111
+
112
+ /** Swap the options pointer after TerrenoApp enriches it. Unknown path is a no-op. */
113
+ export const replaceCollectionOptions = (
114
+ routePath: string,
115
+ options: ModelRouterOptions<unknown>
116
+ ): void => {
117
+ const existing = collectionRegistry.get(routePath);
118
+ if (!existing) {
119
+ return;
120
+ }
121
+ applyAdminBroadcastDefault(options);
122
+ existing.options = options;
123
+ };
124
+
125
+ /** @internal */
126
+ export const getCollection = (routePath: string): CollectionRecord | undefined =>
127
+ collectionRegistry.get(routePath);
128
+
129
+ export const listCollections = (): CollectionRecord[] => Array.from(collectionRegistry.values());
130
+
131
+ /** Wipe the catalog and queued sync indexes so tests cannot leave a stale surface. */
132
+ export const clearCollectionRegistry = (): void => {
133
+ collectionRegistry.clear();
134
+ clearSyncIndexCreationTasks();
135
+ };
@@ -127,14 +127,22 @@ export type ConfigurationPostUpdateHook = (
127
127
  req: express.Request
128
128
  ) => void | Promise<void>;
129
129
 
130
+ /**
131
+ * The subset of a Mongoose model that ConfigurationApp inspects. Structural (rather than
132
+ * `Model<T>`) so consumers can pass any configuration model without generic invariance
133
+ * issues; the configurationPlugin statics are looked up at registration time.
134
+ */
135
+ export interface ConfigurationModelLike {
136
+ modelName: string;
137
+ schema: Schema;
138
+ }
139
+
130
140
  /**
131
141
  * Options for ConfigurationApp.
132
142
  */
133
143
  export interface ConfigurationAppOptions {
134
144
  /** The Mongoose model with configurationPlugin applied. */
135
- // noExplicitAny: Model<any> required for invariance — consumers pass arbitrary configuration models
136
- // biome-ignore lint/suspicious/noExplicitAny: Model<any> required for invariance — consumers pass arbitrary configuration models
137
- model: Model<any>;
145
+ model: ConfigurationModelLike;
138
146
  /** Base path for configuration routes. Defaults to "/configuration". */
139
147
  basePath?: string;
140
148
  /** Per-field widget overrides (e.g., {"ai.systemPrompt": "markdown"}). */
@@ -357,7 +365,7 @@ export class ConfigurationApp implements TerrenoPlugin {
357
365
  const schema = ConfigModel.schema;
358
366
 
359
367
  // Build metadata by inspecting the schema
360
- const meta = this.buildMetadata(ConfigModel, schema);
368
+ const meta = this.buildMetadata(schema);
361
369
 
362
370
  // GET /configuration/meta — schema metadata for the frontend
363
371
  app.get(
@@ -479,9 +487,7 @@ export class ConfigurationApp implements TerrenoPlugin {
479
487
  * Top-level fields with subschemas become sections.
480
488
  * Top-level scalar fields go into a "General" section.
481
489
  */
482
- // noExplicitAny: Model<any> required for invariance with consumer-supplied configuration models
483
- // biome-ignore lint/suspicious/noExplicitAny: Model<any> required for invariance with consumer-supplied configuration models
484
- private buildMetadata(_model: Model<any>, schema: Schema): ConfigurationMetaResponse {
490
+ private buildMetadata(schema: Schema): ConfigurationMetaResponse {
485
491
  const sections: ConfigSectionMeta[] = [];
486
492
  const generalFields: Record<string, ConfigFieldMeta> = {};
487
493