@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,13 +1,21 @@
1
+ import type express from "express";
1
2
  import type {Server} from "socket.io";
2
3
 
3
4
  import type {User} from "../auth";
4
5
  import {logger} from "../logger";
6
+ import {ORGANIZATION_ID_HEADER} from "../orgs/orgContext";
5
7
  import {checkPermissions} from "../permissions";
6
8
  import {awaitSocketFullUser, type SocketWithDecodedToken} from "../realtime/socketUser";
9
+ import {canListAdminBroadcastScope, getAdminBroadcastScope} from "./adminBroadcastScope";
10
+ import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
7
11
  import type {SyncMutationOutcome} from "./mutationHandler";
8
12
  import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
9
13
  import type {SyncAppOptions} from "./routes";
10
- import {MissingScopeResolverError, resolveUserStreamsForEntry} from "./streams";
14
+ import {
15
+ adminBroadcastStream,
16
+ MissingScopeResolverError,
17
+ resolveUserStreamsForEntry,
18
+ } from "./streams";
11
19
  import {runSyncBatch, runSyncMutation} from "./syncBatch";
12
20
  import type {
13
21
  SyncMutateBatchRequest,
@@ -16,20 +24,53 @@ import type {
16
24
  SyncNack,
17
25
  } from "./types";
18
26
 
27
+ const requestFromOrganizationId = ({
28
+ organizationId,
29
+ user,
30
+ }: {
31
+ organizationId?: string;
32
+ user: User;
33
+ }): express.Request => {
34
+ const trimmed = organizationId?.trim();
35
+ if (!trimmed) {
36
+ return {user} as unknown as express.Request;
37
+ }
38
+ return {
39
+ header: (name: string): string | undefined => {
40
+ return String(name).toLowerCase() === ORGANIZATION_ID_HEADER ? trimmed : undefined;
41
+ },
42
+ user,
43
+ } as unknown as express.Request;
44
+ };
45
+
46
+ const organizationIdFromPayload = (payload: unknown): string | undefined => {
47
+ if (typeof payload !== "object" || payload === null) {
48
+ return undefined;
49
+ }
50
+ const organizationId = (payload as {organizationId?: unknown}).organizationId;
51
+ return typeof organizationId === "string" ? organizationId : undefined;
52
+ };
53
+
19
54
  /**
20
55
  * Socket handlers for the SyncDB local-first protocol:
21
56
  *
22
- * - `sync:subscribe {collections}` / `sync:unsubscribe {collections}` — resolves the
57
+ * - `sync:subscribe {collections, mode?}` / `sync:unsubscribe {collections}` — resolves the
23
58
  * caller's streams from the sync registry scope config and joins/leaves `sync:{stream}`
24
59
  * rooms. Owner scopes always use the socket's own userId (never a client-supplied one);
25
60
  * tenant and custom scopes resolve stream values via `SyncAppOptions.getUserScopes`.
61
+ * `mode: "window"` joins `{collection}|admin` only (requires `adminBroadcast` and
62
+ * admin panel access: `admin:access` when `SyncApp` has `accessControl`, else
63
+ * `user.admin`). When AdminApp has registered a broadcast scope, list
64
+ * permission for that model is required as well. Confirms with
65
+ * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
26
66
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
27
67
  * legacy realtime rooms so the two event families never overlap.
28
68
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
29
69
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
30
70
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
31
71
  * - `sync:error {collection, message}` — emitted for per-collection subscribe failures
32
- * (unknown collection, permission denied, missing scope resolver, cap exceeded).
72
+ * (unknown collection, permission denied, non-admin window subscribe, missing scope
73
+ * resolver, cap exceeded).
33
74
  *
34
75
  * ## Wiring
35
76
  *
@@ -133,67 +174,112 @@ export const installSyncSocketHandlers = (
133
174
  socket.data.syncSubscriptions = subscriptions;
134
175
  }
135
176
 
136
- socket.on("sync:subscribe", async (payload: {collections?: unknown}): Promise<void> => {
137
- const collections = Array.isArray(payload?.collections) ? payload.collections : null;
138
- if (!collections) {
139
- return;
140
- }
141
- // C8: reject an oversized array up front (length check before iterating).
142
- if (collections.length > MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH) {
143
- logInfo(`[sync] User ${userId} sent an oversized sync:subscribe array`);
144
- socket.emit("sync:error", {
145
- collection: "",
146
- message: `sync:subscribe accepts at most ${MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH} collections`,
147
- });
148
- return;
149
- }
150
- for (const collection of collections) {
151
- if (typeof collection !== "string" || collection.length === 0) {
152
- continue;
153
- }
154
- if (subscriptions.has(collection)) {
155
- // Already subscribed — idempotent.
156
- continue;
157
- }
158
- if (subscriptions.size >= MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
159
- logInfo(`[sync] User ${userId} hit sync collection subscription limit`);
160
- socket.emit("sync:error", {
161
- collection,
162
- message: `Sync subscription limit of ${MAX_SYNC_COLLECTION_SUBSCRIPTIONS} collections reached`,
163
- });
164
- continue;
165
- }
166
- const entry = findSyncEntryByCollectionTag(collection);
167
- if (!entry) {
168
- socket.emit("sync:error", {collection, message: `Unknown sync collection: ${collection}`});
169
- continue;
170
- }
171
- const user = await currentUser();
172
- if (!user) {
173
- socket.emit("sync:error", {collection, message: "Authentication required"});
174
- continue;
177
+ socket.on(
178
+ "sync:subscribe",
179
+ async (payload: {collections?: unknown; mode?: unknown}): Promise<void> => {
180
+ const collections = Array.isArray(payload?.collections) ? payload.collections : null;
181
+ const isWindow = payload?.mode === "window";
182
+ if (!collections) {
183
+ return;
175
184
  }
176
- if (!(await checkPermissions("list", entry.options.permissions.list, user))) {
177
- logInfo(`[sync] User ${userId} denied sync subscription for ${collection}`);
185
+ // C8: reject an oversized array up front (length check before iterating).
186
+ if (collections.length > MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH) {
187
+ logInfo(`[sync] User ${userId} sent an oversized sync:subscribe array`);
178
188
  socket.emit("sync:error", {
179
- collection,
180
- message: `Access to sync collection ${collection} denied`,
189
+ collection: "",
190
+ message: `sync:subscribe accepts at most ${MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH} collections`,
181
191
  });
182
- continue;
183
- }
184
- const streams = await resolveUserStreams({entry, options, socket, user});
185
- if (!streams) {
186
- continue;
192
+ return;
187
193
  }
188
- const rooms = new Set(streams.map(syncRoomForStream));
189
- for (const room of rooms) {
190
- await socket.join(room);
194
+ for (const collection of collections) {
195
+ if (typeof collection !== "string" || collection.length === 0) {
196
+ continue;
197
+ }
198
+ if (subscriptions.has(collection)) {
199
+ // Already subscribed — idempotent.
200
+ continue;
201
+ }
202
+ if (subscriptions.size >= MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
203
+ logInfo(`[sync] User ${userId} hit sync collection subscription limit`);
204
+ socket.emit("sync:error", {
205
+ collection,
206
+ message: `Sync subscription limit of ${MAX_SYNC_COLLECTION_SUBSCRIPTIONS} collections reached`,
207
+ });
208
+ continue;
209
+ }
210
+ const entry = findSyncEntryByCollectionTag(collection);
211
+ if (!entry) {
212
+ socket.emit("sync:error", {
213
+ collection,
214
+ message: `Unknown sync collection: ${collection}`,
215
+ });
216
+ continue;
217
+ }
218
+ const user = await currentUser();
219
+ if (!user) {
220
+ socket.emit("sync:error", {collection, message: "Authentication required"});
221
+ continue;
222
+ }
223
+ if (!(await checkPermissions("list", entry.options.permissions.list, user))) {
224
+ logInfo(`[sync] User ${userId} denied sync subscription for ${collection}`);
225
+ socket.emit("sync:error", {
226
+ collection,
227
+ message: `Access to sync collection ${collection} denied`,
228
+ });
229
+ continue;
230
+ }
231
+ if (isWindow && entry.config.adminBroadcast !== true) {
232
+ socket.emit("sync:error", {
233
+ collection,
234
+ message: `Window subscribe requires adminBroadcast on ${collection}`,
235
+ });
236
+ continue;
237
+ }
238
+ if (
239
+ isWindow &&
240
+ !(await canUseAdminBroadcastWindow({
241
+ accessControl: options.accessControl,
242
+ canOpenAdminWindow: options.canOpenAdminWindow,
243
+ user,
244
+ }))
245
+ ) {
246
+ logInfo(`[sync] User ${userId} denied window subscribe for ${collection}`);
247
+ socket.emit("sync:error", {
248
+ collection,
249
+ message: `Window subscribe requires admin panel access for ${collection}`,
250
+ });
251
+ continue;
252
+ }
253
+ if (isWindow) {
254
+ const adminScope = getAdminBroadcastScope(entry.modelName);
255
+ if (adminScope && !(await canListAdminBroadcastScope({scope: adminScope, user}))) {
256
+ logInfo(`[sync] User ${userId} denied window subscribe list for ${collection}`);
257
+ socket.emit("sync:error", {
258
+ collection,
259
+ message: `Window subscribe requires admin collection access for ${collection}`,
260
+ });
261
+ continue;
262
+ }
263
+ }
264
+ const streams = isWindow
265
+ ? [adminBroadcastStream(collection)]
266
+ : await resolveUserStreams({entry, options, socket, user});
267
+ if (!streams) {
268
+ continue;
269
+ }
270
+ const rooms = new Set(streams.map(syncRoomForStream));
271
+ for (const room of rooms) {
272
+ await socket.join(room);
273
+ }
274
+ subscriptions.set(collection, rooms);
275
+ socket.emit(
276
+ "sync:subscribed",
277
+ isWindow ? {collection, mode: "window", streams} : {collection, streams}
278
+ );
279
+ logInfo(`[sync] User ${userId} subscribed to ${collection}: ${streams.join(", ")}`);
191
280
  }
192
- subscriptions.set(collection, rooms);
193
- socket.emit("sync:subscribed", {collection, streams});
194
- logInfo(`[sync] User ${userId} subscribed to ${collection}: ${streams.join(", ")}`);
195
281
  }
196
- });
282
+ );
197
283
 
198
284
  socket.on("sync:unsubscribe", async (payload: {collections?: unknown}): Promise<void> => {
199
285
  const collections = Array.isArray(payload?.collections) ? payload.collections : null;
@@ -250,7 +336,12 @@ export const installSyncSocketHandlers = (
250
336
  // USER's window, so opening more sockets no longer multiplies the budget.
251
337
  const {outcome, stage} = await runSyncMutation({
252
338
  mutation: payload,
339
+ req: requestFromOrganizationId({
340
+ organizationId: organizationIdFromPayload(payload),
341
+ user,
342
+ }),
253
343
  scopeResolver: options.getUserScopes,
344
+ syncOptions: options,
254
345
  user,
255
346
  });
256
347
  if (stage === "rate_limited") {
@@ -298,7 +389,12 @@ export const installSyncSocketHandlers = (
298
389
  // Task 9.20: validate -> rate limit -> apply, shared with POST /sync/mutate/batch.
299
390
  const {response, stage} = await runSyncBatch({
300
391
  mutations,
392
+ req: requestFromOrganizationId({
393
+ organizationId: organizationIdFromPayload(payload),
394
+ user,
395
+ }),
301
396
  scopeResolver: options.getUserScopes,
397
+ syncOptions: options,
302
398
  user,
303
399
  });
304
400
  if (stage === "rate_limited") {
@@ -25,6 +25,9 @@ export const getScopeField = (scope: SyncScope): string | null => {
25
25
  return null;
26
26
  };
27
27
 
28
+ /** Fan-in stream for admin window subscribers when `SyncConfig.adminBroadcast` is true. */
29
+ export const adminBroadcastStream = (collectionTag: string): string => `${collectionTag}|admin`;
30
+
28
31
  /** Build a stream key from a collection tag and a raw scope value. */
29
32
  export const streamForScopeValue = ({
30
33
  collectionTag,
@@ -65,6 +68,9 @@ export const parseStreamKey = (
65
68
  if (rest === "all") {
66
69
  return {collectionTag, scopeKind: "all", scopeValue: null};
67
70
  }
71
+ if (rest === "admin") {
72
+ return {collectionTag, scopeKind: "admin", scopeValue: null};
73
+ }
68
74
  const colon = rest.indexOf(":");
69
75
  if (colon < 0) {
70
76
  return null;
@@ -1,5 +1,3 @@
1
- // noExplicitAny: test model typing
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test model typing
3
1
  import {beforeAll, beforeEach, describe, expect, it} from "bun:test";
4
2
  import {model, Schema} from "mongoose";
5
3
  import {type ModelRouterOptions, modelRouter} from "../api";
@@ -73,32 +71,32 @@ unregisteredSchema.plugin(syncPlugin);
73
71
  const UnregisteredModel = model<SyncStuff>("SyncUnregistered", unregisteredSchema);
74
72
 
75
73
  // Missing isDeletedPlugin — registration must throw.
76
- const noDeleteSchema = new Schema({
74
+ const noDeleteSchema = new Schema<SyncStuff>({
77
75
  name: {description: "The name of the item", type: String},
78
76
  ownerId: {description: "The user who owns this item", type: String},
79
77
  });
80
78
  noDeleteSchema.plugin(syncPlugin);
81
- const NoDeleteModel = model("SyncNoDelete", noDeleteSchema);
79
+ const NoDeleteModel = model<SyncStuff>("SyncNoDelete", noDeleteSchema);
82
80
 
83
81
  // Missing syncPlugin — registration must throw.
84
- const noPluginSchema = new Schema({
82
+ const noPluginSchema = new Schema<SyncStuff>({
85
83
  name: {description: "The name of the item", type: String},
86
84
  ownerId: {description: "The user who owns this item", type: String},
87
85
  });
88
86
  noPluginSchema.plugin(isDeletedPlugin);
89
- const NoPluginModel = model("SyncNoPlugin", noPluginSchema);
87
+ const NoPluginModel = model<SyncStuff>("SyncNoPlugin", noPluginSchema);
90
88
 
91
- const stubOptions = {
89
+ const stubOptions = <T>(): ModelRouterOptions<T> => ({
92
90
  permissions: {create: [], delete: [], list: [], read: [], update: []},
93
- } as unknown as ModelRouterOptions<any>;
91
+ });
94
92
 
95
93
  const ownerConfig: SyncConfig = {scope: {type: "owner"}};
96
94
 
97
95
  const registerStuff = (config: SyncConfig = ownerConfig): void => {
98
96
  registerSync({
99
97
  config,
100
- model: SyncStuffModel as any,
101
- options: stubOptions,
98
+ model: SyncStuffModel,
99
+ options: stubOptions<SyncStuff>(),
102
100
  routePath: "/syncStuff",
103
101
  });
104
102
  };
@@ -205,8 +203,8 @@ describe("registerSync validation", () => {
205
203
  expect(() =>
206
204
  registerSync({
207
205
  config: ownerConfig,
208
- model: NoDeleteModel as any,
209
- options: stubOptions,
206
+ model: NoDeleteModel,
207
+ options: stubOptions<SyncStuff>(),
210
208
  routePath: "/noDelete",
211
209
  })
212
210
  ).toThrow(/soft delete/);
@@ -216,8 +214,8 @@ describe("registerSync validation", () => {
216
214
  expect(() =>
217
215
  registerSync({
218
216
  config: ownerConfig,
219
- model: NoPluginModel as any,
220
- options: stubOptions,
217
+ model: NoPluginModel,
218
+ options: stubOptions<SyncStuff>(),
221
219
  routePath: "/noPlugin",
222
220
  })
223
221
  ).toThrow(/syncPlugin/);
@@ -227,16 +225,17 @@ describe("registerSync validation", () => {
227
225
  expect(() =>
228
226
  registerSync({
229
227
  config: {scope: {field: "workspaceId", type: "tenant"}},
230
- model: SyncStuffModel as any,
231
- options: stubOptions,
228
+ model: SyncStuffModel,
229
+ options: stubOptions<SyncStuff>(),
232
230
  routePath: "/syncStuff",
233
231
  })
234
232
  ).toThrow(/workspaceId/);
235
233
  });
236
234
 
237
- it("throws on duplicate registration", () => {
235
+ it("treats duplicate registration of the same model as a no-op", () => {
236
+ registerStuff();
238
237
  registerStuff();
239
- expect(() => registerStuff()).toThrow(/already registered/);
238
+ expect(getSyncRegistry()).toHaveLength(1);
240
239
  });
241
240
 
242
241
  it("registers a compliant model and exposes lookup helpers", () => {
@@ -248,7 +247,9 @@ describe("registerSync validation", () => {
248
247
 
249
248
  it("updateSyncRegistryOptions replaces options on an existing entry", () => {
250
249
  registerStuff();
251
- const updatedOptions = {permissions: {list: []}} as ModelRouterOptions<unknown>;
250
+ const updatedOptions = {
251
+ permissions: {list: []},
252
+ } as unknown as ModelRouterOptions<unknown>;
252
253
  updateSyncRegistryOptions("/syncStuff", updatedOptions);
253
254
  expect(getSyncRegistry()[0]?.options).toBe(updatedOptions);
254
255
  });
@@ -256,14 +257,16 @@ describe("registerSync validation", () => {
256
257
  it("updateSyncRegistryOptions no-ops when the route path is not registered", () => {
257
258
  registerStuff();
258
259
  const originalOptions = getSyncRegistry()[0]?.options;
259
- updateSyncRegistryOptions("/missing", {permissions: {}} as ModelRouterOptions<unknown>);
260
+ updateSyncRegistryOptions("/missing", {
261
+ permissions: {},
262
+ } as unknown as ModelRouterOptions<unknown>);
260
263
  expect(getSyncRegistry()[0]?.options).toBe(originalOptions);
261
264
  });
262
265
 
263
266
  it("makes bulkWrite throw on the registered model (it bypasses every plugin guard)", () => {
264
267
  registerStuff();
265
268
  expect(() =>
266
- (SyncStuffModel as any).bulkWrite([
269
+ SyncStuffModel.bulkWrite([
267
270
  {updateOne: {filter: {_id: "any"}, update: {$set: {name: "nope"}}}},
268
271
  ])
269
272
  ).toThrow(/bulkWrite is not supported on sync-enabled model SyncStuff/);
@@ -299,8 +302,8 @@ describe("modelRouter sync option", () => {
299
302
  });
300
303
 
301
304
  it("registers the model for sync in the three-argument form", () => {
302
- const registration = modelRouter("/syncStuff", SyncStuffModel as any, {
303
- ...stubOptions,
305
+ const registration = modelRouter("/syncStuff", SyncStuffModel, {
306
+ ...stubOptions<SyncStuff>(),
304
307
  sync: ownerConfig,
305
308
  });
306
309
  expect((registration as {__type: string}).__type).toBe("modelRouter");
@@ -308,7 +311,7 @@ describe("modelRouter sync option", () => {
308
311
  });
309
312
 
310
313
  it("does not register in the two-argument form", () => {
311
- modelRouter(SyncStuffModel as any, {...stubOptions, sync: ownerConfig});
314
+ modelRouter(SyncStuffModel, {...stubOptions<SyncStuff>(), sync: ownerConfig});
312
315
  expect(findSyncEntryByCollectionTag("syncStuff")).toBeUndefined();
313
316
  });
314
317
 
@@ -398,7 +401,7 @@ describe("syncPlugin seq stamping", () => {
398
401
  });
399
402
 
400
403
  it("does not consume a seq when validation fails", async () => {
401
- await expect(SyncStuffModel.create({ownerId: "u1"} as any)).rejects.toThrow();
404
+ await expect(SyncStuffModel.create({ownerId: "u1"} as unknown as SyncStuff)).rejects.toThrow();
402
405
  const doc = await SyncStuffModel.create({name: "valid", ownerId: "u1"});
403
406
  expect(doc._syncSeq).toBe(1);
404
407
  });
@@ -21,13 +21,14 @@ export const getSyncAppOptions = (app: express.Application): SyncAppOptions | un
21
21
  * configuration — the socket layer requires both plugins: SyncApp for config/routes and
22
22
  * RealtimeApp for the Socket.io server and `sync:delta` emission.
23
23
  *
24
- * Registration also kicks off the bookkeeping-model index builds (`SyncCounter`,
25
- * `SyncMutation`, `SyncScopeMove`, `SyncKey`) and enqueues them for `ensureSyncIndexes()`,
26
- * which `TerrenoApp.start()` awaits before listening. Those indexes are correctness
24
+ * Registration also enqueues the bookkeeping-model index builds (`SyncCounter`,
25
+ * `SyncMutation`, `SyncScopeMove`, `SyncKey`) for `ensureSyncIndexes()`, which
26
+ * `TerrenoApp.start()` binds the HTTP port first, then awaits `ensureSyncIndexes()`. Those indexes are
27
27
  * requirements — the unique `mutationId` index is what makes duplicate mutation deliveries
28
28
  * idempotent, and the unique `stream` index is what keeps the counter upsert race from
29
29
  * minting duplicate seqs — so an index-build failure fails startup loudly. Apps that build
30
30
  * the Express app without `TerrenoApp.start()` should await `ensureSyncIndexes()` themselves.
31
+ * Pass `httpServer` when the process already bound `PORT` (Cloud Run startup probe).
31
32
  */
32
33
  export class SyncApp implements TerrenoPlugin {
33
34
  private readonly options: SyncAppOptions;
@@ -38,7 +39,7 @@ export class SyncApp implements TerrenoPlugin {
38
39
 
39
40
  register(app: express.Application): void {
40
41
  app.locals[SYNC_APP_OPTIONS_LOCAL_KEY] = this.options;
41
- trackSyncIndexCreation(ensureSyncModelIndexes());
42
+ trackSyncIndexCreation(() => ensureSyncModelIndexes());
42
43
  addSyncRoutes(app, this.options);
43
44
  }
44
45
  }
@@ -1,4 +1,5 @@
1
1
  import type express from "express";
2
+ import {DateTime} from "luxon";
2
3
  import type {User} from "../auth";
3
4
  import {logger} from "../logger";
4
5
  import {
@@ -8,6 +9,7 @@ import {
8
9
  type SyncMutationScopeResolver,
9
10
  validateSyncMutationBatch,
10
11
  } from "./mutationHandler";
12
+ import type {SyncAppOptions} from "./routes";
11
13
  import type {SyncMutateBatchResponse, SyncMutateRequest, SyncNack} from "./types";
12
14
 
13
15
  /**
@@ -56,7 +58,7 @@ let lastEvictionAt = 0;
56
58
  * Returns the number of windows still retained.
57
59
  */
58
60
  export const evictExpiredSyncMutationWindows = ({
59
- now = Date.now(),
61
+ now = DateTime.now().toMillis(),
60
62
  }: {
61
63
  now?: number;
62
64
  } = {}): number => {
@@ -93,7 +95,7 @@ const consumeMutationBudget = ({
93
95
  userId: string;
94
96
  weight: number;
95
97
  }): number | undefined => {
96
- const now = Date.now();
98
+ const now = DateTime.now().toMillis();
97
99
  maybeEvictExpiredWindows(now);
98
100
  const existing = mutationWindows.get(userId);
99
101
  const window =
@@ -148,12 +150,14 @@ export const runSyncMutation = async ({
148
150
  mutation,
149
151
  req,
150
152
  scopeResolver,
153
+ syncOptions,
151
154
  user,
152
155
  }: {
153
156
  mutation: SyncMutateRequest;
154
157
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
155
158
  req?: express.Request;
156
159
  scopeResolver?: SyncMutationScopeResolver;
160
+ syncOptions?: SyncAppOptions;
157
161
  user: User;
158
162
  }): Promise<SyncMutationRunResult> => {
159
163
  const userId = String(user.id);
@@ -167,7 +171,7 @@ export const runSyncMutation = async ({
167
171
  };
168
172
  }
169
173
  return {
170
- outcome: await applySyncMutation({mutation, req, scopeResolver, user}),
174
+ outcome: await applySyncMutation({mutation, req, scopeResolver, syncOptions, user}),
171
175
  stage: "applied",
172
176
  };
173
177
  };
@@ -185,11 +189,13 @@ export const runSyncBatch = async ({
185
189
  mutations,
186
190
  req,
187
191
  scopeResolver,
192
+ syncOptions,
188
193
  user,
189
194
  }: {
190
195
  mutations: SyncMutateRequest[];
191
196
  req?: express.Request;
192
197
  scopeResolver?: SyncMutationScopeResolver;
198
+ syncOptions?: SyncAppOptions;
193
199
  user: User;
194
200
  }): Promise<SyncBatchRunResult> => {
195
201
  const validation = validateSyncMutationBatch(mutations);
@@ -213,7 +219,7 @@ export const runSyncBatch = async ({
213
219
  }
214
220
 
215
221
  return {
216
- response: await applySyncMutationBatch({mutations, req, scopeResolver, user}),
222
+ response: await applySyncMutationBatch({mutations, req, scopeResolver, syncOptions, user}),
217
223
  stage: "applied",
218
224
  };
219
225
  };
@@ -1,5 +1,3 @@
1
- // noExplicitAny: test model typing
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test model typing
3
1
  import {beforeAll, beforeEach, describe, expect, it} from "bun:test";
4
2
  import {model, Schema} from "mongoose";
5
3
  import type {ModelRouterOptions} from "../api";
@@ -84,7 +82,14 @@ const FrontierModel = model<FrontierStuff>("FrontierStuff", frontierSchema);
84
82
 
85
83
  const stubOptions = {
86
84
  permissions: {create: [], delete: [], list: [], read: [], update: []},
87
- } as unknown as ModelRouterOptions<any>;
85
+ } as unknown as ModelRouterOptions<FrontierStuff>;
86
+
87
+ type ScopeMoveCreate = (...args: Parameters<typeof SyncScopeMove.create>) => Promise<unknown>;
88
+
89
+ // Mongoose's `create` is overloaded, so the marker-retry tests swap it out through a
90
+ // single-signature view of the model.
91
+ const scopeMovePatch = SyncScopeMove as unknown as {create: ScopeMoveCreate};
92
+ const originalScopeMoveCreate: ScopeMoveCreate = SyncScopeMove.create.bind(SyncScopeMove);
88
93
 
89
94
  describe("C1 claimSyncSeqs / confirmSyncSeqs / computeStableFrontier", () => {
90
95
  beforeAll(async () => {
@@ -216,7 +221,7 @@ describe("C1 write-path guards (m9 / m10) + C4 scope-move markers", () => {
216
221
  clearSyncRegistry();
217
222
  registerSync({
218
223
  config: {scope: {field: "orgId", type: "tenant"}} as SyncConfig,
219
- model: FrontierModel as any,
224
+ model: FrontierModel,
220
225
  options: stubOptions,
221
226
  routePath: "/frontierStuff",
222
227
  });
@@ -422,19 +427,18 @@ describe("C1 write-path guards (m9 / m10) + C4 scope-move markers", () => {
422
427
 
423
428
  it("C4: a transient marker-write failure on the query path is retried until it lands", async () => {
424
429
  const doc = await FrontierModel.create({name: "n", orgId: "org1", ownerId: "u1"});
425
- const originalCreate = SyncScopeMove.create.bind(SyncScopeMove);
426
430
  let attempts = 0;
427
- (SyncScopeMove as any).create = async (...args: any[]) => {
431
+ scopeMovePatch.create = async (...args) => {
428
432
  attempts += 1;
429
433
  if (attempts === 1) {
430
434
  throw new Error("transient marker write failure");
431
435
  }
432
- return originalCreate(...(args as Parameters<typeof originalCreate>));
436
+ return originalScopeMoveCreate(...args);
433
437
  };
434
438
  try {
435
439
  await FrontierModel.updateOne({_id: doc._id}, {$set: {orgId: "org2"}});
436
440
  } finally {
437
- (SyncScopeMove as any).create = originalCreate;
441
+ scopeMovePatch.create = originalScopeMoveCreate;
438
442
  }
439
443
  expect(attempts).toBe(2);
440
444
  const markers = await SyncScopeMove.find({entityId: String(doc._id)});
@@ -444,20 +448,19 @@ describe("C1 write-path guards (m9 / m10) + C4 scope-move markers", () => {
444
448
 
445
449
  it("C4: a transient marker-write failure on the save path is retried until it lands", async () => {
446
450
  const doc = await FrontierModel.create({name: "n", orgId: "org1", ownerId: "u1"});
447
- const originalCreate = SyncScopeMove.create.bind(SyncScopeMove);
448
451
  let attempts = 0;
449
- (SyncScopeMove as any).create = async (...args: any[]) => {
452
+ scopeMovePatch.create = async (...args) => {
450
453
  attempts += 1;
451
454
  if (attempts === 1) {
452
455
  throw new Error("transient marker write failure");
453
456
  }
454
- return originalCreate(...(args as Parameters<typeof originalCreate>));
457
+ return originalScopeMoveCreate(...args);
455
458
  };
456
459
  try {
457
460
  doc.orgId = "org2";
458
461
  await doc.save();
459
462
  } finally {
460
- (SyncScopeMove as any).create = originalCreate;
463
+ scopeMovePatch.create = originalScopeMoveCreate;
461
464
  }
462
465
  expect(attempts).toBe(2);
463
466
  const markers = await SyncScopeMove.find({entityId: String(doc._id)});
@@ -467,9 +470,8 @@ describe("C1 write-path guards (m9 / m10) + C4 scope-move markers", () => {
467
470
 
468
471
  it("C4: an exhausted marker-write retry is logged, never failing the committed write", async () => {
469
472
  const doc = await FrontierModel.create({name: "n", orgId: "org1", ownerId: "u1"});
470
- const originalCreate = SyncScopeMove.create.bind(SyncScopeMove);
471
473
  let attempts = 0;
472
- (SyncScopeMove as any).create = async () => {
474
+ scopeMovePatch.create = async () => {
473
475
  attempts += 1;
474
476
  throw new Error("permanent marker write failure");
475
477
  };
@@ -477,7 +479,7 @@ describe("C1 write-path guards (m9 / m10) + C4 scope-move markers", () => {
477
479
  // The document write already committed — a marker failure must not surface as an error.
478
480
  await FrontierModel.updateOne({_id: doc._id}, {$set: {orgId: "org2"}});
479
481
  } finally {
480
- (SyncScopeMove as any).create = originalCreate;
482
+ scopeMovePatch.create = originalScopeMoveCreate;
481
483
  }
482
484
  expect(attempts).toBe(SCOPE_MOVE_MARKER_ATTEMPTS);
483
485
  expect(await SyncScopeMove.countDocuments({entityId: String(doc._id)})).toBe(0);