@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
@@ -6,6 +6,7 @@ import type {ModelRouterOptions, RESTMethod} from "./api";
6
6
  import type {User} from "./auth";
7
7
  import {loadDocOr404} from "./docLoader";
8
8
  import {APIError} from "./errors";
9
+ import {isOrgMemberPermission, OrgQueryFilter} from "./orgs/orgPermissions";
9
10
 
10
11
  export type PermissionMethod<T> = (
11
12
  method: RESTMethod,
@@ -43,16 +44,10 @@ export const getUserOrganizationIds = (user?: User): string[] => {
43
44
  };
44
45
 
45
46
  /**
46
- * Restricts list queries to documents belonging to one of the caller's organizations. This is the
47
- * tenant-scoped analog of {@link OwnerQueryFilter}: it filters on the document's `organizationId`
48
- * field using the user's `organizationIds`. Returns `null` for anonymous callers (no user).
47
+ * Restricts list queries to the current request organization (`X-Organization-Id` or inferred
48
+ * single org-admin membership). Does not read `User.organizationIds`.
49
49
  */
50
- export const OrganizationQueryFilter = (user?: User) => {
51
- if (!user) {
52
- return null;
53
- }
54
- return {organizationId: {$in: getUserOrganizationIds(user)}};
55
- };
50
+ export const OrganizationQueryFilter = OrgQueryFilter;
56
51
 
57
52
  export const Permissions = {
58
53
  IsAdmin: (_method: RESTMethod, user?: User) => {
@@ -74,28 +69,11 @@ export const Permissions = {
74
69
  return method === "list" || method === "read";
75
70
  },
76
71
  /**
77
- * Object-level permission for tenant-scoped documents: the caller must belong to the document's
78
- * organization (admins always pass). With no object (list/create checks) it returns true and
79
- * defers to the {@link OrganizationQueryFilter} / a `preCreate` hook to scope access. Expects the
80
- * document to expose an `organizationId` and the user an `organizationIds` array.
72
+ * Object-level permission for tenant-scoped documents: platform org actors must match the
73
+ * current org context; everyone else needs an active Membership. With no object (list/create)
74
+ * it returns true and defers to {@link OrganizationQueryFilter}.
81
75
  */
82
- IsOrganizationMember: (_method: RESTMethod, user?: User, obj?: unknown) => {
83
- // When checking if we can possibly perform the action, return true.
84
- if (!obj) {
85
- return true;
86
- }
87
- if (!user) {
88
- return false;
89
- }
90
- if (user?.admin) {
91
- return true;
92
- }
93
- const organizationId = (obj as {organizationId?: string}).organizationId;
94
- if (!organizationId) {
95
- return false;
96
- }
97
- return getUserOrganizationIds(user).includes(organizationId);
98
- },
76
+ IsOrganizationMember: isOrgMemberPermission,
99
77
  IsOwner: (_method: RESTMethod, user?: User, obj?: unknown) => {
100
78
  // When checking if we can possibly perform the action, return true.
101
79
  if (!obj) {
@@ -19,6 +19,7 @@ import {
19
19
  baseUserPlugin,
20
20
  createdUpdatedPlugin,
21
21
  DateOnly,
22
+ emailVerificationPlugin,
22
23
  excludeArchivedPlugin,
23
24
  findExactlyOne,
24
25
  findOneOrNone,
@@ -94,6 +95,19 @@ describe("baseUserPlugin", () => {
94
95
  });
95
96
  });
96
97
 
98
+ describe("emailVerificationPlugin", () => {
99
+ it("adds emailVerified defaulting to false", () => {
100
+ const testSchema = new Schema({});
101
+ emailVerificationPlugin(testSchema);
102
+
103
+ const emailVerifiedPath = testSchema.path("emailVerified");
104
+ expect(emailVerifiedPath).toBeDefined();
105
+ expect((emailVerifiedPath as unknown as {options: {default: boolean}}).options.default).toBe(
106
+ false
107
+ );
108
+ });
109
+ });
110
+
97
111
  describe("firebaseJWTPlugin", () => {
98
112
  it("adds firebaseId field to the schema", () => {
99
113
  const testSchema = new Schema({});
package/src/plugins.ts CHANGED
@@ -42,6 +42,24 @@ export const baseUserPlugin = (schema: Schema<any, any, any, any>): void => {
42
42
  schema.add({email: {description: "The user's email address", index: true, type: String}});
43
43
  };
44
44
 
45
+ export interface EmailVerified {
46
+ emailVerified: boolean;
47
+ }
48
+
49
+ /**
50
+ * Opt-in `emailVerified` field for user schemas. Defaults to false so existing
51
+ * documents stay unverified until they complete the email-verification flow.
52
+ */
53
+ export const emailVerificationPlugin = (schema: Parameters<typeof baseUserPlugin>[0]): void => {
54
+ schema.add({
55
+ emailVerified: {
56
+ default: false,
57
+ description: "Whether the user has verified their email address",
58
+ type: Boolean,
59
+ },
60
+ });
61
+ };
62
+
45
63
  /** For models with the isDeletedPlugin, extend this interface to add the appropriate fields. */
46
64
  export interface IsDeleted {
47
65
  // Whether the model should be treated as deleted or not.
@@ -355,6 +373,18 @@ export interface FindExactlyOnePlugin<T> {
355
373
  ): Promise<Document & T>;
356
374
  }
357
375
 
376
+ type DateOnlyConditionalHandler = (this: DateOnly, val: unknown) => Date | undefined;
377
+
378
+ interface SchemaTypeWithConditionalHandlers {
379
+ $conditionalHandlers?: Record<string, DateOnlyConditionalHandler>;
380
+ }
381
+
382
+ interface SchemaTypeWithApplySetters {
383
+ applySetters: (val: unknown, context: unknown) => Date | undefined;
384
+ }
385
+
386
+ type SchemaTypesWithDateOnly = typeof mongoose.Schema.Types & {DateOnly: typeof DateOnly};
387
+
358
388
  export class DateOnly extends SchemaType {
359
389
  constructor(key: string, options: SchemaTypeOptions<Date>) {
360
390
  super(key, options, "DateOnly");
@@ -365,9 +395,8 @@ export class DateOnly extends SchemaType {
365
395
  }
366
396
 
367
397
  $conditionalHandlers = {
368
- // noExplicitAny: $conditionalHandlers is not exposed on SchemaType's prototype in Mongoose's public type definitions
369
- // biome-ignore lint/suspicious/noExplicitAny: $conditionalHandlers is not exposed on SchemaType's prototype in Mongoose's public type definitions
370
- ...(SchemaType as any).prototype.$conditionalHandlers,
398
+ ...(SchemaType as unknown as {prototype: SchemaTypeWithConditionalHandlers}).prototype
399
+ .$conditionalHandlers,
371
400
  $gt: this.handleSingle,
372
401
  $gte: this.handleSingle,
373
402
  $lt: this.handleSingle,
@@ -378,9 +407,7 @@ export class DateOnly extends SchemaType {
378
407
  // When using $gt, $gte, $lt, $lte, etc, we need to cast the value to a Date
379
408
  castForQuery($conditional: string | undefined, val: unknown, context: unknown): Date | undefined {
380
409
  if ($conditional == null) {
381
- // noExplicitAny: applySetters is an internal Mongoose SchemaType method not in public type definitions
382
- // biome-ignore lint/suspicious/noExplicitAny: applySetters is an internal Mongoose SchemaType method not in public type definitions
383
- return (this as any).applySetters(val, context);
410
+ return (this as unknown as SchemaTypeWithApplySetters).applySetters(val, context);
384
411
  }
385
412
 
386
413
  const handler = this.$conditionalHandlers[$conditional];
@@ -447,6 +474,4 @@ export class DateOnly extends SchemaType {
447
474
  }
448
475
 
449
476
  // Register DateOnly with Mongoose's Schema.Types
450
- // noExplicitAny: DateOnly is a custom SchemaType not declared in Mongoose's Schema.Types interface
451
- // biome-ignore lint/suspicious/noExplicitAny: DateOnly is a custom SchemaType not declared in Mongoose's Schema.Types interface
452
- (mongoose.Schema.Types as any).DateOnly = DateOnly;
477
+ (mongoose.Schema.Types as SchemaTypesWithDateOnly).DateOnly = DateOnly;
@@ -1,4 +1,5 @@
1
1
  import {beforeEach, describe, expect, it} from "bun:test";
2
+ import {assert} from "chai";
2
3
  import mongoose, {type Document, type HydratedDocument, Schema} from "mongoose";
3
4
 
4
5
  import {fixMixedFields, getOpenApiSpecForModel, unpopulate} from "./populate";
@@ -116,6 +117,31 @@ describe("unpopulate edge cases", () => {
116
117
  expect(result).toEqual(doc);
117
118
  });
118
119
 
120
+ it("leaves unpopulated values untouched", () => {
121
+ const doc = {
122
+ name: "test",
123
+ // Already an id rather than a populated document.
124
+ ownerId: "owner-123",
125
+ tags: ["tag-1", "tag-2"],
126
+ };
127
+ const result = unpopulate(doc as unknown as Document<unknown>, "ownerId") as unknown as {
128
+ ownerId: string;
129
+ tags: string[];
130
+ };
131
+ assert.equal(result.ownerId, "owner-123");
132
+ unpopulate(doc as unknown as Document<unknown>, "tags");
133
+ assert.deepEqual(result.tags, ["tag-1", "tag-2"]);
134
+ });
135
+
136
+ it("returns the doc when a nested path is missing on the parent", () => {
137
+ const doc = {
138
+ name: "test",
139
+ nested: {other: "value"},
140
+ };
141
+ const result = unpopulate(doc as unknown as Document<unknown>, "nested.items");
142
+ assert.deepEqual(result, doc as unknown as Document<unknown>);
143
+ });
144
+
119
145
  it("handles nested array paths", () => {
120
146
  const doc = {
121
147
  containers: [
@@ -170,6 +196,14 @@ describe("fixMixedFields", () => {
170
196
  expect(properties.items.items.properties.meta).toEqual({description: undefined});
171
197
  });
172
198
 
199
+ it("skips arrays of sub-documents whose OpenAPI items have no properties", () => {
200
+ const subSchema = new Schema({meta: {type: Schema.Types.Mixed}});
201
+ const schema = new Schema({items: [subSchema]});
202
+ const properties = {items: {type: "array" as const}};
203
+ fixMixedFields(schema, properties);
204
+ assert.deepEqual(properties, {items: {type: "array"}});
205
+ });
206
+
173
207
  it("skips unknown paths", () => {
174
208
  const schema = new Schema({foo: String});
175
209
  const properties = {unknownKey: {type: "string"}};
package/src/populate.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import isArray from "lodash/isArray";
2
- import type {Document, Schema} from "mongoose";
2
+ import type {Document, Model, Schema} from "mongoose";
3
3
  import m2s from "mongoose-to-swagger";
4
4
 
5
5
  import {APIError} from "./errors";
6
+ import {describeModel, modelDescriptionToOpenApiSpec} from "./schemaMetadata";
6
7
 
7
8
  const m2sOptions = {
8
9
  props: ["readOnly", "required", "enum", "default"],
@@ -139,20 +140,22 @@ export const fixMixedFields = (schema: Schema | null, properties: Record<string,
139
140
  }
140
141
  };
141
142
 
142
- export const getOpenApiSpecForModel = (
143
- // noExplicitAny: Mongoose Model param uses deep internal APIs (schema.path().options.ref, schema.virtuals, schema.childSchemas, db.model) that are not exposed in public type definitions
144
- // biome-ignore lint/suspicious/noExplicitAny: Mongoose Model param uses deep internal APIs (schema.path().options.ref, schema.virtuals, schema.childSchemas, db.model) that are not exposed in public type definitions
145
- model: any,
143
+ export const getOpenApiSpecForModel = <T>(
144
+ model: Model<T>,
146
145
  {
147
146
  populatePaths,
148
147
  extraModelProperties,
149
148
  }: {populatePaths?: PopulatePath[]; extraModelProperties?: Record<string, unknown>} = {}
150
149
  ): {properties: Record<string, unknown>; required: string[]} => {
151
- const modelSwagger = m2s(model, {
152
- props: ["required", "enum"],
153
- });
150
+ const description = describeModel(model);
151
+ const {properties, required} = modelDescriptionToOpenApiSpec(description);
152
+ const modelProperties = properties as Record<string, OpenApiSchemaNode>;
153
+ const modelSwagger = {
154
+ properties: modelProperties,
155
+ required,
156
+ };
154
157
 
155
- fixMixedFields(model.schema, modelSwagger.properties);
158
+ fixMixedFields(model.schema, modelProperties);
156
159
 
157
160
  if (populatePaths && isArray(populatePaths)) {
158
161
  for (const populatePath of populatePaths) {
@@ -190,7 +193,7 @@ export const getOpenApiSpecForModel = (
190
193
 
191
194
  // Navigate through the nested structure and set the schema
192
195
  const pathParts = openApiPath.split(".");
193
- let currentSchema = modelSwagger.properties;
196
+ let currentSchema: Record<string, OpenApiSchemaNode> = modelSwagger.properties;
194
197
  for (let i = 0; i < pathParts.length; i++) {
195
198
  const part = pathParts[i];
196
199
  if (i === pathParts.length - 1) {
@@ -201,7 +204,7 @@ export const getOpenApiSpecForModel = (
201
204
  ...(schemaToSet.properties || {[part]: schemaToSet}),
202
205
  };
203
206
  } else {
204
- currentSchema[part] = schemaToSet;
207
+ currentSchema[part] = schemaToSet as OpenApiSchemaNode;
205
208
  }
206
209
  } else {
207
210
  // We're still navigating, ensure the path exists
@@ -214,7 +217,8 @@ export const getOpenApiSpecForModel = (
214
217
  currentSchema[part] = {properties: {}, type: "object"};
215
218
  }
216
219
  }
217
- currentSchema = currentSchema[part].properties || currentSchema[part];
220
+ const nextSchema = currentSchema[part].properties ?? currentSchema[part];
221
+ currentSchema = nextSchema as Record<string, OpenApiSchemaNode>;
218
222
  }
219
223
  }
220
224
  }
@@ -238,7 +242,11 @@ export const getOpenApiSpecForModel = (
238
242
  if (virtual === "id" || virtual === "__v") {
239
243
  continue;
240
244
  }
241
- modelSwagger.properties[childSchema.model.path].properties[virtual] = {
245
+ const childPath = childSchema.model.path;
246
+ if (!childPath || !modelSwagger.properties[childPath]?.properties) {
247
+ continue;
248
+ }
249
+ modelSwagger.properties[childPath].properties[virtual] = {
242
250
  type: "any",
243
251
  };
244
252
  }
@@ -261,41 +269,44 @@ export const unpopulate = <T>(doc: Document<T>, path: string): Document<T> => {
261
269
  }
262
270
  const pathParts = path.split(".");
263
271
 
272
+ // Traversal treats documents as plain nested records: the populated shapes are only known
273
+ // at runtime, so each level is narrowed as it is visited.
274
+ type NestedRecord = Record<string, unknown>;
275
+ const asRecord = (value: unknown): NestedRecord => value as NestedRecord;
276
+ const idOf = (value: unknown): unknown => (value as {_id?: unknown} | null)?._id;
277
+
264
278
  // Recursive because we need to support nested paths.
265
- // noExplicitAny: recursive document traversal uses bracket-notation indexing on arbitrary nested document shapes that Mongoose Document types do not expose
266
- // biome-ignore lint/suspicious/noExplicitAny: recursive document traversal uses bracket-notation indexing on arbitrary nested document shapes that Mongoose Document types do not expose
267
- const recursiveUnpopulate = (current: any, parts: string[]): any => {
279
+ const recursiveUnpopulate = (current: NestedRecord, parts: string[]): NestedRecord => {
268
280
  const part = parts[0];
281
+ const value = current[part];
269
282
 
270
283
  // If the path doesn't exist, return the original doc
271
- if (!current[part]) {
272
- return doc;
284
+ if (!value) {
285
+ return asRecord(doc);
273
286
  }
274
287
 
275
288
  if (parts.length === 1) {
276
289
  // Base case: we've reached the last part of the path
277
- if (Array.isArray(current[part])) {
290
+ if (Array.isArray(value)) {
278
291
  // If the field is an array, recursively unpopulate each element
279
- current[part] = current[part].map((item) => {
280
- return item?._id ? item._id : item;
281
- });
282
- } else if (current[part]?._id) {
292
+ current[part] = value.map((item) => idOf(item) ?? item);
293
+ } else if (idOf(value)) {
283
294
  // If the field is a populated document, revert to _id
284
- current[part] = current[part]._id;
295
+ current[part] = idOf(value);
285
296
  }
286
297
  } else {
287
298
  // Recursive case: continue down the path
288
- if (Array.isArray(current[part])) {
289
- for (const item of current[part]) {
290
- recursiveUnpopulate(item, parts.slice(1)); // Recursively handle each item in the array
299
+ if (Array.isArray(value)) {
300
+ for (const item of value) {
301
+ recursiveUnpopulate(asRecord(item), parts.slice(1)); // Recursively handle each item in the array
291
302
  }
292
303
  } else {
293
- recursiveUnpopulate(current[part], parts.slice(1)); // Recursively handle the next part
304
+ recursiveUnpopulate(asRecord(value), parts.slice(1)); // Recursively handle the next part
294
305
  }
295
306
  }
296
307
 
297
308
  return current;
298
309
  };
299
310
 
300
- return recursiveUnpopulate(doc, pathParts);
311
+ return recursiveUnpopulate(asRecord(doc), pathParts) as unknown as Document<T>;
301
312
  };
@@ -0,0 +1,17 @@
1
+ import type {Application} from "express";
2
+
3
+ import type {RateLimitOptions} from "./types";
4
+
5
+ export const applyRateLimitTrustProxy = (app: Application, options: RateLimitOptions): void => {
6
+ if (options.trustProxy === false) {
7
+ app.set("trust proxy", false);
8
+ return;
9
+ }
10
+ if (options.trustProxy !== undefined) {
11
+ app.set("trust proxy", options.trustProxy);
12
+ return;
13
+ }
14
+ // Default off so client X-Forwarded-For cannot rotate unauthenticated buckets.
15
+ // Cloud Run / GFE: pass trustProxy: 1.
16
+ app.set("trust proxy", false);
17
+ };
@@ -0,0 +1,25 @@
1
+ import {APIError} from "../errors";
2
+ import {createMemoryRateLimitStore} from "./memoryStore";
3
+ import {createMongoRateLimitStore} from "./mongoStore";
4
+ import {createRedisRateLimitStore} from "./redisStore";
5
+ import type {RateLimitOptions, RateLimitStore} from "./types";
6
+
7
+ export const createRateLimitStore = (options: RateLimitOptions): RateLimitStore => {
8
+ if (options.storeImpl) {
9
+ return options.storeImpl;
10
+ }
11
+ const kind = options.store ?? "memory";
12
+ if (kind === "memory") {
13
+ return createMemoryRateLimitStore();
14
+ }
15
+ if (kind === "redis") {
16
+ return createRedisRateLimitStore(options);
17
+ }
18
+ if (kind === "mongo") {
19
+ return createMongoRateLimitStore();
20
+ }
21
+ throw new APIError({
22
+ status: 500,
23
+ title: `Unknown rate limit store: ${String(kind)}`,
24
+ });
25
+ };
@@ -0,0 +1,40 @@
1
+ import type {RateLimitConsumeArgs, RateLimitConsumeResult, RateLimitStore} from "./types";
2
+
3
+ interface MemoryWindow {
4
+ count: number;
5
+ resetAt: number;
6
+ }
7
+
8
+ export const createMemoryRateLimitStore = (): RateLimitStore => {
9
+ const windows = new Map<string, MemoryWindow>();
10
+
11
+ const consume = async ({
12
+ key,
13
+ max,
14
+ windowMs,
15
+ now,
16
+ }: RateLimitConsumeArgs): Promise<RateLimitConsumeResult> => {
17
+ const existing = windows.get(key);
18
+ if (!existing || existing.resetAt <= now) {
19
+ if (windows.size > 10_000) {
20
+ for (const [windowKey, window] of windows) {
21
+ if (window.resetAt <= now) {
22
+ windows.delete(windowKey);
23
+ }
24
+ }
25
+ }
26
+ const resetAt = now + windowMs;
27
+ windows.set(key, {count: 1, resetAt});
28
+ return {allowed: true, remaining: Math.max(0, max - 1), resetAt};
29
+ }
30
+ existing.count += 1;
31
+ const allowed = existing.count <= max;
32
+ return {
33
+ allowed,
34
+ remaining: Math.max(0, max - existing.count),
35
+ resetAt: existing.resetAt,
36
+ };
37
+ };
38
+
39
+ return {consume};
40
+ };
@@ -0,0 +1,79 @@
1
+ import type {NextFunction, Request, Response} from "express";
2
+ import {DateTime} from "luxon";
3
+
4
+ import {APIError} from "../errors";
5
+ import {classifyRateLimitPolicy, rateLimitKey, shouldSkipRateLimit} from "./policies";
6
+ import type {RateLimitOptions, RateLimitStore} from "./types";
7
+ import {DEFAULT_API_MAX, DEFAULT_AUTH_MAX, DEFAULT_WINDOW_MS} from "./types";
8
+
9
+ const secondsUntil = (resetAt: number, now: number): number => {
10
+ return Math.max(1, Math.ceil((resetAt - now) / 1000));
11
+ };
12
+
13
+ const setRateLimitExceededHeaders = ({
14
+ max,
15
+ remaining,
16
+ resetAt,
17
+ now,
18
+ windowMs,
19
+ res,
20
+ }: {
21
+ max: number;
22
+ remaining: number;
23
+ resetAt: number;
24
+ now: number;
25
+ windowMs: number;
26
+ res: Response;
27
+ }): void => {
28
+ const retryAfter = secondsUntil(resetAt, now);
29
+ const windowSec = Math.max(1, Math.ceil(windowMs / 1000));
30
+ res.setHeader("Retry-After", String(retryAfter));
31
+ res.setHeader("RateLimit", `limit=${max}, remaining=${remaining}, reset=${retryAfter}`);
32
+ res.setHeader("RateLimit-Policy", `${max};w=${windowSec}`);
33
+ };
34
+
35
+ export const createRateLimitMiddleware = (
36
+ store: RateLimitStore,
37
+ options: RateLimitOptions = {}
38
+ ): ((req: Request, res: Response, next: NextFunction) => Promise<void>) => {
39
+ const windowMs = options.limits?.windowMs ?? DEFAULT_WINDOW_MS;
40
+ const authMax = options.limits?.authMax ?? DEFAULT_AUTH_MAX;
41
+ const apiMax = options.limits?.apiMax ?? DEFAULT_API_MAX;
42
+ const betterAuthBasePath = options.betterAuthBasePath;
43
+ const nowFn = options.now ?? ((): number => DateTime.now().toMillis());
44
+
45
+ return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
46
+ if (shouldSkipRateLimit(req, options.skip)) {
47
+ next();
48
+ return;
49
+ }
50
+ const policy = classifyRateLimitPolicy(req, betterAuthBasePath);
51
+ const max = policy === "auth" ? authMax : apiMax;
52
+ const key = `${policy}:${rateLimitKey(req, policy)}`;
53
+ const now = nowFn();
54
+ try {
55
+ const result = await store.consume({key, max, now, windowMs});
56
+ if (result.allowed) {
57
+ next();
58
+ return;
59
+ }
60
+ setRateLimitExceededHeaders({
61
+ max,
62
+ now,
63
+ remaining: result.remaining,
64
+ res,
65
+ resetAt: result.resetAt,
66
+ windowMs,
67
+ });
68
+ next(
69
+ new APIError({
70
+ code: "rate-limit-exceeded",
71
+ status: 429,
72
+ title: "Too many requests",
73
+ })
74
+ );
75
+ } catch (error) {
76
+ next(error);
77
+ }
78
+ };
79
+ };
@@ -0,0 +1,80 @@
1
+ import {beforeEach, describe, it} from "bun:test";
2
+ import {assert} from "chai";
3
+ import mongoose from "mongoose";
4
+
5
+ import {setupTestData} from "../tests";
6
+ import {createRateLimitStore} from "./createStore";
7
+ import {createMongoRateLimitStore, RATE_LIMIT_HITS_COLLECTION} from "./mongoStore";
8
+
9
+ describe("mongo rate limit store", () => {
10
+ beforeEach(async () => {
11
+ await setupTestData();
12
+ const db = mongoose.connection.db;
13
+ if (db) {
14
+ await db.collection(RATE_LIMIT_HITS_COLLECTION).deleteMany({});
15
+ }
16
+ });
17
+
18
+ it("isolates keys and resets after the window", async () => {
19
+ const store = createRateLimitStore({store: "mongo"});
20
+ const t0 = 1_000_000;
21
+ const a1 = await store.consume({key: "a", max: 2, now: t0, windowMs: 1000});
22
+ const a2 = await store.consume({key: "a", max: 2, now: t0 + 10, windowMs: 1000});
23
+ const a3 = await store.consume({key: "a", max: 2, now: t0 + 20, windowMs: 1000});
24
+ const b1 = await store.consume({key: "b", max: 2, now: t0, windowMs: 1000});
25
+ assert.isTrue(a1.allowed);
26
+ assert.isTrue(a2.allowed);
27
+ assert.isFalse(a3.allowed);
28
+ assert.isTrue(b1.allowed);
29
+ const after = await store.consume({key: "a", max: 2, now: t0 + 1001, windowMs: 1000});
30
+ assert.isTrue(after.allowed);
31
+ });
32
+
33
+ it("does not expose rateLimitHits as a modelRouter catalog path", () => {
34
+ const names = mongoose.modelNames();
35
+ assert.notInclude(names, RATE_LIMIT_HITS_COLLECTION);
36
+ assert.notInclude(names, "RateLimitHits");
37
+ });
38
+
39
+ it("creates a TTL index on expiresAt", async () => {
40
+ const store = createMongoRateLimitStore();
41
+ await store.consume({key: "idx", max: 1, now: 1, windowMs: 1000});
42
+ const db = mongoose.connection.db;
43
+ assert.ok(db);
44
+ const indexes = await db.collection(RATE_LIMIT_HITS_COLLECTION).indexes();
45
+ const ttl = indexes.find((index) => index.key.expiresAt === 1);
46
+ assert.ok(ttl);
47
+ assert.equal(ttl.expireAfterSeconds, 0);
48
+ });
49
+
50
+ it("throws APIError when mongoose has no open db", async () => {
51
+ const store = createMongoRateLimitStore();
52
+ const connection = mongoose.connection as {db?: unknown};
53
+ const previous = connection.db;
54
+ Object.defineProperty(mongoose.connection, "db", {
55
+ configurable: true,
56
+ value: undefined,
57
+ });
58
+ try {
59
+ await store.consume({key: "none", max: 1, now: 1, windowMs: 1000});
60
+ assert.fail("expected missing mongoose db to throw");
61
+ } catch (error) {
62
+ assert.include(String(error), "open mongoose connection");
63
+ } finally {
64
+ Object.defineProperty(mongoose.connection, "db", {
65
+ configurable: true,
66
+ value: previous,
67
+ });
68
+ }
69
+ });
70
+
71
+ it("does not allow more than max under concurrent consumes", async () => {
72
+ const store = createMongoRateLimitStore();
73
+ const now = 9_000_000;
74
+ const results = await Promise.all(
75
+ Array.from({length: 20}, () => store.consume({key: "burst", max: 5, now, windowMs: 60_000}))
76
+ );
77
+ const allowed = results.filter((result) => result.allowed).length;
78
+ assert.equal(allowed, 5);
79
+ });
80
+ });
@@ -0,0 +1,77 @@
1
+ import {DateTime} from "luxon";
2
+ import mongoose from "mongoose";
3
+
4
+ import {APIError} from "../errors";
5
+ import type {RateLimitConsumeArgs, RateLimitConsumeResult, RateLimitStore} from "./types";
6
+
7
+ /** @internal */
8
+ export const RATE_LIMIT_HITS_COLLECTION = "rateLimitHits";
9
+
10
+ const ensureIndexes = async (collection: mongoose.mongo.Collection): Promise<void> => {
11
+ await collection.createIndex({key: 1}, {unique: true});
12
+ await collection.createIndex({expiresAt: 1}, {expireAfterSeconds: 0});
13
+ };
14
+
15
+ export const createMongoRateLimitStore = (): RateLimitStore => {
16
+ let indexed = false;
17
+
18
+ const consume = async ({
19
+ key,
20
+ max,
21
+ windowMs,
22
+ now,
23
+ }: RateLimitConsumeArgs): Promise<RateLimitConsumeResult> => {
24
+ const db = mongoose.connection.db;
25
+ if (!db) {
26
+ throw new APIError({
27
+ status: 500,
28
+ title: "Mongo rate limit store requires an open mongoose connection",
29
+ });
30
+ }
31
+ const collection = db.collection(RATE_LIMIT_HITS_COLLECTION);
32
+ if (!indexed) {
33
+ await ensureIndexes(collection);
34
+ indexed = true;
35
+ }
36
+
37
+ const nowDate = DateTime.fromMillis(now).toJSDate();
38
+ const resetAtDate = DateTime.fromMillis(now + windowMs).toJSDate();
39
+ const updated = await collection.findOneAndUpdate(
40
+ {key},
41
+ [
42
+ {
43
+ $set: {
44
+ expiresAt: {
45
+ $cond: [
46
+ {$and: [{$ne: ["$expiresAt", null]}, {$gt: ["$expiresAt", nowDate]}]},
47
+ "$expiresAt",
48
+ resetAtDate,
49
+ ],
50
+ },
51
+ hits: {
52
+ $cond: [
53
+ {$and: [{$ne: ["$expiresAt", null]}, {$gt: ["$expiresAt", nowDate]}]},
54
+ {$add: [{$ifNull: ["$hits", 0]}, 1]},
55
+ 1,
56
+ ],
57
+ },
58
+ key,
59
+ },
60
+ },
61
+ ],
62
+ {returnDocument: "after", upsert: true}
63
+ );
64
+
65
+ const hits = Number(updated?.hits ?? 1);
66
+ const expiresAt = updated?.expiresAt;
67
+ const resetAt =
68
+ expiresAt != null ? DateTime.fromJSDate(expiresAt as Date).toMillis() : now + windowMs;
69
+ return {
70
+ allowed: hits <= max,
71
+ remaining: Math.max(0, max - hits),
72
+ resetAt,
73
+ };
74
+ };
75
+
76
+ return {consume};
77
+ };