diff options
Diffstat (limited to 'taler-challenger-manual.rst')
| -rw-r--r-- | taler-challenger-manual.rst | 168 |
1 files changed, 165 insertions, 3 deletions
diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index e4a59ee6..39b06710 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -1,7 +1,7 @@ .. This file is part of GNU TALER. - Copyright (C) 2023 Taler Systems SA + Copyright (C) 2023, 2024 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -17,8 +17,13 @@ @author Christian Grothoff @author Florian Dold -GNU Taler Challenger Operator Manual -#################################### +Challenger Operator Manual +########################## + +.. contents:: Table of Contents + :depth: 2 + :local: + Introduction ============ @@ -519,3 +524,160 @@ The Challenger database can be re-initialized using: However, running this command will result in all data in the database being lost. + + +.. _ChallengerCustomization: + +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 +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 +``$LANG`` is the 2-letter language code of the template. English templates +must exist and will be used as a fallback. If the browser (user-agent) has +provided language preferences in the HTTP header and the respective language +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. + +enter-$ADDRESS_TYPE-form +------------------------ + +These templates are used to ask the user to enter the address that challenger +is expected to validate. Here, ``$ADDRESS_TYPE`` will be replaced by the +``ADDRESS_TYPE`` configuration option in the ``[challenger]`` section of the +configuration file. Typical values include ``address`` (for physical mailing +addresses), ``phone`` (for mobile phone numbers) and ``email`` (for email +addresses). For testing, ``file`` (where the TAN code is written into a local +file) is also supported. + +The template is instantiated using the following information: + + * restrictions: 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. + * fix_address: boolean; indicates if the given address cannot be changed + anymore, the form should be read-only if set to true. + + * nonce: String; unique value identifying the challenge, should be shown + to the user so that they can recognize it when they receive the TAN code + + * last_address: Object; form values from the previous submission if available, + details depend on the ``ADDRESS_TYPE``, should be used to pre-populate the form + + * changes_left: Integer; number of times the address can still be changed, + may or may not be shown to the user + +enter-tan-form +-------------- + +This page should generate the HTML form for the user to enter the TAN code +that they received at the respective address. + +The template is instantiated using the following information: + + * nonce: String; unique value identifying the challenge, should be shown + to the user so that they can match it to the TAN code they received + + * attempts_left: Integer; 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) + + * address: Object; the address that is being validated, might be shown + or not + + * transmitted: boolean; 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 + + * next_tx_time: String; timestamp explaining when we would re-transmit + the challenge the next time (at the earliest) if requested by the user + + +invalid-pin +----------- + +The user has provided an invalid TAN code (HTTP 403 Forbidden). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * addresses_left: Integer; 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 + + * pin_transmissions_left: Integer; how many times might the PIN still + be retransmitted + + * auth_attempts_left: Integer; how many times might the user still try + entering the PIN code + + * exhausted: Bool; if true, the PIN was not even evaluated as the user previously exhausted the number of attempts + + * no_challenge: Bool; 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!) + +If both *pin_transmissions_left* and *auth_attempts_left* are zero, the link +to re-enter the PIN should be hidden and the user should only be allowed to +specify a different address. The form will never be generated if all three +values are zero. (Thus there is always at least one valid choice when the form +is shown.) + + +validation-unknown +------------------ + +The user has tried to access a validation process that is not known to the +backend (HTTP 404 Not Found). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context + + +invalid-request +--------------- + +The request of the client is invalid (HTTP 400 Bad Request). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context + + +internal-error +-------------- + +The service experienced an internal error (HTTP 500 Internal Server Error). + +The template is instantiated using the following information: + + * ec: Integer; numeric Taler error code, should be shown to indicate the + error compactly for reporting to developers + + * hint: String; human-readable Taler error code, should be shown for the + user to understand the error + + * detail: String; optional, extended human-readable text provided to elaborate + on the error, should be shown to provide additional context |