@terreno/api 57.2.0 → 57.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (472) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +23 -10
  2. package/README.md +23 -7
  3. package/dist/actions.js +19 -7
  4. package/dist/adminTypes.d.ts +7 -0
  5. package/dist/adminTypes.js +6 -1
  6. package/dist/api.d.ts +14 -0
  7. package/dist/api.js +111 -60
  8. package/dist/audit/auditApp.d.ts +30 -0
  9. package/dist/audit/auditApp.js +155 -0
  10. package/dist/audit/auditEventModel.d.ts +29 -0
  11. package/dist/audit/auditEventModel.js +102 -0
  12. package/dist/audit/cloudTasksEnqueue.d.ts +32 -0
  13. package/dist/audit/cloudTasksEnqueue.js +162 -0
  14. package/dist/audit/diff.d.ts +10 -0
  15. package/dist/audit/diff.js +230 -0
  16. package/dist/audit/processQueue.d.ts +6 -0
  17. package/dist/audit/processQueue.js +101 -0
  18. package/dist/audit/rbacSink.d.ts +2 -0
  19. package/dist/audit/rbacSink.js +82 -0
  20. package/dist/audit/record.d.ts +56 -0
  21. package/dist/audit/record.js +373 -0
  22. package/dist/auth.d.ts +23 -10
  23. package/dist/auth.js +97 -32
  24. package/dist/authRecovery.d.ts +5 -0
  25. package/dist/authRecovery.js +350 -0
  26. package/dist/authTokens.d.ts +8 -0
  27. package/dist/authTokens.js +162 -0
  28. package/dist/betterAuth.d.ts +39 -0
  29. package/dist/betterAuthApp.d.ts +4 -0
  30. package/dist/betterAuthApp.js +26 -8
  31. package/dist/betterAuthSetup.d.ts +44 -2
  32. package/dist/betterAuthSetup.js +288 -18
  33. package/dist/collectionRegistry.d.ts +40 -0
  34. package/dist/collectionRegistry.js +97 -0
  35. package/dist/configurationApp.d.ts +11 -2
  36. package/dist/configurationApp.js +2 -4
  37. package/dist/docLoader.js +35 -6
  38. package/dist/expressServer.d.ts +26 -3
  39. package/dist/expressServer.js +79 -11
  40. package/dist/index.d.ts +42 -1
  41. package/dist/index.js +84 -2
  42. package/dist/mcp/auth.d.ts +1 -0
  43. package/dist/mcp/auth.js +47 -25
  44. package/dist/mcp/handlers.d.ts +1 -1
  45. package/dist/mcp/handlers.js +67 -233
  46. package/dist/mcp/query.d.ts +2 -15
  47. package/dist/mcp/query.js +8 -8
  48. package/dist/mcp/registry.d.ts +1 -5
  49. package/dist/mcp/registry.js +31 -20
  50. package/dist/mcp/schemaGenerator.d.ts +2 -7
  51. package/dist/mcp/schemaGenerator.js +41 -116
  52. package/dist/mcp/server.d.ts +1 -0
  53. package/dist/mcp/server.js +1 -0
  54. package/dist/mcp/serviceTokens.d.ts +16 -0
  55. package/dist/mcp/serviceTokens.js +345 -0
  56. package/dist/mcp/types.d.ts +2 -2
  57. package/dist/migrations/fixtures/all-down/20260910120000-one.d.ts +4 -0
  58. package/dist/migrations/fixtures/all-down/20260910120000-one.js +49 -0
  59. package/dist/migrations/fixtures/all-down/20260910120001-two.d.ts +4 -0
  60. package/dist/migrations/fixtures/all-down/20260910120001-two.js +49 -0
  61. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.d.ts +3 -0
  62. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.js +45 -0
  63. package/dist/migrations/fixtures/bad-name/not-a-migration.d.ts +3 -0
  64. package/dist/migrations/fixtures/bad-name/not-a-migration.js +45 -0
  65. package/dist/migrations/fixtures/missing-up/20260910120000-noup.d.ts +2 -0
  66. package/dist/migrations/fixtures/missing-up/20260910120000-noup.js +5 -0
  67. package/dist/migrations/fixtures/valid/20260910120000-alpha.d.ts +3 -0
  68. package/dist/migrations/fixtures/valid/20260910120000-alpha.js +45 -0
  69. package/dist/migrations/fixtures/valid/20260910120001-beta.d.ts +4 -0
  70. package/dist/migrations/fixtures/valid/20260910120001-beta.js +49 -0
  71. package/dist/migrations/generate.d.ts +17 -0
  72. package/dist/migrations/generate.js +277 -0
  73. package/dist/migrations/load.d.ts +20 -0
  74. package/dist/migrations/load.js +236 -0
  75. package/dist/migrations/lock.d.ts +13 -0
  76. package/dist/migrations/lock.js +145 -0
  77. package/dist/migrations/runner.d.ts +42 -0
  78. package/dist/migrations/runner.js +503 -0
  79. package/dist/migrations/schemaCatalog.d.ts +44 -0
  80. package/dist/migrations/schemaCatalog.js +326 -0
  81. package/dist/migrations/types.d.ts +87 -0
  82. package/dist/migrations/types.js +7 -0
  83. package/dist/models/mcpServiceToken.d.ts +3 -0
  84. package/dist/models/mcpServiceToken.js +208 -0
  85. package/dist/models/notification.d.ts +2 -0
  86. package/dist/models/notification.js +62 -0
  87. package/dist/models/notificationPreference.d.ts +2 -0
  88. package/dist/models/notificationPreference.js +49 -0
  89. package/dist/notifications/notificationService.d.ts +40 -0
  90. package/dist/notifications/notificationService.js +323 -0
  91. package/dist/notifications/notificationsApp.d.ts +18 -0
  92. package/dist/notifications/notificationsApp.js +250 -0
  93. package/dist/notifications/notificationsBeforeSend.d.ts +14 -0
  94. package/dist/notifications/notificationsBeforeSend.js +77 -0
  95. package/dist/openApi.d.ts +1 -7
  96. package/dist/openApi.js +7 -6
  97. package/dist/openApiBuilder.d.ts +19 -7
  98. package/dist/openApiBuilder.js +61 -8
  99. package/dist/openApiCompat.js +1 -1
  100. package/dist/openApiValidator.d.ts +13 -1
  101. package/dist/openApiValidator.js +200 -38
  102. package/dist/orgs/orgContext.d.ts +23 -0
  103. package/dist/orgs/orgContext.js +198 -0
  104. package/dist/orgs/orgPermissions.d.ts +4 -0
  105. package/dist/orgs/orgPermissions.js +77 -0
  106. package/dist/orgs/orgPlugin.d.ts +13 -0
  107. package/dist/orgs/orgPlugin.js +84 -0
  108. package/dist/orgs/organizationModel.d.ts +13 -0
  109. package/dist/orgs/organizationModel.js +301 -0
  110. package/dist/orgs/organizationSettings.d.ts +19 -0
  111. package/dist/orgs/organizationSettings.js +120 -0
  112. package/dist/orgs/orgsApp.d.ts +28 -0
  113. package/dist/orgs/orgsApp.js +678 -0
  114. package/dist/permissions.d.ts +7 -13
  115. package/dist/permissions.js +8 -31
  116. package/dist/plugins.d.ts +14 -1
  117. package/dist/plugins.js +17 -6
  118. package/dist/populate.d.ts +2 -2
  119. package/dist/populate.js +47 -42
  120. package/dist/rateLimit/applyTrustProxy.d.ts +3 -0
  121. package/dist/rateLimit/applyTrustProxy.js +17 -0
  122. package/dist/rateLimit/createStore.d.ts +2 -0
  123. package/dist/rateLimit/createStore.js +28 -0
  124. package/dist/rateLimit/memoryStore.d.ts +2 -0
  125. package/dist/rateLimit/memoryStore.js +108 -0
  126. package/dist/rateLimit/middleware.d.ts +3 -0
  127. package/dist/rateLimit/middleware.js +109 -0
  128. package/dist/rateLimit/mongoStore.d.ts +4 -0
  129. package/dist/rateLimit/mongoStore.js +123 -0
  130. package/dist/rateLimit/policies.d.ts +10 -0
  131. package/dist/rateLimit/policies.js +149 -0
  132. package/dist/rateLimit/redisStore.d.ts +4 -0
  133. package/dist/rateLimit/redisStore.js +156 -0
  134. package/dist/rateLimit/types.d.ts +54 -0
  135. package/dist/rateLimit/types.js +9 -0
  136. package/dist/rbac/access.js +35 -14
  137. package/dist/rbac/assertAllowed.d.ts +9 -0
  138. package/dist/rbac/assertAllowed.js +182 -0
  139. package/dist/rbac/membershipOrgAdminSource.d.ts +6 -0
  140. package/dist/rbac/membershipOrgAdminSource.js +122 -0
  141. package/dist/rbac/modelRouterAccess.d.ts +4 -0
  142. package/dist/rbac/modelRouterAccess.js +11 -4
  143. package/dist/rbac/permissionUtils.js +3 -2
  144. package/dist/rbac/resolve.js +65 -35
  145. package/dist/rbac/roleModel.d.ts +2 -5
  146. package/dist/rbac/roleModel.js +18 -4
  147. package/dist/rbac/routes.js +15 -6
  148. package/dist/rbac/statements.d.ts +10 -1
  149. package/dist/rbac/statements.js +19 -2
  150. package/dist/rbac/types.d.ts +5 -0
  151. package/dist/realtime/changeStreamWatcher.d.ts +10 -4
  152. package/dist/realtime/changeStreamWatcher.js +110 -64
  153. package/dist/realtime/deprecation.d.ts +13 -0
  154. package/dist/realtime/deprecation.js +33 -0
  155. package/dist/realtime/realtimeApp.d.ts +2 -1
  156. package/dist/realtime/realtimeApp.js +11 -11
  157. package/dist/realtime/registry.d.ts +0 -31
  158. package/dist/realtime/registry.js +44 -31
  159. package/dist/realtime/socketAuth.d.ts +5 -5
  160. package/dist/realtime/socketAuth.js +11 -1
  161. package/dist/realtime/socketUser.d.ts +5 -1
  162. package/dist/realtime/types.d.ts +14 -4
  163. package/dist/schemaMetadata.d.ts +56 -0
  164. package/dist/schemaMetadata.js +524 -0
  165. package/dist/seedRunner.d.ts +88 -0
  166. package/dist/seedRunner.js +627 -0
  167. package/dist/sync/adminBroadcastScope.d.ts +40 -0
  168. package/dist/sync/adminBroadcastScope.js +194 -0
  169. package/dist/sync/adminWindowAccess.d.ts +13 -0
  170. package/dist/sync/adminWindowAccess.js +96 -0
  171. package/dist/sync/adminWindowMutation.d.ts +88 -0
  172. package/dist/sync/adminWindowMutation.js +247 -0
  173. package/dist/sync/executors.d.ts +19 -3
  174. package/dist/sync/executors.js +194 -165
  175. package/dist/sync/loadHarness.js +28 -19
  176. package/dist/sync/models.js +26 -24
  177. package/dist/sync/mutationHandler.d.ts +14 -2
  178. package/dist/sync/mutationHandler.js +201 -76
  179. package/dist/sync/registrationSideEffects.d.ts +35 -0
  180. package/dist/sync/registrationSideEffects.js +151 -0
  181. package/dist/sync/registry.d.ts +2 -52
  182. package/dist/sync/registry.js +42 -187
  183. package/dist/sync/routes.d.ts +13 -0
  184. package/dist/sync/routes.js +116 -58
  185. package/dist/sync/scripts/compactTombstones.js +0 -2
  186. package/dist/sync/socketHandlers.d.ts +8 -2
  187. package/dist/sync/socketHandlers.js +144 -50
  188. package/dist/sync/streams.d.ts +2 -0
  189. package/dist/sync/streams.js +7 -1
  190. package/dist/sync/syncApp.d.ts +4 -3
  191. package/dist/sync/syncApp.js +5 -4
  192. package/dist/sync/syncBatch.d.ts +5 -2
  193. package/dist/sync/syncBatch.js +7 -6
  194. package/dist/sync/syncSeqPlugin.d.ts +1 -1
  195. package/dist/sync/syncSeqPlugin.js +20 -16
  196. package/dist/sync/types.d.ts +18 -0
  197. package/dist/terrenoApp.d.ts +48 -5
  198. package/dist/terrenoApp.js +157 -72
  199. package/dist/tests/createTestData.d.ts +1 -3
  200. package/dist/tests/createTestData.js +3 -5
  201. package/dist/tests/models.d.ts +3 -0
  202. package/dist/tests/models.js +15 -2
  203. package/dist/tests/testHelper.d.ts +0 -5
  204. package/dist/tests/testHelper.js +2 -9
  205. package/dist/types/authToken.d.ts +33 -0
  206. package/dist/types/authToken.js +2 -0
  207. package/dist/types/mcpServiceToken.d.ts +41 -0
  208. package/dist/types/mcpServiceToken.js +2 -0
  209. package/dist/types/membership.d.ts +23 -0
  210. package/dist/types/membership.js +2 -0
  211. package/dist/types/notification.d.ts +28 -0
  212. package/dist/types/notification.js +2 -0
  213. package/dist/types/notificationPreference.d.ts +20 -0
  214. package/dist/types/notificationPreference.js +2 -0
  215. package/dist/types/organization.d.ts +36 -0
  216. package/dist/types/organization.js +2 -0
  217. package/dist/webhooks/headerValue.d.ts +2 -0
  218. package/dist/webhooks/headerValue.js +14 -0
  219. package/dist/webhooks/idempotency/memoryStore.d.ts +10 -0
  220. package/dist/webhooks/idempotency/memoryStore.js +65 -0
  221. package/dist/webhooks/idempotency/mongoStore.d.ts +4 -0
  222. package/dist/webhooks/idempotency/mongoStore.js +150 -0
  223. package/dist/webhooks/idempotency/webhookReceipt.d.ts +17 -0
  224. package/dist/webhooks/idempotency/webhookReceipt.js +39 -0
  225. package/dist/webhooks/rawBody.d.ts +15 -0
  226. package/dist/webhooks/rawBody.js +23 -0
  227. package/dist/webhooks/timingSafeEqual.d.ts +4 -0
  228. package/dist/webhooks/timingSafeEqual.js +17 -0
  229. package/dist/webhooks/verifiers/hmac.d.ts +15 -0
  230. package/dist/webhooks/verifiers/hmac.js +49 -0
  231. package/dist/webhooks/verifiers/sendgrid.d.ts +10 -0
  232. package/dist/webhooks/verifiers/sendgrid.js +56 -0
  233. package/dist/webhooks/verifiers/stripe.d.ts +9 -0
  234. package/dist/webhooks/verifiers/stripe.js +99 -0
  235. package/dist/webhooks/verifiers/twilio.d.ts +9 -0
  236. package/dist/webhooks/verifiers/twilio.js +112 -0
  237. package/dist/webhooks/webhooksApp.d.ts +33 -0
  238. package/dist/webhooks/webhooksApp.js +195 -0
  239. package/package.json +32 -27
  240. package/src/__snapshots__/openApi.test.ts.snap +444 -36
  241. package/src/__snapshots__/openApiBuilder.test.ts.snap +24 -24
  242. package/src/__snapshots__/schemaMetadata.test.ts.snap +196 -0
  243. package/src/actions.ts +20 -13
  244. package/src/adminModelRouter.test.ts +133 -0
  245. package/src/adminTypes.ts +8 -0
  246. package/src/api.arrayOperations.test.ts +43 -31
  247. package/src/api.hooks.test.ts +38 -29
  248. package/src/api.query.test.ts +31 -31
  249. package/src/api.test.ts +133 -97
  250. package/src/api.ts +84 -27
  251. package/src/audit/auditApp.test.ts +243 -0
  252. package/src/audit/auditApp.ts +139 -0
  253. package/src/audit/auditEventModel.ts +156 -0
  254. package/src/audit/auditRouter.test.ts +456 -0
  255. package/src/audit/cloudTasksEnqueue.test.ts +124 -0
  256. package/src/audit/cloudTasksEnqueue.ts +104 -0
  257. package/src/audit/diff.ts +163 -0
  258. package/src/audit/processQueue.ts +69 -0
  259. package/src/audit/rbacSink.test.ts +86 -0
  260. package/src/audit/rbacSink.ts +42 -0
  261. package/src/audit/record.test.ts +402 -0
  262. package/src/audit/record.ts +328 -0
  263. package/src/auth.test.ts +108 -52
  264. package/src/auth.ts +98 -29
  265. package/src/authRecovery.test.ts +281 -0
  266. package/src/authRecovery.ts +279 -0
  267. package/src/authTokens.test.ts +94 -0
  268. package/src/authTokens.ts +118 -0
  269. package/src/authVerification.test.ts +293 -0
  270. package/src/betterAuth.ts +31 -0
  271. package/src/betterAuthApp.test.ts +1 -0
  272. package/src/betterAuthApp.ts +27 -9
  273. package/src/betterAuthSetup.test.ts +595 -38
  274. package/src/betterAuthSetup.ts +261 -5
  275. package/src/collectionRegistry.test.ts +164 -0
  276. package/src/collectionRegistry.ts +135 -0
  277. package/src/configurationApp.ts +13 -7
  278. package/src/docLoader.test.ts +45 -1
  279. package/src/docLoader.ts +37 -6
  280. package/src/express.d.ts +3 -0
  281. package/src/expressServer.test.ts +180 -68
  282. package/src/expressServer.ts +75 -19
  283. package/src/githubAuth.test.ts +60 -55
  284. package/src/index.ts +127 -0
  285. package/src/mcp/auth.test.ts +47 -0
  286. package/src/mcp/auth.ts +32 -11
  287. package/src/mcp/handlers.test.ts +275 -0
  288. package/src/mcp/handlers.ts +45 -172
  289. package/src/mcp/integration.test.ts +59 -9
  290. package/src/mcp/query.ts +5 -7
  291. package/src/mcp/registry.ts +29 -20
  292. package/src/mcp/schemaGenerator.test.ts +8 -0
  293. package/src/mcp/schemaGenerator.ts +49 -131
  294. package/src/mcp/server.ts +2 -0
  295. package/src/mcp/serviceTokens.test.ts +330 -0
  296. package/src/mcp/serviceTokens.ts +307 -0
  297. package/src/mcp/toolGenerator.test.ts +82 -1
  298. package/src/mcp/types.ts +2 -6
  299. package/src/migrations/cli.test.ts +376 -0
  300. package/src/migrations/cli.ts +283 -0
  301. package/src/migrations/fixtures/all-down/20260910120000-one.ts +6 -0
  302. package/src/migrations/fixtures/all-down/20260910120001-two.ts +6 -0
  303. package/src/migrations/fixtures/bad-id/20260910120000-mismatch.ts +4 -0
  304. package/src/migrations/fixtures/bad-name/not-a-migration.ts +4 -0
  305. package/src/migrations/fixtures/missing-up/20260910120000-noup.ts +2 -0
  306. package/src/migrations/fixtures/valid/20260910120000-alpha.ts +4 -0
  307. package/src/migrations/fixtures/valid/20260910120001-beta.ts +6 -0
  308. package/src/migrations/generate.test.ts +333 -0
  309. package/src/migrations/generate.ts +216 -0
  310. package/src/migrations/load.test.ts +103 -0
  311. package/src/migrations/load.ts +124 -0
  312. package/src/migrations/lock.test.ts +133 -0
  313. package/src/migrations/lock.ts +118 -0
  314. package/src/migrations/runner.test.ts +504 -0
  315. package/src/migrations/runner.ts +358 -0
  316. package/src/migrations/schemaCatalog.test.ts +159 -0
  317. package/src/migrations/schemaCatalog.ts +262 -0
  318. package/src/migrations/types.ts +94 -0
  319. package/src/models/mcpServiceToken.test.ts +129 -0
  320. package/src/models/mcpServiceToken.ts +158 -0
  321. package/src/models/notification.ts +68 -0
  322. package/src/models/notificationPreference.ts +62 -0
  323. package/src/notifications/notificationService.ts +254 -0
  324. package/src/notifications/notificationsApp.test.ts +505 -0
  325. package/src/notifications/notificationsApp.ts +200 -0
  326. package/src/notifications/notificationsBeforeSend.ts +51 -0
  327. package/src/openApi.test.ts +80 -65
  328. package/src/openApi.ts +2 -1
  329. package/src/openApiBuilder.test.ts +95 -7
  330. package/src/openApiBuilder.ts +60 -12
  331. package/src/openApiCompat.ts +1 -1
  332. package/src/openApiValidator.test.ts +270 -56
  333. package/src/openApiValidator.ts +219 -36
  334. package/src/orgs/orgAccessOptIn.test.ts +87 -0
  335. package/src/orgs/orgContext.test.ts +259 -0
  336. package/src/orgs/orgContext.ts +151 -0
  337. package/src/orgs/orgPermissions.test.ts +105 -0
  338. package/src/orgs/orgPermissions.ts +40 -0
  339. package/src/orgs/orgPlugin.test.ts +130 -0
  340. package/src/orgs/orgPlugin.ts +70 -0
  341. package/src/orgs/orgRbac.test.ts +267 -0
  342. package/src/orgs/orgSecurityDefects.test.ts +415 -0
  343. package/src/orgs/organizationModel.test.ts +205 -0
  344. package/src/orgs/organizationModel.ts +257 -0
  345. package/src/orgs/organizationSettings.test.ts +113 -0
  346. package/src/orgs/organizationSettings.ts +126 -0
  347. package/src/orgs/orgsApp.test.ts +382 -0
  348. package/src/orgs/orgsApp.ts +563 -0
  349. package/src/permissions.test.ts +62 -36
  350. package/src/permissions.ts +8 -30
  351. package/src/plugins.test.ts +14 -0
  352. package/src/plugins.ts +34 -9
  353. package/src/populate.test.ts +34 -0
  354. package/src/populate.ts +40 -29
  355. package/src/rateLimit/applyTrustProxy.ts +17 -0
  356. package/src/rateLimit/createStore.ts +25 -0
  357. package/src/rateLimit/memoryStore.ts +40 -0
  358. package/src/rateLimit/middleware.ts +79 -0
  359. package/src/rateLimit/mongoStore.test.ts +80 -0
  360. package/src/rateLimit/mongoStore.ts +77 -0
  361. package/src/rateLimit/policies.ts +130 -0
  362. package/src/rateLimit/rateLimit.test.ts +328 -0
  363. package/src/rateLimit/redisStore.ioredis.test.ts +29 -0
  364. package/src/rateLimit/redisStore.test.ts +114 -0
  365. package/src/rateLimit/redisStore.ts +86 -0
  366. package/src/rateLimit/types.ts +64 -0
  367. package/src/rbac/access.ts +16 -4
  368. package/src/rbac/assertAllowed.test.ts +325 -0
  369. package/src/rbac/assertAllowed.ts +157 -0
  370. package/src/rbac/backfillAdmins.test.ts +124 -0
  371. package/src/rbac/fieldViews.test.ts +89 -0
  372. package/src/rbac/membershipOrgAdminSource.ts +59 -0
  373. package/src/rbac/modelRouterAccess.test.ts +126 -0
  374. package/src/rbac/modelRouterAccess.ts +8 -2
  375. package/src/rbac/permissionUtils.test.ts +26 -5
  376. package/src/rbac/permissionUtils.ts +3 -2
  377. package/src/rbac/realtimeAccess.test.ts +109 -1
  378. package/src/rbac/resolve.test.ts +34 -2
  379. package/src/rbac/resolve.ts +31 -11
  380. package/src/rbac/roleManager.test.ts +169 -0
  381. package/src/rbac/roleModel.test.ts +34 -1
  382. package/src/rbac/roleModel.ts +17 -1
  383. package/src/rbac/routes.test.ts +233 -0
  384. package/src/rbac/routes.ts +16 -6
  385. package/src/rbac/statements.test.ts +19 -0
  386. package/src/rbac/statements.ts +19 -1
  387. package/src/rbac/types.ts +5 -0
  388. package/src/realtime/changeStreamWatcher.ts +73 -33
  389. package/src/realtime/deprecation.test.ts +60 -0
  390. package/src/realtime/deprecation.ts +33 -0
  391. package/src/realtime/realtime.test.ts +365 -189
  392. package/src/realtime/realtimeApp.ts +11 -11
  393. package/src/realtime/realtimeAppSetup.test.ts +32 -5
  394. package/src/realtime/registry.ts +48 -42
  395. package/src/realtime/sessionRevalidation.test.ts +57 -44
  396. package/src/realtime/socketAuth.test.ts +75 -23
  397. package/src/realtime/socketAuth.ts +17 -6
  398. package/src/realtime/socketUser.ts +5 -3
  399. package/src/realtime/types.ts +14 -4
  400. package/src/schemaMetadata.test.ts +419 -0
  401. package/src/schemaMetadata.ts +593 -0
  402. package/src/scrubAdminFields.test.ts +105 -0
  403. package/src/seedRunner.test.ts +591 -0
  404. package/src/seedRunner.ts +464 -0
  405. package/src/sync/adminBroadcastConfig.test.ts +96 -0
  406. package/src/sync/adminBroadcastScope.test.ts +155 -0
  407. package/src/sync/adminBroadcastScope.ts +123 -0
  408. package/src/sync/adminWindowAccess.test.ts +57 -0
  409. package/src/sync/adminWindowAccess.ts +32 -0
  410. package/src/sync/adminWindowMutation.test.ts +450 -0
  411. package/src/sync/adminWindowMutation.ts +283 -0
  412. package/src/sync/docMatchesMutationData.test.ts +16 -0
  413. package/src/sync/ensureSyncIndexes.test.ts +54 -15
  414. package/src/sync/executors.test.ts +40 -0
  415. package/src/sync/executors.ts +57 -18
  416. package/src/sync/integration.test.ts +15 -7
  417. package/src/sync/loadHarness.ts +28 -19
  418. package/src/sync/models.ts +32 -18
  419. package/src/sync/mutationHandler.test.ts +293 -17
  420. package/src/sync/mutationHandler.ts +180 -36
  421. package/src/sync/registrationSideEffects.test.ts +126 -0
  422. package/src/sync/registrationSideEffects.ts +131 -0
  423. package/src/sync/registry.ts +49 -171
  424. package/src/sync/routes.ts +55 -10
  425. package/src/sync/scripts/compactTombstones.ts +0 -2
  426. package/src/sync/sessionRevalidationIntegration.test.ts +12 -11
  427. package/src/sync/socketHandlers.ts +154 -58
  428. package/src/sync/streams.ts +6 -0
  429. package/src/sync/sync.test.ts +28 -25
  430. package/src/sync/syncApp.ts +5 -4
  431. package/src/sync/syncBatch.ts +10 -4
  432. package/src/sync/syncFrontier.test.ts +17 -15
  433. package/src/sync/syncPhaseC.test.ts +54 -43
  434. package/src/sync/syncRoutes.test.ts +347 -38
  435. package/src/sync/syncSeqPlugin.ts +66 -44
  436. package/src/sync/syncSocket.test.ts +341 -81
  437. package/src/sync/types.ts +20 -0
  438. package/src/terrenoApp.mcpServiceTokens.test.ts +173 -0
  439. package/src/terrenoApp.migrations.test.ts +114 -0
  440. package/src/terrenoApp.test.ts +41 -0
  441. package/src/terrenoApp.ts +181 -46
  442. package/src/tests/createTestData.ts +2 -2
  443. package/src/tests/models.ts +24 -3
  444. package/src/tests/testHelper.ts +1 -7
  445. package/src/types/authToken.ts +41 -0
  446. package/src/types/mcpServiceToken.ts +48 -0
  447. package/src/types/membership.ts +48 -0
  448. package/src/types/notification.ts +34 -0
  449. package/src/types/notificationPreference.ts +28 -0
  450. package/src/types/organization.ts +49 -0
  451. package/src/webhooks/headerValue.test.ts +22 -0
  452. package/src/webhooks/headerValue.ts +12 -0
  453. package/src/webhooks/idempotency/memoryStore.ts +34 -0
  454. package/src/webhooks/idempotency/mongoStore.test.ts +274 -0
  455. package/src/webhooks/idempotency/mongoStore.ts +83 -0
  456. package/src/webhooks/idempotency/webhookReceipt.ts +67 -0
  457. package/src/webhooks/rawBody.test.ts +107 -0
  458. package/src/webhooks/rawBody.ts +24 -0
  459. package/src/webhooks/timingSafeEqual.ts +16 -0
  460. package/src/webhooks/verifiers/hmac.test.ts +110 -0
  461. package/src/webhooks/verifiers/hmac.ts +54 -0
  462. package/src/webhooks/verifiers/providerVerifiers.test.ts +388 -0
  463. package/src/webhooks/verifiers/sendgrid.ts +59 -0
  464. package/src/webhooks/verifiers/stripe.ts +67 -0
  465. package/src/webhooks/verifiers/twilio.ts +69 -0
  466. package/src/webhooks/webhooksApp.test.ts +221 -0
  467. package/src/webhooks/webhooksApp.ts +144 -0
  468. package/tsconfig.json +1 -1
  469. package/tsconfig.typedoc.json +2 -1
  470. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.d.ts +0 -2
  471. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
  472. package/src/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
@@ -1,5 +1,3 @@
1
- // noExplicitAny: test mocks use dynamic shapes for sockets and auth stubs
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test mocks use dynamic shapes for sockets and auth stubs
3
1
  /**
4
2
  * Full validator matrix for the socket authentication chain (D1):
5
3
  * - Legacy JWT validator (valid / expired / wrong-secret / wrong-issuer / missing token)
@@ -12,28 +10,34 @@
12
10
  * subscribe/mutate socket handlers) into its own file per the syncdb hardening plan.
13
11
  */
14
12
  import {describe, expect, it} from "bun:test";
13
+ import {assert} from "chai";
15
14
  import jwt from "jsonwebtoken";
15
+ import type {Socket} from "socket.io";
16
16
 
17
+ import type {UserModel} from "../auth";
17
18
  import {
18
19
  type AuthenticatableSocket,
20
+ type BetterAuthSocketOptions,
19
21
  createBetterAuthValidator,
20
22
  createLegacyJwtValidator,
21
23
  createSocketAuthMiddleware,
22
24
  } from "./socketAuth";
23
25
 
26
+ type StubbedAuth = BetterAuthSocketOptions["auth"];
27
+
24
28
  describe("socketAuth", () => {
25
29
  const tokenSecret = "socket-auth-test-secret";
26
30
 
27
- const makeAuthSocket = (token?: string): AuthenticatableSocket & {decodedToken?: any} => ({
31
+ const makeAuthSocket = (token?: string): AuthenticatableSocket => ({
28
32
  handshake: {auth: token === undefined ? {} : {token}},
29
33
  });
30
34
 
31
35
  const runMiddleware = (
32
- middleware: (socket: any, next: (error?: Error) => void) => void,
36
+ middleware: (socket: Socket, next: (error?: Error) => void) => void,
33
37
  socket: AuthenticatableSocket
34
38
  ): Promise<Error | undefined> =>
35
39
  new Promise((resolve) => {
36
- middleware(socket, (error?: Error) => resolve(error));
40
+ middleware(socket as unknown as Socket, (error?: Error) => resolve(error));
37
41
  });
38
42
 
39
43
  describe("createLegacyJwtValidator", () => {
@@ -142,16 +146,20 @@ describe("socketAuth", () => {
142
146
  });
143
147
 
144
148
  describe("createBetterAuthValidator", () => {
145
- const stubAuth = (session: unknown, capture?: {headers?: unknown}): any => ({
146
- api: {
147
- getSession: async ({headers}: {headers: unknown}) => {
148
- if (capture) {
149
- capture.headers = headers;
150
- }
151
- return session;
149
+ const stubAuth = (
150
+ session: unknown,
151
+ capture?: {headers?: Record<string, string>}
152
+ ): StubbedAuth =>
153
+ ({
154
+ api: {
155
+ getSession: async ({headers}: {headers: Record<string, string>}) => {
156
+ if (capture) {
157
+ capture.headers = headers;
158
+ }
159
+ return session;
160
+ },
152
161
  },
153
- },
154
- });
162
+ }) as unknown as StubbedAuth;
155
163
 
156
164
  it("populates decodedToken from a valid Better Auth session", async () => {
157
165
  const validator = createBetterAuthValidator({
@@ -177,15 +185,15 @@ describe("socketAuth", () => {
177
185
  });
178
186
 
179
187
  it("passes the token as a bearer authorization header only", async () => {
180
- const capture: {headers?: any} = {};
188
+ const capture: {headers?: Record<string, string>} = {};
181
189
  const validator = createBetterAuthValidator({
182
190
  auth: stubAuth({session: {id: "s"}, user: {id: "u"}}, capture),
183
191
  });
184
192
  await validator(makeAuthSocket("Bearer session-token-xyz"));
185
- expect(capture.headers.authorization).toBe("Bearer session-token-xyz");
193
+ expect(capture.headers?.authorization).toBe("Bearer session-token-xyz");
186
194
  // A raw (unsigned) token cookie fails signature verification and can shadow the
187
195
  // bearer path, so the validator must not send one.
188
- expect(capture.headers.cookie).toBeUndefined();
196
+ expect(capture.headers?.cookie).toBeUndefined();
189
197
  });
190
198
 
191
199
  it("rejects when the session lookup returns null", async () => {
@@ -211,7 +219,7 @@ describe("socketAuth", () => {
211
219
  query.betterAuthId === "ba-user-1" ? appUser : null;
212
220
  const validator = createBetterAuthValidator({
213
221
  auth: stubAuth({session: {id: "s"}, user: {id: "ba-user-1"}}),
214
- userModel: {...userModel, findOneOrNone} as any,
222
+ userModel: {...userModel, findOneOrNone} as unknown as UserModel,
215
223
  });
216
224
  const socket = makeAuthSocket("session-token");
217
225
  await validator(socket);
@@ -226,7 +234,7 @@ describe("socketAuth", () => {
226
234
  it("rejects when the Better Auth user has no application user", async () => {
227
235
  const validator = createBetterAuthValidator({
228
236
  auth: stubAuth({session: {id: "s"}, user: {id: "ba-orphan"}}),
229
- userModel: {findOneOrNone: async () => null} as any,
237
+ userModel: {findOneOrNone: async () => null} as unknown as UserModel,
230
238
  });
231
239
  await expect(validator(makeAuthSocket("session-token"))).rejects.toThrow(
232
240
  "no application user"
@@ -235,6 +243,34 @@ describe("socketAuth", () => {
235
243
  });
236
244
 
237
245
  describe("createSocketAuthMiddleware — validator chain", () => {
246
+ it("authenticates with Better Auth when no JWT secret is configured", async () => {
247
+ const middleware = createSocketAuthMiddleware({
248
+ betterAuth: {
249
+ auth: {
250
+ api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-only"}})},
251
+ } as unknown as BetterAuthSocketOptions["auth"],
252
+ },
253
+ });
254
+ const socket = makeAuthSocket("better-auth-session-token");
255
+
256
+ const error = await runMiddleware(middleware, socket);
257
+
258
+ assert.isUndefined(error);
259
+ assert.deepEqual(socket.decodedToken, {
260
+ admin: false,
261
+ authKind: "better-auth",
262
+ id: "ba-only",
263
+ isAnonymous: false,
264
+ });
265
+ });
266
+
267
+ it("rejects configuration with no authentication validators", () => {
268
+ assert.throws(
269
+ () => createSocketAuthMiddleware({}),
270
+ "At least one socket authentication validator is required"
271
+ );
272
+ });
273
+
238
274
  it("accepts a legacy JWT with the default chain", async () => {
239
275
  const middleware = createSocketAuthMiddleware({tokenSecret});
240
276
  const token = jwt.sign({admin: false, id: "chain-user"}, tokenSecret);
@@ -258,7 +294,7 @@ describe("socketAuth", () => {
258
294
  betterAuth: {
259
295
  auth: {
260
296
  api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-user-2"}})},
261
- } as any,
297
+ } as unknown as StubbedAuth,
262
298
  },
263
299
  tokenSecret,
264
300
  });
@@ -273,12 +309,28 @@ describe("socketAuth", () => {
273
309
  });
274
310
  });
275
311
 
312
+ it("accepts Better Auth sessions without a legacy JWT secret", async () => {
313
+ const middleware = createSocketAuthMiddleware({
314
+ betterAuth: {
315
+ auth: {
316
+ api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-only-user"}})},
317
+ } as unknown as StubbedAuth,
318
+ },
319
+ });
320
+ const socket = makeAuthSocket("better-auth-session-token");
321
+ const error = await runMiddleware(middleware, socket);
322
+
323
+ assert.isUndefined(error);
324
+ assert.strictEqual(socket.decodedToken?.id, "ba-only-user");
325
+ assert.strictEqual(socket.decodedToken?.authKind, "better-auth");
326
+ });
327
+
276
328
  it("falls through to Better Auth when the JWT is expired", async () => {
277
329
  const middleware = createSocketAuthMiddleware({
278
330
  betterAuth: {
279
331
  auth: {
280
332
  api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-fallback"}})},
281
- } as any,
333
+ } as unknown as StubbedAuth,
282
334
  },
283
335
  tokenSecret,
284
336
  });
@@ -298,7 +350,7 @@ describe("socketAuth", () => {
298
350
  throw new Error("should not be called for a valid JWT");
299
351
  },
300
352
  },
301
- } as any,
353
+ } as unknown as StubbedAuth,
302
354
  },
303
355
  tokenSecret,
304
356
  });
@@ -312,7 +364,7 @@ describe("socketAuth", () => {
312
364
 
313
365
  it("rejects with the last validator's error when every validator fails", async () => {
314
366
  const middleware = createSocketAuthMiddleware({
315
- betterAuth: {auth: {api: {getSession: async () => null}} as any},
367
+ betterAuth: {auth: {api: {getSession: async () => null}} as unknown as StubbedAuth},
316
368
  tokenSecret,
317
369
  });
318
370
  const socket = makeAuthSocket("neither-jwt-nor-session");
@@ -3,6 +3,7 @@ import type {Socket} from "socket.io";
3
3
 
4
4
  import type {UserModel} from "../auth";
5
5
  import type {BetterAuthInstance} from "../betterAuthSetup";
6
+ import {APIError} from "../errors";
6
7
  import {logger} from "../logger";
7
8
  import {findOneOrNoneFor} from "../plugins";
8
9
  import type {SocketWithDecodedToken} from "./socketUser";
@@ -16,9 +17,9 @@ import type {SocketWithDecodedToken} from "./socketUser";
16
17
  * fails, the connection is rejected with the last validator's error.
17
18
  *
18
19
  * Validators:
19
- * 1. Legacy JWT (default, always first) — the existing `@thream/socketio-jwt` middleware,
20
- * wrapped unchanged so accepted payloads, secret handling, and error shapes are
21
- * byte-for-byte identical to the previous hardcoded setup.
20
+ * 1. Legacy JWT (when a token secret is configured, always first) — the existing
21
+ * `@thream/socketio-jwt` middleware, wrapped unchanged so accepted payloads, secret
22
+ * handling, and error shapes are byte-for-byte identical to the previous hardcoded setup.
22
23
  * 2. Better Auth session (optional) — enabled via `RealtimeAppOptions.betterAuth`. The
23
24
  * handshake token is validated as a Better Auth session via `auth.api.getSession`
24
25
  * (presented as an `Authorization: Bearer` credential, resolved by Better Auth's
@@ -188,8 +189,8 @@ export const createSocketAuthMiddleware = ({
188
189
  betterAuth,
189
190
  extraValidators = [],
190
191
  }: {
191
- /** Secret for the legacy JWT validator (same handling as before the refactor). */
192
- tokenSecret: string;
192
+ /** Secret enabling the legacy JWT validator (same handling as before the refactor). */
193
+ tokenSecret?: string;
193
194
  /**
194
195
  * JWT issuer to require (D1 parity with the HTTP path's `jwt.verify(token, secret,
195
196
  * {issuer})`). Omitted means no issuer check, matching pre-D1 behavior. A thunk is
@@ -201,12 +202,22 @@ export const createSocketAuthMiddleware = ({
201
202
  /** Additional validators appended to the chain (after JWT and Better Auth). */
202
203
  extraValidators?: SocketAuthValidator[];
203
204
  }): ((socket: Socket, next: (error?: Error) => void) => void) => {
204
- const validators: SocketAuthValidator[] = [createLegacyJwtValidator(tokenSecret, issuer)];
205
+ const validators: SocketAuthValidator[] = [];
206
+ if (tokenSecret) {
207
+ validators.push(createLegacyJwtValidator(tokenSecret, issuer));
208
+ }
205
209
  if (betterAuth) {
206
210
  validators.push(createBetterAuthValidator(betterAuth));
207
211
  }
208
212
  validators.push(...extraValidators);
209
213
 
214
+ if (validators.length === 0) {
215
+ throw new APIError({
216
+ status: 500,
217
+ title: "[realtime] At least one socket authentication validator is required.",
218
+ });
219
+ }
220
+
210
221
  return (socket, next): void => {
211
222
  void (async () => {
212
223
  let lastError: Error = new UnauthorizedError("credentials_required", {
@@ -28,9 +28,11 @@ export interface DecodedRealtimeToken {
28
28
  * configured, or while the handshake load is still in flight.
29
29
  */
30
30
  export interface SocketDataBag {
31
- // noExplicitAny: the full user is a consumer Mongoose document with app-specific fields
32
- // biome-ignore lint/suspicious/noExplicitAny: the full user is a consumer Mongoose document with app-specific fields
33
- fullUser?: any;
31
+ /**
32
+ * The consumer's own Mongoose user document, so its app-specific fields are opaque
33
+ * here — read it through {@link getSocketUser} rather than narrowing it inline.
34
+ */
35
+ fullUser?: unknown;
34
36
  /**
35
37
  * The in-flight handshake load of {@link SocketDataBag.fullUser}, published so handlers
36
38
  * that must not authorize against the synthetic token user can await it
@@ -8,6 +8,9 @@ import type {BetterAuthSocketOptions} from "./socketAuth";
8
8
  /**
9
9
  * Configuration for real-time sync on a modelRouter.
10
10
  * Determines which CRUD methods emit WebSocket events and how they are routed.
11
+ *
12
+ * @deprecated Removed in Terreno 58. Use `sync` on modelRouter with `@terreno/syncdb`.
13
+ * `RealtimeApp` remains required for sync sockets.
11
14
  */
12
15
  export interface RealtimeConfig {
13
16
  /** Which CRUD methods should emit real-time sync events */
@@ -30,6 +33,9 @@ export interface RealtimeConfig {
30
33
 
31
34
  /**
32
35
  * A real-time sync event emitted to clients via WebSocket.
36
+ *
37
+ * @deprecated Removed in Terreno 58 with modelRouter `realtime` and the RTK
38
+ * cache-patching helpers. Syncdb uses `sync:delta` events instead.
33
39
  */
34
40
  export interface RealtimeEvent {
35
41
  /** Mongoose model name (e.g. "Todo") */
@@ -83,7 +89,10 @@ export interface RealtimeAppOptions {
83
89
  adapter?: "redis" | "none";
84
90
  /** Redis URL for the Redis adapter */
85
91
  redisUrl?: string;
86
- /** JWT secret for socket authentication (default: process.env.TOKEN_SECRET) */
92
+ /**
93
+ * JWT secret for socket authentication (default: process.env.TOKEN_SECRET).
94
+ * Optional when `betterAuth` is configured.
95
+ */
87
96
  tokenSecret?: string;
88
97
  /**
89
98
  * JWT issuer required for socket authentication (default: process.env.TOKEN_ISSUER),
@@ -92,9 +101,10 @@ export interface RealtimeAppOptions {
92
101
  */
93
102
  tokenIssuer?: string;
94
103
  /**
95
- * Enables the Better Auth session validator for socket authentication, tried after the
96
- * legacy JWT validator. Pass the instance returned by `createBetterAuth` (and optionally
97
- * the app user model so `decodedToken.id`/`admin` match the REST identity).
104
+ * Enables the Better Auth session validator for socket authentication. It is tried after
105
+ * the legacy JWT validator when a token secret exists, or used alone otherwise. Pass the
106
+ * instance returned by `createBetterAuth` (and optionally the app user model so
107
+ * `decodedToken.id`/`admin` match the REST identity).
98
108
  */
99
109
  betterAuth?: BetterAuthSocketOptions;
100
110
  /**