`vc-jwt-interop` test artefact repo

[bumblefudge]

New Work Item Proposal

See W3C-CCG New Work Item Process

Include Link to Abstract or Draft

More explanatory than an abstract might be skipping ahead to the Work Plan below. An initial/strawman list of test vectors from the input documents below would be our starting point.

Bibliography/sources:

* [Input document 1: VC data model test suite tests](https://github.com/w3c/vc-test-suite/tree/gh-pages/test/vc-data-model-1.0) * See in particular the [**JWT section**](https://github.com/w3c/vc-test-suite/blob/gh-pages/test/vc-data-model-1.0/50-jwt.js) * See also testing results in [Implementation guide](https://w3c.github.io/vc-test-suite/implementations/) * [Input document 2: VC-HTTP-API test vectors](https://github.com/w3c-ccg/vc-http-api/tree/main/packages/vc-http-api-test-server/__tests__) * See also [test suite results](https://w3c-ccg.github.io/vc-http-api/test-suite/spruce/) * [LDS-JWS2020](https://github.com/w3c-ccg/lds-jws2020) * test vectors coming soon, as a work item at DIF * [DID-JWT-VC](https://github.com/decentralized-identity/did-jwt-vc)

Work Item Owners

• Charles E. Lehner (@clehner, cel)
• Juan Caballero (@bumblefudge, bumblefudge)
• Third volunteer warmly welcome, particularly with JS-based testing background

Work Item Questions

Answer the following questions in order to document how you are meeting the requirements for a new work item at the W3C Credentials Community Group. Please note if this work item supports the Silicon Valley Innovation program or another government or private sector project.

1. Explain what you are trying to do using no jargon or acronyms.

Implementers of Verifiable Credentials wish to achieve and demonstrate interoperability and interworking of their implementations of Verifiable Credentials.

Background

The Verifiable Credentials Data Model (VC Data Model) specifies two formats of Verifiable Credentials: Linked Data Proofs (LDP), and JSON Web Tokens (JWT). Interoperability testing of Verifiable Credentials using the LDP format has been happening indirectly as part of the VC HTTP API work. Implementers of the JWT format of Verifiable Credentials wish to confirm interoperability of their implementations and possibly use the JWT format with the VC HTTP API in an interoperable way. VC HTTP API work item owners have concerns about interoperability of the JWT VC format and have asked that JWT VC implementers demonstrate interoperability outside of the VC HTTP API.

In discussion of a request to add support for JWT VCs to the VC HTTP API specification, @msporny and @OR13 asked @clehner to propose a work item:

Set up a vc-jwt-test-suite repository as a CCG work item, fill it with vc-jwt tests (positive and negative), and get multiple organizations to support passing all of the tests.

The topic was discussed on the 2021-07-06 CCG Weekly call, in which @OR13 proposed that the work item be called vc-jwt-interop, a name +1'd by many (including ex-chair @kimdhamilton ).

2. How is it done today, and what are the limits of the current practice?

Today, there are parts of the VC data model specification that some implementers have interpreted differently, particularly in how to map the inflexible restraints inherited from the JWT representation and those from the JSON-LD representation interact. There are a few minor issues, such as timestamp formatting, disagreements about mandatory fields and null/empty fields, a known but un-published security bug inherent to DID-core, etc. Also, LD Proofs and conventional JWT signatures are quite different.

Our working hypothesis is that these issues could all be fully or at least mostly addressed by a combination of:

1. existing test vectors and fixtures that can be refined or adapted to interop testing purposes,
2. non-normative guidance in the form of annotations of the test vectors documentation, and
3. capturing tribal knowledge in the form of clearly-documented recommendations to other efforts, including future instances of the VC-WG at W3C.

Existing testing happens in the Verifiable Credentials Data Model 1.0 Test Suite (VC Test Suite), in the VC HTTP API previously mentioned, and elsewhere such as in within particular implementations.

VC Test Suite

The VC Test Suite tests normative statements from the Verifiable Credentials Data Model (VC Data Model). Implementers can use the VC Test Suite by implementing a test driver program to generate Verifiable Credentials and/or Verifiable Presentations (VCs/VPs) using their implementation, and running the Test Suite with that program. The Test Suite calls the implementation-provided test driver program with various inputs to generate VCs/VPs, including invalid inputs, and evaluates the results for conformance to normative statements from the VC Data Model specification. From this test run, the Test Suite produces a report of the implementation's test results. The implementer may then submit their report for inclusion in the Test Suite repository. In the Test Suite repository, the collected implementation reports are tabulated in the Implementation Report for the Verifiable Credentials Data Model.

The VC Test Suite does not contain actual VCs for testing implementations; it is concerned with the data model and normative statements, but does not test implementations verifying actual signed verifiable credentials. It also does not therefore test verification relationships between VC issuers (or VP holders) and cryptographic material, and could not do so with did:key, for example, because the VC Data Model is supposed to be independent of Decentralized Identifiers (DIDs).

VC HTTP API Test Suite

The VC HTTP API contains a test suite with report generation. Implementations can use the VC HTTP API Test Suite by adding a configuration file to their local copy of the VC HTTP API repo, including the URLs of their API endpoints, and settings such as the supported proof types, DID methods, credential status types, and other options. The VC HTTP API Test Suite calls the configured API endpoints to request issuing verifiable credentials, and verifying verifiable credentials and verifiable presentations, including invalid inputs. The Test Suite evaluates the results and produces a report file. An implementer running a public instance of the VC HTTP API may submit their VC HTTP API Test Suite configuration for inclusion in the VC HTTP API repository. The VC HTTP API Test Suite is periodically run with the configured public endpoints, and the results are committed to the repository and hosted online, either collectively and/or per implementation (e.g. 1, 2).

The VC HTTP API Test Suite tests VCs/VPs indirectly, as the API must generate and verify VCs/VPs. The API assumes the Linked Data Proof format of Verifiable Credentials, in the API options and in the API type definitions. For showing test results in the API repository, implementers must host a publicly accessible instance of their implementation.

Major Implementations

So far, developers from the following projects have already vouched for the completeness of the following implementations and volunteered them for review:

• Transmute
• Consensys - DIF-governed
• Spruce
• [Identiproof] by Crosswords Cybersecurity for Univ of Toulousse ( gitlab )
• Microsoft - Note: comprehensive review may also require review of a few other SDKs

3. What is new in your approach and why do you think it will be successful?

Our approach is to try to be as descriptive and comprehensive as possible, identifying problems and suggesting solutions.

Proposed Work Plan

1. Create and collect test vectors, including adapting existing ones with JWT prior art and VC-HTTP-API interoperability in mind,
2. Review and iterate on those test vectors with JWT implementers willing to review our first draft,
3. iterated test vectors,
4. complete VC-JWT fixtures made from valid JWTs (no faker data, did:foo, or example.coms) that could be parsed by a standard JWT linter e.g. JWT.io
5. non-normative guidance in the form of annotations of the test vectors document, and
6. revisions/inputs towards the next iteration of the VC Data Model.

For test vectors, we would like to have self-contained, easily-verifiable credentials, such as by using did:key issuers, like in the VC HTTP API Test Suite, but in the JWT format. We would also consider using did:web issuers based in the work item repository, to show working with more features of DID documents. We may also support other DID methods and non-DID issuers, such as by mocking their DID/issuer documents locally, to explore and show greater interoperability. We would consider using one or more JWS (JSON Web Signature) algorithms for baseline support, and/or additional ones for broader interoperability.

4. How are you involving participants from multiple skill sets and global locations in this work item? (Skill sets: technical, design, product, marketing, anthropological, and UX. Global locations: the Americas, APAC, Europe, Middle East.)

VC-JWT implementations are actually quite diverse and far-flung, so we are hoping to work (particularly in stage 2 of the above workplan) with irregular meetings times to accomodate any volunteers who want to provide detailed feedback. We would also like to gather input from design/product/UX personnel by presenting to the Product Managers community of practice at the DIF in stage 2 as well. After stage 4, we would also like to call for volunteers from the greater CCG to help with the test report outputs and hosting design issues.

5. What actions are you taking to make this work item accessible to a non-technical audience?

Since the work item's purpose is to provide technical support to testing work items, non-technical audiences will likely have little interest in the concrete specifics of the repo and discussions. We would instead focus on getting non-technical participation on gathering its inputs (lists of test vectors based on specifications and iterated after review of implementations) and on refining its outputs (test scripts that can produce human-readable reports like those of the VC-HTTP-API and the VC data model test suite). But to the extent that the implementation reports may serve users and developers who want to understand interoperability of JWT VCs, we would aim to make it useful, objective, and easy to understand.

As work item contributors, we would be prepared to answer questions of any level, and provide pointers for learning.

[bumblefudge]

Ooops sorry @kimdhamilton I think @mprorock should probably be tagged for review :D

[OR13]

I am happy to support this, and contribute to implementation side.

There are some things we learned from the vc-http-api, which probably worth tackling upfront.

1. addressing discoverability upfront
2. addressing security upfront
3. using tools like postman can make it easier for non js developers to contribute
4. take error handling seriously, and provide reasons for failures, that can be tested against (such as expiration)
5. automate report generation with CI/CD

Regarding did:web, maybe we can use it for discovery, but not for vc and vp's, by putting did:key's in the alsoKnownAs.

I think the goal should be to establish that interop exists, and then work to merge this into the vc-http-api before they diverge any further.

[vsnt]

I'd like to discuss this item on the 7/27 call.

[Sakurann]

Isn't it "Encrypted Data Vaults and Identity Hub Updates" on 7/27?

[vsnt]

Yes, I didn't expect these items would need a whole meeting to discuss. Does this item need an entire CCG call to discuss?

[Sakurann]

no, I don't think this should take a whole hour. 7/27 it is, than.

[David-Chadwick]

Please change "Verifiable Credentials/Crosswords impl for Univ of Toulousse (VC-WG test suite results" to

Identiproof from Crossword Cybersecurity.

What do you want its hotlink to point to? Is this OK: https://gitlab.com/verifiablecredentials.info

Wrt to the Kent/Toulouse implementation, I now have nothing to do with it now. I can ask them if they would like to participate

[David-Chadwick]

@OR13 wrote

1. addressing discoverability upfront

Because our implementation does not use DIDs for issuers (we use X.509 DV PKCs) then you can discover our Issuer meta-information in the same way that OIDC operates i.e. /.well-known/openid-configuration. I would like us to register "verifiablecredential-configuration" or similar with the IANA well known registry. We can bike shed the term to be registered e.g.: vc-metainformation, vc-config, etc. I don't really mind what string we choose.

[bumblefudge]

I am supportive of multiple discovery mechanisms, and I personally think that interop with VC-JWTs with did:web or non-DID issuers like X.509 are worth including, but I defer to the consensus of the future group, particularly since I personally couldn't implement those tests so usually vote +/-0.5 as a non-doer. Is OIDF already aligned on the structure and contents of that verifiable-configuration object and IANA registry entry, or does it depend on aspects that won't be finalized until the next major version? Or, to ask it another way, why hasn't someone registered it with IANA already?

[David-Chadwick]

@bumblefudge The VC Issuer is not necessarily an OIDC OP. In the OIDC SIOP flow, the user's wallet gets its VCs by some unspecified means from its issuers and packages them into a VP. The OIDC RP must pass the VP to a component for verification. If this verification component finds a VC was signed by an issuer with an X.509 PKC (and the issuer is set to the http URL of the issuer and not to a DID), then it needs a method to pick up the PKC from this URL. The well known VC config http end point will be used for this. This is independent of OIDC or of any application level protocol. It is using the web instead of a blockchain to get the public key of the issuer.

[TallTed]

"The well known VC config http end point" does not yet exist in IANA registration, nor even submission, so far as I know, so while it could someday be used as "a method to pick up the PKC from this URL", it cannot now.

I think that this should probably only be spoken of as a "maybe in the future" thing, given that we (VCWG, CCG, etc.) have not even done the preliminary work necessary to make a .well-known setup work upon IANA registration.

Further, I think that this sub-thread should go into an issue of its own, as I don't think it's particularly relevant to the "vc-jwt-interop test artefact repo".

[OR13]

A related spec I worked on: https://identity.foundation/.well-known/resources/did-configuration/

I don't think Microsoft ever registered it with IANA though.

You could use this spec to get answers regarding discoverability

[msporny]

You could use this spec to get answers regarding discoverability

Just as a quick comment... I continue to believe that .well-known, in general, is a bad hack and is an anti-pattern. We shouldn't be using the feature for discoverability for these reasons:

1. .well-known is a well-known hack... read Appendix B in the spec itself -- specifically, "Aren't well-known locations bad for the Web?"
2. Not all deployments will have control over .well-known.
3. Some SaaS deployments will have many deployed systems under a single domain (multi-tenancy). .well-known is a bad solution for discoverability in multi-tenant systems.
4. Having multiple discovery mechanism create problems when the discovery mechanisms contradict each other.

Instead, we should be providing a configuration URL to clients that is provided by the service provider and clients should bootstrap from there. This is the conclusion we're starting to slowly come to in the EDV work, and if we do that, it solves all 3 problems above. That said, .well-known could make sense for domain-wide configurations, such as binding an x509 cert to a DID, but even then, we should debate whether or not a configuration URL might make more sense there.

[David-Chadwick]

@msporny The well-known path appended to the DNS name of the issuer is such a configuration URL. If you are suggesting some other configuration URL, can you please explain how a verifier can obtain this from an issuer it is unaware of until it receives its first VC from this issuer (via the holder). Are you proposing a new property that is to be inserted into each issued VC?

[msporny]

@msporny The well-known path appended to the DNS name of the issuer is such a configuration URL.

The current proposal seems to state: "The well known URL is the only way to get to this information" vs. what I'm saying, which is "Any URL can be provided to get directly to this information, if people want to use .well-known, go ahead, but the general approach is any URL will do."

Are you proposing a new property that is to be inserted into each issued VC?

Not at this time, no... I don't understand your use case... more below

can you please explain how a verifier can obtain this from an issuer it is unaware of until it receives its first VC from this issuer (via the holder).

Why would a verifier need to do this? Why can't they just use did:web... I don't understand your use case. Can you please outline your use case? I'm getting the impression that what you're after is different from what @OR13 pointed to...

Also, this needs to be moved to a separate issue.

[David-Chadwick]

@msporny You misunderstood me. I am saying that "/.well-known/vc-config"( or similar) will be a well known way of finding the meta information about an Issuer if you have its DNS name. I am not saying it is the only way, but it is a good way if you don't use DIDs and blockchains. You said "Why would a verifier need to do this? Why can't they just use did:web... ". Ans. Because I don't want our customers to have to know anything about DIDs or blockchains as these are an expensive and unnecessary add-on to VC eco-systems in my opinion.

[msporny]

will be a well known way of finding the meta information about an Issuer if you have its DNS name

What sort of meta information would be published at that URL? Do you have an example?

You misunderstood me. I am saying that "/.well-known/vc-config"( or similar) will be a well known way of finding the meta information about an Issuer if you have its DNS name.

Yes, this is where I thought you were going with your statement. So, rather than use "did:web", which the industry seems to be settling on as a good way to do this, what you would like is yet another way of publishing the same sort of information you could express via "did:web" in the DID Document using another mechanism?

I don't want our customers to have to know anything about DIDs or blockchains as these are an expensive and unnecessary add-on to VC eco-systems in my opinion.

Why do your customers need to know anything about DIDs or blockchains? We don't get into those discussions with a lot of our customers, and the ones where we do get into that discussion results in advantages that you just don't get with the Web. In any case, "did:web" seems to strike the right compromise.

All that said, I'd need to see exactly what sort of information you're trying to publish via this mechanism. I suggest you propose a specification that the community can consider as that'll help us have a productive discussion around the benefits and drawbacks of the approach you're proposing.

[David-Chadwick]

@msporny Thanks for the invitation to write a specification. We are currently working on this. It is a JSON document that contains (possibly pointers to) all the information a verifier needs to know in order to validate VCs issued by this issuer e.g. its DV PKC, schemas and at_contexts

[OR13]

I am happy to support this work item in an official capacity as Transmute.

[vsnt]

Discussed at 7/27 call. No community concerns. @OR13 to be added as third co-owner. Will give 7 days for the community to comment on this thread and then open up this work item.

[TallTed]

@David-Chadwick -- Please codefence all @entities (such as @contexts, here) unless you intend to signal that user that there is something they should pay attention to ... which I'm pretty sure was not the case, here, so please edit that comment.

[vsnt]

I have added this work item to the 9/21 CCG call agenda to review+discuss with the community. Would the owners please attend this meeting. Thank you. https://lists.w3.org/Archives/Public/public-credentials/2021Sep/0074.html

[OR13]

@vsnt yes, I am planning on attending.

[vsnt]

Per the CCG 9/21 call, this work item is on hold, and will be revisited Jan 2022 after the current DIF sprint completes.

[peacekeeper]

Sounds very useful!

The VC HTTP API contains a test suite with report generation.

Quick note that this has by now been moved into a separate repo: https://github.com/w3c-ccg/vc-http-api-test-suite

developers from the following projects have already vouched for the completeness of the following implementations

We have also implemented basic support for VC-JWT in our library verifiable-credentials-java and would like to participate in the testing effort whenever that is appropriate.

[vsnt]

Check in on 1/18/22 call. Project is almost done, but not released yet. Plan is to have the DIF group present to CCG mid-Feb and discuss where it makes sense to do follow-on work.

[bumblefudge]

Whoops cleaning up old issues, seems I left this open loooong after abandoning the project. I think this test suite over at DIF might have to suffice, I no longer have the bandwidth to project-manage, much less drive, this work going forward.