@terreno/api 57.3.0 → 57.4.0

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 (293) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +23 -10
  2. package/README.md +6 -0
  3. package/dist/adminTypes.d.ts +7 -0
  4. package/dist/adminTypes.js +6 -1
  5. package/dist/api.d.ts +10 -0
  6. package/dist/api.js +99 -36
  7. package/dist/audit/auditApp.d.ts +30 -0
  8. package/dist/audit/auditApp.js +155 -0
  9. package/dist/audit/auditEventModel.d.ts +29 -0
  10. package/dist/audit/auditEventModel.js +102 -0
  11. package/dist/audit/cloudTasksEnqueue.d.ts +32 -0
  12. package/dist/audit/cloudTasksEnqueue.js +162 -0
  13. package/dist/audit/diff.d.ts +10 -0
  14. package/dist/audit/diff.js +230 -0
  15. package/dist/audit/processQueue.d.ts +6 -0
  16. package/dist/audit/processQueue.js +101 -0
  17. package/dist/audit/rbacSink.d.ts +2 -0
  18. package/dist/audit/rbacSink.js +82 -0
  19. package/dist/audit/record.d.ts +56 -0
  20. package/dist/audit/record.js +373 -0
  21. package/dist/betterAuth.d.ts +6 -0
  22. package/dist/betterAuthSetup.js +1 -1
  23. package/dist/collectionRegistry.d.ts +3 -1
  24. package/dist/collectionRegistry.js +25 -0
  25. package/dist/index.d.ts +26 -1
  26. package/dist/index.js +48 -2
  27. package/dist/mcp/query.d.ts +0 -13
  28. package/dist/mcp/query.js +8 -8
  29. package/dist/migrations/fixtures/all-down/20260910120000-one.d.ts +4 -0
  30. package/dist/migrations/fixtures/all-down/20260910120000-one.js +49 -0
  31. package/dist/migrations/fixtures/all-down/20260910120001-two.d.ts +4 -0
  32. package/dist/migrations/fixtures/all-down/20260910120001-two.js +49 -0
  33. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.d.ts +3 -0
  34. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.js +45 -0
  35. package/dist/migrations/fixtures/bad-name/not-a-migration.d.ts +3 -0
  36. package/dist/migrations/fixtures/bad-name/not-a-migration.js +45 -0
  37. package/dist/migrations/fixtures/missing-up/20260910120000-noup.d.ts +2 -0
  38. package/dist/migrations/fixtures/missing-up/20260910120000-noup.js +5 -0
  39. package/dist/migrations/fixtures/valid/20260910120000-alpha.d.ts +3 -0
  40. package/dist/migrations/fixtures/valid/20260910120000-alpha.js +45 -0
  41. package/dist/migrations/fixtures/valid/20260910120001-beta.d.ts +4 -0
  42. package/dist/migrations/fixtures/valid/20260910120001-beta.js +49 -0
  43. package/dist/migrations/generate.d.ts +17 -0
  44. package/dist/migrations/generate.js +277 -0
  45. package/dist/migrations/load.d.ts +20 -0
  46. package/dist/migrations/load.js +236 -0
  47. package/dist/migrations/lock.d.ts +13 -0
  48. package/dist/migrations/lock.js +145 -0
  49. package/dist/migrations/runner.d.ts +42 -0
  50. package/dist/migrations/runner.js +503 -0
  51. package/dist/migrations/schemaCatalog.d.ts +44 -0
  52. package/dist/migrations/schemaCatalog.js +326 -0
  53. package/dist/migrations/types.d.ts +87 -0
  54. package/dist/migrations/types.js +7 -0
  55. package/dist/models/notification.d.ts +2 -0
  56. package/dist/models/notification.js +62 -0
  57. package/dist/models/notificationPreference.d.ts +2 -0
  58. package/dist/models/notificationPreference.js +49 -0
  59. package/dist/notifications/notificationService.d.ts +40 -0
  60. package/dist/notifications/notificationService.js +323 -0
  61. package/dist/notifications/notificationsApp.d.ts +18 -0
  62. package/dist/notifications/notificationsApp.js +250 -0
  63. package/dist/notifications/notificationsBeforeSend.d.ts +14 -0
  64. package/dist/notifications/notificationsBeforeSend.js +77 -0
  65. package/dist/openApi.d.ts +1 -7
  66. package/dist/openApi.js +7 -6
  67. package/dist/openApiBuilder.d.ts +14 -3
  68. package/dist/openApiValidator.d.ts +13 -1
  69. package/dist/openApiValidator.js +200 -36
  70. package/dist/orgs/orgContext.d.ts +23 -0
  71. package/dist/orgs/orgContext.js +198 -0
  72. package/dist/orgs/orgPermissions.d.ts +4 -0
  73. package/dist/orgs/orgPermissions.js +77 -0
  74. package/dist/orgs/orgPlugin.d.ts +13 -0
  75. package/dist/orgs/orgPlugin.js +84 -0
  76. package/dist/orgs/organizationModel.d.ts +13 -0
  77. package/dist/orgs/organizationModel.js +301 -0
  78. package/dist/orgs/organizationSettings.d.ts +19 -0
  79. package/dist/orgs/organizationSettings.js +120 -0
  80. package/dist/orgs/orgsApp.d.ts +28 -0
  81. package/dist/orgs/orgsApp.js +678 -0
  82. package/dist/permissions.d.ts +7 -13
  83. package/dist/permissions.js +8 -31
  84. package/dist/rateLimit/middleware.d.ts +0 -8
  85. package/dist/rateLimit/middleware.js +2 -3
  86. package/dist/rateLimit/mongoStore.d.ts +1 -0
  87. package/dist/rateLimit/mongoStore.js +1 -0
  88. package/dist/rateLimit/policies.d.ts +0 -4
  89. package/dist/rateLimit/policies.js +5 -7
  90. package/dist/rateLimit/redisStore.d.ts +1 -0
  91. package/dist/rateLimit/redisStore.js +1 -0
  92. package/dist/rbac/access.js +30 -13
  93. package/dist/rbac/membershipOrgAdminSource.d.ts +6 -0
  94. package/dist/rbac/membershipOrgAdminSource.js +122 -0
  95. package/dist/rbac/modelRouterAccess.d.ts +3 -0
  96. package/dist/rbac/modelRouterAccess.js +3 -0
  97. package/dist/rbac/resolve.js +60 -31
  98. package/dist/rbac/roleModel.d.ts +2 -5
  99. package/dist/rbac/roleModel.js +18 -4
  100. package/dist/rbac/statements.d.ts +10 -1
  101. package/dist/rbac/statements.js +19 -2
  102. package/dist/rbac/types.d.ts +5 -0
  103. package/dist/realtime/changeStreamWatcher.d.ts +10 -4
  104. package/dist/realtime/changeStreamWatcher.js +110 -64
  105. package/dist/realtime/deprecation.d.ts +1 -0
  106. package/dist/realtime/deprecation.js +1 -0
  107. package/dist/realtime/realtimeApp.d.ts +1 -0
  108. package/dist/realtime/realtimeApp.js +1 -0
  109. package/dist/schemaMetadata.js +16 -5
  110. package/dist/sync/adminBroadcastScope.d.ts +40 -0
  111. package/dist/sync/adminBroadcastScope.js +194 -0
  112. package/dist/sync/adminWindowAccess.d.ts +13 -0
  113. package/dist/sync/adminWindowAccess.js +96 -0
  114. package/dist/sync/adminWindowMutation.d.ts +88 -0
  115. package/dist/sync/adminWindowMutation.js +247 -0
  116. package/dist/sync/executors.d.ts +9 -3
  117. package/dist/sync/executors.js +190 -159
  118. package/dist/sync/mutationHandler.d.ts +5 -2
  119. package/dist/sync/mutationHandler.js +191 -71
  120. package/dist/sync/registry.js +4 -0
  121. package/dist/sync/routes.d.ts +13 -0
  122. package/dist/sync/routes.js +113 -56
  123. package/dist/sync/socketHandlers.d.ts +8 -2
  124. package/dist/sync/socketHandlers.js +144 -50
  125. package/dist/sync/streams.d.ts +2 -0
  126. package/dist/sync/streams.js +7 -1
  127. package/dist/sync/syncApp.d.ts +2 -1
  128. package/dist/sync/syncApp.js +2 -1
  129. package/dist/sync/syncBatch.d.ts +5 -2
  130. package/dist/sync/syncBatch.js +4 -4
  131. package/dist/sync/types.d.ts +18 -0
  132. package/dist/terrenoApp.d.ts +29 -0
  133. package/dist/terrenoApp.js +91 -54
  134. package/dist/tests/createTestData.d.ts +1 -3
  135. package/dist/tests/createTestData.js +3 -5
  136. package/dist/tests/models.d.ts +1 -0
  137. package/dist/tests/models.js +9 -2
  138. package/dist/tests/testHelper.d.ts +0 -5
  139. package/dist/tests/testHelper.js +2 -9
  140. package/dist/types/authToken.d.ts +3 -3
  141. package/dist/types/mcpServiceToken.d.ts +2 -2
  142. package/dist/types/membership.d.ts +23 -0
  143. package/dist/types/membership.js +2 -0
  144. package/dist/types/notification.d.ts +28 -0
  145. package/dist/types/notification.js +2 -0
  146. package/dist/types/notificationPreference.d.ts +20 -0
  147. package/dist/types/notificationPreference.js +2 -0
  148. package/dist/types/organization.d.ts +36 -0
  149. package/dist/types/organization.js +2 -0
  150. package/dist/webhooks/idempotency/webhookReceipt.d.ts +4 -49
  151. package/dist/webhooks/idempotency/webhookReceipt.js +7 -7
  152. package/dist/webhooks/rawBody.d.ts +1 -0
  153. package/dist/webhooks/rawBody.js +1 -0
  154. package/package.json +31 -25
  155. package/src/__snapshots__/openApi.test.ts.snap +192 -54
  156. package/src/__snapshots__/openApiBuilder.test.ts.snap +0 -18
  157. package/src/__snapshots__/schemaMetadata.test.ts.snap +0 -1
  158. package/src/adminTypes.ts +8 -0
  159. package/src/api.test.ts +39 -2
  160. package/src/api.ts +68 -0
  161. package/src/audit/auditApp.test.ts +243 -0
  162. package/src/audit/auditApp.ts +139 -0
  163. package/src/audit/auditEventModel.ts +156 -0
  164. package/src/audit/auditRouter.test.ts +456 -0
  165. package/src/audit/cloudTasksEnqueue.test.ts +124 -0
  166. package/src/audit/cloudTasksEnqueue.ts +104 -0
  167. package/src/audit/diff.ts +163 -0
  168. package/src/audit/processQueue.ts +69 -0
  169. package/src/audit/rbacSink.test.ts +86 -0
  170. package/src/audit/rbacSink.ts +42 -0
  171. package/src/audit/record.test.ts +402 -0
  172. package/src/audit/record.ts +328 -0
  173. package/src/auth.test.ts +1 -1
  174. package/src/betterAuth.ts +7 -0
  175. package/src/betterAuthSetup.test.ts +27 -0
  176. package/src/betterAuthSetup.ts +1 -0
  177. package/src/collectionRegistry.test.ts +8 -9
  178. package/src/collectionRegistry.ts +21 -1
  179. package/src/express.d.ts +2 -0
  180. package/src/expressServer.test.ts +50 -2
  181. package/src/index.ts +69 -0
  182. package/src/mcp/handlers.test.ts +275 -0
  183. package/src/mcp/query.ts +3 -3
  184. package/src/mcp/toolGenerator.test.ts +81 -0
  185. package/src/migrations/cli.test.ts +376 -0
  186. package/src/migrations/cli.ts +283 -0
  187. package/src/migrations/fixtures/all-down/20260910120000-one.ts +6 -0
  188. package/src/migrations/fixtures/all-down/20260910120001-two.ts +6 -0
  189. package/src/migrations/fixtures/bad-id/20260910120000-mismatch.ts +4 -0
  190. package/src/migrations/fixtures/bad-name/not-a-migration.ts +4 -0
  191. package/src/migrations/fixtures/missing-up/20260910120000-noup.ts +2 -0
  192. package/src/migrations/fixtures/valid/20260910120000-alpha.ts +4 -0
  193. package/src/migrations/fixtures/valid/20260910120001-beta.ts +6 -0
  194. package/src/migrations/generate.test.ts +333 -0
  195. package/src/migrations/generate.ts +216 -0
  196. package/src/migrations/load.test.ts +103 -0
  197. package/src/migrations/load.ts +124 -0
  198. package/src/migrations/lock.test.ts +133 -0
  199. package/src/migrations/lock.ts +118 -0
  200. package/src/migrations/runner.test.ts +504 -0
  201. package/src/migrations/runner.ts +358 -0
  202. package/src/migrations/schemaCatalog.test.ts +159 -0
  203. package/src/migrations/schemaCatalog.ts +262 -0
  204. package/src/migrations/types.ts +94 -0
  205. package/src/models/notification.ts +68 -0
  206. package/src/models/notificationPreference.ts +62 -0
  207. package/src/notifications/notificationService.ts +254 -0
  208. package/src/notifications/notificationsApp.test.ts +505 -0
  209. package/src/notifications/notificationsApp.ts +200 -0
  210. package/src/notifications/notificationsBeforeSend.ts +51 -0
  211. package/src/openApi.test.ts +0 -1
  212. package/src/openApi.ts +2 -1
  213. package/src/openApiBuilder.ts +14 -3
  214. package/src/openApiValidator.test.ts +221 -2
  215. package/src/openApiValidator.ts +218 -33
  216. package/src/orgs/orgAccessOptIn.test.ts +87 -0
  217. package/src/orgs/orgContext.test.ts +259 -0
  218. package/src/orgs/orgContext.ts +151 -0
  219. package/src/orgs/orgPermissions.test.ts +105 -0
  220. package/src/orgs/orgPermissions.ts +40 -0
  221. package/src/orgs/orgPlugin.test.ts +130 -0
  222. package/src/orgs/orgPlugin.ts +70 -0
  223. package/src/orgs/orgRbac.test.ts +267 -0
  224. package/src/orgs/orgSecurityDefects.test.ts +415 -0
  225. package/src/orgs/organizationModel.test.ts +205 -0
  226. package/src/orgs/organizationModel.ts +257 -0
  227. package/src/orgs/organizationSettings.test.ts +113 -0
  228. package/src/orgs/organizationSettings.ts +126 -0
  229. package/src/orgs/orgsApp.test.ts +382 -0
  230. package/src/orgs/orgsApp.ts +563 -0
  231. package/src/permissions.test.ts +62 -36
  232. package/src/permissions.ts +8 -30
  233. package/src/rateLimit/middleware.ts +1 -1
  234. package/src/rateLimit/mongoStore.ts +1 -0
  235. package/src/rateLimit/policies.ts +2 -2
  236. package/src/rateLimit/redisStore.ts +1 -0
  237. package/src/rbac/access.ts +11 -3
  238. package/src/rbac/membershipOrgAdminSource.ts +59 -0
  239. package/src/rbac/modelRouterAccess.ts +3 -0
  240. package/src/rbac/permissionUtils.test.ts +26 -5
  241. package/src/rbac/resolve.test.ts +34 -2
  242. package/src/rbac/resolve.ts +26 -7
  243. package/src/rbac/roleModel.test.ts +34 -1
  244. package/src/rbac/roleModel.ts +17 -1
  245. package/src/rbac/statements.test.ts +19 -0
  246. package/src/rbac/statements.ts +19 -1
  247. package/src/rbac/types.ts +5 -0
  248. package/src/realtime/changeStreamWatcher.ts +73 -33
  249. package/src/realtime/deprecation.ts +1 -0
  250. package/src/realtime/realtime.test.ts +357 -185
  251. package/src/realtime/realtimeApp.ts +1 -0
  252. package/src/schemaMetadata.test.ts +14 -0
  253. package/src/schemaMetadata.ts +5 -5
  254. package/src/sync/adminBroadcastConfig.test.ts +96 -0
  255. package/src/sync/adminBroadcastScope.test.ts +155 -0
  256. package/src/sync/adminBroadcastScope.ts +123 -0
  257. package/src/sync/adminWindowAccess.test.ts +57 -0
  258. package/src/sync/adminWindowAccess.ts +32 -0
  259. package/src/sync/adminWindowMutation.test.ts +450 -0
  260. package/src/sync/adminWindowMutation.ts +283 -0
  261. package/src/sync/executors.ts +33 -6
  262. package/src/sync/mutationHandler.test.ts +277 -1
  263. package/src/sync/mutationHandler.ts +171 -29
  264. package/src/sync/registry.ts +4 -0
  265. package/src/sync/routes.ts +52 -8
  266. package/src/sync/socketHandlers.ts +154 -58
  267. package/src/sync/streams.ts +6 -0
  268. package/src/sync/sync.test.ts +3 -2
  269. package/src/sync/syncApp.ts +2 -1
  270. package/src/sync/syncBatch.ts +7 -2
  271. package/src/sync/syncRoutes.test.ts +297 -3
  272. package/src/sync/syncSocket.test.ts +229 -0
  273. package/src/sync/types.ts +20 -0
  274. package/src/terrenoApp.migrations.test.ts +114 -0
  275. package/src/terrenoApp.test.ts +41 -0
  276. package/src/terrenoApp.ts +94 -31
  277. package/src/tests/createTestData.ts +2 -2
  278. package/src/tests/models.ts +10 -2
  279. package/src/tests/testHelper.ts +1 -7
  280. package/src/types/authToken.ts +2 -4
  281. package/src/types/mcpServiceToken.ts +1 -7
  282. package/src/types/membership.ts +48 -0
  283. package/src/types/notification.ts +34 -0
  284. package/src/types/notificationPreference.ts +28 -0
  285. package/src/types/organization.ts +49 -0
  286. package/src/webhooks/idempotency/webhookReceipt.ts +4 -7
  287. package/src/webhooks/rawBody.test.ts +33 -0
  288. package/src/webhooks/rawBody.ts +1 -0
  289. package/tsconfig.json +1 -1
  290. package/tsconfig.typedoc.json +2 -1
  291. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.d.ts +0 -2
  292. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
  293. package/src/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
@@ -1,4 +1,5 @@
1
1
  import {beforeAll, beforeEach, describe, expect, it} from "bun:test";
2
+ import {assert} from "chai";
2
3
  import type express from "express";
3
4
  import {type Model, model, Schema, Types} from "mongoose";
4
5
  import supertest from "supertest";
@@ -9,10 +10,15 @@ import {APIError} from "../errors";
9
10
  import {OwnerQueryFilter, Permissions} from "../permissions";
10
11
  import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
11
12
  import {authAsUser, getBaseServer, setupDb, UserModel} from "../tests";
13
+ import {registerAdminBroadcastScope} from "./adminBroadcastScope";
12
14
  import {SyncCounter, SyncKey, SyncMutation} from "./models";
13
15
  import {MAX_SYNC_MUTATIONS_PER_BATCH} from "./mutationHandler";
14
- import {clearSyncRegistry, registerSync} from "./registry";
15
- import {MAX_ENTITY_FETCH, MAX_SYNC_HTTP_MUTATIONS_PER_SECOND} from "./routes";
16
+ import {clearSyncRegistry, getSyncRegistry, registerSync, type SyncRegistryEntry} from "./registry";
17
+ import {
18
+ buildSnapshotScopeFilter,
19
+ MAX_ENTITY_FETCH,
20
+ MAX_SYNC_HTTP_MUTATIONS_PER_SECOND,
21
+ } from "./routes";
16
22
  import {SyncApp} from "./syncApp";
17
23
  import {syncPlugin} from "./syncSeqPlugin";
18
24
 
@@ -67,10 +73,34 @@ routeBannerSchema.plugin(createdUpdatedPlugin);
67
73
  routeBannerSchema.plugin(syncPlugin);
68
74
  const RouteBannerModel = model<RouteBanner>("SyncRouteBanner", routeBannerSchema);
69
75
 
76
+ interface RouteNote extends IsDeleted {
77
+ _id: string;
78
+ body: string;
79
+ ownerId: string;
80
+ _syncSeq?: number;
81
+ }
82
+
83
+ // Client-minted string `_id`s (the syncdb default): entity ids are passed through uncast.
84
+ const routeNoteSchema = new Schema<RouteNote>({
85
+ _id: {description: "Client-minted note id", type: String},
86
+ body: {description: "The note body", required: true, type: String},
87
+ ownerId: {description: "The user who owns this note", type: String},
88
+ });
89
+ routeNoteSchema.plugin(isDeletedPlugin);
90
+ routeNoteSchema.plugin(createdUpdatedPlugin);
91
+ routeNoteSchema.plugin(syncPlugin);
92
+ const RouteNoteModel = model<RouteNote>("SyncRouteNote", routeNoteSchema);
93
+
70
94
  interface SnapshotEntity {
71
95
  id: string;
72
96
  seq: number;
73
- data: {name: string};
97
+ deleted: boolean;
98
+ data: {name: string} | null;
99
+ }
100
+
101
+ interface StreamInfo {
102
+ collection: string;
103
+ stream: string;
74
104
  }
75
105
 
76
106
  interface MutationResult {
@@ -198,6 +228,37 @@ describe("sync routes", () => {
198
228
  await agent.get(`/sync/snapshot?stream=${s}&limit=1e9`).expect(400);
199
229
  });
200
230
 
231
+ it("400s for an all-digit cursor that is not a safe integer", async () => {
232
+ const s = encodeURIComponent(ownerStream());
233
+ const res = await agent
234
+ .get(`/sync/snapshot?stream=${s}&cursor=99999999999999999999`)
235
+ .expect(400);
236
+ expect(res.body.title).toMatch(/Invalid cursor/);
237
+ });
238
+
239
+ it("surfaces scope-move markers as tombstones on the old stream (C4)", async () => {
240
+ const doc = await RouteStuffModel.create({name: "moving", ownerId: notAdminId});
241
+ const initial = await agent
242
+ .get(`/sync/snapshot?stream=${encodeURIComponent(ownerStream())}`)
243
+ .expect(200);
244
+ expect(initial.body.entities.map((e: SnapshotEntity) => e.id)).toEqual([String(doc._id)]);
245
+
246
+ doc.ownerId = "someoneElse";
247
+ await doc.save();
248
+
249
+ const res = await agent
250
+ .get(
251
+ `/sync/snapshot?stream=${encodeURIComponent(ownerStream())}&cursor=${initial.body.cursor}`
252
+ )
253
+ .expect(200);
254
+ const tombstone = res.body.entities.find((e: SnapshotEntity) => e.id === String(doc._id));
255
+ expect(tombstone).toBeDefined();
256
+ expect(tombstone.deleted).toBe(true);
257
+ expect(tombstone.data).toBeNull();
258
+ expect(tombstone.seq).toBeGreaterThan(initial.body.cursor);
259
+ expect(res.body.hasMore).toBe(false);
260
+ });
261
+
201
262
  it("enforces the model's list permissions", async () => {
202
263
  clearSyncRegistry();
203
264
  registerSync({
@@ -342,6 +403,132 @@ describe("sync routes", () => {
342
403
  });
343
404
  });
344
405
 
406
+ describe("buildSnapshotScopeFilter", () => {
407
+ it("500s for a custom scope entry that has no snapshotFilter result", () => {
408
+ // Registration rejects this shape up front, so build the entry directly.
409
+ const entry: SyncRegistryEntry = {
410
+ collectionName: "syncroutestuffs",
411
+ collectionTag: "routeStuff",
412
+ config: {scope: () => "custom"},
413
+ modelName: RouteStuffModel.modelName,
414
+ options: authedOptions,
415
+ routePath: "/routeStuff",
416
+ };
417
+ expect(() => buildSnapshotScopeFilter({entry, scopeValue: "custom"})).toThrow(
418
+ expect.objectContaining({status: 500, title: expect.stringMatching(/snapshotFilter/)})
419
+ );
420
+ });
421
+
422
+ it("returns the snapshotFilter result for a custom scope", () => {
423
+ clearSyncRegistry();
424
+ registerSync({
425
+ config: {
426
+ scope: () => "custom",
427
+ snapshotFilter: () => ({name: "keep"}),
428
+ },
429
+ model: RouteStuffModel as unknown as Model<unknown>,
430
+ options: authedOptions,
431
+ routePath: "/routeStuff",
432
+ });
433
+ const [entry] = getSyncRegistry();
434
+ expect(
435
+ buildSnapshotScopeFilter({
436
+ entry,
437
+ scopeValue: "custom",
438
+ snapshotFilterResult: {name: "keep"},
439
+ })
440
+ ).toEqual({name: "keep"});
441
+ });
442
+ });
443
+
444
+ describe("GET /sync/streams", () => {
445
+ it("requires authentication", async () => {
446
+ await server.get("/sync/streams").expect(401);
447
+ });
448
+
449
+ it("omits collections the caller is not allowed to list", async () => {
450
+ registerSync({
451
+ config: {scope: {type: "broadcast"}},
452
+ model: RouteBannerModel as unknown as Model<unknown>,
453
+ options: adminOnlyOptions,
454
+ routePath: "/routeBanners",
455
+ });
456
+
457
+ const res = await agent.get("/sync/streams").expect(200);
458
+ const collections = res.body.streams.map((s: StreamInfo) => s.collection);
459
+ expect(collections).toContain("routeStuff");
460
+ expect(collections).not.toContain("routeBanners");
461
+
462
+ const adminRes = await adminAgent.get("/sync/streams").expect(200);
463
+ expect(adminRes.body.streams).toContainEqual({
464
+ collection: "routeBanners",
465
+ stream: "routeBanners|all",
466
+ });
467
+ });
468
+
469
+ it("500s when a tenant collection has no getUserScopes resolver", async () => {
470
+ const bareApp = getBaseServer();
471
+ setupAuth(bareApp, UserModel as unknown as AuthUserModel);
472
+ addAuthRoutes(bareApp, UserModel as unknown as AuthUserModel);
473
+ new SyncApp().register(bareApp);
474
+ const bareAgent = await authAsUser(bareApp, "notAdmin");
475
+
476
+ const res = await bareAgent.get("/sync/streams").expect(500);
477
+ expect(res.body.title).toMatch(/Failed to resolve streams for routeProjects/);
478
+ });
479
+ });
480
+
481
+ describe("GET /sync/entities", () => {
482
+ it("requires authentication", async () => {
483
+ await server.get("/sync/entities?collection=routeStuff&ids=abc").expect(401);
484
+ });
485
+
486
+ it("400s when the collection parameter is missing", async () => {
487
+ const res = await agent.get("/sync/entities?ids=abc").expect(400);
488
+ expect(res.body.title).toMatch(/collection/);
489
+ });
490
+
491
+ it("400s when no ids are supplied", async () => {
492
+ const res = await agent.get("/sync/entities?collection=routeStuff&ids=,").expect(400);
493
+ expect(res.body.title).toMatch(/ids/);
494
+ });
495
+
496
+ it("404s for an unknown collection", async () => {
497
+ const res = await agent.get("/sync/entities?collection=nope&ids=abc").expect(404);
498
+ expect(res.body.title).toMatch(/Unknown sync collection: nope/);
499
+ });
500
+
501
+ it("403s when the caller may not list the collection", async () => {
502
+ registerSync({
503
+ config: {scope: {type: "broadcast"}},
504
+ model: RouteBannerModel as unknown as Model<unknown>,
505
+ options: adminOnlyOptions,
506
+ routePath: "/routeBanners",
507
+ });
508
+ const doc = await RouteBannerModel.create({name: "secret", ownerId: adminId});
509
+ const res = await agent
510
+ .get(`/sync/entities?collection=routeBanners&ids=${doc._id}`)
511
+ .expect(403);
512
+ expect(res.body.title).toMatch(/denied/);
513
+ });
514
+
515
+ it("passes string ids through uncast for models with string _ids", async () => {
516
+ registerSync({
517
+ config: {scope: {type: "owner"}},
518
+ model: RouteNoteModel as unknown as Model<unknown>,
519
+ options: authedOptions,
520
+ routePath: "/routeNotes",
521
+ });
522
+ await RouteNoteModel.collection.deleteMany({});
523
+ await RouteNoteModel.create({_id: "note-1", body: "hello", ownerId: notAdminId});
524
+
525
+ const res = await agent
526
+ .get("/sync/entities?collection=routeNotes&ids=note-1,not-an-object-id")
527
+ .expect(200);
528
+ expect(res.body.entities.map((e: SnapshotEntity) => e.id)).toEqual(["note-1"]);
529
+ });
530
+ });
531
+
345
532
  describe("POST /sync/mutate", () => {
346
533
  it("requires authentication", async () => {
347
534
  await server
@@ -753,6 +940,113 @@ describe("sync routes", () => {
753
940
  });
754
941
  });
755
942
 
943
+ describe("GET /sync/entities admin window (Task 3.4)", () => {
944
+ it("returns another owner's ids for an admin when adminBroadcast is true", async () => {
945
+ clearSyncRegistry();
946
+ registerSync({
947
+ config: {adminBroadcast: true, scope: {type: "owner"}},
948
+ model: RouteStuffModel as unknown as Model<unknown>,
949
+ options: authedOptions,
950
+ routePath: "/routeStuff",
951
+ });
952
+ const mine = await RouteStuffModel.create({name: "theirs", ownerId: notAdminId});
953
+ const missingId = new Types.ObjectId().toString();
954
+
955
+ const res = await adminAgent
956
+ .get(`/sync/entities?collection=routeStuff&ids=${mine._id},${missingId}`)
957
+ .expect(200);
958
+ assert.equal(res.body.entities.length, 1);
959
+ assert.equal(res.body.entities[0].id, String(mine._id));
960
+ });
961
+
962
+ it("still scopes a non-admin to streams they belong to when adminBroadcast is true", async () => {
963
+ clearSyncRegistry();
964
+ registerSync({
965
+ config: {adminBroadcast: true, scope: {type: "owner"}},
966
+ model: RouteStuffModel as unknown as Model<unknown>,
967
+ options: authedOptions,
968
+ routePath: "/routeStuff",
969
+ });
970
+ const theirs = await RouteStuffModel.create({name: "admin-owned", ownerId: adminId});
971
+
972
+ const res = await agent
973
+ .get(`/sync/entities?collection=routeStuff&ids=${theirs._id}`)
974
+ .expect(200);
975
+ assert.deepEqual(res.body.entities, []);
976
+ });
977
+
978
+ it("does not cross-owner hydrate when accessControl denies admin:access", async () => {
979
+ clearSyncRegistry();
980
+ registerSync({
981
+ config: {adminBroadcast: true, scope: {type: "owner"}},
982
+ model: RouteStuffModel as unknown as Model<unknown>,
983
+ options: authedOptions,
984
+ routePath: "/routeStuff",
985
+ });
986
+ const theirs = await RouteStuffModel.create({name: "flag-admin-owned", ownerId: notAdminId});
987
+ const gatedApp = getBaseServer();
988
+ setupAuth(gatedApp, UserModel as unknown as AuthUserModel);
989
+ addAuthRoutes(gatedApp, UserModel as unknown as AuthUserModel);
990
+ new SyncApp({
991
+ accessControl: {
992
+ can: async () => ({allowed: false}),
993
+ } as never,
994
+ getUserScopes: () => ["org1"],
995
+ }).register(gatedApp);
996
+ const gatedAdmin = await authAsUser(gatedApp, "admin");
997
+
998
+ const res = await gatedAdmin
999
+ .get(`/sync/entities?collection=routeStuff&ids=${theirs._id}`)
1000
+ .expect(200);
1001
+ assert.deepEqual(res.body.entities, []);
1002
+ });
1003
+
1004
+ it("omits ids excluded by a registered AdminApp queryFilter", async () => {
1005
+ clearSyncRegistry();
1006
+ registerSync({
1007
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1008
+ model: RouteStuffModel as unknown as Model<unknown>,
1009
+ options: authedOptions,
1010
+ routePath: "/routeStuff",
1011
+ });
1012
+ registerAdminBroadcastScope("SyncRouteStuff", {
1013
+ listPermissions: [() => true],
1014
+ queryFilter: () => ({ownerId: adminId}),
1015
+ readPermissions: [() => true],
1016
+ });
1017
+ const inScope = await RouteStuffModel.create({name: "in-tenant", ownerId: adminId});
1018
+ const outOfScope = await RouteStuffModel.create({name: "other-tenant", ownerId: notAdminId});
1019
+
1020
+ const res = await adminAgent
1021
+ .get(`/sync/entities?collection=routeStuff&ids=${inScope._id},${outOfScope._id}`)
1022
+ .expect(200);
1023
+ assert.deepEqual(
1024
+ res.body.entities.map((entity: SnapshotEntity) => entity.id),
1025
+ [String(inScope._id)]
1026
+ );
1027
+ });
1028
+
1029
+ it("returns no entities when AdminApp list permission is denied", async () => {
1030
+ clearSyncRegistry();
1031
+ registerSync({
1032
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1033
+ model: RouteStuffModel as unknown as Model<unknown>,
1034
+ options: authedOptions,
1035
+ routePath: "/routeStuff",
1036
+ });
1037
+ registerAdminBroadcastScope("SyncRouteStuff", {
1038
+ listPermissions: [() => false],
1039
+ readPermissions: [() => true],
1040
+ });
1041
+ const theirs = await RouteStuffModel.create({name: "hidden-model", ownerId: notAdminId});
1042
+
1043
+ const res = await adminAgent
1044
+ .get(`/sync/entities?collection=routeStuff&ids=${theirs._id}`)
1045
+ .expect(200);
1046
+ assert.deepEqual(res.body.entities, []);
1047
+ });
1048
+ });
1049
+
756
1050
  describe("GET /sync/key", () => {
757
1051
  it("requires authentication", async () => {
758
1052
  await server.get("/sync/key").expect(401);
@@ -9,6 +9,7 @@
9
9
  */
10
10
 
11
11
  import {afterEach, beforeAll, beforeEach, describe, expect, it} from "bun:test";
12
+ import {assert} from "chai";
12
13
  import mongoose, {type Model, model, Schema} from "mongoose";
13
14
  import type {Server} from "socket.io";
14
15
 
@@ -22,6 +23,7 @@ import {
22
23
  import {clearRealtimeRegistry, registerRealtime} from "../realtime/registry";
23
24
  import {setupDb} from "../tests";
24
25
  import {defaultResponseHandler} from "../transformers";
26
+ import {registerAdminBroadcastScope} from "./adminBroadcastScope";
25
27
  import {SyncCounter, SyncMutation, SyncScopeMove} from "./models";
26
28
  import {MAX_SYNC_MUTATIONS_PER_BATCH} from "./mutationHandler";
27
29
  import {
@@ -271,6 +273,102 @@ describe("installSyncSocketHandlers — subscribe/unsubscribe", () => {
271
273
  });
272
274
  });
273
275
 
276
+ it("window mode joins {collection}|admin and does not emit snapshot pages", async () => {
277
+ clearSyncRegistry();
278
+ registerSync({
279
+ config: {adminBroadcast: true, scope: {type: "owner"}},
280
+ model: SockStuffModel as unknown as Model<unknown>,
281
+ options: ownerReadOptions,
282
+ routePath: "/sockStuff",
283
+ });
284
+ const socket = createMockSocket({admin: true, id: "user1"});
285
+ install(socket);
286
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
287
+
288
+ assert.isTrue(socket.rooms.has("sync:sockStuff|admin"));
289
+ assert.isFalse(socket.rooms.has("sync:sockStuff|owner:user1"));
290
+ const subscribed = socket.emitted.filter((e) => e.event === "sync:subscribed");
291
+ assert.deepEqual(
292
+ subscribed.map((e) => e.payload),
293
+ [{collection: "sockStuff", mode: "window", streams: ["sockStuff|admin"]}]
294
+ );
295
+ const snapshotLike = socket.emitted.filter(
296
+ (e) => e.event.includes("snapshot") || (e.payload as {entities?: unknown})?.entities
297
+ );
298
+ assert.deepEqual(snapshotLike, []);
299
+ });
300
+
301
+ it("nacks window subscribe when the caller is not admin", async () => {
302
+ clearSyncRegistry();
303
+ registerSync({
304
+ config: {adminBroadcast: true, scope: {type: "owner"}},
305
+ model: SockStuffModel as unknown as Model<unknown>,
306
+ options: ownerReadOptions,
307
+ routePath: "/sockStuff",
308
+ });
309
+ const socket = createMockSocket({admin: false, id: "user1"});
310
+ install(socket);
311
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
312
+
313
+ assert.isFalse(socket.rooms.has("sync:sockStuff|admin"));
314
+ assert.deepEqual(
315
+ socket.emitted.filter((e) => e.event === "sync:subscribed"),
316
+ []
317
+ );
318
+ const errors = syncErrors(socket);
319
+ assert.equal(errors.length, 1);
320
+ assert.equal(errors[0].collection, "sockStuff");
321
+ assert.match(errors[0].message, /admin/i);
322
+ });
323
+
324
+ it("nacks window subscribe when accessControl denies admin:access", async () => {
325
+ clearSyncRegistry();
326
+ registerSync({
327
+ config: {adminBroadcast: true, scope: {type: "owner"}},
328
+ model: SockStuffModel as unknown as Model<unknown>,
329
+ options: ownerReadOptions,
330
+ routePath: "/sockStuff",
331
+ });
332
+ const socket = createMockSocket({admin: true, id: "user1"});
333
+ install(socket, {
334
+ accessControl: {
335
+ can: async () => ({allowed: false}),
336
+ } as never,
337
+ });
338
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
339
+
340
+ assert.isFalse(socket.rooms.has("sync:sockStuff|admin"));
341
+ assert.deepEqual(
342
+ socket.emitted.filter((e) => e.event === "sync:subscribed"),
343
+ []
344
+ );
345
+ const errors = syncErrors(socket);
346
+ assert.equal(errors.length, 1);
347
+ assert.match(errors[0].message, /admin panel access/i);
348
+ });
349
+
350
+ it("nacks window subscribe when AdminApp list permission is denied", async () => {
351
+ clearSyncRegistry();
352
+ registerSync({
353
+ config: {adminBroadcast: true, scope: {type: "owner"}},
354
+ model: SockStuffModel as unknown as Model<unknown>,
355
+ options: ownerReadOptions,
356
+ routePath: "/sockStuff",
357
+ });
358
+ registerAdminBroadcastScope("SockStuff", {
359
+ listPermissions: [() => false],
360
+ readPermissions: [() => true],
361
+ });
362
+ const socket = createMockSocket({admin: true, id: "user1"});
363
+ install(socket);
364
+ await socket.trigger("sync:subscribe", {collections: ["sockStuff"], mode: "window"});
365
+
366
+ assert.isFalse(socket.rooms.has("sync:sockStuff|admin"));
367
+ const errors = syncErrors(socket);
368
+ assert.equal(errors.length, 1);
369
+ assert.match(errors[0].message, /admin collection access/i);
370
+ });
371
+
274
372
  it("owner scope never uses a client-supplied user id", async () => {
275
373
  const socket = createMockSocket({id: "user1"});
276
374
  install(socket);
@@ -1027,6 +1125,100 @@ describe("emitSyncDeltaForChange", () => {
1027
1125
  expect((delta.data as Record<string, unknown>).id).toBe("doc-1");
1028
1126
  });
1029
1127
 
1128
+ it("adminBroadcast true: create also emits to {collection}|admin", async () => {
1129
+ clearSyncRegistry();
1130
+ registerSync({
1131
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1132
+ model: SockStuffModel as unknown as Model<unknown>,
1133
+ options: ownerReadOptions,
1134
+ routePath: "/sockStuff",
1135
+ });
1136
+ const entry = findSyncEntryByCollectionTag("sockStuff") as SyncRegistryEntry;
1137
+ const io = makeTrackedIo();
1138
+ io.addSocketToRoom(syncRoomForStream("sockStuff|owner:user1"), {admin: false, id: "user1"});
1139
+ io.addSocketToRoom(syncRoomForStream("sockStuff|admin"), {admin: true, id: "admin1"});
1140
+
1141
+ await emitSyncDeltaForChange({
1142
+ change: makeChange({
1143
+ fullDocument: {_id: "doc-admin-fan", _syncSeq: 11, name: "hello", ownerId: "user1"},
1144
+ operationType: "insert",
1145
+ }),
1146
+ docId: "doc-admin-fan",
1147
+ entry,
1148
+ io,
1149
+ logDebug: () => {},
1150
+ });
1151
+
1152
+ const deltas = io.emissions
1153
+ .filter((e) => e.event === "sync:delta")
1154
+ .map((e) => e.payload as SyncDelta);
1155
+ const streams = deltas.map((d) => d.stream).sort();
1156
+ assert.deepEqual(streams, ["sockStuff|admin", "sockStuff|owner:user1"]);
1157
+ const adminDelta = deltas.find((d) => d.stream === "sockStuff|admin");
1158
+ const ownerDelta = deltas.find((d) => d.stream === "sockStuff|owner:user1");
1159
+ assert.strictEqual(adminDelta?.method, "create");
1160
+ assert.strictEqual(adminDelta?.seq, 11);
1161
+ assert.strictEqual(ownerDelta?.method, "create");
1162
+ assert.strictEqual(ownerDelta?.seq, 11);
1163
+ });
1164
+
1165
+ it("adminBroadcast room skips sockets excluded by AdminApp queryFilter", async () => {
1166
+ clearSyncRegistry();
1167
+ registerSync({
1168
+ config: {adminBroadcast: true, scope: {type: "owner"}},
1169
+ model: SockStuffModel as unknown as Model<unknown>,
1170
+ options: ownerReadOptions,
1171
+ routePath: "/sockStuff",
1172
+ });
1173
+ registerAdminBroadcastScope("SockStuff", {
1174
+ listPermissions: [() => true],
1175
+ queryFilter: () => ({ownerId: "acme"}),
1176
+ readPermissions: [() => true],
1177
+ });
1178
+ const entry = findSyncEntryByCollectionTag("sockStuff") as SyncRegistryEntry;
1179
+ const io = makeTrackedIo();
1180
+ io.addSocketToRoom(syncRoomForStream("sockStuff|admin"), {admin: true, id: "admin1"});
1181
+
1182
+ await emitSyncDeltaForChange({
1183
+ change: makeChange({
1184
+ fullDocument: {_id: "doc-other-tenant", _syncSeq: 12, name: "hello", ownerId: "user1"},
1185
+ operationType: "insert",
1186
+ }),
1187
+ docId: "doc-other-tenant",
1188
+ entry,
1189
+ io,
1190
+ logDebug: () => {},
1191
+ });
1192
+
1193
+ const adminDeltas = io.emissions.filter(
1194
+ (e) => e.event === "sync:delta" && (e.payload as SyncDelta).stream === "sockStuff|admin"
1195
+ );
1196
+ assert.deepEqual(adminDeltas, []);
1197
+ });
1198
+
1199
+ it("adminBroadcast false: create emits only the owner stream", async () => {
1200
+ const entry = ownerEntry();
1201
+ const io = makeTrackedIo();
1202
+ io.addSocketToRoom(syncRoomForStream("sockStuff|owner:user1"), {admin: false, id: "user1"});
1203
+ io.addSocketToRoom(syncRoomForStream("sockStuff|admin"), {admin: true, id: "admin1"});
1204
+
1205
+ await emitSyncDeltaForChange({
1206
+ change: makeChange({
1207
+ fullDocument: {_id: "doc-no-fan", _syncSeq: 2, name: "hello", ownerId: "user1"},
1208
+ operationType: "insert",
1209
+ }),
1210
+ docId: "doc-no-fan",
1211
+ entry,
1212
+ io,
1213
+ logDebug: () => {},
1214
+ });
1215
+
1216
+ const streams = io.emissions
1217
+ .filter((e) => e.event === "sync:delta")
1218
+ .map((e) => (e.payload as SyncDelta).stream);
1219
+ assert.deepEqual(streams, ["sockStuff|owner:user1"]);
1220
+ });
1221
+
1030
1222
  it("emits a delta when the REST responseHandler serializes a BSON post-image", async () => {
1031
1223
  const entry = ownerEntry();
1032
1224
  entry.options = {
@@ -1245,6 +1437,43 @@ describe("emitSyncDeltaForChange", () => {
1245
1437
  expect(io.emissions.filter((e) => e.event === "sync:delta")).toHaveLength(0);
1246
1438
  });
1247
1439
 
1440
+ it("logs and skips changes without a full document", async () => {
1441
+ const entry = ownerEntry();
1442
+ const io = makeTrackedIo();
1443
+ const logs: string[] = [];
1444
+
1445
+ await emitSyncDeltaForChange({
1446
+ change: makeChange({operationType: "update"}),
1447
+ docId: "doc-no-image",
1448
+ entry,
1449
+ io,
1450
+ logDebug: (message) => logs.push(message),
1451
+ });
1452
+
1453
+ assert.deepEqual(logs, ["[sync] Skipping sockStuff/doc-no-image: change has no fullDocument"]);
1454
+ assert.isEmpty(io.emissions);
1455
+ });
1456
+
1457
+ it("skips changes whose operation type does not map to a sync method", async () => {
1458
+ const entry = ownerEntry();
1459
+ const io = makeTrackedIo();
1460
+ const logs: string[] = [];
1461
+
1462
+ await emitSyncDeltaForChange({
1463
+ change: makeChange({
1464
+ fullDocument: {_id: "doc-invalid", _syncSeq: 1, ownerId: "user1"},
1465
+ operationType: "invalidate",
1466
+ }),
1467
+ docId: "doc-invalid",
1468
+ entry,
1469
+ io,
1470
+ logDebug: (message) => logs.push(message),
1471
+ });
1472
+
1473
+ assert.isEmpty(logs);
1474
+ assert.isEmpty(io.emissions);
1475
+ });
1476
+
1248
1477
  it("applies the sync responseHandler to delta data", async () => {
1249
1478
  clearSyncRegistry();
1250
1479
  registerSync({
package/src/sync/types.ts CHANGED
@@ -39,6 +39,13 @@ export type SyncScope = SyncScopeOwner | SyncScopeTenant | SyncScopeBroadcast |
39
39
  * (seq stamping) — validated at registration.
40
40
  */
41
41
  export interface SyncConfig {
42
+ /**
43
+ * When true, change-stream `sync:delta` emission also fans in to `{collection}|admin`
44
+ * in addition to the owner/tenant/broadcast/custom stream. Default false. App clients
45
+ * keep their existing scope; only admin window subscribers join `|admin`. Join
46
+ * permission is admin-only (same checks as `/admin/*`), not owner-stream membership.
47
+ */
48
+ adminBroadcast?: boolean;
42
49
  /** Which stream a document belongs to. Multi-tenant by default via the tenant scope. */
43
50
  scope: SyncScope;
44
51
  /**
@@ -65,6 +72,12 @@ export interface SyncConfig {
65
72
 
66
73
  export type SyncMutationOperation = "create" | "update" | "delete";
67
74
 
75
+ /** Explicit client marker for admin-panel windowed sync writes. */
76
+ export type SyncMutationMode = "adminWindow";
77
+
78
+ /** `sync:subscribe` / `sync:subscribed` window mode for admin fan-in (no snapshot paging). */
79
+ export type SyncSubscribeMode = "window";
80
+
68
81
  /** A single entity in a snapshot response. */
69
82
  export interface SyncEntityPayload {
70
83
  /** Document id. */
@@ -138,6 +151,13 @@ export interface SyncMutateRequest {
138
151
  data?: Record<string, unknown>;
139
152
  /** The `_syncSeq` the client last saw for this document; enables LWW conflict detection. */
140
153
  baseVersion?: number;
154
+ /**
155
+ * When `"adminWindow"`, the server applies AdminApp write semantics (RBAC,
156
+ * writeOwned, readonly/hidden stripping, audit) instead of product sync
157
+ * permissions. Ignored unless the collection is `adminBroadcast`, the caller
158
+ * has admin-window access, and AdminApp registered a write scope.
159
+ */
160
+ mutationMode?: SyncMutationMode;
141
161
  }
142
162
 
143
163
  /** Successful mutation acknowledgement. */