From e8bfac63abf544d9a46d7baf2e88a54ede5b958e Mon Sep 17 00:00:00 2001 From: Benjamin Young Date: Thu, 17 Oct 2024 15:45:08 -0400 Subject: [PATCH 1/7] Improve language/examples around test suite API. --- README.md | 69 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 3decf19b..e7db259b 100644 --- a/README.md +++ b/README.md @@ -37,24 +37,29 @@ npm i ## Setup -To integrate with this test suite, you will need a -[VC-API compatible](https://w3c-ccg.github.io/vc-api/) issuer and verifier that -are capable of issuing and verifying verifiable credentials and verifiable -presentations. If your implementation is not VC-API compatible, it is possible -to "wrap" the implementation in a minimal VC-API implementation, example code -for which is available at . -Additionally, your verifier will need to be able to verify Verifiable Credentials +This test suite uses an HTTP API (based on the +[VC-API](https://w3c-ccg.github.io/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 +). + +Additionally, verifier implementations will need to be able to verify Verifiable Credentials and Verifiable Presentations signed with `eddsa-rdfc-2022`. We recommend -that any issuer endpoints submitted to this test suite also issue using +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. -The issuer endpoint will need to conform to the -[VC Issuer API](https://w3c-ccg.github.io/vc-api/#issue-credential). +### Test Suite HTTP API -A request to issue a credential (`/credentials/issue`) will look like this: + +A request to **issue a credential** (`/credentials/issue`) will look like this: + +```http +POST /credentials/issue +``` ```json { @@ -82,6 +87,10 @@ A request to issue a credential (`/credentials/issue`) will look like this: The response from a call to issue a credential (`/credentials/issue`) will look like this: +```http +HTTP/1.1 200 OK +``` + ```json { "verifiableCredential": { @@ -112,12 +121,13 @@ look like this: } ``` -The credential verifier endpoint will need to conform to the -[VC Verifier API](https://w3c-ccg.github.io/vc-api/#verify-credential). - -A request to the verifier endpoint (`/credentials/verify`) for a credential +A request to the **verifier endpoint** (`/credentials/verify`) for a credential will look like this: +```http +POST /credentials/verify +``` + ```json { "verifiableCredential": { @@ -147,13 +157,16 @@ will look like this: }, "options": {} } - ``` A response from the verifier endpoint (`/credentials/verify`) for a verifiable credential might look like this (only HTTP response codes are checked): +```http +HTTP/1.1 200 OK +``` + ```json { "checks": ["proof"], @@ -162,11 +175,18 @@ checked): } ``` -The presentation verifier endpoint will need to conform to the -[VC Verifier API](https://w3c-ccg.github.io/vc-api/#verify-presentation). +The credential verifier endpoint is based on the +[VC-API Verify Credential](https://w3c-ccg.github.io/vc-api/#verify-credential) +endpoint. -A request to the verifier endpoint for a presentation (`/presentations/verify`) -will look like this: +--- + +A request to the **verifier endpoint** for a presentation +(`/presentations/verify`) will look like this: + +```http +POST /presentations/verify +``` ```json { @@ -221,6 +241,10 @@ A response from the verifier endpoint (`/credentials/verify`) for a verifiable presentation might look like this (only HTTP response codes are checked): +```http +HTTP/1.1 200 OK +``` + ```json { "checks": ["proof"], @@ -229,6 +253,11 @@ checked): } ``` +The presentation verifier endpoint is based on the +[VC API Verify Presentation](https://w3c-ccg.github.io/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: From 5004b7e8cda7958e4a95a3fc496bd08eeaf51e1b Mon Sep 17 00:00:00 2001 From: Benjamin Young Date: Thu, 17 Oct 2024 16:12:14 -0400 Subject: [PATCH 2/7] Update TOC. --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index e7db259b..9abe3113 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,13 @@ specification. ## Table of Contents + + +- [Table of Contents](#table-of-contents) - [Background](#background) - [Install](#install) - [Setup](#setup) + - [Test Suite HTTP API](#test-suite-http-api) - [Usage](#usage) - [Testing Locally](#testing-locally) - [Allure Reporting](#allure-reporting) @@ -23,6 +27,8 @@ specification. - [Contribute](#contribute) - [License](#license) + + ## Background This test suite provides interoperability tests for verifiable credential From 55024ce41458bab9a50fb4a2016994d07f2ef42b Mon Sep 17 00:00:00 2001 From: Benjamin Young Date: Thu, 17 Oct 2024 17:06:01 -0400 Subject: [PATCH 3/7] Remove some repetition; point to imp repo. --- README.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 9abe3113..d9429541 100644 --- a/README.md +++ b/README.md @@ -334,11 +334,12 @@ allure serve allure-results ## Implementation -### VC-API -To add your implementation to this test suite You will need to add 3 endpoints to your implementation manifest. -- A credentials issuer endpoint (`/credentials/issue`) in the `issuers` property. -- A credentials verifier endpoint (`/credentials/verify`) in the `verifiers` property. -- A presentations verifier endpoint (`presentations/verify`) in the `vpVerifiers` property. +To add your implementation to this test suite, add a test manifest describing +your implementation to the +[`w3c/vc-test-suite-implementations`](https://github.com/w3c/vc-test-suite-implementations) +repo by following the +[Adding a new implementation](https://github.com/w3c/vc-test-suite-implementations/tree/main?tab=readme-ov-file#adding-a-new-implementation) +instructions. All endpoints will need the tag `vc2.0`. A simplified manifest will roughly look like the following: @@ -365,16 +366,13 @@ look like the following: } ``` -This example above is for a set of unauthenticated endpoints. You may add zcap -or oauth2 authentication to your endpoints. +This example above is for a set of unauthenticated endpoints. You may add +[ZCAP](https://w3c-ccg.github.io/zcap-spec/) +or OAuth2 authentication to your endpoints. -See the [vc-test-suite-implementations README here](https://github.com/w3c/vc-test-suite-implementations). - -To run the tests, some implementations require client secrets that can be passed -as env variables to the test script. To see which ones require client secrets, -you can check the -[vc-test-suite-implementations](https://github.com/w3c/vc-test-suite-implementations) -library. +See the +[Adding a new implementation](https://github.com/w3c/vc-test-suite-implementations/tree/main?tab=readme-ov-file#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. From 065a7fcccabf4294f90c1706d3f3453f9607ebb6 Mon Sep 17 00:00:00 2001 From: BigBlueHat Date: Mon, 4 Nov 2024 13:25:48 -0500 Subject: [PATCH 4/7] Improve language/links based on review. Co-authored-by: Patrick St-Louis <43082425+PatStLouis@users.noreply.github.com> Co-authored-by: Ted Thibodeau Jr --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d9429541..25cd3e90 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,6 @@ specification. -- [Table of Contents](#table-of-contents) - [Background](#background) - [Install](#install) - [Setup](#setup) @@ -50,7 +49,7 @@ compatible with the VC-API, it is possible to "wrap" the implementation in a minimal VC-API implementation (example code is available at ). -Additionally, verifier implementations will need to be able to verify Verifiable Credentials +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 @@ -366,11 +365,11 @@ look like the following: } ``` -This example above is for a set of unauthenticated endpoints. You may add +The example above is for a set of unauthenticated endpoints. You may add [ZCAP](https://w3c-ccg.github.io/zcap-spec/) -or OAuth2 authentication to your endpoints. +or [OAuth2 authentication](https://oauth.net/2/client-authentication/) to your endpoints. -See the +See [Adding a new implementation](https://github.com/w3c/vc-test-suite-implementations/tree/main?tab=readme-ov-file#adding-a-new-implementation) for more information. From e10bcf0a9ea4e842a8b0f8da5b62aa0d94cc0260 Mon Sep 17 00:00:00 2001 From: BigBlueHat Date: Thu, 7 Nov 2024 10:50:55 -0500 Subject: [PATCH 5/7] Make suggestions to README from TallTed. Co-authored-by: Ted Thibodeau Jr --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 25cd3e90..3087d8c7 100644 --- a/README.md +++ b/README.md @@ -365,7 +365,7 @@ look like the following: } ``` -The example above is for a set of unauthenticated endpoints. You may add +The example above is for a set of unauthenticated endpoints. You can add [ZCAP](https://w3c-ccg.github.io/zcap-spec/) or [OAuth2 authentication](https://oauth.net/2/client-authentication/) to your endpoints. From 842e87af00c41b4997019d20dfd62ac36bc6f9b7 Mon Sep 17 00:00:00 2001 From: Benjamin Young Date: Wed, 13 Nov 2024 15:47:42 -0500 Subject: [PATCH 6/7] Fix API response bodies. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3087d8c7..0b416c17 100644 --- a/README.md +++ b/README.md @@ -174,9 +174,9 @@ HTTP/1.1 200 OK ```json { - "checks": ["proof"], - "warnings": ["invalid-uri"], - "errors": ["invalid proof"] + "verified": true, + "results": {}, + "error": ["invalid proof"] } ``` @@ -252,7 +252,7 @@ HTTP/1.1 200 OK ```json { - "checks": ["proof"], + "verified": true, "warnings": ["invalid-uri"], "errors": ["invalid proof"] } From 603877adb0275525afde8465155ed2d89e67f0d5 Mon Sep 17 00:00:00 2001 From: BigBlueHat Date: Tue, 7 Jan 2025 14:29:56 -0500 Subject: [PATCH 7/7] Use problemDetails in place of errors. To match upstream VC API approach. Per code review feedback from @PatStLouis. Co-authored-by: Patrick St-Louis <43082425+PatStLouis@users.noreply.github.com> --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0b416c17..870caeb7 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,7 @@ HTTP/1.1 200 OK { "verified": true, "results": {}, - "error": ["invalid proof"] + "problemDetails": [] } ``` @@ -253,8 +253,7 @@ HTTP/1.1 200 OK ```json { "verified": true, - "warnings": ["invalid-uri"], - "errors": ["invalid proof"] + "problemDetails": [] } ```