feat: 0.2.0 connection migration script

demo/src/Alice.ts

@@ -27,11 +27,19 @@ export class Alice extends BaseAgent {
   }
 
   private async printConnectionInvite() {
-    const invite = await this.agent.connections.createConnection()
-    this.connectionRecordFaberId = invite.connectionRecord.id
+    const outOfBand = await this.agent.oob.createInvitation()
+    const connectionRecord = await this.agent.connections.findByOutOfBandId(outOfBand.id)
+    if (!connectionRecord) {
+      throw new Error(redText(Output.NoConnectionRecordFromOutOfBand))
+    }
+    this.connectionRecordFaberId = connectionRecord.id
 
-    console.log(Output.ConnectionLink, invite.invitation.toUrl({ domain: `http://localhost:${this.port}` }), '\n')
-    return invite.connectionRecord
+    console.log(
+      Output.ConnectionLink,
+      outOfBand.outOfBandMessage.toUrl({ domain: `http://localhost:${this.port}` }),
+      '\n'
+    )
+    return connectionRecord
   }
 
   private async waitForConnection() {

demo/src/Faber.ts

@@ -32,7 +32,11 @@ export class Faber extends BaseAgent {
   }
 
   private async receiveConnectionRequest(invitationUrl: string) {
-    return await this.agent.connections.receiveInvitationFromUrl(invitationUrl)
+    const { connectionRecord } = await this.agent.oob.receiveInvitationFromUrl(invitationUrl)
+    if (!connectionRecord) {
+      throw new Error(redText(Output.NoConnectionRecordFromOutOfBand))
+    }
+    return connectionRecord
   }
 
   private async waitForConnection(connectionRecord: ConnectionRecord) {

demo/src/OutputClass.ts

@@ -6,6 +6,7 @@ export enum Color {
 }
 
 export enum Output {
+  NoConnectionRecordFromOutOfBand = `\nNo connectionRecord has been created from invitation\n`,
   ConnectionEstablished = `\nConnection established!`,
   MissingConnectionRecord = `\nNo connectionRecord ID has been set yet\n`,
   ConnectionLink = `\nRun 'Receive connection invitation' in Faber and paste this invitation link:\n\n`,

docs/migration/0.1-to-0.2.md

@@ -73,3 +73,85 @@ Because it's not always possible detect whether the role should actually be medi
 - `doNotChange`: The role is not changed
 
 Most agents only act as either the role of mediator or recipient, in which case the `allMediator` or `allRecipient` configuration is the most appropriate. If your agent acts as both a recipient and mediator, the `recipientIfEndpoint` configuration is the most appropriate. The `doNotChange` options is not recommended and can lead to errors if the role is not set correctly.
+
+### Extracting Did Documents to Did Repository
+
+The connection record previously stored both did documents from a connection in the connection record itself. Version 0.2.0 added a generic did storage that can be used for numerous usages, one of which is the storage of did documents for connection records.
+
+The migration script extracts the did documents from the `didDoc` and `theirDidDoc` properties from the connection record, updates them to did documents compliant with the did core spec, and stores them in the did repository. By doing so it also updates the unqualified dids in the `did` and `theirDid` fields generated by the indy-sdk to fully qualified `did:peer` dids compliant with the [Peer DID Method Specification](https://identity.foundation/peer-did-method-spec/).
+
+To account for the fact that the mechanism to migrate legacy did document to peer did documents is not defined yet, the legacy did and did document are stored in the did record metadata. This will be deleted later if we can be certain the did doc conversion to a `did:peer` did document is correct.
+
+The following 0.1.0 connection record structure (unrelated keys omitted):
+
+```json
+{
+  "did": "BBPoJqRKatdcfLEAFL7exC",
+  "theirDid": "N8NQHLtCKfPmWMgCSdfa7h",
+  "didDoc": <legacyDidDoc>,
+  "theirDidDoc": <legacyTheirDidDoc>,
+}
+```
+
+Will be transformed into the following 0.2.0 structure (unrelated keys omitted):
+
+```json
+{
+  "did": "did:peer:1zQmXUaPPhPCbUVZ3hGYmQmGxWTwyDfhqESXCpMFhKaF9Y2A",
+  "theirDid": "did:peer:1zQmZMygzYqNwU6Uhmewx5Xepf2VLp5S4HLSwwgf2aiKZuwa"
+}
+```
+
+### Migrating to the Out of Band Record
+
+With the addition of the out of band protocol, invitations are now stored in the `OutOfBandRecord`. In addition a new field `invitationDid` is added to the connection record that is generated based on the invitation service or did. This allows to reuse existing connections.
+
+The migration script extracts the invitation and other relevant data into a separate `OutOfBandRecord`. By doing so it converts the old connection protocol invitation into the new Out of band invitation message. Based on the service or did of the invitation, the `invitationDid` is populated.
+
+The following 0.1.0 connection record structure (unrelated keys omitted):
+
+```json
+{
+  "invitation": {
+    "@type": "https://didcomm.org/connections/1.0/invitation",
+    "@id": "04a2c382-999e-4de9-a1d2-9dec0b2fa5e4",
+    "recipientKeys": ["E6D1m3eERqCueX4ZgMCY14B4NceAr6XP2HyVqt55gDhu"],
+    "serviceEndpoint": "https://example.com",
+    "label": "test"
+  }
+}
+```
+
+Will be transformed into the following 0.2.0 structure (unrelated keys omitted):
+
+```json
+{
+  "invitationDid": "did:peer:2.Ez6MksYU4MHtfmNhNm1uGMvANr9j4CBv2FymjiJtRgA36bSVH.SeyJzIjoiaHR0cHM6Ly9leGFtcGxlLmNvbSJ9",
+  "outOfBandId": "04a2c382-999e-4de9-a1d2-9dec0b2fa5e4"
+}
+```
+
+### Unifying Connection States and Roles
+
+With the addition of the did exchange protocol there are now two states and roles related to the connection record; for the did exchange protocol and for the connection protocol. To keep it easy to work with the connection record, all state and role values are updated to those of the `DidExchangeRole` and `DidExchangeState` enums.
+
+The migration script transforms all connection record state and role values to their respective values of the `DidExchangeRole` and `DidExchangeState` enums. For convenience a getter
+property `rfc0160ConnectionState` is added to the connection record which returns the `ConnectionState` value.
+
+The following 0.1.0 connection record structure (unrelated keys omitted):
+
+```json
+{
+  "state": "invited",
+  "role": "inviter"
+}
+```
+
+Will be transformed into the following 0.2.0 structure (unrelated keys omitted):
+
+```json
+{
+  "state": "invitation-sent",
+  "role": "responder"
+}
+```

packages/core/src/agent/Agent.ts

@@ -20,6 +20,7 @@ import { CredentialsModule } from '../modules/credentials/CredentialsModule'
 import { DidsModule } from '../modules/dids/DidsModule'
 import { DiscoverFeaturesModule } from '../modules/discover-features'
 import { LedgerModule } from '../modules/ledger/LedgerModule'
+import { OutOfBandModule } from '../modules/oob/OutOfBandModule'
 import { ProofsModule } from '../modules/proofs/ProofsModule'
 import { MediatorModule } from '../modules/routing/MediatorModule'
 import { RecipientModule } from '../modules/routing/RecipientModule'
@@ -61,6 +62,7 @@ export class Agent {
   public readonly discovery: DiscoverFeaturesModule
   public readonly dids: DidsModule
   public readonly wallet: WalletModule
+  public readonly oob!: OutOfBandModule
 
   public constructor(
     initialConfig: InitConfig,
@@ -123,13 +125,14 @@ export class Agent {
     this.discovery = this.container.resolve(DiscoverFeaturesModule)
     this.dids = this.container.resolve(DidsModule)
     this.wallet = this.container.resolve(WalletModule)
+    this.oob = this.container.resolve(OutOfBandModule)
 
     // Listen for new messages (either from transports or somewhere else in the framework / extensions)
     this.messageSubscription = this.eventEmitter
       .observable<AgentMessageReceivedEvent>(AgentEventTypes.AgentMessageReceived)
       .pipe(
         takeUntil(this.agentConfig.stop$),
-        concatMap((e) => this.messageReceiver.receiveMessage(e.payload.message))
+        concatMap((e) => this.messageReceiver.receiveMessage(e.payload.message, { connection: e.payload.connection }))
       )
       .subscribe()
   }
@@ -224,7 +227,9 @@ export class Agent {
     // Also requests mediation ans sets as default mediator
     // Because this requires the connections module, we do this in the agent constructor
     if (mediatorConnectionsInvite) {
-      await this.mediationRecipient.provision(mediatorConnectionsInvite)
+      this.logger.debug('Provision mediation with invitation', { mediatorConnectionsInvite })
+      const mediatonConnection = await this.getMediationConnection(mediatorConnectionsInvite)
+      await this.mediationRecipient.provision(mediatonConnection)
     }
 
     await this.mediationRecipient.initialize()
@@ -254,7 +259,7 @@ export class Agent {
   }
 
   public async receiveMessage(inboundMessage: unknown, session?: TransportSession) {
-    return await this.messageReceiver.receiveMessage(inboundMessage, session)
+    return await this.messageReceiver.receiveMessage(inboundMessage, { session })
   }
 
   public get injectionContainer() {
@@ -264,4 +269,33 @@ export class Agent {
   public get config() {
     return this.agentConfig
   }
+
+  private async getMediationConnection(mediatorInvitationUrl: string) {
+    const outOfBandMessage = await this.oob.parseInvitation(mediatorInvitationUrl)
+    const outOfBandRecord = await this.oob.findByMessageId(outOfBandMessage.id)
+    const connection = outOfBandRecord && (await this.connections.findByOutOfBandId(outOfBandRecord.id))
+
+    if (!connection) {
+      this.logger.debug('Mediation connection does not exist, creating connection')
+      // We don't want to use the current default mediator when connecting to another mediator
+      const routing = await this.mediationRecipient.getRouting({ useDefaultMediator: false })
+
+      this.logger.debug('Routing created', routing)
+      const { connectionRecord: newConnection } = await this.oob.receiveInvitation(outOfBandMessage, {
+        routing,
+      })
+      this.logger.debug(`Mediation invitation processed`, { outOfBandMessage })
+
+      if (!newConnection) {
+        throw new AriesFrameworkError('No connection record to provision mediation.')
+      }
+
+      return this.connections.returnWhenIsConnected(newConnection.id)
+    }
+
+    if (!connection.isReady) {
+      return this.connections.returnWhenIsConnected(connection.id)
+    }
+    return connection
+  }
 }

packages/core/src/agent/Dispatcher.ts

@@ -60,8 +60,8 @@ class Dispatcher {
         this.logger.error(`Error handling message with type ${message.type}`, {
           message: message.toJSON(),
           error,
-          senderVerkey: messageContext.senderVerkey,
-          recipientVerkey: messageContext.recipientVerkey,
+          senderKey: messageContext.senderKey,
+          recipientKey: messageContext.recipientKey,
           connectionId: messageContext.connection?.id,
         })
 

packages/core/src/agent/EnvelopeService.ts

@@ -1,23 +1,25 @@
 import type { Logger } from '../logger'
-import type { DecryptedMessageContext, EncryptedMessage } from '../types'
+import type { EncryptedMessage, PlaintextMessage } from '../types'
 import type { AgentMessage } from './AgentMessage'
 
 import { inject, scoped, Lifecycle } from 'tsyringe'
 
 import { InjectionSymbols } from '../constants'
+import { KeyType } from '../crypto'
+import { Key } from '../modules/dids'
 import { ForwardMessage } from '../modules/routing/messages'
 import { Wallet } from '../wallet/Wallet'
 
 import { AgentConfig } from './AgentConfig'
 
 export interface EnvelopeKeys {
-  recipientKeys: string[]
-  routingKeys: string[]
-  senderKey: string | null
+  recipientKeys: Key[]
+  routingKeys: Key[]
+  senderKey: Key | null
 }
 
 @scoped(Lifecycle.ContainerScoped)
-class EnvelopeService {
+export class EnvelopeService {
   private wallet: Wallet
   private logger: Logger
   private config: AgentConfig
@@ -29,38 +31,50 @@ class EnvelopeService {
   }
 
   public async packMessage(payload: AgentMessage, keys: EnvelopeKeys): Promise<EncryptedMessage> {
-    const { routingKeys, senderKey } = keys
-    let recipientKeys = keys.recipientKeys
+    const { recipientKeys, routingKeys, senderKey } = keys
+    let recipientKeysBase58 = recipientKeys.map((key) => key.publicKeyBase58)
+    const routingKeysBase58 = routingKeys.map((key) => key.publicKeyBase58)
+    const senderKeyBase58 = senderKey && senderKey.publicKeyBase58
 
     // pass whether we want to use legacy did sov prefix
     const message = payload.toJSON({ useLegacyDidSovPrefix: this.config.useLegacyDidSovPrefix })
 
     this.logger.debug(`Pack outbound message ${message['@type']}`)
 
-    let encryptedMessage = await this.wallet.pack(message, recipientKeys, senderKey ?? undefined)
+    let encryptedMessage = await this.wallet.pack(message, recipientKeysBase58, senderKeyBase58 ?? undefined)
 
     // If the message has routing keys (mediator) pack for each mediator
-    for (const routingKey of routingKeys) {
+    for (const routingKeyBase58 of routingKeysBase58) {
       const forwardMessage = new ForwardMessage({
         // Forward to first recipient key
-        to: recipientKeys[0],
+        to: recipientKeysBase58[0],
         message: encryptedMessage,
       })
-      recipientKeys = [routingKey]
+      recipientKeysBase58 = [routingKeyBase58]
       this.logger.debug('Forward message created', forwardMessage)
 
       const forwardJson = forwardMessage.toJSON({ useLegacyDidSovPrefix: this.config.useLegacyDidSovPrefix })
 
       // Forward messages are anon packed
-      encryptedMessage = await this.wallet.pack(forwardJson, [routingKey], undefined)
+      encryptedMessage = await this.wallet.pack(forwardJson, [routingKeyBase58], undefined)
     }
 
     return encryptedMessage
   }
 
   public async unpackMessage(encryptedMessage: EncryptedMessage): Promise<DecryptedMessageContext> {
-    return this.wallet.unpack(encryptedMessage)
+    const decryptedMessage = await this.wallet.unpack(encryptedMessage)
+    const { recipientKey, senderKey, plaintextMessage } = decryptedMessage
+    return {
+      recipientKey: recipientKey ? Key.fromPublicKeyBase58(recipientKey, KeyType.Ed25519) : undefined,
+      senderKey: senderKey ? Key.fromPublicKeyBase58(senderKey, KeyType.Ed25519) : undefined,
+      plaintextMessage,
+    }
   }
 }
 
-export { EnvelopeService }
+export interface DecryptedMessageContext {
+  plaintextMessage: PlaintextMessage
+  senderKey?: Key
+  recipientKey?: Key
+}

packages/core/src/agent/Events.ts

@@ -15,6 +15,7 @@ export interface AgentMessageReceivedEvent extends BaseEvent {
   type: typeof AgentEventTypes.AgentMessageReceived
   payload: {
     message: unknown
+    connection?: ConnectionRecord
   }
 }