diff options
Diffstat (limited to 'libeufin/concepts.rst')
| -rw-r--r-- | libeufin/concepts.rst | 164 |
1 files changed, 0 insertions, 164 deletions
diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst deleted file mode 100644 index a0f2bb7b..00000000 --- a/libeufin/concepts.rst +++ /dev/null @@ -1,164 +0,0 @@ -################### -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. -This is the `HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_ method. -(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" (see definition below) - -Examples: - -.. code-block:: console - - # Download latest transactions via the default bank connection and store them locally - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-accounts/my-acct/fetch-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-block:: console - - # Manually request the inter-day account report via the EBICS C52 order - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-connections/my-ebics-testacct/ebics/download/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. - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-connection/my-ebics-testacct/fetch-accounts - -Facades -------- - -Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts -and bank connections. A *facade* stores 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 facade -* 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 transactions that do -not conform to a certain format. - -Examples: - -.. code-block:: console - - # Request the Taler-specific history through the facade - $ http -a $USER:$PASSWORD \ - https://example1.libeufin.tech/facades/my-taler-wire-gw/taler/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. |