Thanks for the review request. Our main concern is whether VCALM enables interoperability across independently developed systems or primarily within deployments that have agreed on a particular set of technologies. We have several related questions and requests:

• Interoperability and configuration: What shared protocols, query languages, credential formats, DID methods, status mechanisms, and authorization mechanisms can implementations rely on for each conformance class? Please identify any required baseline and make clear where an additional profile is necessary. Also, please explain how a generic client learns which options an instance requires or prohibits.

• Scope and architecture: The architecture diagram is not clear. Please mark which interfaces VCALM standardizes in the architecture diagram and connect them to the conformance classes, including service clients. Resolve tentative scope statements and undefined components such as “Storage Coordinators.” The diagram should also have accessible text and a description of the relationships it depicts.

• Wallet selection and delegation: In a Web interaction, which component discovers available wallets and lets the user choose one? Please clarify what browser or platform integration is assumed. When an interaction on one domain delegates an exchange to another, which identity does the wallet authenticate, which identity does the user see, and what binds the presentation to its intended recipient?

• Complete interface definitions: Several interfaces leave independent implementations needing to infer behavior. Please specify callback payloads, response bodies, authorization action mappings, URL resolution against an instance’s base URL, and error behavior for missing required fields or identifier collisions. Credential and presentation objects should have explicit normative conformance requirements; linked binary content and hashes likewise need a defined mechanism.

• Verification results: Please clarify what verified: true guarantees, particularly when status or validity concerns are reported as warnings, and which acceptance decisions remain the caller’s responsibility.

These clarifications would help us assess both the interoperability claims and the division of responsibility between VCALM, its implementations, and the surrounding Web platform.

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 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. To participate in this API, each party needs to understand how to process a Verifiable Presentation (VP) and a Verifiable Presentation Request (VPR), which is defined in the VCALM specification. Considering the above API design, there is a general expectation that workflow 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 are available at the server for exchanging credentials. This information is discovered from an interaction URL, 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), 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) and 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). 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), (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 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 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) and CHAPI, each of which can be used to return an interaction URL to a compliant wallet. When a coordinator 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, BBS). 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 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 and OAuth 2.0 in the authorization section of the specification.

Credentials and presentations that are exchanged via VCALM have explicit conformance requirements. These requirements are laid out in this section of the VCALM specification, but further details can be found in the Verifiable Credential Data Model (VCDM) specification. 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. For a more detailed breakdown of the verification results, you may consult the results property of the credential verification response and the presentation verification response. 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