@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
@@ -4,7 +4,15 @@ import mongoose from "mongoose";
4
4
  import type {User} from "../auth";
5
5
  import {APIError, isAPIError} from "../errors";
6
6
  import {createFeatureFlaggedLogger, logger} from "../logger";
7
+ import {resolveOrgContext, runWithOrgContext} from "../orgs/orgContext";
7
8
  import {findOneOrNoneFor} from "../plugins";
9
+ import {
10
+ type AdminWindowMutationScope,
11
+ buildAdminWindowExecutorOptions,
12
+ emitAdminWindowMutationAudit,
13
+ prepareAdminWindowMutation,
14
+ withAdminWindowMutationRequestContext,
15
+ } from "./adminWindowMutation";
8
16
  import {
9
17
  executeCreate,
10
18
  executeDelete,
@@ -16,6 +24,7 @@ import {
16
24
  } from "./executors";
17
25
  import {SYNC_MUTATION_LEASE_MS, SyncMutation, type SyncMutationDocument} from "./models";
18
26
  import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
27
+ import type {SyncAppOptions} from "./routes";
19
28
  import {serializeSyncDoc} from "./routes";
20
29
  import {getScopeField} from "./streams";
21
30
  import type {
@@ -511,6 +520,38 @@ const finalizeAlreadyApplied = async ({
511
520
  * - delete: idempotent already (executeDelete on an already-deleted tombstone is a no-op
512
521
  * success in this codebase's soft-delete model), so no special tolerance is needed.
513
522
  */
523
+ const organizationIdFromRequest = (request: express.Request): string | undefined => {
524
+ if (typeof request.header !== "function") {
525
+ return undefined;
526
+ }
527
+ const raw = request.header("X-Organization-Id");
528
+ if (typeof raw !== "string") {
529
+ return undefined;
530
+ }
531
+ const trimmed = raw.trim();
532
+ if (!trimmed) {
533
+ return undefined;
534
+ }
535
+ return trimmed;
536
+ };
537
+
538
+ const withRequestOrgContext = async ({
539
+ request,
540
+ run,
541
+ user,
542
+ }: {
543
+ request: express.Request;
544
+ run: () => Promise<SyncMutationOutcome>;
545
+ user: User;
546
+ }): Promise<SyncMutationOutcome> => {
547
+ const organizationId = organizationIdFromRequest(request);
548
+ if (!organizationId) {
549
+ return run();
550
+ }
551
+ const context = await resolveOrgContext({organizationId, required: false, user});
552
+ return runWithOrgContext(context, run);
553
+ };
554
+
514
555
  const applyClaimedMutation = async ({
515
556
  claimed,
516
557
  entry,
@@ -518,6 +559,7 @@ const applyClaimedMutation = async ({
518
559
  request,
519
560
  user,
520
561
  scopeResolver,
562
+ syncOptions,
521
563
  isLeaseTakeover = false,
522
564
  }: {
523
565
  claimed: SyncMutationDocument;
@@ -526,44 +568,103 @@ const applyClaimedMutation = async ({
526
568
  request: express.Request;
527
569
  user: User;
528
570
  scopeResolver?: SyncMutationScopeResolver;
571
+ syncOptions?: SyncAppOptions;
529
572
  /** True when `claimed` was re-claimed from a stale lease rather than freshly inserted. */
530
573
  isLeaseTakeover?: boolean;
574
+ }): Promise<SyncMutationOutcome> => {
575
+ return withRequestOrgContext({
576
+ request,
577
+ run: () =>
578
+ applyClaimedMutationInContext({
579
+ claimed,
580
+ entry,
581
+ isLeaseTakeover,
582
+ mutation,
583
+ request,
584
+ scopeResolver,
585
+ syncOptions,
586
+ user,
587
+ }),
588
+ user,
589
+ });
590
+ };
591
+
592
+ const applyClaimedMutationInContext = async ({
593
+ claimed,
594
+ entry,
595
+ mutation,
596
+ request,
597
+ user,
598
+ scopeResolver,
599
+ syncOptions,
600
+ isLeaseTakeover = false,
601
+ }: {
602
+ claimed: SyncMutationDocument;
603
+ entry: SyncRegistryEntry;
604
+ mutation: SyncMutateRequest;
605
+ request: express.Request;
606
+ user: User;
607
+ scopeResolver?: SyncMutationScopeResolver;
608
+ syncOptions?: SyncAppOptions;
609
+ isLeaseTakeover?: boolean;
531
610
  }): Promise<SyncMutationOutcome> => {
532
611
  const mutationId = mutation.mutationId;
612
+ let adminWindowScope: AdminWindowMutationScope | undefined;
533
613
 
534
614
  try {
535
615
  // Task 9.18: resolving the model must be INSIDE the try — a MissingSchemaError thrown
536
616
  // here would escape without finalizing the claimed row, wedging the mutationId
537
617
  // `pending` for the whole lease window instead of nacking it.
538
618
  const model = mongoose.model(entry.modelName);
539
- // C6 (M6): sync-boundary write-scope backstop before any write pipeline runs.
540
- await enforceWriteScope({
541
- data: mutation.data,
619
+ const adminWindow = await prepareAdminWindowMutation({
542
620
  entry,
543
- operation: mutation.operation,
544
- scopeResolver,
621
+ mutation,
622
+ req: request,
623
+ syncOptions,
545
624
  user,
546
625
  });
626
+ let effectiveMutation = mutation;
627
+ if (adminWindow) {
628
+ effectiveMutation = adminWindow.mutation;
629
+ adminWindowScope = adminWindow.scope;
630
+ } else {
631
+ // C6 (M6): product-path write-scope backstop before any write pipeline runs.
632
+ await enforceWriteScope({
633
+ data: effectiveMutation.data,
634
+ entry,
635
+ operation: effectiveMutation.operation,
636
+ scopeResolver,
637
+ user,
638
+ });
639
+ }
640
+ const skipPermissionChecks = Boolean(adminWindowScope);
641
+ const executorOptions = adminWindowScope
642
+ ? buildAdminWindowExecutorOptions({productOptions: entry.options, scope: adminWindowScope})
643
+ : entry.options;
644
+ const executorRequest = adminWindowScope
645
+ ? withAdminWindowMutationRequestContext({mutation: effectiveMutation, req: request})
646
+ : request;
547
647
 
548
648
  let doc: mongoose.Document;
549
649
  let postHook: (() => Promise<void>) | undefined;
550
- if (mutation.operation === "create") {
551
- const body: Record<string, unknown> = {...(mutation.data ?? {})};
552
- if (mutation.id) {
553
- body._id = mutation.id;
650
+ if (effectiveMutation.operation === "create") {
651
+ const body: Record<string, unknown> = {...(effectiveMutation.data ?? {})};
652
+ if (effectiveMutation.id) {
653
+ body._id = effectiveMutation.id;
554
654
  }
555
655
  try {
556
656
  const result = await executeCreate({
557
657
  body,
558
658
  model,
559
- options: entry.options,
560
- req: request,
659
+ options: executorOptions,
660
+ req: executorRequest,
661
+ skipPermissionChecks,
561
662
  skipPostHooks: true,
562
663
  user,
563
664
  });
564
665
  doc = result.doc;
565
666
  postHook = (): Promise<void> =>
566
- runPostCreate({doc: result.doc, options: entry.options, request});
667
+ runPostCreate({doc: result.doc, options: executorOptions, request: executorRequest});
567
668
  } catch (createError: unknown) {
568
669
  // M4 (lease takeover only): an E11000 on the exact target _id is
569
670
  // tolerated as "already applied" — a prior (crashed) attempt at
@@ -572,8 +673,12 @@ const applyClaimedMutation = async ({
572
673
  // client-minted UUIDs make a genuine unrelated _id collision
573
674
  // vanishingly unlikely, so gating this on isLeaseTakeover keeps the
574
675
  // tolerance scoped to its actual crash-recovery purpose.
575
- if (isLeaseTakeover && isE11000Error(createError) && typeof mutation.id === "string") {
576
- const existing = await findOneOrNoneFor(model, {_id: mutation.id});
676
+ if (
677
+ isLeaseTakeover &&
678
+ isE11000Error(createError) &&
679
+ typeof effectiveMutation.id === "string"
680
+ ) {
681
+ const existing = await findOneOrNoneFor(model, {_id: effectiveMutation.id});
577
682
  if (existing) {
578
683
  const {resultId, resultSeq} = await finalizeAlreadyApplied({
579
684
  claimedId: claimed._id,
@@ -585,15 +690,16 @@ const applyClaimedMutation = async ({
585
690
  }
586
691
  throw createError;
587
692
  }
588
- } else if (mutation.operation === "update") {
693
+ } else if (effectiveMutation.operation === "update") {
589
694
  try {
590
695
  const result = await executeUpdate({
591
- body: mutation.data ?? {},
592
- concurrencyCheck: {baseSeq: mutation.baseVersion ?? 0, type: "seq"},
593
- id: mutation.id as string,
696
+ body: effectiveMutation.data ?? {},
697
+ concurrencyCheck: {baseSeq: effectiveMutation.baseVersion ?? 0, type: "seq"},
698
+ id: effectiveMutation.id as string,
594
699
  model,
595
- options: entry.options,
596
- req: request,
700
+ options: executorOptions,
701
+ req: executorRequest,
702
+ skipPermissionChecks,
597
703
  skipPostHooks: true,
598
704
  user,
599
705
  });
@@ -603,7 +709,13 @@ const applyClaimedMutation = async ({
603
709
  // biome-ignore lint/style/noNonNullAssertion: executeUpdate with skipPostHooks always returns cleanedBody/prevDoc.
604
710
  const prevDoc = result.prevDoc!;
605
711
  postHook = (): Promise<void> =>
606
- runPostUpdate({cleanedBody, doc: result.doc, options: entry.options, prevDoc, request});
712
+ runPostUpdate({
713
+ cleanedBody,
714
+ doc: result.doc,
715
+ options: executorOptions,
716
+ prevDoc,
717
+ request: executorRequest,
718
+ });
607
719
  } catch (updateError: unknown) {
608
720
  // M4 (lease takeover only): a conflict whose serverSeq is EXACTLY
609
721
  // this mutation's own expected post-write seq COULD mean the write
@@ -619,8 +731,8 @@ const applyClaimedMutation = async ({
619
731
  isLeaseTakeover &&
620
732
  isExecutorConflictError(updateError) &&
621
733
  updateError.conflictType === "seq" &&
622
- updateError.serverSeq === (mutation.baseVersion ?? 0) + 1 &&
623
- docMatchesMutationData(updateError.doc, mutation.data)
734
+ updateError.serverSeq === (effectiveMutation.baseVersion ?? 0) + 1 &&
735
+ docMatchesMutationData(updateError.doc, effectiveMutation.data)
624
736
  ) {
625
737
  const {resultId, resultSeq} = await finalizeAlreadyApplied({
626
738
  claimedId: claimed._id,
@@ -633,16 +745,17 @@ const applyClaimedMutation = async ({
633
745
  }
634
746
  } else {
635
747
  const result = await executeDelete({
636
- id: mutation.id as string,
748
+ id: effectiveMutation.id as string,
637
749
  model,
638
- options: entry.options,
639
- req: request,
750
+ options: executorOptions,
751
+ req: executorRequest,
752
+ skipPermissionChecks,
640
753
  skipPostHooks: true,
641
754
  user,
642
755
  });
643
756
  doc = result.doc;
644
757
  postHook = (): Promise<void> =>
645
- runPostDelete({doc: result.doc, options: entry.options, request});
758
+ runPostDelete({doc: result.doc, options: executorOptions, request: executorRequest});
646
759
  }
647
760
 
648
761
  const resultId = String(doc._id);
@@ -670,6 +783,22 @@ const applyClaimedMutation = async ({
670
783
  mutationId,
671
784
  });
672
785
  }
786
+ if (adminWindowScope?.emitAudit) {
787
+ try {
788
+ await emitAdminWindowMutationAudit({
789
+ doc,
790
+ mutation: effectiveMutation,
791
+ req: executorRequest,
792
+ scope: adminWindowScope,
793
+ });
794
+ } catch (auditError: unknown) {
795
+ logger.error("[sync] Admin window audit hook failed after a committed mutation", {
796
+ collection: mutation.collection,
797
+ error: errorMessageOf(auditError),
798
+ mutationId,
799
+ });
800
+ }
801
+ }
673
802
  return {
674
803
  ack: {id: resultId, mutationId, seq: resultSeq, ...(warning ? {warning} : {})},
675
804
  type: "ack",
@@ -692,12 +821,14 @@ export const applySyncMutation = async ({
692
821
  mutation,
693
822
  req,
694
823
  scopeResolver,
824
+ syncOptions,
695
825
  }: {
696
826
  user: User;
697
827
  mutation: SyncMutateRequest;
698
828
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
699
829
  req?: express.Request;
700
830
  scopeResolver?: SyncMutationScopeResolver;
831
+ syncOptions?: SyncAppOptions;
701
832
  }): Promise<SyncMutationOutcome> => {
702
833
  const mutationId = typeof mutation?.mutationId === "string" ? mutation.mutationId : "";
703
834
  const validationNack = (message: string): SyncMutationOutcome =>
@@ -753,6 +884,7 @@ export const applySyncMutation = async ({
753
884
  mutation,
754
885
  request,
755
886
  scopeResolver,
887
+ syncOptions,
756
888
  user,
757
889
  }),
758
890
  request,
@@ -760,7 +892,15 @@ export const applySyncMutation = async ({
760
892
  });
761
893
  }
762
894
 
763
- return applyClaimedMutation({claimed, entry, mutation, request, scopeResolver, user});
895
+ return applyClaimedMutation({
896
+ claimed,
897
+ entry,
898
+ mutation,
899
+ request,
900
+ scopeResolver,
901
+ syncOptions,
902
+ user,
903
+ });
764
904
  };
765
905
 
766
906
  /** Outcome of a batch validation pre-check (before any mutation is attempted). */
@@ -831,16 +971,18 @@ export const applySyncMutationBatch = async ({
831
971
  mutations,
832
972
  req,
833
973
  scopeResolver,
974
+ syncOptions,
834
975
  }: {
835
976
  user: User;
836
977
  mutations: SyncMutateRequest[];
837
978
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
838
979
  req?: express.Request;
839
980
  scopeResolver?: SyncMutationScopeResolver;
981
+ syncOptions?: SyncAppOptions;
840
982
  }): Promise<SyncMutateBatchResponse> => {
841
983
  const results: SyncMutateBatchResponse["results"] = [];
842
984
  for (const mutation of mutations) {
843
- const outcome = await applySyncMutation({mutation, req, scopeResolver, user});
985
+ const outcome = await applySyncMutation({mutation, req, scopeResolver, syncOptions, user});
844
986
  results.push(outcome);
845
987
  if (outcome.type === "nack") {
846
988
  // Stop-on-error: the client re-sends everything after this point, and
@@ -8,6 +8,8 @@ import {
8
8
  replaceCollectionOptions,
9
9
  } from "../collectionRegistry";
10
10
  import {logger} from "../logger";
11
+ import {clearAdminBroadcastScopes} from "./adminBroadcastScope";
12
+ import {clearAdminWindowMutationScopes} from "./adminWindowMutation";
11
13
  import {
12
14
  clearSyncIndexCreationTasks,
13
15
  ensureSyncIndexes,
@@ -116,4 +118,6 @@ export const findSyncEntryByCollectionName = (
116
118
  export const clearSyncRegistry = (): void => {
117
119
  clearCollectionRegistry();
118
120
  clearSyncIndexCreationTasks();
121
+ clearAdminBroadcastScopes();
122
+ clearAdminWindowMutationScopes();
119
123
  };
@@ -6,6 +6,13 @@ import {APIError, apiErrorMiddleware, apiUnauthorizedMiddleware} from "../errors
6
6
  import {logger} from "../logger";
7
7
  import {checkPermissions} from "../permissions";
8
8
  import {findOneOrNoneFor} from "../plugins";
9
+ import type {AnyTerrenoAccess} from "../rbac/types";
10
+ import {
11
+ canListAdminBroadcastScope,
12
+ getAdminBroadcastScope,
13
+ resolveAdminBroadcastQueryFilter,
14
+ } from "./adminBroadcastScope";
15
+ import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
9
16
  import {
10
17
  computeStableFrontier,
11
18
  getCompactedThroughSeq,
@@ -54,6 +61,18 @@ export interface SyncAppOptions {
54
61
  getUserScopes?: (user: User, entry: SyncRegistryEntry) => Promise<string[]> | string[];
55
62
  /** Default page size for snapshots (default 100, max 100). */
56
63
  defaultSnapshotLimit?: number;
64
+ /**
65
+ * When set, `{collection}|admin` window subscribe and cross-owner entity
66
+ * hydrate require `admin:access` instead of the legacy `user.admin` flag.
67
+ * AdminApp also registers per-model list/read/`queryFilter` so hydrate and
68
+ * `|admin` deltas match `/admin` REST, not product `IsOwner`.
69
+ */
70
+ accessControl?: AnyTerrenoAccess;
71
+ /**
72
+ * Override the admin-window gate. Defaults to `admin:access` when
73
+ * `accessControl` is set, otherwise `Permissions.IsAdmin`.
74
+ */
75
+ canOpenAdminWindow?: (user: User) => boolean | Promise<boolean>;
57
76
  }
58
77
 
59
78
  const MAX_SNAPSHOT_LIMIT = 100;
@@ -696,17 +715,38 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
696
715
  });
697
716
  }
698
717
 
699
- const memberStreams = await resolveUserStreamsForEntry({
700
- entry,
701
- getUserScopes: options.getUserScopes,
702
- user,
703
- });
718
+ const isAdminWindow =
719
+ entry.config.adminBroadcast === true &&
720
+ (await canUseAdminBroadcastWindow({
721
+ accessControl: options.accessControl,
722
+ canOpenAdminWindow: options.canOpenAdminWindow,
723
+ user,
724
+ }));
725
+ const adminScope = isAdminWindow ? getAdminBroadcastScope(entry.modelName) : undefined;
726
+ if (adminScope && !(await canListAdminBroadcastScope({scope: adminScope, user}))) {
727
+ const deniedResponse: SyncEntitiesResponse = {entities: []};
728
+ return res.json(deniedResponse);
729
+ }
730
+
731
+ const memberStreams = isAdminWindow
732
+ ? []
733
+ : await resolveUserStreamsForEntry({
734
+ entry,
735
+ getUserScopes: options.getUserScopes,
736
+ user,
737
+ });
704
738
  const memberSet = new Set(memberStreams);
705
739
 
706
740
  // Task 9.19: mirror the REST list endpoint's row-level scoping. Without this, a
707
741
  // collection that relies on `queryFilter` (rather than a per-doc read permission)
708
742
  // served every requested id here, whatever the caller was allowed to list.
709
- const queryFilterResult = await resolveSyncQueryFilter({entry, user});
743
+ // Admin window hydrate skips the *product* filter so REST-selected ids can load
744
+ // across owners, then applies AdminApp list/read/`queryFilter` when registered.
745
+ const queryFilterResult = adminScope
746
+ ? await resolveAdminBroadcastQueryFilter({scope: adminScope, user})
747
+ : isAdminWindow
748
+ ? {denied: false as const, filter: undefined}
749
+ : await resolveSyncQueryFilter({entry, user});
710
750
  if (queryFilterResult.denied) {
711
751
  const deniedResponse: SyncEntitiesResponse = {entities: []};
712
752
  return res.json(deniedResponse);
@@ -726,7 +766,9 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
726
766
 
727
767
  const entities: SyncEntityPayload[] = [];
728
768
  for (const doc of docs as mongoose.Document[]) {
729
- const allowed = await checkPermissions("read", entry.options.permissions.read, user, doc);
769
+ const allowed = adminScope
770
+ ? await checkPermissions("read", adminScope.readPermissions, user, doc)
771
+ : await checkPermissions("read", entry.options.permissions.read, user, doc);
730
772
  if (!allowed) {
731
773
  continue;
732
774
  }
@@ -736,7 +778,7 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
736
778
  doc: docObj,
737
779
  scope: entry.config.scope,
738
780
  });
739
- if (!memberSet.has(stream)) {
781
+ if (!isAdminWindow && !memberSet.has(stream)) {
740
782
  continue;
741
783
  }
742
784
  const isTombstone = Boolean(docObj.deleted);
@@ -767,6 +809,7 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
767
809
  mutation: req.body as SyncMutateRequest,
768
810
  req,
769
811
  scopeResolver: options.getUserScopes,
812
+ syncOptions: options,
770
813
  user,
771
814
  });
772
815
  if (outcome.type === "ack") {
@@ -794,6 +837,7 @@ export const addSyncRoutes = (app: express.Application, options: SyncAppOptions
794
837
  mutations,
795
838
  req,
796
839
  scopeResolver: options.getUserScopes,
840
+ syncOptions: options,
797
841
  user,
798
842
  });
799
843
  if (stage === "validation") {