taler-docs

commit a86345eb94ac5797ce27a92bfdc10aa87bc30f27
parent a1a2b027706333e014ba604d1eee66ad665c9198
Author: Florian Dold <florian@dold.me>
Date:   Tue,  5 Sep 2023 14:22:31 +0200

libeufin bank API login endpoints, misc. comments and TODOs

Diffstat:
M
core/api-libeufin-bank.rst
 | 
92
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------

1 file changed, 71 insertions(+), 21 deletions(-)
diff --git a/core/api-libeufin-bank.rst b/core/api-libeufin-bank.rst
@@ -29,16 +29,21 @@ Libeufin Bank API
    * Clarify where the libeufin-bank API provides the Taler Wire Gateway API
      and Bank Integration API
 
-     * as a top-level ``/bank-integration-api/${USERNAME}`` or ``/accounts/${username}/bank-integration-api``?
+   * /config => { type: "libeufin-bank" }
+   * /bank-integration-api/config => { type: "taler-bank-integration" }
+   * /accounts/$USERNAME/taler-wire-gateway-api/config => { type: "taler-wire-gateway" }
+     * only for accounts that have been configured as a Taler exchange account
+   * /accounts/$USERNAME/taler-revenue-api/config { type: "taler-revenue-api" }
 
-   * With how it's currently documented, the TWG API and bank integration API
-     is *part* of the libeufin-bank API.  Is this correct?
-     Or do we want a separate name for the "libeufin account access" API?
-     That was the original intention with the (now gone) bank access API.
-     The libeufin-bank API would then just be a composition of multiple
-     other specified APIs.
+     * we used to call this the anastasis facade
 
-   * The pagination of accounts right now is page-based, do we want that?
+   * have flag for exchange account to enable bouncing transactions that don't have a reserve pub
+     or above a certain threshold
+   * in (all?) accounts, we can manage an access token for read-only access
+   * for public accounts, the read-only access token could simply be empty or a well-known token
+   * path: ``/accounts/${username}/taler-wire-gateway-api``?
+
+   * The pagination of account transactions right now is page-based, do we want that?
 
 .. contents:: Table of Contents
 
@@ -51,13 +56,59 @@ it provides features for local/regional currencies.
 Authentication
 --------------
 
-Some requests require the client to authenticate via HTTP Basic auth (RFC
-7617).  The user-id must be the libeufin-bank username, and the password the
-password for the corresponding user.
+Some requests require the client to authenticate via HTTP Basic auth (RFC 7617)
+or using a bearer token which can be obtained or refreshed from the
+``/accounts/$USERNAME/login`` endpoint.
+When using Basic authentication, the user-id must be the libeufin-bank
+username, and the password the password for the corresponding user.
+
+Another way to obtain a login token is by manually configuring it for certain
+endpoints.  For example, the exchange could give an auditor read-only access to
+the taler-wire-gateway facade via such a manually configured access token.
 
 The ``admin`` user is a special, hard-coded username. Some requests require the
 client to authenticate as the admin.
 
+.. http:post:: /accounts/$USERNAME/login
+
+   **Parameters**
+
+   .. ts:def:: LoginRquest
+
+     interface LoginRequest {
+       scope: "readonly" | "write";
+
+       // Server may impose its own upper bound
+       // on the token validity duration
+       duration?: RelativeTime;
+
+       // Can this token be refreshed?
+       // Defaults to false.
+       refreshable?: boolean;
+     }
+
+   **Response:**
+
+   TBD.
+
+   **Details:**
+
+   .. note::
+
+     Typically the ``access_token`` would be an EdDSA signature
+     over (username, scope, timestamp, expiry).
+
+     Alternatively, valid access tokens could also be random identifiers
+     stored in a database table.
+
+   .. ts:def:: LoginSuccessResponse
+
+     interface LoginSuccessResponse {
+       expiration: Timestamp;
+       access_token: string;
+     }
+
+
 Libeufin Bank Web UI
 --------------------
 
@@ -393,6 +444,11 @@ Transactions
 
    **Request**
 
+   .. note::
+
+     We should migrate this to use the same kind of pagination interface
+     that we use elsewhere in Taler (start and +/- delta).
+
    :query long_poll_ms: Optional number to express how many milliseconds the server
      should wait for at least one result to be shown.  If not given, the server
      responds immediately, regardless of the result.
@@ -422,23 +478,17 @@ Transactions
    .. ts:def:: BankAccountTransactionInfo
 
      interface BankAccountTransactionInfo {
+       creditor_payto_uri: string;
+       debtor_payto_uri: string;
 
-       creditor_iban: string;
-       creditor_bic: string; // Optional
-       creditor_name: string;
-
-       debtor_iban: string;
-       debtor_bic: string;
-       debtor_name: string;
+       amount: Amount;
+       direction: "debit" | "credit";
 
-       amount: number;
-       currency: string;
        subject: string;
 
        // Transaction unique ID.  Matches
        // $transaction_id from the URI.
        uid: string;
-       direction: "DBIT" | "CRDT";
        date: Timestamp;
      }