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).
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.
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
* A default bank connection (if configured) that is used by default
for operations on the account
* Other enabled "bank connections" (see definition below)
.. code-block:: console
# Download latest transactions via the default bank connection and store them locally
curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-accounts/my-acct/fetch-transactions
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.
.. code-block:: console
# Manually request the inter-day account report via the EBICS C52 order
curl -XPOST $AUTHEADER 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.
curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connection/my-ebics-testacct/fetch-accounts
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 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.
.. code-block:: console
# Request the Taler-specific history through the facade
curl $AUTHEADER https://example1.libeufin.tech/facades/my-taler-wire-gw/taler/history/incoming
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.