feat(agent): improve OAS spec and refactor DidCommHttpServer code (#615)

* fix(agent): ATL-3796 - exhaustively return issue credential role and protocolState

* fix(agent): return role as part of presentation status

* fix(agent): ATL-5230 - return full presentation record instead of just presentation ID in present-proof protocol

* fix(agent): support undefined env variable (null value) for webhook config params in docker-compose.yml

* chore(agent): refactor, cleanup, and improve error logging in DidCommHttpService

infrastructure/shared/docker-compose.yml

@@ -100,8 +100,8 @@ services:
       SECRET_STORAGE_BACKEND: postgres
       DEV_MODE: true
       WALLET_SEED:
-      WEBHOOK_URL: ${WEBHOOK_URL}
-      WEBHOOK_API_KEY: ${WEBHOOK_API_KEY}
+      WEBHOOK_URL:
+      WEBHOOK_API_KEY:
     depends_on:
       db:
         condition: service_healthy

prism-agent/service/server/src/main/scala/io/iohk/atala/agent/server/DidCommHttpServerError.scala

@@ -0,0 +1,8 @@
+package io.iohk.atala.agent.server
+
+sealed trait DidCommHttpServerError
+
+object DidCommHttpServerError {
+  case class RequestBodyParsingError(error: String) extends DidCommHttpServerError
+  case class DIDCommMessageParsingError(error: String) extends DidCommHttpServerError
+}

prism-agent/service/server/src/main/scala/io/iohk/atala/issue/controller/http/IssueCredentialRecord.scala

@@ -4,9 +4,9 @@ import io.iohk.atala.api.http.Annotation
 import io.iohk.atala.issue.controller.http.IssueCredentialRecord.annotations
 import io.iohk.atala.mercury.model.{AttachmentDescriptor, Base64}
 import io.iohk.atala.pollux.core.model.IssueCredentialRecord as PolluxIssueCredentialRecord
-import sttp.tapir.Schema
-import sttp.tapir.Schema.annotations.{description, encodedExample}
+import sttp.tapir.Schema.annotations.{description, encodedExample, validate}
 import sttp.tapir.json.zio.schemaForZioJsonValue
+import sttp.tapir.{Schema, Validator}
 import zio.json.*
 import zio.json.ast.Json
 
@@ -68,9 +68,11 @@ final case class IssueCredentialRecord(
     updatedAt: Option[OffsetDateTime] = None,
     @description(annotations.role.description)
     @encodedExample(annotations.role.example)
+    @validate(annotations.role.validator)
     role: String,
     @description(annotations.protocolState.description)
     @encodedExample(annotations.protocolState.example)
+    @validate(annotations.protocolState.validator)
     protocolState: String,
     @description(annotations.jwtCredential.description)
     @encodedExample(annotations.jwtCredential.example)
@@ -175,13 +177,37 @@ object IssueCredentialRecord {
     object role
         extends Annotation[String](
           description = "The role played by the Prism agent in the credential issuance flow.",
-          example = "Issuer"
+          example = "Issuer",
+          validator = Validator.enumeration(
+            List(
+              "Issuer",
+              "Holder"
+            )
+          )
         )
 
     object protocolState
-        extends Annotation[String]( // TODO Support Enum
+        extends Annotation[String](
           description = "The current state of the issue credential protocol execution.",
-          example = "OfferPending"
+          example = "OfferPending",
+          validator = Validator.enumeration(
+            List(
+              "OfferPending",
+              "OfferSent",
+              "OfferReceived",
+              "RequestPending",
+              "RequestGenerated",
+              "RequestSent",
+              "RequestReceived",
+              "CredentialPending",
+              "CredentialGenerated",
+              "CredentialSent",
+              "CredentialReceived",
+              "ProblemReportPending",
+              "ProblemReportSent",
+              "ProblemReportReceived"
+            )
+          )
         )
 
     object jwtCredential

prism-agent/service/server/src/main/scala/io/iohk/atala/presentproof/controller/PresentProofController.scala

@@ -14,7 +14,7 @@ trait PresentProofController {
       requestPresentationInput: RequestPresentationInput
   )(implicit
       rc: RequestContext
-  ): IO[ErrorResponse, RequestPresentationOutput]
+  ): IO[ErrorResponse, PresentationStatus]
 
   def getPresentations(
       paginationInput: PaginationInput,

prism-agent/service/server/src/main/scala/io/iohk/atala/presentproof/controller/PresentProofControllerImpl.scala

@@ -24,8 +24,8 @@ class PresentProofControllerImpl(
     with ControllerHelper {
   override def requestPresentation(request: RequestPresentationInput)(implicit
       rc: RequestContext
-  ): IO[ErrorResponse, RequestPresentationOutput] = {
-    val result: IO[ConnectionServiceError | PresentationError, RequestPresentationOutput] = for {
+  ): IO[ErrorResponse, PresentationStatus] = {
+    val result: IO[ConnectionServiceError | PresentationError, PresentationStatus] = for {
       didIdPair <- getPairwiseDIDs(request.connectionId).provide(ZLayer.succeed(connectionService))
       record <- presentationService
         .createPresentationRecord(
@@ -42,7 +42,7 @@ class PresentProofControllerImpl(
           },
           options = request.options.map(x => Options(x.challenge, x.domain)),
         )
-    } yield RequestPresentationOutput.fromDomain(record)
+    } yield PresentationStatus.fromDomain(record)
 
     result.mapError {
       case e: ConnectionServiceError => ConnectionController.toHttpError(e)

prism-agent/service/server/src/main/scala/io/iohk/atala/presentproof/controller/PresentProofEndpoints.scala

@@ -17,7 +17,7 @@ object PresentProofEndpoints {
   val requestPresentation: PublicEndpoint[
     (RequestContext, RequestPresentationInput),
     ErrorResponse,
-    RequestPresentationOutput,
+    PresentationStatus,
     Any
   ] =
     endpoint.post
@@ -33,7 +33,7 @@ object PresentProofEndpoints {
           "The proof presentation request was created successfully and will be sent asynchronously to the Prover."
         )
       )
-      .out(jsonBody[RequestPresentationOutput])
+      .out(jsonBody[PresentationStatus])
       .errorOut(basicFailures)
 
   val getAllPresentations

prism-agent/service/server/src/main/scala/io/iohk/atala/presentproof/controller/http/PresentationStatus.scala

@@ -15,6 +15,10 @@ final case class PresentationStatus(
     @description(annotations.thid.description)
     @encodedExample(annotations.thid.example)
     thid: String,
+    @description(annotations.role.description)
+    @encodedExample(annotations.role.example)
+    @validate(annotations.role.validator)
+    role: String,
     @description(annotations.status.description)
     @encodedExample(annotations.status.example)
     @validate(annotations.status.validator)
@@ -45,6 +49,7 @@ object PresentationStatus {
     PresentationStatus(
       domain.id.value,
       thid = domain.thid.value,
+      role = domain.role.toString,
       status = domain.protocolState.toString,
       proofs = Seq.empty,
       data = data,
@@ -67,7 +72,17 @@ object PresentationStatus {
             "The value will identical on both sides of the presentation flow (verifier and prover)",
           example = "0527aea1-d131-3948-a34d-03af39aba8b4"
         )
-
+    object role
+        extends Annotation[String](
+          description = "The role played by the Prism agent in the proof presentation flow.",
+          example = "Verifier",
+          validator = Validator.enumeration(
+            List(
+              "Verifier",
+              "Prover"
+            )
+          )
+        )
     object status
         extends Annotation[String](
           description = "The current state of the proof presentation record.",