[taler-docs] branch master updated: fix #8731

[gnunet]

This is an automated email from the git hooks/post-receive script.

sebasjm pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new da16cc31 fix #8731
da16cc31 is described below

commit da16cc31bd1136ab202e048368ff69a13ee612d0
Author: Sebastian <sebasjm@gmail.com>
AuthorDate: Fri Apr 12 10:17:21 2024 -0300

    fix #8731
---
 core/api-challenger.rst     | 160 +++++++++++++++++++++++++++++++++++++++++---
 taler-challenger-manual.rst |  14 +++-
 taler-exchange-manual.rst   |   4 +-
 taler-merchant-manual.rst   |   4 +-
 4 files changed, 167 insertions(+), 15 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:
 
diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst
index 39b06710..dab1d954 100644
--- a/taler-challenger-manual.rst
+++ b/taler-challenger-manual.rst
@@ -532,8 +532,8 @@ Template Customization
 ======================
 
 The Challenger service comes with various HTML templates that are shown to
-guide users through the process. Challenger uses `Mustach
-<https://gitlab.com/jbol/mustach>`__ as the templating engine.  This section
+guide users through the process. Challenger uses `C implementation of mustache
+<https://gitlab.com/jobol/mustach>`__ as the templating engine.  This section
 describes the various templates.  In general, the templates must be installed
 to the ``share/challenger/templates/`` directory. The file names must be of
 the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template and
@@ -545,6 +545,8 @@ exists, the correct language will be automatically served.
 The following subsections give details about each of the templates. The
 subsection title is the ``$NAME`` of the respective template.
 
+.. _challenger_enter-address_type-form:
+
 enter-$ADDRESS_TYPE-form
 ------------------------
 
@@ -571,6 +573,8 @@ The template is instantiated using the following 
information:
   * changes_left: Integer; number of times the address can still be changed,
     may or may not be shown to the user
 
+.. _challenger_enter-tan-form:
+
 enter-tan-form
 --------------
 
@@ -597,6 +601,8 @@ The template is instantiated using the following 
information:
     the challenge the next time (at the earliest) if requested by the user
 
 
+.. _challenger_invalid-pin:
+
 invalid-pin
 -----------
 
@@ -631,6 +637,8 @@ values are zero. (Thus there is always at least one valid 
choice when the form
 is shown.)
 
 
+.. _challenger_validation-unknown:
+
 validation-unknown
 ------------------
 
@@ -648,6 +656,7 @@ The template is instantiated using the following 
information:
   * detail: String; optional, extended human-readable text provided to 
elaborate
     on the error, should be shown to provide additional context
 
+.. _challenger_invalid-request:
 
 invalid-request
 ---------------
@@ -665,6 +674,7 @@ The template is instantiated using the following 
information:
   * detail: String; optional, extended human-readable text provided to 
elaborate
     on the error, should be shown to provide additional context
 
+.. _challenger_internal-error:
 
 internal-error
 --------------
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index fd848876..91865f24 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1948,8 +1948,8 @@ Template Customization
 ======================
 
 The Exchange comes with various HTML templates that are shown to
-guide users through the KYC process. The Exchange uses `Mustach
-<https://gitlab.com/jbol/mustach>`__ as the templating engine.  This section
+guide users through the KYC process. The Exchange uses `C implementation of 
mustache
+<https://gitlab.com/jobol/mustach>`__ as the templating engine.  This section
 describes the various templates.  In general, the templates must be installed
 to the ``share/taler/exchange/templates/`` directory. The file names must be of
 the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template and
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 6374910a..353885cd 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1115,8 +1115,8 @@ Template Customization
 
 The installation process will install various HTML templates to be served to
 trigger the wallet interaction. You may change those templates to your own
-design. The templating language used is `Mustach
-<https://gitlab.com/jbol/mustach>`__, and the templates are in the
+design. The templating language used is `C implementation of mustache
+<https://gitlab.com/jobol/mustach>`__, and the templates are in the
 ``share/taler/merchant/templates/`` directory.
 
 The file names must be of the form ``$NAME.$LANG.must`` where ``$NAME`` is the

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.