@terreno/api 57.18.0 → 57.20.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 (169) hide show
  1. package/CHANGELOG.md +2071 -2
  2. package/dist/accountSecurity/accessActions.d.ts +38 -0
  3. package/dist/accountSecurity/accessActions.js +157 -0
  4. package/dist/accountSecurity/accountSecurityApp.d.ts +219 -0
  5. package/dist/accountSecurity/accountSecurityApp.js +438 -0
  6. package/dist/accountSecurity/accountSecurityService.d.ts +200 -0
  7. package/dist/accountSecurity/accountSecurityService.js +481 -0
  8. package/dist/accountSecurity/credentialActions.d.ts +16 -0
  9. package/dist/accountSecurity/credentialActions.js +189 -0
  10. package/dist/accountSecurity/membershipActions.d.ts +15 -0
  11. package/dist/accountSecurity/membershipActions.js +81 -0
  12. package/dist/accountSecurity/orgSecurityRoutes.d.ts +50 -0
  13. package/dist/accountSecurity/orgSecurityRoutes.js +149 -0
  14. package/dist/accountSecurity/securityEventHooks.d.ts +44 -0
  15. package/dist/accountSecurity/securityEventHooks.js +223 -0
  16. package/dist/accountSecurity/securityEvents.d.ts +162 -0
  17. package/dist/accountSecurity/securityEvents.js +114 -0
  18. package/dist/accountSecurity/securityNotifications.d.ts +125 -0
  19. package/dist/accountSecurity/securityNotifications.js +333 -0
  20. package/dist/api.js +38 -6
  21. package/dist/audit/auditEventModel.d.ts +5 -3
  22. package/dist/audit/auditEventModel.js +8 -6
  23. package/dist/audit/processQueue.js +4 -2
  24. package/dist/audit/record.d.ts +2 -2
  25. package/dist/audit/record.js +3 -0
  26. package/dist/authRecovery.js +29 -1
  27. package/dist/betterAuth.d.ts +179 -10
  28. package/dist/betterAuthApp.d.ts +15 -0
  29. package/dist/betterAuthApp.js +23 -0
  30. package/dist/betterAuthChallengeHeaders.d.ts +37 -0
  31. package/dist/betterAuthChallengeHeaders.js +180 -0
  32. package/dist/betterAuthFeatures.d.ts +54 -0
  33. package/dist/betterAuthFeatures.js +239 -0
  34. package/dist/betterAuthMethods.d.ts +73 -0
  35. package/dist/betterAuthMethods.js +55 -0
  36. package/dist/betterAuthOAuthHandoff.d.ts +10 -2
  37. package/dist/betterAuthOAuthHandoff.js +222 -24
  38. package/dist/betterAuthSetPassword.d.ts +33 -0
  39. package/dist/betterAuthSetPassword.js +166 -0
  40. package/dist/betterAuthSetup.d.ts +57 -8
  41. package/dist/betterAuthSetup.js +327 -36
  42. package/dist/consentApp.d.ts +9 -4
  43. package/dist/consentApp.js +344 -28
  44. package/dist/consentStatus.d.ts +60 -0
  45. package/dist/consentStatus.js +111 -0
  46. package/dist/errors.d.ts +6 -0
  47. package/dist/errors.js +41 -2
  48. package/dist/expressServer.js +3 -2
  49. package/dist/index.d.ts +14 -2
  50. package/dist/index.js +23 -3
  51. package/dist/mcp/oauth.js +151 -11
  52. package/dist/mcp/oauthMetadata.d.ts +2 -1
  53. package/dist/mcp/oauthMetadata.js +7 -4
  54. package/dist/models/consentResponse.js +51 -0
  55. package/dist/models/mcpOAuthClient.js +78 -2
  56. package/dist/models/mcpOAuthToken.js +28 -4
  57. package/dist/orgs/membershipGuards.d.ts +7 -0
  58. package/dist/orgs/membershipGuards.js +32 -0
  59. package/dist/orgs/orgsApp.d.ts +19 -1
  60. package/dist/orgs/orgsApp.js +55 -24
  61. package/dist/rateLimit/policies.js +8 -0
  62. package/dist/rbac/access.js +2 -1
  63. package/dist/rbac/resolve.d.ts +9 -1
  64. package/dist/rbac/resolve.js +21 -16
  65. package/dist/rbac/roleManager.d.ts +6 -0
  66. package/dist/rbac/roleManager.js +8 -7
  67. package/dist/rbac/roleModel.d.ts +1 -0
  68. package/dist/rbac/roleModel.js +45 -3
  69. package/dist/rbac/statements.d.ts +2 -2
  70. package/dist/rbac/statements.js +10 -1
  71. package/dist/rbac/types.d.ts +6 -0
  72. package/dist/rbac/userWriteGuards.js +2 -1
  73. package/dist/schemaMetadata.js +8 -1
  74. package/dist/seedRunner.js +7 -2
  75. package/dist/terrenoApp.d.ts +4 -0
  76. package/dist/terrenoApp.js +15 -0
  77. package/dist/tests/models.d.ts +5 -0
  78. package/dist/tests/models.js +8 -0
  79. package/dist/types/consentResponse.d.ts +8 -0
  80. package/dist/types/mcpOAuth.d.ts +35 -2
  81. package/package.json +6 -3
  82. package/src/__snapshots__/openApi.test.ts.snap +288 -0
  83. package/src/__snapshots__/openApiBuilder.test.ts.snap +96 -0
  84. package/src/accountSecurity/accessActions.test.ts +723 -0
  85. package/src/accountSecurity/accessActions.ts +173 -0
  86. package/src/accountSecurity/accountSecurity.test.ts +947 -0
  87. package/src/accountSecurity/accountSecurityApp.ts +720 -0
  88. package/src/accountSecurity/accountSecurityService.ts +826 -0
  89. package/src/accountSecurity/credentialActions.test.ts +867 -0
  90. package/src/accountSecurity/credentialActions.ts +260 -0
  91. package/src/accountSecurity/membershipActions.ts +89 -0
  92. package/src/accountSecurity/orgSecurityRoutes.test.ts +841 -0
  93. package/src/accountSecurity/orgSecurityRoutes.ts +232 -0
  94. package/src/accountSecurity/securityEventHooks.ts +294 -0
  95. package/src/accountSecurity/securityEvents.ts +165 -0
  96. package/src/accountSecurity/securityNotifications.test.ts +1323 -0
  97. package/src/accountSecurity/securityNotifications.ts +516 -0
  98. package/src/api.arrayOperations.test.ts +71 -0
  99. package/src/api.ts +38 -7
  100. package/src/audit/auditEventModel.ts +10 -7
  101. package/src/audit/processQueue.ts +4 -2
  102. package/src/audit/record.test.ts +15 -0
  103. package/src/audit/record.ts +10 -2
  104. package/src/authRecovery.test.ts +23 -0
  105. package/src/authRecovery.ts +34 -1
  106. package/src/authRecoveryBetterAuth.test.ts +169 -0
  107. package/src/betterAuth.ts +194 -8
  108. package/src/betterAuthApp.ts +32 -0
  109. package/src/betterAuthChallengeHeaders.test.ts +476 -0
  110. package/src/betterAuthChallengeHeaders.ts +227 -0
  111. package/src/betterAuthFeatures.test.ts +489 -0
  112. package/src/betterAuthFeatures.ts +283 -0
  113. package/src/betterAuthLinking.test.ts +844 -0
  114. package/src/betterAuthMethods.test.ts +138 -0
  115. package/src/betterAuthMethods.ts +98 -0
  116. package/src/betterAuthOAuthHandoff.test.ts +482 -69
  117. package/src/betterAuthOAuthHandoff.ts +293 -33
  118. package/src/betterAuthOAuthProxy.test.ts +421 -0
  119. package/src/betterAuthPasswordReset.test.ts +190 -0
  120. package/src/betterAuthSetPassword.test.ts +378 -0
  121. package/src/betterAuthSetPassword.ts +213 -0
  122. package/src/betterAuthSetup.test.ts +39 -7
  123. package/src/betterAuthSetup.ts +457 -38
  124. package/src/consentApp.test.ts +869 -2
  125. package/src/consentApp.ts +438 -36
  126. package/src/consentStatus.test.ts +226 -0
  127. package/src/consentStatus.ts +171 -0
  128. package/src/errors.test.ts +81 -0
  129. package/src/errors.ts +50 -1
  130. package/src/expressServer.test.ts +29 -0
  131. package/src/expressServer.ts +3 -2
  132. package/src/index.ts +30 -0
  133. package/src/mcp/oauth.test.ts +463 -2
  134. package/src/mcp/oauth.ts +184 -13
  135. package/src/mcp/oauthMetadata.ts +5 -2
  136. package/src/models/consentResponse.ts +53 -0
  137. package/src/models/mcpOAuthClient.ts +100 -3
  138. package/src/models/mcpOAuthToken.ts +30 -5
  139. package/src/orgs/membershipGuards.ts +39 -0
  140. package/src/orgs/orgRbac.test.ts +1 -1
  141. package/src/orgs/orgsApp.test.ts +101 -2
  142. package/src/orgs/orgsApp.ts +69 -28
  143. package/src/rateLimit/policies.test.ts +53 -0
  144. package/src/rateLimit/policies.ts +8 -0
  145. package/src/rbac/access.ts +4 -1
  146. package/src/rbac/resolve.test.ts +65 -0
  147. package/src/rbac/resolve.ts +37 -17
  148. package/src/rbac/roleManager.test.ts +64 -0
  149. package/src/rbac/roleManager.ts +15 -6
  150. package/src/rbac/roleModel.test.ts +174 -1
  151. package/src/rbac/roleModel.ts +66 -3
  152. package/src/rbac/routes.test.ts +58 -0
  153. package/src/rbac/statements.test.ts +4 -1
  154. package/src/rbac/statements.ts +11 -1
  155. package/src/rbac/types.ts +6 -1
  156. package/src/rbac/userWriteGuards.test.ts +48 -0
  157. package/src/rbac/userWriteGuards.ts +5 -2
  158. package/src/schemaMetadata.test.ts +39 -0
  159. package/src/schemaMetadata.ts +11 -1
  160. package/src/seedRunner.test.ts +56 -0
  161. package/src/seedRunner.ts +7 -2
  162. package/src/terrenoApp.ts +20 -0
  163. package/src/tests/accountSecurityTestApp.ts +290 -0
  164. package/src/tests/betterAuthStubs.ts +188 -0
  165. package/src/tests/mockOidcProvider.ts +105 -0
  166. package/src/tests/models.ts +13 -0
  167. package/src/tests/softwareAuthenticator.ts +183 -0
  168. package/src/types/consentResponse.ts +8 -0
  169. package/src/types/mcpOAuth.ts +39 -3
@@ -339,6 +339,70 @@ describe("roleManager", () => {
339
339
  expect((await UserModel.findById(unprivileged.id))?.roles).toEqual(["member"]);
340
340
  });
341
341
 
342
+ it("refuses with 503 when the target's grants from a failed source are unknown", async () => {
343
+ await setupDb();
344
+ const UserModel = getRbacTestUserModel();
345
+ const target = await UserModel.create({email: "source-target@example.com", roles: []});
346
+ let isDown = false;
347
+ const access = createAccess({
348
+ connection: mongoose.connection,
349
+ defaultRoles: [
350
+ {
351
+ displayName: "Assigner",
352
+ name: "assigner",
353
+ permissions: {rbac: ["assignRoles"], todo: ["read"]},
354
+ },
355
+ ],
356
+ sources: [
357
+ {
358
+ // Additive only, so an outage drops its grants instead of failing every request.
359
+ failClosedWhenDenyUnknown: false,
360
+ getGrants: async ({user}) => {
361
+ if (String(user.id) !== target.id) {
362
+ return null;
363
+ }
364
+ if (isDown) {
365
+ throw new Error("idp down");
366
+ }
367
+ return {permissions: {user: ["delete"]}};
368
+ },
369
+ name: "idp-grants",
370
+ ttlMs: 0,
371
+ },
372
+ ],
373
+ statements: appStatements,
374
+ userModel: UserModel as unknown as UserModel,
375
+ });
376
+ await access.roles.seedDefaults();
377
+ const actor = createTestUser({roles: ["assigner"]});
378
+ const denied = {
379
+ status: 403,
380
+ title: "Cannot modify a user with permissions you do not hold",
381
+ };
382
+ await expect(
383
+ access.roles.assign({actor, roleNames: ["member"], userId: target.id})
384
+ ).rejects.toMatchObject(denied);
385
+
386
+ isDown = true;
387
+ access.invalidateCache({userId: target.id});
388
+
389
+ // Without the source the target looks like it holds nothing the actor lacks.
390
+ const unavailable = {status: 503, title: "Permission source unavailable"};
391
+ await expect(
392
+ access.roles.assign({actor, roleNames: ["member"], userId: target.id})
393
+ ).rejects.toMatchObject(unavailable);
394
+ await expect(
395
+ access.roles.unassign({actor, roleNames: ["member"], userId: target.id})
396
+ ).rejects.toMatchObject(unavailable);
397
+ await expect(
398
+ access.roles.assertCanModifyUser({actor, userId: target.id})
399
+ ).rejects.toMatchObject(unavailable);
400
+ await expect(
401
+ access.roles.previewAssignment({actor, roleNames: ["member"], userId: target.id})
402
+ ).rejects.toMatchObject(unavailable);
403
+ expect((await UserModel.findById(target.id))?.roles).toEqual([]);
404
+ });
405
+
342
406
  it("assertCanModifyUser rejects when the actor lacks the target user's permissions", async () => {
343
407
  await setupDb();
344
408
  const UserModel = getRbacTestUserModel();
@@ -87,10 +87,12 @@ const assertNoEscalation = async (
87
87
  const assertCanModifyTargetUser = async (
88
88
  actor: User,
89
89
  target: User,
90
- getActorPermissions: (user: User) => Promise<PermissionSet>
90
+ getActorPermissions: (user: User) => Promise<PermissionSet>,
91
+ getTargetPermissions: (user: User) => Promise<PermissionSet>
91
92
  ): Promise<void> => {
92
93
  const actorPermissions = await getActorPermissions(actor);
93
- const targetPermissions = await getActorPermissions(target);
94
+ // A target missing a failed source's grants would look less privileged than it is.
95
+ const targetPermissions = await getTargetPermissions(target);
94
96
  if (!isPermissionSubset(actorPermissions, targetPermissions)) {
95
97
  logger.warn("RBAC privileged-user mutation denied", {
96
98
  actorId: actor.id,
@@ -109,6 +111,12 @@ export const createRoleManager = (args: {
109
111
  defaultRoles?: RoleDefinition[];
110
112
  getActorPermissions: (user: User) => Promise<PermissionSet>;
111
113
  getPreviewPermissions: (user: User) => Promise<PermissionSet>;
114
+ /**
115
+ * Resolves the user a role change acts on. It must return the complete set or throw (the
116
+ * access instance passes `requireComplete: true`), since a target missing a failed source's
117
+ * grants looks less privileged than it is. Defaults to `getActorPermissions`.
118
+ */
119
+ getTargetPermissions?: (user: User) => Promise<PermissionSet>;
112
120
  invalidateCache: (invalidateArgs?: {userId?: string}) => void;
113
121
  userModel?: UserModel;
114
122
  persistAudit?: boolean;
@@ -120,6 +128,7 @@ export const createRoleManager = (args: {
120
128
  defaultRoles = terrenoDefaultRoles,
121
129
  getActorPermissions,
122
130
  getPreviewPermissions,
131
+ getTargetPermissions = getActorPermissions,
123
132
  invalidateCache,
124
133
  userModel,
125
134
  persistAudit = true,
@@ -243,7 +252,7 @@ export const createRoleManager = (args: {
243
252
  if (!targetUser) {
244
253
  throw new APIError({status: 404, title: "User not found"});
245
254
  }
246
- await assertCanModifyTargetUser(actor, targetUser, getActorPermissions);
255
+ await assertCanModifyTargetUser(actor, targetUser, getActorPermissions, getTargetPermissions);
247
256
  },
248
257
  assign: async ({actor, userId, roleNames}) => {
249
258
  await assertCanAssignRoles(actor, getActorPermissions);
@@ -255,7 +264,7 @@ export const createRoleManager = (args: {
255
264
  if (!targetUser) {
256
265
  throw new APIError({status: 404, title: "User not found"});
257
266
  }
258
- await assertCanModifyTargetUser(actor, targetUser, getActorPermissions);
267
+ await assertCanModifyTargetUser(actor, targetUser, getActorPermissions, getTargetPermissions);
259
268
  const uniqueRoleNames = [...new Set(roleNames)];
260
269
  for (let i = 0; i < uniqueRoleNames.length; i++) {
261
270
  for (let j = i + 1; j < uniqueRoleNames.length; j++) {
@@ -334,7 +343,7 @@ export const createRoleManager = (args: {
334
343
  if (!targetUser) {
335
344
  throw new APIError({status: 404, title: "User not found"});
336
345
  }
337
- await assertCanModifyTargetUser(actor, targetUser, getActorPermissions);
346
+ await assertCanModifyTargetUser(actor, targetUser, getActorPermissions, getTargetPermissions);
338
347
  const uniqueRoleNames = [...new Set(roleNames)];
339
348
  for (const roleName of uniqueRoleNames) {
340
349
  const role = await rbacRoleModel.findExactlyOne({name: roleName});
@@ -398,7 +407,7 @@ export const createRoleManager = (args: {
398
407
  if (!targetUser) {
399
408
  throw new APIError({status: 404, title: "User not found"});
400
409
  }
401
- await assertCanModifyTargetUser(actor, targetUser, getActorPermissions);
410
+ await assertCanModifyTargetUser(actor, targetUser, getActorPermissions, getTargetPermissions);
402
411
  assertUserSaveAvailable(targetUser);
403
412
  const before = await getPreviewPermissions(targetUser);
404
413
  const rbacUser = targetUser as unknown as User & {roles: string[]};
@@ -39,7 +39,7 @@ describe("rbac role model", () => {
39
39
  expect(superadmin.permissions.user).toContain("delete");
40
40
  expect(superadmin.permissions.featureFlag).toContain("list");
41
41
  expect(superadmin.permissions.consentForm).toContain("list");
42
- expect(superadmin.permissions.consentResponse).toEqual(["list", "read"]);
42
+ expect(superadmin.permissions.consentResponse).toEqual(["list", "read", "signOnBehalf"]);
43
43
  expect(superadmin.permissions.organization).toContain("list");
44
44
 
45
45
  expect(await RbacRole.findOne({name: "operator"})).toBeNull();
@@ -61,9 +61,129 @@ describe("rbac role model", () => {
61
61
  expect(operator.isLocked).toBe(true);
62
62
  expect(operator.permissions.organization).toEqual([...terrenoStatements.organization]);
63
63
  expect(operator.permissions.admin).toEqual(["access"]);
64
+ expect(operator.permissions.user).toEqual(["list", "read", "update", "manageSecurity"]);
65
+ });
66
+
67
+ it("adds manageSecurity to an operator seeded before it existed, keeping its other grants", async () => {
68
+ await setupDb();
69
+ const RbacRole = createRbacRoleModel(mongoose.connection);
70
+ await RbacRole.create({
71
+ displayName: "Operator",
72
+ isLocked: true,
73
+ name: "operator",
74
+ permissions: {organization: ["list"], user: ["read"]},
75
+ });
76
+
77
+ await RbacRole.seedDefaults({
78
+ extraRoles: [organizationOperatorRole],
79
+ statements: terrenoStatements,
80
+ });
81
+
82
+ const operator = await RbacRole.findExactlyOne({name: "operator"});
83
+ expect(operator.permissions.user).toEqual(["read", "manageSecurity"]);
84
+ expect(operator.permissions.organization).toEqual(["list"]);
85
+ expect(operator.appliedGrants).toEqual(["user.manageSecurity"]);
86
+ });
87
+
88
+ it("keeps a revoked manageSecurity revoked across reseeds", async () => {
89
+ await setupDb();
90
+ const RbacRole = createRbacRoleModel(mongoose.connection);
91
+ const seed = (): Promise<void> =>
92
+ RbacRole.seedDefaults({
93
+ extraRoles: [organizationOperatorRole],
94
+ statements: terrenoStatements,
95
+ });
96
+ // A row from before the grant existed gains it once.
97
+ await RbacRole.create({
98
+ displayName: "Operator",
99
+ isLocked: true,
100
+ name: "operator",
101
+ permissions: {user: ["read"]},
102
+ });
103
+ await seed();
104
+ await RbacRole.updateOne({name: "operator"}, {$set: {"permissions.user": ["read"]}});
105
+
106
+ await seed();
107
+ await seed();
108
+
109
+ const operator = await RbacRole.findExactlyOne({name: "operator"});
110
+ expect(operator.permissions.user).toEqual(["read"]);
111
+ });
112
+
113
+ it("keeps a revoked manageSecurity revoked on an operator seeded with it", async () => {
114
+ await setupDb();
115
+ const RbacRole = createRbacRoleModel(mongoose.connection);
116
+ const seed = (): Promise<void> =>
117
+ RbacRole.seedDefaults({
118
+ extraRoles: [organizationOperatorRole],
119
+ statements: terrenoStatements,
120
+ });
121
+ await seed();
122
+ await RbacRole.updateOne(
123
+ {name: "operator"},
124
+ {$set: {"permissions.user": ["list", "read", "update"]}}
125
+ );
126
+
127
+ await seed();
128
+
129
+ const operator = await RbacRole.findExactlyOne({name: "operator"});
64
130
  expect(operator.permissions.user).toEqual(["list", "read", "update"]);
65
131
  });
66
132
 
133
+ it("gives the operator admin read on users when the app declares adminUser", async () => {
134
+ await setupDb();
135
+ const RbacRole = createRbacRoleModel(mongoose.connection);
136
+ await RbacRole.seedDefaults({
137
+ extraRoles: [organizationOperatorRole],
138
+ statements: {...terrenoStatements, adminUser: ["read", "write", "writeOwned"]},
139
+ });
140
+
141
+ const operator = await RbacRole.findExactlyOne({name: "operator"});
142
+ expect(operator.permissions.adminUser).toEqual(["read"]);
143
+ expect(operator.permissions.user).toEqual(["list", "read", "update", "manageSecurity"]);
144
+ expect(operator.appliedGrants).toEqual(["user.manageSecurity", "adminUser.read"]);
145
+ });
146
+
147
+ it("leaves adminUser off an operator in an app that does not declare it", async () => {
148
+ await setupDb();
149
+ const RbacRole = createRbacRoleModel(mongoose.connection);
150
+ await RbacRole.seedDefaults({
151
+ extraRoles: [organizationOperatorRole],
152
+ statements: terrenoStatements,
153
+ });
154
+
155
+ const operator = await RbacRole.findExactlyOne({name: "operator"});
156
+ expect(operator.permissions.adminUser).toBeUndefined();
157
+ expect(operator.appliedGrants).toEqual(["user.manageSecurity"]);
158
+ });
159
+
160
+ it("adds adminUser read to an existing operator once the app declares adminUser", async () => {
161
+ await setupDb();
162
+ const RbacRole = createRbacRoleModel(mongoose.connection);
163
+ const adminUserStatements = {...terrenoStatements, adminUser: ["read", "write", "writeOwned"]};
164
+ await RbacRole.seedDefaults({
165
+ extraRoles: [organizationOperatorRole],
166
+ statements: terrenoStatements,
167
+ });
168
+
169
+ await RbacRole.seedDefaults({
170
+ extraRoles: [organizationOperatorRole],
171
+ statements: adminUserStatements,
172
+ });
173
+ const operator = await RbacRole.findExactlyOne({name: "operator"});
174
+ expect(operator.permissions.adminUser).toEqual(["read"]);
175
+ expect(operator.appliedGrants).toEqual(["user.manageSecurity", "adminUser.read"]);
176
+
177
+ // A revoked grant stays revoked across reseeds.
178
+ await RbacRole.updateOne({name: "operator"}, {$unset: {"permissions.adminUser": ""}});
179
+ await RbacRole.seedDefaults({
180
+ extraRoles: [organizationOperatorRole],
181
+ statements: adminUserStatements,
182
+ });
183
+ const revoked = await RbacRole.findExactlyOne({name: "operator"});
184
+ expect(revoked.permissions.adminUser).toBeUndefined();
185
+ });
186
+
67
187
  it("upserts default roles without duplicating", async () => {
68
188
  await setupDb();
69
189
  const RbacRole = createRbacRoleModel(mongoose.connection);
@@ -128,6 +248,59 @@ describe("rbac role model", () => {
128
248
  expect(admin.permissions.aiExperiment).toEqual([...terrenoStatements.aiExperiment]);
129
249
  });
130
250
 
251
+ it("seeds admin with consentResponse:signOnBehalf", async () => {
252
+ await setupDb();
253
+ const RbacRole = createRbacRoleModel(mongoose.connection);
254
+ await RbacRole.seedDefaults({statements: terrenoStatements});
255
+
256
+ const admin = await RbacRole.findExactlyOne({name: "admin"});
257
+ expect(admin.permissions.consentResponse).toEqual(["signOnBehalf"]);
258
+ });
259
+
260
+ it("adds consentResponse:signOnBehalf to an existing unsealed admin role on re-seed", async () => {
261
+ await setupDb();
262
+ const RbacRole = createRbacRoleModel(mongoose.connection);
263
+ await RbacRole.seedDefaults({statements: terrenoStatements});
264
+ await RbacRole.updateOne({name: "admin"}, {$set: {permissions: {user: ["read"]}}});
265
+ await RbacRole.seedDefaults({statements: terrenoStatements});
266
+
267
+ const admin = await RbacRole.findExactlyOne({name: "admin"});
268
+ expect(admin.permissions.user).toEqual(["read"]);
269
+ expect(admin.permissions.consentResponse).toEqual(["signOnBehalf"]);
270
+ });
271
+
272
+ it("keeps existing consentResponse grants when merging signOnBehalf into admin", async () => {
273
+ await setupDb();
274
+ const RbacRole = createRbacRoleModel(mongoose.connection);
275
+ await RbacRole.seedDefaults({statements: terrenoStatements});
276
+ await RbacRole.updateOne(
277
+ {name: "admin"},
278
+ {$set: {permissions: {consentResponse: ["list", "read"]}}}
279
+ );
280
+ await RbacRole.seedDefaults({statements: terrenoStatements});
281
+
282
+ const admin = await RbacRole.findExactlyOne({name: "admin"});
283
+ expect(admin.permissions.consentResponse).toEqual(["list", "read", "signOnBehalf"]);
284
+ });
285
+
286
+ it("does not merge into a sealed admin role, which is refreshed from code instead", async () => {
287
+ await setupDb();
288
+ const RbacRole = createRbacRoleModel(mongoose.connection);
289
+ await RbacRole.create({
290
+ displayName: "Admin",
291
+ isLocked: true,
292
+ isSealed: true,
293
+ name: "admin",
294
+ permissions: {customApp: ["deploy"], user: ["read"]},
295
+ });
296
+ await RbacRole.seedDefaults({statements: terrenoStatements});
297
+
298
+ const admin = await RbacRole.findExactlyOne({name: "admin"});
299
+ expect(admin.permissions.customApp).toBeUndefined();
300
+ expect(admin.permissions.user).toEqual(["create", "list", "read", "update", "updateIdentity"]);
301
+ expect(admin.permissions.consentResponse).toEqual(["signOnBehalf"]);
302
+ });
303
+
131
304
  it("seeds auditor with observability list and read grants", async () => {
132
305
  await setupDb();
133
306
  const RbacRole = createRbacRoleModel(mongoose.connection);
@@ -26,6 +26,7 @@ export interface RoleDefinition {
26
26
 
27
27
  export interface RbacRoleDocument {
28
28
  _id: mongoose.Types.ObjectId;
29
+ appliedGrants: string[];
29
30
  name: string;
30
31
  displayName: string;
31
32
  description?: string;
@@ -51,6 +52,9 @@ export type RbacRoleModel = Model<RbacRoleDocument> & {
51
52
 
52
53
  export {READ_ONLY_ROLE_PERMISSIONS} from "./statements";
53
54
 
55
+ /** Resources whose default admin grants are added to existing unsealed admin roles on seed. */
56
+ const ADMIN_MERGED_RESOURCES = [...OBSERVABILITY_RBAC_RESOURCES, "consentResponse"] as const;
57
+
54
58
  const observabilityAdminPermissionSpec = (): PermissionSet => ({
55
59
  aiDataset: [...terrenoStatements.aiDataset],
56
60
  aiEvaluator: [...terrenoStatements.aiEvaluator],
@@ -72,6 +76,47 @@ const observabilityReadOnlyPermissionSpec = (statements: Statements): Permission
72
76
  return defaults;
73
77
  };
74
78
 
79
+ interface SeededRoleGrant {
80
+ /** Stable id recorded in `appliedGrants` once the grant has been merged. */
81
+ id: string;
82
+ permissions: PermissionSet;
83
+ }
84
+
85
+ /**
86
+ * Operator grants added after the role first shipped. Each is merged into an existing operator
87
+ * row once and then recorded in `appliedGrants`, so an admin who later revokes it keeps it
88
+ * revoked across restarts.
89
+ */
90
+ const OPERATOR_ADDED_GRANTS: SeededRoleGrant[] = [
91
+ {id: "user.manageSecurity", permissions: {user: ["manageSecurity"]}},
92
+ // An app that opts User into per-model admin access (`adminUser`) gates the admin User list
93
+ // and record on it instead of `user`. Operators find users there to reach their Security
94
+ // screen, so they need the same read they already hold on `user`.
95
+ {id: "adminUser.read", permissions: {adminUser: ["read"]}},
96
+ ];
97
+
98
+ /** Whether the app declares every resource and action a grant adds. */
99
+ const isGrantDeclared = (grant: SeededRoleGrant, statements: Statements): boolean =>
100
+ Object.entries(grant.permissions).every(([resource, actions]) =>
101
+ actions.every((action) => statements[resource]?.includes(action))
102
+ );
103
+
104
+ /**
105
+ * Grants added to a seeded role after it shipped. A grant on a resource the app does not declare
106
+ * is left out (and not recorded as applied), so it is merged once the app declares it.
107
+ */
108
+ const addedGrantsFor = (role: RoleDefinition, statements: Statements): SeededRoleGrant[] =>
109
+ role === organizationOperatorRole
110
+ ? OPERATOR_ADDED_GRANTS.filter((grant) => isGrantDeclared(grant, statements))
111
+ : [];
112
+
113
+ const mergeGrants = (permissions: PermissionSet, grants: SeededRoleGrant[]): PermissionSet =>
114
+ grants.reduce(
115
+ (merged, grant) =>
116
+ mergeMissingResourcePermissions(merged, grant.permissions, Object.keys(grant.permissions)),
117
+ permissions
118
+ );
119
+
75
120
  /**
76
121
  * Insert missing default roles. Existing unsealed roles are left unchanged so admin
77
122
  * customizations survive process restarts. Sealed roles are refreshed from code.
@@ -89,7 +134,7 @@ const upsertSeededRole = async (
89
134
  existing.permissions = mergeMissingResourcePermissions(
90
135
  existing.permissions,
91
136
  permissions,
92
- OBSERVABILITY_RBAC_RESOURCES
137
+ ADMIN_MERGED_RESOURCES
93
138
  );
94
139
  await existing.save();
95
140
  } else if (role.name === "auditor") {
@@ -99,6 +144,14 @@ const upsertSeededRole = async (
99
144
  OBSERVABILITY_RBAC_RESOURCES
100
145
  );
101
146
  await existing.save();
147
+ } else {
148
+ const applied = new Set(existing.appliedGrants ?? []);
149
+ const pending = addedGrantsFor(role, statements).filter((grant) => !applied.has(grant.id));
150
+ if (pending.length > 0) {
151
+ existing.permissions = mergeGrants(existing.permissions, pending);
152
+ existing.appliedGrants = [...applied, ...pending.map((grant) => grant.id)];
153
+ await existing.save();
154
+ }
102
155
  }
103
156
  return;
104
157
  }
@@ -111,14 +164,17 @@ const upsertSeededRole = async (
111
164
  await existing.save();
112
165
  return;
113
166
  }
167
+ // A new row starts with every added grant, so none is merged in later.
168
+ const addedGrants = addedGrantsFor(role, statements);
114
169
  await model.create({
170
+ appliedGrants: addedGrants.map((grant) => grant.id),
115
171
  description: role.description,
116
172
  displayName: role.displayName,
117
173
  excludesRoles: role.excludesRoles ?? [],
118
174
  isLocked: role.isLocked ?? false,
119
175
  isSealed: role.isSealed ?? false,
120
176
  name: role.name,
121
- permissions,
177
+ permissions: mergeGrants(permissions, addedGrants),
122
178
  });
123
179
  };
124
180
 
@@ -136,7 +192,7 @@ export const organizationOperatorRole: RoleDefinition = {
136
192
  permissions: {
137
193
  admin: ["access"],
138
194
  organization: ["create", "list", "read", "update", "delete", "manageMembers", "disable"],
139
- user: ["list", "read", "update"],
195
+ user: ["list", "read", "update", "manageSecurity"],
140
196
  },
141
197
  };
142
198
 
@@ -159,6 +215,7 @@ export const terrenoDefaultRoles: RoleDefinition[] = [
159
215
  adminAnnouncementClickEvent: ["read"],
160
216
  adminAnnouncementImpression: ["read"],
161
217
  configuration: ["read", "update"],
218
+ consentResponse: ["signOnBehalf"],
162
219
  user: ["create", "list", "read", "update", "updateIdentity"],
163
220
  ...observabilityAdminPermissionSpec(),
164
221
  },
@@ -179,6 +236,12 @@ export const terrenoDefaultRoles: RoleDefinition[] = [
179
236
 
180
237
  const rbacRoleSchema = new mongoose.Schema<RbacRoleDocument, RbacRoleModel>(
181
238
  {
239
+ appliedGrants: {
240
+ default: [],
241
+ description:
242
+ "Ids of grants added to a seeded role after it shipped that were already merged in, so a revoked grant is not re-added",
243
+ type: [String],
244
+ },
182
245
  description: {
183
246
  description: "Human-readable description of the role",
184
247
  type: String,
@@ -231,3 +231,61 @@ describe("rbacRouter", () => {
231
231
  expect(missingUserResponse.body.title).toBe("User not found");
232
232
  });
233
233
  });
234
+
235
+ describe("rbacRouter role assignment against a partially resolved target", () => {
236
+ it("refuses PUT /rbac/users/:id/roles with 503 when the target's source grants are unknown", async () => {
237
+ await setupDb();
238
+ const routeUserModel = getRouteUserModel();
239
+ await routeUserModel.deleteMany({});
240
+ const target = await routeUserModel.create({email: "source-target@example.com", roles: []});
241
+ let isDown = false;
242
+ const access = createAccess({
243
+ connection: mongoose.connection,
244
+ // The signed-in actor may assign roles but does not hold user:delete.
245
+ resolvePermissions: async ({user}) =>
246
+ String(user.id) === target.id ? {} : {rbac: ["read", "assignRoles"]},
247
+ sources: [
248
+ {
249
+ // Additive only, so an outage drops its grants instead of failing every request.
250
+ failClosedWhenDenyUnknown: false,
251
+ getGrants: async ({user}) => {
252
+ if (String(user.id) !== target.id) {
253
+ return null;
254
+ }
255
+ if (isDown) {
256
+ throw new Error("idp down");
257
+ }
258
+ return {permissions: {user: ["delete"]}};
259
+ },
260
+ name: "idp-grants",
261
+ ttlMs: 0,
262
+ },
263
+ ],
264
+ statements: appStatements,
265
+ userModel: routeUserModel as unknown as AuthUserModel,
266
+ });
267
+ await access.roles.seedDefaults();
268
+ const app = getBaseServer();
269
+ setupAuth(app, authUserModel);
270
+ addAuthRoutes(app, authUserModel);
271
+ rbacRouter({
272
+ access,
273
+ basePath: "/rbac",
274
+ userModel: routeUserModel as unknown as AuthUserModel,
275
+ }).register(app);
276
+ app.use(apiErrorMiddleware);
277
+ const agent = await authAsUser(app, "notAdmin");
278
+
279
+ const healthy = await agent.put(`/rbac/users/${target.id}/roles`).send({roleNames: ["member"]});
280
+ expect(healthy.status).toBe(403);
281
+ expect(healthy.body.title).toBe("Cannot modify a user with permissions you do not hold");
282
+
283
+ isDown = true;
284
+ access.invalidateCache({userId: target.id});
285
+
286
+ const down = await agent.put(`/rbac/users/${target.id}/roles`).send({roleNames: ["member"]});
287
+ expect(down.status).toBe(503);
288
+ expect(down.body.title).toBe("Permission source unavailable");
289
+ expect((await routeUserModel.findById(target.id))?.roles).toEqual([]);
290
+ });
291
+ });
@@ -36,7 +36,10 @@ describe("rbac statements", () => {
36
36
  "disable",
37
37
  ]);
38
38
  expect(terrenoStatements.consentForm).toEqual(["create", "list", "read", "update", "delete"]);
39
- expect(terrenoStatements.consentResponse).toEqual(["list", "read"]);
39
+ expect(terrenoStatements.consentResponse).toEqual(["list", "read", "signOnBehalf"]);
40
+ expect(terrenoStatementDescriptions.consentResponse.signOnBehalf).toBe(
41
+ "Record, view, and void provisional consent signatures for other users"
42
+ );
40
43
  assert.deepEqual(
41
44
  [...terrenoStatements.adminAnnouncementClickEvent],
42
45
  ["read", "write", "writeOwned"]
@@ -61,7 +61,7 @@ export const terrenoStatements = {
61
61
  announcementImpression: ["list", "read"],
62
62
  configuration: ["read", "update"],
63
63
  consentForm: MODEL_CRUD,
64
- consentResponse: ["list", "read"],
64
+ consentResponse: ["list", "read", "signOnBehalf"],
65
65
  featureFlag: MODEL_CRUD,
66
66
  organization: ORGANIZATION_ACTIONS,
67
67
  rbac: ["read", "manageRoles", "assignRoles"],
@@ -74,6 +74,8 @@ export const terrenoStatements = {
74
74
  "impersonate",
75
75
  "setPassword",
76
76
  "updateIdentity",
77
+ "manageSecurity",
78
+ "issueSignInLink",
77
79
  ],
78
80
  } as const;
79
81
 
@@ -140,7 +142,15 @@ export const terrenoStatementDescriptions: Record<string, Record<string, string>
140
142
  list: "List traces and observability status",
141
143
  read: "View trace detail and run trace test helpers",
142
144
  },
145
+ consentResponse: {
146
+ list: "List consent responses",
147
+ read: "View consent responses",
148
+ signOnBehalf: "Record, view, and void provisional consent signatures for other users",
149
+ },
143
150
  user: {
151
+ issueSignInLink:
152
+ "Create a sign-in account for a legacy user and hand them a set-password link (AccountSecurityApp)",
153
+ manageSecurity: "View any user's sign-in methods and run account recovery (AccountSecurityApp)",
144
154
  updateIdentity:
145
155
  "Change another user's email, disabled flag, email verification, or linked Better Auth and GitHub ids",
146
156
  },
package/src/rbac/types.ts CHANGED
@@ -187,7 +187,12 @@ export interface TerrenoAccess<S extends Statements> {
187
187
  readonly statements: S;
188
188
  readonly ac: ReturnType<typeof createAccessControl<S>>;
189
189
  can: (args: AccessCheckArgs<S>) => Promise<AccessResult>;
190
- getPermissions: (args: {user: User}) => Promise<PermissionSet>;
190
+ /**
191
+ * The user's effective permissions. With `requireComplete`, a permission source that failed and
192
+ * whose grants are unknown throws 503 instead of leaving its grants out; use it for a user whose
193
+ * missing permissions would loosen a check (the target of "may the actor act on this user?").
194
+ */
195
+ getPermissions: (args: {user: User; requireComplete?: boolean}) => Promise<PermissionSet>;
191
196
  queryFilter: (args: {
192
197
  user?: User;
193
198
  resource: string;
@@ -108,6 +108,54 @@ describe("RBAC target-privilege check on user model writes", () => {
108
108
  expect(await UserModel.findById(superadmin.id)).toBeTruthy();
109
109
  });
110
110
 
111
+ it("refuses with 503 when the target's grants from a failed source are unknown", async () => {
112
+ let isDown = false;
113
+ const grantingAccess = createAccess({
114
+ connection: mongoose.connection,
115
+ sources: [
116
+ {
117
+ // Additive only, so an outage drops its grants instead of failing every request.
118
+ failClosedWhenDenyUnknown: false,
119
+ getGrants: async ({user}) => {
120
+ if (String(user.id) !== member.id) {
121
+ return null;
122
+ }
123
+ if (isDown) {
124
+ throw new Error("idp down");
125
+ }
126
+ return {permissions: {user: ["delete"]}};
127
+ },
128
+ name: "idp-grants",
129
+ ttlMs: 0,
130
+ },
131
+ ],
132
+ statements: terrenoStatements,
133
+ userModel: UserModel as unknown as UserMongooseModel,
134
+ }) as unknown as AnyTerrenoAccess;
135
+ const grantingOptions = {
136
+ accessControl: grantingAccess,
137
+ permissions: userPermissions,
138
+ } as unknown as Parameters<typeof executeUpdate>[0]["options"];
139
+ const update = (): Promise<unknown> =>
140
+ executeUpdate({
141
+ body: {name: "Renamed"},
142
+ id: member.id,
143
+ model: UserModel,
144
+ options: grantingOptions,
145
+ user: delegate,
146
+ });
147
+ await expect(update()).rejects.toMatchObject({status: 403});
148
+
149
+ isDown = true;
150
+ grantingAccess.invalidateCache({userId: member.id});
151
+
152
+ await expect(update()).rejects.toMatchObject({
153
+ status: 503,
154
+ title: "Permission source unavailable",
155
+ });
156
+ expect((await UserModel.findById(member.id).lean())?.name).toBe("Member");
157
+ });
158
+
111
159
  it("allows updates to users the actor covers, to the actor itself, and by legacy admins", async () => {
112
160
  await executeUpdate({
113
161
  body: {name: "Member renamed"},
@@ -73,7 +73,9 @@ export const assertCanWriteTargetUser = async ({
73
73
  return;
74
74
  }
75
75
  const getPermissions = (
76
- accessControl as {getPermissions?: (args: {user: User}) => Promise<PermissionSet>}
76
+ accessControl as {
77
+ getPermissions?: (args: {user: User; requireComplete?: boolean}) => Promise<PermissionSet>;
78
+ }
77
79
  ).getPermissions;
78
80
  // Test doubles without a resolver have no permissions to compare.
79
81
  if (typeof getPermissions !== "function") {
@@ -85,7 +87,8 @@ export const assertCanWriteTargetUser = async ({
85
87
  return;
86
88
  }
87
89
  const actorPermissions = await getPermissions({user: actor});
88
- const targetPermissions = await getPermissions({user: target as User});
90
+ // A target missing a failed source's grants would look less privileged than it is.
91
+ const targetPermissions = await getPermissions({requireComplete: true, user: target as User});
89
92
  if (isPermissionSubset(actorPermissions, targetPermissions)) {
90
93
  return;
91
94
  }