document more of reducer

1 files changed, 120 insertions, 23 deletions

diff --git a/anastasis.rst b/anastasis.rst
index 8eab4612..562c2964 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -1536,12 +1536,19 @@ response:
       ]
     }
 
-If the index is invalid, the reducer will transition into an ERROR state.
+If the index is invalid, the reducer will instead
+transition into an ERROR state.
 
 
 **next** (from "AUTHENTICATIONS_EDITING"):
 
-Optional arguments to try uploading recovery document only to specific providers (example):
+This transition confirms that the user has finished adding (or removing)
+authentication methods, and that the system should now automatically compute
+a set of reasonable recovery policies.
+
+This transition does not take any mandatory arguments.  Optional arguments can
+be provided to upload the recovery document only to a specific subset of the
+providers:
 
 .. code-block:: json
 
@@ -1554,21 +1561,72 @@ Optional arguments to try uploading recovery document only to specific providers
 
 ..note::
 
-  This is currently not supported (#6760).
+  This is currently not supported (#6760), the current implementation of the
+  reducer ignores this optional argument.
 
-Expected new state (backup process):
+The resulting state provides the suggested recovery policies in a way suitable
+for presentation to the user:
 
 .. code-block:: javascript
 
     {
       "backup_state": "POLICIES_REVIEWING",
-      // FIXME: give example of calculated policies here!
+      "policies": [
+        {
+          "recovery_cost": "TESTKUDOS:0",
+          "methods": [
+            {
+              "authentication_method": 0,
+              "provider": "http://localhost:8088/"
+            },
+            {
+              "authentication_method": 1,
+              "provider": "http://localhost:8089/"
+            },
+            {
+              "authentication_method": 2,
+              "provider": "http://localhost:8087/"
+            }
+          ]
+        },
+        {
+          "recovery_cost": "TESTKUDOS:0",
+          "methods": [
+            {
+              "authentication_method": 0,
+              "provider": "http://localhost:8088/"
+            },
+            {
+              "authentication_method": 1,
+              "provider": "http://localhost:8089/"
+            },
+            {
+              "authentication_method": 3,
+              "provider": "http://localhost:8089/"
+            }
+          ]
+        }
+      ]
     }
 
+For each recovery policy, the state includes the ``recovery_cost`` (which is
+the sum of the costs to solve all challenges associated with the policy with
+the respective providers), as well as the specific details of which
+authentication ``methods`` must be solved to recovery the secret using this
+policy.  The ``methods`` array specifies the index of the
+``authentication_method`` in the ``authentication_methods`` array, as well as
+the provider that was selected to supervise this authentication.
+
+If no authentication method was provided, the reducer will transition into an
+ERROR state instead of suggesting policies.
+
 
 **add_policy**:
 
-Arguments (example):
+Using this transition, the user can add an additional recovery policy to the
+state.  The argument format is the same that is used in the existing state,
+except that the ``recovery_cost`` should be omitted (as the reducer will
+calculate it). An example for a possible argument would thus be:
 
 .. code-block:: javascript
 
@@ -1585,7 +1643,10 @@ Arguments (example):
       ]
     }
 
-Expected new state:
+Note that the specified providers must already be in the
+``authentication_providers`` of the state. You cannot add new providers at
+this stage.  The reducer will simply attempt to append the suggested policy to
+the "policies" array, returning an updated state:
 
 .. code-block:: json
 
@@ -1647,10 +1708,16 @@ Expected new state:
       ]
     }
 
+If the new policy is invalid, for example because it add an unknown
+authentication method or the selected provider does not support the type of
+authentication, the reducer will transition into an ERROR state instead of
+adding the new policy.
+
 
 **delete_policy:**
 
-Arguments (example):
+This transition allows the deletion of a recovery policy. The argument
+simply specifies the index of the policy to delete, for example:
 
 .. code-block:: json
 
@@ -1658,7 +1725,8 @@ Arguments (example):
       "policy_index": 3
     }
 
-Expected new state:
+Given as input the state from the example above, the expected new state would
+be:
 
 .. code-block:: json
 
@@ -1707,12 +1775,16 @@ Expected new state:
       ]
     }
 
+If the index given is invalid, the reducer will transition into an ERROR state
+instead of deleting a policy.
+
 
 **next** (from "POLICIES_REVIEWING"):
 
-No arguments.
+Using this transition, the user confirms that the policies in the current
+state are acceptable. The transition does not take any arguments.
 
-Expected new state (backup process):
+The reducer will simply transition to the ``SECRET_EDITING`` state:
 
 .. code-block:: json
 
@@ -1721,29 +1793,56 @@ Expected new state (backup process):
     }
 
 
+If the array of ``policies`` is currently empty, the reducer will transition
+into an ERROR state instead of allowing the user to continue.
+
+
 **enter_secret:**
 
-Arguments (example):
+This transition provides the reducer with the actual core secret of the user
+that Anastasis is supposed to backup (and possibly recover). The argument is
+simply the Crockford-Base32 encoded ``secret``, for example:
 
 .. code-block:: javascript
 
     {
-      "secret": string
+      "secret": "EDJP6WK5EG50"
     }
 
-- secret: must be a Crockford-Base32 encoded string of some data
+Applications SHOULD prefix the encoded ``secret`` with some data that allows
+applications to recognize the application and the version of the secret.  The
+suggested notation is ``$APPLICATION/$VERSION:$SECRET``, for example
+``taler-wallet/42:KEYMATERIAL``.  In case the secret is provided from a file
+and the application is oblivious to the details, the same syntax can be used
+to prefix the secret with a MIME type, for example ``image/png:IMAGE``.  If
+the application is unaware of the format, it should use ``*/*:DATA``.
 
+..note::
 
-Expected new states include:
+  The prefixing of the secret with the mime-type or application version
+  is currently not implemented (#6825).
+
+
+After adding a secret, the reducer may transition into different states
+depending on whether payment(s) are necessary.  If payments are needed, the
+``secret`` will be stored in the state under ``core_secret``.  Applications
+should be careful when persisting the resulting state, as the ``core_secret``
+is not protected in the ``PAYING`` states.  The ``PAYING`` states only differ
+in terms of what the payments are for (key shares or the recovery document),
+in all cases the state simply includes an array of Taler URIs that refer to
+payments that need to be made with the Taler wallet.
+
+If all payments are complete, the reducer will transition into the
+``BACKUP_FINISHED`` state and (if applicable) delete the ``core_secret`` as an
+additional safety measure.
+
+Example results are thus:
 
 .. code-block:: json
 
     {
       "backup_state": "TRUTHS_PAYING",
-      "core_secret" : {
-        "secret": "DATA",
-        "type": "passpharse"
-      },
+      "core_secret" : "DATA",
       "payments": [
         "taler://pay/...",
         "taler://pay/..."
@@ -1754,10 +1853,7 @@ Expected new states include:
 
     {
       "backup_state": "POLICIES_PAYING",
-      "core_secret" : {
-        "secret": "DATA",
-        "type": "passpharse"
-      },
+      "core_secret" : "DATA",
       "payments": [
         "taler://pay/...",
         "taler://pay/..."
@@ -1773,6 +1869,7 @@ Expected new states include:
 
 **pay:**
 
+FIXME: this is wrong! long polling!
 Optional arguments to try uploading just specific truths (example):
 
 .. code-block:: json