BbsBls sig test fixtures (valid by various W3C docs) not permitted by current OpenAPI spec

[vdods]

LinkedDataProof specifies only a proof accepting jws as the signature https://github.com/w3c-ccg/vc-http-api/blob/main/docs/components/LinkedDataProof.yml :

    LinkedDataProof:
      type: object
      description: A JSON-LD Linked Data proof.
      properties:
        type:
          type: string
          description: Linked Data Signature Suite used to produce proof.
        created:
          type: string
          description: Date the proof was created.
        verificationMethod:
          type: string
          description: Verification Method used to verify proof.
        proofPurpose:
          type: string
          description: The purpose of the proof to be used with verificationMethod.
        jws:
          type: string
          description: Detached JSON Web Signature

but the various test fixtures allow for other schemas, e.g. case-18.json https://github.com/w3c-ccg/vc-http-api/blob/main/packages/vc-http-api-test-server/__fixtures__/verifiableCredentials/case-18.json :

  "proof": {
    "type": "BbsBlsSignature2020",
    "created": "2021-02-23T19:36:07Z",
    "proofPurpose": "assertionMethod",
    "proofValue": "qSjCNJzoDV3hv3gBPoUNN9m5lj8saDBBxC0iDHuFTXXz4PbbUhecmn/L3rPoGuySNatqC4I8VE22xQy0RAowIxoZCC+B2mZQIAb+/JGlXeAlWgEQc71WipfvsfqSn+KmR/rN1FREOy3rtSltyQ92rA==",
    "verificationMethod": "did:key:zUC724vuGvHpnCGFG1qqpXb81SiBLu3KLSqVzenwEZNPoY35i2Bscb8DLaVwHvRFs6F2NkNNXRcPWvqnPDUd9ukdjLkjZd3u9zzL4wDZDUpkPAatLDGLEYVo8kkAzuAKJQMr7N2#zUC724vuGvHpnCGFG1qqpXb81SiBLu3KLSqVzenwEZNPoY35i2Bscb8DLaVwHvRFs6F2NkNNXRcPWvqnPDUd9ukdjLkjZd3u9zzL4wDZDUpkPAatLDGLEYVo8kkAzuAKJQMr7N2"
  }

case-19.json (values truncated for brevity) https://github.com/w3c-ccg/vc-http-api/blob/main/packages/vc-http-api-test-server/__fixtures__/verifiableCredentials/case-19.json :

  "proof": {
    "type": "BbsBlsSignatureProof2020",
    "created": "2021-02-23T19:37:24Z",
    "nonce": "lEixQKDQvRecCifKl789TQj+Ii6YWDLSwn3AxR0VpPJ1QV5htod/0VCchVf1zVM0y2E=",
    "proofPurpose": "assertionMethod",
    "proofValue": "AAwP/4n.....c1IJp",
    "verificationMethod": "did:key:zUC724vuG...7N2#zUC724v...7N2"
  }

[msporny]

The group discussed this on the 2022-04-12 telecon. Someone needs to take an action to look at this and ensure we support the new Data Integrity work, the legacy jws work, and the new VC-JWT work.

[msporny]

We discussed alternative proof formats on the 2022-12-06 telecon:

@PatStLouis started by explaining that they are doing work w/ customers that want to issue VCs and be compliant with W3C. Solutions are being assessed, want to see how they can use standards in W3C space, given that information, two tests suites -- vc test suite (older test suite run from command line), 2nd test suite (leverage VC Issuer and Verifier test suites). Their solution is exclusive to VC-JWT, there are tests for JWTs, different from rest of tests. Current test suite has command line params -- decode input, JWT w/o JWS, specify audience for presentation. Regarding VC API - not much available on JWT, in order of importance, three questions:

1. Regarding options field, when you want to issue/prove presentation discussion about options -- not required, what's optional, type was removed -- options field, what is the purpose of the options field? Same for all implementations, or field that allows different implementations to have different parameters - in case of JWT, would it make sense for solution to support JWT to have options similar to VC Test Suite that signals whether input is JWT itself, should there be option for audience, same for using embedded proof/external proof (noJws flag represents). Does it make sense to have different implementations have different options used for their solution (to customize), if so, should options be discoverable?

@dlongley noted that it should be whatever is standard in the spec, specific implementation behaviour should be done in issuer instance you're hitting. Throughout lifetime of API, too many options into issue endpoint where we end up having service be a "jack of all trades" -- all combinations need to be supported by one endpoint, probably not possible in every case. It's been much simpler design to have specific types of things to issue, specific settings, generate an issuer instance that is bound to those options and use those as the endpoint. Client has JWT or some different data, it should know which instance to send it to rather than sending it to a single endpoint with an option and try to make that work with the other possibilities. @PatStLouis noted that he figured that was what we meant -- would it make sense to have pre-configured options discoverable, like a GET request on pre-configured options. @dlongley said yes, hitting a configuration instance gets a configuration -- but concerned about more general discovery mechanism. Much of this is probably going to be configured and used out of band rather than being dynamically discoverable. @PatStLouis and @dlongley agreed that it didn't make sense to do dynamic configuration discovery in production. @PatStLouis asked "what if there was a solution that requires additional input?" -- for audience, solution wants there to be audience as a parameter for JWT, how would you do that? @dlongley asked for verification? @manu noted that the design we currently have enables an endpoint to be configured to take arbitrary input for the credential and provide arbitrary output for the secured credential. There were people in the group initially that wanted us to focus on VCs and Data Integrity, but have since stopped participating, so we could open up the aperature a bit to work on other credential types -- that said, it's dangerous to do that and we could end up trying to boil the ocean. However, with VC-JWTs specifically, it would be fairly straightforward to take a credential in as input, specify JWT-specific options in options, and encapsulate the result in a VC-JWT and return that in the response. @PatStLouis noted that was helpful, need to know how to approach this -- rewrite API, motivated to use VC API, align with what's being worked on here even though nothing exists for VC-JWT yet.

2. The output for the calls, when a call is made to /credentials/issue the return we're expecting is a VC per the data model, in a JWT -- do we want to allow a return that is a VC-JWT, or do we want to avoid that because that would complicate things?

@PatStLouis noted it's forseeable to have something that would output a VC-JWT. @msporny agreed. The only change that would be required is a vcJwt field in the return object and possibly options values that enable setting something like the aud field.

3. With embedded proofs in contrast w/ external proofs, tried to see how JWT could move from one to the other, in VC Test Suite "noJwt/noJws", you need proof field, not 100% clear how to move from one to another. One component of JWS can be mapped, how to map these?

@msporny noted that you can't map from one to the other... a JWT does not allow for that sort of mapping. It is possible to map a Data Integrity proof to different carriers (like YAML or CBOR), but not to/from a JWT, which doesn't perform a canonicalization step, which means that you can't transform the base64 message in any way.

4. How can we test this stuff? VC Test Suite is still useful, at end of day, still just evaluates an output and tests it against a specification. There hasn't been breaking changes in specification.

The plan moving forward is to transform the old VCDM 1.0 and 1.1 tests to use the VC API issue/verify endpoints to test to see if a valid data model is being produced.

To progress the issue related to what securing mechanisms are allowed, and which ones are not, individuals seeking other securing mechanisms will need to put in the effort to implement extensions, such as VC-JWT, against the specification.

[msporny]

The group discussed this topic again on the 2023-06-20 telecon:

It was noted that things have moved on from where the issue was a while ago. Namely, we now have endpoint instances, which enable us to have different proof formats and could theoretically issue any Data Integrity Proof format, or AnonCredsv1, or VC-JWT, or SD-JWT, or mdoc, or any other related digital credential format. @PatStLouis noted that testing could be a concern as that might balloon the number of tests we have to write. There was a question from GregB about how much of this comes under media type selection / content negotiation. For example, if someone makes a call to /credentials/issue and requests application/vc+ld+jwt, then would the endpoint return a VC-JWT instead of a Data Integrity protected credential? @msporny suggested that it requires more than just a media type to create a specific type of securing mechanism. It was suggested that specific endpoints can return specific types of secured data.

The VC API components need to be updated to match the latest Data Integrity work in the VCWG. Specifically, this file needs to be updated: https://github.com/w3c-ccg/vc-api/blob/main/components/LinkedDataProof.yml (and anything that integrates with it).

If implementers would like to see other securing formats supported by the API, the group asks that issues be raised for the specific securing format and details on how they would be implemented be included in the issue.

[msporny]

The group discussed this on 2023-12-05 and noted that we just need to align w/ work at W3C VCWG.

[msporny]

PR #358 has been raised to address this issue. This issue will be closed once PR #358 has been merged.

[msporny]

PR #358 has been merged, closing.