@terreno/api 57.1.0 → 57.3.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 (283) hide show
  1. package/README.md +17 -7
  2. package/dist/actions.js +19 -7
  3. package/dist/adminTypes.d.ts +26 -0
  4. package/dist/api.d.ts +4 -0
  5. package/dist/api.js +12 -24
  6. package/dist/auth.d.ts +23 -10
  7. package/dist/auth.js +97 -32
  8. package/dist/authRecovery.d.ts +5 -0
  9. package/dist/authRecovery.js +350 -0
  10. package/dist/authTokens.d.ts +8 -0
  11. package/dist/authTokens.js +162 -0
  12. package/dist/betterAuth.d.ts +33 -0
  13. package/dist/betterAuthApp.d.ts +4 -0
  14. package/dist/betterAuthApp.js +26 -8
  15. package/dist/betterAuthSetup.d.ts +44 -2
  16. package/dist/betterAuthSetup.js +288 -18
  17. package/dist/collectionRegistry.d.ts +38 -0
  18. package/dist/collectionRegistry.js +72 -0
  19. package/dist/configurationApp.d.ts +11 -2
  20. package/dist/configurationApp.js +2 -4
  21. package/dist/docLoader.js +35 -6
  22. package/dist/expressServer.d.ts +26 -3
  23. package/dist/expressServer.js +79 -11
  24. package/dist/index.d.ts +16 -0
  25. package/dist/index.js +38 -2
  26. package/dist/mcp/auth.d.ts +1 -0
  27. package/dist/mcp/auth.js +47 -25
  28. package/dist/mcp/handlers.d.ts +1 -1
  29. package/dist/mcp/handlers.js +67 -233
  30. package/dist/mcp/query.d.ts +2 -2
  31. package/dist/mcp/registry.d.ts +1 -5
  32. package/dist/mcp/registry.js +31 -20
  33. package/dist/mcp/schemaGenerator.d.ts +2 -7
  34. package/dist/mcp/schemaGenerator.js +41 -116
  35. package/dist/mcp/server.d.ts +1 -0
  36. package/dist/mcp/server.js +1 -0
  37. package/dist/mcp/serviceTokens.d.ts +16 -0
  38. package/dist/mcp/serviceTokens.js +345 -0
  39. package/dist/mcp/types.d.ts +2 -2
  40. package/dist/models/mcpServiceToken.d.ts +3 -0
  41. package/dist/models/mcpServiceToken.js +208 -0
  42. package/dist/openApiBuilder.d.ts +5 -4
  43. package/dist/openApiBuilder.js +61 -8
  44. package/dist/openApiCompat.js +1 -1
  45. package/dist/openApiValidator.js +0 -2
  46. package/dist/plugins.d.ts +14 -1
  47. package/dist/plugins.js +17 -6
  48. package/dist/populate.d.ts +2 -2
  49. package/dist/populate.js +47 -42
  50. package/dist/rateLimit/applyTrustProxy.d.ts +3 -0
  51. package/dist/rateLimit/applyTrustProxy.js +17 -0
  52. package/dist/rateLimit/createStore.d.ts +2 -0
  53. package/dist/rateLimit/createStore.js +28 -0
  54. package/dist/rateLimit/memoryStore.d.ts +2 -0
  55. package/dist/rateLimit/memoryStore.js +108 -0
  56. package/dist/rateLimit/middleware.d.ts +11 -0
  57. package/dist/rateLimit/middleware.js +110 -0
  58. package/dist/rateLimit/mongoStore.d.ts +3 -0
  59. package/dist/rateLimit/mongoStore.js +122 -0
  60. package/dist/rateLimit/policies.d.ts +14 -0
  61. package/dist/rateLimit/policies.js +151 -0
  62. package/dist/rateLimit/redisStore.d.ts +3 -0
  63. package/dist/rateLimit/redisStore.js +155 -0
  64. package/dist/rateLimit/types.d.ts +54 -0
  65. package/dist/rateLimit/types.js +9 -0
  66. package/dist/rbac/access.js +5 -1
  67. package/dist/rbac/assertAllowed.d.ts +9 -0
  68. package/dist/rbac/assertAllowed.js +182 -0
  69. package/dist/rbac/modelRouterAccess.d.ts +1 -0
  70. package/dist/rbac/modelRouterAccess.js +8 -4
  71. package/dist/rbac/permissionUtils.js +3 -2
  72. package/dist/rbac/resolve.js +5 -4
  73. package/dist/rbac/routes.js +15 -6
  74. package/dist/rbac/statements.d.ts +10 -0
  75. package/dist/rbac/statements.js +13 -2
  76. package/dist/realtime/deprecation.d.ts +12 -0
  77. package/dist/realtime/deprecation.js +32 -0
  78. package/dist/realtime/realtimeApp.d.ts +1 -1
  79. package/dist/realtime/realtimeApp.js +10 -11
  80. package/dist/realtime/registry.d.ts +0 -31
  81. package/dist/realtime/registry.js +44 -31
  82. package/dist/realtime/socketAuth.d.ts +5 -5
  83. package/dist/realtime/socketAuth.js +11 -1
  84. package/dist/realtime/socketUser.d.ts +5 -1
  85. package/dist/realtime/types.d.ts +14 -4
  86. package/dist/schemaMetadata.d.ts +56 -0
  87. package/dist/schemaMetadata.js +513 -0
  88. package/dist/seedRunner.d.ts +88 -0
  89. package/dist/seedRunner.js +627 -0
  90. package/dist/sync/executors.d.ts +12 -2
  91. package/dist/sync/executors.js +8 -10
  92. package/dist/sync/loadHarness.js +28 -19
  93. package/dist/sync/models.js +26 -24
  94. package/dist/sync/mutationHandler.d.ts +9 -0
  95. package/dist/sync/mutationHandler.js +11 -6
  96. package/dist/sync/registrationSideEffects.d.ts +35 -0
  97. package/dist/sync/registrationSideEffects.js +151 -0
  98. package/dist/sync/registry.d.ts +2 -52
  99. package/dist/sync/registry.js +38 -187
  100. package/dist/sync/routes.js +3 -2
  101. package/dist/sync/scripts/compactTombstones.js +0 -2
  102. package/dist/sync/syncApp.d.ts +3 -3
  103. package/dist/sync/syncApp.js +4 -4
  104. package/dist/sync/syncBatch.js +3 -2
  105. package/dist/sync/syncSeqPlugin.d.ts +1 -1
  106. package/dist/sync/syncSeqPlugin.js +20 -16
  107. package/dist/terrenoApp.d.ts +19 -5
  108. package/dist/terrenoApp.js +66 -18
  109. package/dist/tests/models.d.ts +2 -0
  110. package/dist/tests/models.js +6 -0
  111. package/dist/types/authToken.d.ts +33 -0
  112. package/dist/types/authToken.js +2 -0
  113. package/dist/types/mcpServiceToken.d.ts +41 -0
  114. package/dist/types/mcpServiceToken.js +2 -0
  115. package/dist/webhooks/headerValue.d.ts +2 -0
  116. package/dist/webhooks/headerValue.js +14 -0
  117. package/dist/webhooks/idempotency/memoryStore.d.ts +10 -0
  118. package/dist/webhooks/idempotency/memoryStore.js +65 -0
  119. package/dist/webhooks/idempotency/mongoStore.d.ts +4 -0
  120. package/dist/webhooks/idempotency/mongoStore.js +150 -0
  121. package/dist/webhooks/idempotency/webhookReceipt.d.ts +62 -0
  122. package/dist/webhooks/idempotency/webhookReceipt.js +39 -0
  123. package/dist/webhooks/rawBody.d.ts +14 -0
  124. package/dist/webhooks/rawBody.js +22 -0
  125. package/dist/webhooks/timingSafeEqual.d.ts +4 -0
  126. package/dist/webhooks/timingSafeEqual.js +17 -0
  127. package/dist/webhooks/verifiers/hmac.d.ts +15 -0
  128. package/dist/webhooks/verifiers/hmac.js +49 -0
  129. package/dist/webhooks/verifiers/sendgrid.d.ts +10 -0
  130. package/dist/webhooks/verifiers/sendgrid.js +56 -0
  131. package/dist/webhooks/verifiers/stripe.d.ts +9 -0
  132. package/dist/webhooks/verifiers/stripe.js +99 -0
  133. package/dist/webhooks/verifiers/twilio.d.ts +9 -0
  134. package/dist/webhooks/verifiers/twilio.js +112 -0
  135. package/dist/webhooks/webhooksApp.d.ts +33 -0
  136. package/dist/webhooks/webhooksApp.js +195 -0
  137. package/package.json +5 -6
  138. package/src/__snapshots__/openApi.test.ts.snap +270 -0
  139. package/src/__snapshots__/openApiBuilder.test.ts.snap +30 -12
  140. package/src/__snapshots__/schemaMetadata.test.ts.snap +197 -0
  141. package/src/actions.ts +20 -13
  142. package/src/adminModelRouter.test.ts +133 -0
  143. package/src/adminTypes.ts +23 -0
  144. package/src/api.arrayOperations.test.ts +43 -31
  145. package/src/api.hooks.test.ts +38 -29
  146. package/src/api.query.test.ts +31 -31
  147. package/src/api.test.ts +95 -96
  148. package/src/api.ts +16 -27
  149. package/src/auth.test.ts +107 -51
  150. package/src/auth.ts +98 -29
  151. package/src/authRecovery.test.ts +281 -0
  152. package/src/authRecovery.ts +279 -0
  153. package/src/authTokens.test.ts +94 -0
  154. package/src/authTokens.ts +118 -0
  155. package/src/authVerification.test.ts +293 -0
  156. package/src/betterAuth.ts +24 -0
  157. package/src/betterAuthApp.test.ts +1 -0
  158. package/src/betterAuthApp.ts +27 -9
  159. package/src/betterAuthSetup.test.ts +568 -38
  160. package/src/betterAuthSetup.ts +260 -5
  161. package/src/collectionRegistry.test.ts +165 -0
  162. package/src/collectionRegistry.ts +115 -0
  163. package/src/configurationApp.ts +13 -7
  164. package/src/docLoader.test.ts +45 -1
  165. package/src/docLoader.ts +37 -6
  166. package/src/express.d.ts +1 -0
  167. package/src/expressServer.test.ts +130 -66
  168. package/src/expressServer.ts +75 -19
  169. package/src/githubAuth.test.ts +60 -55
  170. package/src/index.ts +58 -0
  171. package/src/mcp/auth.test.ts +47 -0
  172. package/src/mcp/auth.ts +32 -11
  173. package/src/mcp/handlers.ts +45 -172
  174. package/src/mcp/integration.test.ts +59 -9
  175. package/src/mcp/query.ts +2 -4
  176. package/src/mcp/registry.ts +29 -20
  177. package/src/mcp/schemaGenerator.test.ts +8 -0
  178. package/src/mcp/schemaGenerator.ts +49 -131
  179. package/src/mcp/server.ts +2 -0
  180. package/src/mcp/serviceTokens.test.ts +330 -0
  181. package/src/mcp/serviceTokens.ts +307 -0
  182. package/src/mcp/toolGenerator.test.ts +1 -1
  183. package/src/mcp/types.ts +2 -6
  184. package/src/models/mcpServiceToken.test.ts +129 -0
  185. package/src/models/mcpServiceToken.ts +158 -0
  186. package/src/openApi.test.ts +80 -64
  187. package/src/openApiBuilder.test.ts +95 -7
  188. package/src/openApiBuilder.ts +46 -9
  189. package/src/openApiCompat.ts +1 -1
  190. package/src/openApiValidator.test.ts +49 -54
  191. package/src/openApiValidator.ts +1 -3
  192. package/src/plugins.test.ts +14 -0
  193. package/src/plugins.ts +34 -9
  194. package/src/populate.test.ts +34 -0
  195. package/src/populate.ts +40 -29
  196. package/src/rateLimit/applyTrustProxy.ts +17 -0
  197. package/src/rateLimit/createStore.ts +25 -0
  198. package/src/rateLimit/memoryStore.ts +40 -0
  199. package/src/rateLimit/middleware.ts +79 -0
  200. package/src/rateLimit/mongoStore.test.ts +80 -0
  201. package/src/rateLimit/mongoStore.ts +76 -0
  202. package/src/rateLimit/policies.ts +130 -0
  203. package/src/rateLimit/rateLimit.test.ts +328 -0
  204. package/src/rateLimit/redisStore.ioredis.test.ts +29 -0
  205. package/src/rateLimit/redisStore.test.ts +114 -0
  206. package/src/rateLimit/redisStore.ts +85 -0
  207. package/src/rateLimit/types.ts +64 -0
  208. package/src/rbac/access.ts +5 -1
  209. package/src/rbac/assertAllowed.test.ts +325 -0
  210. package/src/rbac/assertAllowed.ts +157 -0
  211. package/src/rbac/backfillAdmins.test.ts +124 -0
  212. package/src/rbac/fieldViews.test.ts +89 -0
  213. package/src/rbac/modelRouterAccess.test.ts +126 -0
  214. package/src/rbac/modelRouterAccess.ts +5 -2
  215. package/src/rbac/permissionUtils.ts +3 -2
  216. package/src/rbac/realtimeAccess.test.ts +109 -1
  217. package/src/rbac/resolve.ts +5 -4
  218. package/src/rbac/roleManager.test.ts +169 -0
  219. package/src/rbac/routes.test.ts +233 -0
  220. package/src/rbac/routes.ts +16 -6
  221. package/src/rbac/statements.test.ts +2 -0
  222. package/src/rbac/statements.ts +12 -1
  223. package/src/realtime/deprecation.test.ts +60 -0
  224. package/src/realtime/deprecation.ts +32 -0
  225. package/src/realtime/realtime.test.ts +8 -4
  226. package/src/realtime/realtimeApp.ts +10 -11
  227. package/src/realtime/realtimeAppSetup.test.ts +32 -5
  228. package/src/realtime/registry.ts +48 -42
  229. package/src/realtime/sessionRevalidation.test.ts +57 -44
  230. package/src/realtime/socketAuth.test.ts +75 -23
  231. package/src/realtime/socketAuth.ts +17 -6
  232. package/src/realtime/socketUser.ts +5 -3
  233. package/src/realtime/types.ts +14 -4
  234. package/src/schemaMetadata.test.ts +405 -0
  235. package/src/schemaMetadata.ts +593 -0
  236. package/src/scrubAdminFields.test.ts +105 -0
  237. package/src/seedRunner.test.ts +591 -0
  238. package/src/seedRunner.ts +464 -0
  239. package/src/sync/docMatchesMutationData.test.ts +16 -0
  240. package/src/sync/ensureSyncIndexes.test.ts +54 -15
  241. package/src/sync/executors.test.ts +40 -0
  242. package/src/sync/executors.ts +24 -12
  243. package/src/sync/integration.test.ts +15 -7
  244. package/src/sync/loadHarness.ts +28 -19
  245. package/src/sync/models.ts +32 -18
  246. package/src/sync/mutationHandler.test.ts +16 -16
  247. package/src/sync/mutationHandler.ts +9 -7
  248. package/src/sync/registrationSideEffects.test.ts +126 -0
  249. package/src/sync/registrationSideEffects.ts +131 -0
  250. package/src/sync/registry.ts +45 -171
  251. package/src/sync/routes.ts +3 -2
  252. package/src/sync/scripts/compactTombstones.ts +0 -2
  253. package/src/sync/sessionRevalidationIntegration.test.ts +12 -11
  254. package/src/sync/sync.test.ts +25 -23
  255. package/src/sync/syncApp.ts +4 -4
  256. package/src/sync/syncBatch.ts +3 -2
  257. package/src/sync/syncFrontier.test.ts +17 -15
  258. package/src/sync/syncPhaseC.test.ts +54 -43
  259. package/src/sync/syncRoutes.test.ts +51 -36
  260. package/src/sync/syncSeqPlugin.ts +66 -44
  261. package/src/sync/syncSocket.test.ts +112 -81
  262. package/src/terrenoApp.mcpServiceTokens.test.ts +173 -0
  263. package/src/terrenoApp.ts +87 -15
  264. package/src/tests/models.ts +14 -1
  265. package/src/types/authToken.ts +43 -0
  266. package/src/types/mcpServiceToken.ts +54 -0
  267. package/src/webhooks/headerValue.test.ts +22 -0
  268. package/src/webhooks/headerValue.ts +12 -0
  269. package/src/webhooks/idempotency/memoryStore.ts +34 -0
  270. package/src/webhooks/idempotency/mongoStore.test.ts +274 -0
  271. package/src/webhooks/idempotency/mongoStore.ts +83 -0
  272. package/src/webhooks/idempotency/webhookReceipt.ts +70 -0
  273. package/src/webhooks/rawBody.test.ts +74 -0
  274. package/src/webhooks/rawBody.ts +23 -0
  275. package/src/webhooks/timingSafeEqual.ts +16 -0
  276. package/src/webhooks/verifiers/hmac.test.ts +110 -0
  277. package/src/webhooks/verifiers/hmac.ts +54 -0
  278. package/src/webhooks/verifiers/providerVerifiers.test.ts +388 -0
  279. package/src/webhooks/verifiers/sendgrid.ts +59 -0
  280. package/src/webhooks/verifiers/stripe.ts +67 -0
  281. package/src/webhooks/verifiers/twilio.ts +69 -0
  282. package/src/webhooks/webhooksApp.test.ts +221 -0
  283. package/src/webhooks/webhooksApp.ts +144 -0
@@ -1,78 +1,84 @@
1
+ import type {Model} from "mongoose";
2
+
1
3
  import type {ModelRouterOptions} from "../api";
4
+ import {
5
+ clearCollectionRegistry,
6
+ listCollections,
7
+ registerCollection,
8
+ replaceCollectionOptions,
9
+ } from "../collectionRegistry";
2
10
  import type {RealtimeConfig} from "./types";
3
11
 
4
- /**
5
- * A registered model with real-time sync configuration.
6
- */
7
12
  export interface RealtimeRegistryEntry {
8
- /** Mongoose model name (e.g. "Todo") */
9
13
  modelName: string;
10
- /** Route path (e.g. "/todos") */
11
14
  routePath: string;
12
- /** Collection name in MongoDB (e.g. "todos") */
13
15
  collectionName: string;
14
- /** Real-time configuration from modelRouter options */
15
16
  config: RealtimeConfig;
16
- /**
17
- * Full modelRouter options (for responseHandler, permissions, etc.), erased to
18
- * `unknown` since the registry holds entries for every model.
19
- */
20
17
  options: ModelRouterOptions<unknown>;
21
18
  }
22
19
 
23
- const realtimeRegistry: RealtimeRegistryEntry[] = [];
20
+ const toRealtimeEntry = (record: {
21
+ model: Model<unknown>;
22
+ options: ModelRouterOptions<unknown>;
23
+ routePath: string;
24
+ }): RealtimeRegistryEntry => ({
25
+ collectionName: record.model.collection.collectionName,
26
+ config: record.options.realtime as RealtimeConfig,
27
+ modelName: record.model.modelName,
28
+ options: record.options,
29
+ routePath: record.routePath,
30
+ });
31
+
32
+ const realtimeModelForEntry = (entry: RealtimeRegistryEntry): Model<unknown> => {
33
+ const registered = listCollections().find(
34
+ (record) => record.routePath === entry.routePath
35
+ )?.model;
36
+ if (registered) {
37
+ return registered;
38
+ }
39
+ return {
40
+ collection: {collectionName: entry.collectionName},
41
+ modelName: entry.modelName,
42
+ } as Model<unknown>;
43
+ };
24
44
 
25
- /**
26
- * Register a model for real-time sync. Called automatically by modelRouter
27
- * when the `realtime` option is provided.
28
- */
29
45
  export const registerRealtime = (entry: RealtimeRegistryEntry): void => {
30
- realtimeRegistry.push(entry);
46
+ registerCollection({
47
+ model: realtimeModelForEntry(entry),
48
+ options: {
49
+ ...entry.options,
50
+ realtime: entry.config,
51
+ } as ModelRouterOptions<unknown>,
52
+ routePath: entry.routePath,
53
+ });
31
54
  };
32
55
 
33
- /**
34
- * Replace options on an existing registry entry (e.g. after TerrenoApp injects accessControl).
35
- * Matches by routePath; no-op if the route was never registered.
36
- */
37
56
  export const updateRealtimeRegistryOptions = (
38
57
  routePath: string,
39
58
  options: ModelRouterOptions<unknown>
40
59
  ): void => {
41
- const existing = realtimeRegistry.find((entry) => entry.routePath === routePath);
42
- if (!existing) {
43
- return;
44
- }
45
- existing.options = options;
60
+ replaceCollectionOptions(routePath, options);
46
61
  };
47
62
 
48
- /**
49
- * Get all registered real-time models.
50
- */
51
- export const getRealtimeRegistry = (): RealtimeRegistryEntry[] => realtimeRegistry;
63
+ export const getRealtimeRegistry = (): RealtimeRegistryEntry[] =>
64
+ listCollections()
65
+ .filter((record) => record.surfaces.realtime)
66
+ .map(toRealtimeEntry);
52
67
 
53
- /**
54
- * Find a registry entry by MongoDB collection name.
55
- */
56
68
  export const findRegistryEntryByCollection = (
57
69
  collectionName: string
58
70
  ): RealtimeRegistryEntry | undefined => {
59
- return realtimeRegistry.find((entry) => entry.collectionName === collectionName);
71
+ return getRealtimeRegistry().find((entry) => entry.collectionName === collectionName);
60
72
  };
61
73
 
62
- /**
63
- * Find a registry entry by route path / collection tag (e.g. "todos").
64
- */
65
74
  export const findRegistryEntryByRoutePath = (
66
75
  collection: string
67
76
  ): RealtimeRegistryEntry | undefined => {
68
- return realtimeRegistry.find(
77
+ return getRealtimeRegistry().find(
69
78
  (entry) => entry.routePath === `/${collection}` || entry.routePath === collection
70
79
  );
71
80
  };
72
81
 
73
- /**
74
- * Clear the registry (for testing).
75
- */
76
82
  export const clearRealtimeRegistry = (): void => {
77
- realtimeRegistry.length = 0;
83
+ clearCollectionRegistry();
78
84
  };
@@ -1,5 +1,3 @@
1
- // noExplicitAny: test mocks use dynamic shapes for sockets, io, and models
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test mocks use dynamic shapes for sockets, io, and models
3
1
  /**
4
2
  * D1: socket session re-validation sweep.
5
3
  * - revalidateSocketSession: expired/disabled/invalid-session detection per auth kind
@@ -10,7 +8,10 @@
10
8
  import {afterEach, describe, expect, it, mock} from "bun:test";
11
9
  import {DateTime} from "luxon";
12
10
  import mongoose, {model, Schema} from "mongoose";
13
-
11
+ import type {Server} from "socket.io";
12
+ import type {ModelRouterOptions} from "../api";
13
+ import type {UserModel} from "../auth";
14
+ import type {BetterAuthInstance} from "../betterAuthSetup";
14
15
  import {createdUpdatedPlugin, isDeletedPlugin} from "../plugins";
15
16
  import {clearSyncRegistry, registerSync} from "../sync/registry";
16
17
  import {syncPlugin} from "../sync/syncSeqPlugin";
@@ -24,12 +25,24 @@ import {
24
25
  } from "./sessionRevalidation";
25
26
 
26
27
  /** Minimal fake Mongoose model: findOneOrNoneFor falls back to `.find()` without the plugin. */
27
- const fakeUserModel = (users: Record<string, unknown>): any => ({
28
- find: async (query: {_id: string}) => {
29
- const user = users[query._id];
30
- return user ? [user] : [];
31
- },
32
- });
28
+ const fakeUserModel = (users: Record<string, unknown>): UserModel =>
29
+ ({
30
+ find: async (query: {_id: string}) => {
31
+ const user = users[query._id];
32
+ return user ? [user] : [];
33
+ },
34
+ }) as unknown as UserModel;
35
+
36
+ const fakeIo = (sockets: Map<string, RevalidatableSocket>): Server =>
37
+ ({sockets: {sockets}}) as unknown as Server;
38
+
39
+ type LoadableSocket = Parameters<typeof loadFullUserForSocket>[0];
40
+ const asLoadable = (socket: RevalidatableSocket): LoadableSocket =>
41
+ socket as unknown as LoadableSocket;
42
+
43
+ const openPermissions = {
44
+ permissions: {create: [], delete: [], list: [], read: [], update: []},
45
+ } as unknown as ModelRouterOptions<unknown>;
33
46
 
34
47
  /**
35
48
  * Real (but never persisted — no test DB round-trip needed) Mongoose models satisfying
@@ -44,7 +57,7 @@ revalTenantSchema.plugin(isDeletedPlugin);
44
57
  revalTenantSchema.plugin(createdUpdatedPlugin);
45
58
  revalTenantSchema.plugin(syncPlugin);
46
59
  const RevalTenantModel =
47
- (mongoose.models.RevalSessionProject as mongoose.Model<any>) ||
60
+ (mongoose.models.RevalSessionProject as mongoose.Model<unknown>) ||
48
61
  model("RevalSessionProject", revalTenantSchema);
49
62
 
50
63
  const revalOwnerSchema = new Schema({
@@ -55,7 +68,7 @@ revalOwnerSchema.plugin(isDeletedPlugin);
55
68
  revalOwnerSchema.plugin(createdUpdatedPlugin);
56
69
  revalOwnerSchema.plugin(syncPlugin);
57
70
  const RevalOwnerModel =
58
- (mongoose.models.RevalSessionTodo as mongoose.Model<any>) ||
71
+ (mongoose.models.RevalSessionTodo as mongoose.Model<unknown>) ||
59
72
  model("RevalSessionTodo", revalOwnerSchema);
60
73
 
61
74
  const makeSocket = (overrides: Partial<RevalidatableSocket> = {}): RevalidatableSocket => ({
@@ -106,7 +119,9 @@ describe("revalidateSocketSession", () => {
106
119
  });
107
120
  const outcome = await revalidateSocketSession(socket, {
108
121
  betterAuth: {
109
- auth: {api: {getSession: async () => ({user: {id: "u1"}})}} as any,
122
+ auth: {
123
+ api: {getSession: async () => ({user: {id: "u1"}})},
124
+ } as unknown as BetterAuthInstance,
110
125
  },
111
126
  });
112
127
  expect(outcome).toBe("valid");
@@ -118,7 +133,7 @@ describe("revalidateSocketSession", () => {
118
133
  encodedToken: "revoked-session-token",
119
134
  });
120
135
  const outcome = await revalidateSocketSession(socket, {
121
- betterAuth: {auth: {api: {getSession: async () => null}} as any},
136
+ betterAuth: {auth: {api: {getSession: async () => null}} as unknown as BetterAuthInstance},
122
137
  });
123
138
  expect(outcome).toBe("invalid-session");
124
139
  });
@@ -170,7 +185,7 @@ describe("reresolveSyncRoomsForSocket (D4)", () => {
170
185
  registerSync({
171
186
  config: {scope: {field: "organizationId", type: "tenant"}},
172
187
  model: RevalTenantModel,
173
- options: {permissions: {create: [], delete: [], list: [], read: [], update: []}} as any,
188
+ options: openPermissions,
174
189
  routePath: "/projects",
175
190
  });
176
191
 
@@ -202,7 +217,7 @@ describe("reresolveSyncRoomsForSocket (D4)", () => {
202
217
  registerSync({
203
218
  config: {scope: {field: "organizationId", type: "tenant"}},
204
219
  model: RevalTenantModel,
205
- options: {permissions: {create: [], delete: [], list: [], read: [], update: []}} as any,
220
+ options: openPermissions,
206
221
  routePath: "/projects",
207
222
  });
208
223
  const subscriptions = new Map<string, Set<string>>([
@@ -224,7 +239,7 @@ describe("reresolveSyncRoomsForSocket (D4)", () => {
224
239
  registerSync({
225
240
  config: {scope: {type: "owner"}},
226
241
  model: RevalOwnerModel,
227
- options: {permissions: {create: [], delete: [], list: [], read: [], update: []}} as any,
242
+ options: openPermissions,
228
243
  routePath: "/todos",
229
244
  });
230
245
  const subscriptions = new Map<string, Set<string>>([
@@ -251,7 +266,7 @@ describe("runSessionRevalidationSweep", () => {
251
266
  id: "u1",
252
267
  },
253
268
  });
254
- const io = {sockets: {sockets: new Map([["socket-1", socket]])}} as any;
269
+ const io = fakeIo(new Map([["socket-1", socket]]));
255
270
 
256
271
  await runSessionRevalidationSweep(io, {});
257
272
 
@@ -261,7 +276,7 @@ describe("runSessionRevalidationSweep", () => {
261
276
 
262
277
  it("disconnects a disabled user's socket", async () => {
263
278
  const socket = makeSocket({decodedToken: {authKind: "jwt", id: "u1"}});
264
- const io = {sockets: {sockets: new Map([["socket-1", socket]])}} as any;
279
+ const io = fakeIo(new Map([["socket-1", socket]]));
265
280
 
266
281
  await runSessionRevalidationSweep(io, {
267
282
  userModel: fakeUserModel({u1: {_id: "u1", disabled: true}}),
@@ -279,7 +294,7 @@ describe("runSessionRevalidationSweep", () => {
279
294
  id: "u1",
280
295
  },
281
296
  });
282
- const io = {sockets: {sockets: new Map([["socket-1", socket]])}} as any;
297
+ const io = fakeIo(new Map([["socket-1", socket]]));
283
298
 
284
299
  await runSessionRevalidationSweep(io, {});
285
300
 
@@ -305,16 +320,14 @@ describe("runSessionRevalidationSweep", () => {
305
320
  throw new Error("db unavailable");
306
321
  },
307
322
  };
308
- const io = {
309
- sockets: {
310
- sockets: new Map([
311
- ["socket-throws", throwing],
312
- ["socket-expired", expired],
313
- ]),
314
- },
315
- } as any;
323
+ const io = fakeIo(
324
+ new Map([
325
+ ["socket-throws", throwing],
326
+ ["socket-expired", expired],
327
+ ])
328
+ );
316
329
 
317
- await runSessionRevalidationSweep(io, {userModel: throwingUserModel as any});
330
+ await runSessionRevalidationSweep(io, {userModel: throwingUserModel as unknown as UserModel});
318
331
 
319
332
  // The throwing socket's error is caught and logged; it is left connected rather
320
333
  // than disconnected on an ambiguous internal failure.
@@ -325,7 +338,7 @@ describe("runSessionRevalidationSweep", () => {
325
338
 
326
339
  describe("startSessionRevalidationSweep", () => {
327
340
  it("does not arm a timer when intervalMs is 0", () => {
328
- const io = {sockets: {sockets: new Map()}} as any;
341
+ const io = fakeIo(new Map());
329
342
  const handle = startSessionRevalidationSweep(io, {intervalMs: 0});
330
343
  // No assertion beyond "does not throw" is possible without reaching into timer
331
344
  // internals; stop() must be a safe no-op either way.
@@ -333,7 +346,7 @@ describe("startSessionRevalidationSweep", () => {
333
346
  });
334
347
 
335
348
  it("returns a handle whose stop() clears the interval", () => {
336
- const io = {sockets: {sockets: new Map()}} as any;
349
+ const io = fakeIo(new Map());
337
350
  const handle = startSessionRevalidationSweep(io, {intervalMs: 60_000});
338
351
  expect(() => handle.stop()).not.toThrow();
339
352
  // Calling stop() twice must also be safe.
@@ -348,7 +361,7 @@ describe("startSessionRevalidationSweep", () => {
348
361
  registerSync({
349
362
  config: {scope: {field: "organizationId", type: "tenant"}},
350
363
  model: RevalTenantModel,
351
- options: {permissions: {create: [], delete: [], list: [], read: [], update: []}} as any,
364
+ options: openPermissions,
352
365
  routePath: "/projects",
353
366
  });
354
367
  const user = {_id: "u1", disabled: false};
@@ -360,7 +373,7 @@ describe("startSessionRevalidationSweep", () => {
360
373
  },
361
374
  decodedToken: {authKind: "jwt", id: "u1"},
362
375
  });
363
- const io = {sockets: {sockets: new Map([["socket-1", socket]])}} as any;
376
+ const io = fakeIo(new Map([["socket-1", socket]]));
364
377
  let currentScopes = ["org-v1"];
365
378
 
366
379
  const handle = startSessionRevalidationSweep(io, () => ({
@@ -391,23 +404,23 @@ const settleFor = (ms: number): Promise<void> => new Promise((resolve) => setTim
391
404
  describe("loadFullUserForSocket (D2)", () => {
392
405
  it("populates socket.data.fullUser from the decoded token's id", async () => {
393
406
  const user = {_id: "u1", organizationIds: ["org-a"]};
394
- const socket: any = {data: {}, decodedToken: {id: "u1"}, id: "socket-1"};
407
+ const socket = makeSocket({decodedToken: {id: "u1"}});
395
408
 
396
- await loadFullUserForSocket(socket, fakeUserModel({u1: user}));
409
+ await loadFullUserForSocket(asLoadable(socket), fakeUserModel({u1: user}));
397
410
 
398
- expect(socket.data.fullUser).toEqual(user);
411
+ expect(socket.data?.fullUser).toEqual(user);
399
412
  });
400
413
 
401
414
  it("is a no-op when no userModel is configured", async () => {
402
- const socket: any = {data: {}, decodedToken: {id: "u1"}, id: "socket-1"};
403
- await loadFullUserForSocket(socket, undefined);
404
- expect(socket.data.fullUser).toBeUndefined();
415
+ const socket = makeSocket({decodedToken: {id: "u1"}});
416
+ await loadFullUserForSocket(asLoadable(socket), undefined);
417
+ expect(socket.data?.fullUser).toBeUndefined();
405
418
  });
406
419
 
407
420
  it("is a no-op when the decoded token has no id", async () => {
408
- const socket: any = {data: {}, decodedToken: {}, id: "socket-1"};
409
- await loadFullUserForSocket(socket, fakeUserModel({u1: {_id: "u1"}}));
410
- expect(socket.data.fullUser).toBeUndefined();
421
+ const socket = makeSocket({decodedToken: {}});
422
+ await loadFullUserForSocket(asLoadable(socket), fakeUserModel({u1: {_id: "u1"}}));
423
+ expect(socket.data?.fullUser).toBeUndefined();
411
424
  });
412
425
 
413
426
  it("swallows a lookup error and leaves fullUser unset", async () => {
@@ -416,8 +429,8 @@ describe("loadFullUserForSocket (D2)", () => {
416
429
  throw new Error("db down");
417
430
  },
418
431
  };
419
- const socket: any = {data: {}, decodedToken: {id: "u1"}, id: "socket-1"};
420
- await loadFullUserForSocket(socket, throwingModel as any);
421
- expect(socket.data.fullUser).toBeUndefined();
432
+ const socket = makeSocket({decodedToken: {id: "u1"}});
433
+ await loadFullUserForSocket(asLoadable(socket), throwingModel as unknown as UserModel);
434
+ expect(socket.data?.fullUser).toBeUndefined();
422
435
  });
423
436
  });
@@ -1,5 +1,3 @@
1
- // noExplicitAny: test mocks use dynamic shapes for sockets and auth stubs
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test mocks use dynamic shapes for sockets and auth stubs
3
1
  /**
4
2
  * Full validator matrix for the socket authentication chain (D1):
5
3
  * - Legacy JWT validator (valid / expired / wrong-secret / wrong-issuer / missing token)
@@ -12,28 +10,34 @@
12
10
  * subscribe/mutate socket handlers) into its own file per the syncdb hardening plan.
13
11
  */
14
12
  import {describe, expect, it} from "bun:test";
13
+ import {assert} from "chai";
15
14
  import jwt from "jsonwebtoken";
15
+ import type {Socket} from "socket.io";
16
16
 
17
+ import type {UserModel} from "../auth";
17
18
  import {
18
19
  type AuthenticatableSocket,
20
+ type BetterAuthSocketOptions,
19
21
  createBetterAuthValidator,
20
22
  createLegacyJwtValidator,
21
23
  createSocketAuthMiddleware,
22
24
  } from "./socketAuth";
23
25
 
26
+ type StubbedAuth = BetterAuthSocketOptions["auth"];
27
+
24
28
  describe("socketAuth", () => {
25
29
  const tokenSecret = "socket-auth-test-secret";
26
30
 
27
- const makeAuthSocket = (token?: string): AuthenticatableSocket & {decodedToken?: any} => ({
31
+ const makeAuthSocket = (token?: string): AuthenticatableSocket => ({
28
32
  handshake: {auth: token === undefined ? {} : {token}},
29
33
  });
30
34
 
31
35
  const runMiddleware = (
32
- middleware: (socket: any, next: (error?: Error) => void) => void,
36
+ middleware: (socket: Socket, next: (error?: Error) => void) => void,
33
37
  socket: AuthenticatableSocket
34
38
  ): Promise<Error | undefined> =>
35
39
  new Promise((resolve) => {
36
- middleware(socket, (error?: Error) => resolve(error));
40
+ middleware(socket as unknown as Socket, (error?: Error) => resolve(error));
37
41
  });
38
42
 
39
43
  describe("createLegacyJwtValidator", () => {
@@ -142,16 +146,20 @@ describe("socketAuth", () => {
142
146
  });
143
147
 
144
148
  describe("createBetterAuthValidator", () => {
145
- const stubAuth = (session: unknown, capture?: {headers?: unknown}): any => ({
146
- api: {
147
- getSession: async ({headers}: {headers: unknown}) => {
148
- if (capture) {
149
- capture.headers = headers;
150
- }
151
- return session;
149
+ const stubAuth = (
150
+ session: unknown,
151
+ capture?: {headers?: Record<string, string>}
152
+ ): StubbedAuth =>
153
+ ({
154
+ api: {
155
+ getSession: async ({headers}: {headers: Record<string, string>}) => {
156
+ if (capture) {
157
+ capture.headers = headers;
158
+ }
159
+ return session;
160
+ },
152
161
  },
153
- },
154
- });
162
+ }) as unknown as StubbedAuth;
155
163
 
156
164
  it("populates decodedToken from a valid Better Auth session", async () => {
157
165
  const validator = createBetterAuthValidator({
@@ -177,15 +185,15 @@ describe("socketAuth", () => {
177
185
  });
178
186
 
179
187
  it("passes the token as a bearer authorization header only", async () => {
180
- const capture: {headers?: any} = {};
188
+ const capture: {headers?: Record<string, string>} = {};
181
189
  const validator = createBetterAuthValidator({
182
190
  auth: stubAuth({session: {id: "s"}, user: {id: "u"}}, capture),
183
191
  });
184
192
  await validator(makeAuthSocket("Bearer session-token-xyz"));
185
- expect(capture.headers.authorization).toBe("Bearer session-token-xyz");
193
+ expect(capture.headers?.authorization).toBe("Bearer session-token-xyz");
186
194
  // A raw (unsigned) token cookie fails signature verification and can shadow the
187
195
  // bearer path, so the validator must not send one.
188
- expect(capture.headers.cookie).toBeUndefined();
196
+ expect(capture.headers?.cookie).toBeUndefined();
189
197
  });
190
198
 
191
199
  it("rejects when the session lookup returns null", async () => {
@@ -211,7 +219,7 @@ describe("socketAuth", () => {
211
219
  query.betterAuthId === "ba-user-1" ? appUser : null;
212
220
  const validator = createBetterAuthValidator({
213
221
  auth: stubAuth({session: {id: "s"}, user: {id: "ba-user-1"}}),
214
- userModel: {...userModel, findOneOrNone} as any,
222
+ userModel: {...userModel, findOneOrNone} as unknown as UserModel,
215
223
  });
216
224
  const socket = makeAuthSocket("session-token");
217
225
  await validator(socket);
@@ -226,7 +234,7 @@ describe("socketAuth", () => {
226
234
  it("rejects when the Better Auth user has no application user", async () => {
227
235
  const validator = createBetterAuthValidator({
228
236
  auth: stubAuth({session: {id: "s"}, user: {id: "ba-orphan"}}),
229
- userModel: {findOneOrNone: async () => null} as any,
237
+ userModel: {findOneOrNone: async () => null} as unknown as UserModel,
230
238
  });
231
239
  await expect(validator(makeAuthSocket("session-token"))).rejects.toThrow(
232
240
  "no application user"
@@ -235,6 +243,34 @@ describe("socketAuth", () => {
235
243
  });
236
244
 
237
245
  describe("createSocketAuthMiddleware — validator chain", () => {
246
+ it("authenticates with Better Auth when no JWT secret is configured", async () => {
247
+ const middleware = createSocketAuthMiddleware({
248
+ betterAuth: {
249
+ auth: {
250
+ api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-only"}})},
251
+ } as unknown as BetterAuthSocketOptions["auth"],
252
+ },
253
+ });
254
+ const socket = makeAuthSocket("better-auth-session-token");
255
+
256
+ const error = await runMiddleware(middleware, socket);
257
+
258
+ assert.isUndefined(error);
259
+ assert.deepEqual(socket.decodedToken, {
260
+ admin: false,
261
+ authKind: "better-auth",
262
+ id: "ba-only",
263
+ isAnonymous: false,
264
+ });
265
+ });
266
+
267
+ it("rejects configuration with no authentication validators", () => {
268
+ assert.throws(
269
+ () => createSocketAuthMiddleware({}),
270
+ "At least one socket authentication validator is required"
271
+ );
272
+ });
273
+
238
274
  it("accepts a legacy JWT with the default chain", async () => {
239
275
  const middleware = createSocketAuthMiddleware({tokenSecret});
240
276
  const token = jwt.sign({admin: false, id: "chain-user"}, tokenSecret);
@@ -258,7 +294,7 @@ describe("socketAuth", () => {
258
294
  betterAuth: {
259
295
  auth: {
260
296
  api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-user-2"}})},
261
- } as any,
297
+ } as unknown as StubbedAuth,
262
298
  },
263
299
  tokenSecret,
264
300
  });
@@ -273,12 +309,28 @@ describe("socketAuth", () => {
273
309
  });
274
310
  });
275
311
 
312
+ it("accepts Better Auth sessions without a legacy JWT secret", async () => {
313
+ const middleware = createSocketAuthMiddleware({
314
+ betterAuth: {
315
+ auth: {
316
+ api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-only-user"}})},
317
+ } as unknown as StubbedAuth,
318
+ },
319
+ });
320
+ const socket = makeAuthSocket("better-auth-session-token");
321
+ const error = await runMiddleware(middleware, socket);
322
+
323
+ assert.isUndefined(error);
324
+ assert.strictEqual(socket.decodedToken?.id, "ba-only-user");
325
+ assert.strictEqual(socket.decodedToken?.authKind, "better-auth");
326
+ });
327
+
276
328
  it("falls through to Better Auth when the JWT is expired", async () => {
277
329
  const middleware = createSocketAuthMiddleware({
278
330
  betterAuth: {
279
331
  auth: {
280
332
  api: {getSession: async () => ({session: {id: "s"}, user: {id: "ba-fallback"}})},
281
- } as any,
333
+ } as unknown as StubbedAuth,
282
334
  },
283
335
  tokenSecret,
284
336
  });
@@ -298,7 +350,7 @@ describe("socketAuth", () => {
298
350
  throw new Error("should not be called for a valid JWT");
299
351
  },
300
352
  },
301
- } as any,
353
+ } as unknown as StubbedAuth,
302
354
  },
303
355
  tokenSecret,
304
356
  });
@@ -312,7 +364,7 @@ describe("socketAuth", () => {
312
364
 
313
365
  it("rejects with the last validator's error when every validator fails", async () => {
314
366
  const middleware = createSocketAuthMiddleware({
315
- betterAuth: {auth: {api: {getSession: async () => null}} as any},
367
+ betterAuth: {auth: {api: {getSession: async () => null}} as unknown as StubbedAuth},
316
368
  tokenSecret,
317
369
  });
318
370
  const socket = makeAuthSocket("neither-jwt-nor-session");
@@ -3,6 +3,7 @@ import type {Socket} from "socket.io";
3
3
 
4
4
  import type {UserModel} from "../auth";
5
5
  import type {BetterAuthInstance} from "../betterAuthSetup";
6
+ import {APIError} from "../errors";
6
7
  import {logger} from "../logger";
7
8
  import {findOneOrNoneFor} from "../plugins";
8
9
  import type {SocketWithDecodedToken} from "./socketUser";
@@ -16,9 +17,9 @@ import type {SocketWithDecodedToken} from "./socketUser";
16
17
  * fails, the connection is rejected with the last validator's error.
17
18
  *
18
19
  * Validators:
19
- * 1. Legacy JWT (default, always first) — the existing `@thream/socketio-jwt` middleware,
20
- * wrapped unchanged so accepted payloads, secret handling, and error shapes are
21
- * byte-for-byte identical to the previous hardcoded setup.
20
+ * 1. Legacy JWT (when a token secret is configured, always first) — the existing
21
+ * `@thream/socketio-jwt` middleware, wrapped unchanged so accepted payloads, secret
22
+ * handling, and error shapes are byte-for-byte identical to the previous hardcoded setup.
22
23
  * 2. Better Auth session (optional) — enabled via `RealtimeAppOptions.betterAuth`. The
23
24
  * handshake token is validated as a Better Auth session via `auth.api.getSession`
24
25
  * (presented as an `Authorization: Bearer` credential, resolved by Better Auth's
@@ -188,8 +189,8 @@ export const createSocketAuthMiddleware = ({
188
189
  betterAuth,
189
190
  extraValidators = [],
190
191
  }: {
191
- /** Secret for the legacy JWT validator (same handling as before the refactor). */
192
- tokenSecret: string;
192
+ /** Secret enabling the legacy JWT validator (same handling as before the refactor). */
193
+ tokenSecret?: string;
193
194
  /**
194
195
  * JWT issuer to require (D1 parity with the HTTP path's `jwt.verify(token, secret,
195
196
  * {issuer})`). Omitted means no issuer check, matching pre-D1 behavior. A thunk is
@@ -201,12 +202,22 @@ export const createSocketAuthMiddleware = ({
201
202
  /** Additional validators appended to the chain (after JWT and Better Auth). */
202
203
  extraValidators?: SocketAuthValidator[];
203
204
  }): ((socket: Socket, next: (error?: Error) => void) => void) => {
204
- const validators: SocketAuthValidator[] = [createLegacyJwtValidator(tokenSecret, issuer)];
205
+ const validators: SocketAuthValidator[] = [];
206
+ if (tokenSecret) {
207
+ validators.push(createLegacyJwtValidator(tokenSecret, issuer));
208
+ }
205
209
  if (betterAuth) {
206
210
  validators.push(createBetterAuthValidator(betterAuth));
207
211
  }
208
212
  validators.push(...extraValidators);
209
213
 
214
+ if (validators.length === 0) {
215
+ throw new APIError({
216
+ status: 500,
217
+ title: "[realtime] At least one socket authentication validator is required.",
218
+ });
219
+ }
220
+
210
221
  return (socket, next): void => {
211
222
  void (async () => {
212
223
  let lastError: Error = new UnauthorizedError("credentials_required", {
@@ -28,9 +28,11 @@ export interface DecodedRealtimeToken {
28
28
  * configured, or while the handshake load is still in flight.
29
29
  */
30
30
  export interface SocketDataBag {
31
- // noExplicitAny: the full user is a consumer Mongoose document with app-specific fields
32
- // biome-ignore lint/suspicious/noExplicitAny: the full user is a consumer Mongoose document with app-specific fields
33
- fullUser?: any;
31
+ /**
32
+ * The consumer's own Mongoose user document, so its app-specific fields are opaque
33
+ * here — read it through {@link getSocketUser} rather than narrowing it inline.
34
+ */
35
+ fullUser?: unknown;
34
36
  /**
35
37
  * The in-flight handshake load of {@link SocketDataBag.fullUser}, published so handlers
36
38
  * that must not authorize against the synthetic token user can await it