Require explicit un-banning

api/client-server/banning.yaml

@@ -24,7 +24,7 @@ paths:
       description: |-
         Ban a user in the room. If the user is currently in the room, also kick them.
 
-        When a user is banned from a room, they may not join it until they are unbanned.
+        When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
 
         The caller must have the required power level in order to perform this operation.
       security:
@@ -76,3 +76,55 @@ paths:
               }
       tags:
         - Room membership
+  "/rooms/{roomId}/unban":
+    post:
+      summary: Unban a user from the room.
+      description: |-
+        Unban a user from the room. This allows them to be invited to the room,
+        and join if they would otherwise be allowed to join according to its join rules.
+
+        The caller must have the required power level in order to perform this operation.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) from which the user should be unbanned.
+          required: true
+          x-example: "!e42d8c:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the user being unbanned.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been unbanned from the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The unbanner's power level is insufficient to unban users from the room.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_FORBIDDEN",
+                "error": "You do not have a high enough power level to unban from this room."
+              }
+      tags:
+        - Room membership

api/client-server/kicking.yaml

@@ -0,0 +1,77 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Kicking API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/kick":
+    post:
+      summary: Kick a user from the room.
+      description: |-
+        Kick a user from the room.
+
+        The caller must have the required power level in order to perform this operation.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) from which the user should be kicked.
+          required: true
+          x-example: "!e42d8c:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "reason": "Telling unfunny jokes",
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the user being kicked.
+              reason:
+                type: string
+                description: The reason the user has been kicked.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been kicked from the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The kicker is not currently in the room.
+            - The kickee is not currently in the room.
+            - The kicker's power level is insufficient to kick users from the room.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_FORBIDDEN",
+                "error": "You do not have a high enough power level to kick from this room."
+              }
+      tags:
+        - Room membership

specification/client_server_api.rst

@@ -914,10 +914,42 @@ following values:
 ``invite``
   This room can only be joined if you were invited.
 
+The allowable state transitions of membership are::
+
+                                       /ban
+                  +------------------------------------------------------+
+                  |                                                      |
+                  |  +----------------+  +----------------+              |
+                  |  |    /leave      |  |                |              |
+                  |  |                v  v                |              |
+    /invite    +--------+           +-------+             |              |
+  ------------>| invite |<----------| leave |----+        |              |
+               +--------+  /invite  +-------+    |        |              |
+                 |                   |    ^      |        |              |
+                 |                   |    |      |        |              |
+           /join |   +---------------+    |      |        |              |
+                 |   | /join if           |      |        |              |
+                 |   | join_rules         |      | /ban   | /unban       |
+                 |   | public      /leave |      |        |              |
+                 v   v               or   |      |        |              |
+               +------+            /kick  |      |        |              |
+  ------------>| join |-------------------+      |        |              |
+   /join       +------+                          v        |              |
+   if             |                           +-----+     |              |
+   join_rules     +-------------------------->| ban |-----+              |
+   public                   /ban              +-----+                    |
+                                                ^ ^                      |
+                                                | |                      |
+  ----------------------------------------------+ +----------------------+
+                  /ban
+
+
 {{inviting_http_api}}
 
 {{joining_http_api}}
 
+{{kicking_http_api}}
+
 {{banning_http_api}}
 
 Leaving rooms
@@ -947,8 +979,7 @@ to |/rooms/<room_id>/ban|_ with::
     "reason": "string: <reason for the ban>"
   }
 
-Banning a user adjusts the banned member's membership state to ``ban`` and
+Banning a user adjusts the banned member's membership state to ``ban``.
-adjusts the power level of this event to a level higher than the banned person.
 Like with other membership changes, a user can directly adjust the target
 member's state, by making a request to
 ``/rooms/<room id>/state/m.room.member/<user id>``::
@@ -957,6 +988,9 @@ member's state, by making a request to
     "membership": "ban"
   }
 
+A user must be explicitly unbanned with a request to |/rooms/<room_id>/unban|_
+before they can re-join the room or be re-invited.
+
 Listing rooms
 ~~~~~~~~~~~~~
 
@@ -1048,3 +1082,6 @@ have to wait in milliseconds before they can try again.
 .. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
 .. _/rooms/<room_id>/ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban
 
+.. |/rooms/<room_id>/unban| replace:: ``/rooms/<room_id>/unban``
+.. _/rooms/<room_id>/unban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-unban
+