Merge branch 'master' of git+ssh://git.taler.net/docs

4 files changed, 209 insertions, 23 deletions

diff --git a/design-documents/016-backoffice-order-management.rst b/design-documents/016-backoffice-order-management.rst
index 1facccd3..b6564485 100644
--- a/design-documents/016-backoffice-order-management.rst
+++ b/design-documents/016-backoffice-order-management.rst
@@ -107,7 +107,7 @@ list a line with a resume of the total price and units will be shown.
 Create order: Price section
 ...........................
 
-This section scenarios. 
+This section has 2 scenarios. 
 
 The fist one is without products being added: the ``order price`` and
 ``summary`` inputs will be shown.
@@ -146,7 +146,7 @@ This section show optional values that can be overwritten by the merchant
   :width: 800
 
 Create order: all section expanded
-.............................
+..................................
 
 An example of how all section in a page will be shown.
 
diff --git a/design-documents/017-backoffice-inventory-management.rst b/design-documents/017-backoffice-inventory-management.rst
index 5513dd8b..8275e7a7 100644
--- a/design-documents/017-backoffice-inventory-management.rst
+++ b/design-documents/017-backoffice-inventory-management.rst
@@ -39,8 +39,6 @@ Listing the product will shown this columns:
 * image
 * description
 * sell price
-* total taxes
-* profit (price - taxes)
 * stock left (with next_restock in days if present)
 * stock sold
 
@@ -50,27 +48,10 @@ Actions will be
 * delete: with a confirm popup, it may fail if have some locked
 
 
-.. _backoffice-create-product:
-
 Create and Update Product form
 ------------------------------
 
-Creating without stock
-**********************
-
-.. image:: ../backoffice-product-create.with-stock.svg
-  :width: 800
-
-Creating with defined stock
-***************************
-
-.. image:: ../backoffice-product-create.without-stock.svg
-  :width: 800
-
-Updating 
-***************************
-  
-.. image:: ../backoffice-product-update.svg
+.. image:: ../backoffice-product-create.svg
   :width: 800
   
 Update product will use the same form except for the ``product_id``
@@ -96,12 +77,43 @@ Update product will use the same form except for the ``product_id``
 
 * Stock: button that opens more fields for stock control
 
-  * initial stock: number
+  * stock remaining: number
   * address: first collapsed, then field for Location
   * next_restock: date
   * cancel: button to set the stock to infinity, closing the section
 
+Stock management
+----------------
+
+* ``manage stock`` button will open the dialog below
+
+* ``without stock`` will close the dialog and set stock props to not defined
+
+* ``set/change`` button will open next restock sub dialog
+
+* ``update`` button will close subdialog and set the next restock value to input date
+
+* ``not known`` button will close subdialog and set next restock value to undefined
+
+* ``never`` button will close subdialog and set next restock to never
+
+* ``add`` button will show an input to increase the stock
+
+* if stock as added ``add`` button will be ``add more`` and a label with ``+ <number>`` will be shown
+
+* when updating the product, the option ``without stock`` will no be available 
+  if the product already has stock
+
+* when creating the product, ``current stock`` will be an input number
   
+* when updating the product, ``current stock`` will be read only with a button ``update``
+
+* when updating the stock, a new subdialog will appear with a confirm button.
+
+.. image:: ../backoffice-product-create.stock.svg
+  :width: 800
+
+
 Alternatives
 ============
 
diff --git a/design-documents/018-contract-json.rst b/design-documents/018-contract-json.rst
new file mode 100644
index 00000000..7c626007
--- /dev/null
+++ b/design-documents/018-contract-json.rst
@@ -0,0 +1,173 @@
+Design Doc 018: Forgettable Data in JSON Contract Terms
+#######################################################
+
+Summary
+=======
+
+This document defines concepts and algorithms for handling the JSON format of
+contract terms with forgettable data in Taler payments.
+
+Motivation
+==========
+
+The contract terms JSON format used in Taler describes various aspects of a
+payment request, such as the amount to be paid, accepted payment service
+providers, a human-readable summary, a list of products and shipping
+information.
+
+To support data minimization, it would be nice if some pieces of information
+stored in the contract terms (either in the storage of the merchant or the
+customer's wallet) could be deleted as soon as they are not strictly required
+anymore.
+
+However, the cryptographic hash of the contract terms is used throughout the
+Taler protocol as an opaque handle for the payment and associated processes.
+In an audit, a merchant might be asked to reveal the plain-text contract terms for a
+particular hash.
+
+Thus the hashing of the contract terms needs to take into account the
+forgettable parts of a contract terms.  The contract terms hash needs to be the
+same before and after forgetting a forgettable part of the contract terms.
+
+Proposed Solution
+=================
+
+Members of objects can be marked as forgettable by adding metadata to the
+contract terms JSON.  Before hashing the contract terms JSON, it is first
+scrubbed and canonicalized.  Scrubbing replaces forgettable members with a
+salted hash of their (recursively scrubbed and canonicalized) value.  To
+prevent attempts at guessing the value of forgotten members, a salt is
+generated and stored in the contract terms for each forgettable member.
+
+Constraints on Contract Terms JSON
+----------------------------------
+
+In order to make it easy to get a canonical representation for JSON contract
+terms, the following restrictions apply:
+
+* Member names are restricted:  Only strings matching the regular expression
+  ``0-9A-Z_a-z`` or the literal names ``$forgettable`` or ``$forgotten`` are
+  allowed.  This makes the sorting of object members easier, as RFC8785
+  requires sorting by UTF-16 code points.
+* Floating point numbers are forbidden.  Numbers must be integers in the range
+  ``-(2**53 - 1)`` to ``(2**52) - 1``.
+
+
+Marking Members as Forgettable
+------------------------------
+
+A property is marked as forgettable by including the property
+name as a key in the special ``$forgettable`` field of the property's
+parent object.
+
+.. code-block:: json
+
+   {
+    "delivery_address": ...,
+    "$forgettable": {
+      "delivery_address": "<salt>"
+    },
+   }
+
+Clients that write contract terms might not be able to easily generate the salt value.
+Thus, the merchant backend must also allow the following syntax in the order creation request:
+
+.. code-block:: json
+
+   {
+    "$forgettable": {
+      "delivery_address": true
+    },
+   }
+
+However, a JSON object with such a forgettable specification must be considered an
+invalid contract terms object.
+
+Forgetting a Forgettable Member
+-------------------------------
+
+To forget a forgettable member, it is removed from
+the parent object, and the salted hash of the member's
+scrubbed and canonicalized value is put into the special ``$forgotten$``
+member of the parent object.
+
+
+.. code-block:: json
+
+   {
+    ...props,
+    "delivery_address": ...,
+    "$forgettable": {
+      "delivery_address": "<memb_salt>"
+    },
+   }
+
+   => 
+
+   {
+    ...props,
+    "$forgotten": {
+      "delivery_address": "<memb_salted_hash>"
+    },
+    "$forgettable": {
+      "delivery_address": "<memb_salt>"
+    },
+   }
+
+The hash of a member value ``memb_val`` with salt ``memb_salt`` is computed as follows:
+
+.. code-block:: javascript
+
+   memb_val_canon = canonicalized_json(scrub(memb_val));
+
+   memb_salted_hash = hkdf_sha512({
+     output_length: 64,
+     input_key_material: memb_val_canon,
+     salt: memb_salt,
+   });
+
+When encoding ``memb_salted_hash`` with base32-crockford, the resulting output
+must be upper-case.
+
+
+Scrubbing
+---------
+
+A JSON object is scrubbed by recursively identifying and forgetting all
+forgettable fields.
+
+
+Canonicalized Hashing
+---------------------
+
+A JSON object is canonicalized by converting it to an ASCII byte array with the
+algorithm specified in `RFC 8785 <https://tools.ietf.org/html/rfc8785>`__.  The
+resulting bytes are terminated with a single 0-byte and then hashed with
+SHA512.
+
+
+Discussion / Q&A
+================
+
+* It is not completely clear which parts of the contract terms
+  should be forgettable.  This should be individually decided
+  by the merchant based on applicable legislation.
+
+* Is it really necessary that there is one salt per forgettable member?
+  We could also have a "contract terms global" salt, and then
+  use the global salt **and** the path of the forgettable field
+  as the salt for hashing.
+
+* Why do we require the 0-termination in the hash / kdf?  Doesn't seem to match what
+  e.g. ``shasum`` does.
+
+* Why do we not supply any "info" string (= context chunks in the GNUNET_CRYPTO_kdf terminology)
+  to the hkdf?  Does it matter?
+
+* We could also delete the corresponding ``$forgettable`` entry after
+  forgetting a member.  This would save storage.  But to prove that a certain
+  forgettable info matches the contract terms, the prover would need to
+  also store/provide the salt.
+
+* What validations should the wallet do?  Should the wallet ever accept
+  contract terms where fields are already forgotten?
diff --git a/design-documents/index.rst b/design-documents/index.rst
index c07f2a4a..dd740ea3 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -27,3 +27,4 @@ and protocol.
   015-merchant-backoffice-routing
   016-backoffice-order-management
   017-backoffice-inventory-management
+  018-contract-json