diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..03ef6513 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,8 @@ +language: go +go: + - 1.8 + +sudo: false + +script: + - ./scripts/test-and-build.sh diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index e9fab258..4ad43039 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -18,16 +18,24 @@ info: host: localhost:8008 schemes: - https + - http basePath: /_matrix/media/%CLIENT_MAJOR_VERSION% +consumes: + - application/json + - "*/*" produces: - application/json - "*/*" +securityDefinitions: + $ref: definitions/security.yaml paths: "/upload": post: summary: Upload some content to the content repository. operationId: uploadContent produces: ["application/json"] + security: + - accessToken: [] parameters: - in: header name: Content-Type @@ -61,6 +69,10 @@ paths: application/json: { "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media "/download/{serverName}/{mediaId}": @@ -95,6 +107,10 @@ paths: type: "string" schema: type: file + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media "/download/{serverName}/{mediaId}/{fileName}": @@ -136,6 +152,10 @@ paths: type: "string" schema: type: file + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media "/thumbnail/{serverName}/{mediaId}": @@ -188,5 +208,63 @@ paths: enum: ["image/jpeg", "image/png"] schema: type: file + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + tags: + - Media + "/preview_url": + get: + summary: "Get information about a URL for a client" + produces: ["application/json"] + security: + - accessToken: [] + parameters: + - in: query + type: string + x-example: "https://matrix.org" + name: url + description: "The URL to get a preview of" + required: true + - in: query + type: number + x-example: 1510610716656 + name: ts + description: |- + The preferred point in time to return a preview for. The server may + return a newer version if it does not have the requested version + available. + responses: + 200: + description: |- + The OpenGraph data for the URL, which may be empty. Some values are + replaced with matrix equivalents if they are provided in the response. + The differences from the OpenGraph protocol are described here. + schema: + type: object + properties: + "matrix:image:size": + type: number + description: |- + The byte-size of the image. Omitted if there is no image attached. + "og:image": + type: string + description: |- + An MXC URI to the image. Ommitted if there is no image. + examples: + application/json: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml new file mode 100644 index 00000000..4d9d6ceb --- /dev/null +++ b/api/client-server/whoami.yaml @@ -0,0 +1,52 @@ +# Copyright 2017 Travis Ralston +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Account Identification API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/account/whoami": + get: + summary: Gets information about the owner of an access token. + description: |- + Gets information about the owner of a given access token. + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: + The token belongs to a known user. + examples: + application/json: { + "user_id": "@joe:example.org" + } + schema: + type: object + required: ["user_id"] + properties: + user_id: + type: string + description: The user id that owns the access token. + tags: + - User data diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 846ec6dc..ebd306cb 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -1,4 +1,6 @@ # Copyright 2016 OpenMarket Ltd +# Copyright 2017 Kamax.io +# Copyright 2017 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -33,13 +35,13 @@ paths: type: string name: medium required: true - description: The literal string "email". + description: The medium type of the 3pid. See the `3PID Types`_ Appendix. x-example: "email" - in: query type: string name: address required: true - description: The email address being looked up. + description: The address of the 3pid being looked up. See the `3PID Types`_ Appendix. x-example: "louise@bobs.burgers" responses: 200: @@ -83,4 +85,57 @@ paths: description: The unix timestamp at which the association was verified. signatures: type: object - description: The signatures of the verifying identity service which show that the association should be trusted, if you trust the verifying identity service. + description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + "/bulk_lookup": + post: + summary: Lookup Matrix user IDs for a list of 3pids. + description: Lookup Matrix user IDs for a list of 3pids. + 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 + items: + type: string + title: 3PID medium or address + description: an array of arrays containing the `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 + items: + type: string + title: 3PID medium or address or the Matrix ID + description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position. + required: + - "threepids" diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index c24f9ef4..e428605e 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -60,6 +60,12 @@ - ``GET /rooms/{roomId}/joined_members`` (`#999 `_). + - ``GET /account/whoami`` + (`#1063 `_). + + - ``GET /media/{version}/preview_url`` + (`#1064 `_). + - Spec clarifications: - Add endpoints and logic for invites and third-party invites to the federation @@ -96,6 +102,8 @@ - Clarify the relationship between ``username`` and ``user_id`` in the ``/register`` API (`#1032 `_). + - Clarify rate limiting and security for content repository. + (`#1064 `_). r0.2.0 ====== diff --git a/jenkins.sh b/jenkins.sh index d8950ade..79b77acb 100755 --- a/jenkins.sh +++ b/jenkins.sh @@ -1,25 +1,3 @@ -#! /bin/bash +#!/bin/sh -set -ex - -virtualenv env -. env/bin/activate -pip install -r scripts/requirements.txt - -# do sanity checks on the examples and swagger -(cd event-schemas/ && ./check_examples.py) -(cd api && ./check_examples.py) -(cd api && npm install && node validator.js -s "client-server") - -: ${GOPATH:=${WORKSPACE}/.gopath} -mkdir -p "${GOPATH}" -export GOPATH -go get github.com/hashicorp/golang-lru -go get gopkg.in/fsnotify.v1 - -# make sure that the scripts build -(cd scripts/continuserv && go build) -(cd scripts/speculator && go build) - -# build the spec and collect the supporting docs for matrix.org -./scripts/generate-matrix-org-assets +exec ./scripts/test-and-build.sh diff --git a/scripts/continuserv/index.html b/scripts/continuserv/index.html index f698c5b3..24ed7ecb 100644 --- a/scripts/continuserv/index.html +++ b/scripts/continuserv/index.html @@ -3,7 +3,7 @@ window.onload = function() { var url = new URL(window.location); url.pathname += "api-docs.json"; - var newLoc = "http://matrix.org/docs/api/client-server/?url=" + encodeURIComponent(url); + var newLoc = "http://petstore.swagger.io/?url=" + encodeURIComponent(url); document.getElementById("apidocs").href = newLoc; }; diff --git a/scripts/test-and-build.sh b/scripts/test-and-build.sh new file mode 100755 index 00000000..cd25ded2 --- /dev/null +++ b/scripts/test-and-build.sh @@ -0,0 +1,29 @@ +#! /bin/bash + +set -ex + +cd `dirname $0`/.. + +virtualenv env +. env/bin/activate +pip install -r scripts/requirements.txt + +# do sanity checks on the examples and swagger +(cd event-schemas/ && ./check_examples.py) +(cd api && ./check_examples.py) +(cd api && npm install && node validator.js -s "client-server") + +: ${GOPATH:=${WORKSPACE}/.gopath} +mkdir -p "${GOPATH}" +export GOPATH +go get github.com/hashicorp/golang-lru +go get gopkg.in/fsnotify.v1 + +# make sure that the scripts build +(cd scripts/continuserv && go build) +(cd scripts/speculator && go build) + +# build the spec for matrix.org. +# (we don't actually use it on travis, but it's still useful to check we +# can build it. On Jenkins, this is then used to deploy to matrix.org). +./scripts/generate-matrix-org-assets diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst new file mode 100644 index 00000000..84860740 --- /dev/null +++ b/specification/appendices/threepids.rst @@ -0,0 +1,48 @@ +.. Copyright 2017 Kamax.io +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +3PID Types +---------- +Third Party Identifiers (3PIDs) represent identifiers on other namespaces that +might be associated with a particular person. They comprise a tuple of ``medium`` +which is a string that identifies the namespace in which the identifier exists, +and an ``address``: a string representing the identifier in that namespace. This +must be a canonical form of the identifier, *i.e.* if multiple strings could +represent the same identifier, only one of these strings must be used in a 3PID +address, in a well-defined manner. + +For example, for e-mail, the ``medium`` is 'email' and the ``address`` would be the +email address, *e.g.* the string ``bob@example.com``. Since domain resolution is +case-insensitive, the email address ``bob@Example.com`` is also has the 3PID address +of ``bob@example.com`` (without the capital 'e') rather than ``bob@Example.com``. + +The namespaces defined by this specification are listed below. More namespaces +may be defined in future versions of this specification. + +E-Mail +~~~~~~ +Medium: ``email`` + +Represents E-Mail addresses. The ``address`` is the raw email address in +``user@domain`` form with the domain in lowercase. It must not contain other text +such as real name, angle brackets or a mailto: prefix. + +PSTN Phone numbers +~~~~~~~~~~~~~~~~~~ +Medium: ``msisdn`` + +Represents telephone numbers on the public switched telephone network. The +``address`` is the telephone number represented as a MSISDN (Mobile Station +International Subscriber Directory Number) as defined by the E.164 numbering +plan. Note that MSISDNs do not include a leading '+'. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 87e90150..09f73bb9 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -786,6 +786,11 @@ This is independent of any information kept by any Identity Servers. {{administrative_contact_cs_http_api}} +Current account information +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +{{whoami_cs_http_api}} + Pagination ---------- diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index fa03e162..19275593 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -1,4 +1,6 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2017 Kamax.io +.. Copyright 2017 New Vector Ltd .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -52,6 +54,8 @@ necessarily provide evidence that they have validated associations, but claim to have done so. Establishing the trustworthiness of an individual identity service is left as an exercise for the client. +3PID types are described in `3PID Types`_ Appendix. + Privacy ------- @@ -291,3 +295,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe } .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`3PID Types`: ../appendices.html#pid-types diff --git a/specification/targets.yaml b/specification/targets.yaml index fb68e13d..62799afe 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -35,6 +35,7 @@ targets: - appendices/base64.rst - appendices/signing_json.rst - appendices/identifier_grammar.rst + - appendices/threepids.rst - appendices/threat_model.rst - appendices/test_vectors.rst groups: # reusable blobs of files when prefixed with 'group:'