Device management API

api/client-server/definitions/client_device.yaml

@@ -0,0 +1,44 @@
+# 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.
+
+type: object
+description: A client device
+title: Device
+properties:
+  device_id:
+    type: string
+    description: Identifier of this device.
+    example: QBUAZIFURK
+  display_name:
+    type: string
+    description: |-
+      Display name set by the user for this device. Absent if no name has been
+      set.
+    example: android
+  last_seen_ip:
+    type: string
+    description: |-
+      The IP address where this device was last seen. (May be a few minutes out
+      of date, for efficiency reasons).
+    example: 1.2.3.4
+  last_seen_ts:
+    type: integer
+    format: int64
+    description: |-
+      The timestamp (in milliseconds since the unix epoch) when this devices
+      was last seen. (May be a few minutes out of date, for efficiency
+      reasons).
+    example: 1474491775024
+required:
+  - device_id

api/client-server/device_management.yaml

@@ -0,0 +1,139 @@
+# 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 Client-Server device management API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/devices":
+    get:
+      summary: List registered devices for the current user
+      description: |-
+        Gets information about all devices for the current user.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: Device information
+          schema:
+            type: object
+            properties:
+              devices:
+                type: array
+                description: A list of all registered devices for this user.
+                items:
+                  type: object
+                  allOf:
+                    - $ref: "definitions/client_device.yaml"
+          examples:
+            application/json: |-
+              {
+                "devices": [
+                  {
+                    "device_id": "QBUAZIFURK",
+                    "display_name": "android",
+                    "last_seen_ip": "1.2.3.4",
+                    "last_seen_ts": 1474491775024
+                  }
+                ]
+              }
+      tags:
+        - Device management
+  "/devices/{deviceId}":
+    get:
+      summary: Get a single device
+      description: |-
+        Gets information on a single device, by device id.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to retrieve.
+          required: true
+          x-example: "QBUAZIFURK"
+      responses:
+        200:
+          description: Device information
+          schema:
+            type: object
+            allOf:
+               - $ref: "definitions/client_device.yaml"
+          examples:
+            application/json: |-
+              {
+                "device_id": "QBUAZIFURK",
+                "display_name": "android",
+                "last_seen_ip": "1.2.3.4",
+                "last_seen_ts": 1474491775024
+              }
+        404:
+          description: The current user has no device with the given ID.
+      tags:
+        - Device management
+    delete:
+      summary: Delete a device
+      description: |-
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        Deletes the given device, and invalidates any access token assoicated with it.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to retrieve.
+          required: true
+          x-example: "QBUAZIFURK"
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth:
+                description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+      responses:
+        200:
+          description: |-
+            The device was successfully removed, or had been removed
+            previously.
+          schema:
+            type: object
+          examples:
+            application/json: |-
+              {}
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+      tags:
+        - Device management

changelogs/client_server.rst

@@ -32,8 +32,10 @@
     (`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
   - Add ``filter`` optional query param to ``/messages``
     (`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
-  - Add "Send-to-Device messaging" module
+  - Add 'Send-to-Device messaging' module
     (`#386 <https://github.com/matrix-org/matrix-doc/pull/386>`_).
+  - Add 'Device management' module
+    (`#402 <https://github.com/matrix-org/matrix-doc/pull/402>`_).
   - Require that User-Interactive auth fallback pages call
     ``window.postMessage`` to notify apps of completion
     (`#398 <https://github.com/matrix-org/matrix-doc/pull/398>`_).

specification/modules/device_management.rst

@@ -0,0 +1,41 @@
+.. 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.
+
+Device Management
+=================
+
+.. _module:device-management:
+
+This module provides a means for a user to manage their `devices`_.
+
+Client behaviour
+----------------
+Clients that implement this module should offer the user a list of registered
+devices, as well as the means to update their display names. Clients should
+also allow users to delete disused devices.
+
+{{device_management_cs_http_api}}
+
+Security considerations
+-----------------------
+
+Deleting devices has security implications: it invalidates the access_token
+assigned to the device, so an attacker could use it to log out the real user
+(and do it repeatedly every time the real user tries to log in to block the
+attacker). Servers should require additional authentication beyond the access
+token when deleting devices (for example, requiring that the user resubmit
+their password).
+
+The display names of devices are publicly visible. Clients should consider
+advising the user of this.

specification/targets.yaml

@@ -42,6 +42,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/presence.rst
     - modules/content_repo.rst
     - modules/send_to_device.rst
+    - modules/device_management.rst
     - modules/end_to_end_encryption.rst
     - modules/history_visibility.rst
     - modules/push.rst