path: root/core/api-auditor.rst

..
  This file is part of GNU TALER.
  Copyright (C) 2018 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Christian Grothoff

============================
The Auditor RESTful JSON API
============================

The API specified here follows the :ref:`general conventions <http-common>`
for all details not specified in the individual requests.
The `glossary <https://docs.taler.net/glossary.html#glossary>`_
defines all specific terms used in this section.

.. contents:: Table of Contents
  :local:

.. _authentication:

--------------
Authentication
--------------

Each auditor instance has separate authentication settings for the private API resources
of that instance.

Currently, the API supports two main authentication methods:

* ``external``:  With this method, no checks are done by the auditor backend.
  Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
* ``token``: With this method, the client must provide a ``Authorization: Bearer $TOKEN``
  header, where ``$TOKEN`` is a secret authentication token configured for the instance which must begin with the RFC 8959 prefix.

.. _auditor-version:

-------------------------
Obtaining Auditor Version
-------------------------

This API is used by merchants to obtain a list of all exchanges audited by
this auditor.  This may be required for the merchant to perform the required
know-your-customer (KYC) registration before issuing contracts.

.. http:get:: /config

  Get the protocol version and some meta data about the auditor.
  This specification corresponds to ``current`` protocol being version **1**.

  **Response:**

  :http:statuscode:`200 OK`:
    The auditor responds with an `AuditorVersion`_ object. This request should
    virtually always be successful.

  **Details:**

  .. _AuditorVersion:
  .. code-block:: tsref

    interface AuditorVersion {
      // libtool-style representation of the Taler protocol version, see
      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
      // The format is "current:revision:age".  Note that the auditor
      // protocol is versioned independently of the exchange's protocol.
      version: string;

      // URN of the implementation (needed to interpret 'revision' in version).
      // @since v0, may become mandatory in the future.
      implementation?: string;

      // Return which currency this auditor is auditing for.
      currency: string;

      // EdDSA master public key of the auditor.
      auditor_public_key: EddsaPublicKey;

      // EdDSA master public key of the exchange.
      // Added in protocol v1.
      exchange_master_public_key: EddsaPublicKey;
    }

  .. note::

    This API is still experimental (and is not yet implemented at the
    time of this writing).


.. _exchange_signkeys-list:

------------------------------------
Obtaining Exchange Signing Keys List
------------------------------------

This API is used by auditor to obtain a list of all exchanges signing keys to be audited.

.. http:get:: /exchange-sign-keys

  Get a list of all exchange signing keys to be audited by the auditor.

  **Response:**

  :http:statuscode:`200 OK`:
    The auditor responds with a :ts:type:`ExchangeSignKeysList` object. This request should
    virtually always be successful.

  **Details:**

  .. ts:def:: ExchangeSignKeysList

    interface ExchangeSignKeysList {
      // Exchange signing keys to be audited by the auditor.
      exchange-sign-key: ExchangeSignKeyEntry[];
    }

  .. ts:def:: ExchangeSignKeyEntry

    interface ExchangeSignKeyEntry {

      // Public online signing key of the exchange.
      exchange_pub: EddsaPublicKey;

      // Base URL of the exchange.
      master_sig: EddsaSignature;

      // Time when online signing key will first be use.
      ep_valid_from: Timestamp;

      // Time when this online signing key will no longer be used.
      ep_expire_sign: Timestamp;

      // Time when this online signing key legally expires.
      ep_expire_legal: Timestamp;
    }

  .. note::

    This API is still experimental (and is not yet implemented at the
    time of this writing).

.. _deposit-confirmation:

---------------------
Deposit Confirmations
---------------------

Merchants should probabilistically submit some of the deposit
confirmations they receive from the exchange to auditors to ensure
that the exchange does not lie about recording deposit confirmations
with the exchange. Participating in this scheme ensures that in case
an exchange runs into financial trouble to pay its obligations, the
merchants that did participate in detecting the bad behavior can be
paid out first.

.. http:put:: /deposit-confirmation

  Submits a `DepositConfirmation` to the exchange. Should succeed
  unless the signature provided is invalid or the exchange is not
  audited by this auditor.

  **Response:**

  :http:statuscode:`200 Ok`:
        The auditor responds with a `DepositAudited` object.
        This request should virtually always be successful.
  :http:statuscode:`403 Forbidden`:
        The signature on the deposit confirmation is invalid.
  :http:statuscode:`410 Gone`:
        The public key used to sign the deposit confirmation
        was revoked.

  **Details:**

  .. ts:def:: DepositAudited

    interface DepositAudited {
      // TODO: maybe change to ``204 No content`` instead?
    }

  .. ts:def:: DepositConfirmation

    interface DepositConfirmation {

      // Hash over the contract for which this deposit is made.
      h_contract_terms: HashCode;

      // Hash over the extensions.
      h_extensions: HashCode;

      // Hash over the wiring information of the merchant.
      h_wire: HashCode;

      // Time when the deposit confirmation confirmation was generated.
      timestamp: Timestamp;

      // How much time does the merchant have to issue a refund
      // request?  Zero if refunds are not allowed.
      refund_deadline: Timestamp;

      // By what time does the exchange have to wire the funds?
      wire_deadline: Timestamp;

      // Amount to be deposited, excluding fee.  Calculated from the
      // amount with fee and the fee from the deposit request.
      amount_without_fee: Amount;

      // Array of public keys of the deposited coins.
      coin_pubs: EddsaPublicKey[];

      // Array of deposit signatures of the deposited coins.
      // Must have the same length as ``coin_pubs``.
      coin_sigs: EddsaSignature[];

      // The Merchant's public key.  Allows the merchant to later refund
      // the transaction or to inquire about the wire transfer identifier.
      merchant_pub: EddsaPublicKey;

      // Signature from the exchange of type
      // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT``.
      exchange_sig: EddsaSignature;

      // Public signing key from the exchange matching ``exchange_sig``.
      exchange_pub: EddsaPublicKey;

      // Master public key of the exchange corresponding to ``master_sig``.
      // Identifies the exchange this is about.
      // @deprecated since v1 (now ignored, global per auditor)
      master_pub: EddsaPublicKey;

      // When does the validity of the exchange_pub end?
      ep_start: Timestamp;

      // When will the exchange stop using the signing key?
      ep_expire: Timestamp;

      // When does the validity of the exchange_pub end?
      ep_end: Timestamp;

      // Exchange master signature over ``exchange_sig``.
      master_sig: EddsaSignature;
    }

  .. note::

    This API is still experimental (and is not yet implemented at the
    time of this writing). A key open question is whether the auditor
    should sign the response information.

This API is used by the auditor to obtain a list of all deposit confirmations that the auditor
did not receive by the exchange, only by the merchant.

.. http:get:: /deposit-confirmation

  Get a list of all deposit confirmations that were not received by the auditor from the exchange to be manually audited.

  **Response:**

  :http:statuscode:`200 OK`:
    The auditor responds with a :ts:type:`DepositConfirmationList` object.
  :http:statuscode:`204 No Content`:
    No missing deposit confirmations found.

  **Details:**

  .. ts:def:: DepositConfirmationList

    interface DepositConfirmationList {
      // Deposit confirmations to be audited.
      deposit-confirmations: DepositConfirmation[];
    }

  .. ts:def:: DepositConfirmation

    interface DepositConfirmation {

      // Database row id of entry
      row_id: Integer;

      // Time when the deposit confirmation confirmation was generated.
      timestamp: Timestamp;

      // How much time does the merchant have to issue a refund
      // request?  Zero if refunds are not allowed.
      refund_deadline: Timestamp;

      // By what time does the exchange have to wire the funds?
      wire_deadline: Timestamp;

      // Amount to be deposited, excluding fee.  Calculated from the
      // amount with fee and the fee from the deposit request.
      amount_without_fee: Amount;
    }

  .. note::

    This API is still experimental (and is not yet implemented at the
    time of this writing).

This API is used by the auditor to delete an audited deposit confirmation.

.. http:delete:: /deposit-confirmation/$SERIAL_ID

  Delete deposit confirmation entry with given serial_id.

  **Response:**

  :http:statuscode:`204 No content`:
    The deposit confirmation was deleted.

  :http:statuscode:`401 Unauthorized`:
    Unauthorized request.

  :http:statuscode:`404 Not found`:
    The deposit confirmation was unknown.

  .. note::

    This API is still experimental (and is not yet implemented at the
    time of this writing).

.. balances-list:

----------------------------------
Obtaining list of auditor balances
----------------------------------

This API is used to obtain a list of all the balances that are stored by the auditor.

.. http:get:: /balances

  Get a list of all balances stored by the auditor.

  **Response:**

  :http:statuscode:`200 OK`:
    The auditor responds with a :ts:type:`BalanceList` object.

  :http:statuscode:`409 Conflict`:
    Balance missing or other error occured.

  **Details:**

  .. ts:def:: BalanceList

    interface BalanceList {
      // Total amount reported
      auditor_total_reported_balance: Amount;

      // Amount potentially missing
      auditor_missing_balance: Amount;

      //...
    }

  .. note::

    This API is still experimental (and is not yet implemented at the
    time of this writing). The API will be further developed as needed.

.. denominations-pending-list:

---------------------------------------
Obtaining list of pending denominations
---------------------------------------

This API is used by the auditor to obtain a list of pending denominations

.. http:get:: /pending-denominations

  Get a list of all pending denominations.

  **Response:**

  :http:statuscode:`200 OK`:
    The auditor responds with a :ts:type:`PendingDenominationList` object.

  :http:statuscode:`204 No content`:
    No pending demoninations found.

  **Details:**

  .. ts:def:: PendingDenominationList

    interface PendingDenominationList {
      // PendingDenominationList of the auditor.
      pending_denomination: PendingDenomination[];
    }

  .. ts:def:: PendingDenomination

    interface PendingDenomination {

      // Balance of denomination.
      denom_balance: Amount;

      // Amount that was lost due to failures by the exchange.
      denom_loss: Amount;

      // Amount at risk of loss due to recoup operations.
      denom_risk: Amount;

      // Amount actually lost due to recoup operations after a revocation.
      recoup_loss: Amount;
    }

  .. note::

    This API is still experimental (and is not yet implemented at the
    time of this writing).

----------
Complaints
----------

This API is used by the wallet or merchants to submit proof of
misbehavior of an exchange to the auditor.

.. note::

   To be designed and implemented.

.. http:put:: /complain

Complain about misbehavior to the auditor.