@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
@@ -0,0 +1,130 @@
1
+ import type {Request} from "express";
2
+
3
+ import type {RateLimitPolicyName} from "./types";
4
+
5
+ const DEFAULT_BETTER_AUTH_BASE_PATH = "/api/auth";
6
+
7
+ const stripQueryAndFragment = (url: string): string => {
8
+ const hash = url.indexOf("#");
9
+ const withoutHash = hash === -1 ? url : url.slice(0, hash);
10
+ const q = withoutHash.indexOf("?");
11
+ return q === -1 ? withoutHash : withoutHash.slice(0, q);
12
+ };
13
+
14
+ /** Strip query, fragment, and a trailing slash so `/auth/login/` matches `/auth/login`. */
15
+ const normalizeRequestPath = (url: string): string => {
16
+ const withoutQuery = stripQueryAndFragment(url);
17
+ const withoutSlash =
18
+ withoutQuery.length > 1 && withoutQuery.endsWith("/")
19
+ ? withoutQuery.slice(0, -1)
20
+ : withoutQuery;
21
+ return withoutSlash.toLowerCase();
22
+ };
23
+
24
+ /** Prefer Express `req.path` (routing) over the raw request-target. */
25
+ const requestPath = (req: Request): string => {
26
+ const raw = req.path || req.url || req.originalUrl || "";
27
+ return normalizeRequestPath(raw);
28
+ };
29
+
30
+ const JWT_CREDENTIAL_EXCHANGE_EXACT = new Set([
31
+ "/auth/login",
32
+ "/auth/signup",
33
+ "/auth/refresh_token",
34
+ "/auth/forgotpassword",
35
+ "/auth/resetpassword",
36
+ "/resetpassword",
37
+ "/auth/verifyemail",
38
+ ]);
39
+
40
+ /**
41
+ * JWT login, signup, and refresh must not 401 on a stale access token.
42
+ * `setupAuth` runs before those routes so the client can still exchange credentials.
43
+ */
44
+ export const isJwtCredentialExchangePath = (req: Request): boolean => {
45
+ return JWT_CREDENTIAL_EXCHANGE_EXACT.has(requestPath(req));
46
+ };
47
+
48
+ export const shouldSkipRateLimit = (
49
+ req: Request,
50
+ extraSkip?: (req: Request) => boolean
51
+ ): boolean => {
52
+ const path = requestPath(req);
53
+ if (req.method === "GET" && (path === "/health" || path === "/healthz")) {
54
+ return true;
55
+ }
56
+ if (path === "/openapi.json" || path.startsWith("/openapi.json")) {
57
+ return true;
58
+ }
59
+ if (path === "/swagger" || path.startsWith("/swagger/")) {
60
+ return true;
61
+ }
62
+ if (extraSkip?.(req)) {
63
+ return true;
64
+ }
65
+ return false;
66
+ };
67
+
68
+ // `requestPath` lowercases, so camelCase routes live here as lowercase.
69
+ const AUTH_EXACT = new Set([
70
+ "/auth/login",
71
+ "/auth/signup",
72
+ "/auth/refresh_token",
73
+ "/auth/forgotpassword",
74
+ "/auth/resetpassword",
75
+ "/resetpassword",
76
+ "/auth/sendverification",
77
+ "/auth/verifyemail",
78
+ "/auth/github",
79
+ "/auth/github/callback",
80
+ "/auth/github/failure",
81
+ ]);
82
+
83
+ const AUTH_PREFIXES = ["/auth/github/"];
84
+
85
+ const betterAuthAuthPrefixes = (basePath: string): string[] => {
86
+ const trimmed = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
87
+ const base = trimmed.toLowerCase();
88
+ return [
89
+ `${base}/sign-in`,
90
+ `${base}/sign-up`,
91
+ `${base}/forget-password`,
92
+ `${base}/request-password-reset`,
93
+ `${base}/reset-password`,
94
+ `${base}/send-verification-email`,
95
+ `${base}/verify-email`,
96
+ `${base}/callback`,
97
+ ];
98
+ };
99
+
100
+ export const classifyRateLimitPolicy = (
101
+ req: Request,
102
+ betterAuthBasePath = DEFAULT_BETTER_AUTH_BASE_PATH
103
+ ): RateLimitPolicyName => {
104
+ const path = requestPath(req);
105
+ if (AUTH_EXACT.has(path)) {
106
+ return "auth";
107
+ }
108
+ for (const prefix of AUTH_PREFIXES) {
109
+ if (path.startsWith(prefix)) {
110
+ return "auth";
111
+ }
112
+ }
113
+ for (const prefix of betterAuthAuthPrefixes(betterAuthBasePath)) {
114
+ if (path === prefix || path.startsWith(`${prefix}/`)) {
115
+ return "auth";
116
+ }
117
+ }
118
+ return "api";
119
+ };
120
+
121
+ export const rateLimitKey = (req: Request, policy: RateLimitPolicyName): string => {
122
+ if (policy !== "auth") {
123
+ const user = req.user as {_id?: unknown; id?: string} | undefined;
124
+ const userId = user?.id ?? (user?._id != null ? String(user._id) : undefined);
125
+ if (userId) {
126
+ return `user:${userId}`;
127
+ }
128
+ }
129
+ return `ip:${req.ip || req.socket?.remoteAddress || "unknown"}`;
130
+ };
@@ -0,0 +1,328 @@
1
+ import {beforeEach, describe, it} from "bun:test";
2
+ import {assert} from "chai";
3
+ import type {Application} from "express";
4
+ import express from "express";
5
+ import jwt from "jsonwebtoken";
6
+ import {DateTime} from "luxon";
7
+ import supertest from "supertest";
8
+
9
+ import {modelRouter} from "../api";
10
+ import type {UserModel as AuthUserModel} from "../auth";
11
+ import {Permissions} from "../permissions";
12
+ import {TerrenoApp} from "../terrenoApp";
13
+ import {FoodModel, setupTestData, UserModel} from "../tests";
14
+ import {applyRateLimitTrustProxy} from "./applyTrustProxy";
15
+ import {createRateLimitStore} from "./createStore";
16
+ import {createMemoryRateLimitStore} from "./memoryStore";
17
+ import {classifyRateLimitPolicy, rateLimitKey, shouldSkipRateLimit} from "./policies";
18
+ import {DEFAULT_API_MAX, DEFAULT_AUTH_MAX, type RateLimitOptions} from "./types";
19
+
20
+ const foodRouter = modelRouter("/food", FoodModel, {
21
+ allowAnonymous: true,
22
+ permissions: {
23
+ create: [Permissions.IsAuthenticated],
24
+ delete: [],
25
+ list: [Permissions.IsAny],
26
+ read: [Permissions.IsAny],
27
+ update: [],
28
+ },
29
+ });
30
+
31
+ const buildApp = (rateLimit?: RateLimitOptions): Application => {
32
+ return new TerrenoApp({
33
+ configureApp: (app) => {
34
+ app.get("/health", (_req, res) => {
35
+ res.json({ok: true});
36
+ });
37
+ },
38
+ logRequests: false,
39
+ rateLimit,
40
+ skipListen: true,
41
+ userModel: UserModel as unknown as AuthUserModel,
42
+ })
43
+ .register(foodRouter)
44
+ .start();
45
+ };
46
+
47
+ describe("HTTP rate limiting", () => {
48
+ beforeEach(async () => {
49
+ await setupTestData();
50
+ });
51
+
52
+ it("does not 429 burst logins when rateLimit is omitted", async () => {
53
+ const app = buildApp();
54
+ for (let i = 0; i < 25; i++) {
55
+ const res = await supertest(app)
56
+ .post("/auth/login")
57
+ .send({email: "notAdmin@example.com", password: "password"});
58
+ assert.equal(res.status, 200, `login ${i} should succeed without a limiter`);
59
+ }
60
+ }, 30_000);
61
+
62
+ it("returns 429 on the 21st POST /auth/login with default auth max", async () => {
63
+ const app = buildApp({});
64
+ for (let i = 0; i < DEFAULT_AUTH_MAX; i++) {
65
+ const res = await supertest(app)
66
+ .post("/auth/login")
67
+ .send({email: "notAdmin@example.com", password: "password"});
68
+ assert.equal(res.status, 200, `login ${i} should be under the auth cap`);
69
+ }
70
+ const limited = await supertest(app)
71
+ .post("/auth/login")
72
+ .send({email: "notAdmin@example.com", password: "password"});
73
+ assert.equal(limited.status, 429);
74
+ assert.equal(limited.body.code, "rate-limit-exceeded");
75
+ assert.equal(limited.body.title, "Too many requests");
76
+ assert.equal(limited.body.status, 429);
77
+ assert.isString(limited.headers["retry-after"]);
78
+ assert.include(limited.headers.ratelimit, "limit=20");
79
+ assert.include(limited.headers["ratelimit-policy"], "20;w=");
80
+
81
+ const list = await supertest(app).get("/food");
82
+ assert.equal(list.status, 200, "api bucket still has remaining after auth cap");
83
+ }, 30_000);
84
+
85
+ it("returns 429 on the request after apiMax on modelRouter list", async () => {
86
+ const app = buildApp({limits: {apiMax: 3, authMax: 20}});
87
+ for (let i = 0; i < 3; i++) {
88
+ const res = await supertest(app).get("/food");
89
+ assert.equal(res.status, 200, `list ${i} should be under apiMax`);
90
+ }
91
+ const limited = await supertest(app).get("/food");
92
+ assert.equal(limited.status, 429);
93
+ assert.include(limited.headers.ratelimit, "limit=3");
94
+ });
95
+
96
+ it("never rate-limits GET /health", async () => {
97
+ const app = buildApp({limits: {apiMax: 1, authMax: 1}});
98
+ const first = await supertest(app).get("/health");
99
+ assert.equal(first.status, 200);
100
+ const second = await supertest(app).get("/health");
101
+ assert.equal(second.status, 200);
102
+ });
103
+
104
+ it("defaults api max to 600 and denies the 601st consume", async () => {
105
+ const store = createMemoryRateLimitStore();
106
+ const now = 5_000_000;
107
+ for (let i = 0; i < DEFAULT_API_MAX; i++) {
108
+ const result = await store.consume({
109
+ key: "api:ip:1",
110
+ max: DEFAULT_API_MAX,
111
+ now,
112
+ windowMs: 60_000,
113
+ });
114
+ assert.isTrue(result.allowed);
115
+ }
116
+ const over = await store.consume({
117
+ key: "api:ip:1",
118
+ max: DEFAULT_API_MAX,
119
+ now: now + 1,
120
+ windowMs: 60_000,
121
+ });
122
+ assert.isFalse(over.allowed);
123
+ });
124
+
125
+ it("classifies login as auth and /auth/me as api", () => {
126
+ const authPaths = [
127
+ "/auth/login",
128
+ "/auth/login/",
129
+ "/Auth/login",
130
+ "/auth/signup",
131
+ "/auth/refresh_token",
132
+ "/auth/forgotPassword",
133
+ "/auth/resetPassword",
134
+ "/resetPassword",
135
+ "/auth/sendVerification",
136
+ "/auth/verifyEmail",
137
+ "/auth/github",
138
+ "/auth/github/callback",
139
+ "/auth/github/failure",
140
+ "/api/auth/sign-in/email",
141
+ "/api/auth/sign-up/email",
142
+ "/api/auth/forget-password",
143
+ "/api/auth/request-password-reset",
144
+ "/api/auth/reset-password",
145
+ "/api/auth/send-verification-email",
146
+ "/api/auth/verify-email?token=secret",
147
+ "/api/auth/callback/github",
148
+ ];
149
+ for (const originalUrl of authPaths) {
150
+ assert.equal(
151
+ classifyRateLimitPolicy({method: "POST", originalUrl} as never),
152
+ "auth",
153
+ originalUrl
154
+ );
155
+ }
156
+ assert.equal(classifyRateLimitPolicy({method: "GET", originalUrl: "/auth/me"} as never), "api");
157
+ assert.equal(
158
+ classifyRateLimitPolicy({method: "PATCH", originalUrl: "/auth/me"} as never),
159
+ "api"
160
+ );
161
+ assert.equal(
162
+ classifyRateLimitPolicy({method: "POST", originalUrl: "/sync/mutate"} as never),
163
+ "api"
164
+ );
165
+ assert.equal(
166
+ classifyRateLimitPolicy({
167
+ method: "POST",
168
+ originalUrl: "/auth/login#x",
169
+ path: "/auth/login",
170
+ } as never),
171
+ "auth"
172
+ );
173
+ assert.equal(
174
+ classifyRateLimitPolicy({
175
+ method: "POST",
176
+ originalUrl: "http://host/auth/login",
177
+ path: "/auth/login",
178
+ } as never),
179
+ "auth"
180
+ );
181
+ assert.equal(
182
+ classifyRateLimitPolicy(
183
+ {method: "POST", originalUrl: "/custom/auth/sign-in"} as never,
184
+ "/custom/auth"
185
+ ),
186
+ "auth"
187
+ );
188
+ assert.equal(
189
+ rateLimitKey({ip: "203.0.113.10", user: {id: "session-user"}} as never, "auth"),
190
+ "ip:203.0.113.10"
191
+ );
192
+ assert.equal(
193
+ rateLimitKey({ip: "203.0.113.10", user: {id: "session-user"}} as never, "api"),
194
+ "user:session-user"
195
+ );
196
+ assert.isTrue(shouldSkipRateLimit({method: "GET", originalUrl: "/openapi.json"} as never));
197
+ assert.isTrue(shouldSkipRateLimit({method: "GET", originalUrl: "/swagger"} as never));
198
+ assert.isTrue(
199
+ shouldSkipRateLimit({method: "GET", originalUrl: "/food"} as never, (req) =>
200
+ req.originalUrl.startsWith("/food")
201
+ )
202
+ );
203
+ });
204
+
205
+ it("honors rateLimit.skip for extra paths", async () => {
206
+ const app = buildApp({
207
+ limits: {apiMax: 1, authMax: 1},
208
+ skip: (req) => req.path === "/food" || req.originalUrl.startsWith("/food"),
209
+ });
210
+ const first = await supertest(app).get("/food");
211
+ assert.equal(first.status, 200);
212
+ const second = await supertest(app).get("/food");
213
+ assert.equal(second.status, 200);
214
+ });
215
+
216
+ it("keys unauthenticated traffic by X-Forwarded-For when trustProxy is 1", async () => {
217
+ const app = buildApp({limits: {apiMax: 1, authMax: 20}, trustProxy: 1});
218
+ const first = await supertest(app).get("/food").set("X-Forwarded-For", "203.0.113.10");
219
+ assert.equal(first.status, 200);
220
+ const sameClient = await supertest(app).get("/food").set("X-Forwarded-For", "203.0.113.10");
221
+ assert.equal(sameClient.status, 429);
222
+ const otherClient = await supertest(app).get("/food").set("X-Forwarded-For", "198.51.100.20");
223
+ assert.equal(otherClient.status, 200);
224
+ });
225
+
226
+ it("ignores spoofed X-Forwarded-For when trustProxy is omitted", async () => {
227
+ const app = buildApp({limits: {apiMax: 1, authMax: 20}});
228
+ const first = await supertest(app).get("/food").set("X-Forwarded-For", "203.0.113.10");
229
+ assert.equal(first.status, 200);
230
+ const spoofed = await supertest(app).get("/food").set("X-Forwarded-For", "198.51.100.20");
231
+ assert.equal(spoofed.status, 429);
232
+ });
233
+
234
+ it("logs in and refreshes when the access JWT is expired", async () => {
235
+ const app = buildApp({});
236
+ const secret = process.env.TOKEN_SECRET;
237
+ assert.ok(secret);
238
+ const expired = jwt.sign(
239
+ {
240
+ exp: Math.floor(DateTime.now().minus({hours: 1}).toSeconds()),
241
+ id: "stale",
242
+ },
243
+ secret,
244
+ {issuer: process.env.TOKEN_ISSUER}
245
+ );
246
+ const login = await supertest(app)
247
+ .post("/auth/login")
248
+ .set("Authorization", `Bearer ${expired}`)
249
+ .send({email: "notAdmin@example.com", password: "password"});
250
+ assert.equal(login.status, 200);
251
+ assert.isString(login.body.data.refreshToken);
252
+ const refresh = await supertest(app)
253
+ .post("/auth/refresh_token")
254
+ .set("Authorization", `Bearer ${expired}`)
255
+ .send({refreshToken: login.body.data.refreshToken});
256
+ assert.equal(refresh.status, 200);
257
+ const me = await supertest(app).get("/auth/me").set("Authorization", `Bearer ${expired}`);
258
+ assert.equal(me.status, 401);
259
+ });
260
+
261
+ it("keys authenticated JWT traffic by user, not shared IP", async () => {
262
+ const app = buildApp({limits: {apiMax: 1, authMax: 20}});
263
+ const userLogin = await supertest(app)
264
+ .post("/auth/login")
265
+ .send({email: "notAdmin@example.com", password: "password"});
266
+ assert.equal(userLogin.status, 200);
267
+ const adminLogin = await supertest(app)
268
+ .post("/auth/login")
269
+ .send({email: "admin@example.com", password: "securePassword"});
270
+ assert.equal(adminLogin.status, 200);
271
+ const userList = await supertest(app)
272
+ .get("/food")
273
+ .set("Authorization", `Bearer ${userLogin.body.data.token}`);
274
+ assert.equal(userList.status, 200);
275
+ const adminList = await supertest(app)
276
+ .get("/food")
277
+ .set("Authorization", `Bearer ${adminLogin.body.data.token}`);
278
+ assert.equal(adminList.status, 200, "second user should have a separate api bucket");
279
+ });
280
+
281
+ it("rejects an unknown store name at create time", () => {
282
+ try {
283
+ createRateLimitStore({store: "disk" as never});
284
+ assert.fail("expected unknown store to throw");
285
+ } catch (error) {
286
+ assert.include(String(error), "Unknown rate limit store");
287
+ }
288
+ });
289
+ });
290
+
291
+ describe("memory rate limit store", () => {
292
+ it("isolates keys and resets after the window", async () => {
293
+ const store = createMemoryRateLimitStore();
294
+ const t0 = 1_000_000;
295
+ const a1 = await store.consume({key: "a", max: 2, now: t0, windowMs: 1000});
296
+ const a2 = await store.consume({key: "a", max: 2, now: t0 + 10, windowMs: 1000});
297
+ const a3 = await store.consume({key: "a", max: 2, now: t0 + 20, windowMs: 1000});
298
+ const b1 = await store.consume({key: "b", max: 2, now: t0, windowMs: 1000});
299
+ assert.isTrue(a1.allowed);
300
+ assert.isTrue(a2.allowed);
301
+ assert.isFalse(a3.allowed);
302
+ assert.isTrue(b1.allowed);
303
+ const after = await store.consume({key: "a", max: 2, now: t0 + 1001, windowMs: 1000});
304
+ assert.isTrue(after.allowed);
305
+ });
306
+
307
+ it("prunes expired windows when the map grows past 10_000 keys", async () => {
308
+ const store = createMemoryRateLimitStore();
309
+ const now = 1_000;
310
+ for (let i = 0; i < 10_001; i++) {
311
+ await store.consume({key: `k${i}`, max: 1, now, windowMs: 1});
312
+ }
313
+ const next = await store.consume({key: "fresh", max: 1, now: now + 10, windowMs: 1000});
314
+ assert.isTrue(next.allowed);
315
+ });
316
+ });
317
+
318
+ describe("applyRateLimitTrustProxy", () => {
319
+ it("defaults to false and honors hop count", () => {
320
+ const app = express();
321
+ applyRateLimitTrustProxy(app, {});
322
+ assert.equal(app.get("trust proxy"), false);
323
+ applyRateLimitTrustProxy(app, {trustProxy: false});
324
+ assert.equal(app.get("trust proxy"), false);
325
+ applyRateLimitTrustProxy(app, {trustProxy: 2});
326
+ assert.equal(app.get("trust proxy"), 2);
327
+ });
328
+ });
@@ -0,0 +1,29 @@
1
+ import {beforeAll, describe, it, mock} from "bun:test";
2
+ import {assert} from "chai";
3
+
4
+ mock.module("ioredis", () => {
5
+ class Redis {
6
+ incr = async (_key: string): Promise<number> => 1;
7
+ pexpire = async (_key: string, _milliseconds: number): Promise<number> => 1;
8
+ pttl = async (_key: string): Promise<number> => 5_000;
9
+ }
10
+ return {default: Redis};
11
+ });
12
+
13
+ const {createRedisRateLimitStore} = await import("./redisStore");
14
+
15
+ describe("redis rate limit store ioredis loader", () => {
16
+ beforeAll(() => {
17
+ process.env.REDIS_URL = "redis://127.0.0.1:6379";
18
+ Reflect.deleteProperty(process.env, "VALKEY_URL");
19
+ });
20
+
21
+ it("consumes using a dynamically imported ioredis client", async () => {
22
+ const store = createRedisRateLimitStore();
23
+ const first = await store.consume({key: "dyn", max: 5, now: 1, windowMs: 15_000});
24
+ const second = await store.consume({key: "dyn", max: 5, now: 2, windowMs: 15_000});
25
+ assert.isTrue(first.allowed);
26
+ assert.isTrue(second.allowed);
27
+ assert.equal(first.resetAt, 1 + 5_000);
28
+ });
29
+ });
@@ -0,0 +1,114 @@
1
+ import {describe, it} from "bun:test";
2
+ import {assert} from "chai";
3
+
4
+ import {APIError} from "../errors";
5
+ import {createRateLimitStore} from "./createStore";
6
+ import {createRedisRateLimitStore, redisUrlFromEnv} from "./redisStore";
7
+ import type {RateLimitRedisClient} from "./types";
8
+
9
+ const createFakeRedis = (): RateLimitRedisClient & {reset: () => void} => {
10
+ const counts = new Map<string, number>();
11
+ const expiresAt = new Map<string, number>();
12
+ const now = (): number => Date.now();
13
+
14
+ const isExpired = (key: string): boolean => {
15
+ const exp = expiresAt.get(key);
16
+ return exp !== undefined && exp <= now();
17
+ };
18
+
19
+ const client: RateLimitRedisClient & {reset: () => void} = {
20
+ incr: async (key: string): Promise<number> => {
21
+ if (isExpired(key)) {
22
+ counts.delete(key);
23
+ expiresAt.delete(key);
24
+ }
25
+ const next = (counts.get(key) ?? 0) + 1;
26
+ counts.set(key, next);
27
+ return next;
28
+ },
29
+ pExpire: async (key: string, milliseconds: number): Promise<unknown> => {
30
+ expiresAt.set(key, now() + milliseconds);
31
+ return 1;
32
+ },
33
+ pTTL: async (key: string): Promise<number> => {
34
+ if (!counts.has(key) || isExpired(key)) {
35
+ return -2;
36
+ }
37
+ const exp = expiresAt.get(key);
38
+ if (exp === undefined) {
39
+ return -1;
40
+ }
41
+ return Math.max(0, exp - now());
42
+ },
43
+ reset: (): void => {
44
+ counts.clear();
45
+ expiresAt.clear();
46
+ },
47
+ };
48
+ return client;
49
+ };
50
+
51
+ describe("redis rate limit store", () => {
52
+ it("throws APIError when store is redis and no URL or client is set", () => {
53
+ Reflect.deleteProperty(process.env, "VALKEY_URL");
54
+ Reflect.deleteProperty(process.env, "REDIS_URL");
55
+ try {
56
+ createRedisRateLimitStore();
57
+ assert.fail("expected missing Redis URL to throw");
58
+ } catch (error) {
59
+ assert.instanceOf(error, APIError);
60
+ assert.include(String(error), "VALKEY_URL or REDIS_URL");
61
+ }
62
+ try {
63
+ createRateLimitStore({store: "redis"});
64
+ assert.fail("expected createRateLimitStore redis without URL to throw");
65
+ } catch (error) {
66
+ assert.include(String(error), "VALKEY_URL or REDIS_URL");
67
+ }
68
+ });
69
+
70
+ it("prefers VALKEY_URL over REDIS_URL", () => {
71
+ process.env.REDIS_URL = "redis://redis-only";
72
+ process.env.VALKEY_URL = "redis://valkey-wins";
73
+ assert.equal(redisUrlFromEnv(), "redis://valkey-wins");
74
+ Reflect.deleteProperty(process.env, "VALKEY_URL");
75
+ assert.equal(redisUrlFromEnv(), "redis://redis-only");
76
+ Reflect.deleteProperty(process.env, "REDIS_URL");
77
+ });
78
+
79
+ it("matches the memory consume contract with an injected client", async () => {
80
+ Reflect.deleteProperty(process.env, "VALKEY_URL");
81
+ Reflect.deleteProperty(process.env, "REDIS_URL");
82
+ const redisClient = createFakeRedis();
83
+ const store = createRateLimitStore({redisClient, store: "redis"});
84
+ const t0 = 2_000_000;
85
+ const a1 = await store.consume({key: "a", max: 2, now: t0, windowMs: 60_000});
86
+ const a2 = await store.consume({key: "a", max: 2, now: t0 + 10, windowMs: 60_000});
87
+ const a3 = await store.consume({key: "a", max: 2, now: t0 + 20, windowMs: 60_000});
88
+ const b1 = await store.consume({key: "b", max: 2, now: t0, windowMs: 60_000});
89
+ assert.isTrue(a1.allowed);
90
+ assert.isTrue(a2.allowed);
91
+ assert.isFalse(a3.allowed);
92
+ assert.isTrue(b1.allowed);
93
+ assert.equal(a3.remaining, 0);
94
+ });
95
+
96
+ it("re-sets expiry when Redis reports no TTL", async () => {
97
+ Reflect.deleteProperty(process.env, "VALKEY_URL");
98
+ Reflect.deleteProperty(process.env, "REDIS_URL");
99
+ const redisClient: RateLimitRedisClient = {
100
+ incr: async () => 2,
101
+ pExpire: async () => 1,
102
+ pTTL: async () => -1,
103
+ };
104
+ const store = createRedisRateLimitStore({redisClient});
105
+ const result = await store.consume({
106
+ key: "a",
107
+ max: 5,
108
+ now: 1_000,
109
+ windowMs: 15_000,
110
+ });
111
+ assert.isTrue(result.allowed);
112
+ assert.equal(result.resetAt, 1_000 + 15_000);
113
+ });
114
+ });
@@ -0,0 +1,86 @@
1
+ import {APIError} from "../errors";
2
+ import type {
3
+ RateLimitConsumeArgs,
4
+ RateLimitConsumeResult,
5
+ RateLimitOptions,
6
+ RateLimitRedisClient,
7
+ RateLimitStore,
8
+ } from "./types";
9
+
10
+ /** @internal */
11
+ export const redisUrlFromEnv = (): string | undefined => {
12
+ return process.env.VALKEY_URL || process.env.REDIS_URL;
13
+ };
14
+
15
+ interface IoredisClient {
16
+ incr: (key: string) => Promise<number>;
17
+ pexpire: (key: string, milliseconds: number) => Promise<number>;
18
+ pttl: (key: string) => Promise<number>;
19
+ }
20
+
21
+ interface IoredisModule {
22
+ default: new (url: string) => IoredisClient;
23
+ }
24
+
25
+ const connectIoredis = async (url: string): Promise<RateLimitRedisClient> => {
26
+ const loaded = (await import("ioredis").catch(() => null)) as IoredisModule | null;
27
+ if (!loaded?.default) {
28
+ throw new APIError({
29
+ status: 500,
30
+ title: "Redis rate limit store requires the ioredis package",
31
+ });
32
+ }
33
+ const Redis = loaded.default;
34
+ const client = new Redis(url);
35
+ return {
36
+ incr: (key: string) => client.incr(key),
37
+ pExpire: (key: string, milliseconds: number) => client.pexpire(key, milliseconds),
38
+ pTTL: (key: string) => client.pttl(key),
39
+ };
40
+ };
41
+
42
+ export const createRedisRateLimitStore = (options: RateLimitOptions = {}): RateLimitStore => {
43
+ const url = redisUrlFromEnv();
44
+ if (!options.redisClient && !url) {
45
+ throw new APIError({
46
+ status: 500,
47
+ title: "Redis rate limit store requires VALKEY_URL or REDIS_URL",
48
+ });
49
+ }
50
+
51
+ let clientPromise: Promise<RateLimitRedisClient> | undefined;
52
+
53
+ const getClient = (): Promise<RateLimitRedisClient> => {
54
+ if (options.redisClient) {
55
+ return Promise.resolve(options.redisClient);
56
+ }
57
+ if (!clientPromise) {
58
+ clientPromise = connectIoredis(url as string);
59
+ }
60
+ return clientPromise;
61
+ };
62
+
63
+ const consume = async ({
64
+ key,
65
+ max,
66
+ windowMs,
67
+ now,
68
+ }: RateLimitConsumeArgs): Promise<RateLimitConsumeResult> => {
69
+ const client = await getClient();
70
+ const redisKey = `terreno:rate-limit:${key}`;
71
+ const count = await client.incr(redisKey);
72
+ if (count === 1) {
73
+ await client.pExpire(redisKey, windowMs);
74
+ }
75
+ let ttl = await client.pTTL(redisKey);
76
+ if (ttl < 0) {
77
+ await client.pExpire(redisKey, windowMs);
78
+ ttl = windowMs;
79
+ }
80
+ const resetAt = now + ttl;
81
+ const allowed = count <= max;
82
+ return {allowed, remaining: Math.max(0, max - count), resetAt};
83
+ };
84
+
85
+ return {consume};
86
+ };