[proposal] Define a credential revocation API

[mirceanis]

We need a plugin interface for the credential revocation frontend.

At this time, there are 2 foreseeable actions that this interface should perform:

• One is a call to revoke a credential. Probably this interface will be implemented by an aggregator that can look at a credential that is about to be revoked, inspect the credentialStatus entry and then forward the revocation call to the actual credentialStatus driver.

• The other (which may be optional?) is a call that a Credential Issuer might make to build a credentialStatus entry.
  Many credentialStatus methods work on collections of credentials, so it is likely that when a credential is being created it needs to know its place in the collection (its index, its merkle path, etc)

This task only refers to the interface for such a plugin, and should initially serve as a discussion board.

[italobb]

In the picture below, in yellow, we have the current components already implemented when we talk about credential revocation/status in Veramo. In green, a proposal for the components we should build to allow two initial revocation methods: one using local storage (it can implement Revocation List 2020 or a simpler spec) and another one using an EVM network (following the ethr-status-registry).

Here is a brief explanation about each component in the diagram:

• credential-revocation: implements the interface mentioned by @mirceanis for the revocation and delegates their implementation to plugin specific for each revocation method.
• revocation-plugin: an interface for revocation methods plugins.
• revocation-eth: a revocation plugin which uses the ethr-status-registry spec.
• revocation-local: a revocation plugin which uses Revocation List 2020 or a simpler method for revocation, storing the status using the agent data-store. This component, exceptionally, will also be used by the agent to serve the endpoint used in credentialStatus field of the VCs using the revocation method chosen.
• credential-status-eth: a library which implements the status verification using ethr-status-registry.
• revocation-eth: a library which implements the revocation of VCs using the ethr-status-registry.

As suggested by @mirceanis, the credential-revocation will expose 2 main endpoints:

• revoke
  • Params:
    • vc: a reference to the VC to be revoked.
    • method: a reference to the revocation method to be used
    • method-params (optional): a JSON object with the revocation method params, if necessary.
  • Return:
    • The updated revocation status
• metadata
  • Params:
    • method: a reference to the revocation method
  • Return:
    • A JSON describing the params for the revocation method (the params received as input in revoke.method-params).

The revocation-local plugin will additionally implement the endpoint referenced in the credentialStatus field of the VCs using the method Revocation List 2020 or a simpler one TBD in this discussion:

• status
  • Params:
    • vc: a reference to the VC to be revoked.
  • Return:
    • The credential status. In case we decide to use Revocation List 2020, it'll be the a VC following the RevocationList2020Credential schema.

In addition to a feedback regarding this proposal, it would be nice to understand if there are more revocation methods already specified and implemented in libraries which we could plug or adopt, mainly for the local (initial) implementation.

[mirceanis]

@italobb, kudos for all the details!

Some notes:

• revoke - doesn't need the method parameter, since the method should be embedded already in the vc. The method-params are probably required, and will depend on the method. These parameters would be forwarded to the underlying revocation driver. Perhaps a more generic name like options is more appropriate here.
  I think the return type should be something that can accommodate multiple types of revocation methods, so returning the status directly might be too much to expect. For example, if the update requires a transaction to be processed by a blockchain, it's unreasonable to await for a status since that might take days. Some flexibility is required here too, so a result object stating that the revocation request was processed successfully might be more appropriate.

Example:

result: {
  success: true, // mandatory property of the result for successful processing
  error: undefined, // mandatory property of the result for error during processing
  txHash: `0x0a359d...` // optional details provided by the revocation driver specific to the revocation method
}

• metadata - The way I understand this, it would be the method that generates the credentialStatus property that would be embedded in a VC. This is the chance of the revocation driver to specify the coordinates of the credentialStatus method. In that case I think that a name like credentialStatusGenerate might be more descriptive and help with API discovery. Please correct me if I misunderstood.

---

Naming is hard.
Since these endpoints are supposed to be agent plugin interface methods, it makes sense to give them more specific names, with a namespace included, to avoid confusion and collisions down the line:

• revoke -> credentialStatusUpdate - updates the status of an existing credential
• metadata -> credentialStatusGenerate - generates the credentialStatus property for future credentials

• status -> credentialStatusRead - not part of the main interface, but implemented by the revocation-local plugin, returns the status of a particular credential, as it is known by this agent. This might not make sense for most revocation methods, since some may not even require keeping track of this state internally, or some may not support querying for a single credential.

[italobb]

@mirceanis I liked all suggestions, including the naming. Your understanding about the metadata was wrong, but I realized that the endpoint to query the parameters for a revocation method doesn't make sense. So, the credentialStatusGenerate is fine. Actually we'll need an endpoint to list the supported revocation methods in the agent.

So, we would have something like:

• credentialStatusUpdate - updates the status of an existing credential
  • Params:
    • vc: a reference to the VC to be revoked.
    • options (optional): a JSON object with the revocation method specific params, if necessary.
  • Return:
    • result: JSON object
      • success: boolean telling if the request was successfully processed (doesn't mean the revocation was completed yet)
      • error: string with error details.
      • details: JSON with optional details provided by the revocation driver specific to the revocation method.
• credentialStatusGenerate - generates the credentialStatus property for future credentials
  • Params:
    • method: The name of the revocation method
    • options (optional): parameters specific to the revocation method
  • Return:
    • credentialStatus : the credentialStatus property for future credentials
• credentialStatusRead : returns the status of a particular credential, as it is known by this agent.
• credentialStatusListMethods: returns the list of revocation methods supported by the agent.

[Eengineer1]

Hey, @italobb @mirceanis .

Keen on helping with this.
A few questions:

• Have any implementations started on this?
• What's the bandwidth, if yes?

[italobb]

Hi, @Eengineer1!
I'm currently writing the interfaces we just described here and planning the implementation of the components for next Veramo version. It's the right time to have you joining!
Do you have something specific you want to collaborate on? It would be nice to get together to plan. Could you please get in touch with me through the Veramo Discord channel, please?

[Eengineer1]

@italobb Thanks!
You have PM.