Merged in jmathison/DEVOPS-722 (pull request #226)

DEVOPS-722 enforce team management visibility

* DEVOPS-722 enforce team management visibility

* DEVOPS-722 reduce admin user list complexity

* DEVOPS-722 cover admin access helpers

* DEVOPS-722 address team management PR feedback

* DEVOPS-722 fix admin access tests in CI

* DEVOPS-722 fix remaining admin PR feedback

serviceAPIs/queryAPI.yaml

@@ -1659,6 +1659,9 @@ paths:
       description: >-
         Creates a new user in both AWS Cognito and Permit.io systems with optional role assignments.
         Idempotent - returns 200 OK if user already exists with identical attributes.
+        Team Management permissions are enforced before user creation: Super Admin can
+        create any user, User Admin and Client Admin can create only non-AArete users
+        with client_user/user_admin roles, and Auditor cannot create users.
 
 
         **Creation Flow:**
@@ -1745,9 +1748,12 @@ paths:
       summary: List users
       description: >-
         Lists users from AWS Cognito with pagination, filtering, and sorting support.
-        Note: The roles field is not populated in this response. To retrieve roles for
-        a specific user, call GET /admin/users/{email} which returns the full user
-        details including Permit.io roles.
+        Results are filtered according to the viewer's Team Management role. User
+        Admin and Client Admin viewers only receive non-AArete users that do not have
+        auditor or super_admin roles, while Super Admin and Auditor viewers receive all
+        environment-visible users.
+        The roles field is populated from Permit.io so clients can enforce the same
+        visibility and action rules locally.
       security:
         - jwtAuth: []
       parameters:
@@ -1767,7 +1773,7 @@ paths:
             type: integer
             format: int32
             minimum: 1
-            maximum: 100
+            maximum: 60
             default: 50
         - name: search
           in: query
@@ -1828,6 +1834,8 @@ paths:
       summary: Get user by email
       description: >-
         Retrieves user details from both AWS Cognito and Permit.io by email address.
+        Team Management visibility is enforced. Hidden users return 404 so User Admin
+        and Client Admin callers cannot enumerate AArete, Auditor, or Super Admin users.
       security:
         - jwtAuth: []
       responses:
@@ -1859,6 +1867,8 @@ paths:
       summary: Check if user exists
       description: >-
         Checks if a user exists in Cognito and/or Permit.io without returning full details.
+        Team Management visibility is enforced. Hidden users return 404 so User Admin
+        and Client Admin callers cannot enumerate AArete, Auditor, or Super Admin users.
       security:
         - jwtAuth: []
       responses:
@@ -1898,6 +1908,10 @@ paths:
       description: >-
         Updates user attributes (first_name, last_name) in Cognito and manages role assignments in Permit.io.
         Email address cannot be changed (use email path parameter to identify user).
+        Team Management mutation rules are enforced: Super Admin can update any
+        environment-visible user, User Admin and Client Admin can update only non-AArete
+        client-level users and can assign only client_user/user_admin roles, and Auditor
+        is read-only.
 
 
         **Attribute Updates:**
@@ -1986,6 +2000,9 @@ paths:
       description: >-
         Permanently deletes a user from both AWS Cognito and Permit.io.
         This operation is irreversible. Requires confirm=true query parameter.
+        Team Management mutation rules are enforced: Super Admin can delete any
+        environment-visible user, User Admin and Client Admin can delete only non-AArete
+        client-level users, and Auditor is read-only.
       security:
         - jwtAuth: []
       parameters:
@@ -2038,6 +2055,9 @@ paths:
       description: >-
         Disables a user in AWS Cognito, preventing authentication.
         User data and roles are preserved. Idempotent.
+        Team Management mutation rules are enforced: Super Admin can disable any
+        environment-visible user, User Admin and Client Admin can disable only non-AArete
+        client-level users, and Auditor is read-only.
       security:
         - jwtAuth: []
       responses:
@@ -2074,6 +2094,9 @@ paths:
       description: >-
         Re-enables a previously disabled user in AWS Cognito.
         Restores authentication capability. Idempotent.
+        Team Management mutation rules are enforced: Super Admin can enable any
+        environment-visible user, User Admin and Client Admin can enable only non-AArete
+        client-level users, and Auditor is read-only.
       security:
         - jwtAuth: []
       responses:
@@ -5326,8 +5349,9 @@ components:
             maxLength: 100
             pattern: "^.+$"
           description: >-
-            Roles assigned in Permit.io. Only populated by GET /admin/users/{email}.
-            Not populated by GET /admin/users (list endpoint) for performance reasons.
+            Roles assigned in Permit.io. Populated by GET /admin/users and
+            GET /admin/users/{email} so Team Management clients can enforce
+            role-based visibility and action rules.
           example: ["admin", "viewer"]
         created_at:
           type: string
@@ -5362,7 +5386,6 @@ components:
           example: Doe-Smith
         roles:
           type: array
-          minItems: 1
           maxItems: 50
           items:
             type: string