Remove W3C DC API examples #254
Conversation
As the W3C spec is changing a lot, it's best yet to not include any examples.
|
Are we expecting breaking changes to the Browser API, I thought it was fairly settled for now? I'm not sure that removing the examples helps. The examples are non-normative and don't really show anything that's not already described in the normative text. (We can actually update the examples relatively easily, both during any public review period for the 1.0 spec revision, and even after 1.0 is published by making an errata update, but if the normative text is likely to require changes as well that's a much bigger problem.) |
|
Ah, I guess WICG/digital-credentials#165 may be the driver? Although the 'providers' -> 'requests' change itself looks like it shouldn't break normative text in VP, It is slightly concerning that there are suggestions on that PR that would affect the normative text, like changing 'request' to 'query'. |
|
I'm concerned about this here: WICG/digital-credentials#164 |
|
Maybe leaving a link for where to see current examples would be better than just removing them? Eg. maybe they belong in this GitHub repo but in their own non-normative file for easier updating? |
|
I don't think we should lock in this spec with the other at all. We might want to move things around and we haven't yet added the examples to the Digital Credentials Spec. Rest assured that we will add examples, but it might not happen in the accelerated timeframe OpenID4VP is currently on. We can add examples to a future version of OpenID4VP once the W3C Spec is a) in a working group, and b) we are confident on the design (e.g. the spec reaches CR on the W3C side). We don't have enough implementation experience yet to be confident we won't change more things - specially as the W3C spec hasn't been road tested with more request formats, which may change the underlying request model/structure. |
| @@ -1537,34 +1537,11 @@ And lastly, as part of the request, the Wallet is provided with information abou | |||
|
|
|||
| ## Protocol | |||
|
|
|||
| The value of the `protocol` parameter of the W3C Digital Credentials API MUST be set to `openid4vp` for this profile. | |||
| When used with the W3C Digital Credentials API [@!w3c.digital_credentials_api], the exchange protocol is the string `openid4vp` for this profile. | |||
There was a problem hiding this comment.
| When used with the W3C Digital Credentials API [@!w3c.digital_credentials_api], the exchange protocol is the string `openid4vp` for this profile. | |
| For the profile defined in this section, the value of the exchange protocol used with the W3C Digital Credentials API [@!w3c.digital_credentials_api], is the `openid4vp`. |
| // Handle errors and/or fallback to other invocation mechanisms | ||
| } | ||
| ``` | ||
| The W3C Digital Credentials API [@!w3c.digital_credentials_api] contains an OpenID4VP Authorization Request, where every OpenID4VP Authorization Request parameter is represented as a top-level JavaScript object member. |
There was a problem hiding this comment.
where every OpenID4VP Authorization Request parameter is represented as a top-level JavaScript object member
Is this a new development in Digital Credentials API? How would this work for signed requests?
There was a problem hiding this comment.
The change here is removing "request member", I think that's okay, it's removing the coupling between the two specs but it doesn't change how signed requests are handled.
There was a problem hiding this comment.
is there any risk of this changing in the future? wouldn't this prevent passing multiple requests in an array? Would really prefer a text like The Verifier MAY send all the OpenID4VP request parameters to the W3C Digital Credentials API as defined in [@!w3c.digital_credentials_api]
| @@ -1591,7 +1568,7 @@ Any OpenID4VP request compliant to this section of this specification can be use | |||
|
|
|||
| ### Unsigned Request {#unsigned_request} | |||
|
|
|||
| The Verifier MAY send all the OpenID4VP request parameters as members in the `request` member passed to the API. In this case, the Wallet will use the Verifier's origin as asserted by the user agent as the Verifer's Client Identifier. | |||
| The Verifier MAY send all the OpenID4VP request parameters as members to the W3C Digital Credentials API [@!w3c.digital_credentials_api]. In this case, the Wallet will use the Verifier's origin as asserted by the user agent as the Verifer's Client Identifier. | |||
There was a problem hiding this comment.
Again, how does this work for signed request where all the parameters are within a signed JWT which contains all of the parameters?
There was a problem hiding this comment.
This is in the "Unsigned request" section, this text won't affect signed requests.
There was a problem hiding this comment.
i would prefer something like this:
| The Verifier MAY send all the OpenID4VP request parameters as members to the W3C Digital Credentials API [@!w3c.digital_credentials_api]. In this case, the Wallet will use the Verifier's origin as asserted by the user agent as the Verifer's Client Identifier. | |
| The Verifier MAY send all the OpenID4VP request parameters to the W3C Digital Credentials API as defined in [@!w3c.digital_credentials_api]. In this case, the Wallet will use the Verifier's origin as asserted by the user agent as the Verifer's Client Identifier. |
|
Text in this PR does not sufficiently decouple openid4vp text and still makes it susceptible to any future breaking changes in the credentials API. "Put openid4vp request parameters in an appropriate place as defined in digital credentials API; the openid4vp parameter is X for signed requests and Y for unsigned requests" is what I would expect. Also very unsure about removing all of the examples. Will digital credentials API provide examples how to include openid4vp request there once it is stable? If not, we should keep some examples as of today in the spec. If the text is generic enough, changing the examples later as digital credentials API evolves is possible. |
|
|
||
| The following is a non-normative example of how the W3C Digital Credentials API can be used with an unsigned OpenID4VP request when advanced security features of OpenID4VP are not used: | ||
|
|
||
| ```js | ||
| try { | ||
| const credential = await navigator.identity.get({ | ||
| digital: { | ||
| providers: [{ | ||
| protocol: "openid4vp", | ||
| request: { | ||
| response_type: "vp_token", | ||
| response_mode: "w3c_dc_api", | ||
| nonce: "n-0S6_WzA2Mj", | ||
| client_metadata: {...}, | ||
| presentation_definition: {...} | ||
| } | ||
| }] | ||
| } | ||
| }); | ||
| } catch (err) { | ||
| // Handle errors and/or fallback to other invocation mechanisms | ||
| } | ||
| ``` |
There was a problem hiding this comment.
I can't figure out how to actually make a suggestion that undoes the delete, but I believe we should NOT remove the actual OID4VP part of the examples. It was clear from last night's DCP WG call that many people don't understand what is passed by OID4VP to the browser API, and removing the examples will definitely make that even harder to figure out.
I hence suggest we retain this part of the example:
{
response_type: "vp_token",
response_mode: "w3c_dc_api",
nonce: "n-0S6_WzA2Mj",
client_metadata: {...},
presentation_definition: {...}
}
(and apply a similar change to other removed examples)
There was a problem hiding this comment.
Strongly agree.
we should not keep outdated examples, but updating them or keeping the parts that are defined by openid4vp spec, as opposed to browser api spec, should be a solution
There was a problem hiding this comment.
Discussed on today's WG call, consensus to keeping the payload parts but removing the rest of the example.
As the W3C spec is changing a lot, it's best to not include any examples yet. That way, this spec can progress without locking in changes on the W3C side.