add challenger API draft

2 files changed, 258 insertions, 2 deletions

diff --git a/core/api-challenger.rst b/core/api-challenger.rst
new file mode 100644
index 00000000..747f3e6b
--- /dev/null
+++ b/core/api-challenger.rst
@@ -0,0 +1,256 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2023 Taler Systems SA
+
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU Affero General Public License as published by the Free Software
+  Foundation; either version 2.1, or (at your option) any later version.
+
+  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+
+  You should have received a copy of the GNU Affero General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Christian Grothoff
+
+.. _challenger-api:
+
+======================
+Challenger Service API
+======================
+
+The challenger service validates that a user is able to receive challenges at
+an address (such as e-mail or SMS) and allows an OAuth 2.0 client to obtain
+access to these validated addresses.
+
+The high-level flow is that an OAuth 2.0 client is first registered with the
+challenger service (via command-line). Henceforth, that client can use the
+challenger service when it needs a user to prove that the user is able to
+receive messages at a particular address.
+
+In that case, it makes a request to the ``/login`` endpoint of the challenger
+service using its client secret for authentication.  The challenger service
+will return a Web page asking the client to provide its address.
+
+When the user has filled in the form with their address, it will be submitted
+to the ``/challenge`` endpoint and the challenger service will send a
+challenge to the user's address and generate a form asking
+the user to enter the received challenge value.
+
+The user can then enter the answer to the challenge which is then submitted to the ``/solve`` endpoint.  If the answer is correct, the user will be redirected to the client redirect URI that was specified by the OAuth 2.0 client upon ``/login``, together with an authorization grant.
+
+Given this authorization grant, the OAuth 2.0 client can then use the
+``/auth`` endpoint to obtain an access token which will grant it access to the
+resource.  Using the ``/info`` endpoint the client can then finally obtain the
+verified address of the user.  The user-agent should finally be redirected to
+some confirmation site affirming the end of the process.
+
+
+
+.. include:: tos.rst
+
+-----------------------
+Receiving Configuration
+-----------------------
+
+.. http:get:: /config
+
+  Obtain the key configuration settings of the storage service.
+
+  **Response:**
+
+  Returns a `ChallengerTermsOfServiceResponse`.
+
+  .. ts:def:: ChallengerTermsOfServiceResponse
+
+    interface ChallengerTermsOfServiceResponse {
+      // Name of the service
+      name: "challenger";
+
+      // libtool-style representation of the Challenger protocol version, see
+      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+      // The format is "current:revision:age".
+      version: string;
+
+    }
+
+.. _challenger-login:
+
+-----
+Login
+-----
+
+.. http:get:: /login
+
+  An ``Authorization`` header (for now always using a ``bearer`` token) should
+  be included to provide the client's credentials to authorize access to the
+  challenger service.  This token must match the ``client_secret`` in the
+  laster ``/auth`` request.
+
+  **Request:**
+
+  :query response_type: Must be ``code``
+  :query client_id: Identifier of the client.
+  :query redirect_uri: URL-encoded redirection URL to use upon authorization.
+  :query state: Arbitrary client state to associate with the request.
+  :query scope: Not supported, any value is accepted.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The body contains a form to be submitted by the
+    user-agent. The form will ask the user to specify
+    their address.
+
+  :http:statuscode:`403 Forbidden`:
+    The credentials of the client are invalid.
+  :http:statuscode:`404 Not found`:
+    The backup service is unaware of a matching client.
+
+
+.. _challenger-challenge:
+
+---------
+Challenge
+---------
+
+.. http:post:: /challenge
+
+  Submits the address to which a challenge should be
+  sent by the challenger service.
+
+  **Request:**
+
+  Depends on the form from ``/login``. TBD.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The body contains a form asking for the answer to
+    the challenge to be entered by the user.
+  :http:statuscode:`404 Not found`:
+    The backup service is unaware of a matching login.
+
+
+.. _challenger-solve:
+
+-----
+Solve
+-----
+
+.. http:post:: /solve
+
+  Used by the user-agent to submit an answer to the
+  challenge.  If the answer is correct, the user
+  will be redirected to the client's redirect URL,
+  otherwise the user may be given another chance
+  to complete the process.
+
+  **Request:**
+
+  Depends on the form from ``/challenge``. TBD.
+
+  **Response:**
+
+  :http:statuscode:`302 Found`:
+    The user is redirected to the client to pass the
+    grant to the client.  The target will be the
+    redirect URI specified by the client upon
+    ``/login``, plus a ``code`` argument with the
+    authorization code, and the ``state`` argument
+    from the ``/login``.
+  :http:statuscode:`403 Forbidden`:
+    The solution of the user is invalid.  The body
+    is typically again the challenge form (same as
+    from ``/challenge``, except augmented with a
+    message that the previous code was invalid).
+  :http:statuscode:`404 Not found`:
+    The service is unaware of a matching challenge.
+
+
+.. _challenger-auth:
+
+----
+Auth
+----
+
+.. http:post:: /auth
+
+  This endpoint is used by the client to provide
+  its grant, demonstrating that it has the right to
+  learn a particular user's validated address.
+
+  **Request:**
+
+  The request must include an ``application/www-form-urlencoded`` body
+  specifying the ``client_id``, ``redirect_uri``, ``client_secret``, ``code``
+  and ``grant_type``.  The ``grant_type`` must be set to
+  ``authorization_code``.  The ``redirect_uri`` must match the URI from
+  ``/login``. The ``code`` must be the authorization code that ``/solve``
+  returned to the user.  The ``client_id`` and ``client_secret`` must match
+  the usual client credentials.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The body will be a `ChallengerAuthResponse`
+  :http:statuscode:`403 Forbidden`:
+    The credentials of the client are invalid.
+  :http:statuscode:`404 Not found`:
+    The service is unaware of a matching login process.
+
+  **Details::**
+
+  .. ts:def:: ChallengerAuthResponse
+
+  interface ChallengerAuthResponse {
+    // Token used to authenticate access in ``/info``.
+    access_token: string;
+
+    // Type of the access token.
+    token_type: "Bearer";
+
+    // Amount of time that an access token is valid (in seconds).
+    expires_in: Number;
+  }
+
+
+.. _challenger-info:
+
+----
+Info
+----
+
+.. http:get:: /info
+
+  This endpoint is used by the client to obtain the
+  user's validated address.
+
+  **Request:**
+
+  Must include the grant token from ``/auth`` as a bearer token in an ``Authorization`` header.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The body contains the address as a `ChallengerInfoResponse`.
+  :http:statuscode:`403 Forbidden`:
+    The bearer token is invalid.
+
+  **Details::**
+
+  .. ts:def:: ChallengerInfoResponse
+
+  interface ChallengerInfoResponse {
+    // Address that was validated.
+    address: string;
+
+    // Type of the address.
+    address_type: string;
+
+    // How long do we consider the address to be
+    // valid for this user.
+    expires: Timestamp;
+  }
diff --git a/core/index.rst b/core/index.rst
index 2a8352db..09a89c88 100644
--- a/core/index.rst
+++ b/core/index.rst
@@ -45,6 +45,7 @@ interfaces between the core components of Taler.
   api-bank-merchant
   api-bank-integration
   api-bank-access
+  api-challenger
 
 .. toctree::
   :hidden:
@@ -61,7 +62,7 @@ Overview
     **Providers**: GNU Taler Exchange
 
     **Consumers**: Wallet, Merchant
-    
+
     :doc:`Docs <api-exchange>`
 
 
@@ -222,4 +223,3 @@ Overview
     **Consumers**: LibEuFin Nexus
 
     **Providers**: LibEuFin Sandbox, Banks
-