From 0acf2271c7fba4630b16792c9d72ecf0981cfb3d Mon Sep 17 00:00:00 2001 From: Simonas Karuzas Date: Wed, 25 Oct 2023 09:19:18 +0300 Subject: [PATCH 1/2] feat(did-comm): sendDIDCommMessage - returnMessage --- .../messagepickup-message-handler.test.ts | 27 +++++ packages/did-comm/src/didcomm.ts | 22 +++- packages/did-comm/src/plugin.schema.json | 107 ++++++++++-------- .../protocols/trust-ping-message-handler.ts | 2 +- packages/did-comm/src/types/IDIDComm.ts | 3 +- 5 files changed, 109 insertions(+), 52 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 index cd129d561..f362a0060 100644 --- 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 index f286bf347..a6c5da155 100644 --- a/packages/did-comm/src/didcomm.ts +++ b/packages/did-comm/src/didcomm.ts @@ -155,6 +155,19 @@ export interface ISendDIDCommMessageArgs { recipientDidUrl: string } + +/** + * The response from the {@link DIDComm.sendDIDCommMessage} method. + * + * @beta This API may change without a BREAKING CHANGE notice. + * `return_message` is only present if the `return_route: 'all'` was used + * in the packedMessage. + */ +export interface ISendDIDCommMessageResponse { + transportId: string + returnMessage?: IMessage +} + /** * DID Comm plugin for {@link @veramo/core#Agent} * @@ -715,8 +728,8 @@ export class DIDComm implements IAgentPlugin { /** {@inheritdoc IDIDComm.sendDIDCommMessage} */ async sendDIDCommMessage( args: ISendDIDCommMessageArgs, - context: IAgentContext, - ): Promise { + context: IAgentContext, + ): Promise { const { packedMessage, returnTransportId, recipientDidUrl, messageId } = args if (returnTransportId) { @@ -839,11 +852,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/plugin.schema.json b/packages/did-comm/src/plugin.schema.json index c74f08601..d6c2a0fa9 100644 --- a/packages/did-comm/src/plugin.schema.json +++ b/packages/did-comm/src/plugin.schema.json @@ -224,59 +224,20 @@ ], "description": "The input to the {@link DIDComm.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 DIDComm.sendDIDCommMessage } method." }, "IMessage": { "type": "object", @@ -647,6 +608,60 @@ }, "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." @@ -705,7 +720,7 @@ "$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 index 25ecd6abc..66f863b34 100644 --- 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) } diff --git a/packages/did-comm/src/types/IDIDComm.ts b/packages/did-comm/src/types/IDIDComm.ts index 7e313dee7..3099e842d 100644 --- a/packages/did-comm/src/types/IDIDComm.ts +++ b/packages/did-comm/src/types/IDIDComm.ts @@ -10,6 +10,7 @@ import { import { IPackDIDCommMessageArgs, ISendDIDCommMessageArgs, + ISendDIDCommMessageResponse, ISendMessageDIDCommAlpha1Args, IUnpackDIDCommMessageArgs, } from '../didcomm.js' @@ -97,7 +98,7 @@ export interface IDIDComm extends IPluginMethodMap { * * @beta This API may change without a BREAKING CHANGE notice. */ - sendDIDCommMessage(args: ISendDIDCommMessageArgs, context: IAgentContext): Promise + sendDIDCommMessage(args: ISendDIDCommMessageArgs, context: IAgentContext): Promise /** * From 46bed1bfbbe81d1ccccce77eb5f23263c1a1479d Mon Sep 17 00:00:00 2001 From: Mircea Nistor Date: Wed, 1 Nov 2023 17:57:18 +0100 Subject: [PATCH 2/2] docs(did-comm): adapt inline docs for IDIDComm --- packages/did-comm/src/didcomm.ts | 62 +++-------------- packages/did-comm/src/index.ts | 7 +- packages/did-comm/src/plugin.schema.json | 10 +-- packages/did-comm/src/types/IDIDComm.ts | 85 +++++++++++++++++++----- 4 files changed, 82 insertions(+), 82 deletions(-) diff --git a/packages/did-comm/src/didcomm.ts b/packages/did-comm/src/didcomm.ts index a6c5da155..5d538805d 100644 --- 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,55 +123,6 @@ export interface ISendMessageDIDCommAlpha1Args { headers?: Record } -// 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 -} - - -/** - * The response from the {@link DIDComm.sendDIDCommMessage} method. - * - * @beta This API may change without a BREAKING CHANGE notice. - * `return_message` is only present if the `return_route: 'all'` was used - * in the packedMessage. - */ -export interface ISendDIDCommMessageResponse { - transportId: string - returnMessage?: IMessage -} - /** * DID Comm plugin for {@link @veramo/core#Agent} * @@ -435,7 +390,8 @@ export class DIDComm implements IAgentPlugin { recipient.publicKeyBytes, 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, senderECDH, { kid: recipient.kid, diff --git a/packages/did-comm/src/index.ts b/packages/did-comm/src/index.ts index 3ffca0e71..5cf8fc6b0 100644 --- 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 index d6c2a0fa9..7af1fa346 100644 --- 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,7 +222,7 @@ "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." }, "ISendDIDCommMessageResponse": { "type": "object", @@ -237,7 +237,7 @@ "required": [ "transportId" ], - "description": "The response from the {@link DIDComm.sendDIDCommMessage } method." + "description": "The response from the {@link IDIDComm.sendDIDCommMessage } method." }, "IMessage": { "type": "object", @@ -664,7 +664,7 @@ }, "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", @@ -715,7 +715,7 @@ } }, "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" }, diff --git a/packages/did-comm/src/types/IDIDComm.ts b/packages/did-comm/src/types/IDIDComm.ts index 3099e842d..88803b658 100644 --- a/packages/did-comm/src/types/IDIDComm.ts +++ b/packages/did-comm/src/types/IDIDComm.ts @@ -7,20 +7,62 @@ import { IPluginMethodMap, IResolver, } from '@veramo/core-types' -import { - IPackDIDCommMessageArgs, - ISendDIDCommMessageArgs, - ISendDIDCommMessageResponse, - ISendMessageDIDCommAlpha1Args, - IUnpackDIDCommMessageArgs, -} from '../didcomm.js' +import { ISendMessageDIDCommAlpha1Args } from '../didcomm.js' import { DIDCommMessageMediaType, + DIDCommMessagePacking, + IDIDCommMessage, IDIDCommOptions, IPackedDIDCommMessage, IUnpackedDIDCommMessage, } from './message-types.js' +/** + * The input to the {@link IDIDComm.unpackDIDCommMessage} method. + * + * @beta This API may change without a BREAKING CHANGE notice. + */ +export type IUnpackDIDCommMessageArgs = IPackedDIDCommMessage + +/** + * The input to the {@link IDIDComm.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 IDIDComm.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 +} + +/** + * The response from the {@link IDIDComm.sendDIDCommMessage} method. + * + * @beta This API may change without a BREAKING CHANGE notice. + * `return_message` is only present if the `return_route: 'all'` was used + * in the packedMessage. + */ +export interface ISendDIDCommMessageResponse { + transportId: string + returnMessage?: IMessage +} + /** * DID Comm plugin interface for {@link @veramo/core#Agent} * @@ -30,8 +72,8 @@ export interface IDIDComm extends IPluginMethodMap { /** * Partially decodes a possible DIDComm message string to determine the {@link DIDCommMessageMediaType} * - * @param IPackedDIDCommMessage - the message to be interpreted - * @returns the {@link DIDCommMessageMediaType} if it was successfully parsed + * @param args - the message to be interpreted + * @returns - the {@link DIDCommMessageMediaType} if it was successfully parsed * @throws if the message cannot be parsed as DIDComm v2 * * @beta This API may change without a BREAKING CHANGE notice. @@ -52,7 +94,8 @@ export interface IDIDComm extends IPluginMethodMap { * {@link @veramo/core-types#IKeyManager} and {@link @veramo/core-types#IResolver} plugins in use. * When calling this method, the `context` is supplied automatically by the framework. * - * @returns a Promise that resolves to an object containing the serialized packed `message` string + * @returns - a Promise that resolves to a {@link IPackedDIDCommMessage} object containing the serialized packed + * `message` string * * @beta This API may change without a BREAKING CHANGE notice. */ @@ -70,7 +113,7 @@ export interface IDIDComm extends IPluginMethodMap { * {@link @veramo/core-types#IKeyManager} and {@link @veramo/core-types#IResolver} plugins in use. * When calling this method, the `context` is supplied automatically by the framework. * - * @returns a Promise that resolves to an object containing + * @returns - a Promise that resolves to an object containing * the {@link IDIDCommMessage} and {@link DIDCommMessagePacking} used. * * @beta This API may change without a BREAKING CHANGE notice. @@ -81,7 +124,7 @@ export interface IDIDComm extends IPluginMethodMap { ): Promise /** - * Sends the given message to the recipient. If a return transport is provided + * 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. * @@ -90,21 +133,27 @@ export interface IDIDComm extends IPluginMethodMap { * * @param args - An object containing the message, recipient information and optional * information about the transport that should be used. - * @param context - This method requires an agent that also has {@link @veramo/core-types#IResolver} - * plugins in use. When calling this method, the `context` is supplied automatically by the framework. + * @param context - This method requires an agent that also has {@link @veramo/core-types#IResolver}, + * {@link @veramo/core-types#IKeyManager}, {@link @veramo/core-types#IDIDManager}, and + * {@link @veramo/core-types#IMessageHandler} plugins in use. When calling this method, the `context` is supplied + * automatically by the framework. * - * @returns The transport id that was used to send the message. It throws an error in case something - * went wrong. + * @returns - a {@link ISendDIDCommMessageResponse} containing the transport id that was used to send the message and + * a return message, if one is available. It throws an error in case something went wrong. * * @beta This API may change without a BREAKING CHANGE notice. */ - sendDIDCommMessage(args: ISendDIDCommMessageArgs, context: IAgentContext): Promise + sendDIDCommMessage( + args: ISendDIDCommMessageArgs, + context: IAgentContext, + ): Promise /** * * @deprecated Please use {@link IDIDComm.sendDIDCommMessage} instead. This will be removed in Veramo 4.0 * - * This is used to create a message according to the initial {@link https://github.com/decentralized-identifier/DIDComm-js | DIDComm-js} implementation. + * This is used to create a message according to the initial + * {@link https://github.com/decentralized-identifier/DIDComm-js | DIDComm-js} implementation. * * @remarks Be advised that this spec is still not final and that this protocol may need to change. *