commit 164c6211b42cb65bbed2f8809498d2e875d89753
parent 03bd30d8a6150b6326bef3c3118453c482e2b5b1
Author: Nic Eigel <nic@eigel.ch>
Date: Mon, 8 Jan 2024 15:26:28 +0100
adding auditor rest api
Diffstat:
| M | core/api-auditor.rst | | | 364 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 364 insertions(+), 0 deletions(-)
diff --git 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
