@terreno/api 57.0.0-beta.1 → 57.1.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 (175) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +8 -0
  2. package/dist/actions.d.ts +7 -2
  3. package/dist/actions.js +60 -25
  4. package/dist/adminModelRouter.d.ts +14 -0
  5. package/dist/adminModelRouter.js +199 -0
  6. package/dist/adminTypes.d.ts +156 -0
  7. package/dist/adminTypes.js +5 -0
  8. package/dist/api.d.ts +44 -3
  9. package/dist/api.js +74 -26
  10. package/dist/auth.d.ts +18 -1
  11. package/dist/auth.js +122 -20
  12. package/dist/consentApp.d.ts +2 -0
  13. package/dist/consentApp.js +98 -0
  14. package/dist/index.d.ts +22 -1
  15. package/dist/index.js +51 -7
  16. package/dist/mcp/auth.d.ts +11 -0
  17. package/dist/mcp/auth.js +133 -0
  18. package/dist/mcp/createMCPRequest.d.ts +16 -0
  19. package/dist/mcp/createMCPRequest.js +26 -0
  20. package/dist/mcp/handlers.d.ts +8 -0
  21. package/dist/mcp/handlers.js +793 -0
  22. package/dist/mcp/query.d.ts +32 -0
  23. package/dist/mcp/query.js +232 -0
  24. package/dist/mcp/registry.d.ts +21 -0
  25. package/dist/mcp/registry.js +54 -0
  26. package/dist/mcp/schemaGenerator.d.ts +14 -0
  27. package/dist/mcp/schemaGenerator.js +379 -0
  28. package/dist/mcp/server.d.ts +8 -0
  29. package/dist/mcp/server.js +133 -0
  30. package/dist/mcp/toolGenerator.d.ts +14 -0
  31. package/dist/mcp/toolGenerator.js +246 -0
  32. package/dist/mcp/types.d.ts +85 -0
  33. package/dist/mcp/types.js +2 -0
  34. package/dist/openApi.d.ts +1 -1
  35. package/dist/openApi.js +26 -8
  36. package/dist/permissions.js +15 -15
  37. package/dist/rbac/access.d.ts +3 -0
  38. package/dist/rbac/access.js +294 -0
  39. package/dist/rbac/auditModel.d.ts +31 -0
  40. package/dist/rbac/auditModel.js +112 -0
  41. package/dist/rbac/backfillAdmins.d.ts +18 -0
  42. package/dist/rbac/backfillAdmins.js +139 -0
  43. package/dist/rbac/fieldViews.d.ts +3 -0
  44. package/dist/rbac/fieldViews.js +201 -0
  45. package/dist/rbac/middleware.d.ts +21 -0
  46. package/dist/rbac/middleware.js +108 -0
  47. package/dist/rbac/modelRouterAccess.d.ts +42 -0
  48. package/dist/rbac/modelRouterAccess.js +388 -0
  49. package/dist/rbac/permissionUtils.d.ts +8 -0
  50. package/dist/rbac/permissionUtils.js +209 -0
  51. package/dist/rbac/realtimeAccess.d.ts +18 -0
  52. package/dist/rbac/realtimeAccess.js +173 -0
  53. package/dist/rbac/resolve.d.ts +28 -0
  54. package/dist/rbac/resolve.js +387 -0
  55. package/dist/rbac/roleManager.d.ts +20 -0
  56. package/dist/rbac/roleManager.js +741 -0
  57. package/dist/rbac/roleModel.d.ts +42 -0
  58. package/dist/rbac/roleModel.js +267 -0
  59. package/dist/rbac/routes.d.ts +9 -0
  60. package/dist/rbac/routes.js +211 -0
  61. package/dist/rbac/scopes.d.ts +15 -0
  62. package/dist/rbac/scopes.js +155 -0
  63. package/dist/rbac/statements.d.ts +20 -0
  64. package/dist/rbac/statements.js +115 -0
  65. package/dist/rbac/types.d.ts +202 -0
  66. package/dist/rbac/types.js +2 -0
  67. package/dist/rbac/userPlugin.d.ts +12 -0
  68. package/dist/rbac/userPlugin.js +41 -0
  69. package/dist/realtime/changeStreamWatcher.d.ts +1 -1
  70. package/dist/realtime/changeStreamWatcher.js +48 -39
  71. package/dist/realtime/realtimeApp.js +4 -8
  72. package/dist/realtime/registry.d.ts +5 -0
  73. package/dist/realtime/registry.js +13 -1
  74. package/dist/scrubAdminFields.d.ts +17 -0
  75. package/dist/scrubAdminFields.js +192 -0
  76. package/dist/sync/executors.d.ts +1 -1
  77. package/dist/sync/executors.js +63 -40
  78. package/dist/sync/loadHarness.js +4 -5
  79. package/dist/sync/registry.d.ts +5 -0
  80. package/dist/sync/registry.js +13 -1
  81. package/dist/sync/routes.js +41 -36
  82. package/dist/sync/serialize.js +5 -6
  83. package/dist/terrenoApp.d.ts +18 -0
  84. package/dist/terrenoApp.js +46 -3
  85. package/dist/terrenoPlugin.d.ts +8 -1
  86. package/dist/tests/createTestData.js +8 -0
  87. package/dist/tests/models.d.ts +1 -0
  88. package/dist/tests/models.js +5 -0
  89. package/dist/tests/testHelper.js +1 -2
  90. package/dist/transformers.js +16 -1
  91. package/package.json +16 -12
  92. package/src/__snapshots__/openApi.test.ts.snap +192 -0
  93. package/src/actions.test.ts +194 -1
  94. package/src/actions.ts +65 -8
  95. package/src/adminModelRouter.ts +154 -0
  96. package/src/adminTypes.ts +183 -0
  97. package/src/api.test.ts +66 -1
  98. package/src/api.ts +131 -12
  99. package/src/auth.test.ts +135 -1
  100. package/src/auth.ts +81 -3
  101. package/src/consentApp.test.ts +24 -0
  102. package/src/consentApp.ts +100 -0
  103. package/src/index.ts +56 -0
  104. package/src/mcp/auth.test.ts +197 -0
  105. package/src/mcp/auth.ts +100 -0
  106. package/src/mcp/createMCPRequest.test.ts +47 -0
  107. package/src/mcp/createMCPRequest.ts +32 -0
  108. package/src/mcp/customTools.test.ts +54 -0
  109. package/src/mcp/handlers.ts +639 -0
  110. package/src/mcp/integration.test.ts +1493 -0
  111. package/src/mcp/query.test.ts +172 -0
  112. package/src/mcp/query.ts +179 -0
  113. package/src/mcp/registry.ts +70 -0
  114. package/src/mcp/schemaGenerator.test.ts +182 -0
  115. package/src/mcp/schemaGenerator.ts +354 -0
  116. package/src/mcp/server.test.ts +226 -0
  117. package/src/mcp/server.ts +86 -0
  118. package/src/mcp/toolGenerator.test.ts +284 -0
  119. package/src/mcp/toolGenerator.ts +199 -0
  120. package/src/mcp/types.ts +95 -0
  121. package/src/openApi.test.ts +107 -0
  122. package/src/openApi.ts +32 -1
  123. package/src/permissions.ts +3 -2
  124. package/src/rbac/access.test.ts +357 -0
  125. package/src/rbac/access.ts +201 -0
  126. package/src/rbac/auditModel.ts +103 -0
  127. package/src/rbac/backfillAdmins.ts +54 -0
  128. package/src/rbac/fieldViews.test.ts +39 -0
  129. package/src/rbac/fieldViews.ts +122 -0
  130. package/src/rbac/middleware.ts +55 -0
  131. package/src/rbac/modelRouterAccess.test.ts +336 -0
  132. package/src/rbac/modelRouterAccess.ts +331 -0
  133. package/src/rbac/permissionUtils.test.ts +112 -0
  134. package/src/rbac/permissionUtils.ts +83 -0
  135. package/src/rbac/realtimeAccess.test.ts +242 -0
  136. package/src/rbac/realtimeAccess.ts +138 -0
  137. package/src/rbac/resolve.test.ts +358 -0
  138. package/src/rbac/resolve.ts +285 -0
  139. package/src/rbac/roleManager.test.ts +915 -0
  140. package/src/rbac/roleManager.ts +440 -0
  141. package/src/rbac/roleModel.test.ts +114 -0
  142. package/src/rbac/roleModel.ts +196 -0
  143. package/src/rbac/routes.ts +170 -0
  144. package/src/rbac/scopes.test.ts +105 -0
  145. package/src/rbac/scopes.ts +81 -0
  146. package/src/rbac/statements.test.ts +65 -0
  147. package/src/rbac/statements.ts +62 -0
  148. package/src/rbac/types.ts +198 -0
  149. package/src/rbac/userPlugin.test.ts +55 -0
  150. package/src/rbac/userPlugin.ts +25 -0
  151. package/src/realtime/changeStreamWatcher.ts +20 -15
  152. package/src/realtime/realtime.test.ts +25 -1
  153. package/src/realtime/realtimeApp.ts +2 -5
  154. package/src/realtime/registry.ts +15 -0
  155. package/src/scrubAdminFields.test.ts +113 -0
  156. package/src/scrubAdminFields.ts +158 -0
  157. package/src/sync/executors.ts +31 -1
  158. package/src/sync/loadHarness.ts +8 -7
  159. package/src/sync/models.test.ts +262 -0
  160. package/src/sync/registry.ts +15 -0
  161. package/src/sync/routes.ts +25 -11
  162. package/src/sync/scripts/compactTombstones.test.ts +4 -6
  163. package/src/sync/serialize.ts +17 -9
  164. package/src/sync/sync.test.ts +52 -0
  165. package/src/sync/syncRoutes.test.ts +5 -2
  166. package/src/sync/syncSocket.test.ts +28 -0
  167. package/src/terrenoApp.test.ts +100 -0
  168. package/src/terrenoApp.ts +65 -3
  169. package/src/terrenoPlugin.ts +10 -1
  170. package/src/tests/bunSetup.ts +2 -0
  171. package/src/tests/createTestData.ts +5 -1
  172. package/src/tests/models.ts +6 -0
  173. package/src/tests/testHelper.ts +1 -3
  174. package/src/transformers.test.ts +12 -0
  175. package/src/transformers.ts +7 -1
@@ -0,0 +1,915 @@
1
+ import {describe, expect, it} from "bun:test";
2
+ import mongoose, {type Model, model, Schema} from "mongoose";
3
+
4
+ import type {User, UserModel} from "../auth";
5
+ import {setupDb} from "../tests";
6
+ import {createAccess} from "./access";
7
+ import {createRbacAuditModel} from "./auditModel";
8
+ import {createRoleManager} from "./roleManager";
9
+ import {createRbacRoleModel} from "./roleModel";
10
+ import {terrenoStatements} from "./statements";
11
+ import type {PermissionSource} from "./types";
12
+
13
+ const appStatements = {
14
+ ...terrenoStatements,
15
+ todo: ["create", "read", "update", "delete", "list"],
16
+ } as const;
17
+
18
+ interface RbacTestUser extends User {
19
+ email: string;
20
+ roles: string[];
21
+ }
22
+
23
+ const getRbacTestUserModel = (): Model<RbacTestUser> => {
24
+ const modelName = "RbacRoleManagerTestUser";
25
+ if (mongoose.models[modelName]) {
26
+ return mongoose.models[modelName] as Model<RbacTestUser>;
27
+ }
28
+
29
+ const schema = new Schema<RbacTestUser>({
30
+ admin: {default: false, description: "Admin flag", type: Boolean},
31
+ email: {description: "Email", required: true, type: String},
32
+ roles: {default: [], description: "Role names", type: [String]},
33
+ });
34
+
35
+ return model<RbacTestUser>(modelName, schema);
36
+ };
37
+
38
+ const createTestUser = (overrides: Partial<RbacTestUser> = {}): RbacTestUser => {
39
+ const id = new mongoose.Types.ObjectId();
40
+ return {
41
+ _id: id as unknown as User["_id"],
42
+ admin: false,
43
+ email: "actor@example.com",
44
+ id: id.toString(),
45
+ roles: [],
46
+ ...overrides,
47
+ };
48
+ };
49
+
50
+ describe("roleManager", () => {
51
+ it("seeds custom default roles beyond terreno defaults", async () => {
52
+ await setupDb();
53
+ const access = createAccess({
54
+ connection: mongoose.connection,
55
+ defaultRoles: [
56
+ {
57
+ displayName: "Custom Editor",
58
+ name: "custom-editor",
59
+ permissions: {todo: ["read", "update"]},
60
+ },
61
+ ],
62
+ statements: appStatements,
63
+ });
64
+
65
+ await access.roles.seedDefaults();
66
+
67
+ const RbacRole = createRbacRoleModel(mongoose.connection);
68
+ const customRole = await RbacRole.findExactlyOne({name: "custom-editor"});
69
+ expect(customRole.permissions.todo).toEqual(expect.arrayContaining(["read", "update"]));
70
+ });
71
+
72
+ it("does not overwrite customized custom default roles on re-seed", async () => {
73
+ await setupDb();
74
+ const access = createAccess({
75
+ connection: mongoose.connection,
76
+ defaultRoles: [
77
+ {
78
+ displayName: "Custom Editor",
79
+ name: "custom-editor",
80
+ permissions: {todo: ["read", "update"]},
81
+ },
82
+ ],
83
+ statements: appStatements,
84
+ });
85
+
86
+ await access.roles.seedDefaults();
87
+ const RbacRole = createRbacRoleModel(mongoose.connection);
88
+ await RbacRole.updateOne({name: "custom-editor"}, {$set: {permissions: {todo: ["read"]}}});
89
+ await access.roles.seedDefaults();
90
+
91
+ const customRole = await RbacRole.findExactlyOne({name: "custom-editor"});
92
+ expect(customRole.permissions.todo).toEqual(["read"]);
93
+ });
94
+
95
+ it("creates, lists, updates, and removes roles", async () => {
96
+ await setupDb();
97
+ const access = createAccess({
98
+ connection: mongoose.connection,
99
+ statements: appStatements,
100
+ });
101
+ await access.roles.seedDefaults();
102
+
103
+ const actor = createTestUser({roles: ["superadmin"]});
104
+ const created = await access.roles.create({
105
+ actor,
106
+ role: {
107
+ displayName: "Todo Reader",
108
+ name: "todo-reader",
109
+ permissions: {todo: ["read"]},
110
+ },
111
+ });
112
+ expect(created.name).toBe("todo-reader");
113
+
114
+ const roles = await access.roles.list();
115
+ expect(roles.map((role) => role.name)).toContain("todo-reader");
116
+
117
+ const updated = await access.roles.update({
118
+ actor,
119
+ changes: {displayName: "Todo Reader Updated"},
120
+ roleName: "todo-reader",
121
+ });
122
+ expect(updated.displayName).toBe("Todo Reader Updated");
123
+
124
+ const cleared = await access.roles.update({
125
+ actor,
126
+ changes: {description: null},
127
+ roleName: "todo-reader",
128
+ });
129
+ expect(cleared.description == null).toBe(true);
130
+
131
+ await access.roles.remove({actor, roleName: "todo-reader"});
132
+ const remaining = await access.roles.list();
133
+ expect(remaining.map((role) => role.name)).not.toContain("todo-reader");
134
+
135
+ const RbacAudit = createRbacAuditModel(mongoose.connection);
136
+ const createAudit = await RbacAudit.findExactlyOne({
137
+ action: "role.create",
138
+ denied: false,
139
+ targetRoleName: "todo-reader",
140
+ });
141
+ expect(createAudit.permissionDelta?.gained.todo).toEqual(["read"]);
142
+ const updateAudits = await RbacAudit.find({
143
+ action: "role.update",
144
+ denied: false,
145
+ targetRoleName: "todo-reader",
146
+ });
147
+ expect(updateAudits).toHaveLength(2);
148
+ expect(updateAudits.every((entry) => entry.actorId === actor.id)).toBe(true);
149
+ const removeAudit = await RbacAudit.findExactlyOne({
150
+ action: "role.remove",
151
+ denied: false,
152
+ targetRoleName: "todo-reader",
153
+ });
154
+ expect(removeAudit.permissionDelta?.lost.todo).toEqual(["read"]);
155
+ });
156
+
157
+ it("fans successful role writes out to a pluggable audit sink", async () => {
158
+ await setupDb();
159
+ const sinkRecords: Array<{action: string; targetRoleName?: string}> = [];
160
+ const access = createAccess({
161
+ auditSink: async (record) => {
162
+ sinkRecords.push({action: record.action, targetRoleName: record.targetRoleName});
163
+ },
164
+ connection: mongoose.connection,
165
+ statements: appStatements,
166
+ });
167
+ await access.roles.seedDefaults();
168
+
169
+ const actor = createTestUser({roles: ["superadmin"]});
170
+ await access.roles.create({
171
+ actor,
172
+ role: {
173
+ displayName: "Sinked",
174
+ name: "sinked",
175
+ permissions: {todo: ["read"]},
176
+ },
177
+ });
178
+
179
+ const RbacAudit = createRbacAuditModel(mongoose.connection);
180
+ const persisted = await RbacAudit.findExactlyOne({
181
+ action: "role.create",
182
+ targetRoleName: "sinked",
183
+ });
184
+ expect(persisted.denied).toBe(false);
185
+ expect(sinkRecords).toEqual([{action: "role.create", targetRoleName: "sinked"}]);
186
+ });
187
+
188
+ it("can skip the built-in collection when persistAudit is false and a sink is set", async () => {
189
+ await setupDb();
190
+ const sinkRecords: string[] = [];
191
+ const access = createAccess({
192
+ auditSink: async (record) => {
193
+ sinkRecords.push(record.action);
194
+ },
195
+ connection: mongoose.connection,
196
+ persistAudit: false,
197
+ statements: appStatements,
198
+ });
199
+ await access.roles.seedDefaults();
200
+
201
+ const actor = createTestUser({roles: ["superadmin"]});
202
+ await access.roles.create({
203
+ actor,
204
+ role: {
205
+ displayName: "Sink Only",
206
+ name: "sink-only",
207
+ permissions: {todo: ["list"]},
208
+ },
209
+ });
210
+
211
+ expect(sinkRecords).toEqual(["role.create"]);
212
+ const RbacAudit = createRbacAuditModel(mongoose.connection);
213
+ expect(await RbacAudit.countDocuments({targetRoleName: "sink-only"})).toBe(0);
214
+ });
215
+
216
+ it("rejects createAccess when persistAudit is false and no auditSink is provided", () => {
217
+ expect(() =>
218
+ createAccess({
219
+ connection: mongoose.connection,
220
+ persistAudit: false,
221
+ statements: appStatements,
222
+ })
223
+ ).toThrow("RBAC audit requires persistAudit or at least one auditSink");
224
+ });
225
+
226
+ it("assigns and unassigns roles on users", async () => {
227
+ await setupDb();
228
+ const UserModel = getRbacTestUserModel();
229
+ const access = createAccess({
230
+ connection: mongoose.connection,
231
+ defaultRoles: [
232
+ {
233
+ displayName: "Editor",
234
+ name: "editor",
235
+ permissions: {todo: ["read", "update"]},
236
+ },
237
+ ],
238
+ statements: appStatements,
239
+ userModel: UserModel as unknown as UserModel,
240
+ });
241
+ await access.roles.seedDefaults();
242
+
243
+ const actor = createTestUser({roles: ["superadmin"]});
244
+ const target = await UserModel.create({email: "target@example.com", roles: []});
245
+
246
+ await access.roles.assign({
247
+ actor,
248
+ roleNames: ["editor"],
249
+ userId: target.id,
250
+ });
251
+
252
+ const assigned = await UserModel.findById(target.id);
253
+ expect(assigned?.roles).toEqual(["editor"]);
254
+
255
+ await access.roles.unassign({
256
+ actor,
257
+ roleNames: ["editor"],
258
+ userId: target.id,
259
+ });
260
+
261
+ const unassigned = await UserModel.findById(target.id);
262
+ expect(unassigned?.roles).toEqual([]);
263
+
264
+ const RbacAudit = createRbacAuditModel(mongoose.connection);
265
+ const assignAudit = await RbacAudit.findExactlyOne({
266
+ action: "role.assign",
267
+ denied: false,
268
+ targetUserId: target.id,
269
+ });
270
+ expect(assignAudit.permissionDelta?.gained.todo).toEqual(
271
+ expect.arrayContaining(["read", "update"])
272
+ );
273
+ const unassignAudit = await RbacAudit.findExactlyOne({
274
+ action: "role.unassign",
275
+ denied: false,
276
+ targetUserId: target.id,
277
+ });
278
+ expect(unassignAudit.permissionDelta?.lost.todo).toEqual(
279
+ expect.arrayContaining(["read", "update"])
280
+ );
281
+ });
282
+
283
+ it("rejects assign and unassign when the actor lacks the target user's permissions", async () => {
284
+ await setupDb();
285
+ const UserModel = getRbacTestUserModel();
286
+ const access = createAccess({
287
+ connection: mongoose.connection,
288
+ defaultRoles: [
289
+ {
290
+ displayName: "Assigner",
291
+ name: "assigner",
292
+ permissions: {rbac: ["assignRoles"], todo: ["read"]},
293
+ },
294
+ ],
295
+ statements: appStatements,
296
+ userModel: UserModel as unknown as UserModel,
297
+ });
298
+ await access.roles.seedDefaults();
299
+
300
+ const actor = createTestUser({roles: ["assigner"]});
301
+ const privileged = await UserModel.create({
302
+ email: "privileged@example.com",
303
+ roles: ["superadmin"],
304
+ });
305
+ const unprivileged = await UserModel.create({
306
+ email: "unprivileged@example.com",
307
+ roles: [],
308
+ });
309
+
310
+ await expect(
311
+ access.roles.assign({
312
+ actor,
313
+ roleNames: ["member"],
314
+ userId: privileged.id,
315
+ })
316
+ ).rejects.toMatchObject({
317
+ status: 403,
318
+ title: "Cannot modify a user with permissions you do not hold",
319
+ });
320
+ expect((await UserModel.findById(privileged.id))?.roles).toEqual(["superadmin"]);
321
+
322
+ await expect(
323
+ access.roles.unassign({
324
+ actor,
325
+ roleNames: ["superadmin"],
326
+ userId: privileged.id,
327
+ })
328
+ ).rejects.toMatchObject({
329
+ status: 403,
330
+ title: "Cannot modify a user with permissions you do not hold",
331
+ });
332
+ expect((await UserModel.findById(privileged.id))?.roles).toEqual(["superadmin"]);
333
+
334
+ await access.roles.assign({
335
+ actor,
336
+ roleNames: ["member"],
337
+ userId: unprivileged.id,
338
+ });
339
+ expect((await UserModel.findById(unprivileged.id))?.roles).toEqual(["member"]);
340
+ });
341
+
342
+ it("assertCanModifyUser rejects when the actor lacks the target user's permissions", async () => {
343
+ await setupDb();
344
+ const UserModel = getRbacTestUserModel();
345
+ const access = createAccess({
346
+ connection: mongoose.connection,
347
+ defaultRoles: [
348
+ {
349
+ displayName: "Assigner",
350
+ name: "assigner",
351
+ permissions: {rbac: ["assignRoles"], todo: ["read"]},
352
+ },
353
+ ],
354
+ statements: appStatements,
355
+ userModel: UserModel as unknown as UserModel,
356
+ });
357
+ await access.roles.seedDefaults();
358
+
359
+ const actor = createTestUser({roles: ["assigner"]});
360
+ const privileged = await UserModel.create({
361
+ email: "assert-privileged@example.com",
362
+ roles: ["superadmin"],
363
+ });
364
+ const unprivileged = await UserModel.create({
365
+ email: "assert-unprivileged@example.com",
366
+ roles: [],
367
+ });
368
+
369
+ await expect(
370
+ access.roles.assertCanModifyUser({actor, userId: privileged.id})
371
+ ).rejects.toMatchObject({
372
+ status: 403,
373
+ title: "Cannot modify a user with permissions you do not hold",
374
+ });
375
+ await access.roles.assertCanModifyUser({actor, userId: unprivileged.id});
376
+ });
377
+
378
+ it("previews assignment and role permission changes", async () => {
379
+ await setupDb();
380
+ const UserModel = getRbacTestUserModel();
381
+ const access = createAccess({
382
+ connection: mongoose.connection,
383
+ defaultRoles: [
384
+ {
385
+ displayName: "Reader",
386
+ name: "reader",
387
+ permissions: {todo: ["read"]},
388
+ },
389
+ {
390
+ displayName: "Writer",
391
+ name: "writer",
392
+ permissions: {todo: ["update"]},
393
+ },
394
+ ],
395
+ statements: appStatements,
396
+ userModel: UserModel as unknown as UserModel,
397
+ });
398
+ await access.roles.seedDefaults();
399
+
400
+ const target = await UserModel.create({email: "preview@example.com", roles: ["reader"]});
401
+ const actor = createTestUser({roles: ["superadmin"]});
402
+ const assignmentPreview = await access.roles.previewAssignment({
403
+ actor,
404
+ roleNames: ["reader", "writer"],
405
+ userId: target.id,
406
+ });
407
+ expect(assignmentPreview.gained.todo).toEqual(expect.arrayContaining(["update"]));
408
+ expect(assignmentPreview.resulting.todo).toEqual(expect.arrayContaining(["read", "update"]));
409
+
410
+ const rolePreview = await access.roles.previewRoleChange({
411
+ permissions: {todo: ["read", "list"]},
412
+ roleName: "reader",
413
+ });
414
+ expect(rolePreview.gained.todo).toEqual(expect.arrayContaining(["list"]));
415
+ expect(rolePreview.affectedUserCount).toBe(1);
416
+ });
417
+
418
+ it("rejects previewing roles whose permissions the actor does not hold", async () => {
419
+ await setupDb();
420
+ const UserModel = getRbacTestUserModel();
421
+ const access = createAccess({
422
+ connection: mongoose.connection,
423
+ defaultRoles: [
424
+ {
425
+ displayName: "Assigner",
426
+ name: "assigner",
427
+ permissions: {rbac: ["assignRoles"], todo: ["read"]},
428
+ },
429
+ ],
430
+ statements: appStatements,
431
+ userModel: UserModel as unknown as UserModel,
432
+ });
433
+ await access.roles.seedDefaults();
434
+
435
+ const actor = createTestUser({roles: ["assigner"]});
436
+ const target = await UserModel.create({email: "preview-escalation@example.com", roles: []});
437
+
438
+ await expect(
439
+ access.roles.previewAssignment({
440
+ actor,
441
+ roleNames: ["superadmin"],
442
+ userId: target.id,
443
+ })
444
+ ).rejects.toMatchObject({
445
+ status: 403,
446
+ title: "Cannot grant permissions you do not hold",
447
+ });
448
+
449
+ const RbacAudit = createRbacAuditModel(mongoose.connection);
450
+ const deniedAssigns = await RbacAudit.find({action: "role.assign", denied: true});
451
+ expect(deniedAssigns).toHaveLength(0);
452
+ });
453
+
454
+ it("rejects role management without manageRoles permission", async () => {
455
+ await setupDb();
456
+ const access = createAccess({
457
+ connection: mongoose.connection,
458
+ statements: appStatements,
459
+ });
460
+ await access.roles.seedDefaults();
461
+
462
+ const actor = createTestUser({roles: ["member"]});
463
+ await expect(
464
+ access.roles.create({
465
+ actor,
466
+ role: {
467
+ displayName: "Blocked",
468
+ name: "blocked",
469
+ permissions: {todo: ["read"]},
470
+ },
471
+ })
472
+ ).rejects.toMatchObject({status: 403, title: "Missing rbac:manageRoles permission"});
473
+ });
474
+
475
+ it("rejects assignment without assignRoles permission", async () => {
476
+ await setupDb();
477
+ const UserModel = getRbacTestUserModel();
478
+ const access = createAccess({
479
+ connection: mongoose.connection,
480
+ statements: appStatements,
481
+ userModel: UserModel as unknown as UserModel,
482
+ });
483
+ await access.roles.seedDefaults();
484
+
485
+ const actor = createTestUser({roles: ["auditor"]});
486
+ const target = await UserModel.create({email: "noassign@example.com", roles: []});
487
+
488
+ await expect(
489
+ access.roles.assign({
490
+ actor,
491
+ roleNames: ["member"],
492
+ userId: target.id,
493
+ })
494
+ ).rejects.toMatchObject({status: 403, title: "Missing rbac:assignRoles permission"});
495
+ });
496
+
497
+ it("rejects permission escalation when creating roles", async () => {
498
+ await setupDb();
499
+ const access = createAccess({
500
+ connection: mongoose.connection,
501
+ defaultRoles: [
502
+ {
503
+ displayName: "Role Manager",
504
+ name: "role-manager",
505
+ permissions: {rbac: ["manageRoles", "assignRoles"], todo: ["read"]},
506
+ },
507
+ ],
508
+ statements: appStatements,
509
+ });
510
+ await access.roles.seedDefaults();
511
+
512
+ const actor = createTestUser({roles: ["role-manager"]});
513
+ await expect(
514
+ access.roles.create({
515
+ actor,
516
+ role: {
517
+ displayName: "Escalated",
518
+ name: "escalated",
519
+ permissions: {todo: ["delete"]},
520
+ },
521
+ })
522
+ ).rejects.toMatchObject({status: 403, title: "Cannot grant permissions you do not hold"});
523
+
524
+ const RbacAudit = createRbacAuditModel(mongoose.connection);
525
+ const denied = await RbacAudit.find({action: "role.create", denied: true});
526
+ expect(denied).toHaveLength(1);
527
+ expect(denied[0]?.actorId).toBe(actor.id);
528
+ expect(denied[0]?.permissionDelta?.gained.todo).toEqual(["delete"]);
529
+ });
530
+
531
+ it("rejects emptying or deleting a role whose permissions the actor does not hold", async () => {
532
+ await setupDb();
533
+ const access = createAccess({
534
+ connection: mongoose.connection,
535
+ defaultRoles: [
536
+ {
537
+ displayName: "Role Manager",
538
+ name: "role-manager",
539
+ permissions: {rbac: ["manageRoles"], todo: ["read"]},
540
+ },
541
+ ],
542
+ statements: appStatements,
543
+ });
544
+ await access.roles.seedDefaults();
545
+
546
+ const superadmin = createTestUser({roles: ["superadmin"]});
547
+ await access.roles.create({
548
+ actor: superadmin,
549
+ role: {
550
+ displayName: "Writer",
551
+ name: "writer",
552
+ permissions: {todo: ["update"]},
553
+ },
554
+ });
555
+
556
+ const actor = createTestUser({email: "manager@example.com", roles: ["role-manager"]});
557
+ await expect(
558
+ access.roles.update({
559
+ actor,
560
+ changes: {permissions: {}},
561
+ roleName: "writer",
562
+ })
563
+ ).rejects.toMatchObject({status: 403, title: "Cannot grant permissions you do not hold"});
564
+
565
+ await expect(access.roles.remove({actor, roleName: "writer"})).rejects.toMatchObject({
566
+ status: 403,
567
+ title: "Cannot grant permissions you do not hold",
568
+ });
569
+
570
+ const RbacRole = createRbacRoleModel(mongoose.connection);
571
+ const writer = await RbacRole.findExactlyOne({name: "writer"});
572
+ expect(writer.permissions.todo).toEqual(["update"]);
573
+ });
574
+
575
+ it("rejects invalid permission sets", async () => {
576
+ await setupDb();
577
+ const access = createAccess({
578
+ connection: mongoose.connection,
579
+ statements: appStatements,
580
+ });
581
+ await access.roles.seedDefaults();
582
+
583
+ const actor = createTestUser({roles: ["superadmin"]});
584
+ await expect(
585
+ access.roles.create({
586
+ actor,
587
+ role: {
588
+ displayName: "Invalid",
589
+ name: "invalid",
590
+ permissions: {unknown: ["read"]},
591
+ },
592
+ })
593
+ ).rejects.toMatchObject({status: 400, title: "Invalid permissions"});
594
+ });
595
+
596
+ it("does not leave previewed assignment grants in the live permission cache", async () => {
597
+ await setupDb();
598
+ const UserModel = getRbacTestUserModel();
599
+ const access = createAccess({
600
+ connection: mongoose.connection,
601
+ defaultRoles: [
602
+ {
603
+ displayName: "Reader",
604
+ name: "reader",
605
+ permissions: {todo: ["read"]},
606
+ },
607
+ {
608
+ displayName: "Writer",
609
+ name: "writer",
610
+ permissions: {todo: ["update"]},
611
+ },
612
+ ],
613
+ statements: appStatements,
614
+ userModel: UserModel as unknown as UserModel,
615
+ });
616
+ await access.roles.seedDefaults();
617
+
618
+ const target = await UserModel.create({email: "cache-preview@example.com", roles: ["reader"]});
619
+ const actor = createTestUser({roles: ["superadmin"]});
620
+ await access.roles.previewAssignment({
621
+ actor,
622
+ roleNames: ["reader", "writer"],
623
+ userId: target.id,
624
+ });
625
+
626
+ const live = await access.can({
627
+ permissions: {todo: ["update"]},
628
+ user: target as unknown as User,
629
+ });
630
+ expect(live.allowed).toBe(false);
631
+ });
632
+
633
+ it("diffs preview assignment against uncached current grants", async () => {
634
+ await setupDb();
635
+ const UserModel = getRbacTestUserModel();
636
+ let shouldFail = false;
637
+ const source: PermissionSource = {
638
+ getGrants: async () => {
639
+ if (shouldFail) {
640
+ throw new Error("source unavailable");
641
+ }
642
+ return {permissions: {todo: ["list"]}};
643
+ },
644
+ name: "preview-source",
645
+ staleOnFailure: "use-stale",
646
+ };
647
+ const access = createAccess({
648
+ connection: mongoose.connection,
649
+ defaultRoles: [
650
+ {
651
+ displayName: "Reader",
652
+ name: "reader",
653
+ permissions: {todo: ["read"]},
654
+ },
655
+ {
656
+ displayName: "Writer",
657
+ name: "writer",
658
+ permissions: {todo: ["update"]},
659
+ },
660
+ ],
661
+ sources: [source],
662
+ statements: appStatements,
663
+ userModel: UserModel as unknown as UserModel,
664
+ });
665
+ await access.roles.seedDefaults();
666
+
667
+ const target = await UserModel.create({
668
+ email: "preview-source@example.com",
669
+ roles: ["reader"],
670
+ });
671
+ const warmed = await access.can({
672
+ permissions: {todo: ["list"]},
673
+ user: target as unknown as User,
674
+ });
675
+ expect(warmed.allowed).toBe(true);
676
+
677
+ shouldFail = true;
678
+ const assignmentPreview = await access.roles.previewAssignment({
679
+ actor: createTestUser({roles: ["superadmin"]}),
680
+ roleNames: ["reader", "writer"],
681
+ userId: target.id,
682
+ });
683
+
684
+ expect(assignmentPreview.lost.todo ?? []).not.toEqual(expect.arrayContaining(["list"]));
685
+ expect(assignmentPreview.gained.todo).toEqual(expect.arrayContaining(["update"]));
686
+ expect(assignmentPreview.resulting.todo).toEqual(
687
+ expect.arrayContaining(["list", "read", "update"])
688
+ );
689
+
690
+ const live = await access.can({
691
+ permissions: {todo: ["update"]},
692
+ user: target as unknown as User,
693
+ });
694
+ expect(live.allowed).toBe(false);
695
+ });
696
+
697
+ it("rejects conflicting role assignments", async () => {
698
+ await setupDb();
699
+ const UserModel = getRbacTestUserModel();
700
+ const access = createAccess({
701
+ connection: mongoose.connection,
702
+ defaultRoles: [
703
+ {
704
+ displayName: "Role A",
705
+ excludesRoles: ["role-b"],
706
+ name: "role-a",
707
+ permissions: {todo: ["read"]},
708
+ },
709
+ {
710
+ displayName: "Role B",
711
+ name: "role-b",
712
+ permissions: {todo: ["update"]},
713
+ },
714
+ ],
715
+ statements: appStatements,
716
+ userModel: UserModel as unknown as UserModel,
717
+ });
718
+ await access.roles.seedDefaults();
719
+
720
+ const actor = createTestUser({roles: ["superadmin"]});
721
+ const target = await UserModel.create({email: "conflict@example.com", roles: []});
722
+
723
+ await expect(
724
+ access.roles.assign({
725
+ actor,
726
+ roleNames: ["role-a", "role-b"],
727
+ userId: target.id,
728
+ })
729
+ ).rejects.toMatchObject({
730
+ status: 409,
731
+ title: "Role role-a conflicts with role-b",
732
+ });
733
+ });
734
+
735
+ it("rejects locked role deletion and sealed role updates", async () => {
736
+ await setupDb();
737
+ const access = createAccess({
738
+ connection: mongoose.connection,
739
+ statements: appStatements,
740
+ });
741
+ await access.roles.seedDefaults();
742
+
743
+ const actor = createTestUser({roles: ["superadmin"]});
744
+ await expect(access.roles.remove({actor, roleName: "admin"})).rejects.toMatchObject({
745
+ status: 400,
746
+ title: "Cannot delete a locked role",
747
+ });
748
+
749
+ await expect(
750
+ access.roles.update({
751
+ actor,
752
+ changes: {displayName: "Changed"},
753
+ roleName: "superadmin",
754
+ })
755
+ ).rejects.toMatchObject({status: 400, title: "Cannot modify a sealed role"});
756
+ });
757
+
758
+ it("rejects renaming locked roles", async () => {
759
+ await setupDb();
760
+ const access = createAccess({
761
+ connection: mongoose.connection,
762
+ statements: appStatements,
763
+ });
764
+ await access.roles.seedDefaults();
765
+
766
+ const actor = createTestUser({roles: ["superadmin"]});
767
+ await expect(
768
+ access.roles.update({
769
+ actor,
770
+ changes: {name: "renamed-admin"},
771
+ roleName: "admin",
772
+ })
773
+ ).rejects.toMatchObject({status: 400, title: "Cannot rename a locked role"});
774
+ });
775
+
776
+ it("requires a configured user model for assignment operations", async () => {
777
+ await setupDb();
778
+ const access = createAccess({
779
+ connection: mongoose.connection,
780
+ statements: appStatements,
781
+ });
782
+ await access.roles.seedDefaults();
783
+
784
+ const actor = createTestUser({roles: ["superadmin"]});
785
+ const userId = new mongoose.Types.ObjectId().toString();
786
+
787
+ await expect(access.roles.assign({actor, roleNames: ["member"], userId})).rejects.toMatchObject(
788
+ {status: 500, title: "User model not configured for role assignment"}
789
+ );
790
+
791
+ await expect(
792
+ access.roles.previewAssignment({actor, roleNames: ["member"], userId})
793
+ ).rejects.toMatchObject({status: 500, title: "User model not configured for role assignment"});
794
+ });
795
+
796
+ it("returns 404 when the target user does not exist", async () => {
797
+ await setupDb();
798
+ const UserModel = getRbacTestUserModel();
799
+ const access = createAccess({
800
+ connection: mongoose.connection,
801
+ statements: appStatements,
802
+ userModel: UserModel as unknown as UserModel,
803
+ });
804
+ await access.roles.seedDefaults();
805
+
806
+ const actor = createTestUser({roles: ["superadmin"]});
807
+ const missingId = new mongoose.Types.ObjectId().toString();
808
+
809
+ await expect(
810
+ access.roles.assign({actor, roleNames: ["member"], userId: missingId})
811
+ ).rejects.toMatchObject({status: 404, title: "User not found"});
812
+ });
813
+
814
+ it("rejects assignment when the user model cannot save", async () => {
815
+ await setupDb();
816
+ const UserModel = getRbacTestUserModel();
817
+ const access = createAccess({
818
+ connection: mongoose.connection,
819
+ statements: appStatements,
820
+ userModel: UserModel as unknown as UserModel,
821
+ });
822
+ await access.roles.seedDefaults();
823
+
824
+ const actor = createTestUser({roles: ["superadmin"]});
825
+ const targetId = new mongoose.Types.ObjectId();
826
+ const originalFindById = UserModel.findById.bind(UserModel);
827
+ UserModel.findById = (async () => ({
828
+ id: targetId.toString(),
829
+ roles: [],
830
+ })) as unknown as typeof UserModel.findById;
831
+
832
+ try {
833
+ await expect(
834
+ access.roles.assign({
835
+ actor,
836
+ roleNames: ["member"],
837
+ userId: targetId.toString(),
838
+ })
839
+ ).rejects.toMatchObject({
840
+ status: 500,
841
+ title: "User model does not support saving role assignments",
842
+ });
843
+ } finally {
844
+ UserModel.findById = originalFindById;
845
+ }
846
+ });
847
+
848
+ it("does not record denied audits for non-escalation role-lookup failures", async () => {
849
+ await setupDb();
850
+ await createRbacRoleModel(mongoose.connection).seedDefaults({statements: appStatements});
851
+
852
+ const actor = createTestUser({roles: ["superadmin"]});
853
+ let actorCalls = 0;
854
+ const {roleManager} = createRoleManager({
855
+ connection: mongoose.connection,
856
+ getActorPermissions: async () => {
857
+ actorCalls += 1;
858
+ if (actorCalls === 1) {
859
+ return {rbac: ["manageRoles"], todo: ["read"]};
860
+ }
861
+ throw new Error("role lookup failed");
862
+ },
863
+ getPreviewPermissions: async () => ({}),
864
+ invalidateCache: () => undefined,
865
+ statements: appStatements,
866
+ });
867
+
868
+ await expect(
869
+ roleManager.create({
870
+ actor,
871
+ role: {
872
+ displayName: "Lookup Fail",
873
+ name: "lookup-fail",
874
+ permissions: {todo: ["read"]},
875
+ },
876
+ })
877
+ ).rejects.toThrow("role lookup failed");
878
+
879
+ const denied = await createRbacAuditModel(mongoose.connection).find({denied: true});
880
+ expect(denied).toHaveLength(0);
881
+ });
882
+
883
+ it("keeps the original escalation error when denied-audit persistence fails", async () => {
884
+ await setupDb();
885
+ await createRbacRoleModel(mongoose.connection).seedDefaults({statements: appStatements});
886
+
887
+ const actor = createTestUser({roles: ["role-manager"]});
888
+ const {roleManager} = createRoleManager({
889
+ auditSinks: [
890
+ async () => {
891
+ throw new Error("audit sink down");
892
+ },
893
+ ],
894
+ connection: mongoose.connection,
895
+ getActorPermissions: async () => ({rbac: ["manageRoles"], todo: ["read"]}),
896
+ getPreviewPermissions: async () => ({}),
897
+ invalidateCache: () => undefined,
898
+ statements: appStatements,
899
+ });
900
+
901
+ await expect(
902
+ roleManager.create({
903
+ actor,
904
+ role: {
905
+ displayName: "Escalated",
906
+ name: "escalated-audit-fail",
907
+ permissions: {todo: ["delete"]},
908
+ },
909
+ })
910
+ ).rejects.toMatchObject({
911
+ status: 403,
912
+ title: "Cannot grant permissions you do not hold",
913
+ });
914
+ });
915
+ });