Merge branch 'master' into travis/clarification/lowercasing
Travis Ralston
4 years ago
commit
9dc3830e92
@ -0,0 +1 @@
|
||||
Correct examples of `client_secret` request body parameters so that they do not include invalid characters.
|
||||
@ -0,0 +1 @@
|
||||
The v1 identity service API has been removed in favour of the v2 API, as per [MSC2713](https://github.com/matrix-org/matrix-doc/pull/2713).
|
||||
@ -0,0 +1,66 @@
|
||||
{
|
||||
"Pin": "Rajszeg",
|
||||
"Folder": "Mappa",
|
||||
"Headphones": "Fejhallgató",
|
||||
"Anchor": "Horgony",
|
||||
"Bell": "Harang",
|
||||
"Trumpet": "Trombita",
|
||||
"Guitar": "Gitár",
|
||||
"Ball": "Labda",
|
||||
"Trophy": "Trófea",
|
||||
"Rocket": "Rakáta",
|
||||
"Aeroplane": "Repülő",
|
||||
"Bicycle": "Kerékpár",
|
||||
"Train": "Vonat",
|
||||
"Flag": "Zászló",
|
||||
"Telephone": "Telefon",
|
||||
"Hammer": "Kalapács",
|
||||
"Key": "Kulcs",
|
||||
"Lock": "Lakat",
|
||||
"Scissors": "Olló",
|
||||
"Paperclip": "Gémkapocs",
|
||||
"Pencil": "Ceruza",
|
||||
"Book": "Könyv",
|
||||
"Light Bulb": "Égő",
|
||||
"Gift": "Ajándék",
|
||||
"Clock": "Óra",
|
||||
"Hourglass": "Homokóra",
|
||||
"Umbrella": "Esernyő",
|
||||
"Thumbs Up": "Hüvelykujj fel",
|
||||
"Santa": "Télapó",
|
||||
"Spanner": "Csavarkulcs",
|
||||
"Glasses": "Szemüveg",
|
||||
"Hat": "Kalap",
|
||||
"Robot": "Robot",
|
||||
"Smiley": "Mosoly",
|
||||
"Heart": "Szív",
|
||||
"Cake": "Süti",
|
||||
"Pizza": "Pizza",
|
||||
"Corn": "Kukorica",
|
||||
"Strawberry": "Eper",
|
||||
"Apple": "Alma",
|
||||
"Banana": "Banán",
|
||||
"Fire": "Tűz",
|
||||
"Cloud": "Felhő",
|
||||
"Moon": "Hold",
|
||||
"Globe": "Földgömb",
|
||||
"Mushroom": "Gomba",
|
||||
"Cactus": "Kaktusz",
|
||||
"Tree": "Fa",
|
||||
"Flower": "Virág",
|
||||
"Butterfly": "Pillangó",
|
||||
"Octopus": "Polip",
|
||||
"Fish": "Hal",
|
||||
"Turtle": "Teknős",
|
||||
"Penguin": "Pingvin",
|
||||
"Rooster": "Kakas",
|
||||
"Panda": "Panda",
|
||||
"Rabbit": "Nyúl",
|
||||
"Elephant": "Elefánt",
|
||||
"Pig": "Malac",
|
||||
"Unicorn": "Egyszarvú",
|
||||
"Horse": "Ló",
|
||||
"Lion": "Oroszlán",
|
||||
"Cat": "Macska",
|
||||
"Dog": "Kutya"
|
||||
}
|
||||
@ -1,302 +0,0 @@
|
||||
# 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.
|
||||
@ -1,177 +0,0 @@
|
||||
# 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.
|
||||
@ -1,97 +0,0 @@
|
||||
# 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"
|
||||
@ -1,171 +0,0 @@
|
||||
# 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"
|
||||
@ -1,179 +0,0 @@
|
||||
# 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.
|
||||
@ -1,46 +0,0 @@
|
||||
# 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
|
||||
@ -1,129 +0,0 @@
|
||||
# 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']
|
||||
@ -1,161 +0,0 @@
|
||||
# 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"
|
||||
@ -0,0 +1,427 @@
|
||||
# Proposal for Matrix "spaces" (formerly known as "groups as rooms (take 2)")
|
||||
|
||||
This MSC, and related proposals, supercede
|
||||
[MSC1215](https://github.com/matrix-org/matrix-doc/issues/1215).
|
||||
|
||||
## Background and objectives
|
||||
|
||||
Collecting rooms together into groups is useful for a number of
|
||||
purposes. Examples include:
|
||||
|
||||
* Allowing users to discover different rooms related to a particular topic:
|
||||
for example "official matrix.org rooms".
|
||||
* Allowing administrators to manage permissions across a number of rooms: for
|
||||
example "a new employee has joined my company and needs access to all of our
|
||||
rooms".
|
||||
* Letting users classify their rooms: for example, separating "work" from
|
||||
"personal" rooms.
|
||||
|
||||
We refer to such collections of rooms as "spaces".
|
||||
|
||||
Synapse and Element-Web currently implement an unspecced "groups" API (referred
|
||||
to as "`/r0/groups`" in this document) which attempts to provide this
|
||||
functionality (see
|
||||
[MSC971](https://github.com/matrix-org/matrix-doc/issues/971)). However,
|
||||
this is a complex API which has various problems (see
|
||||
[appendix](#appendix-problems-with-the-r0groups-api)).
|
||||
|
||||
This proposal suggests a new approach where spaces are themselves represented
|
||||
by rooms, rather than a custom first-class entity. This requires minimal
|
||||
server changes.
|
||||
|
||||
The existing `/r0/groups` API would be deprecated in Synapse and remain
|
||||
unspecified.
|
||||
|
||||
## Proposal
|
||||
|
||||
Each space is represented by its own room, known as a "space-room". The rooms
|
||||
within the space are determined by state events within the space-room.
|
||||
|
||||
Space-rooms are distinguished from regular messaging rooms by the presence of
|
||||
a `'type': 'm.space'` property in the content of the `m.room.create` event.
|
||||
The value of the `type` property uses the Standardised Identifier Grammar from
|
||||
[MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758). This allows clients to offer slightly customised user experience
|
||||
depending on the purpose of the room. Currently, no server-side behaviour is
|
||||
expected to depend on this property. A `type` property on the `m.room.create`
|
||||
event is used to ensure that a room cannot change between being a space-room
|
||||
and a non-space room. For more information, see the "Rejected Alternatives"
|
||||
section below. Additionally, no client behaviour is recommended for handling
|
||||
unknown room types given the potential for legacy data: clients are free to
|
||||
make their own decisions about hiding unknown room types from users, though
|
||||
should note that a future conversation-like type (for example) might be
|
||||
introduced and could be considered "unknown" by older versions of their client.
|
||||
|
||||
As with regular rooms, public spaces are expected to have an alias, for example
|
||||
`#foo:matrix.org`, which can be used to refer to the space.
|
||||
|
||||
Space-rooms may have `m.room.name`, `m.room.avatar` and `m.room.topic` state
|
||||
events in the same way as a normal room.
|
||||
|
||||
Normal messages within a space-room are discouraged (but not blocked by the
|
||||
server): user interfaces are not expected to have a way to enter or display
|
||||
such messages. Space-rooms should be created with a power level for
|
||||
`events_default` of 100, to prevent the rooms accidentally/maliciously
|
||||
clogging up with messages from random members of the space.
|
||||
|
||||
### Membership of spaces
|
||||
|
||||
Users can be members of spaces (represented by `m.room.member` state events as
|
||||
normal). The existing [`m.room.history_visibility`
|
||||
mechanism](https://matrix.org/docs/spec/client_server/r0.6.1#room-history-visibility)
|
||||
controls whether membership of the space is required to view the room list,
|
||||
membership list, etc. "Public" or "community" spaces would be set to
|
||||
`world_readable` to allow clients to see the directory of rooms within the
|
||||
space by peeking into the space-room (thus avoiding the need to add
|
||||
`m.room.member` events to the event graph within the room).
|
||||
|
||||
Join rules, invites and 3PID invites work as for a normal room. In order for
|
||||
clients to distinguish space invites from room invites, all invites must now
|
||||
include the `m.room.create` event in their `invite_state` and `knock_state`.
|
||||
|
||||
### Relationship between rooms and spaces
|
||||
|
||||
The intention is that rooms and spaces form a hierarchy, which clients can use
|
||||
to structure the user's room list into a tree view. The parent/child
|
||||
relationship can be expressed in one of two ways:
|
||||
|
||||
1. The admins of a space can advertise rooms and subspaces for their space by
|
||||
setting `m.space.child` state events. The `state_key` is the ID of a child
|
||||
room or space, and the content must contain a `via` key which gives a list
|
||||
of candidate servers that can be used to join the room. Something like:
|
||||
|
||||
```jsonc
|
||||
// a child room
|
||||
{
|
||||
"type": "m.space.child",
|
||||
"state_key": "!abcd:example.com",
|
||||
"content": {
|
||||
"via": ["example.com", "test.org"]
|
||||
}
|
||||
}
|
||||
|
||||
// a child room with an ordering.
|
||||
{
|
||||
"type": "m.space.child",
|
||||
"state_key": "!efgh:example.com",
|
||||
"content": {
|
||||
"via": ["example.com"],
|
||||
"order": "abcd"
|
||||
}
|
||||
}
|
||||
|
||||
// no longer a child room
|
||||
{
|
||||
"type": "m.space.child",
|
||||
"state_key": "!jklm:example.com",
|
||||
"content": {}
|
||||
}
|
||||
```
|
||||
|
||||
Children where `via` is not present or invalid (not an array) are ignored.
|
||||
|
||||
The `order` key is a string which is used to provide a default ordering of
|
||||
siblings in the room list. (Rooms are sorted based on a lexicographic
|
||||
ordering of the Unicode codepoints of the characters in `order` values.
|
||||
Rooms with no `order` come last, in ascending numeric order of the
|
||||
`origin_server_ts` of their `m.room.create` events, or ascending
|
||||
lexicographic order of their `room_id`s in case of equal
|
||||
`origin_server_ts`. `order`s which are not strings, or do not consist
|
||||
solely of ascii characters in the range `\x20` (space) to `\x7E` (`~`), or
|
||||
consist of more than 50 characters, are forbidden and the field should be
|
||||
ignored if received.)
|
||||
|
||||
2. Separately, rooms can claim parents via the `m.space.parent` state
|
||||
event.
|
||||
|
||||
Similar to `m.space.child`, the `state_key` is the ID of the parent space,
|
||||
and the content must contain a `via` key which gives a list of candidate
|
||||
servers that can be used to join the parent.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"type": "m.space.parent",
|
||||
"state_key": "!space:example.com",
|
||||
"content": {
|
||||
"via": ["example.com"],
|
||||
"canonical": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Parents where `via` is not present or invalid (not an array) are ignored.
|
||||
|
||||
`canonical` determines whether this is the main parent for the space. When
|
||||
a user joins a room with a canonical parent, clients may switch to view the
|
||||
room in the context of that space, peeking into it in order to find other
|
||||
rooms and group them together. In practice, well behaved rooms should only
|
||||
have one `canonical` parent, but given this is not enforced: if multiple
|
||||
are present the client should select the one with the lowest room ID, as
|
||||
determined via a lexicographic ordering of the Unicode code-points.
|
||||
|
||||
To avoid abuse where a room admin falsely claims that a room is part of a
|
||||
space that it should not be, clients could ignore such `m.space.parent`
|
||||
events unless either (a) there is a corresponding `m.space.child` event in
|
||||
the claimed parent, or (b) the sender of the `m.space.child` event has a
|
||||
sufficient power-level to send such an `m.space.child` event in the
|
||||
parent. (It is not necessarily required that that user currently be a
|
||||
member of the parent room - only the `m.room.power_levels` event is
|
||||
inspected.) [Checking the power-level rather than requiring an *actual*
|
||||
`m.space.child` event in the parent allows for "secret" rooms (see below).]
|
||||
|
||||
Where the parent space also claims a parent, clients can recursively peek
|
||||
into the grandparent space, and so on.
|
||||
|
||||
This structure means that rooms can end up appearing multiple times in the
|
||||
room list hierarchy, given they can be children of multiple different spaces
|
||||
(or have multiple parents in different spaces).
|
||||
|
||||
In a typical hierarchy, we expect *both* parent->child and child->parent
|
||||
relationships to exist, so that the space can be discovered from the room, and
|
||||
vice versa. Occasions when the relationship only exists in one direction
|
||||
include:
|
||||
|
||||
* User-curated lists of rooms: in this case the space will not be listed as a
|
||||
parent of the room.
|
||||
|
||||
* "Secret" rooms: rooms where the admin does not want the room to be
|
||||
advertised as part of a given space, but *does* want the room to form part
|
||||
of the hierarchy of that space for those in the know.
|
||||
|
||||
Cycles in the parent->child and child->parent relationships are *not*
|
||||
permitted, but clients (and servers) should be aware that they may be
|
||||
encountered, and MUST spot and break cycles rather than infinitely looping.
|
||||
|
||||
### Suggested children
|
||||
|
||||
Space admins can mark particular children of a space as "suggested". This
|
||||
mainly serves as a hint to clients that that they can be displayed differently
|
||||
(for example by showing them eagerly in the room list), though future
|
||||
server-side interfaces (such as the summary API proposed in
|
||||
[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946)) might also
|
||||
make use of it.
|
||||
|
||||
A suggested child is identified by a `"suggested": true` property in the
|
||||
`m.space.child` event:
|
||||
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"type": "m.space.child",
|
||||
"state_key": "!abcd:example.com",
|
||||
"content": {
|
||||
"via": ["example.com", "test.org"],
|
||||
"suggested": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A child which is missing the `suggested` property is treated identically to a
|
||||
child with `"suggested": false`. A suggested child may be a room or a subspace.
|
||||
|
||||
### Extended "room invite state"
|
||||
|
||||
The specification is currently vague about what room state should be available
|
||||
to users that have been invited to a room, though the Federation API spec does
|
||||
recommend that the `invite_room_state` sent over federation via [PUT
|
||||
`/_matrix/federation/v2/invite`](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid)
|
||||
should include "the join rules, canonical alias, avatar, and name of the room".
|
||||
|
||||
This MSC proposes adding `m.room.create` to that list, so that the recipient of
|
||||
an invite can distinguish invites to spaces from other invites.
|
||||
|
||||
## Future extensions
|
||||
|
||||
The following sections are not blocking parts of this proposal, but are
|
||||
included as a useful reference for how we imagine it will be extended in future.
|
||||
|
||||
### Auto-joined children
|
||||
|
||||
We could add an `auto_join` flag to `m.space.child` events to allow a space
|
||||
admin to list the sub-spaces and rooms in that space which should be
|
||||
automatically joined by members of that space.
|
||||
|
||||
This would be distinct from a force-join: the user could subsequently part any
|
||||
auto-joined room if they desire.
|
||||
|
||||
Joining would be performed by the client. This could possibly be sped up by
|
||||
using a summary API (such as that proposed in
|
||||
[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946)) to get a summary
|
||||
of the spacetree to be joined, and then using a batch join API to join
|
||||
whichever subset of it makes most sense for the client's UX.
|
||||
|
||||
Obviously auto-joining can be a DoS vector, and we consider it to be antisocial
|
||||
for a space to try to autojoin its members to more than 100 children (in total).
|
||||
|
||||
Clients could display the auto-joined children in the room list whenever the
|
||||
space appears in the list - thus helping users discover other rooms in a space
|
||||
even if they're not joined to that space. For instance, if you join
|
||||
`#matrix:matrix.org`, your client could show that room in the context of its
|
||||
parent space, with that space's auto-joined children shown alongside it as
|
||||
siblings.
|
||||
|
||||
### Restricting access to the spaces membership list
|
||||
|
||||
In the existing `/r0/groups` API, the group server has total control over the
|
||||
visibility of group membership, as seen by a given querying user. In other
|
||||
words, arbitrary users can see entirely different views of a group at the
|
||||
server's discretion.
|
||||
|
||||
Whilst this is very powerful for mapping arbitrary organisational structures
|
||||
into Matrix, it may be overengineered. Instead, the common case is (we believe)
|
||||
a space where some users are publicly visible as members, and others are not.
|
||||
|
||||
One way of achieving this would be to create a separate space for the
|
||||
private members - e.g. have `#foo:matrix.org` and `#foo-private:matrix.org`.
|
||||
`#foo-private:matrix.org` is set up with `m.room.history_visibility` to not to
|
||||
allow peeking; you have to be joined to see the members.
|
||||
|
||||
It's worth noting that any member of a space can currently see who else is a
|
||||
member of that space, which might pose privacy problems for sensitive spaces.
|
||||
While the server itself will inevitably track the space membership in state
|
||||
events, a future MSC could restrict the membership from being sent to clients.
|
||||
This is essentially the same as
|
||||
[matrix-doc#1653](https://github.com/matrix-org/matrix-doc/issues/1653).
|
||||
|
||||
### Flair
|
||||
|
||||
("Flair" is a term we use to describe a small badge which appears next to a
|
||||
user's displayname to advertise their membership of a space.)
|
||||
|
||||
The flair image for a group is given by the room avatar. (In future it might
|
||||
preferable to use hand-crafted small resolution images: see
|
||||
[matrix-doc#1778](https://github.com/matrix-org/matrix-doc/issues/1778).
|
||||
|
||||
One way this might be implemented is:
|
||||
|
||||
* User publishes the spaces they wish to announce on their profile
|
||||
([MSC1769](https://github.com/matrix-org/matrix-doc/issues/1769)
|
||||
as an `m.flair` state event: it lists the spaces which they are advertising.
|
||||
|
||||
* When a client wants to know the current flair for a set of users (i.e.
|
||||
those which it is currently displaying in the timeline), it peeks the
|
||||
profile rooms of those users. (Ideally there would be an API to support
|
||||
peeking multiple rooms at once to facilitate this.)
|
||||
|
||||
* The client must check that the user is *actually* a member of the advertised
|
||||
spaces. Nominally it can do this by peeking the membership list of the
|
||||
space; however for efficiency we could expose a dedicated Client-Server API
|
||||
to do this check (and both servers and clients can cache the results fairly
|
||||
aggressively.)
|
||||
|
||||
## Related MSCs
|
||||
|
||||
* [MSC2946](https://github.com/matrix-org/matrix-doc/issues/2946): Spaces
|
||||
Summary API.
|
||||
|
||||
* [MSC2962](https://github.com/matrix-org/matrix-doc/issues/2962): Managing
|
||||
power levels via Spaces.
|
||||
|
||||
* [MSC3083](https://github.com/matrix-org/matrix-doc/issues/3083): Restricting
|
||||
room membership based on space membership.
|
||||
|
||||
* [MSC2753](https://github.com/matrix-org/matrix-doc/issues/2753) for
|
||||
effective peeking over the C/S API.
|
||||
|
||||
* [MSC2444](https://github.com/matrix-org/matrix-doc/issues/2444) (or similar)
|
||||
for effective peeking over Federation.
|
||||
|
||||
## Security considerations
|
||||
|
||||
None at present.
|
||||
|
||||
## Potential issues
|
||||
|
||||
* If the membership of a space would be large (for example: an organisation of
|
||||
several thousand people), this membership has to be copied entirely into the
|
||||
room, rather than querying/searching incrementally.
|
||||
|
||||
* If the membership list is based on an external service such as LDAP, it is
|
||||
hard to keep the space membership in sync with the LDAP directory. In
|
||||
practice, it might be possible to do so via a nightly "synchronisation" job
|
||||
which searches the LDAP directory, or via "AD auditing".
|
||||
|
||||
* No allowance is made for exposing different 'views' of the membership list to
|
||||
different querying users. (It may be possible to simulate this behaviour
|
||||
using smaller spaces).
|
||||
|
||||
* The requirement that `m.space.parent` links be ignored unless the sender has a
|
||||
high PL in the parent room could lead to suprising effects where a parent
|
||||
link suddenly ceases to take effect because a user loses their PL in the
|
||||
parent room. This is mitigated in the general case by honouring the parent
|
||||
link when there is a corresponding `m.space.child` event, however it remains
|
||||
a problem for "secret" rooms.
|
||||
|
||||
* The `via` servers listed in the `m.space.child` and `m.space.parent` events
|
||||
could get out of date, and will need to be updated from time to time. This
|
||||
remains an unsolved problem.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
### Use a separate state event for type of room
|
||||
|
||||
[MSC1840](https://github.com/matrix-org/matrix-doc/pull/1840) proposes the use
|
||||
of a separate `m.room.type` state event to distinguish different room types.
|
||||
This implies that rooms can dynamically switch between being a Space, and
|
||||
being a regular non-Space room. That is not a usecase we consider useful, and
|
||||
allowing it would impose significant complexity on client and server
|
||||
implementations. Specifically, client and server implementations who store
|
||||
spaces separately from rooms would have to support migrating back and forth
|
||||
between them and dealing with the ambiguities of `room_id`s no longer pointing
|
||||
to valid spaces, etc.
|
||||
|
||||
### Use a different sigil/twigil for spaces
|
||||
|
||||
Groups used + as a sigil to differentiate them from rooms (e.g. +matrix:matrix.org).
|
||||
We considered doing similar for Spaces, e.g. a #+ twigil or reuse the + sigil,
|
||||
but concluded that the resulting complexity and exoticism is not worth it.
|
||||
This means that clients such as matrix.to have to peek into rooms to find out their
|
||||
`type` before being able to display an appropriate UI, and users will not know
|
||||
whether #matrix:matrix.org is a room or a space without using a client (e.g. if
|
||||
reading an advert). It also means that if the client UI requires a space alias the
|
||||
client will need to validate the entered data serverside.
|
||||
|
||||
## Unstable prefix
|
||||
|
||||
The following mapping will be used for identifiers in this MSC during
|
||||
development:
|
||||
|
||||
Proposed final identifier | Purpose | Development identifier
|
||||
------------------------------- | ------- | ----
|
||||
`type` | property in `m.room.create` | `org.matrix.msc1772.type`
|
||||
`m.space` | value of `type` in `m.room.create` | `org.matrix.msc1772.space`
|
||||
`m.space.child` | event type | `org.matrix.msc1772.space.child`
|
||||
`m.space.parent` | event type | `org.matrix.msc1772.space.parent`
|
||||
|
||||
## History
|
||||
|
||||
* This replaces [MSC1215](https://docs.google.com/document/d/1ZnAuA_zti-K2-RnheXII1F1-oyVziT4tJffdw1-SHrE).
|
||||
* Other thoughts that led into this are [documented](https://docs.google.com/document/d/1hljmD-ytdCRL37t-D_LvGDA3a0_2MwowSPIiZRxcabs).
|
||||
|
||||
## Appendix: problems with the `/r0/groups` API
|
||||
|
||||
The existing `/r0/groups` API, as proposed in
|
||||
[MSC971](https://github.com/matrix-org/matrix-doc/issues/971), has various
|
||||
problems, including:
|
||||
|
||||
* It is a large API surface to implement, maintain and spec - particularly for
|
||||
all the different clients out there.
|
||||
* Much of the API overlaps significantly with mechanisms we already have for
|
||||
managing rooms:
|
||||
* Tracking membership identity
|
||||
* Tracking membership hierarchy
|
||||
* Inviting/kicking/banning user
|
||||
* Tracking key/value metadata
|
||||
* There are membership management features which could benefit rooms which
|
||||
would also benefit groups and vice versa (e.g. "auditorium mode")
|
||||
* The current implementations on Riot Web/iOS/Android all suffer bugs and
|
||||
issues which have been solved previously for rooms.
|
||||
* no local-echo of invites
|
||||
* failures to set group avatars
|
||||
* ability to specify multiple admins
|
||||
* It doesn't support pushing updates to clients (particularly for flair
|
||||
membership): https://github.com/vector-im/riot-web/issues/5235
|
||||
* It doesn't support third-party invites.
|
||||
* Groups could benefit from other features which already exist today for rooms
|
||||
* e.g. Room Directories
|
||||
* Groups are centralised, rather than being replicated across all
|
||||
participating servers.
|
||||
@ -0,0 +1,40 @@
|
||||
# MSC3122: Deprecate starting key verifications without requesting first
|
||||
|
||||
Currently, the [Key verification
|
||||
framework](https://spec.matrix.org/unstable/client-server-api/#key-verification-framework)
|
||||
allows a device to begin a verification via to-device messages by sending an
|
||||
`m.key.verification.start` event without first sending or receiving an
|
||||
`m.key.verification.request` message. (The last sentence of the 5th paragraph
|
||||
of the Key verification framework in the unstable spec, as of the time of
|
||||
writing.) However, doing so does not provide a good user experience, and
|
||||
allowing this adds unnecessary complexity to implementations.
|
||||
|
||||
We propose to deprecate allowing this behaviour.
|
||||
|
||||
Note that verifications in DMs do not allow this behaviour. Currently, Element
|
||||
Web is the only client known to do this.
|
||||
|
||||
## Proposal
|
||||
|
||||
The ability to begin a key verification by sending an
|
||||
`m.key.verification.start` event as a to-device event without a prior
|
||||
`m.key.verification.request` is deprecated. New clients should not begin
|
||||
verifications in this way, but will still need to accept verifications begun in
|
||||
this way, until it is removed from the spec.
|
||||
|
||||
## Potential issues
|
||||
|
||||
None.
|
||||
|
||||
## Alternatives
|
||||
|
||||
We could do nothing and leave it in the spec. But we should clean up cruft when
|
||||
possible.
|
||||
|
||||
## Security considerations
|
||||
|
||||
None.
|
||||
|
||||
## Unstable prefix
|
||||
|
||||
No unstable prefix is required since we are simply deprecating behaviour.
|
||||
Loading…
Reference in New Issue