account-lookup-service 15.6.0-snapshot.4 → 16.1.0-iso.0

package/docs/Proxy/Proxy pattern - Unhappy path.plantuml

@@ -0,0 +1,103 @@
+@startuml
+
+title Proxy Patterns - Unhappy Path 
+
+participant "Payer DFSP" as payerDFSP
+box "Scheme A"
+    participant "ALS\nScheme A" as schemeA
+    participant "Proxy Cache\nScheme A" as pc_A
+end box
+participant "Proxy AB" as xnp
+box "Scheme B"
+    participant "ALS\nScheme B" as schemeB
+    participant "Proxy Cache\nScheme B" as pc_B
+end box
+participant "Payee DFS" as payeeDFSP
+
+autonumber 1 "<b>[0]"
+
+== POST ==
+payerDFSP ->> schemeA: POST/GET/PATCH/PUT /xxx
+note left
+header 
+  source: payerDFSP
+  destination: payeeDFSP
+end note
+alt if OpenAPI Error 
+    schemeA -->> payerDFSP: 400 Bad Request
+end
+
+    alt if error in schemeA
+        schemeA ->> payerDFSP: PUT /xxx/{ID}/error
+note right
+Error Codes: 2xxx, 3xxx, 4xxx, 5xxx        
+end note
+    end
+
+    schemeA -> pc_A: lookup proxy for payeeDFSP = Proxy AB
+    alt if not in proxy cache
+      schemeA ->> payerDFSP: PUT /xxx/{ID}/error
+note right
+Error Code: 3201
+end note
+    end
+    schemeA ->> xnp: POST/GET/PATCH/PUT /xxx
+    
+    alt if error in xnp
+        xnp ->> schemeA: PUT /xxx/{ID}/error
+note right
+header 
+  source: Proxy AB
+  destination: payerDFSP
+JWS Signed by Proxy AB  
+Error Codes: 3100
+end note
+    schemeA -->> xnp: 200 OK
+        schemeA ->> payerDFSP: PUT /xxx/{ID}/error
+    end
+    
+    xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+
+    xnp ->> schemeB: POST/GET/PATCH/PUT /xxx
+    schemeB -->> xnp: 202 OK
+    xnp -->> schemeA: 202 OK
+    
+    alt if error in schemeB
+            schemeB ->> xnp: PUT /xxx/{ID}/error
+note right
+Error Codes: 2xxx, 3xxx, 4xxx, 5xxx        
+end note
+    xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+            xnp ->> schemeA: PUT /xxx/{ID}/error
+    schemeA -->> xnp: 200 OK
+    xnp -->> schemeB: 200 OK
+            schemeA ->> payerDFSP: PUT /xxx/{ID}/error
+    end
+    
+    schemeB ->> payeeDFSP: POST/GET/PATCH/PUT /xxx
+    
+    alt if error in payeeDFSP
+        payeeDFSP->> schemeB: PUT /xxx/{ID}/error
+note right
+header destination: PayerDFSP
+Error Codes: 5xxx
+end note
+            schemeB -> schemeB: Lookup proxy for payerDFSP = Proxy AB
+            schemeB ->> xnp: PUT /xxx/{ID}/error
+    xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+            xnp ->> schemeA: PUT /xxx/{ID}/error
+            schemeA -->> xnp: 200 OK
+            xnp -->> schemeB: 200 OK
+            schemeA ->> payerDFSP: PUT /xxx/{ID}/error
+    end
+
+@enduml

package/docs/Proxy/Readme.md

@@ -0,0 +1,39 @@
+# Proxy Implementation
+The proxy implementation method to connect schemes does the following.
+1. Leverages the trust relationship between scheme so that a transaction only has a single pre-funding requirement at the Payer's scheme.
+2. Ensures non-repudiation across schemes; removing the requirement for the cross-network proxy to take on responsibility for clearing; which removes costs
+
+The schemes are connected via a proxy participant, that is registered to act as a proxy in the scheme for adjacent but connected dfsps in other schemes. 
+Essentially, the two connected schemes behave as if they where a single scheme.
+
+This design make the following assumptions
+1. No two connected participant have the same identifier
+1. No limit checks are done against proxy participants
+1. Get \transaction request are resolved at the payee scheme
+1. Timeouts in non-payee schemes are  disabled (maybe enlarged)
+
+## General Patterns
+There are certain general patterns that emerge
+### Happy Path Patterns
+![Happy Path Patterns](Proxy%20pattern%20-%20happy%20path.png)
+
+### Error Patterns
+![Error Patterns](Proxy%20pattern%20-%20Unhappy%20path.png)
+
+## Detailed Designs
+1. [Discovery - On Demand Implementation](./Discovery.md)
+2. [P2P](./P2P.md)
+
+## Admin API - defining Proxy Participants
+![Admin API](SettingUpProxys.png)
+
+### ALS Proxy Timeout flow
+1. If no party info returned from Oracle (see [diagram](./Discovery.md)), and there's some proxies in the hub, we need to send 
+  GET /parties/... requests to each proxy. And wait for the response.
+2. At this moment we add 2 records in cache (redis) using `inter-scheme-proxy-cache-lib`:
+  - key: `als:${sourceId}:${type}:${partyId}` value: `[proxy_1, proxy_2, ...]` (no TTL)
+  - key: `als:${sourceId}:${type}:${partyId}:expiresAt` value: `expiresAt`  (TTL: default 40 seconds)
+3. When we get success/failure callbacks from all proxies within TTL period, we process it, and remove `...:expiresAt` key from cache.
+4. If not all callbacks received within TTL period, redis will expire `...:expiresAt` key, emit appropriate event, and pass _expired cacheKey_.
+5. We subscribe to these events, and provide a [callback](https://github.com/mojaloop/account-lookup-service/blob/feat/fx-impl/src/domain/timeout/index.js#L53) to be executed in case of timeout.
+6. From _expired cacheKey_, we get `destination`, `partyType` and `partyId`, which is used to send error callback to appropriate participant.

package/docs/Proxy/SettingUpProxys.plantuml

@@ -0,0 +1,31 @@
+@startuml
+title Central Ledger API / Admin API
+
+participant "Onboarding Script" as script
+participant "Mojaloop\nScheme A" as schemeA
+participant "XN Proxy" as xnp
+participant "Mojaloop\nScheme B" as schemeB
+
+autonumber 1 "<b>[0]"
+
+== Create Participant Types ==
+
+script -> schemeA: POST /participants
+note left
+{
+  "name": "XN Proxy",
+  "currency": "USD",
+  <color:#ff0000>"isProxy": true
+}
+end note
+
+script -> schemeB: POST /participants
+note left
+{
+  "name": "XN Proxy",
+  "currency": "USD",
+  <color:#ff0000>"isProxy": true
+}
+end note
+
+@enduml

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "account-lookup-service",
   "description": "Account Lookup Service is used to validate Party and Participant lookups.",
-  "version": "15.6.0-snapshot.4",
+  "version": "16.1.0-iso.0",
   "license": "Apache-2.0",
   "author": "ModusBox",
   "contributors": [
@@ -90,23 +90,23 @@
     "@hapi/hapi": "21.3.12",
     "@hapi/inert": "7.1.0",
     "@hapi/vision": "7.0.3",
-    "@mojaloop/central-services-error-handling": "13.0.2",
+    "@mojaloop/central-services-error-handling": "13.0.3",
     "@mojaloop/central-services-health": "15.0.0",
-    "@mojaloop/central-services-logger": "11.5.1",
-    "@mojaloop/central-services-metrics": "12.1.0",
-    "@mojaloop/central-services-shared": "18.11.2",
-    "@mojaloop/central-services-stream": "11.3.1",
-    "@mojaloop/database-lib": "11.0.6",
-    "@mojaloop/event-sdk": "14.1.1",
-    "@mojaloop/inter-scheme-proxy-cache-lib": "2.3.0",
-    "@mojaloop/ml-schema-transformer-lib": "2.4.1",
-    "@mojaloop/sdk-standard-components": "19.5.1",
+    "@mojaloop/central-services-logger": "11.5.2",
+    "@mojaloop/central-services-metrics": "12.4.3",
+    "@mojaloop/central-services-shared": "18.15.1",
+    "@mojaloop/central-services-stream": "11.4.2",
+    "@mojaloop/database-lib": "11.1.1",
+    "@mojaloop/event-sdk": "14.1.2",
+    "@mojaloop/inter-scheme-proxy-cache-lib": "2.3.1",
+    "@mojaloop/ml-schema-transformer-lib": "2.5.1",
+    "@mojaloop/sdk-standard-components": "19.6.3",
     "@now-ims/hapi-now-auth": "2.1.0",
     "ajv": "8.17.1",
     "ajv-keywords": "5.1.0",
     "blipp": "4.0.2",
-    "commander": "12.1.0",
-    "cron": "3.2.1",
+    "commander": "13.0.0",
+    "cron": "3.5.0",
     "fast-safe-stringify": "^2.1.1",
     "hapi-auth-bearer-token": "8.0.0",
     "joi": "17.13.3",
@@ -118,6 +118,9 @@
     "rc": "1.2.8"
   },
   "overrides": {
+    "postcss": {
+      "nanoid": "^3.3.8"
+    },
     "@mojaloop/central-services-health": {
       "@mojaloop/central-services-logger": ">=11.4.0"
     },
@@ -139,28 +142,40 @@
       "yargs-parser": "13.1.2",
       "markdown-it": "12.3.2"
     },
+    "swagger2openapi": {
+      "yaml": "2.7.0"
+    },
+    "oas-validator": {
+      "yaml": "2.7.0"
+    },
+    "oas-linter": {
+      "yaml": "2.7.0"
+    },
+    "cross-spawn": "7.0.6",
     "yargs": {
       "yargs-parser": "^21.1.1"
     },
     "jsonwebtoken": "9.0.0",
-    "jsonpointer": "5.0.0"
+    "jsonpointer": "5.0.0",
+    "validator": "13.7.0"
   },
   "devDependencies": {
     "@types/jest": "29.5.14",
     "audit-ci": "^7.1.0",
-    "axios": "1.7.7",
+    "axios": "1.7.9",
     "axios-retry": "^4.5.0",
     "docdash": "2.0.2",
-    "dotenv": "^16.4.5",
+    "dotenv": "^16.4.7",
     "get-port": "5.1.1",
     "ioredis-mock": "^8.9.0",
     "jest": "29.7.0",
     "jest-junit": "16.0.0",
     "jsdoc": "4.0.4",
-    "nodemon": "3.1.7",
-    "npm-check-updates": "17.1.11",
+    "nodemon": "3.1.9",
+    "npm-check-updates": "17.1.13",
     "nyc": "17.1.0",
     "pre-commit": "1.2.2",
+    "proxyquire": "2.1.3",
     "replace": "^1.2.2",
     "sinon": "19.0.2",
     "standard": "17.1.2",

package/src/constants.js

@@ -1,5 +1,6 @@
 const ERROR_MESSAGES = Object.freeze({
-  partySourceFspNotFound: 'Requester FSP not found',
+  sourceFspNotFound: 'Requester FSP not found',
+  partySourceFspNotFound: 'Requester FSP not found', // todo: use sourceFspNotFound
   partyDestinationFspNotFound: 'Destination FSP not found',
   partyProxyNotFound: 'Proxy not found',
   proxyConnectionError: 'Proxy connection error',

package/src/domain/oracle/oracle.js

@@ -49,9 +49,15 @@ exports.createOracle = async (payload) => {
     'Create Oracle',
     ['success']
   ).startTimer()
+  const errorCounter = Metrics.getCounter('errorCount')
+  let step
+
   try {
+    step = 'getPartyIdTypeByName-1'
     const partyIdTypeModel = await partyIdType.getPartyIdTypeByName(payload.oracleIdType)
+    step = 'getEndpointTypeByType-2'
     const endpointTypeModel = await endpointType.getEndpointTypeByType(payload.endpoint.endpointType)
+    step = 'getAllOracleEndpointsByMatchCondition-3'
     const existingActiveOracle = await oracleEndpoint.getAllOracleEndpointsByMatchCondition(
       payload,
       partyIdTypeModel.partyIdTypeId,
@@ -77,13 +83,23 @@ exports.createOracle = async (payload) => {
     oracleEntity.createdBy = 'Admin'
     oracleEntity.partyIdTypeId = partyIdTypeModel.partyIdTypeId
     oracleEntity.endpointTypeId = endpointTypeModel.endpointTypeId
+    step = 'createOracleEndpoint-4'
     await oracleEndpoint.createOracleEndpoint(oracleEntity)
     histTimerEnd({ success: true })
     return true
   } catch (err) {
     histTimerEnd({ success: false })
     Logger.isErrorEnabled && Logger.error(err)
-    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+    const fspiopError = ErrorHandler.Factory.reformatFSPIOPError(err)
+    const extensions = err.extensions || []
+    const system = extensions.find((element) => element.key === 'system')?.value || ''
+    errorCounter.inc({
+      code: fspiopError?.apiErrorCode?.code,
+      system,
+      operation: 'createOracle',
+      step
+    })
+    throw fspiopError
   }
 }
 
@@ -100,6 +116,8 @@ exports.getOracle = async (query) => {
     'Get Oracle',
     ['success']
   ).startTimer()
+  const errorCounter = Metrics.getCounter('errorCount')
+  let step
   try {
     let oracleEndpointModelList
     let isCurrency; let isType = false
@@ -111,12 +129,16 @@ exports.getOracle = async (query) => {
       isType = true
     }
     if (isCurrency && isType) {
+      step = 'getOracleEndpointByTypeAndCurrency-1'
       oracleEndpointModelList = await cachedOracleEndpoint.getOracleEndpointByTypeAndCurrency(query.type, query.currency)
     } else if (isCurrency && !isType) {
+      step = 'getOracleEndpointByCurrency-2'
       oracleEndpointModelList = await cachedOracleEndpoint.getOracleEndpointByCurrency(query.currency)
     } else if (isType && !isCurrency) {
+      step = 'getOracleEndpointByType-3'
       oracleEndpointModelList = await cachedOracleEndpoint.getOracleEndpointByType(query.type)
     } else {
+      step = 'getAllOracleEndpoint-4'
       oracleEndpointModelList = await oracleEndpoint.getAllOracleEndpoint()
     }
     for (const oracleEndpointModel of oracleEndpointModelList) {
@@ -137,7 +159,16 @@ exports.getOracle = async (query) => {
   } catch (err) {
     histTimerEnd({ success: false })
     Logger.isErrorEnabled && Logger.error(err)
-    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+    const fspiopError = ErrorHandler.Factory.reformatFSPIOPError(err)
+    const extensions = err.extensions || []
+    const system = extensions.find((element) => element.key === 'system')?.value || ''
+    errorCounter.inc({
+      code: fspiopError?.apiErrorCode?.code,
+      system,
+      operation: 'getOracle',
+      step
+    })
+    throw fspiopError
   }
 }
 
@@ -155,11 +186,17 @@ exports.updateOracle = async (params, payload) => {
     'Update Oracle',
     ['success']
   ).startTimer()
+  const errorCounter = Metrics.getCounter('errorCount')
+  let step
   try {
+    step = 'getOracleEndpointById-1'
     const currentOracleEndpointList = await oracleEndpoint.getOracleEndpointById(params.ID)
     if (currentOracleEndpointList.length > 0) {
+      step = 'getPartyIdTypeByName-2'
       const partyIdTypeModel = await partyIdType.getPartyIdTypeByName(payload.oracleIdType)
+      step = 'getEndpointTypeByType-3'
       const endpointTypeModel = await endpointType.getEndpointTypeByType(payload.endpoint.endpointType)
+      step = 'getAllOracleEndpointsByMatchCondition-4'
       const existingActiveOracle = await oracleEndpoint.getAllOracleEndpointsByMatchCondition(
         payload,
         partyIdTypeModel.partyIdTypeId,
@@ -175,6 +212,7 @@ exports.updateOracle = async (params, payload) => {
       const currentOracleEndpoint = currentOracleEndpointList[0]
       const newOracleEntry = {}
       if (payload.oracleIdType && payload.oracleIdType !== currentOracleEndpoint.idType) {
+        step = 'getPartyIdTypeByName-5'
         const partyTypeModel = await partyIdType.getPartyIdTypeByName(payload.oracleIdType)
         newOracleEntry.partyIdTypeId = partyTypeModel.partyIdTypeId
       }
@@ -182,10 +220,12 @@ exports.updateOracle = async (params, payload) => {
         newOracleEntry.value = payload.endpoint.value
       }
       if (payload.endpoint && payload.endpoint.endpointType && payload.endpoint.endpointType !== currentOracleEndpoint.endpointType) {
+        step = 'getEndpointTypeByType-6'
         const endpointTypeModel = await endpointType.getEndpointTypeByType(payload.endpoint.endpointType)
         newOracleEntry.endpointTypeId = endpointTypeModel.endpointTypeId
       }
       if (payload.currency && payload.currency !== currentOracleEndpoint.currency) {
+        step = 'getCurrencyById-7'
         const currencyModel = await currency.getCurrencyById(payload.currency)
         if (currencyModel) {
           newOracleEntry.currencyId = payload.currency
@@ -196,6 +236,7 @@ exports.updateOracle = async (params, payload) => {
       if (payload.isDefault && payload.isDefault !== currentOracleEndpoint.isDefault) {
         newOracleEntry.isDefault = payload.isDefault
       }
+      step = 'updateOracleEndpointById-8'
       await oracleEndpoint.updateOracleEndpointById(params.ID, newOracleEntry)
       histTimerEnd({ success: true })
       return true
@@ -205,7 +246,16 @@ exports.updateOracle = async (params, payload) => {
   } catch (err) {
     histTimerEnd({ success: false })
     Logger.isErrorEnabled && Logger.error(err)
-    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+    const fspiopError = ErrorHandler.Factory.reformatFSPIOPError(err)
+    const extensions = err.extensions || []
+    const system = extensions.find((element) => element.key === 'system')?.value || ''
+    errorCounter.inc({
+      code: fspiopError?.apiErrorCode?.code,
+      system,
+      operation: 'updateOracle',
+      step
+    })
+    throw fspiopError
   }
 }
 
@@ -222,6 +272,7 @@ exports.deleteOracle = async (params) => {
     'Delete Oracle',
     ['success']
   ).startTimer()
+  const errorCounter = Metrics.getCounter('errorCount')
   try {
     await oracleEndpoint.destroyOracleEndpointById(params.ID)
     histTimerEnd({ success: true })
@@ -229,6 +280,14 @@ exports.deleteOracle = async (params) => {
   } catch (err) {
     histTimerEnd({ success: false })
     Logger.isErrorEnabled && Logger.error(err)
-    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+    const fspiopError = ErrorHandler.Factory.reformatFSPIOPError(err)
+    const extensions = err.extensions || []
+    const system = extensions.find((element) => element.key === 'system')?.value || ''
+    errorCounter.inc({
+      code: fspiopError?.apiErrorCode?.code,
+      system,
+      operation: 'deleteOracle'
+    })
+    throw fspiopError
   }
 }