feat(cactus-plugin-ledger-connector-fabric): support delegated (offli…

…ne) signatures - Add new `RunDelegatedSignTransactionEndpointV1` endpoint for delegated / offline signing. Takes `signerCertificate` and `signerMspID`, uses `signCallback` on connector to sign messages. Sign must be implemented by a user, can contain any logic (contacting 3'rd party services, reading from secure sources, etc…). Interface is similar to transact. Supports private transactions. - Refactor transact endpoint: Use common logic for handling response format. with delegated transact - Refactor logic of choosing ednorsers in transact endpoint. Previously both `endorsingPeers` and `endorsingParties` were selecting organizations in sligly different way under different circumstances. Now `endorsingPeers` selectes peers and `endorsingOrgs` selects orgs for all cases (query, send, privatesend) in both transact and transact with delegated sign. This is more consistent and predictable. - Add new socketio endpoint `SubscribeDelegatedSign` for monitoring new blocks with delegated sign. - Use common error handling in getblock, transact and transact delgated endpoints. - Add functional tests for delegated signing feature. Depends on: #2598 Signed-off-by: Michal Bajer <[email protected]>
hyperledger-cacti · Sep 18, 2023 · 4ee177e · 4ee177e
1 parent a28641a
commit 4ee177e
Show file tree

Hide file tree

Showing 39 changed files with 2,787 additions and 277 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -21,6 +21,8 @@
         "cafile",
         "caio",
         "cccs",
+        "ccep",
+        "cccg",
         "cbdc",
         "Cbdc",
         "ccid",
@@ -64,6 +66,7 @@
         "HTLC",
         "Hursley",
         "HyperLedger",
+        "immalleable",
         "ipaddress",
         "ipfs",
         "Iroha",
@@ -86,6 +89,7 @@
         "miekg",
         "mitchellh",
         "MSPCONFIGPATH",
+        "Mspids",
         "MSPID",
         "MSPIDSCOPEALLFORTX",
         "MSPIDSCOPEANYFORTX",

diff --git a/packages/cactus-plugin-ledger-connector-fabric/README.md b/packages/cactus-plugin-ledger-connector-fabric/README.md
@@ -13,6 +13,8 @@
   - [1.5 Monitoring new blocks (WatchBlocks)](#15-monitoring-new-blocks-watchblocks)
     - [1.5.1 Example](#151-example)
     - [1.5.2 Listener Type](#152-listener-type)
+  - [1.6 Delegated Signature](#16-delegated-signature)
+    - [1.6.1 Example](#161-example)
 - [2. Architecture](#2-architecture)
   - [2.1. run-transaction-endpoint](#21-run-transaction-endpoint)
 - [3. Containerization](#3-containerization)
@@ -329,6 +331,47 @@ Corresponds directly to `BlockType` from `fabric-common`:
   - `WatchBlocksListenerTypeV1.Full`,
   - `WatchBlocksListenerTypeV1.Private`,
 
+### 1.6 Delegated Signature
+- Custom signature callback can be used when increased security is needed or currently available options are not sufficient.
+- Signature callback is used whenever fabric request must be signed.
+- To use delegate signature instead of identity supplied directly / through keychain use `transactDelegatedSign` (for transact) or `watchBlocksDelegatedSignV1` for block monitoring.
+- `uniqueTransactionData` can be passed to each delegate sign method on connector. This data is passed to signCallback to identify and verify the request. It can be used to pass signing tokens or any other data needed for performing the signing (e.g. user, scopes, etc...).
+- `signProposal` method from this package can be used to sign the requests in offline location.
+- For more complex examples see tests: `delegate-signing-methods.test` and `fabric-watch-blocks-delegated-sign-v1-endpoint.test`.
+
+#### 1.6.1 Example
+```typescript
+// Setup - supply callback when instantiating the connector plugin
+fabricConnectorPlugin = new PluginLedgerConnectorFabric({
+  instanceId: uuidv4(),
+  // ...
+  signCallback: async (payload, txData) => {
+    log.debug("signCallback called with txData (token):", txData);
+    return signProposal(adminIdentity.credentials.privateKey, payload);
+  },
+});
+
+// Run transactions
+await apiClient.runDelegatedSignTransactionV1({
+  signerCertificate: adminIdentity.credentials.certificate,
+  signerMspID: adminIdentity.mspId,
+  channelName: ledgerChannelName,
+  contractName: assetTradeContractName,
+  invocationType: FabricContractInvocationType.Call,
+  methodName: "ReadAsset",
+  params: ["asset1"],
+  uniqueTransactionData: myJwtToken,
+});
+
+// Monitor for transactions:
+apiClient.watchBlocksDelegatedSignV1({
+  type: WatchBlocksListenerTypeV1.CactusTransactions,
+  signerCertificate: adminIdentity.credentials.certificate,
+  signerMspID: adminIdentity.mspId,
+  channelName: ledgerChannelName,
+})
+```
+
 ##### Cactus (custom)
 Parses the data and returns custom formatted block.
 - `WatchBlocksListenerTypeV1.CactusTransactions`: Returns transactions summary. Compatible with legacy `fabric-socketio` monitoring operation.

diff --git a/packages/cactus-plugin-ledger-connector-fabric/package.json b/packages/cactus-plugin-ledger-connector-fabric/package.json
@@ -77,6 +77,7 @@
     "node-vault": "0.9.22",
     "openapi-types": "9.1.0",
     "prom-client": "13.2.0",
+    "run-time-error": "1.4.0",
     "rxjs": "7.8.1",
     "sanitize-filename": "1.6.3",
     "sanitize-html": "2.7.0",

diff --git a/packages/cactus-plugin-ledger-connector-fabric/src/main/json/openapi.json b/packages/cactus-plugin-ledger-connector-fabric/src/main/json/openapi.json
@@ -374,6 +374,15 @@
           }
         }
       },
+      "RunTransactionResponseType": {
+        "type": "string",
+        "description": "Response format from transaction / query execution",
+        "enum": [
+          "org.hyperledger.cacti.api.hlfabric.RunTransactionResponseType.JSON",
+          "org.hyperledger.cacti.api.hlfabric.RunTransactionResponseType.UTF8"
+        ],
+        "x-enum-varnames": ["JSON", "UTF8"]
+      },
       "RunTransactionRequest": {
         "type": "object",
         "required": [
@@ -387,7 +396,17 @@
         "additionalProperties": false,
         "properties": {
           "endorsingPeers": {
-            "description": "An array of MSP IDs to set as the list of endorsing peers for the transaction.",
+            "description": "An array of endorsing peers (name or url) for the transaction.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096,
+              "nullable": false
+            }
+          },
+          "endorsingOrgs": {
+            "description": "An array of endorsing organizations (by mspID or issuer org name on certificate) for the transaction.",
             "type": "array",
             "items": {
               "type": "string",
@@ -440,35 +459,108 @@
               "nullable": true
             }
           },
-          "endorsingParties": {
-            "type": "array",
-            "nullable": false,
-            "default": [],
-            "items": {
-              "type": "string",
-              "nullable": true
-            }
-          },
           "responseType": {
-            "type": "string"
+            "$ref": "#/components/schemas/RunTransactionResponseType"
           }
         }
       },
       "RunTransactionResponse": {
         "type": "object",
-        "required": ["functionOutput", "success", "transactionId"],
+        "required": ["functionOutput", "transactionId"],
         "properties": {
           "functionOutput": {
             "type": "string",
             "nullable": false
           },
-          "success": {
-            "type": "boolean",
+          "transactionId": {
+            "type": "string",
+            "nullable": false
+          }
+        }
+      },
+      "RunDelegatedSignTransactionRequest": {
+        "type": "object",
+        "required": [
+          "signerCertificate",
+          "signerMspID",
+          "channelName",
+          "contractName",
+          "invocationType",
+          "methodName",
+          "params"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "endorsingPeers": {
+            "description": "An array of endorsing peers (name or url) for the transaction.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096,
+              "nullable": false
+            }
+          },
+          "endorsingOrgs": {
+            "description": "An array of endorsing organizations (by mspID or issuer org name on certificate) for the transaction.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096,
+              "nullable": false
+            }
+          },
+          "transientData": {
+            "type": "object",
+            "nullable": true
+          },
+          "signerCertificate": {
+            "type": "string",
             "nullable": false
           },
-          "transactionId": {
+          "signerMspID": {
             "type": "string",
             "nullable": false
+          },
+          "uniqueTransactionData": {
+            "description": "Can be used to uniquely identify and authorize signing request",
+            "nullable": false
+          },
+          "channelName": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "nullable": false
+          },
+          "contractName": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "nullable": false
+          },
+          "invocationType": {
+            "$ref": "#/components/schemas/FabricContractInvocationType",
+            "nullable": false,
+            "description": "Indicates if it is a CALL or a SEND type of invocation where only SEND ends up creating an actual transaction on the ledger."
+          },
+          "methodName": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "nullable": false
+          },
+          "params": {
+            "type": "array",
+            "nullable": false,
+            "default": [],
+            "items": {
+              "type": "string",
+              "nullable": true
+            }
+          },
+          "responseType": {
+            "$ref": "#/components/schemas/RunTransactionResponseType"
           }
         }
       },
@@ -1031,13 +1123,15 @@
         "description": "Websocket requests for monitoring new blocks.",
         "enum": [
           "org.hyperledger.cactus.api.async.hlfabric.WatchBlocksV1.Subscribe",
+          "org.hyperledger.cactus.api.async.hlfabric.WatchBlocksV1.SubscribeDelegatedSign",
           "org.hyperledger.cactus.api.async.hlfabric.WatchBlocksV1.Next",
           "org.hyperledger.cactus.api.async.hlfabric.WatchBlocksV1.Unsubscribe",
           "org.hyperledger.cactus.api.async.hlfabric.WatchBlocksV1.Error",
           "org.hyperledger.cactus.api.async.hlfabric.WatchBlocksV1.Complete"
         ],
         "x-enum-varnames": [
           "Subscribe",
+          "SubscribeDelegatedSign",
           "Next",
           "Unsubscribe",
           "Error",
@@ -1081,6 +1175,43 @@
           }
         }
       },
+      "WatchBlocksDelegatedSignOptionsV1": {
+        "type": "object",
+        "description": "Options passed when subscribing to block monitoring with delegated signing.",
+        "required": ["type", "channelName", "signerCertificate", "signerMspID"],
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/WatchBlocksListenerTypeV1",
+            "description": "Type of response block to return.",
+            "nullable": false
+          },
+          "startBlock": {
+            "type": "string",
+            "description": "From which block start monitoring. Defaults to latest.",
+            "minLength": 1,
+            "maxLength": 100,
+            "nullable": false
+          },
+          "channelName": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "nullable": false
+          },
+          "signerCertificate": {
+            "type": "string",
+            "nullable": false
+          },
+          "signerMspID": {
+            "type": "string",
+            "nullable": false
+          },
+          "uniqueTransactionData": {
+            "description": "Can be used to uniquely identify and authorize signing request",
+            "nullable": false
+          }
+        }
+      },
       "WatchBlocksCactusTransactionsEventV1": {
         "type": "object",
         "description": "Transaction summary from commited block.",
@@ -1241,8 +1372,61 @@
               }
             }
           },
-          "404": {
-            "description": ""
+          "500": {
+            "description": "Internal Server Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorExceptionResponseV1"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-fabric/run-delegated-sign-transaction": {
+      "post": {
+        "x-hyperledger-cactus": {
+          "http": {
+            "verbLowerCase": "post",
+            "path": "/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-fabric/run-delegated-sign-transaction"
+          }
+        },
+        "operationId": "runDelegatedSignTransactionV1",
+        "summary": "Runs a transaction on a Fabric ledger using user-provided signing callback.",
+        "description": "",
+        "parameters": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RunDelegatedSignTransactionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunTransactionResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorExceptionResponseV1"
+                }
+              }
+            }
           }
         }
       }

diff --git a/...connector-fabric/src/main/kotlin/generated/openapi/kotlin-client/.openapi-generator/FILES b/...connector-fabric/src/main/kotlin/generated/openapi/kotlin-client/.openapi-generator/FILES
@@ -51,8 +51,10 @@ src/main/kotlin/org/openapitools/client/models/GetBlockResponseDecodedV1.kt
 src/main/kotlin/org/openapitools/client/models/GetBlockResponseEncodedV1.kt
 src/main/kotlin/org/openapitools/client/models/GetBlockResponseV1.kt
 src/main/kotlin/org/openapitools/client/models/GetTransactionReceiptResponse.kt
+src/main/kotlin/org/openapitools/client/models/RunDelegatedSignTransactionRequest.kt
 src/main/kotlin/org/openapitools/client/models/RunTransactionRequest.kt
 src/main/kotlin/org/openapitools/client/models/RunTransactionResponse.kt
+src/main/kotlin/org/openapitools/client/models/RunTransactionResponseType.kt
 src/main/kotlin/org/openapitools/client/models/SSHExecCommandResponse.kt
 src/main/kotlin/org/openapitools/client/models/TransactReceiptBlockMetaData.kt
 src/main/kotlin/org/openapitools/client/models/TransactReceiptTransactionCreator.kt
@@ -61,6 +63,7 @@ src/main/kotlin/org/openapitools/client/models/VaultTransitKey.kt
 src/main/kotlin/org/openapitools/client/models/WatchBlocksCactusErrorResponseV1.kt
 src/main/kotlin/org/openapitools/client/models/WatchBlocksCactusTransactionsEventV1.kt
 src/main/kotlin/org/openapitools/client/models/WatchBlocksCactusTransactionsResponseV1.kt
+src/main/kotlin/org/openapitools/client/models/WatchBlocksDelegatedSignOptionsV1.kt
 src/main/kotlin/org/openapitools/client/models/WatchBlocksFilteredResponseV1.kt
 src/main/kotlin/org/openapitools/client/models/WatchBlocksFullResponseV1.kt
 src/main/kotlin/org/openapitools/client/models/WatchBlocksListenerTypeV1.kt