feat(cactus-plugin-ledger-connector-fabric): support delegated (offline) signatures

.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",

.github/workflows/ci.yaml

@@ -831,6 +831,7 @@ jobs:
       CACTI_NPM_PACKAGE_NAME: "@hyperledger/cactus-plugin-ledger-connector-fabric"
       HFC_LOGGING: '{"debug":"console","info":"console","warn": "console","error":"console"}'
       FULL_BUILD_DISABLED: true
+      FREE_UP_GITHUB_RUNNER_DISK_SPACE_DISABLED: false
       JEST_TEST_PATTERN: packages/cactus-plugin-ledger-connector-fabric/src/test/typescript/(unit|integration|benchmark)/.*/*.test.ts
       JEST_TEST_RUNNER_DISABLED: false
       TAPE_TEST_PATTERN: ""

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.

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",

packages/cactus-plugin-ledger-connector-fabric/src/main/json/openapi.json

@@ -373,6 +373,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": [
@@ -386,7 +395,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",
@@ -439,35 +458,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"
           }
         }
       },
@@ -1030,13 +1122,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",
@@ -1080,6 +1174,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.",
@@ -1240,8 +1371,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"
+                }
+              }
+            }
           }
         }
       }

packages/cactus-plugin-ledger-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