@terreno/api 57.21.0 → 58.0.0-beta.2

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 (121) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +1 -1
  3. package/dist/api.d.ts +0 -13
  4. package/dist/api.js +0 -9
  5. package/dist/auth.d.ts +3 -2
  6. package/dist/auth.js +95 -5
  7. package/dist/authRecovery.d.ts +2 -1
  8. package/dist/authRecovery.js +35 -17
  9. package/dist/collectionRegistry.d.ts +3 -4
  10. package/dist/collectionRegistry.js +0 -1
  11. package/dist/consentApp.d.ts +1 -1
  12. package/dist/consentApp.js +58 -2
  13. package/dist/index.d.ts +4 -5
  14. package/dist/index.js +8 -20
  15. package/dist/mcp/adminTracking.js +1 -1
  16. package/dist/mcp/serviceTokens.d.ts +21 -1
  17. package/dist/mcp/serviceTokens.js +159 -183
  18. package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
  19. package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
  20. package/dist/models/mcpRequestLog.js +1 -1
  21. package/dist/models/mcpServiceToken.js +36 -4
  22. package/dist/openApiBuilder.d.ts +4 -0
  23. package/dist/openApiBuilder.js +2 -0
  24. package/dist/rbac/realtimeAccess.d.ts +5 -4
  25. package/dist/rbac/realtimeAccess.js +17 -64
  26. package/dist/realtime/changeStreamWatcher.d.ts +8 -63
  27. package/dist/realtime/changeStreamWatcher.js +32 -391
  28. package/dist/realtime/realtimeApp.d.ts +14 -27
  29. package/dist/realtime/realtimeApp.js +14 -220
  30. package/dist/realtime/types.d.ts +0 -64
  31. package/dist/sync/entityIds.d.ts +14 -0
  32. package/dist/sync/entityIds.js +17 -0
  33. package/dist/sync/executors.js +14 -2
  34. package/dist/sync/models.d.ts +1 -0
  35. package/dist/sync/models.js +4 -0
  36. package/dist/sync/mutationHandler.js +51 -2
  37. package/dist/sync/routes.js +12 -17
  38. package/dist/sync/socketHandlers.d.ts +1 -1
  39. package/dist/sync/socketHandlers.js +1 -1
  40. package/dist/sync/types.d.ts +8 -0
  41. package/dist/terrenoApp.d.ts +7 -5
  42. package/dist/terrenoApp.js +18 -14
  43. package/dist/tests/openApiResponseSchema.d.ts +39 -0
  44. package/dist/tests/openApiResponseSchema.js +56 -0
  45. package/dist/tests.d.ts +1 -0
  46. package/dist/tests.js +4 -1
  47. package/dist/types/mcpAdmin.d.ts +1 -1
  48. package/dist/types/mcpServiceToken.d.ts +7 -4
  49. package/dist/versionCheckPlugin.d.ts +1 -1
  50. package/dist/versionCheckPlugin.js +25 -2
  51. package/package.json +17 -6
  52. package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
  53. package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
  54. package/src/__tests__/openApiResponseSchema.test.ts +148 -0
  55. package/src/__tests__/versionCheckPlugin.test.ts +72 -0
  56. package/src/api.test.ts +9 -7
  57. package/src/api.ts +0 -24
  58. package/src/auth.ts +116 -5
  59. package/src/authOpenApi.test.ts +316 -0
  60. package/src/authRecovery.ts +47 -19
  61. package/src/betterAuthOAuthHandoff.test.ts +13 -5
  62. package/src/collectionRegistry.ts +3 -5
  63. package/src/consentApp.test.ts +98 -0
  64. package/src/consentApp.ts +67 -2
  65. package/src/index.ts +6 -28
  66. package/src/mcp/actionTools.test.ts +2 -2
  67. package/src/mcp/adminTracking.ts +1 -1
  68. package/src/mcp/auth.test.ts +7 -3
  69. package/src/mcp/oauth.test.ts +12 -12
  70. package/src/mcp/serviceTokens.sync.test.ts +230 -0
  71. package/src/mcp/serviceTokens.test.ts +112 -61
  72. package/src/mcp/serviceTokens.ts +193 -212
  73. package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
  74. package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
  75. package/src/models/mcpRequestLog.ts +1 -1
  76. package/src/models/mcpServiceToken.test.ts +52 -5
  77. package/src/models/mcpServiceToken.ts +51 -14
  78. package/src/openApiBuilder.test.ts +34 -1
  79. package/src/openApiBuilder.ts +5 -0
  80. package/src/rateLimit/rateLimit.test.ts +25 -10
  81. package/src/rbac/realtimeAccess.test.ts +20 -172
  82. package/src/rbac/realtimeAccess.ts +17 -82
  83. package/src/realtime/changeStreamWatcher.ts +43 -506
  84. package/src/realtime/realtime.test.ts +205 -2545
  85. package/src/realtime/realtimeApp.ts +16 -295
  86. package/src/realtime/types.ts +0 -72
  87. package/src/sync/entityIds.ts +18 -0
  88. package/src/sync/executors.test.ts +28 -0
  89. package/src/sync/executors.ts +23 -2
  90. package/src/sync/models.ts +6 -0
  91. package/src/sync/mutationHandler.test.ts +84 -0
  92. package/src/sync/mutationHandler.ts +57 -2
  93. package/src/sync/routes.ts +12 -17
  94. package/src/sync/socketHandlers.ts +1 -1
  95. package/src/sync/syncRoutes.test.ts +8 -4
  96. package/src/sync/syncSocket.test.ts +77 -113
  97. package/src/sync/types.ts +9 -0
  98. package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
  99. package/src/terrenoApp.ts +24 -18
  100. package/src/tests/openApiResponseSchema.ts +104 -0
  101. package/src/tests.ts +7 -0
  102. package/src/types/mcpAdmin.ts +1 -1
  103. package/src/types/mcpServiceToken.ts +7 -4
  104. package/src/versionCheckPlugin.ts +41 -2
  105. package/biome.jsonc +0 -22
  106. package/bunfig.toml +0 -10
  107. package/bunfig.unit.toml +0 -3
  108. package/dist/realtime/deprecation.d.ts +0 -13
  109. package/dist/realtime/deprecation.js +0 -31
  110. package/dist/realtime/queryStore.d.ts +0 -37
  111. package/dist/realtime/queryStore.js +0 -103
  112. package/dist/realtime/registry.d.ts +0 -15
  113. package/dist/realtime/registry.js +0 -52
  114. package/e2e/smoke.ts +0 -193
  115. package/src/realtime/deprecation.test.ts +0 -60
  116. package/src/realtime/deprecation.ts +0 -33
  117. package/src/realtime/queryStore.ts +0 -122
  118. package/src/realtime/registry.ts +0 -84
  119. package/tsconfig.json +0 -19
  120. package/tsconfig.typecheck.json +0 -14
  121. package/tsconfig.typedoc.json +0 -13
@@ -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
- }
@@ -0,0 +1,14 @@
1
+ import type mongoose from "mongoose";
2
+ /**
3
+ * True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
4
+ * accepts any 12-character string as raw ObjectId bytes.
5
+ */
6
+ export declare const isObjectIdHex: (id: unknown) => id is string;
7
+ /**
8
+ * True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
9
+ * ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
10
+ * any id shape (syncdb's UUID default).
11
+ */
12
+ export declare const isObjectIdKeyed: (model: {
13
+ schema?: mongoose.Schema;
14
+ }) => boolean;
@@ -0,0 +1,17 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.isObjectIdKeyed = exports.isObjectIdHex = void 0;
4
+ const OBJECT_ID_HEX = /^[0-9a-fA-F]{24}$/;
5
+ /**
6
+ * True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
7
+ * accepts any 12-character string as raw ObjectId bytes.
8
+ */
9
+ const isObjectIdHex = (id) => typeof id === "string" && OBJECT_ID_HEX.test(id);
10
+ exports.isObjectIdHex = isObjectIdHex;
11
+ /**
12
+ * True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
13
+ * ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
14
+ * any id shape (syncdb's UUID default).
15
+ */
16
+ const isObjectIdKeyed = (model) => model.schema?.path("_id")?.instance === "ObjectId";
17
+ exports.isObjectIdKeyed = isObjectIdKeyed;
@@ -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({
@@ -169,6 +169,7 @@ export interface SyncMutationDocument {
169
169
  collectionTag?: string;
170
170
  status: SyncMutationStatus;
171
171
  nackCode?: string;
172
+ nackReason?: string;
172
173
  resultId?: string;
173
174
  resultSeq?: number;
174
175
  error?: string;
@@ -362,6 +362,10 @@ const syncMutationSchema = new mongoose_1.Schema({
362
362
  description: "Nack code recorded for rejected mutations (conflict/unauthorized/validation/error)",
363
363
  type: String,
364
364
  },
365
+ nackReason: {
366
+ description: "Why a validation nack rejected the mutation's entity id (id_collision/invalid_id)",
367
+ type: String,
368
+ },
365
369
  resultId: {
366
370
  description: "The affected document id, recorded when the mutation is applied or conflicts; a " +
367
371
  "duplicate delivery of a conflict re-serializes the live document from this id",
@@ -13,6 +13,7 @@ const permissions_1 = require("../permissions");
13
13
  const plugins_1 = require("../plugins");
14
14
  const adminBroadcastScope_1 = require("./adminBroadcastScope");
15
15
  const adminWindowMutation_1 = require("./adminWindowMutation");
16
+ const entityIds_1 = require("./entityIds");
16
17
  const executors_1 = require("./executors");
17
18
  const models_1 = require("./models");
18
19
  const registry_1 = require("./registry");
@@ -191,6 +192,7 @@ const outcomeFromLedgerRow = async ({ entry, mutation, request, row, scopeResolv
191
192
  code: row.nackCode ?? "error",
192
193
  message: row.error,
193
194
  mutationId: row.mutationId,
195
+ ...(row.nackReason ? { reason: row.nackReason } : {}),
194
196
  });
195
197
  }
196
198
  return undefined;
@@ -281,6 +283,21 @@ const isE11000Error = (error) => {
281
283
  const wrapped = candidate?.error;
282
284
  return wrapped?.code === 11000;
283
285
  };
286
+ /** The `APIError.code` a create gets when its client-minted `_id` already exists. */
287
+ const ID_COLLISION_CODE = "sync-id-collision";
288
+ /**
289
+ * True when an E11000 (raw, or wrapped by the executor) is on the `_id` index rather than
290
+ * some other unique index the model declares.
291
+ */
292
+ const isIdDuplicateKeyError = (error) => {
293
+ if (!isE11000Error(error)) {
294
+ return false;
295
+ }
296
+ const candidate = error;
297
+ const raw = [candidate, candidate.error, candidate.cause].find((value) => value?.code === 11000);
298
+ const keys = Object.keys(raw?.keyPattern ?? raw?.keyValue ?? {});
299
+ return keys.length === 1 && keys[0] === "_id";
300
+ };
284
301
  /**
285
302
  * C5 (FIX 6): true when every key/value in `data` (the mutation's own
286
303
  * intended write) is already present on `doc` — used alongside the
@@ -364,6 +381,7 @@ const finalizeNack = async ({ claimedId, entry, error, mutation, request, }) =>
364
381
  }
365
382
  const code = nackCodeForError(error);
366
383
  const message = (0, errors_1.isAPIError)(error) ? error.title : String(error);
384
+ const reason = (0, errors_1.isAPIError)(error) && error.code === ID_COLLISION_CODE ? "id_collision" : undefined;
367
385
  if (code === "error") {
368
386
  logger_1.logger.warn("[sync] Mutation failed unexpectedly", {
369
387
  collection: mutation.collection,
@@ -380,8 +398,15 @@ const finalizeNack = async ({ claimedId, entry, error, mutation, request, }) =>
380
398
  await models_1.SyncMutation.deleteOne({ _id: claimedId });
381
399
  return makeNack({ code, message, mutationId: mutation.mutationId });
382
400
  }
383
- await models_1.SyncMutation.updateOne({ _id: claimedId }, { $set: { error: message, nackCode: code, status: "failed" } });
384
- return makeNack({ code, message, mutationId: mutation.mutationId });
401
+ await models_1.SyncMutation.updateOne({ _id: claimedId }, {
402
+ $set: {
403
+ error: message,
404
+ nackCode: code,
405
+ status: "failed",
406
+ ...(reason ? { nackReason: reason } : {}),
407
+ },
408
+ });
409
+ return makeNack({ code, message, mutationId: mutation.mutationId, ...(reason ? { reason } : {}) });
385
410
  };
386
411
  /**
387
412
  * C5 (FIX 6): read the doc back and report it as the ack for an ALREADY-APPLIED write —
@@ -541,6 +566,18 @@ const applyClaimedMutationInContext = async ({ claimed, entry, mutation, request
541
566
  return { ack: { id: resultId, mutationId, seq: resultSeq }, type: "ack" };
542
567
  }
543
568
  }
569
+ // Another document already holds the client-minted `_id`. The unique index kept it
570
+ // from being overwritten; reject the create for good (validation is terminal on the
571
+ // client) without naming the holder, which may belong to another user.
572
+ if (isIdDuplicateKeyError(createError)) {
573
+ throw new errors_1.APIError({
574
+ cause: createError,
575
+ code: ID_COLLISION_CODE,
576
+ disableExternalErrorTracking: true,
577
+ status: 400,
578
+ title: "Entity id already exists",
579
+ });
580
+ }
544
581
  throw createError;
545
582
  }
546
583
  }
@@ -688,6 +725,18 @@ const applySyncMutation = async ({ user, mutation, req, scopeResolver, syncOptio
688
725
  if (!entry) {
689
726
  return validationNack(`Unknown sync collection: ${mutation.collection}`);
690
727
  }
728
+ // An ObjectId-keyed collection can only hold 24-hex ids. Rejecting anything else here
729
+ // keeps a client-minted UUID from reaching Mongoose as a CastError, which would nack as a
730
+ // retryable `error` and replay forever.
731
+ const model = mongoose_1.default.models[entry.modelName];
732
+ if (mutation.id && model && (0, entityIds_1.isObjectIdKeyed)(model) && !(0, entityIds_1.isObjectIdHex)(mutation.id)) {
733
+ return makeNack({
734
+ code: "validation",
735
+ message: `${mutation.collection} ids must be 24-character hex ObjectIds`,
736
+ mutationId,
737
+ reason: "invalid_id",
738
+ });
739
+ }
691
740
  const request = req ?? { user };
692
741
  // Atomic claim: inserting the pending row first means exactly one delivery applies.
693
742
  let claimed;
@@ -14,6 +14,7 @@ const permissions_1 = require("../permissions");
14
14
  const plugins_1 = require("../plugins");
15
15
  const adminBroadcastScope_1 = require("./adminBroadcastScope");
16
16
  const adminWindowAccess_1 = require("./adminWindowAccess");
17
+ const entityIds_1 = require("./entityIds");
17
18
  const models_1 = require("./models");
18
19
  const registry_1 = require("./registry");
19
20
  const serialize_1 = require("./serialize");
@@ -162,18 +163,17 @@ const parseNonNegativeInt = (raw, name, fallback) => {
162
163
  };
163
164
  /**
164
165
  * Task 9.14: the legacy cursor is a raw `_id` string, so it must be compared in the
165
- * model's OWN `_id` BSON type. Synced models are designed around client-minted string
166
+ * model's OWN `_id` BSON type. Synced models default to client-minted string
166
167
  * `_id`s: casting those to `ObjectId` either throws (non-hex ids) or — worse — silently
167
168
  * compares across BSON types and matches nothing, so the legacy stratum reported itself
168
169
  * exhausted after one page and the remaining documents were never bootstrapped.
169
170
  * Only ObjectId-keyed models get the cast; a malformed cursor for one is a 400, not a 500.
170
171
  */
171
172
  const legacyCursorClause = ({ model, legacyCursorIn, }) => {
172
- const idInstance = model.schema?.path("_id")?.instance;
173
- if (idInstance !== "ObjectId") {
173
+ if (!(0, entityIds_1.isObjectIdKeyed)(model)) {
174
174
  return { _id: { $gt: legacyCursorIn } };
175
175
  }
176
- if (!mongoose_1.default.isValidObjectId(legacyCursorIn)) {
176
+ if (!(0, entityIds_1.isObjectIdHex)(legacyCursorIn)) {
177
177
  throw new errors_1.APIError({ status: 400, title: `Invalid legacyCursor: ${legacyCursorIn}` });
178
178
  }
179
179
  return { _id: { $gt: new mongoose_1.default.Types.ObjectId(legacyCursorIn) } };
@@ -322,23 +322,18 @@ const pageSeqStratum = async ({ model, scopeFilter, cursor, limit, frontierSeq,
322
322
  exports.MAX_ENTITY_FETCH = 100;
323
323
  /**
324
324
  * Task 9.27: `_id: {$in: ids}` leaves the cast to Mongoose, so one non-hex id against an
325
- * ObjectId-keyed model threw a CastError that surfaced as a 500 for what is purely bad
326
- * caller input. Validate up front and name the offending ids in a 400. Models with
327
- * client-minted string `_id`s (the syncdb default, see `legacyCursorClause`) take any shape.
325
+ * ObjectId-keyed model threw a CastError that surfaced as a 500. A non-hex id cannot name a
326
+ * document of such a model, so it is dropped and comes back absent, which is the true answer.
327
+ * Failing the whole request instead would wedge a client's repair batch: a create the server
328
+ * rejected for a bad id is queued for repair under that id, and every other id in the batch
329
+ * would never load. Models with client-minted string `_id`s (see `legacyCursorClause`) take
330
+ * any shape.
328
331
  */
329
332
  const castEntityIds = ({ model, ids, }) => {
330
- const idInstance = model.schema?.path("_id")?.instance;
331
- if (idInstance !== "ObjectId") {
333
+ if (!(0, entityIds_1.isObjectIdKeyed)(model)) {
332
334
  return ids;
333
335
  }
334
- const invalid = ids.filter((id) => !mongoose_1.default.isValidObjectId(id));
335
- if (invalid.length > 0) {
336
- throw new errors_1.APIError({
337
- status: 400,
338
- title: `Invalid ids for ${model.modelName}: ${invalid.join(",")}`,
339
- });
340
- }
341
- return ids.map((id) => new mongoose_1.default.Types.ObjectId(id));
336
+ return ids.filter(entityIds_1.isObjectIdHex).map((id) => new mongoose_1.default.Types.ObjectId(id));
342
337
  };
343
338
  /**
344
339
  * Serve one snapshot page for one stream: membership/permission checks, frontier and
@@ -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}`.
@@ -178,6 +178,12 @@ export interface SyncAck {
178
178
  warning?: string;
179
179
  }
180
180
  export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
181
+ /**
182
+ * Why a `validation` nack rejected a mutation, when the cause is the entity id itself.
183
+ * `id_collision`: a create named an `_id` that already exists. `invalid_id`: the id is not a
184
+ * 24-character hex ObjectId for an ObjectId-keyed collection.
185
+ */
186
+ export type SyncNackReason = "id_collision" | "invalid_id";
181
187
  /** Rejected mutation. Conflict nacks carry the canonical server document. */
182
188
  export interface SyncNack {
183
189
  mutationId: string;
@@ -187,6 +193,8 @@ export interface SyncNack {
187
193
  /** The server document's current `_syncSeq` (conflict nacks). */
188
194
  serverSeq?: number;
189
195
  message?: string;
196
+ /** Set on `validation` nacks caused by the entity id (see {@link SyncNackReason}). */
197
+ reason?: SyncNackReason;
190
198
  /**
191
199
  * Minimum time (ms) the client should wait before retrying, filled by the
192
200
  * server with the remaining rate-limit window (`rate_limited` nacks only).