@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.
Files changed (101) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +1 -1
  3. package/biome.jsonc +2 -2
  4. package/dist/api.d.ts +0 -13
  5. package/dist/api.js +0 -9
  6. package/dist/auth.d.ts +3 -2
  7. package/dist/auth.js +95 -5
  8. package/dist/authRecovery.d.ts +2 -1
  9. package/dist/authRecovery.js +35 -17
  10. package/dist/collectionRegistry.d.ts +3 -4
  11. package/dist/collectionRegistry.js +0 -1
  12. package/dist/consentApp.d.ts +1 -1
  13. package/dist/consentApp.js +58 -2
  14. package/dist/index.d.ts +4 -5
  15. package/dist/index.js +8 -20
  16. package/dist/mcp/adminTracking.js +1 -1
  17. package/dist/mcp/serviceTokens.d.ts +21 -1
  18. package/dist/mcp/serviceTokens.js +159 -183
  19. package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
  20. package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
  21. package/dist/models/mcpRequestLog.js +1 -1
  22. package/dist/models/mcpServiceToken.js +36 -4
  23. package/dist/openApiBuilder.d.ts +4 -0
  24. package/dist/openApiBuilder.js +2 -0
  25. package/dist/rbac/realtimeAccess.d.ts +5 -4
  26. package/dist/rbac/realtimeAccess.js +17 -64
  27. package/dist/realtime/changeStreamWatcher.d.ts +8 -63
  28. package/dist/realtime/changeStreamWatcher.js +32 -391
  29. package/dist/realtime/realtimeApp.d.ts +14 -27
  30. package/dist/realtime/realtimeApp.js +14 -220
  31. package/dist/realtime/types.d.ts +0 -64
  32. package/dist/sync/executors.js +14 -2
  33. package/dist/sync/socketHandlers.d.ts +1 -1
  34. package/dist/sync/socketHandlers.js +1 -1
  35. package/dist/terrenoApp.d.ts +7 -5
  36. package/dist/terrenoApp.js +18 -14
  37. package/dist/tests/openApiResponseSchema.d.ts +39 -0
  38. package/dist/tests/openApiResponseSchema.js +56 -0
  39. package/dist/tests.d.ts +1 -0
  40. package/dist/tests.js +4 -1
  41. package/dist/types/mcpAdmin.d.ts +1 -1
  42. package/dist/types/mcpServiceToken.d.ts +7 -4
  43. package/dist/versionCheckPlugin.d.ts +1 -1
  44. package/dist/versionCheckPlugin.js +25 -2
  45. package/package.json +10 -6
  46. package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
  47. package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
  48. package/src/__tests__/openApiResponseSchema.test.ts +148 -0
  49. package/src/__tests__/versionCheckPlugin.test.ts +72 -0
  50. package/src/api.test.ts +9 -7
  51. package/src/api.ts +0 -24
  52. package/src/auth.ts +116 -5
  53. package/src/authOpenApi.test.ts +316 -0
  54. package/src/authRecovery.ts +47 -19
  55. package/src/betterAuthOAuthHandoff.test.ts +13 -5
  56. package/src/collectionRegistry.ts +3 -5
  57. package/src/consentApp.test.ts +98 -0
  58. package/src/consentApp.ts +67 -2
  59. package/src/index.ts +6 -28
  60. package/src/mcp/actionTools.test.ts +2 -2
  61. package/src/mcp/adminTracking.ts +1 -1
  62. package/src/mcp/auth.test.ts +7 -3
  63. package/src/mcp/oauth.test.ts +12 -12
  64. package/src/mcp/serviceTokens.sync.test.ts +230 -0
  65. package/src/mcp/serviceTokens.test.ts +112 -61
  66. package/src/mcp/serviceTokens.ts +193 -212
  67. package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
  68. package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
  69. package/src/models/mcpRequestLog.ts +1 -1
  70. package/src/models/mcpServiceToken.test.ts +52 -5
  71. package/src/models/mcpServiceToken.ts +51 -14
  72. package/src/openApiBuilder.test.ts +34 -1
  73. package/src/openApiBuilder.ts +5 -0
  74. package/src/rateLimit/rateLimit.test.ts +25 -10
  75. package/src/rbac/realtimeAccess.test.ts +20 -172
  76. package/src/rbac/realtimeAccess.ts +17 -82
  77. package/src/realtime/changeStreamWatcher.ts +43 -506
  78. package/src/realtime/realtime.test.ts +205 -2545
  79. package/src/realtime/realtimeApp.ts +16 -295
  80. package/src/realtime/types.ts +0 -72
  81. package/src/sync/executors.test.ts +28 -0
  82. package/src/sync/executors.ts +23 -2
  83. package/src/sync/socketHandlers.ts +1 -1
  84. package/src/sync/syncSocket.test.ts +77 -113
  85. package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
  86. package/src/terrenoApp.ts +24 -18
  87. package/src/tests/openApiResponseSchema.ts +104 -0
  88. package/src/tests.ts +7 -0
  89. package/src/types/mcpAdmin.ts +1 -1
  90. package/src/types/mcpServiceToken.ts +7 -4
  91. package/src/versionCheckPlugin.ts +41 -2
  92. package/dist/realtime/deprecation.d.ts +0 -13
  93. package/dist/realtime/deprecation.js +0 -31
  94. package/dist/realtime/queryStore.d.ts +0 -37
  95. package/dist/realtime/queryStore.js +0 -103
  96. package/dist/realtime/registry.d.ts +0 -15
  97. package/dist/realtime/registry.js +0 -52
  98. package/src/realtime/deprecation.test.ts +0 -60
  99. package/src/realtime/deprecation.ts +0 -33
  100. package/src/realtime/queryStore.ts +0 -122
  101. package/src/realtime/registry.ts +0 -84
@@ -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
- });
@@ -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
 
@@ -0,0 +1,104 @@
1
+ import Ajv from "ajv";
2
+ import addFormats from "ajv-formats";
3
+
4
+ /** Raised when a route or response is undocumented, or a body breaks its documented schema. */
5
+ class DocumentedResponseError extends Error {
6
+ name = "DocumentedResponseError";
7
+ }
8
+
9
+ /** The subset of an OpenAPI document needed to look up and validate a response schema. */
10
+ export interface OpenApiResponseSpec {
11
+ components?: Record<string, unknown>;
12
+ paths?: Record<string, Record<string, OpenApiResponseOperation | undefined> | undefined>;
13
+ }
14
+
15
+ interface OpenApiResponseOperation {
16
+ responses?: Record<string, {content?: Record<string, {schema?: unknown}>} | undefined>;
17
+ }
18
+
19
+ export interface DocumentedResponseOptions {
20
+ /** The `/openapi.json` document the app serves. */
21
+ spec: OpenApiResponseSpec;
22
+ /** The OpenAPI path template, e.g. `/announcements/{id}/click`. */
23
+ path: string;
24
+ /** HTTP method, any case. */
25
+ method: string;
26
+ /** The real response: its status picks the documented response, its body is validated. */
27
+ response: {status: number; body: unknown};
28
+ /** Response media type to validate against. Defaults to `application/json`. */
29
+ contentType?: string;
30
+ }
31
+
32
+ export interface DocumentedResponseResult {
33
+ valid: boolean;
34
+ errors: string[];
35
+ }
36
+
37
+ const findResponseSchema = ({
38
+ contentType,
39
+ method,
40
+ path,
41
+ spec,
42
+ status,
43
+ }: {
44
+ contentType: string;
45
+ method: string;
46
+ path: string;
47
+ spec: OpenApiResponseSpec;
48
+ status: number;
49
+ }): unknown => {
50
+ const label = `${method.toUpperCase()} ${path}`;
51
+ const operation = spec.paths?.[path]?.[method.toLowerCase()];
52
+ if (!operation) {
53
+ throw new DocumentedResponseError(`${label} is not documented in the OpenAPI spec`);
54
+ }
55
+ const documented = operation.responses?.[String(status)];
56
+ if (!documented) {
57
+ const statuses = Object.keys(operation.responses ?? {}).join(", ") || "none";
58
+ throw new DocumentedResponseError(
59
+ `${label} has no documented ${status} response (documented: ${statuses})`
60
+ );
61
+ }
62
+ const schema = documented.content?.[contentType]?.schema;
63
+ if (!schema) {
64
+ throw new DocumentedResponseError(`${label} ${status} response has no ${contentType} schema`);
65
+ }
66
+ return schema;
67
+ };
68
+
69
+ /**
70
+ * Validates a real response body against the response schema `/openapi.json` documents for it,
71
+ * resolving `#/components/...` references against the same spec.
72
+ */
73
+ export const validateDocumentedResponse = ({
74
+ contentType = "application/json",
75
+ method,
76
+ path,
77
+ response,
78
+ spec,
79
+ }: DocumentedResponseOptions): DocumentedResponseResult => {
80
+ const schema = findResponseSchema({contentType, method, path, spec, status: response.status});
81
+ const ajv = new Ajv({allErrors: true, strict: false});
82
+ addFormats(ajv as unknown as Parameters<typeof addFormats>[0]);
83
+ // Wrapping keeps `#/components/...` refs resolvable from the root of the compiled schema.
84
+ const validate = ajv.compile({allOf: [schema], components: spec.components ?? {}});
85
+ if (validate(response.body)) {
86
+ return {errors: [], valid: true};
87
+ }
88
+ const errors = (validate.errors ?? []).map(
89
+ (error) => `${error.instancePath || "(root)"} ${error.message ?? "is invalid"}`
90
+ );
91
+ return {errors, valid: false};
92
+ };
93
+
94
+ /** Throws with every schema violation when a response body does not match its documentation. */
95
+ export const expectDocumentedResponse = (options: DocumentedResponseOptions): void => {
96
+ const {errors, valid} = validateDocumentedResponse(options);
97
+ if (valid) {
98
+ return;
99
+ }
100
+ const label = `${options.method.toUpperCase()} ${options.path} ${options.response.status}`;
101
+ throw new DocumentedResponseError(
102
+ `${label} response does not match its OpenAPI schema:\n- ${errors.join("\n- ")}\nBody: ${JSON.stringify(options.response.body)}`
103
+ );
104
+ };
package/src/tests.ts CHANGED
@@ -56,3 +56,10 @@ export const authAsUser = async (
56
56
  };
57
57
 
58
58
  export {loadTestData} from "./tests/mongoTestSetup";
59
+ export {
60
+ type DocumentedResponseOptions,
61
+ type DocumentedResponseResult,
62
+ expectDocumentedResponse,
63
+ type OpenApiResponseSpec,
64
+ validateDocumentedResponse,
65
+ } from "./tests/openApiResponseSchema";
@@ -20,7 +20,7 @@ export interface McpRequestLogDocument extends mongoose.Document {
20
20
  oauthClientId?: string;
21
21
  oauthFamilyId?: string;
22
22
  outcome: McpRequestLogOutcome;
23
- serviceTokenId?: mongoose.Types.ObjectId;
23
+ serviceTokenId?: string;
24
24
  toolName: string;
25
25
  updated: Date;
26
26
  userId?: mongoose.Types.ObjectId;
@@ -15,7 +15,7 @@ export interface McpServiceTokenStatics
15
15
  FindOneOrNonePlugin<McpServiceTokenDocument> {
16
16
  countActiveForUser: (
17
17
  this: McpServiceTokenModel,
18
- userId: mongoose.Types.ObjectId
18
+ userId: mongoose.Types.ObjectId | string
19
19
  ) => Promise<number>;
20
20
  issueFor: (
21
21
  this: McpServiceTokenModel,
@@ -34,7 +34,7 @@ export interface McpServiceTokenStatics
34
34
  revokeForUser: (
35
35
  this: McpServiceTokenModel,
36
36
  user: {_id: {toString(): string}},
37
- tokenId: mongoose.Types.ObjectId
37
+ tokenId: string
38
38
  ) => Promise<McpServiceTokenDocument | null>;
39
39
  verify: (this: McpServiceTokenModel, token: string) => Promise<McpServiceTokenDocument | null>;
40
40
  }
@@ -43,9 +43,12 @@ export interface McpServiceTokenModel
43
43
  extends mongoose.Model<McpServiceTokenDocument, object, McpServiceTokenMethods>,
44
44
  McpServiceTokenStatics {}
45
45
 
46
- export interface McpServiceTokenDocument extends mongoose.Document {
47
- _id: mongoose.Types.ObjectId;
46
+ export interface McpServiceTokenDocument extends mongoose.Document<string> {
47
+ /** UUID for new rows; ObjectId hex for rows migrated by mcp-service-token-string-ids. */
48
+ _id: string;
48
49
  created: Date;
50
+ /** Always false: a delete revokes the token instead of tombstoning it. */
51
+ deleted: boolean;
49
52
  expiresAt?: Date;
50
53
  lastUsedAt?: Date;
51
54
  name: string;
@@ -1,7 +1,8 @@
1
1
  import type express from "express";
2
2
 
3
- import {asyncHandler} from "./api";
3
+ import {asyncHandler, type OpenApiMiddleware} from "./api";
4
4
  import {VersionConfig} from "./models/versionConfig";
5
+ import {createOpenApiBuilder} from "./openApiBuilder";
5
6
  import type {TerrenoPlugin} from "./terrenoPlugin";
6
7
 
7
8
  export type VersionCheckStatus = "ok" | "warning" | "required";
@@ -26,9 +27,47 @@ const DEFAULT_POLLING_INTERVAL_MINUTES = 1440;
26
27
  * Compares client build number against admin-configured thresholds per platform.
27
28
  */
28
29
  export class VersionCheckPlugin implements TerrenoPlugin {
29
- register(app: express.Application): void {
30
+ register(app: express.Application, openApi?: unknown): void {
31
+ // Documentation only: request validation stays off so unparseable versions still get "ok".
32
+ const versionCheckOpenApi = createOpenApiBuilder(
33
+ openApi ? {openApi: openApi as OpenApiMiddleware} : {}
34
+ )
35
+ .withTags(["version"])
36
+ .withSummary("Check whether the client build must or should update")
37
+ .withQueryParameter(
38
+ "platform",
39
+ {enum: ["web", "mobile"], type: "string"},
40
+ {description: "Client platform. Any other value is treated as web."}
41
+ )
42
+ .withQueryParameter(
43
+ "version",
44
+ {type: "integer"},
45
+ {description: "Client build number. When missing or not a number, the status is ok."}
46
+ )
47
+ .withResponse(
48
+ 200,
49
+ {
50
+ message: {
51
+ description: "Message to show when status is warning or required",
52
+ type: "string",
53
+ },
54
+ pollingIntervalMs: {
55
+ description: "How often the client should poll for updates, in milliseconds",
56
+ type: "number",
57
+ },
58
+ requiredVersion: {description: "Minimum supported build number", type: "number"},
59
+ status: {enum: ["ok", "warning", "required"], type: "string"},
60
+ updateUrl: {description: "Where the user can get the update", type: "string"},
61
+ warningVersion: {description: "Builds below this number get a warning", type: "number"},
62
+ },
63
+ {required: ["status"]}
64
+ )
65
+ .withValidation({enabled: false})
66
+ .build();
67
+
30
68
  app.get(
31
69
  "/version-check",
70
+ versionCheckOpenApi,
32
71
  asyncHandler(async (req, res) => {
33
72
  const versionParam = req.query.version;
34
73
  const platform = req.query.platform as string | undefined;
@@ -1,13 +0,0 @@
1
- /**
2
- * One-line warning for modelRouter `realtime`. Keep in sync with the
3
- * `@terreno/rtk` helpers and `docs/implementationPlans/remove-legacy-realtime.md`.
4
- */
5
- /** @internal */
6
- export declare const REALTIME_DEPRECATION_MESSAGE = "modelRouter `realtime` is deprecated and will be removed in Terreno 58. Use `sync` with `@terreno/syncdb` instead. See docs/how-to/migrate-rtk-to-syncdb.md. RealtimeApp remains required for sync sockets.";
7
- /**
8
- * Emits a one-time deprecation warning per model/routePath per process when a
9
- * consumer enables the legacy RTK cache-patching `realtime` option.
10
- */
11
- export declare const warnRealtimeDeprecated: (modelName: string, routePath?: string) => void;
12
- /** @internal Test helper — clears one-time realtime deprecation warnings. */
13
- export declare const resetRealtimeDeprecationWarningsForTests: () => void;