summaryrefslogtreecommitdiff
path: root/libeufin/concepts.rst
blob: a0f2bb7b5e49a00318c7784f08f645d93ebb5258 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
###################
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.