Define interaction between platform credential chooser and the user agent

[marcoscaceres]

Closes #305
Closes #112

This pull request adds a new section to the index.html file that defines and describes the "Credential Request Coordinator" concept, which is central to managing digital credential interactions within a user agent. The section introduces the coordinator's responsibilities, lifecycle management, and its interaction states, laying the groundwork for future implementation details.

New "Credential Request Coordinator" section:

• Introduces the concept of the credential request coordinator, explaining its role as a user-agent-defined component that mediates digital credential interactions within a top-level traversable, orchestrates presentation/issuance flows, and manages interaction states.
• Details the coordinator's responsibilities, including validating inputs/outputs, preparing holder options, presenting holders for user selection, and resolving or rejecting the interaction's promise.
• Defines the finite set of interaction states (idle, requesting, aborting) used by the coordinator to manage the lifecycle of credential requests.
• Adds placeholders for future documentation on preparing credential requests, aborting requests, dismissing the holder chooser, and presenting the holder chooser.
• Adds a cross-reference in the terminology section, linking "Digital credential coordinator" to "credential request coordinator."

---

Preview | Diff

[TallTed]

Small language fix

[marcoscaceres]

@mohamedamir added the diagram above, as we discussed... will fix it up and add to the spec.

[mohamedamir]

@mohamedamir added the diagram above, as we discussed... will fix it up and add to the spec.

Great!
Thanks @marcoscaceres

[timcappalli]

I still don't agree with having this in the spec, as it is very UA specific.

It it also essentially mandates that the credential selector is a UA component, which is not always the case (in most cases it is not).

This is why I previously had the DC Client and DC Client Platform definitions which can clearly separate some of this.

[TallTed]

Tweaks for consistency within source, thence to consistency in rendering for humans.

[hlflanagan]

Discussed on the FedID WG DC API Series B call

[marcoscaceres]

It is also essentially mandates that the credential selector is a UA component, which is not always the case (in most cases it is not).

Sorry, that is not the intent. It's not a UA component, it's either a platform component or generated by the OS.

This is why I previously had the DC Client and DC Client Platform definitions which can clearly separate some of this.

We can just clarify that in the text.

[marcoscaceres]

I still don't agree with having this in the spec, as it is very UA specific.

To be clear, these are not UA specific things - they are generic things to any user agent:

• Coordinator: all UAs must deal with simultaneous requests from multiple browsing contexts (this is common, payment request does this, web share does this, web authn does this... though in somewhat un-good way, etc.) - and it has control of when and how the promise is resolved/rejected, setting up the abort controller algorithm (needs to tell the client to close the sheet and tear down the wallet, then resolve the promise). And also deals with the monitoring the requesting traversable's lifecycle.
• Client: handles UI thread interactions with a wallet - the user aborting, the wallet crashing, the abort controller timing out and telling the Wallet to go away, the wallet sending back a valid or invalid payload, which must then be converted to DigitalCredential (which may result in a DOM Exception), and sent back to the coordinator to resolve/reject the promise.

So there's nothing in the above that is "UA specific", both WebKit and Chromium need to do the same things here (and hopefully Gecko too 🧡🦊). Why this model is needed.

[mohamedamir]

Thank you @marcoscaceres !
I think it's in good shape except some minor comments
@timcappalli could you please take a look?

[timcappalli]

There's some terminology issues, but I don't think they affect implementation. We can fix them once #387 gets merged.

I also don't think this should be it's own section, but that can also get changed at a later date.

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}