@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
@@ -119,13 +119,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
119
119
  return (mod && mod.__esModule) ? mod : { "default": mod };
120
120
  };
121
121
  Object.defineProperty(exports, "__esModule", { value: true });
122
- exports.stopChangeStreamWatcher = exports.startChangeStreamWatcher = exports.emitSyncDeltaForChange = exports.emitToDocumentAndQueryRooms = exports.emitToAuthorizedRoom = exports.emitPayloadToAuthorizedRoom = exports.serializeDoc = exports.ensureApiId = exports.resolveRooms = exports.mapOperationType = exports.DEFAULT_IGNORED_COLLECTIONS = exports.SYNC_RESYNC_EVENT = exports.CHANGE_STREAM_RESTART_MAX_DELAY_MS = exports.CHANGE_STREAM_RESTART_BASE_DELAY_MS = void 0;
122
+ exports.stopChangeStreamWatcher = exports.startChangeStreamWatcher = exports.emitSyncDeltaForChange = exports.emitToDocumentAndQueryRooms = exports.emitToAuthorizedRoom = exports.emitPayloadToAuthorizedRoom = exports.serializeDoc = exports.ensureApiId = exports.resolveRooms = exports.mapOperationType = exports.DEFAULT_IGNORED_COLLECTIONS = exports.SYNC_RESYNC_EVENT = void 0;
123
123
  var Sentry = __importStar(require("@sentry/bun"));
124
124
  var luxon_1 = require("luxon");
125
125
  var mongoose_1 = __importDefault(require("mongoose"));
126
126
  var errors_1 = require("../errors");
127
127
  var logger_1 = require("../logger");
128
128
  var realtimeAccess_1 = require("../rbac/realtimeAccess");
129
+ var adminBroadcastScope_1 = require("../sync/adminBroadcastScope");
129
130
  var models_1 = require("../sync/models");
130
131
  var registry_1 = require("../sync/registry");
131
132
  var serialize_1 = require("../sync/serialize");
@@ -155,15 +156,16 @@ var watcherStopped = true;
155
156
  var restartAttempts = 0;
156
157
  var restartTimer = null;
157
158
  /** First restart delay; doubles per consecutive attempt up to the max. */
158
- exports.CHANGE_STREAM_RESTART_BASE_DELAY_MS = 250;
159
+ var CHANGE_STREAM_RESTART_BASE_DELAY_MS = 250;
159
160
  /** Ceiling for the restart backoff — a long outage retries once every 30s, forever. */
160
- exports.CHANGE_STREAM_RESTART_MAX_DELAY_MS = 30000;
161
+ var CHANGE_STREAM_RESTART_MAX_DELAY_MS = 30000;
161
162
  /**
162
163
  * Socket event telling clients their cached cursors may have gaps and they must
163
164
  * re-bootstrap. Emitted when the change stream's oplog history is gone
164
165
  * (`ChangeStreamHistoryLost`), which is the one failure a resume token cannot repair.
165
166
  * Payload: {@link SyncResyncHint}.
166
167
  */
168
+ /** @internal */
167
169
  exports.SYNC_RESYNC_EVENT = "sync:resync-required";
168
170
  /** MongoDB error code / codeName for an unresumable change stream (oplog rolled past). */
169
171
  var CHANGE_STREAM_HISTORY_LOST_CODE = 286;
@@ -201,6 +203,7 @@ var serializePerEntity = function (key, task) {
201
203
  * events are internal (counters/ledger/markers/keys), and processing them would emit
202
204
  * spurious deltas or reprocess scope-move markers. Exported for testing.
203
205
  */
206
+ /** @internal */
204
207
  exports.DEFAULT_IGNORED_COLLECTIONS = [
205
208
  "socketio",
206
209
  "sessions",
@@ -221,6 +224,7 @@ exports.DEFAULT_IGNORED_COLLECTIONS = [
221
224
  *
222
225
  * Exported for testing.
223
226
  */
227
+ /** @internal */
224
228
  var mapOperationType = function (operationType, change, enabledMethods) {
225
229
  var _a, _b;
226
230
  if (enabledMethods === void 0) { enabledMethods = ["create", "update", "delete"]; }
@@ -274,6 +278,7 @@ var getSocketsInRoom = function (io, room) {
274
278
  }
275
279
  return sockets;
276
280
  };
281
+ var emitCollectionTag = function (entry) { var _a; return (_a = entry.collectionTag) !== null && _a !== void 0 ? _a : (entry.routePath ? getCollectionTag(entry.routePath) : undefined); };
277
282
  var canReadDocument = function (entry, user, doc) { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
278
283
  return [2 /*return*/, (0, realtimeAccess_1.canReadDocumentRealtime)(entry, user, doc)];
279
284
  }); }); };
@@ -281,6 +286,7 @@ var canReadDocument = function (entry, user, doc) { return __awaiter(void 0, voi
281
286
  * Determine which Socket.io rooms to emit to based on the room strategy.
282
287
  * Exported for testing.
283
288
  */
289
+ /** @internal */
284
290
  var resolveRooms = function (entry, doc, method) {
285
291
  var roomStrategy = entry.config.roomStrategy;
286
292
  // Use the collection tag (e.g. "todos") for model rooms, matching what the frontend subscribes to
@@ -312,6 +318,7 @@ exports.resolveRooms = resolveRooms;
312
318
  * Ensure serialized documents include `id` to match REST API responses.
313
319
  * Change stream fullDocument payloads are raw BSON objects with `_id` only.
314
320
  */
321
+ /** @internal */
315
322
  var ensureApiId = function (data) {
316
323
  if (data == null || typeof data !== "object" || Array.isArray(data)) {
317
324
  return data;
@@ -339,6 +346,7 @@ exports.ensureApiId = ensureApiId;
339
346
  * would risk leaking unsanitized fields (e.g. `hash`/`salt`) that the handler
340
347
  * was supposed to strip.
341
348
  */
349
+ /** @internal */
342
350
  var serializeDoc = function (entry, doc, method, user) { return __awaiter(void 0, void 0, void 0, function () {
343
351
  var _a, error_1, responseHandler, restMethod, syntheticReq, serialized, masked, error_2, fallback, maskedFallback;
344
352
  var _b;
@@ -396,65 +404,86 @@ exports.serializeDoc = serializeDoc;
396
404
  * emission both delegate here.
397
405
  */
398
406
  var emitPayloadToAuthorizedRoom = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
399
- var sockets, sockets_1, sockets_1_1, socket, user, permissionDocument, canRead, _c, _d, _e, error_3, e_2_1;
400
- var e_2, _f;
407
+ var sockets, sockets_1, sockets_1_1, socket, user, permissionDocument, collectionTag, adminDecision, _c, _d, _e, canRead, _f, _g, _h, error_3, e_2_1;
408
+ var e_2, _j;
401
409
  var io = _b.io, room = _b.room, eventName = _b.eventName, entry = _b.entry, fullDocument = _b.fullDocument, buildPayload = _b.buildPayload, logDebug = _b.logDebug;
402
- return __generator(this, function (_g) {
403
- switch (_g.label) {
410
+ return __generator(this, function (_k) {
411
+ switch (_k.label) {
404
412
  case 0:
405
413
  sockets = getSocketsInRoom(io, room);
406
- _g.label = 1;
414
+ _k.label = 1;
407
415
  case 1:
408
- _g.trys.push([1, 10, 11, 12]);
416
+ _k.trys.push([1, 13, 14, 15]);
409
417
  sockets_1 = __values(sockets), sockets_1_1 = sockets_1.next();
410
- _g.label = 2;
418
+ _k.label = 2;
411
419
  case 2:
412
- if (!!sockets_1_1.done) return [3 /*break*/, 9];
420
+ if (!!sockets_1_1.done) return [3 /*break*/, 12];
413
421
  socket = sockets_1_1.value;
414
422
  return [4 /*yield*/, (0, socketUser_1.awaitSocketFullUser)(socket)];
415
423
  case 3:
416
- user = _g.sent();
417
- _g.label = 4;
424
+ user = _k.sent();
425
+ _k.label = 4;
418
426
  case 4:
419
- _g.trys.push([4, 7, , 8]);
427
+ _k.trys.push([4, 10, , 11]);
420
428
  permissionDocument = fullDocument !== null && fullDocument !== void 0 ? fullDocument : {};
421
- return [4 /*yield*/, canReadDocument(entry, user, permissionDocument)];
429
+ collectionTag = emitCollectionTag(entry);
430
+ if (!(collectionTag && (0, adminBroadcastScope_1.isAdminBroadcastSocketRoom)(room, collectionTag))) return [3 /*break*/, 7];
431
+ return [4 /*yield*/, (0, adminBroadcastScope_1.authorizeAdminBroadcastDocument)({
432
+ doc: fullDocument,
433
+ modelName: entry.modelName,
434
+ user: user,
435
+ })];
422
436
  case 5:
423
- canRead = _g.sent();
424
- if (!canRead) {
425
- logDebug("[realtime] Skipped ".concat(room, " for ").concat(socket.id, ": read permission denied"));
426
- return [3 /*break*/, 8];
437
+ adminDecision = _k.sent();
438
+ if (adminDecision === "deny") {
439
+ logDebug("[realtime] Skipped ".concat(room, " for ").concat(socket.id, ": admin broadcast scope denied"));
440
+ return [3 /*break*/, 11];
427
441
  }
442
+ if (!(adminDecision === "allow")) return [3 /*break*/, 7];
428
443
  _d = (_c = socket).emit;
429
444
  _e = [eventName];
430
445
  return [4 /*yield*/, buildPayload(user)];
431
446
  case 6:
432
- _d.apply(_c, _e.concat([_g.sent()]));
433
- return [3 /*break*/, 8];
434
- case 7:
435
- error_3 = _g.sent();
447
+ _d.apply(_c, _e.concat([_k.sent()]));
448
+ return [3 /*break*/, 11];
449
+ case 7: return [4 /*yield*/, canReadDocument(entry, user, permissionDocument)];
450
+ case 8:
451
+ canRead = _k.sent();
452
+ if (!canRead) {
453
+ logDebug("[realtime] Skipped ".concat(room, " for ").concat(socket.id, ": read permission denied"));
454
+ return [3 /*break*/, 11];
455
+ }
456
+ _g = (_f = socket).emit;
457
+ _h = [eventName];
458
+ return [4 /*yield*/, buildPayload(user)];
459
+ case 9:
460
+ _g.apply(_f, _h.concat([_k.sent()]));
461
+ return [3 /*break*/, 11];
462
+ case 10:
463
+ error_3 = _k.sent();
436
464
  logger_1.logger.error("[realtime] Failed to emit ".concat(eventName, " for ").concat(entry.modelName, " to socket ").concat(socket.id, ": ").concat(error_3));
437
465
  Sentry.captureException(error_3);
438
- return [3 /*break*/, 8];
439
- case 8:
466
+ return [3 /*break*/, 11];
467
+ case 11:
440
468
  sockets_1_1 = sockets_1.next();
441
469
  return [3 /*break*/, 2];
442
- case 9: return [3 /*break*/, 12];
443
- case 10:
444
- e_2_1 = _g.sent();
470
+ case 12: return [3 /*break*/, 15];
471
+ case 13:
472
+ e_2_1 = _k.sent();
445
473
  e_2 = { error: e_2_1 };
446
- return [3 /*break*/, 12];
447
- case 11:
474
+ return [3 /*break*/, 15];
475
+ case 14:
448
476
  try {
449
- if (sockets_1_1 && !sockets_1_1.done && (_f = sockets_1.return)) _f.call(sockets_1);
477
+ if (sockets_1_1 && !sockets_1_1.done && (_j = sockets_1.return)) _j.call(sockets_1);
450
478
  }
451
479
  finally { if (e_2) throw e_2.error; }
452
480
  return [7 /*endfinally*/];
453
- case 12: return [2 /*return*/];
481
+ case 15: return [2 /*return*/];
454
482
  }
455
483
  });
456
484
  }); };
457
485
  exports.emitPayloadToAuthorizedRoom = emitPayloadToAuthorizedRoom;
486
+ /** @internal */
458
487
  var emitToAuthorizedRoom = function (io, room, event, entry, fullDocument, logDebug) { return __awaiter(void 0, void 0, void 0, function () {
459
488
  return __generator(this, function (_a) {
460
489
  return [2 /*return*/, (0, exports.emitPayloadToAuthorizedRoom)({
@@ -499,6 +528,7 @@ exports.emitToAuthorizedRoom = emitToAuthorizedRoom;
499
528
  *
500
529
  * Exported for testing.
501
530
  */
531
+ /** @internal */
502
532
  var emitToDocumentAndQueryRooms = function (io, collection, event, fullDocument, logDebug, entry) { return __awaiter(void 0, void 0, void 0, function () {
503
533
  var docRoom, isOwnerStrategy, querySubscriptions, querySubscriptions_1, querySubscriptions_1_1, _a, queryId, query, queryRoom, docMatches, removeEvent, e_3_1;
504
534
  var e_3, _b;
@@ -749,7 +779,7 @@ var processRealtimeChange = function (_a) { return __awaiter(void 0, [_a], void
749
779
  * Exported for testing.
750
780
  */
751
781
  var emitSyncDeltaForChange = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
752
- var fullDocument, mapped, method, deleted, seq, stream, markers, movedAway, _loop_1, markers_1, markers_1_1, marker, e_5_1, frontierSeq, delta;
782
+ var fullDocument, mapped, method, deleted, seq, stream, markers, movedAway, _loop_1, markers_1, markers_1_1, marker, e_5_1, emitLiveDelta;
753
783
  var e_5, _c;
754
784
  var io = _b.io, entry = _b.entry, change = _b.change, docId = _b.docId, logDebug = _b.logDebug;
755
785
  return __generator(this, function (_d) {
@@ -856,39 +886,55 @@ var emitSyncDeltaForChange = function (_a) { return __awaiter(void 0, [_a], void
856
886
  if (movedAway && method !== "delete") {
857
887
  method = "create";
858
888
  }
859
- return [4 /*yield*/, (0, models_1.computeStableFrontier)({ stream: stream })];
889
+ emitLiveDelta = function (targetStream) { return __awaiter(void 0, void 0, void 0, function () {
890
+ var frontierSeq, liveDelta;
891
+ return __generator(this, function (_a) {
892
+ switch (_a.label) {
893
+ case 0: return [4 /*yield*/, (0, models_1.computeStableFrontier)({ stream: targetStream })];
894
+ case 1:
895
+ frontierSeq = _a.sent();
896
+ liveDelta = __assign({ collection: entry.collectionTag, frontierSeq: frontierSeq, id: docId, method: method, seq: seq, stream: targetStream }, (deleted ? { deleted: true } : {}));
897
+ return [4 /*yield*/, (0, exports.emitPayloadToAuthorizedRoom)({
898
+ // C7: tombstone deltas carry no data (only id/seq/deleted); live deltas serialize.
899
+ buildPayload: deleted
900
+ ? function () { return liveDelta; }
901
+ : function (user) { return __awaiter(void 0, void 0, void 0, function () {
902
+ var syntheticReq, data, _a;
903
+ return __generator(this, function (_b) {
904
+ switch (_b.label) {
905
+ case 0:
906
+ syntheticReq = { params: {}, query: {}, user: user };
907
+ _a = exports.ensureApiId;
908
+ return [4 /*yield*/, (0, serialize_1.serializeSyncPayload)({ doc: fullDocument, entry: entry, method: method, req: syntheticReq })];
909
+ case 1:
910
+ data = _a.apply(void 0, [_b.sent()]);
911
+ return [2 /*return*/, __assign(__assign({}, liveDelta), { data: data })];
912
+ }
913
+ });
914
+ }); },
915
+ entry: entry,
916
+ eventName: "sync:delta",
917
+ fullDocument: fullDocument,
918
+ io: io,
919
+ logDebug: logDebug,
920
+ room: (0, socketHandlers_1.syncRoomForStream)(targetStream),
921
+ })];
922
+ case 2:
923
+ _a.sent();
924
+ logDebug("[sync] Emitted sync:delta ".concat(method, " for ").concat(entry.collectionTag, "/").concat(docId, " seq=").concat(seq, " stream=").concat(targetStream, " frontier=").concat(frontierSeq));
925
+ return [2 /*return*/];
926
+ }
927
+ });
928
+ }); };
929
+ return [4 /*yield*/, emitLiveDelta(stream)];
860
930
  case 10:
861
- frontierSeq = _d.sent();
862
- delta = __assign({ collection: entry.collectionTag, frontierSeq: frontierSeq, id: docId, method: method, seq: seq, stream: stream }, (deleted ? { deleted: true } : {}));
863
- return [4 /*yield*/, (0, exports.emitPayloadToAuthorizedRoom)({
864
- // C7: tombstone deltas carry no data (only id/seq/deleted); live deltas serialize.
865
- buildPayload: deleted
866
- ? function () { return delta; }
867
- : function (user) { return __awaiter(void 0, void 0, void 0, function () {
868
- var syntheticReq, data, _a;
869
- return __generator(this, function (_b) {
870
- switch (_b.label) {
871
- case 0:
872
- syntheticReq = { params: {}, query: {}, user: user };
873
- _a = exports.ensureApiId;
874
- return [4 /*yield*/, (0, serialize_1.serializeSyncPayload)({ doc: fullDocument, entry: entry, method: method, req: syntheticReq })];
875
- case 1:
876
- data = _a.apply(void 0, [_b.sent()]);
877
- return [2 /*return*/, __assign(__assign({}, delta), { data: data })];
878
- }
879
- });
880
- }); },
881
- entry: entry,
882
- eventName: "sync:delta",
883
- fullDocument: fullDocument,
884
- io: io,
885
- logDebug: logDebug,
886
- room: (0, socketHandlers_1.syncRoomForStream)(stream),
887
- })];
931
+ _d.sent();
932
+ if (!(entry.config.adminBroadcast === true)) return [3 /*break*/, 12];
933
+ return [4 /*yield*/, emitLiveDelta((0, streams_1.adminBroadcastStream)(entry.collectionTag))];
888
934
  case 11:
889
935
  _d.sent();
890
- logDebug("[sync] Emitted sync:delta ".concat(method, " for ").concat(entry.collectionTag, "/").concat(docId, " seq=").concat(seq, " stream=").concat(stream, " frontier=").concat(frontierSeq));
891
- return [2 /*return*/];
936
+ _d.label = 12;
937
+ case 12: return [2 /*return*/];
892
938
  }
893
939
  });
894
940
  }); };
@@ -921,7 +967,7 @@ var scheduleChangeStreamRestart = function (_a) {
921
967
  return;
922
968
  }
923
969
  restartAttempts += 1;
924
- var delayMs = Math.min(exports.CHANGE_STREAM_RESTART_BASE_DELAY_MS * Math.pow(2, (restartAttempts - 1)), exports.CHANGE_STREAM_RESTART_MAX_DELAY_MS);
970
+ var delayMs = Math.min(CHANGE_STREAM_RESTART_BASE_DELAY_MS * Math.pow(2, (restartAttempts - 1)), CHANGE_STREAM_RESTART_MAX_DELAY_MS);
925
971
  logger_1.logger.warn("[realtime] Change stream ".concat(reason, "; reopening in ").concat(delayMs, "ms (attempt ").concat(restartAttempts, ")"), { resumable: lastResumeToken !== undefined });
926
972
  restartTimer = setTimeout(function () {
927
973
  restartTimer = null;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * One-line warning for modelRouter `realtime`. Keep in sync with the
3
+ * `@terreno/rtk` helpers and `docs/implementationPlans/remove-legacy-realtime.md`.
4
+ */
5
+ /** @internal */
6
+ export declare const REALTIME_DEPRECATION_MESSAGE = "modelRouter `realtime` is deprecated and will be removed in Terreno 58. Use `sync` with `@terreno/syncdb` instead. See docs/how-to/migrate-rtk-to-syncdb.md. RealtimeApp remains required for sync sockets.";
7
+ /**
8
+ * Emits a one-time deprecation warning per model/routePath per process when a
9
+ * consumer enables the legacy RTK cache-patching `realtime` option.
10
+ */
11
+ export declare const warnRealtimeDeprecated: (modelName: string, routePath?: string) => void;
12
+ /** @internal Test helper — clears one-time realtime deprecation warnings. */
13
+ export declare const resetRealtimeDeprecationWarningsForTests: () => void;
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.resetRealtimeDeprecationWarningsForTests = exports.warnRealtimeDeprecated = exports.REALTIME_DEPRECATION_MESSAGE = void 0;
4
+ var logger_1 = require("../logger");
5
+ /**
6
+ * One-line warning for modelRouter `realtime`. Keep in sync with the
7
+ * `@terreno/rtk` helpers and `docs/implementationPlans/remove-legacy-realtime.md`.
8
+ */
9
+ /** @internal */
10
+ exports.REALTIME_DEPRECATION_MESSAGE = "modelRouter `realtime` is deprecated and will be removed in Terreno 58. Use `sync` with `@terreno/syncdb` instead. See docs/how-to/migrate-rtk-to-syncdb.md. RealtimeApp remains required for sync sockets.";
11
+ var warnedKeys = new Set();
12
+ var warningKey = function (modelName, routePath) {
13
+ return "".concat(modelName, ":").concat(routePath !== null && routePath !== void 0 ? routePath : "");
14
+ };
15
+ /**
16
+ * Emits a one-time deprecation warning per model/routePath per process when a
17
+ * consumer enables the legacy RTK cache-patching `realtime` option.
18
+ */
19
+ var warnRealtimeDeprecated = function (modelName, routePath) {
20
+ var key = warningKey(modelName, routePath);
21
+ if (warnedKeys.has(key)) {
22
+ return;
23
+ }
24
+ warnedKeys.add(key);
25
+ var location = routePath ? "".concat(modelName, " at ").concat(routePath) : modelName;
26
+ logger_1.logger.warn("[realtime] ".concat(exports.REALTIME_DEPRECATION_MESSAGE, " (").concat(location, ")"));
27
+ };
28
+ exports.warnRealtimeDeprecated = warnRealtimeDeprecated;
29
+ /** @internal Test helper — clears one-time realtime deprecation warnings. */
30
+ var resetRealtimeDeprecationWarningsForTests = function () {
31
+ warnedKeys.clear();
32
+ };
33
+ exports.resetRealtimeDeprecationWarningsForTests = resetRealtimeDeprecationWarningsForTests;
@@ -18,6 +18,7 @@ export declare const MAX_QUERY_SUBSCRIPTIONS = 100;
18
18
  *
19
19
  * Exported for testing.
20
20
  */
21
+ /** @internal */
21
22
  export declare const redactCredentials: (url: string) => string;
22
23
  /**
23
24
  * Minimal shape this module requires from a Socket.io socket. Lets tests pass a
@@ -48,7 +49,7 @@ export declare const installRealtimeSocketHandlers: (socket: RealtimeSocketLike,
48
49
  * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
49
50
  *
50
51
  * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
51
- * sets up JWT authentication for socket connections, manages room subscriptions
52
+ * sets up JWT and/or Better Auth authentication for socket connections, manages room subscriptions
52
53
  * (model, document, and query rooms), and starts a change stream watcher that
53
54
  * emits events to connected clients.
54
55
  *
@@ -109,6 +109,7 @@ exports.MAX_QUERY_SUBSCRIPTIONS = 100;
109
109
  *
110
110
  * Exported for testing.
111
111
  */
112
+ /** @internal */
112
113
  var redactCredentials = function (url) {
113
114
  try {
114
115
  var parsed = new URL(url);
@@ -401,7 +402,7 @@ exports.installRealtimeSocketHandlers = installRealtimeSocketHandlers;
401
402
  * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
402
403
  *
403
404
  * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
404
- * sets up JWT authentication for socket connections, manages room subscriptions
405
+ * sets up JWT and/or Better Auth authentication for socket connections, manages room subscriptions
405
406
  * (model, document, and query rooms), and starts a change stream watcher that
406
407
  * emits events to connected clients.
407
408
  *
@@ -469,13 +470,13 @@ var RealtimeApp = /** @class */ (function () {
469
470
  origin: "*",
470
471
  },
471
472
  });
472
- // Authentication middleware: legacy JWT first, optionally Better Auth sessions.
473
+ // Authentication middleware: legacy JWT first when configured, optionally Better Auth sessions.
473
474
  var tokenSecret = (_d = this.config.tokenSecret) !== null && _d !== void 0 ? _d : process.env.TOKEN_SECRET;
474
- if (!tokenSecret) {
475
+ if (!tokenSecret && !this.config.betterAuth) {
475
476
  throw new errors_1.APIError({
476
477
  status: 500,
477
- title: "[realtime] TOKEN_SECRET is required for socket authentication. " +
478
- "Set process.env.TOKEN_SECRET or pass tokenSecret in RealtimeAppOptions.",
478
+ title: "[realtime] Socket authentication requires TOKEN_SECRET or Better Auth. " +
479
+ "Set process.env.TOKEN_SECRET, pass tokenSecret, or configure betterAuth.",
479
480
  });
480
481
  }
481
482
  // D1: pass the issuer through for parity with the HTTP JWT path
@@ -485,12 +486,11 @@ var RealtimeApp = /** @class */ (function () {
485
486
  // process.env.TOKEN_ISSUER — or to an explicitly configured tokenIssuer — is
486
487
  // honored on every handshake, matching the HTTP path's per-request env read.
487
488
  var resolveTokenIssuer = function () { var _a; return (_a = _this.config.tokenIssuer) !== null && _a !== void 0 ? _a : process.env.TOKEN_ISSUER; };
488
- this.io.use((0, socketAuth_1.createSocketAuthMiddleware)({
489
- betterAuth: this.config.betterAuth,
490
- issuer: resolveTokenIssuer,
491
- tokenSecret: tokenSecret,
492
- }));
493
- logInfo("[realtime] Socket auth middleware added (JWT".concat(this.config.betterAuth ? " + Better Auth" : "", ")"));
489
+ this.io.use((0, socketAuth_1.createSocketAuthMiddleware)(__assign({ betterAuth: this.config.betterAuth, issuer: resolveTokenIssuer }, (tokenSecret ? { tokenSecret: tokenSecret } : {}))));
490
+ var authKinds = [tokenSecret ? "JWT" : null, this.config.betterAuth ? "Better Auth" : null]
491
+ .filter(Boolean)
492
+ .join(" + ");
493
+ logInfo("[realtime] Socket auth middleware added (".concat(authKinds, ")"));
494
494
  // Task 9.21: tenant/custom sync scopes can only be resolved from the full user
495
495
  // document, so warn loudly here (once, at startup) rather than silently serving
496
496
  // empty tenant streams for the life of the process.
@@ -1,46 +1,15 @@
1
1
  import type { ModelRouterOptions } from "../api";
2
2
  import type { RealtimeConfig } from "./types";
3
- /**
4
- * A registered model with real-time sync configuration.
5
- */
6
3
  export interface RealtimeRegistryEntry {
7
- /** Mongoose model name (e.g. "Todo") */
8
4
  modelName: string;
9
- /** Route path (e.g. "/todos") */
10
5
  routePath: string;
11
- /** Collection name in MongoDB (e.g. "todos") */
12
6
  collectionName: string;
13
- /** Real-time configuration from modelRouter options */
14
7
  config: RealtimeConfig;
15
- /**
16
- * Full modelRouter options (for responseHandler, permissions, etc.), erased to
17
- * `unknown` since the registry holds entries for every model.
18
- */
19
8
  options: ModelRouterOptions<unknown>;
20
9
  }
21
- /**
22
- * Register a model for real-time sync. Called automatically by modelRouter
23
- * when the `realtime` option is provided.
24
- */
25
10
  export declare const registerRealtime: (entry: RealtimeRegistryEntry) => void;
26
- /**
27
- * Replace options on an existing registry entry (e.g. after TerrenoApp injects accessControl).
28
- * Matches by routePath; no-op if the route was never registered.
29
- */
30
11
  export declare const updateRealtimeRegistryOptions: (routePath: string, options: ModelRouterOptions<unknown>) => void;
31
- /**
32
- * Get all registered real-time models.
33
- */
34
12
  export declare const getRealtimeRegistry: () => RealtimeRegistryEntry[];
35
- /**
36
- * Find a registry entry by MongoDB collection name.
37
- */
38
13
  export declare const findRegistryEntryByCollection: (collectionName: string) => RealtimeRegistryEntry | undefined;
39
- /**
40
- * Find a registry entry by route path / collection tag (e.g. "todos").
41
- */
42
14
  export declare const findRegistryEntryByRoutePath: (collection: string) => RealtimeRegistryEntry | undefined;
43
- /**
44
- * Clear the registry (for testing).
45
- */
46
15
  export declare const clearRealtimeRegistry: () => void;
@@ -1,50 +1,63 @@
1
1
  "use strict";
2
+ var __assign = (this && this.__assign) || function () {
3
+ __assign = Object.assign || function(t) {
4
+ for (var s, i = 1, n = arguments.length; i < n; i++) {
5
+ s = arguments[i];
6
+ for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
7
+ t[p] = s[p];
8
+ }
9
+ return t;
10
+ };
11
+ return __assign.apply(this, arguments);
12
+ };
2
13
  Object.defineProperty(exports, "__esModule", { value: true });
3
14
  exports.clearRealtimeRegistry = exports.findRegistryEntryByRoutePath = exports.findRegistryEntryByCollection = exports.getRealtimeRegistry = exports.updateRealtimeRegistryOptions = exports.registerRealtime = void 0;
4
- var realtimeRegistry = [];
5
- /**
6
- * Register a model for real-time sync. Called automatically by modelRouter
7
- * when the `realtime` option is provided.
8
- */
15
+ var collectionRegistry_1 = require("../collectionRegistry");
16
+ var toRealtimeEntry = function (record) { return ({
17
+ collectionName: record.model.collection.collectionName,
18
+ config: record.options.realtime,
19
+ modelName: record.model.modelName,
20
+ options: record.options,
21
+ routePath: record.routePath,
22
+ }); };
23
+ var realtimeModelForEntry = function (entry) {
24
+ var _a;
25
+ var registered = (_a = (0, collectionRegistry_1.listCollections)().find(function (record) { return record.routePath === entry.routePath; })) === null || _a === void 0 ? void 0 : _a.model;
26
+ if (registered) {
27
+ return registered;
28
+ }
29
+ return {
30
+ collection: { collectionName: entry.collectionName },
31
+ modelName: entry.modelName,
32
+ };
33
+ };
9
34
  var registerRealtime = function (entry) {
10
- realtimeRegistry.push(entry);
35
+ (0, collectionRegistry_1.registerCollection)({
36
+ model: realtimeModelForEntry(entry),
37
+ options: __assign(__assign({}, entry.options), { realtime: entry.config }),
38
+ routePath: entry.routePath,
39
+ });
11
40
  };
12
41
  exports.registerRealtime = registerRealtime;
13
- /**
14
- * Replace options on an existing registry entry (e.g. after TerrenoApp injects accessControl).
15
- * Matches by routePath; no-op if the route was never registered.
16
- */
17
42
  var updateRealtimeRegistryOptions = function (routePath, options) {
18
- var existing = realtimeRegistry.find(function (entry) { return entry.routePath === routePath; });
19
- if (!existing) {
20
- return;
21
- }
22
- existing.options = options;
43
+ (0, collectionRegistry_1.replaceCollectionOptions)(routePath, options);
23
44
  };
24
45
  exports.updateRealtimeRegistryOptions = updateRealtimeRegistryOptions;
25
- /**
26
- * Get all registered real-time models.
27
- */
28
- var getRealtimeRegistry = function () { return realtimeRegistry; };
46
+ var getRealtimeRegistry = function () {
47
+ return (0, collectionRegistry_1.listCollections)()
48
+ .filter(function (record) { return record.surfaces.realtime; })
49
+ .map(toRealtimeEntry);
50
+ };
29
51
  exports.getRealtimeRegistry = getRealtimeRegistry;
30
- /**
31
- * Find a registry entry by MongoDB collection name.
32
- */
33
52
  var findRegistryEntryByCollection = function (collectionName) {
34
- return realtimeRegistry.find(function (entry) { return entry.collectionName === collectionName; });
53
+ return (0, exports.getRealtimeRegistry)().find(function (entry) { return entry.collectionName === collectionName; });
35
54
  };
36
55
  exports.findRegistryEntryByCollection = findRegistryEntryByCollection;
37
- /**
38
- * Find a registry entry by route path / collection tag (e.g. "todos").
39
- */
40
56
  var findRegistryEntryByRoutePath = function (collection) {
41
- return realtimeRegistry.find(function (entry) { return entry.routePath === "/".concat(collection) || entry.routePath === collection; });
57
+ return (0, exports.getRealtimeRegistry)().find(function (entry) { return entry.routePath === "/".concat(collection) || entry.routePath === collection; });
42
58
  };
43
59
  exports.findRegistryEntryByRoutePath = findRegistryEntryByRoutePath;
44
- /**
45
- * Clear the registry (for testing).
46
- */
47
60
  var clearRealtimeRegistry = function () {
48
- realtimeRegistry.length = 0;
61
+ (0, collectionRegistry_1.clearCollectionRegistry)();
49
62
  };
50
63
  exports.clearRealtimeRegistry = clearRealtimeRegistry;
@@ -11,9 +11,9 @@ import type { SocketWithDecodedToken } from "./socketUser";
11
11
  * fails, the connection is rejected with the last validator's error.
12
12
  *
13
13
  * Validators:
14
- * 1. Legacy JWT (default, always first) — the existing `@thream/socketio-jwt` middleware,
15
- * wrapped unchanged so accepted payloads, secret handling, and error shapes are
16
- * byte-for-byte identical to the previous hardcoded setup.
14
+ * 1. Legacy JWT (when a token secret is configured, always first) — the existing
15
+ * `@thream/socketio-jwt` middleware, wrapped unchanged so accepted payloads, secret
16
+ * handling, and error shapes are byte-for-byte identical to the previous hardcoded setup.
17
17
  * 2. Better Auth session (optional) — enabled via `RealtimeAppOptions.betterAuth`. The
18
18
  * handshake token is validated as a Better Auth session via `auth.api.getSession`
19
19
  * (presented as an `Authorization: Bearer` credential, resolved by Better Auth's
@@ -82,8 +82,8 @@ export declare const createBetterAuthValidator: (options: BetterAuthSocketOption
82
82
  * the first success wins; when all fail the connection is rejected with the last error.
83
83
  */
84
84
  export declare const createSocketAuthMiddleware: ({ tokenSecret, issuer, betterAuth, extraValidators, }: {
85
- /** Secret for the legacy JWT validator (same handling as before the refactor). */
86
- tokenSecret: string;
85
+ /** Secret enabling the legacy JWT validator (same handling as before the refactor). */
86
+ tokenSecret?: string;
87
87
  /**
88
88
  * JWT issuer to require (D1 parity with the HTTP path's `jwt.verify(token, secret,
89
89
  * {issuer})`). Omitted means no issuer check, matching pre-D1 behavior. A thunk is
@@ -74,6 +74,7 @@ var __values = (this && this.__values) || function(o) {
74
74
  Object.defineProperty(exports, "__esModule", { value: true });
75
75
  exports.createSocketAuthMiddleware = exports.createBetterAuthValidator = exports.createLegacyJwtValidator = void 0;
76
76
  var socketio_jwt_1 = require("@thream/socketio-jwt");
77
+ var errors_1 = require("../errors");
77
78
  var logger_1 = require("../logger");
78
79
  var plugins_1 = require("../plugins");
79
80
  /**
@@ -211,11 +212,20 @@ exports.createBetterAuthValidator = createBetterAuthValidator;
211
212
  */
212
213
  var createSocketAuthMiddleware = function (_a) {
213
214
  var tokenSecret = _a.tokenSecret, issuer = _a.issuer, betterAuth = _a.betterAuth, _b = _a.extraValidators, extraValidators = _b === void 0 ? [] : _b;
214
- var validators = [(0, exports.createLegacyJwtValidator)(tokenSecret, issuer)];
215
+ var validators = [];
216
+ if (tokenSecret) {
217
+ validators.push((0, exports.createLegacyJwtValidator)(tokenSecret, issuer));
218
+ }
215
219
  if (betterAuth) {
216
220
  validators.push((0, exports.createBetterAuthValidator)(betterAuth));
217
221
  }
218
222
  validators.push.apply(validators, __spreadArray([], __read(extraValidators), false));
223
+ if (validators.length === 0) {
224
+ throw new errors_1.APIError({
225
+ status: 500,
226
+ title: "[realtime] At least one socket authentication validator is required.",
227
+ });
228
+ }
219
229
  return function (socket, next) {
220
230
  void (function () { return __awaiter(void 0, void 0, void 0, function () {
221
231
  var lastError, validators_1, validators_1_1, validator, error_1, e_1_1;
@@ -26,7 +26,11 @@ export interface DecodedRealtimeToken {
26
26
  * configured, or while the handshake load is still in flight.
27
27
  */
28
28
  export interface SocketDataBag {
29
- fullUser?: any;
29
+ /**
30
+ * The consumer's own Mongoose user document, so its app-specific fields are opaque
31
+ * here — read it through {@link getSocketUser} rather than narrowing it inline.
32
+ */
33
+ fullUser?: unknown;
30
34
  /**
31
35
  * The in-flight handshake load of {@link SocketDataBag.fullUser}, published so handlers
32
36
  * that must not authorize against the synthetic token user can await it