gremiumhub/legalconsenthub-middleware/api/legalconsenthub-middleware.yml

openapi: "3.0.3"
info:
  title: legalconsenthub-middleware
  version: 0.1.0
  description: Middleware for digital signature services using OpenSC pkcs11-tool for hash signing.
  contact:
    name: Denis Lugowski
    email: denis.lugowski@gmail.com

servers:
  - url: http://localhost:8081

security:
  - bearerAuth: []

paths:
  ####### Smart Card Operations #######
  /smart-card/info:
    get:
      summary: Get smart card information
      operationId: getSmartCardInfo
      tags:
        - smart-card
      responses:
        "200":
          description: Smart card information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SmartCardInfoDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /smart-card/certificates:
    get:
      summary: Get available certificates on smart card
      operationId: getSmartCardCertificates
      tags:
        - smart-card
      responses:
        "200":
          description: List of available certificates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CertificateDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### PDF Hash Signing Operations #######
  /sign-pdf-hash:
    post:
      summary: Calculate hash from PDF and sign it using smart card
      operationId: signPdfHash
      tags:
        - signature
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SignPdfHashRequestDto"
      responses:
        "200":
          description: Base64 encoded signature
          content:
            text/plain:
              schema:
                type: string
                description: Base64 encoded signature
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /verify-signature:
    post:
      summary: Verify a signature against a document
      operationId: verifySignature
      tags:
        - signature
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/VerifySignatureRequestDto"
      responses:
        "200":
          description: Signature verification result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifySignatureResponseDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ####### Smart Card DTOs #######
    SmartCardInfoDto:
      type: object
      required:
        - isPresent
        - label
      properties:
        isPresent:
          type: boolean
        label:
          type: string
        serialNumber:
          type: string
        manufacturer:
          type: string
        model:
          type: string

    CertificateDto:
      type: object
      required:
        - id
        - subject
        - issuer
        - validFrom
        - validTo
        - keyUsage
      properties:
        id:
          type: string
        subject:
          type: string
        issuer:
          type: string
        validFrom:
          type: string
          format: date-time
        validTo:
          type: string
          format: date-time
        keyUsage:
          type: array
          items:
            type: string
        fingerprint:
          type: string

    ####### PDF Hash Signing DTOs #######
    SignPdfHashRequestDto:
      type: object
      required:
        - document
        - certificateId
      properties:
        document:
          type: string
          format: binary
          description: PDF document to calculate hash from
        certificateId:
          type: string
          description: ID of the certificate to use for signing
        hashAlgorithm:
          type: string
          enum: [SHA1, SHA256, SHA384, SHA512]
          default: SHA256
          description: Hash algorithm to use

    VerifySignatureRequestDto:
      type: object
      required:
        - document
        - signature
      properties:
        document:
          type: string
          format: binary
          description: Document to verify signature against
        signature:
          type: string
          description: Base64 encoded signature to verify
        certificateId:
          type: string
          description: ID of the certificate to use for verification (optional, will use embedded certificate if not provided)
        hashAlgorithm:
          type: string
          enum: [SHA1, SHA256, SHA384, SHA512]
          default: SHA256
          description: Hash algorithm used for verification

    VerifySignatureResponseDto:
      type: object
      required:
        - isValid
      properties:
        isValid:
          type: boolean
          description: Whether the signature is valid
        certificateInfo:
          $ref: "#/components/schemas/CertificateDto"
          description: Information about the certificate used for signing
        verificationDetails:
          type: string
          description: Additional details about the verification process