Merge branch 'master' of git+ssh://git.taler.net/docs

4 files changed, 224 insertions, 6 deletions

diff --git a/design-documents/004-wallet-withdrawal-flow.rst b/design-documents/004-wallet-withdrawal-flow.rst
index b13896a6..f6382446 100644
--- a/design-documents/004-wallet-withdrawal-flow.rst
+++ b/design-documents/004-wallet-withdrawal-flow.rst
@@ -73,7 +73,7 @@ The user flow between these screens is described in the following graph:
        ];
        transactions [
            label = "List of\nTransactions";
-           shape = circle;
+           shape = oval;
        ];
 
        default_exchange -> tos_changed [label="Yes"];
diff --git a/design-documents/005-wallet-backup-sync.rst b/design-documents/005-wallet-backup-sync.rst
index d91c3ff5..25213c80 100644
--- a/design-documents/005-wallet-backup-sync.rst
+++ b/design-documents/005-wallet-backup-sync.rst
@@ -111,13 +111,89 @@ Multiple sync servers
 
 When a wallet is connected to multiple sync servers, it automatically
 propagates changes it received from one sync server to the others.  Local
-changes made by the wallet are propoagated to all sync servers.  The goal of
+changes made by the wallet are propagated to all sync servers.  The goal of
 this is to make the state of the sync servers converge.
 
 The different sync servers one wallet is enrolled with do not necessarily
 have the same set of other wallet enrolled.  Each sync server has a separate Lamport clock
 and contains a separate CRDT.
 
+Backup user flow
+================
+
+.. graphviz::
+
+   digraph G {
+       nodesep=0.5;
+       withdrawal [
+           label = "First\nWithdrawal";
+           shape = oval;
+       ];
+       has_backup [
+           label = "Has backup\nconfigured?";
+           shape = diamond;
+       ];
+       app_settings [
+           label = "App\nSettings";
+           shape = rect;
+       ];
+       backup_onboarding [
+           label = "Backup\nOnboarding";
+           shape = rect;
+       ];
+       backup_settings [
+           label = "Backup Settings\n\n* time of last backup\n* current service";
+           shape = rect;
+       ];
+       choose_backup_service [
+           label = "Choose\nBackup Service";
+           shape = rect;
+       ];
+       tos_accepted [
+           label = "Current ToS\naccepted?";
+           shape = diamond;
+       ];
+       tos [
+           label = "ToS";
+           shape = rect;
+       ];
+       payment_required [
+           label = "Payment\nrequired?";
+           shape = diamond;
+       ];
+       payment_confirmation [
+           label = "Payment\nConfirmation";
+           shape = rect;
+       ];
+       backup_secret [
+           label = "Backup Secret\n\nStore or write down!";
+           shape = rect;
+       ];
+
+       withdrawal -> has_backup;
+       has_backup -> backup_onboarding [label="No"];
+       backup_onboarding -> backup_settings;
+       app_settings -> backup_settings;
+       backup_settings -> backup_settings [label="Disable Backup"];
+       backup_settings:w -> backup_settings:w [label="Sync now"];
+       backup_settings -> choose_backup_service;
+       choose_backup_service -> tos_accepted [label="Select Service"];
+       tos_accepted -> tos [label="No"];
+       tos_accepted -> payment_required [label="Yes"];
+       choose_backup_service:w -> choose_backup_service [label="Remove current service"];
+       choose_backup_service:n -> choose_backup_service:n [headlabel="Add new service", labeldistance=3.5];
+       tos -> payment_required [label="Accept"];
+       payment_required -> payment_confirmation [label="Yes"];
+       payment_confirmation -> backup_secret [label="Paid"];
+       backup_secret -> backup_settings [label="Stored"];
+       payment_required:s -> backup_secret:w [label="No"];
+
+       { rank=same; has_backup; backup_onboarding; }
+       { rank=same; withdrawal; app_settings; }
+       { rank=same; tos_accepted; tos; }
+       { rank=same; payment_required; payment_confirmation; }
+   }
+
 
 References
 ==========
@@ -133,6 +209,9 @@ Discussion / Q&A
   * For privacy reasons, we can't use some interactive sync service.  Thus we
     use the backup blob as a CRDT that also synchronization for us.
 
+* Do we need to handle backup/sync state becoming very large e.g. by many transactions
+  and embedded product images potentially exceeding service quota?
+
 * Do we synchronize the list of other backup enrollments?  How
   do we handle distributing the different private keys for them?
 
@@ -145,16 +224,40 @@ Discussion / Q&A
 * How do we handle a synced wallet that becomes malicious deleting all coins or purchased products?
 
   * This needs to balance the genuine need to permanently delete data.
+
   * Should the sync server allow to fetch previous versions of the sync blob?
+    (If not, how to provide backup functionality?)
+
   * Should the individual wallets keep tombstones (i.e. entities just marked as deleted)
     around for some time, or should they delete and "sanitize" (delete data not needed for the CRDT)
     tombstones as soon as possible?
 
+* How do we make it easy to remove compromised devices from the sync group
+  and prevent them from getting access to future funds and transactions?
+
+  * We need to remove all sync connections on all connected devices
+    and then individually (and manually) add all devices to the new backup account.
+
+  * If we encrypted the key with each wallet's private sync key,
+    we could choose which wallets we want to migrate to the new sync account.
+
+  * Can we then roll-over wallets to the new account automatically
+    or does it have to be manually on each device to prevent an attacker to roll us over?
+
 * How are wallets identified for backup/sync?
 
   * UUID / EdDSA pub and nick name?  When nickname clashes,
     some number is added based on lexical sort of the random id ("phone#1", "phone#2").
 
+* How do we explain users that it can take days for wallet state to synchronize to all devices?
+
+* How are people supposed to securely store their backup account key(s)?
+
+  * There can be an option to print/export the QR code
+  * They can manually write down the taler:// Uri containing the key.
+  * Maybe encode the key in a different format such as
+    `BIP39 <https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki>`__?
+
 * Do we have a passphrase for our backup account key(s)?
 
   * ???
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 7624e9a6..7c11c2c9 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -168,7 +168,7 @@ Bank Account Management
        uuid: string;
      }
 
-.. http:post:: {nexusBase}/bank-accounts/{acctid}/transactions/fetch
+.. http:post:: {nexusBase}/bank-accounts/{acctid}/fetch-transactions
 
   Nexus will download bank transactions using the given connection.
 
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 015b8d59..6a970962 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -11,7 +11,27 @@ HTTP API
 
 .. http:post:: /admin/payments
 
-   Adds a new payment to the book.
+   Adds a new payment to the book.  Mainly used for testing
+   purposes.
+
+   **Request:**
+
+    .. ts:def:: PaymentRequest
+
+     interface PaymentRequest {
+       
+       // IBAN that will reveice the payment.
+       creditorIban: string;
+
+       // IBAN that will send the payment.
+       debitorIban: string;
+
+       // amount in the CURRENCY:X.Y form.
+       amount: string;
+
+       // subject of the payment.
+       subject: string;
+     }
 
 ..
   Host management.
@@ -20,26 +40,121 @@ HTTP API
    
    Creates a new Ebics host.
 
+   **Request:**
+
+    .. ts:def:: EbicsHostRequest
+
+     interface EbicsHostRequest {
+       
+       // Ebics version.
+       hostID: string;
+
+       // Name of the host.
+       ebicsVersion: string;
+     }
+       
+
 .. http:get:: /admin/ebics/hosts
    
    Shows the list of all the hosts existing
    in the system.
 
+   **Response:**
+
+    .. ts:def:: EbicsHostResponse
+
+     interface EbicsHostResponse {
+       
+       // shows the host IDs that are active in the system.
+       // The Ebics version *is* missing, but it's still available
+       // via the HEV message.
+       ebicsHosts: string[];
+     }
+    
+
 ..
   Subscriber management.
 
 .. http:post:: /admin/ebics/subscribers
 
-   Creates a new subscriber.
+   Creates a new Ebics subscriber.
+
+   **Request:**
+
+   .. ts:def:: SubscriberRequest
+
+     interface SubscriberRequest {
+       
+       // hostID
+       hostID: string;
+
+       // userID
+       userID: string;
+
+       // partnerID
+       partnerID: string;
+
+       // systemID
+       systemID: string;
+
+     }
+       
 
 .. http:get:: /admin/ebics/subscribers
 
    Shows the list of all the subscribers existing
    in the system.
 
+   **Response:**
+
+    .. ts:def:: SubscribersResponse
+
+     interface SubscribersResponse {
+       
+       subscribers: Subscriber[]
+     }
+ 
+    .. ts:def:: Subscriber
+
+      interface Subscriber {
+        
+        // userID
+        userID: string;
+
+        // partnerID
+        partnerID: string;
+
+        // hostID
+        hostID: string;
+
+      }
+
 .. http:post:: /admin/ebics/bank-accounts
 
-   Associates a new bank account to an existing subscriber.
+  Associates a new bank account to an existing subscriber.
+
+  **Request:**
+
+    .. ts:def:: BankAccountRequest
+
+     interface BankAccountRequest {
+
+       // Ebics subscriber
+       subscriber: string;
+
+       // IBAN
+       iban: string;
+
+       // BIC
+       bic: string;
+
+       // human name
+       name: string;
+
+       // bank account label
+       label: string;
+
+     }
 
 ..
   Main EBICS service.