Re: [w3ctag/design-reviews] WG New Spec: VCALM v1.0 (Issue #1273)

kezike left a comment (w3ctag/design-reviews#1273)

Hi @hlflanagan,

Thanks for providing design feedback on the VCALM specification. To address your topline concern about “whether VCALM enables interoperability across independently developed systems or primarily within deployments that have agreed upon a particular set of technologies,” the short answer is that the VCALM specification enables both. In both cases, there are well-defined interfaces for certain HTTP requests and responses. The specification includes a table that identifies which case each API endpoint falls under (see [this table](https://w3c.github.io/vcalm/#workflow-service) as an example).

Most of the components the specification defines fall into the latter category and are intended to be used within a security boundary, with any technological options being agreed upon between the service consumer and the service provider. There are many ways to configure valid VCALM component instances and perform administrative operations on them – and administrative behavior and interfaces are left unspecified.

There are also components that are defined for interoperability across independently developed systems where communication crosses security boundaries and where there may be no preexisting relationships amongst the communicating parties.  The main API that this applies to is the [exchange participation API](https://w3c.github.io/vcalm/#participate-in-an-exchange). To participate in this API, each party needs to understand how to process a [Verifiable Presentation (VP)](https://w3c.github.io/vc-data-model/#presentations) and a [Verifiable Presentation Request (VPR)](https://w3c.github.io/vcalm/#verifiable-presentation-request), which is defined in the VCALM specification. Considering the above API design, there is a general expectation that [workflow](https://w3c.github.io/vcalm/#workflows-and-exchanges) implementations are largely interchangeable in that they are capable of producing the same exchange experience. This feature protects against vendor lock-in, in which an undesirable solution is difficult to swap out for another. Indeed, if the configurations are identical, they should have the same behaviors and side effects.

The remainder of this document will address each of your itemized concerns:

### Interoperability and configuration

Many of the requirements for cross-boundary interactions are defined in the exchange participation interface. Before an exchange client participates in an exchange, it needs to know what [protocol options](https://w3c.github.io/vcalm/#interaction-protocols-response) are available at the server for exchanging credentials. This information is discovered from an [interaction URL](https://w3c.github.io/vcalm/#initiating-interactions), which serves as a TLS-protected entry point for an interaction. Clients that support VCALM interactions *MUST* understand the format of this URL and the data that they can retrieve from it, which is explicitly defined in the specification. The use of TLS enables the client to know that the information served to continue the interaction is authentically from the origin that the client is communicating with to inquire about it. Examples of protocols that can be included are the native VCALM protocol (`vcapi`), OpenID4VCI (`oid4vci-1.0`), and DIDComm (`didcomm`). Each exchange protocol is paired with a URL that is specific to the protocol. These URLs can point at other origins, allowing delegation to external service providers with consent from the interaction URL origin that the client has confirmed via TLS.

Once a client learns of available protocols at the server, it can decide which one to use for the exchange based on support and preference. Each server *SHOULD* at least implement the native `vcapi` protocol. Importantly, the VCALM specification also defines an API that allows the relying party's system to read the state of the exchange as it completes, reducing their need to be opinionated about the offered protocols or which choice the client makes.

After a client selects a protocol for the exchange, it can start exchanging messages. For any exchange protocol other than `vcapi`, the format of subsequent messages is governed by that protocol. For the `vcapi` protocol, one of the core components of a valid message that can be delivered within an exchange - and, hence, *MUST* be understood by both parties to an exchange - is a [Verifiable Presentation Request (VPR)](https://w3c.github.io/vcalm/#verifiable-presentation-request), as noted earlier. This is the focal point of communication and expectation setting in an exchange, because it specifies the credentials that are desired (if any, including acceptable issuers and formats thereof), the credential(s) that will be offered (if any) in the exchange, and the set of cryptosuites and DID methods that the server supports, among other features. A VPR supports the ability to express queries in multiple query languages and a client can choose to read any of the languages provided based on what it supports.

For APIs that are only intended to be used within a trusted security boundary, the VCALM specification offers two non-normative options for controlling access:  [Authorization Capabilities (zcaps)](https://w3c.github.io/vcalm/#authorization-capabilities) and [OAuth 2.0](https://w3c.github.io/vcalm/#oauth-2-0). This choice enables the restriction of privileged operations to only authorized parties; these operations include workflow creation (e.g., limited to system administrators) and exchange creation (e.g., limited to [coordinators](https://w3c.github.io/vcalm/#coordinators)). Again, these are operations that should only occur within a trusted security boundary based on an existing relationship between service consumers and providers.

For operations that occur across trusted boundaries, any necessary authorization is expected to happen by (1) authenticating the party prior to the interaction (e.g., via holder login to a student portal), (2) creating an unguessable URL (aka capability URL) for the API endpoint needed in the interaction session with the party (e.g., the [exchange participation endpoint](https://w3c.github.io/vcalm/#participate-in-an-exchange)), (3) delivering the capability URL via a secure channel, and (4) optionally asking for additional credentials or digitally signed presentations during the subsequent exchange. With this design, there is no need for additional protections of a VCALM API endpoint whose client and server are in separate security boundaries; the protection is inherited by design of the surrounding process and architecture that a [coordinator](https://w3c.github.io/vcalm/#coordinators) is already responsible for today and, if necessary, through the reuse of primitives used to express information that flows within the exchange.

### Scope and architecture

The VCALM editors agree that the architecture diagram can be refined to clarify its relationship to the API interfaces and specify which ones are standardized by VCALM. To that effect, the editors have created [this issue](https://github.com/w3c/vcalm/issues/746) to track it and intend to address it in the specification prior to publication.

### Wallet selection and delegation

The VCALM specification does not specify how to perform wallet discovery and this responsibility does not fall on any of the components in the architecture. That functionality is deferred to external mechanisms, including QR code scanning, [Digital Credentials API (DC API)](https://www.w3.org/TR/digital-credentials/) and [CHAPI](https://chapi.io/), each of which can be used to return an [interaction URL](https://w3c.github.io/vcalm/#initiating-interactions) to a compliant wallet. When a [coordinator](https://w3c.github.io/vcalm/#coordinators) publishes an interaction URL, it delegates processing to the origin(s) hosting the exchange protocol URLs it serves from there. The coordinator is expected to have a trusted partnership with all workflow processing systems that it uses to process exchange interactions and it communicates this to clients by publishing this protocol information from its origin over TLS.

When an interaction on one origin delegates to another, the wallet authenticates the coordinator’s identity (i.e., its origin), which is the same identity that the user (i.e., the holder) should be presented with in the wallet UX. If the holder trusts the coordinator origin to process their exchange, they implicitly also trust the third party service providers the coordinator origin has used to implement the exchange software.

When a presentation is submitted during an exchange, it is delivered over TLS and can be optionally cryptographically bound to the intended recipient with a  digital signature over the VP, including the origin of the coordinator. Some presentations include credentials that are themselves bound by alternative mechanisms (e.g., [mdoc](https://www.iso.org/standard/69084.html), [BBS](https://csrc.nist.gov/csrc/media/presentations/2023/crclub-2023-10-18/images-media/20231018-crypto-club--greg-and-vasilis--slides--BBS.pdf)). The VCALM spec defers this responsibility to those mechanisms and simply enables their transmission within an exchange.

### Complete interface definitions

The VCALM specification defines a set of HTTP APIs on several components playing different roles in the credential management/exchange ecosystem. In order to resolve an API endpoint URL against the base URL of a component instance, the client needs to perform HTTP resolution.

In the [HTTP API section](https://w3c.github.io/vcalm/#http-api) of the VCALM specification, the interface of each API endpoint is defined, including both the request and response schemas (including error responses). As mentioned in the last paragraph of *Interoperability and configuration* above, permissioned authorization in the VCALM specification is only relevant for API endpoints that are exposed to clients in the same security boundary as the server, based on some typically well-defined, preexisting relationship. For these endpoints, implementers are encouraged to use the scopes and actions that are defined for [zcaps](https://w3c.github.io/vcalm/#authorization-capabilities) and [OAuth 2.0](https://w3c.github.io/vcalm/#oauth-2-0) in the [authorization section](https://w3c.github.io/vcalm/#authorization) of the specification.

Credentials and presentations that are exchanged via VCALM have explicit conformance requirements. These requirements are laid out in [this section](https://w3c.github.io/vcalm/#credential-and-presentation-objects-in-api-descriptions) of the VCALM specification, but further details can be found in the [Verifiable Credential Data Model (VCDM) specification](https://www.w3.org/TR/vc-data-model/). As mentioned in that section, the editors have chosen to omit most properties of credentials and presentations as defined in the VCDM specification solely for the sake of preserving space (these repeated definitions were causing excessive bloat in earlier versions of the specification). If this is not clear or if reviewers would prefer to see a normative definition or reference of these schemas and/or complete definitions of each credential and presentation field in each instance where it is mentioned in a request or response, the VCALM editors can arrange for this.

### Verification results

The `verified: true` response denotes that there was no error encountered from the verification of the credential/presentation. It is based on the VCDM's [`verified` flag](https://www.w3.org/TR/vc-data-model-2.0/#securing-mechanism-specifications). For a more detailed breakdown of the verification results, you may consult the `results` property of the [credential verification response](https://w3c.github.io/vcalm/#verify-credential) and the [presentation verification response](https://w3c.github.io/vcalm/#verify-presentation). The former contains boolean `verified` results for items worth verifying in a credential (e.g., `validFrom`, `credentialSchema`, and `proof`), while the latter contains boolean `verified` results for each item in a presentation (`results.presentation`) and its contained credentials (`results.credentials`). Ultimately, the acceptance decision is left to the discretion of the caller (i.e., the verifier), which determines the validation standards that it applies to credentials. However, credentials that pass verification and fulfill the requirements in the VPR will generally be accepted by the verifier.

cc @dlongley @msporny @PatStLouis

-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/1273#issuecomment-6522199846
You are receiving this because you are subscribed to this thread.

Message ID: <w3ctag/design-reviews/issues/1273/6522199846@github.com>