feat: 0.2.0 migration script for connections (#773)

Signed-off-by: Timo Glastra <timo@animo.id>

Author: TimoGlastra

docs/migration/0.1-to-0.2.md

@@ -73,3 +73,89 @@ 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": "UppcJ5APts7ot5WX25943F",
+  "verkey": "GAb4NUvpBcHVCvtP45vTVa5Bp74vFg3iXzdp1Gbd68Wf",
+  "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.
+
+Previously when creating a multi use invitation, a connection record would be created with the `multiUseInvitation` set to true. The connection record would always be in state `invited`. If a request for the multi use invitation came in, a new connection record would be created. With the addition of the out of band module, no connection records are created until a request is received. So for multi use invitation this means that the connection record with multiUseInvitation=true will be deleted, and instead all connections created using that out of band invitation will contain the `outOfBandId` of the multi use invitation.
+
+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"
+  },
+  "multiUseInvitation": "false"
+}
+```
+
+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/MessageReceiver.ts

@@ -10,7 +10,6 @@ import { Lifecycle, scoped } from 'tsyringe'
 
 import { AriesFrameworkError } from '../error'
 import { ConnectionsModule } from '../modules/connections'
-import { OutOfBandService } from '../modules/oob/OutOfBandService'
 import { ProblemReportError, ProblemReportMessage, ProblemReportReason } from '../modules/problem-reports'
 import { isValidJweStructure } from '../utils/JWE'
 import { JsonTransformer } from '../utils/JsonTransformer'
@@ -35,23 +34,20 @@ export class MessageReceiver {
   private logger: Logger
   private connectionsModule: ConnectionsModule
   public readonly inboundTransports: InboundTransport[] = []
-  private outOfBandService: OutOfBandService
 
   public constructor(
     config: AgentConfig,
     envelopeService: EnvelopeService,
     transportService: TransportService,
     messageSender: MessageSender,
     connectionsModule: ConnectionsModule,
-    outOfBandService: OutOfBandService,
     dispatcher: Dispatcher
   ) {
     this.config = config
     this.envelopeService = envelopeService
     this.transportService = transportService
     this.messageSender = messageSender
     this.connectionsModule = connectionsModule
-    this.outOfBandService = outOfBandService
     this.dispatcher = dispatcher
     this.logger = this.config.logger
   }
@@ -96,7 +92,6 @@ export class MessageReceiver {
     )
 
     const connection = await this.findConnectionByMessageKeys(decryptedMessage)
-    const outOfBand = (recipientKey && (await this.outOfBandService.findByRecipientKey(recipientKey))) || undefined
 
     const message = await this.transformAndValidate(plaintextMessage, connection)
 
@@ -126,7 +121,6 @@ export class MessageReceiver {
       // with mediators when you don't have a public endpoint yet.
       session.connection = connection ?? undefined
       messageContext.sessionId = session.id
-      session.outOfBand = outOfBand
       this.transportService.saveSession(session)
     } else if (session) {
       // No need to wait for session to stay open if we're not actually going to respond to the message.

packages/core/src/agent/MessageSender.ts

@@ -189,9 +189,7 @@ export class MessageSender {
     }
     if (!session) {
       // Try to send to already open session
-      session =
-        this.transportService.findSessionByConnectionId(connection.id) ||
-        (outOfBand && this.transportService.findSessionByOutOfBandId(outOfBand.id))
+      session = this.transportService.findSessionByConnectionId(connection.id)
     }
 
     if (session?.inboundMessage?.hasReturnRouting(payload.threadId)) {

packages/core/src/agent/TransportService.ts

@@ -1,6 +1,5 @@
 import type { ConnectionRecord } from '../modules/connections/repository'
 import type { DidDocument } from '../modules/dids'
-import type { OutOfBandRecord } from '../modules/oob/repository'
 import type { EncryptedMessage } from '../types'
 import type { AgentMessage } from './AgentMessage'
 import type { EnvelopeKeys } from './EnvelopeService'
@@ -21,10 +20,6 @@ export class TransportService {
     return Object.values(this.transportSessionTable).find((session) => session?.connection?.id === connectionId)
   }
 
-  public findSessionByOutOfBandId(outOfBandId: string) {
-    return Object.values(this.transportSessionTable).find((session) => session?.outOfBand?.id === outOfBandId)
-  }
-
   public hasInboundEndpoint(didDocument: DidDocument): boolean {
     return Boolean(didDocument.service?.find((s) => s.serviceEndpoint !== DID_COMM_TRANSPORT_QUEUE))
   }
@@ -48,7 +43,6 @@ export interface TransportSession {
   keys?: EnvelopeKeys
   inboundMessage?: AgentMessage
   connection?: ConnectionRecord
-  outOfBand?: OutOfBandRecord
   send(encryptedMessage: EncryptedMessage): Promise<void>
   close(): Promise<void>
 }

packages/core/src/modules/connections/DidExchangeProtocol.ts

@@ -87,7 +87,6 @@ export class DidExchangeProtocol {
       alias,
       state: DidExchangeState.InvitationReceived,
       theirLabel: outOfBandInvitation.label,
-      multiUseInvitation: false,
       did,
       mediatorId,
       autoAcceptConnection: outOfBandRecord.autoAcceptConnection,
@@ -200,7 +199,6 @@ export class DidExchangeProtocol {
       protocol: HandshakeProtocol.DidExchange,
       role: DidExchangeRole.Responder,
       state: DidExchangeState.RequestReceived,
-      multiUseInvitation: false,
       did,
       mediatorId,
       autoAcceptConnection: outOfBandRecord.autoAcceptConnection,
@@ -314,7 +312,7 @@ export class DidExchangeProtocol {
 
     const didDocument = await this.extractDidDocument(
       message,
-      outOfBandRecord.getRecipientKeys().map((key) => key.publicKeyBase58)
+      outOfBandRecord.outOfBandInvitation.getRecipientKeys().map((key) => key.publicKeyBase58)
     )
     const didRecord = new DidRecord({
       id: message.did,

packages/core/src/modules/connections/__tests__/ConnectionService.test.ts

@@ -228,7 +228,6 @@ describe('ConnectionService', () => {
         id: 'test',
         state: DidExchangeState.InvitationSent,
         role: DidExchangeRole.Responder,
-        multiUseInvitation: true,
       })
 
       const theirDid = 'their-did'

packages/core/src/modules/connections/models/did/__tests__/diddoc.json

@@ -1,5 +1,5 @@
 {
-  "@context": "https: //w3id.org/did/v1",
+  "@context": "https://w3id.org/did/v1",
   "id": "did:sov:LjgpST2rjsoxYegQDRm7EL",
   "publicKey": [
     {

packages/core/src/modules/connections/repository/ConnectionRecord.ts

@@ -19,7 +19,6 @@ export interface ConnectionRecordProps {
   threadId?: string
   tags?: CustomConnectionTags
   imageUrl?: string
-  multiUseInvitation?: boolean
   mediatorId?: string
   errorMessage?: string
   protocol?: HandshakeProtocol
@@ -36,6 +35,7 @@ export type DefaultConnectionTags = {
   did: string
   theirDid?: string
   outOfBandId?: string
+  invitationDid?: string
 }
 
 export class ConnectionRecord
@@ -53,7 +53,6 @@ export class ConnectionRecord
   public alias?: string
   public autoAcceptConnection?: boolean
   public imageUrl?: string
-  public multiUseInvitation!: boolean
 
   public threadId?: string
   public mediatorId?: string
@@ -82,7 +81,6 @@ export class ConnectionRecord
       this._tags = props.tags ?? {}
       this.threadId = props.threadId
       this.imageUrl = props.imageUrl
-      this.multiUseInvitation = props.multiUseInvitation || false
       this.mediatorId = props.mediatorId
       this.errorMessage = props.errorMessage
       this.protocol = props.protocol

packages/core/src/modules/connections/repository/__tests__/ConnectionRecord.test.ts

@@ -0,0 +1,30 @@
+import { DidExchangeRole, DidExchangeState } from '../../models'
+import { ConnectionRecord } from '../ConnectionRecord'
+
+describe('ConnectionRecord', () => {
+  describe('getTags', () => {
+    it('should return default tags', () => {
+      const connectionRecord = new ConnectionRecord({
+        state: DidExchangeState.Completed,
+        role: DidExchangeRole.Requester,
+        threadId: 'a-thread-id',
+        mediatorId: 'a-mediator-id',
+        did: 'a-did',
+        theirDid: 'a-their-did',
+        outOfBandId: 'a-out-of-band-id',
+        invitationDid: 'a-invitation-did',
+      })
+
+      expect(connectionRecord.getTags()).toEqual({
+        state: DidExchangeState.Completed,
+        role: DidExchangeRole.Requester,
+        threadId: 'a-thread-id',
+        mediatorId: 'a-mediator-id',
+        did: 'a-did',
+        theirDid: 'a-their-did',
+        outOfBandId: 'a-out-of-band-id',
+        invitationDid: 'a-invitation-did',
+      })
+    })
+  })
+})

packages/core/src/modules/connections/services/ConnectionService.ts

@@ -2,7 +2,6 @@ import type { AgentMessage } from '../../../agent/AgentMessage'
 import type { InboundMessageContext } from '../../../agent/models/InboundMessageContext'
 import type { Logger } from '../../../logger'
 import type { AckMessage } from '../../common'
-import type { DidDocument } from '../../dids'
 import type { OutOfBandDidCommService } from '../../oob/domain/OutOfBandDidCommService'
 import type { OutOfBandRecord } from '../../oob/repository'
 import type { ConnectionStateChangedEvent } from '../ConnectionEvents'
@@ -26,6 +25,7 @@ import { DidDocumentRole } from '../../dids/domain/DidDocumentRole'
 import { didKeyToVerkey } from '../../dids/helpers'
 import { didDocumentJsonToNumAlgo1Did } from '../../dids/methods/peer/peerDidNumAlgo1'
 import { DidRepository, DidRecord } from '../../dids/repository'
+import { DidRecordMetadataKeys } from '../../dids/repository/didRecordMetadataTypes'
 import { OutOfBandRole } from '../../oob/domain/OutOfBandRole'
 import { OutOfBandState } from '../../oob/domain/OutOfBandState'
 import { ConnectionEventTypes } from '../ConnectionEvents'
@@ -112,14 +112,13 @@ export class ConnectionService {
       did,
       mediatorId,
       autoAcceptConnection: config?.autoAcceptConnection,
-      multiUseInvitation: false,
       outOfBandId: outOfBandRecord.id,
       invitationDid,
     })
 
     const { did: peerDid } = await this.createDid({
       role: DidDocumentRole.Created,
-      didDocument: convertToNewDidDocument(didDoc),
+      didDoc,
     })
 
     const { label, imageUrl, autoAcceptConnection } = config
@@ -172,15 +171,14 @@ export class ConnectionService {
       protocol: HandshakeProtocol.Connections,
       role: DidExchangeRole.Responder,
       state: DidExchangeState.RequestReceived,
-      multiUseInvitation: false,
       did,
       mediatorId,
       autoAcceptConnection: outOfBandRecord.autoAcceptConnection,
     })
 
     const { did: peerDid } = await this.createDid({
       role: DidDocumentRole.Received,
-      didDocument: convertToNewDidDocument(message.connection.didDoc),
+      didDoc: message.connection.didDoc,
     })
 
     connectionRecord.theirDid = peerDid
@@ -234,7 +232,7 @@ export class ConnectionService {
 
     const { did: peerDid } = await this.createDid({
       role: DidDocumentRole.Created,
-      didDocument: convertToNewDidDocument(didDoc),
+      didDoc,
     })
 
     const connection = new Connection({
@@ -333,7 +331,7 @@ export class ConnectionService {
 
     const { did: peerDid } = await this.createDid({
       role: DidDocumentRole.Received,
-      didDocument: convertToNewDidDocument(connection.didDoc),
+      didDoc: connection.didDoc,
     })
 
     connectionRecord.theirDid = peerDid
@@ -619,7 +617,6 @@ export class ConnectionService {
     mediatorId?: string
     theirLabel?: string
     autoAcceptConnection?: boolean
-    multiUseInvitation: boolean
     tags?: CustomConnectionTags
     imageUrl?: string
     protocol?: HandshakeProtocol
@@ -635,7 +632,6 @@ export class ConnectionService {
       theirLabel: options.theirLabel,
       autoAcceptConnection: options.autoAcceptConnection,
       imageUrl: options.imageUrl,
-      multiUseInvitation: options.multiUseInvitation,
       mediatorId: options.mediatorId,
       protocol: options.protocol,
       outOfBandId: options.outOfBandId,
@@ -645,7 +641,10 @@ export class ConnectionService {
     return connectionRecord
   }
 
-  private async createDid({ role, didDocument }: { role: DidDocumentRole; didDocument: DidDocument }) {
+  private async createDid({ role, didDoc }: { role: DidDocumentRole; didDoc: DidDoc }) {
+    // Convert the legacy did doc to a new did document
+    const didDocument = convertToNewDidDocument(didDoc)
+
     const peerDid = didDocumentJsonToNumAlgo1Did(didDocument.toJSON())
     didDocument.id = peerDid
     const didRecord = new DidRecord({
@@ -659,6 +658,13 @@ export class ConnectionService {
       },
     })
 
+    // Store the unqualified did with the legacy did document in the metadata
+    // Can be removed at a later stage if we know for sure we don't need it anymore
+    didRecord.metadata.set(DidRecordMetadataKeys.LegacyDid, {
+      unqualifiedDid: didDoc.id,
+      didDocumentString: JsonTransformer.serialize(didDoc),
+    })
+
     this.logger.debug('Saving DID record', {
       id: didRecord.id,
       role: didRecord.role,