Skip to content

Commit

Permalink
fix: VC Verification API Doc (#1118)
Browse files Browse the repository at this point in the history
Signed-off-by: Bassam Riman <bassam.riman@iohk.io>
Co-authored-by: Yurii Shynbuiev - IOHK <yurii.shynbuiev@iohk.io>
  • Loading branch information
CryptoKnightIOG and yshyn-iohk committed May 31, 2024
1 parent 24c62f4 commit d70d4b7
Show file tree
Hide file tree
Showing 7 changed files with 91 additions and 26 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,14 @@ object VcVerificationEndpoints {
endpoint.post
.tag("Verifiable Credentials Verification")
.name("verify")
.summary("As a Verifier, verify a set of credentials")
.description("As a Verifier, verify a set of credentials")
.summary("Verify a set of credentials as a Verifier")
.description("Endpoint to verify a set of verifiable credentials as a Verifier.")
.securityIn(apiKeyHeader)
.securityIn(jwtAuthHeader)
.in("verification" / "credential")
.in(extractFromRequest[RequestContext](RequestContext.apply))
.in(jsonBody[List[http.VcVerificationRequest]].description("List of VC to verify"))
.out(statusCode(StatusCode.Ok).description("List of VC verification outcome"))
.in(jsonBody[List[http.VcVerificationRequest]].description("List of verifiable credentials to verify"))
.out(statusCode(StatusCode.Ok).description("List of verifiable credentials verification outcomes"))
.out(jsonBody[List[http.VcVerificationResponse]])
.errorOut(basicFailuresAndForbidden)
}
Original file line number Diff line number Diff line change
@@ -1,12 +1,23 @@
package org.hyperledger.identus.verification.controller.http

import sttp.tapir.Schema
import sttp.tapir.Schema.annotations.{description, encodedExample}
import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}

/** Represents a parameterizable verification to be performed on a verifiable credential.
*
* @param verification
* The type of verification to perform.
* @param parameter
* Optional parameter for the verification.
*/
final case class ParameterizableVcVerification(
@description("The type of verification to perform.")
verification: VcVerification,
@description("Optional parameter for the verification.")
parameter: Option[VcVerificationParameter]
)

object ParameterizableVcVerification {
given encoder: JsonEncoder[ParameterizableVcVerification] =
DeriveJsonEncoder.gen[ParameterizableVcVerification]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,36 @@ import org.hyperledger.identus.api.http.ErrorResponse
import org.hyperledger.identus.pollux.core.service
import org.hyperledger.identus.pollux.core.service.verification.VcVerification as ServiceVcVerification
import sttp.tapir.Schema
import sttp.tapir.Schema.annotations.description
import zio.{IO, *}
import zio.json.{JsonDecoder, JsonEncoder}

/** Enum representing the various types of verifications that can be performed on a verifiable credential.
*/
enum VcVerification {
case SignatureVerification
case IssuerIdentification
case ExpirationCheck
case NotBeforeCheck
case AudienceCheck
case SubjectVerification
case IntegrityOfClaims
case ComplianceWithStandards
case RevocationCheck
case AlgorithmVerification
case SchemaCheck
case SemanticCheckOfClaims
@description("Verify the digital signature of the credential.") case SignatureVerification

@description("Verify the identity of the issuer of the credential.") case IssuerIdentification

@description("Check if the credential has expired.") case ExpirationCheck

@description("Check if the credential is valid before a certain date and time.") case NotBeforeCheck

@description("Verify the audience for which the credential is intended.") case AudienceCheck

@description("Verify the subject of the credential.") case SubjectVerification

@description("Check the integrity of the claims in the credential.") case IntegrityOfClaims

@description("Ensure the credential complies with required standards.") case ComplianceWithStandards

@description("Check if the credential has been revoked.") case RevocationCheck

@description("Verify the algorithm used for creating the credential.") case AlgorithmVerification

@description("Validate the schema of the credential.") case SchemaCheck

@description("Perform a semantic check on the claims of the credential.") case SemanticCheckOfClaims
}

object VcVerification {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
package org.hyperledger.identus.verification.controller.http

import sttp.tapir.Schema
import sttp.tapir.Schema.annotations.{description, encodedExample}
import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}

import java.time.OffsetDateTime

/** Base trait for verification parameters.
*
* @param parameterType
* The type of the parameter.
*/
sealed trait VcVerificationParameter(val parameterType: String)

object VcVerificationParameter {
Expand All @@ -31,7 +37,16 @@ object VcVerificationParameter {

}

case class DidParameter(did: String) extends VcVerificationParameter("DidParameter")
/** Parameter for DID-based verifications.
*
* @param did
* The DID (Decentralized Identifier) to use for verification.
*/
case class DidParameter(
@description("The DID (Decentralized Identifier) to use for verification.")
@encodedExample("did:prism:issuer")
did: String
) extends VcVerificationParameter("DidParameter")

object DidParameter {
given encoder: JsonEncoder[DidParameter] =
Expand All @@ -43,7 +58,16 @@ object DidParameter {
given schema: Schema[DidParameter] = Schema.derived
}

case class DateTimeParameter(dateTime: OffsetDateTime) extends VcVerificationParameter("DateTimeParameter")
/** Parameter for date-time based verifications.
*
* @param dateTime
* The date and time to use for verification.
*/
case class DateTimeParameter(
@description("The date and time to use for verification.")
@encodedExample("2022-03-10T12:00:00Z")
dateTime: OffsetDateTime
) extends VcVerificationParameter("DateTimeParameter")

object DateTimeParameter {
given encoder: JsonEncoder[DateTimeParameter] =
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@ import org.hyperledger.identus.pollux.core.service.verification.VcVerificationRe
import sttp.tapir.Schema
import sttp.tapir.Schema.annotations.{description, encodedExample}
import zio.{IO, *}
import zio.json.*
import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}
import zio.json.ast.Json
import zio.json.ast.Json.*

import java.time.OffsetDateTime

Expand All @@ -29,8 +32,9 @@ object VcVerificationRequest {
)

object parameterizableVcVerifications
extends Annotation[List[ParameterizableVcVerification]](
description = "The list of Verifications to verify. All verifications run if Verifications left empty",
extends Annotation[String](
description =
"The list of verifications to perform on the credential. If the list is empty, all available verifications will be performed.",
example = List(
ParameterizableVcVerification(VcVerification.SignatureVerification, None),
ParameterizableVcVerification(VcVerification.IssuerIdentification, Some(DidParameter("did:prism:issuer"))),
Expand All @@ -50,7 +54,7 @@ object VcVerificationRequest {
ParameterizableVcVerification(VcVerification.AlgorithmVerification, None),
ParameterizableVcVerification(VcVerification.SchemaCheck, None),
ParameterizableVcVerification(VcVerification.SemanticCheckOfClaims, None)
)
).toJson
)
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@ package org.hyperledger.identus.verification.controller.http
import org.hyperledger.identus.api.http.Annotation
import sttp.tapir.Schema
import sttp.tapir.Schema.annotations.{description, encodedExample}
import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}
import zio.json.*
import zio.json.ast.Json
import zio.json.ast.Json.*

final case class VcVerificationResponse(
@description(VcVerificationResponse.annotations.credential.description)
Expand All @@ -20,14 +22,14 @@ object VcVerificationResponse {

object credential
extends Annotation[String](
description = "Encoded Verifiable Credential to verify",
description = "Encoded Verifiable Credential that was verified.",
example =
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
)

object vcVerificationResults
extends Annotation[List[VcVerificationResult]](
description = "The list executed Verifications",
extends Annotation[String](
description = "The list of verification results for each verification performed on the credential.",
example = List(
VcVerificationResult(VcVerification.SignatureVerification, true),
VcVerificationResult(VcVerification.IssuerIdentification, true),
Expand All @@ -41,7 +43,7 @@ object VcVerificationResponse {
VcVerificationResult(VcVerification.AlgorithmVerification, true),
VcVerificationResult(VcVerification.SchemaCheck, true),
VcVerificationResult(VcVerification.SemanticCheckOfClaims, true),
)
).toJson
)
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,20 @@ package org.hyperledger.identus.verification.controller.http

import org.hyperledger.identus.pollux.core.service.verification.VcVerificationResult as ServiceVcVerificationResult
import sttp.tapir.Schema
import sttp.tapir.Schema.annotations.description
import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}

/** Represents the result of a verification performed on a verifiable credential.
*
* @param verification
* The type of verification that was performed.
* @param success
* Indicates whether the verification was successful.
*/
final case class VcVerificationResult(
@description("The type of verification that was performed.")
verification: VcVerification,
@description("Indicates whether the verification was successful.")
success: Boolean
)
object VcVerificationResult {
Expand Down

0 comments on commit d70d4b7

Please sign in to comment.