@terreno/api 57.3.0 → 57.6.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 (412) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +23 -10
  2. package/README.md +11 -5
  3. package/bunfig.toml +1 -1
  4. package/dist/actions.js +197 -368
  5. package/dist/adminModelRouter.js +88 -173
  6. package/dist/adminTypes.d.ts +7 -0
  7. package/dist/adminTypes.js +6 -1
  8. package/dist/api.d.ts +10 -0
  9. package/dist/api.js +601 -792
  10. package/dist/audit/auditApp.d.ts +30 -0
  11. package/dist/audit/auditApp.js +114 -0
  12. package/dist/audit/auditEventModel.d.ts +29 -0
  13. package/dist/audit/auditEventModel.js +101 -0
  14. package/dist/audit/cloudTasksEnqueue.d.ts +32 -0
  15. package/dist/audit/cloudTasksEnqueue.js +69 -0
  16. package/dist/audit/diff.d.ts +10 -0
  17. package/dist/audit/diff.js +140 -0
  18. package/dist/audit/processQueue.d.ts +6 -0
  19. package/dist/audit/processQueue.js +56 -0
  20. package/dist/audit/rbacSink.d.ts +2 -0
  21. package/dist/audit/rbacSink.js +41 -0
  22. package/dist/audit/record.d.ts +56 -0
  23. package/dist/audit/record.js +251 -0
  24. package/dist/auth.js +432 -681
  25. package/dist/authRecovery.js +155 -269
  26. package/dist/authTokens.js +43 -118
  27. package/dist/betterAuth.d.ts +6 -0
  28. package/dist/betterAuthApp.js +25 -26
  29. package/dist/betterAuthSetup.js +258 -413
  30. package/dist/browserLogsRoute.d.ts +6 -0
  31. package/dist/browserLogsRoute.js +97 -0
  32. package/dist/collectionRegistry.d.ts +3 -1
  33. package/dist/collectionRegistry.js +43 -33
  34. package/dist/config.js +53 -122
  35. package/dist/configurationApp.js +180 -361
  36. package/dist/configurationPlugin.js +130 -302
  37. package/dist/consentApp.js +276 -421
  38. package/dist/docLoader.js +78 -126
  39. package/dist/envConfigurationPlugin.js +25 -147
  40. package/dist/errors.js +151 -247
  41. package/dist/example.js +28 -34
  42. package/dist/expressServer.d.ts +10 -0
  43. package/dist/expressServer.js +109 -255
  44. package/dist/frameworkModelNames.d.ts +24 -0
  45. package/dist/frameworkModelNames.js +31 -0
  46. package/dist/githubAuth.js +152 -216
  47. package/dist/httpClient.js +176 -264
  48. package/dist/index.d.ts +28 -1
  49. package/dist/index.js +53 -2
  50. package/dist/logger.js +145 -278
  51. package/dist/mcp/auth.js +76 -128
  52. package/dist/mcp/createMCPRequest.js +4 -5
  53. package/dist/mcp/handlers.js +268 -480
  54. package/dist/mcp/query.d.ts +0 -13
  55. package/dist/mcp/query.js +57 -151
  56. package/dist/mcp/registry.js +17 -30
  57. package/dist/mcp/schemaGenerator.js +95 -181
  58. package/dist/mcp/server.js +28 -100
  59. package/dist/mcp/serviceTokens.js +102 -191
  60. package/dist/mcp/toolGenerator.js +78 -191
  61. package/dist/middleware.js +15 -27
  62. package/dist/migrations/fixtures/all-down/20260910120000-one.d.ts +4 -0
  63. package/dist/migrations/fixtures/all-down/20260910120000-one.js +9 -0
  64. package/dist/migrations/fixtures/all-down/20260910120001-two.d.ts +4 -0
  65. package/dist/migrations/fixtures/all-down/20260910120001-two.js +9 -0
  66. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.d.ts +3 -0
  67. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.js +7 -0
  68. package/dist/migrations/fixtures/bad-name/not-a-migration.d.ts +3 -0
  69. package/dist/migrations/fixtures/bad-name/not-a-migration.js +7 -0
  70. package/dist/migrations/fixtures/missing-up/20260910120000-noup.d.ts +2 -0
  71. package/dist/migrations/fixtures/missing-up/20260910120000-noup.js +5 -0
  72. package/dist/migrations/fixtures/valid/20260910120000-alpha.d.ts +3 -0
  73. package/dist/migrations/fixtures/valid/20260910120000-alpha.js +7 -0
  74. package/dist/migrations/fixtures/valid/20260910120001-beta.d.ts +4 -0
  75. package/dist/migrations/fixtures/valid/20260910120001-beta.js +9 -0
  76. package/dist/migrations/generate.d.ts +17 -0
  77. package/dist/migrations/generate.js +155 -0
  78. package/dist/migrations/load.d.ts +20 -0
  79. package/dist/migrations/load.js +110 -0
  80. package/dist/migrations/lock.d.ts +13 -0
  81. package/dist/migrations/lock.js +73 -0
  82. package/dist/migrations/runner.d.ts +42 -0
  83. package/dist/migrations/runner.js +249 -0
  84. package/dist/migrations/schemaCatalog.d.ts +44 -0
  85. package/dist/migrations/schemaCatalog.js +185 -0
  86. package/dist/migrations/types.d.ts +87 -0
  87. package/dist/migrations/types.js +7 -0
  88. package/dist/models/consentForm.js +6 -6
  89. package/dist/models/consentResponse.js +5 -5
  90. package/dist/models/mcpServiceToken.js +66 -156
  91. package/dist/models/notification.d.ts +2 -0
  92. package/dist/models/notification.js +62 -0
  93. package/dist/models/notificationPreference.d.ts +2 -0
  94. package/dist/models/notificationPreference.js +49 -0
  95. package/dist/models/versionConfig.js +5 -5
  96. package/dist/notifications/notificationService.d.ts +40 -0
  97. package/dist/notifications/notificationService.js +183 -0
  98. package/dist/notifications/notificationsApp.d.ts +18 -0
  99. package/dist/notifications/notificationsApp.js +156 -0
  100. package/dist/notifications/notificationsBeforeSend.d.ts +14 -0
  101. package/dist/notifications/notificationsBeforeSend.js +32 -0
  102. package/dist/notifiers/googleChatNotifier.js +36 -117
  103. package/dist/notifiers/slackNotifier.d.ts +31 -2
  104. package/dist/notifiers/slackNotifier.js +170 -119
  105. package/dist/notifiers/zoomNotifier.js +60 -111
  106. package/dist/openApi.d.ts +1 -7
  107. package/dist/openApi.js +113 -127
  108. package/dist/openApiBuilder.d.ts +14 -3
  109. package/dist/openApiBuilder.js +117 -159
  110. package/dist/openApiCompat.js +81 -148
  111. package/dist/openApiEtag.js +7 -7
  112. package/dist/openApiValidator.d.ts +13 -1
  113. package/dist/openApiValidator.js +301 -246
  114. package/dist/orgs/orgContext.d.ts +23 -0
  115. package/dist/orgs/orgContext.js +128 -0
  116. package/dist/orgs/orgPermissions.d.ts +4 -0
  117. package/dist/orgs/orgPermissions.js +38 -0
  118. package/dist/orgs/orgPlugin.d.ts +13 -0
  119. package/dist/orgs/orgPlugin.js +66 -0
  120. package/dist/orgs/organizationModel.d.ts +13 -0
  121. package/dist/orgs/organizationModel.js +200 -0
  122. package/dist/orgs/organizationSettings.d.ts +19 -0
  123. package/dist/orgs/organizationSettings.js +113 -0
  124. package/dist/orgs/orgsApp.d.ts +28 -0
  125. package/dist/orgs/orgsApp.js +416 -0
  126. package/dist/permissions.d.ts +7 -13
  127. package/dist/permissions.js +95 -211
  128. package/dist/plugins.js +125 -218
  129. package/dist/populate.js +130 -240
  130. package/dist/rateLimit/applyTrustProxy.js +1 -1
  131. package/dist/rateLimit/createStore.js +7 -8
  132. package/dist/rateLimit/memoryStore.js +22 -100
  133. package/dist/rateLimit/middleware.d.ts +0 -8
  134. package/dist/rateLimit/middleware.js +49 -101
  135. package/dist/rateLimit/mongoStore.d.ts +1 -0
  136. package/dist/rateLimit/mongoStore.js +55 -112
  137. package/dist/rateLimit/policies.d.ts +0 -4
  138. package/dist/rateLimit/policies.js +44 -80
  139. package/dist/rateLimit/redisStore.d.ts +1 -0
  140. package/dist/rateLimit/redisStore.js +40 -133
  141. package/dist/rbac/access.js +122 -253
  142. package/dist/rbac/assertAllowed.js +95 -171
  143. package/dist/rbac/auditModel.js +14 -58
  144. package/dist/rbac/backfillAdmins.js +24 -130
  145. package/dist/rbac/fieldViews.js +46 -141
  146. package/dist/rbac/membershipOrgAdminSource.d.ts +6 -0
  147. package/dist/rbac/membershipOrgAdminSource.js +51 -0
  148. package/dist/rbac/middleware.js +30 -96
  149. package/dist/rbac/modelRouterAccess.d.ts +3 -0
  150. package/dist/rbac/modelRouterAccess.js +133 -307
  151. package/dist/rbac/permissionUtils.js +40 -179
  152. package/dist/rbac/realtimeAccess.js +81 -147
  153. package/dist/rbac/resolve.d.ts +1 -1
  154. package/dist/rbac/resolve.js +154 -319
  155. package/dist/rbac/roleManager.js +318 -700
  156. package/dist/rbac/roleModel.d.ts +2 -5
  157. package/dist/rbac/roleModel.js +60 -173
  158. package/dist/rbac/routes.js +93 -196
  159. package/dist/rbac/scopes.js +39 -133
  160. package/dist/rbac/statements.d.ts +10 -1
  161. package/dist/rbac/statements.js +42 -93
  162. package/dist/rbac/types.d.ts +5 -0
  163. package/dist/rbac/userPlugin.js +3 -29
  164. package/dist/realtime/changeStreamWatcher.d.ts +10 -4
  165. package/dist/realtime/changeStreamWatcher.js +499 -764
  166. package/dist/realtime/deprecation.d.ts +1 -0
  167. package/dist/realtime/deprecation.js +9 -10
  168. package/dist/realtime/queryMatcher.js +110 -191
  169. package/dist/realtime/queryStore.js +35 -118
  170. package/dist/realtime/realtimeApp.d.ts +1 -0
  171. package/dist/realtime/realtimeApp.js +248 -401
  172. package/dist/realtime/registry.js +19 -30
  173. package/dist/realtime/sessionRevalidation.js +132 -358
  174. package/dist/realtime/socketAuth.js +89 -208
  175. package/dist/realtime/socketUser.js +10 -56
  176. package/dist/requestContext.js +93 -139
  177. package/dist/schemaMetadata.js +181 -265
  178. package/dist/scriptRunner.js +96 -266
  179. package/dist/scrubAdminFields.js +36 -108
  180. package/dist/secretProviders.js +130 -299
  181. package/dist/seedRunner.js +221 -514
  182. package/dist/sync/adminBroadcastScope.d.ts +40 -0
  183. package/dist/sync/adminBroadcastScope.js +82 -0
  184. package/dist/sync/adminWindowAccess.d.ts +13 -0
  185. package/dist/sync/adminWindowAccess.js +25 -0
  186. package/dist/sync/adminWindowMutation.d.ts +88 -0
  187. package/dist/sync/adminWindowMutation.js +176 -0
  188. package/dist/sync/executors.d.ts +9 -3
  189. package/dist/sync/executors.js +425 -598
  190. package/dist/sync/loadHarness.js +392 -689
  191. package/dist/sync/models.js +181 -341
  192. package/dist/sync/mutationHandler.d.ts +5 -2
  193. package/dist/sync/mutationHandler.js +549 -697
  194. package/dist/sync/registrationSideEffects.js +41 -95
  195. package/dist/sync/registry.js +31 -47
  196. package/dist/sync/routes.d.ts +13 -0
  197. package/dist/sync/routes.js +484 -760
  198. package/dist/sync/scripts/compactTombstones.js +83 -228
  199. package/dist/sync/serialize.js +18 -58
  200. package/dist/sync/socketHandlers.d.ts +8 -2
  201. package/dist/sync/socketHandlers.js +271 -402
  202. package/dist/sync/streams.d.ts +2 -0
  203. package/dist/sync/streams.js +54 -116
  204. package/dist/sync/syncApp.d.ts +2 -1
  205. package/dist/sync/syncApp.js +14 -16
  206. package/dist/sync/syncBatch.d.ts +5 -2
  207. package/dist/sync/syncBatch.js +63 -168
  208. package/dist/sync/syncSeqPlugin.js +430 -702
  209. package/dist/sync/types.d.ts +18 -0
  210. package/dist/syncConsents.js +113 -253
  211. package/dist/terrenoApp.d.ts +29 -0
  212. package/dist/terrenoApp.js +184 -257
  213. package/dist/tests/createTestData.d.ts +1 -3
  214. package/dist/tests/createTestData.js +147 -259
  215. package/dist/tests/models.d.ts +1 -0
  216. package/dist/tests/models.js +23 -56
  217. package/dist/tests/mongoTestSetup.js +42 -103
  218. package/dist/tests/testHelper.d.ts +0 -5
  219. package/dist/tests/testHelper.js +32 -101
  220. package/dist/tests.js +12 -51
  221. package/dist/transformers.js +61 -164
  222. package/dist/types/authToken.d.ts +3 -3
  223. package/dist/types/mcpServiceToken.d.ts +2 -2
  224. package/dist/types/membership.d.ts +23 -0
  225. package/dist/types/membership.js +2 -0
  226. package/dist/types/notification.d.ts +28 -0
  227. package/dist/types/notification.js +2 -0
  228. package/dist/types/notificationPreference.d.ts +20 -0
  229. package/dist/types/notificationPreference.js +2 -0
  230. package/dist/types/organization.d.ts +36 -0
  231. package/dist/types/organization.js +2 -0
  232. package/dist/utils.js +31 -93
  233. package/dist/vendor/wesleytodd-openapi/index.js +37 -51
  234. package/dist/vendor/wesleytodd-openapi/lib/generate-doc.js +32 -40
  235. package/dist/vendor/wesleytodd-openapi/lib/layer-schema.js +3 -3
  236. package/dist/vendor/wesleytodd-openapi/lib/ui.js +50 -19
  237. package/dist/vendor/wesleytodd-openapi/lib/validate.js +19 -47
  238. package/dist/versionCheckPlugin.js +52 -100
  239. package/dist/webhooks/headerValue.js +2 -2
  240. package/dist/webhooks/idempotency/memoryStore.js +16 -59
  241. package/dist/webhooks/idempotency/mongoStore.js +55 -130
  242. package/dist/webhooks/idempotency/webhookReceipt.d.ts +4 -49
  243. package/dist/webhooks/idempotency/webhookReceipt.js +14 -14
  244. package/dist/webhooks/rawBody.d.ts +1 -0
  245. package/dist/webhooks/rawBody.js +2 -1
  246. package/dist/webhooks/timingSafeEqual.js +4 -5
  247. package/dist/webhooks/verifiers/hmac.js +17 -18
  248. package/dist/webhooks/verifiers/sendgrid.js +20 -22
  249. package/dist/webhooks/verifiers/stripe.js +31 -65
  250. package/dist/webhooks/verifiers/twilio.js +23 -73
  251. package/dist/webhooks/webhooksApp.js +78 -177
  252. package/dist/zodOpenApi.js +2 -2
  253. package/package.json +34 -28
  254. package/src/__snapshots__/openApi.test.ts.snap +192 -54
  255. package/src/__snapshots__/openApiBuilder.test.ts.snap +0 -18
  256. package/src/__snapshots__/schemaMetadata.test.ts.snap +0 -1
  257. package/src/__tests__/browserLogsRoute.test.ts +165 -0
  258. package/src/adminTypes.ts +8 -0
  259. package/src/api.test.ts +39 -2
  260. package/src/api.ts +68 -0
  261. package/src/audit/auditApp.test.ts +243 -0
  262. package/src/audit/auditApp.ts +139 -0
  263. package/src/audit/auditEventModel.ts +160 -0
  264. package/src/audit/auditRouter.test.ts +456 -0
  265. package/src/audit/cloudTasksEnqueue.test.ts +124 -0
  266. package/src/audit/cloudTasksEnqueue.ts +104 -0
  267. package/src/audit/diff.ts +163 -0
  268. package/src/audit/processQueue.ts +69 -0
  269. package/src/audit/rbacSink.test.ts +86 -0
  270. package/src/audit/rbacSink.ts +42 -0
  271. package/src/audit/record.test.ts +402 -0
  272. package/src/audit/record.ts +329 -0
  273. package/src/auth.test.ts +1 -1
  274. package/src/auth.ts +1 -1
  275. package/src/authRecovery.test.ts +43 -0
  276. package/src/authRecovery.ts +16 -10
  277. package/src/authTokens.ts +6 -2
  278. package/src/authVerification.test.ts +22 -0
  279. package/src/betterAuth.ts +7 -0
  280. package/src/betterAuthSetup.test.ts +27 -0
  281. package/src/betterAuthSetup.ts +1 -0
  282. package/src/browserLogsRoute.ts +110 -0
  283. package/src/collectionRegistry.test.ts +8 -9
  284. package/src/collectionRegistry.ts +21 -1
  285. package/src/configurationPlugin.test.ts +1 -11
  286. package/src/express.d.ts +2 -0
  287. package/src/expressServer.test.ts +50 -2
  288. package/src/expressServer.ts +10 -0
  289. package/src/frameworkModelNames.test.ts +62 -0
  290. package/src/frameworkModelNames.ts +33 -0
  291. package/src/index.ts +76 -0
  292. package/src/isolated/migrateCliConnect.isolated.ts +51 -0
  293. package/src/mcp/auth.test.ts +34 -1
  294. package/src/mcp/handlers.test.ts +275 -0
  295. package/src/mcp/query.ts +3 -3
  296. package/src/mcp/toolGenerator.test.ts +81 -0
  297. package/src/migrations/cli.test.ts +353 -0
  298. package/src/migrations/cli.ts +283 -0
  299. package/src/migrations/fixtures/all-down/20260910120000-one.ts +6 -0
  300. package/src/migrations/fixtures/all-down/20260910120001-two.ts +6 -0
  301. package/src/migrations/fixtures/bad-id/20260910120000-mismatch.ts +4 -0
  302. package/src/migrations/fixtures/bad-name/not-a-migration.ts +4 -0
  303. package/src/migrations/fixtures/missing-up/20260910120000-noup.ts +2 -0
  304. package/src/migrations/fixtures/valid/20260910120000-alpha.ts +4 -0
  305. package/src/migrations/fixtures/valid/20260910120001-beta.ts +6 -0
  306. package/src/migrations/generate.test.ts +333 -0
  307. package/src/migrations/generate.ts +216 -0
  308. package/src/migrations/load.test.ts +103 -0
  309. package/src/migrations/load.ts +124 -0
  310. package/src/migrations/lock.test.ts +133 -0
  311. package/src/migrations/lock.ts +118 -0
  312. package/src/migrations/runner.test.ts +504 -0
  313. package/src/migrations/runner.ts +358 -0
  314. package/src/migrations/schemaCatalog.test.ts +159 -0
  315. package/src/migrations/schemaCatalog.ts +262 -0
  316. package/src/migrations/types.ts +94 -0
  317. package/src/models/mcpServiceToken.ts +4 -3
  318. package/src/models/notification.ts +69 -0
  319. package/src/models/notificationPreference.ts +62 -0
  320. package/src/notifications/notificationService.ts +254 -0
  321. package/src/notifications/notificationsApp.test.ts +528 -0
  322. package/src/notifications/notificationsApp.ts +200 -0
  323. package/src/notifications/notificationsBeforeSend.ts +51 -0
  324. package/src/notifiers/slackNotifier.test.ts +186 -1
  325. package/src/notifiers/slackNotifier.ts +167 -8
  326. package/src/openApi.test.ts +0 -1
  327. package/src/openApi.ts +2 -1
  328. package/src/openApiBuilder.ts +14 -3
  329. package/src/openApiValidator.test.ts +221 -2
  330. package/src/openApiValidator.ts +218 -33
  331. package/src/orgs/orgAccessOptIn.test.ts +87 -0
  332. package/src/orgs/orgContext.test.ts +259 -0
  333. package/src/orgs/orgContext.ts +151 -0
  334. package/src/orgs/orgPermissions.test.ts +105 -0
  335. package/src/orgs/orgPermissions.ts +40 -0
  336. package/src/orgs/orgPlugin.test.ts +130 -0
  337. package/src/orgs/orgPlugin.ts +70 -0
  338. package/src/orgs/orgRbac.test.ts +267 -0
  339. package/src/orgs/orgSecurityDefects.test.ts +415 -0
  340. package/src/orgs/organizationModel.test.ts +205 -0
  341. package/src/orgs/organizationModel.ts +262 -0
  342. package/src/orgs/organizationSettings.test.ts +113 -0
  343. package/src/orgs/organizationSettings.ts +126 -0
  344. package/src/orgs/orgsApp.test.ts +382 -0
  345. package/src/orgs/orgsApp.ts +563 -0
  346. package/src/permissions.test.ts +62 -36
  347. package/src/permissions.ts +8 -30
  348. package/src/plugins.test.ts +5 -0
  349. package/src/plugins.ts +3 -0
  350. package/src/rateLimit/middleware.ts +1 -1
  351. package/src/rateLimit/mongoStore.ts +1 -0
  352. package/src/rateLimit/policies.ts +2 -2
  353. package/src/rateLimit/redisStore.ts +1 -0
  354. package/src/rbac/access.ts +11 -3
  355. package/src/rbac/membershipOrgAdminSource.ts +59 -0
  356. package/src/rbac/modelRouterAccess.ts +3 -0
  357. package/src/rbac/permissionUtils.test.ts +26 -5
  358. package/src/rbac/resolve.test.ts +34 -2
  359. package/src/rbac/resolve.ts +26 -7
  360. package/src/rbac/roleModel.test.ts +34 -1
  361. package/src/rbac/roleModel.ts +17 -1
  362. package/src/rbac/statements.test.ts +19 -0
  363. package/src/rbac/statements.ts +19 -1
  364. package/src/rbac/types.ts +5 -0
  365. package/src/realtime/changeStreamWatcher.ts +73 -33
  366. package/src/realtime/deprecation.ts +1 -0
  367. package/src/realtime/realtime.test.ts +357 -185
  368. package/src/realtime/realtimeApp.ts +2 -1
  369. package/src/schemaMetadata.test.ts +14 -0
  370. package/src/schemaMetadata.ts +5 -5
  371. package/src/sync/adminBroadcastConfig.test.ts +96 -0
  372. package/src/sync/adminBroadcastScope.test.ts +155 -0
  373. package/src/sync/adminBroadcastScope.ts +123 -0
  374. package/src/sync/adminWindowAccess.test.ts +57 -0
  375. package/src/sync/adminWindowAccess.ts +32 -0
  376. package/src/sync/adminWindowMutation.test.ts +450 -0
  377. package/src/sync/adminWindowMutation.ts +283 -0
  378. package/src/sync/executors.ts +33 -6
  379. package/src/sync/integration.test.ts +2 -2
  380. package/src/sync/mutationHandler.test.ts +277 -1
  381. package/src/sync/mutationHandler.ts +171 -29
  382. package/src/sync/registry.ts +4 -0
  383. package/src/sync/routes.ts +52 -8
  384. package/src/sync/socketHandlers.ts +154 -58
  385. package/src/sync/streams.ts +6 -0
  386. package/src/sync/sync.test.ts +3 -2
  387. package/src/sync/syncApp.ts +2 -1
  388. package/src/sync/syncBatch.ts +7 -2
  389. package/src/sync/syncRoutes.test.ts +297 -3
  390. package/src/sync/syncSocket.test.ts +229 -0
  391. package/src/sync/types.ts +20 -0
  392. package/src/terrenoApp.migrations.test.ts +114 -0
  393. package/src/terrenoApp.test.ts +41 -0
  394. package/src/terrenoApp.ts +97 -31
  395. package/src/tests/createTestData.ts +2 -2
  396. package/src/tests/models.ts +10 -2
  397. package/src/tests/testHelper.ts +1 -7
  398. package/src/types/authToken.ts +2 -4
  399. package/src/types/mcpServiceToken.ts +1 -7
  400. package/src/types/membership.ts +48 -0
  401. package/src/types/notification.ts +34 -0
  402. package/src/types/notificationPreference.ts +28 -0
  403. package/src/types/organization.ts +49 -0
  404. package/src/types.d.ts +1 -0
  405. package/src/webhooks/idempotency/webhookReceipt.ts +8 -10
  406. package/src/webhooks/rawBody.test.ts +33 -0
  407. package/src/webhooks/rawBody.ts +1 -0
  408. package/tsconfig.json +13 -54
  409. package/tsconfig.typedoc.json +4 -1
  410. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.d.ts +0 -2
  411. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
  412. package/src/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
@@ -1,4 +1,5 @@
1
1
  import {beforeAll, beforeEach, describe, expect, it} from "bun:test";
2
+ import {assert} from "chai";
2
3
  import type express from "express";
3
4
  import {type Model, model, Schema, Types} from "mongoose";
4
5
  import supertest from "supertest";
@@ -9,10 +10,15 @@ import {APIError} from "../errors";
9
10
  import {OwnerQueryFilter, Permissions} from "../permissions";
10
11
  import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
11
12
  import {authAsUser, getBaseServer, setupDb, UserModel} from "../tests";
13
+ import {registerAdminBroadcastScope} from "./adminBroadcastScope";
12
14
  import {SyncCounter, SyncKey, SyncMutation} from "./models";
13
15
  import {MAX_SYNC_MUTATIONS_PER_BATCH} from "./mutationHandler";
14
- import {clearSyncRegistry, registerSync} from "./registry";
15
- import {MAX_ENTITY_FETCH, MAX_SYNC_HTTP_MUTATIONS_PER_SECOND} from "./routes";
16
+ import {clearSyncRegistry, getSyncRegistry, registerSync, type SyncRegistryEntry} from "./registry";
17
+ import {
18
+ buildSnapshotScopeFilter,
19
+ MAX_ENTITY_FETCH,
20
+ MAX_SYNC_HTTP_MUTATIONS_PER_SECOND,
21
+ } from "./routes";
16
22
  import {SyncApp} from "./syncApp";
17
23
  import {syncPlugin} from "./syncSeqPlugin";
18
24
 
@@ -67,10 +73,34 @@ routeBannerSchema.plugin(createdUpdatedPlugin);
67
73
  routeBannerSchema.plugin(syncPlugin);
68
74
  const RouteBannerModel = model<RouteBanner>("SyncRouteBanner", routeBannerSchema);
69
75
 
76
+ interface RouteNote extends IsDeleted {
77
+ _id: string;
78
+ body: string;
79
+ ownerId: string;
80
+ _syncSeq?: number;
81
+ }
82
+
83
+ // Client-minted string `_id`s (the syncdb default): entity ids are passed through uncast.
84
+ const routeNoteSchema = new Schema<RouteNote>({
85
+ _id: {description: "Client-minted note id", type: String},
86
+ body: {description: "The note body", required: true, type: String},
87
+ ownerId: {description: "The user who owns this note", type: String},
88
+ });
89
+ routeNoteSchema.plugin(isDeletedPlugin);
90
+ routeNoteSchema.plugin(createdUpdatedPlugin);
91
+ routeNoteSchema.plugin(syncPlugin);
92
+ const RouteNoteModel = model<RouteNote>("SyncRouteNote", routeNoteSchema);
93
+
70
94
  interface SnapshotEntity {
71
95
  id: string;
72
96
  seq: number;
73
- data: {name: string};
97
+ deleted: boolean;
98
+ data: {name: string} | null;
99
+ }
100
+
101
+ interface StreamInfo {
102
+ collection: string;
103
+ stream: string;
74
104
  }
75
105
 
76
106
  interface MutationResult {
@@ -198,6 +228,37 @@ describe("sync routes", () => {
198
228
  await agent.get(`/sync/snapshot?stream=${s}&limit=1e9`).expect(400);
199
229
  });
200
230
 
231
+ it("400s for an all-digit cursor that is not a safe integer", async () => {
232
+ const s = encodeURIComponent(ownerStream());
233
+ const res = await agent
234
+ .get(`/sync/snapshot?stream=${s}&cursor=99999999999999999999`)
235
+ .expect(400);
236
+ expect(res.body.title).toMatch(/Invalid cursor/);
237
+ });
238
+
239
+ it("surfaces scope-move markers as tombstones on the old stream (C4)", async () => {
240
+ const doc = await RouteStuffModel.create({name: "moving", ownerId: notAdminId});
241
+ const initial = await agent
242
+ .get(`/sync/snapshot?stream=${encodeURIComponent(ownerStream())}`)
243
+ .expect(200);
244
+ expect(initial.body.entities.map((e: SnapshotEntity) => e.id)).toEqual([String(doc._id)]);
245
+
246
+ doc.ownerId = "someoneElse";
247
+ await doc.save();
248
+
249
+ const res = await agent
250
+ .get(
251
+ `/sync/snapshot?stream=${encodeURIComponent(ownerStream())}&cursor=${initial.body.cursor}`
252
+ )
253
+ .expect(200);
254
+ const tombstone = res.body.entities.find((e: SnapshotEntity) => e.id === String(doc._id));
255
+ expect(tombstone).toBeDefined();
256
+ expect(tombstone.deleted).toBe(true);
257
+ expect(tombstone.data).toBeNull();
258
+ expect(tombstone.seq).toBeGreaterThan(initial.body.cursor);
259
+ expect(res.body.hasMore).toBe(false);
260
+ });
261
+
201
262
  it("enforces the model's list permissions", async () => {
202
263
  clearSyncRegistry();
203
264
  registerSync({
@@ -342,6 +403,132 @@ describe("sync routes", () => {
342
403
  });
343
404
  });
344
405
 
406
+ describe("buildSnapshotScopeFilter", () => {
407
+ it("500s for a custom scope entry that has no snapshotFilter result", () => {
408
+ // Registration rejects this shape up front, so build the entry directly.
409
+ const entry: SyncRegistryEntry = {
410
+ collectionName: "syncroutestuffs",
411
+ collectionTag: "routeStuff",
412
+ config: {scope: () => "custom"},
413
+ modelName: RouteStuffModel.modelName,
414
+ options: authedOptions,
415
+ routePath: "/routeStuff",
416
+ };
417
+ expect(() => buildSnapshotScopeFilter({entry, scopeValue: "custom"})).toThrow(
418
+ expect.objectContaining({status: 500, title: expect.stringMatching(/snapshotFilter/)})
419
+ );
420
+ });
421
+
422
+ it("returns the snapshotFilter result for a custom scope", () => {
423
+ clearSyncRegistry();
424
+ registerSync({
425
+ config: {
426
+ scope: () => "custom",
427
+ snapshotFilter: () => ({name: "keep"}),
428
+ },
429
+ model: RouteStuffModel as unknown as Model<unknown>,
430
+ options: authedOptions,
431
+ routePath: "/routeStuff",
432
+ });
433
+ const [entry] = getSyncRegistry();
434
+ expect(
435
+ buildSnapshotScopeFilter({
436
+ entry,
437
+ scopeValue: "custom",
438
+ snapshotFilterResult: {name: "keep"},
439
+ })
440
+ ).toEqual({name: "keep"});
441
+ });
442
+ });
443
+
444
+ describe("GET /sync/streams", () => {
445
+ it("requires authentication", async () => {
446
+ await server.get("/sync/streams").expect(401);
447
+ });
448
+
449
+ it("omits collections the caller is not allowed to list", async () => {
450
+ registerSync({
451
+ config: {scope: {type: "broadcast"}},
452
+ model: RouteBannerModel as unknown as Model<unknown>,
453
+ options: adminOnlyOptions,
454
+ routePath: "/routeBanners",
455
+ });
456
+
457
+ const res = await agent.get("/sync/streams").expect(200);
458
+ const collections = res.body.streams.map((s: StreamInfo) => s.collection);
459
+ expect(collections).toContain("routeStuff");
460
+ expect(collections).not.toContain("routeBanners");
461
+
462
+ const adminRes = await adminAgent.get("/sync/streams").expect(200);
463
+ expect(adminRes.body.streams).toContainEqual({
464
+ collection: "routeBanners",
465
+ stream: "routeBanners|all",
466
+ });
467
+ });
468
+
469
+ it("500s when a tenant collection has no getUserScopes resolver", async () => {
470
+ const bareApp = getBaseServer();
471
+ setupAuth(bareApp, UserModel as unknown as AuthUserModel);
472
+ addAuthRoutes(bareApp, UserModel as unknown as AuthUserModel);
473
+ new SyncApp().register(bareApp);
474
+ const bareAgent = await authAsUser(bareApp, "notAdmin");
475
+
476
+ const res = await bareAgent.get("/sync/streams").expect(500);
477
+ expect(res.body.title).toMatch(/Failed to resolve streams for routeProjects/);
478
+ });
479
+ });
480
+
481
+ describe("GET /sync/entities", () => {
482
+ it("requires authentication", async () => {
483
+ await server.get("/sync/entities?collection=routeStuff&ids=abc").expect(401);
484
+ });
485
+
486
+ it("400s when the collection parameter is missing", async () => {
487
+ const res = await agent.get("/sync/entities?ids=abc").expect(400);
488
+ expect(res.body.title).toMatch(/collection/);
489
+ });
490
+
491
+ it("400s when no ids are supplied", async () => {
492
+ const res = await agent.get("/sync/entities?collection=routeStuff&ids=,").expect(400);
493
+ expect(res.body.title).toMatch(/ids/);
494
+ });
495
+
496
+ it("404s for an unknown collection", async () => {
497
+ const res = await agent.get("/sync/entities?collection=nope&ids=abc").expect(404);
498
+ expect(res.body.title).toMatch(/Unknown sync collection: nope/);
499
+ });
500
+
501
+ it("403s when the caller may not list the collection", async () => {
502
+ registerSync({
503
+ config: {scope: {type: "broadcast"}},
504
+ model: RouteBannerModel as unknown as Model<unknown>,
505
+ options: adminOnlyOptions,
506
+ routePath: "/routeBanners",
507
+ });
508
+ const doc = await RouteBannerModel.create({name: "secret", ownerId: adminId});
509
+ const res = await agent
510
+ .get(`/sync/entities?collection=routeBanners&ids=${doc._id}`)
511
+ .expect(403);
512
+ expect(res.body.title).toMatch(/denied/);
513
+ });
514
+
515
+ it("passes string ids through uncast for models with string _ids", async () => {
516
+ registerSync({
517
+ config: {scope: {type: "owner"}},
518
+ model: RouteNoteModel as unknown as Model<unknown>,
519
+ options: authedOptions,
520
+ routePath: "/routeNotes",
521
+ });
522
+ await RouteNoteModel.collection.deleteMany({});
523
+ await RouteNoteModel.create({_id: "note-1", body: "hello", ownerId: notAdminId});
524
+
525
+ const res = await agent
526
+ .get("/sync/entities?collection=routeNotes&ids=note-1,not-an-object-id")
527
+ .expect(200);
528
+ expect(res.body.entities.map((e: SnapshotEntity) => e.id)).toEqual(["note-1"]);
529
+ });
530
+ });
531
+
345
532
  describe("POST /sync/mutate", () => {
346
533
  it("requires authentication", async () => {
347
534
  await server
@@ -753,6 +940,113 @@ describe("sync routes", () => {
753
940
  });
754
941
  });
755
942
 
943
+ describe("GET /sync/entities admin window (Task 3.4)", () => {
944
+ it("returns another owner's ids for an admin when adminBroadcast is true", async () => {
945
+ clearSyncRegistry();
946
+ registerSync({
947
+ config: {adminBroadcast: true, scope: {type: "owner"}},
948
+ model: RouteStuffModel as unknown as Model<unknown>,
949
+ options: authedOptions,
950
+ routePath: "/routeStuff",
951
+ });
952
+ const mine = await RouteStuffModel.create({name: "theirs", ownerId: notAdminId});
953
+ const missingId = new Types.ObjectId().toString();
954
+
955
+ const res = await adminAgent
956
+ .get(`/sync/entities?collection=routeStuff&ids=${mine._id},${missingId}`)
957
+ .expect(200);
958
+ assert.equal(res.body.entities.length, 1);
959
+ assert.equal(res.body.entities[0].id, String(mine._id));
960
+ });
961
+
962
+ it("still scopes a non-admin to streams they belong to when adminBroadcast is true", async () => {
963
+ clearSyncRegistry();
964
+ registerSync({
965
+ config: {adminBroadcast: true, scope: {type: "owner"}},
966
+ model: RouteStuffModel as unknown as Model<unknown>,
967
+ options: authedOptions,
968
+ routePath: "/routeStuff",
969
+ });
970
+ const theirs = await RouteStuffModel.create({name: "admin-owned", ownerId: adminId});
971
+
972
+ const res = await agent
973
+ .get(`/sync/entities?collection=routeStuff&ids=${theirs._id}`)
974
+ .expect(200);
975
+ assert.deepEqual(res.body.entities, []);
976
+ });
977
+
978
+ it("does not cross-owner hydrate when accessControl denies admin:access", async () => {
979
+ clearSyncRegistry();
980
+ registerSync({
981
+ config: {adminBroadcast: true, scope: {type: "owner"}},
982
+ model: RouteStuffModel as unknown as Model<unknown>,
983
+ options: authedOptions,
984
+ routePath: "/routeStuff",
985
+ });
986
+ const theirs = await RouteStuffModel.create({name: "flag-admin-owned", ownerId: notAdminId});
987
+ const gatedApp = getBaseServer();
988
+ setupAuth(gatedApp, UserModel as unknown as AuthUserModel);
989
+ addAuthRoutes(gatedApp, UserModel as unknown as AuthUserModel);
990
+ new SyncApp({
991
+ accessControl: {
992
+ can: async () => ({allowed: false}),
993
+ } as never,
994
+ getUserScopes: () => ["org1"],
995
+ }).register(gatedApp);
996
+ const gatedAdmin = await authAsUser(gatedApp, "admin");
997
+
998
+ const res = await gatedAdmin
999
+ .get(`/sync/entities?collection=routeStuff&ids=${theirs._id}`)
1000
+ .expect(200);
1001
+ assert.deepEqual(res.body.entities, []);
1002
+ });
1003
+
1004
+ it("omits ids excluded by a registered AdminApp queryFilter", async () => {
1005
+ clearSyncRegistry();
1006
+ registerSync({
1007
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1008
+ model: RouteStuffModel as unknown as Model<unknown>,
1009
+ options: authedOptions,
1010
+ routePath: "/routeStuff",
1011
+ });
1012
+ registerAdminBroadcastScope("SyncRouteStuff", {
1013
+ listPermissions: [() => true],
1014
+ queryFilter: () => ({ownerId: adminId}),
1015
+ readPermissions: [() => true],
1016
+ });
1017
+ const inScope = await RouteStuffModel.create({name: "in-tenant", ownerId: adminId});
1018
+ const outOfScope = await RouteStuffModel.create({name: "other-tenant", ownerId: notAdminId});
1019
+
1020
+ const res = await adminAgent
1021
+ .get(`/sync/entities?collection=routeStuff&ids=${inScope._id},${outOfScope._id}`)
1022
+ .expect(200);
1023
+ assert.deepEqual(
1024
+ res.body.entities.map((entity: SnapshotEntity) => entity.id),
1025
+ [String(inScope._id)]
1026
+ );
1027
+ });
1028
+
1029
+ it("returns no entities when AdminApp list permission is denied", async () => {
1030
+ clearSyncRegistry();
1031
+ registerSync({
1032
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1033
+ model: RouteStuffModel as unknown as Model<unknown>,
1034
+ options: authedOptions,
1035
+ routePath: "/routeStuff",
1036
+ });
1037
+ registerAdminBroadcastScope("SyncRouteStuff", {
1038
+ listPermissions: [() => false],
1039
+ readPermissions: [() => true],
1040
+ });
1041
+ const theirs = await RouteStuffModel.create({name: "hidden-model", ownerId: notAdminId});
1042
+
1043
+ const res = await adminAgent
1044
+ .get(`/sync/entities?collection=routeStuff&ids=${theirs._id}`)
1045
+ .expect(200);
1046
+ assert.deepEqual(res.body.entities, []);
1047
+ });
1048
+ });
1049
+
756
1050
  describe("GET /sync/key", () => {
757
1051
  it("requires authentication", async () => {
758
1052
  await server.get("/sync/key").expect(401);
@@ -9,6 +9,7 @@
9
9
  */
10
10
 
11
11
  import {afterEach, beforeAll, beforeEach, describe, expect, it} from "bun:test";
12
+ import {assert} from "chai";
12
13
  import mongoose, {type Model, model, Schema} from "mongoose";
13
14
  import type {Server} from "socket.io";
14
15
 
@@ -22,6 +23,7 @@ import {
22
23
  import {clearRealtimeRegistry, registerRealtime} from "../realtime/registry";
23
24
  import {setupDb} from "../tests";
24
25
  import {defaultResponseHandler} from "../transformers";
26
+ import {registerAdminBroadcastScope} from "./adminBroadcastScope";
25
27
  import {SyncCounter, SyncMutation, SyncScopeMove} from "./models";
26
28
  import {MAX_SYNC_MUTATIONS_PER_BATCH} from "./mutationHandler";
27
29
  import {
@@ -271,6 +273,102 @@ describe("installSyncSocketHandlers — subscribe/unsubscribe", () => {
271
273
  });
272
274
  });
273
275
 
276
+ it("window mode joins {collection}|admin and does not emit snapshot pages", async () => {
277
+ clearSyncRegistry();
278
+ registerSync({
279
+ config: {adminBroadcast: true, scope: {type: "owner"}},
280
+ model: SockStuffModel as unknown as Model<unknown>,
281
+ options: ownerReadOptions,
282
+ routePath: "/sockStuff",
283
+ });
284
+ const socket = createMockSocket({admin: true, id: "user1"});
285
+ install(socket);
286
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
287
+
288
+ assert.isTrue(socket.rooms.has("sync:sockStuff|admin"));
289
+ assert.isFalse(socket.rooms.has("sync:sockStuff|owner:user1"));
290
+ const subscribed = socket.emitted.filter((e) => e.event === "sync:subscribed");
291
+ assert.deepEqual(
292
+ subscribed.map((e) => e.payload),
293
+ [{collection: "sockStuff", mode: "window", streams: ["sockStuff|admin"]}]
294
+ );
295
+ const snapshotLike = socket.emitted.filter(
296
+ (e) => e.event.includes("snapshot") || (e.payload as {entities?: unknown})?.entities
297
+ );
298
+ assert.deepEqual(snapshotLike, []);
299
+ });
300
+
301
+ it("nacks window subscribe when the caller is not admin", async () => {
302
+ clearSyncRegistry();
303
+ registerSync({
304
+ config: {adminBroadcast: true, scope: {type: "owner"}},
305
+ model: SockStuffModel as unknown as Model<unknown>,
306
+ options: ownerReadOptions,
307
+ routePath: "/sockStuff",
308
+ });
309
+ const socket = createMockSocket({admin: false, id: "user1"});
310
+ install(socket);
311
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
312
+
313
+ assert.isFalse(socket.rooms.has("sync:sockStuff|admin"));
314
+ assert.deepEqual(
315
+ socket.emitted.filter((e) => e.event === "sync:subscribed"),
316
+ []
317
+ );
318
+ const errors = syncErrors(socket);
319
+ assert.equal(errors.length, 1);
320
+ assert.equal(errors[0].collection, "sockStuff");
321
+ assert.match(errors[0].message, /admin/i);
322
+ });
323
+
324
+ it("nacks window subscribe when accessControl denies admin:access", async () => {
325
+ clearSyncRegistry();
326
+ registerSync({
327
+ config: {adminBroadcast: true, scope: {type: "owner"}},
328
+ model: SockStuffModel as unknown as Model<unknown>,
329
+ options: ownerReadOptions,
330
+ routePath: "/sockStuff",
331
+ });
332
+ const socket = createMockSocket({admin: true, id: "user1"});
333
+ install(socket, {
334
+ accessControl: {
335
+ can: async () => ({allowed: false}),
336
+ } as never,
337
+ });
338
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
339
+
340
+ assert.isFalse(socket.rooms.has("sync:sockStuff|admin"));
341
+ assert.deepEqual(
342
+ socket.emitted.filter((e) => e.event === "sync:subscribed"),
343
+ []
344
+ );
345
+ const errors = syncErrors(socket);
346
+ assert.equal(errors.length, 1);
347
+ assert.match(errors[0].message, /admin panel access/i);
348
+ });
349
+
350
+ it("nacks window subscribe when AdminApp list permission is denied", async () => {
351
+ clearSyncRegistry();
352
+ registerSync({
353
+ config: {adminBroadcast: true, scope: {type: "owner"}},
354
+ model: SockStuffModel as unknown as Model<unknown>,
355
+ options: ownerReadOptions,
356
+ routePath: "/sockStuff",
357
+ });
358
+ registerAdminBroadcastScope("SockStuff", {
359
+ listPermissions: [() => false],
360
+ readPermissions: [() => true],
361
+ });
362
+ const socket = createMockSocket({admin: true, id: "user1"});
363
+ install(socket);
364
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
365
+
366
+ assert.isFalse(socket.rooms.has("sync:sockStuff|admin"));
367
+ const errors = syncErrors(socket);
368
+ assert.equal(errors.length, 1);
369
+ assert.match(errors[0].message, /admin collection access/i);
370
+ });
371
+
274
372
  it("owner scope never uses a client-supplied user id", async () => {
275
373
  const socket = createMockSocket({id: "user1"});
276
374
  install(socket);
@@ -1027,6 +1125,100 @@ describe("emitSyncDeltaForChange", () => {
1027
1125
  expect((delta.data as Record<string, unknown>).id).toBe("doc-1");
1028
1126
  });
1029
1127
 
1128
+ it("adminBroadcast true: create also emits to {collection}|admin", async () => {
1129
+ clearSyncRegistry();
1130
+ registerSync({
1131
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1132
+ model: SockStuffModel as unknown as Model<unknown>,
1133
+ options: ownerReadOptions,
1134
+ routePath: "/sockStuff",
1135
+ });
1136
+ const entry = findSyncEntryByCollectionTag("sockStuff") as SyncRegistryEntry;
1137
+ const io = makeTrackedIo();
1138
+ io.addSocketToRoom(syncRoomForStream("sockStuff|owner:user1"), {admin: false, id: "user1"});
1139
+ io.addSocketToRoom(syncRoomForStream("sockStuff|admin"), {admin: true, id: "admin1"});
1140
+
1141
+ await emitSyncDeltaForChange({
1142
+ change: makeChange({
1143
+ fullDocument: {_id: "doc-admin-fan", _syncSeq: 11, name: "hello", ownerId: "user1"},
1144
+ operationType: "insert",
1145
+ }),
1146
+ docId: "doc-admin-fan",
1147
+ entry,
1148
+ io,
1149
+ logDebug: () => {},
1150
+ });
1151
+
1152
+ const deltas = io.emissions
1153
+ .filter((e) => e.event === "sync:delta")
1154
+ .map((e) => e.payload as SyncDelta);
1155
+ const streams = deltas.map((d) => d.stream).sort();
1156
+ assert.deepEqual(streams, ["sockStuff|admin", "sockStuff|owner:user1"]);
1157
+ const adminDelta = deltas.find((d) => d.stream === "sockStuff|admin");
1158
+ const ownerDelta = deltas.find((d) => d.stream === "sockStuff|owner:user1");
1159
+ assert.strictEqual(adminDelta?.method, "create");
1160
+ assert.strictEqual(adminDelta?.seq, 11);
1161
+ assert.strictEqual(ownerDelta?.method, "create");
1162
+ assert.strictEqual(ownerDelta?.seq, 11);
1163
+ });
1164
+
1165
+ it("adminBroadcast room skips sockets excluded by AdminApp queryFilter", async () => {
1166
+ clearSyncRegistry();
1167
+ registerSync({
1168
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1169
+ model: SockStuffModel as unknown as Model<unknown>,
1170
+ options: ownerReadOptions,
1171
+ routePath: "/sockStuff",
1172
+ });
1173
+ registerAdminBroadcastScope("SockStuff", {
1174
+ listPermissions: [() => true],
1175
+ queryFilter: () => ({ownerId: "acme"}),
1176
+ readPermissions: [() => true],
1177
+ });
1178
+ const entry = findSyncEntryByCollectionTag("sockStuff") as SyncRegistryEntry;
1179
+ const io = makeTrackedIo();
1180
+ io.addSocketToRoom(syncRoomForStream("sockStuff|admin"), {admin: true, id: "admin1"});
1181
+
1182
+ await emitSyncDeltaForChange({
1183
+ change: makeChange({
1184
+ fullDocument: {_id: "doc-other-tenant", _syncSeq: 12, name: "hello", ownerId: "user1"},
1185
+ operationType: "insert",
1186
+ }),
1187
+ docId: "doc-other-tenant",
1188
+ entry,
1189
+ io,
1190
+ logDebug: () => {},
1191
+ });
1192
+
1193
+ const adminDeltas = io.emissions.filter(
1194
+ (e) => e.event === "sync:delta" && (e.payload as SyncDelta).stream === "sockStuff|admin"
1195
+ );
1196
+ assert.deepEqual(adminDeltas, []);
1197
+ });
1198
+
1199
+ it("adminBroadcast false: create emits only the owner stream", async () => {
1200
+ const entry = ownerEntry();
1201
+ const io = makeTrackedIo();
1202
+ io.addSocketToRoom(syncRoomForStream("sockStuff|owner:user1"), {admin: false, id: "user1"});
1203
+ io.addSocketToRoom(syncRoomForStream("sockStuff|admin"), {admin: true, id: "admin1"});
1204
+
1205
+ await emitSyncDeltaForChange({
1206
+ change: makeChange({
1207
+ fullDocument: {_id: "doc-no-fan", _syncSeq: 2, name: "hello", ownerId: "user1"},
1208
+ operationType: "insert",
1209
+ }),
1210
+ docId: "doc-no-fan",
1211
+ entry,
1212
+ io,
1213
+ logDebug: () => {},
1214
+ });
1215
+
1216
+ const streams = io.emissions
1217
+ .filter((e) => e.event === "sync:delta")
1218
+ .map((e) => (e.payload as SyncDelta).stream);
1219
+ assert.deepEqual(streams, ["sockStuff|owner:user1"]);
1220
+ });
1221
+
1030
1222
  it("emits a delta when the REST responseHandler serializes a BSON post-image", async () => {
1031
1223
  const entry = ownerEntry();
1032
1224
  entry.options = {
@@ -1245,6 +1437,43 @@ describe("emitSyncDeltaForChange", () => {
1245
1437
  expect(io.emissions.filter((e) => e.event === "sync:delta")).toHaveLength(0);
1246
1438
  });
1247
1439
 
1440
+ it("logs and skips changes without a full document", async () => {
1441
+ const entry = ownerEntry();
1442
+ const io = makeTrackedIo();
1443
+ const logs: string[] = [];
1444
+
1445
+ await emitSyncDeltaForChange({
1446
+ change: makeChange({operationType: "update"}),
1447
+ docId: "doc-no-image",
1448
+ entry,
1449
+ io,
1450
+ logDebug: (message) => logs.push(message),
1451
+ });
1452
+
1453
+ assert.deepEqual(logs, ["[sync] Skipping sockStuff/doc-no-image: change has no fullDocument"]);
1454
+ assert.isEmpty(io.emissions);
1455
+ });
1456
+
1457
+ it("skips changes whose operation type does not map to a sync method", async () => {
1458
+ const entry = ownerEntry();
1459
+ const io = makeTrackedIo();
1460
+ const logs: string[] = [];
1461
+
1462
+ await emitSyncDeltaForChange({
1463
+ change: makeChange({
1464
+ fullDocument: {_id: "doc-invalid", _syncSeq: 1, ownerId: "user1"},
1465
+ operationType: "invalidate",
1466
+ }),
1467
+ docId: "doc-invalid",
1468
+ entry,
1469
+ io,
1470
+ logDebug: (message) => logs.push(message),
1471
+ });
1472
+
1473
+ assert.isEmpty(logs);
1474
+ assert.isEmpty(io.emissions);
1475
+ });
1476
+
1248
1477
  it("applies the sync responseHandler to delta data", async () => {
1249
1478
  clearSyncRegistry();
1250
1479
  registerSync({
package/src/sync/types.ts CHANGED
@@ -39,6 +39,13 @@ export type SyncScope = SyncScopeOwner | SyncScopeTenant | SyncScopeBroadcast |
39
39
  * (seq stamping) — validated at registration.
40
40
  */
41
41
  export interface SyncConfig {
42
+ /**
43
+ * When true, change-stream `sync:delta` emission also fans in to `{collection}|admin`
44
+ * in addition to the owner/tenant/broadcast/custom stream. Default false. App clients
45
+ * keep their existing scope; only admin window subscribers join `|admin`. Join
46
+ * permission is admin-only (same checks as `/admin/*`), not owner-stream membership.
47
+ */
48
+ adminBroadcast?: boolean;
42
49
  /** Which stream a document belongs to. Multi-tenant by default via the tenant scope. */
43
50
  scope: SyncScope;
44
51
  /**
@@ -65,6 +72,12 @@ export interface SyncConfig {
65
72
 
66
73
  export type SyncMutationOperation = "create" | "update" | "delete";
67
74
 
75
+ /** Explicit client marker for admin-panel windowed sync writes. */
76
+ export type SyncMutationMode = "adminWindow";
77
+
78
+ /** `sync:subscribe` / `sync:subscribed` window mode for admin fan-in (no snapshot paging). */
79
+ export type SyncSubscribeMode = "window";
80
+
68
81
  /** A single entity in a snapshot response. */
69
82
  export interface SyncEntityPayload {
70
83
  /** Document id. */
@@ -138,6 +151,13 @@ export interface SyncMutateRequest {
138
151
  data?: Record<string, unknown>;
139
152
  /** The `_syncSeq` the client last saw for this document; enables LWW conflict detection. */
140
153
  baseVersion?: number;
154
+ /**
155
+ * When `"adminWindow"`, the server applies AdminApp write semantics (RBAC,
156
+ * writeOwned, readonly/hidden stripping, audit) instead of product sync
157
+ * permissions. Ignored unless the collection is `adminBroadcast`, the caller
158
+ * has admin-window access, and AdminApp registered a write scope.
159
+ */
160
+ mutationMode?: SyncMutationMode;
141
161
  }
142
162
 
143
163
  /** Successful mutation acknowledgement. */