fix #8731

1 files changed, 151 insertions, 9 deletions

diff --git a/core/api-challenger.rst b/core/api-challenger.rst
index 914d8d01..be8a36c3 100644
--- a/core/api-challenger.rst
+++ b/core/api-challenger.rst
@@ -168,6 +168,16 @@ Login
   endpoint is used by the user-agent. It will return a form to enter the
   address.
 
+  The NONCE is a unique value identifying the challenge, should be shown to
+  the user so that they can recognize it when they receive the TAN code.
+
+  This endpoint typically also supports requests with the "Accept" header
+  requesting "text/html".  In this case, an HTML response using the template
+  :ref:`enter-$ADDRESS_TYPE-form <challenger_enter-address_type-form>` is
+  returned. If the backend installation does not include the required HTML
+  templates, a 406 status code is returned.
+
+
   **Request:**
 
   :query response_type: Must be ``code``
@@ -179,10 +189,55 @@ Login
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The body contains a form to be submitted by the user-agent.
+    If the request ask for application/json then the response is
+    a `ChallengeStatus`. Since protocol **vSPA**.
+    Otherwise, the body contains a form to be submitted by the user-agent
+    using the template :ref:`enter-$ADDRESS_TYPE-form <challenger_enter-address_type-form>`.
     The form will ask the user to specify their address.
+  :http:statuscode:`406 Not Acceptable`:
+    The client ask for "text/html" and the backend installation does
+    not include the required HTML templates.
+  :http:statuscode:`400 Bad Request`:
+    The request does not follow the spec.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`.
+  :http:statuscode:`500 Internal Server Error`:
+    Server is not able to respond due to internal problems.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`.
   :http:statuscode:`404 Not found`:
-    The backup service is unaware of a matching $NONCE.
+    The service is unaware of a matching challenge.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`.
+
+  .. ts:def:: ChallengeStatus
+
+    interface ChallengeStatus {
+      // Object; map of keys (names of the fields of the address
+      // to be entered by the user) to objects with a "regex" (string)
+      // containing an extended Posix regular expression for allowed
+      // address field values, and a "hint"/"hint_i18n" giving a
+      // human-readable explanation to display if the value entered
+      // by the user does not match the regex. Keys that are not mapped
+      // to such an object have no restriction on the value provided by
+      // the user.  See "ADDRESS_RESTRICTIONS" in the challenger configuration.
+      restrictions: Object;
+
+      // indicates if the given address cannot be changed anymore, the
+      // form should be read-only if set to true.
+      fix_address: boolean;
+
+      // form values from the previous submission if available, details depend
+      // on the ``ADDRESS_TYPE``, should be used to pre-populate the form
+      last_address: Object;
+
+      // number of times the address can still be changed, may or may not be
+      // shown to the user
+      changes_left: Integer;
+    }
 
 
 .. _challenger-challenge:
@@ -204,15 +259,57 @@ Challenge
   **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 challenger service is unaware of a matching nonce.
+    If the request ask for application/json the response is `ChallengeCreateResponse`. Since protocol **vSPA**.
+    Otherwise, the body contains a form asking for the answer to
+    the challenge to be entered by the user using the
+    template :ref:`enter-tan-form <challenger_enter-tan-form>`.
+  :http:statuscode:`406 Not Acceptable`:
+    The client ask for "text/html" and the backend installation does
+    not include the required HTML templates.
   :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.
+  :http:statuscode:`400 Bad Request`:
+    The request does not follow the spec.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`.
+  :http:statuscode:`500 Internal Server Error`:
+    Server is not able to respond due to internal problems.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`.
+  :http:statuscode:`404 Not found`:
+    The service is unaware of a matching challenge.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`.
+
+  .. ts:def:: ChallengeCreateResponse
+
+    interface ChallengeCreateResponse {
+
+      // how many more attempts are allowed, might be shown to the user,
+      // highlighting might be appropriate for low values such as 1 or 2 (the
+      // form will never be used if the value is zero)
+      attempts_left: Integer;
+
+      // the address that is being validated, might be shown or not
+      address: Object;
+
+      // true if we just retransmitted the challenge, false if we sent a
+      // challenge recently and thus refused to transmit it again this time;
+      // might make a useful hint to the user
+      transmitted: boolean;
+
+      // timestamp explaining when we would re-transmit the challenge the next
+      // time (at the earliest) if requested by the user
+      next_tx_time: String;
+
+    }
+
 
 
 .. _challenger-solve:
@@ -240,15 +337,60 @@ Solve
     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 to the challenge is invalid.
-  :http:statuscode:`404 Not found`:
-    The service is unaware of a matching challenge.
+    If the request ask for application/json the response is `InvalidPinResponse`. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`invalid-pin <challenger_invalid-pin>`.
   :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).
+  :http:statuscode:`400 Bad Request`:
+    The request does not follow the spec.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`invalid-request <challenger_invalid-request>`.
+  :http:statuscode:`500 Internal Server Error`:
+    Server is not able to respond due to internal problems.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`internal-error <challenger_internal-error>`.
+  :http:statuscode:`404 Not found`:
+    The service is unaware of a matching challenge.
+    If the request ask for application/json the response will include error
+    code, hint and detail. Since protocol **vSPA**.
+    Otherwise, the body contains information using the template :ref:`validation-unknown <challenger_validation-unknown>`.
+
+  .. ts:def:: InvalidPinResponse
 
+    interface InvalidPinResponse {
+      // numeric Taler error code, should be shown to indicate the error
+      // compactly for reporting to developers
+      ec: Integer;
+
+      // human-readable Taler error code, should be shown for the user to
+      // understand the error
+      hint: String;
+
+      // how many times is the user still allowed to change the address;
+      // if 0, the user should not be shown a link to jump to the
+      // address entry form
+      addresses_left: Integer;
+
+      // how many times might the PIN still be retransmitted
+      pin_transmissions_left: Integer;
+
+      // how many times might the user still try entering the PIN code
+      auth_attempts_left: Integer;
+
+      // if true, the PIN was not even evaluated as the user previously
+      // exhausted the number of attempts
+      exhausted: boolean;
+
+      // if true, the PIN was not even evaluated as no challenge was ever
+      // issued (the user must have skipped the step of providing their
+      // address first!)
+      no_challenge: boolean;
+    }
 
 .. _challenger-auth: