wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge remote-tracking branch 'origin/master' into cross-signing-spec

Browse source
This commit is contained in:
Hubert Chathi 2020-05-29 17:25:19 -04:00
commit ec0b9badc7
70 changed files with 1748 additions and 298 deletions
Download patch file Download diff file Expand all files Collapse all files

2
api/client-server/admin.yaml
View file

@ -82,7 +82,7 @@ paths:
devices:
type: object
description: |-
Each key is an identitfier for one of the user's devices.
Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo

16
api/client-server/create_room.yaml
View file

@ -38,20 +38,26 @@ paths:
the new room, including checking power levels for each event. It MUST
apply the events implied by the request in the following order:
0. A default ``m.room.power_levels`` event, giving the room creator
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.
1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
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.
2. Events listed in ``initial_state``, in the order that they are
5. Events listed in ``initial_state``, in the order that they are
listed.
3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
state events).
4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
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:

1
api/client-server/definitions/device_keys.yaml
View file

@ -47,6 +47,7 @@ properties:
"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
``<algorithm>:<device_id>`` to the signature.

4
api/client-server/definitions/third_party_signed.yaml
View file

@ -33,6 +33,10 @@ properties:
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"

82
api/client-server/directory.yaml
View file

@ -19,7 +19,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -27,7 +27,7 @@ produces:
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/room/{roomAlias}":
"/directory/room/{roomAlias}":
put:
summary: Create a new mapping from room alias to room ID.
operationId: setRoomAlias
@ -129,7 +129,16 @@ paths:
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.
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: []
@ -159,3 +168,70 @@ paths:
"$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

2
api/client-server/keys.yaml
View file

@ -102,7 +102,7 @@ paths:
responses:
200:
description:
The provided keys were sucessfully uploaded.
The provided keys were successfully uploaded.
schema:
type: object
properties:

13
api/client-server/registration.yaml
View file

@ -328,8 +328,8 @@ paths:
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, however all other access tokens
for the user should be revoked if the request succeeds.
access token provided in the request. Whether other access tokens for
the user are revoked depends on the request parameters.
security:
- accessToken: []
operationId: changePassword
@ -343,6 +343,15 @@ paths:
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 <#soft-logout>`_
for the user's remaining devices.
example: true
auth:
description: |-
Additional authentication information for the user-interactive authentication API.

2
api/client-server/room_send.yaml
View file

@ -85,5 +85,7 @@ paths:
type: string
description: |-
A unique identifier for the event.
required:
- event_id
tags:
- Room participation

26
api/client-server/room_state.yaml
View file

@ -45,6 +45,12 @@ 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`_ 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: []
@ -92,6 +98,8 @@ paths:
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.
@ -102,5 +110,23 @@ paths:
"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