Skip to content

Define Coordinator and Client #306

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.

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

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
98 changes: 98 additions & 0 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -285,6 +285,104 @@ <h2>
identifier=]. See also section [[[#protocol-registry]]].
</dd>
</dl>
<h3>
Credential Request Coordinator
</h3>
<p>
The <dfn>credential request coordinator</dfn> is a user-agent-defined
component responsible for mediating [=digital credential=] interactions
within a given [=top-level traversable=].
</p>
<p>
Each [=top-level traversable=] has a single associated [=credential
request coordinator=].
</p>
<p>
The [=credential request coordinator=]:
</p>
<ul>
<li>Ensures that only one [=digital credential=] interaction is active at
any time. This includes both via the:
<ul>
<li>{{DigitalCredential/[[DiscoverFromExternalSource]](origin,
options, sameOriginWithAncestors)}} internal method.
</li>
<li>{{DigitalCredential/[[Create]](origin, options,
sameOriginWithAncestors)}} internal method.
</li>
</ul>
</li>
<li>Handles state transitions across the following lifecycle states:
<ul>
<li>
<dfn data-dfn-for="credential request coordinator">Idle</dfn>: No
credential interaction is currently in progress.
</li>
<li>
<dfn data-dfn-for=
"credential request coordinator">Presenting</dfn>: A credential
interaction is currently in progress and the user interface is
being shown to the user.
</li>
<li>
<dfn data-dfn-for="credential request coordinator">Aborting</dfn>:
A credential interaction is being canceled. The coordinator is in
the process of cleaning up the interaction.
</li>
</ul>
</li>
<li>Manages the lifecycle of the current interaction's promise, including
its resolution or rejection.
</li>
<li>Integrates with an {{AbortSignal}} to allow user-initiated or
programmatic cancellation.
</li>
</ul>
<h3>
Digital Credential Client
</h3>
<p>
A <dfn>digital credential client</dfn> is a user-agent-defined component
responsible for presenting available [=holders=] to the user and
coordinating the credential request or issuance flow.
</p>
<p>
Each [=credential request coordinator=] uses a single associated
[=digital credential client=] to fulfill credential request and issuance
operations.
</p>
<p>
The [=digital credential client=]:
</p>
<ul>
<li>Validates and transforms digital credential request or issuance
inputs.
</li>
<li>Interprets each individual request in the input list as targeting a
specific [=holder=], and prepares holder options accordingly.
</li>
<li>Presents the available [=holders=] to the user for selection.
</li>
<li>Once a [=holder=] is selected, invokes it as a [=credential chooser=]
to complete the interaction.
</li>
Copy link
Contributor

Choose a reason for hiding this comment

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

This is probably Webkit-specific.
In Chrome all that logic lives in Android, and doesn't really belong to the user-agent

Copy link
Contributor

Choose a reason for hiding this comment

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

I think also in Cross-Device, that logic doesn't live in the client even in Webkit (as in the Client to Authenticator Protocol)

I suggest we remove this from the responsibilities of the client.
It's sufficient to say as above, that it facilitates the selection of the holder
This covers "Webkits actual displaying of the selector, Chrome delegation to platform, and cross-device's delegation to the authenticator)

What do you think?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I'm ok with dropping this.

Copy link
Contributor

Choose a reason for hiding this comment

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

I still see some of this in the PR.
Is that intentional?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

No. Would you mind suggesting any additional changes if I missed something? 🙏

<li>Returns the result — a selected credential or a cancellation — to the
[=credential request coordinator=].
</li>
</ul>
<aside class="note">
<p>
Although the [=digital credential client=] coordinates the credential
interaction, it is the selected [=holder=] that typically acts as the
[=credential chooser=].
</p>
<p>
In this model, the [=digital credential client=] presents the
user with a list of available [=holders=], and the selected [=holder=]
then displays its own user interface for selecting or issuing [=digital
credentials=].
</p>
</aside>
<h2>
Scope
</h2>
Expand Down