From 317c2f20d31345a656c553dc239563cf9f2de78d Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Mon, 28 Sep 2015 09:29:35 +0100
Subject: [PATCH 1/5] Draft login token spec

---
 specification/1-client_server_api.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst
index 93e3cb90..7f967337 100644
--- a/specification/1-client_server_api.rst
+++ b/specification/1-client_server_api.rst
@@ -197,6 +197,7 @@ This specification defines the following login types:
  - ``m.login.recaptcha``
  - ``m.login.oauth2``
  - ``m.login.email.identity``
+ - ``m.login.token``
  - ``m.login.dummy``
 
 Password-based
@@ -228,6 +229,29 @@ To respond to this type, reply with an auth dict as follows::
     "response": "<captcha response>"
   }
 
+Token-based
+~~~~~~~~~~~
+:Type:
+  ``m.login.token``
+:Description:
+  The client submits a username and token that was generated by the server.
+
+To respond to this type, reply with an auth dict as follows::
+
+  {
+    "type": "m.login.token",
+    "user": "<user_id or user localpart>",
+    "token": "<token>",
+    "nonce": "<client generated nonce>"
+  }
+
+The ``nonce`` should be a random string generated by the client for the
+request. The same ``nonce`` should be used if retrying the request.
+
+The ``token`` may be discovered from e.g. an email or dynamically generated QR
+code.
+
+
 OAuth2-based
 ~~~~~~~~~~~~
 :Type:

From 4c9f524cabbbc74a837743aaa043e977b67ae7d2 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Mon, 28 Sep 2015 09:32:03 +0100
Subject: [PATCH 2/5] Neaten things up

---
 specification/1-client_server_api.rst | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst
index 7f967337..e3817046 100644
--- a/specification/1-client_server_api.rst
+++ b/specification/1-client_server_api.rst
@@ -234,7 +234,7 @@ Token-based
 :Type:
   ``m.login.token``
 :Description:
-  The client submits a username and token that was generated by the server.
+  The client submits a username and token.
 
 To respond to this type, reply with an auth dict as follows::
 
@@ -248,9 +248,8 @@ To respond to this type, reply with an auth dict as follows::
 The ``nonce`` should be a random string generated by the client for the
 request. The same ``nonce`` should be used if retrying the request.
 
-The ``token`` may be discovered from e.g. an email or dynamically generated QR
-code.
-
+There are many ways a client may receive a ``token``, including via an email or
+from an existing logged in device.
 
 OAuth2-based
 ~~~~~~~~~~~~

From 97154cc6b2088ea30d80b0c2eff3196a40b9a484 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Mon, 28 Sep 2015 13:09:54 +0100
Subject: [PATCH 3/5] s/nonce/txn_id/

---
 specification/1-client_server_api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst
index e3817046..988f7bc4 100644
--- a/specification/1-client_server_api.rst
+++ b/specification/1-client_server_api.rst
@@ -242,7 +242,7 @@ To respond to this type, reply with an auth dict as follows::
     "type": "m.login.token",
     "user": "<user_id or user localpart>",
     "token": "<token>",
-    "nonce": "<client generated nonce>"
+    "txn_id": "<client generated nonce>"
   }
 
 The ``nonce`` should be a random string generated by the client for the

From ce53a171800d765b9bcc86e019ec11d4583ed4ea Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Mon, 28 Sep 2015 14:51:10 +0100
Subject: [PATCH 4/5] Add txn_id rationale

---
 specification/1-client_server_api.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst
index 988f7bc4..89698c66 100644
--- a/specification/1-client_server_api.rst
+++ b/specification/1-client_server_api.rst
@@ -251,6 +251,13 @@ request. The same ``nonce`` should be used if retrying the request.
 There are many ways a client may receive a ``token``, including via an email or
 from an existing logged in device.
 
+The ``txn_id`` may be used by the server to disallow other devices from using
+the token, thus providing "single use" tokens while still allowing the device
+to retry the request. This would be done by tying the token to the ``txn_id``
+server side, as well as potentially invalidating the token completely once the
+device has successfully logged in (e.g. when we receive a request from the
+newly provisioned access_token).
+
 OAuth2-based
 ~~~~~~~~~~~~
 :Type:

From 6e6bc8a5a9745627eb172dd98c77c140e89f1a95 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Mon, 28 Sep 2015 14:51:44 +0100
Subject: [PATCH 5/5] Mandate macaroon

---
 specification/1-client_server_api.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst
index 89698c66..893aec73 100644
--- a/specification/1-client_server_api.rst
+++ b/specification/1-client_server_api.rst
@@ -258,6 +258,8 @@ server side, as well as potentially invalidating the token completely once the
 device has successfully logged in (e.g. when we receive a request from the
 newly provisioned access_token).
 
+The ``token`` must be a macaroon.
+
 OAuth2-based
 ~~~~~~~~~~~~
 :Type: