Introduce "wallet" entity as primary handle for applications to interact with

[reinkrul]

Given the wish to support different DID methods and problems resulting from migration, we should decouple the primary application API from the DID that is used for transactions. Because, a DID represents an entity in the real world (e.g., a user, organization, or a system). Otherwise, the application that integrates with the Nuts node ("vendor") will have to migrate their administration of entity to DID mapping every time a newer/better DID is implemented.

By adding a "wallet" concept to the Nuts node with accompanying APIs, applications don't need to refer to a concrete DID, but the Nuts node can choose the right DID in the right circumstances. This way, a wallet can also hold multiple DIDs, which is usable for migration to newer DID methods, supporting cases where the remote party supports a subset of DID methods or for preserving privacy.

This, however, is a big change and has the following impact:

Wallet API

We must introduce a new wallet API that is used to manage a wallet.

Create

Used to create a new wallet. A new DID is created and associated with the wallet. The Nuts node has an ordered list of preferred DID methods.

Input: nothing
Output: wallet ID
Priority: Must Have

Read

Returns the details of the wallet.

Input: wallet ID
Output: DIDs associated with the wallet, creation time
Priority: Must Have

Deactivate

Marks the wallet for deletion after the configured retention period. After that, associated DIDs are deacticated and the wallet is deleted.

Input: wallet ID
Output: date/time at which the wallet is deleted
Priority: Should Have

Activate

Restores the deactivated wallet, if the retention period hasn't passed.

Input: wallet ID
Output: nothing
Priority: Should Have

Create Service

Used to create a service on the DID documents associated with the wallet.

Input: wallet ID, new service
Output: error if it couldn't be created on one or more DID documents
Priority: Must Have

Update Service

Used to update a service on the DID documents associated with the wallet.

Input: wallet ID, service ID, updated service
Output: error if it couldn't be updated on one or more DID documents
Priority: Must Have

Delete Service

Used to delete a service from the DID documents associated with the wallet.

Input: wallet ID, service ID
Output: error if it couldn't be deleted from one or more DID documents
Priority: Must Have

Other, "Should Have" APIs:

• Create verification method
• Rotate verification method

VDR v2 API

This API can be removed entirely.

Auth v2 API

Requires changes.

Request Service Access Token

• requester parameter, currently a DID, needs to be passed the wallet ID instead. We can always add a oneOf with requester_did (or support both forms for the parameter) if parties wish to use a specific DID.
• it must return the DID that is associated with the access token, so createDPoP (which requires the DID) can be used.
  Priority: Must Have

Discovery v1 API

Requires changes.

Activate/Deactivate

Used to activate a Discovery Service for a DID. Needs to change to activating the Discovery Service for a wallet, which effectively activates the Discovery Service for all associated DIDs. The same applies to Deactivate.

Status

Used to check the activation status, needs to change to a wallet ID (returning status for all associated DIDs).

[woutslakhorst]

todo list in #3187