diff --git a/.circleci/config.yml b/.circleci/config.yml index bf4404ce9..e3ac14d86 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -5,9 +5,10 @@ gendoc: &gendoc scripts/gendoc.py genswagger: &genswagger - name: Generate the swagger + name: Validate sources and generate swagger json command: | source /env/bin/activate + scripts/check-swagger-sources.py scripts/dump-swagger.py buildswaggerui: &buildswaggerui @@ -27,10 +28,7 @@ checkexamples: &checkexamples name: Check Event Examples command: | source /env/bin/activate - cd event-schemas - ./check_examples.py - cd ../api - ./check_examples.py + scripts/check-event-schema-examples.py genmatrixassets: &genmatrixassets name: Generate/Verify matrix.org assets @@ -41,9 +39,9 @@ genmatrixassets: &genmatrixassets validateapi: &validateapi name: Validate OpenAPI specifications command: | - cd api + cd scripts npm install - node validator.js -s "client-server" + node validator.js -s "../data/api/client-server" buildspeculator: &buildspeculator name: Build Speculator diff --git a/assets-hugo/scss/custom.scss b/assets-hugo/scss/custom.scss index 7b80d434e..73d14048b 100644 --- a/assets-hugo/scss/custom.scss +++ b/assets-hugo/scss/custom.scss @@ -242,6 +242,130 @@ footer { } } +/* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */ +.rendered-data { + margin: 1rem 0 3rem 0; + padding: 1rem; + + details { + + summary { + padding: .5rem 0; + list-style-position: outside; + } + } + + .deprecated-inline { + + &:after { + content: " — DEPRECATED"; + color: $warning; + font-weight: $font-weight-bold; + } + } + + h1 { + display: inline-block; + font-size: 1.3rem; + + .endpoint { + color: $secondary; + } + } + + h2 { + font-weight: $font-weight-bold; + font-size: 1.3rem; + margin: 3rem 0 .5rem 0; + } + + h3 { + font-weight: $font-weight-bold; + font-size: 1.1rem; + margin: 1.5rem 0 .75rem 0; + } + + h2 + table, h3 + table, h3 + div.highlight { + margin-top: 0; + } + + hr { + border-bottom: 2px solid $dark; + margin-bottom: 1.5rem; + } + + p { + margin: .5rem; + max-width: 80%; + } + + p code, table code { + background-color: $white; + } + + table { + table-layout: fixed; + width: 100%; + margin: 4rem 0; + + caption { + caption-side: top; + color: $dark; + font-size: 1rem; + font-weight: $font-weight-bold; + } + + th, td, caption { + padding: 1rem; + } + + th { + background-color: $white; + } + + caption, tr { + background-color: $table-row-default; + } + + tr:nth-child(even) { + background-color: $table-row-alternate; + } + + &.basic-info, &.basic-info th, &.basic-info td { + table-layout: fixed; + margin: 1rem 0 .5rem 0; + background-color: $white; + } + + &.basic-info th { + width: 15rem; + } + + .col-name, .col-type, .col-status { + width: 25%; + } + + .col-description { + width: 50%; + } + + .col-status-description { + width: 75%; + } + + } + + pre { + border: 0; + border-left: solid 5px $secondary; + } + + .http-api-method { + font-weight: $font-weight-bold; + } + +} + /* Miscellaneous custom bits */ /* Update link colours for MAtrix style */ diff --git a/content/application-service-api.md b/content/application-service-api.md index 13d438831..e324bba05 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -204,7 +204,7 @@ NOT alter (e.g. add more) events they were going to send within that transaction ID on retries, as the application service may have already processed the events. -{{transactions\_as\_http\_api}} +{{% http-api spec="application-service" api="transactions" %}} #### Querying @@ -227,9 +227,9 @@ about information about the entity such as room ID to room alias mappings. {{% /boxes/rationale %}} -{{query\_user\_as\_http\_api}} +{{% http-api spec="application-service" api="query_user" %}} -{{query\_room\_as\_http\_api}} +{{% http-api spec="application-service" api="query_room" %}} #### Third party networks @@ -251,7 +251,7 @@ request the homeserver to search in a particular "network" (protocol), the search fields will be passed along to the application service for filtering. -{{protocols\_as\_http\_api}} +{{% http-api spec="application-service" api="protocols" %}} ### Client-Server API Extensions @@ -356,7 +356,7 @@ defined third party protocols. These room directories may be accessed by clients through additional parameters on the `/publicRooms` client-server endpoint. -{{appservice\_room\_directory\_cs\_http\_api}} +{{% http-api spec="client-server" api="appservice_room_directory" %}} ### Referencing messages from a third party network diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index b6a0b075f..06d161bec 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -205,7 +205,7 @@ Some API endpoints may allow or require the use of `POST` requests without a transaction ID. Where this is optional, the use of a `PUT` request is strongly recommended. -{{versions\_cs\_http\_api}} +{{% http-api spec="client-server" api="versions" %}} ## Web Browser Clients @@ -287,7 +287,7 @@ specify parameter values. The flow for this method is as follows: 1. Parse it as a URL. If it is not a URL, then `FAIL_ERROR`. 2. Clients SHOULD validate that the URL points to a valid homeserver before accepting it by connecting to the - `/_matrix/client/versions`\_ endpoint, ensuring that it does + [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) endpoint, ensuring that it does not return an error, and parsing and validating that the data conforms with the expected response format. If any step in the validation fails, then `FAIL_ERROR`. Validation is @@ -301,7 +301,7 @@ specify parameter values. The flow for this method is as follows: `m.identity_server` property is present, but does not have a `base_url` value, then `FAIL_ERROR`. -{{wellknown\_cs\_http\_api}} +{{% http-api spec="client-server" api="wellknown" %}} ## Client Authentication @@ -1021,9 +1021,9 @@ client supports it, the client should redirect the user to the is complete, the client will need to submit a `/login` request matching `m.login.token`. -{{login\_cs\_http\_api}} +{{% http-api spec="client-server" api="login" %}} -{{logout\_cs\_http\_api}} +{{% http-api spec="client-server" api="logout" %}} #### Login Fallback @@ -1044,7 +1044,7 @@ the login endpoint during the login process. For example: ### Account registration and management -{{registration\_cs\_http\_api}} +{{% http-api spec="client-server" api="registration" %}} #### Notes on password management @@ -1069,11 +1069,11 @@ identifier that is found in an identity server. Note that an identifier can be added and bound at the same time, depending on context. {{% /boxes/note %}} -{{administrative\_contact\_cs\_http\_api}} +{{% http-api spec="client-server" api="administrative_contact" %}} ### Current account information -{{whoami\_cs\_http\_api}} +{{% http-api spec="client-server" api="whoami" %}} #### Notes on identity servers @@ -1111,7 +1111,7 @@ which has no `m.identity_server` account data event should not end up with the client's default identity server in their account data, unless the user first visits their account settings to set the identity server. -{{m\_identity\_server\_event}} +{{% event event="m.identity_server" %}} ## Capabilities negotiation @@ -1148,7 +1148,7 @@ Matrix specification while other values may be used by servers using the Java package naming convention. The capabilities supported by the Matrix specification are defined later in this section. -{{capabilities\_cs\_http\_api}} +{{% http-api spec="client-server" api="capabilities" %}} ### `m.change_password` capability @@ -1350,13 +1350,13 @@ The expected pattern for using lazy-loading is currently: The current endpoints which support lazy-loading room members are: -- `/sync`\_ -- `/rooms//messages`\_ -- `/rooms/{roomId}/context/{eventId}`\_ +- [`/sync`](/client-server-api/#get_matrixclientr0sync) +- [`/rooms//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) +- [`/rooms/{roomId}/context/{eventId}`](/client-server-api/#get_matrixclientr0roomsroomidcontexteventid) ### API endpoints -{{filter\_cs\_http\_api}} +{{% http-api spec="client-server" api="filter" %}} ## Events @@ -1385,14 +1385,12 @@ available room versions. Room events are split into two categories: -State Events -These are events which update the metadata state of the room (e.g. room +* **State events**: These are events which update the metadata state of the room (e.g. room topic, room membership etc). State is keyed by a tuple of event `type` and a `state_key`. State in the room with the same key-tuple will be overwritten. -Message events -These are events which describe transient "once-off" activity in a room: +* **Message events**: These are events which describe transient "once-off" activity in a room: typically communication such as sending an instant message or setting up a VoIP call. @@ -1416,11 +1414,15 @@ assuming the client has access to the `com.example` namespace. Note that the structure of these events may be different than those in the server-server API. -{{common\_event\_fields}} +#### Event fields -{{common\_room\_event\_fields}} +{{% event-fields event_type="event" %}} -#### State Event Fields +#### Room event fields + +{{% event-fields event_type="room_event" %}} + +#### State event fields In addition to the fields of a Room Event, State Events have the following fields. @@ -1460,15 +1462,15 @@ This section is a work in progress. This specification outlines several standard event types, all of which are prefixed with `m.` -{{m\_room\_canonical\_alias\_event}} +{{% event event="m.room.canonical_alias" %}} -{{m\_room\_create\_event}} +{{% event event="m.room.create" %}} -{{m\_room\_join\_rules\_event}} +{{% event event="m.room.join_rules" %}} -{{m\_room\_member\_event}} +{{% event event="m.room.member" %}} -{{m\_room\_power\_levels\_event}} +{{% event event="m.room.power_levels" %}} #### Historical events @@ -1484,13 +1486,13 @@ events. ### Syncing To read events, the intended flow of operation is for clients to first -call the `/sync`\_ API without a `since` parameter. This returns the +call the [`/sync`](/client-server-api/#get_matrixclientr0sync) API without a `since` parameter. This returns the most recent message events for each room, as well as the state of the room at the start of the returned timeline. The response also includes a `next_batch` field, which should be used as the value of the `since` parameter in the next call to `/sync`. Finally, the response includes, for each room, a `prev_batch` field, which can be passed as a `start` -parameter to the `/rooms//messages`\_ API to retrieve earlier +parameter to the [`/rooms//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API to retrieve earlier messages. You can visualise the range of events being returned as: @@ -1527,7 +1529,7 @@ containing only the most recent message events. A state "delta" is also returned, summarising any state changes in the omitted part of the timeline. The client may therefore end up with "gaps" in its knowledge of the message timeline. The client can fill these gaps using the -`/rooms//messages`\_ API. This situation looks like this: +[`/rooms//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API. This situation looks like this: ``` | gap | @@ -1582,23 +1584,23 @@ take a copy of the state dictionary, and *rewind* S1, in order to correctly calculate the display name for M0. {{% /boxes/rationale %}} -{{sync\_cs\_http\_api}} +{{% http-api spec="client-server" api="sync" %}} -{{old\_sync\_cs\_http\_api}} +{{% http-api spec="client-server" api="old_sync" %}} ### Getting events for a room There are several APIs provided to `GET` events for a room: -{{rooms\_cs\_http\_api}} +{{% http-api spec="client-server" api="rooms" %}} -{{message\_pagination\_cs\_http\_api}} +{{% http-api spec="client-server" api="message_pagination" %}} -{{room\_initial\_sync\_cs\_http\_api}} +{{% http-api spec="client-server" api="room_initial_sync" %}} ### Sending events to a room -{{room\_state\_cs\_http\_api}} +{{% http-api spec="client-server" api="room_state" %}} **Examples** @@ -1647,7 +1649,7 @@ PUT /rooms/!roomid:domain/state/m.room.bgd.color { "color": "red", "hex": "#ff0000" } ``` -{{room\_send\_cs\_http\_api}} +{{% http-api spec="client-server" api="room_send" %}} ### Redactions @@ -1682,11 +1684,11 @@ the topic to be removed from the room. #### Events -{{m\_room\_redaction\_event}} +{{% event event="m.room.redaction" %}} #### Client behaviour -{{redaction\_cs\_http\_api}} +{{% http-api spec="client-server" api="redaction" %}} ## Rooms @@ -1706,7 +1708,7 @@ permissions in this room. This includes: See [Room Events](#room-events) for more information on these events. To create a room, a client has to use the following API. -{{create\_room\_cs\_http\_api}} +{{% http-api spec="client-server" api="create_room" %}} ### Room aliases @@ -1731,7 +1733,7 @@ have a room alias of `#alias:example.com`, this SHOULD be checked to make sure that the room's ID matches the `room_id` returned from the request. -{{directory\_cs\_http\_api}} +{{% http-api spec="client-server" api="directory" %}} ### Permissions @@ -1816,13 +1818,13 @@ The allowable state transitions of membership are: /ban ``` -{{list\_joined\_rooms\_cs\_http\_api}} +{{% http-api spec="client-server" api="list_joined_rooms" %}} #### Joining rooms -{{inviting\_cs\_http\_api}} +{{% http-api spec="client-server" api="inviting" %}} -{{joining\_cs\_http\_api}} +{{% http-api spec="client-server" api="joining" %}} #### Leaving rooms @@ -1830,7 +1832,7 @@ A user can leave a room to stop receiving events for that room. A user must have been invited to or have joined the room before they are eligible to leave the room. Leaving a room to which the user has been invited rejects the invite. Once a user leaves a room, it will no longer -appear in the response to the `/sync`\_ API unless it is explicitly +appear in the response to the [`/sync`](/client-server-api/#get_matrixclientr0sync) API unless it is explicitly requested via a filter with the `include_leave` field set to `true`. Whether or not they actually joined the room, if the room is an @@ -1838,7 +1840,7 @@ Whether or not they actually joined the room, if the room is an re-join the room. A user can also forget a room which they have left. Rooms which have -been forgotten will never appear the response to the `/sync`\_ API, +been forgotten will never appear the response to the [`/sync`](/client-server-api/#get_matrixclientr0sync) API, until the user re-joins or is re-invited. A user may wish to force another user to leave a room. This can be done @@ -1848,9 +1850,9 @@ behaviour is the same as if they had left of their own accord. In particular, the user is free to re-join if the room is not "invite-only". -{{leaving\_cs\_http\_api}} +{{% http-api spec="client-server" api="leaving" %}} -{{kicking\_cs\_http\_api}} +{{% http-api spec="client-server" api="kicking" %}} ##### Banning users in a room @@ -1859,7 +1861,7 @@ target user to leave the room and prevents them from re-joining the room. A banned user will not be treated as a joined user, and so will not be able to send or receive events in the room. In order to ban someone, the user performing the ban MUST have the required power level. -To ban a user, a request should be made to `/rooms//ban`\_ +To ban a user, a request should be made to [`/rooms//ban`](/client-server-api/#post_matrixclientr0roomsroomidban) with: ```json @@ -1881,24 +1883,24 @@ target member's state, by making a request to ``` A user must be explicitly unbanned with a request to -`/rooms//unban`\_ before they can re-join the room or be +[`/rooms//unban`](/client-server-api/#post_matrixclientr0roomsroomidunban) before they can re-join the room or be re-invited. -{{banning\_cs\_http\_api}} +{{% http-api spec="client-server" api="banning" %}} ### Listing rooms -{{list\_public\_rooms\_cs\_http\_api}} +{{% http-api spec="client-server" api="list_public_rooms" %}} ## User Data ### User Directory -{{users\_cs\_http\_api}} +{{% http-api spec="client-server" api="users" %}} ### Profiles -{{profile\_cs\_http\_api}} +{{% http-api spec="client-server" api="profile" %}} #### Events on Change of Profile Information diff --git a/content/client-server-api/modules/account_data.md b/content/client-server-api/modules/account_data.md index ea78dc821..2ae346864 100644 --- a/content/client-server-api/modules/account_data.md +++ b/content/client-server-api/modules/account_data.md @@ -23,7 +23,7 @@ These events can also be received in a `/events` response or in the #### Client Behaviour -{{account\_data\_cs\_http\_api}} +{{% http-api spec="client-server" api="account-data" %}} #### Server Behaviour diff --git a/content/client-server-api/modules/admin.md b/content/client-server-api/modules/admin.md index 28176bd99..1f0cbe222 100644 --- a/content/client-server-api/modules/admin.md +++ b/content/client-server-api/modules/admin.md @@ -10,4 +10,4 @@ server state and data. #### Client Behaviour -{{admin\_cs\_http\_api}} +{{% http-api spec="client-server" api="admin" %}} diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index f615e7f75..fba296a06 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -34,7 +34,7 @@ look like: Clients can upload and download content using the following HTTP APIs. -{{content\_repo\_cs\_http\_api}} +{{% http-api spec="client-server" api="content-repo" %}} ##### Thumbnails diff --git a/content/client-server-api/modules/device_management.md b/content/client-server-api/modules/device_management.md index c6fa6c457..2cf93f45a 100644 --- a/content/client-server-api/modules/device_management.md +++ b/content/client-server-api/modules/device_management.md @@ -13,7 +13,7 @@ Clients that implement this module should offer the user a list of registered devices, as well as the means to update their display names. Clients should also allow users to delete disused devices. -{{device\_management\_cs\_http\_api}} +{{% http-api spec="client-server" api="device_management" %}} #### Security considerations diff --git a/content/client-server-api/modules/dm.md b/content/client-server-api/modules/dm.md index c9f4511ae..59d09e3e6 100644 --- a/content/client-server-api/modules/dm.md +++ b/content/client-server-api/modules/dm.md @@ -19,12 +19,12 @@ whether a chat is 'direct' to an invitee. #### Events -{{m\_direct\_event}} +{{% event event="m.direct" %}} #### Client behaviour To start a direct chat with another user, the inviting user's client -should set the `is_direct` flag to \_. The client should do this +should set the `is_direct` flag to [`/createRoom`](/client-server-api/#post_matrixclientr0createroom). The client should do this whenever the flow the user has followed is one where their intention is to speak directly with another person, as opposed to bringing that person in to a shared room. For example, clicking on 'Start Chat' beside @@ -38,10 +38,10 @@ the flag altogether. Both the inviting client and the invitee's client should record the fact that the room is a direct chat by storing an `m.direct` event in the -account data using \_. +account data using [`/user//account_data/`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype). #### Server behaviour -When the `is_direct` flag is given to \_, the home server must set the +When the `is_direct` flag is given to [`/createRoom`](/client-server-api/#post_matrixclientr0createroom), the home server must set the `is_direct` flag in the invite member event for any users invited in the -\_ call. +[`/createRoom`](/client-server-api/#post_matrixclientr0createroom) call. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index d8d1051c7..b5a444a48 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -113,13 +113,13 @@ key, and a number of signed Curve25519 one-time keys. ##### Uploading keys A device uploads the public parts of identity keys to their homeserver -as a signed JSON object, using the `/keys/upload`\_ API. The JSON object +as a signed JSON object, using the [`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) API. The JSON object must include the public part of the device's Ed25519 key, and must be signed by that key, as described in [Signing JSON](/appendices/#signing-json). One-time keys are also uploaded to the homeserver using the -`/keys/upload`\_ API. +[`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) API. Devices must store the private part of each key they upload. They can discard the private part of a one-time key when they receive a message @@ -134,12 +134,12 @@ too many private keys may discard keys starting with the oldest. Before Alice can send an encrypted message to Bob, she needs a list of each of his devices and the associated identity keys, so that she can establish an encryption session with each device. This list can be -obtained by calling `/keys/query`\_, passing Bob's user ID in the +obtained by calling [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery), passing Bob's user ID in the `device_keys` parameter. From time to time, Bob may add new devices, and Alice will need to know this so that she can include his new devices for later encrypted -messages. A naive solution to this would be to call `/keys/query`\_ +messages. A naive solution to this would be to call [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) before sending each message -however, the number of users and devices may be large and this would be inefficient. @@ -157,23 +157,23 @@ process: list, and a separate flag to indicate that its list of Bob's devices is outdated. Both flags should be in storage which persists over client restarts. -2. It then makes a request to `/keys/query`\_, passing Bob's user ID in +2. It then makes a request to [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery), passing Bob's user ID in the `device_keys` parameter. When the request completes, it stores the resulting list of devices in persistent storage, and clears the 'outdated' flag. -3. During its normal processing of responses to \_, Alice's client - inspects the `changed` property of the `device_lists`\_ field. If it +3. During its normal processing of responses to [`/sync`](/client-server-api/#get_matrixclientr0sync), Alice's client + inspects the `changed` property of the [`device_lists`](/client-server-api/#extensions-to-sync-1) field. If it is tracking the device lists of any of the listed users, then it marks the device lists for those users outdated, and initiates - another request to `/keys/query`\_ for them. + another request to [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) for them. 4. Periodically, Alice's client stores the `next_batch` field of the - result from \_ in persistent storage. If Alice later restarts her + result from [`/sync`](/client-server-api/#get_matrixclientr0sync) in persistent storage. If Alice later restarts her client, it can obtain a list of the users who have updated their - device list while it was offline by calling `/keys/changes`\_, + device list while it was offline by calling [`/keys/changes`](/client-server-api/#get_matrixclientr0keyschanges), passing the recorded `next_batch` field as the `from` parameter. If the client is tracking the device list of any of the users listed in the response, it marks them as outdated. It combines this list with - those already flagged as outdated, and initiates a `/keys/query`\_ + those already flagged as outdated, and initiates a [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) request for all of them. {{% boxes/warning %}} @@ -342,7 +342,7 @@ Example: A client wanting to set up a session with another device can claim a one-time key for that device. This is done by making a request to the -`/keys/claim`\_ API. +[`/keys/claim`](/client-server-api/#post_matrixclientr0keysclaim) API. A homeserver should rate-limit the number of one-time keys that a given user or remote server can claim. A homeserver should discard the public @@ -466,11 +466,11 @@ process. After the handshake, the verification process begins. -{{m\_key\_verification\_request\_event}} +{{% event event="m.key.verification.request" %}} -{{m\_key\_verification\_start\_event}} +{{% event event="m.key.verification.start" %}} -{{m\_key\_verification\_cancel\_event}} +{{% event event="m.key.verification.cancel" %}} ##### Short Authentication String (SAS) verification @@ -634,13 +634,13 @@ following error codes are used in addition to those already specified: - `m.mismatched_commitment`: The hash commitment did not match. - `m.mismatched_sas`: The SAS did not match. -{{m\_key\_verification\_start\_m\_sas\_v1\_event}} +{{% event event="m.key.verification.start$m.sas.v1" %}} -{{m\_key\_verification\_accept\_event}} +{{% event event="m.key.verification.accept" %}} -{{m\_key\_verification\_key\_event}} +{{% event event="m.key.verification.key" %}} -{{m\_key\_verification\_mac\_event}} +{{% event event="m.key.verification.mac" %}} ###### HKDF calculation @@ -784,11 +784,11 @@ key, then Alice's device can trust Bob's master key, and she can sign it with her user-signing key. Users upload their cross-signing keys to the server using [POST -/\_matrix/client/r0/keys/device\_signing/upload](). When Alice uploads +/\_matrix/client/r0/keys/device\_signing/upload](/client-server-api/#post_matrixclientr0keysdevice_signingupload). When Alice uploads new cross-signing keys, her user ID will appear in the `changed` property of the `device_lists` field of the `/sync` of response of all users who share an encrypted room with her. When Bob sees Alice's user -ID in his `/sync`, he will call [POST /\_matrix/client/r0/keys/query]() +ID in his `/sync`, he will call [POST /\_matrix/client/r0/keys/query](/client-server-api/#post_matrixclientr0keysquery) to retrieve Alice's device and cross-signing keys. If Alice has a device and wishes to send an encrypted message to Bob, @@ -905,7 +905,7 @@ To avoid leaking of social graphs, servers will only allow users to see: Users will not be able to see signatures made by other users' user-signing keys. -{{cross\_signing\_cs\_http\_api}} +{{% http-api spec="client-server" api="cross_signing" %}} #### Sharing keys between devices @@ -959,8 +959,8 @@ be encrypted through the backup's `auth_data`; other clients can discover the backup by calling [GET /\_matrix/client/r0/room\_keys/version](#get_matrixclientr0room_keysversion). Keys are encrypted according to the backup's `auth_data` and added to the backup by calling [PUT -/\_matrix/client/r0/room\_keys/keys]() or one of its variants, and can -be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys](#put_matrixclientr0room_keyskeys) or +/\_matrix/client/r0/room\_keys/keys](#put_matrixclientr0room_keyskeys) or one of its variants, and can +be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys](#get_matrixclientr0room_keyskeys) or one of its variants. Keys can only be written to the most recently created version of the backup. Backups can also be deleted using [DELETE /\_matrix/client/r0/room\_keys/version/{version}](#delete_matrixclientr0room_keysversionversion), or individual keys @@ -1050,7 +1050,7 @@ The `session_data` field in the backups is constructed as follows: the resulting MAC are base64-encoded, and become the `mac` property of the `session_data`. -{{key\_backup\_cs\_http\_api}} +{{% http-api spec="client-server" api="key_backup" %}} ##### Key exports @@ -1241,7 +1241,7 @@ correspond to the user who sent the event, `recipient` to the local user, and `recipient_keys` to the local ed25519 key. Clients must confirm that the `sender_key` and the `ed25519` field value -under the `keys` property match the keys returned by `/keys/query`\_ for +under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) for the given user, and must also verify the signature of the payload. Without this check, a client cannot be sure that the sender device owns the private part of the ed25519 key it claims to have in the Olm @@ -1355,35 +1355,35 @@ messages. ##### Events -{{m\_room\_encryption\_event}} +{{% event event="m.room.encryption" %}} -{{m\_room\_encrypted\_event}} +{{% event event="m.room.encrypted" %}} -{{m\_room\_key\_event}} +{{% event event="m.room_key" %}} -{{m\_room\_key\_request\_event}} +{{% event event="m.room_key_request" %}} -{{m\_forwarded\_room\_key\_event}} +{{% event event="m.forwarded_room_key" %}} -{{m\_dummy\_event}} +{{% event event="m.dummy" %}} ##### Key management API -{{keys\_cs\_http\_api}} +{{% http-api spec="client-server" api="keys" %}} ##### Extensions to /sync -This module adds an optional `device_lists` property to the \_ response, +This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientr0sync) response, as specified below. The server need only populate this property for an incremental `/sync` (i.e., one where the `since` parameter was -specified). The client is expected to use `/keys/query`\_ or -`/keys/changes`\_ for the equivalent functionality after an initial +specified). The client is expected to use [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) or +[`/keys/changes`](/client-server-api/#get_matrixclientr0keyschanges) for the equivalent functionality after an initial sync, as documented in [Tracking the device list for a user](#tracking-the-device-list-for-a-user). It also adds a `one_time_keys_count` property. Note the spelling difference with the `one_time_key_counts` property in the -`/keys/upload`\_ response. +[`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) response. | Parameter | Type | Description | |----------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------| @@ -1451,4 +1451,4 @@ by including a `withheld` property in the `m.forwarded_room_key` message that is an object with the `code` and `reason` properties from the `m.room_key.withheld` message. -{{m\_room\_key\_withheld\_event}} +{{% event event="m.room_key.withheld" %}} diff --git a/content/client-server-api/modules/event_context.md b/content/client-server-api/modules/event_context.md index 32d7b9e8e..65b1a7a4f 100644 --- a/content/client-server-api/modules/event_context.md +++ b/content/client-server-api/modules/event_context.md @@ -14,7 +14,7 @@ an event. There is a single HTTP API for retrieving event context, documented below. -{{event\_context\_cs\_http\_api}} +{{% http-api spec="client-server" api="event_context" %}} #### Security considerations diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md index b68a8e018..7d04035e9 100644 --- a/content/client-server-api/modules/guest_access.md +++ b/content/client-server-api/modules/guest_access.md @@ -32,7 +32,7 @@ rather than allowing all homeservers to enforce the rules on each other. #### Events -{{m\_room\_guest\_access\_event}} +{{% event event="m.room.guest_access" %}} #### Client behaviour diff --git a/content/client-server-api/modules/history_visibility.md b/content/client-server-api/modules/history_visibility.md index 8eba36431..0a00f01ee 100644 --- a/content/client-server-api/modules/history_visibility.md +++ b/content/client-server-api/modules/history_visibility.md @@ -43,7 +43,7 @@ setting at that time was more restrictive. #### Events -{{m\_room\_history\_visibility\_event}} +{{% event event="m.room.history_visibility" %}} #### Client behaviour diff --git a/content/client-server-api/modules/ignore_users.md b/content/client-server-api/modules/ignore_users.md index 18fadb675..b67f5976c 100644 --- a/content/client-server-api/modules/ignore_users.md +++ b/content/client-server-api/modules/ignore_users.md @@ -11,13 +11,13 @@ and servers can implement the ignoring of users. #### Events -{{m\_ignored\_user\_list\_event}} +{{% event event="m.ignored_user_list" %}} #### Client behaviour To ignore a user, effectively blocking them, the client should add the target user to the `m.ignored_user_list` event in their account data -using \_. Once ignored, the client will no longer receive events sent by +using [`/user//account_data/`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by that user, with the exception of state events. The client should either hide previous content sent by the newly ignored user or perform a new `/sync` with no previous token. diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 8550a7aed..6f60d5a0d 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -11,9 +11,9 @@ room itself such as a room name and topic. #### Events -{{m\_room\_message\_event}} +{{% event event="m.room.message" %}} -{{m\_room\_message\_feedback\_event}} +{{% event event="m.room.message.feedback" %}} Usage of this event is discouraged for several reasons: - The number of feedback events will grow very quickly with the number @@ -24,13 +24,13 @@ Usage of this event is discouraged for several reasons: - There are no guarantees that the client has seen the event ID being acknowledged. -{{m\_room\_name\_event}} +{{% event event="m.room.name" %}} -{{m\_room\_topic\_event}} +{{% event event="m.room.topic" %}} -{{m\_room\_avatar\_event}} +{{% event event="m.room.avatar" %}} -{{m\_room\_pinned\_events\_event}} +{{% event event="m.room.pinned_events" %}} ##### m.room.message msgtypes @@ -116,7 +116,7 @@ extensible message formatting options, such as the proposal [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767). {{% /boxes/note %}} -{{msgtype\_events}} +{{% msgtypes %}} #### Client behaviour diff --git a/content/client-server-api/modules/moderation_policies.md b/content/client-server-api/modules/moderation_policies.md index 923df71e7..c164b1b1e 100644 --- a/content/client-server-api/modules/moderation_policies.md +++ b/content/client-server-api/modules/moderation_policies.md @@ -97,11 +97,11 @@ rules against rooms can describe a room ID or room alias - the subscriber is responsible for resolving the alias to a room ID if desired. -{{m\_policy\_rule\_user\_event}} +{{% event event="m.policy.rule.user" %}} -{{m\_policy\_rule\_room\_event}} +{{% event event="m.policy.rule.room" %}} -{{m\_policy\_rule\_server\_event}} +{{% event event="m.policy.rule.server" %}} #### Client behaviour diff --git a/content/client-server-api/modules/openid.md b/content/client-server-api/modules/openid.md index af8b31c9c..c51591fe4 100644 --- a/content/client-server-api/modules/openid.md +++ b/content/client-server-api/modules/openid.md @@ -10,4 +10,4 @@ service. The third party service does need to be matrix-aware in that it will need to know to resolve matrix homeservers to exchange the user's token for identity information. -{{openid\_cs\_http\_api}} +{{% http-api spec="client-server" api="openid" %}} diff --git a/content/client-server-api/modules/presence.md b/content/client-server-api/modules/presence.md index 83f9c560c..9944f086c 100644 --- a/content/client-server-api/modules/presence.md +++ b/content/client-server-api/modules/presence.md @@ -30,14 +30,14 @@ enum of one of the following: #### Events -{{presence\_events}} +{{% event-group group_name="m.presence" %}} #### Client behaviour Clients can manually set/get their presence using the HTTP APIs listed below. -{{presence\_cs\_http\_api}} +{{% http-api spec="client-server" api="presence" %}} ##### Last active ago diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 00b24cb4f..90546050a 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -90,7 +90,7 @@ Clients MUST configure a Pusher before they will receive push notifications. There is a single API endpoint for this, as described below. -{{pusher\_cs\_http\_api}} +{{% http-api spec="client-server" api="pusher" %}} ##### Listing Notifications @@ -98,7 +98,7 @@ A client can retrieve a list of events that it has been notified about. This may be useful so that users can see a summary of what important messages they have received. -{{notifications\_cs\_http\_api}} +{{% http-api spec="client-server" api="notifications" %}} ##### Receiving notifications @@ -658,7 +658,7 @@ Definition: Clients can retrieve, add, modify and remove push rules globally or per-device using the APIs below. -{{pushrules\_cs\_http\_api}} +{{% http-api spec="client-server" api="pushrules" %}} ##### Push Rules: Events @@ -666,7 +666,7 @@ When a user changes their push rules a `m.push_rules` event is sent to all clients in the `account_data` section of their next `/sync` request. The content of the event is the current push rules for the user. -{{m\_push\_rules\_event}} +{{% event event="m.push_rules" %}} ###### Examples diff --git a/content/client-server-api/modules/read_markers.md b/content/client-server-api/modules/read_markers.md index ccbafd260..a2c0150b7 100644 --- a/content/client-server-api/modules/read_markers.md +++ b/content/client-server-api/modules/read_markers.md @@ -24,7 +24,7 @@ The fully read marker is kept under an `m.fully_read` event. If the event does not exist on the user's account data, the fully read marker should be considered to be the user's read receipt location. -{{m\_fully\_read\_event}} +{{% event event="m.fully_read" %}} #### Client behaviour @@ -39,7 +39,7 @@ commonly updated at the same time, and therefore the client might wish to save an extra HTTP call. Providing an `m.read` location performs the same task as a request to `/receipt/m.read/$event:example.org`. -{{read\_markers\_cs\_http\_api}} +{{% http-api spec="client-server" api="read_markers" %}} #### Server behaviour diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index 423decead..fb28aacd7 100644 --- a/content/client-server-api/modules/receipts.md +++ b/content/client-server-api/modules/receipts.md @@ -24,7 +24,7 @@ information on how read receipts affect notification counts. Each `user_id`, `receipt_type` pair must be associated with only a single `event_id`. -{{m\_receipt\_event}} +{{% event event="m.receipt" %}} #### Client behaviour @@ -58,7 +58,7 @@ for events sent by their own user. A client can update the markers for its user by interacting with the following HTTP APIs. -{{receipts\_cs\_http\_api}} +{{% http-api spec="client-server" api="receipts" %}} #### Server behaviour diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index ff90207d8..c6157f3c5 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -14,7 +14,7 @@ offensive" and 0 is "inoffensive". #### Client behaviour -{{report\_content\_cs\_http\_api}} +{{% http-api spec="client-server" api="report_content" %}} #### Server behaviour diff --git a/content/client-server-api/modules/room_previews.md b/content/client-server-api/modules/room_previews.md index f33680672..ecaedcbd5 100644 --- a/content/client-server-api/modules/room_previews.md +++ b/content/client-server-api/modules/room_previews.md @@ -25,7 +25,7 @@ Clients can of course also call other endpoints such as [GET and [GET /search](#post_matrixclientr0search) to access events outside the `/events` stream. -{{peeking\_events\_cs\_http\_api}} +{{% http-api spec="client-server" api="peeking_events" %}} #### Server behaviour diff --git a/content/client-server-api/modules/room_upgrades.md b/content/client-server-api/modules/room_upgrades.md index 1e5437f3c..dbcb82334 100644 --- a/content/client-server-api/modules/room_upgrades.md +++ b/content/client-server-api/modules/room_upgrades.md @@ -11,7 +11,7 @@ to upgrade to a different room version when needed. #### Events -{{m\_room\_tombstone\_event}} +{{% event event="m.room.tombstone" %}} #### Client behaviour @@ -24,7 +24,7 @@ old room. Another approach may be to virtually merge the rooms such that the old room's timeline seamlessly continues into the new timeline without the user having to jump between the rooms. -{{room\_upgrades\_cs\_http\_api}} +{{% http-api spec="client-server" api="room_upgrades" %}} #### Server behaviour diff --git a/content/client-server-api/modules/search.md b/content/client-server-api/modules/search.md index 3dfe64639..2fa5bc44e 100644 --- a/content/client-server-api/modules/search.md +++ b/content/client-server-api/modules/search.md @@ -15,7 +15,7 @@ it won't include events in rooms that happened after you left. There is a single HTTP API for performing server-side search, documented below. -{{search\_cs\_http\_api}} +{{% http-api spec="client-server" api="search" %}} #### Search Categories diff --git a/content/client-server-api/modules/send_to_device.md b/content/client-server-api/modules/send_to_device.md index 5a8796373..16ce3e46b 100644 --- a/content/client-server-api/modules/send_to_device.md +++ b/content/client-server-api/modules/send_to_device.md @@ -13,26 +13,27 @@ client device. The primary motivation for this API is exchanging data that is meaningless or undesirable to persist in the room DAG - for example, one-time authentication tokens or key data. It is not intended for -conversational data, which should be sent using the normal \_ API for +conversational data, which should be sent using the normal [`/rooms//send`](/client-server-api/#put_matrixclientr0roomsroomidsendeventtypetxnid) API for consistency throughout Matrix. #### Client behaviour To send a message to other devices, a client should call -`/sendToDevice`\_. Only one message can be sent to each device per +[`/sendToDevice`](/client-server-api/#put_matrixclientr0sendtodeviceeventtypetxnid). Only one message can be sent to each device per transaction, and they must all have the same event type. The device ID in the request body can be set to `*` to request that the message be sent to all known devices. If there are send-to-device messages waiting for a client, they will be -returned by \_, as detailed in Extensions to /sync\_. Clients should +returned by [`/sync`](/client-server-api/#get_matrixclientr0sync), as detailed in [Extensions to /sync](/client-server-api/#extensions-to-sync). Clients should inspect the `type` of each returned event, and ignore any they do not understand. #### Server behaviour Servers should store pending messages for local users until they are -successfully delivered to the destination device. When a client calls \_ +successfully delivered to the destination device. When a client calls +[`/sync`](/client-server-api/#get_matrixclientr0sync) with an access token which corresponds to a device with pending messages, the server should list the pending messages, in order of arrival, in the response body. @@ -52,11 +53,11 @@ should be sent on to the remote servers via #### Protocol definitions -{{to\_device\_cs\_http\_api}} +{{% http-api spec="client-server" api="to_device" %}} ##### Extensions to /sync -This module adds the following properties to the \_ response: +This module adds the following properties to the [`/sync`](/client-server-api/#get_matrixclientr0sync) response: | Parameter | Type | Description | |-----------|-----------|-----------------------------------------------------------------------------| diff --git a/content/client-server-api/modules/server_acls.md b/content/client-server-api/modules/server_acls.md index 5ee09501e..fc3089155 100644 --- a/content/client-server-api/modules/server_acls.md +++ b/content/client-server-api/modules/server_acls.md @@ -16,7 +16,7 @@ set of servers, or retroactively make the room no longer federate with any other server, similar to setting the `m.federate` value on the [m.room.create](#mroomcreate) event. -{{m\_room\_server\_acl\_event}} +{{% event event="m.room.server_acl" %}} {{% boxes/note %}} Port numbers are not supported because it is unclear to parsers whether diff --git a/content/client-server-api/modules/server_notices.md b/content/client-server-api/modules/server_notices.md index 13bafc46f..199acd85b 100644 --- a/content/client-server-api/modules/server_notices.md +++ b/content/client-server-api/modules/server_notices.md @@ -36,7 +36,7 @@ maximum. New connections are being refused by the server. What defines "active" is left as an implementation detail, however servers are encouraged to treat syncing users as "active". -{{m\_room\_message\_m\_server\_notice\_event}} +{{% event event="m.room.message$m.server_notice" %}} #### Client behaviour diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 36615375f..eb6a0bb98 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -43,12 +43,12 @@ endpoints which consume the ticket. An overview of the process is as follows: -1. The Matrix client calls `GET /login`\_ to find the supported login +1. The Matrix client calls [`GET /login`](/client-server-api/#get_matrixclientr0login) to find the supported login types, and the homeserver includes a flow with `"type": "m.login.sso"` in the response. 2. To initiate the `m.login.sso` login type, the Matrix client instructs the user's browser to navigate to the - `/login/sso/redirect`\_ endpoint on the user's homeserver. + [`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) endpoint on the user's homeserver. 3. The homeserver responds with an HTTP redirect to the SSO user interface, which the browser follows. 4. The authentication server and the homeserver interact to verify the @@ -57,7 +57,7 @@ An overview of the process is as follows: 5. The browser is directed to the `redirectUrl` provided by the client with a `loginToken` query parameter for the client to log in with. 6. The client exchanges the login token for an access token by calling - the `/login`\_ endpoint with a `type` of `m.login.token`. + the [`/login`](/client-server-api/#post_matrixclientr0login) endpoint with a `type` of `m.login.token`. For native applications, typically steps 1 to 4 are carried out by opening an embedded web view. @@ -100,11 +100,11 @@ otherwise the same. ##### Client behaviour The client starts the process by instructing the browser to navigate to -`/login/sso/redirect`\_ with an appropriate `redirectUrl`. Once +[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) with an appropriate `redirectUrl`. Once authentication is successful, the browser will be redirected to that `redirectUrl`. -{{sso\_login\_redirect\_cs\_http\_api}} +{{% http-api spec="client-server" api="sso_login_redirect" %}} ###### Security considerations @@ -178,7 +178,7 @@ The homeserver then proceeds as follows: registered as a new user. 3. The homeserver should generate a short-term login token. This is an opaque token, suitable for use with the `m.login.token` type of the - `/login`\_ API. The lifetime of this token SHOULD be limited to + [`/login`](/client-server-api/#post_matrixclientr0login) API. The lifetime of this token SHOULD be limited to around five seconds. 4. The homeserver adds a query parameter of `loginToken`, with the value of the generated login token, to the `redirectUrl` given in diff --git a/content/client-server-api/modules/stickers.md b/content/client-server-api/modules/stickers.md index b705d9ac3..234ebba25 100644 --- a/content/client-server-api/modules/stickers.md +++ b/content/client-server-api/modules/stickers.md @@ -22,7 +22,7 @@ when the sticker image is clicked. Sticker events are received as a single `m.sticker` event in the `timeline` section of a room, in a `/sync`. -{{m\_sticker\_event}} +{{% event event="m.sticker" %}} #### Client behaviour diff --git a/content/client-server-api/modules/tags.md b/content/client-server-api/modules/tags.md index 94d455d20..c47be0c1d 100644 --- a/content/client-server-api/modules/tags.md +++ b/content/client-server-api/modules/tags.md @@ -59,8 +59,8 @@ tags are defined in the `m.*` namespace: - `m.server_notice`: Used to identify [Server Notice Rooms](#server-notices). -{{m\_tag\_event}} +{{% event event="m.tag" %}} #### Client Behaviour -{{tags\_cs\_http\_api}} +{{% http-api spec="client-server" api="tags" %}} diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index 3b37dd974..4a5c63e50 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -31,13 +31,13 @@ invitee does indeed own that third party identifier. See the #### Events -{{m\_room\_third\_party\_invite\_event}} +{{% event event="m.room.third_party_invite" %}} #### Client behaviour A client asks a server to invite a user by their third party identifier. -{{third\_party\_membership\_cs\_http\_api}} +{{% http-api spec="client-server" api="third_party_membership" %}} #### Server behaviour diff --git a/content/client-server-api/modules/third_party_networks.md b/content/client-server-api/modules/third_party_networks.md index 13142470b..40ca1883e 100644 --- a/content/client-server-api/modules/third_party_networks.md +++ b/content/client-server-api/modules/third_party_networks.md @@ -19,4 +19,4 @@ A client may wish to provide a rich interface for joining third party locations and connecting with third party users. Information necessary for such an interface is provided by third party lookups. -{{third\_party\_lookup\_cs\_http\_api}} +{{% http-api spec="client-server" api="third_party_lookup" %}} diff --git a/content/client-server-api/modules/typing_notifications.md b/content/client-server-api/modules/typing_notifications.md index d899b4e10..b9254cdb9 100644 --- a/content/client-server-api/modules/typing_notifications.md +++ b/content/client-server-api/modules/typing_notifications.md @@ -12,7 +12,7 @@ events scoped to a `room_id`. This means they do not form part of the #### Events -{{m\_typing\_event}} +{{% event event="m.typing" %}} #### Client behaviour @@ -33,7 +33,7 @@ recommended. When the user stops typing, the state change of the `boolean` to `false` should trigger another HTTP request to inform the server that the user has stopped typing. -{{typing\_cs\_http\_api}} +{{% http-api spec="client-server" api="typing" %}} #### Security considerations diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 31cd3fec2..db33eb4c0 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -15,7 +15,7 @@ send call events to rooms with exactly two participants. #### Events -{{voip\_events}} +{{% event-group group_name="m.call" %}} #### Client behaviour @@ -82,7 +82,7 @@ The homeserver MAY provide a TURN server which clients can use to contact the remote party. The following HTTP API endpoints will be used by clients in order to get information about the TURN server. -{{voip\_cs\_http\_api}} +{{% http-api spec="client-server" api="voip" %}} #### Security considerations diff --git a/content/identity-service-api.md b/content/identity-service-api.md index ef9d1bf0c..60115306c 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -172,7 +172,7 @@ header is inaccessible for the client. When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code `M_UNAUTHORIZED`. -{{v2\_auth\_is\_http\_api}} +{{% http-api spec="identity" api="v2_auth" %}} ## Terms of service @@ -196,15 +196,15 @@ the client should not expect that the server will not respond with another `M_TERMS_NOT_SIGNED` on their next request. The terms the user has just accepted are appended to `m.accepted_terms`. -{{m\_accepted\_terms\_event}} +{{% event event="m.accepted_terms" %}} -{{v2\_terms\_is\_http\_api}} +{{% http-api spec="identity" api="v2_terms" %}} ## Status check -{{ping\_is\_http\_api}} +{{% http-api spec="identity" api="ping" %}} -{{v2\_ping\_is\_http\_api}} +{{% http-api spec="identity" api="v2_ping" %}} ## Key management @@ -217,15 +217,15 @@ The identity server may also keep track of some short-term public-private keypairs, which may have different usage and lifetime characteristics than the service's long-term keys. -{{pubkey\_is\_http\_api}} +{{% http-api spec="identity" api="pubkey" %}} -{{v2\_pubkey\_is\_http\_api}} +{{% http-api spec="identity" api="v2_pubkey" %}} ## Association lookup -{{lookup\_is\_http\_api}} +{{% http-api spec="identity" api="lookup" %}} -{{v2\_lookup\_is\_http\_api}} +{{% http-api spec="identity" api="v2_lookup" %}} ### Client behaviour @@ -398,21 +398,21 @@ through without modification. ### Email associations -{{email\_associations\_is\_http\_api}} +{{% http-api spec="identity" api="email_associations" %}} -{{v2\_email\_associations\_is\_http\_api}} +{{% http-api spec="identity" api="v2_email_associations" %}} ### Phone number associations -{{phone\_associations\_is\_http\_api}} +{{% http-api spec="identity" api="phone_associations" %}} -{{v2\_phone\_associations\_is\_http\_api}} +{{% http-api spec="identity" api="v2_phone_associations" %}} ### General -{{associations\_is\_http\_api}} +{{% http-api spec="identity" api="associations" %}} -{{v2\_associations\_is\_http\_api}} +{{% http-api spec="identity" api="v2_associations" %}} ## Invitation storage @@ -427,9 +427,9 @@ the Matrix user's homeserver via the endpoint. The request MUST be signed with a long-term private key for the identity server. -{{store\_invite\_is\_http\_api}} +{{% http-api spec="identity" api="store_invite" %}} -{{v2\_store\_invite\_is\_http\_api}} +{{% http-api spec="identity" api="v2_store_invite" %}} ## Ephemeral invitation signing @@ -438,6 +438,6 @@ identity server offers some crypto functionality to help in accepting invitations. This is less secure than the client doing it itself, but may be useful where this isn't possible. -{{invitation\_signing\_is\_http\_api}} +{{% http-api spec="identity" api="invitation_signing" %}} -{{v2\_invitation\_signing\_is\_http\_api}} +{{% http-api spec="identity" api="v2_invitation_signing" %}} diff --git a/content/push-gateway-api.md b/content/push-gateway-api.md index a6a3d1a38..541db1296 100644 --- a/content/push-gateway-api.md +++ b/content/push-gateway-api.md @@ -54,4 +54,4 @@ Note that most of the values and behaviour of this endpoint is described by the Client-Server API's [Push Module](/client-server-api#push-notifications). -{{push\_notifier\_push\_http\_api}} +{{% http-api spec="push-gateway" api="push_notifier" %}} diff --git a/content/rooms/v1.md b/content/rooms/v1.md index 450eea6de..b76147df1 100644 --- a/content/rooms/v1.md +++ b/content/rooms/v1.md @@ -276,7 +276,7 @@ Some consequences of these rules: Events in version 1 rooms have the following structure: -{{definition\_ss\_pdu}} +{{% definition path="api/server-server/definitions/pdu" %}} ### Canonical JSON diff --git a/content/rooms/v3.md b/content/rooms/v3.md index 71d64c1a0..e1966b6e0 100644 --- a/content/rooms/v3.md +++ b/content/rooms/v3.md @@ -60,7 +60,7 @@ Additionally, the `auth_events` and `prev_events` have had a format change compared to other room versions to make it easier to handle. Instead of a tuple of values, they are now plain lists of events. -{{definition\_ss\_pdu\_v3}} +{{% definition path="api/server-server/definitions/pdu_v3" %}} ### Changes to APIs diff --git a/content/rooms/v4.md b/content/rooms/v4.md index d2aa8a236..c2853a2c3 100644 --- a/content/rooms/v4.md +++ b/content/rooms/v4.md @@ -58,4 +58,4 @@ receiving end of an event, the server should compute the relevant event ID for itself. Room version 3 also changes the format of `auth_events` and `prev_events` in a PDU. -{{definition\_ss\_pdu\_v4}} +{{% definition path="api/server-server/definitions/pdu_v4" %}} diff --git a/content/server-server-api.md b/content/server-server-api.md index 21d6b4956..32db92d7e 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -150,11 +150,11 @@ SNI is not supported and should not be sent. Servers are encouraged to make use of the [Certificate Transparency](https://www.certificate-transparency.org/) project. -{{wellknown\_ss\_http\_api}} +{{% http-api spec="server-server" api="wellknown" %}} ### Server implementation -{{version\_ss\_http\_api}} +{{% http-api spec="server-server" api="version" %}} ### Retrieving server keys @@ -190,7 +190,7 @@ Homeservers publish their signing keys in a JSON object at homeserver and for signing events. It contains a list of `old_verify_keys` which are only valid for signing events. -{{keys\_server\_ss\_http\_api}} +{{% http-api spec="server-server" api="keys_server" %}} #### Querying Keys Through Another Server @@ -205,7 +205,7 @@ Notary servers can return keys for servers that are offline or having issues serving their own keys by using cached responses. Keys can be queried from multiple servers to mitigate against DNS spoofing. -{{keys\_query\_ss\_http\_api}} +{{% http-api spec="server-server" api="keys_query" %}} ## Authentication @@ -308,7 +308,7 @@ pair of homeservers that exchanged it; they are not globally-meaningful. Transactions are limited in size; they can have at most 50 PDUs and 100 EDUs. -{{transactions\_ss\_http\_api}} +{{% http-api spec="server-server" api="transactions" %}} ## PDUs @@ -559,7 +559,7 @@ to check with other servers to ensure it is receiving the correct auth chain. These APIs give the homeserver an avenue for getting the information it needs. -{{event\_auth\_ss\_http\_api}} +{{% http-api spec="server-server" api="event_auth" %}} ## EDUs @@ -567,7 +567,7 @@ EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of "previous" IDs. They are intended to be non-persistent data such as user presence, typing notifications, etc. -{{definition\_ss\_edu}} +{{% definition path="api/server-server/definitions/edu" %}} ## Room State Resolution @@ -623,7 +623,7 @@ Similar to backfilling a room's history, a server may not have all the events in the graph. That server may use the `/get_missing_events` API to acquire the events it is missing. -{{backfill\_ss\_http\_api}} +{{% http-api spec="server-server" api="backfill" %}} ## Retrieving events @@ -632,7 +632,7 @@ information about the room which cannot be easily determined from backfilling. These APIs provide homeservers with the option of getting events and the state of the room at a given point in the timeline. -{{events\_ss\_http\_api}} +{{% http-api spec="server-server" api="events" %}} ## Joining Rooms @@ -688,7 +688,7 @@ in practice will use just two. The first part of the handshake usually involves using the directory server to request the room ID and join candidates through the -`/query/directory`\_ API endpoint. In the case of a new user joining a +[`/query/directory`](/server-server-api/#get_matrixfederationv1querydirectory) API endpoint. In the case of a new user joining a room as a result of a received invite, the joining user's homeserver could optimise this step away by picking the origin server of that invite message as the join candidate. However, the joining server should @@ -716,9 +716,9 @@ graph, and responds to the joining server with the full set of state for the newly-joined room. The resident server must also send the event to other servers participating in the room. -{{joins\_v1\_ss\_http\_api}} +{{% http-api spec="server-server" api="joins-v1" %}} -{{joins\_v2\_ss\_http\_api}} +{{% http-api spec="server-server" api="joins-v2" %}} ## Inviting to a room @@ -728,9 +728,9 @@ the process defined here. However, when a user invites another user on a different homeserver, a request to that homeserver to have the event signed and verified must be made. -{{invites\_v1\_ss\_http\_api}} +{{% http-api spec="server-server" api="invites-v1" %}} -{{invites\_v2\_ss\_http\_api}} +{{% http-api spec="server-server" api="invites-v2" %}} ## Leaving Rooms (Rejecting Invites) @@ -751,9 +751,9 @@ and replaces the `event_id` with its own. This is then sent to the resident server via `/send_leave`. The resident server will then send the event to other servers in the room. -{{leaving\_v1\_ss\_http\_api}} +{{% http-api spec="server-server" api="leaving-v1" %}} -{{leaving\_v2\_ss\_http\_api}} +{{% http-api spec="server-server" api="leaving-v2" %}} ## Third-party invites @@ -806,7 +806,7 @@ auth the event and send it. However, if the invited homeserver isn't in the room the invite came from, it will need to request the room's homeserver to auth the event. -{{third\_party\_invite\_ss\_http\_api}} +{{% http-api spec="server-server" api="third_party_invite" %}} #### Verifying the invite @@ -841,7 +841,7 @@ homeservers need a way to query the public rooms for another server. This can be done by making a request to the `/publicRooms` endpoint for the server the room directory should be retrieved for. -{{public\_rooms\_ss\_http\_api}} +{{% http-api spec="server-server" api="public_rooms" %}} ## Typing Notifications @@ -850,7 +850,7 @@ need to be sent to other servers in the room so their users are aware of the same state. Receiving servers should verify that the user is in the room, and is a user belonging to the sending server. -{{definition\_ss\_event\_schemas\_m\_typing}} +{{% definition path="api/server-server/definitions/event-schemas/m.typing" %}} ## Presence @@ -861,7 +861,7 @@ Servers should only send presence updates for users that the receiving server would be interested in. Such as the receiving server sharing a room with a given user. -{{definition\_ss\_event\_schemas\_m\_presence}} +{{% definition path="api/server-server/definitions/event-schemas/m.presence" %}} ## Receipts @@ -872,7 +872,7 @@ where in the event graph the user has read up to. Read receipts for events that a user sent do not need to be sent. It is implied that by sending the event the user has read up to the event. -{{definition\_ss\_event\_schemas\_m\_receipt}} +{{% definition path="api/server-server/definitions/event-schemas/m.receipt" %}} ## Querying for information @@ -885,7 +885,7 @@ There are several types of queries that can be made. The generic endpoint to represent all queries is described first, followed by the more specific queries that can be made. -{{query\_ss\_http\_api}} +{{% http-api spec="server-server" api="query" %}} ## OpenID @@ -897,7 +897,7 @@ without granting full access to the user's account. Access tokens generated by the OpenID API are only good for the OpenID API and nothing else. -{{openid\_ss\_http\_api}} +{{% http-api spec="server-server" api="openid" %}} ## Device Management @@ -943,9 +943,9 @@ recognise, it must resynchronise its list by calling the `stream_id` which should be used to correlate with subsequent `m.device_list_update` EDUs. -{{user\_devices\_ss\_http\_api}} +{{% http-api spec="server-server" api="user_devices" %}} -{{definition\_ss\_event\_schemas\_m\_device\_list\_update}} +{{% definition path="api/server-server/definitions/event-schemas/m.device_list_update" %}} ## End-to-End Encryption @@ -958,9 +958,9 @@ The APIs defined here are designed to be able to proxy much of the client's request through to federation, and have the response also be proxied through to the client. -{{user\_keys\_ss\_http\_api}} +{{% http-api spec="server-server" api="user_keys" %}} -{{definition\_ss\_event\_schemas\_m\_signing\_key\_update}} +{{% definition path="api/server-server/definitions/event-schemas/m.signing_key_update" %}} ## Send-to-device messaging @@ -971,7 +971,7 @@ involved. Each send-to-device message should be sent to the destination server using the following EDU: -{{definition\_ss\_event\_schemas\_m\_direct\_to\_device}} +{{% definition path="api/server-server/definitions/event-schemas/m.direct_to_device" %}} ## Content Repository diff --git a/data/api/application-service/definitions/location.yaml b/data/api/application-service/definitions/location.yaml new file mode 100644 index 000000000..5a0f92c88 --- /dev/null +++ b/data/api/application-service/definitions/location.yaml @@ -0,0 +1,32 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +properties: + alias: + description: An alias for a matrix room. + type: string + example: "#freenode_#matrix:matrix.org" + protocol: + description: The protocol ID that the third party location is a part of. + type: string + example: "irc" + fields: + description: Information used to identify this third party location. + type: object + example: { + "network": "freenode", + "channel": "#matrix" + } +required: ['alias', 'protocol', 'fields'] +title: Location +type: object \ No newline at end of file diff --git a/data/api/application-service/definitions/location_batch.yaml b/data/api/application-service/definitions/location_batch.yaml new file mode 100644 index 000000000..3f6de9df0 --- /dev/null +++ b/data/api/application-service/definitions/location_batch.yaml @@ -0,0 +1,17 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: array +description: List of matched third party locations. +items: + $ref: location.yaml diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml new file mode 100644 index 000000000..b16eedfcf --- /dev/null +++ b/data/api/application-service/definitions/protocol.yaml @@ -0,0 +1,113 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Protocol +type: object +properties: + user_fields: + description: |- + Fields which may be used to identify a third party user. These should be + ordered to suggest the way that entities may be grouped, where higher + groupings are ordered first. For example, the name of a network should be + searched before the nickname of a user. + type: array + items: + type: string + description: Field used to identify a third party user. + example: ["network", "nickname"] + location_fields: + description: |- + Fields which may be used to identify a third party location. These should be + ordered to suggest the way that entities may be grouped, where higher + groupings are ordered first. For example, the name of a network should be + searched before the name of a channel. + type: array + items: + type: string + description: Field used to identify a third party location. + example: ["network", "channel"] + icon: + description: A content URI representing an icon for the third party protocol. + type: string + example: "mxc://example.org/aBcDeFgH" + field_types: + title: Field Types + description: |- + The type definitions for the fields defined in the `user_fields` and + `location_fields`. Each entry in those arrays MUST have an entry here. The + `string` key for this object is field name itself. + + May be an empty object if no fields are defined. + type: object + additionalProperties: + title: Field Type + description: Definition of valid values for a field. + type: object + properties: + regexp: + description: |- + A regular expression for validation of a field's value. This may be relatively + coarse to verify the value as the application service providing this protocol + may apply additional validation or filtering. + type: string + placeholder: + description: An placeholder serving as a valid example of the field value. + type: string + required: ['regexp', 'placeholder'] + required: ['fieldname'] + example: { + "network": { + "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", + "placeholder": "irc.example.org" + }, + "nickname": { + "regexp": "[^\\s#]+", + "placeholder": "username" + }, + "channel": { + "regexp": "#[^\\s]+", + "placeholder": "#foobar" + } + } + instances: + description: |- + A list of objects representing independent instances of configuration. + For example, multiple networks on IRC if multiple are provided by the + same application service. + type: array + items: + type: object + title: Protocol Instance + properties: + desc: + type: string + description: A human-readable description for the protocol, such as the name. + example: "Freenode" + icon: + type: string + description: |- + An optional content URI representing the protocol. Overrides the one provided + at the higher level Protocol object. + example: "mxc://example.org/JkLmNoPq" + fields: + type: object + description: Preset values for `fields` the client may use to search by. + example: { + "network": "freenode" + } + network_id: + type: string + description: A unique identifier across all instances. + example: "freenode" + required: ['desc', 'fields', 'network_id'] +required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances'] diff --git a/data/api/application-service/definitions/protocol_metadata.yaml b/data/api/application-service/definitions/protocol_metadata.yaml new file mode 100644 index 000000000..e7bf45da6 --- /dev/null +++ b/data/api/application-service/definitions/protocol_metadata.yaml @@ -0,0 +1,70 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +description: Dictionary of supported third party protocols. +additionalProperties: + $ref: protocol.yaml +example: { + "irc": { + "user_fields": ["network", "nickname"], + "location_fields": ["network", "channel"], + "icon": "mxc://example.org/aBcDeFgH", + "field_types": { + "network": { + "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", + "placeholder": "irc.example.org" + }, + "nickname": { + "regexp": "[^\\s]+", + "placeholder": "username" + }, + "channel": { + "regexp": "#[^\\s]+", + "placeholder": "#foobar" + } + }, + "instances": [ + { + "network_id": "freenode", + "desc": "Freenode", + "icon": "mxc://example.org/JkLmNoPq", + "fields": { + "network": "freenode.net", + } + } + ] + }, + "gitter": { + "user_fields": ["username"], + "location_fields": ["room"], + "field_types": { + "username": { + "regexp": "@[^\\s]+", + "placeholder": "@username" + }, + "room": { + "regexp": "[^\\s]+\\/[^\\s]+", + "placeholder": "matrix-org/matrix-doc" + } + }, + "instances": [ + { + "network_id": "gitter", + "desc": "Gitter", + "icon": "mxc://example.org/zXyWvUt", + "fields": {} + } + ] + } +} \ No newline at end of file diff --git a/data/api/application-service/definitions/security.yaml b/data/api/application-service/definitions/security.yaml new file mode 100644 index 000000000..6d7edd3a4 --- /dev/null +++ b/data/api/application-service/definitions/security.yaml @@ -0,0 +1,18 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +homeserverAccessToken: + type: apiKey + description: The `hs_token` provided by the application service's registration. + name: access_token + in: query diff --git a/data/api/application-service/definitions/user.yaml b/data/api/application-service/definitions/user.yaml new file mode 100644 index 000000000..258e7c138 --- /dev/null +++ b/data/api/application-service/definitions/user.yaml @@ -0,0 +1,33 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# TODO: Change userid to user_id as a breaking change +properties: + userid: + description: A Matrix User ID represting a third party user. + type: string + example: "@_gitter_jim:matrix.org" + protocol: + description: The protocol ID that the third party location is a part of. + type: string + example: "gitter" + fields: + description: Information used to identify this third party location. + type: object + example: { + "user": "jim" + } +required: ['userid', 'protocol', 'fields'] +title: User +type: object \ No newline at end of file diff --git a/data/api/application-service/definitions/user_batch.yaml b/data/api/application-service/definitions/user_batch.yaml new file mode 100644 index 000000000..3653feb44 --- /dev/null +++ b/data/api/application-service/definitions/user_batch.yaml @@ -0,0 +1,17 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: array +description: List of matched third party users. +items: + $ref: user.yaml diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml new file mode 100644 index 000000000..32ac2c3ce --- /dev/null +++ b/data/api/application-service/protocols.yaml @@ -0,0 +1,279 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/app/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/thirdparty/protocol/{protocol}": + get: + summary: Retrieve metadata about a specific protocol that the application service supports. + description: |- + This API is called by the homeserver when it wants to present clients + with specific information about the various third party networks that + an application service supports. + operationId: getProtocolMetadata + security: + - homeserverAccessToken: [] + parameters: + - in: path + name: protocol + type: string + description: The protocol ID. + required: true + x-example: "irc" + responses: + 200: + description: The protocol was found and metadata returned. + schema: + $ref: definitions/protocol_metadata.yaml + 401: + description: |- + The homeserver has not supplied credentials to the application service. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 403: + description: |- + The credentials supplied by the homeserver were rejected. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 404: + description: No protocol was found with the given path. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + "/thirdparty/user/{protocol}": + get: + summary: Retrieve the Matrix User ID of a corresponding third party user. + description: |- + This API is called by the homeserver in order to retrieve a Matrix + User ID linked to a user on the third party network, given a set of + user parameters. + operationId: queryUserByProtocol + security: + - homeserverAccessToken: [] + parameters: + - in: path + name: protocol + type: string + description: The protocol ID. + required: true + x-example: irc + - in: query + name: fields... + type: string + description: |- + One or more custom fields that are passed to the application + service to help identify the user. + responses: + 200: + description: The Matrix User IDs found with the given parameters. + schema: + $ref: definitions/user_batch.yaml + 401: + description: |- + The homeserver has not supplied credentials to the application service. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 403: + description: |- + The credentials supplied by the homeserver were rejected. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 404: + description: No users were found with the given parameters. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + "/thirdparty/location/{protocol}": + get: + summary: Retrieve Matrix-side portal rooms leading to a third party location. + description: |- + Retrieve a list of Matrix portal rooms that lead to the matched third party location. + operationId: queryLocationByProtocol + security: + - homeserverAccessToken: [] + parameters: + - in: path + name: protocol + type: string + description: The protocol ID. + required: true + x-example: irc + - in: query + name: fields... + type: string + description: |- + One or more custom fields that are passed to the application + service to help identify the third party location. + responses: + 200: + description: At least one portal room was found. + schema: + $ref: definitions/location_batch.yaml + 401: + description: |- + The homeserver has not supplied credentials to the application service. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 403: + description: |- + The credentials supplied by the homeserver were rejected. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 404: + description: No mappings were found with the given parameters. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + "/thirdparty/location": + get: + summary: Reverse-lookup third party locations given a Matrix room alias. + description: |- + Retrieve an array of third party network locations from a Matrix room + alias. + operationId: queryLocationByAlias + security: + - homeserverAccessToken: [] + parameters: + - in: query + name: alias + type: string + description: The Matrix room alias to look up. + responses: + 200: + description: |- + All found third party locations. + schema: + $ref: definitions/location_batch.yaml + 401: + description: |- + The homeserver has not supplied credentials to the application service. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 403: + description: |- + The credentials supplied by the homeserver were rejected. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 404: + description: No mappings were found with the given parameters. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + "/thirdparty/user": + get: + summary: Reverse-lookup third party users given a Matrix User ID. + description: |- + Retrieve an array of third party users from a Matrix User ID. + operationId: queryUserByID + security: + - homeserverAccessToken: [] + parameters: + - in: query + name: userid + type: string + description: The Matrix User ID to look up. + responses: + 200: + description: |- + An array of third party users. + schema: + $ref: definitions/user_batch.yaml + 401: + description: |- + The homeserver has not supplied credentials to the application service. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 403: + description: |- + The credentials supplied by the homeserver were rejected. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 404: + description: No mappings were found with the given parameters. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml diff --git a/data/api/application-service/query_room.yaml b/data/api/application-service/query_room.yaml new file mode 100644 index 000000000..6ddc6234d --- /dev/null +++ b/data/api/application-service/query_room.yaml @@ -0,0 +1,90 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/app/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomAlias}": + get: + summary: Query if a room alias should exist on the application service. + description: |- + This endpoint is invoked by the homeserver on an application service to query + the existence of a given room alias. The homeserver will only query room + aliases inside the application service's `aliases` namespace. The + homeserver will send this request when it receives a request to join a + room alias within the application service's namespace. + operationId: queryRoomByAlias + security: + - homeserverAccessToken: [] + parameters: + - in: path + name: roomAlias + type: string + description: The room alias being queried. + required: true + x-example: "#magicforest:example.com" + responses: + 200: + description: |- + The application service indicates that this room alias exists. The + application service MUST have created a room and associated it with + the queried room alias using the client-server API. Additional + information about the room such as its name and topic can be set + before responding. + examples: + application/json: {} + schema: + type: object + 401: + description: |- + The homeserver has not supplied credentials to the application service. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 403: + description: |- + The credentials supplied by the homeserver were rejected. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 404: + description: |- + The application service indicates that this room alias does not exist. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml diff --git a/data/api/application-service/query_user.yaml b/data/api/application-service/query_user.yaml new file mode 100644 index 000000000..f8fc4ef1c --- /dev/null +++ b/data/api/application-service/query_user.yaml @@ -0,0 +1,87 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/app/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/users/{userId}": + get: + summary: Query if a user should exist on the application service. + description: |- + This endpoint is invoked by the homeserver on an application service to query + the existence of a given user ID. The homeserver will only query user IDs + inside the application service's `users` namespace. The homeserver will + send this request when it receives an event for an unknown user ID in + the application service's namespace, such as a room invite. + operationId: queryUserById + security: + - homeserverAccessToken: [] + parameters: + - in: path + name: userId + type: string + description: The user ID being queried. + required: true + x-example: "@alice:example.com" + responses: + 200: + description: |- + The application service indicates that this user exists. The application + service MUST create the user using the client-server API. + examples: + application/json: {} + schema: + type: object + 401: + description: |- + The homeserver has not supplied credentials to the application service. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 403: + description: |- + The credentials supplied by the homeserver were rejected. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml + 404: + description: |- + The application service indicates that this user does not exist. + Optional error information can be included in the body of this response. + examples: + application/json: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + schema: + $ref: ../client-server/definitions/errors/error.yaml diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml new file mode 100644 index 000000000..e4b62e01f --- /dev/null +++ b/data/api/application-service/transactions.yaml @@ -0,0 +1,77 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/app/v1 +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/transactions/{txnId}": + put: + summary: Send some events to the application service. + description: |- + This API is called by the homeserver when it wants to push an event + (or batch of events) to the application service. + + Note that the application service should distinguish state events + from message events via the presence of a `state_key`, rather than + via the event type. + operationId: sendTransaction + security: + - homeserverAccessToken: [] + parameters: + - in: path + name: txnId + type: string + description: |- + The transaction ID for this set of events. Homeservers generate + these IDs and they are used to ensure idempotency of requests. + required: true + x-example: "35" + - in: body + name: body + description: Transaction information + schema: + type: object + example: { + "events": [ + {"$ref": "../../event-schemas/examples/m.room.member.yaml"}, + {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} + ] + } + properties: + events: + type: array + description: |- + A list of events, formatted as per the Client-Server API. + items: + type: object + title: Event + required: ["events"] + responses: + 200: + description: The transaction was processed successfully. + examples: + application/json: {} + schema: + type: object diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml new file mode 100644 index 000000000..ec0d017f5 --- /dev/null +++ b/data/api/client-server/account-data.yaml @@ -0,0 +1,197 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Client Config API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user/{userId}/account_data/{type}": + put: + summary: Set some account_data for the user. + description: |- + Set some account_data for the client. This config is only visible to the user + that set the account_data. The config will be synced to clients in the + top-level `account_data`. + operationId: setAccountData + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The ID of the user to set account_data for. The access token must be + authorized to make requests for this user ID. + x-example: "@alice:example.com" + - in: path + type: string + name: type + required: true + description: |- + The event type of the account_data to set. Custom types should be + namespaced to avoid clashes. + x-example: "org.example.custom.config" + - in: body + name: content + required: true + description: |- + The content of the account_data + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value"} + responses: + 200: + description: + The account_data was successfully added. + tags: + - User data + get: + summary: Get some account_data for the user. + description: |- + Get some account_data for the client. This config is only visible to the user + that set the account_data. + operationId: getAccountData + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The ID of the user to get account_data for. The access token must be + authorized to make requests for this user ID. + x-example: "@alice:example.com" + - in: path + type: string + name: type + required: true + description: |- + The event type of the account_data to get. Custom types should be + namespaced to avoid clashes. + x-example: "org.example.custom.config" + responses: + 200: + description: + The account data content for the given type. + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value"} + tags: + - User data + "/user/{userId}/rooms/{roomId}/account_data/{type}": + put: + summary: Set some account_data for the user. + description: |- + Set some account_data for the client on a given room. This config is only + visible to the user that set the account_data. The config will be synced to + clients in the per-room `account_data`. + operationId: setAccountDataPerRoom + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The ID of the user to set account_data for. The access token must be + authorized to make requests for this user ID. + x-example: "@alice:example.com" + - in: path + type: string + name: roomId + required: true + description: |- + The ID of the room to set account_data on. + x-example: "!726s6s6q:example.com" + - in: path + type: string + name: type + required: true + description: |- + The event type of the account_data to set. Custom types should be + namespaced to avoid clashes. + x-example: "org.example.custom.room.config" + - in: body + name: content + required: true + description: |- + The content of the account_data + schema: + type: object + example: { + "custom_account_data_key": "custom_account_data_value"} + responses: + 200: + description: + The account_data was successfully added. + tags: + - User data + get: + summary: Get some account_data for the user. + description: |- + Get some account_data for the client on a given room. This config is only + visible to the user that set the account_data. + operationId: getAccountDataPerRoom + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The ID of the user to set account_data for. The access token must be + authorized to make requests for this user ID. + x-example: "@alice:example.com" + - in: path + type: string + name: roomId + required: true + description: |- + The ID of the room to get account_data for. + x-example: "!726s6s6q:example.com" + - in: path + type: string + name: type + required: true + description: |- + The event type of the account_data to get. Custom types should be + namespaced to avoid clashes. + x-example: "org.example.custom.room.config" + responses: + 200: + description: + The account data content for the given type. + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value"} + tags: + - User data diff --git a/data/api/client-server/admin.yaml b/data/api/client-server/admin.yaml new file mode 100644 index 000000000..8794a65c3 --- /dev/null +++ b/data/api/client-server/admin.yaml @@ -0,0 +1,115 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Administration API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/admin/whois/{userId}": + get: + summary: Gets information about a particular user. + description: |- + Gets information about a particular user. + + This API may be restricted to only be called by the user being looked + up, or by a server admin. Server-local administrator privileges are not + specified in this document. + operationId: getWhoIs + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: The user to look up. + required: true + x-example: "@peter:rabbit.rocks" + responses: + 200: + description: The lookup was successful. + examples: + application/json: { + "user_id": "@peter:rabbit.rocks", + "devices": { + "teapot": { + "sessions": [ + { + "connections": [ + { + "ip": "127.0.0.1", + "last_seen": 1411996332123, + "user_agent": "curl/7.31.0-DEV" + }, + { + "ip": "10.0.0.2", + "last_seen": 1411996332123, + "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36" + } + ] + } + ] + } + } + } + schema: + type: object + properties: + user_id: + type: string + description: The Matrix user ID of the user. + devices: + type: object + description: |- + Each key is an identifier for one of the user's devices. + additionalProperties: + type: object + title: DeviceInfo + properties: + sessions: + type: array + description: A user's sessions (i.e. what they did with an access token from one login). + items: + type: object + title: SessionInfo + properties: + connections: + type: array + description: Information particular connections in the session. + items: + type: object + title: ConnectionInfo + properties: + ip: + type: string + description: Most recently seen IP address of the session. + last_seen: + type: integer + format: int64 + description: Unix timestamp that the session was last active. + user_agent: + type: string + description: User agent string last seen in the session. + tags: + - Server administration diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml new file mode 100644 index 000000000..cea8538e5 --- /dev/null +++ b/data/api/client-server/administrative_contact.yaml @@ -0,0 +1,517 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Account Administrative Contact API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/account/3pid": + get: + summary: Gets a list of a user's third party identifiers. + description: |- + Gets a list of the third party identifiers that the homeserver has + associated with the user's account. + + This is *not* the same as the list of third party identifiers bound to + the user's Matrix ID in identity servers. + + Identifiers in this list may be used by the homeserver as, for example, + identifiers that it will accept to reset the user's account password. + operationId: getAccount3PIDs + security: + - accessToken: [] + responses: + 200: + description: The lookup was successful. + examples: + application/json: { + "threepids": [ + { + "medium": "email", + "address": "monkey@banana.island", + "validated_at": 1535176800000, + "added_at": 1535336848756 + } + ] + } + schema: + type: object + properties: + threepids: + type: array + items: + type: object + title: Third party identifier + properties: + medium: + type: string + description: The medium of the third party identifier. + enum: ["email", "msisdn"] + address: + type: string + description: The third party identifier address. + validated_at: + type: integer + format: int64 + description: |- + The timestamp, in milliseconds, when the identifier was + validated by the identity server. + added_at: + type: integer + format: int64 + description: + The timestamp, in milliseconds, when the homeserver + associated the third party identifier with the user. + required: ['medium', 'address', 'validated_at', 'added_at'] + tags: + - User data + post: + summary: Adds contact information to the user's account. + description: |- + Adds contact information to the user's account. + + This endpoint is deprecated in favour of the more specific `/3pid/add` + and `/3pid/bind` endpoints. + + **Note:** + Previously this endpoint supported a `bind` parameter. This parameter + has been removed, making this endpoint behave as though it was `false`. + This results in this endpoint being an equivalent to `/3pid/bind` rather + than dual-purpose. + operationId: post3PIDs + deprecated: true + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + three_pid_creds: + title: "ThreePidCredentials" + type: object + description: The third party credentials to associate with the account. + properties: + client_secret: + type: string + description: The client secret used in the session with the identity server. + id_server: + type: string + description: The identity server to use. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + sid: + type: string + description: The session identifier given by the identity server. + required: ["client_secret", "id_server", "id_access_token", "sid"] + required: ["three_pid_creds"] + example: { + "three_pid_creds": { + "id_server": "matrix.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "d0n'tT3ll" + } + } + responses: + 200: + description: The addition was successful. + examples: + application/json: { + "submit_url": "https://example.org/path/to/submitToken" + } + schema: + type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's `POST + /validate/email/submitToken` endpoint (without the requirement + for an access token). The homeserver must send this token to the + user (if applicable), who should then be prompted to provide it + to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement + provided the homeserver advertises this specification version + in the `/versions` response (ie: r0.5.0). + example: "https://example.org/path/to/submitToken" + 403: + description: The credentials could not be verified with the identity server. + examples: + application/json: { + "errcode": "M_THREEPID_AUTH_FAILED", + "error": "The third party credentials could not be verified by the identity server." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - User data + "/account/3pid/add": + post: + summary: Adds contact information to the user's account. + description: |- + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + Adds contact information to the user's account. Homeservers should use 3PIDs added + through this endpoint for password resets instead of relying on the identity server. + + Homeservers should prevent the caller from adding a 3PID to their account if it has + already been added to another user's account on the homeserver. + operationId: add3PID + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: "definitions/auth_data.yaml" + client_secret: + type: string + description: The client secret used in the session with the homeserver. + sid: + type: string + description: The session identifier given by the homeserver. + required: ["client_secret", "sid"] + example: { + "sid": "abc123987", + "client_secret": "d0n'tT3ll" + } + responses: + 200: + description: The addition was successful. + examples: + application/json: {} + schema: + type: object + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + "/account/3pid/bind": + post: + summary: Binds a 3PID to the user's account through an Identity Service. + description: |- + Binds a 3PID to the user's account through the specified identity server. + + Homeservers should not prevent this request from succeeding if another user + has bound the 3PID. Homeservers should simply proxy any errors received by + the identity server to the caller. + + Homeservers should track successful binds so they can be unbound later. + operationId: bind3PID + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + client_secret: + type: string + description: The client secret used in the session with the identity server. + id_server: + type: string + description: The identity server to use. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. + sid: + type: string + description: The session identifier given by the identity server. + required: ["client_secret", "id_server", "id_access_token", "sid"] + example: { + "id_server": "example.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "d0n'tT3ll" + } + responses: + 200: + description: The addition was successful. + examples: + application/json: {} + schema: + type: object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data + "/account/3pid/delete": + post: + summary: Deletes a third party identifier from the user's account + description: |- + Removes a third party identifier from the user's account. This might not + cause an unbind of the identifier from the identity server. + + Unlike other endpoints, this endpoint does not take an `id_access_token` + parameter because the homeserver is expected to sign the request to the + identity server instead. + operationId: delete3pidFromAccount + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + id_server: + type: string + description: |- + The identity server to unbind from. If not provided, the homeserver + MUST use the `id_server` the identifier was added through. If the + homeserver does not know the original `id_server`, it MUST return + a `id_server_unbind_result` of `no-support`. + example: "example.org" + medium: + type: string + description: The medium of the third party identifier being removed. + enum: ["email", "msisdn"] + example: "email" + address: + type: string + description: The third party address being removed. + example: "example@example.org" + required: ['medium', 'address'] + responses: + 200: + description: |- + The homeserver has disassociated the third party identifier from the + user. + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + # XXX: I don't know why, but the order matters here so that "no-support" + # doesn't become "no- support" by the renderer. + - "no-support" + - "success" + description: |- + An indicator as to whether or not the homeserver was able to unbind + the 3PID from the identity server. `success` indicates that the + indentity server has unbound the identifier whereas `no-support` + indicates that the identity server refuses to support the request + or the homeserver was not able to determine an identity server to + unbind from. + example: "success" + required: + - id_server_unbind_result + tags: + - User data + "/account/3pid/unbind": + post: + summary: Removes a user's third party identifier from an identity server. + description: |- + Removes a user's third party identifier from the provided identity server + without removing it from the homeserver. + + Unlike other endpoints, this endpoint does not take an `id_access_token` + parameter because the homeserver is expected to sign the request to the + identity server instead. + operationId: unbind3pidFromAccount + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + id_server: + type: string + description: |- + The identity server to unbind from. If not provided, the homeserver + MUST use the `id_server` the identifier was added through. If the + homeserver does not know the original `id_server`, it MUST return + a `id_server_unbind_result` of `no-support`. + example: "example.org" + medium: + type: string + description: The medium of the third party identifier being removed. + enum: ["email", "msisdn"] + example: "email" + address: + type: string + description: The third party address being removed. + example: "example@example.org" + required: ['medium', 'address'] + responses: + 200: + description: |- + The identity server has disassociated the third party identifier from the + user. + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + # XXX: I don't know why, but the order matters here so that "no-support" + # doesn't become "no- support" by the renderer. + - "no-support" + - "success" + description: |- + An indicator as to whether or not the identity server was able to unbind + the 3PID. `success` indicates that the identity server has unbound the + identifier whereas `no-support` indicates that the identity server + refuses to support the request or the homeserver was not able to determine + an identity server to unbind from. + example: "success" + required: + - id_server_unbind_result + tags: + - User data + "/account/3pid/email/requestToken": + post: + summary: Begins the validation process for an email address for association with the user's account. + description: |- + The homeserver must check that the given email address is **not** + already associated with an account on this homeserver. This API should + be used to request validation tokens when adding an email address to an + account. This API's parameters and response are identical to that of + the [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken) + endpoint. The homeserver should validate + the email itself, either by sending a validation email itself or by using + a service it has control over. + operationId: requestTokenTo3PIDEmail + parameters: + - in: body + name: body + required: true + schema: + $ref: "definitions/request_email_validation.yaml" + responses: + 200: + description: |- + An email was sent to the given address. Note that this may be an + email containing the validation token or it may be informing the + user of an error. + schema: + $ref: "definitions/request_token_response.yaml" + 403: + description: |- + The homeserver does not allow the third party identifier as a + contact option. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_DENIED", + "error": "Third party identifier is not allowed" + } + 400: + description: |- + The third party identifier is already in use on the homeserver, or + the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + can be returned if the server does not trust/support the identity server + provided in the request. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "Third party identifier already in use" + } + "/account/3pid/msisdn/requestToken": + post: + summary: Begins the validation process for a phone number for association with the user's account. + description: |- + The homeserver must check that the given phone number is **not** + already associated with an account on this homeserver. This API should + be used to request validation tokens when adding a phone number to an + account. This API's parameters and response are identical to that of + the [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken) + endpoint. The homeserver should validate + the phone number itself, either by sending a validation message itself or by using + a service it has control over. + operationId: requestTokenTo3PIDMSISDN + parameters: + - in: body + name: body + required: true + schema: + $ref: "definitions/request_msisdn_validation.yaml" + responses: + 200: + description: An SMS message was sent to the given phone number. + schema: + $ref: "definitions/request_token_response.yaml" + 403: + description: |- + The homeserver does not allow the third party identifier as a + contact option. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_DENIED", + "error": "Third party identifier is not allowed" + } + 400: + description: |- + The third party identifier is already in use on the homeserver, or + the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + can be returned if the server does not trust/support the identity server + provided in the request. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "Third party identifier already in use" + } diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml new file mode 100644 index 000000000..ec0470c39 --- /dev/null +++ b/data/api/client-server/appservice_room_directory.yaml @@ -0,0 +1,88 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Application Service Room Directory API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + # Note: this is the same access_token definition used elsewhere in the client + # server API, however this expects an access token for an application service. + $ref: definitions/security.yaml +paths: + "/directory/list/appservice/{networkId}/{roomId}": + put: + summary: |- + Updates a room's visibility in the application service's room directory. + description: |- + Updates the visibility of a given room on the application service's room + directory. + + This API is similar to the room directory visibility API used by clients + to update the homeserver's more general room directory. + + This API requires the use of an application service access token (`as_token`) + instead of a typical client's access_token. This API cannot be invoked by + users who are not identified as application services. + operationId: updateAppserviceRoomDirectoryVsibility + parameters: + - in: path + type: string + name: networkId + description: |- + The protocol (network) ID to update the room list for. This would + have been provided by the application service as being listed as + a supported protocol. + required: true + x-example: "irc" + - in: path + type: string + name: roomId + description: The room ID to add to the directory. + required: true + x-example: "!somewhere:example.org" + - in: body + name: body + required: true + schema: + type: object + properties: + visibility: + type: string + enum: ["public", "private"] + description: |- + Whether the room should be visible (public) in the directory + or not (private). + example: "public" + required: ['visibility'] + security: + # again, this is the appservice's token - not a typical client's + - accessToken: [] + responses: + 200: + description: The room's directory visibility has been updated. + schema: + type: object + examples: + application/json: {} + tags: + - Application service room directory management diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml new file mode 100644 index 000000000..5c6e7ee32 --- /dev/null +++ b/data/api/client-server/banning.yaml @@ -0,0 +1,148 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Banning API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/ban": + post: + summary: Ban a user in the room. + 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 or be invited to it until they are unbanned. + + The caller must have the required power level in order to perform this operation. + operationId: ban + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier (not alias) from which the user should be banned. + 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 banned. + reason: + type: string + description: The reason the user has been banned. This will be supplied as the + `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. + required: ["user_id"] + responses: + 200: + description: The user has been kicked and banned from the room. + examples: + application/json: { + } + schema: + type: object + 403: + description: |- + You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + + - The banner is not currently in the room. + - The banner's power level is insufficient to ban users from the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You do not have a high enough power level to ban from this room." + } + schema: + "$ref": "definitions/errors/error.yaml" + 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. + operationId: unban + 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", + "reason": "They've been banned long enough" + } + properties: + user_id: + type: string + description: The fully qualified user ID of the user being unbanned. + reason: + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + 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." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room membership diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml new file mode 100644 index 000000000..ece0d9adb --- /dev/null +++ b/data/api/client-server/capabilities.yaml @@ -0,0 +1,112 @@ +# Copyright 2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Capabilities API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/capabilities": + get: + summary: Gets information about the server's capabilities. + description: |- + Gets information about the server's supported feature set + and other relevant capabilities. + operationId: getCapabilities + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: + The capabilities of the server. + examples: + application/json: { + "capabilities": { + "m.change_password": { + "enabled": false + }, + "m.room_versions": { + "default": "1", + "available": { + "1": "stable", + "2": "stable", + "3": "unstable", + "test-version": "unstable" + } + }, + "com.example.custom.ratelimit": { + "max_requests_per_hour": 600 + } + } + } + schema: + type: object + required: ["capabilities"] + properties: + capabilities: + type: object + title: Capabilities + description: |- + The custom capabilities the server supports, using the + Java package naming convention. + additionalProperties: + type: object + properties: + "m.change_password": + type: object + description: |- + Capability to indicate if the user can change their password. + title: ChangePasswordCapability + properties: + enabled: + type: boolean + description: |- + True if the user can change their password, false otherwise. + example: false + required: ['enabled'] + "m.room_versions": + type: object + description: The room versions the server supports. + title: RoomVersionsCapability + properties: + default: + type: string + description: |- + The default room version the server is using for new rooms. + example: "1" + available: + type: object + description: |- + A detailed description of the room versions the server supports. + additionalProperties: + type: string + title: RoomVersionStability + enum: [stable, unstable] + description: The stability of the room version. + required: ['default', 'available'] + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Capabilities diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml new file mode 100644 index 000000000..c36fa837d --- /dev/null +++ b/data/api/client-server/content-repo.yaml @@ -0,0 +1,451 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Content Repository API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/media/%CLIENT_MAJOR_VERSION% +consumes: + - application/json + - "*/*" +produces: + - application/json + - "*/*" +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/upload": + post: + summary: Upload some content to the content repository. + operationId: uploadContent + produces: ["application/json"] + security: + - accessToken: [] + parameters: + - in: header + name: Content-Type + type: string + description: The content type of the file being uploaded + x-example: "application/pdf" + - in: query + type: string + x-example: "War and Peace.pdf" + name: filename + description: The name of the file being uploaded + - in: body + name: "" + description: The content to be uploaded. + required: true + x-example: "" # so the spec shows "" without quotes. + schema: + type: string + example: "" + format: byte + responses: + 200: + description: The [MXC URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content. + schema: + type: object + required: ["content_uri"] + properties: + content_uri: + type: string + description: "The [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the uploaded content." + examples: + application/json: { + "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" + } + 403: + description: |- + The user does not have permission to upload the content. Some reasons for this error include: + + - The server does not permit the file type. + - The user has reached a quota for uploaded content. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + schema: + "$ref": "definitions/errors/error.yaml" + 413: + description: |- + The uploaded content is too large for the server. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Cannot upload files larger than 100mb" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/download/{serverName}/{mediaId}": + get: + summary: "Download content from the content repository." + operationId: getContent + produces: ["*/*"] + parameters: + - in: path + type: string + name: serverName + x-example: matrix.org + required: true + description: | + The server name from the `mxc://` URI (the authoritory component) + - in: path + type: string + name: mediaId + x-example: ascERGshawAWawugaAcauga + required: true + description: | + The media ID from the `mxc://` URI (the path component) + - in: query + type: boolean + name: allow_remote + x-example: false + required: false + default: true + description: | + Indicates to the server that it should not attempt to fetch the media if it is deemed + remote. This is to prevent routing loops where the server contacts itself. Defaults to + true if not provided. + responses: + 200: + description: "The content that was previously uploaded." + headers: + Content-Type: + description: "The content type of the file that was previously uploaded." + type: "string" + Content-Disposition: + description: |- + The name of the file that was previously uploaded, if set. + type: "string" + schema: + type: file + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + 502: + description: |- + The content is too large for the server to serve. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/download/{serverName}/{mediaId}/{fileName}": + get: + summary: Download content from the content repository overriding the file name + description: |- + This will download content from the content repository (same as + the previous endpoint) but replace the target file name with the one + provided by the caller. + operationId: getContentOverrideName + produces: ["*/*"] + parameters: + - in: path + type: string + name: serverName + x-example: matrix.org + required: true + description: | + The server name from the `mxc://` URI (the authoritory component) + - in: path + type: string + name: mediaId + x-example: ascERGshawAWawugaAcauga + required: true + description: | + The media ID from the `mxc://` URI (the path component) + - in: path + type: string + name: fileName + x-example: filename.jpg + required: true + description: A filename to give in the `Content-Disposition` header. + - in: query + type: boolean + name: allow_remote + x-example: false + required: false + default: true + description: | + Indicates to the server that it should not attempt to fetch the media if it is deemed + remote. This is to prevent routing loops where the server contacts itself. Defaults to + true if not provided. + responses: + 200: + description: "The content that was previously uploaded." + headers: + Content-Type: + description: "The content type of the file that was previously uploaded." + type: "string" + Content-Disposition: + description: |- + The `fileName` requested or the name of the file that was previously + uploaded, if set. + type: "string" + schema: + type: file + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + 502: + description: |- + The content is too large for the server to serve. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/thumbnail/{serverName}/{mediaId}": + get: + summary: Download a thumbnail of content from the content repository + description: |- + Download a thumbnail of content from the content repository. + See the [Thumbnails](/client-server-api/#thumbnails) section for more information. + operationId: getContentThumbnail + produces: ["image/jpeg", "image/png"] + parameters: + - in: path + type: string + name: serverName + required: true + x-example: example.org + description: | + The server name from the `mxc://` URI (the authoritory component) + - in: path + type: string + name: mediaId + x-example: ascERGshawAWawugaAcauga + required: true + description: | + The media ID from the `mxc://` URI (the path component) + - in: query + type: integer + x-example: 64 + name: width + required: true + description: |- + The *desired* width of the thumbnail. The actual thumbnail may be + larger than the size specified. + - in: query + type: integer + x-example: 64 + name: height + required: true + description: |- + The *desired* height of the thumbnail. The actual thumbnail may be + larger than the size specified. + - in: query + type: string + enum: ["crop", "scale"] + name: method + x-example: "scale" + description: |- + The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails) + section for more information. + - in: query + type: boolean + name: allow_remote + x-example: false + required: false + default: true + description: |- + Indicates to the server that it should not attempt to fetch + the media if it is deemed remote. This is to prevent routing loops + where the server contacts itself. Defaults to true if not provided. + responses: + 200: + description: "A thumbnail of the requested content." + headers: + Content-Type: + description: "The content type of the thumbnail." + type: "string" + enum: ["image/jpeg", "image/png"] + schema: + type: file + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the thumbnail." + 400: + description: |- + The request does not make sense to the server, or the server cannot thumbnail + the content. For example, the client requested non-integer dimensions or asked + for negatively-sized images. + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + schema: + "$ref": "definitions/errors/error.yaml" + 413: + description: |- + The local content is too large for the server to thumbnail. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + schema: + "$ref": "definitions/errors/error.yaml" + 502: + description: |- + The remote content is too large for the server to thumbnail. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/preview_url": + get: + summary: "Get information about a URL for a client" + description: |- + Get information about a URL for the client. Typically this is called when a + client sees a URL in a message and wants to render a preview for the user. + + **Note:** + Clients should consider avoiding this endpoint for URLs posted in encrypted + rooms. Encrypted rooms often contain more sensitive information the users + do not want to share with the homeserver, and this can mean that the URLs + being shared should also not be shared with the homeserver. + + operationId: getUrlPreview + produces: ["application/json"] + security: + - accessToken: [] + parameters: + - in: query + type: string + x-example: "https://matrix.org" + name: url + description: "The URL to get a preview of." + required: true + - in: query + type: integer + format: int64 + x-example: 1510610716656 + name: ts + description: |- + The preferred point in time to return a preview for. The server may + return a newer version if it does not have the requested version + available. + responses: + 200: + description: |- + The OpenGraph data for the URL, which may be empty. Some values are + replaced with matrix equivalents if they are provided in the response. + The differences from the OpenGraph protocol are described here. + schema: + type: object + properties: + "matrix:image:size": + type: integer + format: int64 + description: |- + The byte-size of the image. Omitted if there is no image attached. + "og:image": + type: string + description: |- + An [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image. + examples: + application/json: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/config": + get: + summary: Get the configuration for the content repository. + description: |- + This endpoint allows clients to retrieve the configuration of the content + repository, such as upload limitations. + Clients SHOULD use this as a guide when using content repository endpoints. + All values are intentionally left optional. Clients SHOULD follow + the advice given in the field description when the field is not available. + + **NOTE:** Both clients and server administrators should be aware that proxies + between the client and the server may affect the apparent behaviour of content + repository APIs, for example, proxies may enforce a lower upload size limit + than is advertised by the server on this endpoint. + operationId: getConfig + produces: ["application/json"] + security: + - accessToken: [] + responses: + 200: + description: The public content repository configuration for the matrix server. + schema: + type: object + properties: + m.upload.size: + type: integer + format: int64 + description: |- + The maximum size an upload can be in bytes. + Clients SHOULD use this as a guide when uploading content. + If not listed or null, the size limit should be treated as unknown. + examples: + application/json: { + "m.upload.size": 50000000 + } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/error.yaml" + + tags: + - Media diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml new file mode 100644 index 000000000..fc558c03d --- /dev/null +++ b/data/api/client-server/create_room.yaml @@ -0,0 +1,268 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Creation API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/createRoom": + post: + summary: Create a new room + description: |- + Create a new room with various configuration options. + + The server MUST apply the normal state resolution rules when creating + the new room, including checking power levels for each event. It MUST + apply the events implied by the request in the following order: + + 1. The `m.room.create` event itself. Must be the first event in the + room. + + 2. An `m.room.member` event for the creator to join the room. This is + needed so the remaining events can be sent. + + 3. A default `m.room.power_levels` event, giving the room creator + (and not other members) permission to send state events. Overridden + by the `power_level_content_override` parameter. + + 4. Events set by the `preset`. Currently these are the `m.room.join_rules`, + `m.room.history_visibility`, and `m.room.guest_access` state events. + + 5. Events listed in `initial_state`, in the order that they are + listed. + + 6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` + state events). + + 7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with + `membership: invite` and `m.room.third_party_invite`). + + The available presets do the following with respect to room state: + + | Preset | `join_rules` | `history_visibility` | `guest_access` | Other | + |------------------------|--------------|----------------------|----------------|-------| + | `private_chat` | `invite` | `shared` | `can_join` | | + | `trusted_private_chat` | `invite` | `shared` | `can_join` | All invitees are given the same power level as the room creator. | + | `public_chat` | `public` | `shared` | `forbidden` | | + + The server will create a `m.room.create` event in the room with the + requesting user as the creator, alongside other keys provided in the + `creation_content`. + operationId: createRoom + security: + - accessToken: [] + parameters: + - in: body + name: body + description: The desired room configuration. + required: true + schema: + type: object + example: { + "preset": "public_chat", + "room_alias_name": "thepub", + "name": "The Grand Duke Pub", + "topic": "All about happy hour", + "creation_content": { + "m.federate": false + } + } + properties: + visibility: + type: string + enum: ["public", "private"] + description: |- + A `public` visibility indicates that the room will be shown + in the published room list. A `private` visibility will hide + the room from the published room list. Rooms default to + `private` visibility if this key is not included. NB: This + should not be confused with `join_rules` which also uses the + word `public`. + room_alias_name: + type: string + description: |- + The desired room alias **local part**. If this is included, a + room alias will be created and mapped to the newly created + room. The alias will belong on the *same* homeserver which + created the room. For example, if this was set to "foo" and + sent to the homeserver "example.com" the complete room alias + would be `#foo:example.com`. + + The complete room alias will become the canonical alias for + the room. + name: + type: string + description: |- + If this is included, an `m.room.name` event will be sent + into the room to indicate the name of the room. See Room + Events for more information on `m.room.name`. + topic: + type: string + description: |- + If this is included, an `m.room.topic` event will be sent + into the room to indicate the topic for the room. See Room + Events for more information on `m.room.topic`. + invite: + type: array + description: |- + A list of user IDs to invite to the room. This will tell the + server to invite everyone in the list to the newly created room. + items: + type: string + invite_3pid: + type: array + description: |- + A list of objects representing third party IDs to invite into + the room. + items: + type: object + title: Invite3pid + properties: + id_server: + type: string + description: The hostname+port of the identity server which should be used for third party identifier lookups. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + medium: + type: string + # TODO: Link to Identity Service spec when it eixsts + description: The kind of address being passed in the address field, for example `email`. + address: + type: string + description: The invitee's third party identifier. + required: ["id_server", "id_access_token", "medium", "address"] + room_version: + type: string + description: |- + The room version to set for the room. If not provided, the homeserver is + to use its configured default. If provided, the homeserver will return a + 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not + support the room version. + example: "1" + creation_content: + title: CreationContent + type: object + description: |- + Extra keys, such as `m.federate`, to be added to the content + of the [`m.room.create`](client-server-api/#mroomcreate) event. The server will clobber the following + keys: `creator`, `room_version`. Future versions of the specification + may allow the server to clobber other keys. + initial_state: + type: array + description: |- + A list of state events to set in the new room. This allows + the user to override the default state events set in the new + room. The expected format of the state events are an object + with type, state_key and content keys set. + + Takes precedence over events set by `preset`, but gets + overriden by `name` and `topic` keys. + items: + type: object + title: StateEvent + properties: + type: + type: string + description: The type of event to send. + state_key: + type: string + description: The state_key of the state event. Defaults to an empty string. + content: + type: object + description: The content of the event. + required: ["type", "content"] + preset: + type: string + enum: ["private_chat", "public_chat", "trusted_private_chat"] + description: |- + Convenience parameter for setting various default state events + based on a preset. + + If unspecified, the server should use the `visibility` to determine + which preset to use. A visbility of `public` equates to a preset of + `public_chat` and `private` visibility equates to a preset of + `private_chat`. + is_direct: + type: boolean + description: |- + This flag makes the server set the `is_direct` flag on the + `m.room.member` events sent to the users in `invite` and + `invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information. + power_level_content_override: + title: Power Level Event Content + type: object + description: |- + The power level content to override in the default power level + event. This object is applied on top of the generated + [`m.room.power_levels`](client-server-api/#mroompower_levels) + event content prior to it being sent to the room. Defaults to + overriding nothing. + responses: + 200: + description: Information about the newly created room. + schema: + type: object + description: Information about the newly created room. + properties: + room_id: + type: string + description: |- + The created room's ID. + required: ['room_id'] + examples: + application/json: { + "room_id": "!sefiuhWgwghwWgh:example.com" + } + 400: + description: |- + + The request is invalid. A meaningful `errcode` and description + error text will be returned. Example reasons for rejection include: + + - The request body is malformed (`errcode` set to `M_BAD_JSON` + or `M_NOT_JSON`). + + - The room alias specified is already taken (`errcode` set to + `M_ROOM_IN_USE`). + + - The initial state implied by the parameters to the request is + invalid: for example, the user's `power_level` is set below + that necessary to set the room name (`errcode` set to + `M_INVALID_ROOM_STATE`). + + - The homeserver doesn't support the requested room version, or + one or more users being invited to the new room are residents + of a homeserver which does not support the requested room version. + The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these + cases. + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room creation diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml new file mode 100644 index 000000000..a0516ef2c --- /dev/null +++ b/data/api/client-server/cross_signing.yaml @@ -0,0 +1,224 @@ +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Cross Signing API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/keys/device_signing/upload": + post: + summary: Upload cross-signing keys. + description: |- + Publishes cross-signing keys for the user. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + operationId: uploadCrossSigningKeys + security: + - accessToken: [] + parameters: + - in: body + name: keys + description: |- + The keys to be published. + schema: + type: object + properties: + master_key: + description: |- + Optional. The user\'s master key. + allOf: + - $ref: definitions/cross_signing_key.yaml + self_signing_key: + description: |- + Optional. The user\'s self-signing key. Must be signed by + the accompanying master key, or by the user\'s most recently + uploaded master key if no master key is included in the + request. + allOf: + - $ref: definitions/cross_signing_key.yaml + user_signing_key: + description: |- + Optional. The user\'s user-signing key. Must be signed by + the accompanying master key, or by the user\'s most recently + uploaded master key if no master key is included in the + request. + allOf: + - $ref: definitions/cross_signing_key.yaml + example: { + "master_key": { + "user_id": "@alice:example.com", + "usage": ["master"], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key", + } + }, + "self_signing_key": { + "user_id": "@alice:example.com", + "usage": ["self_signing"], + "keys": { + "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+self+signing+key" + } + } + }, + "user_signing_key": { + "user_id": "@alice:example.com", + "usage": ["user_signing"], + "keys": { + "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+user+signing+key" + } + } + } + } + responses: + 200: + description: The provided keys were successfully uploaded. + schema: + type: object + example: {} + 400: + description: |- + The input was invalid in some way. This can include one of the + following error codes: + + * `M_INVALID_SIGNATURE`: For example, the self-signing or + user-signing key had an incorrect signature. + * `M_MISSING_PARAM`: No master key is available. + schema: + type: object + example: { + "errcode": "M_INVALID_SIGNATURE", + "error": "Invalid signature" + } + 403: + description: |- + The public key of one of the keys is the same as one of the user\'s + device IDs, or the request is not authorized for any other reason. + schema: + type: object + example: { + "errcode": "M_FORBIDDEN", + "error": "Key ID in use" + } + "/keys/signatures/upload": + post: + summary: Upload cross-signing signatures. + description: |- + Publishes cross-signing signatures for the user. The request body is a + map from user ID to key ID to signed JSON object. + operationId: uploadCrossSigningSignatures + security: + - accessToken: [] + parameters: + - in: body + name: signatures + description: |- + The signatures to be published. + schema: + type: object + title: Signatures + additionalProperties: + type: object + additionalProperties: + type: object + example: { + "@alice:example.com": { + "HIJKLMN": { + "user_id": "@alice:example.com", + "device_id": "HIJKLMN", + "algorithms": [ + "m.olm.curve25519-aes-sha256", + "m.megolm.v1.aes-sha" + ], + "keys": { + "curve25519:HIJKLMN": "base64+curve25519+key", + "ed25519:HIJKLMN": "base64+ed25519+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" + } + } + }, + "base64+master+public+key": { + "user_id": "@alice:example.com", + "usage": ["master"], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:HIJKLMN": "base64+signature+of+master+key" + } + } + } + }, + "@bob:example.com": { + "bobs+base64+master+public+key": { + "user_id": "@bob:example.com", + "keys": { + "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" + }, + "usage": ["master"], + "signatures": { + "@alice:example.com": { + "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" + } + } + } + } + } + responses: + 200: + description: The provided signatures were processed. + schema: + type: object + properties: + failures: + type: object + description: |- + A map from user ID to key ID to an error for any signatures + that failed. If a signature was invalid, the `errcode` will + be set to `M_INVALID_SIGNATURE`. + additionalProperties: + type: object + additionalProperties: + type: object + title: Error + example: { + "@alice:example.com": { + "HIJKLMN": { + "errcode": "M_INVALID_SIGNATURE", + "error": "Invalid signature" + } + } + } diff --git a/data/api/client-server/definitions/auth_data.yaml b/data/api/client-server/definitions/auth_data.yaml new file mode 100644 index 000000000..c37c6a481 --- /dev/null +++ b/data/api/client-server/definitions/auth_data.yaml @@ -0,0 +1,33 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Authentication Data +description: |- + Used by clients to submit authentication information to the interactive-authentication API +type: object +properties: + type: + description: The login type that the client is attempting to complete. + type: string + session: + description: The value of the session key given by the homeserver. + type: string +additionalProperties: + description: Keys dependent on the login type + type: object +required: + - type +example: + type: "example.type.foo" + session: "xxxxx" + example_credential: "verypoorsharedsecret" diff --git a/data/api/client-server/definitions/auth_response.yaml b/data/api/client-server/definitions/auth_response.yaml new file mode 100644 index 000000000..5caf7a885 --- /dev/null +++ b/data/api/client-server/definitions/auth_response.yaml @@ -0,0 +1,62 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Authentication response +description: |- + Used by servers to indicate that additional authentication information is required, +type: object +properties: + flows: + description: A list of the login flows supported by the server for this API. + title: Flow information + type: array + items: + type: object + properties: + stages: + description: |- + The login type of each of the stages required to complete this + authentication flow + type: array + items: + type: string + example: "example.type.foo" + required: + - stages + params: + type: object + description: |- + Contains any information that the client will need to know in order to + use a given type of authentication. For each login type presented, + that type may be present as a key in this dictionary. For example, the + public part of an OAuth client ID could be given here. + additionalProperties: + type: object + example: + "example.type.baz": { "example_key": "foobar" } + session: + type: string + description: |- + This is a session identifier that the client must pass back to the home + server, if one is provided, in subsequent attempts to authenticate in the + same API call. + example: "xxxxxxyz" + completed: + type: array + description: |- + A list of the stages the client has completed successfully + items: + type: string + example: "example.type.foo" +required: + - flows diff --git a/data/api/client-server/definitions/client_device.yaml b/data/api/client-server/definitions/client_device.yaml new file mode 100644 index 000000000..6dc3abf37 --- /dev/null +++ b/data/api/client-server/definitions/client_device.yaml @@ -0,0 +1,44 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +description: A client device +title: Device +properties: + device_id: + type: string + description: Identifier of this device. + example: QBUAZIFURK + display_name: + type: string + description: |- + Display name set by the user for this device. Absent if no name has been + set. + example: android + last_seen_ip: + type: string + description: |- + The IP address where this device was last seen. (May be a few minutes out + of date, for efficiency reasons). + example: 1.2.3.4 + last_seen_ts: + type: integer + format: int64 + description: |- + The timestamp (in milliseconds since the unix epoch) when this devices + was last seen. (May be a few minutes out of date, for efficiency + reasons). + example: 1474491775024 +required: + - device_id diff --git a/data/api/client-server/definitions/cross_signing_key.yaml b/data/api/client-server/definitions/cross_signing_key.yaml new file mode 100644 index 000000000..cebc5ecd3 --- /dev/null +++ b/data/api/client-server/definitions/cross_signing_key.yaml @@ -0,0 +1,55 @@ +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: CrossSigningKey +description: Cross signing key +properties: + user_id: + type: string + description: |- + The ID of the user the key belongs to. + example: "@alice:example.com" + usage: + type: array + description: |- + What the key is used for. + items: + type: string + enum: ["master", "self_signing", "user_signing"] + keys: + type: object + additionalProperties: + type: string + description: |- + The public key. The object must have exactly one property, whose name is + in the form `:`, and whose value + is the unpadded base64 public key. + example: + "ed25519:alice+base64+public+key": "alice+base64+public+key" + signatures: + type: object + title: Signatures + description: |- + Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json). + Optional for the master key. Other keys must be signed by the + user\'s master key. + example: { + "@alice:example.com": { + "ed25519:alice+base64+master+key": "signature+of+key" + } + } +required: + - user_id + - usage + - keys diff --git a/data/api/client-server/definitions/device_keys.yaml b/data/api/client-server/definitions/device_keys.yaml new file mode 100644 index 000000000..ab033941d --- /dev/null +++ b/data/api/client-server/definitions/device_keys.yaml @@ -0,0 +1,68 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: DeviceKeys +description: Device identity keys +properties: + user_id: + type: string + description: |- + The ID of the user the device belongs to. Must match the user ID used + when logging in. + example: "@alice:example.com" + device_id: + type: string + description: |- + The ID of the device these keys belong to. Must match the device ID used + when logging in. + example: "JLAFKJWSCS" + algorithms: + type: array + items: + type: string + description: |- + The encryption algorithms supported by this device. + example: ["m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2"] + keys: + type: object + description: |- + Public identity keys. The names of the properties should be in the + format `:`. The keys themselves should be + encoded as specified by the key algorithm. + additionalProperties: + type: string + example: + "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI" + "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" + signatures: + type: object + title: Signatures + description: |- + Signatures for the device key object. A map from user ID, to a map from + `:` to the signature. + + The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). + additionalProperties: + type: object + additionalProperties: + type: string + example: + "@alice:example.com": + "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" +required: + - user_id + - device_id + - algorithms + - keys + - signatures diff --git a/data/api/client-server/definitions/errors/error.yaml b/data/api/client-server/definitions/errors/error.yaml new file mode 100644 index 000000000..7471da6f6 --- /dev/null +++ b/data/api/client-server/definitions/errors/error.yaml @@ -0,0 +1,25 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +description: A Matrix-level Error +properties: + errcode: + type: string + description: An error code. + example: M_UNKNOWN + error: + type: string + description: A human-readable error message. + example: An unknown error occurred +required: ["errcode"] \ No newline at end of file diff --git a/data/api/client-server/definitions/errors/rate_limited.yaml b/data/api/client-server/definitions/errors/rate_limited.yaml new file mode 100644 index 000000000..aca82ce7b --- /dev/null +++ b/data/api/client-server/definitions/errors/rate_limited.yaml @@ -0,0 +1,32 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +$ref: error.yaml +type: object +description: The rate limit was reached for this request +properties: + errcode: + type: string + description: The M_LIMIT_EXCEEDED error code + example: M_LIMIT_EXCEEDED + error: + type: string + description: A human-readable error message. + example: Too many requests + retry_after_ms: + type: integer + description: |- + The amount of time in milliseconds the client should wait + before trying the request again. + example: 2000 +required: ["errcode"] \ No newline at end of file diff --git a/data/api/client-server/definitions/event.yaml b/data/api/client-server/definitions/event.yaml new file mode 100644 index 000000000..54af96f51 --- /dev/null +++ b/data/api/client-server/definitions/event.yaml @@ -0,0 +1,65 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +properties: + event_id: + description: The ID of this event, if applicable. + type: string + content: + description: The content of this event. The fields in this object will vary depending + on the type of event. + title: EventContent + type: object + origin_server_ts: + description: Timestamp in milliseconds on originating homeserver when this event + was sent. + format: int64 + type: integer + sender: + description: The MXID of the user who sent this event. + type: string + state_key: + description: Optional. This key will only be present for state events. A unique + key which defines the overwriting semantics for this piece of room state. + type: string + type: + description: The type of event. + type: string + unsigned: + description: Information about this event which was not sent by the originating + homeserver + properties: + age: + description: Time in milliseconds since the event was sent. + format: int64 + type: integer + prev_content: + description: Optional. The previous `content` for this state. This will + be present only for state events appearing in the `timeline`. If this + is not a state event, or there is no previous content, this key will be + missing. + title: EventContent + type: object + transaction_id: + description: Optional. The transaction ID set when this message was sent. + This key will only be present for message events sent by the device calling + this API. + type: string + redacted_because: + description: Optional. The event that redacted this event, if any. + title: Event + type: object + title: UnsignedData + type: object +title: Event +type: object diff --git a/data/api/client-server/definitions/event_batch.yaml b/data/api/client-server/definitions/event_batch.yaml new file mode 100644 index 000000000..1694652ca --- /dev/null +++ b/data/api/client-server/definitions/event_batch.yaml @@ -0,0 +1,23 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +properties: + events: + description: List of events. + items: + allOf: + - $ref: ../../../event-schemas/schema/core-event-schema/event.yaml + type: object + type: array +type: object diff --git a/data/api/client-server/definitions/event_filter.yaml b/data/api/client-server/definitions/event_filter.yaml new file mode 100644 index 000000000..b68886931 --- /dev/null +++ b/data/api/client-server/definitions/event_filter.yaml @@ -0,0 +1,47 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: EventFilter +properties: + limit: + description: The maximum number of events to return. + type: integer + not_senders: + description: A list of sender IDs to exclude. If this list is absent then no senders + are excluded. A matching sender will be excluded even if it is listed in the + `'senders'` filter. + items: + type: string + type: array + not_types: + description: A list of event types to exclude. If this list is absent then no + event types are excluded. A matching type will be excluded even if it is listed + in the `'types'` filter. A '*' can be used as a wildcard to match any sequence + of characters. + items: + type: string + type: array + senders: + description: A list of senders IDs to include. If this list is absent then all + senders are included. + items: + type: string + type: array + types: + description: A list of event types to include. If this list is absent then all + event types are included. A `'*'` can be used as a wildcard to match any sequence + of characters. + items: + type: string + type: array +type: object diff --git a/data/api/client-server/definitions/key_backup_data.yaml b/data/api/client-server/definitions/key_backup_data.yaml new file mode 100644 index 000000000..c6e6b29e0 --- /dev/null +++ b/data/api/client-server/definitions/key_backup_data.yaml @@ -0,0 +1,50 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: KeyBackupData +description: "The key data" +properties: + first_message_index: + description: |- + The index of the first message in the session that the key can decrypt. + type: integer + example: 1 + forwarded_count: + description: |- + The number of times this key has been forwarded via key-sharing between devices. + type: integer + example: 0 + is_verified: + description: |- + Whether the device backing up the key verified the device that the key + is from. + type: boolean + example: false + session_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: { + "ephemeral": "base64+ephemeral+key", + "ciphertext": "base64+ciphertext+of+JSON+data", + "mac": "base64+mac+of+ciphertext" + } +required: + - first_message_index + - forwarded_count + - is_verified + - session_data diff --git a/data/api/client-server/definitions/openid_token.yaml b/data/api/client-server/definitions/openid_token.yaml new file mode 100644 index 000000000..32929ef6f --- /dev/null +++ b/data/api/client-server/definitions/openid_token.yaml @@ -0,0 +1,36 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +properties: + access_token: + type: string + description: |- + An access token the consumer may use to verify the identity of + the person who generated the token. This is given to the federation + API `GET /openid/userinfo` to verify the user's identity. + token_type: + type: string + description: The string `Bearer`. + matrix_server_name: + type: string + description: |- + The homeserver domain the consumer should use when attempting to + verify the user's identity. + expires_in: + type: integer + description: |- + The number of seconds before this token expires and a new one must + be generated. +required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in'] diff --git a/data/api/client-server/definitions/public_rooms_response.yaml b/data/api/client-server/definitions/public_rooms_response.yaml new file mode 100644 index 000000000..ab7010516 --- /dev/null +++ b/data/api/client-server/definitions/public_rooms_response.yaml @@ -0,0 +1,105 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +description: A list of the rooms on the server. +required: ["chunk"] +properties: + chunk: + title: "PublicRoomsChunks" + type: array + description: |- + A paginated chunk of public rooms. + items: + type: object + title: "PublicRoomsChunk" + required: + - room_id + - num_joined_members + - world_readable + - guest_can_join + properties: + aliases: + type: array + description: |- + Aliases of the room. May be empty. + items: + type: string + canonical_alias: + type: string + description: |- + The canonical alias of the room, if any. + name: + type: string + description: |- + The name of the room, if any. + num_joined_members: + type: integer + description: |- + The number of members joined to the room. + room_id: + type: string + description: |- + The ID of the room. + topic: + type: string + description: |- + The topic of the room, if any. + world_readable: + type: boolean + description: |- + Whether the room may be viewed by guest users without joining. + guest_can_join: + type: boolean + description: |- + Whether guest users may join the room and participate in it. + If they can, they will be subject to ordinary power level + rules like any other user. + avatar_url: + type: string + description: The URL for the room's avatar, if one is set. + next_batch: + type: string + description: |- + A pagination token for the response. The absence of this token + means there are no more results to fetch and the client should + stop paginating. + prev_batch: + type: string + description: |- + A pagination token that allows fetching previous results. The + absence of this token means there are no results before this + batch, i.e. this is the first batch. + total_room_count_estimate: + type: integer + description: |- + An estimate on the total number of public rooms, if the + server has an estimate. +example: { + "chunk": [ + { + "aliases": ["#murrays:cheese.bar"], + "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE", + "guest_can_join": false, + "name": "CHEESE", + "num_joined_members": 37, + "room_id": "!ol19s:bleecker.street", + "topic": "Tasty tasty cheese", + "world_readable": true + } + ], + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 +} \ No newline at end of file diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml new file mode 100644 index 000000000..64d975ff2 --- /dev/null +++ b/data/api/client-server/definitions/push_condition.yaml @@ -0,0 +1,49 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +title: PushCondition +type: object +properties: + kind: + type: string + description: |- + The kind of condition to apply. See [conditions](/client-server-api/#conditions) for + more information on the allowed kinds and how they work. + key: + type: string + description: |- + Required for `event_match` conditions. The dot-separated field of the + event to match. + + Required for `sender_notification_permission` conditions. The field in + the power level event the user needs a minimum power level for. Fields + must be specified under the `notifications` property in the power level + event's `content`. + x-example: content.body + pattern: + type: string + description: |- + Required for `event_match` conditions. The glob-style pattern to + match against. Patterns with no special glob characters should be + treated as having asterisks prepended and appended when testing the + condition. + is: + type: string + description: |- + Required for `room_member_count` conditions. A decimal integer + optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + rooms where the member count is strictly less than the given number and + so forth. If no prefix is present, this parameter defaults to ==. +required: + - kind diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml new file mode 100644 index 000000000..06efad744 --- /dev/null +++ b/data/api/client-server/definitions/push_rule.yaml @@ -0,0 +1,56 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +title: PushRule +type: object +properties: + actions: + items: + type: + - object + - string + type: array + description: |- + The actions to perform when this rule is matched. + default: + type: boolean + description: |- + Whether this is a default rule, or has been set explicitly. + enabled: + type: boolean + description: |- + Whether the push rule is enabled or not. + rule_id: + type: string + description: |- + The ID of this rule. + conditions: + type: array + items: + allOf: + - $ref: push_condition.yaml + description: |- + The conditions that must hold true for an event in order for a rule to be + applied to an event. A rule with no conditions always matches. Only + applicable to `underride` and `override` rules. + pattern: + type: string + description: |- + The glob-style pattern to match against. Only applicable to `content` + rules. +required: + - actions + - default + - enabled + - rule_id diff --git a/data/api/client-server/definitions/push_ruleset.yaml b/data/api/client-server/definitions/push_ruleset.yaml new file mode 100644 index 000000000..2d8cd67c1 --- /dev/null +++ b/data/api/client-server/definitions/push_ruleset.yaml @@ -0,0 +1,50 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +properties: + content: + items: + allOf: + - $ref: push_rule.yaml + title: PushRule + type: object + type: array + override: + items: + allOf: + - $ref: push_rule.yaml + title: PushRule + type: object + type: array + room: + items: + allOf: + - $ref: push_rule.yaml + title: PushRule + type: object + type: array + sender: + items: + allOf: + - $ref: push_rule.yaml + title: PushRule + type: object + type: array + underride: + items: + allOf: + - $ref: push_rule.yaml + title: PushRule + type: object + type: array +type: object diff --git a/data/api/client-server/definitions/request_email_validation.yaml b/data/api/client-server/definitions/request_email_validation.yaml new file mode 100644 index 000000000..d52ea18e9 --- /dev/null +++ b/data/api/client-server/definitions/request_email_validation.yaml @@ -0,0 +1,36 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: +- $ref: "../../identity/definitions/request_email_validation.yaml" +- type: object + properties: + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + + This parameter is deprecated with a plan to be removed in a future specification + version for `/account/password` and `/register` requests. + example: "id.example.com" + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + + Required if an `id_server` is supplied. diff --git a/data/api/client-server/definitions/request_msisdn_validation.yaml b/data/api/client-server/definitions/request_msisdn_validation.yaml new file mode 100644 index 000000000..fba3a615d --- /dev/null +++ b/data/api/client-server/definitions/request_msisdn_validation.yaml @@ -0,0 +1,36 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: +- $ref: "../../identity/definitions/request_msisdn_validation.yaml" +- type: object + properties: + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + + This parameter is deprecated with a plan to be removed in a future specification + version for `/account/password` and `/register` requests. + example: "id.example.com" + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + + Required if an `id_server` is supplied. diff --git a/data/api/client-server/definitions/request_token_response.yaml b/data/api/client-server/definitions/request_token_response.yaml new file mode 100644 index 000000000..b801af984 --- /dev/null +++ b/data/api/client-server/definitions/request_token_response.yaml @@ -0,0 +1,37 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +properties: + sid: + type: string + description: |- + The session ID. Session IDs are opaque strings that must consist entirely + of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 + characters and they must not be empty. + example: "123abc" + submit_url: + type: string + description: |- + An optional field containing a URL where the client must submit the + validation token to, with identical parameters to the Identity Service + API's `POST /validate/email/submitToken` endpoint (without the requirement + for an access token). The homeserver must send this token to the user (if + applicable), who should then be prompted to provide it to the client. + + If this field is not present, the client can assume that verification + will happen without the client's involvement provided the homeserver + advertises this specification version in the `/versions` response + (ie: r0.5.0). + example: "https://example.org/path/to/submitToken" +required: ['sid'] diff --git a/data/api/client-server/definitions/room_event_batch.yaml b/data/api/client-server/definitions/room_event_batch.yaml new file mode 100644 index 000000000..45bcb4231 --- /dev/null +++ b/data/api/client-server/definitions/room_event_batch.yaml @@ -0,0 +1,27 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +properties: + events: + description: List of events. + items: + allOf: + - $ref: ../../../event-schemas/schema/core-event-schema/sync_room_event.yaml + type: object + required: + - event_id + #- room_id - Not in /sync + - sender + - origin_server_ts + type: array +type: object diff --git a/data/api/client-server/definitions/room_event_filter.yaml b/data/api/client-server/definitions/room_event_filter.yaml new file mode 100644 index 000000000..8d96a1658 --- /dev/null +++ b/data/api/client-server/definitions/room_event_filter.yaml @@ -0,0 +1,49 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +allOf: +- $ref: event_filter.yaml +- type: object + title: RoomEventFilter + properties: + lazy_load_members: + type: boolean + description: |- + If `true`, enables lazy-loading of membership events. See + [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) + for more information. Defaults to `false`. + include_redundant_members: + type: boolean + description: |- + If `true`, sends all membership events for all events, even if they have already + been sent to the client. Does not + apply unless `lazy_load_members` is `true`. See + [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) + for more information. Defaults to `false`. + not_rooms: + description: A list of room IDs to exclude. If this list is absent then no rooms + are excluded. A matching room will be excluded even if it is listed in the `'rooms'` + filter. + items: + type: string + type: array + rooms: + description: A list of room IDs to include. If this list is absent then all rooms + are included. + items: + type: string + type: array + contains_url: + type: boolean + description: If `true`, includes only events with a `url` key in their content. If + `false`, excludes those events. If omitted, `url` key is not considered for filtering. diff --git a/data/api/client-server/definitions/room_key_backup.yaml b/data/api/client-server/definitions/room_key_backup.yaml new file mode 100644 index 000000000..5c70850fa --- /dev/null +++ b/data/api/client-server/definitions/room_key_backup.yaml @@ -0,0 +1,38 @@ +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: RoomKeyBackup +description: "The backed up keys for a room." +properties: + sessions: + type: object + description: "A map of session IDs to key data." + additionalProperties: + allOf: + - $ref: "key_backup_data.yaml" + example: { + "sessionid1": { + "first_message_index": 1, + "forwarded_count": 0, + "is_verified": true, + "session_data": { + "ephemeral": "base64+ephemeral+key", + "ciphertext": "base64+ciphertext+of+JSON+data", + "mac": "base64+mac+of+ciphertext" + } + } + } +required: + - sessions diff --git a/data/api/client-server/definitions/security.yaml b/data/api/client-server/definitions/security.yaml new file mode 100644 index 000000000..963e1d435 --- /dev/null +++ b/data/api/client-server/definitions/security.yaml @@ -0,0 +1,18 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +accessToken: + type: apiKey + description: The access_token returned by a call to `/login` or `/register` + name: access_token + in: query diff --git a/data/api/client-server/definitions/state_event_batch.yaml b/data/api/client-server/definitions/state_event_batch.yaml new file mode 100644 index 000000000..9518300fb --- /dev/null +++ b/data/api/client-server/definitions/state_event_batch.yaml @@ -0,0 +1,28 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +properties: + events: + description: List of events. + items: + allOf: + - $ref: ../../../event-schemas/schema/core-event-schema/sync_state_event.yaml + type: object + required: + - event_id + #- room_id - Not in /sync + - sender + - origin_server_ts + - state_key + type: array +type: object diff --git a/data/api/client-server/definitions/sync_filter.yaml b/data/api/client-server/definitions/sync_filter.yaml new file mode 100644 index 000000000..0b4a8dca2 --- /dev/null +++ b/data/api/client-server/definitions/sync_filter.yaml @@ -0,0 +1,83 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Filter +properties: + event_fields: + description: List of event fields to include. If this list is absent then all + fields are included. The entries may include '.' characters to indicate sub-fields. + So ['content.body'] will include the 'body' field of the 'content' object. A + literal '.' character in a field name may be escaped using a '\\'. A server may + include more fields than were requested. + items: + type: string + type: array + event_format: + description: The format to use for events. 'client' will return the events in + a format suitable for clients. 'federation' will return the raw event as received + over federation. The default is 'client'. + enum: + - client + - federation + type: string + presence: + allOf: + - $ref: event_filter.yaml + description: The presence updates to include. + account_data: + allOf: + - $ref: event_filter.yaml + description: The user account data that isn't associated with rooms to include. + room: + title: RoomFilter + description: Filters to be applied to room data. + type: object + properties: + not_rooms: + description: A list of room IDs to exclude. If this list is absent then no rooms + are excluded. A matching room will be excluded even if it is listed in the `'rooms'` + filter. This filter is applied before the filters in `ephemeral`, + `state`, `timeline` or `account_data` + items: + type: string + type: array + rooms: + description: A list of room IDs to include. If this list is absent then all rooms + are included. This filter is applied before the filters in `ephemeral`, + `state`, `timeline` or `account_data` + items: + type: string + type: array + ephemeral: + allOf: + - $ref: room_event_filter.yaml + description: The events that aren't recorded in the room history, e.g. typing + and receipts, to include for rooms. + include_leave: + description: Include rooms that the user has left in the sync, default false + type: boolean + state: + type: object + title: StateFilter + allOf: + - $ref: room_event_filter.yaml + description: The state events to include for rooms. + timeline: + allOf: + - $ref: room_event_filter.yaml + description: The message and state update events to include for rooms. + account_data: + allOf: + - $ref: room_event_filter.yaml + description: The per user account data to include for rooms. diff --git a/data/api/client-server/definitions/third_party_signed.yaml b/data/api/client-server/definitions/third_party_signed.yaml new file mode 100644 index 000000000..4af422b4b --- /dev/null +++ b/data/api/client-server/definitions/third_party_signed.yaml @@ -0,0 +1,45 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Third Party Signed +description: |- + A signature of an `m.third_party_invite` token to prove that this user + owns a third party identity which has been invited to the room. +properties: + sender: + type: string + description: The Matrix ID of the user who issued the invite. + example: "@alice:example.org" + mxid: + type: string + description: The Matrix ID of the invitee. + example: "@bob:example.org" + token: + type: string + description: The state key of the m.third_party_invite event. + example: "random8nonce" + signatures: + type: object + description: A signatures object containing a signature of the entire signed object. + title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string + example: { + "example.org": { + "ed25519:0": "some9signature" + } + } +required: ["sender", "mxid", "token", "signatures"] diff --git a/data/api/client-server/definitions/timeline_batch.yaml b/data/api/client-server/definitions/timeline_batch.yaml new file mode 100644 index 000000000..e243b485f --- /dev/null +++ b/data/api/client-server/definitions/timeline_batch.yaml @@ -0,0 +1,26 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +allOf: +- $ref: room_event_batch.yaml +properties: + limited: + description: True if the number of events returned was limited by the `limit` + on the filter. + type: boolean + prev_batch: + description: A token that can be supplied to the `from` parameter of the + rooms/{roomId}/messages endpoint. + type: string +type: object diff --git a/data/api/client-server/definitions/user_identifier.yaml b/data/api/client-server/definitions/user_identifier.yaml new file mode 100644 index 000000000..7e6eca9c6 --- /dev/null +++ b/data/api/client-server/definitions/user_identifier.yaml @@ -0,0 +1,24 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: User identifier +description: |- + Identification information for a user +type: object +properties: + type: + type: string + description: The type of identification. See [Identifier types](/client-server-api/#identifier-types) for supported values and additional property descriptions. +required: + - type +additionalProperties: true diff --git a/data/api/client-server/definitions/wellknown/full.yaml b/data/api/client-server/definitions/wellknown/full.yaml new file mode 100644 index 000000000..8d8f40387 --- /dev/null +++ b/data/api/client-server/definitions/wellknown/full.yaml @@ -0,0 +1,39 @@ +# Copyright 2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Discovery Information +description: |- + Used by clients to determine the homeserver, identity server, and other + optional components they should be interacting with. +type: object +properties: + "m.homeserver": + $ref: "homeserver.yaml" + "m.identity_server": + $ref: "identity_server.yaml" +additionalProperties: + type: object + description: Application-dependent keys using Java package naming convention. +required: + - m.homeserver +example: { + "m.homeserver": { + "base_url": "https://matrix.example.com" + }, + "m.identity_server": { + "base_url": "https://identity.example.com" + }, + "org.example.custom.property": { + "app_url": "https://custom.app.example.org" + } +} diff --git a/data/api/client-server/definitions/wellknown/homeserver.yaml b/data/api/client-server/definitions/wellknown/homeserver.yaml new file mode 100644 index 000000000..92ff34ed3 --- /dev/null +++ b/data/api/client-server/definitions/wellknown/homeserver.yaml @@ -0,0 +1,24 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Homeserver Information +description: |- + Used by clients to discover homeserver information. +type: object +properties: + base_url: + type: string + description: The base URL for the homeserver for client-server connections. + example: https://matrix.example.com +required: + - base_url diff --git a/data/api/client-server/definitions/wellknown/identity_server.yaml b/data/api/client-server/definitions/wellknown/identity_server.yaml new file mode 100644 index 000000000..a8f7c31cf --- /dev/null +++ b/data/api/client-server/definitions/wellknown/identity_server.yaml @@ -0,0 +1,24 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Identity Server Information +description: |- + Used by clients to discover identity server information. +type: object +properties: + base_url: + type: string + description: The base URL for the identity server for client-server connections. + example: https://identity.example.com +required: + - base_url diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml new file mode 100644 index 000000000..aeb1346ad --- /dev/null +++ b/data/api/client-server/device_management.yaml @@ -0,0 +1,230 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Client-Server device management API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/devices": + get: + summary: List registered devices for the current user + description: |- + Gets information about all devices for the current user. + operationId: getDevices + security: + - accessToken: [] + responses: + 200: + description: Device information + schema: + type: object + properties: + devices: + type: array + description: A list of all registered devices for this user. + items: + type: object + allOf: + - $ref: "definitions/client_device.yaml" + examples: + application/json: { + "devices": [ + { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + ] + } + tags: + - Device management + "/devices/{deviceId}": + get: + summary: Get a single device + description: |- + Gets information on a single device, by device id. + operationId: getDevice + security: + - accessToken: [] + parameters: + - in: path + type: string + name: deviceId + description: The device to retrieve. + required: true + x-example: "QBUAZIFURK" + responses: + 200: + description: Device information + schema: + type: object + allOf: + - $ref: "definitions/client_device.yaml" + examples: + application/json: { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + 404: + description: The current user has no device with the given ID. + tags: + - Device management + put: + summary: Update a device + description: |- + Updates the metadata on the given device. + operationId: updateDevice + security: + - accessToken: [] + parameters: + - in: path + type: string + name: deviceId + description: The device to update. + required: true + x-example: "QBUAZIFURK" + - in: body + name: body + required: true + description: New information for the device. + schema: + type: object + properties: + display_name: + type: string + description: |- + The new display name for this device. If not given, the + display name is unchanged. + example: { "display_name": "My other phone" } + responses: + 200: + description: The device was successfully updated. + examples: + application/json: { + } + schema: + type: object # empty json object + 404: + description: The current user has no device with the given ID. + tags: + - Device management + delete: + summary: Delete a device + description: |- + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + Deletes the given device, and invalidates any access token associated with it. + operationId: deleteDevice + security: + - accessToken: [] + parameters: + - in: path + type: string + name: deviceId + description: The device to delete. + required: true + x-example: "QBUAZIFURK" + - in: body + name: body + required: true + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - "$ref": "definitions/auth_data.yaml" + responses: + 200: + description: |- + The device was successfully removed, or had been removed + previously. + schema: + type: object + examples: + application/json: { + } + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + tags: + - Device management + "/delete_devices": + post: + summary: Bulk deletion of devices + description: |- + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + Deletes the given devices, and invalidates any access token associated with them. + operationId: deleteDevices + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + devices: + type: array + description: The list of device IDs to delete. + items: + type: string + description: A list of device IDs. + example: ["QBUAZIFURK", "AUIECTSRND"] + auth: + allOf: + - "$ref": "definitions/auth_data.yaml" + description: |- + Additional authentication information for the + user-interactive authentication API. + required: + - devices + responses: + 200: + description: |- + The devices were successfully removed, or had been removed + previously. + schema: + type: object + examples: + application/json: { + } + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + tags: + - Device management diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml new file mode 100644 index 000000000..1b01242d2 --- /dev/null +++ b/data/api/client-server/directory.yaml @@ -0,0 +1,237 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Directory API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/directory/room/{roomAlias}": + put: + summary: Create a new mapping from room alias to room ID. + operationId: setRoomAlias + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomAlias + description: The room alias to set. + required: true + x-example: "#monkeys:matrix.org" + - in: body + name: body + description: Information about this room alias. + required: true + schema: + type: object + properties: + room_id: + type: string + description: The room ID to set. + required: ['room_id'] + example: { + "room_id": "!abnjk1jdasj98:capuchins.com" + } + responses: + 200: + description: The mapping was created. + examples: + application/json: {} + schema: + type: object + 409: + description: A room alias with that name already exists. + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "Room alias #monkeys:matrix.org already exists." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room directory + get: + summary: Get the room ID corresponding to this room alias. + description: |- + Requests that the server resolve a room alias to a room ID. + + The server will use the federation API to resolve the alias if the + domain part of the alias does not correspond to the server's own + domain. + + operationId: getRoomIdByAlias + parameters: + - in: path + type: string + name: roomAlias + description: The room alias. + required: true + x-example: "#monkeys:matrix.org" + responses: + 200: + description: The room ID and other information for this alias. + schema: + type: object + properties: + room_id: + type: string + description: The room ID for this room alias. + servers: + type: array + description: A list of servers that are aware of this room alias. + items: + type: string + description: A server which is aware of this room alias. + examples: + application/json: { + "room_id": "!abnjk1jdasj98:capuchins.com", + "servers": [ + "capuchins.com", + "matrix.org", + "another.com" + ] + } + 404: + description: There is no mapped room ID for this room alias. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room alias #monkeys:matrix.org not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room directory + delete: + summary: Remove a mapping of room alias to room ID. + description: |- + Remove a mapping of room alias to room ID. + + Servers may choose to implement additional access control checks here, for instance that + room aliases can only be deleted by their creator or a server administrator. + + **Note:** + Servers may choose to update the `alt_aliases` for the `m.room.canonical_alias` + state event in the room when an alias is removed. Servers which choose to update the + canonical alias event are recommended to, in addition to their other relevant permission + checks, delete the alias and return a successful response even if the user does not + have permission to update the `m.room.canonical_alias` event. + + operationId: deleteRoomAlias + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomAlias + description: The room alias to remove. + required: true + x-example: "#monkeys:matrix.org" + responses: + 200: + description: The mapping was deleted. + examples: + application/json: { + } + schema: + type: object + 404: + description: There is no mapped room ID for this room alias. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room alias #monkeys:example.org not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room directory + "/rooms/{roomId}/aliases": + get: + summary: Get a list of local aliases on a given room. + description: |- + Get a list of aliases maintained by the local server for the + given room. + + This endpoint can be called by users who are in the room (external + users receive an `M_FORBIDDEN` error response). If the room's + `m.room.history_visibility` maps to `world_readable`, any + user can call this endpoint. + + Servers may choose to implement additional access control checks here, + such as allowing server administrators to view aliases regardless of + membership. + + **Note:** + Clients are recommended not to display this list of aliases prominently + as they are not curated, unlike those listed in the `m.room.canonical_alias` + state event. + + operationId: getLocalAliases + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID to find local aliases of. + required: true + x-example: "!abc123:example.org" + responses: + 200: + description: |- + The list of local aliases for the room. + examples: + application/json: { + "aliases": [ + "#somewhere:example.com", + "#another:example.com", + "#hat_trick:example.com" + ] + } + schema: + type: object + properties: + aliases: + type: array + description: The server's local aliases on the room. Can be empty. + items: + type: string + required: ['aliases'] + 403: + description: The user is not permitted to retrieve the list of local aliases for the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You are not a member of the room." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room directory diff --git a/data/api/client-server/event_context.yaml b/data/api/client-server/event_context.yaml new file mode 100644 index 000000000..03e38fe14 --- /dev/null +++ b/data/api/client-server/event_context.yaml @@ -0,0 +1,150 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Event Context API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/context/{eventId}": + get: + summary: Get events and state around the specified event. + description: |- + This API returns a number of events that happened just before and + after the specified event. This allows clients to get the context + surrounding an event. + + *Note*: This endpoint supports lazy-loading of room member events. See + [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information. + operationId: getEventContext + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to get events from. + required: true + x-example: "!636q39766251:example.com" + - in: path + type: string + name: eventId + description: The event to get context around. + required: true + x-example: "$f3h4d129462ha:example.com" + - in: query + type: integer + name: limit + description: |- + The maximum number of events to return. Default: 10. + x-example: 3 + - in: query + name: filter + type: string + description: |- + A JSON `RoomEventFilter` to filter the returned events with. The + filter is only applied to `events_before`, `events_after`, and + `state`. It is not applied to the `event` itself. The filter may + be applied before or/and after the `limit` parameter - whichever the + homeserver prefers. + + See [Filtering](/client-server-api/#filtering) for more information. + x-example: "66696p746572" + responses: + 200: + description: The events and state surrounding the requested event. + schema: + type: object + description: The events and state surrounding the requested event. + properties: + start: + type: string + description: |- + A token that can be used to paginate backwards with. + end: + type: string + description: |- + A token that can be used to paginate forwards with. + events_before: + type: array + description: |- + A list of room events that happened just before the + requested event, in reverse-chronological order. + items: + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + event: + description: |- + Details of the requested event. + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + events_after: + type: array + description: |- + A list of room events that happened just after the + requested event, in chronological order. + items: + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + state: + type: array + description: |- + The state of the room at the last event returned. + items: + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml" + examples: + application/json: { + "end": "t29-57_2_0_2", + "events_after": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "event": { + "event_id": "$f3h4d129462ha:example.com", + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.image.yaml" + }, + "events_before": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" + } + ], + "start": "t27-54_2_0_2", + "state": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + } + tags: + - Room participation diff --git a/data/api/client-server/filter.yaml b/data/api/client-server/filter.yaml new file mode 100644 index 000000000..0a12e2bbb --- /dev/null +++ b/data/api/client-server/filter.yaml @@ -0,0 +1,156 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server filter API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user/{userId}/filter": + post: + summary: Upload a new filter. + description: |- + Uploads a new filter definition to the homeserver. + Returns a filter ID that may be used in future requests to + restrict which events are returned to the client. + operationId: defineFilter + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: + The id of the user uploading the filter. The access token must be + authorized to make requests for this user id. + x-example: "@alice:example.com" + - in: body + name: filter + required: true + description: The filter to upload. + schema: + type: object + allOf: + - $ref: "definitions/sync_filter.yaml" + example: { + "room": { + "state": { + "types": ["m.room.*"], + "not_rooms": ["!726s6s6q:example.com"] + }, + "timeline": { + "limit": 10, + "types": ["m.room.message"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + }, + "ephemeral": { + "types": ["m.receipt", "m.typing"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + } + }, + "presence": { + "types": ["m.presence"], + "not_senders": ["@alice:example.com"] + }, + "event_format": "client", + "event_fields": ["type", "content", "sender"] + } + responses: + 200: + description: The filter was created. + schema: + type: object + properties: + filter_id: + type: string + description: |- + The ID of the filter that was created. Cannot start + with a `{` as this character is used to determine + if the filter provided is inline JSON or a previously + declared filter by homeservers on some APIs. + example: "66696p746572" + required: ['filter_id'] + tags: + - Room participation + "/user/{userId}/filter/{filterId}": + get: + summary: Download a filter + operationId: getFilter + security: + - accessToken: [] + parameters: + - in: path + name: userId + type: string + description: |- + The user ID to download a filter for. + x-example: "@alice:example.com" + required: true + - in: path + name: filterId + type: string + description: |- + The filter ID to download. + x-example: "66696p746572" + required: true + responses: + 200: + description: |- + The filter definition. + examples: + application/json: { + "room": { + "state": { + "types": ["m.room.*"], + "not_rooms": ["!726s6s6q:example.com"] + }, + "timeline": { + "limit": 10, + "types": ["m.room.message"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + }, + "ephemeral": { + "types": ["m.receipt", "m.typing"], + "not_rooms": ["!726s6s6q:example.com"], + "not_senders": ["@spam:example.com"] + } + }, + "presence": { + "types": ["m.presence"], + "not_senders": ["@alice:example.com"] + }, + "event_format": "client", + "event_fields": ["type", "content", "sender"] + } + schema: + type: object + allOf: + - $ref: "definitions/sync_filter.yaml" + 404: + description: "Unknown filter." + tags: + - Room participation diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml new file mode 100644 index 000000000..b099b3ef2 --- /dev/null +++ b/data/api/client-server/inviting.yaml @@ -0,0 +1,120 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Joining API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + # With an extra " " to disambiguate from the 3pid invite endpoint + # The extra space makes it sort first for what I'm sure is a good reason. + "/rooms/{roomId}/invite ": + post: + summary: Invite a user to participate in a particular room. + description: |- + *Note that there are two forms of this API, which are documented separately. + This version of the API requires that the inviter knows the Matrix + identifier of the invitee. The other is documented in the* + [third party invites section](/client-server-api/#post_matrixclientr0roomsroomidinvite-1). + + This API invites a user to participate in a particular room. + They do not start participating in the room until they actually join the + room. + + Only users currently in a particular room can invite other users to + join that room. + + If the user was invited to the room, the homeserver will append a + `m.room.member` event to the room. + + operationId: inviteUser + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier (not alias) to which to invite the user. + required: true + x-example: "!d41d8cd:matrix.org" + - in: body + name: body + required: true + schema: + type: object + example: { + "user_id": "@cheeky_monkey:matrix.org", + "reason": "Welcome to the team!" + } + properties: + user_id: + type: string + description: The fully qualified user ID of the invitee. + reason: + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + required: ["user_id"] + responses: + 200: + description: The user has been invited to join the room. + examples: + application/json: { + } + schema: + type: object + 400: + description: |- + + The request is invalid. A meaningful `errcode` and description + error text will be returned. Example reasons for rejection include: + + - The request body is malformed (`errcode` set to `M_BAD_JSON` + or `M_NOT_JSON`). + + - One or more users being invited to the room are residents of a + homeserver which does not support the requested room version. The + `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. + schema: + "$ref": "definitions/errors/error.yaml" + 403: + description: |- + You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + + - The invitee has been banned from the room. + - The invitee is already a member of the room. + - The inviter is not currently in the room. + - The inviter's power level is insufficient to invite users to the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room membership diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml new file mode 100644 index 000000000..e56d6adac --- /dev/null +++ b/data/api/client-server/joining.yaml @@ -0,0 +1,193 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Inviting API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/join": + post: + summary: Start the requesting user participating in a particular room. + description: |- + *Note that this API requires a room ID, not alias.* + `/join/{roomIdOrAlias}` *exists if you have a room alias.* + + This API starts a user participating in a particular room, if that user + is allowed to participate in that room. After this call, the client is + allowed to see all current state events in the room, and all subsequent + events associated with the room until the user leaves the room. + + After a user has joined a room, the room will appear as an entry in the + response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync) + and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs. + operationId: joinRoomById + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier (not alias) to join. + required: true + x-example: "!d41d8cd:matrix.org" + - in: body + name: body + required: true + schema: + type: object + properties: + third_party_signed: + allOf: + - $ref: "definitions/third_party_signed.yaml" + description: |- + If supplied, the homeserver must verify that it matches a pending + `m.room.third_party_invite` event in the room, and perform + key validity checking if required by the event. + reason: + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: "Looking for support" + responses: + 200: + description: |- + The room has been joined. + + The joined room ID must be returned in the `room_id` field. + examples: + application/json: { + "room_id": "!d41d8cd:matrix.org"} + schema: + type: object + properties: + room_id: + type: string + description: The joined room ID. + required: ["room_id"] + 403: + description: |- + You do not have permission to join the room. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: + + - The room is invite-only and the user was not invited. + - The user has been banned from the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room membership + "/join/{roomIdOrAlias}": + post: + summary: Start the requesting user participating in a particular room. + description: |- + *Note that this API takes either a room ID or alias, unlike* `/room/{roomId}/join`. + + This API starts a user participating in a particular room, if that user + is allowed to participate in that room. After this call, the client is + allowed to see all current state events in the room, and all subsequent + events associated with the room until the user leaves the room. + + After a user has joined a room, the room will appear as an entry in the + response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync) + and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs. + operationId: joinRoom + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomIdOrAlias + description: The room identifier or alias to join. + required: true + x-example: "#monkeys:matrix.org" + - in: query + type: array + items: + type: string + name: server_name + description: |- + The servers to attempt to join the room through. One of the servers + must be participating in the room. + x-example: ["matrix.org", "elsewhere.ca"] + - in: body + name: body + required: true + schema: + type: object + properties: + third_party_signed: + allOf: + - $ref: "definitions/third_party_signed.yaml" + description: |- + If a `third_party_signed` was supplied, the homeserver must verify + that it matches a pending `m.room.third_party_invite` event in the + room, and perform key validity checking if required by the event. + reason: + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: "Looking for support" + responses: + 200: + description: |- + The room has been joined. + + The joined room ID must be returned in the `room_id` field. + examples: + application/json: { + "room_id": "!d41d8cd:matrix.org"} + schema: + type: object + properties: + room_id: + type: string + description: The joined room ID. + required: ["room_id"] + 403: + description: |- + You do not have permission to join the room. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: + + - The room is invite-only and the user was not invited. + - The user has been banned from the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room membership diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml new file mode 100644 index 000000000..7c42f6b53 --- /dev/null +++ b/data/api/client-server/key_backup.yaml @@ -0,0 +1,925 @@ +# Copyright 2019-2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Key Backup API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/room_keys/version": + post: + summary: Create a new backup. + description: |- + Creates a new backup. + operationId: postRoomKeysVersion + security: + - accessToken: [] + parameters: + - in: body + name: version + description: "The backup configuration." + required: true + schema: + type: object + properties: + algorithm: + description: The algorithm used for storing backups. + type: string + enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] + example: "m.megolm_backup.v1.curve25519-aes-sha2" + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: { + "public_key": "abcdefg", + "signatures": { + "@alice:example.org": { + "ed25519:deviceid": "signature" + } + } + } + required: + - algorithm + - auth_data + responses: + 200: + description: + The version id of the new backup. + schema: + type: object + properties: + version: + type: string + description: The backup version. This is an opaque string. + example: "1" + required: + - version + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + get: + summary: Get information about the latest backup version. + description: |- + Get information about the latest backup version. + operationId: getRoomKeysVersionCurrent + security: + - accessToken: [] + responses: + 200: + description: + The information about the backup. + schema: + type: object + properties: + algorithm: + type: string + description: The algorithm used for storing backups. + enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] + example: "m.megolm_backup.v1.curve25519-aes-sha2" + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: { + "public_key": "abcdefg", + "signatures": { + "@alice:example.org": { + "ed25519:deviceid": "signature" + } + } + } + count: + description: The number of keys stored in the backup. + type: integer + example: 42 + etag: + description: |- + An opaque string representing stored keys in the backup. + Clients can compare it with the `etag` value they received + in the request of their last key storage request. If not + equal, another client has modified the backup. + type: string + example: "anopaquestring" + version: + type: string + description: The backup version. + example: "1" + required: + - algorithm + - auth_data + - count + - etag + - version + 404: + description: + No backup exists. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "No current backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + "/room_keys/version/{version}": + get: + summary: Get information about an existing backup. + description: |- + Get information about an existing backup. + operationId: getRoomKeysVersion + security: + - accessToken: [] + parameters: + - in: path + type: string + name: version + description: |- + The backup version to get, as returned in the `version` parameter + of the response in + [`POST /_matrix/client/r0/room_keys/version`](/client-server/#post_matrixclientr0room_keysversion) + or this endpoint. + required: true + x-example: "1" + responses: + 200: + description: + The information about the requested backup. + schema: + type: object + properties: + algorithm: + type: string + description: The algorithm used for storing backups. + enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] + example: "m.megolm_backup.v1.curve25519-aes-sha2" + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: { + "public_key": "abcdefg", + "signatures": { + "@alice:example.org": { + "ed25519:deviceid": "signature" + } + } + } + count: + description: The number of keys stored in the backup. + type: integer + example: 42 + etag: + description: |- + An opaque string representing stored keys in the backup. + Clients can compare it with the `etag` value they received + in the request of their last key storage request. If not + equal, another client has modified the backup. + type: string + example: "anopaquestring" + version: + type: string + description: The backup version. + example: "1" + required: + - algorithm + - auth_data + - count + - etag + - version + 404: + description: + The backup specified does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + put: + summary: Update information about an existing backup. + description: |- + Update information about an existing backup. Only `auth_data` can be modified. + operationId: putRoomKeysVersion + security: + - accessToken: [] + parameters: + - in: path + type: string + name: version + description: |- + The backup version to update, as returned in the `version` + parameter in the response of + [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion) + or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion). + required: true + x-example: "1" + - in: body + name: version + description: "The backup configuration" + required: true + schema: + type: object + properties: + algorithm: + description: |- + The algorithm used for storing backups. Must be the same as + the algorithm currently used by the backup. + type: string + enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] + example: "m.megolm_backup.v1.curve25519-aes-sha2" + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: { + "public_key": "abcdefg", + "signatures": { + "@alice:example.org": { + "ed25519:deviceid": "signature" + } + } + } + version: + description: |- + The backup version. If present, must be the same as the + version in the path parameter. + type: string + example: "1" + required: + - algorithm + - auth_data + responses: + 200: + description: The update succeeded. + schema: + type: object + properties: {} + 400: + description: |- + A parameter was incorrect. For example, the `algorithm` does not + match the current backup algorithm, or the `version` in the body + does not match the `version` in the path. + examples: + application/json: { + "errcode": "M_INVALID_PARAM", + "error": "Algorithm does not match" + } + schema: + "$ref": "definitions/errors/error.yaml" + 404: + description: The backup specified does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + delete: + summary: Delete an existing key backup. + description: |- + Delete an existing key backup. Both the information about the backup, + as well as all key data related to the backup will be deleted. + operationId: deleteRoomKeysVersion + security: + - accessToken: [] + parameters: + - in: path + type: string + name: version + description: |- + The backup version to delete, as returned in the `version` + parameter in the response of + [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion) + or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion). + required: true + x-example: "1" + responses: + 200: + description: |- + The delete succeeded, or the specified backup was previously + deleted. + schema: + type: object + properties: {} + 404: + description: |- + The backup specified does not exist. If the backup was previously + deleted, the call should succeed rather than returning an error. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + "/room_keys/keys/{roomId}/{sessionId}": + put: + summary: Store a key in the backup. + description: |- + Store a key in the backup. + operationId: postRoomKeysKeyRoomIdSessionId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup in which to store the key. Must be the current backup. + required: true + x-example: "1" + - in: path + type: string + name: roomId + description: The ID of the room that the key is for. + required: true + x-example: "!roomid:example.org" + - in: path + type: string + name: sessionId + description: The ID of the megolm session that the key is for. + required: true + x-example: "sessionid" + - in: body + name: data + description: "The key data." + required: true + schema: + "$ref": "definitions/key_backup_data.yaml" + responses: + 200: + description: The update succeeded. + schema: + type: object + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: "abcdefg" + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + 403: + description: |- + The version specified does not match the current backup version. + The current version will be included in the `current_version` + field. + examples: + application/json: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + get: + summary: Retrieve a key from the backup + description: |- + Retrieve a key from the backup. + operationId: getRoomKeysKeyRoomIdSessionId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup from which to retrieve the key. + required: true + x-example: "1" + - in: path + type: string + name: roomId + description: The ID of the room that the requested key is for. + required: true + x-example: "!roomid:example.org" + - in: path + type: string + name: sessionId + description: The ID of the megolm session whose key is requested. + required: true + x-example: "sessionid" + responses: + 200: + description: The key data + schema: + "$ref": "definitions/key_backup_data.yaml" + 404: + description: The key or backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Key not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + delete: + summary: Delete a key from the backup + description: |- + Delete a key from the backup. + operationId: deleteRoomKeysKeyRoomIdSessionId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup from which to delete the key + required: true + x-example: "1" + - in: path + type: string + name: roomId + description: The ID of the room that the specified key is for. + required: true + x-example: "!roomid:example.org" + - in: path + type: string + name: sessionId + description: The ID of the megolm session whose key is to be deleted. + required: true + x-example: "sessionid" + responses: + 200: + description: The update succeeded + schema: + type: object + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: "abcdefg" + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + 404: + description: |- + The backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + "/room_keys/keys/{roomId}": + put: + summary: Store several keys in the backup for a given room. + description: |- + Store a key in the backup. + operationId: postRoomKeysKeyRoomId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup in which to store the keys. Must be the current backup. + required: true + x-example: "1" + - in: path + type: string + name: roomId + description: The ID of the room that the keys are for. + required: true + x-example: "!roomid:example.org" + - in: body + description: "The backup data" + name: backupData + required: true + schema: + $ref: "definitions/room_key_backup.yaml" + responses: + 200: + description: The update succeeded + schema: + type: object + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: "abcdefg" + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + 403: + description: |- + The version specified does not match the current backup version. + The current version will be included in the `current_version` + field. + examples: + application/json: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + schema: + "$ref": "definitions/errors/error.yaml" + 404: + description: |- + The backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + get: + summary: Retrieve the keys from the backup for a given room + description: |- + Retrieve the keys from the backup for a given room + operationId: getRoomKeysKeyRoomId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup from which to retrieve the key. + required: true + x-example: "1" + - in: path + type: string + name: roomId + description: The ID of the room that the requested key is for. + required: true + x-example: "!roomid:example.org" + responses: + 200: + description: |- + The key data. If no keys are found, then an object with an empty + `sessions` property will be returned (`{"sessions": {}}`). + schema: + type: object + $ref: "definitions/room_key_backup.yaml" + 404: + description: |- + The backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + delete: + summary: Delete a key from the backup + description: |- + Delete a key from the backup. + operationId: deleteRoomKeysKeyRoomId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup from which to delete the key. + required: true + x-example: "1" + - in: path + type: string + name: roomId + description: The ID of the room that the specified key is for. + required: true + x-example: "!roomid:example.org" + responses: + 200: + description: The update succeeded + schema: + type: object + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: "abcdefg" + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + 404: + description: |- + The backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + "/room_keys/keys": + put: + summary: Store several keys in the backup. + description: |- + Store several keys in the backup. + operationId: postRoomKeysKey + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup in which to store the keys. Must be the current backup. + required: true + x-example: "1" + - in: body + description: "The backup data." + name: backupData + required: true + schema: + type: object + properties: + rooms: + type: object + description: |- + A map of room IDs to room key backup data. + additionalProperties: + allOf: + - $ref: "definitions/room_key_backup.yaml" + example: { + "!room:example.org": { + "sessions": { + "sessionid1": { + "first_message_index": 1, + "forwarded_count": 0, + "is_verified": true, + "session_data": { + "ephemeral": "base64+ephemeral+key", + "ciphertext": "base64+ciphertext+of+JSON+data", + "mac": "base64+mac+of+ciphertext" + } + } + } + } + } + required: + - rooms + responses: + 200: + description: The update succeeded + schema: + type: object + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: "abcdefg" + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + 403: + description: |- + The version specified does not match the current backup version. + The current version will be included in the `current_version` + field. + examples: + application/json: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + schema: + "$ref": "definitions/errors/error.yaml" + 404: + description: |- + The backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - End-to-end encryption + get: + summary: Retrieve the keys from the backup for a given room + description: |- + Retrieve the keys from the backup for a given room + operationId: getRoomKeysKeyRoomId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup from which to retrieve the keys. + required: true + x-example: "1" + responses: + 200: + description: |- + The key data. If no keys are found, then an object with an empty + `rooms` property will be returned (`{"rooms": {}}`). + schema: + type: object + properties: + rooms: + type: object + description: |- + A map of room IDs to room key backup data. + additionalProperties: + allOf: + - $ref: "definitions/room_key_backup.yaml" + example: { + "!room:example.org": { + "sessions": { + "sessionid1": { + "first_message_index": 1, + "forwarded_count": 0, + "is_verified": true, + "session_data": { + "ephemeral": "base64+ephemeral+key", + "ciphertext": "base64+ciphertext+of+JSON+data", + "mac": "base64+mac+of+ciphertext" + } + } + } + } + } + 404: + description: The backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + delete: + summary: Delete a key from the backup + description: |- + Delete a key from the backup. + operationId: deleteRoomKeysKeyRoomId + security: + - accessToken: [] + parameters: + - in: query + type: string + name: version + description: |- + The backup from which to delete the key + required: true + x-example: "1" + responses: + 200: + description: The update succeeded + schema: + type: object + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: "abcdefg" + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + 404: + description: |- + The backup was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml new file mode 100644 index 000000000..e0788b6ba --- /dev/null +++ b/data/api/client-server/keys.yaml @@ -0,0 +1,481 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Client Config API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/keys/upload": + post: + summary: Upload end-to-end encryption keys. + description: |- + Publishes end-to-end encryption keys for the device. + operationId: uploadKeys + security: + - accessToken: [] + parameters: + - in: body + name: keys + description: |- + The keys to be published + required: true + schema: + type: object + properties: + device_keys: + description: |- + Identity keys for the device. May be absent if no new + identity keys are required. + allOf: + - $ref: definitions/device_keys.yaml + one_time_keys: + type: object + description: |- + One-time public keys for "pre-key" messages. The names of + the properties should be in the format + `:`. The format of the key is determined + by the [key algorithm](/client-server-api/#key-algorithms). + + May be absent if no new one-time keys are required. + additionalProperties: + type: + - string + - object + # XXX: We can't define an actual object here, so we have to hope + # that people will look at the swagger source or can figure it out + # from the other endpoints/example. + # - type: object + # title: KeyObject + # properties: + # key: + # type: string + # description: The key, encoded using unpadded base64. + # signatures: + # type: object + # description: |- + # Signature for the device. Mapped from user ID to signature object. + # additionalProperties: + # type: string + # required: ['key', 'signatures'] + example: { + "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", + "signed_curve25519:AAAAHg": { + "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + } + } + }, + "signed_curve25519:AAAAHQ": { + "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" + } + } + } + } + responses: + 200: + description: + The provided keys were successfully uploaded. + schema: + type: object + properties: + one_time_key_counts: + type: object + additionalProperties: + type: integer + description: |- + For each key algorithm, the number of unclaimed one-time keys + of that type currently held on the server for this device. + example: + curve25519: 10 + signed_curve25519: 20 + required: + - one_time_key_counts + + tags: + - End-to-end encryption + "/keys/query": + post: + summary: Download device identity keys. + description: |- + Returns the current devices and identity keys for the given users. + operationId: queryKeys + security: + - accessToken: [] + parameters: + - in: body + name: query + description: |- + Query defining the keys to be downloaded + required: true + schema: + type: object + properties: + timeout: + type: integer + description: |- + The time (in milliseconds) to wait when downloading keys from + remote servers. 10 seconds is the recommended default. + example: 10000 + device_keys: + type: object + description: |- + The keys to be downloaded. A map from user ID, to a list of + device IDs, or to an empty list to indicate all devices for the + corresponding user. + additionalProperties: + type: array + items: + type: string + description: "device ID" + example: + "@alice:example.com": [] + token: + type: string + description: |- + If the client is fetching keys as a result of a device update received + in a sync request, this should be the 'since' token of that sync request, + or any later sync token. This allows the server to ensure its response + contains the keys advertised by the notification in that sync. + required: + - device_keys + + responses: + 200: + description: + The device information + schema: + type: object + properties: + failures: + type: object + description: |- + If any remote homeservers could not be reached, they are + recorded here. The names of the properties are the names of + the unreachable servers. + + If the homeserver could be reached, but the user or device + was unknown, no failure is recorded. Instead, the corresponding + user or device is missing from the `device_keys` result. + additionalProperties: + type: object + example: {} + device_keys: + type: object + description: |- + Information on the queried devices. A map from user ID, to a + map from device ID to device information. For each device, + the information returned will be the same as uploaded via + `/keys/upload`, with the addition of an `unsigned` + property. + additionalProperties: + type: object + additionalProperties: + title: DeviceInformation + allOf: + - $ref: definitions/device_keys.yaml + properties: + unsigned: + title: UnsignedDeviceInfo + type: object + description: |- + Additional data added to the device key information + by intermediate servers, and not covered by the + signatures. + properties: + device_display_name: + type: string + description: + The display name which the user set on the device. + example: + "@alice:example.com": + JLAFKJWSCS: { + "user_id": "@alice:example.com", + "device_id": "JLAFKJWSCS", + "algorithms": [ + "m.olm.v1.curve25519-aes-sha2", + "m.megolm.v1.aes-sha2" + ], + "keys": { + "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", + "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" + }, + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" + } + }, + "unsigned": { + "device_display_name": "Alice's mobile phone" + } + } + master_keys: + type: object + description: |- + Information on the master cross-signing keys of the queried users. + A map from user ID, to master key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the requesting user + is allowed to see. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: { + "@alice:example.com": { + "user_id": "@alice:example.com", + "usage": ["master"], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key", + } + } + } + self_signing_keys: + type: object + description: |- + Information on the self-signing keys of the queried users. A map + from user ID, to self-signing key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: { + "@alice:example.com": { + "user_id": "@alice:example.com", + "usage": ["self_signing"], + "keys": { + "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+self+signing+key" + } + } + } + } + user_signing_keys: + type: object + description: |- + Information on the user-signing key of the user making the + request, if they queried their own device information. A map + from user ID, to user-signing key information. The + information returned will be the same as uploaded via + `/keys/device_signing/upload`. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: { + "@alice:example.com": { + "user_id": "@alice:example.com", + "usage": ["user_signing"], + "keys": { + "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+user+signing+key" + } + } + } + } + tags: + - End-to-end encryption + "/keys/claim": + post: + summary: Claim one-time encryption keys. + description: |- + Claims one-time keys for use in pre-key messages. + operationId: claimKeys + security: + - accessToken: [] + parameters: + - in: body + name: query + description: |- + Query defining the keys to be claimed + required: true + schema: + type: object + properties: + timeout: + type: integer + description: |- + The time (in milliseconds) to wait when downloading keys from + remote servers. 10 seconds is the recommended default. + example: 10000 + one_time_keys: + type: object + description: |- + The keys to be claimed. A map from user ID, to a map from + device ID to algorithm name. + additionalProperties: + type: object + additionalProperties: + type: string + description: algorithm + example: "signed_curve25519" + example: { + "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } + } + required: + - one_time_keys + responses: + 200: + description: + The claimed keys. + schema: + type: object + properties: + failures: + type: object + description: |- + If any remote homeservers could not be reached, they are + recorded here. The names of the properties are the names of + the unreachable servers. + + If the homeserver could be reached, but the user or device + was unknown, no failure is recorded. Instead, the corresponding + user or device is missing from the `one_time_keys` result. + additionalProperties: + type: object + example: {} + one_time_keys: + type: object + description: |- + One-time keys for the queried devices. A map from user ID, to a + map from devices to a map from `:` to the key object. + + See the [key algorithms](/client-server-api/#key-algorithms) section for information + on the Key Object format. + additionalProperties: + type: object + additionalProperties: + type: + - string + - object + # XXX: We can't define an actual object here, so we have to hope + # that people will look at the swagger source or can figure it out + # from the other endpoints/example. + # - type: object + # title: KeyObject + # properties: + # key: + # type: string + # description: The key, encoded using unpadded base64. + # signatures: + # type: object + # description: |- + # Signature for the device. Mapped from user ID to signature object. + # additionalProperties: + # type: string + # required: ['key', 'signatures'] + example: { + "@alice:example.com": { + "JLAFKJWSCS": { + "signed_curve25519:AAAAHg": { + "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + } + } + } + } + } + } + required: ['one_time_keys'] + tags: + - End-to-end encryption + "/keys/changes": + get: + summary: Query users with recent device key updates. + description: |- + Gets a list of users who have updated their device identity keys since a + previous sync token. + + The server should include in the results any users who: + + * currently share a room with the calling user (ie, both users have + membership state `join`); *and* + * added new device identity keys or removed an existing device with + identity keys, between `from` and `to`. + operationId: getKeysChanges + security: + - accessToken: [] + parameters: + - in: query + name: from + type: string + description: |- + The desired start point of the list. Should be the `next_batch` field + from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientr0sync). Users who have not + uploaded new device identity keys since this point, nor deleted + existing devices with identity keys since then, will be excluded + from the results. + required: true + x-example: "s72594_4483_1934" + - in: query + name: to + type: string + description: |- + The desired end point of the list. Should be the `next_batch` + field from a recent call to [`/sync`](/client-server-api/#get_matrixclientr0sync) - typically the most recent + such call. This may be used by the server as a hint to check its + caches are up to date. + required: true + x-example: "s75689_5632_2435" + responses: + 200: + description: + The list of users who updated their devices. + schema: + type: object + properties: + changed: + type: array + items: + type: string + description: |- + The Matrix User IDs of all users who updated their device + identity keys. + example: ["@alice:example.com", "@bob:example.org"] + left: + type: array + items: + type: string + description: |- + The Matrix User IDs of all users who may have left all + the end-to-end encrypted rooms they previously shared + with the user. + example: ["@clara:example.com", "@doug:example.org"] + tags: + - End-to-end encryption diff --git a/data/api/client-server/kicking.yaml b/data/api/client-server/kicking.yaml new file mode 100644 index 000000000..bf6738e1f --- /dev/null +++ b/data/api/client-server/kicking.yaml @@ -0,0 +1,94 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +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: + $ref: definitions/security.yaml +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. + + Kicking a user adjusts the target member's membership state to be `leave` with an + optional `reason`. 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/`. + operationId: kick + 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. This will be supplied as the + `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. + 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." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room membership diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml new file mode 100644 index 000000000..f3d3b4860 --- /dev/null +++ b/data/api/client-server/leaving.yaml @@ -0,0 +1,130 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Leaving API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/leave": + post: + summary: Stop the requesting user participating in a particular room. + description: |- + This API stops a user participating in a particular room. + + If the user was already in the room, they will no longer be able to see + new events in the room. If the room requires an invite to join, they + will need to be re-invited before they can re-join. + + If the user was invited to the room, but had not joined, this call + serves to reject the invite. + + The user will still be allowed to retrieve history from the room which + they were previously allowed to see. + operationId: leaveRoom + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier to leave. + required: true + x-example: "!nkl290a:matrix.org" + - in: body + name: body + required: true + schema: + type: object + example: { + "reason": "Saying farewell - thanks for the support!" + } + properties: + reason: + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + responses: + 200: + description: |- + The room has been left. + examples: + application/json: { + } + schema: + type: object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room membership + "/rooms/{roomId}/forget": + post: + summary: Stop the requesting user remembering about a particular room. + description: |- + This API stops a user remembering about a particular room. + + In general, history is a first class citizen in Matrix. After this API + is called, however, a user will no longer be able to retrieve history + for this room. If all users on a homeserver forget a room, the room is + eligible for deletion from that homeserver. + + If the user is currently joined to the room, they must leave the room + before calling this API. + operationId: forgetRoom + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier to forget. + required: true + x-example: "!au1ba7o:matrix.org" + responses: + 200: + description: |- + The room has been forgotten. + examples: + application/json: { + } + schema: + type: object + 400: + description: The user has not left the room + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "User @example:matrix.org is in room !au1ba7o:matrix.org" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room membership diff --git a/data/api/client-server/list_joined_rooms.yaml b/data/api/client-server/list_joined_rooms.yaml new file mode 100644 index 000000000..b34f3d5d2 --- /dev/null +++ b/data/api/client-server/list_joined_rooms.yaml @@ -0,0 +1,58 @@ +# Copyright 2017 Michael Telatynski <7t3chguy@gmail.com> +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Listing API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/joined_rooms": + get: + summary: Lists the user's current rooms. + description: |- + This API returns a list of the user's current rooms. + operationId: getJoinedRooms + security: + - accessToken: [] + responses: + 200: + description: A list of the rooms the user is in. + schema: + type: object + required: ["joined_rooms"] + properties: + joined_rooms: + type: array + description: |- + The ID of each room in which the user has `joined` membership. + items: + type: string + examples: + application/json: { + "joined_rooms": [ + "!foo:example.com" + ] + } + tags: + - Room membership diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml new file mode 100644 index 000000000..4175b0a96 --- /dev/null +++ b/data/api/client-server/list_public_rooms.yaml @@ -0,0 +1,223 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Directory API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +paths: + "/directory/list/room/{roomId}": + get: + summary: Gets the visibility of a room in the directory + description: |- + Gets the visibility of a given room on the server's public room directory. + operationId: getRoomVisibilityOnDirectory + parameters: + - in: path + type: string + name: roomId + description: The room ID. + required: true + x-example: "!curbf:matrix.org" + responses: + 200: + description: The visibility of the room in the directory + schema: + type: object + properties: + visibility: + type: string + enum: ['private', 'public'] + description: The visibility of the room in the directory. + examples: + application/json: { + "visibility": "public" + } + 404: + description: The room is not known to the server + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } + schema: + "$ref": "definitions/errors/error.yaml" + put: + summary: Sets the visibility of a room in the room directory + description: |- + Sets the visibility of a given room in the server's public room + directory. + + Servers may choose to implement additional access control checks + here, for instance that room visibility can only be changed by + the room creator or a server administrator. + operationId: setRoomVisibilityOnDirectory + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID. + required: true + x-example: "!curbf:matrix.org" + - in: body + name: body + required: true + description: |- + The new visibility for the room on the room directory. + schema: + type: object + properties: + visibility: + type: string + enum: ["private", "public"] + description: |- + The new visibility setting for the room. + Defaults to 'public'. + example: { + "visibility": "public" + } + responses: + 200: + description: The visibility was updated, or no change was needed. + examples: + application/json: {} + 404: + description: The room is not known to the server + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } + schema: + "$ref": "definitions/errors/error.yaml" + "/publicRooms": + get: + summary: Lists the public rooms on the server. + description: |- + Lists the public rooms on the server. + + This API returns paginated responses. The rooms are ordered by the number + of joined members, with the largest rooms first. + operationId: getPublicRooms + parameters: + - in: query + name: limit + type: integer + description: |- + Limit the number of results returned. + - in: query + name: since + type: string + description: |- + A pagination token from a previous request, allowing clients to + get the next (or previous) batch of rooms. + The direction of pagination is specified solely by which token + is supplied, rather than via an explicit flag. + - in: query + name: server + type: string + description: |- + The server to fetch the public room lists from. Defaults to the + local server. + responses: + 200: + description: A list of the rooms on the server. + schema: + $ref: "definitions/public_rooms_response.yaml" + tags: + - Room discovery + post: + summary: Lists the public rooms on the server with optional filter. + description: |- + Lists the public rooms on the server, with optional filter. + + This API returns paginated responses. The rooms are ordered by the number + of joined members, with the largest rooms first. + operationId: queryPublicRooms + security: + - accessToken: [] + parameters: + - in: query + name: server + type: string + description: |- + The server to fetch the public room lists from. Defaults to the + local server. + - in: body + name: body + required: true + description: |- + Options for which rooms to return. + schema: + type: object + properties: + limit: + type: integer + description: |- + Limit the number of results returned. + since: + type: string + description: |- + A pagination token from a previous request, allowing clients + to get the next (or previous) batch of rooms. The direction + of pagination is specified solely by which token is supplied, + rather than via an explicit flag. + filter: + type: object + title: "Filter" + description: |- + Filter to apply to the results. + properties: + generic_search_term: + type: string + description: |- + A string to search for in the room metadata, e.g. name, + topic, canonical alias etc. (Optional). + include_all_networks: + type: boolean + description: |- + Whether or not to include all known networks/protocols from + application services on the homeserver. Defaults to false. + example: false + third_party_instance_id: + type: string + description: |- + The specific third party network/protocol to request from the + homeserver. Can only be used if `include_all_networks` is false. + example: "irc" + example: { + "limit": 10, + "filter": { + "generic_search_term": "foo" + }, + "include_all_networks": false, + "third_party_instance_id": "irc" + } + responses: + 200: + description: A list of the rooms on the server. + schema: + $ref: "definitions/public_rooms_response.yaml" + tags: + - Room discovery diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml new file mode 100644 index 000000000..14aa3aafc --- /dev/null +++ b/data/api/client-server/login.yaml @@ -0,0 +1,216 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Registration and Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/login": + get: + summary: Get the supported login types to authenticate users + description: |- + Gets the homeserver's supported login types to authenticate users. Clients + should pick one of these and supply it as the `type` when logging in. + operationId: getLoginFlows + responses: + 200: + description: The login types the homeserver supports + examples: + application/json: { + "flows": [ + {"type": "m.login.password"} + ] + } + schema: + type: object + properties: + flows: + type: array + description: The homeserver's supported login types + items: + type: object + title: LoginFlow + properties: + type: + description: |- + The login type. This is supplied as the `type` when + logging in. + type: string + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Session management + post: + summary: Authenticates the user. + description: |- + Authenticates the user, and issues an access token they can + use to authorize themself in subsequent requests. + + If the client does not supply a `device_id`, the server must + auto-generate one. + + The returned access token must be associated with the `device_id` + supplied by the client or generated by the server. The server may + invalidate any access token previously associated with that device. See + [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices). + operationId: login + parameters: + - in: body + name: body + required: true + schema: + type: object + example: { + "type": "m.login.password", + "identifier": { + "type": "m.id.user", + "user": "cheeky_monkey" + }, + "password": "ilovebananas", + "initial_device_display_name": "Jungle Phone" + } + properties: + type: + type: string + enum: ["m.login.password", "m.login.token"] + description: The login type being used. + identifier: + "$ref": "definitions/user_identifier.yaml" + user: + type: string + description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. + medium: + type: string + description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. + address: + type: string + description: Third party identifier for the user. Deprecated in favour of `identifier`. + password: + type: string + description: |- + Required when `type` is `m.login.password`. The user's + password. + token: + type: string + description: |- + Required when `type` is `m.login.token`. Part of Token-based login. + device_id: + type: string + description: |- + ID of the client device. If this does not correspond to a + known client device, a new device will be created. The given + device ID must not be the same as a + [cross-signing](/client-server-api/#cross-signing) key ID. + The server will auto-generate a device_id + if this is not specified. + initial_device_display_name: + type: string + description: |- + A display name to assign to the newly-created device. Ignored + if `device_id` corresponds to a known device. + required: ["type"] + + responses: + 200: + description: The user has been authenticated. + examples: + application/json: { + "user_id": "@cheeky_monkey:matrix.org", + "access_token": "abc123", + "device_id": "GHTYAJCE", + "well_known": { + "m.homeserver": { + "base_url": "https://example.org" + }, + "m.identity_server": { + "base_url": "https://id.example.org" + } + } + } + schema: + type: object + properties: + user_id: + type: string + description: The fully-qualified Matrix ID for the account. + access_token: + type: string + description: |- + An access token for the account. + This access token can then be used to authorize other requests. + home_server: + type: string + description: |- + The server_name of the homeserver on which the account has + been registered. + + **Deprecated**. Clients should extract the server_name from + `user_id` (by splitting at the first colon) if they require + it. Note also that `homeserver` is not spelt this way. + device_id: + type: string + description: |- + ID of the logged-in device. Will be the same as the + corresponding parameter in the request, if one was specified. + well_known: + description: |- + Optional client configuration provided by the server. If present, + clients SHOULD use the provided object to reconfigure themselves, + optionally validating the URLs within. This object takes the same + form as the one returned from .well-known autodiscovery. + allOf: + - "$ref": "definitions/wellknown/full.yaml" + 400: + description: |- + Part of the request was invalid. For example, the login type may not be recognised. + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "Bad login type." + } + schema: + "$ref": "definitions/errors/error.yaml" + 403: + description: |- + The login attempt failed. This can include one of the following error codes: + * `M_FORBIDDEN`: The provided authentication data was incorrect + or the requested device ID is the same as a cross-signing key + ID. + * `M_USER_DEACTIVATED`: The user has been deactivated. + examples: + application/json: { + "errcode": "M_FORBIDDEN" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Session management diff --git a/data/api/client-server/logout.yaml b/data/api/client-server/logout.yaml new file mode 100644 index 000000000..7be4f51c3 --- /dev/null +++ b/data/api/client-server/logout.yaml @@ -0,0 +1,73 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Registration and Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/logout": + post: + summary: Invalidates a user access token + description: |- + Invalidates an existing access token, so that it can no longer be used for + authorization. The device associated with the access token is also deleted. + [Device keys](/client-server-api/#device-keys) for the device are deleted alongside the device. + operationId: logout + security: + - accessToken: [] + responses: + 200: + description: The access token used in the request was successfully invalidated. + schema: + type: object + properties: {} + tags: + - Session management + "/logout/all": + post: + summary: Invalidates all access tokens for a user + description: |- + Invalidates all access tokens for a user, so that they can no longer be used for + authorization. This includes the access token that made this request. All devices + for the user are also deleted. [Device keys](/client-server-api/#device-keys) for the device are + deleted alongside the device. + + This endpoint does not use the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) because + User-Interactive Authentication is designed to protect against attacks where the + someone gets hold of a single access token then takes over the account. This + endpoint invalidates all access tokens for the user, including the token used in + the request, and therefore the attacker is unable to take over the account in + this way. + operationId: logout_all + security: + - accessToken: [] + responses: + 200: + description: The user's access tokens were successfully invalidated. + schema: + type: object + properties: {} + tags: + - Session management diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml new file mode 100644 index 000000000..5b86ce901 --- /dev/null +++ b/data/api/client-server/message_pagination.yaml @@ -0,0 +1,151 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Rooms API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/messages": + get: + summary: Get a list of events for this room + description: |- + This API returns a list of message and state events for a room. It uses + pagination query parameters to paginate history in the room. + + *Note*: This endpoint supports lazy-loading of room member events. See + [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information. + operationId: getRoomEvents + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to get events from. + required: true + x-example: "!636q39766251:example.com" + - in: query + type: string + name: from + description: |- + The token to start returning events from. This token can be obtained + from a `prev_batch` token returned for each room by the sync API, + or from a `start` or `end` token returned by a previous request + to this endpoint. + required: true + x-example: "s345_678_333" + - in: query + type: string + name: to + description: |- + The token to stop returning events at. This token can be obtained from + a `prev_batch` token returned for each room by the sync endpoint, + or from a `start` or `end` token returned by a previous request to + this endpoint. + required: false + - in: query + type: string + enum: ["b", "f"] + name: dir + description: |- + The direction to return events from. + required: true + x-example: "b" + - in: query + type: integer + name: limit + description: |- + The maximum number of events to return. Default: 10. + x-example: "3" + - in: query + type: string + name: filter + description: |- + A JSON RoomEventFilter to filter returned events with. + x-example: |- + {"contains_url":true} + responses: + 200: + description: A list of messages with a new token to request more. + schema: + type: object + description: A list of messages with a new token to request more. + properties: + start: + type: string + description: |- + The token the pagination starts from. If `dir=b` this will be + the token supplied in `from`. + end: + type: string + description: |- + The token the pagination ends at. If `dir=b` this token should + be used again to request even earlier events. + chunk: + type: array + description: |- + A list of room events. The order depends on the `dir` parameter. + For `dir=b` events will be in reverse-chronological order, + for `dir=f` in chronological order, so that events start + at the `from` point. + items: + "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + state: + type: array + description: |- + A list of state events relevant to showing the `chunk`. For example, if + `lazy_load_members` is enabled in the filter then this may contain + the membership events for the senders of events in the `chunk`. + + Unless `include_redundant_members` is `true`, the server + may remove membership events which would have already been + sent to the client in prior calls to this endpoint, assuming + the membership of those members has not changed. + items: + $ref: "../../event-schemas/schema/core-event-schema/state_event.yaml" + examples: + application/json: { + "start": "t47429-4392820_219380_26003_2265", + "end": "t47409-4357353_219380_26003_2265", + "chunk": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.name.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml" + } + ] + } + 403: + description: > + You aren't a member of the room. + tags: + - Room participation diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml new file mode 100644 index 000000000..7d0174037 --- /dev/null +++ b/data/api/client-server/notifications.yaml @@ -0,0 +1,133 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Client-Server Notifications API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/notifications": + get: + summary: Gets a list of events that the user has been notified about + description: |- + This API is used to paginate through the list of events that the + user has been, or would have been notified about. + operationId: getNotifications + security: + - accessToken: [] + parameters: + - in: query + type: string + name: from + description: Pagination token given to retrieve the next set of events. + required: false + x-example: "xxxxx" + - in: query + type: integer + name: limit + description: Limit on the number of events to return in this request. + required: false + x-example: 20 + - in: query + name: only + type: string + description: |- + Allows basic filtering of events returned. Supply `highlight` + to return only events where the notification had the highlight + tweak set. + required: false + x-example: "highlight" + responses: + 200: + description: A batch of events is being returned + examples: + application/json: { + "next_token": "abcdef", + "notifications": [ + { + "actions": [ + "notify" + ], + "profile_tag": "hcbvkzxhcvb", + "read": true, + "room_id": "!abcdefg:example.com", + "ts": 1475508881945, + "event": { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + } + ] + } + schema: + type: object + required: ["notifications"] + properties: + next_token: + type: string + description: |- + The token to supply in the `from` param of the next + `/notifications` request in order to request more + events. If this is absent, there are no more results. + notifications: + type: array + items: + type: object + required: ["actions", "event", "read", "room_id", "ts"] + title: Notification + properties: + actions: + type: array + description: |- + The action(s) to perform when the conditions for this rule are met. + See [Push Rules: API](/client-server-api/#push-rules-api). + items: + type: + - object + - string + event: + type: object + title: Event + description: The Event object for the event that triggered the notification. + allOf: + - "$ref": "definitions/event.yaml" + profile_tag: + type: string + description: The profile tag of the rule that matched this event. + read: + type: boolean + description: |- + Indicates whether the user has sent a read receipt indicating + that they have read this message. + room_id: + type: string + description: The ID of the room in which the event was posted. + ts: + type: integer + description: |- + The unix timestamp at which the event notification was sent, + in milliseconds. + description: The list of events that triggered notifications. + tags: + - Push notifications diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml new file mode 100644 index 000000000..522f0b1a4 --- /dev/null +++ b/data/api/client-server/old_sync.yaml @@ -0,0 +1,338 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Sync API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/events": + get: + summary: Listen on the event stream. + description: |- + This will listen for new events and return them to the caller. This will + block until an event is received, or until the `timeout` is reached. + + This endpoint was deprecated in r0 of this specification. Clients + should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync) + API with a `since` parameter. See + the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + operationId: getEvents + security: + - accessToken: [] + parameters: + - in: query + type: string + name: from + description: |- + The token to stream from. This token is either from a previous + request to this API or from the initial sync API. + required: false + x-example: "s3456_9_0" + - in: query + type: integer + name: timeout + description: The maximum time in milliseconds to wait for an event. + required: false + x-example: "35000" + responses: + 200: + description: "The events received, which may be none." + examples: + application/json: { + "start": "s3456_9_0", + "end": "s3457_9_0", + "chunk": [ + {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} + ] + } + schema: + type: object + properties: + start: + type: string + description: |- + A token which correlates to the first value in `chunk`. This + is usually the same token supplied to `from=`. + end: + type: string + description: |- + A token which correlates to the last value in `chunk`. This + token should be used in the next request to `/events`. + chunk: + type: array + description: "An array of events." + items: + type: object + title: Event + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + 400: + description: "Bad pagination `from` parameter." + tags: + - Room participation + deprecated: true + "/initialSync": + get: + summary: Get the user's current state. + description: |- + This returns the full state for this user, with an optional limit on the + number of messages per room to return. + + This endpoint was deprecated in r0 of this specification. Clients + should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync) + API with no `since` parameter. See + the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + operationId: initialSync + security: + - accessToken: [] + parameters: + - in: query + type: integer + name: limit + description: The maximum number of messages to return for each room. + required: false + x-example: "2" + - in: query + type: boolean + name: archived + description: |- + Whether to include rooms that the user has left. If `false` then + only rooms that the user has been invited to or has joined are + included. If set to `true` then rooms that the user has left are + included as well. By default this is `false`. + required: false + x-example: "true" + responses: + 200: + description: The user's current state. + examples: + application/json: { + "end": "s3456_9_0", + "presence": [ + {"$ref": "../../event-schemas/examples/m.presence.yaml"} + ], + "account_data": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ], + "rooms": [ + { + "membership": "join", + "messages": { + "chunk": [ + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml" + } + ], + "end": "s3456_9_0", + "start": "t44-3453_9_0" + }, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state": [ + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ], + "visibility": "private", + "account_data": [ + { + "type": "m.tag", + "content": {"tags": {"work": {"order": 1}}} + }, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + } + ] + } + schema: + type: object + properties: + end: + type: string + description: |- + A token which correlates to the last value in `chunk`. This + token should be used with the `/events` API to listen for new + events. + presence: + type: array + description: A list of presence events. + items: + type: object + title: Event + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" + rooms: + type: array + items: + type: object + title: RoomInfo + properties: + room_id: + type: string + description: "The ID of this room." + membership: + type: string + description: "The user's membership state in this room." + enum: ["invite", "join", "leave", "ban"] + invite: + type: object + title: "InviteEvent" + description: "The invite event if `membership` is `invite`" + allOf: + - "$ref": "../../event-schemas/schema/m.room.member.yaml" + messages: + type: object + title: PaginationChunk + description: "The pagination chunk for this room." + properties: + start: + type: string + description: |- + A token which correlates to the first value in `chunk`. + Used for pagination. + end: + type: string + description: |- + A token which correlates to the last value in `chunk`. + Used for pagination. + chunk: + type: array + description: |- + If the user is a member of the room this will be a + list of the most recent messages for this room. If + the user has left the room this will be the + messages that preceeded them leaving. This array + will consist of at most `limit` elements. + items: + type: object + title: RoomEvent + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + required: ["start", "end", "chunk"] + state: + type: array + description: |- + If the user is a member of the room this will be the + current state of the room as a list of events. If the + user has left the room this will be the state of the + room when they left it. + items: + title: StateEvent + type: object + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml" + visibility: + type: string + enum: ["private", "public"] + description: |- + Whether this room is visible to the `/publicRooms` API + or not." + account_data: + type: array + description: |- + The private data that this user has attached to + this room. + items: + title: Event + type: object + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" + required: ["room_id", "membership"] + account_data: + type: array + description: |- + The global private data created by this user. + items: + title: Event + type: object + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" + required: ["end", "rooms", "presence"] + 404: + description: There is no avatar URL for this user or this user does not exist. + tags: + - Room participation + deprecated: true + "/events/{eventId}": + get: + summary: Get a single event by event ID. + description: |- + Get a single event based on `event_id`. You must have permission to + retrieve this event e.g. by being a member in the room for this event. + + This endpoint was deprecated in r0 of this specification. Clients + should instead call the + [/rooms/{roomId}/event/{eventId}](/client-server-api/#get_matrixclientr0roomsroomideventeventid) API + or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientr0roomsroomidcontexteventid) API. + operationId: getOneEvent + security: + - accessToken: [] + parameters: + - in: path + type: string + name: eventId + description: The event ID to get. + required: true + x-example: "$asfDuShaf7Gafaw:matrix.org" + responses: + 200: + description: The full event. + examples: + application/json: {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} + schema: + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" + 404: + description: The event was not found or you do not have permission to read this event. + tags: + - Room participation + deprecated: true diff --git a/data/api/client-server/openid.yaml b/data/api/client-server/openid.yaml new file mode 100644 index 000000000..ef76e3d09 --- /dev/null +++ b/data/api/client-server/openid.yaml @@ -0,0 +1,83 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server OpenID API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user/{userId}/openid/request_token": + post: + summary: Get an OpenID token object to verify the requester's identity. + description: |- + Gets an OpenID token object that the requester may supply to another + service to verify their identity in Matrix. The generated token is only + valid for exchanging for user information from the federation API for + OpenID. + + The access token generated is only valid for the OpenID API. It cannot + be used to request another OpenID access token or call `/sync`, for + example. + operationId: requestOpenIdToken + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: |- + The user to request and OpenID token for. Should be the user who + is authenticated for the request. + required: true + x-example: "@alice:example.com" + - in: body + name: body + description: An empty object. Reserved for future expansion. + required: true + schema: + type: object + example: {} + responses: + 200: + description: |- + OpenID token information. This response is nearly compatible with the + response documented in the + [OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) + with the only difference being the lack of an `id_token`. Instead, + the Matrix homeserver's name is provided. + examples: + application/json: { + "access_token": "SomeT0kenHere", + "token_type": "Bearer", + "matrix_server_name": "example.com", + "expires_in": 3600, + } + schema: + $ref: "definitions/openid_token.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - OpenID diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml new file mode 100644 index 000000000..85eb87683 --- /dev/null +++ b/data/api/client-server/peeking_events.yaml @@ -0,0 +1,106 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Sync Guest API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/events": + get: + summary: Listen on the event stream. + description: |- + This will listen for new events related to a particular room and return + them to the caller. This will block until an event is received, or until + the `timeout` is reached. + + This API is the same as the normal `/events` endpoint, but can be + called by users who have not joined the room. + + Note that the normal `/events` endpoint has been deprecated. This + API will also be deprecated at some point, but its replacement is not + yet known. + operationId: peekEvents + security: + - accessToken: [] + parameters: + - in: query + type: string + name: from + description: |- + The token to stream from. This token is either from a previous + request to this API or from the initial sync API. + required: false + x-example: "s3456_9_0" + - in: query + type: integer + name: timeout + description: The maximum time in milliseconds to wait for an event. + required: false + x-example: "35000" + - in: query + type: string + name: room_id + description: |- + The room ID for which events should be returned. + x-example: + - "!somewhere:over.the.rainbow" + responses: + 200: + description: "The events received, which may be none." + examples: + application/json: { + "start": "s3456_9_0", + "end": "s3457_9_0", + "chunk": [ + { + "room_id": "!somewhere:over.the.rainbow", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ] + } + schema: + type: object + properties: + start: + type: string + description: |- + A token which correlates to the first value in `chunk`. This + is usually the same token supplied to `from=`. + end: + type: string + description: |- + A token which correlates to the last value in `chunk`. This + token should be used in the next request to `/events`. + chunk: + type: array + description: "An array of events." + items: + type: object + title: Event + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + 400: + description: "Bad pagination `from` parameter." + # No tags to exclude this from the swagger UI - use the normal version instead. diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml new file mode 100644 index 000000000..003de8ca6 --- /dev/null +++ b/data/api/client-server/presence.yaml @@ -0,0 +1,138 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Presence API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/presence/{userId}/status": + put: + summary: Update this user's presence state. + description: |- + This API sets the given user's presence state. When setting the status, + the activity time is updated to reflect that activity; the client does + not need to specify the `last_active_ago` field. You cannot set the + presence state of another user. + operationId: setPresence + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: The user whose presence state to update. + required: true + x-example: "@alice:example.com" + - in: body + name: presenceState + description: The updated presence state. + required: true + schema: + type: object + example: { + "presence": "online", + "status_msg": "I am here." + } + properties: + presence: + type: string + enum: ["online", "offline", "unavailable"] + description: The new presence state. + status_msg: + type: string + description: The status message to attach to this state. + required: ["presence"] + responses: + 200: + description: The new presence state was set. + examples: + application/json: { + } + schema: + type: object # empty json object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Presence + get: + summary: Get this user's presence state. + description: |- + Get the given user's presence state. + operationId: getPresence + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: The user whose presence state to get. + required: true + x-example: "@alice:example.com" + responses: + 200: + description: The presence state for this user. + examples: + application/json: { + "presence": "unavailable", + "last_active_ago": 420845 + } + schema: + type: object + properties: + presence: + type: string + enum: ["online", "offline", "unavailable"] + description: This user's presence. + last_active_ago: + type: integer + description: |- + The length of time in milliseconds since an action was performed + by this user. + status_msg: + type: [string, "null"] + description: The state message for this user if one was set. + currently_active: + type: boolean + description: "Whether the user is currently active" + required: ["presence"] + 404: + description: |- + There is no presence state for this user. This user may not exist or + isn't exposing presence information to you. + schema: + "$ref": "definitions/errors/error.yaml" + 403: + description: You are not allowed to see this user's presence status. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to see their presence" + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Presence diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml new file mode 100644 index 000000000..6a8d6a775 --- /dev/null +++ b/data/api/client-server/profile.yaml @@ -0,0 +1,214 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Profile API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/profile/{userId}/displayname": + put: + summary: Set the user's display name. + description: |- + This API sets the given user's display name. You must have permission to + set this user's display name, e.g. you need to have their `access_token`. + operationId: setDisplayName + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: The user whose display name to set. + required: true + x-example: "@alice:example.com" + - in: body + name: displayName + description: The new display name information. + required: true + schema: + type: object + example: { + "displayname": "Alice Margatroid" + } + properties: + displayname: + type: string + description: The new display name for this user. + responses: + 200: + description: The display name was set. + examples: + application/json: { + } + schema: + type: object # empty json object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data + get: + summary: Get the user's display name. + description: |- + Get the user's display name. This API may be used to fetch the user's + own displayname or to query the name of other users; either locally or + on remote homeservers. + operationId: getDisplayName + parameters: + - in: path + type: string + name: userId + description: The user whose display name to get. + required: true + x-example: "@alice:example.com" + responses: + 200: + description: The display name for this user. + examples: + application/json: { + "displayname": "Alice Margatroid" + } + schema: + type: object + properties: + displayname: + type: string + description: The user's display name if they have set one, otherwise not present. + 404: + description: There is no display name for this user or this user does not exist. + tags: + - User data + "/profile/{userId}/avatar_url": + put: + summary: Set the user's avatar URL. + description: |- + This API sets the given user's avatar URL. You must have permission to + set this user's avatar URL, e.g. you need to have their `access_token`. + operationId: setAvatarUrl + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: The user whose avatar URL to set. + required: true + x-example: "@alice:example.com" + - in: body + name: avatar_url + description: The new avatar information. + required: true + schema: + type: object + example: { + "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34" + } + properties: + avatar_url: + type: string + description: The new avatar URL for this user. + responses: + 200: + description: The avatar URL was set. + examples: + application/json: { + } + schema: + type: object # empty json object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data + get: + summary: Get the user's avatar URL. + description: |- + Get the user's avatar URL. This API may be used to fetch the user's + own avatar URL or to query the URL of other users; either locally or + on remote homeservers. + operationId: getAvatarUrl + parameters: + - in: path + type: string + name: userId + description: The user whose avatar URL to get. + required: true + x-example: "@alice:example.com" + responses: + 200: + description: The avatar URL for this user. + examples: + application/json: { + "avatar_url": "mxc://matrix.org/SDGdghriugerRg" + } + schema: + type: object + properties: + avatar_url: + type: string + description: The user's avatar URL if they have set one, otherwise not present. + 404: + description: There is no avatar URL for this user or this user does not exist. + tags: + - User data + "/profile/{userId}": + get: + summary: Get this user's profile information. + description: |- + Get the combined profile information for this user. This API may be used + to fetch the user's own profile information or other users; either + locally or on remote homeservers. This API may return keys which are not + limited to `displayname` or `avatar_url`. + operationId: getUserProfile + parameters: + - in: path + type: string + name: userId + description: The user whose profile information to get. + required: true + x-example: "@alice:example.com" + responses: + 200: + description: The avatar URL for this user. + examples: + application/json: { + "avatar_url": "mxc://matrix.org/SDGdghriugerRg", + "displayname": "Alice Margatroid" + } + schema: + type: object + properties: + avatar_url: + type: string + description: The user's avatar URL if they have set one, otherwise not present. + displayname: + type: string + description: The user's display name if they have set one, otherwise not present. + 404: + description: There is no profile information for this user or this user does not exist. + tags: + - User data diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml new file mode 100644 index 000000000..69882066f --- /dev/null +++ b/data/api/client-server/pusher.yaml @@ -0,0 +1,268 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Push API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/pushers": + get: + summary: Gets the current pushers for the authenticated user + description: |- + Gets all currently active pushers for the authenticated user. + operationId: getPushers + security: + - accessToken: [] + responses: + 200: + description: The pushers for this user. + examples: + application/json: { + "pushers": [ + { + "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", + "kind": "http", + "app_id": "face.mcapp.appy.prod", + "app_display_name": "Appy McAppface", + "device_display_name": "Alice's Phone", + "profile_tag": "xyz", + "lang": "en-US", + "data": { + "url": "https://example.com/_matrix/push/v1/notify" + } + } + ] + } + schema: + type: object + properties: + pushers: + type: array + title: Pushers + description: |- + An array containing the current pushers for the user + items: + type: object + title: Pusher + properties: + pushkey: + type: string + description: |- + This is a unique identifier for this pusher. See `/set` for + more detail. + Max length, 512 bytes. + kind: + type: string + description: |- + The kind of pusher. `"http"` is a pusher that + sends HTTP pokes. + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + Max length, 64 chars. + app_display_name: + type: string + description: |- + A string that will allow the user to identify what application + owns this pusher. + device_display_name: + type: string + description: |- + A string that will allow the user to identify what device owns + this pusher. + profile_tag: + type: string + description: |- + This string determines which set of device specific rules this + pusher executes. + lang: + type: string + description: |- + The preferred language for receiving notifications (e.g. 'en' + or 'en-US') + data: + type: object + description: |- + A dictionary of information for the pusher implementation + itself. + title: PusherData + properties: + url: + type: string + description: |- + Required if `kind` is `http`. The URL to use to send + notifications to. + format: + type: string + description: |- + The format to use when sending notifications to the Push + Gateway. + required: + - pushkey + - app_id + - kind + - app_display_name + - device_display_name + - lang + - data + tags: + - Push notifications + "/pushers/set": + post: + summary: Modify a pusher for this user on the homeserver. + description: |- + This endpoint allows the creation, modification and deletion of [pushers](/client-server-api/#push-notifications) + for this user ID. The behaviour of this endpoint varies depending on the + values in the JSON body. + operationId: postPusher + security: + - accessToken: [] + parameters: + - in: body + name: pusher + description: The pusher information. + required: true + schema: + type: object + example: { + "lang": "en", + "kind": "http", + "app_display_name": "Mat Rix", + "device_display_name": "iPhone 9", + "profile_tag": "xxyyzz", + "app_id": "com.example.app.ios", + "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", + "data": { + "url": "https://push-gateway.location.here/_matrix/push/v1/notify", + "format": "event_id_only" + }, + "append": false + } + properties: + pushkey: + type: string + description: |- + This is a unique identifier for this pusher. The value you + should use for this is the routing or destination address + information for the notification, for example, the APNS token + for APNS or the Registration ID for GCM. If your notification + client has no such concept, use any unique identifier. + Max length, 512 bytes. + + If the `kind` is `"email"`, this is the email address to + send notifications to. + kind: + type: string + description: |- + The kind of pusher to configure. `"http"` makes a pusher that + sends HTTP pokes. `"email"` makes a pusher that emails the + user with unread notifications. `null` deletes the pusher. + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + It is recommended that this end with the platform, such that + different platform versions get different app identifiers. + Max length, 64 chars. + + If the `kind` is `"email"`, this is `"m.email"`. + app_display_name: + type: string + description: |- + A string that will allow the user to identify what application + owns this pusher. + device_display_name: + type: string + description: |- + A string that will allow the user to identify what device owns + this pusher. + profile_tag: + type: string + description: |- + This string determines which set of device specific rules this + pusher executes. + lang: + type: string + description: |- + The preferred language for receiving notifications (e.g. 'en' + or 'en-US'). + data: + type: object + description: |- + A dictionary of information for the pusher implementation + itself. If `kind` is `http`, this should contain `url` + which is the URL to use to send notifications to. + title: PusherData + properties: + url: + type: string + description: |- + Required if `kind` is `http`. The URL to use to send + notifications to. MUST be an HTTPS URL with a path of + `/_matrix/push/v1/notify`. + example: "https://push-gateway.location.here/_matrix/push/v1/notify" + format: + type: string + description: |- + The format to send notifications in to Push Gateways if the + `kind` is `http`. The details about what fields the + homeserver should send to the push gateway are defined in the + [Push Gateway Specification](/push-gateway-api/). Currently the only format + available is 'event_id_only'. + append: + type: boolean + description: |- + If true, the homeserver should add another pusher with the + given pushkey and App ID in addition to any others with + different user IDs. Otherwise, the homeserver must remove any + other pushers with the same App ID and pushkey for different + users. The default is `false`. + required: ['kind', 'app_id', 'app_display_name', + 'device_display_name', 'pushkey', 'lang', 'data'] + responses: + 200: + description: The pusher was set. + examples: + application/json: {} + schema: + type: object + description: An empty object. + 400: + description: One or more of the pusher values were invalid. + examples: + application/json: { + "error": "Missing parameters: lang, data", + "errcode": "M_MISSING_PARAM" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Push notifications diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml new file mode 100644 index 000000000..9a5952715 --- /dev/null +++ b/data/api/client-server/pushrules.yaml @@ -0,0 +1,745 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Push Rules API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/pushrules/": + get: + summary: Retrieve all push rulesets. + description: |- + Retrieve all push rulesets for this user. Clients can "drill-down" on + the rulesets by suffixing a `scope` to this path e.g. + `/pushrules/global/`. This will return a subset of this data under the + specified key e.g. the `global` key. + operationId: getPushRules + security: + - accessToken: [] + responses: + 200: + description: All the push rulesets for this user. + schema: + type: object + required: ["global"] + properties: + global: + type: object + description: The global ruleset. + title: Ruleset + allOf: [ + "$ref": "definitions/push_ruleset.yaml" + ] + examples: + application/json: { + "global": { + "content": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "default": true, + "enabled": true, + "pattern": "alice", + "rule_id": ".m.rule.contains_user_name" + } + ], + "override": [ + { + "actions": [ + "dont_notify" + ], + "conditions": [], + "default": true, + "enabled": false, + "rule_id": ".m.rule.master" + }, + { + "actions": [ + "dont_notify" + ], + "conditions": [ + { + "key": "content.msgtype", + "kind": "event_match", + "pattern": "m.notice" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.suppress_notices" + } + ], + "room": [], + "sender": [], + "underride": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.call" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "conditions": [ + { + "kind": "contains_display_name" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.contains_display_name" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.room_one_to_one" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, + { + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.invite_for_me" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.member_event" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.message" + } + ] + } + } + tags: + - Push notifications + "/pushrules/{scope}/{kind}/{ruleId}": + get: + summary: Retrieve a push rule. + description: |- + Retrieve a single specified push rule. + operationId: getPushRule + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + `global` to specify global rules. + - in: path + type: string + name: kind + required: true + x-example: content + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: "nocake" + description: | + The identifier for the rule. + responses: + 200: + description: |- + The specific push rule. This will also include keys specific to the + rule itself such as the rule's `actions` and `conditions` if set. + examples: + application/json: { + "actions": [ + "dont_notify" + ], + "pattern": "cake*lie", + "rule_id": "nocake", + "enabled": true, + "default": false + } + schema: + type: object + description: The push rule. + allOf: [ + "$ref": "definitions/push_rule.yaml" + ] + 404: + description: |- + The push rule does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Push notifications + delete: + summary: Delete a push rule. + description: |- + This endpoint removes the push rule defined in the path. + operationId: deletePushRule + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + `global` to specify global rules. + - in: path + type: string + name: kind + required: true + x-example: content + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: "nocake" + description: | + The identifier for the rule. + responses: + 200: + description: The push rule was deleted. + examples: + application/json: { + } + schema: + type: object # empty json object + 404: + description: |- + The push rule does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Push notifications + put: + summary: Add or change a push rule. + description: |- + This endpoint allows the creation, modification and deletion of pushers + for this user ID. The behaviour of this endpoint varies depending on the + values in the JSON body. + + When creating push rules, they MUST be enabled by default. + operationId: setPushRule + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + `global` to specify global rules. + - in: path + type: string + name: kind + required: true + x-example: content + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: "nocake" + description: | + The identifier for the rule. + - in: query + type: string + name: before + required: false + x-example: someRuleId + description: |- + Use 'before' with a `rule_id` as its value to make the new rule the + next-most important rule with respect to the given user defined rule. + It is not possible to add a rule relative to a predefined server rule. + - in: query + type: string + name: after + required: false + x-example: anotherRuleId + description: |- + This makes the new rule the next-less important rule relative to the + given user defined rule. It is not possible to add a rule relative + to a predefined server rule. + - in: body + name: pushrule + description: |- + The push rule data. Additional top-level keys may be present depending + on the parameters for the rule `kind`. + required: true + schema: + type: object + example: { + "pattern": "cake*lie", + "actions": ["notify"] + } + properties: + actions: + type: array + description: |- + The action(s) to perform when the conditions for this rule are met. + items: + type: + - string + - object + conditions: + type: array + description: |- + The conditions that must hold true for an event in order for a + rule to be applied to an event. A rule with no conditions + always matches. Only applicable to `underride` and `override` rules. + items: + type: object + allOf: [ "$ref": "definitions/push_condition.yaml" ] + pattern: + type: string + description: |- + Only applicable to `content` rules. The glob-style pattern to match against. + required: ["actions"] + responses: + 200: + description: The push rule was created/updated. + examples: + application/json: { + } + schema: + type: object # empty json object + 400: + description: There was a problem configuring this push rule. + examples: + application/json: { + "error": "before/after rule not found: someRuleId", + "errcode": "M_UNKNOWN" + } + schema: + "$ref": "definitions/errors/error.yaml" + 404: + description: |- + The push rule does not exist (when updating a push rule). + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Push notifications + "/pushrules/{scope}/{kind}/{ruleId}/enabled": + get: + summary: "Get whether a push rule is enabled" + description: + This endpoint gets whether the specified push rule is enabled. + operationId: isPushRuleEnabled + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + Either `global` or `device/` to specify global + rules or device rules for the given `profile_tag`. + - in: path + type: string + name: kind + required: true + x-example: cake + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: nocake + description: | + The identifier for the rule. + responses: + 200: + description: Whether the push rule is enabled. + examples: + application/json: { + "enabled": true + } + schema: + type: object + properties: + enabled: + type: boolean + description: Whether the push rule is enabled or not. + required: ["enabled"] + 404: + description: |- + The push rule does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Push notifications + put: + summary: "Enable or disable a push rule." + description: |- + This endpoint allows clients to enable or disable the specified push rule. + operationId: setPushRuleEnabled + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + `global` to specify global rules. + - in: path + type: string + name: kind + required: true + x-example: content + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: "nocake" + description: | + The identifier for the rule. + - in: body + name: body + description: | + Whether the push rule is enabled or not. + required: true + schema: + type: object + properties: + enabled: + type: boolean + description: Whether the push rule is enabled or not. + required: ["enabled"] + example: { + "enabled": true + } + responses: + 200: + description: The push rule was enabled or disabled. + examples: + application/json: { + } + schema: + type: object + 404: + description: |- + The push rule does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Push notifications + "/pushrules/{scope}/{kind}/{ruleId}/actions": + get: + summary: "The actions for a push rule" + description: + This endpoint get the actions for the specified push rule. + operationId: getPushRuleActions + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + Either `global` or `device/` to specify global + rules or device rules for the given `profile_tag`. + - in: path + type: string + name: kind + required: true + x-example: content + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: nocake + description: | + The identifier for the rule. + responses: + 200: + description: The actions for this push rule. + examples: + application/json: { + "actions": [ + "notify", + {"set_tweak": "sound", "value": "bing"} + ] + } + schema: + type: object + properties: + actions: + type: array + description: The action(s) to perform for this rule. + items: + type: + - string + - object + required: ["actions"] + 404: + description: |- + The push rule does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Push notifications + put: + summary: "Set the actions for a push rule." + description: |- + This endpoint allows clients to change the actions of a push rule. + This can be used to change the actions of builtin rules. + operationId: setPushRuleActions + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + `global` to specify global rules. + - in: path + type: string + name: kind + required: true + x-example: room + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: "#spam:example.com" + description: | + The identifier for the rule. + - in: body + name: body + description: | + The action(s) to perform when the conditions for this rule are met. + required: true + schema: + type: object + properties: + actions: + type: array + description: The action(s) to perform for this rule. + items: + type: + - string + - object + required: ["actions"] + example: { + "actions": [ + "notify", + {"set_tweak": "highlight"} + ] + } + responses: + 200: + description: The actions for the push rule were set. + examples: + application/json: { + } + schema: + type: object + 404: + description: |- + The push rule does not exist. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Push notifications diff --git a/data/api/client-server/read_markers.yaml b/data/api/client-server/read_markers.yaml new file mode 100644 index 000000000..aa9d0ecbf --- /dev/null +++ b/data/api/client-server/read_markers.yaml @@ -0,0 +1,79 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Read Marker API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/read_markers": + post: + summary: Set the position of the read marker for a room. + description: |- + Sets the position of the read marker for a given room, and optionally + the read receipt's location. + operationId: setReadMarker + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID to set the read marker in for the user. + required: true + x-example: "!somewhere:example.org" + - in: body + name: body + description: The read marker and optional read receipt locations. + required: true + schema: + type: object + properties: + "m.fully_read": + type: string + description: |- + The event ID the read marker should be located at. The + event MUST belong to the room. + example: "$somewhere:example.org" + "m.read": + type: string + description: |- + The event ID to set the read receipt location at. This is + equivalent to calling `/receipt/m.read/$elsewhere:example.org` + and is provided here to save that extra call. + example: "$elsewhere:example.org" + required: ['m.fully_read'] + responses: + 200: + description: |- + The read marker, and read receipt if provided, have been updated. + schema: + type: object + properties: {} + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Read Markers diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml new file mode 100644 index 000000000..716946ace --- /dev/null +++ b/data/api/client-server/receipts.yaml @@ -0,0 +1,81 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Receipts API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/receipt/{receiptType}/{eventId}": + post: + summary: Send a receipt for the given event ID. + description: |- + This API updates the marker for the given receipt type to the event ID + specified. + operationId: postReceipt + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room in which to send the event. + required: true + x-example: "!wefuh21ffskfuh345:example.com" + - in: path + type: string + name: receiptType + description: The type of receipt to send. + required: true + x-example: "m.read" + enum: ["m.read"] + - in: path + type: string + name: eventId + description: The event ID to acknowledge up to. + required: true + x-example: "$1924376522eioj:example.com" + - in: body + name: receipt + description: |- + Extra receipt information to attach to `content` if any. The + server will automatically set the `ts` field. + schema: + type: object + example: { + } + responses: + 200: + description: The receipt was sent. + examples: + application/json: { + } + schema: + type: object # empty json object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room participation diff --git a/data/api/client-server/redaction.yaml b/data/api/client-server/redaction.yaml new file mode 100644 index 000000000..aeef07a5b --- /dev/null +++ b/data/api/client-server/redaction.yaml @@ -0,0 +1,96 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server message redaction API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/redact/{eventId}/{txnId}": + put: + summary: Strips all non-integrity-critical information out of an event. + description: |- + Strips all information out of an event which isn't critical to the + integrity of the server-side representation of the room. + + This cannot be undone. + + Any user with a power level greater than or equal to the `m.room.redaction` + event power level may send redaction events in the room. If the user's power + level greater is also greater than or equal to the `redact` power level + of the room, the user may redact events sent by other users. + + Server administrators may redact events sent by users on their server. + operationId: redactEvent + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room from which to redact the event. + required: true + x-example: "!637q39766251:example.com" + - in: path + type: string + name: eventId + description: The ID of the event to redact + required: true + x-example: "bai2b1i9:matrix.org" + - in: path + name: txnId + type: string + description: |- + The transaction ID for this event. Clients should generate a + unique ID; it will be used by the server to ensure idempotency of requests. + required: true + x-example: "37" + - in: body + name: body + required: true + schema: + type: object + example: { + "reason": "Indecent material" + } + properties: + reason: + type: string + description: The reason for the event being redacted. + responses: + 200: + description: "An ID for the redaction event." + examples: + application/json: { + "event_id": "$YUwQidLecu:example.com" + } + schema: + type: object + properties: + event_id: + type: string + description: |- + A unique identifier for the event. + tags: + - Room participation diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml new file mode 100644 index 000000000..925ad00b8 --- /dev/null +++ b/data/api/client-server/registration.yaml @@ -0,0 +1,630 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Registration API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +paths: + "/register": + post: + summary: Register for an account on this homeserver. + description: |- + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api), except in + the cases where a guest account is being registered. + + Register for an account on this homeserver. + + There are two kinds of user account: + + - `user` accounts. These accounts may use the full API described in this specification. + + - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers. + + If registration is successful, this endpoint will issue an access token + the client can use to authorize itself in subsequent requests. + + If the client does not supply a `device_id`, the server must + auto-generate one. + + The server SHOULD register an account with a User ID based on the + `username` provided, if any. Note that the grammar of Matrix User ID + localparts is restricted, so the server MUST either map the provided + `username` onto a `user_id` in a logical manner, or reject + `username`\s which do not comply to the grammar, with + `M_INVALID_USERNAME`. + + Matrix clients MUST NOT assume that localpart of the registered + `user_id` matches the provided `username`. + + The returned access token must be associated with the `device_id` + supplied by the client or generated by the server. The server may + invalidate any access token previously associated with that device. See + [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices). + + When registering a guest account, all parameters in the request body + with the exception of `initial_device_display_name` MUST BE ignored + by the server. The server MUST pick a `device_id` for the account + regardless of input. + + Any user ID returned by this API must conform to the grammar given in the + [Matrix specification](/appendices/#user-identifiers). + operationId: register + parameters: + - in: query + name: kind + type: string + # swagger-UI overrides the default with the example, so better make the + # example the default. + x-example: user + required: false + default: user + enum: + - guest + - user + description: The kind of account to register. Defaults to `user`. + - in: body + name: body + required: true + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. Note that this + information is *not* used to define how the registered user + should be authenticated, but is instead used to + authenticate the `register` call itself. + allOf: + - "$ref": "definitions/auth_data.yaml" + username: + type: string + description: |- + The basis for the localpart of the desired Matrix ID. If omitted, + the homeserver MUST generate a Matrix ID local part. + example: cheeky_monkey + password: + type: string + description: The desired password for the account. + example: ilovebananas + device_id: + type: string + description: |- + ID of the client device. If this does not correspond to a + known client device, a new device will be created. The server + will auto-generate a device_id if this is not specified. + example: GHTYAJCE + initial_device_display_name: + type: string + description: |- + A display name to assign to the newly-created device. Ignored + if `device_id` corresponds to a known device. + example: Jungle Phone + inhibit_login: + type: boolean + description: |- + If true, an `access_token` and `device_id` should not be + returned from this call, therefore preventing an automatic + login. Defaults to false. + example: false + responses: + 200: + description: The account has been registered. + examples: + application/json: { + "user_id": "@cheeky_monkey:matrix.org", + "access_token": "abc123", + "device_id": "GHTYAJCE" + } + schema: + type: object + properties: + user_id: + type: string + description: |- + The fully-qualified Matrix user ID (MXID) that has been registered. + + Any user ID returned by this API must conform to the grammar given in the + [Matrix specification](/appendices/#user-identifiers). + access_token: + type: string + description: |- + An access token for the account. + This access token can then be used to authorize other requests. + Required if the `inhibit_login` option is false. + home_server: + type: string + description: |- + The server_name of the homeserver on which the account has + been registered. + + **Deprecated**. Clients should extract the server_name from + `user_id` (by splitting at the first colon) if they require + it. Note also that `homeserver` is not spelt this way. + device_id: + type: string + description: |- + ID of the registered device. Will be the same as the + corresponding parameter in the request, if one was specified. + Required if the `inhibit_login` option is false. + required: ['user_id'] + 400: + description: |- + Part of the request was invalid. This may include one of the following error codes: + + * `M_USER_IN_USE` : The desired user ID is already taken. + * `M_INVALID_USERNAME` : The desired user ID is not a valid user name. + * `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace + claimed by an application service. + + These errors may be returned at any stage of the registration process, + including after authentication if the requested user ID was registered + whilst the client was performing authentication. + + Homeservers MUST perform the relevant checks and return these codes before + performing User-Interactive Authentication, although they may also return + them after authentication is completed if, for example, the requested user ID + was registered whilst the client was performing authentication. + examples: + application/json: { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + schema: + "$ref": "definitions/errors/error.yaml" + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 403: + description: |- + The homeserver does not permit registering the account. This response + can be used to identify that a particular `kind` of account is not + allowed, or that registration is generally not supported by the homeserver. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Registration is disabled" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data + "/register/email/requestToken": + post: + summary: Begins the validation process for an email to be used during registration. + description: |- + The homeserver must check that the given email address is **not** + already associated with an account on this homeserver. The homeserver + should validate the email itself, either by sending a validation email + itself or by using a service it has control over. + operationId: requestTokenToRegisterEmail + parameters: + - in: body + name: body + required: true + schema: + $ref: "definitions/request_email_validation.yaml" + responses: + 200: + description: |- + An email has been sent to the specified address. Note that this + may be an email containing the validation token or it may be + informing the user of an error. + schema: + $ref: "definitions/request_token_response.yaml" + 403: + description: The homeserver does not permit the address to be bound. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_DENIED", + "error": "Third party identifier is not allowed" + } + 400: + description: |- + Part of the request was invalid. This may include one of the following error codes: + + * `M_THREEPID_IN_USE` : The email address is already registered to an account on this server. + However, if the homeserver has the ability to send email, it is recommended that the server + instead send an email to the user with instructions on how to reset their password. + This prevents malicious parties from being able to determine if a given email address + has an account on the homeserver in question. + * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server + that is not trusted by this homeserver. + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } + schema: + "$ref": "definitions/errors/error.yaml" + "/register/msisdn/requestToken": + post: + summary: Requests a validation token be sent to the given phone number for the purpose of registering an account + description: |- + The homeserver must check that the given phone number is **not** + already associated with an account on this homeserver. The homeserver + should validate the phone number itself, either by sending a validation + message itself or by using a service it has control over. + operationId: requestTokenToRegisterMSISDN + parameters: + - in: body + name: body + required: true + schema: + $ref: "definitions/request_msisdn_validation.yaml" + responses: + 200: + description: |- + An SMS message has been sent to the specified phone number. Note + that this may be an SMS message containing the validation token or + it may be informing the user of an error. + schema: + $ref: "definitions/request_token_response.yaml" + 403: + description: The homeserver does not permit the address to be bound. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_DENIED", + "error": "Third party identifier is not allowed" + } + 400: + description: |- + Part of the request was invalid. This may include one of the following error codes: + + * `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server. + However, if the homeserver has the ability to send SMS message, it is recommended that the server + instead send an SMS message to the user with instructions on how to reset their password. + This prevents malicious parties from being able to determine if a given phone number + has an account on the homeserver in question. + * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server + that is not trusted by this homeserver. + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } + schema: + "$ref": "definitions/errors/error.yaml" + "/account/password": + post: + summary: "Changes a user's password." + description: |- + Changes the password for an account on this homeserver. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to + ensure the user changing the password is actually the owner of the + account. + + An access token should be submitted to this endpoint if the client has + an active session. + + The homeserver may change the flows available depending on whether a + valid access token is provided. The homeserver SHOULD NOT revoke the + access token provided in the request. Whether other access tokens for + the user are revoked depends on the request parameters. + security: + - accessToken: [] + operationId: changePassword + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + new_password: + type: string + description: The new password for the account. + example: "ihatebananas" + logout_devices: + type: boolean + description: |- + Whether the user's other access tokens, and their associated devices, should be + revoked if the request succeeds. Defaults to true. + + When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) + for the user's remaining devices. + example: true + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + allOf: + - "$ref": "definitions/auth_data.yaml" + required: ["new_password"] + responses: + 200: + description: The password has been changed. + examples: + application/json: {} + schema: + type: object + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data + "/account/password/email/requestToken": + post: + summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password + description: |- + The homeserver must check that the given email address **is + associated** with an account on this homeserver. This API should be + used to request validation tokens when authenticating for the + `/account/password` endpoint. + + This API's parameters and response are identical to that of the + [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken) + endpoint, except that + `M_THREEPID_NOT_FOUND` may be returned if no account matching the + given email address could be found. The server may instead send an + email to the given address prompting the user to create an account. + `M_THREEPID_IN_USE` may not be returned. + + The homeserver should validate the email itself, either by sending a + validation email itself or by using a service it has control over. + operationId: requestTokenToResetPasswordEmail + parameters: + - in: body + name: body + required: true + schema: + $ref: "definitions/request_email_validation.yaml" + responses: + 200: + description: An email was sent to the given address. + schema: + $ref: "definitions/request_token_response.yaml" + 403: + description: |- + The homeserver does not allow the third party identifier as a + contact option. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_DENIED", + "error": "Third party identifier is not allowed" + } + 400: + description: |- + The referenced third party identifier is not recognised by the + homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + can be returned if the server does not trust/support the identity server + provided in the request. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Email not found" + } + "/account/password/msisdn/requestToken": + post: + summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. + description: |- + The homeserver must check that the given phone number **is + associated** with an account on this homeserver. This API should be + used to request validation tokens when authenticating for the + `/account/password` endpoint. + + This API's parameters and response are identical to that of the + [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken) + endpoint, except that + `M_THREEPID_NOT_FOUND` may be returned if no account matching the + given phone number could be found. The server may instead send the SMS + to the given phone number prompting the user to create an account. + `M_THREEPID_IN_USE` may not be returned. + + The homeserver should validate the phone number itself, either by sending a + validation message itself or by using a service it has control over. + operationId: requestTokenToResetPasswordMSISDN + parameters: + - in: body + name: body + required: true + schema: + $ref: "definitions/request_msisdn_validation.yaml" + responses: + 200: + description: An SMS message was sent to the given phone number. + schema: + $ref: "definitions/request_token_response.yaml" + 403: + description: |- + The homeserver does not allow the third party identifier as a + contact option. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_DENIED", + "error": "Third party identifier is not allowed" + } + 400: + description: |- + The referenced third party identifier is not recognised by the + homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + can be returned if the server does not trust/support the identity server + provided in the request. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Phone number not found" + } + "/account/deactivate": + post: + summary: "Deactivate a user's account." + description: |- + Deactivate the user's account, removing all ability for the user to + login again. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + An access token should be submitted to this endpoint if the client has + an active session. + + The homeserver may change the flows available depending on whether a + valid access token is provided. + + Unlike other endpoints, this endpoint does not take an `id_access_token` + parameter because the homeserver is expected to sign the request to the + identity server instead. + security: + - accessToken: [] + operationId: deactivateAccount + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + allOf: + - $ref: "definitions/auth_data.yaml" + id_server: + type: string + description: |- + The identity server to unbind all of the user's 3PIDs from. + If not provided, the homeserver MUST use the `id_server` + that was originally use to bind each identifier. If the + homeserver does not know which `id_server` that was, + it must return an `id_server_unbind_result` of + `no-support`. + example: "example.org" + responses: + 200: + description: The account has been deactivated. + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - "success" + - "no-support" + description: |- + An indicator as to whether or not the homeserver was able to unbind + the user's 3PIDs from the identity server(s). `success` indicates + that all identifiers have been unbound from the identity server while + `no-support` indicates that one or more identifiers failed to unbind + due to the identity server refusing the request or the homeserver + being unable to determine an identity server to unbind from. This + must be `success` if the homeserver has no identifiers to unbind + for the user. + example: "success" + required: + - id_server_unbind_result + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data + "/register/available": + get: + summary: Checks to see if a username is available on the server. + description: |- + Checks to see if a username is available, and valid, for the server. + + The server should check to ensure that, at the time of the request, the + username requested is available for use. This includes verifying that an + application service has not claimed the username and that the username + fits the server's desired requirements (for example, a server could dictate + that it does not permit usernames with underscores). + + Matrix clients may wish to use this API prior to attempting registration, + however the clients must also be aware that using this API does not normally + reserve the username. This can mean that the username becomes unavailable + between checking its availability and attempting to register it. + operationId: checkUsernameAvailability + parameters: + - in: query + name: username + type: string + x-example: my_cool_localpart + required: true + default: my_cool_localpart + description: The username to check the availability of. + responses: + 200: + description: The username is available + examples: + application/json: { + "available": true + } + schema: + type: object + properties: + available: + type: boolean + description: |- + A flag to indicate that the username is available. This should always + be `true` when the server replies with 200 OK. + 400: + description: |- + Part of the request was invalid or the username is not available. This may + include one of the following error codes: + + * `M_USER_IN_USE` : The desired username is already taken. + * `M_INVALID_USERNAME` : The desired username is not a valid user name. + * `M_EXCLUSIVE` : The desired username is in the exclusive namespace + claimed by an application service. + examples: + application/json: { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml new file mode 100644 index 000000000..380995ead --- /dev/null +++ b/data/api/client-server/report_content.yaml @@ -0,0 +1,77 @@ +# Copyright 2018 Travis Ralston +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Report Content API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/report/{eventId}": + post: + summary: Reports an event as inappropriate. + description: |- + Reports an event as inappropriate to the server, which may then notify + the appropriate people. + operationId: reportContent + parameters: + - in: path + type: string + name: roomId + description: The room in which the event being reported is located. + required: true + x-example: "!637q39766251:example.com" + - in: path + type: string + name: eventId + description: The event to report. + required: true + x-example: "$something:example.org" + - in: body + name: body + schema: + type: object + example: { + "score": -100, + "reason": "this makes me sad" + } + properties: + score: + type: integer + description: |- + The score to rate this content as where -100 is most offensive + and 0 is inoffensive. + reason: + type: string + description: The reason the content is being reported. May be blank. + security: + - accessToken: [] + responses: + 200: + description: The event has been reported successfully. + schema: + type: object + examples: + application/json: {} + tags: + - Reporting content diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml new file mode 100644 index 000000000..bab0e3d92 --- /dev/null +++ b/data/api/client-server/room_initial_sync.yaml @@ -0,0 +1,156 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server Rooms API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/initialSync": + get: + summary: Snapshot the current state of a room and its most recent messages. + description: |- + Get a copy of the current state and the most recent messages in a room. + + This endpoint was deprecated in r0 of this specification. There is no + direct replacement; the relevant information is returned by the + [`/sync`](/client-server-api/#get_matrixclientr0sync) API. See the + [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + operationId: roomInitialSync + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to get the data. + required: true + x-example: "!636q39766251:example.com" + responses: + 200: + description: The current state of the room + examples: + application/json: { + "membership": "join", + "messages": { + "chunk": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" + } + ], + "end": "s3456_9_0", + "start": "t44-3453_9_0" + }, + "room_id": "!636q39766251:example.com", + "state": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ], + "visibility": "private", + "account_data": [{ + "type": "m.tag", + "content": {"tags": {"work": {"order": "1"}}} + }] + } + schema: + title: RoomInfo + type: object + properties: + room_id: + type: string + description: "The ID of this room." + membership: + type: string + description: "The user's membership state in this room." + enum: ["invite", "join", "leave", "ban"] + messages: + type: object + title: PaginationChunk + description: "The pagination chunk for this room." + properties: + start: + type: string + description: |- + A token which correlates to the first value in `chunk`. + Used for pagination. + end: + type: string + description: |- + A token which correlates to the last value in `chunk`. + Used for pagination. + chunk: + type: array + description: |- + If the user is a member of the room this will be a + list of the most recent messages for this room. If + the user has left the room this will be the + messages that preceeded them leaving. This array + will consist of at most `limit` elements. + items: + type: object + title: RoomEvent + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + required: ["start", "end", "chunk"] + state: + type: array + description: |- + If the user is a member of the room this will be the + current state of the room as a list of events. If the + user has left the room this will be the state of the + room when they left it. + items: + title: StateEvent + type: object + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml" + visibility: + type: string + enum: ["private", "public"] + description: |- + Whether this room is visible to the `/publicRooms` API + or not." + account_data: + type: array + description: |- + The private data that this user has attached to this room. + items: + title: Event + type: object + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" + required: ["room_id"] + 403: + description: > + You aren't a member of the room and weren't previously a + member of the room. + tags: + - Room participation + deprecated: true diff --git a/data/api/client-server/room_send.yaml b/data/api/client-server/room_send.yaml new file mode 100644 index 000000000..c22fcfe47 --- /dev/null +++ b/data/api/client-server/room_send.yaml @@ -0,0 +1,91 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server message event send API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/send/{eventType}/{txnId}": + put: + summary: Send a message event to the given room. + description: |- + This endpoint is used to send a message event to a room. Message events + allow access to historical events and pagination, making them suited + for "once-off" activity in a room. + + The body of the request should be the content object of the event; the + fields in this object will vary depending on the type of event. See + [Room Events](/client-server-api/#room-events) for the m. event specification. + operationId: sendMessage + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to send the event to. + required: true + x-example: "!636q39766251:example.com" + - in: path + type: string + name: eventType + description: The type of event to send. + required: true + x-example: "m.room.message" + - in: path + name: txnId + type: string + description: |- + The transaction ID for this event. Clients should generate an + ID unique across requests with the same access token; it will be + used by the server to ensure idempotency of requests. + required: true + x-example: "35" + - in: body + name: body + schema: + type: object + example: { + "msgtype": "m.text", + "body": "hello" + } + responses: + 200: + description: "An ID for the sent event." + examples: + application/json: { + "event_id": "$YUwRidLecu:example.com" + } + schema: + type: object + properties: + event_id: + type: string + description: |- + A unique identifier for the event. + required: + - event_id + tags: + - Room participation diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml new file mode 100644 index 000000000..381c5c57e --- /dev/null +++ b/data/api/client-server/room_state.yaml @@ -0,0 +1,129 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server state event send API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/state/{eventType}/{stateKey}": + put: + summary: Send a state event to the given room. + description: | + State events can be sent using this endpoint. These events will be + overwritten if ``, `` and `` all + match. + + Requests to this endpoint **cannot use transaction IDs** + like other `PUT` paths because they cannot be differentiated from the + `state_key`. Furthermore, `POST` is unsupported on state paths. + + The body of the request should be the content object of the event; the + fields in this object will vary depending on the type of event. See + [Room Events](/client-server-api/#room-events) for the `m.` event specification. + + If the event type being sent is `m.room.canonical_alias` servers + SHOULD ensure that any new aliases being listed in the event are valid + per their grammar/syntax and that they point to the room ID where the + state event is to be sent. Servers do not validate aliases which are + being removed or are already present in the state event. + operationId: setRoomStateWithKey + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to set the state in + required: true + x-example: "!636q39766251:example.com" + - in: path + type: string + name: eventType + description: The type of event to send. + required: true + x-example: "m.room.member" + - in: path + type: string + name: stateKey + description: |- + The state_key for the state to send. Defaults to the empty string. When + an empty string, the trailing slash on this endpoint is optional. + required: true + x-example: "@alice:example.com" + - in: body + name: body + schema: + type: object + example: { + "membership": "join", + "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF", + "displayname": "Alice Margatroid" + } + responses: + 200: + description: "An ID for the sent event." + examples: + application/json: { + "event_id": "$YUwRidLecu:example.com" + } + schema: + type: object + properties: + event_id: + type: string + description: |- + A unique identifier for the event. + required: + - event_id + 403: + description: |- + The sender doesn't have permission to send the event into the room. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You do not have permission to send the event." + } + 400: + description: |- + The sender's request is malformed. + + Some example error codes include: + + * `M_INVALID_PARAMETER`: One or more aliases within the `m.room.canonical_alias` + event have invalid syntax. + + * `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event + do not point to the room ID for which the state event is to be sent to. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_BAD_ALIAS", + "error": "The alias '#hello:example.org' does not point to this room." + } + tags: + - Room participation diff --git a/data/api/client-server/room_upgrades.yaml b/data/api/client-server/room_upgrades.yaml new file mode 100644 index 000000000..97ef611e5 --- /dev/null +++ b/data/api/client-server/room_upgrades.yaml @@ -0,0 +1,92 @@ +# Copyright 2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Upgrades API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/upgrade": + post: + summary: Upgrades a room to a new room version. + description: |- + Upgrades the given room to a particular room version. + operationId: upgradeRoom + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + required: true + description: The ID of the room to upgrade. + x-example: "!oldroom:example.org" + - in: body + name: body + required: true + schema: + type: object + properties: + new_version: + type: string + description: The new version for the room. + example: {"new_version": "2"} + required: [new_version] + responses: + 200: + description: The room was successfully upgraded. + examples: + application/json: { + "replacement_room": "!newroom:example.org" + } + schema: + type: object + properties: + replacement_room: + type: string + description: The ID of the new room. + required: [replacement_room] + 400: + description: |- + The request was invalid. One way this can happen is if the room version + requested is not supported by the homeserver. + examples: + application/json: { + "errcode": "M_UNSUPPORTED_ROOM_VERSION", + "error": "This server does not support that room version" + } + schema: + "$ref": "definitions/errors/error.yaml" + 403: + description: |- + The user is not permitted to upgrade the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You cannot upgrade this room" + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room upgrades diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml new file mode 100644 index 000000000..0dd60d8e6 --- /dev/null +++ b/data/api/client-server/rooms.yaml @@ -0,0 +1,311 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Rooms API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/event/{eventId}": + get: + summary: Get a single event by event ID. + description: |- + Get a single event based on `roomId/eventId`. You must have permission to + retrieve this event e.g. by being a member in the room for this event. + operationId: getOneRoomEvent + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The ID of the room the event is in. + required: true + x-example: "!636q39766251:matrix.org" + - in: path + type: string + name: eventId + description: The event ID to get. + required: true + x-example: "$asfDuShaf7Gafaw:matrix.org" + responses: + 200: + description: The full event. + examples: + application/json: { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + schema: + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" + 404: + description: The event was not found or you do not have permission to read this event. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Room participation + "/rooms/{roomId}/state/{eventType}/{stateKey}": + get: + summary: Get the state identified by the type and key. + description: |- + Looks up the contents of a state event in a room. If the user is + joined to the room then the state is taken from the current + state of the room. If the user has left the room then the state is + taken from the state of the room when they left. + operationId: getRoomStateWithKey + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to look up the state in. + required: true + x-example: "!636q39766251:example.com" + - in: path + type: string + name: eventType + description: The type of state to look up. + required: true + x-example: "m.room.name" + - in: path + type: string + name: stateKey + description: |- + The key of the state to look up. Defaults to an empty string. When + an empty string, the trailing slash on this endpoint is optional. + required: true + x-example: "" + responses: + 200: + description: The content of the state event. + examples: + application/json: { + "name": "Example room name"} + schema: + type: object + 404: + description: The room has no state with the given type or key. + 403: + description: > + You aren't a member of the room and weren't previously a + member of the room. + tags: + - Room participation + "/rooms/{roomId}/state": + get: + summary: Get all state events in the current state of a room. + description: |- + Get the state events for the current state of a room. + operationId: getRoomState + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room to look up the state for. + required: true + x-example: "!636q39766251:example.com" + responses: + 200: + description: The current state of the room + examples: + application/json: [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ] + schema: + type: array + title: RoomState + description: |- + If the user is a member of the room this will be the + current state of the room as a list of events. If the user + has left the room then this will be the state of the room + when they left as a list of events. + items: + title: StateEvent + type: object + allOf: + - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml" + 403: + description: > + You aren't a member of the room and weren't previously a + member of the room. + tags: + - Room participation + "/rooms/{roomId}/members": + get: + summary: Get the m.room.member events for the room. + description: + Get the list of members for this room. + operationId: getMembersByRoom + parameters: + - in: path + type: string + name: roomId + description: The room to get the member events for. + required: true + x-example: "!636q39766251:example.com" + - in: query + name: at + type: string + description: |- + The point in time (pagination token) to return members for in the room. + This token can be obtained from a `prev_batch` token returned for + each room by the sync API. Defaults to the current state of the room, + as determined by the server. + x-example: "YWxsCgpOb25lLDM1ODcwOA" + # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON + # filter might be a better alternative. + # See https://github.com/matrix-org/matrix-doc/issues/1337 + - in: query + name: membership + type: string + enum: + - join + - invite + - leave + - ban + description: |- + The kind of membership to filter for. Defaults to no filtering if + unspecified. When specified alongside `not_membership`, the two + parameters create an 'or' condition: either the membership *is* + the same as `membership` **or** *is not* the same as `not_membership`. + x-example: "join" + - in: query + name: not_membership + type: string + enum: + - join + - invite + - leave + - ban + description: |- + The kind of membership to exclude from the results. Defaults to no + filtering if unspecified. + x-example: leave + security: + - accessToken: [] + responses: + 200: + description: |- + A list of members of the room. If you are joined to the room then + this will be the current members of the room. If you have left the + room then this will be the members of the room when you left. + examples: + application/json: { + "chunk": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + } + schema: + type: object + properties: + chunk: + type: array + items: + title: MemberEvent + type: object + allOf: + - "$ref": "../../event-schemas/schema/m.room.member.yaml" + 403: + description: > + You aren't a member of the room and weren't previously a + member of the room. + tags: + - Room participation + "/rooms/{roomId}/joined_members": + get: + summary: Gets the list of currently joined users and their profile data. + description: + This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. + This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server. + operationId: getJoinedMembersByRoom + parameters: + - in: path + type: string + name: roomId + description: The room to get the members of. + required: true + x-example: "!636q39766251:example.com" + security: + - accessToken: [] + responses: + 200: + description: |- + A map of MXID to room member objects. + examples: + application/json: { + "joined": { + "@bar:example.com": { + "display_name": "Bar", + "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK" + } + } + } + schema: + type: object + properties: + joined: + additionalProperties: + title: RoomMember + type: object + properties: + display_name: + type: string + description: The display name of the user this object is representing. + avatar_url: + type: string + description: The mxc avatar url of the user this object is representing. + description: A map from user ID to a RoomMember object. + type: object + 403: + description: > + You aren't a member of the room. + tags: + - Room participation diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml new file mode 100644 index 000000000..1dc9804e2 --- /dev/null +++ b/data/api/client-server/search.yaml @@ -0,0 +1,364 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Search API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/search": + post: + summary: Perform a server-side search. + description: |- + Performs a full text search across different categories. + operationId: search + security: + - accessToken: [] + parameters: + - in: query + name: next_batch + type: string + description: |- + The point to return events from. If given, this should be a + `next_batch` result from a previous call to this endpoint. + x-example: "YWxsCgpOb25lLDM1ODcwOA" + - in: body + name: body + required: true + schema: + type: object + example: { + "search_categories": { + "room_events": { + "keys": [ + "content.body" + ], + "search_term": "martians and men", + "order_by": "recent", + "groupings": { + "group_by": [ + { + "key": "room_id" + } + ] + } + } + } + } + properties: + search_categories: + type: object + title: "Categories" + description: Describes which categories to search in and + their criteria. + properties: + room_events: + type: object + title: Room Events Criteria + description: Mapping of category name to search criteria. + properties: + search_term: + type: string + description: The string to search events for + keys: + type: array + items: + type: string + enum: ["content.body", "content.name", "content.topic"] + description: The keys to search. Defaults to all. + filter: + type: object + title: Filter + description: |- + This takes a [filter](/client-server-api/#filtering). + allOf: + - $ref: "definitions/room_event_filter.yaml" + order_by: + title: "Ordering" + type: string + enum: ["recent", "rank"] + description: |- + The order in which to search for results. + By default, this is `"rank"`. + event_context: + title: Include Event Context + type: object + description: |- + Configures whether any context for the events + returned are included in the response. + properties: + before_limit: + type: integer + title: "Before limit" + description: |- + How many events before the result are + returned. By default, this is `5`. + after_limit: + type: integer + title: "After limit" + description: |- + How many events after the result are + returned. By default, this is `5`. + include_profile: + type: boolean + title: "Return profile information" + description: |- + Requests that the server returns the + historic profile information for the users + that sent the events that were returned. + By default, this is `false`. + include_state: + type: boolean + title: Include current state + description: |- + Requests the server return the current state for + each room returned. + groupings: + type: object + title: Groupings + description: |- + Requests that the server partitions the result set + based on the provided list of keys. + properties: + group_by: + type: array + title: Groups + description: List of groups to request. + items: + type: object + title: Group + description: Configuration for group. + properties: + key: + type: string + title: Group Key + description: |- + Key that defines the group. + enum: ["room_id", "sender"] + required: ["search_term"] + required: ["search_categories"] + responses: + 200: + description: Results of the search. + schema: + type: object + title: Results + required: ["search_categories"] + properties: + search_categories: + type: object + title: Result Categories + description: Describes which categories to search in and + their criteria. + properties: + room_events: + type: object + title: Result Room Events + description: Mapping of category name to search criteria. + properties: + count: + type: integer + description: An approximate count of the total number of results found. + highlights: + type: array + title: Highlights + description: List of words which should be highlighted, useful for stemming which may change the query terms. + items: + type: string + results: + type: array + title: Results + description: List of results in the requested order. + items: + type: object + title: Result + description: The result object. + properties: + rank: + type: number + description: A number that describes how closely + this result matches the search. Higher is + closer. + result: + type: object + title: Event + description: The event that matched. + "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + context: + type: object + title: Event Context + description: Context for result, if requested. + properties: + start: + type: string + title: Start Token + description: |- + Pagination token for the start of the chunk + end: + type: string + title: End Token + description: |- + Pagination token for the end of the chunk + profile_info: + type: object + title: Profile Information + description: |- + The historic profile information of the + users that sent the events returned. + + The `string` key is the user ID for which + the profile belongs to. + additionalProperties: + type: object + title: User Profile + properties: + displayname: + type: string + title: Display name + avatar_url: + type: string + title: Avatar Url + events_before: + type: array + title: Events Before + description: Events just before the result. + items: + title: Event + type: object + "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + events_after: + type: array + title: Events After + description: Events just after the result. + items: + title: Event + type: object + "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" + state: + type: object + title: Current state + description: |- + The current state for every room in the results. + This is included if the request had the + `include_state` key set with a value of `true`. + + The `string` key is the room ID for which the `State + Event` array belongs to. + additionalProperties: + type: array + title: Room State + items: + type: object + "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml" + groups: + type: object + title: Groups + description: |- + Any groups that were requested. + + The outer `string` key is the group key requested (eg: `room_id` + or `sender`). The inner `string` key is the grouped value (eg: + a room's ID or a user's ID). + additionalProperties: + type: object + title: Group Key + description: The results for a given group. + additionalProperties: + type: object + title: Group Value + description: |- + The results for a particular group value. + properties: + next_batch: + type: string + title: Next Batch in Group + description: |- + Token that can be used to get the next batch + of results in the group, by passing as the + `next_batch` parameter to the next call. If + this field is absent, there are no more + results in this group. + order: + type: integer + title: Group Order + description: |- + Key that can be used to order different + groups. + results: + type: array + description: |- + Which results are in this group. + items: + type: string + title: Result Event ID + next_batch: + type: string + title: Next Batch + description: |- + Token that can be used to get the next batch of + results, by passing as the `next_batch` parameter to + the next call. If this field is absent, there are no + more results. + examples: + application/json: { + "search_categories": { + "room_events": { + "groups": { + "room_id": { + "!qPewotXpIctQySfjSy:localhost": { + "order": 1, + "next_batch": "BdgFsdfHSf-dsFD", + "results": [ + "$144429830826TWwbB:localhost" + ] + } + } + }, + "highlights": [ + "martians", + "men" + ], + "next_batch": "5FdgFsd234dfgsdfFD", + "count": 1224, + "results": [ + { + "rank": 0.00424866, + "result": { + "room_id": "!qPewotXpIctQySfjSy:localhost", + "event_id": "$144429830826TWwbB:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + } + ] + } + } + } + 400: + description: Part of the request was invalid. + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Search diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml new file mode 100644 index 000000000..acbafc578 --- /dev/null +++ b/data/api/client-server/sso_login_redirect.yaml @@ -0,0 +1,46 @@ +# Copyright 2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server SSO Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +paths: + "/login/sso/redirect": + get: + summary: Redirect the user's browser to the SSO interface. + description: |- + A web-based Matrix client should instruct the user's browser to + navigate to this endpoint in order to log in via SSO. + + The server MUST respond with an HTTP redirect to the SSO interface. + operationId: redirectToSSO + parameters: + - in: query + type: string + name: redirectUrl + description: |- + URI to which the user will be redirected after the homeserver has + authenticated the user with SSO. + required: true + responses: + 302: + description: A redirect to the SSO interface. + headers: + Location: + type: "string" diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml new file mode 100644 index 000000000..a7090d6b9 --- /dev/null +++ b/data/api/client-server/sync.yaml @@ -0,0 +1,443 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server sync API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/sync": + get: + summary: Synchronise the client's state and receive new messages. + description: |- + Synchronise the client's state with the latest state on the server. + Clients use this API when they first log in to get an initial snapshot + of the state on the server, and then continue to call this API to get + incremental deltas to the state, and to receive new messages. + + *Note*: This endpoint supports lazy-loading. See [Filtering](/client-server-api/#filtering) + for more information. Lazy-loading members is only supported on a `StateFilter` + for this endpoint. When lazy-loading is enabled, servers MUST include the + syncing user's own membership event when they join a room, or when the + full state of rooms is requested, to aid discovering the user's avatar & + displayname. + + Further, like other members, the user's own membership event is eligible + for being considered redundant by the server. When a sync is `limited`, + the server MUST return membership events for events in the gap + (between `since` and the start of the returned timeline), regardless + as to whether or not they are redundant. This ensures that joins/leaves + and profile changes which occur during the gap are not lost. + + Note that the default behaviour of `state` is to include all membership + events, alongside other state, when lazy-loading is not enabled. + operationId: sync + security: + - accessToken: [] + parameters: + - in: query + name: filter + type: string + description: |- + The ID of a filter created using the filter API or a filter JSON + object encoded as a string. The server will detect whether it is + an ID or a JSON object by whether the first character is a `"{"` + open brace. Passing the JSON inline is best suited to one off + requests. Creating a filter using the filter API is recommended for + clients that reuse the same filter multiple times, for example in + long poll requests. + + See [Filtering](/client-server-api/#filtering) for more information. + x-example: "66696p746572" + - in: query + name: since + type: string + description: |- + A point in time to continue a sync from. + x-example: "s72594_4483_1934" + - in: query + name: full_state + type: boolean + description: |- + Controls whether to include the full state for all rooms the user + is a member of. + + If this is set to `true`, then all state events will be returned, + even if `since` is non-empty. The timeline will still be limited + by the `since` parameter. In this case, the `timeout` parameter + will be ignored and the query will return immediately, possibly with + an empty timeline. + + If `false`, and `since` is non-empty, only state which has + changed since the point indicated by `since` will be returned. + + By default, this is `false`. + x-example: "false" + - in: query + name: set_presence + type: string + enum: ["offline", "online", "unavailable"] + description: |- + Controls whether the client is automatically marked as online by + polling this API. If this parameter is omitted then the client is + automatically marked as online when it uses this API. Otherwise if + the parameter is set to "offline" then the client is not marked as + being online when it uses this API. When set to "unavailable", the + client is marked as being idle. + x-example: "offline" + - in: query + name: timeout + type: integer + description: |- + The maximum time to wait, in milliseconds, before returning this + request. If no events (or other data) become available before this + time elapses, the server will return a response with empty fields. + + By default, this is `0`, so the server will return immediately + even if the response is empty. + x-example: 30000 + responses: + 200: + description: + The initial snapshot or delta for the client to use to update their + state. + schema: + type: object + properties: + next_batch: + type: string + description: |- + The batch token to supply in the `since` param of the next + `/sync` request. + rooms: + title: Rooms + type: object + description: |- + Updates to rooms. + properties: + join: + title: Joined Rooms + type: object + description: |- + The rooms that the user has joined, mapped as room ID to + room information. + additionalProperties: + title: Joined Room + type: object + properties: + summary: + title: RoomSummary + type: object + description: |- + Information about the room which clients may need to + correctly render it to users. + properties: + "m.heroes": + type: array + description: |- + The users which can be used to generate a room name + if the room does not have one. Required if the room's + `m.room.name` or `m.room.canonical_alias` state events + are unset or empty. + + This should be the first 5 members of the room, ordered + by stream ordering, which are joined or invited. The + list must never include the client's own user ID. When + no joined or invited members are available, this should + consist of the banned and left users. More than 5 members + may be provided, however less than 5 should only be provided + when there are less than 5 members to represent. + + When lazy-loading room members is enabled, the membership + events for the heroes MUST be included in the `state`, + unless they are redundant. When the list of users changes, + the server notifies the client by sending a fresh list of + heroes. If there are no changes since the last sync, this + field may be omitted. + items: + type: string + "m.joined_member_count": + type: integer + description: |- + The number of users with `membership` of `join`, + including the client's own user ID. If this field has + not changed since the last sync, it may be omitted. + Required otherwise. + "m.invited_member_count": + type: integer + description: |- + The number of users with `membership` of `invite`. + If this field has not changed since the last sync, it + may be omitted. Required otherwise. + state: + title: State + type: object + description: |- + Updates to the state, between the time indicated by + the `since` parameter, and the start of the + `timeline` (or all state up to the start of the + `timeline`, if `since` is not given, or + `full_state` is true). + + N.B. state updates for `m.room.member` events will + be incomplete if `lazy_load_members` is enabled in + the `/sync` filter, and only return the member events + required to display the senders of the timeline events + in this response. + allOf: + - $ref: "definitions/state_event_batch.yaml" + timeline: + title: Timeline + type: object + description: |- + The timeline of messages and state changes in the + room. + allOf: + - $ref: "definitions/timeline_batch.yaml" + ephemeral: + title: Ephemeral + type: object + description: |- + The ephemeral events in the room that aren't + recorded in the timeline or state of the room. + e.g. typing. + allOf: + - $ref: "definitions/event_batch.yaml" + account_data: + title: Account Data + type: object + description: |- + The private data that this user has attached to + this room. + allOf: + - $ref: "definitions/event_batch.yaml" + unread_notifications: + title: Unread Notification Counts + type: object + description: |- + Counts of unread notifications for this room. See the + [Receiving notifications](/client-server-api/#receiving-notifications) section + for more information on how these are calculated. + properties: + highlight_count: + title: Highlighted notification count + type: integer + description: The number of unread notifications + for this room with the highlight flag set + notification_count: + title: Total notification count + type: integer + description: The total number of unread notifications + for this room + invite: + title: Invited Rooms + type: object + description: |- + The rooms that the user has been invited to, mapped as room ID to + room information. + additionalProperties: + title: Invited Room + type: object + properties: + invite_state: + title: InviteState + type: object + description: |- + The state of a room that the user has been invited + to. These state events may only have the `sender`, + `type`, `state_key` and `content` keys + present. These events do not replace any state that + the client already has for the room, for example if + the client has archived the room. Instead the + client should keep two separate copies of the + state: the one from the `invite_state` and one + from the archived `state`. If the client joins + the room then the current state will be given as a + delta against the archived `state` not the + `invite_state`. + properties: + events: + description: The StrippedState events that form the invite state. + items: + $ref: "../../event-schemas/schema/stripped_state.yaml" + type: array + leave: + title: Left rooms + type: object + description: |- + The rooms that the user has left or been banned from, mapped as room ID to + room information. + additionalProperties: + title: Left Room + type: object + properties: + state: + title: State + type: object + description: |- + The state updates for the room up to the start of the timeline. + allOf: + - $ref: "definitions/state_event_batch.yaml" + timeline: + title: Timeline + type: object + description: |- + The timeline of messages and state changes in the + room up to the point when the user left. + allOf: + - $ref: "definitions/timeline_batch.yaml" + account_data: + title: Account Data + type: object + description: |- + The private data that this user has attached to + this room. + allOf: + - $ref: "definitions/event_batch.yaml" + presence: + title: Presence + type: object + description: |- + The updates to the presence status of other users. + allOf: + - $ref: "definitions/event_batch.yaml" + account_data: + title: Account Data + type: object + description: |- + The global private data created by this user. + allOf: + - $ref: "definitions/event_batch.yaml" + to_device: + title: ToDevice + type: object + description: |- + Information on the send-to-device messages for the client + device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync). + device_lists: + title: DeviceLists + type: object + description: |- + Information on end-to-end device updates, as specified in + [End-to-end encryption](/client-server-api/#extensions-to-sync-1). + device_one_time_keys_count: + title: One-time keys count + type: object + additionalProperties: + type: integer + description: |- + Information on end-to-end encryption keys, as specified + in [End-to-end encryption](/client-server-api/#extensions-to-sync-1). + required: + - next_batch + examples: + application/json: { + "next_batch": "s72595_4483_1934", + "presence": { + "events": [ + {"$ref": "../../event-schemas/examples/m.presence.yaml"} + ] + }, + "account_data": { + "events": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + }, + "rooms": { + "join": { + "!726s6s6q:example.com": { + "summary": { + "m.heroes": [ + "@alice:example.com", + "@bob:example.com" + ], + "m.joined_member_count": 2, + "m.invited_member_count": 0 + }, + "state": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + }, + "timeline": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "limited": true, + "prev_batch": "t34-23535_0_0" + }, + "ephemeral": { + "events": [ + {"$ref": "../../event-schemas/examples/m.typing.yaml"} + ] + }, + "account_data": { + "events": [ + {"$ref": "../../event-schemas/examples/m.tag.yaml"}, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + } + } + }, + "invite": { + "!696r7674:example.com": { + "invite_state": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "", + "content": {"name": "My Room Name"} + }, + { + "sender": "@alice:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": {"membership": "invite"} + } + ] + } + } + }, + "leave": {} + } + } + tags: + - Room participation diff --git a/data/api/client-server/tags.yaml b/data/api/client-server/tags.yaml new file mode 100644 index 000000000..94e7be076 --- /dev/null +++ b/data/api/client-server/tags.yaml @@ -0,0 +1,183 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server tag API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user/{userId}/rooms/{roomId}/tags": + get: + summary: List the tags for a room. + description: |- + List the tags set by a user on a room. + operationId: getRoomTags + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The id of the user to get tags for. The access token must be + authorized to make requests for this user ID. + x-example: "@alice:example.com" + - in: path + type: string + name: roomId + required: true + description: |- + The ID of the room to get tags for. + x-example: "!726s6s6q:example.com" + responses: + 200: + description: + The list of tags for the user for the room. + schema: + type: object + properties: + tags: + type: object + additionalProperties: + title: Tag + type: object + properties: + order: + type: number + format: float + description: |- + A number in a range `[0,1]` describing a relative + position of the room under the given tag. + additionalProperties: true + examples: + application/json: { + "tags": { + "m.favourite": {"order": 0.1}, + "u.Work": {"order": 0.7}, + "u.Customers": {} + } + } + tags: + - User data + "/user/{userId}/rooms/{roomId}/tags/{tag}": + put: + summary: Add a tag to a room. + description: |- + Add a tag to the room. + operationId: setRoomTag + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The id of the user to add a tag for. The access token must be + authorized to make requests for this user ID. + x-example: "@alice:example.com" + - in: path + type: string + name: roomId + required: true + description: |- + The ID of the room to add a tag to. + x-example: "!726s6s6q:example.com" + - in: path + type: string + name: tag + required: true + description: |- + The tag to add. + x-example: "u.work" + - in: body + name: body + required: true + description: |- + Extra data for the tag, e.g. ordering. + schema: + type: object + properties: + order: + type: number + format: float + description: |- + A number in a range `[0,1]` describing a relative + position of the room under the given tag. + additionalProperties: true + example: { + "order": 0.25 + } + responses: + 200: + description: + The tag was successfully added. + schema: + type: object + examples: + application/json: {} + tags: + - User data + delete: + summary: Remove a tag from the room. + description: |- + Remove a tag from the room. + operationId: deleteRoomTag + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The id of the user to remove a tag for. The access token must be + authorized to make requests for this user ID. + x-example: "@alice:example.com" + - in: path + type: string + name: roomId + required: true + description: |- + The ID of the room to remove a tag from. + x-example: "!726s6s6q:example.com" + - in: path + type: string + name: tag + required: true + description: |- + The tag to remove. + x-example: "u.work" + responses: + 200: + description: + The tag was successfully removed. + schema: + type: object + examples: + application/json: {} + tags: + - User data diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml new file mode 100644 index 000000000..3d348df2f --- /dev/null +++ b/data/api/client-server/third_party_lookup.yaml @@ -0,0 +1,208 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Third Party Lookup API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/thirdparty/protocols": + get: + summary: Retrieve metadata about all protocols that a homeserver supports. + description: |- + Fetches the overall metadata about protocols supported by the + homeserver. Includes both the available protocols and all fields + required for queries against each protocol. + operationId: getProtocols + security: + - accessToken: [] + responses: + 200: + description: The protocols supported by the homeserver. + schema: + $ref: ../application-service/definitions/protocol_metadata.yaml + "/thirdparty/protocol/{protocol}": + get: + summary: Retrieve metadata about a specific protocol that the homeserver supports. + description: |- + Fetches the metadata from the homeserver about a particular third party protocol. + operationId: getProtocolMetadata + security: + - accessToken: [] + parameters: + - in: path + name: protocol + type: string + description: |- + The name of the protocol. + required: true + x-example: "irc" + responses: + 200: + description: The protocol was found and metadata returned. + schema: + $ref: ../application-service/definitions/protocol.yaml + 404: + description: The protocol is unknown. + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + $ref: definitions/errors/error.yaml + "/thirdparty/location/{protocol}": + get: + summary: Retrieve Matrix-side portals rooms leading to a third party location. + description: |- + Requesting this endpoint with a valid protocol name results in a list + of successful mapping results in a JSON array. Each result contains + objects to represent the Matrix room or rooms that represent a portal + to this third party network. Each has the Matrix room alias string, + an identifier for the particular third party network protocol, and an + object containing the network-specific fields that comprise this + identifier. It should attempt to canonicalise the identifier as much + as reasonably possible given the network type. + operationId: queryLocationByProtocol + security: + - accessToken: [] + parameters: + - in: path + name: protocol + type: string + description: The protocol used to communicate to the third party network. + required: true + x-example: irc + - in: query + name: searchFields + type: string + description: |- + One or more custom fields to help identify the third party + location. + responses: + 200: + description: At least one portal room was found. + schema: + $ref: ../application-service/definitions/location_batch.yaml + 404: + description: No portal rooms were found. + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + $ref: definitions/errors/error.yaml + "/thirdparty/user/{protocol}": + get: + summary: Retrieve the Matrix User ID of a corresponding third party user. + description: |- + Retrieve a Matrix User ID linked to a user on the third party service, given + a set of user parameters. + operationId: queryUserByProtocol + security: + - accessToken: [] + parameters: + - in: path + name: protocol + type: string + description: |- + The name of the protocol. + required: true + x-example: irc + - in: query + name: fields... + type: string + description: |- + One or more custom fields that are passed to the AS to help identify the user. + responses: + 200: + description: The Matrix User IDs found with the given parameters. + schema: + $ref: ../application-service/definitions/user_batch.yaml + 404: + description: The Matrix User ID was not found + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + $ref: definitions/errors/error.yaml + "/thirdparty/location": + get: + summary: Reverse-lookup third party locations given a Matrix room alias. + description: |- + Retrieve an array of third party network locations from a Matrix room + alias. + operationId: queryLocationByAlias + security: + - accessToken: [] + parameters: + - in: query + name: alias + type: string + description: The Matrix room alias to look up. + required: true + x-example: "#matrix:matrix.org" + responses: + 200: + description: |- + All found third party locations. + schema: + $ref: ../application-service/definitions/location_batch.yaml + 404: + description: The Matrix room alias was not found + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + $ref: definitions/errors/error.yaml + "/thirdparty/user": + get: + summary: Reverse-lookup third party users given a Matrix User ID. + description: |- + Retrieve an array of third party users from a Matrix User ID. + operationId: queryUserByID + security: + - accessToken: [] + parameters: + - in: query + name: userid + type: string + description: The Matrix User ID to look up. + required: true + x-example: "@bob:matrix.org" + responses: + 200: + description: |- + An array of third party users. + schema: + $ref: ../application-service/definitions/user_batch.yaml + 404: + description: The Matrix User ID was not found + examples: + application/json: { + "errcode": "M_NOT_FOUND" + } + schema: + $ref: definitions/errors/error.yaml diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml new file mode 100644 index 000000000..c48b4697a --- /dev/null +++ b/data/api/client-server/third_party_membership.yaml @@ -0,0 +1,140 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Room Membership API for third party identifiers" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/invite": + post: + summary: Invite a user to participate in a particular room. + description: |- + *Note that there are two forms of this API, which are documented separately. + This version of the API does not require that the inviter know the Matrix + identifier of the invitee, and instead relies on third party identifiers. + The homeserver uses an identity server to perform the mapping from + third party identifier to a Matrix identifier. The other is documented in the* + [joining rooms section](/client-server-api/#post_matrixclientr0roomsroomidinvite). + + This API invites a user to participate in a particular room. + They do not start participating in the room until they actually join the + room. + + Only users currently in a particular room can invite other users to + join that room. + + If the identity server did know the Matrix user identifier for the + third party identifier, the homeserver will append a `m.room.member` + event to the room. + + If the identity server does not know a Matrix user identifier for the + passed third party identifier, the homeserver will issue an invitation + which can be accepted upon providing proof of ownership of the third + party identifier. This is achieved by the identity server generating a + token, which it gives to the inviting homeserver. The homeserver will + add an `m.room.third_party_invite` event into the graph for the room, + containing that token. + + When the invitee binds the invited third party identifier to a Matrix + user ID, the identity server will give the user a list of pending + invitations, each containing: + + - The room ID to which they were invited + + - The token given to the homeserver + + - A signature of the token, signed with the identity server's private key + + - The matrix user ID who invited them to the room + + If a token is requested from the identity server, the homeserver will + append a `m.room.third_party_invite` event to the room. + + operationId: inviteBy3PID + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier (not alias) to which to invite the user. + required: true + x-example: "!d41d8cd:matrix.org" + - in: body + name: body + required: true + schema: + type: object + example: { + "id_server": "matrix.org", + "id_access_token": "abc123_OpaqueString", + "medium": "email", + "address": "cheeky@monkey.com" + } + properties: + id_server: + type: string + description: The hostname+port of the identity server which should be used for third party identifier lookups. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + medium: + type: string + # TODO: Link to Identity Service spec when it eixsts + description: The kind of address being passed in the address field, for example `email`. + address: + type: string + description: The invitee's third party identifier. + required: ["id_server", "id_access_token", "medium", "address"] + responses: + 200: + description: The user has been invited to join the room. + examples: + application/json: { + } + schema: + type: object + 403: + description: |- + You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + + - The invitee has been banned from the room. + - The invitee is already a member of the room. + - The inviter is not currently in the room. + - The inviter's power level is insufficient to invite users to the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room membership diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml new file mode 100644 index 000000000..a4d2f6dd7 --- /dev/null +++ b/data/api/client-server/to_device.yaml @@ -0,0 +1,91 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Client-Server Send-to-device API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/sendToDevice/{eventType}/{txnId}": + put: + summary: Send an event to a given set of devices. + description: |- + This endpoint is used to send send-to-device events to a set of + client devices. + operationId: sendToDevice + security: + - accessToken: [] + parameters: + - in: path + type: string + name: eventType + description: The type of event to send. + required: true + x-example: "m.new_device" + - in: path + name: txnId + type: string + description: |- + The transaction ID for this event. Clients should generate an + ID unique across requests with the same access token; it will be + used by the server to ensure idempotency of requests. + required: true + x-example: "35" + - in: body + name: body + required: true + schema: + type: object + title: body + properties: + messages: + type: object + description: |- + The messages to send. A map from user ID, to a map from + device ID to message body. The device ID may also be `*`, + meaning all known devices for the user. + additionalProperties: + type: object + additionalProperties: + type: object + title: EventContent + description: Message content + example: { + "@alice:example.com": { + "TLLBEANAAG": { + "example_content_key": "value" + } + } + } + required: ["messages"] + responses: + 200: + description: + The message was successfully sent. + examples: + application/json: { + } + tags: + - Send-to-Device messaging diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml new file mode 100644 index 000000000..c7138950d --- /dev/null +++ b/data/api/client-server/typing.yaml @@ -0,0 +1,87 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Typing API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/typing/{userId}": + put: + summary: Informs the server that the user has started or stopped typing. + description: |- + This tells the server that the user is typing for the next N + milliseconds where N is the value specified in the `timeout` key. + Alternatively, if `typing` is `false`, it tells the server that the + user has stopped typing. + operationId: setTyping + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + description: The user who has started to type. + required: true + x-example: "@alice:example.com" + - in: path + type: string + name: roomId + description: The room in which the user is typing. + required: true + x-example: "!wefh3sfukhs:example.com" + - in: body + name: typingState + description: The current typing state. + required: true + schema: + type: object + example: { + "typing": true, + "timeout": 30000 + } + properties: + typing: + type: boolean + description: |- + Whether the user is typing or not. If `false`, the `timeout` + key can be omitted. + timeout: + type: integer + description: The length of time in milliseconds to mark this user as typing. + required: ["typing"] + responses: + 200: + description: The new typing state was set. + examples: + application/json: { + } + schema: + type: object # empty json object + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room participation diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml new file mode 100644 index 000000000..255c538b1 --- /dev/null +++ b/data/api/client-server/users.yaml @@ -0,0 +1,108 @@ +# Copyright 2017 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server User Directory API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user_directory/search": + post: + summary: Searches the user directory. + description: |- + Performs a search for users. The homeserver may + determine which subset of users are searched, however the homeserver + MUST at a minimum consider the users the requesting user shares a + room with and those who reside in public rooms (known to the homeserver). + The search MUST consider local users to the homeserver, and SHOULD + query remote users as part of the search. + + The search is performed case-insensitively on user IDs and display + names preferably using a collation determined based upon the + `Accept-Language` header provided in the request, if present. + operationId: searchUserDirectory + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + properties: + search_term: + type: string + description: The term to search for + example: "foo" + limit: + type: integer + description: The maximum number of results to return. Defaults to 10. + example: 10 + required: ["search_term"] + responses: + 200: + description: The results of the search. + examples: + application/json: { + "results": [ + { + "user_id": "@foo:bar.com", + "display_name": "Foo", + "avatar_url": "mxc://bar.com/foo" + } + ], + "limited": false + } + schema: + type: object + required: ["results", "limited"] + properties: + results: + type: array + description: Ordered by rank and then whether or not profile info is available. + items: + title: User + type: object + required: ["user_id"] + properties: + user_id: + type: string + example: "@foo:bar.com" + description: The user's matrix user ID. + display_name: + type: string + example: "Foo" + description: The display name of the user, if one exists. + avatar_url: + type: string + example: "mxc://bar.com/foo" + description: The avatar url, as an MXC, if one exists. + limited: + type: boolean + description: Indicates if the result list has been truncated by the limit. + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml new file mode 100644 index 000000000..e359de3c9 --- /dev/null +++ b/data/api/client-server/versions.yaml @@ -0,0 +1,80 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Versions API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client +produces: + - application/json +paths: + "/versions": + get: + summary: Gets the versions of the specification supported by the server. + description: |- + Gets the versions of the specification supported by the server. + + Values will take the form `rX.Y.Z`. + + Only the latest `Z` value will be reported for each supported `X.Y` value. + i.e. if the server implements `r0.0.0`, `r0.0.1`, and `r1.2.0`, it will report `r0.0.1` and `r1.2.0`. + + The server may additionally advertise experimental features it supports + through `unstable_features`. These features should be namespaced and + may optionally include version information within their name if desired. + Features listed here are not for optionally toggling parts of the Matrix + specification and should only be used to advertise support for a feature + which has not yet landed in the spec. For example, a feature currently + undergoing the proposal process may appear here and eventually be taken + off this list once the feature lands in the spec and the server deems it + reasonable to do so. Servers may wish to keep advertising features here + after they've been released into the spec to give clients a chance to + upgrade appropriately. Additionally, clients should avoid using unstable + features in their stable releases. + operationId: getVersions + responses: + 200: + description: The versions supported by the server. + examples: + application/json: { + "versions": ["r0.0.1"], + "unstable_features": { + "org.example.my_feature": true + } + } + schema: + type: object + properties: + versions: + type: array + description: The supported versions. + items: + type: string + description: The supported versions + unstable_features: + type: object + description: |- + Experimental features the server supports. Features not listed here, + or the lack of this property all together, indicate that a feature is + not supported. + additionalProperties: + type: boolean + description: Whether or not the namespaced feature is supported. + required: ['versions'] + tags: + - Server administration diff --git a/data/api/client-server/voip.yaml b/data/api/client-server/voip.yaml new file mode 100644 index 000000000..75ace4c3a --- /dev/null +++ b/data/api/client-server/voip.yaml @@ -0,0 +1,78 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Voice over IP API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/voip/turnServer": + get: + summary: Obtain TURN server credentials. + description: |- + This API provides credentials for the client to use when initiating + calls. + operationId: getTurnServer + security: + - accessToken: [] + responses: + 200: + description: The TURN server credentials. + examples: + application/json: { + "username":"1443779631:@user:example.com", + "password":"JlKfBy1QwLrO20385QyAtEyIv0=", + "uris":[ + "turn:turn.example.com:3478?transport=udp", + "turn:10.20.30.40:3478?transport=tcp", + "turns:10.20.30.40:443?transport=tcp" + ], + "ttl":86400 + } + schema: + type: object + properties: + username: + type: string + description: |- + The username to use. + password: + type: string + description: |- + The password to use. + uris: + type: array + items: + type: string + description: A list of TURN URIs + ttl: + type: integer + description: The time-to-live in seconds + required: ["username", "password", "uris", "ttl"] + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - VOIP diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml new file mode 100644 index 000000000..9fff7ea78 --- /dev/null +++ b/data/api/client-server/wellknown.yaml @@ -0,0 +1,46 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Server Discovery API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https +basePath: /.well-known +produces: + - application/json +paths: + "/matrix/client": + get: + summary: Gets Matrix server discovery information about the domain. + description: |- + Gets discovery information about the domain. The file may include + additional keys, which MUST follow the Java package naming convention, + e.g. `com.example.myapp.property`. This ensures property names are + suitably namespaced for each application and reduces the risk of + clashes. + + Note that this endpoint is not necessarily handled by the homeserver, + but by another webserver, to be used for discovering the homeserver URL. + operationId: getWellknown + responses: + 200: + description: Server discovery information. + schema: + "$ref": "definitions/wellknown/full.yaml" + 404: + description: No server discovery information available. + tags: + - Server administration diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml new file mode 100644 index 000000000..713ed3702 --- /dev/null +++ b/data/api/client-server/whoami.yaml @@ -0,0 +1,84 @@ +# Copyright 2017 Travis Ralston +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Account Identification API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/account/whoami": + get: + summary: Gets information about the owner of an access token. + description: |- + Gets information about the owner of a given access token. + + Note that, as with the rest of the Client-Server API, + Application Services may masquerade as users within their + namespace by giving a `user_id` query parameter. In this + situation, the server should verify that the given `user_id` + is registered by the appservice, and return it in the response + body. + operationId: getTokenOwner + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: + The token belongs to a known user. + examples: + application/json: { + "user_id": "@joe:example.org" + } + schema: + type: object + required: ["user_id"] + properties: + user_id: + type: string + description: The user id that owns the access token. + 401: + description: + The token is not recognised + examples: + application/json: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecognised access token." + } + schema: + "$ref": "definitions/errors/error.yaml" + 403: + description: + The appservice cannot masquerade as the user or has not registered them. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Application service has not registered this user." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data diff --git a/data/api/identity/associations.yaml b/data/api/identity/associations.yaml new file mode 100644 index 000000000..f2d09af1c --- /dev/null +++ b/data/api/identity/associations.yaml @@ -0,0 +1,302 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Establishing Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/3pid/getValidated3pid": + get: + summary: Check whether ownership of a 3pid was validated. + description: |- + Determines if a given 3pid has been validated by a user. + operationId: getValidated3pid + deprecated: true + parameters: + - in: query + type: string + name: sid + description: The Session ID generated by the `requestToken` call. + required: true + x-example: 1234 + - in: query + type: string + name: client_secret + description: The client secret passed to the `requestToken` call. + required: true + x-example: monkeys_are_GREAT + responses: + 200: + description: Validation information for the session. + examples: + application/json: { + "medium": "email", + "validated_at": 1457622739026, + "address": "louise@bobs.burgers" + } + schema: + type: object + properties: + medium: + type: string + description: The medium type of the 3pid. + address: + type: string + description: The address of the 3pid being looked up. + validated_at: + type: integer + description: |- + Timestamp, in milliseconds, indicating the time that the 3pid + was validated. + required: ['medium', 'address', 'validated_at'] + 400: + description: |- + The session has not been validated. + + If the session has not been validated, then `errcode` will be + `M_SESSION_NOT_VALIDATED`. If the session has timed out, then + `errcode` will be `M_SESSION_EXPIRED`. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: The Session ID or client secret were not found. + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/3pid/bind": + post: + summary: Publish an association between a session and a Matrix user ID. + description: |- + Publish an association between a session and a Matrix user ID. + + Future calls to `/lookup` for any of the session\'s 3pids will return + this association. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: bind + deprecated: true + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:matrix.org" + } + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to associate with the 3pids. + required: ["sid", "client_secret", "mxid"] + responses: + 200: + description: The association was published. + examples: + application/json: { + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" + } + } + } + schema: + type: object + properties: + address: + type: string + description: The 3pid address of the user being looked up. + medium: + type: string + description: The medium type of the 3pid. + mxid: + type: string + description: The Matrix user ID associated with the 3pid. + not_before: + type: integer + description: A unix timestamp before which the association is not known to be valid. + not_after: + type: integer + description: A unix timestamp after which the association is not known to be valid. + ts: + type: integer + description: The unix timestamp at which the association was verified. + signatures: + type: object + description: |- + The signatures of the verifying identity servers which show that the + association should be trusted, if you trust the verifying identity + services. + $ref: "../../schemas/server-signatures.yaml" + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures + 400: + description: |- + The association was not published. + + If the session has not been validated, then `errcode` will be + `M_SESSION_NOT_VALIDATED`. If the session has timed out, then + `errcode` will be `M_SESSION_EXPIRED`. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: The Session ID or client secret were not found + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/3pid/unbind": + post: + summary: Remove an association between a session and a Matrix user ID. + description: |- + Remove an association between a session and a Matrix user ID. + + Future calls to `/lookup` for any of the session's 3pids will not + return the removed association. + + The identity server should authenticate the request in one of two + ways: + + 1. The request is signed by the homeserver which controls the `user_id`. + 2. The request includes the `sid` and `client_secret` parameters, + as per `/3pid/bind`, which proves ownership of the 3PID. + + If this endpoint returns a JSON Matrix error, that error should be passed + through to the client requesting an unbind through a homeserver, if the + homeserver is acting on behalf of a client. + operationId: unbind + deprecated: true + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:example.org", + "threepid": { + "medium": "email", + "address": "monkeys_have_ears@example.org" + } + } + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to remove from the 3pids. + threepid: + type: object + title: 3PID + description: |- + The 3PID to remove. Must match the 3PID used to generate the session + if using `sid` and `client_secret` to authenticate this request. + properties: + medium: + type: string + description: |- + A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium + of the identifier to unbind. + address: + type: string + description: The 3PID address to remove. + required: ['medium', 'address'] + required: ["threepid", "mxid"] + responses: + 200: + description: The association was successfully removed. + examples: + application/json: {} + schema: + type: object + 400: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 404: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 403: + description: |- + The credentials supplied to authenticate the request were invalid. + This may also be returned if the identity server does not support + the chosen authentication method (such as blocking homeservers from + unbinding identifiers). + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Invalid homeserver signature" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 501: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. diff --git a/data/api/identity/definitions/request_email_validation.yaml b/data/api/identity/definitions/request_email_validation.yaml new file mode 100644 index 000000000..c8a3af6a3 --- /dev/null +++ b/data/api/identity/definitions/request_email_validation.yaml @@ -0,0 +1,52 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +example: { + "client_secret": "monkeys_are_GREAT", + "email": "foo@example.com", + "send_attempt": 1 +} +properties: + client_secret: + type: string + description: | + A unique string generated by the client, and used to identify the + validation attempt. It must be a string consisting of the characters + `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + must not be empty. + example: "monkeys_are_GREAT" + email: + type: string + description: The email address to validate. + example: "alice@example.org" + send_attempt: + type: integer + description: |- + The server will only send an email if the `send_attempt` + is a number greater than the most recent one which it has seen, + scoped to that `email` + `client_secret` pair. This is to + avoid repeatedly sending the same email in the case of request + retries between the POSTing user and the identity server. + The client should increment this value if they desire a new + email (e.g. a reminder) to be sent. If they do not, the server + should respond with success but not resend the email. + example: 1 + next_link: + type: string + description: |- + Optional. When the validation is completed, the identity server will + redirect the user to this URL. This option is ignored when submitting + 3PID validation information through a POST request. + example: "https://example.org/congratulations.html" +required: ["client_secret", "email", "send_attempt"] diff --git a/data/api/identity/definitions/request_msisdn_validation.yaml b/data/api/identity/definitions/request_msisdn_validation.yaml new file mode 100644 index 000000000..2b1c87080 --- /dev/null +++ b/data/api/identity/definitions/request_msisdn_validation.yaml @@ -0,0 +1,58 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +example: { + "client_secret": "monkeys_are_GREAT", + "country": "GB", + "phone_number": "07700900001", + "send_attempt": 1 +} +properties: + client_secret: + type: string + description: | + A unique string generated by the client, and used to identify the + validation attempt. It must be a string consisting of the characters + `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + must not be empty. + example: "monkeys_are_GREAT" + country: + type: string + description: |- + The two-letter uppercase ISO-3166-1 alpha-2 country code that the + number in `phone_number` should be parsed as if it were dialled from. + example: "GB" + phone_number: + type: string + description: The phone number to validate. + example: "07700900001" + send_attempt: + type: integer + description: |- + The server will only send an SMS if the `send_attempt` is a + number greater than the most recent one which it has seen, + scoped to that `country` + `phone_number` + `client_secret` + triple. This is to avoid repeatedly sending the same SMS in + the case of request retries between the POSTing user and the + identity server. The client should increment this value if + they desire a new SMS (e.g. a reminder) to be sent. + example: 1 + next_link: + type: string + description: |- + Optional. When the validation is completed, the identity server will + redirect the user to this URL. This option is ignored when submitting + 3PID validation information through a POST request. + example: "https://example.org/congratulations.html" +required: ["client_secret", "country", "phone_number", "send_attempt"] diff --git a/data/api/identity/definitions/security.yaml b/data/api/identity/definitions/security.yaml new file mode 100644 index 000000000..64225ec44 --- /dev/null +++ b/data/api/identity/definitions/security.yaml @@ -0,0 +1,18 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +accessToken: + type: apiKey + description: The access_token returned by a call to `/register`. + name: access_token + in: query diff --git a/data/api/identity/definitions/sid.yaml b/data/api/identity/definitions/sid.yaml new file mode 100644 index 000000000..904f79e12 --- /dev/null +++ b/data/api/identity/definitions/sid.yaml @@ -0,0 +1,24 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +properties: + sid: + type: string + description: | + The session ID. Session IDs are opaque strings generated by the identity + server. They must consist entirely of the characters + `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 characters and they + must not be empty. + example: "123abc" +required: ['sid'] diff --git a/data/api/identity/email_associations.yaml b/data/api/identity/email_associations.yaml new file mode 100644 index 000000000..6aa7bf4ac --- /dev/null +++ b/data/api/identity/email_associations.yaml @@ -0,0 +1,177 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Email Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/validate/email/requestToken": + post: + summary: Request a token for validating an email address. + description: |- + Create a session for validating an email address. + + The identity server will send an email containing a token. If that + token is presented to the identity server in the future, it indicates + that that user was able to read the email for that email address, and + so we validate ownership of the email address. + + Note that homeservers offer APIs that proxy this API, adding + additional behaviour on top, for example, + `/register/email/requestToken` is designed specifically for use when + registering an account and therefore will inform the user if the email + address given is already registered on the server. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: emailRequestToken + deprecated: true + parameters: + - in: body + name: body + schema: + $ref: "definitions/request_email_validation.yaml" + responses: + 200: + description: Session created. + schema: + $ref: "definitions/sid.yaml" + 400: + description: | + An error ocurred. Some possible errors are: + + - `M_INVALID_EMAIL`: The email address provided was invalid. + - `M_EMAIL_SEND_ERROR`: The validation email could not be sent. + examples: + application/json: { + "errcode": "M_INVALID_EMAIL", + "error": "The email address is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/validate/email/submitToken": + post: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + associate the email address with any Matrix user ID. Specifically, + calls to `/lookup` will not show a binding. + + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: emailSubmitTokenPost + deprecated: true + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and emailed to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: ['success'] + get: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + associate the email address with any Matrix user ID. Specifically, + calls to `/lookup` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: emailSubmitTokenGet + deprecated: true + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the `requestToken` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the `requestToken` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the `requestToken` call and emailed to the user. + x-example: atoken + responses: + 200: + description: Email address is validated. + "3xx": + description: |- + Email address is validated, and the `next_link` parameter was + provided to the `requestToken` call. The user must be redirected + to the URL provided by the `next_link` parameter. + "4xx": + description: + Validation failed. diff --git a/data/api/identity/invitation_signing.yaml b/data/api/identity/invitation_signing.yaml new file mode 100644 index 000000000..a3d215f2e --- /dev/null +++ b/data/api/identity/invitation_signing.yaml @@ -0,0 +1,97 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Ephemeral Invitation Signing API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/sign-ed25519": + post: + summary: Sign invitation details + description: |- + Sign invitation details. + + The identity server will look up `token` which was stored in a call + to `store-invite`, and fetch the sender of the invite. + operationId: blindlySignStuff + deprecated: true + parameters: + - in: body + name: body + schema: + type: object + example: { + "mxid": "@foo:bar.com", + "token": "sometoken", + "private_key": "base64encodedkey" + } + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + token: + type: string + description: The token from the call to `store-invite`. + private_key: + type: string + description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64). + required: ["mxid", "token", "private_key"] + responses: + 200: + description: The signed JSON of the mxid, sender, and token. + schema: + type: object + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + sender: + type: string + description: The Matrix user ID of the user who sent the invitation. + signatures: + type: object + description: The signature of the mxid, sender, and token. + $ref: "../../schemas/server-signatures.yaml" + token: + type: string + description: The token for the invitation. + required: ['mxid', 'sender', 'signatures', 'token'] + examples: + application/json: { + "mxid": "@foo:bar.com", + "sender": "@baz:bar.com", + "signatures": { + "my.id.server": { + "ed25519:0": "def987" + } + }, + "token": "abc123" + } + 404: + description: The token was not found. + examples: + application/json: { + "errcode": "M_UNRECOGNIZED", + "error": "Didn't recognize token" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/lookup.yaml b/data/api/identity/lookup.yaml new file mode 100644 index 000000000..6163807e1 --- /dev/null +++ b/data/api/identity/lookup.yaml @@ -0,0 +1,171 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2017 Kamax.io +# Copyright 2017 New Vector Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Lookup API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/lookup": + get: + summary: Look up the Matrix user ID for a 3pid. + description: Look up the Matrix user ID for a 3pid. + operationId: lookupUser + deprecated: true + parameters: + - in: query + type: string + name: medium + required: true + description: The medium type of the 3pid. See the [3PID Types](/appendices/#3pid-types) Appendix. + x-example: "email" + - in: query + type: string + name: address + required: true + description: The address of the 3pid being looked up. See the [3PID Types](/appendices/#3pid-types) Appendix. + x-example: "louise@bobs.burgers" + responses: + 200: + description: + The association for that 3pid, or an empty object if no association is known. + examples: + application/json: { + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" + } + } + } + schema: + type: object + properties: + address: + type: string + description: The 3pid address of the user being looked up, matching the address requested. + medium: + type: string + description: A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium requested. + mxid: + type: string + description: The Matrix user ID associated with the 3pid. + not_before: + type: integer + description: A unix timestamp before which the association is not known to be valid. + not_after: + type: integer + description: A unix timestamp after which the association is not known to be valid. + ts: + type: integer + description: The unix timestamp at which the association was verified. + signatures: + type: object + description: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity servers. + $ref: "../../schemas/server-signatures.yaml" + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures + "/bulk_lookup": + post: + summary: Lookup Matrix user IDs for a list of 3pids. + description: Lookup Matrix user IDs for a list of 3pids. + operationId: lookupUsers + deprecated: true + parameters: + - in: body + name: body + schema: + type: object + example: { + "threepids": + [ + ["email","user@example.org"], + ["msisdn", "123456789"], + ["email","user2@example.org"] + ] + } + properties: + threepids: + type: array + items: + type: array + title: 3PID mappings + minItems: 2 + maxItems: 2 + items: + # TODO: Give real names to these values. Adding a `title` does not work. + #- type: 3PID Medium + #- type: 3PID Address + - type: string + - type: string + description: |- + An array of arrays containing the [3PID Types](/appendices/#3pid-types) with the `medium` + in first position and the `address` in second position. + required: + - "threepids" + responses: + 200: + description: A list of known 3PID mappings for the supplied 3PIDs. + examples: + application/json: { + "threepids": [ + ["email","user@example.org", "@bla:example.org"], + ["msisdn", "123456789", "@blah2:example.com"] + ] + } + schema: + type: object + properties: + threepids: + type: array + items: + type: array + title: 3PID mappings + minItems: 3 + maxItems: 3 + items: + # TODO: Give real names to these values. Adding a `title` does not work. + #- type: 3PID Medium + #- type: 3PID Address + #- type: Matrix User ID + - type: string + - type: string + - type: string + description: |- + An array of array containing the [3PID Types](/appendices/#3pid-types) with the `medium` + in first position, the `address` in second position and Matrix user + ID in third position. + required: + - "threepids" diff --git a/data/api/identity/phone_associations.yaml b/data/api/identity/phone_associations.yaml new file mode 100644 index 000000000..53d4132da --- /dev/null +++ b/data/api/identity/phone_associations.yaml @@ -0,0 +1,179 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Phone Number Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/validate/msisdn/requestToken": + post: + summary: Request a token for validating a phone number. + description: |- + Create a session for validating a phone number. + + The identity server will send an SMS message containing a token. If + that token is presented to the identity server in the future, it + indicates that that user was able to read the SMS for that phone + number, and so we validate ownership of the phone number. + + Note that homeservers offer APIs that proxy this API, adding + additional behaviour on top, for example, + `/register/msisdn/requestToken` is designed specifically for use when + registering an account and therefore will inform the user if the phone + number given is already registered on the server. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: msisdnRequestToken + deprecated: true + parameters: + - in: body + name: body + schema: + $ref: "definitions/request_msisdn_validation.yaml" + responses: + 200: + description: Session created. + schema: + $ref: "definitions/sid.yaml" + 400: + description: | + An error ocurred. Some possible errors are: + + - `M_INVALID_ADDRESS`: The phone number provided was invalid. + - `M_SEND_ERROR`: The validation SMS could not be sent. + - `M_DESTINATION_REJECTED`: The identity server cannot deliver an + SMS to the provided country or region. + examples: + application/json: { + "errcode": "M_INVALID_ADDRESS", + "error": "The phone number is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/validate/msisdn/submitToken": + post: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the phone number is considered to + have been validated. This does not publish any information publicly, or + associate the phone number address with any Matrix user + ID. Specifically, calls to `/lookup` will not show a binding. + + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: msisdnSubmitTokenPost + deprecated: true + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and sent to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: ['success'] + get: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the phone number address is + considered to have been validated. This does not publish any + information publicly, or associate the phone number with any Matrix + user ID. Specifically, calls to `/lookup` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: msisdnSubmitTokenGet + deprecated: true + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the `requestToken` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the `requestToken` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the `requestToken` call and sent to the user. + x-example: atoken + responses: + 200: + description: Phone number is validated. + "3xx": + description: |- + Phone number address is validated, and the `next_link` parameter + was provided to the `requestToken` call. The user must be + redirected to the URL provided by the `next_link` parameter. + "4xx": + description: + Validation failed. diff --git a/data/api/identity/ping.yaml b/data/api/identity/ping.yaml new file mode 100644 index 000000000..d7249a772 --- /dev/null +++ b/data/api/identity/ping.yaml @@ -0,0 +1,46 @@ +# Copyright 2018 Kamax Sàrl +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: "2.0" +info: + title: "Matrix Identity Service Ping API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity +produces: + - application/json +paths: + "/api/v1": + get: + summary: Checks that an identity server is available at this API endpoint. + description: |- + Checks that an identity server is available at this API endpoint. + + To discover that an identity server is available at a specific URL, + this endpoint can be queried and will return an empty object. + + This is primarly used for auto-discovery and health check purposes + by entities acting as a client for the identity server. + operationId: ping + deprecated: true + responses: + 200: + description: An identity server is ready to serve requests. + examples: + application/json: {} + schema: + type: object diff --git a/data/api/identity/pubkey.yaml b/data/api/identity/pubkey.yaml new file mode 100644 index 000000000..a585e7ecb --- /dev/null +++ b/data/api/identity/pubkey.yaml @@ -0,0 +1,129 @@ +# Copyright 2016 OpenMarket Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Public Key API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/pubkey/{keyId}": + get: + summary: Get a public key. + description: |- + Get the public key for the passed key ID. + operationId: getPubKey + deprecated: true + parameters: + - in: path + type: string + name: keyId + required: true + description: |- + The ID of the key. This should take the form algorithm:identifier + where algorithm identifies the signing algorithm, and the identifier + is an opaque string. + x-example: "ed25519:0" + responses: + 200: + description: + The public key exists. + examples: + application/json: { + "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + } + schema: + type: object + properties: + public_key: + type: string + description: Unpadded Base64 encoded public key. + required: ['public_key'] + 404: + description: + The public key was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The public key was not found" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/pubkey/isvalid": + get: + summary: Check whether a long-term public key is valid. + description: |- + Check whether a long-term public key is valid. The response should always + be the same, provided the key exists. + operationId: isPubKeyValid + deprecated: true + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: ['valid'] + "/pubkey/ephemeral/isvalid": + get: + summary: Check whether a short-term public key is valid. + description: |- + Check whether a short-term public key is valid. + operationId: isEphemeralPubKeyValid + deprecated: true + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: ['valid'] diff --git a/data/api/identity/store_invite.yaml b/data/api/identity/store_invite.yaml new file mode 100644 index 000000000..20e408522 --- /dev/null +++ b/data/api/identity/store_invite.yaml @@ -0,0 +1,161 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Store Invitations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/store-invite": + post: + summary: Store pending invitations to a user's 3pid. + description: |- + Store pending invitations to a user's 3pid. + + In addition to the request parameters specified below, an arbitrary + number of other parameters may also be specified. These may be used in + the invite message generation described below. + + The service will generate a random token and an ephemeral key used for + accepting the invite. + + The service also generates a `display_name` for the inviter, which is + a redacted version of `address` which does not leak the full contents + of the `address`. + + The service records persistently all of the above information. + + It also generates an email containing all of this data, sent to the + `address` parameter, notifying them of the invitation. + + Also, the generated ephemeral public key will be listed as valid on + requests to `/_matrix/identity/api/v1/pubkey/ephemeral/isvalid`. + + Currently, invites may only be issued for 3pids of the `email` medium. + + Optional fields in the request should be populated to the best of the + server's ability. Identity servers may use these variables when notifying + the `address` of the pending invite for display purposes. + operationId: storeInvite + deprecated: true + parameters: + - in: body + name: body + schema: + type: object + properties: + medium: + type: string + description: The literal string `email`. + example: "email" + address: + type: string + description: The email address of the invited user. + example: "foo@example.com" + room_id: + type: string + description: The Matrix room ID to which the user is invited + example: "!something:example.org" + sender: + type: string + description: The Matrix user ID of the inviting user + example: "@bob:example.com" + room_alias: + type: string + description: |- + The Matrix room alias for the room to which the user is + invited. This should be retrieved from the `m.room.canonical_alias` + state event. + example: "#somewhere:exmaple.org" + room_avatar_url: + type: string + description: |- + The Content URI for the room to which the user is invited. This should + be retrieved from the `m.room.avatar` state event. + example: "mxc://example.org/s0meM3dia" + room_join_rules: + type: string + description: |- + The `join_rule` for the room to which the user is invited. This should + be retrieved from the `m.room.join_rules` state event. + example: "public" + room_name: + type: string + description: |- + The name of the room to which the user is invited. This should be retrieved + from the `m.room.name` state event. + example: "Bob's Emporium of Messages" + sender_display_name: + type: string + description: The display name of the user ID initiating the invite. + example: "Bob Smith" + sender_avatar_url: + type: string + description: The Content URI for the avatar of the user ID initiating the invite. + example: "mxc://example.org/an0th3rM3dia" + required: ["medium", "address", "room_id", "sender"] + responses: + 200: + description: The invitation was stored. + schema: + type: object + properties: + token: + type: string + description: | + The generated token. Must be a string consisting of the + characters `[0-9a-zA-Z.=_-]`. Its length must not exceed + 255 characters and it must not be empty. + public_keys: + type: array + description: | + A list of [server's long-term public key, generated ephemeral + public key]. + items: + type: string + display_name: + type: string + description: The generated (redacted) display_name. + required: ['token', 'public_keys', 'display_name'] + example: + application/json: { + "token": "sometoken", + "public_keys": [ + "serverpublickey", + "ephemeralpublickey" + ], + "display_name": "f...@b..." + } + 400: + description: | + An error has occured. + + If the 3pid is already bound to a Matrix user ID, the error code + will be `M_THREEPID_IN_USE`. If the medium is unsupported, the + error code will be `M_UNRECOGNIZED`. + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "Binding already known", + "mxid": "@alice:example.com" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml new file mode 100644 index 000000000..e08ac1dab --- /dev/null +++ b/data/api/identity/v2_associations.yaml @@ -0,0 +1,333 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Establishing Associations API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/3pid/getValidated3pid": + get: + summary: Check whether ownership of a 3pid was validated. + description: |- + Determines if a given 3pid has been validated by a user. + operationId: getValidated3pidV2 + security: + - accessToken: [] + parameters: + - in: query + type: string + name: sid + description: The Session ID generated by the `requestToken` call. + required: true + x-example: 1234 + - in: query + type: string + name: client_secret + description: The client secret passed to the `requestToken` call. + required: true + x-example: monkeys_are_GREAT + responses: + 200: + description: Validation information for the session. + examples: + application/json: { + "medium": "email", + "validated_at": 1457622739026, + "address": "louise@bobs.burgers" + } + schema: + type: object + properties: + medium: + type: string + description: The medium type of the 3pid. + address: + type: string + description: The address of the 3pid being looked up. + validated_at: + type: integer + description: |- + Timestamp, in milliseconds, indicating the time that the 3pid + was validated. + required: ['medium', 'address', 'validated_at'] + 400: + description: |- + The session has not been validated. + + If the session has not been validated, then `errcode` will be + `M_SESSION_NOT_VALIDATED`. If the session has timed out, then + `errcode` will be `M_SESSION_EXPIRED`. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: The Session ID or client secret were not found. + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/3pid/bind": + post: + summary: Publish an association between a session and a Matrix user ID. + description: |- + Publish an association between a session and a Matrix user ID. + + Future calls to `/lookup` for any of the session\'s 3pids will return + this association. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: bindV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:matrix.org" + } + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to associate with the 3pids. + required: ["sid", "client_secret", "mxid"] + responses: + 200: + description: The association was published. + examples: + application/json: { + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" + } + } + } + schema: + type: object + properties: + address: + type: string + description: The 3pid address of the user being looked up. + medium: + type: string + description: The medium type of the 3pid. + mxid: + type: string + description: The Matrix user ID associated with the 3pid. + not_before: + type: integer + description: A unix timestamp before which the association is not known to be valid. + not_after: + type: integer + description: A unix timestamp after which the association is not known to be valid. + ts: + type: integer + description: The unix timestamp at which the association was verified. + signatures: + type: object + description: |- + The signatures of the verifying identity servers which show that the + association should be trusted, if you trust the verifying identity + services. + $ref: "../../schemas/server-signatures.yaml" + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures + 400: + description: |- + The association was not published. + + If the session has not been validated, then `errcode` will be + `M_SESSION_NOT_VALIDATED`. If the session has timed out, then + `errcode` will be `M_SESSION_EXPIRED`. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: The Session ID or client secret were not found + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/3pid/unbind": + post: + summary: Remove an association between a session and a Matrix user ID. + description: |- + Remove an association between a session and a Matrix user ID. + + Future calls to `/lookup` for any of the session's 3pids will not + return the removed association. + + The identity server should authenticate the request in one of two + ways: + + 1. The request is signed by the homeserver which controls the `user_id`. + 2. The request includes the `sid` and `client_secret` parameters, + as per `/3pid/bind`, which proves ownership of the 3PID. + + If this endpoint returns a JSON Matrix error, that error should be passed + through to the client requesting an unbind through a homeserver, if the + homeserver is acting on behalf of a client. + operationId: unbindV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:example.org", + "threepid": { + "medium": "email", + "address": "monkeys_have_ears@example.org" + } + } + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to remove from the 3pids. + threepid: + type: object + title: 3PID + description: |- + The 3PID to remove. Must match the 3PID used to generate the session + if using `sid` and `client_secret` to authenticate this request. + properties: + medium: + type: string + description: |- + A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium + of the identifier to unbind. + address: + type: string + description: The 3PID address to remove. + required: ['medium', 'address'] + required: ["threepid", "mxid"] + responses: + 200: + description: The association was successfully removed. + examples: + application/json: {} + schema: + type: object + 400: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 404: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 403: + description: |- + The credentials supplied to authenticate the request were invalid. + This may also be returned if the identity server does not support + the chosen authentication method (such as blocking homeservers from + unbinding identifiers). + + Another common error code is `M_TERMS_NOT_SIGNED` where the user + needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Invalid homeserver signature" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 501: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. diff --git a/data/api/identity/v2_auth.yaml b/data/api/identity/v2_auth.yaml new file mode 100644 index 000000000..b5d1a41cc --- /dev/null +++ b/data/api/identity/v2_auth.yaml @@ -0,0 +1,131 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Authentication API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/account/register": + post: + summary: Exchanges an OpenID token for an access token. + description: |- + Exchanges an OpenID token from the homeserver for an access token to + access the identity server. The request body is the same as the values + returned by `/openid/request_token` in the Client-Server API. + operationId: registerAccount + parameters: + - in: body + name: body + schema: + $ref: "../client-server/definitions/openid_token.yaml" + responses: + 200: + description: |- + A token which can be used to authenticate future requests to the + identity server. + examples: + application/json: { + "token": "abc123_OpaqueString" + } + schema: + type: object + properties: + token: + type: string + description: |- + An opaque string representing the token to authenticate future + requests to the identity server with. + required: ['token'] + "/account": + get: + summary: Gets account holder information for a given token. + description: |- + Gets information about what user owns the access token used in the request. + operationId: getAccount + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: The token holder's information. + examples: + application/json: { + "user_id": "@alice:example.org" + } + schema: + type: object + properties: + user_id: + type: string + description: The user ID which registered the token. + required: ['user_id'] + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/account/logout": + post: + summary: Logs out an access token, rendering it unusable. + description: |- + Logs out the access token, preventing it from being used to authenticate + future requests to the server. + operationId: logout + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: The token was successfully logged out. + examples: + application/json: {} + schema: + type: object + 401: + description: |- + The token is not registered or is otherwise unknown to the server. + examples: + application/json: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecognised access token" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml new file mode 100644 index 000000000..08e8c9fa1 --- /dev/null +++ b/data/api/identity/v2_email_associations.yaml @@ -0,0 +1,216 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Email Associations API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/validate/email/requestToken": + post: + summary: Request a token for validating an email address. + description: |- + Create a session for validating an email address. + + The identity server will send an email containing a token. If that + token is presented to the identity server in the future, it indicates + that that user was able to read the email for that email address, and + so we validate ownership of the email address. + + Note that homeservers offer APIs that proxy this API, adding + additional behaviour on top, for example, + `/register/email/requestToken` is designed specifically for use when + registering an account and therefore will inform the user if the email + address given is already registered on the server. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: emailRequestTokenV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + $ref: "definitions/request_email_validation.yaml" + responses: + 200: + description: Session created. + schema: + $ref: "definitions/sid.yaml" + 400: + description: | + An error ocurred. Some possible errors are: + + - `M_INVALID_EMAIL`: The email address provided was invalid. + - `M_EMAIL_SEND_ERROR`: The validation email could not be sent. + examples: + application/json: { + "errcode": "M_INVALID_EMAIL", + "error": "The email address is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/validate/email/submitToken": + post: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + associate the email address with any Matrix user ID. Specifically, + calls to `/lookup` will not show a binding. + + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: emailSubmitTokenPostV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and emailed to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: ['success'] + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + get: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + associate the email address with any Matrix user ID. Specifically, + calls to `/lookup` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: emailSubmitTokenGetV2 + security: + - accessToken: [] + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the `requestToken` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the `requestToken` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the `requestToken` call and emailed to the user. + x-example: atoken + responses: + 200: + description: Email address is validated. + "3xx": + description: |- + Email address is validated, and the `next_link` parameter was + provided to the `requestToken` call. The user must be redirected + to the URL provided by the `next_link` parameter. + "4xx": + description: + Validation failed. + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/v2_invitation_signing.yaml b/data/api/identity/v2_invitation_signing.yaml new file mode 100644 index 000000000..d81b973dd --- /dev/null +++ b/data/api/identity/v2_invitation_signing.yaml @@ -0,0 +1,112 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Ephemeral Invitation Signing API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/sign-ed25519": + post: + summary: Sign invitation details + description: |- + Sign invitation details. + + The identity server will look up `token` which was stored in a call + to `store-invite`, and fetch the sender of the invite. + operationId: blindlySignStuffV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + example: { + "mxid": "@foo:bar.com", + "token": "sometoken", + "private_key": "base64encodedkey" + } + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + token: + type: string + description: The token from the call to `store-invite`. + private_key: + type: string + description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64). + required: ["mxid", "token", "private_key"] + responses: + 200: + description: The signed JSON of the mxid, sender, and token. + schema: + type: object + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + sender: + type: string + description: The Matrix user ID of the user who sent the invitation. + signatures: + type: object + description: The signature of the mxid, sender, and token. + $ref: "../../schemas/server-signatures.yaml" + token: + type: string + description: The token for the invitation. + required: ['mxid', 'sender', 'signatures', 'token'] + examples: + application/json: { + "mxid": "@foo:bar.com", + "sender": "@baz:bar.com", + "signatures": { + "my.id.server": { + "ed25519:0": "def987" + } + }, + "token": "abc123" + } + 404: + description: The token was not found. + examples: + application/json: { + "errcode": "M_UNRECOGNIZED", + "error": "Didn't recognize token" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/v2_lookup.yaml b/data/api/identity/v2_lookup.yaml new file mode 100644 index 000000000..9e5b18ecf --- /dev/null +++ b/data/api/identity/v2_lookup.yaml @@ -0,0 +1,148 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2017 Kamax.io +# Copyright 2017 New Vector Ltd +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Lookup API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/hash_details": + get: + summary: Gets hash function information from the server. + description: |- + Gets parameters for hashing identifiers from the server. This can include + any of the algorithms defined in this specification. + operationId: getHashDetails + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: The hash function information. + examples: + application/json: { + "lookup_pepper": "matrixrocks", + "algorithms": ["none", "sha256"] + } + schema: + type: object + properties: + lookup_pepper: + type: string + description: |- + The pepper the client MUST use in hashing identifiers, and MUST + supply to the `/lookup` endpoint when performing lookups. + + Servers SHOULD rotate this string often. + algorithms: + type: array + items: + type: string + description: |- + The algorithms the server supports. Must contain at least `sha256`. + required: ['lookup_pepper', 'algorithms'] + "/lookup": + post: + summary: Look up Matrix User IDs for a set of 3PIDs. + description: |- + Looks up the set of Matrix User IDs which have bound the 3PIDs given, if + bindings are available. Note that the format of the addresses is defined + later in this specification. + operationId: lookupUsersV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + properties: + algorithm: + type: string + description: |- + The algorithm the client is using to encode the `addresses`. This + should be one of the available options from `/hash_details`. + example: "sha256" + pepper: + type: string + description: |- + The pepper from `/hash_details`. This is required even when the + `algorithm` does not make use of it. + example: "matrixrocks" + addresses: + type: array + items: + type: string + description: |- + The addresses to look up. The format of the entries here depend on + the `algorithm` used. Note that queries which have been incorrectly + hashed or formatted will lead to no matches. + example: [ + "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc", + "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I" + ] + required: ['algorithm', 'pepper', 'addresses'] + responses: + 200: + description: + The associations for any matched `addresses`. + examples: + application/json: { + "mappings": { + "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org" + } + } + schema: + type: object + properties: + mappings: + type: object + description: |- + Any applicable mappings of `addresses` to Matrix User IDs. Addresses + which do not have associations will not be included, which can make + this property be an empty object. + title: AssociatedMappings + additionalProperties: + type: string + required: ['mappings'] + 400: + description: + The client's request was invalid in some way. One possible problem could + be the `pepper` being invalid after the server has rotated it - this is + presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make + a call to `/hash_details` to get a new pepper in this scenario, being + careful to avoid retry loops. + + `M_INVALID_PARAM` can also be returned to indicate the client supplied + an `algorithm` that is unknown to the server. + examples: + application/json: { + "errcode": "M_INVALID_PEPPER", + "error": "Unknown or invalid pepper - has it been rotated?" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml new file mode 100644 index 000000000..72680064b --- /dev/null +++ b/data/api/identity/v2_phone_associations.yaml @@ -0,0 +1,218 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Phone Number Associations API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/validate/msisdn/requestToken": + post: + summary: Request a token for validating a phone number. + description: |- + Create a session for validating a phone number. + + The identity server will send an SMS message containing a token. If + that token is presented to the identity server in the future, it + indicates that that user was able to read the SMS for that phone + number, and so we validate ownership of the phone number. + + Note that homeservers offer APIs that proxy this API, adding + additional behaviour on top, for example, + `/register/msisdn/requestToken` is designed specifically for use when + registering an account and therefore will inform the user if the phone + number given is already registered on the server. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: msisdnRequestTokenV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + $ref: "definitions/request_msisdn_validation.yaml" + responses: + 200: + description: Session created. + schema: + $ref: "definitions/sid.yaml" + 400: + description: | + An error ocurred. Some possible errors are: + + - `M_INVALID_ADDRESS`: The phone number provided was invalid. + - `M_SEND_ERROR`: The validation SMS could not be sent. + - `M_DESTINATION_REJECTED`: The identity server cannot deliver an + SMS to the provided country or region. + examples: + application/json: { + "errcode": "M_INVALID_ADDRESS", + "error": "The phone number is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/validate/msisdn/submitToken": + post: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the phone number is considered to + have been validated. This does not publish any information publicly, or + associate the phone number address with any Matrix user + ID. Specifically, calls to `/lookup` will not show a binding. + + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + `application/x-form-www-urlencoded` data. However, this usage is + deprecated. + operationId: msisdnSubmitTokenPostV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and sent to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: ['success'] + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + get: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + `requestToken` call, ownership of the phone number address is + considered to have been validated. This does not publish any + information publicly, or associate the phone number with any Matrix + user ID. Specifically, calls to `/lookup` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: msisdnSubmitTokenGetV2 + security: + - accessToken: [] + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the `requestToken` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the `requestToken` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the `requestToken` call and sent to the user. + x-example: atoken + responses: + 200: + description: Phone number is validated. + "3xx": + description: |- + Phone number address is validated, and the `next_link` parameter + was provided to the `requestToken` call. The user must be + redirected to the URL provided by the `next_link` parameter. + "4xx": + description: + Validation failed. + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/v2_ping.yaml b/data/api/identity/v2_ping.yaml new file mode 100644 index 000000000..61f5d35b2 --- /dev/null +++ b/data/api/identity/v2_ping.yaml @@ -0,0 +1,46 @@ +# Copyright 2018 Kamax Sàrl +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: "2.0" +info: + title: "Matrix Identity Service Ping API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity +produces: + - application/json +paths: + "/v2": + get: + summary: Checks that an identity server is available at this API endpoint. + description: |- + Checks that an identity server is available at this API endpoint. + + To discover that an identity server is available at a specific URL, + this endpoint can be queried and will return an empty object. + + This is primarly used for auto-discovery and health check purposes + by entities acting as a client for the identity server. + operationId: pingV2 + responses: + 200: + description: An identity server is ready to serve requests. + examples: + application/json: {} + schema: + type: object diff --git a/data/api/identity/v2_pubkey.yaml b/data/api/identity/v2_pubkey.yaml new file mode 100644 index 000000000..68facd681 --- /dev/null +++ b/data/api/identity/v2_pubkey.yaml @@ -0,0 +1,127 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Public Key API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +paths: + "/pubkey/{keyId}": + get: + summary: Get a public key. + description: |- + Get the public key for the passed key ID. + operationId: getPubKeyV2 + parameters: + - in: path + type: string + name: keyId + required: true + description: |- + The ID of the key. This should take the form algorithm:identifier + where algorithm identifies the signing algorithm, and the identifier + is an opaque string. + x-example: "ed25519:0" + responses: + 200: + description: + The public key exists. + examples: + application/json: { + "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + } + schema: + type: object + properties: + public_key: + type: string + description: Unpadded Base64 encoded public key. + required: ['public_key'] + 404: + description: + The public key was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The public key was not found" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/pubkey/isvalid": + get: + summary: Check whether a long-term public key is valid. + description: |- + Check whether a long-term public key is valid. The response should always + be the same, provided the key exists. + operationId: isPubKeyValidV2 + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: ['valid'] + "/pubkey/ephemeral/isvalid": + get: + summary: Check whether a short-term public key is valid. + description: |- + Check whether a short-term public key is valid. + operationId: isEphemeralPubKeyValidV2 + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: ['valid'] diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml new file mode 100644 index 000000000..c3fbc7ca0 --- /dev/null +++ b/data/api/identity/v2_store_invite.yaml @@ -0,0 +1,176 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Store Invitations API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/store-invite": + post: + summary: Store pending invitations to a user's 3pid. + description: |- + Store pending invitations to a user's 3pid. + + In addition to the request parameters specified below, an arbitrary + number of other parameters may also be specified. These may be used in + the invite message generation described below. + + The service will generate a random token and an ephemeral key used for + accepting the invite. + + The service also generates a `display_name` for the inviter, which is + a redacted version of `address` which does not leak the full contents + of the `address`. + + The service records persistently all of the above information. + + It also generates an email containing all of this data, sent to the + `address` parameter, notifying them of the invitation. + + Also, the generated ephemeral public key will be listed as valid on + requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`. + + Currently, invites may only be issued for 3pids of the `email` medium. + + Optional fields in the request should be populated to the best of the + server's ability. Identity servers may use these variables when notifying + the `address` of the pending invite for display purposes. + operationId: storeInviteV2 + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + properties: + medium: + type: string + description: The literal string `email`. + example: "email" + address: + type: string + description: The email address of the invited user. + example: "foo@example.com" + room_id: + type: string + description: The Matrix room ID to which the user is invited + example: "!something:example.org" + sender: + type: string + description: The Matrix user ID of the inviting user + example: "@bob:example.com" + room_alias: + type: string + description: |- + The Matrix room alias for the room to which the user is + invited. This should be retrieved from the `m.room.canonical_alias` + state event. + example: "#somewhere:exmaple.org" + room_avatar_url: + type: string + description: |- + The Content URI for the room to which the user is invited. This should + be retrieved from the `m.room.avatar` state event. + example: "mxc://example.org/s0meM3dia" + room_join_rules: + type: string + description: |- + The `join_rule` for the room to which the user is invited. This should + be retrieved from the `m.room.join_rules` state event. + example: "public" + room_name: + type: string + description: |- + The name of the room to which the user is invited. This should be retrieved + from the `m.room.name` state event. + example: "Bob's Emporium of Messages" + sender_display_name: + type: string + description: The display name of the user ID initiating the invite. + example: "Bob Smith" + sender_avatar_url: + type: string + description: The Content URI for the avatar of the user ID initiating the invite. + example: "mxc://example.org/an0th3rM3dia" + required: ["medium", "address", "room_id", "sender"] + responses: + 200: + description: The invitation was stored. + schema: + type: object + properties: + token: + type: string + description: | + The generated token. Must be a string consisting of the + characters `[0-9a-zA-Z.=_-]`. Its length must not exceed + 255 characters and it must not be empty. + public_keys: + type: array + description: | + A list of [server's long-term public key, generated ephemeral + public key]. + items: + type: string + display_name: + type: string + description: The generated (redacted) display_name. + required: ['token', 'public_keys', 'display_name'] + example: + application/json: { + "token": "sometoken", + "public_keys": [ + "serverpublickey", + "ephemeralpublickey" + ], + "display_name": "f...@b..." + } + 400: + description: | + An error has occured. + + If the 3pid is already bound to a Matrix user ID, the error code + will be `M_THREEPID_IN_USE`. If the medium is unsupported, the + error code will be `M_UNRECOGNIZED`. + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "Binding already known", + "mxid": "@alice:example.com" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 403: + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + examples: + application/json: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml new file mode 100644 index 000000000..fcab28b7d --- /dev/null +++ b/data/api/identity/v2_terms.yaml @@ -0,0 +1,149 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Terms of Service API" + version: "2.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/terms": + get: + summary: Gets the terms of service offered by the server. + description: |- + Gets all the terms of service offered by the server. The client is expected + to filter through the terms to determine which terms need acceptance from the + user. Note that this endpoint does not require authentication. + operationId: getTerms + parameters: [] + responses: + 200: + description: |- + The terms of service offered by the server. + examples: + application/json: { + "policies": { + "terms_of_service": { + "version": "2.0", + "en": { + "name": "Terms of Service", + "url": "https://example.org/somewhere/terms-2.0-en.html" + }, + "fr": { + "name": "Conditions d'utilisation", + "url": "https://example.org/somewhere/terms-2.0-fr.html" + } + }, + "privacy_policy": { + "version": "1.2", + "en": { + "name": "Privacy Policy", + "url": "https://example.org/somewhere/privacy-1.2-en.html" + }, + "fr": { + "name": "Politique de confidentialité", + "url": "https://example.org/somewhere/privacy-1.2-fr.html" + } + } + } + } + schema: + type: object + properties: + policies: + type: object + title: Policy Map + description: |- + The policies the server offers. Mapped from arbitrary ID (unused in + this version of the specification) to a Policy Object. + additionalProperties: + type: object + title: Policy Object + description: |- + The policy. Includes a map of language (ISO 639-2) to language-specific + policy information. + properties: + version: + type: string + description: |- + The version for the policy. There are no requirements on what this + might be and could be "alpha", semantically versioned, or arbitrary. + required: ['version'] + # TODO: TravisR - Make this render + additionalProperties: + type: object + title: Internationalised Policy + description: |- + The policy information for the specified language. + properties: + name: + type: string + description: The translated name of the policy. + url: + type: string + description: |- + The URL, which should include the policy ID, version, and language + in it, to be presented to the user as the policy. URLs should have + all three criteria to avoid conflicts when the policy is updated + in the future: for example, if this was "https://example.org/terms.html" + then the server would be unable to update it because the client would + have already added that URL to the `m.accepted_terms` collection. + required: ['name', 'url'] + required: ['policies'] + post: + summary: Indicates acceptance of terms to the server. + description: |- + Called by a client to indicate that the user has accepted/agreed to the included + set of URLs. Servers MUST NOT assume that the client will be sending all previously + accepted URLs and should therefore append the provided URLs to what the server + already knows has been accepted. + + Clients MUST provide the URL of the policy in the language that was presented + to the user. Servers SHOULD consider acceptance of any one language's URL as + acceptance for all other languages of that policy. + + The server should avoid returning `M_TERMS_NOT_SIGNED` because the client + may not be accepting all terms at once. + operationId: agreeToTerms + security: + - accessToken: [] + parameters: + - in: body + name: body + schema: + type: object + properties: + user_accepts: + type: array + items: + type: string + description: The URLs the user is accepting in this request. + example: "https://example.org/somewhere/terms-2.0-en.html" + required: ['user_accepts'] + responses: + 200: + description: |- + The server has considered the user as having accepted the provided URLs. + examples: + application/json: {} + schema: + type: object diff --git a/data/api/push-gateway/push_notifier.yaml b/data/api/push-gateway/push_notifier.yaml new file mode 100644 index 000000000..2f03433bd --- /dev/null +++ b/data/api/push-gateway/push_notifier.yaml @@ -0,0 +1,228 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Push Notification API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/push/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/notify": + post: + summary: Notify a push gateway about an event. + description: |- + This endpoint is invoked by HTTP pushers to notify a push gateway about + an event or update the number of unread notifications a user has. + In the former case it will contain selected information about the event. + In either case it may contain numeric counts of the number of unread + events of different types the user has. The counts may be sent along + with a notification about an event or by themselves. + + Notifications about a particular event will normally cause the user to be + alerted in some way. It is therefore necessary to perform duplicate + suppression for such notifications using the `event_id` field to avoid + retries of this HTTP API causing duplicate alerts. The operation of + updating counts of unread notifications should be idempotent and + therefore do not require duplicate suppression. + + Notifications are sent to the URL configured when the pusher is created. + This means that the HTTP path may be different depending on the push + gateway. + operationId: notify + parameters: + - in: body + name: notification + description: Information about the push notification. + required: true + schema: + type: object + example: { + "notification": { + "event_id": "$3957tyerfgewrf384", + "room_id": "!slw48wfj34rtnrf:example.com", + "type": "m.room.message", + "sender": "@exampleuser:matrix.org", + "sender_display_name": "Major Tom", + "room_name": "Mission Control", + "room_alias": "#exampleroom:matrix.org", + "prio": "high", + "content": { + "msgtype": "m.text", + "body": "I'm floating in a most peculiar way." + }, + "counts": { + "unread" : 2, + "missed_calls": 1 + }, + "devices": [ + { + "app_id": "org.matrix.matrixConsole.ios", + "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", + "pushkey_ts": 12345678, + "data" : {}, + "tweaks": { + "sound": "bing" + } + } + ] + } + } + required: ["notification"] + properties: + notification: + type: object + title: Notification + description: Information about the push notification + required: ["devices"] + properties: + event_id: + type: string + description: |- + The Matrix event ID of the event being notified about. + This is required if the notification is about a + particular Matrix event. It may be omitted for notifications + that only contain updated badge counts. This ID can and + should be used to detect duplicate notification requests. + room_id: + type: string + description: |- + The ID of the room in which this event occurred. + Required if the notification relates to a specific + Matrix event. + type: + type: string + description: |- + The type of the event as in the event's `type` field. + sender: + type: string + description: |- + The sender of the event as in the corresponding event field. + sender_display_name: + type: string + description: |- + The current display name of the sender in the room in which + the event occurred. + room_name: + type: string + description: The name of the room in which the event occurred. + room_alias: + type: string + description: An alias to display for the room in which the event occurred. + user_is_target: + type: boolean + description: |- + This is true if the user receiving the notification is the + subject of a member event (i.e. the `state_key` of the + member event is equal to the user's Matrix ID). + prio: + type: string + enum: ["high", "low"] + description: |- + The priority of the notification. If omitted, `high` is + assumed. This may be used by push gateways to deliver less + time-sensitive notifications in a way that will preserve + battery power on mobile devices. + content: + type: object + title: EventContent + description: |- + The `content` field from the event, if present. The pusher + may omit this if the event had no content or for any other + reason. + counts: + type: object + title: Counts + description: |- + This is a dictionary of the current number of unacknowledged + communications for the recipient user. Counts whose value is + zero should be omitted. + properties: + unread: + type: integer + description: |- + The number of unread messages a user has across all of the + rooms they are a member of. + missed_calls: + type: integer + description: |- + The number of unacknowledged missed calls a user has + across all rooms of which they are a member. + devices: + type: array + title: Devices + description: |- + This is an array of devices that the notification should be sent to. + items: + type: object + title: Device + properties: + app_id: + type: string + description: |- + The `app_id` given when the pusher was created. + pushkey: + type: string + description: The `pushkey` given when the pusher was created. + pushkey_ts: + type: integer + description: |- + The unix timestamp (in seconds) when the + pushkey was last updated. + data: + type: object + title: PusherData + description: |- + A dictionary of additional pusher-specific data. For + 'http' pushers, this is the data dictionary passed in at + pusher creation minus the `url` key. + tweaks: + type: object + title: Tweaks + description: |- + A dictionary of customisations made to the way this + notification is to be presented. These are added by push rules. + required: ['app_id', 'pushkey'] + responses: + 200: + description: A list of rejected push keys. + examples: + application/json: { + "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] + } + schema: + type: object # empty json object + properties: + rejected: + type: array + description: |- + A list of all pushkeys given in the notification request that + are not valid. These could have been rejected by an upstream + gateway because they have expired or have never been valid. + Homeservers must cease sending notification requests for these + pushkeys and remove the associated pushers. It may not + necessarily be the notification in the request that failed: + it could be that a previous notification to the same pushkey + failed. May be empty. + items: + type: string + description: A pushkey that has been rejected. + required: ['rejected'] diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml new file mode 100644 index 000000000..42a0e3bd4 --- /dev/null +++ b/data/api/server-server/backfill.yaml @@ -0,0 +1,143 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Events API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/backfill/{roomId}": + get: + summary: Retrieves the events which precede the given event + description: |- + Retrieves a sliding-window history of previous PDUs that occurred in the given room. + Starting from the PDU ID(s) given in the `v` argument, the PDUs given in `v` and + the PDUs that preceded them are retrieved, up to the total number given by the `limit`. + operationId: backfillRoom + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID to backfill. + required: true + x-example: "!SomeRoom:matrix.org" + - in: query + name: v + type: array + items: + type: string + description: The event IDs to backfill from. + required: true + x-example: ["$abc123:matrix.org"] + - in: query + name: limit + type: integer + description: The maximum number of PDUs to retrieve, including the given events. + required: true + x-example: 2 + responses: + 200: + description: |- + A transaction containing the PDUs that preceded the given event(s), including the given + event(s), up to the given limit. + + **Note:** + Though the PDU definitions require that `prev_events` and `auth_events` be limited + in number, the response of backfill MUST NOT be validated on these specific restrictions. + + Due to historical reasons, it is possible that events which were previously accepted + would now be rejected by these limitations. The events should be rejected per usual by + the `/send`, `/get_missing_events`, and remaining endpoints. + schema: + $ref: "definitions/unlimited_pdu_transaction.yaml" + "/get_missing_events/{roomId}": + post: + summary: Retrieves events that the sender is missing + description: |- + Retrieves previous events that the sender is missing. This is done by doing a breadth-first + walk of the `prev_events` for the `latest_events`, ignoring any events in `earliest_events` + and stopping at the `limit`. + operationId: getMissingPreviousEvents + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID to search in. + required: true + x-example: "!SomeRoom:matrix.org" + - in: body + name: body + schema: + type: object + properties: + limit: + type: integer + description: The maximum number of events to retrieve. Defaults to 10. + example: 10 + min_depth: + type: integer + description: The minimum depth of events to retrieve. Defaults to 0. + example: 0 + earliest_events: + type: array + description: |- + The latest event IDs that the sender already has. These are skipped when retrieving + the previous events of `latest_events`. + items: + type: string + example: ["$missing_event:example.org"] + latest_events: + type: array + description: The event IDs to retrieve the previous events for. + items: + type: string + example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"] + required: ['earliest_events', 'latest_events'] + responses: + 200: + description: |- + The previous events for `latest_events`, excluding any `earliest_events`, up to the + provided `limit`. + schema: + type: object + properties: + events: + type: array + description: |- + The missing events. The event format varies depending on the room version - check + the [room version specification](/#room-versions) for precise event formats. + items: + type: object + title: PDU + required: ['events'] + examples: + application/json: { + "events": [ + {"$ref": "examples/minimal_pdu.json"} + ] + } diff --git a/data/api/server-server/definitions/edu.yaml b/data/api/server-server/definitions/edu.yaml new file mode 100644 index 000000000..0e4edcc65 --- /dev/null +++ b/data/api/server-server/definitions/edu.yaml @@ -0,0 +1,28 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: Ephemeral Data Unit +description: An ephemeral data unit. +example: + $ref: "../examples/edu.json" +properties: + edu_type: + type: string + description: The type of ephemeral message. + example: "m.presence" + content: + type: object + description: The content of the ephemeral message. +required: ['edu_type', 'content'] \ No newline at end of file diff --git a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml new file mode 100644 index 000000000..2a9d9b602 --- /dev/null +++ b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml @@ -0,0 +1,91 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: m.device_list_update +description: |- + An EDU that lets servers push details to each other when one of their users + adds a new device to their account, required for E2E encryption to correctly + target the current set of devices for a given user. This event will also be + sent when an existing device gets a new cross-signing signature. + +# FIXME: It's very unclear why we have this API surface for synchronising +# device lists, rather than just using a room (which could also be used for +# profile info, etc). But documenting what we have for now... + +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: enum + enum: ['m.device_list_update'] + description: The string `m.device_list_update`. + example: "m.device_list_update" + content: + type: object + description: The description of the device whose details has changed. + title: Device List Update + properties: + user_id: + type: string + description: The user ID who owns this device. + example: "@john:example.com" + device_id: + type: string + description: The ID of the device whose details are changing. + example: "QBUAZIFURK" + device_display_name: + type: string + description: |- + The public human-readable name of this device. Will be absent + if the device has no name. + example: "Mobile" + stream_id: + type: integer + description: |- + An ID sent by the server for this update, unique for a given + user_id. Used to identify any gaps in the sequence of `m.device_list_update` + EDUs broadcast by a server. + example: 6 + prev_id: + type: array + description: |- + The stream_ids of any prior m.device_list_update EDUs sent for this user + which have not been referred to already in an EDU's prev_id field. If the + receiving server does not recognise any of the prev_ids, it means an EDU + has been lost and the server should query a snapshot of the device list + via `/user/keys/query` in order to correctly interpret future `m.device_list_update` + EDUs. May be missing or empty for the first EDU in a sequence. + items: + type: integer + description: |- + The stream_id of a prior EDU in this sequence which has not been referred + to already in an EDU's prev_id field. + example: 5 + deleted: + type: boolean + description: |- + True if the server is announcing that this device has been deleted. + example: false + keys: + description: |- + The updated identity keys (if any) for this device. May be absent if the + device has no E2E keys defined. + $ref: ../../../client-server/definitions/device_keys.yaml + required: + - user_id + - device_id + - stream_id diff --git a/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml new file mode 100644 index 000000000..916922cf3 --- /dev/null +++ b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -0,0 +1,75 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: m.direct_to_device +description: |- + An EDU that lets servers push send events directly to a specific device on + a remote server - for instance, to maintain an Olm E2E encrypted message channel + between a local and remote device. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: enum + enum: ['m.direct_to_device'] + description: The string `m.direct_to_device`. + example: "m.direct_to_device" + content: + type: object + description: The description of the direct-to-device message. + title: To Device Message + properties: + sender: + type: string + description: User ID of the sender. + example: "john@example.com" + type: + type: string + description: Event type for the message. + example: "m.room_key_request" + message_id: + type: string + description: Unique ID for the message, used for idempotence. Arbitrary + utf8 string, of maximum length 32 codepoints. + example: "hiezohf6Hoo7kaev" + messages: + type: object + description: |- + The contents of the messages to be sent. These are arranged in + a map of user IDs to a map of device IDs to message bodies. + The device ID may also be `*`, meaning all known devices for the user. + additionalProperties: + type: object + title: User Devices + additionalProperties: + type: object + title: Device Message Contents + properties: {} + example: { + "alice@example.org": { + "IWHQUZUIAH": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." + } + } + } + required: + - sender + - type + - message_id + - messages diff --git a/data/api/server-server/definitions/event-schemas/m.presence.yaml b/data/api/server-server/definitions/event-schemas/m.presence.yaml new file mode 100644 index 000000000..09d5d0d2d --- /dev/null +++ b/data/api/server-server/definitions/event-schemas/m.presence.yaml @@ -0,0 +1,71 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: m.presence +description: |- + An EDU representing presence updates for users of the sending homeserver. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: enum + enum: ['m.presence'] + description: The string `m.presence` + example: "m.presence" + content: + type: object + description: The presence updates and requests. + title: Presence Update + properties: + push: + type: array + description: |- + A list of presence updates that the receiving server is likely + to be interested in. + items: + type: object + title: User Presence Update + properties: + user_id: + type: string + description: The user ID this presence EDU is for. + example: "@john:matrix.org" + presence: + type: enum + enum: ['offline', 'unavailable', 'online'] + description: The presence of the user. + example: "online" + status_msg: + type: string + description: An optional description to accompany the presence. + example: "Making cupcakes" + last_active_ago: + type: integer + format: int64 + description: |- + The number of milliseconds that have elapsed since the user + last did something. + example: 5000 + currently_active: + type: boolean + description: |- + True if the user is likely to be interacting with their + client. This may be indicated by the user having a + `last_active_ago` within the last few minutes. Defaults + to false. + example: true + required: ['user_id', 'presence', 'last_active_ago'] + required: ['push'] diff --git a/data/api/server-server/definitions/event-schemas/m.receipt.yaml b/data/api/server-server/definitions/event-schemas/m.receipt.yaml new file mode 100644 index 000000000..335e7c27d --- /dev/null +++ b/data/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -0,0 +1,82 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: m.receipt +description: |- + An EDU representing receipt updates for users of the sending homeserver. + When receiving receipts, the server should only update entries that are + listed in the EDU. Receipts previously received that do not appear in the + EDU should not be removed or otherwise manipulated. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: enum + enum: ['m.receipt'] + description: The string `m.receipt` + example: "m.receipt" + content: + type: object + description: |- + Receipts for a particular room. The string key is the room ID for + which the receipts under it belong. + additionalProperties: + type: object + title: Room Receipts + properties: + # We strongly define the receipt type to help spec future ones later + # on. At that point, m.read can become optional (maybe). + "m.read": + type: object + description: Read receipts for users in the room. + title: User Read Receipt + properties: + event_ids: + type: array + description: |- + The extremity event IDs that the user has read up to. + minItems: 1 + maxItems: 1 + items: + type: string + example: ['$read_this_event:matrix.org'] + data: + type: object + description: Metadata for the read receipt. + title: Read Receipt Metadata + properties: + ts: + type: integer + format: int64 + description: |- + A POSIX timestamp in milliseconds for when the user read + the event specified in the read receipt. + example: 1533358089009 + required: ['ts'] + required: ['event_ids', 'data'] + required: ['m.read'] + example: { + "!some_room:example.org": { + "m.read": { + "@john:matrix.org": { + "event_ids": ["$read_this_event:matrix.org"], + "data": { + "ts": 1533358089009 + } + } + } + } + } diff --git a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml new file mode 100644 index 000000000..c84cd6c31 --- /dev/null +++ b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml @@ -0,0 +1,64 @@ +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: m.signing_key_update +description: |- + An EDU that lets servers push details to each other when one of their users + updates their cross-signing keys. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: enum + enum: ['m.signing_key_update'] + description: The string `m.signing_update`. + example: "m.signing_key_update" + content: + type: object + description: The updated signing keys. + title: Signing Key Update + properties: + user_id: + type: string + description: The user ID whose cross-signing keys have changed. + example: "@alice:example.com" + master_key: + type: object + $ref: ../../../client-server/definitions/cross_signing_key.yaml + example: { + "user_id": "@alice:example.com", + "usage": ["master"], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key", + } + } + self_signing_key: + type: object + $ref: ../../../client-server/definitions/cross_signing_key.yaml + example: { + "user_id": "@alice:example.com", + "usage": ["self_signing"], + "keys": { + "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+self+signing+key" + } + } + } + required: + - user_id diff --git a/data/api/server-server/definitions/event-schemas/m.typing.yaml b/data/api/server-server/definitions/event-schemas/m.typing.yaml new file mode 100644 index 000000000..7f23bae14 --- /dev/null +++ b/data/api/server-server/definitions/event-schemas/m.typing.yaml @@ -0,0 +1,46 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: m.typing +description: A typing notification EDU for a user in a room. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: enum + enum: ['m.typing'] + description: The string `m.typing` + example: "m.typing" + content: + type: object + description: The typing notification. + title: Typing Notification + properties: + room_id: + type: string + description: |- + The room where the user's typing status has been updated. + example: "!somewhere:matrix.org" + user_id: + type: string + description: |- + The user ID that has had their typing status changed. + example: "@john:matrix.org" + typing: + type: boolean + description: Whether the user is typing in the room or not. + example: true + required: ['room_id', 'user_id', 'typing'] diff --git a/data/api/server-server/definitions/invite_event.yaml b/data/api/server-server/definitions/invite_event.yaml new file mode 100644 index 000000000..416eb709a --- /dev/null +++ b/data/api/server-server/definitions/invite_event.yaml @@ -0,0 +1,63 @@ +# Copyright 2018-2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: InviteEvent +description: |- + An invite event. Note that events have a different format depending on the + room version - check the [room version specification](/#room-versions) for precise event formats. +allOf: + - type: object + properties: + sender: + type: string + description: |- + The matrix ID of the user who sent the original `m.room.third_party_invite`. + example: "@someone:example.org" + origin: + type: string + description: The name of the inviting homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the inviting homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: "m.room.member" + state_key: + type: string + description: The user ID of the invited member. + example: "@joe:elsewhere.com" + content: + type: object + title: Membership Event Content + description: |- + The content of the event, matching what is available in the + [Client-Server API](/client-server-api/). Must include a `membership` of `invite`. + example: {"membership": "invite"} + properties: + membership: + type: string + description: The value `invite`. + example: "invite" + required: ['membership'] + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml new file mode 100644 index 000000000..3676ae521 --- /dev/null +++ b/data/api/server-server/definitions/keys.yaml @@ -0,0 +1,100 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Server Keys +description: Server keys +example: + $ref: "../examples/server_key.json" +properties: + server_name: + type: string + description: DNS name of the homeserver. + example: "example.org" + verify_keys: + type: object + description: |- + Public keys of the homeserver for verifying digital signatures. + + The object's key is the algorithm and version combined (`ed25519` being the + algorithm and `abc123` being the version in the example below). Together, + this forms the Key ID. The version must have characters matching the regular + expression `[a-zA-Z0-9_]`. + additionalProperties: + type: object + title: Verify Key + example: { + "ed25519:abc123": { + "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA" + } + } + properties: + key: + type: string + description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key. + example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA" + required: ["key"] + old_verify_keys: + type: object + description: |- + The public keys that the server used to use and when it stopped using them. + + The object's key is the algorithm and version combined (`ed25519` being the + algorithm and `0ldK3y` being the version in the example below). Together, + this forms the Key ID. The version must have characters matching the regular + expression `[a-zA-Z0-9_]`. + additionalProperties: + type: object + title: Old Verify Key + example: { + "ed25519:0ldK3y": { + "expired_ts": 1532645052628, + "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg" + } + } + properties: + expired_ts: + type: integer + format: int64 + description: POSIX timestamp in milliseconds for when this key expired. + example: 1532645052628 + key: + type: string + description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key. + example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg" + required: ["expired_ts", "key"] + signatures: + type: object + description: |- + Digital signatures for this object signed using the `verify_keys`. + + The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). + title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string + valid_until_ts: + type: integer + format: int64 + description: |- + POSIX timestamp when the list of valid keys should be refreshed. This field MUST + be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST + be considered invalid, depending on the [room version specification](/#room-versions). + + Servers MUST use the lesser of this field and 7 days into the future when + determining if a key is valid. This is to avoid a situation where an attacker + publishes a key which is valid for a significant amount of time without a way + for the homeserver owner to revoke it. + example: 1052262000000 +required: ["server_name", "verify_keys"] diff --git a/data/api/server-server/definitions/keys_query_response.yaml b/data/api/server-server/definitions/keys_query_response.yaml new file mode 100644 index 000000000..52ad506ca --- /dev/null +++ b/data/api/server-server/definitions/keys_query_response.yaml @@ -0,0 +1,27 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +description: Server keys +example: { + "server_keys": [{ + $ref: "../examples/server_key_notary_signed.json" + }] +} +properties: + server_keys: + type: array + title: Server Keys + description: The queried server's keys, signed by the notary server. + items: + $ref: "keys.yaml" diff --git a/data/api/server-server/definitions/pdu.yaml b/data/api/server-server/definitions/pdu.yaml new file mode 100644 index 000000000..d87db1a30 --- /dev/null +++ b/data/api/server-server/definitions/pdu.yaml @@ -0,0 +1,53 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Persistent Data Unit +description: A persistent data unit (event) for room versions 1 and 2. +example: + $ref: "../examples/pdu.json" +allOf: + - $ref: "unsigned_pdu.yaml" + - type: object + properties: + hashes: + type: object + title: Event Hash + description: |- + Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). + example: { + "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" + } + properties: + sha256: + type: string + description: The hash. + example: ThisHashCoversAllFieldsInCaseThisIsRedacted + required: ['sha256'] + signatures: + type: object + description: |- + Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). + example: { + "example.com": { + "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent" + } + } + additionalProperties: + type: object + title: Server Signatures + additionalProperties: + type: string + required: + - hashes + - signatures diff --git a/data/api/server-server/definitions/pdu_v3.yaml b/data/api/server-server/definitions/pdu_v3.yaml new file mode 100644 index 000000000..32d05b36f --- /dev/null +++ b/data/api/server-server/definitions/pdu_v3.yaml @@ -0,0 +1,83 @@ +# Copyright 2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Persistent Data Unit +description: A persistent data unit (event) for room version 3 and beyond. +example: + $ref: "../examples/pdu_v3.json" +allOf: + - $ref: "unsigned_pdu_base.yaml" + - type: object + properties: + redacts: + type: string + description: For redaction events, the ID of the event being redacted. + example: "$def/456+oldevent" + auth_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the authorization events that would + allow this event to be in the room. + + Must contain less than or equal to 10 events. Note that if the relevant + auth event selection rules are used, this restriction should never be + encountered. + example: ["$base64EncodedHash", "$AnotherEvent"] + prev_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the most recent events in the room + that the homeserver was aware of when it made this event. + + Must contain less than or equal to 20 events. + example: ["$base64EncodedHash", "$AnotherEvent"] + hashes: + type: object + title: Event Hash + description: |- + Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). + example: { + "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" + } + properties: + sha256: + type: string + description: The hash. + example: ThisHashCoversAllFieldsInCaseThisIsRedacted + required: ['sha256'] + signatures: + type: object + description: |- + Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). + example: { + "example.com": { + "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent" + } + } + additionalProperties: + type: object + title: Server Signatures + additionalProperties: + type: string + required: + - auth_events + - prev_events + - hashes + - signatures diff --git a/data/api/server-server/definitions/pdu_v4.yaml b/data/api/server-server/definitions/pdu_v4.yaml new file mode 100644 index 000000000..d22956c69 --- /dev/null +++ b/data/api/server-server/definitions/pdu_v4.yaml @@ -0,0 +1,53 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Persistent Data Unit +description: A persistent data unit (event) for room version 4 and beyond. +example: + $ref: "../examples/pdu_v4.json" +allOf: + - $ref: "pdu_v3.yaml" + - type: object + properties: + redacts: + type: string + description: For redaction events, the ID of the event being redacted. + example: "$def_456-oldevent" + auth_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the authorization events that would + allow this event to be in the room. + + Must contain less than or equal to 10 events. Note that if the relevant + auth event selection rules are used, this restriction should never be + encountered. + example: ["$URLsafe-base64EncodedHash", "$Another_Event"] + prev_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the most recent events in the room + that the homeserver was aware of when it made this event. + + Must contain less than or equal to 20 events. + example: ["$URLsafe-base64EncodedHash", "$Another_Event"] + required: + - auth_events + - prev_events diff --git a/data/api/server-server/definitions/security.yaml b/data/api/server-server/definitions/security.yaml new file mode 100644 index 000000000..822b3fdfc --- /dev/null +++ b/data/api/server-server/definitions/security.yaml @@ -0,0 +1,19 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +signedRequest: + type: apiKey + description: |- + The `Authorization` header defined in the [Authentication](/server-server-api/#authentication) section. + name: Authorization + in: header diff --git a/data/api/server-server/definitions/send_join_response.yaml b/data/api/server-server/definitions/send_join_response.yaml new file mode 100644 index 000000000..0aad17586 --- /dev/null +++ b/data/api/server-server/definitions/send_join_response.yaml @@ -0,0 +1,58 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Room State +description: The state for the room. +properties: + origin: + type: string + description: The resident server's DNS name. + auth_chain: + type: array + description: |- + The auth chain for the entire current room state prior to the join event. + + Note that events have a different format depending on the room version - check the + [room version specification](/#room-versions) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending + on the room version - check the [room version specification](/#room-versions) for precise event formats. + schema: + type: object + properties: [] + example: + $ref: "../examples/minimal_pdu.json" + state: + type: array + description: |- + The resolved current room state prior to the join event. + + The event format varies depending on the room version - check the [room version specification](/#room-versions) + for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending + on the room version - check the [room version specification](/#room-versions) for precise event formats. + schema: + type: object + properties: [] + example: + $ref: "../examples/minimal_pdu.json" +required: ["auth_chain", "state", "origin"] diff --git a/data/api/server-server/definitions/single_pdu_transaction.yaml b/data/api/server-server/definitions/single_pdu_transaction.yaml new file mode 100644 index 000000000..3c406e8fb --- /dev/null +++ b/data/api/server-server/definitions/single_pdu_transaction.yaml @@ -0,0 +1,32 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: + - $ref: "transaction.yaml" +properties: + pdus: + type: array + description: |- + A single PDU. Note that events have a different format depending on the room + version - check the [room version specification](/#room-versions) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending + on the room version - check the [room version specification](/#room-versions) for precise event formats. + properties: [] + example: + $ref: "../examples/minimal_pdu.json" +required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/data/api/server-server/definitions/transaction.yaml b/data/api/server-server/definitions/transaction.yaml new file mode 100644 index 000000000..4d9f3ae4d --- /dev/null +++ b/data/api/server-server/definitions/transaction.yaml @@ -0,0 +1,47 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Transaction +description: Transaction +example: + $ref: "../examples/transaction.json" +properties: + origin: + type: string + description: |- + The `server_name` of the homeserver sending this transaction. + example: "example.org" + origin_server_ts: + type: integer + format: int64 + description: |- + POSIX timestamp in milliseconds on originating homeserver when this + transaction started. + example: 1532991320875 + pdus: + type: array + description: |- + List of persistent updates to rooms. Must not include more than 50 PDUs. Note that + events have a different format depending on the room version - check the + [room version specification](/#room-versions) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending + on the room version - check the [room version specification](/#room-versions) for precise event formats. + properties: [] + example: + $ref: "../examples/minimal_pdu.json" +required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/data/api/server-server/definitions/unlimited_pdu_transaction.yaml b/data/api/server-server/definitions/unlimited_pdu_transaction.yaml new file mode 100644 index 000000000..bfa29609f --- /dev/null +++ b/data/api/server-server/definitions/unlimited_pdu_transaction.yaml @@ -0,0 +1,33 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: + - $ref: "transaction.yaml" +properties: + pdus: + type: array + description: |- + List of persistent updates to rooms. Note that events have a different format + depending on the room version - check the [room version specification](/#room-versions) for + precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending + on the room version - check the [room version specification](/#room-versions) for precise event formats. + properties: [] + example: + $ref: "../examples/minimal_pdu.json" +required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/data/api/server-server/definitions/unsigned_pdu.yaml b/data/api/server-server/definitions/unsigned_pdu.yaml new file mode 100644 index 000000000..a27a21cde --- /dev/null +++ b/data/api/server-server/definitions/unsigned_pdu.yaml @@ -0,0 +1,28 @@ +# Copyright 2018-2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Unsigned Persistent Data Unit +description: An unsigned persistent data unit (event) +example: + $ref: "../examples/unsigned_pdu.json" +allOf: + - $ref: "unsigned_pdu_base.yaml" + - type: object + properties: + event_id: + type: string + description: The event ID for the PDU. + example: "$a4ecee13e2accdadf56c1025:example.com" + required: + - event_id diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml new file mode 100644 index 000000000..dae148a18 --- /dev/null +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -0,0 +1,157 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Unsigned Persistent Data Unit +description: An unsigned persistent data unit (event) +example: + $ref: "../examples/unsigned_pdu_base.json" +properties: + room_id: + type: string + description: Room identifier. + example: "!abc123:matrix.org" + sender: + type: string + description: The ID of the user sending the event. + example: "@someone:matrix.org" + origin: + type: string + description: The `server_name` of the homeserver that created this event. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: Timestamp in milliseconds on origin homeserver when this event was created. + example: 1234567890 + type: + type: string + description: Event type + example: "m.room.message" + state_key: + type: string + description: |- + If this key is present, the event is a state event, and it will replace previous events + with the same `type` and `state_key` in the room state. + example: "my_key" + content: + type: object + description: The content of the event. + example: {"key": "value"} + prev_events: + type: array + description: |- + Event IDs and reference hashes for the most recent events in the room + that the homeserver was aware of when it made this event. + + Must contain less than or equal to 20 events. + items: + type: array + maxItems: 2 + minItems: 2 + items: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^63 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12 + auth_events: + type: array + description: |- + Event IDs and reference hashes for the authorization events that would + allow this event to be in the room. + + Must contain less than or equal to 10 events. Note that if the relevant + auth event selection rules are used, this restriction should never be + encountered. + items: + type: array + maxItems: 2 + minItems: 2 + items: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] + redacts: + type: string + description: For redaction events, the ID of the event being redacted. + example: "$def456:matrix.org" + unsigned: + type: object + title: UnsignedData + description: |- + Additional data added by the origin server but not covered by the `signatures`. More + keys than those defined here may be used. + example: {"key": "value"} + properties: + age: + type: integer + description: The number of milliseconds that have passed since this message was sent. + example: 4612 + replaces_state: + type: string + description: The event ID of the state event this event replaces. + example: "$state_event:example.org" + prev_sender: + type: string + description: The sender of the replaced state event. + example: "@someone:example.org" + prev_content: + type: object + description: The content of the replaced state event. + example: { + "membership": "join", + "displayname": "Bob" + } + redacted_because: + type: string + description: A reason for why the event was redacted. + example: "Inappropriate content" +required: + - event_id + - room_id + - sender + - origin + - origin_server_ts + - type + - content + - prev_events + - depth + - auth_events diff --git a/data/api/server-server/event_auth.yaml b/data/api/server-server/event_auth.yaml new file mode 100644 index 000000000..0d9fdec1c --- /dev/null +++ b/data/api/server-server/event_auth.yaml @@ -0,0 +1,74 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Event Authorization API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/event_auth/{roomId}/{eventId}": + get: + summary: Get the auth chain for a given event + description: |- + Retrieves the complete auth chain for a given event. + operationId: getEventAuth + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID to get the auth chain for. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID to get the auth chain of. + required: true + x-example: "$helloworld:example.org" + responses: + 200: + description: The auth chain for the event. + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The full set of authorization events that make up the state of + the room, and their authorization events, recursively. Note that + events have a different format depending on the room version - + check the [room version specification](/#room-versions) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format + varies depending on the room version - check the [room version specification](/#room-versions) + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" + required: ['auth_chain'] diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml new file mode 100644 index 000000000..51405d1ce --- /dev/null +++ b/data/api/server-server/events.yaml @@ -0,0 +1,159 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Events API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/state/{roomId}": + get: + summary: Get all the state of a given room + description: |- + Retrieves a snapshot of a room's state at a given event. + operationId: getRoomState + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID to get state for. + required: true + x-example: "!abc123:matrix.org" + - in: query + name: event_id + type: string + description: An event ID in the room to retrieve the state at. + required: true + x-example: "$helloworld:matrix.org" + responses: + 200: + description: |- + The fully resolved state for the room, prior to considering any state + changes induced by the requested event. Includes the authorization + chain for the events. + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The full set of authorization events that make up the state + of the room, and their authorization events, recursively. Note that + events have a different format depending on the room version - + check the [room version specification](/#room-versions) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format + varies depending on the room version - check the [room version specification](/#room-versions) + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" + pdus: + type: array + description: |- + The fully resolved state of the room at the given event. Note that + events have a different format depending on the room version - + check the [room version specification](/#room-versions) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format + varies depending on the room version - check the [room version specification](/#room-versions) + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" + required: ['auth_chain', 'pdus'] + "/state_ids/{roomId}": + get: + summary: Get all the state event IDs of a given room + description: |- + Retrieves a snapshot of a room's state at a given event, in the form of + event IDs. This performs the same function as calling `/state/{roomId}`, + however this returns just the event IDs rather than the full events. + operationId: getRoomStateIds + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID to get state for. + required: true + x-example: "!abc123:matrix.org" + - in: query + name: event_id + type: string + description: An event ID in the room to retrieve the state at. + required: true + x-example: "$helloworld:matrix.org" + responses: + 200: + description: |- + The fully resolved state for the room, prior to considering any state + changes induced by the requested event. Includes the authorization + chain for the events. + schema: + type: object + properties: + auth_chain_ids: + type: array + description: |- + The full set of authorization events that make up the state + of the room, and their authorization events, recursively. + items: + type: string + example: ["$an_event:example.org"] + pdu_ids: + type: array + description: |- + The fully resolved state of the room at the given event. + items: + type: string + example: ["$an_event:example.org"] + required: ['auth_chain_ids', 'pdu_ids'] + "/event/{eventId}": + get: + summary: Get a single event + description: |- + Retrieves a single event. + operationId: getEvent + security: + - signedRequest: [] + parameters: + - in: path + name: eventId + type: string + description: The event ID to get. + required: true + x-example: "$abc123:matrix.org" + responses: + 200: + description: A transaction containing a single PDU which is the event requested. + schema: + $ref: "definitions/single_pdu_transaction.yaml" diff --git a/data/api/server-server/examples/edu.json b/data/api/server-server/examples/edu.json new file mode 100644 index 000000000..f5a58e219 --- /dev/null +++ b/data/api/server-server/examples/edu.json @@ -0,0 +1,6 @@ +{ + "edu_type": "m.presence", + "content": { + "key": "value" + } +} \ No newline at end of file diff --git a/data/api/server-server/examples/minimal_pdu.json b/data/api/server-server/examples/minimal_pdu.json new file mode 100644 index 000000000..f8b8efc35 --- /dev/null +++ b/data/api/server-server/examples/minimal_pdu.json @@ -0,0 +1,7 @@ +{ + "type": "m.room.minimal_pdu", + "room_id": "!somewhere:example.org", + "content": { + "see_room_version_spec": "The event format changes depending on the room version." + } +} diff --git a/data/api/server-server/examples/pdu.json b/data/api/server-server/examples/pdu.json new file mode 100644 index 000000000..81981b23c --- /dev/null +++ b/data/api/server-server/examples/pdu.json @@ -0,0 +1,11 @@ +{ + "$ref": "unsigned_pdu.json", + "hashes": { + "sha256": "thishashcoversallfieldsincasethisisredacted" + }, + "signatures": { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } + } +} \ No newline at end of file diff --git a/data/api/server-server/examples/pdu_v3.json b/data/api/server-server/examples/pdu_v3.json new file mode 100644 index 000000000..acffdf266 --- /dev/null +++ b/data/api/server-server/examples/pdu_v3.json @@ -0,0 +1,20 @@ +{ + "$ref": "unsigned_pdu_base.json", + "hashes": { + "sha256": "thishashcoversallfieldsincasethisisredacted" + }, + "signatures": { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } + }, + "auth_events": [ + "$base64encodedeventid", + "$adifferenteventid" + ], + "prev_events": [ + "$base64encodedeventid", + "$adifferenteventid" + ], + "redacts": "$some/old+event" +} diff --git a/data/api/server-server/examples/pdu_v4.json b/data/api/server-server/examples/pdu_v4.json new file mode 100644 index 000000000..3c2f0e220 --- /dev/null +++ b/data/api/server-server/examples/pdu_v4.json @@ -0,0 +1,12 @@ +{ + "$ref": "pdu_v3.json", + "auth_events": [ + "$urlsafe_base64_encoded_eventid", + "$a-different-event-id" + ], + "prev_events": [ + "$urlsafe_base64_encoded_eventid", + "$a-different-event-id" + ], + "redacts": "$some-old_event" +} diff --git a/data/api/server-server/examples/server_key.json b/data/api/server-server/examples/server_key.json new file mode 100644 index 000000000..ffdfcb5a5 --- /dev/null +++ b/data/api/server-server/examples/server_key.json @@ -0,0 +1,20 @@ +{ + "server_name": "example.org", + "verify_keys": { + "ed25519:abc123": { + "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA" + } + }, + "old_verify_keys": { + "ed25519:0ldk3y": { + "expired_ts": 1532645052628, + "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg" + } + }, + "signatures": { + "example.org": { + "ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU" + } + }, + "valid_until_ts": 1652262000000 +} diff --git a/data/api/server-server/examples/server_key_notary_signed.json b/data/api/server-server/examples/server_key_notary_signed.json new file mode 100644 index 000000000..d3a461ba6 --- /dev/null +++ b/data/api/server-server/examples/server_key_notary_signed.json @@ -0,0 +1,11 @@ +{ + "$ref": "server_key.json", + "signatures": { + "example.org": { + "ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU" + }, + "notary.server.com": { + "ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ" + } + } +} \ No newline at end of file diff --git a/data/api/server-server/examples/transaction.json b/data/api/server-server/examples/transaction.json new file mode 100644 index 000000000..bbc661d99 --- /dev/null +++ b/data/api/server-server/examples/transaction.json @@ -0,0 +1,7 @@ +{ + "origin": "matrix.org", + "origin_server_ts": 1234567890, + "pdus": [{ + "$ref": "minimal_pdu.json" + }] +} diff --git a/data/api/server-server/examples/unsigned_pdu.json b/data/api/server-server/examples/unsigned_pdu.json new file mode 100644 index 000000000..b886a3658 --- /dev/null +++ b/data/api/server-server/examples/unsigned_pdu.json @@ -0,0 +1,4 @@ +{ + "$ref": "unsigned_pdu_base.json", + "event_id": "$a4ecee13e2accdadf56c1025:example.com" +} diff --git a/data/api/server-server/examples/unsigned_pdu_base.json b/data/api/server-server/examples/unsigned_pdu_base.json new file mode 100644 index 000000000..4826ccefc --- /dev/null +++ b/data/api/server-server/examples/unsigned_pdu_base.json @@ -0,0 +1,26 @@ +{ + "room_id": "!UcYsUzyxTGDxLBEvLy:example.org", + "sender": "@alice:example.com", + "origin": "example.com", + "origin_server_ts": 1404838188000, + "depth": 12, + "auth_events": [ + [ + "$af232176:example.org", + {"sha256": "abase64encodedsha256hashshouldbe43byteslong"} + ] + ], + "type": "m.room.message", + "prev_events": [ + [ + "$af232176:example.org", + {"sha256": "abase64encodedsha256hashshouldbe43byteslong"} + ] + ], + "content": { + "key": "value" + }, + "unsigned": { + "age": 4612 + } +} diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml new file mode 100644 index 000000000..4925221fc --- /dev/null +++ b/data/api/server-server/invites-v1.yaml @@ -0,0 +1,168 @@ +# Copyright 2018-2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Invite User To Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/invite/{roomId}/{eventId}": + put: + summary: Invites a remote user to a room + description: |- + Invites a remote user to a room. Once the event has been signed by both the inviting + homeserver and the invited homeserver, it can be sent to all of the servers in the + room by the inviting homeserver. + + Servers should prefer to use the v2 API for invites instead of the v1 API. Servers + which receive a v1 invite request must assume that the room version is either `"1"` + or `"2"`. + + Note that events have a different format depending on the room version - check the + [room version specification](/#room-versions) for precise event formats. **The request and response + bodies here describe the common event fields in more detail and may be missing other + required fields for a PDU.** + operationId: sendInviteV1 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that the user is being invited to. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the invite event, generated by the inviting server. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + allOf: + - $ref: "definitions/invite_event.yaml" + - type: object + properties: + unsigned: + type: object + title: UnsignedData + description: |- + Information included alongside the event that is not signed. May include more + than what is listed here. + properties: + invite_room_state: + type: array + description: |- + An optional list of simplified events to help the receiver of the invite + identify the room. The recommended events to include are the join rules, + canonical alias, avatar, and name of the room. + items: + $ref: "../../event-schemas/schema/stripped_state.yaml" + example: + $ref: "../../event-schemas/examples/invite_room_state.json" + example: { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } + } + responses: + 200: + description: |- + The event with the invited server's signature added. All other fields of the events + should remain untouched. Note that events have a different format depending on the + room version - check the [room version specification](/#room-versions) for precise event formats. + schema: + type: array + minItems: 2 + maxItems: 2 + items: + - type: integer + description: The value `200`. + example: 200 + - type: object + description: An object containing the signed invite event. + title: Event Container + properties: + event: + $ref: "definitions/invite_event.yaml" + required: ['event'] + examples: + application/json: [ + 200, + { + "event": { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "unsigned": { + "invite_room_state": { + "$ref": "../../event-schemas/examples/invite_room_state.json" + } + }, + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + "elsewhere.com": { + "ed25519:k3y_versi0n": "SomeOtherSignatureHere" + } + } + } + } + ] + 403: + description: |- + The invite is not allowed. This could be for a number of reasons, including: + + * The sender is not allowed to send invites to the target user/homeserver. + * The homeserver does not permit anyone to invite its users. + * The homeserver refuses to participate in the room. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "User cannot invite the target user." + } diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml new file mode 100644 index 000000000..039a9e657 --- /dev/null +++ b/data/api/server-server/invites-v2.yaml @@ -0,0 +1,187 @@ +# Copyright 2018-2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Invite User To Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/invite/{roomId}/{eventId}": + put: + summary: Invites a remote user to a room + description: |- + **Note:** + This API is nearly identical to the v1 API with the exception of the request + body being different, and the response format fixed. + + Invites a remote user to a room. Once the event has been signed by both the inviting + homeserver and the invited homeserver, it can be sent to all of the servers in the + room by the inviting homeserver. + + This endpoint is preferred over the v1 API as it is more useful for servers. Senders + which receive a 400 or 404 response to this endpoint should retry using the v1 + API as the server may be older, if the room version is "1" or "2". + + Note that events have a different format depending on the room version - check the + [room version specification](/#room-versions) for precise event formats. **The request and response + bodies here describe the common event fields in more detail and may be missing other + required fields for a PDU.** + operationId: sendInviteV2 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that the user is being invited to. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the invite event, generated by the inviting server. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + room_version: + type: string + description: The version of the room where the user is being invited to. + example: "2" + event: + $ref: "definitions/invite_event.yaml" + invite_room_state: + type: array + description: |- + An optional list of simplified events to help the receiver of the invite + identify the room. The recommended events to include are the join rules, + canonical alias, avatar, and name of the room. + items: + $ref: "../../event-schemas/schema/stripped_state.yaml" + example: + $ref: "../../event-schemas/examples/invite_room_state.json" + required: ['room_version', 'event'] + example: { + "room_version": "2", + "event": { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } + } + } + responses: + 200: + description: |- + The event with the invited server's signature added. All other fields of the events + should remain untouched. Note that events have a different format depending on the + room version - check the [room version specification](/#room-versions) for precise event formats. + schema: + type: object + description: An object containing the signed invite event. + title: Event Container + properties: + event: + $ref: "definitions/invite_event.yaml" + required: ['event'] + examples: + application/json: { + "event": { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "unsigned": { + "invite_room_state": { + "$ref": "../../event-schemas/examples/invite_room_state.json" + } + }, + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + "elsewhere.com": { + "ed25519:k3y_versi0n": "SomeOtherSignatureHere" + } + } + } + } + 403: + description: |- + The invite is not allowed. This could be for a number of reasons, including: + + * The sender is not allowed to send invites to the target user/homeserver. + * The homeserver does not permit anyone to invite its users. + * The homeserver refuses to participate in the room. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "User cannot invite the target user." + } + 400: + description: |- + The request is invalid or the room the server is attempting + to join has a version that is not listed in the `ver` + parameters. + + The error should be passed through to clients so that they + may give better feedback to users. + schema: + allOf: + - $ref: "../client-server/definitions/errors/error.yaml" + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + application/json: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to join this room", + "room_version": "3" + } diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml new file mode 100644 index 000000000..696ca5333 --- /dev/null +++ b/data/api/server-server/joins-v1.yaml @@ -0,0 +1,283 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Join Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/make_join/{roomId}/{userId}": + get: + summary: Get information required to make a join event for a room + description: |- + Asks the receiving server to return information that the sending + server will need to prepare a join event to get into the room. + operationId: makeJoin + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be joined. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: userId + type: string + description: The user ID the join event will be for. + required: true + x-example: "@someone:example.org" + - in: query + type: array + items: + type: string + name: ver + description: |- + The room versions the sending server has support for. Defaults + to `[1]`. + x-example: ["1", "2"] + responses: + 200: + description: |- + A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that + events have a different format depending on the room version - check the + [room version specification](/#room-versions) for precise event formats. **The response body + here describes the common event fields in more detail and may be missing other + required fields for a PDU.** + schema: + type: object + properties: + room_version: + type: string + description: |- + The version of the room where the server is trying to join. If not provided, + the room version is assumed to be either "1" or "2". + example: "2" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/#room-versions) + for precise event formats. + type: object + title: Event Template + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: "m.room.member" + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "join"} + properties: + membership: + type: string + description: The value `join`. + example: "join" + required: ['membership'] + required: + - state_key + - origin + - origin_server_ts + - type + - content + - sender + examples: + application/json: { + "room_version": "2", + "event": { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join" + } + } + } + 400: + description: |- + The request is invalid or the room the server is attempting + to join has a version that is not listed in the `ver` + parameters. + + The error should be passed through to clients so that they + may give better feedback to users. + schema: + allOf: + - $ref: "../client-server/definitions/errors/error.yaml" + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + application/json: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to join this room", + "room_version": "3" + } + 404: + description: |- + The room that the joining server is attempting to join is unknown + to the receiving server. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unknown room", + } + + "/send_join/{roomId}/{eventId}": + put: + summary: Submit a signed join event to a resident server + description: |- + **Note:** + Servers should instead prefer to use the v2 `/send_join` endpoint. + + Submits a signed join event to the resident server for it + to accept it into the room's graph. Note that events have + a different format depending on the room version - check + the [room version specification](/#room-versions) for precise event formats. + **The request and response body here describe the common + event fields in more detail and may be missing other required + fields for a PDU.** + operationId: sendJoinV1 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be joined. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the join event. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the joining homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the joining homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: "m.room.member" + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "join"} + properties: + membership: + type: string + description: The value `join`. + example: "join" + required: ['membership'] + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + example: { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join" + } + } + responses: + 200: + description: |- + The full state for the room, having accepted the join event. + schema: + type: array + minItems: 2 + maxItems: 2 + items: + - type: integer + description: The value `200`. + example: 200 + - $ref: "./definitions/send_join_response.yaml" + examples: + application/json: [ + 200, + { + "origin": "matrix.org", + "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], + "state": [{"$ref": "examples/minimal_pdu.json"}] + } + ] diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml new file mode 100644 index 000000000..de5c57113 --- /dev/null +++ b/data/api/server-server/joins-v2.yaml @@ -0,0 +1,136 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Join Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + # Note: there is no v2 of make_join (yet) + "/send_join/{roomId}/{eventId}": + put: + summary: Submit a signed join event to a resident server + description: |- + **Note:** + This API is nearly identical to the v1 API with the + exception of the response format being fixed. + + This endpoint is preferred over the v1 API as it provides + a more standarised response format. Senders which receive + a 400, 404, or other status code which indicates this endpoint + is not available should retry using the v1 API instead. + + Submits a signed join event to the resident server for it + to accept it into the room's graph. Note that events have + a different format depending on the room version - check + the [room version specification](/#room-versions) for precise event formats. + **The request and response body here describe the common + event fields in more detail and may be missing other required + fields for a PDU.** + operationId: sendJoinV2 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be joined. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the join event. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the joining homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the joining homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: "m.room.member" + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "join"} + properties: + membership: + type: string + description: The value `join`. + example: "join" + required: ['membership'] + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + example: { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join" + } + } + responses: + 200: + description: |- + The full state for the room, having accepted the join event. + schema: + $ref: "./definitions/send_join_response.yaml" + examples: + application/json: { + "origin": "matrix.org", + "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], + "state": [{"$ref": "examples/minimal_pdu.json"}] + } diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml new file mode 100644 index 000000000..cad6b8824 --- /dev/null +++ b/data/api/server-server/keys_query.yaml @@ -0,0 +1,133 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Key Exchange API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/key/v2 +consumes: + - application/json +produces: + - application/json +paths: + "/query/{serverName}/{keyId}": + get: + summary: Query for another server's keys + description: |- + Query for another server's keys. The receiving (notary) server must + sign the keys returned by the queried server. + operationId: perspectivesKeyQuery + parameters: + - in: path + name: serverName + type: string + description: The server's DNS name to query + required: true + x-example: matrix.org + - in: path + name: keyId + type: string + description: |- + **Deprecated**. Servers should not use this parameter and instead + opt to return all keys, not just the requested one. The key ID to + look up. + + When excluded, the trailing slash on this endpoint is optional. + required: false + x-example: "ed25519:abc123" + - in: query + name: minimum_valid_until_ts + type: integer + format: int64 + description: |- + A millisecond POSIX timestamp in milliseconds indicating when the returned + certificates will need to be valid until to be useful to the requesting server. + + If not supplied, the current time as determined by the notary server is used. + required: false + x-example: 1234567890 + responses: + 200: + description: |- + The keys for the server, or an empty array if the server could not be reached + and no cached keys were available. + schema: + $ref: "definitions/keys_query_response.yaml" + "/query": + post: + summary: Query for several server's keys + description: |- + Query for keys from multiple servers in a batch format. The receiving (notary) + server must sign the keys returned by the queried servers. + operationId: bulkPerspectivesKeyQuery + parameters: + - in: body + name: body + schema: + type: object + example: { + "server_keys": { + "example.org": { + "ed25519:abc123": { + "minimum_valid_until_ts": 1234567890 + } + } + } + } + properties: + server_keys: + type: object + description: |- + The query criteria. The outer `string` key on the object is the + server name (eg: `matrix.org`). The inner `string` key is the + Key ID to query for the particular server. If no key IDs are given + to be queried, the notary server should query for all keys. If no + servers are given, the notary server must return an empty `server_keys` + array in the response. + + The notary server may return multiple keys regardless of the Key IDs + given. + additionalProperties: + type: object + name: ServerName + description: The server names to query. + additionalProperties: + type: object + title: Query Criteria + description: The server key IDs to query. + properties: + minimum_valid_until_ts: + type: integer + format: int64 + description: |- + A millisecond POSIX timestamp in milliseconds indicating when + the returned certificates will need to be valid until to be + useful to the requesting server. + + If not supplied, the current time as determined by the notary + server is used. + example: 1234567890 + required: ['server_keys'] + responses: + 200: + description: |- + The keys for the queried servers, signed by the notary server. Servers which + are offline and have no cached keys will not be included in the result. This + may result in an empty array. + schema: + $ref: "definitions/keys_query_response.yaml" diff --git a/data/api/server-server/keys_server.yaml b/data/api/server-server/keys_server.yaml new file mode 100644 index 000000000..81b98b1e9 --- /dev/null +++ b/data/api/server-server/keys_server.yaml @@ -0,0 +1,63 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Key Exchange API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/key/v2 +produces: + - application/json +paths: + "/server/{keyId}": + get: + summary: Get the homeserver's public key(s) + description: |- + Gets the homeserver's published signing keys. + The homeserver may have any number of active keys and may have a + number of old keys. + + Intermediate notary servers should cache a response for half of its + lifetime to avoid serving a stale response. Originating servers should + avoid returning responses that expire in less than an hour to avoid + repeated requests for a certificate that is about to expire. Requesting + servers should limit how frequently they query for certificates to + avoid flooding a server with requests. + + If the server fails to respond to this request, intermediate notary + servers should continue to return the last response they received + from the server so that the signatures of old events can still be + checked. + operationId: getServerKey + parameters: + - in: path + name: keyId + type: string + description: |- + **Deprecated**. Servers should not use this parameter and instead + opt to return all keys, not just the requested one. The key ID to + look up. + + When excluded, the trailing slash on this endpoint is optional. + required: false + x-example: "ed25519:abc123" + deprecated: true + responses: + 200: + description: The homeserver's keys + schema: + $ref: "definitions/keys.yaml" diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml new file mode 100644 index 000000000..ce96ab4ab --- /dev/null +++ b/data/api/server-server/leaving-v1.yaml @@ -0,0 +1,251 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Leave Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/make_leave/{roomId}/{userId}": + get: + summary: Get information required to make a leave event for a room + description: |- + Asks the receiving server to return information that the sending + server will need to prepare a leave event to get out of the room. + operationId: makeLeave + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be left. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: userId + type: string + description: The user ID the leave event will be for. + required: true + x-example: "@someone:example.org" + responses: + 200: + description: |- + A template to be used to call `/send_leave`. Note that + events have a different format depending on the room version - check the + [room version specification](/#room-versions) for precise event formats. **The response body + here describes the common event fields in more detail and may be missing other + required fields for a PDU.** + schema: + type: object + properties: + room_version: + type: string + description: |- + The version of the room where the server is trying to leave. If not provided, + the room version is assumed to be either "1" or "2". + example: "2" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/#room-versions) + for precise event formats. + type: object + title: Event Template + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: "m.room.member" + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "leave"} + properties: + membership: + type: string + description: The value `leave`. + example: "leave" + required: ['membership'] + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + examples: + application/json: { + "room_version": "2", + "event": { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } + } + 403: + description: |- + The request is not authorized. This could mean that the user is not in the room. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "User is not in the room." + } + "/send_leave/{roomId}/{eventId}": + put: + summary: Submit a signed leave event to a resident server + description: |- + **Note:** + Servers should instead prefer to use the v2 `/send_leave` endpoint. + + Submits a signed leave event to the resident server for it + to accept it into the room's graph. Note that events have + a different format depending on the room version - check + the [room version specification](/#room-versions) for precise event formats. + **The request and response body here describe the common + event fields in more detail and may be missing other required + fields for a PDU.** + operationId: sendLeaveV1 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be left. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the leave event. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the leaving homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the leaving homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: "m.room.member" + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "leave"} + properties: + membership: + type: string + description: The value `leave`. + example: "leave" + required: ['membership'] + depth: + type: integer + description: This field must be present but is ignored; it may be 0. + example: 12 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - depth + - content + example: { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } + responses: + 200: + description: |- + An empty response to indicate the event was accepted into the graph by + the receiving homeserver. + schema: + type: array + minItems: 2 + maxItems: 2 + items: + - type: integer + description: The value `200`. + example: 200 + - type: object + title: Empty Object + description: An empty object. + examples: + application/json: [200, {}] diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml new file mode 100644 index 000000000..28a417591 --- /dev/null +++ b/data/api/server-server/leaving-v2.yaml @@ -0,0 +1,140 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Leave Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + # Note: there is no v2 of make_leave (yet) + "/send_leave/{roomId}/{eventId}": + put: + summary: Submit a signed leave event to a resident server + description: |- + **Note:** + This API is nearly identical to the v1 API with the + exception of the response format being fixed. + + This endpoint is preferred over the v1 API as it provides + a more standarised response format. Senders which receive + a 400, 404, or other status code which indicates this endpoint + is not available should retry using the v1 API instead. + + Submits a signed leave event to the resident server for it + to accept it into the room's graph. Note that events have + a different format depending on the room version - check + the [room version specification](/#room-versions) for precise event formats. + **The request and response body here describe the common + event fields in more detail and may be missing other required + fields for a PDU.** + operationId: sendLeaveV2 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be left. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the leave event. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the leaving homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the leaving homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: "m.room.member" + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "leave"} + properties: + membership: + type: string + description: The value `leave`. + example: "leave" + required: ['membership'] + depth: + type: integer + description: This field must be present but is ignored; it may be 0. + example: 12 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - depth + - content + example: { + "$ref": "examples/minimal_pdu.json", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } + responses: + 200: + description: |- + An empty response to indicate the event was accepted into the graph by + the receiving homeserver. + schema: + type: object + title: Empty Object + description: An empty object. + examples: + application/json: {} diff --git a/data/api/server-server/openid.yaml b/data/api/server-server/openid.yaml new file mode 100644 index 000000000..0761618d9 --- /dev/null +++ b/data/api/server-server/openid.yaml @@ -0,0 +1,63 @@ +# Copyright 2017 Kamax.io +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation OpenID API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +paths: + "/openid/userinfo": + get: + summary: Exchange an OpenID token for user information + description: |- + Exchanges an OpenID access token for information about the user + who generated the token. Currently this only exposes the Matrix + User ID of the owner. + operationId: exchangeOpenIdToken + parameters: + - in: query + name: access_token + type: string + description: |- + The OpenID access token to get information about the owner for. + required: true + x-example: SomeT0kenHere + responses: + 200: + description: |- + Information about the user who generated the OpenID access token. + schema: + type: object + properties: + sub: + type: string + description: The Matrix User ID who generated the token. + example: "@alice:example.com" + required: ['sub'] + 401: + description: The token was not recognized or has expired. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Access token unknown or expired" + } diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml new file mode 100644 index 000000000..3c8d7ea6f --- /dev/null +++ b/data/api/server-server/public_rooms.yaml @@ -0,0 +1,230 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Public Rooms API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/publicRooms": + get: + summary: Get all the public rooms for a homeserver + description: |- + Gets all the public rooms for the homeserver. This should not return + rooms that are listed on another homeserver's directory, just those + listed on the receiving homeserver's directory. + operationId: getPublicRooms + security: + - signedRequest: [] + parameters: + - in: query + name: limit + type: integer + description: |- + The maximum number of rooms to return. Defaults to 0 (no limit). + x-example: 10 + - in: query + name: since + type: string + description: |- + A pagination token from a previous call to this endpoint to fetch more + rooms. + x-example: "GetMoreRoomsTokenHere" + - in: query + name: include_all_networks + type: boolean + description: |- + Whether or not to include all networks/protocols defined by application + services on the homeserver. Defaults to false. + x-example: false + - in: query + name: third_party_instance_id + type: string + description: |- + The specific third party network/protocol to request from the homeserver. + Can only be used if `include_all_networks` is false. + x-example: "irc" + responses: + 200: + description: The public room list for the homeserver. + schema: + $ref: "../client-server/definitions/public_rooms_response.yaml" + post: + summary: Gets the public rooms on the server with optional filter. + description: |- + Lists the public rooms on the server, with optional filter. + + This API returns paginated responses. The rooms are ordered by the number + of joined members, with the largest rooms first. + + Note that this endpoint receives and returns the same format that is seen + in the Client-Server API's `POST /publicRooms` endpoint. + operationId: queryPublicRooms + security: + - signedRequest: [] + parameters: + - in: body + name: body + required: true + description: |- + Options for which rooms to return, or empty object to use defaults. + schema: + type: object + properties: + limit: + type: integer + description: |- + Limit the number of results returned. + since: + type: string + description: |- + A pagination token from a previous request, allowing servers + to get the next (or previous) batch of rooms. The direction + of pagination is specified solely by which token is supplied, + rather than via an explicit flag. + filter: + type: object + title: "Filter" + description: |- + Filter to apply to the results. + properties: + generic_search_term: + type: string + description: |- + A string to search for in the room metadata, e.g. name, + topic, canonical alias etc. (Optional). + include_all_networks: + type: boolean + description: |- + Whether or not to include all known networks/protocols from + application services on the homeserver. Defaults to false. + example: false + third_party_instance_id: + type: string + description: |- + The specific third party network/protocol to request from the + homeserver. Can only be used if `include_all_networks` is false. + example: "irc" + example: { + "limit": 10, + "filter": { + "generic_search_term": "foo" + }, + "include_all_networks": false, + "third_party_instance_id": "irc" + } + responses: + 200: + description: A list of the rooms on the server. + schema: + type: object + description: A list of the rooms on the server. + required: ["chunk"] + properties: + chunk: + title: "PublicRoomsChunks" + type: array + description: |- + A paginated chunk of public rooms. + items: + type: object + title: "PublicRoomsChunk" + required: + - room_id + - num_joined_members + - world_readable + - guest_can_join + properties: + aliases: + type: array + description: |- + Aliases of the room. May be empty. + items: + type: string + canonical_alias: + type: string + description: |- + The canonical alias of the room, if any. + name: + type: string + description: |- + The name of the room, if any. + num_joined_members: + type: integer + description: |- + The number of members joined to the room. + room_id: + type: string + description: |- + The ID of the room. + topic: + type: string + description: |- + The topic of the room, if any. + world_readable: + type: boolean + description: |- + Whether the room may be viewed by guest users without joining. + guest_can_join: + type: boolean + description: |- + Whether guest users may join the room and participate in it. + If they can, they will be subject to ordinary power level + rules like any other user. + avatar_url: + type: string + description: The URL for the room's avatar, if one is set. + next_batch: + type: string + description: |- + A pagination token for the response. The absence of this token + means there are no more results to fetch and the client should + stop paginating. + prev_batch: + type: string + description: |- + A pagination token that allows fetching previous results. The + absence of this token means there are no results before this + batch, i.e. this is the first batch. + total_room_count_estimate: + type: integer + description: |- + An estimate on the total number of public rooms, if the + server has an estimate. + examples: + application/json: { + "chunk": [ + { + "aliases": ["#murrays:cheese.bar"], + "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE", + "guest_can_join": false, + "name": "CHEESE", + "num_joined_members": 37, + "room_id": "!ol19s:bleecker.street", + "topic": "Tasty tasty cheese", + "world_readable": true + } + ], + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 + } diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml new file mode 100644 index 000000000..42b64ea81 --- /dev/null +++ b/data/api/server-server/query.yaml @@ -0,0 +1,175 @@ +# Copyright 2017 Kamax.io +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Query API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/query/{queryType}": + get: + summary: Query for information + description: |- + Performs a single query request on the receiving homeserver. The query string + arguments are dependent on which type of query is being made. Known query types + are specified as their own endpoints as an extension to this definition. + operationId: queryInfo + security: + - signedRequest: [] + parameters: + - in: path + name: queryType + type: string + description: The type of query to make + required: true + x-example: profile + responses: + 200: + description: |- + The query response. The schema varies depending on the query being made. + "/query/directory": + get: + summary: Query for the room ID and resident homeservers for a room alias + description: |- + Performs a query to get the mapped room ID and list of resident homeservers in + the room for a given room alias. Homeservers should only query room aliases + that belong to the target server (identified by the DNS Name in the alias). + + Servers may wish to cache the response to this query to avoid requesting the + information too often. + operationId: queryRoomDirectory + security: + - signedRequest: [] + parameters: + - in: query + name: room_alias + type: string + description: The room alias to query. + required: true + x-example: "#room_alias:example.org" + responses: + 200: + description: |- + The corresponding room ID and list of known resident homeservers for the room. + schema: + type: object + properties: + room_id: + type: string + description: The room ID mapped to the queried room alias. + x-example: "!roomid1234:example.org" + servers: + type: array + description: |- + An array of server names that are likely to hold the given room. This + list may or may not include the server answering the query. + items: + type: string + required: + - "room_id" + - "servers" + examples: + application/json: { + "room_id": "!roomid1234:example.org", + "servers": [ + "example.org", + "example.com", + "another.example.com:8449", + ] + } + 404: + description: The room alias was not found. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room alias not found." + } + "/query/profile": + get: + summary: Query for profile information about a given user + description: |- + Performs a query to get profile information, such as a display name or avatar, + for a given user. Homeservers should only query profiles for users that belong + to the target server (identified by the DNS Name in the user ID). + + Servers may wish to cache the response to this query to avoid requesting the + information too often. + operationId: queryProfile + security: + - signedRequest: [] + parameters: + - in: query + name: user_id + type: string + description: The user ID to query. + required: true + x-example: "@someone:example.org" + - in: query + name: field + type: string + enum: ['displayname', 'avatar_url'] + description: |- + The field to query. If specified, the server will only return the given field + in the response. If not specified, the server will return the full profile for + the user. + responses: + 200: + description: |- + The profile for the user. If a `field` is specified in the request, only the + matching field should be included in the response. If no `field` was specified, + the response should include the fields of the user's profile that can be made + public, such as the display name and avatar. + + If the user does not have a particular field set on their profile, the server + should exclude it from the response body or give it the value `null`. + schema: + type: object + properties: + displayname: + type: string + description: |- + The display name of the user. May be omitted if the user does not have a + display name set. + x-example: "John Doe" + avatar_url: + type: string + description: |- + The avatar URL for the user's avatar. May be omitted if the user does not + have an avatar set. + x-example: "mxc://matrix.org/MyC00lAvatar" + examples: + application/json: { + "displayname": "John Doe", + "avatar_url": "mxc://matrix.org/MyC00lAvatar" + } + 404: + description: The user does not exist or does not have a profile. + schema: + $ref: "../client-server/definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "User does not exist." + } diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml new file mode 100644 index 000000000..9a636aa92 --- /dev/null +++ b/data/api/server-server/third_party_invite.yaml @@ -0,0 +1,325 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Third Party Invites API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/exchange_third_party_invite/{roomId}": + put: + summary: Request a server to auth a third party invite event + description: |- + The receiving server will verify the partial `m.room.member` event + given in the request body. If valid, the receiving server will issue + an invite as per the [Inviting to a room](/server-server-api/#inviting-to-a-room) section before returning a + response to this request. + operationId: exchangeThirdPartyInvite + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID to exchange a third party invite in + required: true + x-example: "!abc123:matrix.org" + - in: body + name: body + type: object + description: A partial `m.room.member` event + required: true + schema: + type: object + properties: + type: + type: string + description: The event type. Must be `m.room.member` + example: "m.room.member" + room_id: + type: string + description: |- + The room ID the event is for. Must match the ID given in + the path. + example: "!abc123:matrix.org" + sender: + type: string + description: |- + The user ID of the user who sent the original `m.room.third_party_invite` + event. + example: "@joe:matrix.org" + state_key: + type: string + description: The user ID of the invited user + example: "@someone:example.org" + content: + type: object + description: The event content + title: Event Content + properties: + membership: + type: string + description: The membership state. Must be `invite` + example: invite + third_party_invite: + type: object + description: The third party invite + title: Third Party Invite + properties: + display_name: + type: string + description: |- + A name which can be displayed to represent the user instead of their + third party identifier. + example: "alice" + signed: + type: object + description: |- + A block of content which has been signed, which servers can use to + verify the event. + title: Invite Signatures + properties: + signatures: + type: object + title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string + description: |- + The server signatures for this event. + + The signature is calculated using the process + described at [Signing JSON](/appendices/#signing-json). + example: { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + mxid: + type: string + description: The invited matrix user ID + example: "@alice:localhost" + token: + type: string + description: The token used to verify the event + example: abc123 + required: ['signatures', 'mxid', 'token'] + example: { + "mxid": "@alice:localhost", + "token": "abc123", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + } + required: ['display_name', 'signed'] + example: { + "display_name": "alice", + "signed": { + "mxid": "@alice:localhost", + "token": "abc123", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + } + } + required: ['membership', 'third_party_invite'] + example: { + "membership": "invite", + "third_party_invite": { + "display_name": "alice", + "signed": { + "mxid": "@alice:localhost", + "token": "abc123", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + } + } + } + required: + - type + - room_id + - sender + - state_key + - content + example: { + "type": "m.room.member", + "room_id": "!abc123:matrix.org", + "sender": "@joe:matrix.org", + "state_key": "@someone:example.org", + "content": { + "membership": "invite", + "third_party_invite": { + "display_name": "alice", + "signed": { + "mxid": "@alice:localhost", + "token": "abc123", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + } + } + } + } + responses: + 200: + description: The invite has been issued successfully. + examples: + application/json: {} + schema: + type: object + description: An empty object + example: {} + "/3pid/onbind": + put: + summary: |- + Notifies the server that a third party identifier has been bound to one + of its users. + description: |- + Used by identity servers to notify the homeserver that one of its users + has bound a third party identifier successfully, including any pending + room invites the identity server has been made aware of. + operationId: onBindThirdPartyIdentifier + parameters: + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + medium: + type: string + description: |- + The type of third party identifier. Currently only "email" is + a possible value. + example: "email" + address: + type: string + description: |- + The third party identifier itself. For example, an email address. + example: "alice@example.com" + mxid: + type: string + description: The user that is now bound to the third party identifier. + example: "@alice:matrix.org" + invites: + type: array + description: |- + A list of pending invites that the third party identifier has received. + items: + type: object + title: Third Party Invite + properties: + medium: + type: string + description: |- + The type of third party invite issues. Currently only + "email" is used. + example: "email" + address: + type: string + description: |- + The third party identifier that received the invite. + example: "alice@example.com" + mxid: + type: string + description: The now-bound user ID that received the invite. + example: "@alice:matrix.org" + room_id: + type: string + description: The room ID the invite is valid for. + example: "!somewhere:example.org" + sender: + type: string + description: The user ID that sent the invite. + example: "@bob:matrix.org" + # TODO (TravisR): Make this reusable when doing IS spec changes + # also make sure it isn't lying about anything, like the key version + signed: + type: object + title: Identity Server Signatures + description: |- + Signature from the identity server using a long-term private + key. + properties: + mxid: + type: string + description: |- + The user ID that has been bound to the third party + identifier. + example: "@alice:matrix.org" + token: + type: string + # TODO: What is this actually? + description: A token. + example: "Hello World" + signatures: + type: object + title: Identity Server Signature + description: |- + The signature from the identity server. The `string` key + is the identity server's domain name, such as vector.im + additionalProperties: + type: object + title: Identity Server Domain Signature + description: The signature for the identity server. + properties: + "ed25519:0": + type: string + description: The signature. + example: "SomeSignatureGoesHere" + required: ['ed25519:0'] + example: { + "vector.im": { + "ed25519:0": "SomeSignatureGoesHere" + } + } + required: ['mxid', 'token', 'signatures'] + required: + - medium + - address + - mxid + - room_id + - sender + - signed + required: ['medium', 'address', 'mxid', 'invites'] + responses: + 200: + description: The homeserver has processed the notification. + examples: + application/json: {} + schema: + type: object + description: An empty object + example: {} diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml new file mode 100644 index 000000000..15b3ee368 --- /dev/null +++ b/data/api/server-server/transactions.yaml @@ -0,0 +1,109 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Transaction API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/send/{txnId}": + put: + summary: Send a transaction + description: |- + Push messages representing live activity to another server. The destination name + will be set to that of the receiving server itself. Each embedded PDU in the + transaction body will be processed. + + The sending server must wait and retry for a 200 OK response before sending a + transaction with a different `txnId` to the receiving server. + + Note that events have a different format depending on the room version - check + the [room version specification](/#room-versions) for precise event formats. + operationId: sendTransaction + security: + - signedRequest: [] + parameters: + - in: path + name: txnId + type: string + description: |- + The transaction ID. + required: true + x-example: S0meTransacti0nId + - in: body + name: body + type: object + required: true + schema: + allOf: + - $ref: "definitions/transaction.yaml" + - type: object + properties: + edus: + type: array + description: |- + List of ephemeral messages. May be omitted if there are no ephemeral + messages to be sent. Must not include more than 100 EDUs. + items: + $ref: "definitions/edu.yaml" + example: { + "$ref": "examples/transaction.json", + "edus": [{"$ref": "edu.json"}] # Relative to the examples directory + } + responses: + 200: + description: |- + The result of processing the transaction. The server is to use this response even in + the event of one or more PDUs failing to be processed. + schema: + type: object + title: PDU Processing Results + description: The results for the processing of each PDU in the transaction. + properties: + pdus: + type: object + description: |- + The PDUs from the original transaction. The string key represents the ID of the + PDU (event) that was processed. + additionalProperties: + type: object + title: PDU Processing Result + description: Information about how the PDU was handled. + properties: + error: + type: string + description: |- + A human readable description about what went wrong in processing this PDU. + If no error is present, the PDU can be considered successfully handled. + example: "You are not allowed to send a message to this room." + required: ['pdus'] + examples: + application/json: { + "pdus": { + "$successful_event:example.org": {}, + "$failed_event:example.org": { + "error": "You are not allowed to send a message to this room." + } + } + } diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml new file mode 100644 index 000000000..0c2348dab --- /dev/null +++ b/data/api/server-server/user_devices.yaml @@ -0,0 +1,118 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation User Device Management API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user/devices/{userId}": + get: + summary: Gets all of the user's devices + description: Gets information on all of the user's devices + operationId: getUserDevices + security: + - signedRequest: [] + parameters: + - in: path + name: userId + type: string + required: true + description: |- + The user ID to retrieve devices for. Must be a user local to the + receiving homeserver. + x-example: "@alice:example.org" + responses: + 200: + description: The user's devices. + schema: + type: object + properties: + user_id: + type: string + description: The user ID devices were requested for. + example: "@alice:example.org" + stream_id: + type: integer + description: |- + A unique ID for a given user_id which describes the version of + the returned device list. This is matched with the `stream_id` + field in `m.device_list_update` EDUs in order to incrementally + update the returned device_list. + example: 5 + devices: + type: array + description: The user's devices. May be empty. + items: + type: object + title: User Device + properties: + device_id: + type: string + description: The device ID. + example: "JLAFKJWSCS" + keys: + type: object + description: Identity keys for the device. + $ref: "../client-server/definitions/device_keys.yaml" + device_display_name: + type: string + description: Optional display name for the device. + example: "Alice's Mobile Phone" + required: ['device_id', 'keys'] + master_key: + type: object + description: |- + The user\'s master cross-signing key. + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + # FIXME: why isn't the doc generator picking up this example? + - example: { + "user_id": "@alice:example.com", + "usage": ["master"], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key", + } + } + self_signing_keys: + type: object + description: |- + The user\'s self-signing key. + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + # FIXME: why isn't the doc generator picking up this example? + - example: { + "user_id": "@alice:example.com", + "usage": ["self_signing"], + "keys": { + "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+self+signing+key" + } + } + } + required: ['user_id', 'stream_id', 'devices'] diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml new file mode 100644 index 000000000..e1601e33c --- /dev/null +++ b/data/api/server-server/user_keys.yaml @@ -0,0 +1,252 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation User Key Management API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/user/keys/claim": + post: + summary: Claims one-time encryption keys for a user. + description: |- + Claims one-time keys for use in pre-key messages. + operationId: claimUserEncryptionKeys + security: + - signedRequest: [] + parameters: + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + one_time_keys: + type: object + description: |- + The keys to be claimed. A map from user ID, to a map from + device ID to algorithm name. + additionalProperties: + type: object + additionalProperties: + type: string + description: algorithm + example: "signed_curve25519" + example: { + "@alice:example.com": { + "JLAFKJWSCS": "signed_curve25519" + } + } + required: + - one_time_keys + responses: + 200: + description: The claimed keys. + schema: + type: object + properties: + one_time_keys: + type: object + description: |- + One-time keys for the queried devices. A map from user ID, to a + map from devices to a map from `:` to the key object. + + See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on + the Key Object format. + additionalProperties: + type: object + additionalProperties: + type: + - string + - type: object + title: KeyObject + properties: + key: + type: string + description: The key, encoded using unpadded base64. + signatures: + type: object + title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string + description: |- + Signature of the key object. + + The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). + required: ['key', 'signatures'] + example: { + "@alice:example.com": { + "JLAFKJWSCS": { + "signed_curve25519:AAAAHg": { + "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + } + } + } + } + } + } + required: ['one_time_keys'] + "/user/keys/query": + post: + summary: Download device identity keys. + description: |- + Returns the current devices and identity keys for the given users. + operationId: queryUserEncryptionKeys + security: + - signedRequest: [] + parameters: + - in: body + name: body + type: object + required: true + schema: + type: object + properties: + device_keys: + type: object + description: |- + The keys to be downloaded. A map from user ID, to a list of + device IDs, or to an empty list to indicate all devices for the + corresponding user. + additionalProperties: + type: array + items: + type: string + description: "Device ID" + example: { + "@alice:example.com": [] + } + required: ['device_keys'] + responses: + 200: + description: The device information. + schema: + type: object + properties: + device_keys: + type: object + description: |- + Information on the queried devices. A map from user ID, to a + map from device ID to device information. For each device, + the information returned will be the same as uploaded via + `/keys/upload`, with the addition of an `unsigned` + property. + additionalProperties: + type: object + additionalProperties: + allOf: + - $ref: ../client-server/definitions/device_keys.yaml + properties: + unsigned: + title: UnsignedDeviceInfo + type: object + description: |- + Additional data added to the device key information + by intermediate servers, and not covered by the + signatures. + properties: + device_display_name: + type: string + description: + The display name which the user set on the device. + master_keys: + type: object + description: |- + Information on the master cross-signing keys of the queried users. + A map from user ID, to master key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the user is + allowed to see. + additionalProperties: + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + example: { + "@alice:example.com": { + "user_id": "@alice:example.com", + "usage": ["master"], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key", + } + } + } + self_signing_keys: + type: object + description: |- + Information on the self-signing keys of the queried users. A map + from user ID, to self-signing key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`. + additionalProperties: + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + example: { + "@alice:example.com": { + "user_id": "@alice:example.com", + "usage": ["self_signing"], + "keys": { + "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+self+signing+key" + } + } + } + } + required: ['device_keys'] + examples: + application/json: { + "device_keys": { + "@alice:example.com": { + "JLAFKJWSCS": { + "user_id": "@alice:example.com", + "device_id": "JLAFKJWSCS", + "algorithms": [ + "m.olm.v1.curve25519-aes-sha2", + "m.megolm.v1.aes-sha2" + ], + "keys": { + "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", + "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" + }, + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" + } + }, + "unsigned": { + "device_display_name": "Alice's mobile phone" + } + } + } + } + } diff --git a/data/api/server-server/version.yaml b/data/api/server-server/version.yaml new file mode 100644 index 000000000..929f7b91f --- /dev/null +++ b/data/api/server-server/version.yaml @@ -0,0 +1,54 @@ +# Copyright 2017 Kamax.io +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: '2.0' +info: + title: "Matrix Federation Version API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +paths: + "/version": + get: + summary: Get the implementation name and version of this homeserver. + description: Get the implementation name and version of this homeserver. + operationId: getVersion + responses: + 200: + description: + The implementation name and version of this homeserver. + examples: + application/json: { + "server": { + "name": "My_Homeserver_Implementation", + "version": "ArbitraryVersionNumber" + } + } + schema: + type: object + properties: + server: + title: Server + type: object + properties: + name: + type: string + description: Arbitrary name that identify this implementation. + version: + type: string + description: Version of this implementation. The version format depends on the implementation. diff --git a/data/api/server-server/wellknown.yaml b/data/api/server-server/wellknown.yaml new file mode 100644 index 000000000..54da2c75c --- /dev/null +++ b/data/api/server-server/wellknown.yaml @@ -0,0 +1,53 @@ +# Copyright 2019 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Federation Server Discovery API" + version: "1.0.0" +host: localhost:443 +schemes: + - https +basePath: /.well-known +produces: + - application/json +paths: + "/matrix/server": + get: + summary: Gets information about the delegated server for server-server communication. + description: |- + Gets information about the delegated server for server-server communication + between Matrix homeservers. Servers should follow 30x redirects, carefully + avoiding redirect loops, and use normal X.509 certificate validation. + operationId: getWellKnown + responses: + 200: + description: + The delegated server information. The `Content-Type` for this response SHOULD + be `application/json`, however servers parsing the response should assume that + the body is JSON regardless of type. Failures parsing the JSON or invalid data + provided in the resulting parsed JSON should not result in discovery failure - + consult the server discovery process for information on how to continue. + examples: + application/json: { + "m.server": "delegated.example.com:1234" + } + schema: + type: object + properties: + "m.server": + type: string + description: |- + The server name to delegate server-server communciations to, with optional + port. The delegated server name uses the same grammar as + [server names in the appendices](/appendices/#server-name). diff --git a/data/event-schemas/examples/core/event.json b/data/event-schemas/examples/core/event.json new file mode 100644 index 000000000..8a469a5cb --- /dev/null +++ b/data/event-schemas/examples/core/event.json @@ -0,0 +1,6 @@ +{ + "content": { + "key": "value" + }, + "type": "org.example.custom.event" +} diff --git a/data/event-schemas/examples/core/room_edu.json b/data/event-schemas/examples/core/room_edu.json new file mode 100644 index 000000000..30ad80818 --- /dev/null +++ b/data/event-schemas/examples/core/room_edu.json @@ -0,0 +1,4 @@ +{ + "$ref": "event.json", + "room_id": "!jEsUZKDJdhlrceRyVU:example.org" +} diff --git a/data/event-schemas/examples/core/room_event.json b/data/event-schemas/examples/core/room_event.json new file mode 100644 index 000000000..521225cc0 --- /dev/null +++ b/data/event-schemas/examples/core/room_event.json @@ -0,0 +1,10 @@ +{ + "$ref": "event.json", + "event_id": "$143273582443PhrSn:example.org", + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "sender": "@example:example.org", + "origin_server_ts": 1432735824653, + "unsigned": { + "age": 1234 + } +} diff --git a/data/event-schemas/examples/core/state_event.json b/data/event-schemas/examples/core/state_event.json new file mode 100644 index 000000000..910747ee2 --- /dev/null +++ b/data/event-schemas/examples/core/state_event.json @@ -0,0 +1,4 @@ +{ + "$ref": "room_event.json", + "state_key": "ArbitraryString" +} diff --git a/data/event-schemas/examples/invite_room_state.json b/data/event-schemas/examples/invite_room_state.json new file mode 100644 index 000000000..9d8c1b2bf --- /dev/null +++ b/data/event-schemas/examples/invite_room_state.json @@ -0,0 +1,18 @@ +[ + { + "type": "m.room.name", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "name": "Example Room" + } + }, + { + "type": "m.room.join_rules", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "join_rule": "invite" + } + } +] diff --git a/data/event-schemas/examples/m.accepted_terms.yaml b/data/event-schemas/examples/m.accepted_terms.yaml new file mode 100644 index 000000000..5e8dad16f --- /dev/null +++ b/data/event-schemas/examples/m.accepted_terms.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/event.json", + "type": "m.accepted_terms", + "content": { + "accepted": [ + "https://example.org/somewhere/terms-1.2-en.html", + "https://example.org/somewhere/privacy-1.2-en.html" + ] + } +} diff --git a/data/event-schemas/examples/m.call.answer.yaml b/data/event-schemas/examples/m.call.answer.yaml new file mode 100644 index 000000000..a4cfc1e16 --- /dev/null +++ b/data/event-schemas/examples/m.call.answer.yaml @@ -0,0 +1,13 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.answer", + "content": { + "version" : 0, + "call_id": "12345", + "lifetime": 60000, + "answer": { + "type" : "answer", + "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" + } + } +} diff --git a/data/event-schemas/examples/m.call.candidates.yaml b/data/event-schemas/examples/m.call.candidates.yaml new file mode 100644 index 000000000..8f1f807ad --- /dev/null +++ b/data/event-schemas/examples/m.call.candidates.yaml @@ -0,0 +1,15 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.candidates", + "content": { + "version" : 0, + "call_id": "12345", + "candidates": [ + { + "sdpMid": "audio", + "sdpMLineIndex": 0, + "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0" + } + ] + } +} diff --git a/data/event-schemas/examples/m.call.hangup.yaml b/data/event-schemas/examples/m.call.hangup.yaml new file mode 100644 index 000000000..295f16e48 --- /dev/null +++ b/data/event-schemas/examples/m.call.hangup.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.hangup", + "content": { + "version" : 0, + "call_id": "12345" + } +} diff --git a/data/event-schemas/examples/m.call.invite.yaml b/data/event-schemas/examples/m.call.invite.yaml new file mode 100644 index 000000000..fa482bd94 --- /dev/null +++ b/data/event-schemas/examples/m.call.invite.yaml @@ -0,0 +1,13 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.invite", + "content": { + "version" : 0, + "call_id": "12345", + "lifetime": 60000, + "offer": { + "type" : "offer", + "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" + } + } +} diff --git a/data/event-schemas/examples/m.direct.yaml b/data/event-schemas/examples/m.direct.yaml new file mode 100644 index 000000000..e453dd599 --- /dev/null +++ b/data/event-schemas/examples/m.direct.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/event.json", + "type": "m.direct", + "content": { + "@bob:example.com": [ + "!abcdefgh:example.com", + "!hgfedcba:example.com" + ] + } +} diff --git a/data/event-schemas/examples/m.dummy.yaml b/data/event-schemas/examples/m.dummy.yaml new file mode 100644 index 000000000..0cd39166f --- /dev/null +++ b/data/event-schemas/examples/m.dummy.yaml @@ -0,0 +1,4 @@ +{ + "content": {}, + "type": "m.dummy" +} diff --git a/data/event-schemas/examples/m.forwarded_room_key.yaml b/data/event-schemas/examples/m.forwarded_room_key.yaml new file mode 100644 index 000000000..ef1d6180b --- /dev/null +++ b/data/event-schemas/examples/m.forwarded_room_key.yaml @@ -0,0 +1,14 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...", + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y", + "forwarding_curve25519_key_chain": [ + "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" + ] + }, + "type": "m.forwarded_room_key" +} diff --git a/data/event-schemas/examples/m.fully_read.yaml b/data/event-schemas/examples/m.fully_read.yaml new file mode 100644 index 000000000..0af2a6ea6 --- /dev/null +++ b/data/event-schemas/examples/m.fully_read.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/event.json", + "type": "m.fully_read", + "room_id": "!somewhere:example.org", + "content": { + "event_id": "$someplace:example.org" + } +} diff --git a/data/event-schemas/examples/m.identity_server.yaml b/data/event-schemas/examples/m.identity_server.yaml new file mode 100644 index 000000000..32855e9ce --- /dev/null +++ b/data/event-schemas/examples/m.identity_server.yaml @@ -0,0 +1,7 @@ +{ + "$ref": "core/event.json", + "type": "m.identity_server", + "content": { + "base_url": "https://example.org" + } +} diff --git a/data/event-schemas/examples/m.ignored_user_list.yaml b/data/event-schemas/examples/m.ignored_user_list.yaml new file mode 100644 index 000000000..83def6e47 --- /dev/null +++ b/data/event-schemas/examples/m.ignored_user_list.yaml @@ -0,0 +1,9 @@ +{ + "$ref": "core/event.json", + "type": "m.ignored_user_list", + "content": { + "ignored_users": { + "@someone:example.org": {} + } + } +} diff --git a/data/event-schemas/examples/m.key.verification.accept.yaml b/data/event-schemas/examples/m.key.verification.accept.yaml new file mode 100644 index 000000000..98e89c06e --- /dev/null +++ b/data/event-schemas/examples/m.key.verification.accept.yaml @@ -0,0 +1,12 @@ +{ + "type": "m.key.verification.accept", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "method": "m.sas.v1", + "key_agreement_protocol": "curve25519", + "hash": "sha256", + "message_authentication_code": "hkdf-hmac-sha256", + "short_authentication_string": ["decimal", "emoji"], + "commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } +} diff --git a/data/event-schemas/examples/m.key.verification.cancel.yaml b/data/event-schemas/examples/m.key.verification.cancel.yaml new file mode 100644 index 000000000..9d78f67c5 --- /dev/null +++ b/data/event-schemas/examples/m.key.verification.cancel.yaml @@ -0,0 +1,8 @@ +{ + "type": "m.key.verification.cancel", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "code": "m.user", + "reason": "User rejected the key verification request" + } +} diff --git a/data/event-schemas/examples/m.key.verification.key.yaml b/data/event-schemas/examples/m.key.verification.key.yaml new file mode 100644 index 000000000..608a2ebd3 --- /dev/null +++ b/data/event-schemas/examples/m.key.verification.key.yaml @@ -0,0 +1,7 @@ +{ + "type": "m.key.verification.key", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } +} diff --git a/data/event-schemas/examples/m.key.verification.mac.yaml b/data/event-schemas/examples/m.key.verification.mac.yaml new file mode 100644 index 000000000..c77c3a8d9 --- /dev/null +++ b/data/event-schemas/examples/m.key.verification.mac.yaml @@ -0,0 +1,10 @@ +{ + "type": "m.key.verification.mac", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA", + "mac": { + "ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } +} diff --git a/data/event-schemas/examples/m.key.verification.request.yaml b/data/event-schemas/examples/m.key.verification.request.yaml new file mode 100644 index 000000000..258471d29 --- /dev/null +++ b/data/event-schemas/examples/m.key.verification.request.yaml @@ -0,0 +1,11 @@ +{ + "type": "m.key.verification.request", + "content": { + "from_device": "AliceDevice2", + "transaction_id": "S0meUniqueAndOpaqueString", + "methods": [ + "m.sas.v1" + ], + "timestamp": 1559598944869 + } +} diff --git a/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml new file mode 100644 index 000000000..dae1d4053 --- /dev/null +++ b/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml @@ -0,0 +1,12 @@ +{ + "type": "m.key.verification.start", + "content": { + "from_device": "BobDevice1", + "transaction_id": "S0meUniqueAndOpaqueString", + "method": "m.sas.v1", + "key_agreement_protocols": ["curve25519"], + "hashes": ["sha256"], + "message_authentication_codes": ["hkdf-hmac-sha256"], + "short_authentication_string": ["decimal", "emoji"] + } +} diff --git a/data/event-schemas/examples/m.key.verification.start.yaml b/data/event-schemas/examples/m.key.verification.start.yaml new file mode 100644 index 000000000..52f16150f --- /dev/null +++ b/data/event-schemas/examples/m.key.verification.start.yaml @@ -0,0 +1,8 @@ +{ + "type": "m.key.verification.start", + "content": { + "from_device": "BobDevice1", + "transaction_id": "S0meUniqueAndOpaqueString", + "method": "m.sas.v1" + } +} diff --git a/data/event-schemas/examples/m.policy.rule.room.yaml b/data/event-schemas/examples/m.policy.rule.room.yaml new file mode 100644 index 000000000..5a532cb5d --- /dev/null +++ b/data/event-schemas/examples/m.policy.rule.room.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/state_event.json", + "type": "m.policy.rule.room", + "state_key": "rule:#*:example.org", + "content": { + "entity": "#*:example.org", + "recommendation": "m.ban", + "reason": "undesirable content" + } +} diff --git a/data/event-schemas/examples/m.policy.rule.server.yaml b/data/event-schemas/examples/m.policy.rule.server.yaml new file mode 100644 index 000000000..3d740a286 --- /dev/null +++ b/data/event-schemas/examples/m.policy.rule.server.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/state_event.json", + "type": "m.policy.rule.server", + "state_key": "rule:*.example.org", + "content": { + "entity": "*.example.org", + "recommendation": "m.ban", + "reason": "undesirable engagement" + } +} diff --git a/data/event-schemas/examples/m.policy.rule.user.yaml b/data/event-schemas/examples/m.policy.rule.user.yaml new file mode 100644 index 000000000..eb3832da9 --- /dev/null +++ b/data/event-schemas/examples/m.policy.rule.user.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/state_event.json", + "type": "m.policy.rule.user", + "state_key": "rule:@alice*:example.org", + "content": { + "entity": "@alice*:example.org", + "recommendation": "m.ban", + "reason": "undesirable behaviour" + } +} diff --git a/data/event-schemas/examples/m.presence.yaml b/data/event-schemas/examples/m.presence.yaml new file mode 100644 index 000000000..ec4ce6e03 --- /dev/null +++ b/data/event-schemas/examples/m.presence.yaml @@ -0,0 +1,12 @@ +{ + "$ref": "core/event.json", + "sender": "@example:localhost", + "type": "m.presence", + "content": { + "avatar_url": "mxc://localhost:wefuiwegh8742w", + "last_active_ago": 2478593, + "presence": "online", + "currently_active": false, + "status_msg": "Making cupcakes" + } +} diff --git a/data/event-schemas/examples/m.push_rules.yaml b/data/event-schemas/examples/m.push_rules.yaml new file mode 100644 index 000000000..34bc2fe6e --- /dev/null +++ b/data/event-schemas/examples/m.push_rules.yaml @@ -0,0 +1,197 @@ +{ + "$ref": "core/event.json", + "type": "m.push_rules", + "content": { + "global": { + "content": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "default": true, + "enabled": true, + "pattern": "alice", + "rule_id": ".m.rule.contains_user_name" + } + ], + "override": [ + { + "actions": [ + "dont_notify" + ], + "conditions": [], + "default": true, + "enabled": false, + "rule_id": ".m.rule.master" + }, + { + "actions": [ + "dont_notify" + ], + "conditions": [ + { + "key": "content.msgtype", + "kind": "event_match", + "pattern": "m.notice" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.suppress_notices" + } + ], + "room": [], + "sender": [], + "underride": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.call" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "conditions": [ + { + "kind": "contains_display_name" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.contains_display_name" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.room_one_to_one" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, + { + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.invite_for_me" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.member_event" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.message" + } + ] + } + } +} diff --git a/data/event-schemas/examples/m.receipt.yaml b/data/event-schemas/examples/m.receipt.yaml new file mode 100644 index 000000000..c52d8540f --- /dev/null +++ b/data/event-schemas/examples/m.receipt.yaml @@ -0,0 +1,13 @@ +{ + "$ref": "core/room_edu.json", + "type": "m.receipt", + "content": { + "$1435641916114394fHBLK:matrix.org": { + "m.read": { + "@rikj:jki.re": { + "ts": 1436451550453 + } + } + } + } +} diff --git a/data/event-schemas/examples/m.room.avatar.yaml b/data/event-schemas/examples/m.room.avatar.yaml new file mode 100644 index 000000000..cf0d17f3e --- /dev/null +++ b/data/event-schemas/examples/m.room.avatar.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.avatar", + "state_key": "", + "content": { + "info": { + "h": 398, + "w": 394, + "mimetype": "image/jpeg", + "size": 31037 + }, + "url": "mxc://example.org/JWEIFJgwEIhweiWJE" + } +} diff --git a/data/event-schemas/examples/m.room.canonical_alias.yaml b/data/event-schemas/examples/m.room.canonical_alias.yaml new file mode 100644 index 000000000..698c11b84 --- /dev/null +++ b/data/event-schemas/examples/m.room.canonical_alias.yaml @@ -0,0 +1,12 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.canonical_alias", + "state_key": "", + "content": { + "alias": "#somewhere:localhost", + "alt_aliases": [ + "#somewhere:example.org", + "#myroom:example.com" + ] + } +} diff --git a/data/event-schemas/examples/m.room.create.yaml b/data/event-schemas/examples/m.room.create.yaml new file mode 100644 index 000000000..e33dbc3ba --- /dev/null +++ b/data/event-schemas/examples/m.room.create.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.create", + "state_key": "", + "content": { + "creator": "@example:example.org", + "room_version": "1", + "m.federate": true, + "predecessor": { + "event_id": "$something:example.org", + "room_id": "!oldroom:example.org" + } + } +} diff --git a/data/event-schemas/examples/m.room.encrypted$megolm.yaml b/data/event-schemas/examples/m.room.encrypted$megolm.yaml new file mode 100644 index 000000000..ac542e254 --- /dev/null +++ b/data/event-schemas/examples/m.room.encrypted$megolm.yaml @@ -0,0 +1,11 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.encrypted", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...", + "device_id": "RJYKSTBOIE", + "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" + } +} diff --git a/data/event-schemas/examples/m.room.encrypted$olm.yaml b/data/event-schemas/examples/m.room.encrypted$olm.yaml new file mode 100644 index 000000000..381651d95 --- /dev/null +++ b/data/event-schemas/examples/m.room.encrypted$olm.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.encrypted", + "content": { + "algorithm": "m.olm.v1.curve25519-aes-sha2", + "sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU", + "ciphertext": { + "7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": { + "type": 0, + "body": "AwogGJJzMhf/S3GQFXAOrCZ3iKyGU5ZScVtjI0KypTYrW..." + } + } + } +} diff --git a/data/event-schemas/examples/m.room.encryption.yaml b/data/event-schemas/examples/m.room.encryption.yaml new file mode 100644 index 000000000..6158b9379 --- /dev/null +++ b/data/event-schemas/examples/m.room.encryption.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.encryption", + "state_key": "", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "rotation_period_ms": 604800000, + "rotation_period_msgs": 100 + } +} diff --git a/data/event-schemas/examples/m.room.guest_access.yaml b/data/event-schemas/examples/m.room.guest_access.yaml new file mode 100644 index 000000000..a6deff8c0 --- /dev/null +++ b/data/event-schemas/examples/m.room.guest_access.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.guest_access", + "state_key": "", + "content": { + "guest_access": "can_join" + } +} diff --git a/data/event-schemas/examples/m.room.history_visibility.yaml b/data/event-schemas/examples/m.room.history_visibility.yaml new file mode 100644 index 000000000..27c4fec35 --- /dev/null +++ b/data/event-schemas/examples/m.room.history_visibility.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.history_visibility", + "state_key": "", + "content": { + "history_visibility": "shared" + } +} diff --git a/data/event-schemas/examples/m.room.join_rules.yaml b/data/event-schemas/examples/m.room.join_rules.yaml new file mode 100644 index 000000000..2873be781 --- /dev/null +++ b/data/event-schemas/examples/m.room.join_rules.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.join_rules", + "state_key": "", + "content": { + "join_rule": "public" + } +} diff --git a/data/event-schemas/examples/m.room.member$invite_room_state.yaml b/data/event-schemas/examples/m.room.member$invite_room_state.yaml new file mode 100644 index 000000000..d2c465aaa --- /dev/null +++ b/data/event-schemas/examples/m.room.member$invite_room_state.yaml @@ -0,0 +1,15 @@ +{ + "$ref": "m.room.member", + "content": { + "membership": "invite", + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", + "displayname": "Alice Margatroid", + "reason": "Looking for support" + }, + "unsigned": { + "age": 1234, + "invite_room_state": { + "$ref": "invite_room_state.json" + } + } +} diff --git a/data/event-schemas/examples/m.room.member$third_party_invite.yaml b/data/event-schemas/examples/m.room.member$third_party_invite.yaml new file mode 100644 index 000000000..a40d44f99 --- /dev/null +++ b/data/event-schemas/examples/m.room.member$third_party_invite.yaml @@ -0,0 +1,20 @@ +{ + "$ref": "m.room.member", + "content": { + "membership": "invite", + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", + "displayname": "Alice Margatroid", + "third_party_invite": { + "display_name": "alice", + "signed": { + "mxid": "@alice:example.org", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + }, + "token": "abc123" + } + } + } +} diff --git a/data/event-schemas/examples/m.room.member.yaml b/data/event-schemas/examples/m.room.member.yaml new file mode 100644 index 000000000..5147b258f --- /dev/null +++ b/data/event-schemas/examples/m.room.member.yaml @@ -0,0 +1,11 @@ +{ + "$ref": "core/state_event.json", + "state_key": "@alice:example.org", + "type": "m.room.member", + "content": { + "membership": "join", + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", + "displayname": "Alice Margatroid", + "reason": "Looking for support" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.audio.yaml b/data/event-schemas/examples/m.room.message$m.audio.yaml new file mode 100644 index 000000000..58e874e0c --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.audio.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "Bee Gees - Stayin' Alive", + "url": "mxc://example.org/ffed755USFFxlgbQYZGtryd", + "info": { + "duration": 2140786, + "size": 1563685, + "mimetype": "audio/mpeg" + }, + "msgtype": "m.audio" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.emote.yaml b/data/event-schemas/examples/m.room.message$m.emote.yaml new file mode 100644 index 000000000..5fecb9a3f --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.emote.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "thinks this is an example emote", + "msgtype": "m.emote", + "format": "org.matrix.custom.html", + "formatted_body": "thinks this is an example emote" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.file.yaml b/data/event-schemas/examples/m.room.message$m.file.yaml new file mode 100644 index 000000000..c375861bd --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.file.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "something-important.doc", + "filename": "something-important.doc", + "info": { + "mimetype": "application/msword", + "size": 46144 + }, + "msgtype": "m.file", + "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.image.yaml b/data/event-schemas/examples/m.room.message$m.image.yaml new file mode 100644 index 000000000..a0e38c822 --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.image.yaml @@ -0,0 +1,15 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "filename.jpg", + "info": { + "h": 398, + "w": 394, + "mimetype": "image/jpeg", + "size": 31037 + }, + "url": "mxc://example.org/JWEIFJgwEIhweiWJE", + "msgtype": "m.image" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.location.yaml b/data/event-schemas/examples/m.room.message$m.location.yaml new file mode 100644 index 000000000..49820419d --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.location.yaml @@ -0,0 +1,18 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "Big Ben, London, UK", + "geo_uri": "geo:51.5008,0.1247", + "info": { + "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe", + "thumbnail_info": { + "mimetype": "image/jpeg", + "size": 46144, + "w": 300, + "h": 300 + } + }, + "msgtype": "m.location" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.notice.yaml b/data/event-schemas/examples/m.room.message$m.notice.yaml new file mode 100644 index 000000000..d33751da3 --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.notice.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "This is an example notice", + "msgtype": "m.notice", + "format": "org.matrix.custom.html", + "formatted_body": "This is an example notice" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.server_notice.yaml b/data/event-schemas/examples/m.room.message$m.server_notice.yaml new file mode 100644 index 000000000..0eb44ea7f --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.server_notice.yaml @@ -0,0 +1,11 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "Human-readable message to explain the notice", + "msgtype": "m.server_notice", + "server_notice_type": "m.server_notice.usage_limit_reached", + "admin_contact": "mailto:server.admin@example.org", + "limit_type": "monthly_active_user" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.text.yaml b/data/event-schemas/examples/m.room.message$m.text.yaml new file mode 100644 index 000000000..ba1fb7697 --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.text.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "This is an example text message", + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "formatted_body": "This is an example text message" + } +} diff --git a/data/event-schemas/examples/m.room.message$m.video.yaml b/data/event-schemas/examples/m.room.message$m.video.yaml new file mode 100644 index 000000000..71f19a666 --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.video.yaml @@ -0,0 +1,23 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "Gangnam Style", + "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442", + "info": { + "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe", + "thumbnail_info": { + "mimetype": "image/jpeg", + "size": 46144, + "w": 300, + "h": 300 + }, + "w": 480, + "h": 320, + "duration": 2140786, + "size": 1563685, + "mimetype": "video/mp4" + }, + "msgtype": "m.video" + } +} diff --git a/data/event-schemas/examples/m.room.message.feedback.yaml b/data/event-schemas/examples/m.room.message.feedback.yaml new file mode 100644 index 000000000..e146e8743 --- /dev/null +++ b/data/event-schemas/examples/m.room.message.feedback.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message.feedback", + "content": { + "type": "delivered", + "target_event_id": "$WEIGFHFW:localhost" + } +} diff --git a/data/event-schemas/examples/m.room.name.yaml b/data/event-schemas/examples/m.room.name.yaml new file mode 100644 index 000000000..e77e2b53a --- /dev/null +++ b/data/event-schemas/examples/m.room.name.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.name", + "state_key": "", + "content": { + "name": "The room name" + } +} diff --git a/data/event-schemas/examples/m.room.pinned_events.yaml b/data/event-schemas/examples/m.room.pinned_events.yaml new file mode 100644 index 000000000..5bf31f05f --- /dev/null +++ b/data/event-schemas/examples/m.room.pinned_events.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.pinned_events", + "state_key": "", + "content": { + "pinned": ["$someevent:example.org"] + } +} diff --git a/data/event-schemas/examples/m.room.power_levels.yaml b/data/event-schemas/examples/m.room.power_levels.yaml new file mode 100644 index 000000000..ad741e88e --- /dev/null +++ b/data/event-schemas/examples/m.room.power_levels.yaml @@ -0,0 +1,24 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.power_levels", + "state_key": "", + "content": { + "ban": 50, + "events": { + "m.room.name": 100, + "m.room.power_levels": 100 + }, + "events_default": 0, + "invite": 50, + "kick": 50, + "redact": 50, + "state_default": 50, + "users": { + "@example:localhost": 100 + }, + "users_default": 0, + "notifications": { + "room": 20 + } + } +} diff --git a/data/event-schemas/examples/m.room.redaction.yaml b/data/event-schemas/examples/m.room.redaction.yaml new file mode 100644 index 000000000..42bc84115 --- /dev/null +++ b/data/event-schemas/examples/m.room.redaction.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.redaction", + "redacts": "$fukweghifu23:localhost", + "content": { + "reason": "Spamming" + } +} diff --git a/data/event-schemas/examples/m.room.server_acl.yaml b/data/event-schemas/examples/m.room.server_acl.yaml new file mode 100644 index 000000000..06586f79f --- /dev/null +++ b/data/event-schemas/examples/m.room.server_acl.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.server_acl", + "state_key": "", + "content": { + "allow_ip_literals": false, + "allow": ["*"], + "deny": ["*.evil.com", "evil.com"] + } +} diff --git a/data/event-schemas/examples/m.room.third_party_invite.yaml b/data/event-schemas/examples/m.room.third_party_invite.yaml new file mode 100644 index 000000000..03f35375e --- /dev/null +++ b/data/event-schemas/examples/m.room.third_party_invite.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.third_party_invite", + "state_key": "pc98", + "content": { + "display_name": "Alice Margatroid", + "key_validity_url": "https://magic.forest/verifykey", + "public_key": "abc123", + "public_keys": [{ + "public_key": "def456", + "key_validity_url": "https://magic.forest/verifykey" + }] + } +} diff --git a/data/event-schemas/examples/m.room.tombstone.yaml b/data/event-schemas/examples/m.room.tombstone.yaml new file mode 100644 index 000000000..b62244764 --- /dev/null +++ b/data/event-schemas/examples/m.room.tombstone.yaml @@ -0,0 +1,9 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.tombstone", + "state_key": "", + "content": { + "body": "This room has been replaced", + "replacement_room": "!newroom:example.org" + } +} diff --git a/data/event-schemas/examples/m.room.topic.yaml b/data/event-schemas/examples/m.room.topic.yaml new file mode 100644 index 000000000..69e5d4f1c --- /dev/null +++ b/data/event-schemas/examples/m.room.topic.yaml @@ -0,0 +1,8 @@ +{ + "$ref": "core/state_event.json", + "type": "m.room.topic", + "state_key": "", + "content": { + "topic": "A room topic" + } +} diff --git a/data/event-schemas/examples/m.room_key.withheld.yaml b/data/event-schemas/examples/m.room_key.withheld.yaml new file mode 100644 index 000000000..fa8f135f1 --- /dev/null +++ b/data/event-schemas/examples/m.room_key.withheld.yaml @@ -0,0 +1,12 @@ +{ + "$ref": "core/event.json", + "type": "m.room_key.withheld", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "code": "m.unverified", + "reason": "Device not verified" + } +} diff --git a/data/event-schemas/examples/m.room_key.yaml b/data/event-schemas/examples/m.room_key.yaml new file mode 100644 index 000000000..dba497b42 --- /dev/null +++ b/data/event-schemas/examples/m.room_key.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/event.json", + "type": "m.room_key", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." + } +} diff --git a/data/event-schemas/examples/m.room_key_request$cancel_request.yaml b/data/event-schemas/examples/m.room_key_request$cancel_request.yaml new file mode 100644 index 000000000..afc1c350b --- /dev/null +++ b/data/event-schemas/examples/m.room_key_request$cancel_request.yaml @@ -0,0 +1,8 @@ +{ + "content": { + "action": "request_cancellation", + "requesting_device_id": "RJYKSTBOIE", + "request_id": "1495474790150.19" + }, + "type": "m.room_key_request" +} diff --git a/data/event-schemas/examples/m.room_key_request$request.yaml b/data/event-schemas/examples/m.room_key_request$request.yaml new file mode 100644 index 000000000..8557f08e8 --- /dev/null +++ b/data/event-schemas/examples/m.room_key_request$request.yaml @@ -0,0 +1,14 @@ +{ + "content": { + "body": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU" + }, + "action": "request", + "requesting_device_id": "RJYKSTBOIE", + "request_id": "1495474790150.19" + }, + "type": "m.room_key_request" +} diff --git a/data/event-schemas/examples/m.sticker.yaml b/data/event-schemas/examples/m.sticker.yaml new file mode 100644 index 000000000..971cdc905 --- /dev/null +++ b/data/event-schemas/examples/m.sticker.yaml @@ -0,0 +1,21 @@ +{ + "$ref": "core/room_event.json", + "type": "m.sticker", + "content": { + "body": "Landing", + "info": { + "mimetype": "image/png", + "thumbnail_info": { + "mimetype": "image/png", + "h": 200, + "w": 140, + "size": 73602 + }, + "h": 200, + "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP", + "w": 140, + "size": 73602 + }, + "url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP" + } +} diff --git a/data/event-schemas/examples/m.tag.yaml b/data/event-schemas/examples/m.tag.yaml new file mode 100644 index 000000000..7e56b1ea1 --- /dev/null +++ b/data/event-schemas/examples/m.tag.yaml @@ -0,0 +1,9 @@ +{ + "$ref": "core/event.json", + "type": "m.tag", + "content": { + "tags": { + "u.work": {"order": 0.9} + } + } +} diff --git a/data/event-schemas/examples/m.typing.yaml b/data/event-schemas/examples/m.typing.yaml new file mode 100644 index 000000000..416b99688 --- /dev/null +++ b/data/event-schemas/examples/m.typing.yaml @@ -0,0 +1,7 @@ +{ + "$ref": "core/room_edu.json", + "type": "m.typing", + "content": { + "user_ids": ["@alice:matrix.org", "@bob:example.com"] + } +} diff --git a/data/event-schemas/moderation_policy_rule.yaml b/data/event-schemas/moderation_policy_rule.yaml new file mode 100644 index 000000000..a57a1ffe7 --- /dev/null +++ b/data/event-schemas/moderation_policy_rule.yaml @@ -0,0 +1,30 @@ +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +properties: + entity: + description: |- + The entity affected by this rule. Glob characters `*` and `?` can be used + to match zero or more and one or more characters respectively. + type: string + recommendation: + description: The suggested action to take. Currently only `m.ban` is specified. + type: string + reason: + description: The human-readable description for the `recommendation`. + type: string +type: object +required: + - entity + - recommendation + - reason diff --git a/data/event-schemas/schema/core-event-schema/event.yaml b/data/event-schemas/schema/core-event-schema/event.yaml new file mode 100644 index 000000000..0fe5ac6c5 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/event.yaml @@ -0,0 +1,15 @@ +description: The basic set of fields all events must have. +properties: + content: + description: The fields in this object will vary depending on the type of event. + When interacting with the REST API, this is the HTTP body. + type: object + type: + description: The type of event. This SHOULD be namespaced similar to Java package + naming conventions e.g. 'com.example.subdomain.event.type' + type: string +required: + - type + - content +title: Event +type: object diff --git a/data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml new file mode 100644 index 000000000..b83bf6c13 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -0,0 +1,37 @@ +$schema: http://json-schema.org/draft-04/schema# +description: Metadata about an image. +properties: + h: + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + w: + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + mimetype: + description: The mimetype of the image, e.g. `image/jpeg`. + type: string + size: + description: Size of the image in bytes. + type: integer + thumbnail_url: + description: |- + The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) to a thumbnail of the image. + Only present if the thumbnail is unencrypted. + type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + Only present if the thumbnail is encrypted. + title: EncryptedFile + type: object + thumbnail_info: + allOf: + - $ref: thumbnail_info.yaml + description: Metadata about the image referred to in `thumbnail_url`. +title: ImageInfo +type: object diff --git a/data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml b/data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml new file mode 100644 index 000000000..79f7c2532 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml @@ -0,0 +1,21 @@ +$schema: http://json-schema.org/draft-04/schema# +description: Metadata about a thumbnail image. +properties: + h: + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + w: + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + mimetype: + description: The mimetype of the image, e.g. `image/jpeg`. + type: string + size: + description: Size of the image in bytes. + type: integer +title: ThumbnailInfo +type: object diff --git a/data/event-schemas/schema/core-event-schema/room_event.yaml b/data/event-schemas/schema/core-event-schema/room_event.yaml new file mode 100644 index 000000000..7eaae2236 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/room_event.yaml @@ -0,0 +1,13 @@ +allOf: +- $ref: sync_room_event.yaml +description: Room Events have the following fields. +properties: + room_id: + description: |- + The ID of the room associated with this event. Will not be present on events + that arrive through `/sync`, despite being required everywhere else. + type: string +required: +- room_id +title: RoomEvent +type: object diff --git a/data/event-schemas/schema/core-event-schema/state_event.yaml b/data/event-schemas/schema/core-event-schema/state_event.yaml new file mode 100644 index 000000000..d2ff5243e --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/state_event.yaml @@ -0,0 +1,6 @@ +allOf: +- $ref: room_event.yaml +- $ref: sync_state_event.yaml +description: State Events have the following fields. +title: StateEvent +type: object diff --git a/data/event-schemas/schema/core-event-schema/sync_room_event.yaml b/data/event-schemas/schema/core-event-schema/sync_room_event.yaml new file mode 100644 index 000000000..7ad7191b5 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/sync_room_event.yaml @@ -0,0 +1,43 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Note: this is technically not a core event schema, however it is included here +# to keep things sane. The short story is that /sync doesn't require a room_id to +# be on events, so we give it a whole event structure as a base for room_event. +# This base doesn't declare a room_id, which instead appears in the room_event. + +allOf: +- $ref: event.yaml +description: In addition to the Event fields, Room Events have the following additional + fields. +properties: + event_id: + description: The globally unique event identifier. + type: string + sender: + description: Contains the fully-qualified ID of the user who sent this event. + type: string + origin_server_ts: + description: Timestamp in milliseconds on originating homeserver + when this event was sent. + type: integer + format: int64 + unsigned: + $ref: unsigned_prop.yaml +required: +- event_id +- sender +- origin_server_ts +title: SyncRoomEvent +type: object diff --git a/data/event-schemas/schema/core-event-schema/sync_state_event.yaml b/data/event-schemas/schema/core-event-schema/sync_state_event.yaml new file mode 100644 index 000000000..e7a061f52 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -0,0 +1,39 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# See sync_room_event.yaml for why this file is here. + +allOf: +- $ref: sync_room_event.yaml +description: In addition to the Room Event fields, State Events have the following + additional fields. +properties: + prev_content: + description: Optional. The previous `content` for this event. If there is no + previous content, this key will be missing. + title: EventContent + type: object + state_key: + description: A unique key which defines the overwriting semantics for this piece + of room state. This value is often a zero-length string. The presence of this + key makes this event a State Event. + + State keys starting with an `@` are reserved for referencing user IDs, such + as room members. With the exception of a few events, state events set with a + given user's ID as the state key MUST only be set by that user. + type: string +required: +- state_key +title: SyncStateEvent +type: object diff --git a/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml b/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml new file mode 100644 index 000000000..aace29ffd --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml @@ -0,0 +1,34 @@ +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +title: UnsignedData +type: object +description: Contains optional extra information about the event. +properties: + age: + description: The time in milliseconds that has elapsed since the event was + sent. This field is generated by the local homeserver, and may be incorrect + if the local time on at least one of the two servers is out of sync, which can + cause the age to either be negative or greater than it actually is. + type: integer + redacted_because: + description: The event that redacted this event, if any. + title: Event + type: object + transaction_id: + description: | + The client-supplied transaction ID, for example, provided via + `PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}`, + if the client being given the event is the same one which sent it. + type: string diff --git a/data/event-schemas/schema/m.accepted_terms.yaml b/data/event-schemas/schema/m.accepted_terms.yaml new file mode 100644 index 000000000..510e741d6 --- /dev/null +++ b/data/event-schemas/schema/m.accepted_terms.yaml @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + A list of terms URLs the user has previously accepted. Clients SHOULD use this + to avoid presenting the user with terms they have already agreed to. +properties: + content: + type: object + properties: + accepted: + type: array + items: + type: string + description: |- + The list of URLs the user has previously accepted. Should be appended to + when the user agrees to new terms. + type: + enum: + - m.accepted_terms + type: string +title: Accepted Terms of Service URLs +type: object diff --git a/data/event-schemas/schema/m.call.answer.yaml b/data/event-schemas/schema/m.call.answer.yaml new file mode 100644 index 000000000..9d98dd7d2 --- /dev/null +++ b/data/event-schemas/schema/m.call.answer.yaml @@ -0,0 +1,44 @@ +{ + "type": "object", + "description": "This event is sent by the callee when they wish to answer the call.", + "allOf": [{ + "$ref": "core-event-schema/room_event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "call_id": { + "type": "string", + "description": "The ID of the call this event relates to." + }, + "answer": { + "type": "object", + "title": "Answer", + "description": "The session description object", + "properties": { + "type": { + "type": "string", + "enum": ["answer"], + "description": "The type of session description." + }, + "sdp": { + "type": "string", + "description": "The SDP text of the session description." + } + }, + "required": ["type", "sdp"] + }, + "version": { + "type": "number", + "description": "" + } + }, + "required": ["call_id", "answer", "version"] + }, + "type": { + "type": "string", + "enum": ["m.call.answer"] + } + } +} diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml new file mode 100644 index 000000000..7426717c6 --- /dev/null +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -0,0 +1,50 @@ +{ + "type": "object", + "description": "This event is sent by callers after sending an invite and by the callee after answering. Its purpose is to give the other party additional ICE candidates to try using to communicate.", + "allOf": [{ + "$ref": "core-event-schema/room_event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "call_id": { + "type": "string", + "description": "The ID of the call this event relates to." + }, + "candidates": { + "type": "array", + "description": "Array of objects describing the candidates.", + "items": { + "type": "object", + "title": "Candidate", + "properties": { + "sdpMid": { + "type": "string", + "description": "The SDP media type this candidate is intended for." + }, + "sdpMLineIndex": { + "type": "number", + "description": "The index of the SDP 'm' line this candidate is intended for." + }, + "candidate": { + "type": "string", + "description": "The SDP 'a' line of the candidate." + } + }, + "required": ["candidate", "sdpMLineIndex", "sdpMid"] + } + }, + "version": { + "type": "integer", + "description": "The version of the VoIP specification this messages adheres to. This specification is version 0." + } + }, + "required": ["call_id", "candidates", "version"] + }, + "type": { + "type": "string", + "enum": ["m.call.candidates"] + } + } +} diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml new file mode 100644 index 000000000..116d5af7d --- /dev/null +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -0,0 +1,35 @@ +{ + "type": "object", + "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.", + "allOf": [{ + "$ref": "core-event-schema/room_event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "call_id": { + "type": "string", + "description": "The ID of the call this event relates to." + }, + "version": { + "type": "integer", + "description": "The version of the VoIP specification this message adheres to. This specification is version 0." + }, + "reason": { + "type": "string", + "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or `invite_timeout` for when the other party did not answer in time.", + "enum": [ + "ice_failed", + "invite_timeout" + ] + } + }, + "required": ["call_id", "version"] + }, + "type": { + "type": "string", + "enum": ["m.call.hangup"] + } + } +} diff --git a/data/event-schemas/schema/m.call.invite.yaml b/data/event-schemas/schema/m.call.invite.yaml new file mode 100644 index 000000000..65796e1e9 --- /dev/null +++ b/data/event-schemas/schema/m.call.invite.yaml @@ -0,0 +1,48 @@ +{ + "type": "object", + "description": "This event is sent by the caller when they wish to establish a call.", + "allOf": [{ + "$ref": "core-event-schema/room_event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "call_id": { + "type": "string", + "description": "A unique identifier for the call." + }, + "offer": { + "type": "object", + "title": "Offer", + "description": "The session description object", + "properties": { + "type": { + "type": "string", + "enum": ["offer"], + "description": "The type of session description." + }, + "sdp": { + "type": "string", + "description": "The SDP text of the session description." + } + }, + "required": ["type", "sdp"] + }, + "version": { + "type": "integer", + "description": "The version of the VoIP specification this message adheres to. This specification is version 0." + }, + "lifetime": { + "type": "integer", + "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI." + } + }, + "required": ["call_id", "offer", "version", "lifetime"] + }, + "type": { + "type": "string", + "enum": ["m.call.invite"] + } + } +} diff --git a/data/event-schemas/schema/m.direct.yaml b/data/event-schemas/schema/m.direct.yaml new file mode 100644 index 000000000..f00b83bce --- /dev/null +++ b/data/event-schemas/schema/m.direct.yaml @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + A map of which rooms are considered 'direct' rooms for specific users + is kept in `account_data` in an event of type `m.direct`. The + content of this event is an object where the keys are the user IDs + and values are lists of room ID strings of the 'direct' rooms for + that user ID. +properties: + content: + additionalProperties: + type: array + title: User ID + items: + type: string + type: object + type: + enum: + - m.direct + type: string +title: Direct Chat Mapping +type: object diff --git a/data/event-schemas/schema/m.dummy.yaml b/data/event-schemas/schema/m.dummy.yaml new file mode 100644 index 000000000..4699dd869 --- /dev/null +++ b/data/event-schemas/schema/m.dummy.yaml @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to indicate new Olm sessions for end-to-end encryption. + Typically it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging) + event. + + The event does not have any content associated with it. The sending client is expected + to send a key share request shortly after this message, causing the receiving client to + process this `m.dummy` event as the most recent event and using the keyshare request + to set up the session. The keyshare request and `m.dummy` combination should result + in the original sending client receiving keys over the newly established session. +properties: + content: + properties: {} + type: object + type: + enum: + - m.dummy + type: string +type: object diff --git a/data/event-schemas/schema/m.forwarded_room_key.yaml b/data/event-schemas/schema/m.forwarded_room_key.yaml new file mode 100644 index 000000000..71ea6690c --- /dev/null +++ b/data/event-schemas/schema/m.forwarded_room_key.yaml @@ -0,0 +1,68 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to forward keys for end-to-end encryption. Typically + it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging) + event. +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm the key in this event is to be used with. + room_id: + type: string + description: The room where the key is used. + sender_key: + type: string + description: |- + The Curve25519 key of the device which initiated the session originally. + session_id: + type: string + description: The ID of the session that the key is for. + session_key: + type: string + description: The key to be exchanged. + sender_claimed_ed25519_key: + type: string + description: |- + The Ed25519 key of the device which initiated the session originally. + It is 'claimed' because the receiving device has no way to tell that the + original room_key actually came from a device which owns the private part of + this key unless they have done device verification. + forwarding_curve25519_key_chain: + type: array + items: + type: string + description: |- + Chain of Curve25519 keys. It starts out empty, but each time the + key is forwarded to another device, the previous sender in the chain is added + to the end of the list. For example, if the key is forwarded from A to B to + C, this field is empty between A and B, and contains A's Curve25519 key between + B and C. + withheld: + type: object + description: |- + Indicates that the key cannot be used to decrypt all the messages + from the session because a portion of the session was withheld as + described in [Reporting that decryption keys are withheld](/client-server-api/#reporting-that-decryption-keys-are-withheld). This + object must include the `code` and `reason` properties from the + `m.room_key.withheld` message that was received by the sender of + this message. + required: + - algorithm + - room_id + - session_id + - session_key + - sender_claimed_ed25519_key + - forwarding_curve25519_key_chain + - sender_key + type: object + type: + enum: + - m.forwarded_room_key + type: string +type: object diff --git a/data/event-schemas/schema/m.fully_read.yaml b/data/event-schemas/schema/m.fully_read.yaml new file mode 100644 index 000000000..51a1942f0 --- /dev/null +++ b/data/event-schemas/schema/m.fully_read.yaml @@ -0,0 +1,29 @@ +{ + "type": "object", + "title": "Read Marker Location Event", + "description": "The current location of the user's read marker in a room. This event appears in the user's room account data for the room the marker is applicable for.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "event_id": { + "type": "string", + "description": "The event the user's read marker is located at in the room." + } + }, + "required": ["event_id"] + }, + "type": { + "type": "string", + "enum": ["m.fully_read"] + }, + "room_id": { + "type": "string", + "description": "The room ID the read marker applies to." + } + }, + "required": ["type", "room_id", "content"] +} diff --git a/data/event-schemas/schema/m.identity_server.yaml b/data/event-schemas/schema/m.identity_server.yaml new file mode 100644 index 000000000..acd0eb92a --- /dev/null +++ b/data/event-schemas/schema/m.identity_server.yaml @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + Persists the user's preferred identity server, or preference to not use + an identity server at all, in the user's account data. +properties: + content: + type: object + properties: + base_url: + type: string + description: |- + The URL of the identity server the user prefers to use, or `null` + if the user does not want to use an identity server. This value is + similar in structure to the `base_url` for identity servers in the + `.well-known/matrix/client` schema. + type: + enum: + - m.identity_server + type: string +title: Identity Server Preference +type: object diff --git a/data/event-schemas/schema/m.ignored_user_list.yaml b/data/event-schemas/schema/m.ignored_user_list.yaml new file mode 100644 index 000000000..0f0b2f85e --- /dev/null +++ b/data/event-schemas/schema/m.ignored_user_list.yaml @@ -0,0 +1,28 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + A map of users which are considered ignored is kept in `account_data` + in an event type of `m.ignored_user_list`. +properties: + content: + type: object + properties: + ignored_users: + type: object + title: "Ignored users" + description: "The map of users to ignore" + patternProperties: + "^@": + type: "object" + title: "Ignored User" + description: "An empty object for future enhancement" + x-pattern: "$USER_ID" + required: + - ignored_users + type: + enum: + - m.ignored_user_list + type: string +title: Ignored User List +type: object diff --git a/data/event-schemas/schema/m.key.verification.accept.yaml b/data/event-schemas/schema/m.key.verification.accept.yaml new file mode 100644 index 000000000..92ff6dfcd --- /dev/null +++ b/data/event-schemas/schema/m.key.verification.accept.yaml @@ -0,0 +1,59 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Accepts a previously sent `m.key.verification.start` message. Typically sent as a + [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be the same as + the one used for the `m.key.verification.start` message. + key_agreement_protocol: + type: string + description: |- + The key agreement protocol the device is choosing to use, out of the + options in the `m.key.verification.start` message. + hash: + type: string + description: |- + The hash method the device is choosing to use, out of the options in + the `m.key.verification.start` message. + message_authentication_code: + type: string + description: |- + The message authentication code the device is choosing to use, out of + the options in the `m.key.verification.start` message. + short_authentication_string: + type: array + description: |- + The SAS methods both devices involved in the verification process + understand. Must be a subset of the options in the `m.key.verification.start` + message. + items: + type: string + enum: ["decimal", "emoji"] + commitment: + type: string + description: |- + The hash (encoded as unpadded base64) of the concatenation of the device's + ephemeral public key (encoded as unpadded base64) and the canonical JSON + representation of the `m.key.verification.start` message. + required: + - transaction_id + - method + - key_agreement_protocol + - hash + - message_authentication_code + - short_authentication_string + - commitment + type: object + type: + enum: + - m.key.verification.accept + type: string +type: object diff --git a/data/event-schemas/schema/m.key.verification.cancel.yaml b/data/event-schemas/schema/m.key.verification.cancel.yaml new file mode 100644 index 000000000..1c6cd8410 --- /dev/null +++ b/data/event-schemas/schema/m.key.verification.cancel.yaml @@ -0,0 +1,68 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Cancels a key verification process/request. Typically sent as a [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + The opaque identifier for the verification process/request. + reason: + type: string + description: |- + A human readable description of the `code`. The client should only rely on this + string if it does not understand the `code`. + code: + type: string + # Note: this is not an enum because we go into detail about the different + # error codes. If we made this an enum, we'd be repeating information. + # Also, we can't put a real bulleted list in here because the HTML2RST parser + # cuts the text at weird points, breaking the list completely. + description: |- + The error code for why the process/request was cancelled by the user. Error + codes should use the Java package naming convention if not in the following + list: + + * `m.user`: The user cancelled the verification. + + * `m.timeout`: The verification process timed out. Verification processes + can define their own timeout parameters. + + * `m.unknown_transaction`: The device does not know about the given transaction + ID. + + * `m.unknown_method`: The device does not know how to handle the requested + method. This should be sent for `m.key.verification.start` messages and + messages defined by individual verification processes. + + * `m.unexpected_message`: The device received an unexpected message. Typically + raised when one of the parties is handling the verification out of order. + + * `m.key_mismatch`: The key was not verified. + + * `m.user_mismatch`: The expected user did not match the user verified. + + * `m.invalid_message`: The message received was invalid. + + * `m.accepted`: A `m.key.verification.request` was accepted by a different + device. The device receiving this error can ignore the verification request. + + Clients should be careful to avoid error loops. For example, if a device sends + an incorrect message and the client returns `m.invalid_message` to which it + gets an unexpected response with `m.unexpected_message`, the client should not + respond again with `m.unexpected_message` to avoid the other device potentially + sending another error response. + required: + - transaction_id + - code + - reason + type: object + type: + enum: + - m.key.verification.cancel + type: string +type: object diff --git a/data/event-schemas/schema/m.key.verification.key.yaml b/data/event-schemas/schema/m.key.verification.key.yaml new file mode 100644 index 000000000..34993bd45 --- /dev/null +++ b/data/event-schemas/schema/m.key.verification.key.yaml @@ -0,0 +1,28 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Sends the ephemeral public key for a device to the partner device. Typically sent as a + [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be the same as + the one used for the `m.key.verification.start` message. + key: + type: string + description: |- + The device's ephemeral public key, encoded as unpadded base64. + required: + - transaction_id + - key + type: object + type: + enum: + - m.key.verification.key + type: string +type: object diff --git a/data/event-schemas/schema/m.key.verification.mac.yaml b/data/event-schemas/schema/m.key.verification.mac.yaml new file mode 100644 index 000000000..eec5d65bf --- /dev/null +++ b/data/event-schemas/schema/m.key.verification.mac.yaml @@ -0,0 +1,38 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Sends the MAC of a device's key to the partner device. Typically sent as a + [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be the same as + the one used for the `m.key.verification.start` message. + mac: + type: object + description: |- + A map of the key ID to the MAC of the key, using the algorithm in the + verification process. The MAC is encoded as unpadded base64. + additionalProperties: + type: string + description: The key's MAC, encoded as unpadded base64. + keys: + type: string + description: |- + The MAC of the comma-separated, sorted, list of key IDs given in the `mac` + property, encoded as unpadded base64. + required: + - transaction_id + - mac + - keys + type: object + type: + enum: + - m.key.verification.mac + type: string +type: object diff --git a/data/event-schemas/schema/m.key.verification.request.yaml b/data/event-schemas/schema/m.key.verification.request.yaml new file mode 100644 index 000000000..05e88b0f9 --- /dev/null +++ b/data/event-schemas/schema/m.key.verification.request.yaml @@ -0,0 +1,43 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Requests a key verification with another user's devices. Typically sent as a + [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + from_device: + type: string + description: |- + The device ID which is initiating the request. + transaction_id: + type: string + description: |- + An opaque identifier for the verification request. Must be unique + with respect to the devices involved. + methods: + type: array + description: |- + The verification methods supported by the sender. + items: + type: string + timestamp: + type: integer + format: int64 + description: |- + The POSIX timestamp in milliseconds for when the request was made. If + the request is in the future by more than 5 minutes or more than 10 + minutes in the past, the message should be ignored by the receiver. + required: + - from_device + - transaction_id + - methods + - timestamp + type: object + type: + enum: + - m.key.verification.request + type: string +type: object diff --git a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml new file mode 100644 index 000000000..aa833549f --- /dev/null +++ b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml @@ -0,0 +1,69 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Begins a SAS key verification process using the `m.sas.v1` method. Typically sent as a [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + from_device: + type: string + description: |- + The device ID which is initiating the process. + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be unique + with respect to the devices involved. Must be the same as the + `transaction_id` given in the `m.key.verification.request` + if this process is originating from a request. + method: + type: string + enum: ["m.sas.v1"] + description: |- + The verification method to use. + key_agreement_protocols: + type: array + description: |- + The key agreement protocols the sending device understands. Should + include at least `curve25519-hkdf-sha256`. + items: + type: string + hashes: + type: array + description: |- + The hash methods the sending device understands. Must include at least + `sha256`. + items: + type: string + message_authentication_codes: + type: array + description: |- + The message authentication codes that the sending device understands. + Must include at least `hkdf-hmac-sha256`. + items: + type: string + short_authentication_string: + type: array + description: |- + The SAS methods the sending device (and the sending device's user) + understands. Must include at least `decimal`. Optionally can include + `emoji`. + items: + type: string + enum: ["decimal", "emoji"] + required: + - from_device + - transaction_id + - method + - key_agreement_protocols + - hashes + - message_authentication_codes + - short_authentication_string + type: object + type: + enum: + - m.key.verification.start + type: string +type: object diff --git a/data/event-schemas/schema/m.key.verification.start.yaml b/data/event-schemas/schema/m.key.verification.start.yaml new file mode 100644 index 000000000..0cc60cb24 --- /dev/null +++ b/data/event-schemas/schema/m.key.verification.start.yaml @@ -0,0 +1,42 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Begins a key verification process. Typically sent as a [to-device](/client-server-api/#send-to-device-messaging) event. The `method` + field determines the type of verification. The fields in the event will differ depending + on the `method`. This definition includes fields that are in common among all variants. +properties: + content: + properties: + from_device: + type: string + description: |- + The device ID which is initiating the process. + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be unique + with respect to the devices involved. Must be the same as the + `transaction_id` given in the `m.key.verification.request` + if this process is originating from a request. + method: + type: string + description: |- + The verification method to use. + next_method: + type: string + description: |- + Optional method to use to verify the other user's key with. Applicable + when the `method` chosen only verifies one user's key. This field will + never be present if the `method` verifies keys both ways. + required: + - from_device + - transaction_id + - method + type: object + type: + enum: + - m.key.verification.start + type: string +type: object diff --git a/data/event-schemas/schema/m.policy.rule.room.yaml b/data/event-schemas/schema/m.policy.rule.room.yaml new file mode 100644 index 000000000..ff81543e3 --- /dev/null +++ b/data/event-schemas/schema/m.policy.rule.room.yaml @@ -0,0 +1,15 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: A moderation policy rule which affects room IDs and room aliases. +properties: + content: + $ref: "../moderation_policy_rule.yaml" + state_key: + description: An arbitrary string decided upon by the sender. + type: string + type: + enum: + - m.policy.rule.room + type: string +type: object diff --git a/data/event-schemas/schema/m.policy.rule.server.yaml b/data/event-schemas/schema/m.policy.rule.server.yaml new file mode 100644 index 000000000..ca37e8ff3 --- /dev/null +++ b/data/event-schemas/schema/m.policy.rule.server.yaml @@ -0,0 +1,15 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: A moderation policy rule which affects servers. +properties: + content: + $ref: "../moderation_policy_rule.yaml" + state_key: + description: An arbitrary string decided upon by the sender. + type: string + type: + enum: + - m.policy.rule.server + type: string +type: object diff --git a/data/event-schemas/schema/m.policy.rule.user.yaml b/data/event-schemas/schema/m.policy.rule.user.yaml new file mode 100644 index 000000000..4fa65ad8a --- /dev/null +++ b/data/event-schemas/schema/m.policy.rule.user.yaml @@ -0,0 +1,15 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: A moderation policy rule which affects users. +properties: + content: + $ref: "../moderation_policy_rule.yaml" + state_key: + description: An arbitrary string decided upon by the sender. + type: string + type: + enum: + - m.policy.rule.user + type: string +type: object diff --git a/data/event-schemas/schema/m.presence.yaml b/data/event-schemas/schema/m.presence.yaml new file mode 100644 index 000000000..540fc7a00 --- /dev/null +++ b/data/event-schemas/schema/m.presence.yaml @@ -0,0 +1,49 @@ +{ + "type": "object", + "title": "Presence Event", + "description": "Informs the client of a user's presence state change.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string", + "description": "The current avatar URL for this user, if any." + }, + "displayname": { + "type": "string", + "description": "The current display name for this user, if any." + }, + "last_active_ago": { + "type": "number", + "description": "The last time since this used performed some action, in milliseconds." + }, + "presence": { + "type": "string", + "description": "The presence state for this user.", + "enum": ["online", "offline", "unavailable"] + }, + "currently_active": { + "type": boolean, + "description": "Whether the user is currently active" + }, + "status_msg": { + "type": "string", + "description": "An optional description to accompany the presence." + } + }, + "required": ["presence"] + }, + "type": { + "type": "string", + "enum": ["m.presence"] + }, + "sender": { + "type": "string" + } + }, + "required": ["sender", "type", "content"] +} diff --git a/data/event-schemas/schema/m.push_rules.yaml b/data/event-schemas/schema/m.push_rules.yaml new file mode 100644 index 000000000..6fde9e148 --- /dev/null +++ b/data/event-schemas/schema/m.push_rules.yaml @@ -0,0 +1,21 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: Describes all push rules for this user. +properties: + content: + properties: + global: + type: object + title: Ruleset + description: The global ruleset + allOf: + - $ref: ../../api/client-server/definitions/push_ruleset.yaml + type: object + type: + enum: + - m.push_rules + type: string +title: Push rules +type: object + diff --git a/data/event-schemas/schema/m.receipt.yaml b/data/event-schemas/schema/m.receipt.yaml new file mode 100644 index 000000000..4b04e6d68 --- /dev/null +++ b/data/event-schemas/schema/m.receipt.yaml @@ -0,0 +1,51 @@ +{ + "type": "object", + "title": "Receipt Event", + "description": "Informs the client of new receipts.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "content": { + "type": "object", + "patternProperties": { + "^\\$": { + "type": "object", + "x-pattern": "$EVENT_ID", + "title": "Receipts", + "description": "The mapping of event ID to a collection of receipts for this event ID. The event ID is the ID of the event being acknowledged and *not* an ID for the receipt itself.", + "properties": { + "m.read": { + "type": "object", + "title": "Users", + "description": "A collection of users who have sent `m.read` receipts for this event.", + "patternProperties": { + "^@": { + "type": "object", + "title": "Receipt", + "description": "The mapping of user ID to receipt. The user ID is the entity who sent this receipt.", + "x-pattern": "$USER_ID", + "properties": { + "ts": { + "type": "number", + "description": "The timestamp the receipt was sent at." + } + } + } + } + } + } + } + }, + "additionalProperties": false + }, + "type": { + "type": "string", + "enum": ["m.receipt"] + }, + "room_id": { + "type": "string" + } + }, + "required": ["room_id", "type", "content"] +} diff --git a/data/event-schemas/schema/m.room.avatar.yaml b/data/event-schemas/schema/m.room.avatar.yaml new file mode 100644 index 000000000..7d4b90b15 --- /dev/null +++ b/data/event-schemas/schema/m.room.avatar.yaml @@ -0,0 +1,27 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: A picture that is associated with the room. This can be displayed alongside the room information. +properties: + content: + properties: + info: + allOf: + - $ref: core-event-schema/msgtype_infos/image_info.yaml + description: Metadata about the image referred to in `url`. + url: + description: The URL to the image. + type: string + required: + - url + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.avatar + type: string +title: RoomAvatar +type: object diff --git a/data/event-schemas/schema/m.room.canonical_alias.yaml b/data/event-schemas/schema/m.room.canonical_alias.yaml new file mode 100644 index 000000000..7547bd3af --- /dev/null +++ b/data/event-schemas/schema/m.room.canonical_alias.yaml @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: |- + This event is used to inform the room about which alias should be + considered the canonical one, and which other aliases point to the room. + This could be for display purposes or as suggestion to users which alias + to use to advertise and access the room. +properties: + content: + properties: + alias: + description: | + The canonical alias for the room. If not present, null, or empty the + room should be considered to have no canonical alias. + type: string + alt_aliases: + description: | + Alternative aliases the room advertises. This list can have aliases + despite the `alias` field being null, empty, or otherwise not present. + type: array + items: + type: string + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.canonical_alias + type: string +title: Informs the room as to which alias is the canonical one. +type: object diff --git a/data/event-schemas/schema/m.room.create.yaml b/data/event-schemas/schema/m.room.create.yaml new file mode 100644 index 000000000..80ff046e9 --- /dev/null +++ b/data/event-schemas/schema/m.room.create.yaml @@ -0,0 +1,41 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: This is the first event in a room and cannot be changed. It acts as the root of all other events. +properties: + content: + properties: + creator: + description: The `user_id` of the room creator. This is set by the homeserver. + type: string + m.federate: + description: Whether users on other servers can join this room. Defaults to `true` if key does not exist. + type: boolean + room_version: + description: The version of the room. Defaults to `"1"` if the key does not exist. + type: string + predecessor: + description: A reference to the room this room replaces, if the previous room was upgraded. + type: object + title: Previous Room + properties: + room_id: + type: string + description: The ID of the old room. + event_id: + type: string + description: The event ID of the last known event in the old room. + required: [room_id, event_id] + required: + - creator + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.create + type: string +title: The first event in the room. +type: object diff --git a/data/event-schemas/schema/m.room.encrypted.yaml b/data/event-schemas/schema/m.room.encrypted.yaml new file mode 100644 index 000000000..32e869029 --- /dev/null +++ b/data/event-schemas/schema/m.room.encrypted.yaml @@ -0,0 +1,61 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used when sending encrypted events. It can be used either + within a room (in which case it will have all of the [Room Event fields](/client-server-api/#room-event-fields)), or + as a [to-device](/client-server-api/#send-to-device-messaging) event. + +properties: + content: + properties: + algorithm: + type: string + enum: + - m.olm.v1.curve25519-aes-sha2 + - m.megolm.v1.aes-sha2 + description: |- + The encryption algorithm used to encrypt this event. The + value of this field determines which other properties will be + present. + ciphertext: + oneOf: + - type: string + - type: object + additionalProperties: + type: object + title: CiphertextInfo + properties: + body: + type: string + description: The encrypted payload. + type: + type: integer + description: The Olm message type. + description: |- + The encrypted content of the event. Either the encrypted payload + itself, in the case of a Megolm event, or a map from the recipient + Curve25519 identity key to ciphertext information, in the case of an + Olm event. For more details, see [Messaging Algorithms](/client-server-api/#messaging-algorithms). + sender_key: + type: string + description: The Curve25519 key of the sender. + device_id: + type: string + description: The ID of the sending device. Required with Megolm. + session_id: + type: string + description: |- + The ID of the session used to encrypt the message. Required with + Megolm. + required: + - algorithm + - sender_key + - ciphertext + type: object + type: + enum: + - m.room.encrypted + type: string +type: object diff --git a/data/event-schemas/schema/m.room.encryption.yaml b/data/event-schemas/schema/m.room.encryption.yaml new file mode 100644 index 000000000..9f443b5eb --- /dev/null +++ b/data/event-schemas/schema/m.room.encryption.yaml @@ -0,0 +1,36 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: Defines how messages sent in this room should be encrypted. +properties: + content: + properties: + algorithm: + type: string + enum: + - "m.megolm.v1.aes-sha2" + description: |- + The encryption algorithm to be used to encrypt messages sent in this + room. + rotation_period_ms: + type: integer + description: |- + How long the session should be used before changing it. `604800000` + (a week) is the recommended default. + rotation_period_msgs: + type: integer + description: |- + How many messages should be sent before changing the session. `100` is the + recommended default. + required: + - algorithm + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.encryption + type: string +type: object diff --git a/data/event-schemas/schema/m.room.guest_access.yaml b/data/event-schemas/schema/m.room.guest_access.yaml new file mode 100644 index 000000000..f886dfe59 --- /dev/null +++ b/data/event-schemas/schema/m.room.guest_access.yaml @@ -0,0 +1,26 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: 'This event controls whether guest users are allowed to join rooms. If this event is absent, servers should act as if it is present and has the guest_access value "forbidden".' +properties: + content: + properties: + guest_access: + description: Whether guests can join the room. + enum: + - can_join + - forbidden + type: string + required: + - guest_access + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.guest_access + type: string +title: Controls whether guest users are allowed to join rooms. +type: object diff --git a/data/event-schemas/schema/m.room.history_visibility.yaml b/data/event-schemas/schema/m.room.history_visibility.yaml new file mode 100644 index 000000000..27ec67c78 --- /dev/null +++ b/data/event-schemas/schema/m.room.history_visibility.yaml @@ -0,0 +1,28 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: This event controls whether a user can see the events that happened in a room from before they joined. +properties: + content: + properties: + history_visibility: + description: Who can see the room history. + enum: + - invited + - joined + - shared + - world_readable + type: string + required: + - history_visibility + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.history_visibility + type: string +title: Controls visibility of history. +type: object diff --git a/data/event-schemas/schema/m.room.join_rules.yaml b/data/event-schemas/schema/m.room.join_rules.yaml new file mode 100644 index 000000000..faa0f249c --- /dev/null +++ b/data/event-schemas/schema/m.room.join_rules.yaml @@ -0,0 +1,28 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: 'A room may be `public` meaning anyone can join the room without any prior action. Alternatively, it can be `invite` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, `knock` and `private` are reserved keywords which are not implemented.' +properties: + content: + properties: + join_rule: + description: The type of rules used for users wishing to join this room. + enum: + - public + - knock + - invite + - private + type: string + required: + - join_rule + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.join_rules + type: string +title: Describes how users are allowed to join the room. +type: object diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml new file mode 100644 index 000000000..181c5737e --- /dev/null +++ b/data/event-schemas/schema/m.room.member.yaml @@ -0,0 +1,132 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: |- + Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms//invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. + + The following membership states are specified: + + - `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join. + + - `join` - The user has joined the room (possibly after accepting an invite), and may participate in it. + + - `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked). + + - `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`). + + - `knock` - This is a reserved word, which currently has no meaning. + + The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise. + + This event may also include an `invite_room_state` key inside the event's `unsigned` data. + If present, this contains an array of `StrippedState` Events. These events provide information + on a subset of state events such as the room name. + + The user for which a membership applies is represented by the `state_key`. Under some conditions, + the `sender` and `state_key` may not match - this may be interpreted as the `sender` affecting + the membership state of the `state_key` user. + + The `membership` for a given user can change over time. The table below represents the various changes + over time and how clients and servers must interpret those changes. Previous membership can be retrieved + from the `prev_content` object on an event. If not present, the user's previous membership must be assumed + as `leave`. + + | | to `invite` | to `join` | to `leave` | to `ban` | to `knock` | + |-------------------|---------------------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|------------------| + | **from `invite`** | No change. | User joined the room. | If the `state_key` is the same as the `sender`, the user rejected the invite. Otherwise, the `state_key` user had their invite revoked. | User was banned. | Not implemented. | + | **from `join`** |Must never happen. | `displayname` or `avatar_url` changed. | If the `state_key` is the same as the `sender`, the user left. Otherwise, the `state_key` user was kicked. | User was kicked and banned. | Not implemented. | + | **from `leave`** |New invitation sent. | User joined. | No change. | User was banned. | Not implemented. | + | **from `ban`** |Must never happen. | Must never happen. | User was unbanned. | No change. | Not implemented. | + | **from `knock`** |Not implemented. | Not implemented. | Not implemented. | Not implemented. | Not implemented. | + +properties: + content: + properties: + avatar_url: + description: 'The avatar URL for this user, if any.' + type: string + displayname: + description: 'The display name for this user, if any.' + type: + - "string" + - "null" + membership: + description: The membership state of the user. + enum: + - invite + - join + - knock + - leave + - ban + type: string + is_direct: + description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging). + type: boolean + reason: + type: string + description: |- + Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban. + For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such + as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day. + + Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the + reason behind a button or other component is recommended. + third_party_invite: + properties: + display_name: + description: A name which can be displayed to represent the user instead of their third party identifier + type: string + signed: + description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.' + properties: + mxid: + description: The invited matrix user ID. Must be equal to the user_id property of the event. + type: string + signatures: + description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.' + title: Signatures + type: object + additionalProperties: + type: object + additionalProperties: + type: string + token: + description: The token property of the containing third_party_invite object. + type: string + required: + - mxid + - signatures + - token + title: signed + type: object + required: + - display_name + - signed + title: Invite + type: object + required: + - membership + title: EventContent + type: object + state_key: + description: |- + The `user_id` this membership event relates to. In all cases except for when `membership` is + `join`, the user ID sending the event does not need to match the user ID in the `state_key`, + unlike other events. Regular authorisation rules still apply. + type: string + type: + enum: + - m.room.member + type: string + unsigned: + allOf: + - $ref: "core-event-schema/unsigned_prop.yaml" + - type: object + properties: + invite_room_state: + description: 'A subset of the state of the room at the time of the invite, if `membership` is `invite`. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name` SHOULD be included.' + items: + $ref: "stripped_state.yaml" + type: array +title: The current membership state of a user in the room. +type: object diff --git a/data/event-schemas/schema/m.room.message$m.audio.yaml b/data/event-schemas/schema/m.room.message$m.audio.yaml new file mode 100644 index 000000000..3faf0c312 --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.audio.yaml @@ -0,0 +1,50 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a single audio clip. +properties: + content: + properties: + body: + description: "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'." + type: string + info: + description: Metadata for the audio clip referred to in `url`. + properties: + duration: + description: The duration of the audio in milliseconds. + type: integer + mimetype: + description: The mimetype of the audio e.g. `audio/aac`. + type: string + size: + description: The size of the audio clip in bytes. + type: integer + title: AudioInfo + type: object + msgtype: + enum: + - m.audio + type: string + url: + description: |- + Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) + to the audio clip. + type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + title: EncryptedFile + type: object + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: AudioMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.emote.yaml b/data/event-schemas/schema/m.room.message$m.emote.yaml new file mode 100644 index 000000000..43e2639dc --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.emote.yaml @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: "This message is similar to `m.text` except that the sender is 'performing' the action contained in the `body` key, similar to `/me` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular `m.text` messages." +properties: + content: + properties: + body: + description: The emote action to perform. + type: string + msgtype: + enum: + - m.emote + type: string + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + formatted_body: + description: |- + The formatted version of the `body`. This is required if `format` + is specified. + type: string + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: EmoteMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.file.yaml b/data/event-schemas/schema/m.room.message$m.file.yaml new file mode 100644 index 000000000..5958e1176 --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.file.yaml @@ -0,0 +1,66 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a generic file. +properties: + content: + properties: + body: + description: A human-readable description of the file. This is recommended to be the filename of the original upload. + type: string + filename: + description: The original filename of the uploaded file. + type: string + info: + description: Information about the file referred to in `url`. + properties: + mimetype: + description: The mimetype of the file e.g. `application/msword`. + type: string + size: + description: The size of the file in bytes. + type: integer + thumbnail_url: + description: |- + The URL to the thumbnail of the file. Only present if the + thumbnail is unencrypted. + type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + Only present if the thumbnail is encrypted. + title: EncryptedFile + type: object + thumbnail_info: + allOf: + - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml + description: Metadata about the image referred to in `thumbnail_url`. + title: FileInfo + type: object + msgtype: + enum: + - m.file + type: string + url: + description: |- + Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) + to the file. + type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + title: EncryptedFile + type: object + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: FileMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.image.yaml b/data/event-schemas/schema/m.room.message$m.image.yaml new file mode 100644 index 000000000..5eaa89d48 --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.image.yaml @@ -0,0 +1,40 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a single image and an optional thumbnail. +properties: + content: + properties: + body: + description: "A textual representation of the image. This could be the alt text of the image, the filename of the image, or some kind of content description for accessibility e.g. 'image attachment'." + type: string + info: + allOf: + - $ref: core-event-schema/msgtype_infos/image_info.yaml + description: Metadata about the image referred to in `url`. + msgtype: + enum: + - m.image + type: string + url: + description: |- + Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) + to the image. + type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + title: EncryptedFile + type: object + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: ImageMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.location.yaml b/data/event-schemas/schema/m.room.message$m.location.yaml new file mode 100644 index 000000000..5ddf68b7f --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.location.yaml @@ -0,0 +1,48 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a real-world location. +properties: + content: + properties: + body: + description: "A description of the location e.g. 'Big Ben, London, UK', or some kind of content description for accessibility e.g. 'location attachment'." + type: string + geo_uri: + description: A geo URI representing this location. + type: string + msgtype: + enum: + - m.location + type: string + info: + type: object + properties: + thumbnail_url: + description: |- + The URL to the thumbnail of the file. Only present if the + thumbnail is unencrypted. + type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + Only present if the thumbnail is encrypted. + title: EncryptedFile + type: object + thumbnail_info: + allOf: + - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml + description: Metadata about the image referred to in `thumbnail_url`. + title: LocationInfo + required: + - msgtype + - body + - geo_uri + type: object + type: + enum: + - m.room.message + type: string +title: LocationMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.notice.yaml b/data/event-schemas/schema/m.room.message$m.notice.yaml new file mode 100644 index 000000000..7b735d60d --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.notice.yaml @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: 'The `m.notice` type is primarily intended for responses from automated clients. An `m.notice` message must be treated the same way as a regular `m.text` message with two exceptions. Firstly, clients should present `m.notice` messages to users in a distinct manner, and secondly, `m.notice` messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.' +properties: + content: + properties: + body: + description: The notice text to send. + type: string + msgtype: + enum: + - m.notice + type: string + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + formatted_body: + description: |- + The formatted version of the `body`. This is required if `format` + is specified. + type: string + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: NoticeMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.server_notice.yaml b/data/event-schemas/schema/m.room.message$m.server_notice.yaml new file mode 100644 index 000000000..ca7144b08 --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.server_notice.yaml @@ -0,0 +1,39 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: Represents a server notice for a user. +properties: + content: + properties: + body: + description: A human-readable description of the notice. + type: string + msgtype: + enum: + - m.server_notice + type: string + server_notice_type: + description: |- + The type of notice being represented. + type: string + admin_contact: + description: |- + A URI giving a contact method for the server administrator. Required if the + notice type is `m.server_notice.usage_limit_reached`. + type: string + limit_type: + description: |- + The kind of usage limit the server has exceeded. Required if the notice type is + `m.server_notice.usage_limit_reached`. + type: string + required: + - msgtype + - body + - server_notice_type + type: object + type: + enum: + - m.room.message + type: string +title: ServerNoticeMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.text.yaml b/data/event-schemas/schema/m.room.message$m.text.yaml new file mode 100644 index 000000000..4cba2bd64 --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.text.yaml @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message is the most basic message and is used to represent text. +properties: + content: + properties: + body: + description: The body of the message. + type: string + msgtype: + enum: + - m.text + type: string + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + formatted_body: + description: |- + The formatted version of the `body`. This is required if `format` + is specified. + type: string + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: TextMessage +type: object diff --git a/data/event-schemas/schema/m.room.message$m.video.yaml b/data/event-schemas/schema/m.room.message$m.video.yaml new file mode 100644 index 000000000..1879df65c --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.video.yaml @@ -0,0 +1,72 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a single video clip. +properties: + content: + properties: + body: + description: "A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'." + type: string + info: + description: Metadata about the video clip referred to in `url`. + properties: + duration: + description: The duration of the video in milliseconds. + type: integer + h: + description: The height of the video in pixels. + type: integer + w: + description: The width of the video in pixels. + type: integer + mimetype: + description: The mimetype of the video e.g. `video/mp4`. + type: string + size: + description: The size of the video in bytes. + type: integer + thumbnail_url: + description: |- + The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) to an image thumbnail of + the video clip. Only present if the thumbnail is unencrypted. + type: string + thumbnail_file: + description: |- + Information on the encrypted thumbnail file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + Only present if the thumbnail is encrypted. + title: EncryptedFile + type: object + thumbnail_info: + allOf: + - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml + description: Metadata about the image referred to in `thumbnail_url`. + title: VideoInfo + type: object + msgtype: + enum: + - m.video + type: string + url: + description: |- + Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) + to the video clip. + type: string + file: + description: |- + Required if the file is encrypted. Information on the encrypted + file, as specified in + [End-to-end encryption](/client-server-api/#sending-encrypted-attachments). + title: EncryptedFile + type: object + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: VideoMessage +type: object diff --git a/data/event-schemas/schema/m.room.message.feedback.yaml b/data/event-schemas/schema/m.room.message.feedback.yaml new file mode 100644 index 000000000..fbb39c0a1 --- /dev/null +++ b/data/event-schemas/schema/m.room.message.feedback.yaml @@ -0,0 +1,26 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: '**NB: Usage of this event is discouraged in favour of the** [receipts module](/client-server-api/#receipts). **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: `delivered` (sent when the event has been received) and `read` (sent when the event has been observed by the end-user). The `target_event_id` should reference the `m.room.message` event being acknowledged.' +properties: + content: + properties: + target_event_id: + description: The event that this feedback is related to. + type: string + type: + description: The type of feedback. + enum: + - delivered + - read + type: string + required: + - type + - target_event_id + type: object + type: + enum: + - m.room.message.feedback + type: string +title: MessageFeedback +type: object diff --git a/data/event-schemas/schema/m.room.message.yaml b/data/event-schemas/schema/m.room.message.yaml new file mode 100644 index 000000000..546b5e19e --- /dev/null +++ b/data/event-schemas/schema/m.room.message.yaml @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: 'This event is used when sending messages in a room. Messages are not limited to be text. The `msgtype` key outlines the type of message, e.g. text, audio, image, video, etc. The `body` key is text and MUST be used with every kind of `msgtype` as a fallback mechanism for when a client cannot render a message. This allows clients to display *something* even if it is just plain text.' +properties: + content: + properties: + body: + description: The textual representation of this message. + type: string + msgtype: + description: 'The type of message, e.g. `m.image`, `m.text`' + type: string + required: + - msgtype + - body + type: object + type: + enum: + - m.room.message + type: string +title: Message +type: object diff --git a/data/event-schemas/schema/m.room.name.yaml b/data/event-schemas/schema/m.room.name.yaml new file mode 100644 index 000000000..bbc5fc9aa --- /dev/null +++ b/data/event-schemas/schema/m.room.name.yaml @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: |- + A room has an opaque room ID which is not human-friendly to read. A room + alias is human-friendly, but not all rooms have room aliases. The room name + is a human-friendly string designed to be displayed to the end-user. The + room name is not unique, as multiple rooms can have the same room name set. + + A room with an `m.room.name` event with an absent, null, or empty + `name` field should be treated the same as a room with no `m.room.name` + event. + + An event of this type is automatically created when creating a room using + `/createRoom` with the `name` key. +properties: + content: + properties: + name: + description: The name of the room. This MUST NOT exceed 255 bytes. + type: string + required: + - name + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.name + type: string +title: RoomName +type: object diff --git a/data/event-schemas/schema/m.room.pinned_events.yaml b/data/event-schemas/schema/m.room.pinned_events.yaml new file mode 100644 index 000000000..7b4a0d61d --- /dev/null +++ b/data/event-schemas/schema/m.room.pinned_events.yaml @@ -0,0 +1,25 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: This event is used to "pin" particular events in a room for other participants to review later. The order of the pinned events is guaranteed and based upon the order supplied in the event. Clients should be aware that the current user may not be able to see some of the events pinned due to visibility settings in the room. Clients are responsible for determining if a particular event in the pinned list is displayable, and have the option to not display it if it cannot be pinned in the client. +properties: + content: + properties: + pinned: + description: An ordered list of event IDs to pin. + items: + type: string + type: array + required: + - pinned + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.pinned_events + type: string +title: Pinned events in a room +type: object diff --git a/data/event-schemas/schema/m.room.power_levels.yaml b/data/event-schemas/schema/m.room.power_levels.yaml new file mode 100644 index 000000000..39c1988c4 --- /dev/null +++ b/data/event-schemas/schema/m.room.power_levels.yaml @@ -0,0 +1,110 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: |- + This event specifies the minimum level a user must have in order to perform a + certain action. It also specifies the levels of each user in the room. + + If a `user_id` is in the `users` list, then that `user_id` has the + associated power level. Otherwise they have the default level + `users_default`. If `users_default` is not supplied, it is assumed to be + 0. If the room contains no `m.room.power_levels` event, the room's creator has + a power level of 100, and all other users have a power level of 0. + + The level required to send a certain event is governed by `events`, + `state_default` and `events_default`. If an event type is specified in + `events`, then the user must have at least the level specified in order to + send that event. If the event type is not supplied, it defaults to + `events_default` for Message Events and `state_default` for State + Events. + + If there is no `state_default` in the `m.room.power_levels` event, the + `state_default` is 50. If there is no `events_default` in the + `m.room.power_levels` event, the `events_default` is 0. If the room + contains no `m.room.power_levels` event, *both* the `state_default` and + `events_default` are 0. + + The power level required to invite a user to the room, kick a user from the + room, ban a user from the room, or redact an event sent by another user, is + defined by `invite`, `kick`, `ban`, and `redact`, respectively. Each + of these levels defaults to 50 if they are not specified in the + `m.room.power_levels` event, or if the room contains no `m.room.power_levels` + event. + + **Note:** + + As noted above, in the absence of an `m.room.power_levels` event, the + `state_default` is 0, and all users are considered to have power level 0. + That means that **any** member of the room can send an + `m.room.power_levels` event, changing the permissions in the room. + + Server implementations should therefore ensure that each room has an + `m.room.power_levels` event as soon as it is created. See also the + documentation of the `/createRoom` API. + +properties: + content: + properties: + ban: + description: The level required to ban a user. Defaults to 50 if unspecified. + type: integer + events: + additionalProperties: + type: integer + description: The level required to send specific event types. This is a mapping from event type to power level required. + title: Event power levels + type: object + events_default: + description: |- + The default level required to send message events. Can be + overridden by the `events` key. Defaults to 0 if unspecified. + type: integer + invite: + description: The level required to invite a user. Defaults to 50 if unspecified. + type: integer + kick: + description: The level required to kick a user. Defaults to 50 if unspecified. + type: integer + redact: + description: The level required to redact an event sent by another user. Defaults to 50 if unspecified. + type: integer + state_default: + description: |- + The default level required to send state events. Can be overridden + by the `events` key. Defaults to 50 if unspecified. + type: integer + users: + additionalProperties: + type: integer + description: The power levels for specific users. This is a mapping from `user_id` to power level for that user. + title: User power levels + type: object + users_default: + description: |- + The default power level for every user in the room, unless their + `user_id` is mentioned in the `users` key. Defaults to 0 if + unspecified. + type: integer + notifications: + properties: + room: + type: integer + description: The level required to trigger an `@room` notification. Defaults to 50 if unspecified. + additionalProperties: + type: integer + description: |- + The power level requirements for specific notification types. + This is a mapping from `key` to power level for that notifications key. + title: Notifications + type: object + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.power_levels + type: string +title: Defines the power levels (privileges) of users in the room. +type: object diff --git a/data/event-schemas/schema/m.room.redaction.yaml b/data/event-schemas/schema/m.room.redaction.yaml new file mode 100644 index 000000000..143e7eff1 --- /dev/null +++ b/data/event-schemas/schema/m.room.redaction.yaml @@ -0,0 +1,22 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: 'This event is created by the server to describe which event has been redacted, by whom, and optionally why. The event that has been redacted is specified in the `redacts` event level key. Redacting an event means that all keys not required by the protocol are stripped off, allowing messages to be hidden or allowing admins to remove offensive or illegal content.' +properties: + content: + properties: + reason: + description: 'The reason for the redaction, if any.' + type: string + type: object + redacts: + description: The event ID that was redacted. + type: string + type: + enum: + - m.room.redaction + type: string +required: + - redacts +title: Redaction +type: object diff --git a/data/event-schemas/schema/m.room.server_acl.yaml b/data/event-schemas/schema/m.room.server_acl.yaml new file mode 100644 index 000000000..3a7128f0b --- /dev/null +++ b/data/event-schemas/schema/m.room.server_acl.yaml @@ -0,0 +1,88 @@ +--- +title: Server ACL +description: |- + An event to indicate which servers are permitted to participate in the + room. Server ACLs may allow or deny groups of hosts. All servers participating + in the room, including those that are denied, are expected to uphold the + server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts + list in order for the ACLs to remain effective. + + The `allow` and `deny` lists are lists of globs supporting `?` and `*` + as wildcards. When comparing against the server ACLs, the suspect server's port + number must not be considered. Therefore `evil.com`, `evil.com:8448`, and + `evil.com:1234` would all match rules that apply to `evil.com`, for example. + + The ACLs are applied to servers when they make requests, and are applied in + the following order: + + 1. If there is no `m.room.server_acl` event in the room state, allow. + #. If the server name is an IP address (v4 or v6) literal, and `allow_ip_literals` + is present and `false`, deny. + #. If the server name matches an entry in the `deny` list, deny. + #. If the server name matches an entry in the `allow` list, allow. + #. Otherwise, deny. + + **Note:** + Server ACLs do not restrict the events relative to the room DAG via authorisation + rules, but instead act purely at the network layer to determine which servers are + allowed to connect and interact with a given room. + + **Warning:** + Failing to provide an `allow` rule of some kind will prevent **all** + servers from participating in the room, including the sender. This renders + the room unusable. A common allow rule is `[ "*" ]` which would still + permit the use of the `deny` list without losing the room. + + **Warning:** + All compliant servers must implement server ACLs. However, legacy or noncompliant + servers exist which do not uphold ACLs, and these MUST be manually appended to + the denied hosts list when setting an ACL to prevent them from leaking events from + banned servers into a room. Currently, the only way to determine noncompliant hosts is + to check the `prev_events` of leaked events, therefore detecting servers which + are not upholding the ACLs. Server versions can also be used to try to detect hosts that + will not uphold the ACLs, although this is not comprehensive. Server ACLs were added + in Synapse v0.32.0, although other server implementations and versions exist in the world. +allOf: + - $ref: core-event-schema/state_event.yaml +type: object +properties: + content: + properties: + allow_ip_literals: + type: boolean + description: |- + True to allow server names that are IP address literals. False to + deny. Defaults to true if missing or otherwise not a boolean. + + This is strongly recommended to be set to `false` as servers running + with IP literal names are strongly discouraged in order to require + legitimate homeservers to be backed by a valid registered domain name. + allow: + type: array + description: |- + The server names to allow in the room, excluding any port information. + Wildcards may be used to cover a wider range of hosts, where `*` + matches zero or more characters and `?` matches exactly one character. + + **This defaults to an empty list when not provided, effectively disallowing + every server.** + items: + type: string + deny: + type: array + description: |- + The server names to disallow in the room, excluding any port information. + Wildcards may be used to cover a wider range of hosts, where `*` + matches zero or more characters and `?` matches exactly one character. + + This defaults to an empty list when not provided. + items: + type: string + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: ['m.room.server_acl'] + type: string diff --git a/data/event-schemas/schema/m.room.third_party_invite.yaml b/data/event-schemas/schema/m.room.third_party_invite.yaml new file mode 100644 index 000000000..f4188192e --- /dev/null +++ b/data/event-schemas/schema/m.room.third_party_invite.yaml @@ -0,0 +1,46 @@ +--- +$schema: http://json-schema.org/draft-04/schema# +allOf: + - $ref: core-event-schema/state_event.yaml +description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room." +properties: + content: + properties: + display_name: + description: "A user-readable string which represents the user who has been invited. This should not contain the user's third party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third party ID." + type: string + key_validity_url: + description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'." + type: string + public_key: + description: A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility. + type: string + public_keys: + description: Keys with which the token may be signed. + items: + properties: + key_validity_url: + description: "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely." + type: string + public_key: + description: A base-64 encoded ed25519 key with which token may be signed. + type: string + required: + - public_key + title: PublicKeys + type: object + type: array + required: + - display_name + - key_validity_url + - public_key + type: object + state_key: + description: 'The token, of which a signature must be produced in order to join the room.' + type: string + type: + enum: + - m.room.third_party_invite + type: string +title: 'An invitation to a room issued to a third party identifier, rather than a matrix user ID.' +type: object diff --git a/data/event-schemas/schema/m.room.tombstone.yaml b/data/event-schemas/schema/m.room.tombstone.yaml new file mode 100644 index 000000000..0fd8ba452 --- /dev/null +++ b/data/event-schemas/schema/m.room.tombstone.yaml @@ -0,0 +1,27 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: 'A state event signifying that a room has been upgraded to a different room version, and that clients should go there.' +properties: + content: + properties: + body: + type: string + description: A server-defined message. + replacement_room: + type: string + description: The new room the client should be visiting. + required: + - replacement_room + - body + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.tombstone + type: string +title: Indication that the room has been upgraded. +type: object diff --git a/data/event-schemas/schema/m.room.topic.yaml b/data/event-schemas/schema/m.room.topic.yaml new file mode 100644 index 000000000..78a3d878a --- /dev/null +++ b/data/event-schemas/schema/m.room.topic.yaml @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.' +properties: + content: + properties: + topic: + description: The topic text. + type: string + required: + - topic + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.topic + type: string +title: Topic +type: object diff --git a/data/event-schemas/schema/m.room_key.withheld.yaml b/data/event-schemas/schema/m.room_key.withheld.yaml new file mode 100644 index 000000000..797b51f9b --- /dev/null +++ b/data/event-schemas/schema/m.room_key.withheld.yaml @@ -0,0 +1,86 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to indicate that the sender is not sharing room keys + with the recipient. It is sent as a to-device event. + + Possible values for `code` include: + + * `m.blacklisted`: the user/device was blacklisted. + * `m.unverified`: the user/device was not verified, and the sender is only + sharing keys with verified users/devices. + * `m.unauthorised`: the user/device is not allowed to have the key. For + example, this could be sent in response to a key request if the user/device + was not in the room when the original message was sent. + * `m.unavailable`: sent in reply to a key request if the device that the + key is requested from does not have the requested key. + * `m.no_olm`: an olm session could not be established. + + In most cases, this event refers to a specific room key. The one exception to + this is when the sender is unable to establish an olm session with the + recipient. When this happens, multiple sessions will be affected. In order + to avoid filling the recipient\'s device mailbox, the sender should only send + one `m.room_key.withheld` message with no `room_id` nor `session_id` + set. If the sender retries and fails to create an olm session again in the + future, it should not send another `m.room_key.withheld` message with a + `code` of `m.no_olm`, unless another olm session was previously + established successfully. In response to receiving an + `m.room_key.withheld` message with a `code` of `m.no_olm`, the + recipient may start an olm session with the sender and send an `m.dummy` + message to notify the sender of the new olm session. The recipient may + assume that this `m.room_key.withheld` message applies to all encrypted + room messages sent before it receives the message. +properties: + content: + properties: + algorithm: + type: string + enum: ["m.megolm.v1.aes-sha2"] + description: |- + The encryption algorithm for the key that this event is about. + room_id: + type: string + description: |- + Required if `code` is not `m.no_olm`. The room for the key that + this event is about. + session_id: + type: string + description: |- + Required of `code` is not `m.no_olm`. The session ID of the key + that this event is aboutis for. + sender_key: + type: string + description: |- + The unpadded base64-encoded device curve25519 key of the event\'s + sender. + code: + type: string + enum: + - m.blacklisted + - m.unverified + - m.unauthorised + - m.unavailable + - m.no_olm + description: |- + A machine-readable code for why the key was not sent. Codes beginning + with `m.` are reserved for codes defined in the Matrix + specification. Custom codes must use the Java package naming + convention. + reason: + type: string + description: |- + A human-readable reason for why the key was not sent. The receiving + client should only use this string if it does not understand the + `code`. + required: + - algorithm + - sender_key + - code + type: object + type: + enum: + - m.room_key.withheld + type: string +type: object diff --git a/data/event-schemas/schema/m.room_key.yaml b/data/event-schemas/schema/m.room_key.yaml new file mode 100644 index 000000000..6eebbec5f --- /dev/null +++ b/data/event-schemas/schema/m.room_key.yaml @@ -0,0 +1,35 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to exchange keys for end-to-end encryption. Typically + it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + algorithm: + type: string + enum: ["m.megolm.v1.aes-sha2"] + description: |- + The encryption algorithm the key in this event is to be used with. + room_id: + type: string + description: The room where the key is used. + session_id: + type: string + description: The ID of the session that the key is for. + session_key: + type: string + description: The key to be exchanged. + required: + - algorithm + - room_id + - session_id + - session_key + type: object + type: + enum: + - m.room_key + type: string +type: object diff --git a/data/event-schemas/schema/m.room_key_request.yaml b/data/event-schemas/schema/m.room_key_request.yaml new file mode 100644 index 000000000..99afdb191 --- /dev/null +++ b/data/event-schemas/schema/m.room_key_request.yaml @@ -0,0 +1,61 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to request keys for end-to-end encryption. It is sent as an + unencrypted [to-device](/client-server-api/#send-to-device-messaging) event. +properties: + content: + properties: + body: + description: |- + Information about the requested key. Required when `action` is + `request`. + properties: + algorithm: + type: string + description: |- + The encryption algorithm the requested key in this event is to be used + with. + room_id: + type: string + description: The room where the key is used. + sender_key: + type: string + description: |- + The Curve25519 key of the device which initiated the session originally. + session_id: + type: string + description: The ID of the session that the key is for. + required: + - algorithm + - room_id + - session_id + - sender_key + type: object + title: RequestedKeyInfo + action: + enum: + - request + - request_cancellation + type: string + requesting_device_id: + description: ID of the device requesting the key. + type: string + request_id: + description: |- + A random string uniquely identifying the request for a key. If the key is + requested multiple times, it should be reused. It should also reused in order + to cancel a request. + type: string + required: + - action + - requesting_device_id + - request_id + type: object + type: + enum: + - m.room_key_request + type: string +type: object diff --git a/data/event-schemas/schema/m.sticker.yaml b/data/event-schemas/schema/m.sticker.yaml new file mode 100644 index 000000000..5856cca6f --- /dev/null +++ b/data/event-schemas/schema/m.sticker.yaml @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a single sticker image. +properties: + content: + properties: + body: + description: |- + A textual representation or associated description of the sticker + image. This could be the alt text of the original image, or a message + to accompany and further describe the sticker. + type: string + info: + allOf: + - $ref: core-event-schema/msgtype_infos/image_info.yaml + description: |- + Metadata about the image referred to in `url` including a thumbnail + representation. + url: + description: |- + The URL to the sticker image. This must be a valid `mxc://` URI. + type: string + required: + - body + - info + - url + type: object + type: + enum: + - m.sticker + type: string +title: StickerMessage +type: object diff --git a/data/event-schemas/schema/m.tag.yaml b/data/event-schemas/schema/m.tag.yaml new file mode 100644 index 000000000..afa224209 --- /dev/null +++ b/data/event-schemas/schema/m.tag.yaml @@ -0,0 +1,36 @@ +{ + "type": "object", + "title": "Tag Event", + "description": "Informs the client of tags on a room.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "type": { + "type": "string", + "enum": ["m.tag"] + }, + "content": { + "type": "object", + "properties": { + "tags": { + "type": "object", + "description": "The tags on the room and their contents.", + "additionalProperties": { + "title": "Tag", + "type": "object", + "properties": { + "order": { + "type": "number", + "format": "float", + "description": + "A number in a range `[0,1]` describing a relative position of the room under the given tag." + } + } + } + } + } + } + }, + "required": ["type", "content"] +} diff --git a/data/event-schemas/schema/m.typing.yaml b/data/event-schemas/schema/m.typing.yaml new file mode 100644 index 000000000..705b3b6c7 --- /dev/null +++ b/data/event-schemas/schema/m.typing.yaml @@ -0,0 +1,31 @@ +{ + "type": "object", + "title": "Typing Event", + "description": "Informs the client of the list of users currently typing.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "user_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The list of user IDs typing in this room, if any." + } + }, + "required": ["user_ids"] + }, + "type": { + "type": "string", + "enum": ["m.typing"] + }, + "room_id": { + "type": "string" + } + }, + "required": ["type", "room_id", "content"] +} diff --git a/data/event-schemas/schema/stripped_state.yaml b/data/event-schemas/schema/stripped_state.yaml new file mode 100644 index 000000000..92306dc99 --- /dev/null +++ b/data/event-schemas/schema/stripped_state.yaml @@ -0,0 +1,44 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Note: this, and the example, are in the `event-schemas` directory because +# the CS API uses a symlink. In order for the `m.room.member` event to +# reference this, we'd need to use relative pathing. The symlink makes this +# difficult because the schema would be at two different locations, with +# different relative pathing. + +title: StrippedState +type: object +description: |- + A stripped down state event, with only the `type`, `state_key`, + `sender`, and `content` keys. +properties: + content: + description: The `content` for the event. + title: EventContent + type: object + state_key: + description: The `state_key` for the event. + type: string + type: + description: The `type` for the event. + type: string + sender: + description: The `sender` for the event. + type: string +required: + - type + - state_key + - content + - sender diff --git a/data/schemas/server-signatures.yaml b/data/schemas/server-signatures.yaml new file mode 100644 index 000000000..a18552566 --- /dev/null +++ b/data/schemas/server-signatures.yaml @@ -0,0 +1,24 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +example: { + "example.com": { + "ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } +} +additionalProperties: + type: object + title: Server Signatures + additionalProperties: + type: string \ No newline at end of file diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html new file mode 100644 index 000000000..b4bb75b4f --- /dev/null +++ b/layouts/partials/events/render-event.html @@ -0,0 +1,93 @@ +{{/* + + Renders a single event, given: + + * `event_name`: the name we want to display for the event + * `event_data`: the event specification + * `desired_example_name` (optional): the exact name of the examples to render. + If `desired_example_name` is omitted we render all examples + whose names start with the `event_name`. + +*/}} + +{{ $event_name := .event_name }} +{{ $desired_example_name := .desired_example_name }} +{{ $event_data := .event_data }} + +
+ +
+ + +

+ {{ $event_name }} +

+ +
+ +{{ $event_data.description | markdownify }} + + + +{{ $state_key := index $event_data.properties "state_key" }} + + + + + + +{{ if $state_key }} + + + + +{{ end }} +
Event type:{{ if $state_key }}State event{{ else }}Message event{{ end }}
State key{{ $state_key.description | markdownify }}
+ +

Content

+ +{{ $additional_types := partial "json-schema/resolve-additional-types" $event_data.properties.content }} + +{{ range $additional_types }} + {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} +{{end}} + +

Examples

+ +{{ $all_examples := index site.Data "event-schemas" "examples" }} + +{{ range $example_name, $example := $all_examples }} + + {{/* + This is to allow the msgtype template to work. + It lets callers specify exactly the name of the example they want + */}} + {{ if $desired_example_name }} + {{ if eq $example_name $desired_example_name }} + {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }} +```json +{{ jsonify (dict "indent" " ") $example_content }} +``` + {{ end }} + {{/* + If `$desired_example_name` is not given, we will include any + examples whose first part (before "$") matches the event name + */}} + {{ else }} + + {{ $pieces := split $example_name "$" }} + {{ $example_base_name := index $pieces 0 }} + {{ if eq $event_name $example_base_name }} + {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }} + {{ $example_json := jsonify (dict "indent" " ") $example_content }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + +```json +{{ $example_json }} +``` + {{ end }} + {{ end }} +{{ end }} + +
diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html new file mode 100644 index 000000000..26df52e59 --- /dev/null +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -0,0 +1,92 @@ +{{/* + + Finds and returns all nested objects, given: + + * `this_object`: a JSON schema object + + Given a schema object, this template finds all nested objects under that + schema. + + It "cleans" each object by copying only the parts of the objects that + the renderer needs, and adds the result to an array, `additional_objects`. + + Finally it returns the array of all the objects it found. + + Note that the returned array may contain duplicate objects. + +*/}} + +{{ $this_object := partial "json-schema/resolve-allof" . }} +{{ $additional_objects := slice }} + +{{ if eq $this_object.type "object" }} + + {{/* + Add the object we were passed into the $additional_objects array + */}} + {{ $additional_objects = $additional_objects | append (partial "clean-object" $this_object) }} + + {{/* + Add any nested objects referenced in this object's `additionalProperties` + */}} + {{ if $this_object.additionalProperties }} + {{ if reflect.IsMap $this_object.additionalProperties }} + {{ $additional_objects = $additional_objects | append (partial "clean-object" $this_object.additionalProperties) }} + + {{ range $key, $property := $this_object.additionalProperties.properties }} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects) }} + {{ end }} + + {{ end }} + {{ end }} + + {{/* + Add any nested objects referenced in this object's `properties` + */}} + {{ range $key, $property := $this_object.properties}} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects) }} + {{ end }} + +{{ end }} + +{{ if eq $this_object.type "array" }} + {{/* + Add any nested objects referenced in this object's `items` + */}} + {{ if reflect.IsSlice $this_object.items}} + {{ range $this_object.items }} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" . "additional_objects" $additional_objects) }} + {{ end }} + {{ else }} + {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $this_object.items "additional_objects" $additional_objects) }} + {{ end }} +{{ end }} + +{{ return $additional_objects }} + + +{{/* + This actually makes the recursive call and adds the returned objects to the array +*/}} +{{ define "partials/get-additional-objects" }} + {{ $additional_objects := .additional_objects }} + + {{ $this_object := partial "json-schema/resolve-allof" .this_object }} + {{ $more_objects := partial "json-schema/resolve-additional-types" $this_object }} + {{/* + As far as I know we don't have something like Array.concat(), so add them one at a time + */}} + {{ range $more_objects}} + {{ $additional_objects = $additional_objects | append (partial "clean-object" .) }} + {{ end }} + {{ return $additional_objects }} +{{ end }} + +{{/* + Only copy the bits of the object that we actually care about. + This is needed for uniqify to work - otherwise objects that are the same + but with (for example) different examples will be considered different. +*/}} +{{ define "partials/clean-object" }} + {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum) }} +{{ end }} diff --git a/layouts/partials/json-schema/resolve-allof.html b/layouts/partials/json-schema/resolve-allof.html new file mode 100644 index 000000000..0150cfdeb --- /dev/null +++ b/layouts/partials/json-schema/resolve-allof.html @@ -0,0 +1,76 @@ +{{/* + + Resolves the `allOf` keyword (https://swagger.io/specification/v2/#composition-and-inheritance-polymorphism), + given a JSON schema object. + + `allOf` is used to support a kind of inheritance for JSON schema objects. + + An object can reference a "parent" object using `allOf`, and it then inherits + its parent's properties. If the same property is present in the child, then + we use the child's version (the child overrides the parent). + + Of course the parent can itself inherit from *its* parent, so we recurse to + handle that. + +*/}} + +{{ $ret := . }} +{{ $original := . }} + +{{ $required := .required }} +{{ if not $required }} + {{ $required := slice }} +{{ end }} + +{{ with $ret.allOf }} + + {{ $all_of_values := dict }} + + {{/* + allOf is always an array + */}} + {{ range . }} + + {{ with .required }} + {{ $required = union $required . }} + {{ end }} + + {{/* + With merge, values from the second argument override those from the first argument. + So this order will accumulate values from allOf items, allowing later ones to override earlier + */}} + {{ $all_of_values = merge $all_of_values . }} + + {{ end }} + + {{/* + Then apply allOf values to the original, but allow the original to override allOf. + */}} + {{ $ret = merge $all_of_values $ret }} + + {{/* + Except that if allOf *itself* contains allOf, we do want to override the original for that field only. + */}} + {{ with $all_of_values.allOf }} + {{ $ret = merge $ret (dict "allOf" . ) }} + {{ end }} + + {{ with $ret.required }} + {{ $required = union $required $ret.required }} + {{ end }} + + {{ $ret = merge $ret (dict "required" $required) }} + +{{ end }} + +{{/* + Recurse while we are finding new allOf entries to resolve +*/}} +{{ if ne $ret.allOf $original.allOf }} + + {{ $resolved := partial "json-schema/resolve-allof" $ret }} + {{ $ret = merge $ret $resolved }} + +{{ end }} + +{{ return $ret }} diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html new file mode 100644 index 000000000..51ce6d532 --- /dev/null +++ b/layouts/partials/json-schema/resolve-example.html @@ -0,0 +1,29 @@ +{{/* + + For complex objects, example content is sometimes attached to the + object's individual properties (and subproperties...), so to get + a complete example for the whole object we need to iterate through + its properties (and subproperties...) and assemble them. + + That's what this template does. + +*/}} + +{{ $this_object := partial "json-schema/resolve-allof" . }} + +{{ if eq $this_object.type "object" }} + + {{ if not $this_object.example }} + {{ $this_object := merge (dict "example" dict ) $this_object }} + {{ end }} + + {{ range $key, $property := $this_object.properties}} + {{ $this_property_example := partial "json-schema/resolve-example" $property }} + {{ if $this_property_example }} + {{ $this_object = merge (dict "example" (dict $key $this_property_example)) $this_object }} + {{ end }} + {{ end }} + +{{ end }} + +{{ return $this_object.example }} diff --git a/layouts/partials/json-schema/resolve-refs.html b/layouts/partials/json-schema/resolve-refs.html new file mode 100644 index 000000000..1d99201db --- /dev/null +++ b/layouts/partials/json-schema/resolve-refs.html @@ -0,0 +1,65 @@ +{{/* + + Resolves the `$ref` JSON schema keyword, by recursively replacing + it with the object it points to. + + This template uses [`Scratch`](https://gohugo.io/functions/scratch/) + rather than a normal `dict` because with `dict` you can't replace key values: + https://discourse.gohugo.io/t/how-can-i-add-set-and-delete-keys-in-a-dictionary/29661 + +*/}} + +{{ $schema := .schema }} +{{ $path := .path}} + +{{ $ret := $schema }} + +{{ if reflect.IsMap $schema }} + + {{ $scratch := newScratch }} + {{ $scratch.Set "result_map" dict }} + + {{ $ref_value := index $schema "$ref"}} + {{ if $ref_value}} + {{ $full_path := path.Join $path $ref_value }} + {{/* + Apparently Hugo doesn't give us a nice way to split the extension off a filename. + */}} + {{ $without_ext := replaceRE "\\.[^\\.]*$" "" $full_path }} + {{ $pieces := split $without_ext "/" }} + + {{ $ref := index site.Data $pieces }} + + {{ $new_path := (path.Split $full_path).Dir}} + {{ $result_map := partial "json-schema/resolve-refs" (dict "schema" $ref "path" $new_path)}} + {{ if $result_map}} + {{ $scratch.Set "result_map" $result_map }} + {{end }} + {{ end }} + + + {{ range $key, $value := $schema }} + {{ if ne $key "$ref" }} + {{ $resolved := partial "json-schema/resolve-refs" (dict "schema" $value "path" $path) }} + {{ $scratch.SetInMap "result_map" $key $resolved }} + {{ end }} + {{ end }} + + {{ $ret = $scratch.Get "result_map" }} + +{{ end }} + +{{ if reflect.IsSlice $schema }} + + {{ $result_slice := slice }} + + {{ range $schema }} + {{ $resolved := partial "json-schema/resolve-refs" (dict "schema" . "path" $path) }} + {{ $result_slice = $result_slice | append $resolved }} + {{ end }} + + {{ $ret = $result_slice }} + +{{ end }} + +{{ return $ret }} diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html new file mode 100644 index 000000000..db10b98c0 --- /dev/null +++ b/layouts/partials/openapi/render-api.html @@ -0,0 +1,54 @@ +{{/* + + Render an HTTP API, given: + + * `api_data`: the OpenAPI/Swagger data + * `base_url`: the base URL: that is, the part we glue onto the front + of each value in `paths` to get a complete URL. + * `path`: the directory under /data where we found this API definition. + We use this to resolve "$ref" values, since they are relative to the schema's + location. + +*/}} + +{{ $api_data := index .api_data }} +{{ $base_url := .base_url }} +{{ $path := .path }} + +{{ range $path_name, $path_data := $api_data.paths }} + + {{ $endpoint := delimit (slice $base_url $path_name ) "" }} + + {{/* note that a `paths` entry can be a $ref */}} + + {{ $params := dict "endpoint" $endpoint "path" $path }} + + {{ with $path_data.get }} + + {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . ) }} + {{ partial "openapi/render-operation" $operation_params }} + + {{ end }} + + {{ with $path_data.post }} + + {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . ) }} + {{ partial "openapi/render-operation" $operation_params }} + + {{ end }} + + {{ with $path_data.put }} + + {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . ) }} + {{ partial "openapi/render-operation" $operation_params }} + + {{ end }} + + {{ with $path_data.delete }} + + {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . ) }} + {{ partial "openapi/render-operation" $operation_params }} + + {{ end }} + +{{ end }} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html new file mode 100644 index 000000000..bf275ed6e --- /dev/null +++ b/layouts/partials/openapi/render-object-table.html @@ -0,0 +1,92 @@ +{{/* + + Render a table listing the properties of an object, given: + + * `caption`: optional caption for the table + * `properties`: dictionary of the properties to list, each given as: + `property_name` : `property_data` + * `required`: array containing the names of required properties. + In some cases (such as response body specifications) this isn't used, and + instead properties have a `required` boolean attribute. We support this too. + +*/}} + +{{ $caption := .caption }} +{{ $properties := .properties}} +{{ $required := .required}} + +{{ if $properties }} + + + {{ with $caption }} + + {{ end }} + + + + + + + {{ range $property_name, $property := $properties }} + + {{ $property := partial "json-schema/resolve-allof" $property }} + + {{/* + If the property has a `title`, use that rather than `type`. + This means we can write things like `EventFilter` rather than `object`. + */}} + {{ $type := $property.type}} + {{ if $property.title }} + {{ $type = $property.title }} + {{ end }} + + {{/* + If the property is an array, indicate this with square brackets, + like `[type]`. + */}} + {{ if eq $type "array"}} + {{ $items := $property.items }} + {{ if $property.items }} + {{ $items = partial "json-schema/resolve-allof" $property.items }} + {{ end }} + {{ $inner_type := $items.type }} + {{ if $items.title }} + {{ $inner_type = $items.title }} + {{ end }} + {{ $type = delimit (slice "[" $inner_type "]") "" }} + {{ end }} + + {{/* + If the property is an enum, indicate this. + */}} + {{ if (and (eq $type "string") ($property.enum)) }} + {{ $type = "enum" }} + {{ end }} + + {{/* + If the property uses `additionalProperties` to describe its + internal structure, handle this. + */}} + {{ if reflect.IsMap $property.additionalProperties }} + {{ if $property.additionalProperties.title }} + {{ $type = delimit (slice "{ string: " $property.additionalProperties.title "}" ) "" }} + {{ end }} + {{ end }} + + {{/* + Handle two ways of indicating "required", one for simple parameters, + the other for request and response body objects. + */}} + {{ $required := cond (or (in $required $property_name) ( eq $property.required true )) true false }} + + + + + + + + {{ end }} + +
{{ . }}
NameTypeDescription
{{ $property_name }}{{ $type }}{{ if $required }}Required: {{end}}{{ $property.description | markdownify }}{{ if eq $type "enum"}}

One of: {{ $property.enum }}.

{{ end }}
+ +{{ end }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html new file mode 100644 index 000000000..430c571a0 --- /dev/null +++ b/layouts/partials/openapi/render-operation.html @@ -0,0 +1,65 @@ +{{/* + + Render a single HTTP API operation: that is, a method+endpoint combination, given: + + * `method`: the method, e.g. GET, PUT + * `endpoint`: the endpoint + * `operation_data`: the OpenAPI/Swagger data for the operation + * `path`: the path where this definition was found, to enable us to resolve "$ref" + + This template renders the operation as a `
` containing: + + * an `

` heading containing the method and endpoint + * a `
` element containing the details, including: + * operation description + * basic info about the operation + * request details + * response details + +*/}} + +{{ $method := .method }} +{{ $endpoint := .endpoint }} +{{ $operation_data := .operation_data }} +{{ $path := .path }} + +
+ +
+ + +

+ {{ $method }} + {{ $endpoint }} +

+ +
+ +{{ if $operation_data.deprecated }} + {{ partial "alert" (dict "type" "warning" "omit_title" "true" "content" "This API is deprecated and will be removed from a future release.") }} +{{ end }} + +

{{ $operation_data.description | markdownify }}

+ + + + + + + {{ $rate_limited := index $operation_data.responses "429" }} + + + + + + +
Rate-limited:{{ if $rate_limited }}Yes{{ else }}No{{ end }}
Requires authentication:{{ if $operation_data.security }}Yes{{ else }}No{{ end }}
+ +
+{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "path" $path) }} +
+{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "path" $path) }} + +
+ +
diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html new file mode 100644 index 000000000..2b4fb09db --- /dev/null +++ b/layouts/partials/openapi/render-parameters.html @@ -0,0 +1,30 @@ +{{/* + + Render the parameters of a given type, given: + + * `parameters`: OpenAPI/Swagger data specifying the parameters + * `type`: the type of parameters to render: "header, ""path", "query" + * `caption`: caption to use for the table + + This template renders a single table containing parameters of the given type. + +*/}} + +{{ $parameters := .parameters }} +{{ $type := .type }} +{{ $caption := .caption }} + +{{ $parameters_of_type := where $parameters "in" $type }} + +{{ with $parameters_of_type }} + + {{/* convert parameters into the format that render-object-table expects to see */}} + {{ $param_dict := dict }} + {{ range $parameter := . }} + {{ $param_dict = merge $param_dict (dict $parameter.name (dict "type" $parameter.type "description" $parameter.description "required" $parameter.required "enum" $parameter.enum) )}} + {{ end }} + + {{/* and render the parameters */}} + {{ partial "openapi/render-object-table" (dict "caption" $caption "properties" $param_dict) }} + +{{ end }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html new file mode 100644 index 000000000..1695c2f83 --- /dev/null +++ b/layouts/partials/openapi/render-request.html @@ -0,0 +1,67 @@ +{{/* + + Render the request part of a single HTTP API operation, given: + + * `parameters`: OpenAPI/Swagger data specifying the parameters + * `path`: the path where this definition was found, to enable us to resolve "$ref" + + This template renders: + * the "simple parameters" (header, path, query parameters) + * body parameters, which may be more complex, containing nested objects + * response body examples + +*/}} + +{{ $parameters := .parameters }} +{{ $path := .path }} + +

Request

+ +{{ if $parameters }} + + {{ $simple_parameters := where $parameters "in" "!=" "body"}} + {{ if $simple_parameters }} +

Request parameters

+ + {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "header" "caption" "header parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "path" "caption" "path parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "query" "caption" "query parameters") }} + + {{ end }} + + {{ $body_parameters := where $parameters "in" "body"}} + {{ if $body_parameters }} +

Request body

+ + {{/* at most one body param is allowed by the spec */}} + {{ $body_parameter := index $body_parameters 0 }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body_parameter.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + + {{ $additional_types := partial "json-schema/resolve-additional-types" $schema }} + {{ $additional_types = uniq $additional_types }} + {{ range $additional_types }} + {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} + {{ end }} + +

Request body example

+ + {{ $example := partial "json-schema/resolve-example" $schema }} + {{ if $example }} + {{ $example_json := jsonify (dict "indent" " ") $example }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + +```json +{{ $example_json }} +``` + + {{ else }} + {{ partial "alert" (dict "type" "warning" "omit_title" "true" "color" "warning" "content" "Specification error: Example invalid or not present") }} + {{ end }} + + {{ end }} + +{{ else }} +

No request parameters or request body.

+{{ end }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html new file mode 100644 index 000000000..c92aba8e3 --- /dev/null +++ b/layouts/partials/openapi/render-responses.html @@ -0,0 +1,97 @@ +{{/* + + Render the response part of a single HTTP API operation, given: + + * `responses`: OpenAPI/Swagger data specifying the responses + * `path`: the path where this definition was found, to enable us to resolve "$ref" + + This template renders: + * a summary of all the different responses + * details of the body for each response code + * body parameters, which may be more complex, containing nested objects + * response body examples + +*/}} + +{{ $responses := .responses }} +{{ $path := .path }} + +

Responses

+ + + + + + + +{{ range $code, $response := $responses }} + + + + + + +{{ end }} + +
StatusDescription
{{ $code }}{{ $response.description | markdownify }}
+ +{{ range $code, $response := $responses }} + + {{ if $response.schema }} + + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $response.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + + {{ if or $schema.properties (eq $schema.type "array") }} +

{{ $code}} response

+ + {{/* + All this is to work out how to express the content of the response + in the case where it is an array. + */}} + {{ if eq $schema.type "array" }} + {{ $type_of := "" }} + {{ if reflect.IsSlice $schema.items }} + {{ $types := slice }} + {{ range $schema.items }} + {{ if .title }} + {{ $types = $types | append .title}} + {{ else }} + {{ $types = $types | append .type }} + {{ end }} + {{ end }} + {{ $type_of = delimit $types ", "}} + {{ else }} + {{ $type_of = $schema.items.title }} + {{ end }} +

Array of {{ $type_of }}.

+ {{ end }} + + {{ $additional_types := partial "json-schema/resolve-additional-types" $schema }} + {{ $additional_types = uniq $additional_types }} + {{ range $additional_types }} + {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} + {{ end }} + + {{ $example := partial "json-schema/resolve-example" $schema }} + {{ if $response.examples }} + {{ $example = partial "json-schema/resolve-refs" (dict "schema" $response.examples "path" $path) }} + {{ $example = index $example "application/json" }} + {{ end }} + + {{ if $example }} + {{ $example_json := jsonify (dict "indent" " ") $example }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + +```json +{{ $example_json }} +``` + + {{ else }} + {{ partial "alert" (dict "type" "warning" "omit_title" "true" "color" "warning" "content" "Specification error: Example invalid or not present") }} + {{ end }} + + {{ end }} + {{ end }} +{{ end }} diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html new file mode 100644 index 000000000..151e06060 --- /dev/null +++ b/layouts/shortcodes/definition.html @@ -0,0 +1,59 @@ +{{/* + + This template is used to render EDUs and PDUs in the server-server and room versions specs. + + It expects to be passed a `path` parameter, which is a path, relative to /data, + pointing to a schema file. The file extension is omitted. For example: + + {{% definition path="api/server-server/definitions/edu" %}} + + This template replaces the old {{definition_*}} template. + +*/}} + +{{ $path := .Params.path }} +{{ $compact := .Params.compact }} +{{ $pieces := split $path "/" }} + +{{/* The definition is referenced by the .path parameter */}} +{{ $definition := index .Site.Data $pieces }} + +{{/* The base path, which we use to resolve $ref, omits the last component */}} +{{ $pieces = first (sub (len $pieces) 1) $pieces}} +{{ $path = delimit $pieces "/" }} + +{{/* Resolve $ref and allOf */}} +{{ $definition = partial "json-schema/resolve-refs" (dict "schema" $definition "path" $path) }} +{{ $definition = partial "json-schema/resolve-allof" $definition }} + +
+ +
+ + +

+ {{ $definition.title }} +

+ +
+ +{{ $definition.description | markdownify }} + + + +{{ $additional_types := partial "json-schema/resolve-additional-types" $definition }} +{{ $additional_types = uniq $additional_types }} + +{{ range $additional_types }} + {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} +{{end}} + +

Examples

+ +{{ $example := partial "json-schema/resolve-example" $definition }} + +```json +{{ jsonify (dict "indent" " ") $example }} +``` + +
diff --git a/layouts/shortcodes/event-fields.html b/layouts/shortcodes/event-fields.html new file mode 100644 index 000000000..83651c213 --- /dev/null +++ b/layouts/shortcodes/event-fields.html @@ -0,0 +1,45 @@ +{{/* + + This template is used to render the fields that all basic events and room events + must or may contain. + + It expects to be passed an `event_type` parameter, is the name of a file under + /data/event-schemas/core-event-schema. The file extension is omitted. For example: + + {{% event-fields event_type="room_event" %}} + + This template replaces the old {{common_event_fields}} and {{common_room_event_fields}} templates. + +*/}} + +{{ $event := index .Site.Data "event-schemas" "schema" "core-event-schema" .Params.event_type }} +{{ $path := "event-schemas/schema/core-event-schema" }} + +{{ $event = partial "json-schema/resolve-refs" (dict "schema" $event "path" $path) }} +{{ $event := partial "json-schema/resolve-allof" $event }} + +
+ +
+ + +

+ {{ humanize $event.title }} +

+ +
+ +{{ $event.description | markdownify }} + + + +{{ $event = merge $event (dict "title" "") }} + +{{ $additional_types := partial "json-schema/resolve-additional-types" $event }} +{{ range $additional_types }} + {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }} +{{end}} + +
+ +
diff --git a/layouts/shortcodes/event-group.html b/layouts/shortcodes/event-group.html new file mode 100644 index 000000000..5e2900f04 --- /dev/null +++ b/layouts/shortcodes/event-group.html @@ -0,0 +1,32 @@ +{{/* + + This template is used to render a group of events starting with a given prefix. + + It expects to be passed a `group_name` parameter. For example: + + {{% event-group group_name="m.call" %}} + + The template will then render all events whose schema starts with the given name. + + This template replaces the old {{*_events}} template. + +*/}} + +{{ $path := "event-schemas/schema" }} + +{{ $events := index .Site.Data "event-schemas" "schema" }} +{{ $group_name := .Params.group_name }} + +{{ range $event_name, $event_data := $events }} + + {{ $prefix := substr $event_name 0 (len $group_name) }} + {{ if eq $prefix $group_name }} + + {{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }} + {{ $event_data := partial "json-schema/resolve-allof" $event_data }} + + {{ partial "events/render-event" (dict "event_name" $event_name "event_data" $event_data)}} + + {{ end }} + +{{ end }} diff --git a/layouts/shortcodes/event.html b/layouts/shortcodes/event.html new file mode 100644 index 000000000..71c9c5349 --- /dev/null +++ b/layouts/shortcodes/event.html @@ -0,0 +1,20 @@ +{{/* + + This template is used to render an event. + + It expects to be passed an `event` parameter, which is the name of a schema file under + "data/event-schemas/schema". The file extension is omitted. For example: + + {{% event event="m.accepted_terms" %}} + + This template replaces the old {{*_event}} template. + +*/}} + +{{ $event_data := index .Site.Data "event-schemas" "schema" .Params.event }} +{{ $path := "event-schemas/schema" }} + +{{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }} +{{ $event_data := partial "json-schema/resolve-allof" $event_data }} + +{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data)}} diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html new file mode 100644 index 000000000..b4bc6d0dc --- /dev/null +++ b/layouts/shortcodes/http-api.html @@ -0,0 +1,26 @@ +{{/* + + This template is used to render an HTTP API, given an OpenAPI/Swagger definition. + + It expects to be passed two parameters: + + * a `spec` parameter identifying the spec, which must be the name of + a directory under /data/api + * an `api` parameter, identifying an OpenAPI/Swagger definition, + which is the name of a schema file under "data/api/$spec". + The file extension is omitted. For example: + + {{% http-api spec="server-server" api="public_rooms" %}} + + This template replaces the old {{*_http_api}} template. + +*/}} + +{{ $spec := .Params.spec}} +{{ $api := .Params.api}} + +{{ $api_data := index .Site.Data.api .Params.spec .Params.api }} +{{ $base_url := replace $api_data.basePath "%CLIENT_MAJOR_VERSION%" "r0" }} +{{ $path := delimit (slice "api" $spec) "/" }} + +{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }} diff --git a/layouts/shortcodes/msgtypes.html b/layouts/shortcodes/msgtypes.html new file mode 100644 index 000000000..ccdfda5fa --- /dev/null +++ b/layouts/shortcodes/msgtypes.html @@ -0,0 +1,48 @@ +{{/* + + This template is used to render the `m.room.message` events. + + It replaces the old {{msgtype_events}} template. + +*/}} + +{{ $path := "event-schemas/schema" }} +{{ $compact := false }} + +{{/* + The old template starts with an explicit list of events, presumably + to define the order in which they are rendered. +*/}} +{{ $msgtypes := (slice "m.room.message$m.text" "m.room.message$m.emote" "m.room.message$m.notice" "m.room.message$m.image" "m.room.message$m.file") }} + +{{/* + It excludes `m.room.message$m.server_notice` +*/}} +{{ $excluded := slice "m.room.message$m.server_notice" }} + +{{/* + It then adds any other events that start with `m.room.message`. +*/}} +{{ $events := index .Site.Data "event-schemas" "schema" }} +{{ $expected_prefix := "m.room.message$"}} +{{ range $object_name, $event_data := $events }} + + {{ $prefix := substr $object_name 0 (len $expected_prefix) }} + {{ if and (eq $prefix $expected_prefix) (not (in $excluded $object_name)) (not (in $msgtypes $object_name)) }} + {{ $msgtypes = $msgtypes | append $object_name }} + {{ end }} + +{{ end }} + +{{ $site_data := .Site.Data }} + +{{ range $msgtypes }} + + {{ $event_data := index $site_data "event-schemas" "schema" . }} + {{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }} + {{ $event_data := partial "json-schema/resolve-allof" $event_data }} + + {{ $event_name := index (split . "$") 1 }} + {{ partial "events/render-event" (dict "event_name" $event_name "desired_example_name" . "event_data" $event_data)}} + +{{ end }} diff --git a/openapi_extensions.md b/openapi_extensions.md new file mode 100644 index 000000000..b450e49f7 --- /dev/null +++ b/openapi_extensions.md @@ -0,0 +1,66 @@ +# OpenAPI Extensions + +For some functionality that is not directly provided by the OpenAPI v2 +specification, some extensions have been added that are to be consistent +across the specification. The defined extensions are listed below. Extensions +should not break parsers, however if extra functionality is required, aware +parsers should be able to take advantage of the added syntax. + +## Using multiple files to describe API + +To ease API design and management, the API definition is split across several +files. Each of these files is self-contained valid OpenAPI (except +client-server files that become valid OpenAPI after substituting +`%CLIENT_MAJOR_VERSION%` with `unstable` or an API release). + +There is no single root file in the source tree as OpenAPI requires; this file +can be generated by `dump_swagger.py` (also doing the substitution mentioned +above). The script does not convert the extensions described further in this +document (`oneOf` and parameter exploding) so there can be minor +interoperability issues with tooling that expects compliant Swagger. + +## Extensible Query Parameters + + + +If a unknown amount of query parameters can be added to a request, the `name` +must be `fields...`, with the trailing ellipses representing the possibility +of more fields. + +Example: + +``` + - in: query + name: fields... + type: string +``` + +## Using oneOf to provide type alternatives + + + +`oneOf` (available in JSON Schema and Swagger/OpenAPI v3 but not in v2) +is used in cases when a simpler type specification as a list of types +doesn't work, as in the following example: +``` + properties: + old: # compliant with old Swagger + type: + - string + - object # Cannot specify a schema here + new: # uses oneOf extension + oneOf: + - type: string + - type: object + title: CustomSchemaForTheWin + properties: + ... +``` + +## OpenAPI 3's "2xx" format for response codes + + + +In some cases, the schema will have HTTP response code definitions like +`2xx`, `3xx`, and `4xx`. These indicate that a response code within those +ranges (`2xx` = `200` to `299`) is valid for the schema. diff --git a/event-schemas/check_examples.py b/scripts/check-event-schema-examples.py similarity index 90% rename from event-schemas/check_examples.py rename to scripts/check-event-schema-examples.py index 31daa4783..50f9de7be 100755 --- a/event-schemas/check_examples.py +++ b/scripts/check-event-schema-examples.py @@ -128,7 +128,14 @@ def check_example_dir(exampledir, schemadir): if __name__ == '__main__': + # Get the directory that this script is residing in + script_directory = os.path.dirname(os.path.realpath(__file__)) + + # Resolve the directories to check, relative to the script path + examples_directory = os.path.join(script_directory, "../event-schemas/examples") + schema_directory = os.path.join(script_directory, "../event-schemas/schema") + try: - check_example_dir("examples", "schema") + check_example_dir(examples_directory, schema_directory) except: sys.exit(1) diff --git a/api/check_examples.py b/scripts/check-swagger-sources.py similarity index 69% rename from api/check_examples.py rename to scripts/check-swagger-sources.py index 94f3495e3..df99b7c00 100755 --- a/api/check_examples.py +++ b/scripts/check-swagger-sources.py @@ -108,13 +108,36 @@ def check_swagger_file(filepath): def resolve_references(path, schema): + """Recurse through a given schema until we find a $ref key. Upon doing so, + check that the referenced file exists, then load it up and check all of the + references in that file. Continue on until we've hit all dead ends. + + $ref values are deleted from schemas as they are validated, to prevent + duplicate work. + """ if isinstance(schema, dict): # do $ref first if '$ref' in schema: - value = schema['$ref'] - path = os.path.abspath(os.path.join(os.path.dirname(path), value)) - ref = load_file("file://" + path) - result = resolve_references(path, ref) + # Pull the referenced filepath from the schema + referenced_file = schema['$ref'] + + # Referenced filepaths are relative, so take the current path's + # directory and append the relative, referenced path to it. + inner_path = os.path.join(os.path.dirname(path), referenced_file) + + # Then convert the path (which may contiain '../') into a + # normalised, absolute path + inner_path = os.path.abspath(inner_path) + + # Load the referenced file + ref = load_file("file://" + inner_path) + + # Check that the references in *this* file are valid + result = resolve_references(inner_path, ref) + + # They were valid, and so were the sub-references. Delete + # the reference here to ensure we don't pass over it again + # when checking other files del schema['$ref'] else: result = {} @@ -143,15 +166,22 @@ def load_file(path): if __name__ == '__main__': - paths = sys.argv[1:] - if not paths: - paths = [] - for (root, dirs, files) in os.walk(os.curdir): - for filename in files: - if filename.endswith(".yaml"): - paths.append(os.path.join(root, filename)) - for path in paths: - try: - check_swagger_file(path) - except Exception as e: - raise ValueError("Error checking file %r" % (path,), e) + # Get the directory that this script is residing in + script_directory = os.path.dirname(os.path.realpath(__file__)) + + # Resolve the directory containing the swagger sources, + # relative to the script path + source_files_directory = os.path.realpath(os.path.join(script_directory, "../data")) + + # Walk the source path directory, looking for YAML files to check + for (root, dirs, files) in os.walk(source_files_directory): + for filename in files: + if not filename.endswith(".yaml"): + continue + + path = os.path.join(root, filename) + + try: + check_swagger_file(path) + except Exception as e: + raise ValueError("Error checking file %s" % (path,), e) diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py index 232ca8adc..4b4922fff 100755 --- a/scripts/dump-swagger.py +++ b/scripts/dump-swagger.py @@ -31,7 +31,7 @@ import yaml scripts_dir = os.path.dirname(os.path.abspath(__file__)) templating_dir = os.path.join(scripts_dir, "templating") -api_dir = os.path.join(os.path.dirname(scripts_dir), "api") +api_dir = os.path.join(os.path.dirname(scripts_dir), "data", "api") sys.path.insert(0, templating_dir) diff --git a/scripts/package.json b/scripts/package.json new file mode 100644 index 000000000..84b9dd7b5 --- /dev/null +++ b/scripts/package.json @@ -0,0 +1,15 @@ +{ + "name": "swagger-cli-validator", + "version": "0.0.1", + "description": "", + "main": "validator.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + "dependencies": { + "nopt": "^3.0.2", + "swagger-parser": "^3.2.1" + } +} diff --git a/scripts/test-and-build.sh b/scripts/test-and-build.sh index f45e2da61..76f49e2e8 100755 --- a/scripts/test-and-build.sh +++ b/scripts/test-and-build.sh @@ -11,12 +11,16 @@ virtualenv -p python3 env python --version pip --version +# Install python dependencies pip install -r scripts/requirements.txt +# Install node dependencies +npm install --prefix=scripts + # do sanity checks on the examples and swagger -(cd event-schemas/ && ./check_examples.py) -(cd api && ./check_examples.py) -(cd api && npm install && node validator.js -s "client-server") +scripts/check-event-schema-examples.py +scripts/check-swagger-sources.py +node scripts/validator.js --schema "data/api/client-server" : ${GOPATH:=${WORKSPACE}/.gopath} mkdir -p "${GOPATH}" diff --git a/scripts/validator.js b/scripts/validator.js new file mode 100644 index 000000000..c20dd9930 --- /dev/null +++ b/scripts/validator.js @@ -0,0 +1,86 @@ +"use strict"; +var fs = require("fs"); +var nopt = require("nopt"); +var parser = require("swagger-parser"); +var path = require("path"); + +var opts = nopt({ + "help": Boolean, + "schema": path +}, { + "h": "--help", + "s": "--schema" +}); + +if (opts.help) { + console.log( + "Use swagger-parser to validate against Swagger 2.0\n"+ + "Usage:\n"+ + " node validator.js -s " + ); + process.exit(0); +} +if (!opts.schema) { + console.error("No [s]chema specified."); + process.exit(1); +} + + +var errFn = function(err, api) { + if (!err) { + return; + } + console.error(err); + process.exit(1); +}; + +/** + * @brief Produce a handler for parser.validate(). + * Recommended usage: `parser.validate(filename, makeHandler(filename));` + * or `parser.validate(schema, makeHandler());`. + * @param scope - usually a filename, this will be used to denote + * an (in)valid schema in console output; "Schema" if undefined + * @returns {function} the handler that can be passed to parser.validate + */ +function makeHandler(scope) { + if (!scope) + scope = "Schema"; + return function(err, api, metadata) { + if (err) { + console.error("%s is not valid.", scope || "Schema"); + errFn(err, api, metadata); // Won't return + } + + Object.keys(api.paths).forEach(function (endpoint) { + var operationsMap = api.paths[endpoint]; + Object.keys(operationsMap).forEach(function (verb) { + if (!operationsMap[verb]["operationId"]) { + console.error("%s is not valid", scope); + errFn("operationId is missing in " + endpoint + ", verb " + verb, api); + } + }) + }); + + console.log("%s is valid.", scope); + } +} + +var isDir = fs.lstatSync(opts.schema).isDirectory(); +if (isDir) { + console.log("Checking directory %s for .yaml files...", opts.schema); + fs.readdir(opts.schema, function(err, files) { + if (err) { + errFn(err); // Won't return + } + files.forEach(function(f) { + var suffix = ".yaml"; + if (f.indexOf(suffix, f.length - suffix.length) > 0) { + parser.validate(path.join(opts.schema, f), makeHandler(f)); + } + }); + }); +} +else{ + parser.validate(opts.schema, makeHandler(opts.schema)); +} +