[taler-docs] branch master updated: adding auditor rest api

[gnunet]

This is an automated email from the git hooks/post-receive script.

nic-eigel pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 164c6211 adding auditor rest api
164c6211 is described below

commit 164c6211b42cb65bbed2f8809498d2e875d89753
Author: Nic Eigel <nic@eigel.ch>
AuthorDate: Mon Jan 8 15:26:28 2024 +0100

    adding auditor rest api
---
 core/api-auditor.rst | 364 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 364 insertions(+)

diff --git a/core/api-auditor.rst b/core/api-auditor.rst
index 38c1c142..12d2d611 100644
--- a/core/api-auditor.rst
+++ b/core/api-auditor.rst
@@ -26,6 +26,22 @@ defines all specific terms used in this section.
 
 .. contents:: Table of Contents
 
+.. _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:
 
 -------------------------
@@ -117,6 +133,230 @@ know-your-customer (KYC) registration before issuing 
contracts.
     time of this writing). A key open question is whether the auditor
     should sign the information. We might also want to support more
     delta downloads in the future.
+       
+.. _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).
+       
+.. _purses-list:
+
+-----------------------
+Obtaining Purses List
+-----------------------
+
+This API is used by auditor to obtain a list of all the purses and their 
respective balances that the auditor is aware of. 
+
+.. http:get:: /purses
+
+  Get a list of all purses and their respective balances known by the auditor.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The auditor responds with a :ts:type:`PursesList` object.
+       
+  :http:statuscode:`204 No content`:
+    No purses found.
+
+  **Details:**
+
+  .. ts:def:: PursesList
+
+    interface PursesList {
+      // Purse known by the auditor.
+      purse: PurseEntry[];
+    }
+
+  .. ts:def:: PurseEntry
+
+    interface PurseEntry {
+
+      // Public online signing key of the exchange.
+      purse_pub: EddsaPublicKey;
+         
+         // Time when online signing key will first be use.
+      balance: taler_amount;
+         
+         // Time when this online signing key will no longer be used.
+      target: taler_amount;
+         
+         // Time when this online signing key legally expires.
+      expiration_date: Timestamp;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing).
+       
+.. _purses-list:
+
+-----------------------
+Obtaining Reserves List
+-----------------------
+
+This API is used by auditor to obtain a list of all the customer reserves and 
their respective balances that the auditor is aware of. 
+
+.. http:get:: /reserves
+
+  Get a list of all the reserves and their respective balances known by the 
auditor.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The auditor responds with a :ts:type:`ReservesList` object.
+       
+  :http:statuscode:`204 No content`:
+    No reserves found.
+
+  **Details:**
+
+  .. ts:def:: ReservesList
+
+    interface ReservesList {
+      // Reserve known by the auditor.
+      reserve: ReserveEntry[];
+    }
+
+  .. ts:def:: ReserveEntry
+
+    interface ReserveEntry {
+
+      // Public online signing key of the reserve
+      reserve_pub: EddsaPublicKey;
+         
+         // Balance of respective reserve.
+      reserve_balance: taler_amount;
+         
+         // Loss of respective reserve.
+      reserve_loss: taler_amount;
+         
+         // Withdraw fee balance.
+      withdraw_fee_balance: taler_amount;
+         
+         // Closing fee balance.
+      close_fee_balance: taler_amount;
+         
+         // Purse fee balance.
+      purse_fee_balance: taler_amount;
+         
+         // Open fee balance.
+      open_fee_balance: taler_amount;
+         
+         // Time when this online signing key will no longer be used.
+      history_fee_balance: taler_amount;
+         
+         // Time when this reserve expires.
+      expiration_date: Timestamp;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing).
+       
+.. deposit-confirmation-list:
+
+-----------------------
+Obtaining list of deposit confirmations to check
+-----------------------
+
+This API is used by the auditor to obtain a list of all deposit confirmations 
that need to be audited by
+this auditor.
+
+.. http:get:: /deposit-confirmation
+
+  Get a list of all deposit confirmations to be manually audited.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The auditor responds with a :ts:type:`DepositConfirmationList` object. 
This request should
+    virtually always be successful.
+
+  **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).
 
 .. _deposit-confirmation:
 
@@ -225,6 +465,130 @@ paid out first.
     time of this writing). A key open question is whether the auditor
     should sign the response information.
 
+.. delete-deposit-confirmation:
+
+-----------------------
+Delete audited deposit confirmation
+-----------------------
+
+This API is used by the auditor to delete an audited deposit confirmation.
+
+.. http:delete:: /deposit-confirmation/$rowid
+
+  Delete deposit confirmation entry with given row 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 already unknown.
+       
+  :http:statuscode:`409 Conflict`:
+  The deposit confirmation cannot be deleted anymore.
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing).
+       
+.. balances-list:
+
+-----------------------
+Obtaining list of auditor balances to check
+-----------------------
+
+This API is used by the auditor to obtain a list of all balances that need to 
be audited by
+this auditor.
+
+.. http:get:: /balances
+
+  Get a list of all auditor balances.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The auditor responds with a :ts:type:`BalanceList` object. This request 
should
+    virtually always be successful.
+
+  **Details:**
+
+  .. ts:def:: BalanceList
+
+    interface BalanceList {
+      // Balances of the auditor.
+      balance: Balance[];
+    }
+
+  .. ts:def:: Balance
+
+    interface Balance {
+         // By what time does the exchange have to wire the funds?
+      balance_key: string;
+
+      // amount with fee and the fee from the deposit request.
+      balance_value: taler_amount;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing).
+       
+.. 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: taler_amount;
+         
+         // Amount that was lost due to failures by the exchange.
+      denom_loss: taler_amount;
+         
+         // Amount at risk of loss due to recoup operations.
+      denom_risk: taler_amount;
+         
+         // Amount actually lost due to recoup operations after a revocation.
+      recoup_loss: taler_amount;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing).
 
 ----------
 Complaints

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.