@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
@@ -6,6 +6,13 @@ import {APIError, apiErrorMiddleware, apiUnauthorizedMiddleware} from "../errors
6
6
  import {logger} from "../logger";
7
7
  import {checkPermissions} from "../permissions";
8
8
  import {findOneOrNoneFor} from "../plugins";
9
+ import type {AnyTerrenoAccess} from "../rbac/types";
10
+ import {
11
+ canListAdminBroadcastScope,
12
+ getAdminBroadcastScope,
13
+ resolveAdminBroadcastQueryFilter,
14
+ } from "./adminBroadcastScope";
15
+ import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
9
16
  import {
10
17
  computeStableFrontier,
11
18
  getCompactedThroughSeq,
@@ -54,6 +61,18 @@ export interface SyncAppOptions {
54
61
  getUserScopes?: (user: User, entry: SyncRegistryEntry) => Promise<string[]> | string[];
55
62
  /** Default page size for snapshots (default 100, max 100). */
56
63
  defaultSnapshotLimit?: number;
64
+ /**
65
+ * When set, `{collection}|admin` window subscribe and cross-owner entity
66
+ * hydrate require `admin:access` instead of the legacy `user.admin` flag.
67
+ * AdminApp also registers per-model list/read/`queryFilter` so hydrate and
68
+ * `|admin` deltas match `/admin` REST, not product `IsOwner`.
69
+ */
70
+ accessControl?: AnyTerrenoAccess;
71
+ /**
72
+ * Override the admin-window gate. Defaults to `admin:access` when
73
+ * `accessControl` is set, otherwise `Permissions.IsAdmin`.
74
+ */
75
+ canOpenAdminWindow?: (user: User) => boolean | Promise<boolean>;
57
76
  }
58
77
 
59
78
  const MAX_SNAPSHOT_LIMIT = 100;
@@ -696,17 +715,38 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
696
715
  });
697
716
  }
698
717
 
699
- const memberStreams = await resolveUserStreamsForEntry({
700
- entry,
701
- getUserScopes: options.getUserScopes,
702
- user,
703
- });
718
+ const isAdminWindow =
719
+ entry.config.adminBroadcast === true &&
720
+ (await canUseAdminBroadcastWindow({
721
+ accessControl: options.accessControl,
722
+ canOpenAdminWindow: options.canOpenAdminWindow,
723
+ user,
724
+ }));
725
+ const adminScope = isAdminWindow ? getAdminBroadcastScope(entry.modelName) : undefined;
726
+ if (adminScope && !(await canListAdminBroadcastScope({scope: adminScope, user}))) {
727
+ const deniedResponse: SyncEntitiesResponse = {entities: []};
728
+ return res.json(deniedResponse);
729
+ }
730
+
731
+ const memberStreams = isAdminWindow
732
+ ? []
733
+ : await resolveUserStreamsForEntry({
734
+ entry,
735
+ getUserScopes: options.getUserScopes,
736
+ user,
737
+ });
704
738
  const memberSet = new Set(memberStreams);
705
739
 
706
740
  // Task 9.19: mirror the REST list endpoint's row-level scoping. Without this, a
707
741
  // collection that relies on `queryFilter` (rather than a per-doc read permission)
708
742
  // served every requested id here, whatever the caller was allowed to list.
709
- const queryFilterResult = await resolveSyncQueryFilter({entry, user});
743
+ // Admin window hydrate skips the *product* filter so REST-selected ids can load
744
+ // across owners, then applies AdminApp list/read/`queryFilter` when registered.
745
+ const queryFilterResult = adminScope
746
+ ? await resolveAdminBroadcastQueryFilter({scope: adminScope, user})
747
+ : isAdminWindow
748
+ ? {denied: false as const, filter: undefined}
749
+ : await resolveSyncQueryFilter({entry, user});
710
750
  if (queryFilterResult.denied) {
711
751
  const deniedResponse: SyncEntitiesResponse = {entities: []};
712
752
  return res.json(deniedResponse);
@@ -726,7 +766,9 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
726
766
 
727
767
  const entities: SyncEntityPayload[] = [];
728
768
  for (const doc of docs as mongoose.Document[]) {
729
- const allowed = await checkPermissions("read", entry.options.permissions.read, user, doc);
769
+ const allowed = adminScope
770
+ ? await checkPermissions("read", adminScope.readPermissions, user, doc)
771
+ : await checkPermissions("read", entry.options.permissions.read, user, doc);
730
772
  if (!allowed) {
731
773
  continue;
732
774
  }
@@ -736,7 +778,7 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
736
778
  doc: docObj,
737
779
  scope: entry.config.scope,
738
780
  });
739
- if (!memberSet.has(stream)) {
781
+ if (!isAdminWindow && !memberSet.has(stream)) {
740
782
  continue;
741
783
  }
742
784
  const isTombstone = Boolean(docObj.deleted);
@@ -767,6 +809,7 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
767
809
  mutation: req.body as SyncMutateRequest,
768
810
  req,
769
811
  scopeResolver: options.getUserScopes,
812
+ syncOptions: options,
770
813
  user,
771
814
  });
772
815
  if (outcome.type === "ack") {
@@ -794,6 +837,7 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
794
837
  mutations,
795
838
  req,
796
839
  scopeResolver: options.getUserScopes,
840
+ syncOptions: options,
797
841
  user,
798
842
  });
799
843
  if (stage === "validation") {
@@ -1,13 +1,21 @@
1
+ import type express from "express";
1
2
  import type {Server} from "socket.io";
2
3
 
3
4
  import type {User} from "../auth";
4
5
  import {logger} from "../logger";
6
+ import {ORGANIZATION_ID_HEADER} from "../orgs/orgContext";
5
7
  import {checkPermissions} from "../permissions";
6
8
  import {awaitSocketFullUser, type SocketWithDecodedToken} from "../realtime/socketUser";
9
+ import {canListAdminBroadcastScope, getAdminBroadcastScope} from "./adminBroadcastScope";
10
+ import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
7
11
  import type {SyncMutationOutcome} from "./mutationHandler";
8
12
  import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
9
13
  import type {SyncAppOptions} from "./routes";
10
- import {MissingScopeResolverError, resolveUserStreamsForEntry} from "./streams";
14
+ import {
15
+ adminBroadcastStream,
16
+ MissingScopeResolverError,
17
+ resolveUserStreamsForEntry,
18
+ } from "./streams";
11
19
  import {runSyncBatch, runSyncMutation} from "./syncBatch";
12
20
  import type {
13
21
  SyncMutateBatchRequest,
@@ -16,20 +24,53 @@ import type {
16
24
  SyncNack,
17
25
  } from "./types";
18
26
 
27
+ const requestFromOrganizationId = ({
28
+ organizationId,
29
+ user,
30
+ }: {
31
+ organizationId?: string;
32
+ user: User;
33
+ }): express.Request => {
34
+ const trimmed = organizationId?.trim();
35
+ if (!trimmed) {
36
+ return {user} as unknown as express.Request;
37
+ }
38
+ return {
39
+ header: (name: string): string | undefined => {
40
+ return String(name).toLowerCase() === ORGANIZATION_ID_HEADER ? trimmed : undefined;
41
+ },
42
+ user,
43
+ } as unknown as express.Request;
44
+ };
45
+
46
+ const organizationIdFromPayload = (payload: unknown): string | undefined => {
47
+ if (typeof payload !== "object" || payload === null) {
48
+ return undefined;
49
+ }
50
+ const organizationId = (payload as {organizationId?: unknown}).organizationId;
51
+ return typeof organizationId === "string" ? organizationId : undefined;
52
+ };
53
+
19
54
  /**
20
55
  * Socket handlers for the SyncDB local-first protocol:
21
56
  *
22
- * - `sync:subscribe {collections}` / `sync:unsubscribe {collections}` — resolves the
57
+ * - `sync:subscribe {collections, mode?}` / `sync:unsubscribe {collections}` — resolves the
23
58
  * caller's streams from the sync registry scope config and joins/leaves `sync:{stream}`
24
59
  * rooms. Owner scopes always use the socket's own userId (never a client-supplied one);
25
60
  * tenant and custom scopes resolve stream values via `SyncAppOptions.getUserScopes`.
61
+ * `mode: "window"` joins `{collection}|admin` only (requires `adminBroadcast` and
62
+ * admin panel access: `admin:access` when `SyncApp` has `accessControl`, else
63
+ * `user.admin`). When AdminApp has registered a broadcast scope, list
64
+ * permission for that model is required as well. Confirms with
65
+ * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
26
66
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
27
67
  * legacy realtime rooms so the two event families never overlap.
28
68
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
29
69
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
30
70
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
31
71
  * - `sync:error {collection, message}` — emitted for per-collection subscribe failures
32
- * (unknown collection, permission denied, missing scope resolver, cap exceeded).
72
+ * (unknown collection, permission denied, non-admin window subscribe, missing scope
73
+ * resolver, cap exceeded).
33
74
  *
34
75
  * ## Wiring
35
76
  *
@@ -133,67 +174,112 @@ export const installSyncSocketHandlers = (
133
174
  socket.data.syncSubscriptions = subscriptions;
134
175
  }
135
176
 
136
- socket.on("sync:subscribe", async (payload: {collections?: unknown}): Promise<void> => {
137
- const collections = Array.isArray(payload?.collections) ? payload.collections : null;
138
- if (!collections) {
139
- return;
140
- }
141
- // C8: reject an oversized array up front (length check before iterating).
142
- if (collections.length > MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH) {
143
- logInfo(`[sync] User ${userId} sent an oversized sync:subscribe array`);
144
- socket.emit("sync:error", {
145
- collection: "",
146
- message: `sync:subscribe accepts at most ${MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH} collections`,
147
- });
148
- return;
149
- }
150
- for (const collection of collections) {
151
- if (typeof collection !== "string" || collection.length === 0) {
152
- continue;
153
- }
154
- if (subscriptions.has(collection)) {
155
- // Already subscribed — idempotent.
156
- continue;
157
- }
158
- if (subscriptions.size >= MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
159
- logInfo(`[sync] User ${userId} hit sync collection subscription limit`);
160
- socket.emit("sync:error", {
161
- collection,
162
- message: `Sync subscription limit of ${MAX_SYNC_COLLECTION_SUBSCRIPTIONS} collections reached`,
163
- });
164
- continue;
165
- }
166
- const entry = findSyncEntryByCollectionTag(collection);
167
- if (!entry) {
168
- socket.emit("sync:error", {collection, message: `Unknown sync collection: ${collection}`});
169
- continue;
170
- }
171
- const user = await currentUser();
172
- if (!user) {
173
- socket.emit("sync:error", {collection, message: "Authentication required"});
174
- continue;
177
+ socket.on(
178
+ "sync:subscribe",
179
+ async (payload: {collections?: unknown; mode?: unknown}): Promise<void> => {
180
+ const collections = Array.isArray(payload?.collections) ? payload.collections : null;
181
+ const isWindow = payload?.mode === "window";
182
+ if (!collections) {
183
+ return;
175
184
  }
176
- if (!(await checkPermissions("list", entry.options.permissions.list, user))) {
177
- logInfo(`[sync] User ${userId} denied sync subscription for ${collection}`);
185
+ // C8: reject an oversized array up front (length check before iterating).
186
+ if (collections.length > MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH) {
187
+ logInfo(`[sync] User ${userId} sent an oversized sync:subscribe array`);
178
188
  socket.emit("sync:error", {
179
- collection,
180
- message: `Access to sync collection ${collection} denied`,
189
+ collection: "",
190
+ message: `sync:subscribe accepts at most ${MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH} collections`,
181
191
  });
182
- continue;
183
- }
184
- const streams = await resolveUserStreams({entry, options, socket, user});
185
- if (!streams) {
186
- continue;
192
+ return;
187
193
  }
188
- const rooms = new Set(streams.map(syncRoomForStream));
189
- for (const room of rooms) {
190
- await socket.join(room);
194
+ for (const collection of collections) {
195
+ if (typeof collection !== "string" || collection.length === 0) {
196
+ continue;
197
+ }
198
+ if (subscriptions.has(collection)) {
199
+ // Already subscribed — idempotent.
200
+ continue;
201
+ }
202
+ if (subscriptions.size >= MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
203
+ logInfo(`[sync] User ${userId} hit sync collection subscription limit`);
204
+ socket.emit("sync:error", {
205
+ collection,
206
+ message: `Sync subscription limit of ${MAX_SYNC_COLLECTION_SUBSCRIPTIONS} collections reached`,
207
+ });
208
+ continue;
209
+ }
210
+ const entry = findSyncEntryByCollectionTag(collection);
211
+ if (!entry) {
212
+ socket.emit("sync:error", {
213
+ collection,
214
+ message: `Unknown sync collection: ${collection}`,
215
+ });
216
+ continue;
217
+ }
218
+ const user = await currentUser();
219
+ if (!user) {
220
+ socket.emit("sync:error", {collection, message: "Authentication required"});
221
+ continue;
222
+ }
223
+ if (!(await checkPermissions("list", entry.options.permissions.list, user))) {
224
+ logInfo(`[sync] User ${userId} denied sync subscription for ${collection}`);
225
+ socket.emit("sync:error", {
226
+ collection,
227
+ message: `Access to sync collection ${collection} denied`,
228
+ });
229
+ continue;
230
+ }
231
+ if (isWindow && entry.config.adminBroadcast !== true) {
232
+ socket.emit("sync:error", {
233
+ collection,
234
+ message: `Window subscribe requires adminBroadcast on ${collection}`,
235
+ });
236
+ continue;
237
+ }
238
+ if (
239
+ isWindow &&
240
+ !(await canUseAdminBroadcastWindow({
241
+ accessControl: options.accessControl,
242
+ canOpenAdminWindow: options.canOpenAdminWindow,
243
+ user,
244
+ }))
245
+ ) {
246
+ logInfo(`[sync] User ${userId} denied window subscribe for ${collection}`);
247
+ socket.emit("sync:error", {
248
+ collection,
249
+ message: `Window subscribe requires admin panel access for ${collection}`,
250
+ });
251
+ continue;
252
+ }
253
+ if (isWindow) {
254
+ const adminScope = getAdminBroadcastScope(entry.modelName);
255
+ if (adminScope && !(await canListAdminBroadcastScope({scope: adminScope, user}))) {
256
+ logInfo(`[sync] User ${userId} denied window subscribe list for ${collection}`);
257
+ socket.emit("sync:error", {
258
+ collection,
259
+ message: `Window subscribe requires admin collection access for ${collection}`,
260
+ });
261
+ continue;
262
+ }
263
+ }
264
+ const streams = isWindow
265
+ ? [adminBroadcastStream(collection)]
266
+ : await resolveUserStreams({entry, options, socket, user});
267
+ if (!streams) {
268
+ continue;
269
+ }
270
+ const rooms = new Set(streams.map(syncRoomForStream));
271
+ for (const room of rooms) {
272
+ await socket.join(room);
273
+ }
274
+ subscriptions.set(collection, rooms);
275
+ socket.emit(
276
+ "sync:subscribed",
277
+ isWindow ? {collection, mode: "window", streams} : {collection, streams}
278
+ );
279
+ logInfo(`[sync] User ${userId} subscribed to ${collection}: ${streams.join(", ")}`);
191
280
  }
192
- subscriptions.set(collection, rooms);
193
- socket.emit("sync:subscribed", {collection, streams});
194
- logInfo(`[sync] User ${userId} subscribed to ${collection}: ${streams.join(", ")}`);
195
281
  }
196
- });
282
+ );
197
283
 
198
284
  socket.on("sync:unsubscribe", async (payload: {collections?: unknown}): Promise<void> => {
199
285
  const collections = Array.isArray(payload?.collections) ? payload.collections : null;
@@ -250,7 +336,12 @@ export const installSyncSocketHandlers = (
250
336
  // USER's window, so opening more sockets no longer multiplies the budget.
251
337
  const {outcome, stage} = await runSyncMutation({
252
338
  mutation: payload,
339
+ req: requestFromOrganizationId({
340
+ organizationId: organizationIdFromPayload(payload),
341
+ user,
342
+ }),
253
343
  scopeResolver: options.getUserScopes,
344
+ syncOptions: options,
254
345
  user,
255
346
  });
256
347
  if (stage === "rate_limited") {
@@ -298,7 +389,12 @@ export const installSyncSocketHandlers = (
298
389
  // Task 9.20: validate -> rate limit -> apply, shared with POST /sync/mutate/batch.
299
390
  const {response, stage} = await runSyncBatch({
300
391
  mutations,
392
+ req: requestFromOrganizationId({
393
+ organizationId: organizationIdFromPayload(payload),
394
+ user,
395
+ }),
301
396
  scopeResolver: options.getUserScopes,
397
+ syncOptions: options,
302
398
  user,
303
399
  });
304
400
  if (stage === "rate_limited") {
@@ -25,6 +25,9 @@ export const getScopeField = (scope: SyncScope): string | null => {
25
25
  return null;
26
26
  };
27
27
 
28
+ /** Fan-in stream for admin window subscribers when `SyncConfig.adminBroadcast` is true. */
29
+ export const adminBroadcastStream = (collectionTag: string): string => `${collectionTag}|admin`;
30
+
28
31
  /** Build a stream key from a collection tag and a raw scope value. */
29
32
  export const streamForScopeValue = ({
30
33
  collectionTag,
@@ -65,6 +68,9 @@ export const parseStreamKey = (
65
68
  if (rest === "all") {
66
69
  return {collectionTag, scopeKind: "all", scopeValue: null};
67
70
  }
71
+ if (rest === "admin") {
72
+ return {collectionTag, scopeKind: "admin", scopeValue: null};
73
+ }
68
74
  const colon = rest.indexOf(":");
69
75
  if (colon < 0) {
70
76
  return null;
@@ -232,9 +232,10 @@ describe("registerSync validation", () => {
232
232
  ).toThrow(/workspaceId/);
233
233
  });
234
234
 
235
- it("throws on duplicate registration", () => {
235
+ it("treats duplicate registration of the same model as a no-op", () => {
236
236
  registerStuff();
237
- expect(() => registerStuff()).toThrow(/already registered/);
237
+ registerStuff();
238
+ expect(getSyncRegistry()).toHaveLength(1);
238
239
  });
239
240
 
240
241
  it("registers a compliant model and exposes lookup helpers", () => {
@@ -23,11 +23,12 @@ export const getSyncAppOptions = (app: express.Application): SyncAppOptions | un
23
23
  *
24
24
  * Registration also enqueues the bookkeeping-model index builds (`SyncCounter`,
25
25
  * `SyncMutation`, `SyncScopeMove`, `SyncKey`) for `ensureSyncIndexes()`, which
26
- * `TerrenoApp.start()` awaits before the HTTP server begins listening. Those indexes are
26
+ * `TerrenoApp.start()` binds the HTTP port first, then awaits `ensureSyncIndexes()`. Those indexes are
27
27
  * requirements — the unique `mutationId` index is what makes duplicate mutation deliveries
28
28
  * idempotent, and the unique `stream` index is what keeps the counter upsert race from
29
29
  * minting duplicate seqs — so an index-build failure fails startup loudly. Apps that build
30
30
  * the Express app without `TerrenoApp.start()` should await `ensureSyncIndexes()` themselves.
31
+ * Pass `httpServer` when the process already bound `PORT` (Cloud Run startup probe).
31
32
  */
32
33
  export class SyncApp implements TerrenoPlugin {
33
34
  private readonly options: SyncAppOptions;
@@ -9,6 +9,7 @@ import {
9
9
  type SyncMutationScopeResolver,
10
10
  validateSyncMutationBatch,
11
11
  } from "./mutationHandler";
12
+ import type {SyncAppOptions} from "./routes";
12
13
  import type {SyncMutateBatchResponse, SyncMutateRequest, SyncNack} from "./types";
13
14
 
14
15
  /**
@@ -149,12 +150,14 @@ export const runSyncMutation = async ({
149
150
  mutation,
150
151
  req,
151
152
  scopeResolver,
153
+ syncOptions,
152
154
  user,
153
155
  }: {
154
156
  mutation: SyncMutateRequest;
155
157
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
156
158
  req?: express.Request;
157
159
  scopeResolver?: SyncMutationScopeResolver;
160
+ syncOptions?: SyncAppOptions;
158
161
  user: User;
159
162
  }): Promise<SyncMutationRunResult> => {
160
163
  const userId = String(user.id);
@@ -168,7 +171,7 @@ export const runSyncMutation = async ({
168
171
  };
169
172
  }
170
173
  return {
171
- outcome: await applySyncMutation({mutation, req, scopeResolver, user}),
174
+ outcome: await applySyncMutation({mutation, req, scopeResolver, syncOptions, user}),
172
175
  stage: "applied",
173
176
  };
174
177
  };
@@ -186,11 +189,13 @@ export const runSyncBatch = async ({
186
189
  mutations,
187
190
  req,
188
191
  scopeResolver,
192
+ syncOptions,
189
193
  user,
190
194
  }: {
191
195
  mutations: SyncMutateRequest[];
192
196
  req?: express.Request;
193
197
  scopeResolver?: SyncMutationScopeResolver;
198
+ syncOptions?: SyncAppOptions;
194
199
  user: User;
195
200
  }): Promise<SyncBatchRunResult> => {
196
201
  const validation = validateSyncMutationBatch(mutations);
@@ -214,7 +219,7 @@ export const runSyncBatch = async ({
214
219
  }
215
220
 
216
221
  return {
217
- response: await applySyncMutationBatch({mutations, req, scopeResolver, user}),
222
+ response: await applySyncMutationBatch({mutations, req, scopeResolver, syncOptions, user}),
218
223
  stage: "applied",
219
224
  };
220
225
  };