clarifications to challenger docu

2 files changed, 118 insertions, 52 deletions

diff --git a/core/api-challenger.rst b/core/api-challenger.rst
index 4936b6f3..2e62a0dd 100644
--- a/core/api-challenger.rst
+++ b/core/api-challenger.rst
@@ -26,26 +26,66 @@ 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 ``/authorize`` 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.
+challenger service (via command-line). Using the command-line tool will print
+the resulting client ID to the console.
+
+  .. note::
+
+     The current service mandates that redirection URIs
+     start with "http://" or "https://". See issue #7838
+     for what should be done to lift this restriction.
+
+  .. note::
+
+     Right now, registration of a unique redirection URI is *mandatory* for
+     each client. If multiple redirection URIs are needed, it is suggested to
+     just register additional clients.  (While OAuth 2.0 would support not
+     registering fixed redirection URIs with a client, this is not recommended
+     as it would create an open redirector.)
+
+Once a client is registered, 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.  However, asking a user to prove access to a particular
+address can be expensive as it may involve sending an SMS or even postal mail
+depending on the type of address.  Thus, challenger does not allow a user
+agent to begin an address validation process without prior approval by a
+registered client.  Thus, the process begins with a ``/setup`` request where a
+client requests challenger to begin an address validation request.  The
+``/setup`` response contains a ``nonce`` which is then used to construct the
+URL of the endpoint to which the client must redirect the user-agent to begin
+the address validation and authorization process.
+
+The client then redirects the user-agent to the ``/authorize/$NONCE`` endpoint
+of the challenger service, adding its ``state``, ``client_id`` and
+``redirect_uri`` as query parameters.  The ``redirect_uri`` must match the
+redirect URI registered with the client. From this endpoint, the challenger
+service will return a Web page asking the user to provide its address.
+
+  .. note::
+
+    Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL
+    makes the authorization endpoint URL (deliberately) unpredictable, while
+    for many other OAuth 2.0 APIs this endpoint is static. However, this is
+    compliant with OAuth 2.0 as determining the authorization URL is left out
+    of the scope of the standard.
 
 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.
+to the ``/challenge/$NONCE`` endpoint and the challenger service will send a
+challenge to the user's address and generate an HTML 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 ``/authorize``, together with an authorization grant.
+The user can then enter the answer to the challenge which is then submitted to
+the ``/solve/$NONCE`` endpoint.  If the answer is correct, the user agent will
+be redirected to the client redirect URI that was specified by the OAuth 2.0
+client upon ``/authorize``, together with an authorization grant encoded in
+the redirection URI.
 
 Given this authorization grant, the OAuth 2.0 client can then use the
-``/token`` 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.
+``/token`` 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 (now)
+verified address of the user.
 
 
 
@@ -84,12 +124,12 @@ Setup
 
 .. http:post:: /setup/$CLIENT_ID
 
-  This endpoint is used by the client to authorize the
-  execution of an address validation on its behalf.
-  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
-  later ``/token`` request.
+  This endpoint is used by the client to authorize the execution of an address
+  validation on its behalf.  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`` from the registration of the client with the challenger
+  service (which will also be used in the later ``/token`` request).
 
   **Response:**
 
@@ -118,23 +158,23 @@ Login
 .. http:get:: /authorize/$NONCE
 .. http:post:: /authorize/$NONCE
 
-  This endpoint is used by the user-agent. It will
-  return a form to enter the address.
+  This is the "authorization" endpoint of the OAuth 2.0 protocol.  This
+  endpoint is used by the user-agent. It will return a form to enter the
+  address.
 
   **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 redirect_uri: URI-encoded redirection URI 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.
+    The body contains a form to be submitted by the user-agent.
+    The form will ask the user to specify their address.
   :http:statuscode:`404 Not found`:
     The backup service is unaware of a matching $NONCE.
 
@@ -147,8 +187,8 @@ Challenge
 
 .. http:post:: /challenge/$NONCE
 
-  Submits the address to which a challenge should be
-  sent by the challenger service.
+  This endpoint is used by the user-agent to submit the address to which a
+  challenge should be sent by the challenger service.
 
   **Request:**
 
@@ -161,7 +201,12 @@ Challenge
     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.
+    The challenger service is unaware of a matching nonce.
+  :http:statuscode:`429 Too Many Requests`:
+    There have been too many attempts to request challenge
+    transmissions for this $NONCE. The user-agent should
+    wait and (eventually) request a fresh nonce to be set
+    up by the client.
 
 
 .. _challenger-solve:
@@ -172,11 +217,9 @@ Solve
 
 .. http:post:: /solve/$NONCE
 
-  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.
+  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 URI,
+  otherwise the user may be given another chance to complete the process.
 
   **Request:**
 
@@ -185,19 +228,20 @@ Solve
   **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
-    ``/authorize``, plus a ``code`` argument with the
-    authorization code, and the ``state`` argument
-    from the ``/authorize`` endpoint.
+    The user is redirected to the redirect URI of the client to pass the
+    grant to the client.  The target will be the redirect URI specified
+    by the client (during registration and again upon ``/authorize``),
+    plus a ``code`` argument with the authorization code, and the
+    ``state`` argument from the ``/authorize`` endpoint.
   :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).
+    The solution of the user to the challenge is invalid.
   :http:statuscode:`404 Not found`:
     The service is unaware of a matching challenge.
+  :http:statuscode:`429 Too Many Requests`:
+    There have been too many attempts to solve the challenge
+    for this address (and $NONCE). The user-agent should
+    either try a different address (or wait and (eventually)
+    request a fresh nonce to be set up by the client).
 
 
 .. _challenger-auth:
@@ -208,9 +252,11 @@ Auth
 
 .. http:post:: /token
 
-  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.
+  This is the token endpoint of the OAuth 2.0 specification.
+  This endpoint is used by the client to provide its authorization code,
+  demonstrating that it has the right to learn a particular user's validated
+  address.  In return, the challenger service returns the access token.
+  Renewal is not supported.
 
   **Request:**
 
@@ -224,6 +270,9 @@ Auth
 
   **Response:**
 
+  Error responses follow RFC 6749, section 5.2 with an "error" field in JSON,
+  as well as also returning GNU Taler style error messages.
+
   :http:statuscode:`200 OK`:
     The body will be a `ChallengerAuthResponse`
   :http:statuscode:`403 Forbidden`:
@@ -256,19 +305,22 @@ Info
 
 .. http:get:: /info
 
-  This endpoint is used by the client to obtain the
-  user's validated address.
+  This userinfo endpoint of the OAuth 2.0 specification.
+  This endpoint is used by the client to obtain the user's validated address.
 
   **Request:**
 
-  Must include the grant token from ``/token`` as a bearer token in an ``Authorization`` header.
+  Must include the token returned to the client from the ``/token`` endpoint
+  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.
+    The bearer token is missing or invalid (malformed).
+  :http:statuscode:`404 Not found`:
+    The bearer token is invalid (includes unknown or expired).
 
   **Details::**
 
diff --git a/manpages/challenger.conf.5.rst b/manpages/challenger.conf.5.rst
index 6081a893..a46b8461 100644
--- a/manpages/challenger.conf.5.rst
+++ b/manpages/challenger.conf.5.rst
@@ -58,6 +58,20 @@ UNIXPATH_MODE = 660
 DB
   Plugin to use for the database, e.g. “postgres”.
 
+VALIDATION_DURATION
+  How long is a validation challenge valid. After this time period, a fresh random challenge code will be generated and the retry limit counter (against guessing attacks) will be reset (to 3).
+
+VALIDATION_EXPIRATION
+  How long is a validation allowed to take (time from
+  ``/setup`` to ``/token``). After this time, the garbage collection process can delete all associated data. (Note that tokens will always allow access to 1h after they have been issued, regardless of when the validation expires).
+
+AUTH_COMMAND
+  Which command should we execute to transmit the challenge code to the address. The address is given as the first argument, while the message to send is provided on stdin. Templates (possibly without the necessary credentials) for such commands are provided as challenger-send-email.sh, challenger-send-post.sh and challenger-send-sms.sh.
+
+ADDRESS_TYPE
+  Type of the address that is being collected, returned as part of the ``address_type`` in the ``/info`` endpoint. Examples include ``email`` or ``phone``.
+
+
 
 SEE ALSO
 ========