Merge remote-tracking branch 'matrix-org/master' into travis/releases/push-gateway/r0.1.0
Travis Ralston
6 years ago
commit
2ab2f91088
@ -0,0 +1,86 @@
|
||||
# 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: "/"
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
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
|
||||
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
|
||||
@ -0,0 +1,83 @@
|
||||
# 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: "/"
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
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
|
||||
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
|
||||
@ -0,0 +1,74 @@
|
||||
# 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: "/"
|
||||
produces:
|
||||
- application/json
|
||||
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
|
||||
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: A list of events.
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"events": [
|
||||
{"$ref": "../../event-schemas/examples/m.room.member"},
|
||||
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
|
||||
]
|
||||
}
|
||||
description: Transaction information
|
||||
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
|
||||
@ -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:domain.com"
|
||||
- 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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -0,0 +1,103 @@
|
||||
# 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 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:
|
||||
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``.
|
||||
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']
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- OpenID
|
||||
@ -0,0 +1,66 @@
|
||||
# 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.
|
||||
examples:
|
||||
application/json: {
|
||||
"m.homeserver": {
|
||||
"base_url": "https://matrix.example.com"
|
||||
},
|
||||
"m.identity_server": {
|
||||
"base_url": "https://identity.example.com"
|
||||
}
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
m.homeserver:
|
||||
description: Information about the homeserver to connect to.
|
||||
"$ref": "definitions/wellknown/homeserver.yaml"
|
||||
m.identity_server:
|
||||
description: Optional. Information about the identity server to connect to.
|
||||
"$ref": "definitions/wellknown/identity_server.yaml"
|
||||
additionalProperties:
|
||||
description: Application-dependent keys using Java package naming convention.
|
||||
required:
|
||||
- m.homeserver
|
||||
404:
|
||||
description: No server discovery information available.
|
||||
tags:
|
||||
- Server administration
|
||||
@ -0,0 +1,212 @@
|
||||
# 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
|
||||
- http
|
||||
basePath: /_matrix/identity/api/v1
|
||||
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 service will send an SMS message containing a token. If
|
||||
that token is presented to the identity service 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 Home Servers 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 older versions of this
|
||||
specification, the parameters may also be specified as
|
||||
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||
deprecated.
|
||||
operationId: msisdnRequestToken
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
schema:
|
||||
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 used to identify the validation attempt.
|
||||
country:
|
||||
type: string
|
||||
description: |-
|
||||
The two-letter uppercase ISO country code that the number in
|
||||
``phone_number`` should be parsed as if it were dialled from.
|
||||
phone_number:
|
||||
type: string
|
||||
description: The phone number to validate.
|
||||
send_attempt:
|
||||
type: integer
|
||||
description: |-
|
||||
Optional. If specified, the server will only send an SMS if
|
||||
the ``send_attempt`` is a number greater than the most recent
|
||||
one which it has seen (or if it has never seen one), 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 service. The client should increment this value if
|
||||
they desire a new SMS (e.g. a reminder) to be sent.
|
||||
next_link:
|
||||
type: string
|
||||
description: |-
|
||||
Optional. When the validation is completed, the identity
|
||||
service will redirect the user to this URL.
|
||||
required: ["client_secret", "country", "phone_number"]
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
Session created.
|
||||
examples:
|
||||
application/json: {
|
||||
"sid": "1234"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
sid:
|
||||
type: string
|
||||
description: The session ID.
|
||||
required: ['sid']
|
||||
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.
|
||||
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.
|
||||
|
||||
Note: for backwards compatibility with older versions of this
|
||||
specification, the parameters may also be specified as
|
||||
``application/x-form-www-urlencoded`` data. However, this usage is
|
||||
deprecated.
|
||||
operationId: msisdnSubmitTokenPost
|
||||
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
|
||||
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.
|
||||
@ -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']
|
||||
@ -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.presence_accept
|
||||
description: |-
|
||||
An EDU representing approval for the observing user to subscribe to the
|
||||
presence of the the observed user.
|
||||
allOf:
|
||||
- $ref: ../edu.yaml
|
||||
- type: object
|
||||
properties:
|
||||
edu_type:
|
||||
type: enum
|
||||
enum: ['m.presence_accept']
|
||||
description: The string ``m.presence_accept``
|
||||
example: "m.presence_accept"
|
||||
content:
|
||||
type: object
|
||||
description: The invite information.
|
||||
title: Invite Information
|
||||
properties:
|
||||
observed_user:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID that has approved the ``observer_user`` to
|
||||
subscribe to their presence.
|
||||
example: "@alice:elsewhere.com"
|
||||
observer_user:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID that requested to subscribe to the presence of
|
||||
the ``observed_user``.
|
||||
example: "@john:matrix.org"
|
||||
required: ['observer_user', 'observed_user']
|
||||
@ -0,0 +1,55 @@
|
||||
# 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_deny
|
||||
description: |-
|
||||
An EDU representing a declination or revocation for the observing user
|
||||
to subscribe to the presence of the observed user.
|
||||
example: {
|
||||
"origin": "domain.com",
|
||||
"destination": "elsewhere.org",
|
||||
"edu_type": "m.presence_deny",
|
||||
"content": {
|
||||
"observed_user": "@alice:elsewhere.org",
|
||||
"observer_user": "@john:domain.com"
|
||||
}
|
||||
}
|
||||
allOf:
|
||||
- $ref: ../edu.yaml
|
||||
- type: object
|
||||
properties:
|
||||
edu_type:
|
||||
type: enum
|
||||
enum: ['m.presence_deny']
|
||||
description: The string ``m.presence_deny``
|
||||
example: "m.presence_deny"
|
||||
content:
|
||||
type: object
|
||||
description: The invite information.
|
||||
title: Invite Information
|
||||
properties:
|
||||
observed_user:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID that has declined or revoked the ``observer_user`` from
|
||||
subscribing to their presence.
|
||||
example: "@alice:elsewhere.com"
|
||||
observer_user:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID that requested to subscribe to the presence of
|
||||
the ``observed_user``.
|
||||
example: "@john:matrix.org"
|
||||
required: ['observer_user', 'observed_user']
|
||||
@ -0,0 +1,45 @@
|
||||
# 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_invite
|
||||
description: |-
|
||||
An EDU representing a request to subscribe to a user's presence.
|
||||
allOf:
|
||||
- $ref: ../edu.yaml
|
||||
- type: object
|
||||
properties:
|
||||
edu_type:
|
||||
type: enum
|
||||
enum: ['m.presence_invite']
|
||||
description: The string ``m.presence_invite``
|
||||
example: "m.presence_invite"
|
||||
content:
|
||||
type: object
|
||||
description: The invite information.
|
||||
title: Invite Information
|
||||
properties:
|
||||
observed_user:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID the ``observer_user`` would like to subscribe
|
||||
to the presence of.
|
||||
example: "@alice:elsewhere.com"
|
||||
observer_user:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID that is wishing to subscribe to the presence of
|
||||
the ``observed_user``.
|
||||
example: "@john:matrix.org"
|
||||
required: ['observer_user', 'observed_user']
|
||||
@ -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:domain.com": {
|
||||
"m.read": {
|
||||
"@john:matrix.org": {
|
||||
"event_ids": ["$read_this_event:matrix.org"],
|
||||
"data": {
|
||||
"ts": 1533358089009
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -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`_ section.
|
||||
name: Authorization
|
||||
in: header
|
||||
@ -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: path
|
||||
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"
|
||||
}
|
||||
@ -0,0 +1 @@
|
||||
Specify how to control the power level required for ``@room``
|
||||
@ -0,0 +1 @@
|
||||
Clarify ``changed`` field behaviour in device tracking process
|
||||
@ -0,0 +1,7 @@
|
||||
End-to-end encryption for group chats:
|
||||
|
||||
- Olm and Megolm messaging algorithms.
|
||||
- ``m.room.encrypted``, ``m.room.encryption``, ``m.room_key`` events.
|
||||
- Device verification process.
|
||||
- ``device_one_time_keys_count`` sync parameter.
|
||||
- ``device_lists:left`` sync parameter.
|
||||
@ -0,0 +1 @@
|
||||
Add ``.well-known`` server discovery method
|
||||
@ -0,0 +1 @@
|
||||
``POST /account/3pid/msisdn/requestToken``, ``POST /register/msisdn/requestToken``, and ``POST /account/password/msisdn/requestToken``
|
||||
@ -0,0 +1 @@
|
||||
Add support for Room Versions.
|
||||
@ -0,0 +1 @@
|
||||
Clarify how access tokens are meant to be supplied to the homeserver.
|
||||
@ -0,0 +1 @@
|
||||
Document additional parameters on the ``/createRoom`` API.
|
||||
@ -0,0 +1 @@
|
||||
Guests can now call /context and /event to fetch events
|
||||
@ -0,0 +1 @@
|
||||
Add a common standard for user, room, and group mentions in messages.
|
||||
@ -0,0 +1 @@
|
||||
Add server ACLs as an option for controlling federation in a room.
|
||||
@ -0,0 +1 @@
|
||||
Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match.
|
||||
@ -0,0 +1 @@
|
||||
Add new push rules for encrypted events and ``@room`` notifications.
|
||||
@ -0,0 +1 @@
|
||||
Add third party network room directories, as provided by application services.
|
||||
@ -0,0 +1 @@
|
||||
Clarify the supported HTML features for room messages.
|
||||
@ -0,0 +1 @@
|
||||
Move the ``invite_room_state`` definition under ``unsigned`` where it actually resides.
|
||||
@ -0,0 +1 @@
|
||||
Clarify the object structures and defaults for Filters.
|
||||
@ -0,0 +1 @@
|
||||
Clarify instances of ``type: number`` in the swagger/OpenAPI schema definitions.
|
||||
@ -0,0 +1 @@
|
||||
Clarify that left rooms also have account data in ``/sync``.
|
||||
@ -0,0 +1 @@
|
||||
Fix naming of the body field in ``PUT /directory/room``.
|
||||
@ -0,0 +1 @@
|
||||
Clarify the filter object schema used in room searching.
|
||||
@ -0,0 +1,14 @@
|
||||
{
|
||||
"content": {
|
||||
"algorithm": "m.megolm.v1.aes-sha2",
|
||||
"ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...",
|
||||
"device_id": "RJYKSTBOIE",
|
||||
"sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA",
|
||||
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ"
|
||||
},
|
||||
"event_id": "$WLGTSEFSEF:localhost",
|
||||
"room_id": "!Cuyf34gef24t:localhost",
|
||||
"origin_server_ts": 1476648761524,
|
||||
"sender": "@example:localhost",
|
||||
"type": "m.room.encrypted"
|
||||
}
|
||||
@ -0,0 +1,14 @@
|
||||
{
|
||||
"type": "m.room.encrypted",
|
||||
"sender": "@example:localhost",
|
||||
"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..."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,13 @@
|
||||
{
|
||||
"content": {
|
||||
"algorithm": "m.megolm.v1.aes-sha2",
|
||||
"rotation_period_ms": 604800000,
|
||||
"rotation_period_msgs": 100
|
||||
},
|
||||
"event_id": "$WLGTSEFJJKJ:localhost",
|
||||
"origin_server_ts": 1476648761524,
|
||||
"sender": "@example:localhost",
|
||||
"room_id": "!Cuyf34gef24t:localhost",
|
||||
"state_key": "",
|
||||
"type": "m.room.encryption"
|
||||
}
|
||||
@ -0,0 +1,14 @@
|
||||
{
|
||||
"age": 242352,
|
||||
"content": {
|
||||
"allow_ip_literals": false,
|
||||
"allow": ["*"],
|
||||
"deny": ["*.evil.com", "evil.com"]
|
||||
},
|
||||
"state_key": "",
|
||||
"origin_server_ts": 1431961217939,
|
||||
"event_id": "$WLGTSEFSEF:localhost",
|
||||
"type": "m.room.server_acl",
|
||||
"room_id": "!Cuyf34gef24t:localhost",
|
||||
"sender": "@example:localhost"
|
||||
}
|
||||
@ -0,0 +1,9 @@
|
||||
{
|
||||
"content": {
|
||||
"algorithm": "m.megolm.v1.aes-sha2",
|
||||
"room_id": "!Cuyf34gef24t:localhost",
|
||||
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
|
||||
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
|
||||
},
|
||||
"type": "m.room_key"
|
||||
}
|
||||
@ -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`_), or
|
||||
as a `to-device`_ 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`_.
|
||||
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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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`_ 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
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue