14.1. Conceptual Overview

14.1.1. 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).

14.1.2. 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:

# 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:

# 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:

# Request the Taler-specific history through the facade
curl $AUTHEADER https://example1.libeufin.tech/facades/my-taler-wire-gw/api/history/incoming

14.1.3. 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.