Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define registry inclusion rules #157

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Define registry inclusion rules #157

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ff834c5
Define registry inclusion rules
marcoscaceres Aug 7, 2024
b808c7d
Update index.html
marcoscaceres Aug 13, 2024
dbdffb7
Update index.html
marcoscaceres Aug 13, 2024
f83e9ca
Update index.html
marcoscaceres Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 103 additions & 4 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,9 +388,101 @@ <h2 id="protocol-registry">
<h3>
Inclusion criteria
</h3>
<aside class="note">
The below criteria are a work in progress and are likely to change as
this document evolves.
</aside>
<p>
To be included in the registry, the [=digital credential/exchange
protocol=]:
</p>
<ol>
<li>MUST be standardized at a recognized standards organization and have
marcoscaceres marked this conversation as resolved.
Show resolved Hide resolved
a stable URL.
</li>
<li>MUST define a [[WebIDL]] [=dictionary=] representation of the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like a good goal to me, but seems hard to accomplish logistically. Where does the WebIDL live? In this spec? In the protocol spec? What happens when they get out of sync?

Copy link
Collaborator Author

@marcoscaceres marcoscaceres Aug 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was imagining the protocol spec. In our spec, we would only link to the dictionary (i.e., our spec would only have [FooBar](https:/link-to-whatever.com/spec/#FooBar)).

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like it would be easier to include the definition in this spec as part of the inclusion process.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It could certainly be done that way. I do share @samuelgoto’s concerns about this spec falling out of sync though.

I was thinking that having just the name of dictionary in this spec minimizes the chance of things getting out of sync. Listing just the name is also what the Cred Man spec does in its registry:

https://www.w3.org/TR/credential-management-1/#credential-type-registry-appropriate-interface-object

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either would work, but we shouldn't require other specs that may already be completed to reopen themselves if they could just drop some webidl that describes themselves here. Particularly where they don't already define their structures with webidl.

Copy link
Collaborator Author

@marcoscaceres marcoscaceres Aug 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's a good point. Someone can correct me, but I think the only candidates right now are OpendID4VP (and the mDoc part), and maybe W3C VC? I think all of those are in active development with the aim of integrating with this.

but we shouldn't require other specs that may already be completed to reopen themselves if they could just drop some webidl that describes themselves here.

Generally speaking, what I'm finding is that you can't take existing specs and expect them to work out of the box with the DC API. They really need to be developed in tandem because the Web and JS have very specific requirements. The IDL requirement, along with clearly specified validation criteria, is actually a forcing function for those specs to integrate properly with this spec.

My feeling right now is that they might need to reopen themselves if they want to integrate, because they wouldn't be designed to work with a JS API in the first place (and if any such spec exists).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expanded on my concerns about this specific requirement here on this other PR, but I remain fairly concerned (security-wise) about requiring all browsers to redeploy before protocols can be extended:

#156 (comment)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth including a non-normative example?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Certainly could, but if we can get one into OpenID, then that can serve as a good basis. Alternatively, we are going to specify that fake test protocol... so we could point to that too as an example.

[=digital credential/exchange protocol=] request structure (i.e., the
[=dictionary=] to which the {{DigitalCredentialsProvider}}'s
{{DigitalCredentialsProvider/request}} is [=converted to idl
values|converted=] to before it is passed onto underlying platform).
</li>
<li>MUST define a [[WebIDL]] [=dictionary=] representation of the
[=digital credential/exchange protocol=] response structure (i.e., the
[=dictionary=] to which the {{DigitalCredential}}'s
{{DigitalCredential/data}} is [=converted to idl values|=] to before it
marcoscaceres marked this conversation as resolved.
Show resolved Hide resolved
is made available to the relying party).
</li>
<li>MUST define validation rules for members of the request and response
structures.
</li>
<li>MUST have undergone privacy review by the W3C's Privacy Interest
Group and Federated Identity Working Group.
</li>
<li>MUST have undergone security review by the Federated Identity Working
Group.
</li>
Comment on lines +418 to +423
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to define the criteria by which this group would review those?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. I think so. I was hoping to let those folks chime in about how we might do it, as some are already members of this group.

<li>MUST have implementation commitment from at least two implementers in
independent browser engines, to meet the W3C's adequate implementation
experience requirements.
</li>
<li>MUST have formally recorded consensus by the Working Group to be
included in the registry.
</li>
</ol>
<p>
Once the above criteria are met, the protocol will be included in the
registry.
</p>
<h3>
Change process
</h3>
<p>
To be included in the registry...
To add a new [=digital credential/exchange protocol=]to the registry, or
marcoscaceres marked this conversation as resolved.
Show resolved Hide resolved
to update an existing one:
</p>
<dl>
<dt>
Define a protocol identifier
</dt>
<dd>
The protocol identifier MUST be a unique string that is not already in
use in the registry. Use only lowercase ASCII letters, digits, and
hyphens (e.g., "protocol", "the-protocol"). Avoid using version numbers
in the protocol identifier.
</dd>
<dt>
Link to a Web IDL request dictionary
</dt>
<dd>
The <dfn>Web IDL request dictionary</dfn> MUST be a [=dictionary=] that
defines the structure of the request that is passed, via
{{DigitalCredentialsProvider}}'s
{{DigitalCredentialsProvider/request}}, to the holder's a digital
wallet.
</dd>
<dt>
Link to a Web IDL response dictionary
</dt>
<dd>
The <dfn>Web IDL response dictionary</dfn> MUST be a [=dictionary=]
that defines the structure of {{DigitalCredential}}'s
{{DigitalCredential/data}}.
</dd>
<dt>
Describe the protocol
</dt>
<dd>
The description MUST be a brief summary of the protocol's purpose and
use case.
</dd>
<dt>
Provide a link to the specification
</dt>
<dd>
The specification MUST be a stable URL that points to the authoritative
source for the protocol, including validation rules.
</dd>
</dl>
<aside class="issue" data-number="58"></aside>
<p>
[=User agents=] MUST support the following [=digital credential/exchange
Expand All @@ -404,13 +496,20 @@ <h3>
<thead>
<tr>
<th>
Protocol identifier
<dfn data-dfn-for="digital credentials registry">Protocol
identifier</dfn>
</th>
<th>
<dfn data-dfn-for="digital credentials registry">Web IDL request
dictionary</dfn>
</th>
<th>
Description
<dfn data-dfn-for="digital credentials registry">Web IDL response
dictionary</dfn>
</th>
<th>
Specification
<dfn data-dfn-for=
"digital credentials registry">Specification</dfn>
</th>
</tr>
</thead>
Expand Down