@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
@@ -33,29 +33,18 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.RealtimeApp = exports.installRealtimeSocketHandlers = exports.redactCredentials = exports.MAX_QUERY_SUBSCRIPTIONS = exports.MAX_DOCUMENT_SUBSCRIPTIONS = exports.MAX_MODEL_SUBSCRIPTIONS = void 0;
36
+ exports.RealtimeApp = exports.installRealtimeSocketHandlers = exports.redactCredentials = void 0;
37
37
  const Sentry = __importStar(require("@sentry/bun"));
38
38
  const socket_io_1 = require("socket.io");
39
39
  const betterAuthApp_1 = require("../betterAuthApp");
40
40
  const errors_1 = require("../errors");
41
41
  const logger_1 = require("../logger");
42
- const realtimeAccess_1 = require("../rbac/realtimeAccess");
43
42
  const registry_1 = require("../sync/registry");
44
43
  const socketHandlers_1 = require("../sync/socketHandlers");
45
44
  const syncApp_1 = require("../sync/syncApp");
46
45
  const changeStreamWatcher_1 = require("./changeStreamWatcher");
47
- const queryStore_1 = require("./queryStore");
48
- const registry_2 = require("./registry");
49
46
  const sessionRevalidation_1 = require("./sessionRevalidation");
50
47
  const socketAuth_1 = require("./socketAuth");
51
- const socketUser_1 = require("./socketUser");
52
- /**
53
- * Caps on per-socket subscriptions. Prevents a malicious or buggy client from
54
- * exhausting server memory by opening unbounded subscriptions.
55
- */
56
- exports.MAX_MODEL_SUBSCRIPTIONS = 50;
57
- exports.MAX_DOCUMENT_SUBSCRIPTIONS = 500;
58
- exports.MAX_QUERY_SUBSCRIPTIONS = 100;
59
48
  /**
60
49
  * Replace any userinfo (`user:password@`) component in a URL with `***@` so the
61
50
  * credentials are not written to logs. Falls back to a regex when the string
@@ -81,78 +70,19 @@ const redactCredentials = (url) => {
81
70
  }
82
71
  };
83
72
  exports.redactCredentials = redactCredentials;
84
- const LOGICAL_QUERY_KEYS = new Set(["$and", "$or"]);
85
- const isPlainQueryObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
86
- /**
87
- * Returns the first field a client query names outside `queryFields`, walking `$and` / `$or`
88
- * clauses, or undefined when every field is allowed. A query room's event method reveals
89
- * whether a document matches, so subscriptions may only filter on the fields REST list
90
- * accepts.
91
- */
92
- const findDisallowedQueryField = (query, queryFields) => {
93
- for (const [key, condition] of Object.entries(query)) {
94
- if (LOGICAL_QUERY_KEYS.has(key)) {
95
- if (!Array.isArray(condition)) {
96
- return key;
97
- }
98
- for (const clause of condition) {
99
- if (!isPlainQueryObject(clause)) {
100
- return key;
101
- }
102
- const nested = findDisallowedQueryField(clause, queryFields);
103
- if (nested) {
104
- return nested;
105
- }
106
- }
107
- continue;
108
- }
109
- if (!queryFields.includes(key)) {
110
- return key;
111
- }
112
- }
113
- return undefined;
114
- };
115
- const canSubscribe = async (entry, method, user) => (0, realtimeAccess_1.canSubscribeRealtime)(entry, method, user);
116
- const getAuthorizedQuery = async (entry, query, user) => {
117
- if (!(await canSubscribe(entry, "list", user))) {
118
- return null;
119
- }
120
- if (!entry.options.queryFilter) {
121
- return query;
122
- }
123
- let filteredQuery;
124
- try {
125
- filteredQuery = await entry.options.queryFilter(user, query);
126
- }
127
- catch (error) {
128
- logger_1.logger.error(`[realtime] queryFilter threw for ${entry.modelName}/list: ${error}. Denying query subscription.`);
129
- Sentry.captureException(error);
130
- return null;
131
- }
132
- if (filteredQuery === null) {
133
- return null;
134
- }
135
- return { ...query, ...filteredQuery };
136
- };
137
73
  /**
138
- * Install the realtime subscription handlers on a single socket. Extracted from the
139
- * RealtimeApp connection handler so this logic can be unit-tested with a mock socket
140
- * (no real Socket.io / HTTP server / JWT handshake required).
74
+ * Install the base socket handlers on a single socket: join the per-user, `authenticated`,
75
+ * and (for admins) `admin` rooms, and log disconnects. Extracted from the RealtimeApp
76
+ * connection handler so it can be unit-tested with a mock socket (no real Socket.io /
77
+ * HTTP server / JWT handshake required).
141
78
  *
142
- * Enforces:
143
- * - per-socket subscription caps (DoS protection)
144
- * - registry membership (only realtime-enabled collections can be subscribed)
145
- * - owner-strategy isolation (non-admin users cannot subscribe to other users' rooms)
146
- * - server-side queryId computation (clients can't hijack queries by colliding ids)
79
+ * Collection subscriptions go through the sync protocol (`sync:subscribe`), installed
80
+ * separately by `installSyncSocketHandlers`.
147
81
  */
148
82
  const installRealtimeSocketHandlers = (socket, options = {}) => {
149
83
  const logInfo = options.logInfo ?? (() => { });
150
84
  const userId = socket.decodedToken?.id;
151
85
  const isAdmin = socket.decodedToken?.admin === true;
152
- // D2: re-derive per event rather than capturing once at install time, so a
153
- // handshake-time-loaded full user (or one refreshed by D1's sweep) is always used.
154
- const currentUser = () => (0, socketUser_1.getSocketUser)(socket);
155
- const counts = { document: 0, model: 0, query: 0 };
156
86
  const joinUserRooms = async () => {
157
87
  if (userId) {
158
88
  await socket.join(`user:${userId}`);
@@ -166,156 +96,19 @@ const installRealtimeSocketHandlers = (socket, options = {}) => {
166
96
  };
167
97
  // Fire-and-forget — there is nothing useful for the caller to await.
168
98
  void joinUserRooms();
169
- socket.on("subscribe:model", async (modelName) => {
170
- if (typeof modelName !== "string" || modelName.length === 0) {
171
- return;
172
- }
173
- if (counts.model >= exports.MAX_MODEL_SUBSCRIPTIONS) {
174
- logInfo(`[realtime] User ${userId} hit model subscription limit`);
175
- return;
176
- }
177
- const entry = (0, registry_2.findRegistryEntryByRoutePath)(modelName);
178
- if (!entry) {
179
- logInfo(`[realtime] User ${userId} denied model subscription: collection "${modelName}" not registered`);
180
- return;
181
- }
182
- // Owner-strategy models fan out via user:{ownerId} — there is no shared model room
183
- // that should be open to all users. Owners receive events through their user room
184
- // automatically; admins can use the admin room to see everything.
185
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
186
- logInfo(`[realtime] User ${userId} denied model subscription for ${modelName}: ` +
187
- "owner strategy restricts model room to admins");
188
- return;
189
- }
190
- if (!(await canSubscribe(entry, "list", currentUser()))) {
191
- logInfo(`[realtime] User ${userId} denied model subscription for ${modelName}: list permission denied`);
192
- return;
193
- }
194
- counts.model += 1;
195
- await socket.join(`model:${modelName}`);
196
- logInfo(`[realtime] User ${userId} subscribed to model:${modelName}`);
197
- });
198
- socket.on("unsubscribe:model", async (modelName) => {
199
- if (typeof modelName === "string" && modelName.length > 0) {
200
- await socket.leave(`model:${modelName}`);
201
- counts.model = Math.max(0, counts.model - 1);
202
- logInfo(`[realtime] User ${userId} unsubscribed from model:${modelName}`);
203
- }
204
- });
205
- socket.on("subscribe:document", async (payload) => {
206
- if (!payload?.collection ||
207
- !payload?.id ||
208
- typeof payload.collection !== "string" ||
209
- typeof payload.id !== "string") {
210
- return;
211
- }
212
- if (counts.document >= exports.MAX_DOCUMENT_SUBSCRIPTIONS) {
213
- logInfo(`[realtime] User ${userId} hit document subscription limit`);
214
- return;
215
- }
216
- const entry = (0, registry_2.findRegistryEntryByRoutePath)(payload.collection);
217
- if (!entry) {
218
- logInfo(`[realtime] User ${userId} denied document subscription: ` +
219
- `collection "${payload.collection}" not registered`);
220
- return;
221
- }
222
- if (!(await canSubscribe(entry, "read", currentUser()))) {
223
- logInfo(`[realtime] User ${userId} denied document subscription for ` +
224
- `${payload.collection}/${payload.id}: read permission denied`);
225
- return;
226
- }
227
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
228
- logInfo(`[realtime] User ${userId} denied document subscription for ` +
229
- `${payload.collection}/${payload.id}: owner strategy requires admin`);
230
- return;
231
- }
232
- counts.document += 1;
233
- const room = `document:${payload.collection}:${payload.id}`;
234
- await socket.join(room);
235
- logInfo(`[realtime] User ${userId} subscribed to ${room}`);
236
- });
237
- socket.on("unsubscribe:document", async (payload) => {
238
- if (payload?.collection && payload?.id) {
239
- const room = `document:${payload.collection}:${payload.id}`;
240
- await socket.leave(room);
241
- counts.document = Math.max(0, counts.document - 1);
242
- logInfo(`[realtime] User ${userId} unsubscribed from ${room}`);
243
- }
244
- });
245
- socket.on("subscribe:query", async (payload) => {
246
- if (!payload?.collection ||
247
- !payload?.query ||
248
- typeof payload.collection !== "string" ||
249
- typeof payload.query !== "object" ||
250
- Array.isArray(payload.query)) {
251
- return;
252
- }
253
- if (counts.query >= exports.MAX_QUERY_SUBSCRIPTIONS) {
254
- logInfo(`[realtime] User ${userId} hit query subscription limit`);
255
- return;
256
- }
257
- const entry = (0, registry_2.findRegistryEntryByRoutePath)(payload.collection);
258
- if (!entry) {
259
- logInfo(`[realtime] User ${userId} denied query subscription: ` +
260
- `collection "${payload.collection}" not registered`);
261
- return;
262
- }
263
- const disallowedField = findDisallowedQueryField(payload.query, entry.options.queryFields ?? []);
264
- if (disallowedField) {
265
- logInfo(`[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
266
- `${disallowedField} is not in queryFields`);
267
- return;
268
- }
269
- let query = await getAuthorizedQuery(entry, { ...payload.query }, currentUser());
270
- if (!query) {
271
- logInfo(`[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
272
- "list permission or query filter denied");
273
- return;
274
- }
275
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
276
- if (!userId) {
277
- return;
278
- }
279
- query = { ...query, ownerId: userId };
280
- }
281
- const queryId = (0, queryStore_1.computeQueryId)(payload.collection, query);
282
- (0, queryStore_1.addQuerySubscription)(socket.id, payload.collection, query, queryId);
283
- counts.query += 1;
284
- await socket.join(`query:${queryId}`);
285
- socket.emit("query:subscribed", {
286
- clientQueryId: payload.queryId,
287
- collection: payload.collection,
288
- queryId,
289
- });
290
- logInfo(`[realtime] User ${userId} subscribed to query:${queryId} on ${payload.collection}`);
291
- });
292
- socket.on("unsubscribe:query", async (payload) => {
293
- if (payload?.queryId) {
294
- (0, queryStore_1.removeQuerySubscription)(socket.id, payload.queryId);
295
- await socket.leave(`query:${payload.queryId}`);
296
- counts.query = Math.max(0, counts.query - 1);
297
- logInfo(`[realtime] User ${userId} unsubscribed from query:${payload.queryId}`);
298
- }
299
- });
300
99
  socket.on("disconnect", () => {
301
- (0, queryStore_1.removeAllSocketQueries)(socket.id);
302
100
  logInfo(`[realtime] User ${userId} disconnected`);
303
101
  });
304
102
  };
305
103
  exports.installRealtimeSocketHandlers = installRealtimeSocketHandlers;
306
104
  /**
307
- * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
105
+ * TerrenoPlugin that hosts Socket.io and the MongoDB change stream watcher for
106
+ * `@terreno/syncdb`.
308
107
  *
309
108
  * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
310
- * sets up JWT and/or Better Auth authentication for socket connections, manages room subscriptions
311
- * (model, document, and query rooms), and starts a change stream watcher that
312
- * emits events to connected clients.
313
- *
314
- * ## Subscription types
315
- *
316
- * - **Model rooms**: `subscribe:model` / `unsubscribe:model` — receive all events for a collection
317
- * - **Document rooms**: `subscribe:document` / `unsubscribe:document` — receive events for a single document
318
- * - **Query rooms**: `subscribe:query` / `unsubscribe:query` — receive events matching a MongoDB query
109
+ * sets up JWT and/or Better Auth authentication for socket connections, installs the
110
+ * sync protocol handlers (`sync:subscribe` / `sync:mutate`), and starts a change stream
111
+ * watcher that emits `sync:delta` events for models registered with `sync`.
319
112
  *
320
113
  * @example
321
114
  * ```typescript
@@ -323,7 +116,8 @@ exports.installRealtimeSocketHandlers = installRealtimeSocketHandlers;
323
116
  * userModel: User,
324
117
  * realtime: { debug: true },
325
118
  * })
326
- * .register(todoRouter) // todoRouter has realtime config
119
+ * .register(todoRouter) // todoRouter has a `sync` config
120
+ * .register(new SyncApp())
327
121
  * .start();
328
122
  * ```
329
123
  */
@@ -1,52 +1,8 @@
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
- /**
8
- * Configuration for real-time sync on a modelRouter.
9
- * Determines which CRUD methods emit WebSocket events and how they are routed.
10
- *
11
- * @deprecated Removed in Terreno 58. Use `sync` on modelRouter with `@terreno/syncdb`.
12
- * `RealtimeApp` remains required for sync sockets.
13
- */
14
- export interface RealtimeConfig {
15
- /** Which CRUD methods should emit real-time sync events */
16
- methods: Array<"create" | "update" | "delete">;
17
- /**
18
- * Strategy for determining which Socket.io rooms receive events.
19
- * - 'owner': emit to `user:{doc.ownerId}` room
20
- * - 'model': emit to `model:{modelName}` room (clients must subscribe)
21
- * - 'broadcast': emit to all authenticated sockets
22
- * - function: custom room resolver returning room name(s)
23
- */
24
- roomStrategy: "owner" | "model" | "broadcast" | ((doc: Record<string, unknown>, method: string, req: express.Request) => string[]);
25
- /** Custom serializer for real-time events. Falls back to the modelRouter responseHandler. */
26
- realtimeResponseHandler?: (doc: Record<string, unknown>, method: string) => unknown;
27
- }
28
- /**
29
- * A real-time sync event emitted to clients via WebSocket.
30
- *
31
- * @deprecated Removed in Terreno 58 with modelRouter `realtime` and the RTK
32
- * cache-patching helpers. Syncdb uses `sync:delta` events instead.
33
- */
34
- export interface RealtimeEvent {
35
- /** Mongoose model name (e.g. "Todo") */
36
- model: string;
37
- /** Route path used as tag type (e.g. "todos") */
38
- collection: string;
39
- /** The CRUD method that triggered this event */
40
- method: "create" | "update" | "delete";
41
- /** Document ID */
42
- id: string;
43
- /** Serialized document data (omitted for hard deletes) */
44
- data?: unknown;
45
- /** Fields that were updated (for update events from change streams) */
46
- updatedFields?: string[];
47
- /** Epoch milliseconds when the event was generated */
48
- timestamp: number;
49
- }
50
6
  /**
51
7
  * Configuration for the MongoDB change stream watcher.
52
8
  */
@@ -145,23 +101,3 @@ export interface RealtimeAppOptions {
145
101
  */
146
102
  startChangeStreamWatcher?: typeof startChangeStreamWatcher;
147
103
  }
148
- /**
149
- * Payload sent by the client to subscribe to a single document's changes.
150
- */
151
- export interface DocumentSubscription {
152
- /** Collection tag (e.g. "todos") */
153
- collection: string;
154
- /** Document ID */
155
- id: string;
156
- }
157
- /**
158
- * Payload sent by the client to subscribe to a query-filtered list.
159
- */
160
- export interface QuerySubscription {
161
- /** Collection tag (e.g. "todos") */
162
- collection: string;
163
- /** MongoDB-style query filter (e.g. {completed: false}) */
164
- query: Record<string, unknown>;
165
- /** Client-provided queryId (ignored — server computes a canonical ID) */
166
- queryId?: string;
167
- }
@@ -58,6 +58,18 @@ exports.isExecutorConflictError = isExecutorConflictError;
58
58
  * populated — see the module doc comment for the hook compatibility contract.
59
59
  */
60
60
  const stubRequest = (user) => ({ user });
61
+ /**
62
+ * The request a hook sees for an update or delete of `id`. Over HTTP it is the real request. Over
63
+ * sync it is a stub (or the socket's `{user}` object) with no `params`, so `params.id` is filled
64
+ * in, as in the REST routes: hooks that read `req.params.id` must work over sync too.
65
+ */
66
+ const requestForId = ({ id, req, user, }) => {
67
+ const request = req ?? stubRequest(user);
68
+ if (request.params === undefined) {
69
+ request.params = { id };
70
+ }
71
+ return request;
72
+ };
61
73
  /**
62
74
  * True for the Mongoose error thrown when an `optimisticConcurrency` save matched no
63
75
  * document (its `__v` filter failed) — i.e. another write landed since the load.
@@ -320,7 +332,7 @@ exports.runPostCreate = runPostCreate;
320
332
  * handler; concurrency conflicts throw `ExecutorConflictError` (409) carrying the server doc.
321
333
  */
322
334
  const executeUpdate = async ({ model, options, user, id, body, concurrencyCheck, existingDoc, req, skipPermissionChecks, skipPostHooks, writeModelName, }) => {
323
- const request = req ?? stubRequest(user);
335
+ const request = requestForId({ id, req, user });
324
336
  if (!skipPermissionChecks &&
325
337
  !(await (0, permissions_1.checkPermissions)("update", options.permissions.update, user))) {
326
338
  throw new errors_1.APIError({
@@ -533,7 +545,7 @@ exports.runPostUpdate = runPostUpdate;
533
545
  * APIErrors with the same statuses/titles as the REST handler.
534
546
  */
535
547
  const executeDelete = async ({ model, options, user, id, existingDoc, req, skipPermissionChecks, skipPostHooks, }) => {
536
- const request = req ?? stubRequest(user);
548
+ const request = requestForId({ id, req, user });
537
549
  if (!skipPermissionChecks &&
538
550
  !(await (0, permissions_1.checkPermissions)("delete", options.permissions.delete, user))) {
539
551
  throw new errors_1.APIError({
@@ -14,7 +14,7 @@ import type { SyncAppOptions } from "./routes";
14
14
  * permission for that model is required as well. Confirms with
15
15
  * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
16
16
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
17
- * legacy realtime rooms so the two event families never overlap.
17
+ * per-user rooms joined at connect.
18
18
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
19
19
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
20
20
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
@@ -42,7 +42,7 @@ const organizationIdFromPayload = (payload) => {
42
42
  * permission for that model is required as well. Confirms with
43
43
  * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
44
44
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
45
- * legacy realtime rooms so the two event families never overlap.
45
+ * per-user rooms joined at connect.
46
46
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
47
47
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
48
48
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
@@ -8,6 +8,7 @@ import { type ConfigurationAppOptions, type ConfigurationModelLike } from "./con
8
8
  import { type AddRoutes, type AuthOptions } from "./expressServer";
9
9
  import { type GitHubAuthOptions } from "./githubAuth";
10
10
  import { type LoggingOptions } from "./logger";
11
+ import { type McpRequestLogAppOption } from "./mcp/adminTracking";
11
12
  import { type McpOAuthAppOption } from "./mcp/oauthMetadata";
12
13
  import { type McpServiceTokensAppOption } from "./mcp/serviceTokens";
13
14
  import { type StartupMigrationsOption } from "./migrations/runner";
@@ -73,11 +74,13 @@ export interface TerrenoAppOptions {
73
74
  */
74
75
  configureApp?: AddRoutes;
75
76
  /**
76
- * Optional HTTP rate limiting. Omitted or `undefined` leaves the limiter off
77
- * (Terreno 58 will default it on). Pass `{}` or `{store, limits, trustProxy}`
78
- * to enable. See [Rate limiting](../how-to/rate-limiting.md).
77
+ * HTTP rate limiting. On by default: omitted or `undefined` mounts the limiter with the
78
+ * memory store and default limits (auth 20 / 15 min, api 600 / 15 min). Pass
79
+ * `{store, limits, trustProxy, skip}` to configure it (`{}` is the same as omitting it).
80
+ * Pass `false` to turn it off. On Cloud Run pass `trustProxy: 1` so unauthenticated
81
+ * traffic keys by client IP. See [Rate limiting](../how-to/rate-limiting.md).
79
82
  */
80
- rateLimit?: RateLimitOptions;
83
+ rateLimit?: RateLimitOptions | false;
81
84
  /**
82
85
  * Opt-in personal MCP service tokens. `true` is `{enabled: true}`. When enabled,
83
86
  * mounts `/mcp/service-tokens` and accepts `Authorization: Bearer mcp_…` on `/mcp`.
@@ -92,6 +95,17 @@ export interface TerrenoAppOptions {
92
95
  * [Enable MCP OAuth](../how-to/enable-mcp-oauth.md).
93
96
  */
94
97
  mcpOAuth?: McpOAuthAppOption;
98
+ /**
99
+ * Opt-in log of MCP tool calls for the admin panel. `true` keeps rows 30 days. Rows hold
100
+ * metadata only (tool, user, credential ids, duration, outcome, error class), never tool
101
+ * arguments, results, or error text. See [Manage MCP from the admin panel](../how-to/manage-mcp-in-admin.md).
102
+ */
103
+ mcpRequestLog?: McpRequestLogAppOption;
104
+ /**
105
+ * Opt-in MCP tool registry. When true, every tool is recorded in `McpToolSetting` at startup,
106
+ * and tools an admin switches off are hidden from `tools/list` and rejected by `tools/call`.
107
+ */
108
+ mcpToolSettings?: boolean;
95
109
  /**
96
110
  * Versioned MongoDB migrations. `runOnStart` defaults to false. When true, wet `up`
97
111
  * runs after listen and `ensureSyncIndexes`. Production still requires
@@ -260,7 +274,7 @@ export declare class TerrenoApp {
260
274
  * Build the Express application without starting the server.
261
275
  *
262
276
  * Configures the complete middleware stack including:
263
- * - CORS, JSON parsing, JWT decode, optional HTTP rate limiting, auth routes
277
+ * - CORS, JSON parsing, JWT decode, HTTP rate limiting (unless `rateLimit: false`), auth routes
264
278
  * - Better Auth session (when BetterAuthApp is registered) before the limiter
265
279
  * - Logging, Sentry, OpenAPI, model routers and plugins
266
280
  * - Error handling middleware
@@ -54,6 +54,7 @@ const errors_1 = require("./errors");
54
54
  const expressServer_1 = require("./expressServer");
55
55
  const githubAuth_1 = require("./githubAuth");
56
56
  const logger_1 = require("./logger");
57
+ const adminTracking_1 = require("./mcp/adminTracking");
57
58
  const oauth_1 = require("./mcp/oauth");
58
59
  const oauthMetadata_1 = require("./mcp/oauthMetadata");
59
60
  const server_1 = require("./mcp/server");
@@ -260,7 +261,7 @@ class TerrenoApp {
260
261
  * Build the Express application without starting the server.
261
262
  *
262
263
  * Configures the complete middleware stack including:
263
- * - CORS, JSON parsing, JWT decode, optional HTTP rate limiting, auth routes
264
+ * - CORS, JSON parsing, JWT decode, HTTP rate limiting (unless `rateLimit: false`), auth routes
264
265
  * - Better Auth session (when BetterAuthApp is registered) before the limiter
265
266
  * - Logging, Sentry, OpenAPI, model routers and plugins
266
267
  * - Error handling middleware
@@ -323,10 +324,12 @@ class TerrenoApp {
323
324
  app.use((0, betterAuthSetup_1.createBetterAuthSessionMiddleware)(auth, options.userModel));
324
325
  betterAuthForLimiter.markSessionMiddlewareMounted?.();
325
326
  }
326
- if (options.rateLimit) {
327
- const betterAuthBasePath = options.rateLimit.betterAuthBasePath ?? betterAuthForLimiter?.getBetterAuthBasePath?.();
327
+ // Rate limiting is on unless the app passes `rateLimit: false`.
328
+ const rateLimitOptions = options.rateLimit === false ? undefined : (options.rateLimit ?? {});
329
+ if (rateLimitOptions) {
330
+ const betterAuthBasePath = rateLimitOptions.betterAuthBasePath ?? betterAuthForLimiter?.getBetterAuthBasePath?.();
328
331
  const rateLimit = {
329
- ...options.rateLimit,
332
+ ...rateLimitOptions,
330
333
  ...(betterAuthBasePath ? { betterAuthBasePath } : {}),
331
334
  };
332
335
  (0, applyTrustProxy_1.applyRateLimitTrustProxy)(app, rateLimit);
@@ -338,7 +341,17 @@ class TerrenoApp {
338
341
  options.authOptions = {};
339
342
  }
340
343
  const authOptions = options.authOptions;
341
- (0, auth_1.addAuthRoutes)(app, options.userModel, authOptions);
344
+ // The OpenAPI generator walks the router stack on each /openapi.json request, so the
345
+ // instance can exist before it is mounted below. Auth routes need it to document themselves.
346
+ const oapi = (0, index_1.default)({
347
+ info: {
348
+ description: "Generated docs from an Express api",
349
+ title: "Express Application",
350
+ version: "1.0.0",
351
+ },
352
+ openapi: "3.0.0",
353
+ });
354
+ (0, auth_1.addAuthRoutes)(app, options.userModel, authOptions, oapi);
342
355
  if (options.logRequests !== false && options.loggingOptions?.logRequests !== false) {
343
356
  app.use(expressServer_1.logRequests);
344
357
  }
@@ -370,14 +383,6 @@ class TerrenoApp {
370
383
  app.use(openApiCompat_1.openApiCompatMiddleware);
371
384
  app.use(openApiEtag_1.openApiEtagMiddleware);
372
385
  app.use(middleware_1.jsonResponseRequestIdMiddleware);
373
- const oapi = (0, index_1.default)({
374
- info: {
375
- description: "Generated docs from an Express api",
376
- title: "Express Application",
377
- version: "1.0.0",
378
- },
379
- openapi: "3.0.0",
380
- });
381
386
  app.use(oapi);
382
387
  if (process.env.ENABLE_SWAGGER === "true") {
383
388
  app.use("/swagger", oapi.swaggerui());
@@ -430,6 +435,8 @@ class TerrenoApp {
430
435
  betterAuth,
431
436
  mcpOAuth,
432
437
  mcpServiceTokens: mcpServiceTokens.enabled,
438
+ requestLog: (0, adminTracking_1.resolveMcpRequestLogOption)(options.mcpRequestLog),
439
+ toolSettings: options.mcpToolSettings === true,
433
440
  userModel: options.userModel,
434
441
  });
435
442
  if (options.configureApp) {
@@ -437,7 +444,7 @@ class TerrenoApp {
437
444
  }
438
445
  // /auth/me must be registered after plugins so that session middleware
439
446
  // (e.g. Better Auth) has a chance to populate req.user first.
440
- (0, auth_1.addMeRoutes)(app, options.userModel, options.authOptions, options.accessControl);
447
+ (0, auth_1.addMeRoutes)(app, options.userModel, options.authOptions, options.accessControl, oapi);
441
448
  Sentry.setupExpressErrorHandler(app);
442
449
  // Error middleware
443
450
  app.use(errors_1.apiUnauthorizedMiddleware);
@@ -1,5 +1,8 @@
1
1
  import mongoose, { type Model } from "mongoose";
2
+ import type { UserModel as AuthUserModel } from "../auth";
2
3
  export interface User {
4
+ _id: mongoose.Types.ObjectId;
5
+ id: string;
3
6
  admin: boolean;
4
7
  name?: string;
5
8
  username: string;
@@ -56,35 +59,27 @@ export interface RequiredField {
56
59
  name: string;
57
60
  about?: string;
58
61
  }
59
- export declare const UserModel: mongoose.Model<User, {}, {}, {}, mongoose.Document<unknown, {}, User, {}, mongoose.DefaultSchemaOptions> & User & {
62
+ export declare const UserModel: mongoose.Model<User, {}, {}, {}, mongoose.Document<unknown, {}, User, {}, mongoose.DefaultSchemaOptions> & User & Required<{
60
63
  _id: mongoose.Types.ObjectId;
61
- } & {
64
+ }> & {
62
65
  __v: number;
63
- } & {
64
- id: string;
65
66
  }, any, User>;
66
- export declare const SuperUserModel: mongoose.Model<User & SuperUser, {}, {}, {
67
- id: string;
68
- }, mongoose.Document<unknown, {}, User & SuperUser, {
69
- id: string;
70
- }, mongoose.DefaultSchemaOptions> & Omit<User & SuperUser & {
67
+ /**
68
+ * `UserModel` typed as the auth `UserModel` for `setupAuth`, `TerrenoApp({userModel})`, and
69
+ * friends. passport-local-mongoose adds the statics at runtime but ships no types, and the auth
70
+ * `User._id` uses mongoose's schema `ObjectId` type, so the models are not structurally related.
71
+ */
72
+ export declare const authUserModel: AuthUserModel;
73
+ export declare const SuperUserModel: mongoose.Model<User & SuperUser, {}, {}, {}, mongoose.Document<unknown, {}, User & SuperUser, {}, mongoose.DefaultSchemaOptions> & User & SuperUser & Required<{
71
74
  _id: mongoose.Types.ObjectId;
72
- } & {
75
+ }> & {
73
76
  __v: number;
74
- }, "id"> & mongoose.HydratedDocumentOverrides<{
75
- id: string;
76
- }>, any, User & SuperUser>;
77
- export declare const StaffUserModel: mongoose.Model<User & StaffUser, {}, {}, {
78
- id: string;
79
- }, mongoose.Document<unknown, {}, User & StaffUser, {
80
- id: string;
81
- }, mongoose.DefaultSchemaOptions> & Omit<User & StaffUser & {
77
+ }, any, User & SuperUser>;
78
+ export declare const StaffUserModel: mongoose.Model<User & StaffUser, {}, {}, {}, mongoose.Document<unknown, {}, User & StaffUser, {}, mongoose.DefaultSchemaOptions> & User & StaffUser & Required<{
82
79
  _id: mongoose.Types.ObjectId;
83
- } & {
80
+ }> & {
84
81
  __v: number;
85
- }, "id"> & mongoose.HydratedDocumentOverrides<{
86
- id: string;
87
- }>, any, User & StaffUser>;
82
+ }, any, User & StaffUser>;
88
83
  export declare const FoodModel: Model<Food>;
89
84
  export declare const RequiredModel: mongoose.Model<RequiredField, {}, {}, {}, mongoose.Document<unknown, {}, RequiredField, {}, mongoose.DefaultSchemaOptions> & RequiredField & {
90
85
  _id: mongoose.Types.ObjectId;
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.RequiredModel = exports.FoodModel = exports.StaffUserModel = exports.SuperUserModel = exports.UserModel = void 0;
6
+ exports.RequiredModel = exports.FoodModel = exports.StaffUserModel = exports.SuperUserModel = exports.authUserModel = exports.UserModel = void 0;
7
7
  const mongoose_1 = require("mongoose");
8
8
  const passport_local_mongoose_1 = __importDefault(require("passport-local-mongoose"));
9
9
  const plugins_1 = require("../plugins");
@@ -47,6 +47,12 @@ userSchema.methods.postCreate = async function (body) {
47
47
  return this.save();
48
48
  };
49
49
  exports.UserModel = (0, mongoose_1.model)("User", userSchema);
50
+ /**
51
+ * `UserModel` typed as the auth `UserModel` for `setupAuth`, `TerrenoApp({userModel})`, and
52
+ * friends. passport-local-mongoose adds the statics at runtime but ships no types, and the auth
53
+ * `User._id` uses mongoose's schema `ObjectId` type, so the models are not structurally related.
54
+ */
55
+ exports.authUserModel = exports.UserModel;
50
56
  const superUserSchema = new mongoose_1.Schema({
51
57
  superTitle: { description: "The super user's title", required: true, type: String },
52
58
  });