diff options
Diffstat (limited to 'libeufin/concepts.rst')
-rw-r--r-- | libeufin/concepts.rst | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst new file mode 100644 index 00000000..da48d7f8 --- /dev/null +++ b/libeufin/concepts.rst @@ -0,0 +1,160 @@ +################### +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 requests into interactions + with other banking APIs, abstracting away different underlying protocols 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 user has a login name and a (salted, hashed) password. (Other authentication +methods could be added in the future.) + +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 connection (if configured) that is used by default + for operations on the account +* Other enabled bank connections + +Examples: + +.. code:: none + + # 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 Connections +---------------- + +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 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 connections provide the following actions: + +* 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 connection must be invoked via the bank account. + +* Import bank accounts + + * 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: + +.. code:: none + + # Manually request the inter-day account report via the EBICS C52 order + curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connections/my-ebics-testacct/send-c52 + + # 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-connection/my-ebics-testacct/import-accounts + +Facades +------- + +Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts +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 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. +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 facade + curl $AUTHEADER https://example1.libeufin.tech/facades/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/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. + +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 connection, facade) has a list of +nexus users with write access, and a list of users with read access. + +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 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 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. + |