[taler-docs] branch master updated: work on Anastasis docs

[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 eb97aa4  work on Anastasis docs
eb97aa4 is described below

commit eb97aa4cf503bdc7955dda78bc1599d5a0660603
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Mon Mar 29 21:24:31 2021 +0200

    work on Anastasis docs
---
 anastasis.rst | 173 +++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 160 insertions(+), 13 deletions(-)

diff --git a/anastasis.rst b/anastasis.rst
index 0499ab8..3262565 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -922,10 +922,42 @@ above would look like following for the transition 
action_ "select_continent":
     ]
   }
 
-**State**:
-  - In SELECTING-States the user has to choose one value out of a predefined 
set of values (for example a continent out of a set of continents).
-  - In COLLECTING-States the user has to give certain values.
-  - In EDITING-States the user is free to choose which values he wants to give.
+States
+^^^^^^
+
+Overall, the reducer knows the following states:
+
+  - **ERROR**: The transition lead to an error. No further transitions are 
possible from
+               this state, but the client may want to continue from a previous 
state.
+  - **CONTINENT_SELECTING**: The user should specify the continent where they 
are living,
+               so that we can show a list of countries to choose from.
+  - **COUNTRY_SELECTING**: The user should specify the country where they are 
living,
+               so that we can determine appropriate attributes, currencies and 
Anastasis
+               providers.
+  - **USER_ATTRIBUTES_COLLECTING**: The user should provide the 
country-specific personal
+               attributes.
+  - **AUTHENTICATIONS_EDITING**: The user should add authentication methods to 
be used
+               during recovery.
+  - **POLICIES_REVIEWING**: The user should review the recovery policies.
+  - **SECRET_EDITING**: The user should edit the secret to be backed up.
+  - **TRUTHS_PAYING**: The user needs to pay for one or more uploads of data 
associated
+               with an authentication method.
+  - **POLICIES_PAYING**: The user needs to pay for storing the recovery policy 
document.
+  - **BACKUP_FINISHED**: A backup has been successfully generated.
+  - **CHALLENGE_SELECTING**: The user needs to select an authorization 
challenge to
+               proceed with recovery.
+  - **CHALLENGE_PAYING**: The user needs to pay to proceed with the 
authorization challenge.
+  - **CHALLENGE_SOLVING**: The user needs to solve the authorization challenge.
+  - **RECOVERY_FINISHED**: The secret of the user has been recovered.
+
+State names:
+
+  - In SELECTING-states, the user has to choose one value out of a predefined 
set of values (for example a continent out of a set of continents).
+  - In COLLECTING-states, the user has to give certain values.
+  - In EDITING-states, the user is free to choose which values he wants to 
give.
+  - In REVEIWING-states, the user may make a few choices, but primarily is 
expected to affirm something.
+  - in PAYING-states, the user must make a payment.
+  - in FINISHED-states, the operation has definitively concluded.
 
 
 Backup Reducer
@@ -963,12 +995,14 @@ process.
 Reducer transitions
 ^^^^^^^^^^^^^^^^^^^
 In the following, the individual transitions will be specified in more detail.
+Note that we only show fields added by the reducer, typically the previous
+state is preserved to enable "back" transitions to function smoothly.
 
 
 Initial state
 -------------
 
-The initial states for backup and recovery processes are looking like 
following:
+The initial states for backup and recovery processes are:
 
 **Initial backup state:**
 
@@ -978,7 +1012,7 @@ The initial states for backup and recovery processes are 
looking like following:
       "backup_state": "CONTINENT_SELECTING",
       "continents": [
         "Europe",
-        "North_America"
+        "North America"
       ]
     }
 
@@ -991,17 +1025,49 @@ The initial states for backup and recovery processes are 
looking like following:
       "recovery_state": "CONTINENT_SELECTING",
       "continents": [
         "Europe",
-        "North_America"
+        "North America"
+      ]
+    }
+
+Here, "continents" is an array of English strings with the names of the
+continents which contain countries for which Anastasis could function (based
+on having providers that are known to operate and rules being provided for
+user attributes from those countries).
+
+For internationalization, another field "continents_i18n" may be present.
+This field would be a map of language names to arrays of translated
+continent names:
+
+.. code-block:: json
+
+    {
+      "recovery_state": "CONTINENT_SELECTING",
+      "continents": [
+        "Europe",
+        "North America"
       ]
+      "continents_i18n":
+      {
+        "de_DE" : [
+          "Europa",
+          "Nordamerika"
+          ],
+        "de_CH" : [
+          "Europa",
+          "Nordamerika"
+          ]
+      }
     }
 
+Translations must be given in the same order as the main English array.
+
 
 Common transitions
 ------------------
 
 **select_continent:**
 
-Arguments (example):
+Here the user specifies the continent they live on.  Arguments (example):
 
 .. code-block:: json
 
@@ -1009,7 +1075,11 @@ Arguments (example):
       "continent": "Europe"
     }
 
-Expected new state:
+The continent must be given using the English name from the "continents" array.
+Using a translated continent name is invalid and may result in failure.
+
+The reducer returns an updated state with a list of countries to choose from,
+for example:
 
 .. code-block:: json
 
@@ -1047,6 +1117,19 @@ Expected new state:
       ]
     }
 
+Here "countries" is an array of countries on the "selected_continent".  For
+each country, the "code" is the ISO 3166-1 alpha-2 country code.  The
+"continent" is only present because some countries span continents, the
+information is redundant and will always match "selected_continent".  The
+"name" is the name of the country in English, internationalizations of the
+name may be provided in "name_i18n".  The "currency" is **an** official
+currency of the country, if a country has multiple currencies, it may appear
+multiple times in the list.  In this case, the user should select the entry
+with the currency they intend to pay with.  It is also possible for users
+to select a currency that does not match their country, but user interfaces
+should by default try to use currencies that match the user's residence.
+
+
 **select_country:**
 
 Selects the country (via the country code) and specifies the currency.
@@ -1063,7 +1146,13 @@ Arguments (example):
       "currency": "EUR"
     }
 
-Expected new state:
+The "country_code" must be an ISO 3166-1 alpha-2 country code from
+the array of "countries" of the reducer's state.  The "currency"
+field must be a valid currency accepted by the Taler payment system.
+
+The reducer returns a new state with the list of attributes the
+user is expected to provide, as well as possible authentication
+providers that accept payments in the selected currency:
 
 .. code-block:: json
 
@@ -1082,7 +1171,8 @@ Expected new state:
             "fr": "Nom complet",
             "en": "Full name"
           },
-          "widget": "anastasis_gtk_ia_full_name"
+          "widget": "anastasis_gtk_ia_full_name",
+          "uuid" : "9e8f463f-575f-42cb-85f3-759559997331"
         },
         {
           "type": "date",
@@ -1094,6 +1184,7 @@ Expected new state:
             "fr": "Date de naissance",
             "en": "Birthdate"
           },
+          "uuid" : "83d655c7-bdb6-484d-904e-80c1058c8854"
           "widget": "anastasis_gtk_ia_birthdate"
         },
         {
@@ -1106,8 +1197,10 @@ Expected new state:
             "fr": "Numéro de sécurité sociale",
             "en": "Social security number"
           },
-          "widget": "anastasis_gtk_ia_ssn"
-        }
+          "widget": "anastasis_gtk_ia_ssn",
+             "validation-regex": "^[0-9]{8}[[:upper:]][0-9]{3}$",
+             "validation-logic": "DE_SVN_check"
+      }
       ],
       "authentication_providers": {
         "http://localhost:8089/": {
@@ -1145,6 +1238,60 @@ Expected new state:
       }
     }
 
+The array of "required_attributes" contains attributes about the user
+that must be provided includes:
+
+  - **type**: the type of the attribute, for now only 'string' and 'date' are
+    supported
+  - **name**: the name of the attribute, this is the key under which the
+    attribute value must be provided later. The name must be unique per 
response.
+  - **label**: a human-readable description of the attribute in English.
+    Translated descriptions may be provided under **label_i18n**.
+  - **uuid**: a UUID that uniquely identifies identical attributes across
+    different countries. Useful to preserve values should the user enter
+    some attributes, and then switch to another country.  Note that
+    attributes must not be preserved if they merely have the same **name**,
+    only the **uuid** will be identical if the semantics is identicial.
+  - **widget**: an optional name of a widget that is known to nicely render
+    the attribute entry in user interfaces where named widgets are
+    supported.
+  - **validation-regex**: an optional extended POSIX regular expression
+    that is to be used to validate (string) inputs to ensure they are
+    well-formed.
+  - **validation-logic**: optional name of a function that should be called
+    to validate the input.  If the function is not known to the particular
+    client, the respective validation can be skipped (at the expense of
+    typos by users not being detected, possibly rendering secrets
+    irrecoverable).
+
+The authentication providers are listed under a key that is the
+base URL of the service. For each provider, the following
+information is provided:
+
+  - **methods**: array of authentication methods supported by this
+    provider. Includes the **type** of the authentication method
+    and the **usage_fee** (how much the user must pay for authorization
+    using this method during recovery).
+  - **annual_fee**: fee the provider charges to store the recovery
+    policy for one year.
+  - **truth_upload_fee**: fee the provider charges to store a key share.
+  - **truth_lifetime**: Taler-style relative time that specifies how
+    long the provider will store truth data (key shares) after an upload.
+  - **liability_limit**: amount the provider can be held liable for in
+    case a key share or recovery document cannot be recovered due to
+    provider failures.
+  - **currency**: currency in which the provider wants to be paid,
+    will match all of the fees.
+  - **storage_limit_in_megabytes**: maximum size of an upload (for
+    both recovery document and truth data) in megabytes.
+  - **provider_name**: human-readable name of the provider's business.
+  - **salt**: salt value used by the provider, used to derive the
+    user's identity at this provider. Should be unique per provider,
+    and must never change for a given provider.  The salt is
+    base32 encoded.
+
+FIXME: specify what will be provided in case GET /config fails!
+
 
 **add_provider**:
 

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