Document that endpoint instances have specific behaviour by default, but can have options

[msporny]

The group discussed this on 2024-09-10:

The specification needs to elaborate that endpoint instances are configured in a ways that perform a concrete set of steps when called. Implementers can add options to the call to change the default behavior of the endpoint. A particular workflow can be configured to have access to multiple issuer instances and can choose which one to use based on options provided to protocol used in an exchange w/ a particular exchange client aka digital wallet. Each protocol that is used on trust boundary expresses information in different way, up to workflow to make sure that it's configured against is appropriately expressed when client makes a choice. Workflow maps into config on what it can do. Keep configurations simple and allow configs to be composed according to a business use case.

A PR needs to be raised that accomplishes the goals above.

[dlongley]

Some outline text that might be helpful here:

• In order to keep services simple, they are composed of "instances", each of which is configured by an administrator for a specific use and access to that specific instance is then given to a coordinator system. This approach enables service software to be written such that it doesn't need to support a (potentially ever growing) number of combinations of options that a client might send, i.e., options for the key to use to sign, the format to use, the various types of credential status – and all of its own options – to use, individual claims, message digest algorithms, cryptographic suites – and so on.

• Not every combination of options will even be viable or could produce various second order problems such as privacy violations, i.e., generating too many status lists for a population of VC holders, interoperability problems because VC status lists are signed with a type of cryptography that is incompatible with the VCs it tracks state for, accidental use of one key for the wrong type of VCs, and so on. By creating specific configurations and isolating them – and handing them off to specific coordinators for specific use cases helps avoid these problems and simplify the validation process (indeed, eliminate much of it) at services.

• The privileges granted to coordinator systems can also be made more appropriate, limiting them to only the power they need, i.e., giving an issuer coordinator authorization to only use a particular workflow that is preconfigured with a particular set of VC templates that require certain variables to be provided; no other VCs can be issued through the coordinator by accident or by adversary.

• There is no need for runtime discovery of available options for coordinators by "searching for a service/instance to use", rather, coordinators are built around business logic with specific requirements and goals and this can be matched against specifically provisioned instances (by administrators) to meet those goals. There's no "guessing" whether a particular secret key / capability to use a secret key associated with a verification method will be available – and this information doesn't even need to be known to a coordinator in most cases, i.e., it should be an encapsulated/hidden away detail of the instance exposed to the coordinator. The coordinator's interface into issuing/verifying VCs should instead be "workflows" designed and provisioned for specific business use cases matching what the coordinator needs to accomplish; the details of key management, etc. can be hidden away and handled by appropriate parties, i.e., a website or the repository for it should not be involved in key management, only in specifying the workflow instances to be used to accomplish the goals / forward the purpose of the website.

• Different protocols that might be used with a VC API exchange (e.g., VC API exchange, OID4*, DIDComm) specify options in different ways, and it is the responsibility of a given workflow service to map those to, for example, configured issuer instances – and to expose what it supports appropriately in whatever given protocol is chosen by the exchange client.

[jrhender]

Some notes on this issue as I work on the related PR (#426):

1. On this point from @dlongley's previous post:

Different protocols that might be used with a VC API exchange (e.g., VC API exchange, OID4*, DIDComm) specify options in different ways

I think there is text in the workflows section of the spec relates to this: "The request body can also include configuration options to enable the exchange to be executed using additional protocols beyond VC API."

2. On this point from @dlongley's previous post:

The coordinator's interface into issuing/verifying VCs should instead be "workflows" designed and provisioned for specific business use cases matching what the coordinator needs to accomplish;

I think this might be at odds with the current VC API architecture as the current architecture expects that issuer and verifier services are called from the respective coordinators. I think that the above text implies that issuer and verifier coordinators should rather interface with the workflow services and the workflow services should interface with the issuer and verifier coordinators.