038-demobanks-protocol-suppliers.rst (5957B)
1 DD 38: Demobanks protocol suppliers 2 ################################### 3 4 :Design status: Abandoned 5 :Implementation status: Not started 6 :DD shepherd: TBD 7 :Historical contributors: Marcello Stanisci, Özgür Kesim, Florian Dold, Christian Grothoff 8 :First published: 2023-03-15 9 :Last substantive change: 2023-03-21 10 11 .. warning:: 12 13 This is an abandoned historical design. The terminology and LibEuFin 14 Sandbox architecture described below are not normative for current 15 implementations. 16 17 Summary 18 ======= 19 20 This document models the association between financial data 21 held in a LibEuFin *demobank* and the interface to let users 22 access such financial data. 23 24 Motivation 25 ========== 26 27 LibEuFin Sandbox offers multitenency banking by the means of 28 'demobanks'. Each demobank offers access to financial data via 29 *several* APIs. The objective is to model such APIs so that each 30 operation impacts one and only one demobank. 31 32 Definitions 33 =========== 34 35 Each API to access financial data at one demobank is offered by 36 a **resource** called *protocol supplier*. Therefore protocol 37 suppliers MAY be subject to all the CRUD operations 38 39 For each request that a protocol supplier serves, the demobank 40 being impacted can be found in the following ways: 41 42 .. _demobank-mutually-exclusive: 43 44 1. In a value that belongs to the request. 45 2. In a value that belongs to the protocol supplier's state. 46 3. Relying on the default demobank. 47 48 Note: the three elements are mutually exclusive, so as to reduce 49 ambiguity and simplify the implementation. 50 51 Suppliers creation 52 ================== 53 54 Suppliers can be static or dynamic. 55 56 Static 57 ^^^^^^ 58 59 This supplier never changes its state. Whether this type 60 of supplier is associated or not with a particular demobank 61 MUST be stated in the documentation. 62 63 Examples 64 -------- 65 66 1. A JSON-based protocol that lets users access their bank accounts 67 always under the 'default' demobank belongs to this category. It 68 is therefore a 'static protocol supplier' with static demobank. 69 70 2. A XML-based protocol that lets users access their bank accounts 71 in a demobank whose name appear in the URI is as well a 'static protocol 72 supplier' with dynamic demobank. 73 74 Historical note: the JSON-based supplier that was planned for version 0.9.3 75 let Nexus reach Sandbox accounts is planned as a 'dynamic protocol 76 supplier' with dynamic demobank. That allows Taler demos to only 77 speak JSON. 78 79 Dynamic 80 ^^^^^^^ 81 82 This supplier has a name and its state CAN refer to one 83 particular demobank. These suppliers need to be created 84 first, in order to be used. 85 86 Examples 87 -------- 88 89 1. A JSON-based protocol that lets users access their bank 90 accounts under the demobank whose name is held in the supplier 91 state belongs to this category. It is therefore a dynamic 92 supplier with semi-dynamic demobank. 93 94 2. A XML-based protocol that lets user access their bank 95 accounts under the demobank whose name is held both in the 96 supplier state *and* in the URI is **wrong**. This supplier 97 doesn't respect this :ref:`mutual exclusivity <demobank-mutually-exclusive>`. 98 99 3. A XML-based protocol that lets user access their bank accounts 100 always under the 'default' demobank belongs to this category. It 101 is a dynamic supplier with static demobank. 102 103 Supplier reachability 104 ===================== 105 106 Each supplier must be available under its own URI. 107 108 109 Current protocol suppliers design 110 ================================= 111 112 Static X-LIBEUFIN-BANK with dynamic demobank 113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 114 115 The ``x-libeufin-bank`` protocol supplier is reachable under 116 ``/demobanks/{demobankName}/access-api/``. As the path suggests, 117 it offers banking operations via the :doc:`Core Bank API </core/api-corebank>`. 118 It is static in the sense that it's not possible to assign a name 119 to one particular x-libeufin-bank protocol supplier. On the other 120 hand, the demobank is dynamic because can be specified along the path 121 in the ``demobankName`` placeholder. 122 123 Dynamic EBICS supplier with dynamic demobank 124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 125 126 Every protocol supplier of this type is reachable under ``POST /ebicsweb`` 127 and by specifying its EBICS host name inside the EBICS message. 128 129 As of the internal representation, Sandbox keeps a database table called 130 ``EbicsHostsTable`` that does **not** point at any demobank. Such table 131 is the one that provides the bank's EBICS private keys and has **no** business 132 implications. 133 134 CCT (Payment initiations) 135 ------------------------- 136 137 This handler gets the bank account directly from the IBAN that was 138 carried along the pain.001, therefore -- as long as every IBAN is 139 unique -- this works with **any** demobank that hosts such IBAN. The 140 EBICS subscriber public keys are extracted differently: they come from 141 the tuple [userID, partnerID, systemID?] held in the request. Hence as 142 long as such tuple is unique for each subscriber (Sandbox checks that), 143 even the subscriber public keys are found regardless of the demobank name. 144 145 .. note:: 146 147 The 'context' object found via the [userID, partnerID, systemID?] tuple 148 has **also** a reference to the bank account. The consistency with the 149 other bank account reference returned by the IBAN is currently NOT checked. 150 151 C52 (transactions report) 152 ------------------------- 153 154 This handler gets the reference to the subscriber public keys and bank 155 account via the [userID, partnerID, systemID?] tuple. It then uses 156 this bank account label to find the transactions that belong to the 157 subscriber that made the request. 158 159 .. note:: 160 161 The current implementation does NOT uses any demobank name along 162 the transactions research: only the bank account label. This can 163 lead to **ambiguity**, in case two different demobanks host respectively 164 one bank account under the same label. This is not possible however 165 in the current version, as Sandbox only admits one ``default`` demobank. 166 167 168 Alternatives 169 ============ 170 171 Drop support for multitenancy banking. What is the benefit of this anyway?