From 2e46b587b8a9cba1872973a701ac1bfb6e1a5060 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Fri, 15 Jan 2016 14:08:40 +0000 Subject: [PATCH] Require explicit un-banning --- api/client-server/banning.yaml | 54 +++++++++++++++++++- api/client-server/kicking.yaml | 77 +++++++++++++++++++++++++++++ specification/client_server_api.rst | 41 ++++++++++++++- 3 files changed, 169 insertions(+), 3 deletions(-) create mode 100644 api/client-server/kicking.yaml diff --git a/api/client-server/banning.yaml b/api/client-server/banning.yaml index ad0e2834..87326608 100644 --- a/api/client-server/banning.yaml +++ b/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 diff --git a/api/client-server/kicking.yaml b/api/client-server/kicking.yaml new file mode 100644 index 00000000..41db8b48 --- /dev/null +++ b/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 diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 1cd2a49d..782c48ec 100644 --- a/specification/client_server_api.rst +++ b/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//ban|_ with:: "reason": "string: " } -Banning a user adjusts the banned member's membership state to ``ban`` and -adjusts the power level of this event to a level higher than the banned person. +Banning a user adjusts the banned member's membership state to ``ban``. Like with other membership changes, a user can directly adjust the target member's state, by making a request to ``/rooms//state/m.room.member/``:: @@ -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//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//ban| replace:: ``/rooms//ban`` .. _/rooms//ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban +.. |/rooms//unban| replace:: ``/rooms//unban`` +.. _/rooms//unban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-unban +