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

2 files changed, 216 insertions, 108 deletions

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 681811aa..7624e9a6 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -16,7 +16,7 @@ be supported in the future.
 Users Management
 ----------------
 
-.. http:get:: <nexus>/user
+.. http:get:: {nexusBase}/user
 
   Get information about the current user (based on the authentication information
   in this request).
@@ -34,9 +34,9 @@ Users Management
        superuser: boolean;
      }
 
-.. http:post:: <nexus>/users
+.. http:post:: {nexusBase}/users
 
-  Create a new user.  Only the super-user can call this API.
+  Create a new user.  Only a superuser can call this API.
 
   **Request:**
 
@@ -59,10 +59,15 @@ Users Management
        password: string;
      }
 
+
+.. http:get:: {nexusBase}/users
+
+  Return list of users.
+
 Bank Account Management
 -----------------------
 
-.. http:get:: <nexus>/bank-accounts
+.. http:get:: {nexusBase}/bank-accounts
   
   **Response:**
 
@@ -82,43 +87,15 @@ Bank Account Management
        holder: string;
      }
 
-.. http:post:: <nexus>/bank-accounts/prepared-payments/submit
+.. http:post:: {nexusBase}/bank-accounts/{acctid}/prepared-payments/{pmtid}/submit
 
   Ask nexus to submit one prepare payment at the bank.
 
-  **Request:**
-
-  .. ts:def:: SubmitPayment
-
-     interface SubmitPayment {
-       // Unique identifier of the (previously) prepared payment
-       // to submit at the bank.
-       uuid: string;
-
-       // Specify the bank transport to use for the submission.
-       transport?: Transport;
-     }
-
-    
-  .. ts:def:: Transport
-
-     interface Transport {
-
-       // Transport type: 'ebics', 'local', 'fints' (forthcoming).
-       // It must match one of the types actually implemented by
-       // nexus.
-       type: string;
-
-       // A mnemonic identifier given by the user to one particular
-       // transport instance.
-       name: string;
-     }
-
   :status 404 Not Found: the unique identifier **or**
-    the bank transport could not be found in the system
+    the bank connection could not be found in the system
 
 
-.. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payments/$uuid
+.. http:get:: {nexus}/bank-accounts/{my-acct}/prepared-payments/{uuid}
    
    Ask the status of payment ``$uuid``.
 
@@ -156,7 +133,7 @@ Bank Account Management
         preparationDate: string;
       }
 
-.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments
+.. http:post:: {nexusBase}/bank-accounts/{my-acct}/prepared-payments
   
   Ask nexus to prepare instructions for a new payment.
   Note that ``my-acct`` is the bank account that will be
@@ -191,18 +168,18 @@ Bank Account Management
        uuid: string;
      }
 
-.. http:post:: <nexus>/bank-accounts/collected-transactions
+.. http:post:: {nexusBase}/bank-accounts/{acctid}/transactions/fetch
 
-  Nexus will download bank transactions from the given transport.
+  Nexus will download bank transactions using the given connection.
 
   **Request:**
 
   .. ts:def:: CollectedTransaction
 
      interface CollectedTransaction {
-       // Optional field to specify the bank transport to
+       // Optional field to specify the bank connection to
        // use for such operation.
-       bankTransport?: Transport;
+       bankConnection?: string;
        // dashed date (YYYY-MM-DD) of the earliest payment
        // in the result. Optional, defaults to "earliest
        // possible" date.
@@ -213,7 +190,7 @@ Bank Account Management
        end: string;
      }
 
-.. http:get:: <nexus>/bank-accounts/<my-acct>/collected-transactions
+.. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions
 
   Shows which transactions are stored locally at nexus.
 
@@ -254,57 +231,58 @@ Bank Account Management
        subject: string;
      }
 
-Bank Transports
----------------
 
-Bank transports connect the local LibEuFin bank account
+Bank Connections
+----------------
+
+Bank connections connect the local LibEuFin bank account
 to the real bank.
 
-.. http:post:: <nexus>/bank-transports
+.. http:post:: <nexus>/bank-connections
   
-  Activate a new bank transport for the requesting user.
+  Activate a new bank connection for the requesting user.
 
   **Request:**
 
-  .. ts:def:: BankTransport
+  .. ts:def:: BankConnectionRestoreRequest
 
-     interface BankTransport {
+     interface BankConnectionRestoreRequest {
 
-       transport: Transport;
+       name: string;
 
-       // Restore a previous transport.  Take precedence
+       // Restore a previous connection.  Take precedence
        // over the 'new' field.
-       backup?: TransportBackup;
+       backup?: BankConnectionBackup;
        
-       // Data to create a fresh bank transport without
+       // Data to create a fresh bank connection without
        // restoring any backup.
-       data?: TransportNew;
+       data?: BankConnectionNew;
      }
 
 
-  .. ts:def:: TransportNew
+  .. ts:def:: ConnectionNew
 
-     interface TransportNew {
+     interface ConnectionNew {
 
        // This type is strictly dependent on
-       // the transport being created.  For Ebics,
+       // the connection being created.  For Ebics,
        // it will contain the required fields (as strings):
        // 'ebicsURL', 'userID', 'partnerID', 'hostID', and
        // the optional 'systemID'.
   
-       // Other transport types, like 'local' (used for testing
+       // Other connection types, like 'local' (used for testing
        // purposes skipping any interaction with the bank service)
        // and 'fints' are all work in progress!
 
      }
 
 
-  .. ts:def:: TransportBackup
+  .. ts:def:: BankConnectionBackup
      
-     interface TransportBackup {
+     interface BankConnectionBackup {
 
        // The information needed in this type depend entirely
-       // on which transport is being restored.
+       // on which connectionis being restored.
 
      }
 
@@ -313,30 +291,160 @@ to the real bank.
   :status 409 Conflict: The ``name`` field exists already for
     the requesting user.
 
-.. http:post:: <nexus>/bank-transports/sendMSG.
-  
-  Perform the ``MSG`` operation offered by ``transport-name``
-  **without** affecting the nexus database.
 
-  **Request:**
-  
-  A `Transport` object.
+.. http:get:: {nexusBase}/bank-connections
 
-  **Response:**
+   List available bank connections.
 
-  :status 404 Not Found: ``transport-name`` doesn't exist for
-    the requesting user.
 
-.. http:post:: <nexus>/bank-transports/<transport-name>/syncMSG.
+.. http:get:: {nexusBase}/bank-connections/{connid}
+
+   Get information about one bank connection.
+
+   .. ts:def:: BankConnectionInfo
+      
+      interface BankConnectionInfo {
+         name: string;
+
+         connectionType: string;
+
+         ready: boolean;
+
+         // Did the user review the bank's keys?
+         bankKeysReviewed: boolean;
+      }
+
+
+.. http:post:: {nexusBase}/bank-connections/{connid}/connect
+
+   Initialize the connection by talking to the bank.
+
+.. http:post:: {nexusBase}/bank-connections/{connid}/export-backup
+
+   Make a passphrase-encrypted backup of this connection.
+
+.. http:post:: {nexusBase}/bank-connections/{connid}/accounts/fetch
+
+   Update accounts that are accessible via this bank connection.
+
+.. http:get:: {nexusBase}/bank-connections/{connid}/accounts
+
+   list accounts that are accessible via this bank connection and what
+   LibEuFin accounts they are connected to.
+
+
+Facades
+-------
+
+.. http:get:: <nexus>/facades
+
+  List available facades.  
+
+.. http:get:: {nexus}/facade/${fcid}
+
+  Get details about a facade.
+
+  .. ts:def:: FacadeInfo
+     
+     interface FacadeInfo {
+        // Name of the facade, same as the "fcid" parameter.
+        name: string;
+
+        // Type of the facade.
+        // For example, "taler-wire-gateway".
+        type: string;
+
+        // Name of the user that created the facade.
+        // Whenever the facade accesses a resource it is allowed to
+        // access, the creator must *also* have access to that resource.
+        creator: string;
+
+        // Bank accounts that the facade has read/write
+        // access to.
+        bankAccountsRead: string[];
+        bankAccountsWrite: string[];
+
+        // Bank connections that the facade has read/write
+        // access to.
+        bankConnectionsRead: string[];
+        bankConnectionsWrite: string[];
+
+        // Facade-specific configuration details.
+        config: any;
+     }
+
+
+Bank Connection Protocols
+-------------------------
+
+.. http:get:: {nexus}/bank-connection-protocols
+
+   List supported bank connection protocols.
+
+.. http:post:: {nexus}/bank-connection-protocols/ebics/test-host
+
+   Check if the nexus can talk to an EBICS host.
+   This doesn't create a new connection in the database,
+   and is useful during setup when the user hasn't entered
+   the full details for the connection yet.
+
+   .. ts:def:: EbicsHostTestRequest
+      
+      interface EbicsHostTestRequest {
+        ebicsBaseUrl: string;
+        ebicsHostId: string;
+      }
+
+
+EBICS-specific APIs
+-------------------
+
+The following endpoints are only available for EBICS bank connections.
+They are namespaced under the ``/ebics/`` sub-resource.
+
+.. http:post:: {nexusBase}/bank-connections/{connection-name}/ebics/download/{msg}
+
+  .. warning::
+
+    Use with care.  Typically only necessary for testing and debugging.
+
+  Perform an EBICS download transaction of type ``msg``.
+  This request will not affect any bank account or other state
+  in the nexus database.  It will just make a request to the bank
+  and return the answer.
+
+.. http:post:: {nexusBase}/bank-connections/{connection-name}/ebics/upload/{msg}
+
+  .. warning::
+
+    Use with care.  Typically only necessary for testing and debugging.
   
-  Some transports **do** have operations that aren't semantically
-  related to a bank account but need to be stored locally at the nexus.
-  One typical example is the downloading of the bank's keys vie the
-  EBICS transport.  This API lets the user perform the ``MSG``
-  operation that should result in new data being stored locally
-  at the nexus.
+  Perform an EBICS upload transaction of type ``msg``.
+  This request will not affect any bank account or other state
+  in the nexus database.  It will just make a request to the bank
+  and return the answer.
 
-  **Response:**
 
-  :status 404 Not Found: ``transport-name`` doesn't exist for
-    the requesting user.
+The taler-wire-gateway facade
+-----------------------------
+
+The ``taler-wire-gateway`` facade has the following configuration:
+
+
+.. ts:def:: TalerWireGatewayFacadeConfig
+   
+   interface TalerWireGatewayFacadeConfig {
+     // Bank account and connection that is
+     // abstracted over.
+     bankAccount: string;
+     bankConnection: string;
+
+     // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT)
+     // for incoming transfers.
+     reserveTransferLevel: "statement" | "report" | "notification";
+
+     // Time between incremental requests
+     intervalIncremental: string;
+
+     // FIXME:  maybe more scheduling parameters?
+   }
diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst
index 00afe9a6..da48d7f8 100644
--- a/libeufin/concepts.rst
+++ b/libeufin/concepts.rst
@@ -57,42 +57,42 @@ The information stored about it includes:
   with their state (sent or not sent, acknowledged in bank statement or not).
 * Error reports (e.g. failed payment requests, bank statement items that were not understood
   by LibEuFin)
-* A default bank transport (if configured) that is used by default
+* A default bank connection (if configured) that is used by default
   for operations on the account
-* Other connected bank transports
+* Other enabled bank connections
 
 Examples:
 
 .. code:: none
 
-  # Download latest transactions via the default bank transport and store them locally
+  # Download latest transactions via the default bank connection and store them locally
   curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-accounts/my-acct/collect-transactions
 
-Bank Transports
----------------
+Bank Connections
+----------------
 
-Bank transports connect the local LibEuFin bank account to the real bank.
-The bank transport includes the following data:
+Bank connections connect the local LibEuFin bank account to the real bank.
+The bank connection includes the following data:
 
-* Local alias ("nickname") of the bank transport
-* the type of transport (EBICS, FinTS, loopback, sandbox)
-* credentials to use the transport (e.g. password, EBICS subscriber keys)
+* Local alias ("nickname") of the bank connection
+* the type of connection, i.e. the protocol used (EBICS, FinTS, loopback, sandbox)
 * protocol configuration (hostname, port, protocol sub-version/flags)
+* credentials to use the connection (e.g. password, EBICS subscriber keys)
 
-Bank transports provide the following actions:
+Bank connections provide the following actions:
 
-* Initial setup of the transport
+* Initial setup of the connection
 
 * Execute protocol-specific actions (e.g. EBICS: C53, C52, CCT, CRZ)
 
   * These actions do not have any effect on the LibEuFin local bank account.
     To persist changes to the local bank account (transaction history, payment request status),
-    the bank transport must be invoked via the bank account.
+    the bank connection must be invoked via the bank account.
 
 * Import bank accounts
 
-  * Some bank transport protocols allow LibEuFin to query a list of bank
-    accounts that the transport has access to.  This makes setup easier,
+  * Some bank connection protocols allow LibEuFin to query a list of bank
+    accounts that the connection has access to.  This makes setup easier,
     as the user doesn't have to create the local bank account manually.
 
 Examples:
@@ -100,22 +100,22 @@ Examples:
 .. code:: none
 
   # Manually request the inter-day account report via the EBICS C52 order
-  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-transports/my-ebics-testacct/send-c52
+  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connections/my-ebics-testacct/send-c52
 
-  # Download available bank accounts that can be accessed through this transport,
+  # Download available bank accounts that can be accessed through this connection,
   # according to the bank server (with EBICS, does a HTD request).
   # For each of them, create a bank account resource in LibEuFin.
-  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-transports/my-ebics-testacct/import-accounts
+  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connection/my-ebics-testacct/import-accounts
 
 Facades
 -------
 
 Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts
-and bank transports.  Facades store the following information:
+and bank connections.  Facades store the following information:
 
 * Local name of the facade
 * Facade type and options specific to the type
-* Associated bank accounts and bank transports that can be accessed by the layer
+* Associated bank accounts and bank connections that can be accessed by the layer
 * Internal tables used by the facade (i.e. facades are stateful)
 
 The only facade currently supported by LibEuFin is the "Taler Wire Gateway API" layer.
@@ -135,7 +135,7 @@ Access Control
 
 The goal of access control in LibEuFin is to allow the following scenarios:
 
-* The Nexus can be used by multiple clients for different bank accounts/transports,
+* The Nexus can be used by multiple clients for different bank accounts/connections
   and these users can't access each other's bank accounts
 * For monitoring / dashboard (e.g. Taler rejected transactions, blacklists),
   some users should only be able to have read-only access.
@@ -146,15 +146,15 @@ spending limits or more fine-grained read/write permissions.
 Users can be normal users or superusers.  Permission checks do not apply to superusers,
 and only superusers can create other users.
 
-Each top-level object (bank account, bank transport, layer) has a list of
+Each top-level object (bank account, bank connection, facade) has a list of
 nexus users with write access, and a list of users with read access.
 
-When using a bank transport through a bank account, permission checks must
-succeed for both the bank account and the bank transport.
+When using a bank connection through a bank account, permission checks must
+succeed for both the bank account and the bank connection
 
-This works differently for layers:  A layer has a set of associated bank transports
+This works differently for facades:  A facade has a set of associated bank connections
 and bank accounts it can access.  Permissions on these associated objects
-are checked when the layer is *created*.  When invoking operations on the layer,
-the nexus only checks if the current nexus user can access the layer and *not* the
-underlying objects abstracted by the layer.
+are checked when the facade is *created*.  When invoking operations on the facade,
+the nexus only checks if the current nexus user can access the facade and *not* the
+underlying objects abstracted by the facade.