document KYC templates:

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