From 0eabf108d9a8765213f6f80d27c5dcb6a5c2acd3 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Wed, 9 Jan 2019 15:05:27 -0700
Subject: [PATCH] Add a mechanism for redirecting clients after login

Implements https://github.com/matrix-org/matrix-doc/pull/1730
---
 .../definitions/wellknown/full.yaml           | 39 +++++++++++++++++++
 api/client-server/login.yaml                  | 18 ++++++++-
 api/client-server/wellknown.yaml              | 21 +---------
 3 files changed, 57 insertions(+), 21 deletions(-)
 create mode 100644 api/client-server/definitions/wellknown/full.yaml

diff --git a/api/client-server/definitions/wellknown/full.yaml b/api/client-server/definitions/wellknown/full.yaml
new file mode 100644
index 00000000..8d8f4038
--- /dev/null
+++ b/api/client-server/definitions/wellknown/full.yaml
@@ -0,0 +1,39 @@
+# Copyright 2019 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.
+title: Discovery Information
+description: |-
+  Used by clients to determine the homeserver, identity server, and other
+  optional components they should be interacting with.
+type: object
+properties:
+  "m.homeserver":
+    $ref: "homeserver.yaml"
+  "m.identity_server":
+    $ref: "identity_server.yaml"
+additionalProperties:
+  type: object
+  description: Application-dependent keys using Java package naming convention.
+required:
+  - m.homeserver
+example: {
+  "m.homeserver": {
+    "base_url": "https://matrix.example.com"
+  },
+  "m.identity_server": {
+    "base_url": "https://identity.example.com"
+  },
+  "org.example.custom.property": {
+    "app_url": "https://custom.app.example.org"
+  }
+}
diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index 43aae5df..cef3d26f 100644
--- a/api/client-server/login.yaml
+++ b/api/client-server/login.yaml
@@ -139,7 +139,15 @@ paths:
             application/json: {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "device_id": "GHTYAJCE"
+                "device_id": "GHTYAJCE",
+                "well_known": {
+                  "m.homeserver": {
+                    "base_url": "https://example.org"
+                  },
+                  "m.identity_server": {
+                    "base_url": "https://id.example.org"
+                  }
+                }
               }
           schema:
             type: object
@@ -166,6 +174,14 @@ paths:
                 description: |-
                   ID of the logged-in device. Will be the same as the
                   corresponding parameter in the request, if one was specified.
+              well_known:
+                type: object
+                description: |-
+                  Optional client configuration provided by the server. If present,
+                  clients SHOULD ise the provided object to reconfigure themselves,
+                  optionally validating the URLs within. This object takes the same
+                  form as the one returned from .well-known autodiscovery.
+                "$ref": "definitions/wellknown/full.yaml"
         400:
           description: |-
             Part of the request was invalid. For example, the login type may not be recognised.
diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml
index 24e190f9..b63bd041 100644
--- a/api/client-server/wellknown.yaml
+++ b/api/client-server/wellknown.yaml
@@ -38,28 +38,9 @@ paths:
       responses:
         200:
           description: Server discovery information.
-          examples:
-            application/json: {
-                "m.homeserver": {
-                  "base_url": "https://matrix.example.com"
-                },
-                "m.identity_server": {
-                  "base_url": "https://identity.example.com"
-                }
-              }
           schema:
             type: object
-            properties:
-              m.homeserver:
-                description: Information about the homeserver to connect to.
-                "$ref": "definitions/wellknown/homeserver.yaml"
-              m.identity_server:
-                description: Optional. Information about the identity server to connect to.
-                "$ref": "definitions/wellknown/identity_server.yaml"
-            additionalProperties:
-              description: Application-dependent keys using Java package naming convention.
-            required:
-              - m.homeserver
+            "$ref": "definitions/wellknown/full.yaml"
         404:
           description: No server discovery information available.
       tags: