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 #44.)

[hlflanagan]

Discussed on 20 August 2025 call