From 3c194b56f1a01af0f37378bb60d3ffac9a4a07b2 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Wed, 28 Feb 2024 12:45:18 -0500 Subject: [PATCH 1/5] Add challenge endpoint. - add challenge creation endpoint - remove passing `options.challenge` and `options.domain` to incorrect endpoints --- components/Challenge.yml | 65 ++++++++++++++++++++++++++++++++++++++++ holder.yml | 11 ++++++- index.html | 14 ++++++++- verifier.yml | 34 ++++++++++++++++----- 4 files changed, 115 insertions(+), 9 deletions(-) create mode 100644 components/Challenge.yml diff --git a/components/Challenge.yml b/components/Challenge.yml new file mode 100644 index 0000000..7bccbf8 --- /dev/null +++ b/components/Challenge.yml @@ -0,0 +1,65 @@ +openapi: 3.0.0 +info: + version: "0.0.3-unstable" + title: VC API + description: This is an Experimental Open API Specification for the [VC Data Model](https://www.w3.org/TR/vc-data-model/). + license: + name: W3C Software and Document License + url: http://www.w3.org/Consortium/Legal/copyright-software. + contact: + name: GitHub Source Code + url: https://github.com/w3c-ccg/vc-api +paths: +components: + schemas: + CreateChallengeResult: + type: object + additionalProperties: false + description: Object containg a challenge + properties: + challenge: + type: string + description: The challenge value + ChallengeVerificationMetadata: + type: object + additionalProperties: false + description: Metadata about the verification of options.challenge. + properties: + verified: + type: string + description: Whether verification of the challenge was successful + uses: + type: string + description: The number of times options.challenge has been used + VerificationResultWithChallengeMetadata: + type: object + additionalProperties: false + description: Object summarizing a verification + properties: + checks: + type: array + description: The checks performed + items: + type: string + warnings: + type: array + description: Warnings + items: + type: string + errors: + type: array + description: Errors + items: + type: string + ChallengeVerificationMetadata: + type: object + additionalProperties: false + description: Metadata about the verification of options.challenge. + properties: + verified: + type: string + description: Whether verification of the challenge was successful + uses: + type: string + description: The number of times options.challenge has been used + diff --git a/holder.yml b/holder.yml index 77030e5..847c123 100644 --- a/holder.yml +++ b/holder.yml @@ -268,7 +268,9 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ProvePresentationResponse" + oneOf: + - $ref: "#/components/schemas/ProvePresentationResponse" + - $ref: "#/components/schemas/ProvePresentationResponseWithChallengeVerificationMetadata" "400": description: invalid input! "500": @@ -504,6 +506,13 @@ components: properties: verifiablePresentation: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + ProvePresentationResponseWithChallengeVerificationMetadata: + type: object + properties: + verifiablePresentation: + $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + ChallengeVerificationMetadata: + $ref: "./components/Challenge.yml#/components/schemas/ChallengeVerificationMetadata" NotifyPresentationAvailableRequest: type: object properties: diff --git a/index.html b/index.html index 2090ad4..a68ccaf 100644 --- a/index.html +++ b/index.html @@ -735,7 +735,7 @@

Verifying

+ data-api-path="/credentials/verify /presentations/verify /challenges">

Verify Credential

@@ -755,6 +755,18 @@

Verify Presentation

data-api-endpoint="post /presentations/verify">
+
+

Create Challenge

+

+

+ +
+

+The issuer should track the number of times a challenge has been passed to an endpoint as `options.challenge`. +

+
+
diff --git a/verifier.yml b/verifier.yml index 78288aa..c121f8c 100644 --- a/verifier.yml +++ b/verifier.yml @@ -62,11 +62,13 @@ paths: description: Parameters for verifying a verifiablePresentation. responses: "200": - description: Verifiable Presentation successfully verified! - content: - application/json: - schema: - $ref: "#/components/schemas/VerifyPresentationResponse" + description: Verifiable Presentation successfully verified! + content: + application/json: + schema: + oneOf: + - $ref: "#/components/schemas/VerifyPresentationResponse" + - $ref: "#/components/schemas/VerifyPresentationResponseWithChallengeMetadata" "400": description: Invalid or malformed input "413": @@ -75,6 +77,22 @@ paths: description: Request rate limit exceeded. "500": description: Internal Server Error + /challenges: + post: + summary: Passing an empty body to this endpoint creates and returns a challenge string in the response body. + operationId: challenge + description: Creates a challenge to be used as `options.challenge` in future requests. + responses: + "200": + description: Challenge created + content: + application/json: + schema: + $ref: "#/components/schemas/CreateChallengeResponse" + "400": + description: Invalid or malformed input + "500": + description: Internal server error components: securitySchemes: $ref: "./components/SecuritySchemes.yml#/components/securitySchemes" @@ -84,8 +102,6 @@ components: properties: verifiableCredential: $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential" - options: - $ref: "./components/VerifyOptions.yml#/components/schemas/VerifyOptions" VerifyCredentialResponse: $ref: "./components/VerificationResult.yml#/components/schemas/VerificationResult" VerifyPresentationRequest: @@ -102,3 +118,7 @@ components: $ref: "./components/Presentation.yml#/components/schemas/Presentation" VerifyPresentationResponse: $ref: "./components/VerificationResult.yml#/components/schemas/VerificationResult" + VerifyPresentationResponseWithChallengeMetadata: + $ref: "./components/Challenge.yml#/components/schemas/VerificationResultWithChallengeMetadata" + CreateChallengeResponse: + $ref: "./components/Challenge.yml#/components/schemas/CreateChallengeResult" From 1b61b18327fa8b1c284392ad02c9b4cd04120360 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Fri, 8 Mar 2024 12:52:56 -0500 Subject: [PATCH 2/5] Add firstVerified to challenge metadata, update wording, remove ChallengeVerificationMetadata from results. Co-authored-by: Manu Sporny Co-authored-by: Dave Longley --- components/Challenge.yml | 3 +++ index.html | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/components/Challenge.yml b/components/Challenge.yml index 7bccbf8..0535d13 100644 --- a/components/Challenge.yml +++ b/components/Challenge.yml @@ -28,6 +28,9 @@ components: verified: type: string description: Whether verification of the challenge was successful + firstVerified: + type: string + description: dateTimeStamp when the challenge was first verified. uses: type: string description: The number of times options.challenge has been used diff --git a/index.html b/index.html index a68ccaf..4b05c6b 100644 --- a/index.html +++ b/index.html @@ -763,7 +763,7 @@

Create Challenge

-The issuer should track the number of times a challenge has been passed to an endpoint as `options.challenge`. +The instance should create a challenge for use during verification and it should keep track of the number of times a challenge has been passed to verification endpoints as `options.challenge`.

From f41990c93cd9649556a0964b5669eed068f9eebd Mon Sep 17 00:00:00 2001 From: wes-smith Date: Fri, 8 Mar 2024 13:02:10 -0500 Subject: [PATCH 3/5] Remove ChallengeVerificationMetadata from responses.. --- components/Challenge.yml | 31 ------------------------------- holder.yml | 11 +---------- verifier.yml | 7 ++----- 3 files changed, 3 insertions(+), 46 deletions(-) diff --git a/components/Challenge.yml b/components/Challenge.yml index 0535d13..0b800a7 100644 --- a/components/Challenge.yml +++ b/components/Challenge.yml @@ -34,35 +34,4 @@ components: uses: type: string description: The number of times options.challenge has been used - VerificationResultWithChallengeMetadata: - type: object - additionalProperties: false - description: Object summarizing a verification - properties: - checks: - type: array - description: The checks performed - items: - type: string - warnings: - type: array - description: Warnings - items: - type: string - errors: - type: array - description: Errors - items: - type: string - ChallengeVerificationMetadata: - type: object - additionalProperties: false - description: Metadata about the verification of options.challenge. - properties: - verified: - type: string - description: Whether verification of the challenge was successful - uses: - type: string - description: The number of times options.challenge has been used diff --git a/holder.yml b/holder.yml index 847c123..3564fc8 100644 --- a/holder.yml +++ b/holder.yml @@ -268,9 +268,7 @@ paths: content: application/json: schema: - oneOf: - - $ref: "#/components/schemas/ProvePresentationResponse" - - $ref: "#/components/schemas/ProvePresentationResponseWithChallengeVerificationMetadata" + $ref: "#/components/schemas/ProvePresentationResponse" "400": description: invalid input! "500": @@ -506,13 +504,6 @@ components: properties: verifiablePresentation: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" - ProvePresentationResponseWithChallengeVerificationMetadata: - type: object - properties: - verifiablePresentation: - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" - ChallengeVerificationMetadata: - $ref: "./components/Challenge.yml#/components/schemas/ChallengeVerificationMetadata" NotifyPresentationAvailableRequest: type: object properties: diff --git a/verifier.yml b/verifier.yml index c121f8c..fcf3551 100644 --- a/verifier.yml +++ b/verifier.yml @@ -66,9 +66,8 @@ paths: content: application/json: schema: - oneOf: - - $ref: "#/components/schemas/VerifyPresentationResponse" - - $ref: "#/components/schemas/VerifyPresentationResponseWithChallengeMetadata" + $ref: "#/components/schemas/VerifyPresentationResponse" + "400": description: Invalid or malformed input "413": @@ -118,7 +117,5 @@ components: $ref: "./components/Presentation.yml#/components/schemas/Presentation" VerifyPresentationResponse: $ref: "./components/VerificationResult.yml#/components/schemas/VerificationResult" - VerifyPresentationResponseWithChallengeMetadata: - $ref: "./components/Challenge.yml#/components/schemas/VerificationResultWithChallengeMetadata" CreateChallengeResponse: $ref: "./components/Challenge.yml#/components/schemas/CreateChallengeResult" From 0f47ef806a614951124965dc8b2e65acaa79f318 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 12 Mar 2024 14:26:43 -0400 Subject: [PATCH 4/5] Apply changes from code review to formatting, property naming, and endpoint description. Co-authored-by: Dave Longley Co-authored-by: Ted Thibodeau Jr --- components/Challenge.yml | 2 +- holder.yml | 2 +- index.html | 2 +- verifier.yml | 10 +++++----- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/components/Challenge.yml b/components/Challenge.yml index 0b800a7..6393dcf 100644 --- a/components/Challenge.yml +++ b/components/Challenge.yml @@ -28,7 +28,7 @@ components: verified: type: string description: Whether verification of the challenge was successful - firstVerified: + firstVerifiedAt: type: string description: dateTimeStamp when the challenge was first verified. uses: diff --git a/holder.yml b/holder.yml index 3564fc8..77030e5 100644 --- a/holder.yml +++ b/holder.yml @@ -268,7 +268,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ProvePresentationResponse" + $ref: "#/components/schemas/ProvePresentationResponse" "400": description: invalid input! "500": diff --git a/index.html b/index.html index 4b05c6b..369a32d 100644 --- a/index.html +++ b/index.html @@ -763,7 +763,7 @@

Create Challenge

-The instance should create a challenge for use during verification and it should keep track of the number of times a challenge has been passed to verification endpoints as `options.challenge`. +The instance should create a challenge for use during verification, and track the number of times the challenge has been passed to verification endpoints as `options.challenge`.

diff --git a/verifier.yml b/verifier.yml index fcf3551..24f8289 100644 --- a/verifier.yml +++ b/verifier.yml @@ -62,11 +62,11 @@ paths: description: Parameters for verifying a verifiablePresentation. responses: "200": - description: Verifiable Presentation successfully verified! - content: - application/json: - schema: - $ref: "#/components/schemas/VerifyPresentationResponse" + description: Verifiable Presentation successfully verified! + content: + application/json: + schema: + $ref: "#/components/schemas/VerifyPresentationResponse" "400": description: Invalid or malformed input From 4f343891a6cf275085b86d528b08799165016b55 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 19 Mar 2024 14:52:30 -0400 Subject: [PATCH 5/5] Fix issuance options after rebase, add `security` to endpoint xml. --- components/IssueCredentialOptions.yml | 6 ------ verifier.yml | 4 ++++ 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/components/IssueCredentialOptions.yml b/components/IssueCredentialOptions.yml index 6e83fb1..ef810da 100644 --- a/components/IssueCredentialOptions.yml +++ b/components/IssueCredentialOptions.yml @@ -20,12 +20,6 @@ components: created: type: string description: The date and time of the proof (with a maximum accuracy in seconds). Defaults to current system time. - challenge: - type: string - description: A challenge provided by the party requesting the proof. For example, 6e62f66e-67de-11eb-b490-ef3eeefa55f2 - domain: - type: string - description: The intended domain of validity for the proof. For example, website.example mandatoryPointers: type: array items: diff --git a/verifier.yml b/verifier.yml index 24f8289..4b832d3 100644 --- a/verifier.yml +++ b/verifier.yml @@ -79,6 +79,10 @@ paths: /challenges: post: summary: Passing an empty body to this endpoint creates and returns a challenge string in the response body. + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] operationId: challenge description: Creates a challenge to be used as `options.challenge` in future requests. responses: