Skip to content

Latest commit

 

History

History
410 lines (345 loc) · 11.8 KB

README.md

File metadata and controls

410 lines (345 loc) · 11.8 KB

Verifiable Credentials v2.0 Test Suite

This is the test suite for the W3C Verifiable Credentials Data Model (VCDM) v2.0 specification.

Table of Contents

Background

This test suite provides interoperability tests for verifiable credential processors (issuers/verifiers) that support the W3C Verifiable Credentials Data Model v2.0.

Install

npm i

Setup

This test suite uses an HTTP API (based on the VC-API) for passing credentials into issuer and verifier implementations. If your implementation is not already compatible with the VC-API, it is possible to "wrap" the implementation in a minimal VC-API implementation (example code is available at https://github.com/Wind4Greg/Server-for-VCs).

Additionally, verifier implementations will need to be able to process Verifiable Credentials and Verifiable Presentations signed with eddsa-rdfc-2022. We recommend that any issuer endpoints used with this test suite also issue using eddsa-rdfc-2022. Both signed and unsigned Verifiable Presentations will be submitted for verification. Signed Verifiable Presentations from this suite will have a domain and challenge set. The domain should be the test repo, and the challenge is static.

Test Suite HTTP API

A request to issue a credential (/credentials/issue) will look like this:

POST /credentials/issue
{
  "credential": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "id": "http://university.example/credentials/1872",
    "type": ["VerifiableCredential", "ExampleAlumniCredential"],
    "issuer": "https://university.example/issuers/565049",
    "validFrom": "2023-07-01T19:23:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "alumniOf": {
        "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
        "name": "Example University"
      }
    }
  },
  "options": {}
}

The response from a call to issue a credential (/credentials/issue) will look like this:

HTTP/1.1 200 OK
{
  "verifiableCredential": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "id": "http://university.example/credentials/1872",
    "type": ["VerifiableCredential", "ExampleAlumniCredential"],
    "issuer": "https://university.example/issuers/565049",
    "validFrom": "2023-07-01T19:23:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "alumniOf": {
        "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
        "name": "Example University"
      }
    },
    "proof": {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-rdfc-2022",
      "created": "2023-06-18T21:19:10Z",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "https://university.example/issuers/565049#key-1",
      "proofValue": "zQeVbY4oey...V6doDwLWx"
    }
  }
}

A request to the verifier endpoint (/credentials/verify) for a credential will look like this:

POST /credentials/verify
{
  "verifiableCredential": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "id": "http://university.example/credentials/1872",
    "type": ["VerifiableCredential", "ExampleAlumniCredential"],
    "issuer": "https://university.example/issuers/565049",
    "validFrom": "2023-07-01T19:23:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "alumniOf": {
        "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
        "name": "Example University"
      }
    },
    "proof": {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-rdfc-2022",
      "created": "2023-06-18T21:19:10Z",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "https://university.example/issuers/565049#key-1",
      "proofValue": "zQeVbY4oey...V6doDwLWx"
    }
  },
  "options": {}
}

A response from the verifier endpoint (/credentials/verify) for a verifiable credential might look like this (only HTTP response codes are checked):

HTTP/1.1 200 OK
{
  "verified": true,
  "results": {},
  "problemDetails": []
}

The credential verifier endpoint is based on the VC-API Verify Credential endpoint.

A request to the verifier endpoint for a presentation (/presentations/verify) will look like this:

POST /presentations/verify
{
  "verifiablePresentation": {
    "@context": ["https://www.w3.org/ns/credentials/v2"],
    "type": ["VerifiablePresentation"],
    "holder": "did:example:holder123456789",
    "verifiableCredential": [{
      "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://www.w3.org/ns/credentials/examples/v2"
      ],
      "id": "http://university.example/credentials/1872",
      "type": ["VerifiableCredential", "ExampleAlumniCredential"],
      "issuer": "https://university.example/issuers/565049",
      "validFrom": "2023-07-01T19:23:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "alumniOf": {
          "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
          "name": "Example University"
        }
      },
      "proof": {
        "type": "DataIntegrityProof",
        "cryptosuite": "eddsa-rdfc-2022",
        "created": "2023-06-18T21:19:10Z",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "https://university.example/issuers/565049#key-1",
        "proofValue": "zQeVbY4oey...V6doDwLWx"
      }
    }],
    "proof": {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-rdfc-2022",
      "challenge": "08cf4ce0-2bd0-11ee-8622-83054936f200",
      "domain": "example.com",
      "created": "2023-06-18T21:19:10Z",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:example:holder123456789#key-1",
      "proofValue": "zQeVbY4y...oDwLWxV6d"
    }
  },
  "options": {
    "challenge": "secret",
    "domain": "example.com"
  }
}

A response from the verifier endpoint (/credentials/verify) for a verifiable presentation might look like this (only HTTP response codes are checked):

HTTP/1.1 200 OK
{
  "verified": true,
  "problemDetails": []
}

The presentation verifier endpoint is based on the VC API Verify Presentation endpoint.

Required Contexts

Implementations are expected to not error when any of the following context files are used in a verifiable credential or a verifiable presentation:

Usage

npm test

Testing Locally

To test a single implementation or endpoint running locally, you can copy localConfig.example.cjs to localConfig.cjs in the root directory of the test suite.

cp localConfig.example.cjs localConfig.cjs

This file must be a CommonJS module that exports an object containing a settings object (for configuring the test suite code itself) and an implementations array (for configuring the implementation(s) to test against).

The format of the object contained in the implementations array is identical to the one defined in the Testing locally section of VC Test Suite Implementations. The implementations array may contain more than one implementation object, enabling you to test multiple implementations in one run.

// localConfig.cjs defines local implementations
// Before running the tests, you can specify a BASE_URL, such as
// BASE_URL=http://localhost:40443/zDdfsdfs npm test
const baseUrl = process.env.BASE_URL || 'https://localhost:40443/id';
module.exports = {
  settings: {
    enableInteropTests: false, // default
    testAllImplementations: false // default
  },
  implementations: [{
    name: 'My Company',
    implementation: 'My Implementation Name',
    issuers: [{
      id: 'did:myMethod:implementation:issuer:id',
      endpoint: `${baseUrl}/credentials/issue`
    }],
    verifiers: [{
      id: 'did:myMethod:implementation:verifier:id',
      endpoint: `${baseUrl}/credentials/verify`
    }]
  }];

Allure Reporting

It's also possible to generate local allure reports for analyzing and debugging results. Allure is a language agnostic reporting framework which enables useful features for developers and test-suite designers.

To run the tests and browse the report, use the following commands:

# Running the tests
npx mocha tests/

# Running the reporting server
allure serve allure-results

Implementation

To add your implementation to this test suite, add a test manifest describing your implementation to the w3c/vc-test-suite-implementations repo by following the Adding a new implementation instructions.

All endpoints will need the tag vc2.0. A simplified manifest will roughly look like the following:

{
  "name": "My Company",
  "implementation": "My implementation",
  "issuers": [{
    "id": "",
    "endpoint": "https://issuer.mycompany.com/credentials/issue",
    "tags": ["vc2.0"]
  }],
  "verifiers": [{
    "id": "",
    "endpoint": "https://verifier.mycompany.com/credentials/verify",
    "tags": ["vc2.0"]
  }],
  "vpVerifiers": [{
    "id": "",
    "endpoint": "https://verifier.mycompany.com/presentations/verify",
    "tags": ["vc2.0"]
  }]
}

The example above is for a set of unauthenticated endpoints. You can add ZCAP or OAuth2 authentication to your endpoints.

See Adding a new implementation for more information.

Enveloping Proof

Implementers who rely on an enveloping proof securing mechanism can add the EnvelopingProof tag to their implementation registration.

This will instruct the test suite to conduct further testing on the implementation and assert the Data Model based on the payload instead of the direct output.

{
  "name": "My Company",
  "implementation": "My implementation",
  "issuers": [{
    "id": "",
    "endpoint": "https://issuer.mycompany.com/credentials/issue",
    "tags": ["vc2.0", "EnvelopingProof"]
  }],
  "verifiers": [{
    "id": "",
    "endpoint": "https://verifier.mycompany.com/credentials/verify",
    "tags": ["vc2.0", "EnvelopingProof"]
  }],
  "vpVerifiers": [{
    "id": "",
    "endpoint": "https://verifier.mycompany.com/presentations/verify",
    "tags": ["vc2.0", "EnvelopingProof"]
  }]
}

Contribute

See the CONTRIBUTING.md file in the w3c/vc-test-suite-implementations repo.

Pull Requests are welcome!

License

See the LICENSE.md file