@terreno/api 57.21.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.
- package/CHANGELOG.md +43 -0
- package/README.md +1 -1
- package/biome.jsonc +2 -2
- package/dist/api.d.ts +0 -13
- package/dist/api.js +0 -9
- package/dist/auth.d.ts +3 -2
- package/dist/auth.js +95 -5
- package/dist/authRecovery.d.ts +2 -1
- package/dist/authRecovery.js +35 -17
- package/dist/collectionRegistry.d.ts +3 -4
- package/dist/collectionRegistry.js +0 -1
- package/dist/consentApp.d.ts +1 -1
- package/dist/consentApp.js +58 -2
- package/dist/index.d.ts +4 -5
- package/dist/index.js +8 -20
- package/dist/mcp/adminTracking.js +1 -1
- package/dist/mcp/serviceTokens.d.ts +21 -1
- package/dist/mcp/serviceTokens.js +159 -183
- package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
- package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
- package/dist/models/mcpRequestLog.js +1 -1
- package/dist/models/mcpServiceToken.js +36 -4
- package/dist/openApiBuilder.d.ts +4 -0
- package/dist/openApiBuilder.js +2 -0
- package/dist/rbac/realtimeAccess.d.ts +5 -4
- package/dist/rbac/realtimeAccess.js +17 -64
- package/dist/realtime/changeStreamWatcher.d.ts +8 -63
- package/dist/realtime/changeStreamWatcher.js +32 -391
- package/dist/realtime/realtimeApp.d.ts +14 -27
- package/dist/realtime/realtimeApp.js +14 -220
- package/dist/realtime/types.d.ts +0 -64
- package/dist/sync/executors.js +14 -2
- package/dist/sync/socketHandlers.d.ts +1 -1
- package/dist/sync/socketHandlers.js +1 -1
- package/dist/terrenoApp.d.ts +7 -5
- package/dist/terrenoApp.js +18 -14
- package/dist/tests/openApiResponseSchema.d.ts +39 -0
- package/dist/tests/openApiResponseSchema.js +56 -0
- package/dist/tests.d.ts +1 -0
- package/dist/tests.js +4 -1
- package/dist/types/mcpAdmin.d.ts +1 -1
- package/dist/types/mcpServiceToken.d.ts +7 -4
- package/dist/versionCheckPlugin.d.ts +1 -1
- package/dist/versionCheckPlugin.js +25 -2
- package/package.json +10 -6
- package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
- package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
- package/src/__tests__/openApiResponseSchema.test.ts +148 -0
- package/src/__tests__/versionCheckPlugin.test.ts +72 -0
- package/src/api.test.ts +9 -7
- package/src/api.ts +0 -24
- package/src/auth.ts +116 -5
- package/src/authOpenApi.test.ts +316 -0
- package/src/authRecovery.ts +47 -19
- package/src/betterAuthOAuthHandoff.test.ts +13 -5
- package/src/collectionRegistry.ts +3 -5
- package/src/consentApp.test.ts +98 -0
- package/src/consentApp.ts +67 -2
- package/src/index.ts +6 -28
- package/src/mcp/actionTools.test.ts +2 -2
- package/src/mcp/adminTracking.ts +1 -1
- package/src/mcp/auth.test.ts +7 -3
- package/src/mcp/oauth.test.ts +12 -12
- package/src/mcp/serviceTokens.sync.test.ts +230 -0
- package/src/mcp/serviceTokens.test.ts +112 -61
- package/src/mcp/serviceTokens.ts +193 -212
- package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
- package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
- package/src/models/mcpRequestLog.ts +1 -1
- package/src/models/mcpServiceToken.test.ts +52 -5
- package/src/models/mcpServiceToken.ts +51 -14
- package/src/openApiBuilder.test.ts +34 -1
- package/src/openApiBuilder.ts +5 -0
- package/src/rateLimit/rateLimit.test.ts +25 -10
- package/src/rbac/realtimeAccess.test.ts +20 -172
- package/src/rbac/realtimeAccess.ts +17 -82
- package/src/realtime/changeStreamWatcher.ts +43 -506
- package/src/realtime/realtime.test.ts +205 -2545
- package/src/realtime/realtimeApp.ts +16 -295
- package/src/realtime/types.ts +0 -72
- package/src/sync/executors.test.ts +28 -0
- package/src/sync/executors.ts +23 -2
- package/src/sync/socketHandlers.ts +1 -1
- package/src/sync/syncSocket.test.ts +77 -113
- package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
- package/src/terrenoApp.ts +24 -18
- package/src/tests/openApiResponseSchema.ts +104 -0
- package/src/tests.ts +7 -0
- package/src/types/mcpAdmin.ts +1 -1
- package/src/types/mcpServiceToken.ts +7 -4
- package/src/versionCheckPlugin.ts +41 -2
- package/dist/realtime/deprecation.d.ts +0 -13
- package/dist/realtime/deprecation.js +0 -31
- package/dist/realtime/queryStore.d.ts +0 -37
- package/dist/realtime/queryStore.js +0 -103
- package/dist/realtime/registry.d.ts +0 -15
- package/dist/realtime/registry.js +0 -52
- package/src/realtime/deprecation.test.ts +0 -60
- package/src/realtime/deprecation.ts +0 -33
- package/src/realtime/queryStore.ts +0 -122
- 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 =
|
|
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
|
|
139
|
-
*
|
|
140
|
-
* (no real Socket.io /
|
|
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
|
-
*
|
|
143
|
-
*
|
|
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
|
|
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,
|
|
311
|
-
*
|
|
312
|
-
* emits events
|
|
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
|
|
119
|
+
* .register(todoRouter) // todoRouter has a `sync` config
|
|
120
|
+
* .register(new SyncApp())
|
|
327
121
|
* .start();
|
|
328
122
|
* ```
|
|
329
123
|
*/
|
package/dist/realtime/types.d.ts
CHANGED
|
@@ -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
|
-
}
|
package/dist/sync/executors.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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}`.
|
package/dist/terrenoApp.d.ts
CHANGED
|
@@ -74,11 +74,13 @@ export interface TerrenoAppOptions {
|
|
|
74
74
|
*/
|
|
75
75
|
configureApp?: AddRoutes;
|
|
76
76
|
/**
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
* to
|
|
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).
|
|
80
82
|
*/
|
|
81
|
-
rateLimit?: RateLimitOptions;
|
|
83
|
+
rateLimit?: RateLimitOptions | false;
|
|
82
84
|
/**
|
|
83
85
|
* Opt-in personal MCP service tokens. `true` is `{enabled: true}`. When enabled,
|
|
84
86
|
* mounts `/mcp/service-tokens` and accepts `Authorization: Bearer mcp_…` on `/mcp`.
|
|
@@ -272,7 +274,7 @@ export declare class TerrenoApp {
|
|
|
272
274
|
* Build the Express application without starting the server.
|
|
273
275
|
*
|
|
274
276
|
* Configures the complete middleware stack including:
|
|
275
|
-
* - CORS, JSON parsing, JWT decode,
|
|
277
|
+
* - CORS, JSON parsing, JWT decode, HTTP rate limiting (unless `rateLimit: false`), auth routes
|
|
276
278
|
* - Better Auth session (when BetterAuthApp is registered) before the limiter
|
|
277
279
|
* - Logging, Sentry, OpenAPI, model routers and plugins
|
|
278
280
|
* - Error handling middleware
|
package/dist/terrenoApp.js
CHANGED
|
@@ -261,7 +261,7 @@ class TerrenoApp {
|
|
|
261
261
|
* Build the Express application without starting the server.
|
|
262
262
|
*
|
|
263
263
|
* Configures the complete middleware stack including:
|
|
264
|
-
* - CORS, JSON parsing, JWT decode,
|
|
264
|
+
* - CORS, JSON parsing, JWT decode, HTTP rate limiting (unless `rateLimit: false`), auth routes
|
|
265
265
|
* - Better Auth session (when BetterAuthApp is registered) before the limiter
|
|
266
266
|
* - Logging, Sentry, OpenAPI, model routers and plugins
|
|
267
267
|
* - Error handling middleware
|
|
@@ -324,10 +324,12 @@ class TerrenoApp {
|
|
|
324
324
|
app.use((0, betterAuthSetup_1.createBetterAuthSessionMiddleware)(auth, options.userModel));
|
|
325
325
|
betterAuthForLimiter.markSessionMiddlewareMounted?.();
|
|
326
326
|
}
|
|
327
|
-
|
|
328
|
-
|
|
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?.();
|
|
329
331
|
const rateLimit = {
|
|
330
|
-
...
|
|
332
|
+
...rateLimitOptions,
|
|
331
333
|
...(betterAuthBasePath ? { betterAuthBasePath } : {}),
|
|
332
334
|
};
|
|
333
335
|
(0, applyTrustProxy_1.applyRateLimitTrustProxy)(app, rateLimit);
|
|
@@ -339,7 +341,17 @@ class TerrenoApp {
|
|
|
339
341
|
options.authOptions = {};
|
|
340
342
|
}
|
|
341
343
|
const authOptions = options.authOptions;
|
|
342
|
-
|
|
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);
|
|
343
355
|
if (options.logRequests !== false && options.loggingOptions?.logRequests !== false) {
|
|
344
356
|
app.use(expressServer_1.logRequests);
|
|
345
357
|
}
|
|
@@ -371,14 +383,6 @@ class TerrenoApp {
|
|
|
371
383
|
app.use(openApiCompat_1.openApiCompatMiddleware);
|
|
372
384
|
app.use(openApiEtag_1.openApiEtagMiddleware);
|
|
373
385
|
app.use(middleware_1.jsonResponseRequestIdMiddleware);
|
|
374
|
-
const oapi = (0, index_1.default)({
|
|
375
|
-
info: {
|
|
376
|
-
description: "Generated docs from an Express api",
|
|
377
|
-
title: "Express Application",
|
|
378
|
-
version: "1.0.0",
|
|
379
|
-
},
|
|
380
|
-
openapi: "3.0.0",
|
|
381
|
-
});
|
|
382
386
|
app.use(oapi);
|
|
383
387
|
if (process.env.ENABLE_SWAGGER === "true") {
|
|
384
388
|
app.use("/swagger", oapi.swaggerui());
|
|
@@ -440,7 +444,7 @@ class TerrenoApp {
|
|
|
440
444
|
}
|
|
441
445
|
// /auth/me must be registered after plugins so that session middleware
|
|
442
446
|
// (e.g. Better Auth) has a chance to populate req.user first.
|
|
443
|
-
(0, auth_1.addMeRoutes)(app, options.userModel, options.authOptions, options.accessControl);
|
|
447
|
+
(0, auth_1.addMeRoutes)(app, options.userModel, options.authOptions, options.accessControl, oapi);
|
|
444
448
|
Sentry.setupExpressErrorHandler(app);
|
|
445
449
|
// Error middleware
|
|
446
450
|
app.use(errors_1.apiUnauthorizedMiddleware);
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/** The subset of an OpenAPI document needed to look up and validate a response schema. */
|
|
2
|
+
export interface OpenApiResponseSpec {
|
|
3
|
+
components?: Record<string, unknown>;
|
|
4
|
+
paths?: Record<string, Record<string, OpenApiResponseOperation | undefined> | undefined>;
|
|
5
|
+
}
|
|
6
|
+
interface OpenApiResponseOperation {
|
|
7
|
+
responses?: Record<string, {
|
|
8
|
+
content?: Record<string, {
|
|
9
|
+
schema?: unknown;
|
|
10
|
+
}>;
|
|
11
|
+
} | undefined>;
|
|
12
|
+
}
|
|
13
|
+
export interface DocumentedResponseOptions {
|
|
14
|
+
/** The `/openapi.json` document the app serves. */
|
|
15
|
+
spec: OpenApiResponseSpec;
|
|
16
|
+
/** The OpenAPI path template, e.g. `/announcements/{id}/click`. */
|
|
17
|
+
path: string;
|
|
18
|
+
/** HTTP method, any case. */
|
|
19
|
+
method: string;
|
|
20
|
+
/** The real response: its status picks the documented response, its body is validated. */
|
|
21
|
+
response: {
|
|
22
|
+
status: number;
|
|
23
|
+
body: unknown;
|
|
24
|
+
};
|
|
25
|
+
/** Response media type to validate against. Defaults to `application/json`. */
|
|
26
|
+
contentType?: string;
|
|
27
|
+
}
|
|
28
|
+
export interface DocumentedResponseResult {
|
|
29
|
+
valid: boolean;
|
|
30
|
+
errors: string[];
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Validates a real response body against the response schema `/openapi.json` documents for it,
|
|
34
|
+
* resolving `#/components/...` references against the same spec.
|
|
35
|
+
*/
|
|
36
|
+
export declare const validateDocumentedResponse: ({ contentType, method, path, response, spec, }: DocumentedResponseOptions) => DocumentedResponseResult;
|
|
37
|
+
/** Throws with every schema violation when a response body does not match its documentation. */
|
|
38
|
+
export declare const expectDocumentedResponse: (options: DocumentedResponseOptions) => void;
|
|
39
|
+
export {};
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.expectDocumentedResponse = exports.validateDocumentedResponse = void 0;
|
|
7
|
+
const ajv_1 = __importDefault(require("ajv"));
|
|
8
|
+
const ajv_formats_1 = __importDefault(require("ajv-formats"));
|
|
9
|
+
/** Raised when a route or response is undocumented, or a body breaks its documented schema. */
|
|
10
|
+
class DocumentedResponseError extends Error {
|
|
11
|
+
name = "DocumentedResponseError";
|
|
12
|
+
}
|
|
13
|
+
const findResponseSchema = ({ contentType, method, path, spec, status, }) => {
|
|
14
|
+
const label = `${method.toUpperCase()} ${path}`;
|
|
15
|
+
const operation = spec.paths?.[path]?.[method.toLowerCase()];
|
|
16
|
+
if (!operation) {
|
|
17
|
+
throw new DocumentedResponseError(`${label} is not documented in the OpenAPI spec`);
|
|
18
|
+
}
|
|
19
|
+
const documented = operation.responses?.[String(status)];
|
|
20
|
+
if (!documented) {
|
|
21
|
+
const statuses = Object.keys(operation.responses ?? {}).join(", ") || "none";
|
|
22
|
+
throw new DocumentedResponseError(`${label} has no documented ${status} response (documented: ${statuses})`);
|
|
23
|
+
}
|
|
24
|
+
const schema = documented.content?.[contentType]?.schema;
|
|
25
|
+
if (!schema) {
|
|
26
|
+
throw new DocumentedResponseError(`${label} ${status} response has no ${contentType} schema`);
|
|
27
|
+
}
|
|
28
|
+
return schema;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Validates a real response body against the response schema `/openapi.json` documents for it,
|
|
32
|
+
* resolving `#/components/...` references against the same spec.
|
|
33
|
+
*/
|
|
34
|
+
const validateDocumentedResponse = ({ contentType = "application/json", method, path, response, spec, }) => {
|
|
35
|
+
const schema = findResponseSchema({ contentType, method, path, spec, status: response.status });
|
|
36
|
+
const ajv = new ajv_1.default({ allErrors: true, strict: false });
|
|
37
|
+
(0, ajv_formats_1.default)(ajv);
|
|
38
|
+
// Wrapping keeps `#/components/...` refs resolvable from the root of the compiled schema.
|
|
39
|
+
const validate = ajv.compile({ allOf: [schema], components: spec.components ?? {} });
|
|
40
|
+
if (validate(response.body)) {
|
|
41
|
+
return { errors: [], valid: true };
|
|
42
|
+
}
|
|
43
|
+
const errors = (validate.errors ?? []).map((error) => `${error.instancePath || "(root)"} ${error.message ?? "is invalid"}`);
|
|
44
|
+
return { errors, valid: false };
|
|
45
|
+
};
|
|
46
|
+
exports.validateDocumentedResponse = validateDocumentedResponse;
|
|
47
|
+
/** Throws with every schema violation when a response body does not match its documentation. */
|
|
48
|
+
const expectDocumentedResponse = (options) => {
|
|
49
|
+
const { errors, valid } = (0, exports.validateDocumentedResponse)(options);
|
|
50
|
+
if (valid) {
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
const label = `${options.method.toUpperCase()} ${options.path} ${options.response.status}`;
|
|
54
|
+
throw new DocumentedResponseError(`${label} response does not match its OpenAPI schema:\n- ${errors.join("\n- ")}\nBody: ${JSON.stringify(options.response.body)}`);
|
|
55
|
+
};
|
|
56
|
+
exports.expectDocumentedResponse = expectDocumentedResponse;
|
package/dist/tests.d.ts
CHANGED
|
@@ -12,3 +12,4 @@ export { createTestData, FoodModel, loadTestDataFromCache, RequiredModel, StaffU
|
|
|
12
12
|
export declare const getBaseServer: () => Express;
|
|
13
13
|
export declare const authAsUser: (app: express.Application, type: "admin" | "notAdmin") => Promise<TestAgent>;
|
|
14
14
|
export { loadTestData } from "./tests/mongoTestSetup";
|
|
15
|
+
export { type DocumentedResponseOptions, type DocumentedResponseResult, expectDocumentedResponse, type OpenApiResponseSpec, validateDocumentedResponse, } from "./tests/openApiResponseSchema";
|
package/dist/tests.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.loadTestData = exports.authAsUser = exports.getBaseServer = exports.UserModel = exports.setupTestData = exports.setupTestCache = exports.setupDb = exports.SuperUserModel = exports.StaffUserModel = exports.RequiredModel = exports.loadTestDataFromCache = exports.FoodModel = exports.createTestData = exports.authUserModel = void 0;
|
|
3
|
+
exports.validateDocumentedResponse = exports.expectDocumentedResponse = exports.loadTestData = exports.authAsUser = exports.getBaseServer = exports.UserModel = exports.setupTestData = exports.setupTestCache = exports.setupDb = exports.SuperUserModel = exports.StaffUserModel = exports.RequiredModel = exports.loadTestDataFromCache = exports.FoodModel = exports.createTestData = exports.authUserModel = void 0;
|
|
4
4
|
const test_1 = require("@terreno/test");
|
|
5
5
|
const openApiCompat_1 = require("./openApiCompat");
|
|
6
6
|
const createTestData_1 = require("./tests/createTestData");
|
|
@@ -33,3 +33,6 @@ const authAsUser = async (app, type) => {
|
|
|
33
33
|
exports.authAsUser = authAsUser;
|
|
34
34
|
var mongoTestSetup_2 = require("./tests/mongoTestSetup");
|
|
35
35
|
Object.defineProperty(exports, "loadTestData", { enumerable: true, get: function () { return mongoTestSetup_2.loadTestData; } });
|
|
36
|
+
var openApiResponseSchema_1 = require("./tests/openApiResponseSchema");
|
|
37
|
+
Object.defineProperty(exports, "expectDocumentedResponse", { enumerable: true, get: function () { return openApiResponseSchema_1.expectDocumentedResponse; } });
|
|
38
|
+
Object.defineProperty(exports, "validateDocumentedResponse", { enumerable: true, get: function () { return openApiResponseSchema_1.validateDocumentedResponse; } });
|
package/dist/types/mcpAdmin.d.ts
CHANGED
|
@@ -18,7 +18,7 @@ export interface McpRequestLogDocument extends mongoose.Document {
|
|
|
18
18
|
oauthClientId?: string;
|
|
19
19
|
oauthFamilyId?: string;
|
|
20
20
|
outcome: McpRequestLogOutcome;
|
|
21
|
-
serviceTokenId?:
|
|
21
|
+
serviceTokenId?: string;
|
|
22
22
|
toolName: string;
|
|
23
23
|
updated: Date;
|
|
24
24
|
userId?: mongoose.Types.ObjectId;
|