feat: did rotate

[genaris]

Adds support for Aries RFC 0794.

API changes in Connections module are quite simple:

• rotate: given a connection id, rotate our did to a new one. We can specify an external did (that we control) or create a peer did (did:peer:4 by default). Routing setting can be also set.
  Former and new dids' keys will be marked as tags for the connection, in order to accept messages that may be received out of order (e.g. a message using previous keys after receiving the acknowledge)
• hangup: It will terminate a connection. Can also delete it (and remove any mediation key). If not deleted (default behaviour), it will still be able to receive messages but will not allow to send messages through it

There are also some fixes related to the changes introduced in #1550, related to cases where external dids are specified.

For the moment, when a rotation is being done, previous dids related to the connection are not removed, meaning that it is still possible to receive messages using former keys. There is a new API method called removePreviousDids that allows to explicitly remove any previous did associated to a given connection.

We should also consider that the keys related to dids are not actually being deleted from the wallet (this is something pending from general connection deletion flows), which is something that certainly would be nice to add in a further PR.

[swcurran]

FYI @dbluhm @Jsyro

[dbluhm]

Just to comment on what I think we'll end up doing in ACA-Py on the question of when to delete keys, ACA-Py has a cache for mapping from inbound keys to a did then to a connection. The cache has a TTL of one hour by default. So I think we'll commit the changes immediately and then let the cache handle any potentially straggling out-of-order messages. We'll see how that works out in implementation.

[TimoGlastra]

No blockers, just some nits

[TimoGlastra]

Do we also want to create routing when we have a toDid specified?

[genaris]

If toDid is specified, routing is disallowed (the same thing as we did in #1550).

[TimoGlastra]

Yes if routing is not provided we will go to || (await this.routingService.getRouting(this.agentContext, {})),, so it willl still be generated right? I think we shouldn't call getRouting in this case

[genaris]

I'm under a heavy jetlag right now but I think that case will not happen, as a few lines before that we have:

if (toDid && routing) {
      throw new AriesFrameworkError(`'routing' is disallowed when defining 'did'`)
    }

[TimoGlastra]

Yes but if routing is not defined, this will not throw an error. Then later on it will do routing || (await this.routingService.getRouting(this.agentContext, {})). Routing will never be defined when toDid is defined, so that will mean it will call this.routingService.

I think || (await this.routingService.getRouting(this.agentContext, {})) should ONLY be called if toDid is not defined.

if (toDid && routing) {
  throw new AriesFrameworkError(`'routing' is disallowed when defining 'did'`)
}

let routingToUse = routing
if (!toDid && !routing) {
  routingToUse = await this.routingService.getRouting(this.agentContext, {})
}

[TimoGlastra]

Maybe I'm missing something here, but I think your influenced by the jetlag 😅

[genaris]

Ooh I see. It is creating an unnecessary routing 🤦. Thanks for the explanation, I think I should have some rest 😄.

[TimoGlastra]

Should the did doc also be removed? Once we support dids othee than did:peer we will need to update this probably as you may not want to remove your public did (we could pass in a method array or something?)

removePreviousDids({ methods: ['key', 'peer', 'jwk'] })

[genaris]

For the moment the method is only intended to remove the relationship between the connection and its previous dids, meaning that records will not be deleted. This is actually the same thing that happens when we delete a connection.

IMHO we should revisit this process in order to clean up the underlying keys as well, but as you say, now we are supporting more DID methods and flows we should carefully analyze when this data is safe to be removed.