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

convert IS endpoints to Swagger (#1427)

Browse source
This commit is contained in:
Hubert Chathi 2018-08-10 16:21:06 -04:00 • committed by GitHub
parent 292d334509
commit cd4fed509c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 587 additions and 134 deletions
Download patch file Download diff file Expand all files Collapse all files

179
api/identity/associations.yaml Normal file
View file

@ -0,0 +1,179 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Establishing Associations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
produces:
- application/json
paths:
"/3pid/getValidated3pid":
get:
summary: Check whether ownership of a 3pid was validated.
description: A client can check whether ownership of a 3pid was validated
operationId: getValidated3pid
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 indicating the time that the 3pid was validated.
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"
}
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"
}
"/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 older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: bind
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 services which show that the association should be trusted, if you trust the verifying identity services.
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"
}
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"
}

197
api/identity/email_associations.yaml Normal file
View file

@ -0,0 +1,197 @@
# 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
- http
basePath: /_matrix/identity/api/v1
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 service will send an email 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 email for that email address, and
so we validate ownership of the email address.
Note that Home Servers 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 older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: emailRequestToken
parameters:
- in: body
name: body
schema:
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"email": "foo@example.com",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt
email:
type: string
description: The email address to validate.
send_attempt:
type: integer
description: |-
Optional. If specified, the server will only send an email 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 ``email`` + ``client_secret`` pair. This is to avoid
repeatedly sending the same email in the case of request
retries between the POSTing user and the identity
service. The client should increment this value if they
desire a new email (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", "email"]
responses:
200:
description:
Session created.
examples:
application/json: {
"sid": "1234"
}
schema:
type: object
properties:
sid:
type: string
description: The session ID.
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.
"/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.
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: emailSubmitTokenPost
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.
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
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.

90
api/identity/invitation_signing.yaml Normal file
View file

@ -0,0 +1,90 @@
# 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
- http
basePath: /_matrix/identity/api/v1
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
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: Token from the call to ``store-invite``
private_key:
type: string
description: The private key, encoded as `Unpadded base64`_.
required: ["mxid", "token", "private_key"]
responses:
200:
description: The signedjson 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.
token:
type: string
description: The token for the invitation.
examples:
application/json: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
404:
description: Token was not found.
example: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}

114
api/identity/store_invite.yaml Normal file
View file

@ -0,0 +1,114 @@
# 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
- http
basePath: /_matrix/identity/api/v1
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``.
operationId: storeInvite
parameters:
- in: body
name: body
schema:
type: object
example: {
"medium": "email",
"address": "foo@bar.baz",
"room_id": "!something:example.tld",
"sender": "@bob:example.com"
}
properties:
medium:
type: string
description: The literal string ``email``.
address:
type: string
description: The email address of the invited user.
room_id:
type: string
description: The Matrix room ID to which the user is invited
sender:
type: string
description: The Matrix user ID of the inviting user
required: ["medium", "address", "room_id", "sender"]
responses:
200:
description: The invitation was stored.
schema:
type: object
properties:
token:
type: string
description: The generated token.
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.
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": mxid
}

141
specification/identity_service_api.rst
View file

@ -114,100 +114,15 @@ session, within a 24 hour period since its most recent modification. Any
attempts to perform these actions after the expiry will be rejected, and a new
session should be created and used instead.
Creating a session
Email associations
~~~~~~~~~~~~~~~~~~
A client makes a call to::
{{email_associations_is_http_api}}
POST https://my.id.server:8090/_matrix/identity/api/v1/validate/email/requestToken
General
~~~~~~~
client_secret=monkeys_are_GREAT&
email=foo@bar.com&
send_attempt=1
It may also optionally specify next_link. If next_link is specified, when the
validation is completed, the identity service will redirect the user to that
URL.
This will create a new "session" on the identity service, identified by an
``sid``.
The identity service will send an email 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 email for that email address, and so we validate ownership of
the email address.
We return the ``sid`` generated for this session to the caller, in a JSON object
containing the ``sid`` key.
If a send_attempt is specified, the server will only send an email 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 email address + client_secret pair.
This is to avoid repeatedly sending the same email in the case of request
retries between the POSTing user and the identity service. The client should
increment this value if they desire a new email (e.g. a reminder) to be sent.
Note that Home Servers 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.
Validating ownership of an email
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A user may make either a ``GET`` or a ``POST`` request to
``/_matrix/identity/api/v1/validate/email/submitToken`` with the following
parameters (either as query parameters or URL-encoded POST parameters):
- ``sid`` the sid for the session, generated by the ``requestToken`` call.
- ``client_secret`` the client secret which was supplied to the ``requestToken`` call.
- ``token`` the token generated by the ``requestToken`` call, and emailed to the user.
If these three values 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.
Otherwise, an error will be returned.
Checking non-published 3pid ownership
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A client can check whether ownership of a 3pid was validated by making an
HTTP GET request to ``/_matrix/identity/api/v1/3pid/getValidated3pid``, passing
the ``sid`` and ``client_secret`` as query parameters from the ``requestToken``
call.
It will return something of either the form::
{"medium": "email", "validated_at": 1457622739026, "address": "foo@bar.com"}
or::
{"errcode": "M_SESSION_NOT_VALIDATED", "error": "This validation session has not yet been completed"}
If the ``sid`` and ``client_secret`` were not recognised, or were not correct,
an error will be returned.
Publishing a validated association
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An association between a session and a Matrix user ID can be published by making
a URL-encoded HTTP POST request to ``/_matrix/identity/api/v1/3pid/bind`` with
the following parameters::
sid=sid&
client_secret=monkeys_are_GREAT&
mxid=@foo:bar.com
If the session is still valid, this will publish an association between the
3pids validated on that session and the passed Matrix user ID. Future calls
to ``/lookup`` for any of the session's 3pids will return this association.
If the 3pid has not yet been validated, the HTTP request will be rejected, and
the association will not be established.
If the ``sid`` and ``client_secret`` were not recognised, or were not correct,
an error will be returned.
{{associations_is_http_api}}
Invitation Storage
------------------
@ -216,32 +131,6 @@ An identity service can store pending invitations to a user's 3pid, which will
be retrieved and can be either notified on or look up when the 3pid is
associated with a Matrix user ID.
If one makes a ``POST`` request to ``/_matrix/identity/api/v1/store-invite`` with the following URL-encoded POST parameters:
- ``medium`` (string, required): The literal string ``email``.
- ``address`` (string, required): The email address of the invited user.
- ``room_id`` (string, required): The Matrix room ID to which the user is invited.
- ``sender`` (string, required): The matrix user ID of the inviting user.
An arbitrary number of other parameters may also be specified. These may be used in the email generation described below.
The service will look up whether the 3pid is bound to a Matrix user ID. If it is, the request will be rejected with a 400 status code.
If the medium is something other than the literal string ``email``, the request will be rejected with a 400 status code.
Otherwise, the service will then generate a random string called ``token``, and an ephemeral public key.
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.
The response body is then populated as the JSON-encoded dictionary containing the following fields:
- ``token`` (string): The generated token.
- ``public_keys`` ([string]): A list of [server's long-term public key, generated ephemeral public key].
- ``display_name`` (string): The generated (redacted) display_name.
At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below::
POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
@ -273,7 +162,7 @@ At a later point, if the owner of that particular 3pid binds it with a Matrix us
Where the signature is produced using a long-term private key.
Also, the generated ephemeral public key will be listed as valid on requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
{{store_invite_is_http_api}}
Ephemeral invitation signing
----------------------------
@ -281,23 +170,7 @@ Ephemeral invitation signing
To aid clients who may not be able to perform crypto themselves, the identity service offers some crypto functionality to help in accepting invitations.
This is less secure than the client doing it itself, but may be useful where this isn't possible.
The identity service will happily sign invitation details with a request-specified ed25519 private key for you, if you want it to. It takes URL-encoded POST parameters:
- mxid (string, required)
- token (string, required)
- private_key (string, required): The private key, encoded as `Unpadded base64`_.
It will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. It will then respond with JSON which looks something like::
{
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures" {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
{{invitation_signing_is_http_api}}
.. _`Unpadded Base64`: ../appendices.html#unpadded-base64
.. _`3PID Types`: ../appendices.html#pid-types