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