@terreno/api 57.20.0 → 58.0.0-beta.1

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 (183) hide show
  1. package/CHANGELOG.md +93 -0
  2. package/README.md +1 -1
  3. package/biome.jsonc +3 -2
  4. package/dist/api.d.ts +3 -16
  5. package/dist/api.js +0 -9
  6. package/dist/auth.d.ts +3 -2
  7. package/dist/auth.js +95 -5
  8. package/dist/authRecovery.d.ts +2 -1
  9. package/dist/authRecovery.js +35 -17
  10. package/dist/collectionRegistry.d.ts +3 -4
  11. package/dist/collectionRegistry.js +0 -1
  12. package/dist/consentApp.d.ts +1 -1
  13. package/dist/consentApp.js +58 -2
  14. package/dist/frameworkModelNames.d.ts +4 -0
  15. package/dist/frameworkModelNames.js +4 -0
  16. package/dist/index.d.ts +8 -5
  17. package/dist/index.js +14 -20
  18. package/dist/mcp/adminTracking.d.ts +28 -0
  19. package/dist/mcp/adminTracking.js +80 -0
  20. package/dist/mcp/auth.d.ts +6 -0
  21. package/dist/mcp/auth.js +12 -2
  22. package/dist/mcp/server.d.ts +8 -0
  23. package/dist/mcp/server.js +48 -4
  24. package/dist/mcp/serviceTokens.d.ts +21 -1
  25. package/dist/mcp/serviceTokens.js +159 -183
  26. package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
  27. package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
  28. package/dist/models/mcpOAuthToken.js +27 -0
  29. package/dist/models/mcpRequestLog.d.ts +2 -0
  30. package/dist/models/mcpRequestLog.js +73 -0
  31. package/dist/models/mcpServiceToken.js +40 -4
  32. package/dist/models/mcpToolSetting.d.ts +2 -0
  33. package/dist/models/mcpToolSetting.js +119 -0
  34. package/dist/models/versionConfig.d.ts +2 -0
  35. package/dist/openApiBuilder.d.ts +4 -0
  36. package/dist/openApiBuilder.js +2 -0
  37. package/dist/rbac/auditModel.d.ts +2 -1
  38. package/dist/rbac/realtimeAccess.d.ts +5 -4
  39. package/dist/rbac/realtimeAccess.js +17 -64
  40. package/dist/realtime/changeStreamWatcher.d.ts +8 -63
  41. package/dist/realtime/changeStreamWatcher.js +32 -391
  42. package/dist/realtime/realtimeApp.d.ts +14 -27
  43. package/dist/realtime/realtimeApp.js +14 -220
  44. package/dist/realtime/types.d.ts +0 -64
  45. package/dist/sync/executors.js +14 -2
  46. package/dist/sync/socketHandlers.d.ts +1 -1
  47. package/dist/sync/socketHandlers.js +1 -1
  48. package/dist/terrenoApp.d.ts +19 -5
  49. package/dist/terrenoApp.js +21 -14
  50. package/dist/tests/models.d.ts +17 -22
  51. package/dist/tests/models.js +7 -1
  52. package/dist/tests/openApiResponseSchema.d.ts +39 -0
  53. package/dist/tests/openApiResponseSchema.js +56 -0
  54. package/dist/tests/testHelper.d.ts +6 -12
  55. package/dist/tests.d.ts +2 -0
  56. package/dist/tests.js +6 -1
  57. package/dist/types/mcpAdmin.d.ts +58 -0
  58. package/dist/types/mcpAdmin.js +2 -0
  59. package/dist/types/mcpOAuth.d.ts +2 -0
  60. package/dist/types/mcpServiceToken.d.ts +9 -4
  61. package/dist/versionCheckPlugin.d.ts +1 -1
  62. package/dist/versionCheckPlugin.js +25 -2
  63. package/e2e/smoke.ts +193 -0
  64. package/package.json +14 -8
  65. package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
  66. package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
  67. package/src/__tests__/openApiResponseSchema.test.ts +148 -0
  68. package/src/__tests__/versionCheckPlugin.test.ts +72 -0
  69. package/src/adminModelRouter.test.ts +8 -6
  70. package/src/api.arrayOperations.test.ts +31 -22
  71. package/src/api.hooks.test.ts +12 -11
  72. package/src/api.query.test.ts +2 -2
  73. package/src/api.test.ts +17 -14
  74. package/src/api.ts +3 -27
  75. package/src/audit/auditApp.test.ts +1 -1
  76. package/src/audit/cloudTasksEnqueue.test.ts +19 -14
  77. package/src/auth.test.ts +21 -7
  78. package/src/auth.ts +116 -5
  79. package/src/authOpenApi.test.ts +316 -0
  80. package/src/authRecovery.test.ts +10 -10
  81. package/src/authRecovery.ts +47 -19
  82. package/src/authVerification.test.ts +7 -7
  83. package/src/betterAuthFeatures.test.ts +3 -2
  84. package/src/betterAuthLinking.test.ts +3 -1
  85. package/src/betterAuthOAuthHandoff.test.ts +13 -5
  86. package/src/betterAuthSetup.test.ts +77 -51
  87. package/src/collectionRegistry.test.ts +4 -4
  88. package/src/collectionRegistry.ts +3 -5
  89. package/src/consentApp.test.ts +98 -0
  90. package/src/consentApp.ts +67 -2
  91. package/src/frameworkModelNames.test.ts +8 -0
  92. package/src/frameworkModelNames.ts +4 -0
  93. package/src/githubAuth.test.ts +11 -11
  94. package/src/index.ts +14 -28
  95. package/src/isolated/migrateCliConnect.isolated.ts +3 -2
  96. package/src/mcp/actionTools.test.ts +13 -7
  97. package/src/mcp/adminTracking.test.ts +272 -0
  98. package/src/mcp/adminTracking.ts +104 -0
  99. package/src/mcp/auth.test.ts +7 -3
  100. package/src/mcp/auth.ts +18 -2
  101. package/src/mcp/oauth.test.ts +13 -13
  102. package/src/mcp/server.ts +67 -4
  103. package/src/mcp/serviceTokens.sync.test.ts +230 -0
  104. package/src/mcp/serviceTokens.test.ts +114 -62
  105. package/src/mcp/serviceTokens.ts +193 -212
  106. package/src/mcp/toolGenerator.test.ts +9 -5
  107. package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
  108. package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
  109. package/src/migrations/cli.test.ts +15 -14
  110. package/src/migrations/cli.ts +1 -1
  111. package/src/migrations/generate.test.ts +2 -2
  112. package/src/migrations/load.test.ts +1 -1
  113. package/src/migrations/lock.test.ts +8 -3
  114. package/src/migrations/runner.test.ts +16 -5
  115. package/src/migrations/schemaCatalog.test.ts +4 -1
  116. package/src/models/mcpOAuthToken.test.ts +42 -0
  117. package/src/models/mcpOAuthToken.ts +32 -0
  118. package/src/models/mcpRequestLog.ts +81 -0
  119. package/src/models/mcpServiceToken.test.ts +75 -5
  120. package/src/models/mcpServiceToken.ts +61 -14
  121. package/src/models/mcpToolSetting.test.ts +69 -0
  122. package/src/models/mcpToolSetting.ts +138 -0
  123. package/src/models/versionConfig.ts +2 -0
  124. package/src/notifications/notificationsApp.test.ts +5 -8
  125. package/src/notifiers/slackWebApi.test.ts +30 -8
  126. package/src/openApi.test.ts +4 -4
  127. package/src/openApiBuilder.test.ts +34 -1
  128. package/src/openApiBuilder.ts +5 -0
  129. package/src/openApiValidator.test.ts +3 -3
  130. package/src/orgs/orgPermissions.test.ts +2 -2
  131. package/src/orgs/orgPlugin.test.ts +4 -3
  132. package/src/orgs/orgSecurityDefects.test.ts +3 -1
  133. package/src/orgs/organizationSettings.test.ts +1 -1
  134. package/src/orgs/orgsApp.test.ts +5 -3
  135. package/src/permissions.test.ts +2 -2
  136. package/src/rateLimit/rateLimit.test.ts +25 -10
  137. package/src/rateLimit/redisStore.ioredis.test.ts +3 -2
  138. package/src/rbac/assertAllowed.test.ts +1 -1
  139. package/src/rbac/auditModel.ts +10 -2
  140. package/src/rbac/realtimeAccess.test.ts +20 -171
  141. package/src/rbac/realtimeAccess.ts +17 -82
  142. package/src/rbac/routes.test.ts +1 -1
  143. package/src/rbac/userWriteGuards.test.ts +8 -5
  144. package/src/realtime/changeStreamWatcher.ts +43 -506
  145. package/src/realtime/realtime.test.ts +211 -2547
  146. package/src/realtime/realtimeApp.ts +16 -295
  147. package/src/realtime/types.ts +0 -72
  148. package/src/scrubAdminFields.test.ts +1 -1
  149. package/src/sync/adminWindowMutation.test.ts +4 -3
  150. package/src/sync/executors.test.ts +29 -1
  151. package/src/sync/executors.ts +23 -2
  152. package/src/sync/scripts/compactTombstones.test.ts +4 -3
  153. package/src/sync/socketHandlers.ts +1 -1
  154. package/src/sync/sync.test.ts +1 -1
  155. package/src/sync/syncPhaseC.test.ts +14 -11
  156. package/src/sync/syncRoutes.test.ts +8 -8
  157. package/src/sync/syncSeqPlugin.test.ts +1 -2
  158. package/src/sync/syncSocket.test.ts +78 -113
  159. package/src/terrenoApp.mcpServiceTokens.test.ts +16 -8
  160. package/src/terrenoApp.migrations.test.ts +8 -7
  161. package/src/terrenoApp.ts +38 -18
  162. package/src/tests/betterAuthStubs.ts +3 -2
  163. package/src/tests/bunSetup.ts +1 -1
  164. package/src/tests/models.ts +10 -0
  165. package/src/tests/openApiResponseSchema.ts +104 -0
  166. package/src/tests/testEnv.ts +7 -0
  167. package/src/tests.ts +8 -0
  168. package/src/types/mcpAdmin.ts +80 -0
  169. package/src/types/mcpOAuth.ts +5 -0
  170. package/src/types/mcpServiceToken.ts +12 -4
  171. package/src/versionCheckPlugin.ts +41 -2
  172. package/src/webhooks/verifiers/hmac.test.ts +1 -1
  173. package/tsconfig.typecheck.json +14 -0
  174. package/dist/realtime/deprecation.d.ts +0 -13
  175. package/dist/realtime/deprecation.js +0 -31
  176. package/dist/realtime/queryStore.d.ts +0 -37
  177. package/dist/realtime/queryStore.js +0 -103
  178. package/dist/realtime/registry.d.ts +0 -15
  179. package/dist/realtime/registry.js +0 -52
  180. package/src/realtime/deprecation.test.ts +0 -60
  181. package/src/realtime/deprecation.ts +0 -33
  182. package/src/realtime/queryStore.ts +0 -122
  183. package/src/realtime/registry.ts +0 -84
@@ -3,40 +3,24 @@ import * as Sentry from "@sentry/bun";
3
3
  import type express from "express";
4
4
  import {Server, type Socket} from "socket.io";
5
5
 
6
- import type {User, UserModel} from "../auth";
6
+ import type {UserModel} from "../auth";
7
7
  import {findBetterAuthProvider, getProvidedBetterAuth} from "../betterAuthApp";
8
8
  import {APIError} from "../errors";
9
9
  import {logger} from "../logger";
10
- import {canSubscribeRealtime} from "../rbac/realtimeAccess";
11
10
  import {warnOnSyncScopesWithoutUserModel} from "../sync/registry";
12
11
  import {installSyncSocketHandlers} from "../sync/socketHandlers";
13
12
  import {getSyncAppOptions} from "../sync/syncApp";
14
13
  import type {TerrenoApp} from "../terrenoApp";
15
14
  import type {TerrenoPlugin} from "../terrenoPlugin";
16
15
  import {startChangeStreamWatcher, stopChangeStreamWatcher} from "./changeStreamWatcher";
17
- import {
18
- addQuerySubscription,
19
- computeQueryId,
20
- removeAllSocketQueries,
21
- removeQuerySubscription,
22
- } from "./queryStore";
23
- import {findRegistryEntryByRoutePath, type RealtimeRegistryEntry} from "./registry";
24
16
  import {
25
17
  loadFullUserForSocket,
26
18
  type SessionRevalidationHandle,
27
19
  startSessionRevalidationSweep,
28
20
  } from "./sessionRevalidation";
29
21
  import {type BetterAuthSocketOptions, createSocketAuthMiddleware} from "./socketAuth";
30
- import {getSocketUser, type SocketDataBag, type SocketWithDecodedToken} from "./socketUser";
31
- import type {DocumentSubscription, QuerySubscription, RealtimeAppOptions} from "./types";
32
-
33
- /**
34
- * Caps on per-socket subscriptions. Prevents a malicious or buggy client from
35
- * exhausting server memory by opening unbounded subscriptions.
36
- */
37
- export const MAX_MODEL_SUBSCRIPTIONS = 50;
38
- export const MAX_DOCUMENT_SUBSCRIPTIONS = 500;
39
- export const MAX_QUERY_SUBSCRIPTIONS = 100;
22
+ import type {SocketDataBag, SocketWithDecodedToken} from "./socketUser";
23
+ import type {RealtimeAppOptions} from "./types";
40
24
 
41
25
  /**
42
26
  * Replace any userinfo (`user:password@`) component in a URL with `***@` so the
@@ -74,91 +58,14 @@ export interface RealtimeSocketLike extends SocketWithDecodedToken {
74
58
  on: (event: string, handler: (...args: never[]) => void | Promise<void>) => void;
75
59
  }
76
60
 
77
- const LOGICAL_QUERY_KEYS = new Set(["$and", "$or"]);
78
-
79
- const isPlainQueryObject = (value: unknown): value is Record<string, unknown> =>
80
- typeof value === "object" && value !== null && !Array.isArray(value);
81
-
82
61
  /**
83
- * Returns the first field a client query names outside `queryFields`, walking `$and` / `$or`
84
- * clauses, or undefined when every field is allowed. A query room's event method reveals
85
- * whether a document matches, so subscriptions may only filter on the fields REST list
86
- * accepts.
87
- */
88
- const findDisallowedQueryField = (
89
- query: Record<string, unknown>,
90
- queryFields: string[]
91
- ): string | undefined => {
92
- for (const [key, condition] of Object.entries(query)) {
93
- if (LOGICAL_QUERY_KEYS.has(key)) {
94
- if (!Array.isArray(condition)) {
95
- return key;
96
- }
97
- for (const clause of condition) {
98
- if (!isPlainQueryObject(clause)) {
99
- return key;
100
- }
101
- const nested = findDisallowedQueryField(clause, queryFields);
102
- if (nested) {
103
- return nested;
104
- }
105
- }
106
- continue;
107
- }
108
- if (!queryFields.includes(key)) {
109
- return key;
110
- }
111
- }
112
- return undefined;
113
- };
114
-
115
- const canSubscribe = async (
116
- entry: RealtimeRegistryEntry,
117
- method: "list" | "read",
118
- user?: User
119
- ): Promise<boolean> => canSubscribeRealtime(entry, method, user);
120
-
121
- const getAuthorizedQuery = async (
122
- entry: RealtimeRegistryEntry,
123
- query: Record<string, unknown>,
124
- user?: User
125
- ): Promise<Record<string, unknown> | null> => {
126
- if (!(await canSubscribe(entry, "list", user))) {
127
- return null;
128
- }
129
-
130
- if (!entry.options.queryFilter) {
131
- return query;
132
- }
133
-
134
- let filteredQuery: Record<string, unknown> | null;
135
- try {
136
- filteredQuery = await entry.options.queryFilter(user, query);
137
- } catch (error) {
138
- logger.error(
139
- `[realtime] queryFilter threw for ${entry.modelName}/list: ${error}. Denying query subscription.`
140
- );
141
- Sentry.captureException(error);
142
- return null;
143
- }
144
-
145
- if (filteredQuery === null) {
146
- return null;
147
- }
148
-
149
- return {...query, ...filteredQuery};
150
- };
151
-
152
- /**
153
- * Install the realtime subscription handlers on a single socket. Extracted from the
154
- * RealtimeApp connection handler so this logic can be unit-tested with a mock socket
155
- * (no real Socket.io / HTTP server / JWT handshake required).
62
+ * Install the base socket handlers on a single socket: join the per-user, `authenticated`,
63
+ * and (for admins) `admin` rooms, and log disconnects. Extracted from the RealtimeApp
64
+ * connection handler so it can be unit-tested with a mock socket (no real Socket.io /
65
+ * HTTP server / JWT handshake required).
156
66
  *
157
- * Enforces:
158
- * - per-socket subscription caps (DoS protection)
159
- * - registry membership (only realtime-enabled collections can be subscribed)
160
- * - owner-strategy isolation (non-admin users cannot subscribe to other users' rooms)
161
- * - server-side queryId computation (clients can't hijack queries by colliding ids)
67
+ * Collection subscriptions go through the sync protocol (`sync:subscribe`), installed
68
+ * separately by `installSyncSocketHandlers`.
162
69
  */
163
70
  export const installRealtimeSocketHandlers = (
164
71
  socket: RealtimeSocketLike,
@@ -167,11 +74,6 @@ export const installRealtimeSocketHandlers = (
167
74
  const logInfo = options.logInfo ?? ((): void => {});
168
75
  const userId = socket.decodedToken?.id;
169
76
  const isAdmin = socket.decodedToken?.admin === true;
170
- // D2: re-derive per event rather than capturing once at install time, so a
171
- // handshake-time-loaded full user (or one refreshed by D1's sweep) is always used.
172
- const currentUser = (): User | undefined => getSocketUser(socket);
173
-
174
- const counts = {document: 0, model: 0, query: 0};
175
77
 
176
78
  const joinUserRooms = async (): Promise<void> => {
177
79
  if (userId) {
@@ -188,201 +90,19 @@ export const installRealtimeSocketHandlers = (
188
90
  // Fire-and-forget — there is nothing useful for the caller to await.
189
91
  void joinUserRooms();
190
92
 
191
- socket.on("subscribe:model", async (modelName: string): Promise<void> => {
192
- if (typeof modelName !== "string" || modelName.length === 0) {
193
- return;
194
- }
195
- if (counts.model >= MAX_MODEL_SUBSCRIPTIONS) {
196
- logInfo(`[realtime] User ${userId} hit model subscription limit`);
197
- return;
198
- }
199
-
200
- const entry = findRegistryEntryByRoutePath(modelName);
201
- if (!entry) {
202
- logInfo(
203
- `[realtime] User ${userId} denied model subscription: collection "${modelName}" not registered`
204
- );
205
- return;
206
- }
207
-
208
- // Owner-strategy models fan out via user:{ownerId} — there is no shared model room
209
- // that should be open to all users. Owners receive events through their user room
210
- // automatically; admins can use the admin room to see everything.
211
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
212
- logInfo(
213
- `[realtime] User ${userId} denied model subscription for ${modelName}: ` +
214
- "owner strategy restricts model room to admins"
215
- );
216
- return;
217
- }
218
-
219
- if (!(await canSubscribe(entry, "list", currentUser()))) {
220
- logInfo(
221
- `[realtime] User ${userId} denied model subscription for ${modelName}: list permission denied`
222
- );
223
- return;
224
- }
225
-
226
- counts.model += 1;
227
- await socket.join(`model:${modelName}`);
228
- logInfo(`[realtime] User ${userId} subscribed to model:${modelName}`);
229
- });
230
-
231
- socket.on("unsubscribe:model", async (modelName: string): Promise<void> => {
232
- if (typeof modelName === "string" && modelName.length > 0) {
233
- await socket.leave(`model:${modelName}`);
234
- counts.model = Math.max(0, counts.model - 1);
235
- logInfo(`[realtime] User ${userId} unsubscribed from model:${modelName}`);
236
- }
237
- });
238
-
239
- socket.on("subscribe:document", async (payload: DocumentSubscription): Promise<void> => {
240
- if (
241
- !payload?.collection ||
242
- !payload?.id ||
243
- typeof payload.collection !== "string" ||
244
- typeof payload.id !== "string"
245
- ) {
246
- return;
247
- }
248
- if (counts.document >= MAX_DOCUMENT_SUBSCRIPTIONS) {
249
- logInfo(`[realtime] User ${userId} hit document subscription limit`);
250
- return;
251
- }
252
-
253
- const entry = findRegistryEntryByRoutePath(payload.collection);
254
- if (!entry) {
255
- logInfo(
256
- `[realtime] User ${userId} denied document subscription: ` +
257
- `collection "${payload.collection}" not registered`
258
- );
259
- return;
260
- }
261
-
262
- if (!(await canSubscribe(entry, "read", currentUser()))) {
263
- logInfo(
264
- `[realtime] User ${userId} denied document subscription for ` +
265
- `${payload.collection}/${payload.id}: read permission denied`
266
- );
267
- return;
268
- }
269
-
270
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
271
- logInfo(
272
- `[realtime] User ${userId} denied document subscription for ` +
273
- `${payload.collection}/${payload.id}: owner strategy requires admin`
274
- );
275
- return;
276
- }
277
-
278
- counts.document += 1;
279
- const room = `document:${payload.collection}:${payload.id}`;
280
- await socket.join(room);
281
- logInfo(`[realtime] User ${userId} subscribed to ${room}`);
282
- });
283
-
284
- socket.on("unsubscribe:document", async (payload: DocumentSubscription): Promise<void> => {
285
- if (payload?.collection && payload?.id) {
286
- const room = `document:${payload.collection}:${payload.id}`;
287
- await socket.leave(room);
288
- counts.document = Math.max(0, counts.document - 1);
289
- logInfo(`[realtime] User ${userId} unsubscribed from ${room}`);
290
- }
291
- });
292
-
293
- socket.on("subscribe:query", async (payload: QuerySubscription): Promise<void> => {
294
- if (
295
- !payload?.collection ||
296
- !payload?.query ||
297
- typeof payload.collection !== "string" ||
298
- typeof payload.query !== "object" ||
299
- Array.isArray(payload.query)
300
- ) {
301
- return;
302
- }
303
- if (counts.query >= MAX_QUERY_SUBSCRIPTIONS) {
304
- logInfo(`[realtime] User ${userId} hit query subscription limit`);
305
- return;
306
- }
307
-
308
- const entry = findRegistryEntryByRoutePath(payload.collection);
309
- if (!entry) {
310
- logInfo(
311
- `[realtime] User ${userId} denied query subscription: ` +
312
- `collection "${payload.collection}" not registered`
313
- );
314
- return;
315
- }
316
-
317
- const disallowedField = findDisallowedQueryField(
318
- payload.query,
319
- entry.options.queryFields ?? []
320
- );
321
- if (disallowedField) {
322
- logInfo(
323
- `[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
324
- `${disallowedField} is not in queryFields`
325
- );
326
- return;
327
- }
328
-
329
- let query = await getAuthorizedQuery(entry, {...payload.query}, currentUser());
330
- if (!query) {
331
- logInfo(
332
- `[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
333
- "list permission or query filter denied"
334
- );
335
- return;
336
- }
337
-
338
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
339
- if (!userId) {
340
- return;
341
- }
342
- query = {...query, ownerId: userId};
343
- }
344
-
345
- const queryId = computeQueryId(payload.collection, query);
346
-
347
- addQuerySubscription(socket.id, payload.collection, query, queryId);
348
- counts.query += 1;
349
- await socket.join(`query:${queryId}`);
350
- socket.emit("query:subscribed", {
351
- clientQueryId: payload.queryId,
352
- collection: payload.collection,
353
- queryId,
354
- });
355
- logInfo(`[realtime] User ${userId} subscribed to query:${queryId} on ${payload.collection}`);
356
- });
357
-
358
- socket.on("unsubscribe:query", async (payload: {queryId: string}): Promise<void> => {
359
- if (payload?.queryId) {
360
- removeQuerySubscription(socket.id, payload.queryId);
361
- await socket.leave(`query:${payload.queryId}`);
362
- counts.query = Math.max(0, counts.query - 1);
363
- logInfo(`[realtime] User ${userId} unsubscribed from query:${payload.queryId}`);
364
- }
365
- });
366
-
367
93
  socket.on("disconnect", () => {
368
- removeAllSocketQueries(socket.id);
369
94
  logInfo(`[realtime] User ${userId} disconnected`);
370
95
  });
371
96
  };
372
97
 
373
98
  /**
374
- * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
99
+ * TerrenoPlugin that hosts Socket.io and the MongoDB change stream watcher for
100
+ * `@terreno/syncdb`.
375
101
  *
376
102
  * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
377
- * sets up JWT and/or Better Auth authentication for socket connections, manages room subscriptions
378
- * (model, document, and query rooms), and starts a change stream watcher that
379
- * emits events to connected clients.
380
- *
381
- * ## Subscription types
382
- *
383
- * - **Model rooms**: `subscribe:model` / `unsubscribe:model` — receive all events for a collection
384
- * - **Document rooms**: `subscribe:document` / `unsubscribe:document` — receive events for a single document
385
- * - **Query rooms**: `subscribe:query` / `unsubscribe:query` — receive events matching a MongoDB query
103
+ * sets up JWT and/or Better Auth authentication for socket connections, installs the
104
+ * sync protocol handlers (`sync:subscribe` / `sync:mutate`), and starts a change stream
105
+ * watcher that emits `sync:delta` events for models registered with `sync`.
386
106
  *
387
107
  * @example
388
108
  * ```typescript
@@ -390,7 +110,8 @@ export const installRealtimeSocketHandlers = (
390
110
  * userModel: User,
391
111
  * realtime: { debug: true },
392
112
  * })
393
- * .register(todoRouter) // todoRouter has realtime config
113
+ * .register(todoRouter) // todoRouter has a `sync` config
114
+ * .register(new SyncApp())
394
115
  * .start();
395
116
  * ```
396
117
  */
@@ -1,59 +1,9 @@
1
- import type express from "express";
2
1
  import type {Server as SocketIoServer} from "socket.io";
3
2
  import type {UserModel} from "../auth";
4
3
  import type {SyncAppOptions} from "../sync/routes";
5
4
  import type {startChangeStreamWatcher} from "./changeStreamWatcher";
6
5
  import type {BetterAuthSocketOptions} from "./socketAuth";
7
6
 
8
- /**
9
- * Configuration for real-time sync on a modelRouter.
10
- * Determines which CRUD methods emit WebSocket events and how they are routed.
11
- *
12
- * @deprecated Removed in Terreno 58. Use `sync` on modelRouter with `@terreno/syncdb`.
13
- * `RealtimeApp` remains required for sync sockets.
14
- */
15
- export interface RealtimeConfig {
16
- /** Which CRUD methods should emit real-time sync events */
17
- methods: Array<"create" | "update" | "delete">;
18
- /**
19
- * Strategy for determining which Socket.io rooms receive events.
20
- * - 'owner': emit to `user:{doc.ownerId}` room
21
- * - 'model': emit to `model:{modelName}` room (clients must subscribe)
22
- * - 'broadcast': emit to all authenticated sockets
23
- * - function: custom room resolver returning room name(s)
24
- */
25
- roomStrategy:
26
- | "owner"
27
- | "model"
28
- | "broadcast"
29
- | ((doc: Record<string, unknown>, method: string, req: express.Request) => string[]);
30
- /** Custom serializer for real-time events. Falls back to the modelRouter responseHandler. */
31
- realtimeResponseHandler?: (doc: Record<string, unknown>, method: string) => unknown;
32
- }
33
-
34
- /**
35
- * A real-time sync event emitted to clients via WebSocket.
36
- *
37
- * @deprecated Removed in Terreno 58 with modelRouter `realtime` and the RTK
38
- * cache-patching helpers. Syncdb uses `sync:delta` events instead.
39
- */
40
- export interface RealtimeEvent {
41
- /** Mongoose model name (e.g. "Todo") */
42
- model: string;
43
- /** Route path used as tag type (e.g. "todos") */
44
- collection: string;
45
- /** The CRUD method that triggered this event */
46
- method: "create" | "update" | "delete";
47
- /** Document ID */
48
- id: string;
49
- /** Serialized document data (omitted for hard deletes) */
50
- data?: unknown;
51
- /** Fields that were updated (for update events from change streams) */
52
- updatedFields?: string[];
53
- /** Epoch milliseconds when the event was generated */
54
- timestamp: number;
55
- }
56
-
57
7
  /**
58
8
  * Configuration for the MongoDB change stream watcher.
59
9
  */
@@ -150,25 +100,3 @@ export interface RealtimeAppOptions {
150
100
  */
151
101
  startChangeStreamWatcher?: typeof startChangeStreamWatcher;
152
102
  }
153
-
154
- /**
155
- * Payload sent by the client to subscribe to a single document's changes.
156
- */
157
- export interface DocumentSubscription {
158
- /** Collection tag (e.g. "todos") */
159
- collection: string;
160
- /** Document ID */
161
- id: string;
162
- }
163
-
164
- /**
165
- * Payload sent by the client to subscribe to a query-filtered list.
166
- */
167
- export interface QuerySubscription {
168
- /** Collection tag (e.g. "todos") */
169
- collection: string;
170
- /** MongoDB-style query filter (e.g. {completed: false}) */
171
- query: Record<string, unknown>;
172
- /** Client-provided queryId (ignored — server computes a canonical ID) */
173
- queryId?: string;
174
- }
@@ -176,7 +176,7 @@ describe("stripAdminBodyFields", () => {
176
176
  {internal: "n", role: "admin", slug: "fixed", title: "x"},
177
177
  admin
178
178
  );
179
- expect(result).toEqual({title: "x"});
179
+ expect<unknown>(result).toEqual({title: "x"});
180
180
  });
181
181
 
182
182
  it("strips keys from every object in an array body and leaves non-objects alone", () => {
@@ -2,7 +2,7 @@ import {afterEach, beforeEach, describe, expect, it} from "bun:test";
2
2
  import {assert} from "chai";
3
3
  import mongoose from "mongoose";
4
4
 
5
- import {addAuthRoutes, setupAuth, type UserModel as UserModelType} from "../auth";
5
+ import {addAuthRoutes, setupAuth, type User, type UserModel as UserModelType} from "../auth";
6
6
  import {Permissions} from "../permissions";
7
7
  import {createdUpdatedPlugin, findOneOrNoneFor, isDeletedPlugin} from "../plugins";
8
8
  import {authAsUser, getBaseServer, setupDb, UserModel} from "../tests";
@@ -88,7 +88,7 @@ describe("adminWindowMutation", () => {
88
88
  await WindowTodoModel.deleteMany({});
89
89
  });
90
90
 
91
- const loadUser = async (type: "admin" | "notAdmin") => {
91
+ const loadUser = async (type: "admin" | "notAdmin"): Promise<User> => {
92
92
  const app = getBaseServer();
93
93
  setupAuth(app, UserModel as unknown as UserModelType);
94
94
  addAuthRoutes(app, UserModel as unknown as UserModelType);
@@ -96,7 +96,7 @@ describe("adminWindowMutation", () => {
96
96
  const email = type === "admin" ? "admin@example.com" : "notAdmin@example.com";
97
97
  const doc = await findOneOrNoneFor(UserModel, {email});
98
98
  expect(doc).toBeTruthy();
99
- return doc as {admin?: boolean; id: string};
99
+ return doc as unknown as User;
100
100
  };
101
101
 
102
102
  it("returns undefined for product mutations without a marker", async () => {
@@ -398,6 +398,7 @@ describe("adminWindowMutation", () => {
398
398
  const options = buildAdminWindowExecutorOptions({
399
399
  productOptions: {
400
400
  maxLimit: 123,
401
+ permissions: {create: [], delete: [], list: [], read: [], update: []},
401
402
  preCreate: productPreCreate,
402
403
  preUpdate: productPreCreate,
403
404
  },
@@ -465,6 +465,34 @@ describe("executeUpdate", () => {
465
465
  expect(error.status).toBe(404);
466
466
  });
467
467
 
468
+ it("gives preUpdate the document id as req.params.id when no request is passed", async () => {
469
+ const doc = await createDoc();
470
+ const seenIds: unknown[] = [];
471
+ const options = baseOptions({
472
+ preUpdate: (body, req) => {
473
+ seenIds.push(req.params.id);
474
+ return body as ExecStuff;
475
+ },
476
+ });
477
+ await executeUpdate<ExecStuff>({
478
+ body: {name: "renamed"},
479
+ id: doc._id.toString(),
480
+ model: ExecStuffModel,
481
+ options,
482
+ user: owner,
483
+ });
484
+ // A socket sync mutation passes a `{user}` request that has no params.
485
+ await executeUpdate<ExecStuff>({
486
+ body: {name: "renamed again"},
487
+ id: doc._id.toString(),
488
+ model: ExecStuffModel,
489
+ options,
490
+ req: {user: owner} as unknown as express.Request,
491
+ user: owner,
492
+ });
493
+ expect(seenIds).toEqual([doc._id.toString(), doc._id.toString()]);
494
+ });
495
+
468
496
  it("returns 403 when preUpdate returns null", async () => {
469
497
  const doc = await createDoc();
470
498
  const options = baseOptions({preUpdate: () => null});
@@ -1293,7 +1321,7 @@ describe("soft-delete flag in client write bodies", () => {
1293
1321
  body: {name: "archived"},
1294
1322
  id: doc._id.toString(),
1295
1323
  model: ExecStuffModel,
1296
- options: baseOptions({preUpdate: (body) => ({...body, deleted: true})}),
1324
+ options: baseOptions({preUpdate: (body) => ({...body, deleted: true}) as ExecStuff}),
1297
1325
  user: owner,
1298
1326
  });
1299
1327
  expect(await ExecStuffModel.countDocuments({_id: doc._id})).toBe(0);
@@ -146,6 +146,27 @@ export const isExecutorConflictError = (error: unknown): error is ExecutorConfli
146
146
  */
147
147
  const stubRequest = (user?: User): express.Request => ({user}) as unknown as express.Request;
148
148
 
149
+ /**
150
+ * The request a hook sees for an update or delete of `id`. Over HTTP it is the real request. Over
151
+ * sync it is a stub (or the socket's `{user}` object) with no `params`, so `params.id` is filled
152
+ * in, as in the REST routes: hooks that read `req.params.id` must work over sync too.
153
+ */
154
+ const requestForId = ({
155
+ id,
156
+ req,
157
+ user,
158
+ }: {
159
+ id: string;
160
+ req?: express.Request;
161
+ user?: User;
162
+ }): express.Request => {
163
+ const request = req ?? stubRequest(user);
164
+ if (request.params === undefined) {
165
+ request.params = {id};
166
+ }
167
+ return request;
168
+ };
169
+
149
170
  /**
150
171
  * True for the Mongoose error thrown when an `optimisticConcurrency` save matched no
151
172
  * document (its `__v` filter failed) — i.e. another write landed since the load.
@@ -523,7 +544,7 @@ export const executeUpdate = async <T>({
523
544
  /** When true, skip modelRouter permission checks (admin-window sync mutations). */
524
545
  skipPermissionChecks?: boolean;
525
546
  }): Promise<ExecutorResult<T>> => {
526
- const request = req ?? stubRequest(user);
547
+ const request = requestForId({id, req, user});
527
548
 
528
549
  if (
529
550
  !skipPermissionChecks &&
@@ -805,7 +826,7 @@ export const executeDelete = async <T>({
805
826
  /** When true, skip modelRouter permission checks (admin-window sync mutations). */
806
827
  skipPermissionChecks?: boolean;
807
828
  }): Promise<ExecutorResult<T>> => {
808
- const request = req ?? stubRequest(user);
829
+ const request = requestForId({id, req, user});
809
830
 
810
831
  if (
811
832
  !skipPermissionChecks &&
@@ -6,7 +6,7 @@ import {Permissions} from "../../permissions";
6
6
  import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../../plugins";
7
7
  import {setupDb} from "../../tests";
8
8
  import {getCompactedThroughSeq, SyncCounter, SyncScopeMove} from "../models";
9
- import {clearSyncRegistry, registerSync} from "../registry";
9
+ import {clearSyncRegistry, registerSync, type SyncRegistryEntry} from "../registry";
10
10
  import {syncPlugin} from "../syncSeqPlugin";
11
11
  import {
12
12
  compactEntryTombstones,
@@ -228,7 +228,7 @@ describe("compactTombstones (C7 retention)", () => {
228
228
  });
229
229
 
230
230
  // Helper: re-register and return the entry (retentionDays override) for compactEntryTombstones.
231
- const clearSyncRegistryAndReRegister = (retentionDays: number) => {
231
+ const clearSyncRegistryAndReRegister = (retentionDays: number): SyncRegistryEntry => {
232
232
  clearSyncRegistry();
233
233
  registerSync({
234
234
  config: {retentionDays, scope: {type: "owner"}},
@@ -241,7 +241,8 @@ const clearSyncRegistryAndReRegister = (retentionDays: number) => {
241
241
  collectionTag: "compactStuff",
242
242
  config: {retentionDays, scope: {type: "owner"} as const},
243
243
  modelName: CompactStuffModel.modelName,
244
- options,
244
+ // The registry stores entries type-erased, as registerSync does.
245
+ options: options as unknown as ModelRouterOptions<unknown>,
245
246
  routePath: "/compactStuff",
246
247
  };
247
248
  };
@@ -64,7 +64,7 @@ const organizationIdFromPayload = (payload: unknown): string | undefined => {
64
64
  * permission for that model is required as well. Confirms with
65
65
  * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
66
66
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
67
- * legacy realtime rooms so the two event families never overlap.
67
+ * per-user rooms joined at connect.
68
68
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
69
69
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
70
70
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
@@ -347,7 +347,7 @@ describe("modelRouter sync option", () => {
347
347
  });
348
348
 
349
349
  const after = findSyncEntryByCollectionTag("syncStuff");
350
- expect(after?.options.accessControl).toBe(accessControl);
350
+ expect<unknown>(after?.options.accessControl).toBe(accessControl);
351
351
  expect(after?.options.permissions.list).not.toBe(before);
352
352
  });
353
353
  });