feat(did-comm): returnMessage from sendDIDCommMessage() when available (

#1283) * feat(did-comm): returnMessage from sendDIDCommMessage() when available BREAKING CHANGE: the return type of `IDIDComm.sendDIDCommMessage()` has changed from a string representing the transport ID to an object that may include a `returnMessage` property along with a `transportId` property.
decentralized-identity · Nov 1, 2023 · f7a3851 · f7a3851
1 parent ba88d6b
commit f7a3851
Show file tree

Hide file tree

Showing 6 changed files with 175 additions and 118 deletions.
diff --git a/packages/did-comm/src/__tests__/messagepickup-message-handler.test.ts b/packages/did-comm/src/__tests__/messagepickup-message-handler.test.ts
@@ -334,6 +334,33 @@ describe('messagepickup-message-handler', () => {
       )
     })
 
+    it('should contain returnMessage', async () => {
+
+      // Send StatusRequest
+      const statusRequestMessage: IDIDCommMessage = {
+        id: v4(),
+        type: STATUS_REQUEST_MESSAGE_TYPE,
+        to: mediator.did,
+        from: recipient.did,
+        return_route: 'all',
+        body: {
+          recipient_key: `${recipient.did}#${recipient.keys[0].kid}`,
+        },
+      }
+      const packedMessage = await agent.packDIDCommMessage({
+        packing: 'authcrypt',
+        message: statusRequestMessage,
+      })
+      const result = await agent.sendDIDCommMessage({
+        messageId: statusRequestMessage.id,
+        packedMessage,
+        recipientDidUrl: mediator.did,
+      })
+
+      expect(result.transportId).toBeDefined()
+      expect(result.returnMessage).toBeDefined()
+    })
+
     it('should not respond to StatusRequest with no return_route', async () => {
       expect.assertions(1)
       const statusRequestMessage: IDIDCommMessage = {

diff --git a/packages/did-comm/src/didcomm.ts b/packages/did-comm/src/didcomm.ts
@@ -80,13 +80,17 @@ import {
 } from '@veramo/utils'
 
 import Debug from 'debug'
-import { IDIDComm } from './types/IDIDComm.js'
+import {
+  IDIDComm,
+  IPackDIDCommMessageArgs,
+  ISendDIDCommMessageArgs,
+  ISendDIDCommMessageResponse,
+  IUnpackDIDCommMessageArgs,
+} from './types/IDIDComm.js'
 import { DIDCommHttpTransport, IDIDCommTransport } from './transports/transports.js'
 import {
   DIDCommMessageMediaType,
-  DIDCommMessagePacking,
   IDIDCommMessage,
-  IDIDCommOptions,
   IPackedDIDCommMessage,
   IUnpackedDIDCommMessage,
 } from './types/message-types.js'
@@ -119,42 +123,6 @@ export interface ISendMessageDIDCommAlpha1Args {
   headers?: Record<string, string>
 }
 
-// interface arguments
-
-/**
- * The input to the {@link DIDComm.unpackDIDCommMessage} method.
- *
- * @beta This API may change without a BREAKING CHANGE notice.
- */
-export type IUnpackDIDCommMessageArgs = IPackedDIDCommMessage
-
-/**
- * The input to the {@link DIDComm.packDIDCommMessage} method.
- * When `packing` is `authcrypt` or `jws`, a `keyRef` MUST be provided.
- *
- * @beta This API may change without a BREAKING CHANGE notice.
- */
-export interface IPackDIDCommMessageArgs {
-  message: IDIDCommMessage
-  packing: DIDCommMessagePacking
-  keyRef?: string
-  options?: IDIDCommOptions
-}
-
-/**
- * The input to the {@link DIDComm.sendDIDCommMessage} method.
- * The provided `messageId` will be used in the emitted
- * event to allow event/message correlation.
- *
- * @beta This API may change without a BREAKING CHANGE notice.
- */
-export interface ISendDIDCommMessageArgs {
-  packedMessage: IPackedDIDCommMessage
-  messageId: string
-  returnTransportId?: string
-  recipientDidUrl: string
-}
-
 /**
  * DID Comm plugin for {@link @veramo/core#Agent}
  *
@@ -422,7 +390,8 @@ export class DIDComm implements IAgentPlugin {
                 recipient.publicKeyBytes,
                 <ECDH>senderECDH,
                 { kid: recipient.kid },
-            )} else if (options?.alg?.endsWith('+A256KW')) {
+              )
+            } else if (options?.alg?.endsWith('+A256KW')) {
               // FIXME: the didcomm spec actually links to ECDH-1PU(v4)
               return xc20pAuthEncrypterEcdh1PuV3x25519WithA256KW(recipient.publicKeyBytes, <ECDH>senderECDH, {
                 kid: recipient.kid,
@@ -715,8 +684,8 @@ export class DIDComm implements IAgentPlugin {
   /** {@inheritdoc IDIDComm.sendDIDCommMessage} */
   async sendDIDCommMessage(
     args: ISendDIDCommMessageArgs,
-    context: IAgentContext<IDIDManager & IKeyManager & IResolver>,
-  ): Promise<string> {
+    context: IAgentContext<IDIDManager & IKeyManager & IResolver & IMessageHandler>,
+  ): Promise<ISendDIDCommMessageResponse> {
     const { packedMessage, returnTransportId, recipientDidUrl, messageId } = args
 
     if (returnTransportId) {
@@ -839,11 +808,12 @@ export class DIDComm implements IAgentPlugin {
 
     if (response.returnMessage) {
       // Handle return message
-      await context.agent.handleMessage({
+      const returnMessage = await context.agent.handleMessage({
         raw: response.returnMessage,
       })
+      return { transportId: transport.id, returnMessage }
     }
-    return transport.id
+    return { transportId: transport.id }
   }
 
   /** {@inheritdoc IDIDComm.sendMessageDIDCommAlpha1} */

diff --git a/packages/did-comm/src/index.ts b/packages/did-comm/src/index.ts
@@ -6,12 +6,7 @@
  * @packageDocumentation
  */
 
-export {
-  DIDComm,
-  ISendMessageDIDCommAlpha1Args,
-  IPackDIDCommMessageArgs,
-  IUnpackDIDCommMessageArgs,
-} from './didcomm.js'
+export * from './didcomm.js'
 export * from './types/message-types.js'
 export * from './types/utility-types.js'
 export * from './types/IDIDComm.js'

diff --git a/packages/did-comm/src/plugin.schema.json b/packages/did-comm/src/plugin.schema.json
@@ -43,7 +43,7 @@
             "message",
             "packing"
           ],
-          "description": "The input to the  {@link  DIDComm.packDIDCommMessage }  method. When `packing` is `authcrypt` or `jws`, a `keyRef` MUST be provided."
+          "description": "The input to the  {@link  IDIDComm.packDIDCommMessage }  method. When `packing` is `authcrypt` or `jws`, a `keyRef` MUST be provided."
         },
         "IDIDCommMessage": {
           "type": "object",
@@ -222,61 +222,22 @@
             "messageId",
             "recipientDidUrl"
           ],
-          "description": "The input to the  {@link  DIDComm.sendDIDCommMessage }  method. The provided `messageId` will be used in the emitted event to allow event/message correlation."
+          "description": "The input to the  {@link  IDIDComm.sendDIDCommMessage }  method. The provided `messageId` will be used in the emitted event to allow event/message correlation."
         },
-        "ISendMessageDIDCommAlpha1Args": {
+        "ISendDIDCommMessageResponse": {
           "type": "object",
           "properties": {
-            "url": {
+            "transportId": {
               "type": "string"
             },
-            "save": {
-              "type": "boolean"
-            },
-            "data": {
-              "type": "object",
-              "properties": {
-                "id": {
-                  "type": "string"
-                },
-                "from": {
-                  "type": "string"
-                },
-                "to": {
-                  "type": "string"
-                },
-                "type": {
-                  "type": "string"
-                },
-                "body": {
-                  "anyOf": [
-                    {
-                      "type": "object"
-                    },
-                    {
-                      "type": "string"
-                    }
-                  ]
-                }
-              },
-              "required": [
-                "from",
-                "to",
-                "type",
-                "body"
-              ]
-            },
-            "headers": {
-              "type": "object",
-              "additionalProperties": {
-                "type": "string"
-              }
+            "returnMessage": {
+              "$ref": "#/components/schemas/IMessage"
             }
           },
           "required": [
-            "data"
+            "transportId"
           ],
-          "deprecated": "Please use {@link IDIDComm.sendDIDCommMessage } instead. This will be removed in Veramo 4.0.\nInput arguments for {@link IDIDComm.sendMessageDIDCommAlpha1 }"
+          "description": "The response from the  {@link  IDIDComm.sendDIDCommMessage }  method."
         },
         "IMessage": {
           "type": "object",
@@ -647,9 +608,63 @@
           },
           "description": "The DIDComm message structure for data in an attachment. See https://identity.foundation/didcomm-messaging/spec/#attachments"
         },
+        "ISendMessageDIDCommAlpha1Args": {
+          "type": "object",
+          "properties": {
+            "url": {
+              "type": "string"
+            },
+            "save": {
+              "type": "boolean"
+            },
+            "data": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "from": {
+                  "type": "string"
+                },
+                "to": {
+                  "type": "string"
+                },
+                "type": {
+                  "type": "string"
+                },
+                "body": {
+                  "anyOf": [
+                    {
+                      "type": "object"
+                    },
+                    {
+                      "type": "string"
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "from",
+                "to",
+                "type",
+                "body"
+              ]
+            },
+            "headers": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          },
+          "required": [
+            "data"
+          ],
+          "deprecated": "Please use {@link IDIDComm.sendDIDCommMessage } instead. This will be removed in Veramo 4.0.\nInput arguments for {@link IDIDComm.sendMessageDIDCommAlpha1 }"
+        },
         "IUnpackDIDCommMessageArgs": {
           "$ref": "#/components/schemas/IPackedDIDCommMessage",
-          "description": "The input to the  {@link  DIDComm.unpackDIDCommMessage }  method."
+          "description": "The input to the  {@link  IDIDComm.unpackDIDCommMessage }  method."
         },
         "IUnpackedDIDCommMessage": {
           "type": "object",
@@ -700,12 +715,12 @@
           }
         },
         "sendDIDCommMessage": {
-          "description": "Sends the given message to the recipient. If a return transport is provided it will be checked whether the parent thread allows reusing the route. You cannot reuse the transport if the message was forwarded from a DIDComm mediator.",
+          "description": "Sends the given message to the recipient. If a return-transport is provided it will be checked whether the parent thread allows reusing the route. You cannot reuse the transport if the message was forwarded from a DIDComm mediator.",
           "arguments": {
             "$ref": "#/components/schemas/ISendDIDCommMessageArgs"
           },
           "returnType": {
-            "type": "string"
+            "$ref": "#/components/schemas/ISendDIDCommMessageResponse"
           }
         },
         "sendMessageDIDCommAlpha1": {

diff --git a/packages/did-comm/src/protocols/trust-ping-message-handler.ts b/packages/did-comm/src/protocols/trust-ping-message-handler.ts
@@ -73,7 +73,7 @@ export class TrustPingMessageHandler extends AbstractMessageHandler {
           packedMessage: packedResponse,
           recipientDidUrl: from!,
         })
-        message.addMetaData({ type: 'TrustPingResponseSent', value: sent })
+        message.addMetaData({ type: 'TrustPingResponseSent', value: JSON.stringify(sent) })
       } catch (ex) {
         debug(ex)
       }