@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
@@ -0,0 +1,283 @@
1
+ import type express from "express";
2
+ import mongoose from "mongoose";
3
+
4
+ import type {ModelRouterOptions} from "../api";
5
+ import type {User} from "../auth";
6
+ import {APIError} from "../errors";
7
+ import {checkPermissions, type PermissionMethod} from "../permissions";
8
+ import {findOneOrNoneFor} from "../plugins";
9
+ import type {AnyTerrenoAccess} from "../rbac/types";
10
+ import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
11
+ import type {SyncRegistryEntry} from "./registry";
12
+ import type {SyncAppOptions} from "./routes";
13
+ import type {SyncMutateRequest, SyncMutationOperation} from "./types";
14
+
15
+ export interface AdminWindowMutationAuditEvent {
16
+ actorId?: string;
17
+ /** Serialized document after the successful mutation. */
18
+ doc?: Record<string, unknown>;
19
+ modelName: string;
20
+ recordId?: string;
21
+ recordLabel?: string;
22
+ verb: "created" | "deleted" | "updated";
23
+ }
24
+
25
+ export interface AdminWindowMutationScopeHooks {
26
+ preCreate?: ModelRouterOptions<unknown>["preCreate"];
27
+ preUpdate?: ModelRouterOptions<unknown>["preUpdate"];
28
+ preDelete?: ModelRouterOptions<unknown>["preDelete"];
29
+ postCreate?: ModelRouterOptions<unknown>["postCreate"];
30
+ postUpdate?: ModelRouterOptions<unknown>["postUpdate"];
31
+ postDelete?: ModelRouterOptions<unknown>["postDelete"];
32
+ }
33
+
34
+ export interface AdminWindowMutationScope extends AdminWindowMutationScopeHooks {
35
+ /** RBAC access used by AdminApp User admin-flag and role assignment hooks. */
36
+ accessControl?: AnyTerrenoAccess;
37
+ modelName: string;
38
+ permissions: {create: boolean; update: boolean; delete: boolean};
39
+ createPermissions: PermissionMethod<unknown>[];
40
+ updatePermissions: PermissionMethod<unknown>[];
41
+ deletePermissions: PermissionMethod<unknown>[];
42
+ stripMutationData: (data: Record<string, unknown>) => Record<string, unknown>;
43
+ /** Legacy standalone audit callback; prefer `postCreate` / `postUpdate` / `postDelete`. */
44
+ emitAudit?: (args: {
45
+ event: AdminWindowMutationAuditEvent;
46
+ req: express.Request;
47
+ }) => void | Promise<void>;
48
+ }
49
+
50
+ /** Coalesce `req.user.id` and `req.user._id` to match Admin REST audit actor ids. */
51
+ export const auditActorIdFromRequest = (req: express.Request): string | undefined => {
52
+ const actor = req.user as {id?: unknown; _id?: unknown} | undefined;
53
+ if (!actor) {
54
+ return undefined;
55
+ }
56
+ if (actor.id != null) {
57
+ return String(actor.id);
58
+ }
59
+ if (actor._id != null) {
60
+ return String(actor._id);
61
+ }
62
+ return undefined;
63
+ };
64
+
65
+ /**
66
+ * Admin-window sync mutations use AdminApp router pre/post hooks, not product `modelRouter`
67
+ * hooks. Product hooks can overwrite stripped or admin-authorized fields (for example by
68
+ * forcing `ownerId` in `preCreate`).
69
+ */
70
+ export const buildAdminWindowExecutorOptions = <T>({
71
+ productOptions,
72
+ scope,
73
+ }: {
74
+ productOptions: ModelRouterOptions<T>;
75
+ scope: AdminWindowMutationScope;
76
+ }): ModelRouterOptions<T> => ({
77
+ ...productOptions,
78
+ accessControl: scope.accessControl ?? productOptions.accessControl,
79
+ postCreate: scope.postCreate as ModelRouterOptions<T>["postCreate"],
80
+ postDelete: scope.postDelete as ModelRouterOptions<T>["postDelete"],
81
+ postUpdate: scope.postUpdate as ModelRouterOptions<T>["postUpdate"],
82
+ preCreate: scope.preCreate as ModelRouterOptions<T>["preCreate"],
83
+ preDelete: scope.preDelete as ModelRouterOptions<T>["preDelete"],
84
+ preUpdate: scope.preUpdate as ModelRouterOptions<T>["preUpdate"],
85
+ });
86
+
87
+ /** Ensure `req.params.id` is set for AdminApp update/delete hooks (User admin-flag gates). */
88
+ export const withAdminWindowMutationRequestContext = ({
89
+ mutation,
90
+ req,
91
+ }: {
92
+ mutation: SyncMutateRequest;
93
+ req: express.Request;
94
+ }): express.Request => {
95
+ if (mutation.operation === "create" || mutation.id == null) {
96
+ return req;
97
+ }
98
+ const params = {...(req.params ?? {}), id: mutation.id};
99
+ return Object.assign(req, {params}) as express.Request;
100
+ };
101
+
102
+ const adminWindowMutationScopes = new Map<string, AdminWindowMutationScope>();
103
+
104
+ export const registerAdminWindowMutationScope = (
105
+ modelName: string,
106
+ scope: AdminWindowMutationScope
107
+ ): void => {
108
+ adminWindowMutationScopes.set(modelName, scope);
109
+ };
110
+
111
+ export const getAdminWindowMutationScope = (
112
+ modelName: string
113
+ ): AdminWindowMutationScope | undefined => adminWindowMutationScopes.get(modelName);
114
+
115
+ export const clearAdminWindowMutationScopes = (): void => {
116
+ adminWindowMutationScopes.clear();
117
+ };
118
+
119
+ const operationEnabled = (
120
+ scope: AdminWindowMutationScope,
121
+ operation: SyncMutationOperation
122
+ ): boolean => {
123
+ if (operation === "create") {
124
+ return scope.permissions.create;
125
+ }
126
+ if (operation === "update") {
127
+ return scope.permissions.update;
128
+ }
129
+ return scope.permissions.delete;
130
+ };
131
+
132
+ const permissionsForOperation = (
133
+ scope: AdminWindowMutationScope,
134
+ operation: SyncMutationOperation
135
+ ): PermissionMethod<unknown>[] => {
136
+ if (operation === "create") {
137
+ return scope.createPermissions;
138
+ }
139
+ if (operation === "update") {
140
+ return scope.updatePermissions;
141
+ }
142
+ return scope.deletePermissions;
143
+ };
144
+
145
+ const loadInstance = async ({
146
+ entry,
147
+ id,
148
+ }: {
149
+ entry: SyncRegistryEntry;
150
+ id: string;
151
+ }): Promise<unknown> => {
152
+ const model = mongoose.model(entry.modelName);
153
+ return findOneOrNoneFor(model, {_id: id, deleted: {$in: [true, false]}});
154
+ };
155
+
156
+ /**
157
+ * Validates an explicit `mutationMode: "adminWindow"` marker and applies AdminApp write
158
+ * semantics before the product sync executor runs. Returns the mutation with stripped
159
+ * data, or `undefined` when the request stays on the product path.
160
+ *
161
+ * The marker alone is never trusted: callers must also have admin-window access, the
162
+ * collection must be `adminBroadcast`, and AdminApp must have registered a write scope.
163
+ */
164
+ export const prepareAdminWindowMutation = async ({
165
+ entry,
166
+ mutation,
167
+ req: _req,
168
+ syncOptions,
169
+ user,
170
+ }: {
171
+ entry: SyncRegistryEntry;
172
+ mutation: SyncMutateRequest;
173
+ req: express.Request;
174
+ syncOptions?: SyncAppOptions;
175
+ user: User;
176
+ }): Promise<{mutation: SyncMutateRequest; scope: AdminWindowMutationScope} | undefined> => {
177
+ if (mutation.mutationMode !== "adminWindow") {
178
+ return undefined;
179
+ }
180
+ if (!entry.config.adminBroadcast) {
181
+ throw new APIError({
182
+ status: 403,
183
+ title: "Admin window mutations require an adminBroadcast collection",
184
+ });
185
+ }
186
+ if (
187
+ !(await canUseAdminBroadcastWindow({
188
+ accessControl: syncOptions?.accessControl,
189
+ canOpenAdminWindow: syncOptions?.canOpenAdminWindow,
190
+ user,
191
+ }))
192
+ ) {
193
+ throw new APIError({status: 403, title: "Admin window access required"});
194
+ }
195
+ const scope = getAdminWindowMutationScope(entry.modelName);
196
+ if (!scope) {
197
+ throw new APIError({
198
+ status: 403,
199
+ title: "Admin window mutations are not registered for this collection",
200
+ });
201
+ }
202
+ if (!operationEnabled(scope, mutation.operation)) {
203
+ throw new APIError({
204
+ status: 403,
205
+ title: `${mutation.operation} is disabled for this admin model`,
206
+ });
207
+ }
208
+
209
+ let instance: unknown;
210
+ if (mutation.operation !== "create") {
211
+ if (!mutation.id) {
212
+ throw new APIError({
213
+ status: 400,
214
+ title: `id is required for ${mutation.operation} mutations`,
215
+ });
216
+ }
217
+ instance = await loadInstance({entry, id: mutation.id});
218
+ if (!instance && mutation.operation === "update") {
219
+ throw new APIError({status: 404, title: "Not found"});
220
+ }
221
+ }
222
+
223
+ const permissionMethod =
224
+ mutation.operation === "create"
225
+ ? "create"
226
+ : mutation.operation === "update"
227
+ ? "update"
228
+ : "delete";
229
+ const permissionInstance =
230
+ mutation.operation === "create" ? (mutation.data as unknown) : instance;
231
+ if (
232
+ !(await checkPermissions(
233
+ permissionMethod,
234
+ permissionsForOperation(scope, mutation.operation),
235
+ user,
236
+ permissionInstance
237
+ ))
238
+ ) {
239
+ throw new APIError({status: 403, title: "Admin write access denied"});
240
+ }
241
+
242
+ if (mutation.operation === "delete" || !mutation.data) {
243
+ return {mutation, scope};
244
+ }
245
+ return {
246
+ mutation: {...mutation, data: scope.stripMutationData(mutation.data)},
247
+ scope,
248
+ };
249
+ };
250
+
251
+ export const emitAdminWindowMutationAudit = async ({
252
+ doc,
253
+ mutation,
254
+ req,
255
+ scope,
256
+ }: {
257
+ doc: mongoose.Document;
258
+ mutation: SyncMutateRequest;
259
+ req: express.Request;
260
+ scope: AdminWindowMutationScope;
261
+ }): Promise<void> => {
262
+ if (!scope.emitAudit) {
263
+ return;
264
+ }
265
+ const plain = doc.toObject() as Record<string, unknown>;
266
+ const recordId = plain._id != null ? String(plain._id) : mutation.id;
267
+ const verb =
268
+ mutation.operation === "create"
269
+ ? "created"
270
+ : mutation.operation === "delete"
271
+ ? "deleted"
272
+ : "updated";
273
+ await scope.emitAudit({
274
+ event: {
275
+ actorId: auditActorIdFromRequest(req),
276
+ doc: plain,
277
+ modelName: scope.modelName,
278
+ recordId,
279
+ verb,
280
+ },
281
+ req,
282
+ });
283
+ };
@@ -184,6 +184,7 @@ export const executeCreate = async <T>({
184
184
  user,
185
185
  body,
186
186
  req,
187
+ skipPermissionChecks,
187
188
  skipPostHooks,
188
189
  writeModelName,
189
190
  }: {
@@ -205,10 +206,15 @@ export const executeCreate = async <T>({
205
206
  * committed write look like a failure. REST handlers never set this.
206
207
  */
207
208
  skipPostHooks?: boolean;
209
+ /** When true, skip modelRouter permission checks (admin-window sync mutations). */
210
+ skipPermissionChecks?: boolean;
208
211
  }): Promise<ExecutorResult<T>> => {
209
212
  const request = req ?? stubRequest(user);
210
213
 
211
- if (!(await checkPermissions("create", options.permissions.create, user))) {
214
+ if (
215
+ !skipPermissionChecks &&
216
+ !(await checkPermissions("create", options.permissions.create, user))
217
+ ) {
212
218
  throw new APIError({
213
219
  status: 405,
214
220
  title: `Access to CREATE on ${model.modelName} denied for ${user?.id}`,
@@ -348,6 +354,7 @@ export const executeUpdate = async <T>({
348
354
  concurrencyCheck,
349
355
  existingDoc,
350
356
  req,
357
+ skipPermissionChecks,
351
358
  skipPostHooks,
352
359
  writeModelName,
353
360
  }: {
@@ -371,10 +378,15 @@ export const executeUpdate = async <T>({
371
378
  * MCP passes the registry `modelName` because compiled mongoose names can differ.
372
379
  */
373
380
  writeModelName?: string;
381
+ /** When true, skip modelRouter permission checks (admin-window sync mutations). */
382
+ skipPermissionChecks?: boolean;
374
383
  }): Promise<ExecutorResult<T>> => {
375
384
  const request = req ?? stubRequest(user);
376
385
 
377
- if (!(await checkPermissions("update", options.permissions.update, user))) {
386
+ if (
387
+ !skipPermissionChecks &&
388
+ !(await checkPermissions("update", options.permissions.update, user))
389
+ ) {
378
390
  throw new APIError({
379
391
  status: 405,
380
392
  title: `Access to UPDATE on ${model.modelName} denied for ${user?.id}`,
@@ -384,7 +396,10 @@ export const executeUpdate = async <T>({
384
396
  let doc =
385
397
  existingDoc ?? ((await loadDocOr404<T>(model, id, options.populatePaths)) as ExecutorDoc<T>);
386
398
 
387
- if (!(await checkPermissions("update", options.permissions.update, user, doc))) {
399
+ if (
400
+ !skipPermissionChecks &&
401
+ !(await checkPermissions("update", options.permissions.update, user, doc))
402
+ ) {
388
403
  throw new APIError({
389
404
  status: 403,
390
405
  title: `Access to GET on ${model.modelName}:${id} denied for ${user?.id}`,
@@ -603,6 +618,7 @@ export const executeDelete = async <T>({
603
618
  id,
604
619
  existingDoc,
605
620
  req,
621
+ skipPermissionChecks,
606
622
  skipPostHooks,
607
623
  }: {
608
624
  model: Model<T>;
@@ -618,10 +634,15 @@ export const executeDelete = async <T>({
618
634
  req?: express.Request;
619
635
  /** C5 (FIX 6): see `executeCreate`'s `skipPostHooks` doc comment. */
620
636
  skipPostHooks?: boolean;
637
+ /** When true, skip modelRouter permission checks (admin-window sync mutations). */
638
+ skipPermissionChecks?: boolean;
621
639
  }): Promise<ExecutorResult<T>> => {
622
640
  const request = req ?? stubRequest(user);
623
641
 
624
- if (!(await checkPermissions("delete", options.permissions.delete, user))) {
642
+ if (
643
+ !skipPermissionChecks &&
644
+ !(await checkPermissions("delete", options.permissions.delete, user))
645
+ ) {
625
646
  throw new APIError({
626
647
  status: 405,
627
648
  title: `Access to DELETE on ${model.modelName} denied for ${user?.id}`,
@@ -649,7 +670,10 @@ export const executeDelete = async <T>({
649
670
  if (!resolved) {
650
671
  throw error;
651
672
  }
652
- if (!(await checkPermissions("delete", options.permissions.delete, user, resolved))) {
673
+ if (
674
+ !skipPermissionChecks &&
675
+ !(await checkPermissions("delete", options.permissions.delete, user, resolved))
676
+ ) {
653
677
  throw new APIError({
654
678
  status: 403,
655
679
  title: `Access to GET on ${model.modelName}:${id} denied for ${user?.id}`,
@@ -661,7 +685,10 @@ export const executeDelete = async <T>({
661
685
  }
662
686
  }
663
687
 
664
- if (!(await checkPermissions("delete", options.permissions.delete, user, doc))) {
688
+ if (
689
+ !skipPermissionChecks &&
690
+ !(await checkPermissions("delete", options.permissions.delete, user, doc))
691
+ ) {
665
692
  throw new APIError({
666
693
  status: 403,
667
694
  title: `Access to GET on ${model.modelName}:${id} denied for ${user?.id}`,
@@ -1,4 +1,5 @@
1
- import {beforeAll, beforeEach, describe, expect, it} from "bun:test";
1
+ import {afterEach, beforeAll, beforeEach, describe, expect, it, spyOn} from "bun:test";
2
+ import {assert} from "chai";
2
3
  import mongoose, {model, Schema} from "mongoose";
3
4
  import type {ModelRouterOptions} from "../api";
4
5
  import type {User} from "../auth";
@@ -6,10 +7,17 @@ import {APIError} from "../errors";
6
7
  import {Permissions} from "../permissions";
7
8
  import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
8
9
  import {setupDb} from "../tests";
10
+ import {
11
+ type AdminWindowMutationAuditEvent,
12
+ type AdminWindowMutationScope,
13
+ clearAdminWindowMutationScopes,
14
+ registerAdminWindowMutationScope,
15
+ } from "./adminWindowMutation";
9
16
  import {computeStableFrontier, SyncCounter, SyncMutation} from "./models";
10
17
  import {
11
18
  applySyncMutation,
12
19
  applySyncMutationBatch,
20
+ docMatchesMutationData,
13
21
  MAX_SYNC_MUTATIONS_PER_BATCH,
14
22
  type SyncMutationOutcome,
15
23
  validateSyncMutationBatch,
@@ -365,6 +373,32 @@ describe("applySyncMutation", () => {
365
373
  expect(row?.resultId).toBe(entityId);
366
374
  });
367
375
 
376
+ it("create: surfaces the E11000 as a nack when the colliding _id is not readable (soft-deleted)", async () => {
377
+ const entityId = new mongoose.Types.ObjectId().toHexString();
378
+ await MutStuffModel.create({
379
+ _id: entityId,
380
+ deleted: true,
381
+ name: "tombstone",
382
+ ownerId: owner.id,
383
+ });
384
+ await createStalePendingRow("m-lease-create-tombstone", 90_000);
385
+
386
+ const nack = expectNack(
387
+ await applySyncMutation({
388
+ mutation: {
389
+ collection: "mutStuff",
390
+ data: {name: "tombstone", ownerId: owner.id},
391
+ id: entityId,
392
+ mutationId: "m-lease-create-tombstone",
393
+ operation: "create",
394
+ },
395
+ user: owner,
396
+ })
397
+ );
398
+ assert.notEqual(nack.code, "conflict");
399
+ assert.equal(await MutStuffModel.countDocuments({_id: entityId, deleted: true}), 1);
400
+ });
401
+
368
402
  it("update: tolerates the write having already landed (seq already advanced by exactly this mutation) and reads back the doc as the ack", async () => {
369
403
  const doc = await MutStuffModel.create({name: "v1", ownerId: owner.id});
370
404
  // Simulate the crash: the update write from the FIRST attempt landed
@@ -813,6 +847,25 @@ describe("applySyncMutation", () => {
813
847
  expect(nack.message).toContain("Unknown sync collection");
814
848
  });
815
849
 
850
+ it("nacks validation when an update omits baseVersion", async () => {
851
+ const doc = await MutStuffModel.create({name: "no base", ownerId: owner.id});
852
+ const nack = expectNack(
853
+ await applySyncMutation({
854
+ mutation: {
855
+ collection: "mutStuff",
856
+ data: {name: "changed"},
857
+ id: String(doc._id),
858
+ mutationId: "m-no-base-version",
859
+ operation: "update",
860
+ },
861
+ user: owner,
862
+ })
863
+ );
864
+ assert.equal(nack.code, "validation");
865
+ assert.include(nack.message, "baseVersion is required");
866
+ assert.equal(await SyncMutation.countDocuments({mutationId: "m-no-base-version"}), 0);
867
+ });
868
+
816
869
  it("nacks validation when update or delete is missing an id", async () => {
817
870
  for (const operation of ["update", "delete"] as const) {
818
871
  const nack = expectNack(
@@ -1000,6 +1053,229 @@ describe("applySyncMutation", () => {
1000
1053
  // Task 9.18: error-class outcomes release the claim rather than recording it.
1001
1054
  expect(await SyncMutation.countDocuments({mutationId: "m-plain-error"})).toBe(0);
1002
1055
  });
1056
+
1057
+ it("rethrows a non-duplicate failure from the ledger claim insert", async () => {
1058
+ const createSpy = spyOn(SyncMutation, "create").mockImplementation((() => {
1059
+ throw new Error("ledger unavailable");
1060
+ }) as never);
1061
+ try {
1062
+ let thrown: unknown;
1063
+ try {
1064
+ await applySyncMutation({
1065
+ mutation: {
1066
+ collection: "mutStuff",
1067
+ data: {name: "never claimed", ownerId: owner.id},
1068
+ mutationId: "m-claim-crash",
1069
+ operation: "create",
1070
+ },
1071
+ user: owner,
1072
+ });
1073
+ } catch (error: unknown) {
1074
+ thrown = error;
1075
+ }
1076
+ assert.instanceOf(thrown, Error);
1077
+ assert.equal((thrown as Error).message, "ledger unavailable");
1078
+ } finally {
1079
+ createSpy.mockRestore();
1080
+ }
1081
+ assert.equal(await MutStuffModel.countDocuments({name: "never claimed"}), 0);
1082
+ });
1083
+ });
1084
+
1085
+ describe("write scope enforcement", () => {
1086
+ it("skips the write-scope check for broadcast collections", async () => {
1087
+ registerMutStuff({config: {scope: {type: "broadcast"}}});
1088
+ const ack = expectAck(
1089
+ await applySyncMutation({
1090
+ mutation: {
1091
+ collection: "mutStuff",
1092
+ data: {name: "broadcast", ownerId: stranger.id},
1093
+ mutationId: "m-broadcast-create",
1094
+ operation: "create",
1095
+ },
1096
+ user: owner,
1097
+ })
1098
+ );
1099
+ assert.equal(ack.seq, 1);
1100
+ const saved = await MutStuffModel.findById(ack.id);
1101
+ assert.equal(saved?.ownerId, stranger.id);
1102
+ });
1103
+
1104
+ it("nacks error when a tenant-scoped collection has no scope resolver", async () => {
1105
+ registerMutStuff({config: {scope: {field: "ownerId", type: "tenant"}}});
1106
+ const nack = expectNack(
1107
+ await applySyncMutation({
1108
+ mutation: {
1109
+ collection: "mutStuff",
1110
+ data: {name: "tenant", ownerId: "tenant-1"},
1111
+ mutationId: "m-tenant-no-resolver",
1112
+ operation: "create",
1113
+ },
1114
+ user: owner,
1115
+ })
1116
+ );
1117
+ assert.equal(nack.code, "error");
1118
+ assert.include(nack.message, "no getUserScopes resolver");
1119
+ assert.equal(await MutStuffModel.countDocuments({name: "tenant"}), 0);
1120
+ });
1121
+
1122
+ it("acks a tenant-scoped create when the resolver confirms the membership", async () => {
1123
+ registerMutStuff({config: {scope: {field: "ownerId", type: "tenant"}}});
1124
+ const ack = expectAck(
1125
+ await applySyncMutation({
1126
+ mutation: {
1127
+ collection: "mutStuff",
1128
+ data: {name: "tenant ok", ownerId: "tenant-1"},
1129
+ mutationId: "m-tenant-member",
1130
+ operation: "create",
1131
+ },
1132
+ scopeResolver: async () => ["tenant-1", "tenant-2"],
1133
+ user: owner,
1134
+ })
1135
+ );
1136
+ assert.equal(ack.seq, 1);
1137
+ });
1138
+ });
1139
+
1140
+ describe("recorded conflict replay", () => {
1141
+ const recordConflict = async (
1142
+ mutationId: string,
1143
+ resultId: string | undefined
1144
+ ): Promise<void> => {
1145
+ await SyncMutation.create({
1146
+ claimedAt: new Date(),
1147
+ error: "recorded conflict",
1148
+ mutationId,
1149
+ resultId,
1150
+ resultSeq: 3,
1151
+ status: "conflicted",
1152
+ userId: String(owner.id),
1153
+ });
1154
+ };
1155
+
1156
+ const replay = (mutationId: string): Promise<SyncMutationOutcome> =>
1157
+ applySyncMutation({
1158
+ mutation: {
1159
+ baseVersion: 1,
1160
+ collection: "mutStuff",
1161
+ data: {name: "replayed"},
1162
+ id: new mongoose.Types.ObjectId().toHexString(),
1163
+ mutationId,
1164
+ operation: "update",
1165
+ },
1166
+ user: owner,
1167
+ });
1168
+
1169
+ it("omits the server doc when the recorded conflict has no resultId", async () => {
1170
+ await recordConflict("m-conflict-no-id", undefined);
1171
+ const nack = expectNack(await replay("m-conflict-no-id"));
1172
+ assert.equal(nack.code, "conflict");
1173
+ assert.equal(nack.message, "recorded conflict");
1174
+ assert.equal(nack.serverSeq, 3);
1175
+ assert.isUndefined(nack.serverDoc);
1176
+ });
1177
+
1178
+ it("omits the server doc when the recorded resultId no longer resolves to a document", async () => {
1179
+ await recordConflict("m-conflict-missing", new mongoose.Types.ObjectId().toHexString());
1180
+ const nack = expectNack(await replay("m-conflict-missing"));
1181
+ assert.equal(nack.code, "conflict");
1182
+ assert.isUndefined(nack.serverDoc);
1183
+ });
1184
+
1185
+ it("omits the server doc when loading it throws", async () => {
1186
+ await recordConflict("m-conflict-bad-id", "not-an-object-id");
1187
+ const nack = expectNack(await replay("m-conflict-bad-id"));
1188
+ assert.equal(nack.code, "conflict");
1189
+ assert.isUndefined(nack.serverDoc);
1190
+ });
1191
+ });
1192
+
1193
+ describe("admin window mutations", () => {
1194
+ const admin = {_id: "mut-admin", admin: true, id: "mut-admin"} as unknown as User;
1195
+
1196
+ const registerAdminScope = (
1197
+ emitAudit?: AdminWindowMutationScope["emitAudit"]
1198
+ ): AdminWindowMutationScope => {
1199
+ const scope: AdminWindowMutationScope = {
1200
+ createPermissions: [Permissions.IsAdmin],
1201
+ deletePermissions: [Permissions.IsAdmin],
1202
+ emitAudit,
1203
+ modelName: MutStuffModel.modelName,
1204
+ permissions: {create: true, delete: true, update: true},
1205
+ stripMutationData: (data) => {
1206
+ const next = {...data};
1207
+ delete next.secret;
1208
+ return next;
1209
+ },
1210
+ updatePermissions: [Permissions.IsAdmin],
1211
+ };
1212
+ registerAdminWindowMutationScope(MutStuffModel.modelName, scope);
1213
+ return scope;
1214
+ };
1215
+
1216
+ beforeEach(() => {
1217
+ clearAdminWindowMutationScopes();
1218
+ registerMutStuff({config: {adminBroadcast: true, scope: {type: "owner"}}});
1219
+ });
1220
+
1221
+ afterEach(() => {
1222
+ clearAdminWindowMutationScopes();
1223
+ });
1224
+
1225
+ it("applies an admin window create with stripped data and emits the audit event", async () => {
1226
+ const events: AdminWindowMutationAuditEvent[] = [];
1227
+ registerAdminScope(({event}) => {
1228
+ events.push(event);
1229
+ });
1230
+ const ack = expectAck(
1231
+ await applySyncMutation({
1232
+ mutation: {
1233
+ collection: "mutStuff",
1234
+ data: {name: "admin created", ownerId: owner.id, secret: "strip me"},
1235
+ mutationId: "m-admin-create",
1236
+ mutationMode: "adminWindow",
1237
+ operation: "create",
1238
+ },
1239
+ user: admin,
1240
+ })
1241
+ );
1242
+ assert.equal(ack.seq, 1);
1243
+ assert.isUndefined(ack.warning);
1244
+ const saved = await MutStuffModel.findById(ack.id);
1245
+ assert.equal(saved?.name, "admin created");
1246
+ assert.equal(saved?.ownerId, owner.id);
1247
+ assert.lengthOf(events, 1);
1248
+ assert.equal(events[0].verb, "created");
1249
+ assert.equal(events[0].recordId, ack.id);
1250
+ });
1251
+
1252
+ it("still acks when the admin window audit hook throws after the write committed", async () => {
1253
+ registerAdminScope(() => {
1254
+ throw new Error("audit sink down");
1255
+ });
1256
+ const ack = expectAck(
1257
+ await applySyncMutation({
1258
+ mutation: {
1259
+ collection: "mutStuff",
1260
+ data: {name: "audited anyway", ownerId: owner.id},
1261
+ mutationId: "m-admin-audit-throw",
1262
+ mutationMode: "adminWindow",
1263
+ operation: "create",
1264
+ },
1265
+ user: admin,
1266
+ })
1267
+ );
1268
+ assert.isUndefined(ack.warning);
1269
+ assert.equal(await MutStuffModel.countDocuments({name: "audited anyway"}), 1);
1270
+ const row = await SyncMutation.findOne({mutationId: "m-admin-audit-throw"});
1271
+ assert.equal(row?.status, "applied");
1272
+ });
1273
+ });
1274
+ });
1275
+
1276
+ describe("docMatchesMutationData", () => {
1277
+ it("treats an absent mutation payload as matching any document", () => {
1278
+ assert.isTrue(docMatchesMutationData({name: "anything"}, undefined));
1003
1279
  });
1004
1280
  });
1005
1281