@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
@@ -15,6 +15,7 @@ import {
15
15
  prepareAdminWindowMutation,
16
16
  withAdminWindowMutationRequestContext,
17
17
  } from "./adminWindowMutation";
18
+ import {isObjectIdHex, isObjectIdKeyed} from "./entityIds";
18
19
  import {
19
20
  executeCreate,
20
21
  executeDelete,
@@ -35,6 +36,7 @@ import type {
35
36
  SyncMutateRequest,
36
37
  SyncNack,
37
38
  SyncNackCode,
39
+ SyncNackReason,
38
40
  } from "./types";
39
41
 
40
42
  export type SyncMutationScopeResolver = (
@@ -314,6 +316,7 @@ const outcomeFromLedgerRow = async ({
314
316
  code: (row.nackCode as SyncNackCode) ?? "error",
315
317
  message: row.error,
316
318
  mutationId: row.mutationId,
319
+ ...(row.nackReason ? {reason: row.nackReason as SyncNackReason} : {}),
317
320
  });
318
321
  }
319
322
  return undefined;
@@ -431,6 +434,25 @@ const isE11000Error = (error: unknown): boolean => {
431
434
  return wrapped?.code === 11000;
432
435
  };
433
436
 
437
+ /** The `APIError.code` a create gets when its client-minted `_id` already exists. */
438
+ const ID_COLLISION_CODE = "sync-id-collision";
439
+
440
+ /**
441
+ * True when an E11000 (raw, or wrapped by the executor) is on the `_id` index rather than
442
+ * some other unique index the model declares.
443
+ */
444
+ const isIdDuplicateKeyError = (error: unknown): boolean => {
445
+ if (!isE11000Error(error)) {
446
+ return false;
447
+ }
448
+ const candidate = error as {cause?: unknown; error?: unknown; keyPattern?: unknown};
449
+ const raw = [candidate, candidate.error, candidate.cause].find(
450
+ (value) => (value as {code?: number} | undefined)?.code === 11000
451
+ ) as {keyPattern?: Record<string, unknown>; keyValue?: Record<string, unknown>} | undefined;
452
+ const keys = Object.keys(raw?.keyPattern ?? raw?.keyValue ?? {});
453
+ return keys.length === 1 && keys[0] === "_id";
454
+ };
455
+
434
456
  /**
435
457
  * C5 (FIX 6): true when every key/value in `data` (the mutation's own
436
458
  * intended write) is already present on `doc` — used alongside the
@@ -535,6 +557,8 @@ const finalizeNack = async ({
535
557
 
536
558
  const code = nackCodeForError(error);
537
559
  const message = isAPIError(error) ? error.title : String(error);
560
+ const reason: SyncNackReason | undefined =
561
+ isAPIError(error) && error.code === ID_COLLISION_CODE ? "id_collision" : undefined;
538
562
  if (code === "error") {
539
563
  logger.warn("[sync] Mutation failed unexpectedly", {
540
564
  collection: mutation.collection,
@@ -553,9 +577,16 @@ const finalizeNack = async ({
553
577
  }
554
578
  await SyncMutation.updateOne(
555
579
  {_id: claimedId},
556
- {$set: {error: message, nackCode: code, status: "failed"}}
580
+ {
581
+ $set: {
582
+ error: message,
583
+ nackCode: code,
584
+ status: "failed",
585
+ ...(reason ? {nackReason: reason} : {}),
586
+ },
587
+ }
557
588
  );
558
- return makeNack({code, message, mutationId: mutation.mutationId});
589
+ return makeNack({code, message, mutationId: mutation.mutationId, ...(reason ? {reason} : {})});
559
590
  };
560
591
 
561
592
  /**
@@ -777,6 +808,18 @@ const applyClaimedMutationInContext = async ({
777
808
  return {ack: {id: resultId, mutationId, seq: resultSeq}, type: "ack"};
778
809
  }
779
810
  }
811
+ // Another document already holds the client-minted `_id`. The unique index kept it
812
+ // from being overwritten; reject the create for good (validation is terminal on the
813
+ // client) without naming the holder, which may belong to another user.
814
+ if (isIdDuplicateKeyError(createError)) {
815
+ throw new APIError({
816
+ cause: createError,
817
+ code: ID_COLLISION_CODE,
818
+ disableExternalErrorTracking: true,
819
+ status: 400,
820
+ title: "Entity id already exists",
821
+ });
822
+ }
780
823
  throw createError;
781
824
  }
782
825
  } else if (effectiveMutation.operation === "update") {
@@ -946,6 +989,18 @@ export const applySyncMutation = async ({
946
989
  if (!entry) {
947
990
  return validationNack(`Unknown sync collection: ${mutation.collection}`);
948
991
  }
992
+ // An ObjectId-keyed collection can only hold 24-hex ids. Rejecting anything else here
993
+ // keeps a client-minted UUID from reaching Mongoose as a CastError, which would nack as a
994
+ // retryable `error` and replay forever.
995
+ const model = mongoose.models[entry.modelName];
996
+ if (mutation.id && model && isObjectIdKeyed(model) && !isObjectIdHex(mutation.id)) {
997
+ return makeNack({
998
+ code: "validation",
999
+ message: `${mutation.collection} ids must be 24-character hex ObjectIds`,
1000
+ mutationId,
1001
+ reason: "invalid_id",
1002
+ });
1003
+ }
949
1004
 
950
1005
  const request = req ?? ({user} as unknown as express.Request);
951
1006
 
@@ -13,6 +13,7 @@ import {
13
13
  resolveAdminBroadcastQueryFilter,
14
14
  } from "./adminBroadcastScope";
15
15
  import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
16
+ import {isObjectIdHex, isObjectIdKeyed} from "./entityIds";
16
17
  import {
17
18
  computeStableFrontier,
18
19
  getCompactedThroughSeq,
@@ -256,7 +257,7 @@ const parseNonNegativeInt = (raw: unknown, name: string, fallback: number): numb
256
257
 
257
258
  /**
258
259
  * Task 9.14: the legacy cursor is a raw `_id` string, so it must be compared in the
259
- * model's OWN `_id` BSON type. Synced models are designed around client-minted string
260
+ * model's OWN `_id` BSON type. Synced models default to client-minted string
260
261
  * `_id`s: casting those to `ObjectId` either throws (non-hex ids) or — worse — silently
261
262
  * compares across BSON types and matches nothing, so the legacy stratum reported itself
262
263
  * exhausted after one page and the remaining documents were never bootstrapped.
@@ -269,11 +270,10 @@ const legacyCursorClause = ({
269
270
  model: SyncedModel;
270
271
  legacyCursorIn: string;
271
272
  }): Record<string, unknown> => {
272
- const idInstance = (model.schema?.path("_id") as {instance?: string} | undefined)?.instance;
273
- if (idInstance !== "ObjectId") {
273
+ if (!isObjectIdKeyed(model)) {
274
274
  return {_id: {$gt: legacyCursorIn}};
275
275
  }
276
- if (!mongoose.isValidObjectId(legacyCursorIn)) {
276
+ if (!isObjectIdHex(legacyCursorIn)) {
277
277
  throw new APIError({status: 400, title: `Invalid legacyCursor: ${legacyCursorIn}`});
278
278
  }
279
279
  return {_id: {$gt: new mongoose.Types.ObjectId(legacyCursorIn)}};
@@ -473,9 +473,12 @@ export const MAX_ENTITY_FETCH = 100;
473
473
 
474
474
  /**
475
475
  * Task 9.27: `_id: {$in: ids}` leaves the cast to Mongoose, so one non-hex id against an
476
- * ObjectId-keyed model threw a CastError that surfaced as a 500 for what is purely bad
477
- * caller input. Validate up front and name the offending ids in a 400. Models with
478
- * client-minted string `_id`s (the syncdb default, see `legacyCursorClause`) take any shape.
476
+ * ObjectId-keyed model threw a CastError that surfaced as a 500. A non-hex id cannot name a
477
+ * document of such a model, so it is dropped and comes back absent, which is the true answer.
478
+ * Failing the whole request instead would wedge a client's repair batch: a create the server
479
+ * rejected for a bad id is queued for repair under that id, and every other id in the batch
480
+ * would never load. Models with client-minted string `_id`s (see `legacyCursorClause`) take
481
+ * any shape.
479
482
  */
480
483
  const castEntityIds = ({
481
484
  model,
@@ -484,18 +487,10 @@ const castEntityIds = ({
484
487
  ids: string[];
485
488
  model: SyncedModel;
486
489
  }): (string | mongoose.Types.ObjectId)[] => {
487
- const idInstance = (model.schema?.path("_id") as {instance?: string} | undefined)?.instance;
488
- if (idInstance !== "ObjectId") {
490
+ if (!isObjectIdKeyed(model)) {
489
491
  return ids;
490
492
  }
491
- const invalid = ids.filter((id) => !mongoose.isValidObjectId(id));
492
- if (invalid.length > 0) {
493
- throw new APIError({
494
- status: 400,
495
- title: `Invalid ids for ${model.modelName}: ${invalid.join(",")}`,
496
- });
497
- }
498
- return ids.map((id) => new mongoose.Types.ObjectId(id));
493
+ return ids.filter(isObjectIdHex).map((id) => new mongoose.Types.ObjectId(id));
499
494
  };
500
495
 
501
496
  /**
@@ -64,7 +64,7 @@ const organizationIdFromPayload = (payload: unknown): string | undefined => {
64
64
  * permission for that model is required as well. Confirms with
65
65
  * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
66
66
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
67
- * legacy realtime rooms so the two event families never overlap.
67
+ * per-user rooms joined at connect.
68
68
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
69
69
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
70
70
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
@@ -1021,12 +1021,16 @@ describe("sync routes", () => {
1021
1021
  // Task 9.27(b): bad caller input on the repair-fetch endpoint used to come back as a 500
1022
1022
  // (CastError) or, worse, a truncated 200 the client read as "those entities are gone".
1023
1023
  describe("GET /sync/entities input validation (Task 9.27)", () => {
1024
- it("400s (not 500s) for ids that cannot be cast to the model's _id type", async () => {
1024
+ it("returns ids that cannot be cast to the model's _id type as absent (not a 500)", async () => {
1025
1025
  const doc = await RouteStuffModel.create({name: "real", ownerId: notAdminId});
1026
+ // A rejected client-minted UUID create is queued for repair under that id; it must not
1027
+ // fail the rest of the repair batch.
1026
1028
  const res = await agent
1027
- .get(`/sync/entities?collection=routeStuff&ids=${doc._id},not-an-object-id`)
1028
- .expect(400);
1029
- expect(res.body.title).toMatch(/not-an-object-id/);
1029
+ .get(
1030
+ `/sync/entities?collection=routeStuff&ids=${doc._id},not-an-object-id,${crypto.randomUUID()},abcdefghijkl`
1031
+ )
1032
+ .expect(200);
1033
+ expect(res.body.entities.map((e: SnapshotEntity) => e.id)).toEqual([String(doc._id)]);
1030
1034
  });
1031
1035
 
1032
1036
  it("400s instead of silently truncating an over-cap id list", async () => {
@@ -14,14 +14,13 @@ import mongoose, {type Model, model, Schema} from "mongoose";
14
14
  import type {Server} from "socket.io";
15
15
 
16
16
  import type {ModelRouterOptions} from "../api";
17
+ import {Permissions} from "../permissions";
17
18
  import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
18
19
  import {
19
20
  emitSyncDeltaForChange,
20
21
  startChangeStreamWatcher,
21
22
  stopChangeStreamWatcher,
22
23
  } from "../realtime/changeStreamWatcher";
23
- import {addQuerySubscription, clearQueryStore, computeQueryId} from "../realtime/queryStore";
24
- import {clearRealtimeRegistry, registerRealtime} from "../realtime/registry";
25
24
  import {setupDb} from "../tests";
26
25
  import {defaultResponseHandler} from "../transformers";
27
26
  import {registerAdminBroadcastScope} from "./adminBroadcastScope";
@@ -72,6 +71,29 @@ sockStuffSchema.plugin(createdUpdatedPlugin);
72
71
  sockStuffSchema.plugin(syncPlugin);
73
72
  const SockStuffModel = model<SockStuff>("SockStuff", sockStuffSchema);
74
73
 
74
+ /** Owned through `userId`, with an `ownerId` virtual alias for `Permissions.IsOwner` (as GptHistory). */
75
+ interface SockNote extends IsDeleted {
76
+ _id: string;
77
+ text: string;
78
+ userId: string;
79
+ _syncSeq?: number;
80
+ }
81
+
82
+ const sockNoteSchema = new Schema<SockNote>(
83
+ {
84
+ text: {description: "The note text", required: true, type: String},
85
+ userId: {description: "The user who owns this note", type: String},
86
+ },
87
+ {toJSON: {virtuals: true}, toObject: {virtuals: true}}
88
+ );
89
+ sockNoteSchema.virtual("ownerId").get(function (this: SockNote) {
90
+ return this.userId;
91
+ });
92
+ sockNoteSchema.plugin(isDeletedPlugin);
93
+ sockNoteSchema.plugin(createdUpdatedPlugin);
94
+ sockNoteSchema.plugin(syncPlugin);
95
+ const SockNoteModel = model<SockNote>("SockNote", sockNoteSchema);
96
+
75
97
  interface SockProject extends IsDeleted {
76
98
  _id: string;
77
99
  title: string;
@@ -1126,6 +1148,50 @@ describe("emitSyncDeltaForChange", () => {
1126
1148
  expect((delta.data as Record<string, unknown>).id).toBe("doc-1");
1127
1149
  });
1128
1150
 
1151
+ it("checks read permissions against the model document, so virtual owner fields resolve", async () => {
1152
+ clearSyncRegistry();
1153
+ registerSync({
1154
+ config: {scope: {field: "userId", type: "owner"}},
1155
+ model: SockNoteModel as unknown as Model<unknown>,
1156
+ options: {
1157
+ permissions: {
1158
+ create: [Permissions.IsOwner],
1159
+ delete: [Permissions.IsOwner],
1160
+ list: [Permissions.IsAuthenticated],
1161
+ read: [Permissions.IsOwner],
1162
+ update: [Permissions.IsOwner],
1163
+ },
1164
+ } as unknown as ModelRouterOptions<unknown>,
1165
+ routePath: "/sock/notes",
1166
+ });
1167
+ const entry = findSyncEntryByCollectionTag("sock/notes") as SyncRegistryEntry;
1168
+ const io = makeTrackedIo();
1169
+ io.addSocketToRoom(syncRoomForStream("sock/notes|owner:user1"), {admin: false, id: "user1"});
1170
+ io.addSocketToRoom(syncRoomForStream("sock/notes|owner:user1"), {admin: false, id: "user2"});
1171
+
1172
+ await emitSyncDeltaForChange({
1173
+ change: makeChange({
1174
+ fullDocument: {_id: "note-1", _syncSeq: 3, text: "hi", userId: "user1"},
1175
+ ns: {coll: "socknotes"},
1176
+ operationType: "insert",
1177
+ }),
1178
+ docId: "note-1",
1179
+ entry,
1180
+ io,
1181
+ logDebug: () => {},
1182
+ });
1183
+
1184
+ const deltas = io.emissions.filter((e) => e.event === "sync:delta");
1185
+ expect(deltas.map((e) => e.socketId)).toHaveLength(1);
1186
+ const delta = deltas[0]?.payload as SyncDelta;
1187
+ expect(delta).toMatchObject({
1188
+ collection: "sock/notes",
1189
+ seq: 3,
1190
+ stream: "sock/notes|owner:user1",
1191
+ });
1192
+ expect((delta.data as Record<string, unknown>).text).toBe("hi");
1193
+ });
1194
+
1129
1195
  it("adminBroadcast true: create also emits to {collection}|admin", async () => {
1130
1196
  clearSyncRegistry();
1131
1197
  registerSync({
@@ -1555,7 +1621,7 @@ describe("sync:delta — change stream integration", () => {
1555
1621
  });
1556
1622
 
1557
1623
  beforeEach(async () => {
1558
- clearRealtimeRegistry();
1624
+ clearSyncRegistry();
1559
1625
  registerAll();
1560
1626
  await Promise.all([
1561
1627
  SockStuffModel.collection.deleteMany({}),
@@ -1566,7 +1632,6 @@ describe("sync:delta — change stream integration", () => {
1566
1632
 
1567
1633
  afterEach(async () => {
1568
1634
  await stopChangeStreamWatcher();
1569
- clearRealtimeRegistry();
1570
1635
  clearSyncRegistry();
1571
1636
  });
1572
1637
 
@@ -1673,43 +1738,33 @@ describe("sync:delta — change stream integration", () => {
1673
1738
  expect((create.data as Record<string, unknown>).orgId).toBe("org2");
1674
1739
  });
1675
1740
 
1676
- it("a model with both realtime and sync configs emits both event types", async () => {
1741
+ it("never emits the legacy RTK sync event, even to legacy realtime rooms", async () => {
1677
1742
  if (!replicaSetAvailable) {
1678
1743
  return;
1679
1744
  }
1680
- registerRealtime({
1681
- collectionName: SockStuffModel.collection.collectionName,
1682
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
1683
- modelName: "SockStuff",
1684
- options: permissiveOptions,
1685
- routePath: "/sockStuff",
1686
- });
1687
-
1688
1745
  const io = makeTrackedIo();
1689
1746
  io.addSocketToRoom("model:sockStuff", {admin: true, id: "admin"});
1690
- io.addSocketToRoom(syncRoomForStream("sockStuff|owner:both-user"), {
1747
+ io.addSocketToRoom("authenticated", {admin: true, id: "admin"});
1748
+ io.addSocketToRoom("user:legacy-user", {admin: false, id: "legacy-user"});
1749
+ io.addSocketToRoom(syncRoomForStream("sockStuff|owner:legacy-user"), {
1691
1750
  admin: false,
1692
- id: "both-user",
1751
+ id: "legacy-user",
1693
1752
  });
1694
1753
  await startWatcherAndSettle(io);
1695
1754
 
1696
- const doc = await SockStuffModel.create({name: "both", ownerId: "both-user"});
1755
+ const doc = await SockStuffModel.create({name: "legacy", ownerId: "legacy-user"});
1697
1756
  const docId = String(doc._id);
1698
1757
  await waitForDelta(io, (d) => d.id === docId);
1699
1758
 
1700
- const legacy = io.emissions.filter((e) => {
1701
- const payload = e.payload as {id?: string; method?: string} | undefined;
1702
- return e.event === "sync" && payload?.id === docId && payload?.method === "create";
1703
- });
1704
1759
  const deltas = io.emissions.filter(
1705
1760
  (e) => e.event === "sync:delta" && (e.payload as SyncDelta).id === docId
1706
1761
  );
1707
- expect(legacy.length).toBeGreaterThanOrEqual(1);
1708
1762
  expect(deltas).toHaveLength(1);
1709
1763
  expect((deltas[0].payload as SyncDelta).seq).toBe(1);
1764
+ expect(io.emissions.filter((e) => e.event === "sync")).toHaveLength(0);
1710
1765
  });
1711
1766
 
1712
- it("a sync-only model emits deltas even without a realtime registry entry", async () => {
1767
+ it("a sync model emits deltas through its sync stream room", async () => {
1713
1768
  if (!replicaSetAvailable) {
1714
1769
  return;
1715
1770
  }
@@ -1728,94 +1783,3 @@ describe("sync:delta — change stream integration", () => {
1728
1783
  expect(io.emissions.filter((e) => e.event === "sync")).toHaveLength(0);
1729
1784
  });
1730
1785
  });
1731
-
1732
- // ─────────────────────────────────────────────────────────────────────────────
1733
- // change handler — realtime query fan-out failures stay isolated
1734
- // ─────────────────────────────────────────────────────────────────────────────
1735
-
1736
- describe("change handler isolation", () => {
1737
- let originalDb: typeof mongoose.connection.db;
1738
-
1739
- beforeAll(async () => {
1740
- await setupDb();
1741
- });
1742
-
1743
- beforeEach(() => {
1744
- originalDb = mongoose.connection.db;
1745
- clearRealtimeRegistry();
1746
- clearQueryStore();
1747
- clearSyncRegistry();
1748
- });
1749
-
1750
- afterEach(async () => {
1751
- await stopChangeStreamWatcher();
1752
- (mongoose.connection as unknown as {db: unknown}).db = originalDb;
1753
- clearRealtimeRegistry();
1754
- clearQueryStore();
1755
- clearSyncRegistry();
1756
- });
1757
-
1758
- it("an unevaluable query predicate does not block sync:delta or later query rooms", async () => {
1759
- const listeners = new Map<string, (...args: unknown[]) => unknown>();
1760
- const mockStream = {
1761
- close: async (): Promise<void> => {},
1762
- on(event: string, handler: (...args: unknown[]) => unknown) {
1763
- listeners.set(event, handler);
1764
- return this;
1765
- },
1766
- };
1767
- (mongoose.connection as unknown as {db: unknown}).db = {watch: () => mockStream};
1768
- // One registration carries both surfaces, as modelRouter does for realtime + sync.
1769
- registerSync({
1770
- config: {scope: {type: "owner"}},
1771
- model: SockStuffModel as unknown as Model<unknown>,
1772
- options: {
1773
- ...permissiveOptions,
1774
- realtime: {methods: ["create", "update", "delete"], roomStrategy: "model"},
1775
- },
1776
- routePath: "/sockStuff",
1777
- });
1778
- const poisoned = [{$and: [null]}, {name: {$eq: {toString: 1}}}] as Record<string, unknown>[];
1779
- for (const [index, query] of poisoned.entries()) {
1780
- addQuerySubscription(`attacker-${index}`, "sockStuff", query, `poisoned-${index}`);
1781
- }
1782
- const healthyQueryId = computeQueryId("sockStuff", {name: "poison-check"});
1783
- addQuerySubscription("victim", "sockStuff", {name: "poison-check"}, healthyQueryId);
1784
-
1785
- const io = makeTrackedIo();
1786
- io.addSocketToRoom(`query:${healthyQueryId}`, {admin: true, id: "admin"});
1787
- io.addSocketToRoom(syncRoomForStream("sockStuff|owner:victim-user"), {
1788
- admin: false,
1789
- id: "victim-user",
1790
- });
1791
- startChangeStreamWatcher(io, {}, true);
1792
- const changeHandler = listeners.get("change");
1793
- if (!changeHandler) {
1794
- throw new Error("expected change handler");
1795
- }
1796
-
1797
- await changeHandler(
1798
- makeChange({
1799
- documentKey: {_id: "poison-doc"},
1800
- fullDocument: {
1801
- _id: "poison-doc",
1802
- _syncSeq: 3,
1803
- name: "poison-check",
1804
- ownerId: "victim-user",
1805
- },
1806
- ns: {coll: SockStuffModel.collection.collectionName},
1807
- operationType: "insert",
1808
- })
1809
- );
1810
- await waitForDelta(io, (d) => d.id === "poison-doc", 2000);
1811
-
1812
- const deltas = io.emissions.filter(
1813
- (e) => e.event === "sync:delta" && (e.payload as SyncDelta).id === "poison-doc"
1814
- );
1815
- expect(deltas).toHaveLength(1);
1816
- const healthy = io.emissions.filter(
1817
- (e) => e.event === "sync" && e.room === `query:${healthyQueryId}`
1818
- );
1819
- expect(healthy).toHaveLength(1);
1820
- });
1821
- });
package/src/sync/types.ts CHANGED
@@ -199,6 +199,13 @@ export interface SyncAck {
199
199
 
200
200
  export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
201
201
 
202
+ /**
203
+ * Why a `validation` nack rejected a mutation, when the cause is the entity id itself.
204
+ * `id_collision`: a create named an `_id` that already exists. `invalid_id`: the id is not a
205
+ * 24-character hex ObjectId for an ObjectId-keyed collection.
206
+ */
207
+ export type SyncNackReason = "id_collision" | "invalid_id";
208
+
202
209
  /** Rejected mutation. Conflict nacks carry the canonical server document. */
203
210
  export interface SyncNack {
204
211
  mutationId: string;
@@ -208,6 +215,8 @@ export interface SyncNack {
208
215
  /** The server document's current `_syncSeq` (conflict nacks). */
209
216
  serverSeq?: number;
210
217
  message?: string;
218
+ /** Set on `validation` nacks caused by the entity id (see {@link SyncNackReason}). */
219
+ reason?: SyncNackReason;
211
220
  /**
212
221
  * Minimum time (ms) the client should wait before retrying, filled by the
213
222
  * server with the remaining rate-limit window (`rate_limited` nacks only).
@@ -1,4 +1,4 @@
1
- import {beforeEach, describe, it} from "bun:test";
1
+ import {afterEach, beforeEach, describe, it} from "bun:test";
2
2
  import {assert} from "chai";
3
3
  import mongoose, {model, Schema} from "mongoose";
4
4
  import supertest from "supertest";
@@ -9,6 +9,7 @@ import {clearMCPRegistry} from "./mcp/registry";
9
9
  import {McpServiceToken} from "./models/mcpServiceToken";
10
10
  import {Permissions} from "./permissions";
11
11
  import {createdUpdatedPlugin} from "./plugins";
12
+ import {clearSyncRegistry} from "./sync/registry";
12
13
  import {TerrenoApp} from "./terrenoApp";
13
14
  import {authAsUser, setupDb, UserModel} from "./tests";
14
15
 
@@ -53,11 +54,15 @@ describe("TerrenoApp mcpServiceTokens", () => {
53
54
  beforeEach(async () => {
54
55
  const users = await setupDb();
55
56
  notAdminId = users[1]._id as mongoose.Types.ObjectId;
56
- await McpServiceToken.deleteMany({});
57
+ await McpServiceToken.collection.deleteMany({});
57
58
  await TokenMcpNote.deleteMany({});
58
59
  clearMCPRegistry();
59
60
  });
60
61
 
62
+ afterEach(() => {
63
+ clearSyncRegistry();
64
+ });
65
+
61
66
  it("does not serve token routes or accept mcp_ on /mcp when the flag is off", async () => {
62
67
  const app = new TerrenoApp({
63
68
  skipListen: true,
@@ -89,7 +94,7 @@ describe("TerrenoApp mcpServiceTokens", () => {
89
94
  .build();
90
95
 
91
96
  const agent = await authAsUser(app, "notAdmin");
92
- const created = await agent.post("/mcp/service-tokens").send({name: "Perplexity"});
97
+ const created = await agent.post("/mcp/service-tokens/create").send({name: "Perplexity"});
93
98
 
94
99
  assert.equal(created.status, 200);
95
100
  assert.match(created.body.data.token, /^mcp_[0-9a-f]{64}$/);
@@ -114,7 +119,7 @@ describe("TerrenoApp mcpServiceTokens", () => {
114
119
  }).build();
115
120
 
116
121
  const agent = await authAsUser(app, "notAdmin");
117
- const created = await agent.post("/mcp/service-tokens").send({name: "Named"});
122
+ const created = await agent.post("/mcp/service-tokens/create").send({name: "Named"});
118
123
 
119
124
  assert.equal(created.status, 200);
120
125
  assert.equal(created.body.data.mcpUrl, `${PUBLIC_MCP_URL}/mcp`);
@@ -128,7 +133,10 @@ describe("TerrenoApp mcpServiceTokens", () => {
128
133
  }).build();
129
134
 
130
135
  const res = await supertest(app).get("/openapi.json");
131
- assert.equal(res.body.paths["/mcp/service-tokens"].post.operationId, "createMcpServiceToken");
136
+ assert.equal(
137
+ res.body.paths["/mcp/service-tokens/create"].post.operationId,
138
+ "mcpServiceTokens_create"
139
+ );
132
140
  });
133
141
 
134
142
  it("lets a minted service token call tools as the owner while GET /mcp stays 405", async () => {
@@ -142,7 +150,7 @@ describe("TerrenoApp mcpServiceTokens", () => {
142
150
  .build();
143
151
 
144
152
  const agent = await authAsUser(app, "notAdmin");
145
- const created = await agent.post("/mcp/service-tokens").send({name: "Perplexity probe"});
153
+ const created = await agent.post("/mcp/service-tokens/create").send({name: "Perplexity probe"});
146
154
  const mcpToken = created.body.data.token as string;
147
155
 
148
156
  const jwtCall = await agent
package/src/terrenoApp.ts CHANGED
@@ -130,11 +130,13 @@ export interface TerrenoAppOptions {
130
130
  */
131
131
  configureApp?: AddRoutes;
132
132
  /**
133
- * Optional HTTP rate limiting. Omitted or `undefined` leaves the limiter off
134
- * (Terreno 58 will default it on). Pass `{}` or `{store, limits, trustProxy}`
135
- * to enable. See [Rate limiting](../how-to/rate-limiting.md).
133
+ * HTTP rate limiting. On by default: omitted or `undefined` mounts the limiter with the
134
+ * memory store and default limits (auth 20 / 15 min, api 600 / 15 min). Pass
135
+ * `{store, limits, trustProxy, skip}` to configure it (`{}` is the same as omitting it).
136
+ * Pass `false` to turn it off. On Cloud Run pass `trustProxy: 1` so unauthenticated
137
+ * traffic keys by client IP. See [Rate limiting](../how-to/rate-limiting.md).
136
138
  */
137
- rateLimit?: RateLimitOptions;
139
+ rateLimit?: RateLimitOptions | false;
138
140
  /**
139
141
  * Opt-in personal MCP service tokens. `true` is `{enabled: true}`. When enabled,
140
142
  * mounts `/mcp/service-tokens` and accepts `Authorization: Bearer mcp_…` on `/mcp`.
@@ -371,7 +373,7 @@ export class TerrenoApp {
371
373
  * Build the Express application without starting the server.
372
374
  *
373
375
  * Configures the complete middleware stack including:
374
- * - CORS, JSON parsing, JWT decode, optional HTTP rate limiting, auth routes
376
+ * - CORS, JSON parsing, JWT decode, HTTP rate limiting (unless `rateLimit: false`), auth routes
375
377
  * - Better Auth session (when BetterAuthApp is registered) before the limiter
376
378
  * - Logging, Sentry, OpenAPI, model routers and plugins
377
379
  * - Error handling middleware
@@ -446,11 +448,13 @@ export class TerrenoApp {
446
448
  betterAuthForLimiter.markSessionMiddlewareMounted?.();
447
449
  }
448
450
 
449
- if (options.rateLimit) {
451
+ // Rate limiting is on unless the app passes `rateLimit: false`.
452
+ const rateLimitOptions = options.rateLimit === false ? undefined : (options.rateLimit ?? {});
453
+ if (rateLimitOptions) {
450
454
  const betterAuthBasePath =
451
- options.rateLimit.betterAuthBasePath ?? betterAuthForLimiter?.getBetterAuthBasePath?.();
455
+ rateLimitOptions.betterAuthBasePath ?? betterAuthForLimiter?.getBetterAuthBasePath?.();
452
456
  const rateLimit = {
453
- ...options.rateLimit,
457
+ ...rateLimitOptions,
454
458
  ...(betterAuthBasePath ? {betterAuthBasePath} : {}),
455
459
  };
456
460
  applyRateLimitTrustProxy(app, rateLimit);
@@ -464,7 +468,17 @@ export class TerrenoApp {
464
468
  options.authOptions = {};
465
469
  }
466
470
  const authOptions = options.authOptions;
467
- addAuthRoutes(app, options.userModel, authOptions);
471
+ // The OpenAPI generator walks the router stack on each /openapi.json request, so the
472
+ // instance can exist before it is mounted below. Auth routes need it to document themselves.
473
+ const oapi = openapi({
474
+ info: {
475
+ description: "Generated docs from an Express api",
476
+ title: "Express Application",
477
+ version: "1.0.0",
478
+ },
479
+ openapi: "3.0.0",
480
+ });
481
+ addAuthRoutes(app, options.userModel, authOptions, oapi);
468
482
 
469
483
  if (options.logRequests !== false && options.loggingOptions?.logRequests !== false) {
470
484
  app.use(logRequests);
@@ -500,14 +514,6 @@ export class TerrenoApp {
500
514
  app.use(openApiCompatMiddleware);
501
515
  app.use(openApiEtagMiddleware);
502
516
  app.use(jsonResponseRequestIdMiddleware);
503
- const oapi = openapi({
504
- info: {
505
- description: "Generated docs from an Express api",
506
- title: "Express Application",
507
- version: "1.0.0",
508
- },
509
- openapi: "3.0.0",
510
- });
511
517
  app.use(oapi);
512
518
 
513
519
  if (process.env.ENABLE_SWAGGER === "true") {
@@ -579,7 +585,7 @@ export class TerrenoApp {
579
585
 
580
586
  // /auth/me must be registered after plugins so that session middleware
581
587
  // (e.g. Better Auth) has a chance to populate req.user first.
582
- addMeRoutes(app, options.userModel, options.authOptions, options.accessControl);
588
+ addMeRoutes(app, options.userModel, options.authOptions, options.accessControl, oapi);
583
589
 
584
590
  Sentry.setupExpressErrorHandler(app);
585
591