Merge branch 'master' into age-restriction

6 files changed, 450 insertions, 123 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index d25c2e52..1aae8e75 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1395,12 +1395,7 @@ exchange.
     The user should be redirected to the provided location to perform
     the required KYC checks to open the account before withdrawing.
     Afterwards, the request should be repeated.
-    The response will be an `AccountKycRedirect` object.
-
-    FIXME: Alternatively, we could return only a
-    PAYMENT_TARGET_UUID and expect the client to
-    then do a ``/kyc/`` request. That might be
-    more uniform with other APIs.
+    The response will be an `KycNeededRedirect` object.
 
     Implementation note: internally, we need to
     distinguish between upgrading the reserve to an
@@ -1492,6 +1487,16 @@ exchange.
 
     }
 
+  .. ts:def:: KycNeededRedirect
+
+    interface KycNeededRedirect {
+      // Payment target that the merchant should
+      // use to check for its KYC status using
+      // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint.
+      payment_target_uuid: Integer;
+
+    }
+
   .. ts:def:: WithdrawError
 
     interface WithdrawError {
@@ -1694,7 +1699,7 @@ denomination.
 
       // Payment target that the merchant should
       // use to check for its KYC status using
-      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint.
       payment_target_uuid: Integer;
 
       // Timestamp when the deposit was received by the exchange.
@@ -2547,7 +2552,7 @@ typically also view the balance.)
 
       // Payment target that the merchant should
       // use to check for its KYC status using
-      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint.
       payment_target_uuid: Integer;
 
       // Raw wire transfer identifier of the deposit.
@@ -2580,7 +2585,7 @@ typically also view the balance.)
 
       // Payment target that the merchant should
       // use to check for its KYC status using
-      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
+      // the ``/kyc-check/$PAYMENT_TARGET_UUID`` endpoint.
       payment_target_uuid: Integer;
 
       // Time by which the exchange currently thinks the deposit will be executed.
@@ -3183,15 +3188,6 @@ Wallet-to-wallet transfers
       // public key used to create the signature.
       exchange_pub: EddsaPublicKey;
 
-      // Payment target that the recipient should
-      // use to check for its KYC status using
-      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
-      //
-      // FIXME: may need to be a URL in case the
-      // exchange is foreign, alas, in this case
-      // we ALSO don't know the target UUID!
-      // => make optional?
-      payment_target_uuid: Integer;
     }
 
   .. ts:def:: MergeAccepted
@@ -3202,16 +3198,6 @@ Wallet-to-wallet transfers
       // under the given account.
       remaining_purses: Integer;
 
-      // Payment target that the recipient should
-      // use to check for its KYC status using
-      // the ``/kyc/$PAYMENT_TARGET_UUID`` endpoint.
-      //
-      // FIXME: may need to be a URL in case the
-      // exchange is foreign, alas, in this case
-      // we ALSO don't know the target UUID!
-      // => make optional?
-      payment_target_uuid: Integer;
-
     }
 
 
@@ -3373,7 +3359,7 @@ KYC status updates
 
       // EdDSA signature of the exchange affirming the account
       // is KYC'ed, must be of purpose
-      // ``TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS``
+      // ``TALER_SIGNATURE_EXCHANGE_ACCOUNT_SETUP_SUCCESS``
       // and over `TALER_AccountSetupStatusSignaturePS`.
       exchange_sig: EddsaSignature;
 
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index c9981543..519a4324 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1219,7 +1219,7 @@ KYC status checks
 
   :query h_wire=H_WIRE: *Optional*. If specified, the KYC check should return the KYC status only for this wire account. Otherwise, for all wire accounts.
   :query exchange_url=URL: *Optional*. If specified, the KYC check should return the KYC status only for the given exchange. Otherwise, for all exchanges we interacted with.
-  :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
+  :query timeout_ms=NUMBER: *Optional.*  If specified, the merchant will
     wait up to ``timeout_ms`` milliseconds for the exchanges to confirm completion of the KYC process(es).
 
   **Response:**
@@ -1261,7 +1261,7 @@ KYC status checks
 
        // URL that the user should open in a browser to
        // proceed with the KYC process (as returned
-       // by the exchange's ``/kyc/`` endpoint).
+       // by the exchange's ``/kyc-check/`` endpoint).
        kyc_url: string;
 
        // Base URL of the exchange this is about.
@@ -1272,9 +1272,9 @@ KYC status checks
 
      }
 
-  .. ts:def:: MerchantAccountKycRedirect
+  .. ts:def:: ExchangeKycTimeout
 
-     interface MerchantAccountKycRedirect {
+     interface ExchangeKycTimeout {
 
        // Base URL of the exchange this is about.
        exchange_url: string;
diff --git a/design-documents/006-extensions.rst b/design-documents/006-extensions.rst
new file mode 100644
index 00000000..e663b2f5
--- /dev/null
+++ b/design-documents/006-extensions.rst
@@ -0,0 +1,135 @@
+Design Document 006: Extensions for GNU Taler
+#############################################
+
+Summary
+=======
+
+This design document describes a generic framework for how extensions (i.e.
+optional features) to GNU Taler can be offered and used by the exchange,
+merchants and wallets.
+
+Motivation
+==========
+
+GNU Taler's list of supported features evolves over time.  For example, the
+following features are going to be designed and implemented during the course
+of 2021 and 2022:
+
+* Peer-to-peer payments
+* Anonymous age-restriction
+* Escrow service for anonymous auctions
+
+We call a feature an *extension* when it is *optional* for either the
+exchange, wallet or merchant to enable and support it. (However, enabling
+a feature might *require* the other parties to support the feature, too)
+
+For optional features we therefore need a mechanism to express the
+availability, version and configuration of a particular feature, f.e. p2p or
+age-restriction offered by an exchange, and make it verifiable by the other
+participants.
+
+Requirements
+============
+
+TODO. Not sure if we have any requirements - other than particular
+ideas/designs for extensions?
+
+
+Proposed Solution
+=================
+
+Exchange
+^^^^^^^^
+
+The exchange will add two new REQUIRED fields in response to ``/keys``:
+
+#. The (but maybe empty) field ``extensions`` which contains a dictionary of
+   extension-names and their configuration, see below.
+
+#. The field ``extensions_sig`` that contains the EdDSA signature of the SHA256-hash
+   of the normalized JSON-string of the ``extenstions`` object.
+
+The names of extensions MUST be unique and SHOULD include a version information
+in Taler's `protocol version ranges notation`_ as suffix starting with letter
+'``v``', f.e.: ``age_restriction.v1`` or ``p2p.v1:2:3``.
+
+.. _protocol version ranges notation: https://docs.taler.net/core/api-common.html#protocol-version-ranges
+
+
+The necessary changes to ``ExchangeKeysResponse`` are highlighted here:
+
+.. ts:def:: ExchangeKeysResponse
+
+   interface ExchangeKeysResponse {
+   //...
+
+   // Required (but maybe emtpy) field with a dictionary of (name, object)
+   // pairs defining the supported extensions.
+   // The name MUST be unique and SHOULD include version information in Taler's
+   // protocol version ranges notation as suffix, starting with letter 'v',
+   // f.e.: "age_restriction.v1" or "p2p.v1:2:3".
+   extensions: { name: Extension };
+
+   // Signature by the exchange master key of the SHA-512 hash of the
+   // normalized JSON-object of field ``extenstions``.
+   // The signature MUST have purpose ``TALER_SIGNATURE_MASTER_EXTENSIONS``.
+   extensions_sig: EddsaSignature;
+
+   //...
+   }
+
+
+The definition of ``Extension`` object itself is mostly up to the particular
+feature.  However, it MUST contain the following fields:
+
+* ``description`` ― a short description of the feature itself.  Can be used by wallets to display information about the feature to the customer.
+
+*  ``required`` ― a boolean that indicates if this feature MUST be supported by the wallets and/or merchants in order to use this exchange.
+
+.. ts:def:: Extension
+
+   interface Extension {
+     // Short description of the feature.
+     description: string;
+
+     // Set to ``true`` if this extension MUST be supported by wallets and/or
+     // merchants.
+     required: boolean;
+
+     // Additional fields defined by the feature itself
+     ...
+
+   }
+
+
+**TODO**:
+
+* Add examples for age-restriction and p2p.
+
+Merchant
+^^^^^^^^
+
+TODO:
+
+* Needs to express support for particular extensions, too.  F.e. age-restriction.
+
+Alternatives
+============
+
+TODO.  None yet.
+
+
+Drawbacks
+=========
+
+* We do not offer (yet) any lifetime cycle of a feature, that is:  There are
+  only two states that a feature can be in: "available" or "not-available".
+
+* The existing design for peer-to-peer payments must be adapted to this.
+
+Discussion / Q&A
+================
+
+The initial ideas presented here are based on discussions between Özgür Kesim
+and Christian Grothoff.
+
diff --git a/design-documents/index.rst b/design-documents/index.rst
index e5cd09e6..7de0d2ea 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -14,6 +14,7 @@ and protocol.
   003-tos-rendering
   004-wallet-withdrawal-flow
   005-wallet-backup-sync
+  006-extensions
   007-payment
   008-fees
   009-backup
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index b30061ae..b75fcf8d 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -2,104 +2,91 @@
 
 .. _sandbox-api:
 
-Sandbox API
-###########
+Current Sandbox API
+###################
 
 ..
   Current Sandbox endpoints.
 
-  POST /register
-  GET /jinja-test
-  GET /profile
-  GET /static
   GET /
-  GET /config
-  POST /admin/payments/camt
-  POST /admin/bank-accounts/$accountLabel
-  GET /admin/bank-accounts/$accountLabel
-  POST /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
-  POST /admin/payments
-  POST /admin/ebics/bank-accounts
-  GET /admin/bank-accounts
-  GET /admin/bank-accounts/$accountLabel/transactions
-  POST /admin/bank-accounts/$accountLabel/generate-transactions
-  POST /admin/ebics/subscribers
-  GET /admin/ebics/subscribers
-  POST /admin/ebics/hosts/$hostID/rotate-keys
-  POST /admin/ebics/hosts
-  GET /admin/ebics/hosts
-  POST /ebicsweb
+  Welcome message.
 
-HTTP API
-========
+  ** Camt debug **
 
-..
-  Payments.
+  POST /admin/payments/camt 
+  give last statement of requesting account
 
+  ** Bank accounting **
 
-.. http:post:: /admin/payments/camt
+  POST /admin/bank-accounts/$accountLabel 
+  create bank account (no EBICS involved)
 
-  Return the history of one IBAN in Camt.053 format.
+  GET /admin/bank-accounts
+  Give summary of all the bank accounts.
 
-  **Request**
+  GET /admin/bank-accounts/$accountLabel 
+  give general information about a bank account
 
-   .. code-block:: tsref
+  ** Transactions **
 
-     interface CamtParams {
+  POST /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
+  Book one incoming transaction for $accountLabel.
+  The debtor (not required to be in the same bank)
+  information is taken from the request.
 
-       // label of the bank account being queried.
-       bankaccount: string;
+  GET /admin/bank-accounts/$accountLabel/transactions
+  Inform about all the transactions of one bank account.
 
-       // The Camt type to return.  Only '53' is allowed
-       // at this moment.
-       type: number;
-     }
+  POST /admin/bank-accounts/$accountLabel/generate-transactions
+  Generate one incoming and one outgoing transaction
+  for one bank account.
 
-  **Response**
+  ** EBICS subscribers management **
 
-  The expected Camt.053 document.
+  POST /admin/ebics/subscribers
+  Create a new EBICS subscriber.
+
+  GET /admin/ebics/subscribers
+  Give details of all the EBICS subscribers in the bank.
 
-.. http:post:: /admin/payments
+  POST /admin/ebics/bank-accounts
+  Create a *new* bank account and link it with a existing
+  EBICS subscriber.
 
-   Adds a new payment to the book.  Mainly used for testing
-   purposes.
+  ** EBICS host management **
 
-   **Request:**
+  POST /admin/ebics/hosts/$hostID/rotate-keys
+  Change the bank's keys used in EBICS communication.
 
-   One object of type `SandboxPayment`
+  POST /admin/ebics/hosts
+  Create a new EBICS host.
 
-    .. ts:def:: SandboxPayment
+  GET /admin/ebics/hosts
+  Show details of all the EBICS hosts in the bank. 
 
-     interface SandboxPayment {
+  ** EBICS serving **
 
-       // IBAN that will receive the payment.
-       creditorIban: string;
-       // FIXME
-       creditorBic: string;
-       // FIXME
-       creditorName: string;
+  POST /ebicsweb
+  Processes a EBICS request.
 
-       // IBAN that will send the payment.
-       debitorIban: string;
-       // FIXME
-       debitorBic: string;
-       // FIXME
-       debitorName: string;
+  ** Taler .. **
 
-       amount: string;
-       currency: string;
+  GET /taler
+  Show one taler://-URI to initiate a withdrawal.
 
-       // subject of the payment.
-       subject: string;
+  - Taler integration API.
 
-       // Whether the payment is credit or debit *for* the
-       // account being managed *by* the running sandbox.
-       // Can take the values: "CRDT" or "DBIT".
-       direction: string;
-     }
+  - Demobank configuration API.
+    ToDo.
 
-..
-  Host management.
+  - Taler access API.
+    ToDo.
+
+EBICS.
+^^^^^^
+
+Hosts.
+++++++
 
 .. http:post:: /admin/ebics/hosts
 
@@ -141,8 +128,37 @@ HTTP API
    meant for tests (as the Sandbox itself is) and no backup will be
    produced along this operation.
 
-..
-  Subscriber management.
+
+Subscribers.
+++++++++++++
+
+.. http:post:: /admin/ebics/bank-accounts
+
+  Associates a new bank account to an existing subscriber.
+
+  **Request:**
+
+    .. ts:def:: BankAccountRequest
+
+     interface BankAccountRequest {
+
+       // Ebics subscriber
+       subscriber: string;
+
+       // IBAN
+       iban: string;
+
+       // BIC
+       bic: string;
+
+       // human name
+       name: string;
+
+       // bank account label
+       label: string;
+
+     }
+
 
 .. http:post:: /admin/ebics/subscribers
 
@@ -197,36 +213,205 @@ HTTP API
 
       }
 
-.. http:post:: /admin/ebics/bank-accounts
 
-  Associates a new bank account to an existing subscriber.
+Bank accounts.
+^^^^^^^^^^^^^^
 
-  **Request:**
+.. http:get:: /admin/bank-accounts
 
-    .. ts:def:: BankAccountRequest
+   Give summary of all the bank accounts.
 
-     interface BankAccountRequest {
+.. http:get:: /admin/bank-accounts/$accountLabel
 
-       // Ebics subscriber
-       subscriber: string;
+   Give information about a bank account.
 
-       // IBAN
-       iban: string;
 
-       // BIC
-       bic: string;
+Main EBICS service.
+^^^^^^^^^^^^^^^^^^^
 
-       // human name
-       name: string;
+.. http:post:: /ebicsweb
 
-       // bank account label
-       label: string;
+   Serves all the Ebics requests.
+
+
+Transactions.
+^^^^^^^^^^^^^
+
+JSON.
++++++
+
+.. http:get:: /admin/bank-accounts/$accountLabel/transactions
+
+   Inform about all the transactions of one bank account.
 
+.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions
+
+   Generate one incoming and one outgoing transaction for one bank account.
+
+.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
+
+   Book one incoming transaction for $accountLabel.
+   The debtor (not required to be in the same bank)
+   information is taken from the request.
+
+
+Camt.
++++++
+
+.. http:post:: /admin/payments/camt
+
+  Return the last statement of the requesting account.
+
+  **Request**
+
+   .. code-block:: tsref
+
+     interface CamtParams {
+
+       // label of the bank account being queried.
+       bankaccount: string;
+
+       // The Camt type to return.  Only '53' is allowed
+       // at this moment.
+       type: number;
      }
 
-..
-  Main EBICS service.
+  **Response**
 
-.. http:post:: /ebicsweb
+  The expected Camt.053 document.
 
-   Serves all the Ebics requests.
+Future Sandbox API
+##################
+
+Resources.
+----------
+
+Sandbox serves the following resources:
+
+ - Demobanks.
+ - Bank accounts.
+ - Subscribers.
+ - Transactions.
+ - Customers.
+ - Reports.
+ 
+The resources are subject to all CRUD operations, via by two
+types of users: the 'admin' and the customers.  The admin has
+rights on all of them.
+
+One of the main differences with the previous versions is the
+removal of the "/admin" initial component.  If the administrator
+authenticates for one operation, then this one is of type `admin`:
+no need for a dedicate and extra URI part.
+
+For example, mocking transactions in the system was a typical
+/admin-operation, but since transactions themselves are resources
+and any resource is subject to CRUD operations, then mocking one
+becomes just a `C` operation on the 'transactions' resources.  If
+a test case wants to simplify the authentication - by hard-coding
+the credentials, for example - before mocking one transaction, then
+it can impersonate the administrator.
+
+.. note::
+
+   ``POST``-ing to a endpoint with a trailing ``$id`` means
+   modification of a existing resource.
+
+Demobanks
+^^^^^^^^^
+
+Demobanks are the main containers of all the other resources.
+They take configuration values, like the currency for example.
+
+.. http:get:: /admin/demobanks
+.. http:get:: /admin/demobanks/$id
+.. http:post:: /admin/demobanks
+.. http:post:: /admin/demobanks/$id
+.. http:delete:: /admin/demobanks/$id
+
+Bank accounts.
+^^^^^^^^^^^^^^
+
+Bank accounts collect money of customers and participate
+in transactions.
+
+The ``$base`` is one demobank, in the form ``/demobanks/$id``.
+That is due because a bank account must inherit some defaults
+from the demobank, like the currency.
+
+.. http:get:: $base/bankaccounts
+.. http:get:: $base/bankaccounts/$id
+.. http:post:: $base/bankaccounts
+.. http:post:: $base/bankaccounts/$id
+.. http:delete:: $base/bankaccounts/$id
+
+Subscribers.
+^^^^^^^^^^^^
+
+Subscribers are (optional) customers identities for protocols
+other than the native one.
+
+A subscriber is not required to have a bank account `soon`.  Therefore,
+it can be created, and later be linked to one bank account.  For this
+reason, the ``$base`` should not mention one bank account.
+
+.. note::
+
+   Creating a subscriber is a time-consuming operation that goes often
+   through slow channels, therefore it should basically never be done
+   more than once.
+
+.. http:get:: $base/subscribers
+.. http:get:: $base/subscribers/$id
+.. http:post:: $base/subscribers
+.. http:post:: $base/subscribers/$id
+.. http:delete:: $base/subscribers/$id
+
+Transactions.
+^^^^^^^^^^^^^
+
+Transactions are money movements between bank accounts.
+
+For convenience, ``$base`` **could** mention one bank account
+to let customers see their transactions without defining "history"
+query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``.
+
+At the same time, transactions should be easy to query regardless
+of whose bank account they involve -- for administrative reasons, for
+example.  Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX``
+should be offered as well.
+
+.. http:get:: $base/transactions
+.. http:get:: $base/transactions/$id
+.. http:post:: $base/transactions
+.. http:post:: $base/transactions/$id
+.. http:delete:: $base/transactions/$id
+
+Customers.
+^^^^^^^^^^
+
+Customers are persons that **can** have one bank account.  As
+with subscribers, ``$base`` should not mention any bank account
+so as to leave more flexibility to assign new bank accounts to
+the same customer.
+
+.. http:get:: $base/customers
+.. http:get:: $base/customers/$id
+.. http:post:: $base/customers
+.. http:post:: $base/customers/$id
+.. http:delete:: $base/customers/$id
+
+Reports.
+^^^^^^^^
+
+Reports are persistent documents witnessing transactions.
+A typical example is a Camt.053 statement.  A report lives
+even after a bank account gets deleted or a customer leaves
+the bank, therefore ``$base`` should only mention a demobank
+instance.
+
+.. http:get:: $base/reports
+.. http:get:: $base/reports/$id
+.. http:post:: $base/reports
+.. http:post:: $base/reports/$id
+.. http:delete:: $base/reports/$id
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 1a366608..7d7f5b86 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -174,6 +174,26 @@ PRIVACY_DIR
 PRIVACY_ETAG
   Works the same as ``TERMS_ETAG``, just for the privacy policy.
 
+KYC_MODE
+  Set to "NONE" to disable KYC for this exchange (but check with your lawyer first).
+  Set to "OAUTH2" to use OAuth2 for KYC.
+
+
+EXCHANGE KYC OAUTH2 OPTIONS
+---------------------------
+
+The following options must be in the section "[exchange-kyc-oauth2]".
+
+
+KYC_OAUTH2_URL
+  URL of the OAuth2 endpoint to be used for KYC checks. Requires KYC_ENABLED to be "OAUTH2".
+
+KYC_OAUTH2_CLIENT_ID
+  Client ID of the exchange when it talks to the KYC OAuth2 endpoint. Requires KYC_ENABLED to be "OAUTH2".
+
+KYC_OAUTH2_CLIENT_SECRET
+  Client secret of the exchange to use when talking to the KYC Oauth2 endpoint. Requires KYC_ENABLED to be "OAUTH2".
+
 
 EXCHANGE OFFLINE SIGNING OPTIONS
 --------------------------------