path: root/core/api-challenger.rst

..
  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;
  }