@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
@@ -4,17 +4,23 @@ import type { SyncAppOptions } from "./routes";
4
4
  /**
5
5
  * Socket handlers for the SyncDB local-first protocol:
6
6
  *
7
- * - `sync:subscribe {collections}` / `sync:unsubscribe {collections}` — resolves the
7
+ * - `sync:subscribe {collections, mode?}` / `sync:unsubscribe {collections}` — resolves the
8
8
  * caller's streams from the sync registry scope config and joins/leaves `sync:{stream}`
9
9
  * rooms. Owner scopes always use the socket's own userId (never a client-supplied one);
10
10
  * tenant and custom scopes resolve stream values via `SyncAppOptions.getUserScopes`.
11
+ * `mode: "window"` joins `{collection}|admin` only (requires `adminBroadcast` and
12
+ * admin panel access: `admin:access` when `SyncApp` has `accessControl`, else
13
+ * `user.admin`). When AdminApp has registered a broadcast scope, list
14
+ * permission for that model is required as well. Confirms with
15
+ * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
11
16
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
12
17
  * legacy realtime rooms so the two event families never overlap.
13
18
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
14
19
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
15
20
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
16
21
  * - `sync:error {collection, message}` — emitted for per-collection subscribe failures
17
- * (unknown collection, permission denied, missing scope resolver, cap exceeded).
22
+ * (unknown collection, permission denied, non-admin window subscribe, missing scope
23
+ * resolver, cap exceeded).
18
24
  *
19
25
  * ## Wiring
20
26
  *
@@ -60,25 +60,54 @@ var __values = (this && this.__values) || function(o) {
60
60
  Object.defineProperty(exports, "__esModule", { value: true });
61
61
  exports.installSyncSocketHandlers = exports.syncRoomForStream = exports.MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH = exports.MAX_SYNC_COLLECTION_SUBSCRIPTIONS = void 0;
62
62
  var logger_1 = require("../logger");
63
+ var orgContext_1 = require("../orgs/orgContext");
63
64
  var permissions_1 = require("../permissions");
64
65
  var socketUser_1 = require("../realtime/socketUser");
66
+ var adminBroadcastScope_1 = require("./adminBroadcastScope");
67
+ var adminWindowAccess_1 = require("./adminWindowAccess");
65
68
  var registry_1 = require("./registry");
66
69
  var streams_1 = require("./streams");
67
70
  var syncBatch_1 = require("./syncBatch");
71
+ var requestFromOrganizationId = function (_a) {
72
+ var organizationId = _a.organizationId, user = _a.user;
73
+ var trimmed = organizationId === null || organizationId === void 0 ? void 0 : organizationId.trim();
74
+ if (!trimmed) {
75
+ return { user: user };
76
+ }
77
+ return {
78
+ header: function (name) {
79
+ return String(name).toLowerCase() === orgContext_1.ORGANIZATION_ID_HEADER ? trimmed : undefined;
80
+ },
81
+ user: user,
82
+ };
83
+ };
84
+ var organizationIdFromPayload = function (payload) {
85
+ if (typeof payload !== "object" || payload === null) {
86
+ return undefined;
87
+ }
88
+ var organizationId = payload.organizationId;
89
+ return typeof organizationId === "string" ? organizationId : undefined;
90
+ };
68
91
  /**
69
92
  * Socket handlers for the SyncDB local-first protocol:
70
93
  *
71
- * - `sync:subscribe {collections}` / `sync:unsubscribe {collections}` — resolves the
94
+ * - `sync:subscribe {collections, mode?}` / `sync:unsubscribe {collections}` — resolves the
72
95
  * caller's streams from the sync registry scope config and joins/leaves `sync:{stream}`
73
96
  * rooms. Owner scopes always use the socket's own userId (never a client-supplied one);
74
97
  * tenant and custom scopes resolve stream values via `SyncAppOptions.getUserScopes`.
98
+ * `mode: "window"` joins `{collection}|admin` only (requires `adminBroadcast` and
99
+ * admin panel access: `admin:access` when `SyncApp` has `accessControl`, else
100
+ * `user.admin`). When AdminApp has registered a broadcast scope, list
101
+ * permission for that model is required as well. Confirms with
102
+ * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
75
103
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
76
104
  * legacy realtime rooms so the two event families never overlap.
77
105
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
78
106
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
79
107
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
80
108
  * - `sync:error {collection, message}` — emitted for per-collection subscribe failures
81
- * (unknown collection, permission denied, missing scope resolver, cap exceeded).
109
+ * (unknown collection, permission denied, non-admin window subscribe, missing scope
110
+ * resolver, cap exceeded).
82
111
  *
83
112
  * ## Wiring
84
113
  *
@@ -163,12 +192,13 @@ var installSyncSocketHandlers = function (_io, socket, options, handlerOptions)
163
192
  socket.data.syncSubscriptions = subscriptions;
164
193
  }
165
194
  socket.on("sync:subscribe", function (payload) { return __awaiter(void 0, void 0, void 0, function () {
166
- var collections, collections_1, collections_1_1, collection, entry, user, streams, rooms, rooms_1, rooms_1_1, room, e_1_1, e_2_1;
167
- var e_2, _a, e_1, _b;
168
- return __generator(this, function (_c) {
169
- switch (_c.label) {
195
+ var collections, isWindow, collections_1, collections_1_1, collection, entry, user, _a, adminScope, _b, streams, _c, rooms, rooms_1, rooms_1_1, room, e_1_1, e_2_1;
196
+ var e_2, _d, e_1, _e;
197
+ return __generator(this, function (_f) {
198
+ switch (_f.label) {
170
199
  case 0:
171
200
  collections = Array.isArray(payload === null || payload === void 0 ? void 0 : payload.collections) ? payload.collections : null;
201
+ isWindow = (payload === null || payload === void 0 ? void 0 : payload.mode) === "window";
172
202
  if (!collections) {
173
203
  return [2 /*return*/];
174
204
  }
@@ -181,20 +211,20 @@ var installSyncSocketHandlers = function (_io, socket, options, handlerOptions)
181
211
  });
182
212
  return [2 /*return*/];
183
213
  }
184
- _c.label = 1;
214
+ _f.label = 1;
185
215
  case 1:
186
- _c.trys.push([1, 16, 17, 18]);
216
+ _f.trys.push([1, 23, 24, 25]);
187
217
  collections_1 = __values(collections), collections_1_1 = collections_1.next();
188
- _c.label = 2;
218
+ _f.label = 2;
189
219
  case 2:
190
- if (!!collections_1_1.done) return [3 /*break*/, 15];
220
+ if (!!collections_1_1.done) return [3 /*break*/, 22];
191
221
  collection = collections_1_1.value;
192
222
  if (typeof collection !== "string" || collection.length === 0) {
193
- return [3 /*break*/, 14];
223
+ return [3 /*break*/, 21];
194
224
  }
195
225
  if (subscriptions.has(collection)) {
196
226
  // Already subscribed — idempotent.
197
- return [3 /*break*/, 14];
227
+ return [3 /*break*/, 21];
198
228
  }
199
229
  if (subscriptions.size >= exports.MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
200
230
  logInfo("[sync] User ".concat(userId, " hit sync collection subscription limit"));
@@ -202,83 +232,137 @@ var installSyncSocketHandlers = function (_io, socket, options, handlerOptions)
202
232
  collection: collection,
203
233
  message: "Sync subscription limit of ".concat(exports.MAX_SYNC_COLLECTION_SUBSCRIPTIONS, " collections reached"),
204
234
  });
205
- return [3 /*break*/, 14];
235
+ return [3 /*break*/, 21];
206
236
  }
207
237
  entry = (0, registry_1.findSyncEntryByCollectionTag)(collection);
208
238
  if (!entry) {
209
- socket.emit("sync:error", { collection: collection, message: "Unknown sync collection: ".concat(collection) });
210
- return [3 /*break*/, 14];
239
+ socket.emit("sync:error", {
240
+ collection: collection,
241
+ message: "Unknown sync collection: ".concat(collection),
242
+ });
243
+ return [3 /*break*/, 21];
211
244
  }
212
245
  return [4 /*yield*/, currentUser()];
213
246
  case 3:
214
- user = _c.sent();
247
+ user = _f.sent();
215
248
  if (!user) {
216
249
  socket.emit("sync:error", { collection: collection, message: "Authentication required" });
217
- return [3 /*break*/, 14];
250
+ return [3 /*break*/, 21];
218
251
  }
219
252
  return [4 /*yield*/, (0, permissions_1.checkPermissions)("list", entry.options.permissions.list, user)];
220
253
  case 4:
221
- if (!(_c.sent())) {
254
+ if (!(_f.sent())) {
222
255
  logInfo("[sync] User ".concat(userId, " denied sync subscription for ").concat(collection));
223
256
  socket.emit("sync:error", {
224
257
  collection: collection,
225
258
  message: "Access to sync collection ".concat(collection, " denied"),
226
259
  });
227
- return [3 /*break*/, 14];
260
+ return [3 /*break*/, 21];
228
261
  }
229
- return [4 /*yield*/, resolveUserStreams({ entry: entry, options: options, socket: socket, user: user })];
262
+ if (isWindow && entry.config.adminBroadcast !== true) {
263
+ socket.emit("sync:error", {
264
+ collection: collection,
265
+ message: "Window subscribe requires adminBroadcast on ".concat(collection),
266
+ });
267
+ return [3 /*break*/, 21];
268
+ }
269
+ _a = isWindow;
270
+ if (!_a) return [3 /*break*/, 6];
271
+ return [4 /*yield*/, (0, adminWindowAccess_1.canUseAdminBroadcastWindow)({
272
+ accessControl: options.accessControl,
273
+ canOpenAdminWindow: options.canOpenAdminWindow,
274
+ user: user,
275
+ })];
230
276
  case 5:
231
- streams = _c.sent();
277
+ _a = !(_f.sent());
278
+ _f.label = 6;
279
+ case 6:
280
+ if (_a) {
281
+ logInfo("[sync] User ".concat(userId, " denied window subscribe for ").concat(collection));
282
+ socket.emit("sync:error", {
283
+ collection: collection,
284
+ message: "Window subscribe requires admin panel access for ".concat(collection),
285
+ });
286
+ return [3 /*break*/, 21];
287
+ }
288
+ if (!isWindow) return [3 /*break*/, 9];
289
+ adminScope = (0, adminBroadcastScope_1.getAdminBroadcastScope)(entry.modelName);
290
+ _b = adminScope;
291
+ if (!_b) return [3 /*break*/, 8];
292
+ return [4 /*yield*/, (0, adminBroadcastScope_1.canListAdminBroadcastScope)({ scope: adminScope, user: user })];
293
+ case 7:
294
+ _b = !(_f.sent());
295
+ _f.label = 8;
296
+ case 8:
297
+ if (_b) {
298
+ logInfo("[sync] User ".concat(userId, " denied window subscribe list for ").concat(collection));
299
+ socket.emit("sync:error", {
300
+ collection: collection,
301
+ message: "Window subscribe requires admin collection access for ".concat(collection),
302
+ });
303
+ return [3 /*break*/, 21];
304
+ }
305
+ _f.label = 9;
306
+ case 9:
307
+ if (!isWindow) return [3 /*break*/, 10];
308
+ _c = [(0, streams_1.adminBroadcastStream)(collection)];
309
+ return [3 /*break*/, 12];
310
+ case 10: return [4 /*yield*/, resolveUserStreams({ entry: entry, options: options, socket: socket, user: user })];
311
+ case 11:
312
+ _c = _f.sent();
313
+ _f.label = 12;
314
+ case 12:
315
+ streams = _c;
232
316
  if (!streams) {
233
- return [3 /*break*/, 14];
317
+ return [3 /*break*/, 21];
234
318
  }
235
319
  rooms = new Set(streams.map(exports.syncRoomForStream));
236
- _c.label = 6;
237
- case 6:
238
- _c.trys.push([6, 11, 12, 13]);
320
+ _f.label = 13;
321
+ case 13:
322
+ _f.trys.push([13, 18, 19, 20]);
239
323
  rooms_1 = (e_1 = void 0, __values(rooms)), rooms_1_1 = rooms_1.next();
240
- _c.label = 7;
241
- case 7:
242
- if (!!rooms_1_1.done) return [3 /*break*/, 10];
324
+ _f.label = 14;
325
+ case 14:
326
+ if (!!rooms_1_1.done) return [3 /*break*/, 17];
243
327
  room = rooms_1_1.value;
244
328
  return [4 /*yield*/, socket.join(room)];
245
- case 8:
246
- _c.sent();
247
- _c.label = 9;
248
- case 9:
329
+ case 15:
330
+ _f.sent();
331
+ _f.label = 16;
332
+ case 16:
249
333
  rooms_1_1 = rooms_1.next();
250
- return [3 /*break*/, 7];
251
- case 10: return [3 /*break*/, 13];
252
- case 11:
253
- e_1_1 = _c.sent();
334
+ return [3 /*break*/, 14];
335
+ case 17: return [3 /*break*/, 20];
336
+ case 18:
337
+ e_1_1 = _f.sent();
254
338
  e_1 = { error: e_1_1 };
255
- return [3 /*break*/, 13];
256
- case 12:
339
+ return [3 /*break*/, 20];
340
+ case 19:
257
341
  try {
258
- if (rooms_1_1 && !rooms_1_1.done && (_b = rooms_1.return)) _b.call(rooms_1);
342
+ if (rooms_1_1 && !rooms_1_1.done && (_e = rooms_1.return)) _e.call(rooms_1);
259
343
  }
260
344
  finally { if (e_1) throw e_1.error; }
261
345
  return [7 /*endfinally*/];
262
- case 13:
346
+ case 20:
263
347
  subscriptions.set(collection, rooms);
264
- socket.emit("sync:subscribed", { collection: collection, streams: streams });
348
+ socket.emit("sync:subscribed", isWindow ? { collection: collection, mode: "window", streams: streams } : { collection: collection, streams: streams });
265
349
  logInfo("[sync] User ".concat(userId, " subscribed to ").concat(collection, ": ").concat(streams.join(", ")));
266
- _c.label = 14;
267
- case 14:
350
+ _f.label = 21;
351
+ case 21:
268
352
  collections_1_1 = collections_1.next();
269
353
  return [3 /*break*/, 2];
270
- case 15: return [3 /*break*/, 18];
271
- case 16:
272
- e_2_1 = _c.sent();
354
+ case 22: return [3 /*break*/, 25];
355
+ case 23:
356
+ e_2_1 = _f.sent();
273
357
  e_2 = { error: e_2_1 };
274
- return [3 /*break*/, 18];
275
- case 17:
358
+ return [3 /*break*/, 25];
359
+ case 24:
276
360
  try {
277
- if (collections_1_1 && !collections_1_1.done && (_a = collections_1.return)) _a.call(collections_1);
361
+ if (collections_1_1 && !collections_1_1.done && (_d = collections_1.return)) _d.call(collections_1);
278
362
  }
279
363
  finally { if (e_2) throw e_2.error; }
280
364
  return [7 /*endfinally*/];
281
- case 18: return [2 /*return*/];
365
+ case 25: return [2 /*return*/];
282
366
  }
283
367
  });
284
368
  }); });
@@ -389,7 +473,12 @@ var installSyncSocketHandlers = function (_io, socket, options, handlerOptions)
389
473
  _b.trys.push([2, 4, , 5]);
390
474
  return [4 /*yield*/, (0, syncBatch_1.runSyncMutation)({
391
475
  mutation: payload,
476
+ req: requestFromOrganizationId({
477
+ organizationId: organizationIdFromPayload(payload),
478
+ user: user,
479
+ }),
392
480
  scopeResolver: options.getUserScopes,
481
+ syncOptions: options,
393
482
  user: user,
394
483
  })];
395
484
  case 3:
@@ -444,7 +533,12 @@ var installSyncSocketHandlers = function (_io, socket, options, handlerOptions)
444
533
  _b.trys.push([2, 4, , 5]);
445
534
  return [4 /*yield*/, (0, syncBatch_1.runSyncBatch)({
446
535
  mutations: mutations,
536
+ req: requestFromOrganizationId({
537
+ organizationId: organizationIdFromPayload(payload),
538
+ user: user,
539
+ }),
447
540
  scopeResolver: options.getUserScopes,
541
+ syncOptions: options,
448
542
  user: user,
449
543
  })];
450
544
  case 3:
@@ -10,6 +10,8 @@ import type { SyncScope } from "./types";
10
10
  */
11
11
  /** The document field a scope reads, or null for broadcast/custom scopes. */
12
12
  export declare const getScopeField: (scope: SyncScope) => string | null;
13
+ /** Fan-in stream for admin window subscribers when `SyncConfig.adminBroadcast` is true. */
14
+ export declare const adminBroadcastStream: (collectionTag: string) => string;
13
15
  /** Build a stream key from a collection tag and a raw scope value. */
14
16
  export declare const streamForScopeValue: ({ collectionTag, scope, scopeValue, }: {
15
17
  collectionTag: string;
@@ -51,7 +51,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
51
51
  }
52
52
  };
53
53
  Object.defineProperty(exports, "__esModule", { value: true });
54
- exports.resolveUserStreamsForEntry = exports.MissingScopeResolverError = exports.assertWritableStream = exports.resolveStreamForDoc = exports.parseStreamKey = exports.streamForScopeValue = exports.getScopeField = void 0;
54
+ exports.resolveUserStreamsForEntry = exports.MissingScopeResolverError = exports.assertWritableStream = exports.resolveStreamForDoc = exports.parseStreamKey = exports.streamForScopeValue = exports.adminBroadcastStream = exports.getScopeField = void 0;
55
55
  var errors_1 = require("../errors");
56
56
  /**
57
57
  * Stream key resolution for SyncDB.
@@ -75,6 +75,9 @@ var getScopeField = function (scope) {
75
75
  return null;
76
76
  };
77
77
  exports.getScopeField = getScopeField;
78
+ /** Fan-in stream for admin window subscribers when `SyncConfig.adminBroadcast` is true. */
79
+ var adminBroadcastStream = function (collectionTag) { return "".concat(collectionTag, "|admin"); };
80
+ exports.adminBroadcastStream = adminBroadcastStream;
78
81
  /** Build a stream key from a collection tag and a raw scope value. */
79
82
  var streamForScopeValue = function (_a) {
80
83
  var collectionTag = _a.collectionTag, scope = _a.scope, scopeValue = _a.scopeValue;
@@ -106,6 +109,9 @@ var parseStreamKey = function (stream) {
106
109
  if (rest === "all") {
107
110
  return { collectionTag: collectionTag, scopeKind: "all", scopeValue: null };
108
111
  }
112
+ if (rest === "admin") {
113
+ return { collectionTag: collectionTag, scopeKind: "admin", scopeValue: null };
114
+ }
109
115
  var colon = rest.indexOf(":");
110
116
  if (colon < 0) {
111
117
  return null;
@@ -14,13 +14,14 @@ export declare const getSyncAppOptions: (app: express.Application) => SyncAppOpt
14
14
  * configuration — the socket layer requires both plugins: SyncApp for config/routes and
15
15
  * RealtimeApp for the Socket.io server and `sync:delta` emission.
16
16
  *
17
- * Registration also kicks off the bookkeeping-model index builds (`SyncCounter`,
18
- * `SyncMutation`, `SyncScopeMove`, `SyncKey`) and enqueues them for `ensureSyncIndexes()`,
19
- * which `TerrenoApp.start()` awaits before listening. Those indexes are correctness
17
+ * Registration also enqueues the bookkeeping-model index builds (`SyncCounter`,
18
+ * `SyncMutation`, `SyncScopeMove`, `SyncKey`) for `ensureSyncIndexes()`, which
19
+ * `TerrenoApp.start()` binds the HTTP port first, then awaits `ensureSyncIndexes()`. Those indexes are
20
20
  * requirements — the unique `mutationId` index is what makes duplicate mutation deliveries
21
21
  * idempotent, and the unique `stream` index is what keeps the counter upsert race from
22
22
  * minting duplicate seqs — so an index-build failure fails startup loudly. Apps that build
23
23
  * the Express app without `TerrenoApp.start()` should await `ensureSyncIndexes()` themselves.
24
+ * Pass `httpServer` when the process already bound `PORT` (Cloud Run startup probe).
24
25
  */
25
26
  export declare class SyncApp implements TerrenoPlugin {
26
27
  private readonly options;
@@ -21,13 +21,14 @@ exports.getSyncAppOptions = getSyncAppOptions;
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
  var SyncApp = /** @class */ (function () {
33
34
  function SyncApp(options) {
@@ -36,7 +37,7 @@ var SyncApp = /** @class */ (function () {
36
37
  }
37
38
  SyncApp.prototype.register = function (app) {
38
39
  app.locals[SYNC_APP_OPTIONS_LOCAL_KEY] = this.options;
39
- (0, registry_1.trackSyncIndexCreation)((0, models_1.ensureSyncModelIndexes)());
40
+ (0, registry_1.trackSyncIndexCreation)(function () { return (0, models_1.ensureSyncModelIndexes)(); });
40
41
  (0, routes_1.addSyncRoutes)(app, this.options);
41
42
  };
42
43
  return SyncApp;
@@ -1,6 +1,7 @@
1
1
  import type express from "express";
2
2
  import type { User } from "../auth";
3
3
  import { type SyncMutationOutcome, type SyncMutationScopeResolver } from "./mutationHandler";
4
+ import type { SyncAppOptions } from "./routes";
4
5
  import type { SyncMutateBatchResponse, SyncMutateRequest } from "./types";
5
6
  /**
6
7
  * Task 9.20: the single orchestration both mutation transports run.
@@ -47,11 +48,12 @@ export interface SyncBatchRunResult {
47
48
  response: SyncMutateBatchResponse;
48
49
  }
49
50
  /** Shared orchestration for a SINGLE mutation: rate limit, then apply. */
50
- export declare const runSyncMutation: ({ mutation, req, scopeResolver, user, }: {
51
+ export declare const runSyncMutation: ({ mutation, req, scopeResolver, syncOptions, user, }: {
51
52
  mutation: SyncMutateRequest;
52
53
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
53
54
  req?: express.Request;
54
55
  scopeResolver?: SyncMutationScopeResolver;
56
+ syncOptions?: SyncAppOptions;
55
57
  user: User;
56
58
  }) => Promise<SyncMutationRunResult>;
57
59
  /**
@@ -63,9 +65,10 @@ export declare const runSyncMutation: ({ mutation, req, scopeResolver, user, }:
63
65
  * mutations that would have succeeded. The budget is then charged per MUTATION (not per
64
66
  * batch), so batching cannot buy extra throughput over single sends.
65
67
  */
66
- export declare const runSyncBatch: ({ mutations, req, scopeResolver, user, }: {
68
+ export declare const runSyncBatch: ({ mutations, req, scopeResolver, syncOptions, user, }: {
67
69
  mutations: SyncMutateRequest[];
68
70
  req?: express.Request;
69
71
  scopeResolver?: SyncMutationScopeResolver;
72
+ syncOptions?: SyncAppOptions;
70
73
  user: User;
71
74
  }) => Promise<SyncBatchRunResult>;
@@ -75,6 +75,7 @@ var __read = (this && this.__read) || function (o, n) {
75
75
  };
76
76
  Object.defineProperty(exports, "__esModule", { value: true });
77
77
  exports.runSyncBatch = exports.runSyncMutation = exports.syncMutationRateLimitWindowCount = exports.resetSyncMutationRateLimits = exports.evictExpiredSyncMutationWindows = exports.MAX_SYNC_MUTATIONS_PER_SECOND = void 0;
78
+ var luxon_1 = require("luxon");
78
79
  var logger_1 = require("../logger");
79
80
  var mutationHandler_1 = require("./mutationHandler");
80
81
  /**
@@ -112,7 +113,7 @@ var lastEvictionAt = 0;
112
113
  */
113
114
  var evictExpiredSyncMutationWindows = function (_a) {
114
115
  var e_1, _b;
115
- var _c = _a === void 0 ? {} : _a, _d = _c.now, now = _d === void 0 ? Date.now() : _d;
116
+ var _c = _a === void 0 ? {} : _a, _d = _c.now, now = _d === void 0 ? luxon_1.DateTime.now().toMillis() : _d;
116
117
  lastEvictionAt = now;
117
118
  try {
118
119
  for (var mutationWindows_1 = __values(mutationWindows), mutationWindows_1_1 = mutationWindows_1.next(); !mutationWindows_1_1.done; mutationWindows_1_1 = mutationWindows_1.next()) {
@@ -150,7 +151,7 @@ var maybeEvictExpiredWindows = function (now) {
150
151
  */
151
152
  var consumeMutationBudget = function (_a) {
152
153
  var userId = _a.userId, weight = _a.weight;
153
- var now = Date.now();
154
+ var now = luxon_1.DateTime.now().toMillis();
154
155
  maybeEvictExpiredWindows(now);
155
156
  var existing = mutationWindows.get(userId);
156
157
  var window = !existing || now - existing.windowStart >= RATE_LIMIT_WINDOW_MS
@@ -184,7 +185,7 @@ var rateLimitNack = function (retryAfterMs) { return ({
184
185
  var runSyncMutation = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
185
186
  var userId, mutationId, retryAfterMs;
186
187
  var _c;
187
- var mutation = _b.mutation, req = _b.req, scopeResolver = _b.scopeResolver, user = _b.user;
188
+ var mutation = _b.mutation, req = _b.req, scopeResolver = _b.scopeResolver, syncOptions = _b.syncOptions, user = _b.user;
188
189
  return __generator(this, function (_d) {
189
190
  switch (_d.label) {
190
191
  case 0:
@@ -199,7 +200,7 @@ var runSyncMutation = function (_a) { return __awaiter(void 0, [_a], void 0, fun
199
200
  }];
200
201
  }
201
202
  _c = {};
202
- return [4 /*yield*/, (0, mutationHandler_1.applySyncMutation)({ mutation: mutation, req: req, scopeResolver: scopeResolver, user: user })];
203
+ return [4 /*yield*/, (0, mutationHandler_1.applySyncMutation)({ mutation: mutation, req: req, scopeResolver: scopeResolver, syncOptions: syncOptions, user: user })];
203
204
  case 1: return [2 /*return*/, (_c.outcome = _d.sent(),
204
205
  _c.stage = "applied",
205
206
  _c)];
@@ -219,7 +220,7 @@ exports.runSyncMutation = runSyncMutation;
219
220
  var runSyncBatch = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
220
221
  var validation, userId, retryAfterMs;
221
222
  var _c;
222
- var mutations = _b.mutations, req = _b.req, scopeResolver = _b.scopeResolver, user = _b.user;
223
+ var mutations = _b.mutations, req = _b.req, scopeResolver = _b.scopeResolver, syncOptions = _b.syncOptions, user = _b.user;
223
224
  return __generator(this, function (_d) {
224
225
  switch (_d.label) {
225
226
  case 0:
@@ -242,7 +243,7 @@ var runSyncBatch = function (_a) { return __awaiter(void 0, [_a], void 0, functi
242
243
  }];
243
244
  }
244
245
  _c = {};
245
- return [4 /*yield*/, (0, mutationHandler_1.applySyncMutationBatch)({ mutations: mutations, req: req, scopeResolver: scopeResolver, user: user })];
246
+ return [4 /*yield*/, (0, mutationHandler_1.applySyncMutationBatch)({ mutations: mutations, req: req, scopeResolver: scopeResolver, syncOptions: syncOptions, user: user })];
246
247
  case 1: return [2 /*return*/, (_c.response = _d.sent(),
247
248
  _c.stage = "applied",
248
249
  _c)];
@@ -5,4 +5,4 @@ import type { Schema } from "mongoose";
5
5
  * so a transient failure (replica step-down, transient network error) is retried.
6
6
  */
7
7
  export declare const SCOPE_MOVE_MARKER_ATTEMPTS = 3;
8
- export declare const syncPlugin: (schema: Schema<any, any, any, any>) => void;
8
+ export declare const syncPlugin: (schema: Schema) => void;
@@ -75,6 +75,7 @@ var __read = (this && this.__read) || function (o, n) {
75
75
  };
76
76
  Object.defineProperty(exports, "__esModule", { value: true });
77
77
  exports.syncPlugin = exports.SCOPE_MOVE_MARKER_ATTEMPTS = void 0;
78
+ var errors_1 = require("../errors");
78
79
  var logger_1 = require("../logger");
79
80
  var models_1 = require("./models");
80
81
  var registry_1 = require("./registry");
@@ -349,9 +350,12 @@ var syncPlugin = function (schema) {
349
350
  // so the `baseVersion` comparison in executeUpdate cannot be defeated by a concurrent
350
351
  // save landing between the read and the write.
351
352
  if (!schema.options.versionKey) {
352
- throw new Error("syncPlugin requires a versionKey on the schema: sync relies on Mongoose " +
353
- "optimisticConcurrency to make the baseVersion conflict check atomic. " +
354
- "Remove `versionKey: false` from the schema options.");
353
+ throw new errors_1.APIError({
354
+ status: 500,
355
+ title: "syncPlugin requires a versionKey on the schema: sync relies on Mongoose " +
356
+ "optimisticConcurrency to make the baseVersion conflict check atomic. " +
357
+ "Remove `versionKey: false` from the schema options.",
358
+ });
355
359
  }
356
360
  schema.set("optimisticConcurrency", true);
357
361
  schema.add({
@@ -640,7 +644,7 @@ var syncPlugin = function (schema) {
640
644
  if (typeof (doc === null || doc === void 0 ? void 0 : doc.$session) === "function" && doc.$session()) {
641
645
  continue;
642
646
  }
643
- obj = (typeof (doc === null || doc === void 0 ? void 0 : doc.toObject) === "function" ? doc.toObject() : doc);
647
+ obj = typeof (doc === null || doc === void 0 ? void 0 : doc.toObject) === "function" ? doc.toObject() : doc;
644
648
  seq = obj._syncSeq;
645
649
  if (typeof seq !== "number") {
646
650
  continue;
@@ -705,8 +709,6 @@ var syncPlugin = function (schema) {
705
709
  });
706
710
  });
707
711
  });
708
- // Single-document query writes: fetch the target to resolve its stream (and detect
709
- // scope moves), claim a seq, and merge the stamp into the update.
710
712
  var preQueryWrite = function () {
711
713
  return __awaiter(this, void 0, void 0, function () {
712
714
  var model, entry, operation, rawFilter, session, filter, matches, target, targetObj, previousStream, rawUpdate, op, isTrueReplacement, hasOperators, setFields, scopeField, currentStream, effectiveDoc, unsetFields, newScopeValue, prevStream, claim;
@@ -827,16 +829,18 @@ var syncPlugin = function (schema) {
827
829
  // scope-move marker. Query post middleware `this` is the Query (not a document).
828
830
  var postQueryWrite = function () {
829
831
  return __awaiter(this, void 0, void 0, function () {
830
- var pending, _a, claim, currentStream, entityId, entry, prevStream, session;
831
- return __generator(this, function (_b) {
832
- switch (_b.label) {
832
+ var pending, claim, currentStream, entityId, entry, prevStream, session;
833
+ return __generator(this, function (_a) {
834
+ switch (_a.label) {
833
835
  case 0:
834
- pending = this._syncPendingConfirm;
836
+ pending = this
837
+ ._syncPendingConfirm;
835
838
  if (!pending) {
836
839
  return [2 /*return*/];
837
840
  }
838
- this._syncPendingConfirm = undefined;
839
- _a = pending, claim = _a.claim, currentStream = _a.currentStream, entityId = _a.entityId, entry = _a.entry, prevStream = _a.prevStream, session = _a.session;
841
+ this._syncPendingConfirm =
842
+ undefined;
843
+ claim = pending.claim, currentStream = pending.currentStream, entityId = pending.entityId, entry = pending.entry, prevStream = pending.prevStream, session = pending.session;
840
844
  if (!claim.registered) return [3 /*break*/, 2];
841
845
  return [4 /*yield*/, (0, models_1.confirmSyncSeqs)({ seqs: claim.seqs, stream: currentStream }).catch(function (error) {
842
846
  logger_1.logger.error("[sync] Failed to confirm seq after query write", {
@@ -845,8 +849,8 @@ var syncPlugin = function (schema) {
845
849
  });
846
850
  })];
847
851
  case 1:
848
- _b.sent();
849
- _b.label = 2;
852
+ _a.sent();
853
+ _a.label = 2;
850
854
  case 2:
851
855
  if (!prevStream) return [3 /*break*/, 4];
852
856
  // Retries internally and never throws: the move already committed, so the marker
@@ -861,8 +865,8 @@ var syncPlugin = function (schema) {
861
865
  case 3:
862
866
  // Retries internally and never throws: the move already committed, so the marker
863
867
  // must not be dropped on the first transient failure nor fail the user's write.
864
- _b.sent();
865
- _b.label = 4;
868
+ _a.sent();
869
+ _a.label = 4;
866
870
  case 4: return [2 /*return*/];
867
871
  }
868
872
  });
@@ -33,6 +33,13 @@ export type SyncScope = SyncScopeOwner | SyncScopeTenant | SyncScopeBroadcast |
33
33
  * (seq stamping) — validated at registration.
34
34
  */
35
35
  export interface SyncConfig {
36
+ /**
37
+ * When true, change-stream `sync:delta` emission also fans in to `{collection}|admin`
38
+ * in addition to the owner/tenant/broadcast/custom stream. Default false. App clients
39
+ * keep their existing scope; only admin window subscribers join `|admin`. Join
40
+ * permission is admin-only (same checks as `/admin/*`), not owner-stream membership.
41
+ */
42
+ adminBroadcast?: boolean;
36
43
  /** Which stream a document belongs to. Multi-tenant by default via the tenant scope. */
37
44
  scope: SyncScope;
38
45
  /**
@@ -57,6 +64,10 @@ export interface SyncConfig {
57
64
  retentionDays?: number;
58
65
  }
59
66
  export type SyncMutationOperation = "create" | "update" | "delete";
67
+ /** Explicit client marker for admin-panel windowed sync writes. */
68
+ export type SyncMutationMode = "adminWindow";
69
+ /** `sync:subscribe` / `sync:subscribed` window mode for admin fan-in (no snapshot paging). */
70
+ export type SyncSubscribeMode = "window";
60
71
  /** A single entity in a snapshot response. */
61
72
  export interface SyncEntityPayload {
62
73
  /** Document id. */
@@ -125,6 +136,13 @@ export interface SyncMutateRequest {
125
136
  data?: Record<string, unknown>;
126
137
  /** The `_syncSeq` the client last saw for this document; enables LWW conflict detection. */
127
138
  baseVersion?: number;
139
+ /**
140
+ * When `"adminWindow"`, the server applies AdminApp write semantics (RBAC,
141
+ * writeOwned, readonly/hidden stripping, audit) instead of product sync
142
+ * permissions. Ignored unless the collection is `adminBroadcast`, the caller
143
+ * has admin-window access, and AdminApp registered a write scope.
144
+ */
145
+ mutationMode?: SyncMutationMode;
128
146
  }
129
147
  /** Successful mutation acknowledgement. */
130
148
  export interface SyncAck {