@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,13 +1,21 @@
1
+ import type express from "express";
1
2
  import type {Server} from "socket.io";
2
3
 
3
4
  import type {User} from "../auth";
4
5
  import {logger} from "../logger";
6
+ import {ORGANIZATION_ID_HEADER} from "../orgs/orgContext";
5
7
  import {checkPermissions} from "../permissions";
6
8
  import {awaitSocketFullUser, type SocketWithDecodedToken} from "../realtime/socketUser";
9
+ import {canListAdminBroadcastScope, getAdminBroadcastScope} from "./adminBroadcastScope";
10
+ import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
7
11
  import type {SyncMutationOutcome} from "./mutationHandler";
8
12
  import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
9
13
  import type {SyncAppOptions} from "./routes";
10
- import {MissingScopeResolverError, resolveUserStreamsForEntry} from "./streams";
14
+ import {
15
+ adminBroadcastStream,
16
+ MissingScopeResolverError,
17
+ resolveUserStreamsForEntry,
18
+ } from "./streams";
11
19
  import {runSyncBatch, runSyncMutation} from "./syncBatch";
12
20
  import type {
13
21
  SyncMutateBatchRequest,
@@ -16,20 +24,53 @@ import type {
16
24
  SyncNack,
17
25
  } from "./types";
18
26
 
27
+ const requestFromOrganizationId = ({
28
+ organizationId,
29
+ user,
30
+ }: {
31
+ organizationId?: string;
32
+ user: User;
33
+ }): express.Request => {
34
+ const trimmed = organizationId?.trim();
35
+ if (!trimmed) {
36
+ return {user} as unknown as express.Request;
37
+ }
38
+ return {
39
+ header: (name: string): string | undefined => {
40
+ return String(name).toLowerCase() === ORGANIZATION_ID_HEADER ? trimmed : undefined;
41
+ },
42
+ user,
43
+ } as unknown as express.Request;
44
+ };
45
+
46
+ const organizationIdFromPayload = (payload: unknown): string | undefined => {
47
+ if (typeof payload !== "object" || payload === null) {
48
+ return undefined;
49
+ }
50
+ const organizationId = (payload as {organizationId?: unknown}).organizationId;
51
+ return typeof organizationId === "string" ? organizationId : undefined;
52
+ };
53
+
19
54
  /**
20
55
  * Socket handlers for the SyncDB local-first protocol:
21
56
  *
22
- * - `sync:subscribe {collections}` / `sync:unsubscribe {collections}` — resolves the
57
+ * - `sync:subscribe {collections, mode?}` / `sync:unsubscribe {collections}` — resolves the
23
58
  * caller's streams from the sync registry scope config and joins/leaves `sync:{stream}`
24
59
  * rooms. Owner scopes always use the socket's own userId (never a client-supplied one);
25
60
  * tenant and custom scopes resolve stream values via `SyncAppOptions.getUserScopes`.
61
+ * `mode: "window"` joins `{collection}|admin` only (requires `adminBroadcast` and
62
+ * admin panel access: `admin:access` when `SyncApp` has `accessControl`, else
63
+ * `user.admin`). When AdminApp has registered a broadcast scope, list
64
+ * permission for that model is required as well. Confirms with
65
+ * `sync:subscribed {mode: "window"}` without dumping snapshot pages.
26
66
  * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
27
67
  * legacy realtime rooms so the two event families never overlap.
28
68
  * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
29
69
  * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
30
70
  * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
31
71
  * - `sync:error {collection, message}` — emitted for per-collection subscribe failures
32
- * (unknown collection, permission denied, missing scope resolver, cap exceeded).
72
+ * (unknown collection, permission denied, non-admin window subscribe, missing scope
73
+ * resolver, cap exceeded).
33
74
  *
34
75
  * ## Wiring
35
76
  *
@@ -133,67 +174,112 @@ export const installSyncSocketHandlers = (
133
174
  socket.data.syncSubscriptions = subscriptions;
134
175
  }
135
176
 
136
- socket.on("sync:subscribe", async (payload: {collections?: unknown}): Promise<void> => {
137
- const collections = Array.isArray(payload?.collections) ? payload.collections : null;
138
- if (!collections) {
139
- return;
140
- }
141
- // C8: reject an oversized array up front (length check before iterating).
142
- if (collections.length > MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH) {
143
- logInfo(`[sync] User ${userId} sent an oversized sync:subscribe array`);
144
- socket.emit("sync:error", {
145
- collection: "",
146
- message: `sync:subscribe accepts at most ${MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH} collections`,
147
- });
148
- return;
149
- }
150
- for (const collection of collections) {
151
- if (typeof collection !== "string" || collection.length === 0) {
152
- continue;
153
- }
154
- if (subscriptions.has(collection)) {
155
- // Already subscribed — idempotent.
156
- continue;
157
- }
158
- if (subscriptions.size >= MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
159
- logInfo(`[sync] User ${userId} hit sync collection subscription limit`);
160
- socket.emit("sync:error", {
161
- collection,
162
- message: `Sync subscription limit of ${MAX_SYNC_COLLECTION_SUBSCRIPTIONS} collections reached`,
163
- });
164
- continue;
165
- }
166
- const entry = findSyncEntryByCollectionTag(collection);
167
- if (!entry) {
168
- socket.emit("sync:error", {collection, message: `Unknown sync collection: ${collection}`});
169
- continue;
170
- }
171
- const user = await currentUser();
172
- if (!user) {
173
- socket.emit("sync:error", {collection, message: "Authentication required"});
174
- continue;
177
+ socket.on(
178
+ "sync:subscribe",
179
+ async (payload: {collections?: unknown; mode?: unknown}): Promise<void> => {
180
+ const collections = Array.isArray(payload?.collections) ? payload.collections : null;
181
+ const isWindow = payload?.mode === "window";
182
+ if (!collections) {
183
+ return;
175
184
  }
176
- if (!(await checkPermissions("list", entry.options.permissions.list, user))) {
177
- logInfo(`[sync] User ${userId} denied sync subscription for ${collection}`);
185
+ // C8: reject an oversized array up front (length check before iterating).
186
+ if (collections.length > MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH) {
187
+ logInfo(`[sync] User ${userId} sent an oversized sync:subscribe array`);
178
188
  socket.emit("sync:error", {
179
- collection,
180
- message: `Access to sync collection ${collection} denied`,
189
+ collection: "",
190
+ message: `sync:subscribe accepts at most ${MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH} collections`,
181
191
  });
182
- continue;
183
- }
184
- const streams = await resolveUserStreams({entry, options, socket, user});
185
- if (!streams) {
186
- continue;
192
+ return;
187
193
  }
188
- const rooms = new Set(streams.map(syncRoomForStream));
189
- for (const room of rooms) {
190
- await socket.join(room);
194
+ for (const collection of collections) {
195
+ if (typeof collection !== "string" || collection.length === 0) {
196
+ continue;
197
+ }
198
+ if (subscriptions.has(collection)) {
199
+ // Already subscribed — idempotent.
200
+ continue;
201
+ }
202
+ if (subscriptions.size >= MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
203
+ logInfo(`[sync] User ${userId} hit sync collection subscription limit`);
204
+ socket.emit("sync:error", {
205
+ collection,
206
+ message: `Sync subscription limit of ${MAX_SYNC_COLLECTION_SUBSCRIPTIONS} collections reached`,
207
+ });
208
+ continue;
209
+ }
210
+ const entry = findSyncEntryByCollectionTag(collection);
211
+ if (!entry) {
212
+ socket.emit("sync:error", {
213
+ collection,
214
+ message: `Unknown sync collection: ${collection}`,
215
+ });
216
+ continue;
217
+ }
218
+ const user = await currentUser();
219
+ if (!user) {
220
+ socket.emit("sync:error", {collection, message: "Authentication required"});
221
+ continue;
222
+ }
223
+ if (!(await checkPermissions("list", entry.options.permissions.list, user))) {
224
+ logInfo(`[sync] User ${userId} denied sync subscription for ${collection}`);
225
+ socket.emit("sync:error", {
226
+ collection,
227
+ message: `Access to sync collection ${collection} denied`,
228
+ });
229
+ continue;
230
+ }
231
+ if (isWindow && entry.config.adminBroadcast !== true) {
232
+ socket.emit("sync:error", {
233
+ collection,
234
+ message: `Window subscribe requires adminBroadcast on ${collection}`,
235
+ });
236
+ continue;
237
+ }
238
+ if (
239
+ isWindow &&
240
+ !(await canUseAdminBroadcastWindow({
241
+ accessControl: options.accessControl,
242
+ canOpenAdminWindow: options.canOpenAdminWindow,
243
+ user,
244
+ }))
245
+ ) {
246
+ logInfo(`[sync] User ${userId} denied window subscribe for ${collection}`);
247
+ socket.emit("sync:error", {
248
+ collection,
249
+ message: `Window subscribe requires admin panel access for ${collection}`,
250
+ });
251
+ continue;
252
+ }
253
+ if (isWindow) {
254
+ const adminScope = getAdminBroadcastScope(entry.modelName);
255
+ if (adminScope && !(await canListAdminBroadcastScope({scope: adminScope, user}))) {
256
+ logInfo(`[sync] User ${userId} denied window subscribe list for ${collection}`);
257
+ socket.emit("sync:error", {
258
+ collection,
259
+ message: `Window subscribe requires admin collection access for ${collection}`,
260
+ });
261
+ continue;
262
+ }
263
+ }
264
+ const streams = isWindow
265
+ ? [adminBroadcastStream(collection)]
266
+ : await resolveUserStreams({entry, options, socket, user});
267
+ if (!streams) {
268
+ continue;
269
+ }
270
+ const rooms = new Set(streams.map(syncRoomForStream));
271
+ for (const room of rooms) {
272
+ await socket.join(room);
273
+ }
274
+ subscriptions.set(collection, rooms);
275
+ socket.emit(
276
+ "sync:subscribed",
277
+ isWindow ? {collection, mode: "window", streams} : {collection, streams}
278
+ );
279
+ logInfo(`[sync] User ${userId} subscribed to ${collection}: ${streams.join(", ")}`);
191
280
  }
192
- subscriptions.set(collection, rooms);
193
- socket.emit("sync:subscribed", {collection, streams});
194
- logInfo(`[sync] User ${userId} subscribed to ${collection}: ${streams.join(", ")}`);
195
281
  }
196
- });
282
+ );
197
283
 
198
284
  socket.on("sync:unsubscribe", async (payload: {collections?: unknown}): Promise<void> => {
199
285
  const collections = Array.isArray(payload?.collections) ? payload.collections : null;
@@ -250,7 +336,12 @@ export const installSyncSocketHandlers = (
250
336
  // USER's window, so opening more sockets no longer multiplies the budget.
251
337
  const {outcome, stage} = await runSyncMutation({
252
338
  mutation: payload,
339
+ req: requestFromOrganizationId({
340
+ organizationId: organizationIdFromPayload(payload),
341
+ user,
342
+ }),
253
343
  scopeResolver: options.getUserScopes,
344
+ syncOptions: options,
254
345
  user,
255
346
  });
256
347
  if (stage === "rate_limited") {
@@ -298,7 +389,12 @@ export const installSyncSocketHandlers = (
298
389
  // Task 9.20: validate -> rate limit -> apply, shared with POST /sync/mutate/batch.
299
390
  const {response, stage} = await runSyncBatch({
300
391
  mutations,
392
+ req: requestFromOrganizationId({
393
+ organizationId: organizationIdFromPayload(payload),
394
+ user,
395
+ }),
301
396
  scopeResolver: options.getUserScopes,
397
+ syncOptions: options,
302
398
  user,
303
399
  });
304
400
  if (stage === "rate_limited") {
@@ -25,6 +25,9 @@ export const getScopeField = (scope: SyncScope): string | null => {
25
25
  return null;
26
26
  };
27
27
 
28
+ /** Fan-in stream for admin window subscribers when `SyncConfig.adminBroadcast` is true. */
29
+ export const adminBroadcastStream = (collectionTag: string): string => `${collectionTag}|admin`;
30
+
28
31
  /** Build a stream key from a collection tag and a raw scope value. */
29
32
  export const streamForScopeValue = ({
30
33
  collectionTag,
@@ -65,6 +68,9 @@ export const parseStreamKey = (
65
68
  if (rest === "all") {
66
69
  return {collectionTag, scopeKind: "all", scopeValue: null};
67
70
  }
71
+ if (rest === "admin") {
72
+ return {collectionTag, scopeKind: "admin", scopeValue: null};
73
+ }
68
74
  const colon = rest.indexOf(":");
69
75
  if (colon < 0) {
70
76
  return null;
@@ -232,9 +232,10 @@ describe("registerSync validation", () => {
232
232
  ).toThrow(/workspaceId/);
233
233
  });
234
234
 
235
- it("throws on duplicate registration", () => {
235
+ it("treats duplicate registration of the same model as a no-op", () => {
236
236
  registerStuff();
237
- expect(() => registerStuff()).toThrow(/already registered/);
237
+ registerStuff();
238
+ expect(getSyncRegistry()).toHaveLength(1);
238
239
  });
239
240
 
240
241
  it("registers a compliant model and exposes lookup helpers", () => {
@@ -23,11 +23,12 @@ export const getSyncAppOptions = (app: express.Application): SyncAppOptions | un
23
23
  *
24
24
  * Registration also enqueues the bookkeeping-model index builds (`SyncCounter`,
25
25
  * `SyncMutation`, `SyncScopeMove`, `SyncKey`) for `ensureSyncIndexes()`, which
26
- * `TerrenoApp.start()` awaits before the HTTP server begins listening. Those indexes are
26
+ * `TerrenoApp.start()` binds the HTTP port first, then awaits `ensureSyncIndexes()`. Those indexes are
27
27
  * requirements — the unique `mutationId` index is what makes duplicate mutation deliveries
28
28
  * idempotent, and the unique `stream` index is what keeps the counter upsert race from
29
29
  * minting duplicate seqs — so an index-build failure fails startup loudly. Apps that build
30
30
  * the Express app without `TerrenoApp.start()` should await `ensureSyncIndexes()` themselves.
31
+ * Pass `httpServer` when the process already bound `PORT` (Cloud Run startup probe).
31
32
  */
32
33
  export class SyncApp implements TerrenoPlugin {
33
34
  private readonly options: SyncAppOptions;
@@ -9,6 +9,7 @@ import {
9
9
  type SyncMutationScopeResolver,
10
10
  validateSyncMutationBatch,
11
11
  } from "./mutationHandler";
12
+ import type {SyncAppOptions} from "./routes";
12
13
  import type {SyncMutateBatchResponse, SyncMutateRequest, SyncNack} from "./types";
13
14
 
14
15
  /**
@@ -149,12 +150,14 @@ export const runSyncMutation = async ({
149
150
  mutation,
150
151
  req,
151
152
  scopeResolver,
153
+ syncOptions,
152
154
  user,
153
155
  }: {
154
156
  mutation: SyncMutateRequest;
155
157
  /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
156
158
  req?: express.Request;
157
159
  scopeResolver?: SyncMutationScopeResolver;
160
+ syncOptions?: SyncAppOptions;
158
161
  user: User;
159
162
  }): Promise<SyncMutationRunResult> => {
160
163
  const userId = String(user.id);
@@ -168,7 +171,7 @@ export const runSyncMutation = async ({
168
171
  };
169
172
  }
170
173
  return {
171
- outcome: await applySyncMutation({mutation, req, scopeResolver, user}),
174
+ outcome: await applySyncMutation({mutation, req, scopeResolver, syncOptions, user}),
172
175
  stage: "applied",
173
176
  };
174
177
  };
@@ -186,11 +189,13 @@ export const runSyncBatch = async ({
186
189
  mutations,
187
190
  req,
188
191
  scopeResolver,
192
+ syncOptions,
189
193
  user,
190
194
  }: {
191
195
  mutations: SyncMutateRequest[];
192
196
  req?: express.Request;
193
197
  scopeResolver?: SyncMutationScopeResolver;
198
+ syncOptions?: SyncAppOptions;
194
199
  user: User;
195
200
  }): Promise<SyncBatchRunResult> => {
196
201
  const validation = validateSyncMutationBatch(mutations);
@@ -214,7 +219,7 @@ export const runSyncBatch = async ({
214
219
  }
215
220
 
216
221
  return {
217
- response: await applySyncMutationBatch({mutations, req, scopeResolver, user}),
222
+ response: await applySyncMutationBatch({mutations, req, scopeResolver, syncOptions, user}),
218
223
  stage: "applied",
219
224
  };
220
225
  };