diff options
| -rw-r--r-- | core/api-challenger.rst | 160 | ||||
| -rw-r--r-- | taler-challenger-manual.rst | 14 | ||||
| -rw-r--r-- | taler-exchange-manual.rst | 4 | ||||
| -rw-r--r-- | 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 |