diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/VcVerificationEndpoints.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/VcVerificationEndpoints.scala index 29f14bbebd..266e24fd20 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/VcVerificationEndpoints.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/VcVerificationEndpoints.scala @@ -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) } diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/ParameterizableVcVerification.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/ParameterizableVcVerification.scala index 7200824ec0..fc12dca251 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/ParameterizableVcVerification.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/ParameterizableVcVerification.scala @@ -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] diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerification.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerification.scala index 42aa1b626f..5d83c81070 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerification.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerification.scala @@ -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 { diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationParameter.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationParameter.scala index 0ceba92f3f..a10a501e00 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationParameter.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationParameter.scala @@ -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 { @@ -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] = @@ -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] = diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationRequest.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationRequest.scala index cdbd46a7ad..fe0bcdcb4c 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationRequest.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationRequest.scala @@ -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 @@ -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"))), @@ -50,7 +54,7 @@ object VcVerificationRequest { ParameterizableVcVerification(VcVerification.AlgorithmVerification, None), ParameterizableVcVerification(VcVerification.SchemaCheck, None), ParameterizableVcVerification(VcVerification.SemanticCheckOfClaims, None) - ) + ).toJson ) } diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResponse.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResponse.scala index f8c71f335e..93a2c82dc0 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResponse.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResponse.scala @@ -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) @@ -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), @@ -41,7 +43,7 @@ object VcVerificationResponse { VcVerificationResult(VcVerification.AlgorithmVerification, true), VcVerificationResult(VcVerification.SchemaCheck, true), VcVerificationResult(VcVerification.SemanticCheckOfClaims, true), - ) + ).toJson ) } diff --git a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResult.scala b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResult.scala index 3eab310e22..a7024bcc14 100644 --- a/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResult.scala +++ b/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResult.scala @@ -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 {