summaryrefslogtreecommitdiff
path: root/libeufin/concepts.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2020-05-01 23:12:50 +0530
committerFlorian Dold <florian.dold@gmail.com>2020-05-01 23:13:02 +0530
commit0c0defcf958cf42c67fe34c2c8f75c86c0a74650 (patch)
tree80575f45ca56d944d3a13683a9e923f5a2ce81e3 /libeufin/concepts.rst
parent85efbc75fb302299b8c249be9a38b7f5ead3a407 (diff)
downloaddocs-0c0defcf958cf42c67fe34c2c8f75c86c0a74650.tar.gz
docs-0c0defcf958cf42c67fe34c2c8f75c86c0a74650.tar.bz2
docs-0c0defcf958cf42c67fe34c2c8f75c86c0a74650.zip
LibEuFin conceptual overview
Diffstat (limited to 'libeufin/concepts.rst')
-rw-r--r--libeufin/concepts.rst158
1 files changed, 158 insertions, 0 deletions
diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst
new file mode 100644
index 00000000..0825a8c8
--- /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.
+