Top level request object structure should be fully defined by protocol identifier

[timcappalli]

Some protocols may have different modes / types for requests, such as signing the entire request object. This changes the top level structure of the request object in the Digital Credentials API.

OID4VP is a protocol which supports both unsigned and signed requests. For example:

OID4VP unsigned request

const credential = await navigator.credentials.get({
  digital: {
    requests: [{
      protocol: "openid4vp",
      data: {
        "client_id": "digital-credentials.dev",
        "client_id_scheme": "web-origin",
        "response_type": "vp_token",
        "nonce": "m6wM5ykCK6UnsFfDCV8-F9pWNv-vZ92JFHYc9R2w0ms=",
        "presentation_definition": {}
      }
    }]
  }
});

OID4VP signed request (proposed, not final)

const credential = await navigator.credentials.get({
  digital: {
    providers: [{
      protocol: "openid4vp",
      data: {
        "payload": "eyAiaXNzIjogImh0dHBzOi8...NzY4Mzc4MzYiIF0gfQ",
        "signatures": [
          {
            "protected": "eyJhbGciOiJFUzI1NiJ9",
            "header": {
              "client_id": "987647789",
              "client_id_scheme": "x509_san_dns"
            },
            "signature": "PFwem0Ajp2Sag...T2z784h8TQqgTR9tXcif0jw"
          },
          {
            "protected": "eyJhbGciOiJFUzI1NiJ9",
            "header": {
              "client_id": "https://rp.federation.eu",
              "client_id_scheme": "entity_id"
            },
            "signature": "irgtXbJGwE2wN4Lc...2TvUodsE0vaC-NXpB9G39cMXZ9A"
          }
        ]
      }
    }
    ]
  }
});

So for these examples, the standard unsigned OID4VP request could just use the protocol name openid4vp-v1, whereas the signed request would use openid4vp-signed-v1 (or do we always want to be explicit and not have a default mode, e.g. openid4vp-unsigned-v1?)

This would be instead of introducing another top level property to the API (such as requestType or requestMode).

The registry in the spec would point to the specific portion of the protocol specification which defines that mode/type/behavior.

[OR13]

It seems like you are considering specifying request as being a JSON parsed version of https://www.iana.org/assignments/media-types/application/jose+json

Not sure if you need agility here (for example to support more compact binary requests), but you might consider generalizing the signed request variant to support media types.

request_content_type: application/jose+json or application/cose or application/eat+cwt, etc...
request_content: Uint8Array

perhaps for protocol: "openid4vp", you know this will only ever be JOSE / JSON... so this comment is not relevant to that protocol.

If you are considering both signed and unsigned structured data, you might find this draft relevant to your design: https://datatracker.ietf.org/doc/draft-ietf-rats-eat-media-type/

[bc-pi]

As mentioned on yesterday's call - at this level, I'm in favor of continuing to treat OpenID4VP as one "protocol" and using a single protocol identifier for it.

[bc-pi]

notes of yesterday's call copied below and noting this corresponding issue over in the OIDF's DCP WG openid/OpenID4VP#326

Issue: Top level request object structure should be fully defined by protocol identifier #185
Tim: Signed request looks very different from unsigned request. From DX perspective this looks awkward. Should these requests be different identifiers?
Marcos: This seems outside the scope of the WICG
Lee: In support of having an identifier. Requests are different enough
Brian: This discussion should be handled over in OIDF
Tim: Registry of protocol IDs is in this spec, so that part is relevant here
Lee: Could still write the sentence that contents of data will be defined in OID4VP
Brian: Generally speaking, protocol identifier ID's the protocol. Is likely to cause more harm and confusion breaking up protocol identifiers
Sam: Registry lives in this spec, but algorithm lives in OID4VP spec. Therefore this seems like an OID4VP concern. If they feel like they'd benefit from a separate string for protocols then this spec could incorporate that. But adding something extra here but OID4VP didn't then it wouldn't have any effect.
Tim: The ergonomics of this API are for the consumers of this API, not for OID4VP. Registry is providing a map only in the context of the DC API. Identifier is paired with a link to the OID4VP spec that describes the protocol
Sam: If OID4VP group would benefit from the separation then we could introduce it
Tim: There's a benefit to developers to communicate the different protocols
Marcos: IANA ensures that certain accommodations are made for a protocol to be included. Having a top-level protocol identifier that does these kinds of changes we'd reject adding to the registry. "Hey, you shouldn't be changing these structures." So we could e.g. provide guidance to OID4VP if they attempt to define different request structures under the same identifier.
Brian: Media types registry doesn't go out and find where media types need to be registered, then assign them an identifier. I assumed that this model would be similar. It doesn't have to be that way, but it's how these things typically work. Real guidance can be offered of what goes into the registry. Various ergonomics are different for different people, it's reasonable to think there'd be better ergonomics as separate identifiers; others would think it reasonable to keep identifiers consistent. Would be super awkward to have a registry seek out and assign identifiers.
Matt: Having two protocols seemed like a slam dunk, but acknowledge prior art that it could have unintended consequences. Possible to pull this off without introducing new identifiers
Marcos: We own the registry and the rules about getting into it. If a protocol doesn't match the quality and privacy requirements then it wouldn't be included.
Tim: Question 1: Do we think this is a good idea? Introduce a new top-level value?
Brian: Doesn't want to add more "stuff."
Tim: A SIGNED/UNSIGNED enum? Registry inclusion could dictate specifying one of these values to be included
Brian: Better to engage the WG where these identifiers are being declared to consider assigning new identifiers.
Tim: Not disagreeing that it couldn't get solved at protocol level. Can we agree there's a need to make this request to OID4VP WG?
Marcos: Let's trial the registry and see how it goes. Learn by doing.
Sam: Just wanted to note that cost Marcos is paying is not the cost that Chrome is paying from architectural differences. Users aren't going to know the difference, but developers will pay the cost.
Matt: If developers can easily map from protocol identifier in DC API to appropriate protocol spec then there's a chance to push this off to the registry. Where would be responsible for maintaining these links for devs to follow?
Tim: Web implementation helps shape platform APIs.
Lee: Less nice to introspect data structure to understand shape of data
Sam: Speaking personally, intuition is from experience with FedCM. From a DX perspective, we would send users to OID4VP, then over there define how to use the protocol from that spec. Could work the same here.
Tim: Timeline of when OAuth arrived on the scene to when FedCM dropped, may not be analogous to things now because VC protocols are being defined alongside transport APIs like DC API
Brian: Recognize there's different viewpoints on what's complicated or not. Would be great if this represented collaboration between DC API and protocol WGs
Lee: Not the hardest thing to solve, more implicit than explicit right now. Would be nicer to make things more explicit. "Presence of this field is how to parse it" makes things implicit.
Tim: Reiterating that this much conversation on this topic means we shouldn't punt.
Marcos: Would love to see collaboration in the community around this as protocols and DC API evolve together.

[Sakurann]

Can we please consolidate the discussion on the protocol identifier for oid4vp in OID4VP? we can schedule a call dedicated to that with WICG participants? thank you.

[timcappalli]

There was no intention to continue the discussion here. This was an issue to bring forward the initial topic for initial discussion, to gauge interest from the web platform angle. That is now complete with the creation of the issue in DCP WG.

This issue will get closed out when there is closure from that discussion.

[timcappalli]

To Do: add requirement to registry criteria (#157)