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
|
XX 38: Demobanks protocol suppliers
###################################
Summary
=======
This document models the association between financial data
held in a LibEuFin *demobank* and the interface to let users
access such financial data.
Motivation
==========
LibEuFin Sandbox offers multitenency banking by the means of
'demobanks'. Each demobank offers access to financial data via
*several* APIs. The objective is to model such APIs so that each
operation impacts one and only one demobank.
Definitions
===========
Each API to access financial data at one demobank is offered by
a **resource** called *protocol supplier*. Therefore protocol
suppliers MAY be subject to all the CRUD operations
For each request that a protocol supplier serves, the demobank
being impacted can be found in the following ways:
.. _demobank-mutually-exclusive:
1. In a value that belongs to the request.
2. In a value that belongs to the protocol supplier's state.
3. Relying on the default demobank.
Note: the three elements are mutually exclusive, so as to reduce
ambiguity and simplify the implementation.
Suppliers creation
==================
Suppliers can be static or dynamic.
Static
^^^^^^
This supplier never changes its state. Whether this type
of supplier is associated or not with a particular demobank
MUST be stated in the documentation.
Examples
--------
1. A JSON-based protocol that lets users access their bank accounts
always under the 'default' demobank belongs to this category. It
is therefore a 'static protocol supplier' with static demobank.
2. A XML-based protocol that lets users access their bank accounts
in a demobank whose name appear in the URI is as well a 'static protocol
supplier' with dynamic demobank.
Note: the upcoming (in version 0.9.3) JSON-based supplier that will
let Nexus reach Sandbox accounts is planned as a 'dynamic protocol
supplier' with dynamic demobank. That allows Taler demos to only
speak JSON.
Dynamic
^^^^^^^
This supplier has a name and its state CAN refer to one
particular demobank. These suppliers need to be created
first, in order to be used.
Examples
--------
1. A JSON-based protocol that lets users access their bank
accounts under the demobank whose name is held in the supplier
state belongs to this category. It is therefore a dynamic
supplier with semi-dynamic demobank.
2. A XML-based protocol that lets user access their bank
accounts under the demobank whose name is held both in the
supplier state *and* in the URI is **wrong**. This supplier
doesn't respect this `mutual exclusivity <demobank-mutually-exclusive_>`_.
3. A XML-based protocol that lets user access their bank accounts
always under the 'default' demobank belongs to this category. It
is a dynamic supplier with static demobank.
Supplier reachability
=====================
Each supplier must be available under its own URI.
Current protocol suppliers design
=================================
Static X-LIBEUFIN-BANK with dynamic demobank
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``x-libeufin-bank`` protocol supplier is reachable under
``/demobanks/{demobankName}/access-api/``. As the path suggests,
it offers banking operations via the :doc:`Core Bank API </core/api-corebank>`.
It is static in the sense that it's not possible to assign a name
to one particular x-libeufin-bank protocol supplier. On the other
hand, the demobank is dynamic because can be specified along the path
in the ``demobankName`` placeholder.
Dynamic EBICS supplier with dynamic demobank
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Every protocol supplier of this type is reachable under ``POST /ebicsweb``
and by specifying its EBICS host name inside the EBICS message.
As of the internal representation, Sandbox keeps a database table called
``EbicsHostsTable`` that does **not** point at any demobank. Such table
is the one that provides the bank's EBICS private keys and has **no** business
implications.
CCT (Payment initiations)
-------------------------
This handler gets the bank account directly from the IBAN that was
carried along the pain.001, therefore -- as long as every IBAN is
unique -- this works with **any** demobank that hosts such IBAN. The
EBICS subscriber public keys are extracted differently: they come from
the tuple [userID, partnerID, systemID?] held in the request. Hence as
long as such tuple is unique for each subscriber (Sandbox checks that),
even the subscriber public keys are found regardless of the demobank name.
.. note::
The 'context' object found via the [userID, partnerID, systemID?] tuple
has **also** a reference to the bank account. The consistency with the
other bank account reference returned by the IBAN is currently NOT checked.
C52 (transactions report)
-------------------------
This handler gets the reference to the subscriber public keys and bank
account via the [userID, partnerID, systemID?] tuple. It then uses
this bank account label to find the transactions that belong to the
subscriber that made the request.
.. note::
The current implementation does NOT uses any demobank name along
the transactions research: only the bank account label. This can
lead to **ambiguity**, in case two different demobanks host respectively
one bank account under the same label. This is not possible however
in the current version, as Sandbox only admits one ``default`` demobank.
Alternatives
============
Drop support for multitenancy banking. What is the benefit of this anyway?
|
