[taler-docs] branch master updated: LibEuFin conceptual overview

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 0c0defc  LibEuFin conceptual overview
0c0defc is described below

commit 0c0defcf958cf42c67fe34c2c8f75c86c0a74650
Author: Florian Dold <address@hidden>
AuthorDate: Fri May 1 23:12:50 2020 +0530

    LibEuFin conceptual overview
---
 libeufin/concepts.rst | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++
 libeufin/index.rst    |   1 +
 2 files changed, 159 insertions(+)

diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst
new file mode 100644
index 0000000..0825a8c
--- /dev/null
+++ b/libeufin/concepts.rst
@@ -0,0 +1,158 @@
+###################
+Conceptual Overview
+###################
+
+
+What is LibEuFin
+================
+
+The goal of LibEuFin is to make the development and testing of
+FinTech applications easier.  It hides implementation details
+of complex legacy banking APIs behind a simple interface.
+
+LibEuFin Nexus and Sandbox
+--------------------------
+
+LibEuFin has two main components:
+
+1. The LibEuFin nexus receives banking-related requests in a LibEuFin-specific
+   format via an HTTP API.  It then translates those request into interactions
+   with other banking APIs, abstracting away different underlying protocol and
+   hiding the complexity of the legacy protocols used by some banks.
+   
+2. The LibEuFin sandbox implements the server side of protocols
+   that banks speak.  It also emulates a *very*, *very* simple
+   core banking system to manage accounts and their balance.
+   The main use case for the sandbox is testing LibEuFin itself,
+   as well as applications developed with LibEuFin.
+   The sandbox has a JSON API to set it up for tests (creating bank
+   hosts, bank accounts, fake transactions).
+
+
+High-Level Concepts
+===================
+
+Nexus Users
+-----------
+
+The concept of a *nexus user* is used to implement access control to the
+operations that the nexus provides.
+
+A nexus user can be marked as *superuser*.  All permission checks
+are skipped for superusers.
+
+Only superusers are allowed to create/modify other users.
+
+Bank Accounts
+-------------
+
+A bank account is the local representation of some bank account.
+The information stored about it includes:
+
+* Local alias ("nickname") of the bank account
+* Account identification (IBAN / BIC / account holder)
+* A local mirror of the bank transaction history
+* Payment requests, i.e. payments that have been locally requested, together
+  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
+  for operations on the account
+* Other connected bank transports
+
+Examples:
+
+.. code:: none
+
+  # Download latest transactions via the default bank transport and store them 
locally
+  curl -XPOST $AUTHEADER 
https://example1.libeufin.tech/bank-accounts/my-acct/collect-transactions
+
+Bank Transports
+---------------
+
+Bank transports connect the local LibEuFin bank account to the real bank.
+The bank transport 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)
+* protocol configuration (hostname, port, protocol sub-version/flags)
+
+Bank transports provide the following actions:
+
+* Initial setup of the transport
+
+* Execute protocol-specific actions (e.g. EBICS: C53, C52, CCT, CRZ)
+
+  * These actions to 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.
+
+* 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,
+    as the user doesn't have to create the local bank account manually.
+
+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
+
+  # Download available bank accounts that can be accessed through this 
transport,
+  # according to the bank server (with EBICS, does a HTD request).
+  curl -XPOST $AUTHEADER 
https://example1.libeufin.tech/bank-transports/my-ebics-testacct/query-bank-accounts
+
+Layers
+------
+
+Layers allow extra domain-specific functionality to be implemented on top of 
users, bank accounts
+and bank transports.  Layers store the following information:
+
+* Local name of the layer
+* Layer type and options specific to the type
+* associated bank accounts and bank transports that can be accessed by the 
layer
+* internal tables used by the layer (i.e. layers are stateful)
+
+The only layer currently supported by LibEuFin is the "Taler Wire Gateway API" 
layer.
+It provides a filtered view on the transaction history, a more restricted API 
to create payment
+requests, and a mechanism to create a counter-transaction for incoming 
transaction that do
+not conform to a certain format.
+
+Examples:
+
+.. code:: none
+
+  # Request the Taler-specific history through the layer
+  curl $AUTHEADER 
https://example1.libeufin.tech/layers/my-taler-wire-gw/api/history/incoming
+
+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,
+  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.
+
+It is currently not planned to have more fine-grained permissions, such as
+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
+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
+succees for both the bank account and the bank transport.
+
+This works differently for layers:  A layer has a set of associated bank 
transports
+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.
+
diff --git a/libeufin/index.rst b/libeufin/index.rst
index 62af14b..9dc6268 100644
--- a/libeufin/index.rst
+++ b/libeufin/index.rst
@@ -6,6 +6,7 @@ LibEuFin is a project providing free software tooling for 
European FinTech.
 .. toctree::
   :glob:
 
+  concepts
   ebics
   architecture
   api-sandbox

-- 
To stop receiving notification emails like this one, please contact
address@hidden.