openapi: 3.1.0
info:
  title: Alloy Mesh Substrate API (Module L5)
  version: mesh-v1.0.0-m0
  description: >
    OpenAPI 3.1 equivalent of the Alloy Mesh M0 mock DKG and signing wire protocol.
    Supports opaque orchestration context, explicit client/version traceability,
    resumable checkpoints, and governed diagnostic receipts.

paths:
  /v1/dkg/initiate:
    post:
      summary: Initiate mock 3-of-5 Distributed Key Generation (DKG)
      operationId: initiateDkg
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
        - $ref: '#/components/parameters/CorrelationHeader'
        - $ref: '#/components/parameters/ClientNameHeader'
        - $ref: '#/components/parameters/ClientVersionHeader'
        - $ref: '#/components/parameters/ContractVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateDkgRequest'
      responses:
        '200':
          description: DKG session response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateDkgResponse'

  /v1/dkg/shares:
    post:
      summary: Exchange mock Feldman VSS shares and commitments
      operationId: exchangeDkgShares
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
        - $ref: '#/components/parameters/CorrelationHeader'
        - $ref: '#/components/parameters/ClientNameHeader'
        - $ref: '#/components/parameters/ClientVersionHeader'
        - $ref: '#/components/parameters/ContractVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DkgShareExchangeRequest'
      responses:
        '200':
          description: Share verification response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DkgShareExchangeResponse'

  /v1/signing/initiate:
    post:
      summary: Initiate mock threshold signing ceremony
      operationId: initiateSigning
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
        - $ref: '#/components/parameters/CorrelationHeader'
        - $ref: '#/components/parameters/ClientNameHeader'
        - $ref: '#/components/parameters/ClientVersionHeader'
        - $ref: '#/components/parameters/ContractVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateSigningRequest'
      responses:
        '200':
          description: Signing session response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateSigningResponse'

  /v1/signing/share:
    post:
      summary: Submit partial signature share
      operationId: submitSignatureShare
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
        - $ref: '#/components/parameters/CorrelationHeader'
        - $ref: '#/components/parameters/ClientNameHeader'
        - $ref: '#/components/parameters/ClientVersionHeader'
        - $ref: '#/components/parameters/ContractVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureShareRequest'
      responses:
        '200':
          description: Partial signature processing response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureShareResponse'

  /v1/sessions/resume:
    post:
      summary: Resume a previously paused or escalated session
      operationId: resumeSession
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
        - $ref: '#/components/parameters/CorrelationHeader'
        - $ref: '#/components/parameters/ClientNameHeader'
        - $ref: '#/components/parameters/ClientVersionHeader'
        - $ref: '#/components/parameters/ContractVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeSessionRequest'
      responses:
        '200':
          description: Resume response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSessionResponse'

components:
  parameters:
    TraceparentHeader:
      name: traceparent
      in: header
      required: false
      schema:
        type: string
    CorrelationHeader:
      name: x-correlation-id
      in: header
      required: false
      schema:
        type: string
    ClientNameHeader:
      name: x-alloy-client-name
      in: header
      required: false
      schema:
        type: string
    ClientVersionHeader:
      name: x-alloy-client-version
      in: header
      required: false
      schema:
        type: string
    ContractVersionHeader:
      name: x-alloy-contract-version
      in: header
      required: false
      schema:
        type: string

  schemas:
    ApprovalMode:
      type: string
      enum:
        - UNSPECIFIED
        - DIRECT_ALLOWED
        - HUMAN_REQUIRED

    ReceiptState:
      type: string
      enum:
        - UNSPECIFIED
        - ACCEPTED
        - DENIED
        - PENDING_HUMAN_APPROVAL
        - RESUMED
        - EXPIRED
        - REPLAY_REJECTED
        - REVOKED
        - BACKEND_COMPLETED
        - BACKEND_FAILED
        - UNSUPPORTED_CLIENT_CONTRACT_VERSION

    KeystoreType:
      type: string
      enum:
        - KEYSTORE_TYPE_UNSPECIFIED
        - KEYSTORE_TYPE_MOCK_THRESHOLD
        - KEYSTORE_TYPE_MULTISIG_EVM_SAFE
        - KEYSTORE_TYPE_MPC_SEPIOR
        - KEYSTORE_TYPE_MPC_FROST
        - KEYSTORE_TYPE_HSM_PKCS11

    MockDirective:
      type: string
      enum:
        - MOCK_DIRECTIVE_UNSPECIFIED
        - MOCK_DIRECTIVE_FORCE_DENIED
        - MOCK_DIRECTIVE_FORCE_REVOKED
        - MOCK_DIRECTIVE_FORCE_EXPIRED
        - MOCK_DIRECTIVE_FORCE_BACKEND_FAILED

    ClientVersionInfo:
      type: object
      properties:
        client_name:
          type: string
        client_version:
          type: string
        contract_version:
          type: string
      required:
        - contract_version

    OrchestrationContext:
      type: object
      properties:
        payload:
          type: string
          format: byte
          description: Base64-encoded opaque payload from WalletKit/PolicyKit.
        traceparent:
          type: string
          description: W3C distributed tracing header.
        correlation_id:
          type: string
          description: End-to-end correlation ID across modules.
        client:
          $ref: '#/components/schemas/ClientVersionInfo'

    ThresholdDerivation:
      type: object
      properties:
        derivation_path:
          type: string
          example: "m/44'/60'/0'/0/0"
        curve:
          type: string
          enum:
            - secp256k1
            - ed25519
        network_id:
          type: string
      required:
        - derivation_path
        - curve

    DiagnosticReceipt:
      type: object
      properties:
        receipt_id:
          type: string
        state:
          $ref: '#/components/schemas/ReceiptState'
        approval_mode:
          $ref: '#/components/schemas/ApprovalMode'
        reason_code:
          type: string
        message:
          type: string
        correlation_id:
          type: string
        session_id:
          type: string
        contract_version:
          type: string
        client_name:
          type: string
        client_version:
          type: string
        epoch:
          type: integer
        checkpoint_id:
          type: string
        resumable:
          type: boolean
        keystore_type:
          $ref: '#/components/schemas/KeystoreType'
        backend_route:
          type: string

    SessionCheckpoint:
      type: object
      properties:
        checkpoint_id:
          type: string
        epoch:
          type: integer
        created_at_epoch_ms:
          type: integer
        state:
          $ref: '#/components/schemas/ReceiptState'
        resume_token:
          type: string

    InitiateDkgRequest:
      type: object
      properties:
        session_id:
          type: string
        threshold:
          type: integer
        total_nodes:
          type: integer
        derivation:
          $ref: '#/components/schemas/ThresholdDerivation'
        context:
          $ref: '#/components/schemas/OrchestrationContext'
      required:
        - session_id
        - threshold
        - total_nodes
        - derivation

    InitiateDkgResponse:
      type: object
      properties:
        session_id:
          type: string
        state:
          $ref: '#/components/schemas/ReceiptState'
        epoch:
          type: integer
        receipt:
          $ref: '#/components/schemas/DiagnosticReceipt'
        checkpoint:
          $ref: '#/components/schemas/SessionCheckpoint'

    DkgShareExchangeRequest:
      type: object
      properties:
        session_id:
          type: string
        sender_node_id:
          type: integer
        recipient_node_id:
          type: integer
        encrypted_share:
          type: string
          format: byte
        commitments:
          type: array
          items:
            type: string
            format: byte
        context:
          $ref: '#/components/schemas/OrchestrationContext'
      required:
        - session_id
        - sender_node_id
        - recipient_node_id
        - encrypted_share
        - commitments

    DkgShareExchangeResponse:
      type: object
      properties:
        session_id:
          type: string
        verified:
          type: boolean
        error_message:
          type: string
        receipt:
          $ref: '#/components/schemas/DiagnosticReceipt'
        checkpoint:
          $ref: '#/components/schemas/SessionCheckpoint'

    InitiateSigningRequest:
      type: object
      properties:
        transaction_intent_id:
          type: string
        wallet_id:
          type: string
        derivation:
          $ref: '#/components/schemas/ThresholdDerivation'
        message_hash:
          type: string
          format: byte
        policy_approval_token:
          type: string
          format: byte
        human_approval_witness:
          type: string
          format: byte
        approval_mode:
          $ref: '#/components/schemas/ApprovalMode'
        context:
          $ref: '#/components/schemas/OrchestrationContext'
        keystore_type:
          $ref: '#/components/schemas/KeystoreType'
        mock_directive:
          $ref: '#/components/schemas/MockDirective'
      required:
        - transaction_intent_id
        - wallet_id
        - message_hash
        - approval_mode
        - keystore_type
        - context

    InitiateSigningResponse:
      type: object
      properties:
        signing_session_id:
          type: string
        state:
          $ref: '#/components/schemas/ReceiptState'
        epoch:
          type: integer
        receipt:
          $ref: '#/components/schemas/DiagnosticReceipt'
        checkpoint:
          $ref: '#/components/schemas/SessionCheckpoint'

    SignatureShareRequest:
      type: object
      properties:
        signing_session_id:
          type: string
        node_id:
          type: integer
        partial_signature:
          type: string
          format: byte
        ephemeral_public_key:
          type: string
          format: byte
        context:
          $ref: '#/components/schemas/OrchestrationContext'
      required:
        - signing_session_id
        - node_id
        - partial_signature

    SignatureShareResponse:
      type: object
      properties:
        signing_session_id:
          type: string
        is_complete:
          type: boolean
        full_signature:
          type: string
          format: byte
        recovery_id:
          type: string
          format: byte
        receipt:
          $ref: '#/components/schemas/DiagnosticReceipt'
        checkpoint:
          $ref: '#/components/schemas/SessionCheckpoint'

    ResumeSessionRequest:
      type: object
      properties:
        session_id:
          type: string
        resume_token:
          type: string
        context:
          $ref: '#/components/schemas/OrchestrationContext'
        human_approval_witness:
          type: string
          format: byte
      required:
        - session_id
        - resume_token
        - context

    ResumeSessionResponse:
      type: object
      properties:
        session_id:
          type: string
        state:
          $ref: '#/components/schemas/ReceiptState'
        epoch:
          type: integer
        receipt:
          $ref: '#/components/schemas/DiagnosticReceipt'
        checkpoint:
          $ref: '#/components/schemas/SessionCheckpoint'