@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
@@ -1,12 +1,18 @@
1
- // noExplicitAny: the mutation handler operates generically across registered models
2
- // biome-ignore-all lint/suspicious/noExplicitAny: the mutation handler operates generically across registered models
3
1
  import type express from "express";
4
2
  import {DateTime} from "luxon";
5
3
  import mongoose from "mongoose";
6
4
  import type {User} from "../auth";
7
5
  import {APIError, isAPIError} from "../errors";
8
6
  import {createFeatureFlaggedLogger, logger} from "../logger";
7
+ import {resolveOrgContext, runWithOrgContext} from "../orgs/orgContext";
9
8
  import {findOneOrNoneFor} from "../plugins";
9
+ import {
10
+ type AdminWindowMutationScope,
11
+ buildAdminWindowExecutorOptions,
12
+ emitAdminWindowMutationAudit,
13
+ prepareAdminWindowMutation,
14
+ withAdminWindowMutationRequestContext,
15
+ } from "./adminWindowMutation";
10
16
  import {
11
17
  executeCreate,
12
18
  executeDelete,
@@ -18,6 +24,7 @@ import {
18
24
  } from "./executors";
19
25
  import {SYNC_MUTATION_LEASE_MS, SyncMutation, type SyncMutationDocument} from "./models";
20
26
  import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
27
+ import type {SyncAppOptions} from "./routes";
21
28
  import {serializeSyncDoc} from "./routes";
22
29
  import {getScopeField} from "./streams";
23
30
  import type {
@@ -257,7 +264,7 @@ const takeoverStaleLease = async (
257
264
  const cutoff = DateTime.now().minus({milliseconds: SYNC_MUTATION_LEASE_MS}).toJSDate();
258
265
  const claimed = await SyncMutation.findOneAndUpdate(
259
266
  {claimedAt: {$lt: cutoff}, mutationId, status: "pending"},
260
- {$set: {claimedAt: new Date()}},
267
+ {$set: {claimedAt: DateTime.now().toJSDate()}},
261
268
  {new: true}
262
269
  );
263
270
  return claimed ?? undefined;
@@ -305,7 +312,7 @@ const waitForRecordedOutcome = async ({
305
312
  if (takenOver) {
306
313
  logger.warn("[sync] Took over a stale mutation lease", {
307
314
  mutationId,
308
- staleForMs: Date.now() - new Date(row.claimedAt).getTime(),
315
+ staleForMs: DateTime.now().diff(DateTime.fromJSDate(row.claimedAt)).toMillis(),
309
316
  });
310
317
  return onTakeover(takenOver);
311
318
  }
@@ -343,7 +350,7 @@ const isE11000Error = (error: unknown): boolean => {
343
350
  * different write landed and happens to have advanced the seq by exactly
344
351
  * one" (a real conflict; a seq match alone cannot tell these apart).
345
352
  */
346
- const docMatchesMutationData = (
353
+ export const docMatchesMutationData = (
347
354
  doc: unknown,
348
355
  data: Record<string, unknown> | undefined
349
356
  ): boolean => {
@@ -358,7 +365,11 @@ const docMatchesMutationData = (
358
365
  return Object.entries(data).every(([key, value]) => {
359
366
  const current = plain?.[key];
360
367
  if (current instanceof Date && typeof value === "string") {
361
- return current.toISOString() === new Date(value).toISOString();
368
+ const parsed = DateTime.fromISO(value, {zone: "utc"});
369
+ if (!parsed.isValid) {
370
+ return false;
371
+ }
372
+ return current.toISOString() === parsed.toJSDate().toISOString();
362
373
  }
363
374
  return JSON.stringify(current) === JSON.stringify(value);
364
375
  });
@@ -509,6 +520,38 @@ const finalizeAlreadyApplied = async ({
509
520
  * - delete: idempotent already (executeDelete on an already-deleted tombstone is a no-op
510
521
  * success in this codebase's soft-delete model), so no special tolerance is needed.
511
522
  */
523
+ const organizationIdFromRequest = (request: express.Request): string | undefined => {
524
+ if (typeof request.header !== "function") {
525
+ return undefined;
526
+ }
527
+ const raw = request.header("X-Organization-Id");
528
+ if (typeof raw !== "string") {
529
+ return undefined;
530
+ }
531
+ const trimmed = raw.trim();
532
+ if (!trimmed) {
533
+ return undefined;
534
+ }
535
+ return trimmed;
536
+ };
537
+
538
+ const withRequestOrgContext = async ({
539
+ request,
540
+ run,
541
+ user,
542
+ }: {
543
+ request: express.Request;
544
+ run: () => Promise<SyncMutationOutcome>;
545
+ user: User;
546
+ }): Promise<SyncMutationOutcome> => {
547
+ const organizationId = organizationIdFromRequest(request);
548
+ if (!organizationId) {
549
+ return run();
550
+ }
551
+ const context = await resolveOrgContext({organizationId, required: false, user});
552
+ return runWithOrgContext(context, run);
553
+ };
554
+
512
555
  const applyClaimedMutation = async ({
513
556
  claimed,
514
557
  entry,
@@ -516,6 +559,7 @@ const applyClaimedMutation = async ({
516
559
  request,
517
560
  user,
518
561
  scopeResolver,
562
+ syncOptions,
519
563
  isLeaseTakeover = false,
520
564
  }: {
521
565
  claimed: SyncMutationDocument;
@@ -524,44 +568,103 @@ const applyClaimedMutation = async ({
524
568
  request: express.Request;
525
569
  user: User;
526
570
  scopeResolver?: SyncMutationScopeResolver;
571
+ syncOptions?: SyncAppOptions;
527
572
  /** True when `claimed` was re-claimed from a stale lease rather than freshly inserted. */
528
573
  isLeaseTakeover?: boolean;
574
+ }): Promise<SyncMutationOutcome> => {
575
+ return withRequestOrgContext({
576
+ request,
577
+ run: () =>
578
+ applyClaimedMutationInContext({
579
+ claimed,
580
+ entry,
581
+ isLeaseTakeover,
582
+ mutation,
583
+ request,
584
+ scopeResolver,
585
+ syncOptions,
586
+ user,
587
+ }),
588
+ user,
589
+ });
590
+ };
591
+
592
+ const applyClaimedMutationInContext = async ({
593
+ claimed,
594
+ entry,
595
+ mutation,
596
+ request,
597
+ user,
598
+ scopeResolver,
599
+ syncOptions,
600
+ isLeaseTakeover = false,
601
+ }: {
602
+ claimed: SyncMutationDocument;
603
+ entry: SyncRegistryEntry;
604
+ mutation: SyncMutateRequest;
605
+ request: express.Request;
606
+ user: User;
607
+ scopeResolver?: SyncMutationScopeResolver;
608
+ syncOptions?: SyncAppOptions;
609
+ isLeaseTakeover?: boolean;
529
610
  }): Promise<SyncMutationOutcome> => {
530
611
  const mutationId = mutation.mutationId;
612
+ let adminWindowScope: AdminWindowMutationScope | undefined;
531
613
 
532
614
  try {
533
615
  // Task 9.18: resolving the model must be INSIDE the try — a MissingSchemaError thrown
534
616
  // here would escape without finalizing the claimed row, wedging the mutationId
535
617
  // `pending` for the whole lease window instead of nacking it.
536
618
  const model = mongoose.model(entry.modelName);
537
- // C6 (M6): sync-boundary write-scope backstop before any write pipeline runs.
538
- await enforceWriteScope({
539
- data: mutation.data,
619
+ const adminWindow = await prepareAdminWindowMutation({
540
620
  entry,
541
- operation: mutation.operation,
542
- scopeResolver,
621
+ mutation,
622
+ req: request,
623
+ syncOptions,
543
624
  user,
544
625
  });
626
+ let effectiveMutation = mutation;
627
+ if (adminWindow) {
628
+ effectiveMutation = adminWindow.mutation;
629
+ adminWindowScope = adminWindow.scope;
630
+ } else {
631
+ // C6 (M6): product-path write-scope backstop before any write pipeline runs.
632
+ await enforceWriteScope({
633
+ data: effectiveMutation.data,
634
+ entry,
635
+ operation: effectiveMutation.operation,
636
+ scopeResolver,
637
+ user,
638
+ });
639
+ }
640
+ const skipPermissionChecks = Boolean(adminWindowScope);
641
+ const executorOptions = adminWindowScope
642
+ ? buildAdminWindowExecutorOptions({productOptions: entry.options, scope: adminWindowScope})
643
+ : entry.options;
644
+ const executorRequest = adminWindowScope
645
+ ? withAdminWindowMutationRequestContext({mutation: effectiveMutation, req: request})
646
+ : request;
545
647
 
546
648
  let doc: mongoose.Document;
547
649
  let postHook: (() => Promise<void>) | undefined;
548
- if (mutation.operation === "create") {
549
- const body: Record<string, unknown> = {...(mutation.data ?? {})};
550
- if (mutation.id) {
551
- body._id = mutation.id;
650
+ if (effectiveMutation.operation === "create") {
651
+ const body: Record<string, unknown> = {...(effectiveMutation.data ?? {})};
652
+ if (effectiveMutation.id) {
653
+ body._id = effectiveMutation.id;
552
654
  }
553
655
  try {
554
656
  const result = await executeCreate({
555
657
  body,
556
658
  model,
557
- options: entry.options,
558
- req: request,
659
+ options: executorOptions,
660
+ req: executorRequest,
661
+ skipPermissionChecks,
559
662
  skipPostHooks: true,
560
663
  user,
561
664
  });
562
665
  doc = result.doc;
563
666
  postHook = (): Promise<void> =>
564
- runPostCreate({doc: result.doc, options: entry.options, request});
667
+ runPostCreate({doc: result.doc, options: executorOptions, request: executorRequest});
565
668
  } catch (createError: unknown) {
566
669
  // M4 (lease takeover only): an E11000 on the exact target _id is
567
670
  // tolerated as "already applied" — a prior (crashed) attempt at
@@ -570,8 +673,12 @@ const applyClaimedMutation = async ({
570
673
  // client-minted UUIDs make a genuine unrelated _id collision
571
674
  // vanishingly unlikely, so gating this on isLeaseTakeover keeps the
572
675
  // tolerance scoped to its actual crash-recovery purpose.
573
- if (isLeaseTakeover && isE11000Error(createError) && typeof mutation.id === "string") {
574
- const existing = await findOneOrNoneFor(model, {_id: mutation.id});
676
+ if (
677
+ isLeaseTakeover &&
678
+ isE11000Error(createError) &&
679
+ typeof effectiveMutation.id === "string"
680
+ ) {
681
+ const existing = await findOneOrNoneFor(model, {_id: effectiveMutation.id});
575
682
  if (existing) {
576
683
  const {resultId, resultSeq} = await finalizeAlreadyApplied({
577
684
  claimedId: claimed._id,
@@ -583,15 +690,16 @@ const applyClaimedMutation = async ({
583
690
  }
584
691
  throw createError;
585
692
  }
586
- } else if (mutation.operation === "update") {
693
+ } else if (effectiveMutation.operation === "update") {
587
694
  try {
588
695
  const result = await executeUpdate({
589
- body: mutation.data ?? {},
590
- concurrencyCheck: {baseSeq: mutation.baseVersion ?? 0, type: "seq"},
591
- id: mutation.id as string,
696
+ body: effectiveMutation.data ?? {},
697
+ concurrencyCheck: {baseSeq: effectiveMutation.baseVersion ?? 0, type: "seq"},
698
+ id: effectiveMutation.id as string,
592
699
  model,
593
- options: entry.options,
594
- req: request,
700
+ options: executorOptions,
701
+ req: executorRequest,
702
+ skipPermissionChecks,
595
703
  skipPostHooks: true,
596
704
  user,
597
705
  });
@@ -601,7 +709,13 @@ const applyClaimedMutation = async ({
601
709
  // biome-ignore lint/style/noNonNullAssertion: executeUpdate with skipPostHooks always returns cleanedBody/prevDoc.
602
710
  const prevDoc = result.prevDoc!;
603
711
  postHook = (): Promise<void> =>
604
- runPostUpdate({cleanedBody, doc: result.doc, options: entry.options, prevDoc, request});
712
+ runPostUpdate({
713
+ cleanedBody,
714
+ doc: result.doc,
715
+ options: executorOptions,
716
+ prevDoc,
717
+ request: executorRequest,
718
+ });
605
719
  } catch (updateError: unknown) {
606
720
  // M4 (lease takeover only): a conflict whose serverSeq is EXACTLY
607
721
  // this mutation's own expected post-write seq COULD mean the write
@@ -617,8 +731,8 @@ const applyClaimedMutation = async ({
617
731
  isLeaseTakeover &&
618
732
  isExecutorConflictError(updateError) &&
619
733
  updateError.conflictType === "seq" &&
620
- updateError.serverSeq === (mutation.baseVersion ?? 0) + 1 &&
621
- docMatchesMutationData(updateError.doc, mutation.data)
734
+ updateError.serverSeq === (effectiveMutation.baseVersion ?? 0) + 1 &&
735
+ docMatchesMutationData(updateError.doc, effectiveMutation.data)
622
736
  ) {
623
737
  const {resultId, resultSeq} = await finalizeAlreadyApplied({
624
738
  claimedId: claimed._id,
@@ -631,16 +745,17 @@ const applyClaimedMutation = async ({
631
745
  }
632
746
  } else {
633
747
  const result = await executeDelete({
634
- id: mutation.id as string,
748
+ id: effectiveMutation.id as string,
635
749
  model,
636
- options: entry.options,
637
- req: request,
750
+ options: executorOptions,
751
+ req: executorRequest,
752
+ skipPermissionChecks,
638
753
  skipPostHooks: true,
639
754
  user,
640
755
  });
641
756
  doc = result.doc;
642
757
  postHook = (): Promise<void> =>
643
- runPostDelete({doc: result.doc, options: entry.options, request});
758
+ runPostDelete({doc: result.doc, options: executorOptions, request: executorRequest});
644
759
  }
645
760
 
646
761
  const resultId = String(doc._id);
@@ -668,6 +783,22 @@ const applyClaimedMutation = async ({
668
783
  mutationId,
669
784
  });
670
785
  }
786
+ if (adminWindowScope?.emitAudit) {
787
+ try {
788
+ await emitAdminWindowMutationAudit({
789
+ doc,
790
+ mutation: effectiveMutation,
791
+ req: executorRequest,
792
+ scope: adminWindowScope,
793
+ });
794
+ } catch (auditError: unknown) {
795
+ logger.error("[sync] Admin window audit hook failed after a committed mutation", {
796
+ collection: mutation.collection,
797
+ error: errorMessageOf(auditError),
798
+ mutationId,
799
+ });
800
+ }
801
+ }
671
802
  return {
672
803
  ack: {id: resultId, mutationId, seq: resultSeq, ...(warning ? {warning} : {})},
673
804
  type: "ack",
@@ -690,12 +821,14 @@ export const applySyncMutation = async ({
690
821
  mutation,
691
822
  req,
692
823
  scopeResolver,
824
+ syncOptions,
693
825
  }: {
694
826
  user: User;
695
827
  mutation: SyncMutateRequest;
696
828
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
697
829
  req?: express.Request;
698
830
  scopeResolver?: SyncMutationScopeResolver;
831
+ syncOptions?: SyncAppOptions;
699
832
  }): Promise<SyncMutationOutcome> => {
700
833
  const mutationId = typeof mutation?.mutationId === "string" ? mutation.mutationId : "";
701
834
  const validationNack = (message: string): SyncMutationOutcome =>
@@ -731,7 +864,7 @@ export const applySyncMutation = async ({
731
864
  let claimed: SyncMutationDocument;
732
865
  try {
733
866
  claimed = await SyncMutation.create({
734
- claimedAt: new Date(),
867
+ claimedAt: DateTime.now().toJSDate(),
735
868
  mutationId,
736
869
  status: "pending",
737
870
  userId: String(user.id),
@@ -751,6 +884,7 @@ export const applySyncMutation = async ({
751
884
  mutation,
752
885
  request,
753
886
  scopeResolver,
887
+ syncOptions,
754
888
  user,
755
889
  }),
756
890
  request,
@@ -758,7 +892,15 @@ export const applySyncMutation = async ({
758
892
  });
759
893
  }
760
894
 
761
- return applyClaimedMutation({claimed, entry, mutation, request, scopeResolver, user});
895
+ return applyClaimedMutation({
896
+ claimed,
897
+ entry,
898
+ mutation,
899
+ request,
900
+ scopeResolver,
901
+ syncOptions,
902
+ user,
903
+ });
762
904
  };
763
905
 
764
906
  /** Outcome of a batch validation pre-check (before any mutation is attempted). */
@@ -829,16 +971,18 @@ export const applySyncMutationBatch = async ({
829
971
  mutations,
830
972
  req,
831
973
  scopeResolver,
974
+ syncOptions,
832
975
  }: {
833
976
  user: User;
834
977
  mutations: SyncMutateRequest[];
835
978
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
836
979
  req?: express.Request;
837
980
  scopeResolver?: SyncMutationScopeResolver;
981
+ syncOptions?: SyncAppOptions;
838
982
  }): Promise<SyncMutateBatchResponse> => {
839
983
  const results: SyncMutateBatchResponse["results"] = [];
840
984
  for (const mutation of mutations) {
841
- const outcome = await applySyncMutation({mutation, req, scopeResolver, user});
985
+ const outcome = await applySyncMutation({mutation, req, scopeResolver, syncOptions, user});
842
986
  results.push(outcome);
843
987
  if (outcome.type === "nack") {
844
988
  // Stop-on-error: the client re-sends everything after this point, and
@@ -0,0 +1,126 @@
1
+ import {beforeEach, describe, expect, it} from "bun:test";
2
+ import {model, Schema} from "mongoose";
3
+
4
+ import type {ModelRouterOptions} from "../api";
5
+ import {registerCollection} from "../collectionRegistry";
6
+ import {Permissions} from "../permissions";
7
+ import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
8
+ import {
9
+ applySyncRegistrationSideEffects,
10
+ clearSyncIndexCreationTasks,
11
+ ensureSyncIndexes,
12
+ trackSyncIndexCreation,
13
+ } from "./registrationSideEffects";
14
+ import {clearSyncRegistry, registerSync} from "./registry";
15
+ import {syncPlugin} from "./syncSeqPlugin";
16
+
17
+ interface SideEffectTodo extends IsDeleted {
18
+ _id: string;
19
+ ownerId: string;
20
+ title: string;
21
+ _syncSeq?: number;
22
+ }
23
+
24
+ const buildModel = (name: string, extraFields: Record<string, unknown> = {}) => {
25
+ const schema = new Schema<SideEffectTodo>({
26
+ ownerId: {description: "The owner", type: String},
27
+ title: {description: "The title", required: true, type: String},
28
+ ...extraFields,
29
+ });
30
+ schema.plugin(isDeletedPlugin);
31
+ schema.plugin(createdUpdatedPlugin);
32
+ schema.plugin(syncPlugin);
33
+ return model<SideEffectTodo>(name, schema);
34
+ };
35
+
36
+ const authedOptions = {
37
+ permissions: {
38
+ create: [Permissions.IsAuthenticated],
39
+ delete: [Permissions.IsAuthenticated],
40
+ list: [Permissions.IsAuthenticated],
41
+ read: [Permissions.IsAuthenticated],
42
+ update: [Permissions.IsAuthenticated],
43
+ },
44
+ } as unknown as ModelRouterOptions<SideEffectTodo>;
45
+
46
+ describe("applySyncRegistrationSideEffects", () => {
47
+ beforeEach(() => {
48
+ clearSyncRegistry();
49
+ });
50
+
51
+ it("requires snapshotFilter when scope is a custom resolver function", () => {
52
+ const SideEffectTodoModel = buildModel("SideEffectCustomScope");
53
+ expect(() =>
54
+ applySyncRegistrationSideEffects({
55
+ config: {scope: () => "owner:abc"},
56
+ existingSyncEntries: [],
57
+ model: SideEffectTodoModel,
58
+ options: authedOptions,
59
+ routePath: "/sideEffectCustomScope",
60
+ })
61
+ ).toThrow(/snapshotFilter/);
62
+ });
63
+
64
+ it("rejects registering the same model name on a second route path", () => {
65
+ const SideEffectTodoModel = buildModel("SideEffectDupModel");
66
+ registerSync({
67
+ config: {scope: {type: "owner"}},
68
+ model: SideEffectTodoModel,
69
+ options: authedOptions,
70
+ routePath: "/sideEffectDupA",
71
+ });
72
+
73
+ expect(() =>
74
+ registerSync({
75
+ config: {scope: {type: "owner"}},
76
+ model: SideEffectTodoModel,
77
+ options: authedOptions,
78
+ routePath: "/sideEffectDupB",
79
+ })
80
+ ).toThrow(/already registered/);
81
+ });
82
+
83
+ it("rejects a duplicate collection tag across route path spellings", () => {
84
+ const FirstModel = buildModel("SideEffectDupTagA");
85
+ registerCollection({
86
+ model: FirstModel,
87
+ options: {...authedOptions, sync: {scope: {type: "owner"}}},
88
+ routePath: "/sideEffectDupTag",
89
+ });
90
+
91
+ const SecondModel = buildModel("SideEffectDupTagB");
92
+ expect(() =>
93
+ applySyncRegistrationSideEffects({
94
+ config: {scope: {type: "owner"}},
95
+ existingSyncEntries: [{collectionTag: "sideEffectDupTag", modelName: "SideEffectDupTagA"}],
96
+ model: SecondModel,
97
+ options: authedOptions,
98
+ routePath: "sideEffectDupTag",
99
+ })
100
+ ).toThrow(/already registered/);
101
+ });
102
+
103
+ it("wraps createIndex failures in an actionable APIError at startup", async () => {
104
+ const SideEffectTodoModel = buildModel("SideEffectIndexFail");
105
+ SideEffectTodoModel.collection.createIndex = async (): Promise<string> => {
106
+ throw new Error("boom: index build failed");
107
+ };
108
+ applySyncRegistrationSideEffects({
109
+ config: {scope: {type: "owner"}},
110
+ existingSyncEntries: [],
111
+ model: SideEffectTodoModel,
112
+ options: authedOptions,
113
+ routePath: "/sideEffectIndexFail",
114
+ });
115
+
116
+ await expect(ensureSyncIndexes()).rejects.toThrow(/Failed to create sync snapshot index/);
117
+ });
118
+
119
+ it("clearSyncIndexCreationTasks drops deferred index work", async () => {
120
+ trackSyncIndexCreation(async () => {
121
+ throw new Error("should not run");
122
+ });
123
+ clearSyncIndexCreationTasks();
124
+ await expect(ensureSyncIndexes()).resolves.toBeUndefined();
125
+ });
126
+ });
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Schema and Mongo work that must happen when a collection first becomes
3
+ * sync-enabled — kept out of CollectionRegistry so catalog writes stay a
4
+ * Map update, while models can still register before Mongo is connected.
5
+ *
6
+ * Registration only validates the schema and queues index creation.
7
+ * TerrenoApp.start() (or a host that builds Express without it) must later
8
+ * await ensureSyncIndexes() so snapshot/catch-up queries have their indexes.
9
+ */
10
+ import type {Model} from "mongoose";
11
+
12
+ import type {ModelRouterOptions} from "../api";
13
+ import {APIError, errorDetail} from "../errors";
14
+ import {logger} from "../logger";
15
+ import {getScopeField} from "./streams";
16
+ import type {SyncConfig} from "./types";
17
+
18
+ type IndexCreationTask = () => Promise<void>;
19
+ const indexCreationTasks: IndexCreationTask[] = [];
20
+
21
+ export interface SyncRegistrationSnapshot {
22
+ collectionTag: string;
23
+ modelName: string;
24
+ }
25
+
26
+ /** Queue extra index work (tests and SyncApp bookkeeping models). */
27
+ export const trackSyncIndexCreation = (task: IndexCreationTask): void => {
28
+ indexCreationTasks.push(task);
29
+ };
30
+
31
+ /**
32
+ * Fail loud if the model cannot participate in sync, then queue the
33
+ * snapshot index. Call only on the first sync enable for a routePath.
34
+ */
35
+ export const applySyncRegistrationSideEffects = <T>({
36
+ config,
37
+ existingSyncEntries,
38
+ model,
39
+ routePath,
40
+ }: {
41
+ config: SyncConfig;
42
+ existingSyncEntries: SyncRegistrationSnapshot[];
43
+ model: Model<T>;
44
+ options: ModelRouterOptions<T>;
45
+ routePath: string;
46
+ }): void => {
47
+ const name = model.modelName;
48
+ const deletedPath = model.schema.path("deleted");
49
+ if (deletedPath?.instance !== "Boolean") {
50
+ throw new APIError({
51
+ status: 500,
52
+ title:
53
+ `Model ${name} has a sync config but no soft delete support. ` +
54
+ "Apply isDeletedPlugin to the schema — sync catch-up requires delete tombstones.",
55
+ });
56
+ }
57
+ if (!model.schema.path("_syncSeq")) {
58
+ throw new APIError({
59
+ status: 500,
60
+ title:
61
+ `Model ${name} has a sync config but syncPlugin is not applied to its schema. ` +
62
+ "Apply syncPlugin so every write stamps a per-stream _syncSeq.",
63
+ });
64
+ }
65
+ const scopeField = getScopeField(config.scope);
66
+ if (scopeField && !model.schema.path(scopeField)) {
67
+ throw new APIError({
68
+ status: 500,
69
+ title: `Model ${name} has a sync scope on field "${scopeField}" but the schema has no such path.`,
70
+ });
71
+ }
72
+ if (typeof config.scope === "function" && !config.snapshotFilter) {
73
+ throw new APIError({
74
+ status: 500,
75
+ title:
76
+ `Model ${name} uses a custom sync scope resolver, which requires a snapshotFilter ` +
77
+ "so the snapshot endpoint can restrict queries to the caller's documents.",
78
+ });
79
+ }
80
+ if (existingSyncEntries.some((entry) => entry.modelName === name)) {
81
+ throw new APIError({
82
+ status: 500,
83
+ title: `Model ${name} is already registered for sync.`,
84
+ });
85
+ }
86
+ const collectionTag = routePath.replace(/^\//, "");
87
+ if (existingSyncEntries.some((entry) => entry.collectionTag === collectionTag)) {
88
+ throw new APIError({
89
+ status: 500,
90
+ title:
91
+ `Sync collection tag "${collectionTag}" is already registered (routePath ${routePath}). ` +
92
+ "Each synced model must have a unique route path.",
93
+ });
94
+ }
95
+
96
+ (model as unknown as {bulkWrite: () => never}).bulkWrite = (): never => {
97
+ throw new APIError({
98
+ status: 500,
99
+ title:
100
+ `bulkWrite is not supported on sync-enabled model ${name}: it bypasses Mongoose ` +
101
+ "middleware, so writes are never stamped with a per-stream _syncSeq and become " +
102
+ "invisible to sync delta emission and snapshot catch-up. Loop per document instead.",
103
+ });
104
+ };
105
+
106
+ const indexSpec: Record<string, 1> = scopeField ? {[scopeField]: 1, _syncSeq: 1} : {_syncSeq: 1};
107
+ indexCreationTasks.push(async () => {
108
+ try {
109
+ await model.collection.createIndex(indexSpec);
110
+ } catch (error: unknown) {
111
+ logger.error(`[sync] Failed to create sync index for ${name}`, {error: String(error)});
112
+ throw new APIError({
113
+ cause: error,
114
+ code: "sync-snapshot-index-failed",
115
+ detail: `${errorDetail(error)}. The snapshot/catch-up query requires this index; fix the schema/DB and restart.`,
116
+ status: 500,
117
+ title: `Failed to create sync snapshot index for ${name}`,
118
+ });
119
+ }
120
+ });
121
+ };
122
+
123
+ /** Create every queued sync index after Mongo is connected. */
124
+ export const ensureSyncIndexes = async (): Promise<void> => {
125
+ await Promise.all(indexCreationTasks.map((task) => task()));
126
+ };
127
+
128
+ /** Drop queued index work when the collection catalog is wiped (tests). */
129
+ export const clearSyncIndexCreationTasks = (): void => {
130
+ indexCreationTasks.length = 0;
131
+ };