openapi: 3.0.3
info:
  title: CryptoARM API (JSON-RPC over HTTP) - OpenAPI wrapper
  version: "1.0.0"
  description: |
    OpenAPI wrapper для JSON-RPC методов, используемых КриптоАРМ (signAndEncrypt, certificates,
    certrequests, diagnostics, sendMail и т.д.). Все вызовы — через HTTP POST с телом JSON-RPC 2.0.
    Схема и поля описаны по руководству разработчика (PDF). :contentReference[oaicite:1]{index=1}
servers:
  - url: https://api.example.com
    description: Replace with real server URL

paths:
  /jsonrpc:
    post:
      summary: JSON-RPC 2.0 endpoint for CryptoARM methods
      description: >
        Все запросы соответствуют спецификации JSON-RPC 2.0 и передаются методом POST.
        Content-Type: application/json; Accept: application/json. См. методы:
        - signAndEncrypt.parameters (ответ на получение параметров операции)
        - signAndEncrypt.outDirectResults (notification: отправка результатов прямой операции)
        - signAndEncrypt.outReverseResults (notification: отправка результатов обратной операции)
        - signAndEncrypt.verifySignResults (notification: отправка результатов проверки подписи)
        - certificates.parameters / certificates.base64 / certificates.information
        - certrequests.parameters / certrequests.base64
        - diagnostics.parameters / diagnostics.information
        - sendMail.parameters (и связанные)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC success response (or error object). HTTP 200 используется и для ошибок по спецификации документа.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '204':
          description: No Response (used for notifications)
        '415':
          description: Unsupported Media Type (если Content-Type != application/json)

components:
  schemas:

    # --- JSON-RPC envelope ---
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          description: JSON-RPC version
        method:
          type: string
          description: JSON-RPC method name (например "signAndEncrypt.parameters")
        id:
          oneOf:
            - type: string
            - type: integer
          description: Идентификатор запроса. Обязателен для запросов, отсутствует для уведомлений.
        params:
          oneOf:
            - type: object
            - type: array
          description: Параметры вызова. Структура зависит от метода.
    JsonRpcResponse:
      type: object
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        id:
          oneOf:
            - type: string
            - type: integer
        result:
          type: object
          description: Результат (если нет ошибки)
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          description: Дополнительные сведения (string или object)
          oneOf:
            - type: string
            - type: object

    # --- signAndEncrypt related ---
    ISignAndEncryptParametersResult:
      type: object
      description: Результат на метод signAndEncrypt.parameters (поле result)
      properties:
        operation:
          type: array
          items:
            type: string
          description: Список операций: SIGN, ARCHIVE, ENCRYPT и проч.
        props:
          $ref: '#/components/schemas/ISignAndEncryptOperadonProps'
    ISignAndEncryptOperadonProps:
      type: object
      properties:
        headerText:
          type: string
          maxLength: 40
        license:
          type: string
        files:
          type: array
          items:
            $ref: '#/components/schemas/IFile'
        archive:
          $ref: '#/components/schemas/IFile'
        extra:
          $ref: '#/components/schemas/IExtra'
        uploader:
          type: string
          description: URL для загрузки результатов (uploader)
        localResultParams:
          $ref: '#/components/schemas/ILocalResultParams'
    IFile:
      type: object
      properties:
        name:
          type: string
          description: Имя файла
        url:
          type: string
          format: uri
          description: Ссылка на скачивание файла
        id:
          oneOf:
            - type: string
            - type: integer
        urlDetached:
          type: string
          description: URL для detached подписи (опционально)

    IExtra:
      type: object
      properties:
        headerText:
          type: string
        descriptionText:
          type: string
        license:
          type: string
        uploader:
          type: string
        signType:
          type: integer
          description: 0 - attached, 1 - detached
        signStandart:
          type: integer
          description: 0-CMS,1-CAdES-X Long Type 1,2-CAdES-T,3-CAdES-A
        signEncoding:
          type: integer
          description: 0-BASE64,1-DER
        timestamOnSign:
          type: string
          description: "True/False"
        timestamOnData:
          type: string
          description: "True/False"
        encryptEncoding:
          type: integer
        encryptAlgorithm:
          type: integer
          description: 0-GOST28147-89,1-Magma,2-Kuznechik
        token:
          type: string
        tspURL:
          type: string
        ocspURL:
          type: string
        encryptCerdficates:
          type: array
          items:
            type: string
        signCerdficate:
          type: object
          properties:
            x509:
              type: string
        signatureExtension:
          type: string

    IDirectResults:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        directResults:
          type: array
          items:
            $ref: '#/components/schemas/IDirectResultOut'
        separateArchivesForSignResults:
          type: boolean
        isAddStampToPdf:
          type: boolean
        signStampAppearance:
          $ref: '#/components/schemas/ISignStampAppearance'
        signStamp:
          $ref: '#/components/schemas/IPdfMarkedArea'
    IDirectResultOut:
      type: object
      properties:
        id:
          oneOf:
            - type: string
            - type: integer
        out:
          type: string
          description: Результат операции в BASE-64
        outSignStamp:
          type: string
        signers:
          type: array
          items:
            $ref: '#/components/schemas/ISignerStatus'
        signValid:
          type: boolean

    IReverseResults:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        reverseResults:
          type: array
          items:
            $ref: '#/components/schemas/IReverseResultOut'
    IReverseResultOut:
      type: object
      properties:
        id:
          oneOf:
            - type: string
            - type: integer
        out:
          type: string
          description: base64 result

    IVerifySignResults:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        verifyResults:
          type: array
          items:
            $ref: '#/components/schemas/IVerifySignResult'
    IVerifySignResult:
      type: object
      properties:
        id:
          oneOf:
            - type: string
            - type: integer
        signValid:
          type: boolean
        signers:
          type: array
          items:
            $ref: '#/components/schemas/ISignerStatus'
    ISignerStatus:
      type: object
      properties:
        hash:
          type: string
        issuerFriendlyName:
          type: string
        issuerName:
          type: string
        subjectFriendlyName:
          type: string
        subjectName:
          type: string
        status:
          type: boolean
        signerCerdficate:
          $ref: '#/components/schemas/ICertificateInfo'

    ISignStampAppearance:
      type: object
      properties:
        mockupSetngs:
          $ref: '#/components/schemas/IMockupSettings'
        requisitesSetngs:
          $ref: '#/components/schemas/IRequisitesSettings'
        pageSelection:
          type: string
          enum: ["all","last","some"]
        pageNumbers:
          type: string
        posidon:
          type: string
          enum: ["fitArea","actualSize","fitMockup"]
        addBackground:
          type: boolean
    IMockupSettings:
      type: object
      properties:
        addBorders:
          type: boolean
        logotype:
          type: string
        isHiddenLogo:
          type: boolean
        height:
          type: number
        width:
          type: number
        horizontalPadding:
          type: number
        verticalPadding:
          type: number
    IRequisitesSettings:
      type: object
      properties:
        posidon:
          type: string
          enum: ["default","left","right","leftAndRight"]
        centralDisplayType:
          type: string
          enum: ["byGost","arbitrary"]
        central:
          type: array
          items:
            $ref: '#/components/schemas/IPdfCertRequisite'
        left:
          type: array
          items:
            $ref: '#/components/schemas/IPdfCertRequisite'
        right:
          type: array
          items:
            $ref: '#/components/schemas/IPdfCertRequisite'
    IPdfCertRequisite:
      type: object
      properties:
        title:
          type: string
        dataKey:
          type: string
        isEditable:
          type: boolean
        editedValue:
          type: string
        editedValueCharLimit:
          type: integer

    IPdfMarkedArea:
      type: object
      properties:
        height:
          type: number
        width:
          type: number
        horizontalPadding:
          type: number
        verticalPadding:
          type: number

    ILocalResultParams:
      type: object
      properties:
        savePath:
          type: string
        saveResultsSeparately:
          type: boolean

    # --- certificates ---
    ICerdficatesParameters:
      type: object
      properties:
        operation:
          type: string
          enum: ["import","export","information"]
        props:
          $ref: '#/components/schemas/ICerdficatesOperadonProps'
        id:
          type: string
    ICerdficatesOperadonProps:
      type: object
      properties:
        headerText:
          type: string
        descriptionText:
          type: string
        store:
          type: array
          items:
            type: string
        multy:
          type: boolean
        certificateBase64:
          type: string
    ICerdficateBase64Params:
      type: object
      required:
        - id
        - certificateBase64
      properties:
        id:
          type: string
        certificateBase64:
          type: string
        friendlyName:
          type: string
    ICertificateInfo:
      type: object
      properties:
        id:
          type: string
        hash:
          type: string
        issuerFriendlyName:
          type: string
        issuerName:
          type: string
        subjectFriendlyName:
          type: string
        subjectName:
          type: string
        status:
          type: boolean
        notAfter:
          type: string
        notBefore:
          type: string
        serial:
          type: string
        x509:
          type: string

    # --- certrequests ---
    ICertrequestsParameters:
      type: object
      properties:
        operation:
          type: string
          enum: ["GENERATE"]
        props:
          $ref: '#/components/schemas/ICertrequestsOperadonGenerateProps'
        id:
          type: string
    ICertrequestsOperadonGenerateProps:
      type: object
      properties:
        headerText:
          type: string
        descriptionText:
          type: string
        templateType:
          type: string
        template:
          type: object
          description: JSONTemplate (см. руководство)
    ICertrequestBase64Params:
      type: object
      required:
        - id
        - certificaterequestBase64
      properties:
        id:
          type: string
        certificaterequestBase64:
          type: string
        friendlyName:
          type: string

    # --- diagnostics ---
    IDiagnosticsParameters:
      type: object
      properties:
        operation:
          type: array
          items:
            type: string
          description: Возможные значения: SYSTEMINFORMATION, CSP_ENABLED, CADES_ENABLED, VERSIONS, PROVIDERS, LICENSES, PERSONALCERTIFICATES
        props:
          type: object
    IDiagnosticsInformation:
      type: object
      properties:
        id:
          type: string
        API_VERSION:
          type: string
        SYSTEMINFORMATION:
          $ref: '#/components/schemas/ISystemInformation'
        CSP_ENABLED:
          type: boolean
        CADES_ENABLED:
          type: boolean
        VERSIONS:
          $ref: '#/components/schemas/IVersions'
        PROVIDERS:
          $ref: '#/components/schemas/IProviders'
        LICENSES:
          $ref: '#/components/schemas/ILicenses'
        PERSONALCERTIFICATES:
          type: array
          items:
            $ref: '#/components/schemas/ICertificateIdentityInfo'
    ISystemInformation:
      type: object
      properties:
        type:
          type: string
          description: 'Linux, Darwin, Windows_NT'
        arch:
          type: string
        platform:
          type: string
        packageType:
          type: string
    IVersions:
      type: object
      properties:
        csp:
          type: string
        cryptoarm:
          type: string
    IProviders:
      type: object
      properties:
        GOST2012_256:
          type: boolean
        GOST2012_512:
          type: boolean
    ILicenses:
      type: object
      properties:
        csp:
          $ref: '#/components/schemas/ILicenseInfo'
        cryptoarm:
          $ref: '#/components/schemas/ILicenseInfo'
    ILicenseInfo:
      type: object
      properties:
        status:
          type: boolean
        type:
          type: string
          description: License type: Permanent, Subscription, Daily, Trial
        expiration:
          type: string

    ICertificateIdentityInfo:
      type: object
      properties:
        hash:
          type: string
        issuerFriendlyName:
          type: string
        subjectFriendlyName:
          type: string

    # --- sendMail ---
    IMailParameters:
      type: object
      properties:
        operation:
          type: string
          enum: ["SEND","OPEN"]
        props:
          $ref: '#/components/schemas/IMailOperadonProps'
    IMailOperadonProps:
      type: object
      properties:
        eml:
          $ref: '#/components/schemas/IFile'
        mailProps:
          $ref: '#/components/schemas/IMailProps'
        extra:
          $ref: '#/components/schemas/IExtra'
    IMailProps:
      type: object
      properties:
        to:
          type: array
          items:
            type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        subject:
          type: string
        content:
          type: string
        htmlContent:
          type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/IFile'
        sign:
          type: boolean
        encrypt:
          type: boolean
        deliveryReport:
          type: boolean
        readReport:
          type: boolean

  examples:
    signAndEncryptParametersExample:
      summary: Пример ответа signAndEncrypt.parameters
      value:
        jsonrpc: "2.0"
        result:
          operation: ["SIGN","ARCHIVE","ENCRYPT"]
          props:
            headerText: "Подпись документов cryptoarm.ru"
            files:
              - name: "file1.txt"
                url: "http://localhost:8080/public/files/file1.txt"
                id: 1
            extra:
              token: "9c7101f7-9c47-4481-b4da-a6a497abde08"
              signType: 1
            uploader: "http://localhost:8080/upload"
        id: "2c48eb32-a0a8-405c-ade9-eed130605cba"

security:
  - tls:
      - gost

components:
  securitySchemes:
    tls:
      type: apiKey
      in: header
      name: X-TLS-Client
      description: >
        Placeholder: TLS / mTLS must be used per spec. Документ требует TLS; при опции "использовать
        только ГОСТ TLS" — разрешается только ГОСТ шифросюиты. (Информационное поле.)
