@terreno/api 57.16.2 → 57.18.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 (184) hide show
  1. package/dist/actions.d.ts +26 -3
  2. package/dist/actions.js +102 -16
  3. package/dist/api.d.ts +7 -0
  4. package/dist/api.js +59 -3
  5. package/dist/auth.d.ts +28 -4
  6. package/dist/auth.js +140 -15
  7. package/dist/authRecovery.d.ts +31 -0
  8. package/dist/authRecovery.js +86 -6
  9. package/dist/betterAuth.d.ts +86 -0
  10. package/dist/betterAuthApp.d.ts +17 -0
  11. package/dist/betterAuthApp.js +12 -1
  12. package/dist/betterAuthOAuthHandoff.d.ts +24 -0
  13. package/dist/betterAuthOAuthHandoff.js +305 -0
  14. package/dist/betterAuthSetup.d.ts +37 -2
  15. package/dist/betterAuthSetup.js +304 -24
  16. package/dist/expressServer.d.ts +16 -0
  17. package/dist/expressServer.js +61 -14
  18. package/dist/githubAuth.d.ts +9 -0
  19. package/dist/githubAuth.js +230 -31
  20. package/dist/index.d.ts +9 -1
  21. package/dist/index.js +27 -3
  22. package/dist/mcp/actionTools.d.ts +4 -0
  23. package/dist/mcp/actionTools.js +158 -0
  24. package/dist/mcp/auth.d.ts +30 -0
  25. package/dist/mcp/auth.js +83 -28
  26. package/dist/mcp/createMCPRequest.d.ts +5 -1
  27. package/dist/mcp/createMCPRequest.js +3 -3
  28. package/dist/mcp/handlers.d.ts +3 -0
  29. package/dist/mcp/handlers.js +43 -27
  30. package/dist/mcp/oauth.d.ts +14 -0
  31. package/dist/mcp/oauth.js +618 -0
  32. package/dist/mcp/oauthMetadata.d.ts +89 -0
  33. package/dist/mcp/oauthMetadata.js +137 -0
  34. package/dist/mcp/registry.d.ts +5 -0
  35. package/dist/mcp/registry.js +9 -1
  36. package/dist/mcp/server.d.ts +6 -0
  37. package/dist/mcp/server.js +44 -7
  38. package/dist/mcp/serviceTokens.js +12 -2
  39. package/dist/mcp/toolExecution.d.ts +12 -0
  40. package/dist/mcp/toolExecution.js +60 -0
  41. package/dist/mcp/toolGenerator.d.ts +4 -1
  42. package/dist/mcp/toolGenerator.js +26 -60
  43. package/dist/mcp/types.d.ts +4 -4
  44. package/dist/models/mcpOAuthAuthorization.d.ts +2 -0
  45. package/dist/models/mcpOAuthAuthorization.js +86 -0
  46. package/dist/models/mcpOAuthClient.d.ts +2 -0
  47. package/dist/models/mcpOAuthClient.js +42 -0
  48. package/dist/models/mcpOAuthRevokedFamily.d.ts +2 -0
  49. package/dist/models/mcpOAuthRevokedFamily.js +36 -0
  50. package/dist/models/mcpOAuthToken.d.ts +12 -0
  51. package/dist/models/mcpOAuthToken.js +159 -0
  52. package/dist/models/mcpServiceToken.d.ts +1 -0
  53. package/dist/models/mcpServiceToken.js +21 -4
  54. package/dist/permissions.d.ts +7 -0
  55. package/dist/permissions.js +18 -1
  56. package/dist/rateLimit/policies.d.ts +4 -0
  57. package/dist/rateLimit/policies.js +46 -7
  58. package/dist/rbac/access.js +1 -0
  59. package/dist/rbac/membershipOrgAdminSource.d.ts +4 -0
  60. package/dist/rbac/membershipOrgAdminSource.js +5 -0
  61. package/dist/rbac/modelRouterAccess.d.ts +7 -1
  62. package/dist/rbac/modelRouterAccess.js +37 -24
  63. package/dist/rbac/realtimeAccess.js +17 -3
  64. package/dist/rbac/resolve.js +66 -9
  65. package/dist/rbac/roleManager.js +60 -5
  66. package/dist/rbac/roleModel.js +1 -1
  67. package/dist/rbac/statements.d.ts +1 -1
  68. package/dist/rbac/statements.js +13 -1
  69. package/dist/rbac/types.d.ts +12 -0
  70. package/dist/rbac/userWriteGuards.d.ts +50 -0
  71. package/dist/rbac/userWriteGuards.js +156 -0
  72. package/dist/realtime/changeStreamWatcher.d.ts +4 -1
  73. package/dist/realtime/changeStreamWatcher.js +157 -73
  74. package/dist/realtime/queryMatcher.d.ts +3 -0
  75. package/dist/realtime/queryMatcher.js +25 -10
  76. package/dist/realtime/realtimeApp.d.ts +16 -1
  77. package/dist/realtime/realtimeApp.js +76 -8
  78. package/dist/realtime/socketAuth.d.ts +17 -6
  79. package/dist/realtime/socketAuth.js +77 -16
  80. package/dist/realtime/types.d.ts +8 -5
  81. package/dist/requestContext.d.ts +22 -0
  82. package/dist/requestContext.js +22 -1
  83. package/dist/seedRunner.js +3 -1
  84. package/dist/sortFields.d.ts +33 -0
  85. package/dist/sortFields.js +55 -0
  86. package/dist/sync/executors.js +140 -2
  87. package/dist/sync/models.d.ts +2 -0
  88. package/dist/sync/models.js +5 -0
  89. package/dist/sync/mutationHandler.js +70 -7
  90. package/dist/sync/routes.js +4 -2
  91. package/dist/sync/syncSeqPlugin.js +6 -5
  92. package/dist/terrenoApp.d.ts +14 -0
  93. package/dist/terrenoApp.js +21 -6
  94. package/dist/types/mcpOAuth.d.ts +101 -0
  95. package/dist/types/mcpOAuth.js +2 -0
  96. package/dist/types/mcpServiceToken.d.ts +8 -0
  97. package/package.json +3 -3
  98. package/src/actions.test.ts +118 -0
  99. package/src/actions.ts +139 -17
  100. package/src/api.arrayOperations.test.ts +78 -0
  101. package/src/api.test.ts +36 -0
  102. package/src/api.ts +76 -4
  103. package/src/auth.test.ts +521 -3
  104. package/src/auth.ts +171 -17
  105. package/src/authRecovery.test.ts +99 -0
  106. package/src/authRecovery.ts +117 -5
  107. package/src/authVerification.test.ts +3 -3
  108. package/src/betterAuth.ts +104 -1
  109. package/src/betterAuthApp.test.ts +634 -1
  110. package/src/betterAuthApp.ts +28 -0
  111. package/src/betterAuthOAuthHandoff.test.ts +946 -0
  112. package/src/betterAuthOAuthHandoff.ts +375 -0
  113. package/src/betterAuthSetup.test.ts +393 -4
  114. package/src/betterAuthSetup.ts +402 -29
  115. package/src/expressServer.test.ts +93 -0
  116. package/src/expressServer.ts +81 -14
  117. package/src/githubAuth.test.ts +448 -6
  118. package/src/githubAuth.ts +276 -34
  119. package/src/index.ts +35 -1
  120. package/src/mcp/actionTools.test.ts +498 -0
  121. package/src/mcp/actionTools.ts +220 -0
  122. package/src/mcp/auth.test.ts +114 -1
  123. package/src/mcp/auth.ts +122 -35
  124. package/src/mcp/createMCPRequest.ts +8 -2
  125. package/src/mcp/handlers.test.ts +27 -0
  126. package/src/mcp/handlers.ts +21 -6
  127. package/src/mcp/oauth.test.ts +1026 -0
  128. package/src/mcp/oauth.ts +798 -0
  129. package/src/mcp/oauthMetadata.ts +234 -0
  130. package/src/mcp/registry.ts +11 -0
  131. package/src/mcp/server.ts +54 -14
  132. package/src/mcp/serviceTokens.ts +16 -3
  133. package/src/mcp/toolExecution.ts +67 -0
  134. package/src/mcp/toolGenerator.ts +27 -83
  135. package/src/mcp/types.ts +4 -4
  136. package/src/models/mcpOAuthAuthorization.ts +97 -0
  137. package/src/models/mcpOAuthClient.ts +49 -0
  138. package/src/models/mcpOAuthRevokedFamily.ts +47 -0
  139. package/src/models/mcpOAuthToken.test.ts +82 -0
  140. package/src/models/mcpOAuthToken.ts +195 -0
  141. package/src/models/mcpServiceToken.ts +26 -2
  142. package/src/permissions.ts +17 -0
  143. package/src/rateLimit/policies.ts +54 -10
  144. package/src/rateLimit/rateLimit.test.ts +41 -0
  145. package/src/rbac/access.ts +1 -0
  146. package/src/rbac/membershipOrgAdminSource.ts +5 -0
  147. package/src/rbac/modelRouterAccess.ts +40 -23
  148. package/src/rbac/realtimeAccess.test.ts +43 -0
  149. package/src/rbac/realtimeAccess.ts +23 -3
  150. package/src/rbac/resolve.test.ts +179 -1
  151. package/src/rbac/resolve.ts +78 -9
  152. package/src/rbac/roleManager.test.ts +132 -0
  153. package/src/rbac/roleManager.ts +69 -5
  154. package/src/rbac/roleModel.ts +1 -1
  155. package/src/rbac/statements.ts +14 -1
  156. package/src/rbac/types.ts +12 -0
  157. package/src/rbac/userWriteGuards.test.ts +407 -0
  158. package/src/rbac/userWriteGuards.ts +185 -0
  159. package/src/realtime/changeStreamWatcher.ts +203 -75
  160. package/src/realtime/queryMatcher.ts +30 -13
  161. package/src/realtime/realtime.test.ts +132 -0
  162. package/src/realtime/realtimeApp.ts +94 -10
  163. package/src/realtime/realtimeAppSetup.test.ts +282 -1
  164. package/src/realtime/socketAuth.test.ts +140 -8
  165. package/src/realtime/socketAuth.ts +90 -19
  166. package/src/realtime/types.ts +8 -5
  167. package/src/requestContext.ts +52 -1
  168. package/src/requestCredential.test.ts +89 -0
  169. package/src/seedRunner.test.ts +21 -0
  170. package/src/seedRunner.ts +3 -1
  171. package/src/sortFields.ts +69 -0
  172. package/src/sync/executors.test.ts +382 -3
  173. package/src/sync/executors.ts +179 -4
  174. package/src/sync/models.ts +8 -0
  175. package/src/sync/mutationHandler.test.ts +166 -2
  176. package/src/sync/mutationHandler.ts +97 -5
  177. package/src/sync/routes.ts +4 -2
  178. package/src/sync/syncFrontier.test.ts +11 -0
  179. package/src/sync/syncPhaseC.test.ts +18 -0
  180. package/src/sync/syncSeqPlugin.ts +6 -5
  181. package/src/sync/syncSocket.test.ts +92 -0
  182. package/src/terrenoApp.ts +36 -21
  183. package/src/types/mcpOAuth.ts +129 -0
  184. package/src/types/mcpServiceToken.ts +6 -1
@@ -635,6 +635,7 @@ describe("roleManager", () => {
635
635
  const UserModel = getRbacTestUserModel();
636
636
  let shouldFail = false;
637
637
  const source: PermissionSource = {
638
+ failClosedWhenDenyUnknown: false,
638
639
  getGrants: async () => {
639
640
  if (shouldFail) {
640
641
  throw new Error("source unavailable");
@@ -773,6 +774,137 @@ describe("roleManager", () => {
773
774
  ).rejects.toMatchObject({status: 400, title: "Cannot rename a locked role"});
774
775
  });
775
776
 
777
+ it("rejects non-object permissions on a role update without changing the role", async () => {
778
+ await setupDb();
779
+ const access = createAccess({
780
+ connection: mongoose.connection,
781
+ defaultRoles: [
782
+ {
783
+ displayName: "Role manager",
784
+ name: "role-manager",
785
+ permissions: {rbac: ["read", "manageRoles"], todo: ["read"]},
786
+ },
787
+ ],
788
+ statements: appStatements,
789
+ });
790
+ await access.roles.seedDefaults();
791
+ const RbacRole = createRbacRoleModel(mongoose.connection);
792
+ const before = (await RbacRole.findExactlyOne({name: "admin"})).permissions;
793
+ const manager = createTestUser({roles: ["role-manager"]});
794
+ const superadmin = createTestUser({roles: ["superadmin"]});
795
+
796
+ for (const actor of [manager, superadmin]) {
797
+ for (const permissions of [false, 0, "", null, ["todo"]]) {
798
+ await expect(
799
+ access.roles.update({
800
+ actor,
801
+ changes: {permissions: permissions as never},
802
+ roleName: "admin",
803
+ })
804
+ ).rejects.toMatchObject({status: 400, title: "Invalid permissions"});
805
+ }
806
+ }
807
+ await expect(
808
+ access.roles.update({actor: manager, changes: {permissions: {}}, roleName: "admin"})
809
+ ).rejects.toMatchObject({status: 403});
810
+
811
+ const after = (await RbacRole.findExactlyOne({name: "admin"})).permissions;
812
+ expect(after).toEqual(before);
813
+ });
814
+
815
+ describe("role renames", () => {
816
+ const setup = async () => {
817
+ await setupDb();
818
+ const UserModel = getRbacTestUserModel();
819
+ await UserModel.deleteMany({});
820
+ const access = createAccess({
821
+ connection: mongoose.connection,
822
+ defaultRoles: [
823
+ {
824
+ displayName: "Delegate",
825
+ name: "delegate",
826
+ permissions: {rbac: ["read", "manageRoles"], todo: ["read"]},
827
+ },
828
+ {displayName: "Viewer", name: "viewer", permissions: {todo: ["list"]}},
829
+ {
830
+ displayName: "Clinician",
831
+ name: "clinician",
832
+ permissions: {todo: ["update", "delete"]},
833
+ },
834
+ ],
835
+ statements: appStatements,
836
+ userModel: UserModel as unknown as UserModel,
837
+ });
838
+ await access.roles.seedDefaults();
839
+ const actor = (await UserModel.create({
840
+ email: "rename-delegate@example.com",
841
+ roles: ["delegate", "viewer"],
842
+ })) as unknown as RbacTestUser;
843
+ const clinician = await UserModel.create({
844
+ email: "rename-clinician@example.com",
845
+ roles: ["clinician"],
846
+ });
847
+ return {access, actor, clinician, UserModel};
848
+ };
849
+
850
+ it("does not let a manageRoles holder rename a stronger role onto a name it holds", async () => {
851
+ const {access, actor, UserModel} = await setup();
852
+
853
+ await access.roles.update({actor, changes: {name: "viewer-parked"}, roleName: "viewer"});
854
+ const reloadedActor = (await UserModel.findById(actor._id).orFail()) as unknown as User;
855
+ await expect(
856
+ access.roles.update({
857
+ actor: reloadedActor,
858
+ changes: {name: "viewer"},
859
+ roleName: "clinician",
860
+ })
861
+ ).rejects.toMatchObject({status: 403, title: "Cannot grant permissions you do not hold"});
862
+
863
+ const permissions = await access.getPermissions({
864
+ user: (await UserModel.findById(actor._id).orFail()) as unknown as User,
865
+ });
866
+ expect(permissions.todo ?? []).not.toContain("delete");
867
+ expect(permissions.todo ?? []).toContain("list");
868
+ });
869
+
870
+ it("moves holders to the new name so their grants do not change", async () => {
871
+ const {access, clinician, UserModel} = await setup();
872
+ const superadmin = createTestUser({roles: ["superadmin"]});
873
+
874
+ await access.roles.update({
875
+ actor: superadmin,
876
+ changes: {name: "care-clinician"},
877
+ roleName: "clinician",
878
+ });
879
+
880
+ const reloaded = await UserModel.findById(clinician._id).orFail();
881
+ expect(reloaded.roles).toEqual(["care-clinician"]);
882
+ const permissions = await access.getPermissions({user: reloaded as unknown as User});
883
+ expect(permissions.todo).toEqual(expect.arrayContaining(["update", "delete"]));
884
+ });
885
+
886
+ it("rejects a rename onto a name users already hold", async () => {
887
+ const {access, UserModel} = await setup();
888
+ const superadmin = createTestUser({roles: ["superadmin"]});
889
+ await UserModel.create({email: "stale-holder@example.com", roles: ["retired-role"]});
890
+
891
+ await expect(
892
+ access.roles.update({
893
+ actor: superadmin,
894
+ changes: {name: "retired-role"},
895
+ roleName: "clinician",
896
+ })
897
+ ).rejects.toMatchObject({status: 409});
898
+ await expect(
899
+ access.roles.update({
900
+ actor: superadmin,
901
+ changes: {name: "viewer"},
902
+ roleName: "clinician",
903
+ })
904
+ ).rejects.toMatchObject({status: 409});
905
+ });
906
+ });
907
+
776
908
  it("requires a configured user model for assignment operations", async () => {
777
909
  await setupDb();
778
910
  const access = createAccess({
@@ -180,6 +180,56 @@ export const createRoleManager = (args: {
180
180
  }
181
181
  };
182
182
 
183
+ // Users hold roles by name, so a rename changes who holds which permissions. Treat it like a
184
+ // permission edit: the actor must hold the role's grants, and the new name must not already
185
+ // bind any user or role (a stale `user.roles` entry would otherwise inherit the grants).
186
+ const assertRenameAllowed = async (args: {
187
+ actor: User;
188
+ existing: RbacRoleDocument;
189
+ newName: unknown;
190
+ roleName: string;
191
+ }): Promise<void> => {
192
+ const {actor, existing, newName, roleName} = args;
193
+ if (existing.isLocked) {
194
+ throw new APIError({status: 400, title: "Cannot rename a locked role"});
195
+ }
196
+ if (typeof newName !== "string" || newName.trim() === "") {
197
+ throw new APIError({status: 400, title: "Role name must be a non-empty string"});
198
+ }
199
+ await assertNoEscalationOrAudit({
200
+ action: "role.update",
201
+ actor,
202
+ permissions: existing.permissions ?? {},
203
+ targetRoleName: roleName,
204
+ });
205
+ if (await rbacRoleModel.exists({name: newName})) {
206
+ throw new APIError({status: 409, title: "A role with that name already exists"});
207
+ }
208
+ if (userModel && (await userModel.countDocuments({roles: newName})) > 0) {
209
+ throw new APIError({status: 409, title: "Users already hold a role with that name"});
210
+ }
211
+ };
212
+
213
+ // Keeps holders of a renamed role on the same grants.
214
+ const moveRoleHolders = async (args: {fromName: string; toName: string}): Promise<void> => {
215
+ try {
216
+ if (userModel) {
217
+ await userModel.updateMany({roles: args.fromName}, {$set: {"roles.$": args.toName}});
218
+ }
219
+ await rbacRoleModel.updateMany(
220
+ {excludesRoles: args.fromName},
221
+ {$set: {"excludesRoles.$": args.toName}}
222
+ );
223
+ } catch (error) {
224
+ logger.error("Failed to move role holders after a rename", {
225
+ error,
226
+ fromName: args.fromName,
227
+ toName: args.toName,
228
+ });
229
+ throw error;
230
+ }
231
+ };
232
+
183
233
  const seedDefaults = async (): Promise<void> => {
184
234
  await rbacRoleModel.seedDefaults({extraRoles: defaultRoles, statements});
185
235
  };
@@ -381,17 +431,28 @@ export const createRoleManager = (args: {
381
431
  });
382
432
  }
383
433
  }
384
- if (changes.permissions) {
385
- assertValidPermissionSet(changes.permissions, statements);
434
+ // Any `permissions` key is written below, so validate on presence, not truthiness:
435
+ // `false` or `""` would otherwise skip both checks and empty the role.
436
+ if ("permissions" in changes) {
437
+ const incoming: unknown = changes.permissions;
438
+ if (!incoming || typeof incoming !== "object" || Array.isArray(incoming)) {
439
+ throw new APIError({
440
+ detail: "permissions must be an object of resource action lists",
441
+ status: 400,
442
+ title: "Invalid permissions",
443
+ });
444
+ }
445
+ assertValidPermissionSet(incoming as PermissionSet, statements);
386
446
  await assertNoEscalationOrAudit({
387
447
  action: "role.update",
388
448
  actor,
389
- permissions: unionPermissionSets(existing.permissions ?? {}, changes.permissions),
449
+ permissions: unionPermissionSets(existing.permissions ?? {}, incoming as PermissionSet),
390
450
  targetRoleName: roleName,
391
451
  });
392
452
  }
393
- if (changes.name && existing.isLocked) {
394
- throw new APIError({status: 400, title: "Cannot rename a locked role"});
453
+ const isRename = changes.name !== undefined && changes.name !== roleName;
454
+ if (isRename) {
455
+ await assertRenameAllowed({actor, existing, newName: changes.name, roleName});
395
456
  }
396
457
  if (changes.excludesRoles && userModel) {
397
458
  const holders = await userModel.find({roles: roleName});
@@ -423,6 +484,9 @@ export const createRoleManager = (args: {
423
484
  existing.set("description", undefined);
424
485
  }
425
486
  await existing.save();
487
+ if (isRename) {
488
+ await moveRoleHolders({fromName: roleName, toName: existing.name});
489
+ }
426
490
  invalidateCache();
427
491
  await emitAudit({
428
492
  action: "role.update",
@@ -159,7 +159,7 @@ export const terrenoDefaultRoles: RoleDefinition[] = [
159
159
  adminAnnouncementClickEvent: ["read"],
160
160
  adminAnnouncementImpression: ["read"],
161
161
  configuration: ["read", "update"],
162
- user: ["create", "list", "read", "update"],
162
+ user: ["create", "list", "read", "update", "updateIdentity"],
163
163
  ...observabilityAdminPermissionSpec(),
164
164
  },
165
165
  },
@@ -65,7 +65,16 @@ export const terrenoStatements = {
65
65
  featureFlag: MODEL_CRUD,
66
66
  organization: ORGANIZATION_ACTIONS,
67
67
  rbac: ["read", "manageRoles", "assignRoles"],
68
- user: ["create", "list", "read", "update", "delete", "impersonate", "setPassword"],
68
+ user: [
69
+ "create",
70
+ "list",
71
+ "read",
72
+ "update",
73
+ "delete",
74
+ "impersonate",
75
+ "setPassword",
76
+ "updateIdentity",
77
+ ],
69
78
  } as const;
70
79
 
71
80
  export type Statements = Record<string, readonly string[]>;
@@ -131,6 +140,10 @@ export const terrenoStatementDescriptions: Record<string, Record<string, string>
131
140
  list: "List traces and observability status",
132
141
  read: "View trace detail and run trace test helpers",
133
142
  },
143
+ user: {
144
+ updateIdentity:
145
+ "Change another user's email, disabled flag, email verification, or linked Better Auth and GitHub ids",
146
+ },
134
147
  };
135
148
 
136
149
  /** Add missing actions for selected resources without removing consumer-defined grants. */
package/src/rbac/types.ts CHANGED
@@ -111,6 +111,13 @@ export interface PermissionSource {
111
111
  ttlMs?: number;
112
112
  staleOnFailure?: StaleOnFailurePolicy;
113
113
  staleMaxAgeMs?: number;
114
+ /**
115
+ * When true (the default), a failed `getGrants` for a user this process has no last-known deny
116
+ * posture for (cold instance, or the posture was evicted) throws a 503 instead of resolving
117
+ * local roles without this source's deny. Set it to `false` on additive-only sources that never
118
+ * return `deny`, so their outage drops only their grants.
119
+ */
120
+ failClosedWhenDenyUnknown?: boolean;
114
121
  getGrants: (args: {user: User}) => Promise<PermissionSourceGrants | null>;
115
122
  }
116
123
 
@@ -200,4 +207,9 @@ export interface TerrenoAccess<S extends Statements> {
200
207
  permission: (permissions: PermissionRequest<S>) => PermissionMethod<unknown>;
201
208
  roles: RoleManager;
202
209
  invalidateCache: (args?: {userId?: string}) => void;
210
+ /**
211
+ * The `userModel` passed to `createAccess`. Write paths use it to recognize the user model when
212
+ * it is compiled under a name other than `"User"`.
213
+ */
214
+ readonly userModel?: UserModel;
203
215
  }