@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,328 @@
1
+ import type {Request} from "express";
2
+ import mongoose from "mongoose";
3
+
4
+ import {logger} from "../logger";
5
+ import {getOrgContext, ORGANIZATION_ID_HEADER} from "../orgs/orgContext";
6
+ import type {AuditEventModel, AuditEventOperation, AuditEventVerb} from "./auditEventModel";
7
+ import {changedFieldDiff, recordLabelFromDoc, toAuditPlain} from "./diff";
8
+
9
+ export interface ModelRouterAuditOptions {
10
+ redact?: string[];
11
+ }
12
+
13
+ export type ModelRouterAuditConfig = boolean | ModelRouterAuditOptions;
14
+
15
+ /** Off-process persist (Cloud Tasks). When set, Mongo is not written in this process. */
16
+ export type AuditEnqueue = (write: AuditEventWrite) => Promise<void>;
17
+
18
+ export interface AuditRecorderOptions {
19
+ enqueue?: AuditEnqueue;
20
+ }
21
+
22
+ export interface AuditEventWrite {
23
+ actorId?: string;
24
+ after?: Record<string, unknown>;
25
+ before?: Record<string, unknown>;
26
+ modelName: string;
27
+ operation: AuditEventOperation;
28
+ organizationId?: string;
29
+ recordId?: string;
30
+ recordLabel?: string;
31
+ source: "admin" | "modelRouter" | "rbac";
32
+ verb: AuditEventVerb;
33
+ }
34
+
35
+ const MISSING_PLUGIN_MESSAGE =
36
+ "modelRouter audit: true requires AuditApp to be registered; skipping AuditEvent write";
37
+
38
+ let auditEventModel: AuditEventModel | undefined;
39
+ let auditEnqueue: AuditEnqueue | undefined;
40
+ let missingPluginLogged = false;
41
+ const inflightWrites = new Set<Promise<void>>();
42
+
43
+ export const installAuditRecorder = (
44
+ model: AuditEventModel,
45
+ options: AuditRecorderOptions = {}
46
+ ): void => {
47
+ auditEventModel = model;
48
+ auditEnqueue = options.enqueue;
49
+ };
50
+
51
+ export const isAuditRecorderInstalled = (): boolean => Boolean(auditEventModel);
52
+
53
+ export const resetAuditRecorderForTests = (): void => {
54
+ auditEventModel = undefined;
55
+ auditEnqueue = undefined;
56
+ missingPluginLogged = false;
57
+ inflightWrites.clear();
58
+ };
59
+
60
+ export const flushAuditRecorderForTests = async (): Promise<void> => {
61
+ await Promise.all([...inflightWrites]);
62
+ };
63
+
64
+ const operationFromVerb = (verb: AuditEventVerb): AuditEventOperation => {
65
+ if (verb === "created") {
66
+ return "create";
67
+ }
68
+ if (verb === "deleted") {
69
+ return "delete";
70
+ }
71
+ return "update";
72
+ };
73
+
74
+ export const maybeRecordAdminAudit = async ({
75
+ after,
76
+ before,
77
+ extraRedact = [],
78
+ modelName,
79
+ recordLabel,
80
+ req,
81
+ verb,
82
+ }: {
83
+ after?: unknown;
84
+ before?: unknown;
85
+ extraRedact?: string[];
86
+ modelName: string;
87
+ recordLabel?: string;
88
+ req: Request;
89
+ verb: AuditEventVerb;
90
+ }): Promise<void> => {
91
+ try {
92
+ if (!auditEventModel) {
93
+ return;
94
+ }
95
+ if (modelName === "AuditEvent") {
96
+ return;
97
+ }
98
+ const beforePlain = toAuditPlain(before);
99
+ const afterPlain = toAuditPlain(after);
100
+ const diff = changedFieldDiff({after: afterPlain, before: beforePlain, extraRedact});
101
+ const recordIdValue = afterPlain?._id ?? beforePlain?._id;
102
+ await recordAuditEvent({
103
+ actorId: actorIdFromRequest(req),
104
+ after: diff.after,
105
+ before: diff.before,
106
+ modelName,
107
+ operation: operationFromVerb(verb),
108
+ organizationId: organizationIdFromAuditContext(req, afterPlain, beforePlain),
109
+ recordId: recordIdValue != null ? String(recordIdValue) : undefined,
110
+ recordLabel: recordLabel ?? recordLabelFromDoc(afterPlain) ?? recordLabelFromDoc(beforePlain),
111
+ source: "admin",
112
+ verb,
113
+ });
114
+ } catch (error: unknown) {
115
+ logger.error("Failed to persist AuditEvent", error);
116
+ }
117
+ };
118
+
119
+ const resolveAuditRedact = (audit?: ModelRouterAuditConfig): string[] | undefined => {
120
+ if (!audit) {
121
+ return undefined;
122
+ }
123
+ if (audit === true) {
124
+ return [];
125
+ }
126
+ return audit.redact ?? [];
127
+ };
128
+
129
+ const actorIdFromRequest = (req: Request): string | undefined => {
130
+ const user = req.user;
131
+ if (!user) {
132
+ return undefined;
133
+ }
134
+ if (user.id) {
135
+ return String(user.id);
136
+ }
137
+ if (user._id) {
138
+ return String(user._id);
139
+ }
140
+ return undefined;
141
+ };
142
+
143
+ const idString = (value: unknown): string | undefined => {
144
+ if (value === null || value === undefined) {
145
+ return undefined;
146
+ }
147
+ if (typeof value === "string") {
148
+ return value.length > 0 ? value : undefined;
149
+ }
150
+ if (typeof value === "object" && ("id" in value || "_id" in value)) {
151
+ const record = value as {_id?: unknown; id?: unknown};
152
+ if (record.id !== undefined && record.id !== null) {
153
+ return String(record.id);
154
+ }
155
+ if (record._id !== undefined && record._id !== null) {
156
+ return String(record._id);
157
+ }
158
+ }
159
+ return String(value);
160
+ };
161
+
162
+ const organizationIdFromAuditContext = (
163
+ req: Request,
164
+ after?: Record<string, unknown>,
165
+ before?: Record<string, unknown>
166
+ ): string | undefined => {
167
+ const organization = (req as Request & {organization?: unknown}).organization;
168
+ const fromRequest = idString(organization);
169
+ if (fromRequest) {
170
+ return fromRequest;
171
+ }
172
+ const fromAls = idString(getOrgContext()?.organization);
173
+ if (fromAls) {
174
+ return fromAls;
175
+ }
176
+ const fromHeader =
177
+ typeof req.header === "function" ? req.header(ORGANIZATION_ID_HEADER)?.trim() : undefined;
178
+ if (fromHeader) {
179
+ return fromHeader;
180
+ }
181
+ const fromDoc = after?.organizationId ?? before?.organizationId;
182
+ return idString(fromDoc);
183
+ };
184
+
185
+ /** 24-hex ObjectIds only. mongoose.isValidObjectId also accepts 12-char strings. */
186
+ const isCanonicalObjectId = (id: string): boolean => {
187
+ try {
188
+ return new mongoose.Types.ObjectId(id).toString() === id;
189
+ } catch {
190
+ return false;
191
+ }
192
+ };
193
+
194
+ export const actorIdForAuditWrite = (actorId?: string): string | undefined => {
195
+ if (!actorId) {
196
+ return undefined;
197
+ }
198
+ if (!isCanonicalObjectId(actorId)) {
199
+ logger.warn(`AuditEvent actorId is not an ObjectId, recording without an actor: ${actorId}`);
200
+ return undefined;
201
+ }
202
+ return actorId;
203
+ };
204
+
205
+ const actorObjectId = (actorId?: string): mongoose.Types.ObjectId | undefined => {
206
+ const validId = actorIdForAuditWrite(actorId);
207
+ if (!validId) {
208
+ return undefined;
209
+ }
210
+ return new mongoose.Types.ObjectId(validId);
211
+ };
212
+
213
+ /** Capture pre-mutation state only when audit is on. A throwing toJSON must not fail the write. */
214
+ export const snapshotAuditBefore = ({
215
+ audit,
216
+ doc,
217
+ }: {
218
+ audit?: ModelRouterAuditConfig;
219
+ doc: {toJSON?: () => unknown};
220
+ }): unknown => {
221
+ if (!audit) {
222
+ return undefined;
223
+ }
224
+ try {
225
+ if (typeof doc.toJSON === "function") {
226
+ return doc.toJSON();
227
+ }
228
+ return doc;
229
+ } catch (error: unknown) {
230
+ logger.error("Failed to snapshot document for AuditEvent", error);
231
+ return undefined;
232
+ }
233
+ };
234
+
235
+ const persistAuditEvent = async (write: AuditEventWrite): Promise<void> => {
236
+ if (write.modelName === "AuditEvent") {
237
+ return;
238
+ }
239
+ if (!auditEventModel) {
240
+ if (!missingPluginLogged) {
241
+ missingPluginLogged = true;
242
+ logger.error(MISSING_PLUGIN_MESSAGE);
243
+ }
244
+ return;
245
+ }
246
+ const actorId = actorObjectId(write.actorId);
247
+ await auditEventModel.create({
248
+ ...(actorId ? {actorId} : {}),
249
+ ...(write.after ? {after: write.after} : {}),
250
+ ...(write.before ? {before: write.before} : {}),
251
+ modelName: write.modelName,
252
+ operation: write.operation,
253
+ ...(write.organizationId ? {organizationId: write.organizationId} : {}),
254
+ ...(write.recordId ? {recordId: write.recordId} : {}),
255
+ ...(write.recordLabel ? {recordLabel: write.recordLabel} : {}),
256
+ source: write.source,
257
+ verb: write.verb,
258
+ });
259
+ };
260
+
261
+ const runAuditWrite = async (write: AuditEventWrite): Promise<void> => {
262
+ try {
263
+ if (auditEnqueue) {
264
+ await auditEnqueue(write);
265
+ return;
266
+ }
267
+ await persistAuditEvent(write);
268
+ } catch (error: unknown) {
269
+ logger.error("Failed to persist AuditEvent", error);
270
+ }
271
+ };
272
+
273
+ export const persistEnqueuedAuditEvent = async (write: AuditEventWrite): Promise<void> => {
274
+ await persistAuditEvent(write);
275
+ };
276
+
277
+ export const recordAuditEvent = (write: AuditEventWrite): Promise<void> => {
278
+ const run = runAuditWrite(write);
279
+ inflightWrites.add(run);
280
+ void run.finally(() => {
281
+ inflightWrites.delete(run);
282
+ });
283
+ return run;
284
+ };
285
+
286
+ export const maybeRecordModelRouterAudit = async ({
287
+ after,
288
+ audit,
289
+ before,
290
+ modelName,
291
+ operation,
292
+ recordId,
293
+ req,
294
+ verb,
295
+ }: {
296
+ after?: unknown;
297
+ audit?: ModelRouterAuditConfig;
298
+ before?: unknown;
299
+ modelName: string;
300
+ operation: AuditEventOperation;
301
+ recordId?: string;
302
+ req: Request;
303
+ verb: AuditEventVerb;
304
+ }): Promise<void> => {
305
+ try {
306
+ const extraRedact = resolveAuditRedact(audit);
307
+ if (extraRedact === undefined) {
308
+ return;
309
+ }
310
+ const beforePlain = toAuditPlain(before);
311
+ const afterPlain = toAuditPlain(after);
312
+ const diff = changedFieldDiff({after: afterPlain, before: beforePlain, extraRedact});
313
+ await recordAuditEvent({
314
+ actorId: actorIdFromRequest(req),
315
+ after: diff.after,
316
+ before: diff.before,
317
+ modelName,
318
+ operation,
319
+ organizationId: organizationIdFromAuditContext(req, afterPlain, beforePlain),
320
+ recordId,
321
+ recordLabel: recordLabelFromDoc(afterPlain) ?? recordLabelFromDoc(beforePlain),
322
+ source: "modelRouter",
323
+ verb,
324
+ });
325
+ } catch (error: unknown) {
326
+ logger.error("Failed to persist AuditEvent", error);
327
+ }
328
+ };
package/src/auth.test.ts CHANGED
@@ -1103,7 +1103,7 @@ describe("privileged user fields", () => {
1103
1103
  );
1104
1104
 
1105
1105
  expect((user as unknown as {admin?: boolean}).admin).toBe(false);
1106
- expect((user as unknown as {roles?: string[]}).roles).toBeUndefined();
1106
+ expect((user as unknown as {roles?: string[]}).roles ?? []).toEqual([]);
1107
1107
  });
1108
1108
 
1109
1109
  it("does not let PATCH /auth/me escalate to admin or join organizations", async () => {
package/src/betterAuth.ts CHANGED
@@ -90,6 +90,13 @@ export interface BetterAuthConfig {
90
90
  authMailTemplates?: Partial<
91
91
  Record<"resetPassword" | "verifyEmail", {html?: string; subject: string; text?: string}>
92
92
  >;
93
+
94
+ /**
95
+ * Disable Better Auth's built-in IP limiter. Use only on throwaway in-process
96
+ * seed apps — production `BetterAuthApp` instances keep the default (on in
97
+ * `NODE_ENV=production`).
98
+ */
99
+ disableRateLimit?: boolean;
93
100
  }
94
101
 
95
102
  /**
@@ -146,6 +146,33 @@ describe("createBetterAuth", () => {
146
146
  expect(auth.api).toBeDefined();
147
147
  });
148
148
 
149
+ it("does not 429 a burst of email sign-ups when disableRateLimit is set", async () => {
150
+ await setup;
151
+ const config: BetterAuthConfig = {
152
+ baseURL: "http://localhost:3000",
153
+ disableRateLimit: true,
154
+ enabled: true,
155
+ secret: "test-secret-at-least-32-characters-long",
156
+ };
157
+ const auth = createBetterAuth({config, mongoClient: getClient()});
158
+
159
+ for (let index = 0; index < 6; index += 1) {
160
+ const response = await auth.handler(
161
+ new globalThis.Request("https://localhost:3000/api/auth/sign-up/email", {
162
+ body: JSON.stringify({
163
+ email: `seed-burst-${index}@example.com`,
164
+ name: `Seed Burst ${index}`,
165
+ password: "testpassword123",
166
+ }),
167
+ headers: {"Content-Type": "application/json"},
168
+ method: "POST",
169
+ })
170
+ );
171
+ assert.notEqual(response.status, 429, `sign-up ${index} was rate-limited`);
172
+ assert.isTrue(response.ok, `sign-up ${index} failed: ${response.status}`);
173
+ }
174
+ });
175
+
149
176
  it("sets cross-site session cookies when crossDomainCookies is enabled", async () => {
150
177
  await setup;
151
178
  const origin = "https://frontend.example.com";
@@ -228,6 +228,7 @@ export const createBetterAuth = (options: CreateBetterAuthOptions): BetterAuthIn
228
228
  // token as a bearer header) — without it, a raw session token cannot be validated and
229
229
  // socket auth silently fails (the sync client shows perpetually "offline").
230
230
  plugins: [bearer()],
231
+ rateLimit: config.disableRateLimit ? {enabled: false} : undefined,
231
232
  secret,
232
233
  session: {
233
234
  cookieCache: {
@@ -135,7 +135,7 @@ describe("CollectionRegistry", () => {
135
135
  expect(getSyncRegistry()[0]?.options).toBe(updatedOptions);
136
136
  });
137
137
 
138
- it("rejects re-registering sync at the same route path", () => {
138
+ it("treats re-registering the same model at the same route path as a no-op", () => {
139
139
  clearSyncRegistry();
140
140
  registerSync({
141
141
  config: {scope: {type: "owner"}},
@@ -143,14 +143,13 @@ describe("CollectionRegistry", () => {
143
143
  options: syncOptions,
144
144
  routePath: "/catalogTodos",
145
145
  });
146
- expect(() =>
147
- registerSync({
148
- config: {scope: {type: "owner"}},
149
- model: CatalogTodoModel,
150
- options: syncOptions,
151
- routePath: "/catalogTodos",
152
- })
153
- ).toThrow(/already registered/);
146
+ registerSync({
147
+ config: {scope: {type: "owner"}},
148
+ model: CatalogTodoModel,
149
+ options: syncOptions,
150
+ routePath: "/catalogTodos",
151
+ });
152
+ expect(getSyncRegistry()).toHaveLength(1);
154
153
  });
155
154
 
156
155
  it("clearCollectionRegistry resets deferred sync index tasks", async () => {
@@ -19,8 +19,22 @@ import {
19
19
  applySyncRegistrationSideEffects,
20
20
  clearSyncIndexCreationTasks,
21
21
  } from "./sync/registrationSideEffects";
22
+ import type {SyncConfig} from "./sync/types";
22
23
 
23
- export interface CollectionSurfaces {
24
+ const withAdminBroadcastDefault = (config: SyncConfig): SyncConfig => ({
25
+ ...config,
26
+ adminBroadcast: config.adminBroadcast === true,
27
+ });
28
+
29
+ /** Store `adminBroadcast: false` when the host omitted the flag (default). */
30
+ const applyAdminBroadcastDefault = (options: ModelRouterOptions<unknown>): void => {
31
+ if (!options.sync) {
32
+ return;
33
+ }
34
+ options.sync = withAdminBroadcastDefault(options.sync);
35
+ };
36
+
37
+ interface CollectionSurfaces {
24
38
  mcp: boolean;
25
39
  realtime: boolean;
26
40
  sync: boolean;
@@ -55,10 +69,14 @@ export const registerCollection = <T>({
55
69
  options: ModelRouterOptions<T>;
56
70
  routePath: string;
57
71
  }): void => {
72
+ applyAdminBroadcastDefault(options as ModelRouterOptions<unknown>);
58
73
  const existing = collectionRegistry.get(routePath);
59
74
  const wasSyncEnabled = existing?.surfaces.sync ?? false;
60
75
 
61
76
  if (options.sync && wasSyncEnabled) {
77
+ if (existing?.model.modelName === model.modelName) {
78
+ return;
79
+ }
62
80
  const collectionTag = routePath.replace(/^\//, "");
63
81
  throw new APIError({
64
82
  status: 500,
@@ -100,9 +118,11 @@ export const replaceCollectionOptions = (
100
118
  if (!existing) {
101
119
  return;
102
120
  }
121
+ applyAdminBroadcastDefault(options);
103
122
  existing.options = options;
104
123
  };
105
124
 
125
+ /** @internal */
106
126
  export const getCollection = (routePath: string): CollectionRecord | undefined =>
107
127
  collectionRegistry.get(routePath);
108
128
 
package/src/express.d.ts CHANGED
@@ -19,5 +19,7 @@ declare namespace Express {
19
19
  email?: string;
20
20
  [key: string]: unknown;
21
21
  };
22
+ organization?: unknown;
23
+ membership?: unknown;
22
24
  }
23
25
  }
@@ -904,8 +904,8 @@ describe("expressServer", () => {
904
904
  skipListen: false,
905
905
  userModel: typedUserModel,
906
906
  }).start();
907
- // start() defers listen behind an awaited ensureSyncIndexes(), so the
908
- // exit-on-listen-error path settles asynchronously.
907
+ // start() binds listen first, then awaits ensureSyncIndexes(), so the
908
+ // exit-on-listen-error path still settles asynchronously if listen throws.
909
909
  const deadline = Date.now() + 2_000;
910
910
  while (exit.mock.calls.length === 0 && Date.now() < deadline) {
911
911
  await new Promise((resolve) => setTimeout(resolve, 5));
@@ -972,6 +972,54 @@ describe("expressServer", () => {
972
972
  expect(app).toBeDefined();
973
973
  await new Promise((resolve) => setTimeout(resolve, 100));
974
974
  });
975
+
976
+ it("attaches the Express app to an already-listening httpServer", async () => {
977
+ const http = await import("node:http");
978
+ const holder = http.createServer((_req, res) => {
979
+ res.writeHead(503);
980
+ res.end("starting");
981
+ });
982
+ await new Promise<void>((resolve) => {
983
+ holder.listen(0, "127.0.0.1", () => {
984
+ resolve();
985
+ });
986
+ });
987
+ const address = holder.address();
988
+ const port = typeof address === "object" && address ? address.port : 0;
989
+ try {
990
+ new TerrenoApp({
991
+ configureApp: (app) => {
992
+ app.get("/ping", (_req, res) => {
993
+ res.json({ok: true});
994
+ });
995
+ },
996
+ httpServer: holder,
997
+ skipListen: false,
998
+ userModel: typedUserModel,
999
+ }).start();
1000
+ const deadline = Date.now() + 2_000;
1001
+ let status = 0;
1002
+ while (Date.now() < deadline) {
1003
+ const response = await fetch(`http://127.0.0.1:${port}/ping`);
1004
+ status = response.status;
1005
+ if (status === 200) {
1006
+ break;
1007
+ }
1008
+ await new Promise((resolve) => setTimeout(resolve, 20));
1009
+ }
1010
+ expect(status).toBe(200);
1011
+ } finally {
1012
+ await new Promise<void>((resolve, reject) => {
1013
+ holder.close((error) => {
1014
+ if (error) {
1015
+ reject(error);
1016
+ return;
1017
+ }
1018
+ resolve();
1019
+ });
1020
+ });
1021
+ }
1022
+ });
975
1023
  });
976
1024
 
977
1025
  describe("wrapScript timeout callbacks", () => {
package/src/index.ts CHANGED
@@ -1,6 +1,35 @@
1
1
  export * from "./actions";
2
2
  export * from "./adminTypes";
3
3
  export * from "./api";
4
+ export {AuditApp, type AuditAppOptions} from "./audit/auditApp";
5
+ export {
6
+ type AuditEventDocument,
7
+ type AuditEventModel,
8
+ type AuditEventOperation,
9
+ type AuditEventSource,
10
+ type AuditEventVerb,
11
+ createAuditEventModel,
12
+ } from "./audit/auditEventModel";
13
+ export {
14
+ AUDIT_SECRET_HEADER,
15
+ auditEnqueueFromEnv,
16
+ type CloudTasksAuditEnqueueOptions,
17
+ createCloudTasksAuditEnqueue,
18
+ } from "./audit/cloudTasksEnqueue";
19
+ export {persistRbacAuditToAuditEvent} from "./audit/rbacSink";
20
+ export {
21
+ type AuditEnqueue,
22
+ type AuditEventWrite,
23
+ type AuditRecorderOptions,
24
+ flushAuditRecorderForTests,
25
+ isAuditRecorderInstalled,
26
+ type ModelRouterAuditConfig,
27
+ type ModelRouterAuditOptions,
28
+ maybeRecordAdminAudit,
29
+ persistEnqueuedAuditEvent,
30
+ recordAuditEvent,
31
+ resetAuditRecorderForTests,
32
+ } from "./audit/record";
4
33
  export * from "./auth";
5
34
  export * from "./authRecovery";
6
35
  export * from "./authTokens";
@@ -50,10 +79,36 @@ export type {
50
79
  MCPToolResult,
51
80
  } from "./mcp/types";
52
81
  export * from "./middleware";
82
+ export * from "./migrations/generate";
83
+ export * from "./migrations/load";
84
+ export * from "./migrations/lock";
85
+ export * from "./migrations/runner";
86
+ export * from "./migrations/schemaCatalog";
87
+ export * from "./migrations/types";
53
88
  export * from "./models/consentForm";
54
89
  export * from "./models/consentResponse";
55
90
  export * from "./models/mcpServiceToken";
91
+ export * from "./models/notification";
92
+ export * from "./models/notificationPreference";
56
93
  export * from "./models/versionConfig";
94
+ export {
95
+ configureNotificationService,
96
+ createNotificationService,
97
+ getNotificationService,
98
+ type NotificationService,
99
+ type NotificationServiceOptions,
100
+ type NotificationsCommsService,
101
+ } from "./notifications/notificationService";
102
+ export {
103
+ NotificationsApp,
104
+ type NotificationsAppOptions,
105
+ } from "./notifications/notificationsApp";
106
+ export {
107
+ type NotificationsBeforeSendChannel,
108
+ type NotificationsBeforeSendContext,
109
+ type NotificationsBeforeSendResult,
110
+ notificationsBeforeSend,
111
+ } from "./notifications/notificationsBeforeSend";
57
112
  export * from "./notifiers/googleChatNotifier";
58
113
  export * from "./notifiers/slackNotifier";
59
114
  export * from "./notifiers/zoomNotifier";
@@ -61,6 +116,12 @@ export * from "./openApiBuilder";
61
116
  export * from "./openApiCompat";
62
117
  export * from "./openApiEtag";
63
118
  export * from "./openApiValidator";
119
+ export * from "./orgs/organizationModel";
120
+ export * from "./orgs/organizationSettings";
121
+ export * from "./orgs/orgContext";
122
+ export * from "./orgs/orgPermissions";
123
+ export * from "./orgs/orgPlugin";
124
+ export * from "./orgs/orgsApp";
64
125
  export * from "./permissions";
65
126
  export * from "./plugins";
66
127
  export * from "./populate";
@@ -88,11 +149,17 @@ export {
88
149
  backfillAdmins,
89
150
  } from "./rbac/backfillAdmins";
90
151
  export * from "./rbac/fieldViews";
152
+ export {
153
+ MEMBERSHIP_ORG_ADMIN_PERMISSION_SOURCE_NAME,
154
+ membershipOrgAdminPermissionSource,
155
+ ORG_ADMIN_PERMISSION_BUNDLE,
156
+ } from "./rbac/membershipOrgAdminSource";
91
157
  export * from "./rbac/middleware";
92
158
  export * from "./rbac/permissionUtils";
93
159
  export {
94
160
  createRbacRoleModel,
95
161
  expandRolePermissions,
162
+ organizationOperatorRole,
96
163
  type RbacRoleDocument,
97
164
  type RbacRoleModel,
98
165
  READ_ONLY_ROLE_PERMISSIONS,
@@ -192,6 +259,8 @@ export * from "./scriptRunner";
192
259
  export {adminBodyFieldsToStrip, scrubAdminFields, stripAdminBodyFields} from "./scrubAdminFields";
193
260
  export * from "./secretProviders";
194
261
  export * from "./seedRunner";
262
+ export * from "./sync/adminBroadcastScope";
263
+ export * from "./sync/adminWindowMutation";
195
264
  export * from "./sync/executors";
196
265
  export * from "./sync/models";
197
266
  export * from "./sync/mutationHandler";