[taler-docs] branch master updated: document KYC templates:

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new b061229e document KYC templates:
b061229e is described below

commit b061229e5610b01faf1ccd48b9a0aa1d596f85ba
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat Feb 17 19:11:51 2024 +0100

    document KYC templates:
---
 libeufin/regional-manual.rst |  30 ++--
 taler-exchange-manual.rst    | 317 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 332 insertions(+), 15 deletions(-)

diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
index b47adee9..e3389a2d 100644
--- a/libeufin/regional-manual.rst
+++ b/libeufin/regional-manual.rst
@@ -101,28 +101,28 @@ reachable IP address(es) *and* with various DNS names 
already pointing to
 these IPs.
 
 Preparing the required subdomain names
-++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++
 
-The GNU Taler program needs to have three subdomains pointing to your server 
IP address, in order to let NGINX to accommodate each component. 
-These are "bank", "exchange" and "backend", this said, you need to have a 
registered top level domain name, 
-where you can create type (A) entries, as subdomains pointing to your own 
server public IP address. 
+The GNU Taler program needs to have three subdomains pointing to your server 
IP address, in order to let NGINX to accommodate each component.
+These are "bank", "exchange" and "backend", this said, you need to have a 
registered top level domain name,
+where you can create type (A) entries, as subdomains pointing to your own 
server public IP address.
 A very good advice when creating these subdomains, and if your domain panel 
lets you specify the TTL (time to live) figure, is
-to specify a very low value (such as 300), so in case of future changes, its 
value (the IP address), will be propagated quickly.  
+to specify a very low value (such as 300), so in case of future changes, its 
value (the IP address), will be propagated quickly.
 
 Once you have added the three required subdomains in your domain control 
panel, you have to make sure as well, these subdomains have
-propogated over the Internet correctly, and they are currently publicly 
available. 
+propogated over the Internet correctly, and they are currently publicly 
available.
 
 You can check this from your terminal very easily with the "dig" command, as 
this:
 
 .. code-block:: console
 
-   $ dig -t txt bank.domainname.ltd 
+   $ dig -t txt bank.domainname.ltd
    $ dig -t txt exchange.domainname.ltd
    $ dig -t txt backend.domainname.ltd
 
-You can also use `this tool <https://toolbox.googleapps.com/apps/dig/>`_ for 
the same purpose, and to check the propagation status. 
+You can also use `this tool <https://toolbox.googleapps.com/apps/dig/>`_ for 
the same purpose, and to check the propagation status.
 
-Now you are ready to go with the next step. 
+Now you are ready to go with the next step.
 
 Obtaining the Scripts
 +++++++++++++++++++++
@@ -185,13 +185,13 @@ Grab a coffee.
 Running the script again from scratch
 +++++++++++++++++++++++++++++++++++++
 
-If for some reason your installation doesn't work because you have answered 
erroneously 
+If for some reason your installation doesn't work because you have answered 
erroneously
 some of the interactive questions, or you just want to reset the current 
installation and to re-deploy
-the script again for having its latest changes, you will have to proceed as 
follows: 
+the script again for having its latest changes, you will have to proceed as 
follows:
 
 In brief you need to wipe completely the "content" of the file 
config/user.conf, this doesn't mean
 to remove the file itself, but only its content. Eventhough you can do this 
manually by editing the file manually
-with you preferred text editor, you can also do this in one single command. 
+with you preferred text editor, you can also do this in one single command.
 
 .. code-block:: console
 
@@ -199,8 +199,8 @@ with you preferred text editor, you can also do this in one 
single command.
 
 .. note::
 
-   In future versions of the program when executed for the second time, the 
program itself will 
-   show an option to offer wiping the content of this config/user.conf file, 
automatically. 
+   In future versions of the program when executed for the second time, the 
program itself will
+   show an option to offer wiping the content of this config/user.conf file, 
automatically.
 
 Multi-factor authentification
 +++++++++++++++++++++++++++++
@@ -236,7 +236,7 @@ Manual Setup
 
 This section describes how to setup a regional currency manually.
 
-You first need to setup the :ref:`libeufin-bank<libeufin-bank>` and integrate 
it with a Taler exchange. 
+You first need to setup the :ref:`libeufin-bank<libeufin-bank>` and integrate 
it with a Taler exchange.
 
 If you don't want your regional currency to be backed by a fiat currency, you 
can stop here.
 
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 9cdd51d1..088f71d2 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1936,6 +1936,323 @@ grant the permissions to the other exchange processes 
again.
 
 
 
+.. _ExchangeTemplateCustomization:
+
+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
+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
+``$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. Most
+subsection title are the ``$NAME`` of the respective template.
+
+
+Generic Errors Templates
+------------------------
+
+A number of templates are used for generic errors. These are:
+
+  * kyc-proof-already-done (KYC process already completed)
+  * kyc-bad-request (400 Bad Request)
+  * kyc-proof-endpoint-unknown (404 Not Found for KYC logic)
+  * kyc-proof-internal-error (500 Internal Server Error)
+  * kyc-proof-target-unknown (404 Not Found for KYC operation)
+
+All of these templates are 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
+
+  * message: String; optional, extended human-readable text provided to 
elaborate
+    on the error, should be shown to provide additional context
+
+
+kycaid-invalid-request
+----------------------
+
+The KYCaid plugin does not support requests to the
+``/kyc-proof/`` endpoint (HTTP 400 bad request).
+
+This templates 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
+
+  * error: String; error code from the server
+
+  * error_details: String; optional error description from the server
+
+  * error_uri: optional URI with further details about the error from the 
server
+
+
+
+oauth2-authentication-failure
+-----------------------------
+
+The OAuth2 server said that the request was not
+properly authenticated (HTTP 403 Forbidden).
+
+
+This templates 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
+
+
+oauth2-authorization-failure
+----------------------------
+
+The OAuth2 server refused to return the KYC data
+because the authorization code provided was
+invalid (HTTP 403 Forbidden).
+
+This templates 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
+
+  * error: String; error code from the server
+
+  * error_message: String; error message from the server
+
+
+oauth2-authorization-failure-malformed
+--------------------------------------
+
+The server refused the authorization, but then provided
+a malformed response (HTTP 502 Bad Gateway).
+
+This templates 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
+
+  * debug: Bool; true if we are running in debug mode and are allowed to 
return HTML with potentially sensitive information
+
+  * server_response: Object; could be NULL; this includes the (malformed) 
OAuth2 server response, it should be shown to the use if "debug" is true
+
+
+oauth2-bad-request
+------------------
+
+The client made an invalid request (HTTP 400 Bad Request).
+
+This templates 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
+
+  * message: String; additional error message elaborating on what was bad 
about the request
+
+
+oauth2-conversion-failure
+-------------------------
+
+Converting the KYC data into the exchange's internal
+format failed (HTTP 502 Bad Gateway).
+
+This templates 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
+
+  * debug: Bool; true if we are running in debug mode and are allowed to 
return HTML with potentially sensitive information
+
+  * converter: String; name of the conversion command that failed which was 
used by the Exchange
+
+  * attributes: Object; attributes returned by the conversion command, often 
NULL (after all, conversion failed)
+
+  * message: error message elaborating on the conversion failure
+
+
+oauth2-provider-failure
+-----------------------
+
+We did not get an acceptable response from the OAuth2
+provider (HTTP 502 Bad Gateway).
+
+This templates 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
+
+  * message: String; could be NULL; text elaborating on the details of the 
failure
+
+
+persona-exchange-unauthorized
+-----------------------------
+
+The Persona server refused our request (HTTP 403 Forbidden from Persona, 
returned as a HTTP 502 Bad Gateway).
+
+This templates 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
+
+  * data: Object; data returned from Persona service, optional
+
+  * persona_http_status: Integer; HTTP status code returned by Persona
+
+
+persona-load-failure
+--------------------
+
+The Persona server refused our request (HTTP 429 Too Many Requests from 
Persona, returned as a HTTP 503 Service Unavailable).
+
+This templates 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
+
+  * data: Object; data returned from Persona service, optional
+
+  * persona_http_status: Integer; HTTP status code returned by Persona
+
+
+persona-exchange-unpaid
+-----------------------
+
+The Persona server refused our request (HTTP 402 Payment REquired from 
Persona, returned as a HTTP 503 Service Unavailable).
+
+This templates 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
+
+  * data: Object; data returned from Persona service, optional
+
+  * persona_http_status: Integer; HTTP status code returned by Persona
+
+
+
+persona-logic-failure
+---------------------
+
+The Persona server refused our request (HTTP 400, 403, 409, 422 from Persona, 
returned as a HTTP 502 Bad Gateway).
+
+This templates 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
+
+  * data: Object; data returned from Persona service, optional
+
+  * persona_http_status: Integer; HTTP status code returned by Persona
+
+
+persona-invalid-response
+------------------------
+
+The Persona server refused our request in an
+unexpected way; returned as a HTTP 502 Bad Gateway.
+
+This templates 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
+
+  * debug: Bool; true if we are running in debug mode and are allowed to 
return HTML with potentially sensitive information
+
+  * server_response: Object; could be NULL; this includes the (malformed) 
OAuth2 server response, it should be shown to the use if "debug" is true
+
+
+persona-network-timeout
+-----------------------
+
+The Persona server refused our request (HTTP 408 from Persona, returned as a 
HTTP 504 Gateway Timeout).
+
+This templates 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
+
+  * data: Object; data returned from Persona service, optional
+
+  * persona_http_status: Integer; HTTP status code returned by Persona
+
+
+persona-kyc-failed
+------------------
+
+The Persona server indicated a problem with the KYC process, saying it was not 
completed.
+
+This templates is instantiated using the following information:
+
+  * persona_inquiry_id: String; internal ID of the inquiry within Persona, 
useful for further diagnostics by staff
+
+  * data: Object; could be NULL; this includes the server response, it 
contains extensive diagnostics, see Persona documentation on their 
``/api/v1/inquiries/$ID``.
+
+  * persona_http_status: Integer; HTTP status code returned by Persona
+
+persona-provider-failure
+------------------------
+
+The Persona server refused our request (HTTP 500 from Persona, returned as a 
HTTP 502 Bad Gateway).
+
+This templates 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
+
+  * data: Object; data returned from Persona service, optional
+
+  * persona_http_status: Integer; HTTP status code returned by Persona
+
+
 .. _ExchangeBenchmarking:
 
 Benchmarking

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