From 0c0defcf958cf42c67fe34c2c8f75c86c0a74650 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Fri, 1 May 2020 23:12:50 +0530 Subject: LibEuFin conceptual overview --- libeufin/concepts.rst | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 libeufin/concepts.rst (limited to 'libeufin/concepts.rst') 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. + -- cgit v1.2.3