Merge remote-tracking branch 'remotes/origin/master'

.travis.yml

@@ -0,0 +1,8 @@
+language: go
+go:
+  - 1.8
+
+sudo: false
+
+script:
+  - ./scripts/test-and-build.sh

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

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

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"

changelogs/client_server.rst

@@ -60,6 +60,12 @@
     - ``GET /rooms/{roomId}/joined_members``
       (`#999 <https://github.com/matrix-org/matrix-doc/pull/999>`_).
 
+    - ``GET /account/whoami``
+      (`#1063 <https://github.com/matrix-org/matrix-doc/pull/1063>`_).
+
+    - ``GET /media/{version}/preview_url``
+      (`#1064 <https://github.com/matrix-org/matrix-doc/pull/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 <https://github.com/matrix-org/matrix-doc/pull/1032>`_).
+  - Clarify rate limiting and security for content repository.
+    (`#1064 <https://github.com/matrix-org/matrix-doc/pull/1064>`_).
 
 r0.2.0
 ======

jenkins.sh

@@ -1,25 +1,3 @@
-#! /bin/bash
+#!/bin/sh
 
-set -ex
+exec ./scripts/test-and-build.sh
-
-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

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;
 };
 </script>

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

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 '+'.

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
 ----------
 

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

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:'