window.postmessage for Interactive Auth fallback

Require that User-Interactive auth fallback pages call
`window.postMessage` to notify apps of completion.

changelogs/client_server.rst

@@ -34,6 +34,9 @@
     (`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
   - Add "Send-to-Device messaging" module
     (`#386 <https://github.com/matrix-org/matrix-doc/pull/386>`_).
+  - 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>`_).
 
 - Spec clarifications:
 

specification/client_server_api.rst

@@ -428,7 +428,8 @@ To use this authentication type, clients should submit an auth dict as follows:
   {
     "type": "m.login.password",
     "user": "<user_id or user localpart>",
-    "password": "<password>"
+    "password": "<password>",
+    "session": "<session ID>"
   }
 
 Alternatively reply using a 3pid bound to the user's account on the homeserver
@@ -441,7 +442,8 @@ follows:
     "type": "m.login.password",
     "medium": "<The medium of the third party identifier. Must be 'email'>",
     "address": "<The third party address of the user>",
-    "password": "<password>"
+    "password": "<password>",
+    "session": "<session ID>"
   }
 
 In the case that the homeserver does not know about the supplied 3pid, the
@@ -460,7 +462,8 @@ To use this authentication type, clients should submit an auth dict as follows:
 
   {
     "type": "m.login.recaptcha",
-    "response": "<captcha response>"
+    "response": "<captcha response>",
+    "session": "<session ID>"
   }
 
 Token-based
@@ -477,7 +480,8 @@ To use this authentication type, clients should submit an auth dict as follows:
   {
     "type": "m.login.token",
     "token": "<token>",
-    "txn_id": "<client generated nonce>"
+    "txn_id": "<client generated nonce>",
+    "session": "<session ID>"
   }
 
 The ``nonce`` should be a random string generated by the client for the
@@ -544,7 +548,8 @@ To use this authentication type, clients should submit an auth dict as follows:
         "client_secret": "<identity server client secret>",
         "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
       }
-    ]
+    ],
+    "session": "<session ID>"
   }
 
 Dummy Auth
@@ -562,12 +567,13 @@ the type and session, if provided:
 .. code:: json
 
   {
-    "type": "m.login.dummy"
+    "type": "m.login.dummy",
+    "session": "<session ID>"
   }
 
 
 Fallback
-<<<<<<<<
+++++++++
 Clients cannot be expected to be able to know how to process every single login
 type. If a client does not know how to handle a given login type, it can direct
 the user to a web browser with the URL of a fallback page which will allow the
@@ -577,11 +583,92 @@ should open is::
   /_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<auth type>/fallback/web?session=<session ID>
 
 Where ``auth type`` is the type name of the stage it is attempting and
-``session id`` is the ID of the session given by the homeserver.
+``session ID`` is the ID of the session given by the homeserver.
 
 This MUST return an HTML page which can perform this authentication stage. This
-page must attempt to call the JavaScript function ``window.onAuthDone`` when
+page must use the following JavaScript when the authentication has been
-the authentication has been completed.
+completed:
+
+.. code:: javascript
+
+   if (window.onAuthDone) {
+       window.onAuthDone();
+   } else if (window.opener && window.opener.postMessage) {
+       window.opener.postMessage("authDone", "*");
+   }
+
+This allows the client to either arrange for the global function ``onAuthDone``
+to be defined in an embedded browser, or to use the HTML5 `cross-document
+messaging <https://www.w3.org/TR/webmessaging/#web-messaging>`_ API, to receive
+a notification that the authentication stage has been completed.
+
+Once a client receives the notificaton that the authentication stage has been
+completed, it should resubmit the request with an auth dict with just the
+session ID:
+
+.. code:: json
+
+  {
+    "session": "<session ID>"
+  }
+
+
+Example
+<<<<<<<
+A client webapp might use the following javascript to open a popup window which will
+handle unknown login types:
+
+.. code:: javascript
+
+  /**
+   * Arguments:
+   *     homeserverUrl: the base url of the homeserver (eg "https://matrix.org")
+   *
+   *     apiEndpoint: the API endpoint being used (eg
+   *        "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password")
+   *
+   *     loginType: the loginType being attempted (eg "m.login.recaptcha")
+   *
+   *     sessionID: the session ID given by the homeserver in earlier requests
+   *
+   *     onComplete: a callback which will be called with the results of the request
+   */
+  function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onComplete) {
+      var popupWindow;
+
+      var eventListener = function(ev) {
+          if (ev.data !== "authDone" ) {
+              return;
+          }
+
+          // close the popup
+          popupWindow.close();
+          window.removeEventListener("message", eventListener);
+
+          // repeat the request
+          var requestBody = {
+              auth: {
+                  session: sessionID,
+              },
+          };
+
+          request({
+              method:'POST', url:apiEndpint, json:requestBody,
+          }, onComplete);
+      };
+
+      window.addEventListener("message", eventListener);
+
+      var url = homeserverUrl +
+          "/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/" +
+          encodeURIComponent(loginType) +
+          "/fallback/web?session=" +
+          encodeURIComponent(sessionID);
+
+
+     popupWindow = window.open(url);
+  }
+
 
 Login
 ~~~~~