update coin spend history for #5777 API change - merging

7 files changed, 206 insertions, 32 deletions

diff --git a/api-auditor.rst b/api-auditor.rst
index 6ea01d7c..957b1c01 100644
--- a/api-auditor.rst
+++ b/api-auditor.rst
@@ -46,7 +46,7 @@ know-your-customer (KYC) registration before issuing contracts.
 
   **Details:**
 
-  .. _ExchangeList:
+  .. _AuditorVersion:
   .. code-block:: tsref
 
     interface AuditorVersion {
diff --git a/api-bank.rst b/api-bank.rst
index 9256e3d7..07de8191 100644
--- a/api-bank.rst
+++ b/api-bank.rst
@@ -21,6 +21,87 @@
 Bank API
 =========
 
+This API provides programmatic user registration at the bank.
+
+.. _bank-register:
+.. http:post:: /register
+
+**Request** The body of this request must have the format of a `BankRegistrationRequest`_.
+
+**Response**
+
+:status 200 OK: The new user has been correctly registered.
+:status 409 Conflict: the username requested by the client is not available anymore
+:status 406 Not Acceptable: unacceptable characters were given for the username. See https://docs.djangoproject.com/en/2.2/ref/contrib/auth/#django.contrib.auth.models.User.username for the accepted character set.
+
+**Details**
+
+.. _BankRegistrationRequest:
+.. code-block:: tsref
+
+  interface BankRegistrationRequest {
+  
+    // Username to use for registration; max length is 150 chars.
+    username: string;
+
+    // Password to associate with the username.  Any characters and
+    // any length are valid; next releases will enforce a minimum length
+    // and a safer characters choice.
+    password: string;
+  }
+
+
+This API provides programmatic withdrawal of cash via Taler to all the
+users registered at the bank.  It triggers a wire transfer from the client
+bank account to the exchange's.
+
+.. _bank-register:
+.. http:post:: /taler/withdraw
+
+**Request** The body of this request must have the format of a `BankTalerWithdrawRequest`_.
+
+**Response**
+
+:status 200 OK: The withdrawal was correctly initiated, therefore the exchange received the payment.  A `BankTalerWithdrawResponse`_ object is returned.
+:status 406 Not Acceptable: the user does not have sufficient credit to fulfill their request.
+:status 404 Not Found: The exchange wire details did not point to any valid bank account.
+
+**Details**
+
+.. _BankTalerWithdrawRequest:
+.. code-block:: tsref
+
+  interface BankTalerWithdrawRequest {
+
+    // Authentication method used
+    auth: BankAuth;
+  
+    // Amount to withdraw.
+    amount: Amount;
+
+    // Reserve public key.
+    reserve_pub: string;
+
+    // Exchange bank details specified in the 'payto'
+    // format.  NOTE: this field is optional, therefore
+    // the bank will initiate the withdrawal with the
+    // default exchange, if not given.
+    exchange_wire_details: string;
+  }
+
+.. _BankTalerWithdrawResponse:
+.. code-block:: tsref
+
+  interface BankTalerWithdrawResponse {
+
+    // Sender account details in 'payto' format.
+    sender_wire_details: string;
+
+    // Exchange base URL.  Optional: only returned
+    // if the user used the default exchange.
+    exchange_url: string;
+  }
+
 This API allows one user to send money to another user, within the same "test"
 bank.  The user calling it has to authenticate by including his credentials in the
 request.
diff --git a/api-common.rst b/api-common.rst
index 3b0bc4b2..8f3ae378 100644
--- a/api-common.rst
+++ b/api-common.rst
@@ -796,3 +796,17 @@ within the
     struct TALER_ReservePublicKeyP reserve_pub;
     struct GNUNET_HashCode h_wire;
   };
+
+.. _TALER_CoinLinkSignaturePS:
+.. sourcecode:: c
+
+  struct TALER_CoinLinkSignaturePS {
+    /**
+     * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_LINK
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct GNUNET_HashCode h_denom_pub;
+    struct TALER_CoinSpendPublicKeyP old_coin_pub;
+    struct TALER_TransferPublicKeyP transfer_pub;
+    struct GNUNET_HashCode coin_envelope_hash;
+  };
diff --git a/api-exchange.rst b/api-exchange.rst
index b18cab3c..32f3d5ce 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -717,6 +717,14 @@ denomination.
 
       // public key used to sign `exchange_sig`, only present if `exchange_sig` present.
       exchange_pub?: EddsaPublicKey;
+
+      // Blinding factor of the revoked new coin,
+      // only present if `type` is "REFRESH_PAYBACK".
+      new_coin_blinding_secret: RsaBlindingKeySecret;
+
+      // Blinded public key of the revoked new coin,
+      // only present if `type` is "REFRESH_PAYBACK".
+      new_coin_ev: RsaBlindingKeySecret;
     }
 
 ----------
@@ -881,10 +889,14 @@ the API during normal operation.
       // transfer public key at the `noreveal_index`.
       transfer_pub: EddsaPublicKey;
 
+      // Array of `n` signatures made by the wallet using the old coin's private key,
+      // used later to verify the /refresh/link response from the exchange.
+      // Signs over a `TALER_CoinLinkSignaturePS`_
+      link_sigs: EddsaSignature[];
+
       // The original commitment, used to match the /refresh/reveal
       // to the corresponding /refresh/melt operation.
-      rc: TALER_RefreshCommitmentP;
-
+      rc: HashCode;
     }
 
 
@@ -910,8 +922,47 @@ the API during normal operation.
       code: integer;
 
       // Commitment as calculated by the exchange from the revealed data.
-      rc_expected: TALER_RefreshCommitmentP;
+      rc_expected: HashCode;
+
+    }
+
+
+.. http:post:: /refresh/payback
+
+  When a fresh coin that was obtained via refresh is revoked, the refresh payback can be used
+  to revert the refresh and credit the old coin with the refreshed coin's value.
+
+  :status 200 OK:
+    The old coin was successfully credited with the value of the revoked new coin.
+  :status 404 Not Found:
+    Either the refresh commitment has not been seen by the exchange before,
+    the old coin was not found among the refreshed coins,
+    or the blinded new coin's public key has not been seen and signed before
+    by the exchange.
+  :status 401 Unauthorized:
+    The blinding secret does not match the signature stored by the exchange
+    the new_coin_ev.
+
+  **Details:**
+
+  Request body contains a JSON object with the following fields:
+
+  .. code-block:: tsref
 
+    interface RefreshPaybackRequest {
+      // Public key of the old coin that should receive the
+      // refund for the refreshed coin.
+      old_coin_pub: RsaPublicKey;
+
+      // Blinded public key of the coin of the revoked denomination.
+      new_coin_ev: CoinEnvelope;
+
+      // Secret blinding factor of the new coin
+      new_coin_blinding_secret: RsaBlindingKeySecret;
+
+      // Commitment that identifies the refresh operation.
+      // Redundant, but speeds up the exchange's database lookup.
+      rc: HashCode;
     }
 
 
@@ -957,6 +1008,14 @@ the API during normal operation.
 
       // Exchange's blinded signature over the exchangeed coin.
       ev_sig: BlindedRsaSignature;
+
+      // Blinded coin, to be verified by the wallet to protect against
+      // a malicious exchange.
+      coin_ev: CoinEnvelope;
+
+      // Signature made by the old coin over the refresh request.
+      // Signs over a `TALER_CoinLinkSignaturePS`_
+      link_sig: EddsaSignature;
     }
 
 
diff --git a/api-merchant.rst b/api-merchant.rst
index 9a04236e..0d0302f9 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -607,7 +607,7 @@ Dynamic Merchant Instance
     The backend has successfully returned the list of instances stored. Returns
     a `InstancesResponse`_.
 
-  .. InstancesResponse:
+  .. _InstancesResponse:
   .. code-block:: tsref
 
     interface InstancesResponse {
@@ -650,7 +650,7 @@ The `instance` object describes the instance registered with the backend. It has
     The backend has successfully created the instance.  The response is a
     `CreateInstanceResponse`_.
 
-  .. CreateInstanceRequest:
+  .. _CreateInstanceRequest:
   .. code-block:: tsref
 
     interface CreateInstanceRequest {
@@ -668,7 +668,7 @@ The `instance` object describes the instance registered with the backend. It has
 
     }
 
-  .. CreateInstanceResponse:
+  .. _CreateInstanceResponse:
   .. code-block:: tsref
 
     interface CreateInstanceResponse {
@@ -694,7 +694,7 @@ The `instance` object describes the instance registered with the backend. It has
     The backend has successfully returned the list of instances stored. Returns
     a `QueryInstancesResponse`_.
 
-  .. QueryInstancesResponse:
+  .. _QueryInstancesResponse:
   .. code-block:: tsref
 
     interface QueryInstancesResponse {
@@ -728,7 +728,7 @@ The `instance` object describes the instance registered with the backend. It has
     The backend has successfully updated the instance.  The response is a
     `PostInstanceUpdateResponse`_.
 
-  .. PostInstanceUpdateRequest:
+  .. _PostInstanceUpdateRequest:
   .. code-block:: tsref
 
     interface PostInstanceUpdateRequest {
@@ -744,7 +744,7 @@ The `instance` object describes the instance registered with the backend. It has
 
     }
 
-  .. PostInstanceUpdateResponse:
+  .. _PostInstanceUpdateResponse:
   .. code-block:: tsref
 
     interface PostInstanceUpdateResponse {
@@ -770,7 +770,7 @@ The `instance` object describes the instance registered with the backend. It has
     The backend has successfully removed the instance.  The response is a
     `PostInstanceRemoveResponse`_.
 
-  .. PostInstanceRemoveResponse:
+  .. _PostInstanceRemoveResponse:
   .. code-block:: tsref
 
     interface PostInstanceRemoveResponse {
diff --git a/api-sync.rst b/api-sync.rst
index 4966a01e..701c7df5 100644
--- a/api-sync.rst
+++ b/api-sync.rst
@@ -288,7 +288,7 @@ Receiving Terms of Service
     HTTP specification, the synchronization service may require
     the client to provide the length upfront.
 
-  :status 413 Payload too large:
+  :status 413 Request Entity Too Large:
     The requested upload exceeds the quota for the type of
     account.  The wallet should suggest to the user to
     migrate to another backup and synchronization service
@@ -375,23 +375,24 @@ Synchronization user experience
 
 The menu should include three entries for synchronization:
 
-  *  "synchronize" to manually trigger synchronization,
-     insensitive if no synchronization provider is available
-  *  "export backup configuration" to re-display (and possibly
-     print) the synchronization and backup parameters (URL and
-     private key), insensitive if no synchronization
-     provider is available, and
-  *  "import backup configuration" to:
-     *  import another devices' synchronization options
-	(by specifying URL and private key, or possibly
-	scanning a QR code), or
-     *	select a synchronization provider from the list,
-	including manual specification of a URL; here
-	confirmation should only be possible if the provider
-	is free or can be paid for; in this case, the
-	wallet should trigger the payment interaction when
-	the user presses the "select" button.
-     *  a special button to "disable synchronization and backup"
+* "synchronize" to manually trigger synchronization,
+    insensitive if no synchronization provider is available
+* "export backup configuration" to re-display (and possibly
+   print) the synchronization and backup parameters (URL and
+   private key), insensitive if no synchronization
+   provider is available, and
+* "import backup configuration" to:
+
+  * import another devices' synchronization options
+    (by specifying URL and private key, or possibly
+    scanning a QR code), or
+  * select a synchronization provider from the list,
+    including manual specification of a URL; here
+    confirmation should only be possible if the provider
+    is free or can be paid for; in this case, the
+    wallet should trigger the payment interaction when
+    the user presses the "select" button.
+  * a special button to "disable synchronization and backup"
 
 One usability issue here is that we are asking users to deal with a
 private key.  It is likely better to map private keys to trustwords
diff --git a/exts/httpdomain/httpdomain.py b/exts/httpdomain/httpdomain.py
index 03d58b79..a5e34716 100644
--- a/exts/httpdomain/httpdomain.py
+++ b/exts/httpdomain/httpdomain.py
@@ -64,7 +64,7 @@ class IETFRef(DocRef):
     """Represents a reference to the specific IETF RFC."""
 
     def __init__(self, rfc, section):
-        url = 'http://tools.ietf.org/html/rfc{0:d}'.format(rfc)
+        url = 'https://tools.ietf.org/html/rfc{0:d}'.format(rfc)
         super(IETFRef, self).__init__(url, 'section-', section)
 
 
@@ -124,7 +124,7 @@ HEADER_REFS = {
     'Cookie': IETFRef(2109, '4.3.4'), # also RFC6265 section 5.4
     'Date': IETFRef(7231, '7.1.1.2'),
     'Destination': IETFRef(2518, 9.3),
-    'ETag': IETFRef(7231, 2.3),
+    'ETag': IETFRef(7232, 2.3),
     'Expect': IETFRef(7231, '5.1.1'),
     'Expires': IETFRef(7234, 5.3),
     'From': IETFRef(7231, '5.5.2'),
@@ -492,6 +492,8 @@ class HTTPXRefStatusRole(XRefRole):
             url = 'http://tools.ietf.org/html/rfc6585#section-4'
         elif code == 449:
             url = 'http://msdn.microsoft.com/en-us/library/dd891478(v=prot.10).aspx'
+        elif code == 451:
+            url = 'http://www.ietf.org/rfc/rfc7725.txt'
         elif code in WEBDAV_STATUS_CODES:
             url = 'http://tools.ietf.org/html/rfc4918#section-11.%d' % (WEBDAV_STATUS_CODES.index(code) + 1)
         elif code in HTTP_STATUS_CODES:
@@ -646,7 +648,23 @@ class HTTPDomain(Domain):
         try:
             info = self.data[str(typ)][target]
         except KeyError:
-            return None
+            text = contnode.rawsource
+            role = self.roles.get(typ)
+            if role is None:
+                return None
+
+            if fromdocname not in _doctree_cache:
+                _doctree_cache[fromdocname] = env.get_doctree(fromdocname)
+            doctree = _doctree_cache[fromdocname]
+
+            resnode = role.result_nodes(doctree, env, node, None)[0][0]
+            if isinstance(resnode, addnodes.pending_xref):
+                text = node[0][0]
+                reporter = doctree.reporter
+                reporter.warning('Cannot resolve reference to %r' % text,
+                                 line=node.line)
+                return None
+            return resnode
         else:
             anchor = http_resource_anchor(typ, target)
             title = typ.upper() + ' ' + target
@@ -741,6 +759,7 @@ class HTTPLexer(RegexLexer):
 
 def setup(app):
     app.add_domain(HTTPDomain)
+
     try:
         get_lexer_by_name('http')
     except ClassNotFound: