Add `<fullExchangeId>/protocols` endpoint that serves interaction "protocols" object

[dlongley]

Performing an HTTP GET on an exchange URL + /protocols should return a "protocols" object with the supported protocols for interacting with that exchange. For example:

GET /workflows/abc/exchanges/123/protocols

{
  "protocols": {
    "vcapi": "https://vcapi.example/workflows/abc/exchanges/123",
    "OID4VCI": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fvcapi.example%2Fworkflows%2Fabc%2Fexchanges%2F123%2Fopenid%2Fcredential-offer"
  }
}

[dlongley]

We should also document that a coordinator website could serve any route (of their choice) from their origin that they can send via QR code or via CHAPI as an "interact" protocol:

const result = await navigator.credentials.get({
  web: {
    protocols: {
      // the "interact" protocol returns more "protocols" from a VC API exchange
      interact: '<any URL with origin of coordinator site>'
    }
  }
});

That way an exchange client (e.g., digital wallet) can use origin-based security/trust to get the list of protocol URLs directly from the coordinator website, allowing trust to be anchored in the coordinator origin, even if the coordinator serves a protocols object that points at an exchange that is hosted by some other origin. (Note: This enables different origins to be used (really, the workflow/exchange service origin to be introduced when previously not known to the user) in a trusted way without requiring the complexity of signed authorization requests like are used in some other protocols.

Once an exchange client gets the interact URL, they perform a GET on it -- and the coordinator site can, in turn, perform a GET on the associated exchange to return the protocols object from the exchange server. The exchangeId can be embedded in the interaction URL to help facilitate this.

[dlongley]

Notably, if protocols.vcapi is given directly in a CHAPI request you can also append /protocols to it to get all supported protocols. However, the interact option helps coordinators that don't want to or cannot setup proxies in support of origin-based security/trust if the exchange lives at another origin.

If we wanted to enable using another origin without adding interact (and still using just vcapi), then the coordinator could put an exchange URL in vcapi that will simply return redirectUrl when the client interacts with it -- and we could say that exchange clients should try fetching it using Accept: application/json before redirecting to it, to see if the wallet can just continue the exchange that way -- or we should return a VPR with an interact field. These are alternative options to explore that could be moved to a separate issue if we want to explore them. Ideally we reduce the number of ways that this can be done.

[msporny]

The group discussed this on 2024-09-17:

@dlongley provided a background on what the change would do (see above). There didn't seem to be objections to the endpoint or the feature set. A PR should be raised to add this endpoint to the specification.

[msporny]

A coordinator creates an exchange, the exchange always has the protocols endpoint, the coordinator can expose the endpoint on a system of their own that can proxy what the exchange returns back to the client that made the request. That ensures that the client (digital wallet) is retrieving the request through the origin that the end user is expected to trust and/or understand. That eliminates the need for doing anything like a signed authorization request (because you trust the domain) -- no keys or signing is required by the hosting domain because the trust comes from the domain certificate used to serve the .../protocols endpoint (regular trust model provided by DNS and TLS).

[msporny]

A PR needs to be raised that defines the .../protocols endpoint, why it is useful, and what can be returned from that endpoint.

[kezike]

@dlongley Would this update involve a schema change to exchanges, whereby they include the protocols under a protocols property or should we expect implementers to dynamically construct this object using all the other metadata in an exchange?

[kezike]

Another option would be to include the interaction ID in the exchange schema, but that depends on how much we want to couple the design of exchanges and interactions (which are naturally already tightly coupled anyway).

[dlongley]

@kezike,

Would this update involve a schema change to exchanges, whereby they include the protocols under a protocols property or should we expect implementers to dynamically construct this object using all the other metadata in an exchange?

No schema change required, it can be dynamically constructed based on the other information. Our implementation already does this.