From 7e669bcf6b6336ec429da949bcb4aa456971dba2 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 30 Jul 2021 10:38:27 +0200 Subject: folding history in preparation of GNU Anastasis v0.0.0 release --- doc/sphinx/design-documents/001-anastasis-ux.rst | 318 +++++++++++++++++++++++ 1 file changed, 318 insertions(+) create mode 100644 doc/sphinx/design-documents/001-anastasis-ux.rst (limited to 'doc/sphinx/design-documents/001-anastasis-ux.rst') diff --git a/doc/sphinx/design-documents/001-anastasis-ux.rst b/doc/sphinx/design-documents/001-anastasis-ux.rst new file mode 100644 index 0000000..741d6ca --- /dev/null +++ b/doc/sphinx/design-documents/001-anastasis-ux.rst @@ -0,0 +1,318 @@ +Design Doc 001: Anastasis User Experience +######################################### + +Summary +======= + +This document describes the recommended way of implementing the user experience +of setting up and making use of :doc:`../introduction` account recovery. + +Motivation +========== + +Wallet state consisting of digital cash, transaction history etc. should not be lost. +Taler provides a backup mechanism to prevent that. +As an additional protection measure Anastasis can be used to provide access to the backup, +even if all devices and offline secrets have been lost. + +Access to the backup key is shared with escrow providers that can be chosen by the user. + +Setup Steps +=========== + +.. graphviz:: + + digraph G { + rankdir=LR; + nodesep=0.5; + settings [ + label = "Backup\nSettings"; + shape = oval; + ]; + backup_is_setup [ + label = "Backup\nsetup?"; + shape = diamond; + ]; + provide_id [ + label = "Provide\nIdentification"; + shape = rectangle; + ]; + select_auth [ + label = "Select\nAuthentication Methods"; + shape = rectangle; + ]; + provide_auth [ + label = "Provide\nAuthentication Data"; + shape = rectangle; + ]; + select_providers [ + label = "Select\nService Providers"; + shape = rectangle; + ]; + review_policy [ + label = "Review Recovery Policy"; + shape = rectangle; + ]; + edit_policy [ + label = "Edit Recovery Policy"; + shape = rectangle; + ]; + pay [ + label = "Confirm Payment"; + shape = oval; + ]; + settings -> backup_is_setup; + backup_is_setup -> provide_id [label="Yes: Setup Recovery"]; + backup_is_setup -> settings [label="No"]; + provide_id -> select_auth; + select_auth -> provide_auth; + provide_auth -> select_auth; + select_auth -> select_providers; + select_providers -> select_auth; + select_providers -> review_policy; + review_policy -> edit_policy; + edit_policy -> review_policy; + review_policy -> pay; + } + +Entry point: Settings +--------------------- + +The app settings should have a section for Anastasis using a different more +universally understood name like Wallet Recovery. + +The section should have an option to setup Anastasis initially. This option +should be disabled as long as no backup has been set up. The section could +maybe be integrated into the backup settings. + +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/menu.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/settings.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/backupsettings.png + :width: 800 + +Providing Identification +------------------------ + +Instead of a forgettable freely chosen user name, Anastasis collects various +static information from the user to generate a unique user identifier from +that. Examples for such identifier would be a concatenation of the full name +of the user and their social security or passport number(s). + +The information that can reasonably used here various from cultural context +and jurisdiction. Therefore, one idea is to start by asking for continent and +then the country of primary legal residence, and then continue from there with +country-specific attributes (and also offer a stateless person option). + +Special care should be taken to avoid that information can later be provided +ambiguously thus changing the user identifier and not being able to restore +the user's data. This can be typographic issues like someone providing +"Seestr." and later "Seestrasse" or "Seestraße" or "seestrasse". But it can +also be simple typos that we can only prevent in some instances like when +checking checksums in passport numbers. + +The user should be made aware that this data will not leave the app and that +it is only used to compute a unique identifier that can not be forgotten. + +If possible, we should guide the user in the country selection by accessing +permission-less information such as the currently set language/locale and the +country of the SIM card. But nothing invasive like the actual GPS location. + +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/userid.png + :width: 800 + +Add Authentication Methods +-------------------------- + +After creating a unique identifier, the user can chose one or more +:ref:`anastasis-auth-methods` supported by Anastasis. + +When selecting a method, the user is already asked to provide the information +required for the recovery with that method. For example, a photo of +themselves, their phone number or mailing address. + +The user interface validates that the inputs are well-formed, and refuses +inputs that are clearly invalid. Where possible, it pre-fills the fields with +sane values (phone number, e-mail addresses, country of residence). + +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/truth.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addtruth.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addtruthmail.png + :width: 800 + + +Confirm/Change Service Providers +-------------------------------- + +From the dialog where the user is adding authentication methods, the user can +optionally jump to a side-action with list of available providers (and their +status) and possibly add additional providers that are not included in the +default list provided by the wallet. + +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/policy.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addpolicy.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addpolicymethod.png + :width: 800 + + +Defining Recovery Options +------------------------- + +After mapping authentication methods to providers, the user needs select which +combinations are sufficient to recover the secret. Here, the system +pre-computes a reasonably sane allocation, for small ``n`` the default could +be ``n-1`` out of ``n``. + +We should propose a mapping of authentication methods to providers by +minimizing cost (tricky: sign-up vs. recovery costs, different currencies) and +distributing the selected authentication methods across as many providers as +possible. + +The user should be able to change the proposed default selection +and add more than one provider to each chosen method. + +Using Anastatis providers usually is not free. From here on, the UI should +show estimated recurring costs (yearly) and the cost of recovery. These costs +should get updated with each user action affecting those costs such as +when the user reconfigures the policies. + + +Pay for Setup +------------- + +As the last step when all information has been properly provided, the user is +asked to pay for the service with the regular wallet payment confirmation +screen. + + +Show Service Status After Setup +=============================== + +TODO + +Recovery Steps +============== + +.. graphviz:: + + digraph G { + rankdir=LR; + nodesep=0.5; + settings [ + label = "Restore from Backup"; + shape = oval; + ]; + provide_id [ + label = "Provide\nIdentification"; + shape = rectangle; + ]; + select_challenge [ + label = "Select\nAuthentication Challenge"; + shape = rectangle; + ]; + satisfy_challenge [ + label = "Enter\nChallenge Response"; + shape = rectangle; + ]; + pay [ + label = "Confirm Payment"; + shape = oval; + ]; + finished [ + label = "Success"; + shape = rectangle; + ]; + settings -> provide_id; + provide_id -> settings [label="Back"]; + provide_id -> select_challenge; + select_challenge -> provide_id [label="Back"]; + select_challenge -> satisfy_challenge; + select_challenge -> pay; + satisfy_challenge -> pay; + pay -> satisfy_challenge; + satisfy_challenge -> select_challenge; + pay -> finished; + satisfy_challenge -> finished; + } + + +Entry point: Settings +--------------------- + +Like the backup, the recovery option should be available via +the App settings. + +The section should have an option to recover from backup. If a previous +recovery was not completed, the interaction should resume from that previous +checkpoint instead of from the beginning. + + +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/menu.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/settings.png + :width: 800 +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/backupsettings.png + :width: 800 + + +Providing Identification +------------------------ + +The first dialog(s) during recovery should be identical to the first dialog +during backup: the user is asked to select a continent, country of residence +and then to provide country-specific inputs for identification. + +.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/userid.png + :width: 800 + +Select Authentication Challenge +------------------------------- + +If Anastasis could recover the recovery document via any provider, it should +show a dialog allowing the user to select one of the open challenges, and +highlight which challenges still need to be satisfied for the various policies. + +Additionally, the specific provider and recovery document version should be shown. +The user should be able to change the provider or recovery document version, +resulting in a switch of the recovery document and policies. If the user has +already satisfied some challenges of the current recovery document, switching to a +different recovery document should only be done after a confirmation pop-up dialog +warning the user that the existing progress will be lost. + +When selecting a challenge, the user may be asked to confirm making a payment +for this challenge if the provider requires payment. + + +Payment +------- + +Typcially, this would be the canonical wallet payment confirmation dialog. + +However, in the case of a security question, the payment confirmation should +be combined with the dialog where the user enters the security answer (so +instead of an ``Ok`` button, text showing the amount due and ``Pay`` should be +used -- except of course if the security question challenge is free of +charge). + + +Enter Challenge Response +------------------------ + +If the challenge was not a security question, the dialog to enter the security +code (PIN/TAN) should open after payment. The security code field should have +a prefix ``A-``. However, the user should be able to enter both only the +numeric code, or the full code with the ``A-`` prefix (or ideally, the user +cannot delete the pre-filled ``A-`` text). + + +Success +------- + +The user is informed about the successful recovery. We may want to do this +as part of a separate screen, or simply with a notification bar in the +main wallet screen. -- cgit v1.2.3