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

8 files changed, 184 insertions, 65 deletions

diff --git a/api-bank.rst b/api-bank.rst
index ea07e3a8..d59cfd54 100644
--- a/api-bank.rst
+++ b/api-bank.rst
@@ -1,5 +1,5 @@
 =========
-Banks API
+Bank API
 =========
 
 The following APIs are served from banks, in order to allow mints to
@@ -7,12 +7,12 @@ deposit funds to money recipients.  A typical scenario for calling this
 APIs is after a merchant has deposited coins to the mint, and the mint
 needs to give real money to the merchant.
 
---------
-Test API
---------
+------------------
+Administrative API
+------------------
 
-This API is useful for testing purposes, as no real money will be
-involved.
+This is `local` API, meant to make the bank communicate with trusted entities,
+namely mints.
 
 .. _bank-deposit:
 .. http:post:: /admin/add/incoming
@@ -21,28 +21,36 @@ involved.
 
 **Response:**
 
-:status 200: The request has been correctly handled, so the funds have been transferred to the merchant's account
+:status 200 OK: The request has been correctly handled, so the funds have been transferred to
+the recipient's account
+
+:status 400 Bad Request: The bank replies a `BankIncomingError`_ object
 **Details:**
 
-  .. _BankDepositRequest:
-  .. code-block:: tsref
-
-    interface BankDepositRequest {
-      
-      // JSON 'amount' object. The amount the caller wants to transfer
-      // to the recipient's count
-      f: Amount;
-
-      // The transaction id (meant as in 'Taler transaction id') according
-      // to which the caller is now giving money to the recipient. That way,
-      // the recipient can link inwards money to commercial activity.
-      tid: number; 
-
-      // The recipient's account identificator. For this testing purpose, the
-      // account format will the normal IBAN format having the token "TEST"
-      // in place of the country code and having the check digit removed. For instance,
-      // if "SA03 8000 0000 6080 1016 7519" were a valid Saudi Arabian IBAN, then
-      // "TEST 8000 0000 6080 1016 7519" would be a correct test account number as well.
-      account: string;
+.. _BankDepositRequest:
+.. code-block:: tsref
+
+  interface BankDepositRequest {
+    
+    // JSON 'amount' object. The amount the caller wants to transfer
+    // to the recipient's count
+    amount: Amount;
+
+    // The id of this wire transfer
+    wid: base32; 
+
+    // The recipient's account identificator
+    account: number;
     
-    }
+  }
+
+.. _BankIncomingError:
+.. code-block:: tsref
+
+  interface BankIncomingError {
+
+    // The reason which made this request fail. Typically due to malfomation
+    // of the POST's body
+    reason: string
+  
+  }
diff --git a/api-merchant.rst b/api-merchant.rst
index 6f175552..72b7592e 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -48,15 +48,6 @@ that is legally non-binding:
       // Signature over the contract made by the merchant.
       // Must confirm to the `Signature specification`_ below.
       sig: EddsaSignature;
-
-      // URL where the customer's wallet
-      // must send the payment for the contract.
-      // May be relative to the URL of the page that
-      // delivered the contract.
-      pay_url: string;
-
-      // URL to the `execution page`_.
-      exec_url: string;
     }
 
 The contract must have the following structure:
@@ -76,6 +67,15 @@ The contract must have the following structure:
       // product instance.
       repurchase_correlation_id?: string;
 
+      // URL that the wallet will navigate to after the customer
+      // confirmed purchasing the contract.  Responsible for
+      // doing the actual payment and making available the product (if digital)
+      // or displaying a confirmation.
+      // The placeholder ${H_contract} will be replaced
+      // with the contract hash by wallets before navigating
+      // to the fulfillment URL.
+      fulfillment_url: string;
+
       // Maximum total deposit fee accepted by the merchant for this contract
       max_fee: Amount;
 
diff --git a/api-mint.rst b/api-mint.rst
index c9f6e2ff..2b438dfa 100644
--- a/api-mint.rst
+++ b/api-mint.rst
@@ -80,10 +80,6 @@ possibly by using HTTPS.
       // When does the denomination key become valid?
       stamp_start: Timestamp;
 
-      // When is it no longer possible to withdraw fresh coins
-      // of this denomination?
-      stamp_expire_withdraw: Timestamp;
-
       // When is it no longer possible to deposit coins
       // of this denomination?
       stamp_expire_withdraw: Timestamp;
diff --git a/example-essay-store.rst b/example-essay-store.rst
new file mode 100644
index 00000000..74a25990
--- /dev/null
+++ b/example-essay-store.rst
@@ -0,0 +1,49 @@
+==================================
+Example: Essay Store
+==================================
+
+The main page of the essay store shows links to essays of the form `/essay?name=:name`.
+
+The `/essay` URL takes the following query parameters:
+ * `name`: mandatory, name of the essay
+ * `tid`: optional, transaction ID generated by the merchant for the
+   contract that was used to purchase an instance of the article
+ * `timestamp`, optional, timestamp for the contract that was used to purchase
+   the essay with the given `tid`.
+
+These are the steps for showing `/essay`.  If the wallet is not present in
+steps 2 and 3, the user agent is redirected to a mock credit card
+payment page.
+
+1. The server checks the status of the the essay with the name `name` in the server-side
+   session state
+
+  * If the essay is marked as payed, display the essay.
+  * Otherwise proceed with step 2
+
+2. The server checks if the `tid` and `timestamp` query parameters are present
+
+  * If `tid` and `timestamp` are present, restore the contract for the essay
+    (using `tid` as transaction id in the contract, `timestamp` as timestamp
+    and `timestamp+REFUND_DELTA` as refund deadline) and emit the
+    `taler-execute-contract` DOM event in the user agent.
+  * Otherwise proceed with step 3
+
+3. The server generates a new contract and emits the `taler-confirm-contract` DOM event in the user agent,
+   with the essay name as repurchase correlation identifier and `/essay?name=:name?tid=:tid` as fulfillment url.
+
+
+In step 2, the `taler-execute-contract` event has the following parameters:
+
+* `H_contract`: hash of the contract that was restored
+* `payment_url`: The internal URL `/pay?H_contract=...` of the essay store,
+  will set the server-side session state for the article associated with the
+  contract hash on successful coin deposit.  The contract hash is associated
+  with the article name in the server-side session state when the contract is restored.
+* `offer_url`: Link to a teaser page (`/teaser?name=...`), which also contains a link to the article
+  page, without the `tid` parameter.
+
+
+Note that we assume that all essays cost the same (otherwise the amount would have to be included in
+the restoration information in the /essay fulfillment URL).  The refund deadline is computed
+by adding the merchant-specific constant `REFUND_DELTA` to the contract's timestamp.
diff --git a/impl-merchant.rst b/impl-merchant.rst
index 0b5d1975..28bfc76b 100644
--- a/impl-merchant.rst
+++ b/impl-merchant.rst
@@ -50,6 +50,23 @@ The Merchant Backend HTTP API
 
 The following API are made available by the merchant's `backend` to the merchant's `frontend`.
 
+.. http:post:: /hash-contract
+  
+  Ask the backend to compute the hash of the `contract` given in the POST's body (the full contract
+  should be the value of a JSON field named `contract`). This feature allows frontends to verify
+  that names of resources which are going to be sold are actually `in` the paid cotnract. Without
+  this feature, a malicious wallet can request resource A and pay for resource B without the frontend
+  being aware of that.
+
+  **Response**
+
+  :status 200 OK:
+    hash succesfully computed. The returned value is a JSON having one field called `hash` containing
+    the hashed contract
+  :status 400 Bad Request:
+    Request not understood. The JSON was invalid. Possibly due to some error in
+    formatting the JSON by the `frontend`.
+
 .. http:post:: /contract
 
   Ask the backend to add some missing (mostly related to cryptography) information to the contract.
diff --git a/index.rst b/index.rst
index deca474c..f8b938e1 100644
--- a/index.rst
+++ b/index.rst
@@ -50,6 +50,7 @@ the material covered in the *Operator Handbook*.
   integration-general
   integration-bank
   integration-merchant
+  example-essay-store
 
 
 --------------------------------------
diff --git a/integration-bank.rst b/integration-bank.rst
index c90bf042..348f70ae 100644
--- a/integration-bank.rst
+++ b/integration-bank.rst
@@ -17,36 +17,64 @@ For JavaScript code examples, see :ref:`communication`.
 Reserve Creation Request
 -------------------------
 
-The bank website can request the creation of a :term:`reserve`.  Note that the
-user will always be prompted by the wallet before a reserve is created in the
-wallet.
+The bank website can request the creation of a :term:`reserve`.  This operation
+will require the user to specify the mint where he wants to create the reserve
+and the resolution of a CAPTCHA, before any action will be taken.
 
-As a result of the reserve creation request, the following steps will happen insequence:
- 1. The wallet will prompt the user for the *mint base URL* and ask the user to
-    confirm creating the reserve.
+As a result of the reserve creation request, the following steps will happen in sequence:
+ 1. The user chooses the desired amount from the bank's form
+ 2. Upon confirmation, the wallet fetches the desired amount from the user-filled form and
+    prompts the user for the *mint base URL*. Then ask the user to confirm creating the
+    reserve.
  2. The wallet will create a key pair for the reserve.
- 3. The wallet will make a request to the bank, containing
-    the reserve's public key and the mint base URL chosen by the user
+ 3. The wallet will request the CAPTCHA page to the bank. In that request's parameters it
+    communicates the desired amount, the reserve's public key and the mint base URL to the
+    bank
+ 4. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve
+    creation according to the gotten parameters. Together with `200 OK` status code sent back
+    to the wallet, it gets also a `ReserveCreated`_ object.
 
-The bank should then take steps that will establish the reserve at the
-customer's requested mint.  This could, depending on the bank and mint, either
-be a SEPA wire transfer or some other means.
+Note that the reserve creation can be done by a SEPA wire transfer or some other means,
+depending on the user's bank and chosen mint.
 
 In response to the reserve creation request, the Taler wallet MAY cause the
 current document location to be changed, in order to navigate to a
 wallet-internal confirmation page.
 
 The bank requests reserve creation with the ``taler-create-reserve`` event.
-The event data must be a JavaScript ``object`` with the following fields:
-
- * ``form_id``: The ``id`` of the ``form`` HTML element that contains data for the HTTP POST request
-   that confirms reserve creation with the bank.
- * ``input_amount``: Amount of the reserve in the format ``N.C CUR``, where ``CUR`` is the
-   currency code.
- * ``mint_rcv``: The ``id`` of the ``input`` HTML element in the reserve creation form
-   that will contain mint base URL for the reserve
- * ``input_pub``: The ``id`` of the ``input`` HTML element in the reserve creation form
-   that will contain the reserve's public key.
-
-Note that the bank website MUST contain an HTML form with the data required for the request and
-input fields for receiving data from the mint.
+The event data must be a `CreateReserveDetail`_:
+
+
+.. _CreateReserveDetail:
+.. code-block:: tsref
+
+  interface CreateReserveDetail {
+    
+    // JSON 'amount' object. The amount the caller wants to transfer
+    // to the recipient's count
+    amount: Amount;
+
+    // CAPTCHA's page URL which needs the following parameters
+    // query parameters:
+    // amount_value
+    // amount_fraction
+    // amount_currency
+    // reserve_pub
+    // mint
+    callback_url: string;
+
+    // list of wire transfer types supported by the bank
+    // e.g. "SEPA", "test"
+    wt_types: Array<string>
+  }
+
+.. _ReserveCreated:
+.. code-block:: tsref
+
+  interface ReserveCreated {
+
+    // A URL informing the user about the succesfull outcome
+    // of his operation
+    redirect_url: string;  
+
+  }
diff --git a/wireformats.rst b/wireformats.rst
index f759bf62..be090596 100644
--- a/wireformats.rst
+++ b/wireformats.rst
@@ -12,6 +12,26 @@ The information required for wire transfer depends on the type of wire transfer
 used.  Since the wire transfers differ for each region, we document here the
 ones currently supported by the mint.
 
+TEST
+----
+
+The TEST wire format is used for testing and for integration with Taler's
+simple "bank" system which in the future might be useful to setup a bank
+for a local / regional currency or accounting system.  Using the TEST
+wire format in combination with the Taler's bank, it is thus possible to
+fully test the Taler system without using real currencies.  The wire
+format for "TEST" is very simple, in that it only specifies an account
+number in a field "account_number".  The account number given must be
+a positive 53-bit integer.  Additional fields may be present, but are
+not required.
+
+For the merchant or mint to receive deposits through TEST, the deposit
+request must thus contain a JSON object with the following fields:
+
+  * `type`: the string constant `"TEST"`
+  * `account_number`: the account number of the merchant at the bank
+
+
 SEPA
 ----