Implement moderator/admin endpoints

Allows adding/removing room-specific and global moderators/admins.

Author: jagerman

api.yaml

@@ -894,12 +894,16 @@ paths:
   /user/{sessionId}/moderator:
     post:
       tags: [Users]
-      summary: Adds or removes moderator powers.
+      summary: Adds or removes moderator/admin powers.
       description: >
         Adds or removes moderator or admin permissions to a user for specific rooms, or globally on
         the server.
         
         
+        The invoking user must have admin permissions in all of the rooms specified when adding room
+        mods/admins, and must have global admin permissions when adding a global moderator or admin.
+        
+        
         Note that the given session ID does not have to exist: it is possible to grant moderator
         permissions preemptively for a session ID that has never visited the server or room(s).
       parameters:
@@ -922,22 +926,37 @@ paths:
                     invoking user must be an admin of all of the given rooms.
                     
                     
-                    Exclusive of `global`.
+                    This may be set to the single-element list ['*'] to add or remove the moderator
+                    from all rooms in which the current user has admin permissions (the call will
+                    succeed if the calling user is an admin in at least one channel).
+                    
+                    
+                    Exclusive of `global`.  (If you want to apply both at once use two calls, e.g.
+                    bundled in a batch request).
                 global:
                   type: boolean
                   description: >
-                    If true then appoint this user as a moderator or admin of the global server.
-                    The user will receive moderator/admin ability in all rooms on the server.
-                
+                    If true then appoint this user as a global moderator or admin of the server.
+                    The user will receive moderator/admin ability in all rooms on the server (both
+                    current and future).
+                    
+                    
+                    The caller must be a global admin to add/remove a global moderator or admin.
                 moderator:
                   type: boolean
                   description: >
                     If `true` then this user will be granted moderator permission to either the
-                    listed room or the server globally.
+                    listed room(s) or the server globally.
+                    
+                    
+                    If `false` then this user will have their moderator *and admin* permissions
+                    removed from the given rooms (or server).  Note that removing a global moderator
+                    only removes the global permission but does not remove individual room
+                    moderator permissions that may also be present.
                     
                     
-                    If `false` then this user will have their moderator and admin permissions
-                    removed from the given rooms (or server).
+                    See the `admin` parameter description for information on how `admin` and
+                    `moderator` parameters interact.
                 admin:
                   type: boolean
                   description: >
@@ -947,53 +966,87 @@ paths:
                     pinned messages, and changing the name/description of the room.
                     
                     
-                    If false then this user will have their admin permission removed, but will
-                    remain a moderator (if they were previously a moderator or admin).  To remove
-                    both moderator and admin status you can specify simply `moderator: false` rather
-                    than needing to specify both values as false.
+                    If false then this user will have their admin permission removed, but will keep
+                    moderator permissions.  To remove both moderator and admin permissions specify
+                    `moderator: false` (which implies clearing admin permissions as well).
+                    
+                    
+                    Note that removing a global admin only removes the global permission but does not remove
+                    individual room admin permissions that may also be present.
+                    
+                    
+                    The `admin`/`moderator` paramters interact as follows:
+                    - `admin=true`, `moderator` omitted: this adds admin permissions, which
+                      automatically also implies moderator permissions.
+                    - `admin=true, moderator=true`: exactly the same as above.
+                    - `admin=false, moderator=true`: removes any existing admin permissions from the
+                      rooms (or globally), if present, and adds moderator permissions to the
+                      rooms/globally (if not already present).
+                    - `admin=false`, `moderator` omitted: this removes admin permissions but leaves
+                      moderator permissions, if present.  (This effectively "downgrades" an admin to
+                      a moderator).  Unlike the above this does *not* add moderator permissions to
+                      matching rooms if not already present.
+                    - `moderator=true`, `admin` omitted: adds moderator permissions to the given
+                      rooms (or globally), if not already present.  If the user already has admin
+                      permissions this does nothing (that is, admin permission is *not* removed,
+                      unlike the above).
+                    - `moderator=false`, `admin` omitted: this removes moderator *and* admin
+                      permissions from all given rooms (or globally).
+                    - `moderator=false, admin=false`: exactly the same as above.
+                    - `moderator=false, admin=true`: this combination is *not* *permitted* (because
+                      admin permissions imply moderator permissions) and will result in Bad Request
+                      error if given.
                 visible:
                   type: boolean
                   description: >
-                    Whether this user should be a "visible" moderator in the server rooms.  Visible
-                    moderators are identified to all room users (e.g. via a special status badge in
-                    Session clients).
+                    Whether this user should be a "visible" moderator or admin in the specified
+                    rooms (or globally).  Visible moderators are identified to all room users (e.g.
+                    via a special status badge in Session clients).
                     
                     
                     Invisible moderators/admins have the same permission as as visible ones, but
-                    their moderator/admin status is only visible to other moderators but not to
+                    their moderator/admin status is only visible to other moderators, not to
                     ordinary room participants.
                     
                     
                     The default if this field is omitted is true for room-specific moderators/admins
                     and false for server-level global moderators/admins.
+                    
+                    
+                    If an admin or moderator has both global and room-specific moderation
+                    permissions then the visibility of the admin/mod for that room's moderator/admin
+                    list will use the room-specific visibility value, regardless of the global
+                    setting.  (This differs from moderator/admin permissions themselves, which are
+                    additive).
             examples:
-              tworooms:
-                summary: "1-day mute in two rooms"
+              room-moderator:
+                summary: "Add a moderator to a pair of rooms"
                 value:
                   rooms: ["session", "lokinet"]
-                  timeout: 86400
-                  write: false
-              allow-uploads:
-                summary: "Allow file attachments for 1 week"
+                  moderator: true
+              global-admin:
+                summary: "Add a global server admin, visible in all rooms"
                 value:
-                  rooms: ["session-help"]
-                  upload: true
-                  timeout: 604800
-              secretroom:
-                summary: "Grant access to a restricted room"
+                  global: true
+                  admin: true
+                  visible: true
+              hidden-mod:
+                summary: "Add a hidden admin to a room"
                 value:
-                  rooms: ["top-secret"]
-                  read: true
-                  write: true
-                  upload: true
+                  rooms: ["session"]
+                  admin: true
+                  visible: false
       responses:
         200:
           description: Permission update applied successfully.
           content: {}
         403:
           description: >
-            Permission denied.  The user attempting to set the permissions does not have moderator
-            permissions for one or more of the given rooms.
+            Permission denied.  The user attempting to set the permissions does not have admin
+            permissions for one or more of the given rooms and/or global admin permissions.
+          content: {}
+        404:
+          description: Returned if one or more specified room tokens do not exist.
           content: {}
   /user/{sessionId}/deleteMessages:
     post:

sogs/model/room.py

@@ -940,6 +940,8 @@ def set_moderator(self, user: User, *, added_by: User, admin=False, visible=True
         Sets `user` as a moderator or admin of this room.  Replaces current admin/moderator/visible
         status with the new values if the user is already a moderator/admin of the room.
 
+        `admin` can be specified as None to not touch the current admin permission on the room.
+
         added_by is the user performing the update and must have admin permission.
         """
 
@@ -951,12 +953,13 @@ def set_moderator(self, user: User, *, added_by: User, admin=False, visible=True
             raise BadPermission()
 
         query(
-            """
-            INSERT INTO user_permission_overrides (room, "user", moderator, admin, visible_mod)
-            VALUES (:r, :u, TRUE, :admin, :visible)
+            f"""
+            INSERT INTO user_permission_overrides
+                (room, "user", moderator, {'admin,' if admin is not None else ''} visible_mod)
+            VALUES (:r, :u, TRUE, {':admin,' if admin is not None else ''} :visible)
             ON CONFLICT (room, "user") DO UPDATE SET
                 moderator = excluded.moderator,
-                admin = excluded.admin,
+                {'admin = excluded.admin,' if admin is not None else ''}
                 visible_mod = excluded.visible_mod
             """,
             r=self.id,
@@ -970,16 +973,22 @@ def set_moderator(self, user: User, *, added_by: User, admin=False, visible=True
 
         app.logger.info(f"{added_by} set {user} as {'admin' if admin else 'moderator'} of {self}")
 
-    def remove_moderator(self, user: User, *, removed_by: User):
-        """Remove `user` as a moderator/admin of this room.  Requires admin permission."""
+    def remove_moderator(self, user: User, *, removed_by: User, remove_admin_only: bool = False):
+        """
+        Remove `user` as a moderator/admin of this room.  Requires admin permission.
+
+        If `remove_admin_only` is True then user will have admin permissions removed but will remain
+        a room moderator if already a room moderator or admin.
+        """
 
         if not self.check_admin(removed_by):
             raise BadPermission()
 
         query(
-            """
+            f"""
             UPDATE user_permission_overrides
-            SET moderator = FALSE, admin = FALSE, visible_mod = TRUE
+            SET admin = FALSE
+                {', moderator = FALSE, visible_mod = TRUE' if not remove_admin_only else ''}
             WHERE room = :r AND "user" = :u
             """,
             r=self.id,
@@ -1321,6 +1330,63 @@ def get_rooms():
     return [Room(row) for row in query("SELECT * FROM rooms ORDER BY token")]
 
 
+def get_rooms_with_permission(
+    user: User,
+    *,
+    tokens: Optional[Union[list, tuple]] = None,
+    read: Optional[bool] = None,
+    write: Optional[bool] = None,
+    upload: Optional[bool] = None,
+    banned: Optional[bool] = None,
+    moderator: Optional[bool] = None,
+    admin: Optional[bool] = None,
+):
+    """
+    Returns a list of rooms that the given user has matching permissions for.
+
+    Parameters:
+    user: the user object to query permissions for.  May not be None.
+    tokens: if non-None then this specifies a list or tuple of room tokens to filter by.  When
+            omitted, all rooms are returned.  Note that rooms are returned sorted by token, *not* in
+            the order specified here; duplicates are not returned; nor are entries for non-existent
+            tokens.
+    read/write/upload/banned/moderator/admin:
+        Any of these that are specified as non-None must match the user's permissions for the room.
+        For example `read=True, write=False` would return all rooms where the user has read-only
+        access but not rooms in which the user has both or neither read and write permissions.
+        At least one of these arguments must be specified as non-None.
+    """
+    if user is None:
+        raise RuntimeError("user is required for get_rooms_with_permission")
+    if not any(arg is not None for arg in (read, write, upload, banned, moderator, admin)):
+        raise RuntimeError("At least one of read/write/upload/banned/moderator/admin must be given")
+    if tokens and (
+        not (isinstance(tokens, list) or isinstance(tokens, tuple))
+        or any(not isinstance(t, str) for t in tokens)
+    ):
+        raise RuntimeError("tokens= must be a list or tuple of room token names")
+
+    return [
+        Room(row)
+        for row in query(
+            f"""
+        SELECT rooms.* FROM user_permissions perm JOIN rooms ON rooms.id = room
+        WHERE "user" = :u {'AND token IN :tokens' if tokens else ''}
+            {'' if banned is None else ('AND' if banned else 'AND NOT') + ' perm.banned'}
+            {'' if read is None else ('AND' if read else 'AND NOT') + ' perm.read'}
+            {'' if write is None else ('AND' if write else 'AND NOT') + ' perm.write'}
+            {'' if upload is None else ('AND' if upload else 'AND NOT') + ' perm.upload'}
+            {'' if moderator is None else ('AND' if moderator else 'AND NOT') + ' perm.moderator'}
+            {'' if admin is None else ('AND' if admin else 'AND NOT') + ' perm.admin'}
+        ORDER BY token
+        """,
+            u=user.id,
+            tokens=tokens,
+            bind_expanding=['tokens'] if tokens else None,
+        )
+    ]
+
+
 def get_readable_rooms(user: Optional[User] = None):
     """
     Get a list of rooms that a user can access; if user is None then return all publicly readable
@@ -1329,14 +1395,7 @@ def get_readable_rooms(user: Optional[User] = None):
     if user is None:
         result = query("SELECT * FROM rooms WHERE read ORDER BY token")
     else:
-        result = query(
-            """
-            SELECT rooms.* FROM user_permissions perm JOIN rooms ON rooms.id = room
-            WHERE "user" = :u AND perm.read AND NOT perm.banned
-            ORDER BY token
-            """,
-            u=user.id,
-        )
+        return get_rooms_with_permission(user, read=True, banned=False)
     return [Room(row) for row in result]
 
 

sogs/model/user.py

@@ -34,11 +34,23 @@ def __init__(self, row=None, *, id=None, session_id=None, autovivify=True, touch
         touch - if True (default is False) then update the last_activity time of this user before
         returning it.
         """
+        self._touched = False
+        self._refresh(row=row, id=id, session_id=session_id)
 
-        if sum(x is not None for x in (row, session_id, id)) != 1:
+        if touch:
+            self._touch()
+
+    def _refresh(self, *, row=None, id=None, session_id=None, autovivify=True):
+        """
+        Internal method to (re-)fetch details from the database; this is used during construction
+        but also in the test suite to forcibly re-fetch details.
+        """
+        n_args = sum(x is not None for x in (row, session_id, id))
+        if n_args == 0 and hasattr(self, 'id'):
+            id = self.id
+        elif n_args != 1:
             raise ValueError("User() error: exactly one of row/session_id/id is required")
 
-        self._touched = False
         if session_id is not None:
             row = query("SELECT * FROM users WHERE session_id = :s", s=session_id).first()
 
@@ -62,9 +74,6 @@ def __init__(self, row=None, *, id=None, session_id=None, autovivify=True, touch
             bool(row[c]) for c in ('banned', 'moderator', 'admin', 'visible_mod')
         )
 
-        if touch:
-            self._touch()
-
     def __str__(self):
         """Returns string representation of a user: U[050123…cdef], the id prefixed with @ or % if
         the user is a global admin or moderator, respectively."""
@@ -113,6 +122,8 @@ def set_moderator(self, *, added_by: User, admin=False, visible=False):
         """
         Make this user a global moderator or admin.  If the user is already a global mod/admin then
         their status is updated according to the given arguments (that is, this can promote/demote).
+
+        If `admin` is None then the current admin status is left unchanged.
         """
 
         if not added_by.global_admin:
@@ -123,20 +134,21 @@ def set_moderator(self, *, added_by: User, admin=False, visible=False):
             raise BadPermission()
 
         query(
-            """
+            f"""
             UPDATE users
-            SET moderator = TRUE, admin = :admin, visible_mod = :visible
+            SET moderator = TRUE, visible_mod = :visible
+                {', admin = :admin' if admin is not None else ''}
             WHERE id = :u
             """,
-            admin=admin,
+            admin=bool(admin),
             visible=visible,
             u=self.id,
         )
         self.global_admin = admin
         self.global_moderator = True
         self.visible_mod = visible
 
-    def remove_moderator(self, *, removed_by: User):
+    def remove_moderator(self, *, removed_by: User, remove_admin_only: bool = False):
         """Removes this user's global moderator/admin status, if set."""
 
         if not removed_by.global_admin:
@@ -145,7 +157,14 @@ def remove_moderator(self, *, removed_by: User):
             )
             raise BadPermission()
 
-        query("UPDATE users SET moderator = FALSE, admin = FALSE WHERE id = :u", u=self.id)
+        query(
+            f"""
+            UPDATE users
+            SET admin = FALSE {', moderator = FALSE' if not remove_admin_only else ''}
+            WHERE id = :u
+            """,
+            u=self.id,
+        )
         self.global_admin = False
         self.global_moderator = False