@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
@@ -6,6 +6,7 @@ import type {ModelRouterOptions, RESTMethod} from "./api";
6
6
  import type {User} from "./auth";
7
7
  import {loadDocOr404} from "./docLoader";
8
8
  import {APIError} from "./errors";
9
+ import {isOrgMemberPermission, OrgQueryFilter} from "./orgs/orgPermissions";
9
10
 
10
11
  export type PermissionMethod<T> = (
11
12
  method: RESTMethod,
@@ -43,16 +44,10 @@ export const getUserOrganizationIds = (user?: User): string[] => {
43
44
  };
44
45
 
45
46
  /**
46
- * Restricts list queries to documents belonging to one of the caller's organizations. This is the
47
- * tenant-scoped analog of {@link OwnerQueryFilter}: it filters on the document's `organizationId`
48
- * field using the user's `organizationIds`. Returns `null` for anonymous callers (no user).
47
+ * Restricts list queries to the current request organization (`X-Organization-Id` or inferred
48
+ * single org-admin membership). Does not read `User.organizationIds`.
49
49
  */
50
- export const OrganizationQueryFilter = (user?: User) => {
51
- if (!user) {
52
- return null;
53
- }
54
- return {organizationId: {$in: getUserOrganizationIds(user)}};
55
- };
50
+ export const OrganizationQueryFilter = OrgQueryFilter;
56
51
 
57
52
  export const Permissions = {
58
53
  IsAdmin: (_method: RESTMethod, user?: User) => {
@@ -74,28 +69,11 @@ export const Permissions = {
74
69
  return method === "list" || method === "read";
75
70
  },
76
71
  /**
77
- * Object-level permission for tenant-scoped documents: the caller must belong to the document's
78
- * organization (admins always pass). With no object (list/create checks) it returns true and
79
- * defers to the {@link OrganizationQueryFilter} / a `preCreate` hook to scope access. Expects the
80
- * document to expose an `organizationId` and the user an `organizationIds` array.
72
+ * Object-level permission for tenant-scoped documents: platform org actors must match the
73
+ * current org context; everyone else needs an active Membership. With no object (list/create)
74
+ * it returns true and defers to {@link OrganizationQueryFilter}.
81
75
  */
82
- IsOrganizationMember: (_method: RESTMethod, user?: User, obj?: unknown) => {
83
- // When checking if we can possibly perform the action, return true.
84
- if (!obj) {
85
- return true;
86
- }
87
- if (!user) {
88
- return false;
89
- }
90
- if (user?.admin) {
91
- return true;
92
- }
93
- const organizationId = (obj as {organizationId?: string}).organizationId;
94
- if (!organizationId) {
95
- return false;
96
- }
97
- return getUserOrganizationIds(user).includes(organizationId);
98
- },
76
+ IsOrganizationMember: isOrgMemberPermission,
99
77
  IsOwner: (_method: RESTMethod, user?: User, obj?: unknown) => {
100
78
  // When checking if we can possibly perform the action, return true.
101
79
  if (!obj) {
@@ -10,7 +10,7 @@ const secondsUntil = (resetAt: number, now: number): number => {
10
10
  return Math.max(1, Math.ceil((resetAt - now) / 1000));
11
11
  };
12
12
 
13
- export const setRateLimitExceededHeaders = ({
13
+ const setRateLimitExceededHeaders = ({
14
14
  max,
15
15
  remaining,
16
16
  resetAt,
@@ -4,6 +4,7 @@ import mongoose from "mongoose";
4
4
  import {APIError} from "../errors";
5
5
  import type {RateLimitConsumeArgs, RateLimitConsumeResult, RateLimitStore} from "./types";
6
6
 
7
+ /** @internal */
7
8
  export const RATE_LIMIT_HITS_COLLECTION = "rateLimitHits";
8
9
 
9
10
  const ensureIndexes = async (collection: mongoose.mongo.Collection): Promise<void> => {
@@ -12,7 +12,7 @@ const stripQueryAndFragment = (url: string): string => {
12
12
  };
13
13
 
14
14
  /** Strip query, fragment, and a trailing slash so `/auth/login/` matches `/auth/login`. */
15
- export const normalizeRequestPath = (url: string): string => {
15
+ const normalizeRequestPath = (url: string): string => {
16
16
  const withoutQuery = stripQueryAndFragment(url);
17
17
  const withoutSlash =
18
18
  withoutQuery.length > 1 && withoutQuery.endsWith("/")
@@ -22,7 +22,7 @@ export const normalizeRequestPath = (url: string): string => {
22
22
  };
23
23
 
24
24
  /** Prefer Express `req.path` (routing) over the raw request-target. */
25
- export const requestPath = (req: Request): string => {
25
+ const requestPath = (req: Request): string => {
26
26
  const raw = req.path || req.url || req.originalUrl || "";
27
27
  return normalizeRequestPath(raw);
28
28
  };
@@ -7,6 +7,7 @@ import type {
7
7
  RateLimitStore,
8
8
  } from "./types";
9
9
 
10
+ /** @internal */
10
11
  export const redisUrlFromEnv = (): string | undefined => {
11
12
  return process.env.VALKEY_URL || process.env.REDIS_URL;
12
13
  };
@@ -1,10 +1,11 @@
1
1
  import type {User} from "../auth";
2
2
  import {APIError} from "../errors";
3
3
  import {normalizeRbacAuditSinks} from "./auditModel";
4
+ import {membershipOrgAdminPermissionSource} from "./membershipOrgAdminSource";
4
5
  import {createIsPermitted, createRequireAccess} from "./middleware";
5
6
  import {createPermissionResolver} from "./resolve";
6
7
  import {createRoleManager} from "./roleManager";
7
- import {createRbacRoleModel} from "./roleModel";
8
+ import {createRbacRoleModel, organizationOperatorRole} from "./roleModel";
8
9
  import {mergeStatements, type Statements} from "./statements";
9
10
  import type {
10
11
  AccessCheckArgs,
@@ -39,19 +40,26 @@ export const createAccess = <S extends Statements>(options: AccessOptions<S>): T
39
40
 
40
41
  const mergedStatements = mergeStatements(options.statements) as S;
41
42
  const rbacRoleModel = createRbacRoleModel(options.connection);
43
+ const extraRoles = [...(options.defaultRoles ?? [])];
44
+ if (options.organizations && !extraRoles.some((role) => role.name === "operator")) {
45
+ extraRoles.push(organizationOperatorRole);
46
+ }
47
+ const sources = options.organizations
48
+ ? [membershipOrgAdminPermissionSource(), ...(options.sources ?? [])]
49
+ : (options.sources ?? []);
42
50
 
43
51
  const resolver = createPermissionResolver({
44
52
  cacheTtlMs: options.cacheTtlMs,
45
53
  rbacRoleModel,
46
54
  resolvePermissions: options.resolvePermissions,
47
- sources: options.sources,
55
+ sources,
48
56
  statements: mergedStatements,
49
57
  });
50
58
 
51
59
  const {roleManager} = createRoleManager({
52
60
  auditSinks,
53
61
  connection: options.connection,
54
- defaultRoles: options.defaultRoles,
62
+ defaultRoles: extraRoles,
55
63
  getActorPermissions: (user) => resolver.resolvePermissionsForUser(user),
56
64
  getPreviewPermissions: (user) => resolver.resolvePermissionsForUserUncached(user),
57
65
  invalidateCache: resolver.invalidateCache,
@@ -0,0 +1,59 @@
1
+ import type {User} from "../auth";
2
+ import {Membership} from "../orgs/organizationModel";
3
+ import {getOrgContext} from "../orgs/orgContext";
4
+ import type {PermissionSet} from "./statements";
5
+ import type {PermissionSource, PermissionSourceGrants} from "./types";
6
+
7
+ export const MEMBERSHIP_ORG_ADMIN_PERMISSION_SOURCE_NAME = "membership-org-admin";
8
+
9
+ /** Grants applied when `Membership.roleName` is `org-admin` in the current org context. */
10
+ export const ORG_ADMIN_PERMISSION_BUNDLE: PermissionSet = {
11
+ admin: ["access"],
12
+ organization: ["read", "update", "manageMembers"],
13
+ };
14
+
15
+ const userIdForMembershipLookup = (user: User): string => {
16
+ if (user._id) {
17
+ return String(user._id);
18
+ }
19
+ return user.id;
20
+ };
21
+
22
+ const isActiveOrgAdminMembership = (membership?: {roleName?: string; status?: string}): boolean => {
23
+ return membership?.roleName === "org-admin" && membership.status === "active";
24
+ };
25
+
26
+ const fullOrgAdminGrants = (): PermissionSourceGrants => ({
27
+ permissions: {
28
+ admin: [...ORG_ADMIN_PERMISSION_BUNDLE.admin],
29
+ organization: [...ORG_ADMIN_PERMISSION_BUNDLE.organization],
30
+ },
31
+ });
32
+
33
+ const shellOnlyOrgAdminGrants = (): PermissionSourceGrants => ({
34
+ permissions: {
35
+ admin: [...ORG_ADMIN_PERMISSION_BUNDLE.admin],
36
+ },
37
+ });
38
+
39
+ export const membershipOrgAdminPermissionSource = (): PermissionSource => ({
40
+ getGrants: async ({user}): Promise<PermissionSourceGrants | null> => {
41
+ const contextMembership = getOrgContext()?.membership;
42
+ if (contextMembership) {
43
+ if (!isActiveOrgAdminMembership(contextMembership)) {
44
+ return null;
45
+ }
46
+ return fullOrgAdminGrants();
47
+ }
48
+
49
+ const activeMemberships = await Membership.findActiveForUser(userIdForMembershipLookup(user));
50
+ const hasOrgAdminMembership = activeMemberships.some((row) => row.roleName === "org-admin");
51
+ if (!hasOrgAdminMembership) {
52
+ return null;
53
+ }
54
+
55
+ return shellOnlyOrgAdminGrants();
56
+ },
57
+ name: MEMBERSHIP_ORG_ADMIN_PERMISSION_SOURCE_NAME,
58
+ ttlMs: 0,
59
+ });
@@ -62,6 +62,7 @@ const buildPermissionRequest = (resource: string, action: string): Record<string
62
62
  [resource]: [action],
63
63
  });
64
64
 
65
+ /** @internal */
65
66
  export const buildAccessPermissions = <T>(
66
67
  accessControl: AnyTerrenoAccess,
67
68
  access: ModelRouterAccessOptions
@@ -115,6 +116,7 @@ export const buildAccessPermissions = <T>(
115
116
  };
116
117
  };
117
118
 
119
+ /** @internal */
118
120
  export const buildAccessQueryFilter = <_T>(
119
121
  accessControl: AnyTerrenoAccess,
120
122
  access: ModelRouterAccessOptions,
@@ -161,6 +163,7 @@ export const buildAccessQueryFilter = <_T>(
161
163
  };
162
164
  };
163
165
 
166
+ /** @internal */
164
167
  export const wrapAccessResponseHandler = <T>(
165
168
  accessControl: AnyTerrenoAccess,
166
169
  access: ModelRouterAccessOptions,
@@ -101,12 +101,33 @@ describe("rbac permission utils and middleware", () => {
101
101
  const first = await access.getPermissions({user});
102
102
  expect(first.todo).toEqual(["read"]);
103
103
 
104
- user.roles = [];
105
- const cached = await access.getPermissions({user});
106
- expect(cached.todo).toEqual(["read"]);
107
-
108
104
  access.invalidateCache({userId: user.id});
109
105
  const refreshed = await access.getPermissions({user});
110
- expect(refreshed.todo).toBeUndefined();
106
+ expect(refreshed.todo).toEqual(["read"]);
107
+ });
108
+
109
+ it("does not reuse cached permissions after the user's roles change", async () => {
110
+ await setupDb();
111
+ const access = createAccess({
112
+ cacheTtlMs: 60_000,
113
+ connection: mongoose.connection,
114
+ defaultRoles: [
115
+ {
116
+ displayName: "Reader",
117
+ name: "reader",
118
+ permissions: {todo: ["read"]},
119
+ },
120
+ ],
121
+ statements: appStatements,
122
+ });
123
+ await access.roles.seedDefaults();
124
+
125
+ const user = createUser({roles: ["reader"]});
126
+ const first = await access.getPermissions({user});
127
+ expect(first.todo).toEqual(["read"]);
128
+
129
+ user.roles = [];
130
+ const afterRoleChange = await access.getPermissions({user});
131
+ expect(afterRoleChange.todo).toBeUndefined();
111
132
  });
112
133
  });
@@ -53,13 +53,45 @@ describe("createPermissionResolver", () => {
53
53
  const first = await resolver.resolvePermissionsForUser(user);
54
54
  expect(first.todo).toEqual(["read"]);
55
55
 
56
- user.roles = [];
56
+ await RbacRole.findOneAndUpdate({name: "reader"}, {$set: {permissions: {todo: ["create"]}}});
57
57
  const cached = await resolver.resolvePermissionsForUser(user);
58
58
  expect(cached.todo).toEqual(["read"]);
59
59
 
60
60
  resolver.invalidateCache({userId: user.id});
61
61
  const refreshed = await resolver.resolvePermissionsForUser(user);
62
- expect(refreshed.todo).toBeUndefined();
62
+ expect(refreshed.todo).toEqual(["create"]);
63
+ });
64
+
65
+ it("does not reuse cached permissions after the user's roles change", async () => {
66
+ await setupDb();
67
+ const RbacRole = createRbacRoleModel(mongoose.connection);
68
+ await RbacRole.seedDefaults({statements: appStatements});
69
+ await RbacRole.findOneAndUpdate(
70
+ {name: "reader"},
71
+ {
72
+ $set: {
73
+ displayName: "Reader",
74
+ name: "reader",
75
+ permissions: {todo: ["read"]},
76
+ },
77
+ },
78
+ {upsert: true}
79
+ );
80
+
81
+ const resolver = createPermissionResolver({
82
+ cacheTtlMs: 60_000,
83
+ rbacRoleModel: RbacRole,
84
+ statements: appStatements,
85
+ });
86
+
87
+ const user = createTestUser({roles: ["reader"]});
88
+ const first = await resolver.resolvePermissionsForUser(user);
89
+ expect(first.todo).toEqual(["read"]);
90
+ expect(first.admin).toBeUndefined();
91
+
92
+ user.roles = ["superadmin"];
93
+ const promoted = await resolver.resolvePermissionsForUser(user);
94
+ expect(promoted.admin).toEqual(expect.arrayContaining(["access"]));
63
95
  });
64
96
 
65
97
  it("clears all cached permissions when invalidateCache is called without userId", async () => {
@@ -3,6 +3,7 @@ import {DateTime} from "luxon";
3
3
 
4
4
  import type {User} from "../auth";
5
5
  import {logger} from "../logger";
6
+ import {getOrgContext} from "../orgs/orgContext";
6
7
  import {unionPermissionSets} from "./permissionUtils";
7
8
  import type {RbacRoleModel} from "./roleModel";
8
9
  import type {PermissionSet, Statements} from "./statements";
@@ -26,6 +27,23 @@ const getUserRoles = (user: User): string[] => {
26
27
  return withRoles.roles ?? [];
27
28
  };
28
29
 
30
+ /** Include org context and roles so tenant switches and Mongo promotions are not stuck behind TTL. */
31
+ const permissionCacheKey = (user: User): string => {
32
+ const ctx = getOrgContext();
33
+ const organizationId = ctx?.organization?._id?.toString() ?? "";
34
+ const membershipRole = ctx?.membership?.roleName ?? "";
35
+ const roles = [...getUserRoles(user)].sort().join(",");
36
+ return `${user.id}::org=${organizationId}::role=${membershipRole}::roles=${roles}`;
37
+ };
38
+
39
+ const deletePermissionCacheForUser = (cache: Map<string, CacheEntry>, userId: string): void => {
40
+ for (const key of [...cache.keys()]) {
41
+ if (key === userId || key.startsWith(`${userId}:`) || key.startsWith(`${userId}::`)) {
42
+ cache.delete(key);
43
+ }
44
+ }
45
+ };
46
+
29
47
  export const createPermissionResolver = <S extends Statements>(args: {
30
48
  statements: S;
31
49
  rbacRoleModel: RbacRoleModel;
@@ -71,15 +89,15 @@ export const createPermissionResolver = <S extends Statements>(args: {
71
89
  }
72
90
  };
73
91
 
74
- const rememberPermissions = (userId: string, entry: CacheEntry): void => {
75
- permissionCache.delete(userId);
76
- permissionCache.set(userId, entry);
92
+ const rememberPermissions = (cacheKey: string, entry: CacheEntry): void => {
93
+ permissionCache.delete(cacheKey);
94
+ permissionCache.set(cacheKey, entry);
77
95
  enforceCacheBound();
78
96
  };
79
97
 
80
98
  const invalidateCache = (invalidateArgs?: {userId?: string}): void => {
81
99
  if (invalidateArgs?.userId) {
82
- permissionCache.delete(invalidateArgs.userId);
100
+ deletePermissionCacheForUser(permissionCache, invalidateArgs.userId);
83
101
  sourceCache.delete(invalidateArgs.userId);
84
102
  return;
85
103
  }
@@ -205,10 +223,11 @@ export const createPermissionResolver = <S extends Statements>(args: {
205
223
  user: User,
206
224
  shouldCache: boolean
207
225
  ): Promise<PermissionSet> => {
226
+ const cacheKey = permissionCacheKey(user);
208
227
  if (shouldCache) {
209
- const cached = permissionCache.get(user.id);
228
+ const cached = permissionCache.get(cacheKey);
210
229
  if (cached && cached.expiresAt > DateTime.now().toMillis()) {
211
- rememberPermissions(user.id, cached);
230
+ rememberPermissions(cacheKey, cached);
212
231
  return cached.permissions;
213
232
  }
214
233
  }
@@ -251,7 +270,7 @@ export const createPermissionResolver = <S extends Statements>(args: {
251
270
  }
252
271
 
253
272
  if (shouldCache) {
254
- rememberPermissions(user.id, {
273
+ rememberPermissions(cacheKey, {
255
274
  expiresAt: DateTime.now().plus({milliseconds: cacheTtlMs}).toMillis(),
256
275
  permissions,
257
276
  });
@@ -1,9 +1,15 @@
1
1
  import {describe, expect, it} from "bun:test";
2
+ import {assert} from "chai";
2
3
  import mongoose from "mongoose";
3
4
 
4
5
  import {setupDb} from "../tests";
5
6
  import {createRbacAuditModel} from "./auditModel";
6
- import {createRbacRoleModel, expandRolePermissions, terrenoDefaultRoles} from "./roleModel";
7
+ import {
8
+ createRbacRoleModel,
9
+ expandRolePermissions,
10
+ organizationOperatorRole,
11
+ terrenoDefaultRoles,
12
+ } from "./roleModel";
7
13
  import {READ_ONLY_ROLE_PERMISSIONS, terrenoStatements} from "./statements";
8
14
 
9
15
  describe("rbac role model", () => {
@@ -11,6 +17,15 @@ describe("rbac role model", () => {
11
17
  const names = terrenoDefaultRoles.map((role) => role.name);
12
18
 
13
19
  expect(names).toEqual(["superadmin", "admin", "auditor", "member"]);
20
+
21
+ const admin = terrenoDefaultRoles.find((role) => role.name === "admin");
22
+ assert.isObject(admin?.permissions);
23
+ if (!admin?.permissions || admin.permissions === "*" || "readOnly" in admin.permissions) {
24
+ assert.fail("Expected concrete admin permissions");
25
+ }
26
+ assert.deepEqual(admin.permissions.adminAnnouncementAcknowledgement, ["read"]);
27
+ assert.deepEqual(admin.permissions.adminAnnouncementClickEvent, ["read"]);
28
+ assert.deepEqual(admin.permissions.adminAnnouncementImpression, ["read"]);
14
29
  });
15
30
 
16
31
  it("seeds default roles with expanded permissions", async () => {
@@ -25,12 +40,30 @@ describe("rbac role model", () => {
25
40
  expect(superadmin.permissions.featureFlag).toContain("list");
26
41
  expect(superadmin.permissions.consentForm).toContain("list");
27
42
  expect(superadmin.permissions.consentResponse).toEqual(["list", "read"]);
43
+ expect(superadmin.permissions.organization).toContain("list");
44
+
45
+ expect(await RbacRole.findOne({name: "operator"})).toBeNull();
28
46
 
29
47
  const auditor = await RbacRole.findExactlyOne({name: "auditor"});
30
48
  expect(auditor.permissions.user).toEqual(["list", "read"]);
31
49
  expect(auditor.permissions.rbac).toEqual(["read"]);
32
50
  });
33
51
 
52
+ it("seeds the locked operator role when passed as an extra role", async () => {
53
+ await setupDb();
54
+ const RbacRole = createRbacRoleModel(mongoose.connection);
55
+ await RbacRole.seedDefaults({
56
+ extraRoles: [organizationOperatorRole],
57
+ statements: terrenoStatements,
58
+ });
59
+
60
+ const operator = await RbacRole.findExactlyOne({name: "operator"});
61
+ expect(operator.isLocked).toBe(true);
62
+ expect(operator.permissions.organization).toEqual([...terrenoStatements.organization]);
63
+ expect(operator.permissions.admin).toEqual(["access"]);
64
+ expect(operator.permissions.user).toEqual(["list", "read", "update"]);
65
+ });
66
+
34
67
  it("upserts default roles without duplicating", async () => {
35
68
  await setupDb();
36
69
  const RbacRole = createRbacRoleModel(mongoose.connection);
@@ -52,7 +52,7 @@ export {READ_ONLY_ROLE_PERMISSIONS} from "./statements";
52
52
  * Insert missing default roles. Existing unsealed roles are left unchanged so admin
53
53
  * customizations survive process restarts. Sealed roles are refreshed from code.
54
54
  */
55
- export const upsertSeededRole = async (
55
+ const upsertSeededRole = async (
56
56
  model: RbacRoleModel,
57
57
  role: RoleDefinition,
58
58
  statements: Statements
@@ -89,6 +89,18 @@ export const expandRolePermissions = (
89
89
  readActions: readonly string[] = READ_ACTIONS
90
90
  ): PermissionSet => expandRolePermissionSpec(spec, statements, readActions);
91
91
 
92
+ /** Locked platform role seeded only when `createAccess({organizations: true})`. */
93
+ export const organizationOperatorRole: RoleDefinition = {
94
+ displayName: "Operator",
95
+ isLocked: true,
96
+ name: "operator",
97
+ permissions: {
98
+ admin: ["access"],
99
+ organization: ["create", "list", "read", "update", "delete", "manageMembers", "disable"],
100
+ user: ["list", "read", "update"],
101
+ },
102
+ };
103
+
92
104
  export const terrenoDefaultRoles: RoleDefinition[] = [
93
105
  {
94
106
  displayName: "Super Admin",
@@ -103,6 +115,10 @@ export const terrenoDefaultRoles: RoleDefinition[] = [
103
115
  name: "admin",
104
116
  permissions: {
105
117
  admin: ["access"],
118
+ adminAnnouncement: ["read", "write", "writeOwned"],
119
+ adminAnnouncementAcknowledgement: ["read"],
120
+ adminAnnouncementClickEvent: ["read"],
121
+ adminAnnouncementImpression: ["read"],
106
122
  configuration: ["read", "update"],
107
123
  user: ["create", "list", "read", "update"],
108
124
  },
@@ -1,4 +1,5 @@
1
1
  import {describe, expect, it} from "bun:test";
2
+ import {assert} from "chai";
2
3
 
3
4
  import {
4
5
  ADMIN_PAGE_PERMISSION,
@@ -12,13 +13,27 @@ import {
12
13
  describe("rbac statements", () => {
13
14
  it("exports terreno default vocabulary", () => {
14
15
  expect(terrenoStatements.admin).toContain("access");
16
+ expect(terrenoStatements.admin).toContain("jobs");
15
17
  expect(ADMIN_PAGE_PERMISSION).toEqual({admin: ["access"]});
16
18
  expect(terrenoStatements.rbac).toContain("manageRoles");
17
19
  expect(terrenoStatements.user).toContain("read");
18
20
  expect(terrenoStatements.configuration).toContain("update");
19
21
  expect(terrenoStatements.featureFlag).toEqual(["create", "list", "read", "update", "delete"]);
22
+ expect(terrenoStatements.organization).toEqual([
23
+ "create",
24
+ "list",
25
+ "read",
26
+ "update",
27
+ "delete",
28
+ "manageMembers",
29
+ "disable",
30
+ ]);
20
31
  expect(terrenoStatements.consentForm).toEqual(["create", "list", "read", "update", "delete"]);
21
32
  expect(terrenoStatements.consentResponse).toEqual(["list", "read"]);
33
+ assert.deepEqual(
34
+ [...terrenoStatements.adminAnnouncementClickEvent],
35
+ ["read", "write", "writeOwned"]
36
+ );
22
37
  });
23
38
 
24
39
  it("merges app statements over terreno defaults", () => {
@@ -40,6 +55,9 @@ describe("rbac statements", () => {
40
55
  expect(expanded.featureFlag).toEqual([...terrenoStatements.featureFlag]);
41
56
  expect(expanded.consentForm).toEqual([...terrenoStatements.consentForm]);
42
57
  expect(expanded.consentResponse).toEqual([...terrenoStatements.consentResponse]);
58
+ assert.deepEqual(expanded.adminAnnouncementClickEvent, [
59
+ ...terrenoStatements.adminAnnouncementClickEvent,
60
+ ]);
43
61
  });
44
62
 
45
63
  it("expands read-only sentinel to read-ish actions", () => {
@@ -56,6 +74,7 @@ describe("rbac statements", () => {
56
74
  expect(expanded.featureFlag).toEqual(["list", "read"]);
57
75
  expect(expanded.consentForm).toEqual(["list", "read"]);
58
76
  expect(expanded.consentResponse).toEqual(["list", "read"]);
77
+ expect(expanded.organization).toEqual(["list", "read"]);
59
78
  });
60
79
 
61
80
  it("returns concrete permission sets unchanged", () => {
@@ -8,15 +8,33 @@ export const ADMIN_PAGE_PERMISSION = {
8
8
  [ADMIN_PAGE_RESOURCE]: [ADMIN_PAGE_ACTION],
9
9
  } as const;
10
10
 
11
+ export const ORGANIZATION_ACTIONS = [
12
+ "create",
13
+ "list",
14
+ "read",
15
+ "update",
16
+ "delete",
17
+ "manageMembers",
18
+ "disable",
19
+ ] as const;
20
+
11
21
  export const terrenoStatements = {
12
- admin: [ADMIN_PAGE_ACTION, "runScripts", "viewBackgroundTasks"],
22
+ admin: [ADMIN_PAGE_ACTION, "jobs", "runScripts", "viewBackgroundTasks"],
23
+ adminAnnouncement: ADMIN_MODEL_ACCESS,
24
+ adminAnnouncementAcknowledgement: ADMIN_MODEL_ACCESS,
25
+ adminAnnouncementClickEvent: ADMIN_MODEL_ACCESS,
26
+ adminAnnouncementImpression: ADMIN_MODEL_ACCESS,
13
27
  adminConsentForm: ADMIN_MODEL_ACCESS,
14
28
  adminConsentResponse: ADMIN_MODEL_ACCESS,
15
29
  adminFeatureFlag: ADMIN_MODEL_ACCESS,
30
+ announcement: MODEL_CRUD,
31
+ announcementAcknowledgement: ["list", "read"],
32
+ announcementImpression: ["list", "read"],
16
33
  configuration: ["read", "update"],
17
34
  consentForm: MODEL_CRUD,
18
35
  consentResponse: ["list", "read"],
19
36
  featureFlag: MODEL_CRUD,
37
+ organization: ORGANIZATION_ACTIONS,
20
38
  rbac: ["read", "manageRoles", "assignRoles"],
21
39
  user: ["create", "list", "read", "update", "delete", "impersonate", "setPassword"],
22
40
  } as const;
package/src/rbac/types.ts CHANGED
@@ -150,6 +150,11 @@ export type RbacAuditSink = (record: RbacAuditWrite) => void | Promise<void>;
150
150
  export interface AccessOptions<S extends Statements> {
151
151
  connection: Connection;
152
152
  statements: S;
153
+ /**
154
+ * Opt in to organization RBAC: membership `org-admin` grants and the locked `operator` seed.
155
+ * Default `false` so existing single-tenant apps stay unchanged. New apps from bootstrap pass `true`.
156
+ */
157
+ organizations?: boolean;
153
158
  userModel?: UserModel;
154
159
  defaultRoles?: RoleDefinition[];
155
160
  scopes?: ResourceScopes<S>;