search

WICG / digital-credentials

Digital Credentials, like driver's licenses
https://wicg.github.io/digital-credentials/
Other
82 stars 9 forks source link

Consider Verifiable Presentation Request design patterns #12

Open msporny opened 1 year ago

msporny commented 1 year ago

Based on commentary in this issue about the complexity in PeX and it being viewed as too complicated for a presentation request language (I agree):

https://bitbucket.org/openid/connect/issues/1917/moving-to-a-credential-format-specific

The charter should consider the design approach taken in the Credential Handler API (CHAPI) and the Verifiable Presentation Request (VPR) work. Namely, that the design is meant to be protocol and query language agnostic. That is, it is designed to support mdoc query languages, VC query languages, and different protocols for mdoc, VCs, and other market vertical formats:

Demonstration of being query language agnostic: https://w3c-ccg.github.io/vp-request-spec/#query-and-response-types

Demonstration of being protocol agnostic: https://w3c-ccg.github.io/vp-request-spec/#interaction-types

While the examples are out of date, the design pattern still holds (and it looks like the discussion in the OpenID community is converging on the same design pattern that was established by VPR many years ago).

Fundamentally, the query languages and protocols for moving the newest types of digital credentials over the Web, NFC, and QR Codes are very new and unsettled. Trying to lock one in at this moment in time, or in a WG over the next 1-2 years is premature. Thus, the safest design approach would be to allow for agility at both the query language layer and the protocol layer.

samuelgoto commented 1 year ago

The charter should consider the design approach taken in the Credential Handler API (CHAPI) and the Verifiable Presentation Request (VPR) work. Namely, that the design is meant to be protocol and query language agnostic. That is, it is designed to support mdoc query languages, VC query languages, and different protocols for mdoc, VCs, and other market vertical formats:

Yeah, we are really struggling with this question and we could really use your help and experience figuring this one out.

Can you help us by making a concrete proposal on what that API may look like here? I'm somewhat familiar with CHAPI (as you know), but I could use a concrete proposal to help me visualize in concrete terms what things would look like (I think I generally agree with the sense/direction you are proposing).

Could you help us re-write this mDocs example and this VC example in terms of what you are suggesting with Verifiable Presentations?

Here is what I think it would look like, but can you check if this is what you are suggesting?

// Gets a CBOR with specific fields out of mobile driver's license as an mdoc
const {response} = await navigator.credentials.get({
  identity: {
    providers: [{
      vc: {
        query: {
            // newly introduced query type
            type: "QueryByDocTypeAndElements",
            documentType: "org.iso.18013.5.1.mDL",
            requestedElements: [
              { namespace: "org.iso.18013.5.1", name: "document_number" },
              { namespace: "org.iso.18013.5.1", name: "portrait" },
              { namespace: "org.iso.18013.5.1", name: "driving_privileges" },
              { namespace: "org.iso.18013.5.1.aamva", name: "organ_donor" },
            ],
        }

        // Query agnostic / Protocol layer
        challenge: "gf69kepV+m5tGxUIsFtLi6pwg=",
        recipient: ["ftl+VEHPB17r2 ... Nioc9QZ7X/6w..."],
        // where should retention go?
        // retentionDays: 90,
      }
    }],
  }
});

Is this more or less what you have in mind?

msporny commented 1 year ago

@samuelgoto wrote:

Is this more or less what you have in mind?

Yes, very close.

What is being proposed, and how CHAPI approached this design question, was to be completely agnostic to the query format. That is, CHAPI isn't locked into one credential format or another, one protocol or another, or the query/response formats used in the protocol. It is effectively a "dumb pipe" which channels queries from relying parties, mediates those queries to particular applications (native and web) that have registered themselves as being able to "speak" specific protocols and query formats, and passes the query onto the application. The response can either come through CHAPI, or it can come back in some sort of out of band mechanism (such as OpenID, or VC API Exchanges).

The key design consideration here is the protocol and query format agnosticism. Note that this doesn't mean a browser can't introspect into the query, or that we can't do pre-flight stuff to see which applications might actually have a credential to provide for a particular query, but those are orthogonal decisions to the base decision to presume that this API is going to have to deal with multiple, possibly very different, protocols and query formats.

We are very early days wrt. Verifiable Credential query formats and protocols. While there are some claiming that "there will be standard X that moves VCs and that will be 'done' in the next X months", I think that is wishful thinking. All of the protocols under consideration right now have challenges (based on early days implementation feedback rolling these features out to customers). So, locking specific protocols or query formats in, especially for VCs (and dare I say mdoc) are premature. Contrast that to SAML and traditional OpenID, which have been around for a long time and are probably safer bets when it comes to what you can and can't expect the protocol to do.

So, with that long preface out of the way, have you considered something like the following:

// Gets a CBOR with specific fields out of mobile driver's license as an mdoc
const {response} = await navigator.credentials.get({
  identity: {
    providers: [{
      mdoc: {
        query: {
            // newly introduced query type
            type: "mDocQueryLanguage1", // there might be several mdoc query languages in time
            // mdoc specific query goes here
        }
       }
     }],
   }
 });
// Gets a Verifiable Credential using QueryByExample
const {response} = await navigator.credentials.get({
  identity: {
    providers: [{
      vc: {
        query: {
            // another query type
            type: "QueryByExample", // there are already several VC query languages 
                                                          //in development (VPR, PEv2, DIDComm)
            // QueryByExample specific query goes here
        }
       }
     }],
   }
 });
// Gets a Verifiable Credential using PresentationExchangev2
const {response} = await navigator.credentials.get({
  identity: {
    providers: [{
      vc: {
        query: {
            // yet another query type
            type: "PresentationExchangev2", 
            // PresentationExchangev2 specific query goes here
        }
       }
     }],
   }
 });

If we use this type-based approach, we might be able to get rid of the "vc/mdoc" part of the tree above (and probably should):

// Gets a Verifiable Credential using QueryByFrame
const {response} = await navigator.credentials.get({
  identity: {
      query: {
          // do we need providers[n].mdoc and providers[n].vc ? 
            type: "QueryLanguageX", 
            // QueryLanguageX specific query goes here
        }
       }
     }],
   }
 });

One argument is that the browsers don't need to understand query, except for perhaps the type. Applications will register for which types of query formats they support and the browser could just re-route queries to registered applications.

Now, there are more important questions that are important here, like: What happens if you don't want to hand the request off to a particular application unless you KNOW that they're going to respond w/ a credential? Or, how do you stop applications from lying about the query languages they support? Or, how does the browser know that the application speaks a specific query language AND sub-protocol necessary to fulfill the request? Those are still open questions, but a bit orthogonal to this concept that whatever this API ends up being doesn't try to prematurely lock in the query request/response formats for ecosystems that have not settled on best practices for heir query formats yet (and probably won't for several years). You also don't want to prevent innovation in the space by not allowing new query request/response formats to appear in time.

Does the above make sense? Is there any particular aspect that you'd like to see in a form that is more concrete?

Sakurann commented 3 months ago

I think from the browser API perspective, making the API protocol agnostic is sufficient and query language should be handled as part of the protocol, so no need for the API itself to be query language agnostic directly.

Speaking more concretely, for openid4vp. We took the feedback seriously and have designed a new query language that reflects the feedback and has support from this group: