The reference implementation of the Nuts specification. A decentralized identity network based on the w3c ssi concepts with practical functionality for the healthcare domain.
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
commented
3 months ago
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:
VDR v2 API
This API can be removed entirely.
Auth v2 API
Requires changes.
Request Service Access Token
requesterparameter, currently a DID, needs to be passed the wallet ID instead. We can always add aoneOfwithrequester_did(or support both forms for the parameter) if parties wish to use a specific DID.createDPoP(which requires the DID) can be used. Priority: Must HaveDiscovery 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).