Add guidance on how to handle multiple presentation request entries #249

MasterKale · 2025-05-28T21:47:59Z

This PR adds initial text on A) how user agents MUST handle the presence of multiple presentation requests in options.digital.requests, and B) how verifiers SHOULD populate options.digital.requests to handle getting back a corresponding presentation response.

Closes #220.

The following tasks have been completed:

Modified Web platform tests (link)

Implementation commitment:

WebKit (link to issue)
Chromium (link to issue)
Gecko (link to issue)

Documentation and checks

Preview | Diff

index.html

wseltzer · 2025-06-12T00:00:02Z

Discussed 11 June minutes

index.html

npdoty · 2025-07-09T22:28:31Z

I think we should indicate to the verifier that the multiple requests (and similarly for the request language) should be semantically compatible/equivalent, or the user/user agent/wallet are easily going to be confused, or might be seen as abuse. Browsers can try to catch really extreme cases that violate that, but it probably wouldn't be easy to test.

MasterKale · 2025-07-09T22:29:21Z

From WG meeting:

Add a note to Verifiers that request options within requests should be semantically similar
Review text to see how it might clarify that we're talking about multiple requests within a single invocation of DC API

wseltzer · 2025-07-10T17:17:06Z

Discussed 9 July.

TallTed · 2025-07-10T20:51:50Z

Might I suggest that this be reworked/rewritten a bit, to more closely mimic the HTTP content negotiation accept: header, such that each entry pairs a protocol (with associated priority) with one or more credentials (each with their own associated priority)?

A single artificially complicated request (with syntactically invisible line break, here just to make comprehension easier) might then look something like —
foo-proto-v1(ex-cred-1;cp=1.0, ex-cred-2;cp=0.5);pp=1.0, foo-proto-v2(ex-cred-1;cp=0.7, ex-cred-2;cp=0.3);pp=0.5

I would multiply the internal credential priority, cp, values by the wrapping protocol priority, pp, to make a net priority, p.

This could be made less visibly complicated by having two multi-valued parameters instead of one, such that the protocol priorities are in one parameter and the credential priorities are in another, or by having one slightly-more complex multi-valued parameter for which each value includes both protocol and credential (basically containing the permutations of the above), maybe something like —
(foo-proto-v1;ex-cred-1;p=1.0), (foo-proto-v2;ex-cred-1;p=0.35), (foo-proto-v1;ex-cred-2;p=0.5), (foo-proto-v2;ex-cred-2;p=0.15)

Note that the ordering of these is not important. It's the p value that dictates preference/priority of receiving that combination.

MasterKale · 2025-08-27T18:50:17Z

index.html

+        <p>
+          Verifiers may wish to define a single credential request
+          using multiple [=digital credential/exchange protocols=],
+          for example to achieve maximum compatibility across [=user agent | user agents=]
+          or when migrating to a newer version of a protocol. When doing so,
+          verifiers SHOULD ensure that all requests are semantically equivalent to avoid confusing
+          the user, the user agent, and the wallet during processing of the request.
+        </p>


@npdoty I added this text under a different section to try and cover your suggestion that multiple requests should be semantically similar. What do you think?

index.html

TallTed · 2025-08-29T18:34:15Z

index.html

+            When multiple [=digital credential/presentation request | presentation requests=]
+            are present in |requests|,
+            a [=user agent=] MUST NOT return more than one
+            [=digital credential/presentation response=].
+            However, multiple credentials MAY be included in this single response
+            depending on the capabilities
+            of the corresponding [=digital credential/exchange protocol=].


Suggested change

When multiple [=digital credential/presentation request | presentation requests=]

are present in |requests|,

a [=user agent=] MUST NOT return more than one

[=digital credential/presentation response=].

However, multiple credentials MAY be included in this single response

depending on the capabilities

of the corresponding [=digital credential/exchange protocol=].

A [=user agent=] MUST NOT return more than one

[=digital credential/presentation response=] to |requests|,

even when |requests| contains multiple

[=digital credential/presentation request | presentation requests=].

However, multiple credentials MAY be included in this single response

depending on the capabilities

of the corresponding [=digital credential/exchange protocol=].

Incorporating all the comments by @marcoscaceres. Too many lines changed in too many ways, so GitHub can't properly highlight the changes. I hope you have a better diff tool at hand.

Suggested change

When multiple [=digital credential/presentation request | presentation requests=]

are present in |requests|,

a [=user agent=] MUST NOT return more than one

[=digital credential/presentation response=].

However, multiple credentials MAY be included in this single response

depending on the capabilities

of the corresponding [=digital credential/exchange protocol=].

A [=user agent=] cannot return more than one

[=digital credential/presentation response=] to |requests|,

even when |requests| contains multiple

[=digital credential/presentation request | presentation requests=],

because the WebIDL for a digital credential requires an object

(i.e., it can't be a sequence).

However, a [=user agent=] MAY include multiple credentials in this

single response if the [=digital credential/exchange protocol=]

in use supports doing so.

wseltzer · 2025-09-03T22:59:49Z

Discussed 3 September minutes.

marcoscaceres · 2025-09-15T08:43:47Z

index.html

+            </aside>
+            When multiple [=digital credential/presentation request | presentation requests=]
+            are present in |requests|,
+            a [=user agent=] MUST NOT return more than one


A user agent can't do this regardless, because the WebIDL for a digital credential requires an object (i.e., it can't be a sequence).

Excellent! That should let us simplify the phrasing here substantially. I'll do so lower, as a revision of a previous suggestion for this block.

marcoscaceres · 2025-09-15T08:44:12Z

index.html

+            are present in |requests|,
+            a [=user agent=] MUST NOT return more than one
+            [=digital credential/presentation response=].
+            However, multiple credentials MAY be included in this single response


This doesn't make sense as a normative requirement, as we can't put normative requirements on formats (only on user agents). This might be useful as a non-normative note though.

I don't read this as putting requirements on any format (which aren't mentioned here anyway) nor protocol (which are), but rather putting requirements on user agents subject to the limitations of the ~~format~~ protocol in use, i.e., the user agent MAY include multiple credentials in a single response if the ~~format~~ protocol in use supports doing so.

marcoscaceres · 2025-09-15T08:45:09Z

index.html

+        <p>
+          Verifiers may wish to define a single credential request
+          using multiple [=digital credential/exchange protocols=],
+          for example to achieve maximum compatibility across [=user agent | user agents=]


Suggested change

for example to achieve maximum compatibility across [=user agent | user agents=]

for example to achieve maximum compatibility across [=user agents=]

marcoscaceres · 2025-09-15T08:46:09Z

index.html

+          using multiple [=digital credential/exchange protocols=],
+          for example to achieve maximum compatibility across [=user agent | user agents=]
+          or when migrating to a newer version of a protocol. When doing so,
+          verifiers SHOULD ensure that all requests are semantically equivalent to avoid confusing


As above... we can't put conformance requirements on verifiers, but we can suggest best practices in non-normative ways.

How about —

Suggested change

verifiers SHOULD ensure that all requests are semantically equivalent to avoid confusing

verifiers are expected to ensure that all requests are semantically equivalent to avoid confusing

Add some basic guidance

c81fa61

MasterKale requested a review from a team as a code owner May 28, 2025 21:48

Remove note to self

f28d35f

MasterKale added the agenda+ Add to the weekly agenda label May 29, 2025

TallTed suggested changes Jun 4, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

Merge branch 'main' into mm/220-handle-multiple-presentation-requests

8248f1e

wseltzer removed the agenda+ Add to the weekly agenda label Jun 12, 2025

marcoscaceres reviewed Jun 19, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

Make a SHOULD into a should

21e26cd

MasterKale self-assigned this Jun 23, 2025

MasterKale added the agenda+ Add to the weekly agenda label Jul 2, 2025

Merge branch 'main' into mm/220-handle-multiple-presentation-requests

94c8b6c

wseltzer removed the agenda+ Add to the weekly agenda label Jul 10, 2025

MasterKale added 3 commits August 26, 2025 15:19

Merge branch 'main' into mm/220-handle-multiple-presentation-requests

172c9ae

Incorporate PR feedback

9e9c7df

Add text about semantic equivalency of requests

28cb8d4

MasterKale commented Aug 27, 2025

View reviewed changes

MasterKale added the agenda+ Add to the weekly agenda label Aug 27, 2025

MasterKale commented Aug 27, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

TallTed reviewed Aug 28, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

Incorporate PR feedback

2d3c3c5

TallTed reviewed Aug 28, 2025

View reviewed changes

index.html Show resolved Hide resolved

Merge branch 'main' into mm/220-handle-multiple-presentation-requests

62d9a9d

TallTed reviewed Aug 29, 2025

View reviewed changes

Merge branch 'main' into mm/220-handle-multiple-presentation-requests

603bf0c

wseltzer removed the agenda+ Add to the weekly agenda label Sep 3, 2025

marcoscaceres reviewed Sep 15, 2025

View reviewed changes

-            When multiple [=digital credential/presentation request | presentation requests=]
-            are present in |requests|,
-            a [=user agent=] MUST NOT return more than one
-            [=digital credential/presentation response=].
-            However, multiple credentials MAY be included in this single response
-            depending on the capabilities
-            of the corresponding [=digital credential/exchange protocol=].
+            A [=user agent=] cannot return more than one
+            [=digital credential/presentation response=] to |requests|,
+            even when |requests| contains multiple
+            [=digital credential/presentation request | presentation requests=],
+            because the WebIDL for a digital credential requires an object
+            (i.e., it can't be a sequence).
+            However, a [=user agent=] MAY include multiple credentials in this
+            single response if the [=digital credential/exchange protocol=]
+            in use supports doing so.

	for example to achieve maximum compatibility across [=user agent \| user agents=]
	for example to achieve maximum compatibility across [=user agents=]

	verifiers SHOULD ensure that all requests are semantically equivalent to avoid confusing
	verifiers are expected to ensure that all requests are semantically equivalent to avoid confusing

Add guidance on how to handle multiple presentation request entries #249

Are you sure you want to change the base?

Add guidance on how to handle multiple presentation request entries #249

Uh oh!

Conversation

MasterKale commented May 28, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wseltzer commented Jun 12, 2025

Uh oh!

Uh oh!

npdoty commented Jul 9, 2025

Uh oh!

MasterKale commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wseltzer commented Jul 10, 2025

Uh oh!

TallTed commented Jul 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wseltzer commented Sep 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TallTed Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MasterKale commented May 28, 2025 •

edited by pr-preview bot

Loading

MasterKale commented Jul 9, 2025 •

edited

Loading

TallTed Sep 15, 2025 •

edited

Loading