About CHALLENGER
----------------


Challenger implements an HTTP server that allows clients to validate
that a user is able to receive TAN codes at a given address using
OAuth 2.0-style authorization.

Envisioned use-cases are KYC checks where a user must prove that they
are able to receive SMS, e-mails or physical mail.


Accountability:
===============

Clients must be registered before they can use the service. To
initiate an address verification, clients must first setup an
authorization session before directing the user agent towards the
``/login`` endpoint.  The system automatically tracks how many address
verification session a particular client has authorized.  This is
expected to be useful in cases where address verifications have
non-negligible cost.  The system also limits how often a user-agent
may change the address per authorization session as well as the number
of times the TAN code is transmitted to each address. Finally, it
of course also limits the number of times a user may enter a TAN
code.


Time limits:
============

Once authorized, a client has limited time to use the user agent's
authorization code.  The resulting grant also has limited lifetime
during which the client must download the verified address of the
user.


Flexibility:
============

The actual transmission of the TAN code is done via a separate
program that is simply invoked by the challenger service. This makes
the code useful for all types of address validations.  Simple shell
scripts are provided for SMS, e-mail and physical address validation.

All user-facing forms are fully customizable and provided as Mustach
templates.  By changing the templates, the look-and-feel of the
service can be freely adapted.


Usability:
==========

Challenger uses a simple REST-based API documented at
https://docs.taler.net/.  The authorization flow is believed
to be fully compatible with OAuth 2.0.


Limitations:
============

Challenger does at this time not include HTTPS support. While this could
be trivially added, we expect Challenger to be run behind a reverse proxy
that terminates TLS.

At this time, Challenger only works with a Postgres database. Other database
backends could easily be written in the future.


Installation
============

See INSTALL for generic installation instructions.  In addition,
Challenger requires GNUnet, GNU Taler Exchange, and GNU Taler Merchant
libraries.  If these are installed in a non-standard place, use the
configure script options --with-gnunet=DIR, --with-exchange=DIR, and
--with-merchant=DIR, respectively.

The following are likewise required:

  libmicrohttpd --with-microhttpd=DIR
  PostgreSQL    --with-postgresql=PATH-TO-PG-CONFIG

Other non-essential dependencies are indicated by --with-FOO
in the "./configure --help" output.



Dependencies:
=============

Build tools for compiling Challenger from source:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- gcc or clang
- autoconf           >= 2.69        (building from git)
- automake           >= 1.11.1      (building from git)
- recutils           >= 1.0         (building from git)
- libtool            >= 2.2
- makeinfo           >= 4.8
- make[*3]
- pkgconf or pkg-config
- sphinx
- sphinx-rtd-theme
- sphinx-multiversion


Direct dependencies
~~~~~~~~~~~~~~~~~~~

These are the direct dependencies for running Challenger:

- GNU Taler exchange >= 0.14.0
- PostgreSQL         >= 15.0


License:
========

Challenger is released under the Affero GPL v3 or later.

The primary source code is maintained at
https://git.taler.net/challenger.git by the GNU Taler team.
