[taler-docs] branch master updated: expand 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 1173ab8  expand docs
1173ab8 is described below

commit 1173ab8e99c321f5d9db780cf49142b1176612bf
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Wed Mar 31 12:34:10 2021 +0200

    expand docs
---
 anastasis.rst | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 73 insertions(+), 11 deletions(-)

diff --git a/anastasis.rst b/anastasis.rst
index 19612a0..77fb1d6 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2019 Taler Systems SA
+  Copyright (C) 2019. 2021 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU General Public License as published by the Free Software
@@ -1942,23 +1942,85 @@ a state where the user can choose which challenges to 
satisfy:
 
     {
       "recovery_state": "CHALLENGE_SELECTING",
-      FIXME: document rest of state here!
+      "recovery_information": {
+        "challenges": [
+          {
+            "uuid": "MW2R3RCBZPHNC78AW8AKWRCHF9KV3Y82EN62T831ZP54S3K5599G",
+            "cost": "TESTKUDOS:0",
+            "type": "question",
+            "instructions": "q1"
+          },
+          {
+            "uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+            "cost": "TESTKUDOS:0",
+            "type": "email",
+            "instructions": "e-mail address m?il@f*.bar"
+          }
+        ],
+        "policies": [
+          [
+            {
+              "uuid": "MW2R3RCBZPHNC78AW8AKWRCHF9KV3Y82EN62T831ZP54S3K5599G"
+            },
+            {
+              "uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0"
+            }
+          ]
+        ],
+        "provider_url": "http://localhost:8088/";,
+        "version": 1 // FIXME: wrong in code!
+      },
+      "recovery_document": {
+        ...
+      }
     }
 
+The ``recovery_document`` is an internal representation of the recovery
+information and of no concern to the user interface. The pertinent information
+is in the ``recovery_information``. Here, the ``challenges`` array is a list
+of possible challenges the user could attempt to solve next, while ``policies``
+is an array of policies, with each policy being an array of challenges.
+Satisfying all of the challenges of one of the policies will enable the secret
+to be recovered.  The ``provider_url`` from where the recovery document was
+obtained and its ``version`` are also provided.  Each challenge comes with
+four mandatory fields:
+
+    - **uuid**: a unique identifier of the challenge; this is what the
+      UUIDs in the policies array refer to, but also this UUID may be
+      included in messages sent to the user. They allow the user to
+      distinguish different PIN/TANs should say the same phone number be
+      used for SMS-authentication with different providers.
+    - **cost**: this is the amount the Anastasis provider will charge
+      to allow the user to pass the challenge.
+    - **type**: this is the type of the challenge, as a string.
+    - **instructions**: contains additional important hints for the user
+      to allow the user to satisfy the challenge.  It typically includes
+      an abbreviated form of the contact information or the security
+      question. Details depend on ``type``.
+
 If a recovery document was not found, either the user never performed
 a backup, entered incorrect attributes or used a provider not yet in
 the list of Anastasis providers.  Hence, the user must now either
 select a different provider, or go ``back`` and update the identity
-attributes.  In the case a recovery document was not found, an
-example for the new state is:
+attributes.  In the case a recovery document was not found, the
+transition fails, returning the error code and a human-readable error
+message together with a transition failure:
 
 .. code-block:: json
 
     {
-      "recovery_state": "CHALLENGE_SELECTING",
-      FIXME: document rest of state here!
+      "recovery_state": "ERROR",
+      "error_message": "account unknown to Anastasis server",
+      "error_code": 9,
     }
 
+Here, the ``error_code`` is from the ``enum ANASTASIS_RecoveryStatus``
+and describes precisely what failed about the download, while the
+``error_message`` is a human-readable (English) explanation of the code.
+However, in general it should be sufficient to display the slightly
+more generic Taler error code that is returned with the new state.
+
+
 **change_version:**
 
 Even if a recovery document was found, it is possible that the user
@@ -1972,13 +2034,13 @@ which takes a provider URL and policy version as 
arguments:
 
     {
       "provider_url": "https://localhost:8080/";,
-      "version": 2 // FIXME: correct like this?
+      "version": 2
     }
 
-The resulting states are the same as those of the
-``enter_user_attributes`` transition, except that the recovery
-document version is not necessarily the latest available version
-at the provider.
+Note that using a version of 0 implies fetching ``the latest version``.  The
+resulting states are the same as those of the ``enter_user_attributes``
+transition, except that the recovery document version is not necessarily the
+latest available version at the provider.
 
 
 **select_challenge:**

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