enumerated values for purpose, sharing and retention in API method

[npdoty]

In order to prompt and facilitate site/verifier presentation of purpose and use information, and to improve auditing and verification of those requests, the API could be designed to accept enumerated values for the purpose, sharing and retention of information.

const credentialResponse = await navigator.credentials.get({
  protocol: 'openid4vp',
  data: '[protocol request string]',
  purpose: [
    "identity-verification",
    "government-eligibility"
  ],
  sharing: "no-sharing",
  retention: "primary-purpose"
})

(This assumes pre-specified enumerations for the strings used in purpose, sharing and retention.)

That information could be used to populate a browser/OS permission prompt, and also be communicated to the wallet as part of the request. Third-party (whether governmental or a trustmark auditer) registration and verification of those enumerated values in the request by that origin could be confirmed -- by the browser, wallet, or out-of-band.

See also midi enumerated permission prompt example from https://github.com/mikewest/purposeful-permissions.

(This is a proposal for one of the suggestions in https://github.com/WICG/digital-credentials/issues/44.)

[hlflanagan]

Discussed on 20 August 2025 call

[RByers]

In the TPAC meeting @mharbach presented this UXR analysis and argued for the benefits of having purpose statements in the platform credential selection UI. I'm now convinced we should seriously explore doing this.

I don't know if it will be possible to communicate this purpose to the wallet, purpose was dropped from OpenID4VP (but we could reopen that debate). Alternately the design in #266 of reading the purpose from a (credential-less) well-know location might be more realistic and also enable some level of accountability (from crawlers, archive.org, etc.).

[RByers]

OpenID4VP removed it here, in part aligning with @marcoscaceres arguments on it being the responsibility of the verifier.

However if we can enable auditability somehow (like in #266) and we are free to solve only the most common cases (those which we'd want to visually differentiate as being lower risk as @mharbach suggests), then I think it may be tractable.

[npdoty]

When we discussed this in August, there seemed to be more interest in #208 for requiring the purpose/context from the verifier in HTML (or another source) rather than an enumeration in the browser UI, with accountability managed through logging what was presented.

But if the UX advantages are specific to having the purpose described in the browser, platform or wallet UI, then yes we would need to define parameters, in the DC API, the exchange protocols, or some additional out-of-band location.

Another way to think of it is that if there is a location where verifiers are making a commitment about the context (either in response to regulation in the EU or self-regulatory commitments), including use case registration/restriction, then we should have hooks for that information to be consumed by user agents.

[c2bo]

OpenID4VP removed it here, in part aligning with @marcoscaceres arguments on it being the responsibility of the verifier.

However if we can enable auditability somehow (like in #266) and we are free to solve only the most common cases (those which we'd want to visually differentiate as being lower risk as @mharbach suggests), then I think it may be tractable.

Another way to think of it is that if there is a location where verifiers are making a commitment about the context (either in response to regulation in the EU or self-regulatory commitments), including use case registration/restriction, then we should have hooks for that information to be consumed by user agents.

That is very close to what we are currently planning to do. We introduced verifier_info as an optional request parameter for OpenID4VP (https://openid.github.io/OpenID4VP/openid-4-verifiable-presentations-wg-draft.html#section-5.1-2.10.1). This parameter can carry additional information about the request & verifier, such as a registration certificate. In the case of EUDI that would basically be a signed statement (by a registrar) where the verifier (that was already onboarded to the ecosystem and is known/identified) registers a purpose. This information is also made publicly available and can be used to file complaints with data protection agencies etc.

[RByers]

Thank you Christian! Ok that is indeed more like #266, and I agree fitting into an existing scheme at the protocol level is better than defining something at our level. I will move the conversation on next steps to #266. If we can get progress there, I suggest we close this issue as unnecessary (though perhaps scenarios will emerge where it's useful to have at both layers).