[taler-docs] branch master updated: terminology for merchant backend

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 18012a7  terminology for merchant backend
18012a7 is described below

commit 18012a7d0568cda761b6f7886fa445e4e8f8ff65
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Fri Jun 26 17:42:30 2020 +0200

    terminology for merchant backend
---
 taler-merchant-api-tutorial.rst |  23 +++-
 taler-merchant-manual.rst       | 289 +++++++++++++++++++++++++++++++---------
 2 files changed, 247 insertions(+), 65 deletions(-)

diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
index 6442e7c..eb9505c 100644
--- a/taler-merchant-api-tutorial.rst
+++ b/taler-merchant-api-tutorial.rst
@@ -1,5 +1,26 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014-2020 Taler Systems SA
+
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU 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 Lesser General Public License for more 
details.
+
+  You should have received a copy of the GNU Lesser General Public License 
along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Marcello Stanisci
+  @author Florian Dold
+  @author Christian Grothoff
+
+.. _merchant-api-tutorial:
+
 GNU Taler Merchant API Tutorial
-###################################
+###############################
 
 Introduction
 ============
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 7e3eac6..6ffd193 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -73,21 +73,24 @@ components:
    enables the customer to build a shopping cart and place an order.
    Upon payment, it triggers the respective business logic to satisfy
    the order. This component is not included with Taler, but rather
-   assumed to exist at the merchant. This manual describes how to
-   integrate Taler with Web shop frontends.
+   assumed to exist at the merchant.
+   The `Merchant API Tutorial <#merchant-api-tutorial>`__ gives an
+   introduction for how to integrate Taler with Web shop frontends.
 -  A back office application that enables the shop operators to view
    customer orders, match them to financial transfers, and possibly
    approve refunds if an order cannot be satisfied. This component is
-   again not included with Taler, but rather assumed to exist at the
-   merchant. This manual will describe how to integrate such a component
-   to handle payments managed by Taler.
+   not included with Taler, but rather assumed to exist at the
+   merchant. The `Merchant Backend API <#merchant-api>`__ provides
+   the API specification that should be reviewed to integrate such a
+   back office with the Taler backend.
 -  A Taler-specific payment backend which makes it easy for the frontend
-   to process financial transactions with Taler. The next two chapters
-   will describe how to install and configure this backend.
+   to process financial transactions with Taler. This manual primarily
+   describes how to install and configure this backend.
 -  A DBMS which stores the transaction history for the Taler backend.
    For now, the GNU Taler reference implemenation only supports
    Postgres, but the code could be easily extended to support another
-   DBMS.
+   DBMS.  Please review the Postgres documentation for details on
+   how to configure the database.
 
 The following image illustrates the various interactions of these key
 components:
@@ -96,13 +99,150 @@ components:
 
 .. index:: RESTful
 
-Basically, the backend provides the cryptographic protocol support,
-stores Taler-specific financial information in a DBMS and communicates
-with the GNU Taler exchange over the Internet. The frontend accesses the
-backend via a RESTful API. As a result, the frontend never has to
-directly communicate with the exchange, and also does not deal with
-sensitive data. In particular, the merchant’s signing keys and bank
-account information is encapsulated within the Taler backend.
+Basically, the backend provides the cryptographic protocol support, stores
+Taler-specific financial information in a DBMS and communicates with the GNU
+Taler exchange over the Internet. The frontend accesses the backend via a
+RESTful API. As a result, the frontend never has to directly communicate with
+the exchange, and also does not deal with sensitive data. In particular, the
+merchant’s signing keys and bank account information is encapsulated within
+the Taler backend.
+
+A typical deployment will additionally include a full-blown Web server (like
+Apache or Nginx). Such a Web server would be responsible for TLS termination
+and access control to the /private/ API endpoints of the merchant backend.
+Please carefully review the section on `Secure setup <#Secure-setup>`__ before
+deploying a Taler merchant backend to production.
+
+
+Terminology
+===========
+
+This chapter describes some of the key concepts used throughout the manual.
+
+Instances
+---------
+
+.. index:: instance
+
+The backend allows the user to run multiple *instances* of shops with distinct
+business entities sharing a single backend. Each instance uses its own bank
+accounts and key for signing contracts. All major accounting functionality is
+separate per instance.  What is shared is the database, HTTP(S) address and
+the main Taler configuration (accepted currency, exchanges and auditors).
+
+Accounts
+--------
+
+.. index:: account
+
+To receive payments, an instance must have configured one or more bank
+*accounts*.  The backend does not have accounts for users, and instances are
+also not really 'accounts'. So whenever we use the term *account*, it is about
+a bank account of a merchant.
+
+Inventory
+---------
+
+.. index:: inventory
+.. index:: product
+.. index:: lock
+.. index:: unit
+.. index:: order
+
+The Taler backend offers inventory management as an optional function.
+Inventory is tracked per instance and consists of *products* sold in
+*units*. Inventory can be finite or infinite (for digital products).
+Products may include previews (images) to be shown to the user and other
+meta-data. Inventory management allows the frontend to *lock* products,
+reserving them for a particular (unpaid) *order*. The backend can keep
+track of how many units of a product remain in stock and ensure that
+the number of units sold does not exceed the number of units in stock.
+
+Inventory management is optional, and it is possible for the frontend to
+include products in orders that are not in the inventory, or to override
+prices of products in the inventory.
+
+Orders and Contracts
+--------------------
+
+.. index:: order
+.. index:: contract
+.. index:: claim
+.. index:: pay
+.. index:: refund
+.. index:: wire deadline
+.. index:: lock
+.. index:: legal expiration
+
+In Taler, users pay merchants for orders. An order is first created by the
+merchant, where the merchant specifies the specific terms of the order.
+
+After an order is created, it is *claimed* by a wallet. Once an order is
+claimed by a specific wallet, only that wallet will be able to pay for this
+order, to the exclusion of other wallets even if they see the same order URL.
+
+A wallet may *pay* for a claimed order, at which point the order turns into
+a (paid) contract.  Orders have an expiration date after which the commercial
+offer expires and any stock of products *locked* by the order is released,
+allowing the stock to be sold in other orders.
+
+Once a contract has been paid, the merchant should fulfill the contract.  It
+is possible for the merchant to *refund* a contract order, for example if the
+contract cannot be fulfilled after all. Refunds are only possible until the
+exchange has *wired* the payment to the merchant. Once the funds have been
+wired, refunds are no longer allowed by the Taler exchange.  The *wire
+deadline* specifies the latest time by which an exchange must wire the funds,
+while the (earlier) *refund deadline* specifies the earliest time when an
+exchange may wire the funds.
+
+Contract information is kept for legal reasons, typically to provide tax
+records in case of a tax audit.  After the *legal expiration* (by default a
+decade), contract information is deleted.
+
+Transfers
+---------
+
+.. index:: transfer
+.. index:: wire transfer
+
+The Taler backend can be used to verify that the exchange correctly wired all
+of the funds to the merchant. However, the backend does not have access to the
+incoming wire transfers of the merchant's bank account. Thus, merchants must
+manually provide the backend with wire *transfer* data that specifies the wire
+transfer subject and the amount that was received. Given this information, the
+backend can detect and report any irregularities that might arise.
+
+Tipping
+-------
+
+.. index:: tip
+.. index:: grant
+.. index:: pick up
+
+Taler does not only allow a Website to be paid, but also to make voluntary,
+non-contractual payments to visitors, called *tips*.  Such tips could be
+granted as a reward for filling in surveys or watching advertisements. For
+tips, there is no contract, tips are always voluntary actions by the Web
+site that do not arise from a contractual obligation.  Before a Web site
+can create tips, it must establish a reserve.  Once a reserve has been
+established, the merchant can *grant* tips, allowing wallets to *pick up*
+the tip.
+
+Reserves
+--------
+
+.. index:: reserve
+.. index:: close
+
+A *reserve* is a pool of electronic cash at an exchange under the control of
+a private key.  Merchants withdraw coins from a reserve when granting
+tips.  A reserve is established by first generating the required key material
+in the merchant backend, and then wiring the desired amount of funds to the
+exchange.
+
+An exchange will automatically *close* a reserve after a fixed period of time
+(typically about a month), wiring any remaining funds back to the merchant.
+
 
 Installation
 ============
@@ -211,17 +351,17 @@ Installing the GNU Taler exchange
 After installing GNUnet, you can download and install the exchange as
 follows:
 
-::
+    ::
 
-   $ git clone https://git.taler.net/exchange/
-   $ cd exchange
-   $ ./bootstrap
-   $ ./configure [--prefix=EXCHANGEPFX] \
-                 [--with-gnunet=GNUNETPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
+      $ git clone https://git.taler.net/exchange/
+      $ cd exchange
+      $ ./bootstrap
+      $ ./configure [--prefix=EXCHANGEPFX] \
+                    [--with-gnunet=GNUNETPFX]
+      $ # Each dependency can be fetched from non standard locations via
+      $ # the '--with-<LIBNAME>' option. See './configure --help'.
+      $ make
+      # make install
 
 If you did not specify a prefix, the exchange will install to ``/usr/local``,
 which requires you to run the last step as ``root``.  You have to specify
@@ -244,18 +384,18 @@ The following steps assume all dependencies are installed.
 
 Use the following commands to download and install the merchant backend:
 
-::
+  ::
 
-   $ git clone https://git.taler.net/merchant/
-   $ cd merchant
-   $ ./bootstrap
-   $ ./configure [--prefix=PFX] \
-                 [--with-gnunet=GNUNETPFX] \
-                 [--with-exchange=EXCHANGEPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
+     $ git clone https://git.taler.net/merchant/
+     $ cd merchant
+     $ ./bootstrap
+     $ ./configure [--prefix=PFX] \
+                   [--with-gnunet=GNUNETPFX] \
+                   [--with-exchange=EXCHANGEPFX]
+     $ # Each dependency can be fetched from non standard locations via
+     $ # the '--with-<LIBNAME>' option. See './configure --help'.
+     $ make
+     # make install
 
 If you did not specify a prefix, the exchange will install to
 ``/usr/local``, which requires you to run the last step as ``root``.
@@ -287,7 +427,7 @@ On Debian jessie, only GNU libmicrohttpd needs to be 
compiled from
 source. To install dependencies on Debian jesse, run the following
 commands:
 
-::
+  ::
 
    # apt-get install \
      autoconf \
@@ -313,7 +453,7 @@ commands:
 
 For more recent versions of Debian, you should instead run:
 
-::
+  ::
 
    # apt-get install \
      autoconf \
@@ -587,7 +727,7 @@ Sample backend configuration
 
 The following is an example for a complete backend configuration:
 
-::
+  ::
 
    [TALER]
    CURRENCY = KUDOS
@@ -634,9 +774,9 @@ Launching the backend
 .. index:: taler-merchant-httpd
 
 Assuming you have configured everything correctly, you can launch the
-merchant backend as ``$USER`` using:
+merchant backend as ``$USER`` using
 
-::
+  ::
 
    $ taler-merchant-httpd
 
@@ -647,13 +787,13 @@ system for how to start and stop daemons.
 
 If everything worked as expected, the command
 
-::
+  ::
 
    $ curl http://localhost:8888/
 
 should return the message
 
-::
+  ::
 
    Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
 
@@ -662,21 +802,19 @@ Production systems should be configured to bind to a UNIX 
domain socket
 and use TLS for improved network privacy, see `Secure setup <#Secure-setup>`__.
 
 
-.. _Instances:
+.. index:: instance
+.. _Instance-setup:
 
-Instances
-=========
+Instance setup
+==============
 
-The backend allows the user to run multiple instances of shops with
-distinct business entities against a single backend. Each instance
-uses its own bank accounts and key for signing contracts. It is
-mandatory to configure at least the "default" instance.
+Before using the backend, you must at least configure the "default" instance.
 
 Instances can be configured by POSTing the necessary requests to the
 backend.  To create a first instance, create a file ``instance.json``
-with an `InstanceConfigurationMessage`:
+with an `InstanceConfigurationMessage`
 
-::
+  ::
 
    {
      payto_uris : [ "payto://iban/IBANNUMBERHERE" ],
@@ -693,7 +831,8 @@ with an `InstanceConfigurationMessage`:
 
 You can then create the instance using:
 
-::
+  ::
+
    $ wget --post-file=instance.json http://localhost:8888/private/instances
 
 The base URL for the instance will then be
@@ -719,14 +858,6 @@ The bank account information is provided in the form of a 
``payto://``-URL.
 See RFC XXXX for the format of ``payto://``-URLs.
 
 
-.. _Inventory:
-
-Inventory management
-====================
-
-
-
-
 
 .. _Secure-setup:
 
@@ -736,14 +867,26 @@ Secure setup
 .. index:: security
 .. index:: TLS
 
-For additional security, you may want to have the backend bind to a UNIX
-domain socket and use an HTTP reverse proxy for TLS termination:
+The Taler backend does not include even the most basic forms of
+access control or transport layer security.  Thus, production
+setups **must** deploy the Taler backend behind an HTTP(S) server
+that acts as a *reverse proxy*, performs TLS termination and
+authentication and then forwards requests to the backend.
+
+Using UNIX domain sockets
+-------------------------
+
+To ensure that the merchant backend is not exposed directly to the network,
+you should bind the backend to a UNIX domain socket:
 
    ::
 
       $ taler-config -s MERCHANT -o SERVE -V UNIX
       $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
 
+Reverse proxy configuration
+---------------------------
+
 Assuming your domain name is /example.com/ and you have TLS configured,
 a possible reverse proxy directive for Nginx would be:
 
@@ -757,7 +900,25 @@ a possible reverse proxy directive for Nginx would be:
 
 Leave out the last line if your Nginx reverse proxy does not have HTTPS
 enabled.  Make sure to restart the /taler-merchant-httpd/ process after
-changing the configuration.
+changing the ``SERVE`` configuration.
+
+Access control
+--------------
+
+All endpoints with /private/ in the URL must be restricted to authorized users
+of the respective instance.  Specifically, the HTTP server must be configured
+to only allow access to ``$BASE_URL/private/`` to the authorized users of the
+default instance, and to ``$BASE_URL/instances/$ID/private/`` to the
+authorized users of the instance ``$ID``.
+
+How access control is done (TLS client authentication, HTTP basic or digest
+authentication, etc.) is completely up to the merchant and does not matter to
+the Taler merchant backend.
+
+Note that all of the other endpoints (without /private/) are expected to be
+fully exposed to the Internet, and wallets may have to interact with those
+endpoints directly without client authentication.
+
 
 
 Upgrade procedure

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