[tor-commits] [bridgedb/master] Specify the moat API.

[isis at torproject.org]

commit 9d452247e4378a44e46fb31b14acf2238e4d9dd6
Author: Isis Lovecruft <isis at torproject.org>
Date:   Tue Sep 12 21:33:22 2017 +0000

    Specify the moat API.
    
     * FIXES part of https://bugs.torproject.org/22871
---
 README.rst | 173 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)

diff --git a/README.rst b/README.rst
index faeae5c..a2d3b27 100644
--- a/README.rst
+++ b/README.rst
@@ -420,6 +420,179 @@ e.g. bridges at ...) and sent from an ``@riseup.net``, ``@gmail.com``, or
 
 You can email our BridgeDB instance `here <mailto:bridges at torproject.org>`__.
 
+
+----------------------------
+Accessing the Moat Interface
+----------------------------
+
+Moat is a bridge distributor for requesting bridges through `Tor Launcher's
+<https://gitweb.torproject.org/tor-launcher.git/>`__ user interface.
+
+The following describes the Moat API, version 0.1.0.
+
+The client and server both MUST conform to `JSON-API <http://jsonapi.org/>`__.
+
+The client SHOULD direct all requests via the Meek reflector at ``MEEK_REFECTOR``.
+..
+   XXX meek reflector URL
+
+Requesting Bridges
+""""""""""""""""""
+
+The client MUST send a ``POST /meek/moat/fetch`` containing the following JSON::
+
+    {
+      'data': {
+        'version': '0.1.0',
+        'type': 'moat client supported transports',
+        'supported': [ 'TRANSPORT', 'TRANSPORT', ... ],
+      }
+    }
+
+where:
+
+* ``TRANSPORT`` is a string identifying a transport, e.g. ``"obfs3"`` or
+  ``"obfs4"``.  Currently supported transport identifiers are:
+  - ``"vanilla"``
+  - ``"fte"``
+  - ``"obfs3"``
+  - ``"obfs4"``
+  - ``"scramblesuit"``
+
+
+Receiving a CAPTCHA challenge
+"""""""""""""""""""""""""""""
+
+The moat server will respond with ``200 OK``.
+
+If there is no overlap with the transports which BridgeDB supports, the moat
+server will respond with the list of transports which is *does* support::
+
+    {
+      'data': {
+        'version': '0.1.0',
+        'type': 'moat server supported transports',
+        'supported': [ 'TRANSPORT', 'TRANSPORT', ... ],
+      }
+    }
+
+If there is an overlap with what BridgeDB supports, the moat server will select
+the "best" transport from the list of supported transports, and respond with the
+following JSON containing a CAPTCHA challenge::
+
+    {
+      'data': {
+        'id': 1,
+        'type': 'moat farfetchd challenge',
+        'version': '0.1.0',
+        'transport': TRANSPORT,
+        'image': CAPTCHA,
+        'challenge': CHALLENGE,
+      }
+    }
+
+where:
+
+* ``TRANSPORT`` is the agreed upon transport which will be distributed,
+* ``CAPTCHA`` is a base64-encoded, jpeg image that is 400 pixels in
+  length and 125 pixels in height,
+* ``CHALLENGE`` is a base64-encoded CAPTCHA challenge which MUST be
+  later passed back to the server along with the proposed solution.
+
+The challenge contains an encrypted-then-HMACed timestamp, and
+solutions submitted more than 30 minutes after requesting the CAPTCHA
+are considered invalid.
+
+
+Responding to a CAPTCHA challenge
+"""""""""""""""""""""""""""""""""
+
+To propose a solution to a CAPTCHA, the client MUST send a request for ``POST
+/meek/moat/check``, where the body of the request contains the following JSON::
+
+    {
+      'data': {
+        'id': 2,
+        'type': 'moat farfetchd solution',
+        'version': '0.1.0',
+        'transport': TRANSPORT,
+        'challenge': CHALLENGE,
+        'solution': SOLUTION,
+        'qrcode': BOOLEAN,
+      }
+    }
+
+
+where:
+
+* ``TRANSPORT`` is the agreed upon transport which will be distributed,
+* ``CHALLENGE`` is a base64-encoded CAPTCHA challenge which MUST be
+  later passed back to the server along with the proposed solution.
+* ``SOLUTION`` is a valid unicode string, up to 20 bytes in length,
+  containing the client's answer (i.e. what characters the CAPTCHA
+  image displayed).  The solution is *not* case-sensitive.
+* ``BOOLEAN`` is ``'true'`` if the client wants a qrcode containing the bridge
+  lines to be generated and returned; ``'false'`` otherwise.
+
+
+Receiving Bridges
+"""""""""""""""""
+
+If the ``CHALLENGE`` has already timed out, or if the ``SOLUTION`` was
+incorrect, the server SHOULD respond with ``419 No You're A Teapot``.
+
+If the ``SOLUTION`` was successful for the supplied ``CHALLENGE``, the
+server responds ``200 OK`` with the following JSON::
+
+    {
+      'data': {
+        'id': 3,
+        'type': 'moat bridges',
+        'version': '0.1.0',
+        'bridges': [ 'BRIDGE_LINE', ... ],
+        'qrcode': QRCODE,
+      }
+    }
+
+where:
+
+* ``BRIDGE_LINE`` is a bridge line suitable for configuration in a torrc,
+* ``QRCODE`` is a base64-encoded jpeg image of a QRCode containing all the
+  ``BRIDGE_LINE``, if one was requested, otherwise this field will be ``NaN``.
+
+..
+    XXX do we care to differentiate the errors for "unable to distribute
+        bridges"? are any of these useful to Tor Launcher?
+
+If the ``SOLUTION`` was successful for the supplied ``CHALLENGE``, but the
+server is unable to distribute the requested Bridges, the server responds ``200
+OK`` with the following JSON::
+
+    {
+      'error': {
+        'id': 1,
+        'code': '404',
+        'status': 'Not Found',
+        'title': 'Could not fetch the type of bridges you requested',
+        'detail': DETAILS,
+      }
+    }
+
+where:
+
+* ``DETAILS`` is some string describing the detailed nature of the issue.
+
+
+Other Responses
+"""""""""""""""
+
+If the client requested some page other than ``/meek/moat/fetch``, or
+``/meek/moat/check``, the server MUST respond with ``501 Not Implemented``.
+
+If the client attempts any other HTTP method, other than ``POST``, the server
+MUST respond ``403 FORBIDDEN``.
+
+
 =================
 Contact & Support
 =================