-editing Taldir spec

3 files changed, 144 insertions, 32 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 4142b049..faad3b90 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -253,8 +253,8 @@ Making the payment
     The exchange rejected the payment because a coin was already spent, or
     the merchant rejected the payment because the order was already fully paid
     (and then return signatures with refunds). If a coin was already spent,
-    the response will include the ``coin_pub`` for which the payment failed,
-    in addition to the response from the exchange to the ``/deposit`` request.
+    the response will include the ``exchange_url`` for which the payment failed,
+    in addition to the response from the exchange to the ``/batch-deposit`` request.
   :http:statuscode:`410 Gone`:
     The offer has expired and is no longer available.
   :http:statuscode:`412 Precondition failed`:
diff --git a/core/api-taldir.rst b/core/api-taldir.rst
index 1493300c..ebf783b6 100644
--- a/core/api-taldir.rst
+++ b/core/api-taldir.rst
@@ -1,6 +1,87 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2022 Taler Systems SA
 
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU Affero 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 Affero General Public License for more details.
+
+  You should have received a copy of the GNU Affero General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Christian Grothoff
+  @author Martin Schanzenbach
+
+
+======================
+The TalDir RESTful API
+======================
+
+This is a proposed API for the TalDir service which allows Taler wallets to
+securely associate an inbox service (URL and public key) with the address of a
+messaging service used by the wallet's user.  Wallets can also lookup the
+inbox of other users. This will enable wallets to make wallet-to-wallet
+payments to distant wallets where the target user is only identified by their
+address in a messaging service. Examples for messaging services include E-mail
+and SMS.
+
+The API specified here follows the :ref:`general conventions <http-common>`
+for all details not specified in the individual requests.
+The `glossary <https://docs.taler.net/glossary.html#glossary>`_
+defines all specific terms used in this section.
+
+--------------------
+Terms of service API
+--------------------
+
+These APIs allow wallets to obtain the terms of service
+and the privacy policy of the TalDir.
+
+
+.. http:get:: /terms
+
+  Get the terms of service of the TalDir.
+  The TalDir will consider the "Accept" and "Accept-Language" and
+  "Accept-Encoding" headers when generating a response. Specifically,
+  it will try to find a response with an acceptable mime-type, then
+  pick the version in the most preferred language of the user, and
+  finally apply compression if that is allowed by the client and
+  deemed beneficial.
+
+  The TalDir will set an "Etag", and subsequent requests of the
+  same client should provide the tag in an "If-None-Match" header
+  to detect if the terms of service have changed.  If not, a
+  "204 Not Modified" response will be returned.
+
+  If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the terms of service were not configured correctly.
+
+
+.. http:get:: /privacy
+
+  Get the privacy policy of the TalDir.
+  The TalDir will consider the "Accept" and "Accept-Language" and
+  "Accept-Encoding" headers when generating a response. Specifically,
+  it will try to find a response with an acceptable mime-type, then
+  pick the version in the most preferred language of the user, and
+  finally apply compression if that is allowed by the client and
+  deemed beneficial.
+
+  The TalDir will set an "Etag", and subsequent requests of the
+  same client should provide the tag in an "If-None-Match" header
+  to detect if the privacy policy has changed.  If not, a
+  "204 Not Modified" response will be returned.
+
+  If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the privacy policy was not configured correctly.
+
+
+-------------------------
+Configuration information
+-------------------------
 
-```
 .. http:get:: /config
 
   Return the protocol version and currency supported by this service.
@@ -37,13 +118,16 @@
       challenge_fee: Amount;
 
     }
-```
-```
+
+--------------------
+Address registration
+--------------------
+
 .. http:post:: /register/$METHOD
 
   Endpoint to register, extend or modify the registration for an address in
   the directory.
-  Where $METHOD is the type of address to register, e.g. "email", or "phone".
+  Here, $METHOD is the type of address to register, e.g. "email", or "phone".
 
   **Request**
 
@@ -75,15 +159,24 @@
   :http:statuscode:`402 Payment Required`
      Client needs to make a Taler payment before proceeding. See
      standard Taler payment procedure.
+  :http:statuscode:`403 Forbidden`
+     The specified ``order_id`` does not permit registration
+     of this address. Possible reaons include the order
+     being for a different registration, unpaid or
+     malformed.
+     This response comes with a standard `ErrorDetail` response.
+  :http:statuscode:`404 Not found`
+     The TalDir service does not support the specified method.
+     This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`429 Too Many Requests`:
     The client exceeded the number of allowed attempts for initiating
     a challenge for this address in the given timeframe.
-    The response format is given by `RateLimitedMessage`_.
+    The response format is given by `RateLimitedResponse`_.
 
-  .. _RateLimitedMessage:
-  .. ts:def:: RateLimitedMessage
+  .. _RateLimitedResponse:
+  .. ts:def:: RateLimitedResponse
 
-    interface RateLimitedMessage {
+    interface RateLimitedResponse {
 
       // Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED.
       code: number;
@@ -96,33 +189,43 @@
 
     }
 
-
-```
-```
 .. http:get:: /register/$H_ADDRESS/$PINTAN
 
   Endpoint that generates an HTML Web site with a QR code and
-  taler://taldir/$H_ADDRESS/$PIN-wallet link for
-  completing the registration. Useful to open the registration
-  challenge in a browser (say if it was received on a different
-  device than where the wallet is running).
-  Does NOT complete the registration, as some providers automatically
-  click on all links in messages. Yes, privacy and so.
-
-  Opening the link will lead the wallet to do the POST call below.
-  If the Taler wallet
-  can somehow intercept the URL (say for SMS, if it has the right
-  permissions) it can skip this request and directly do the POST.
+  ``taler://taldir/$H_ADDRESS/$PINTAN-wallet`` link for completing the
+  registration. Useful to open the registration challenge in a browser (say if
+  it was received on a different device than where the wallet is running).
+  Does NOT complete the registration, as some providers automatically click on
+  all links in messages. Yes, we do not like them doing so either, but ``GET``
+  is a "safe" method according to the HTTP standard, so technically this is
+  allowed.
+
+  Opening the link will lead the **wallet** to do the POST call below.  If the
+  Taler wallet can somehow intercept the URL (say for SMS, if it has the right
+  permissions) it can skip this request and directly do the POST, as all of
+  the required new information is already encoded in the URL.
+
+  Note that the wallet must be involved before the POST is made, as the
+  wallet's public key from the registration must be hashed with the ``$PINTAN``
+  to protect the user against phishing. Otherwise, someone else might attempt
+  a concurrent registration of a different public key, and the user might
+  accidentally authorize the registration of the public key of a different
+  wallet.
 
 .. http:post:: /$H_ADDRESS
 
-  Where $ID_KEY is the SHA-512 hash of the to be registered address in Crockford base32 encoding.
+  This request is the last step of a registration, proving to the TalDir that
+  the user of the wallet is indeed able to receive messages at the specified
+  address.  ``$H_ADDRESS`` is the SHA-512 hash of the address to be registered in
+  Crockford base32 encoding.
 
   **Request**
 
   .. ts:def:: IdentityConfirmation {
-    // The challenge ($PINTAN) value chosen by TalDir hashed
-    // with the wallet's public key.
+    // The solution is the SHA-512 hash of the challenge ($PINTAN) value
+    // chosen by TalDir (encoded as string just as given in the URL, but
+    // excluding the 0-termination) concatenated with the binary 32-byte
+    // value representing the wallet's EdDSA public key.
     solution: Hash;
 
   }
@@ -132,27 +235,35 @@
   :http:statuscode:`204 No Content`:
      Registration complete.
   :http:statuscode:`403 Forbidden`:
-     The solution is invalid. Retrying immediately is allowed.
+     The ``solution`` is invalid. Retrying immediately is allowed.
   :http:statuscode:`404 Not found`:
      The address is unknown (original registration attempt may have expired).
   :http:statuscode:`429 Too Many Requests`:
     The client exceeded the number of allowed attempts for solving
     a challenge for this address in the given timeframe.
 
+--------------
+Address lookup
+--------------
+
 .. http:get:: /$H_ADDRESS
 
+  Lookup the public key (and mailbox service base URL) associated with
+  an address in the TalDir. Here, ``$H_ADDRESS`` is the SHA-512 hash of
+  a (presumably) registered address in Crockford base32 encoding.
+
   **Response**
 
   Standard HTTP cache control headers are used to specify how long the
   registration is still expected to be valid.
 
   :http:statuscode:`200 Ok`:
-     Registration information returned, of type `IdentityKey`
+     Registration information returned, of type `MailboxDetailResponse`
   :http:statuscode:`404 Not found`:
-     The address is unknown (original registration attempt may have expired).
-
+     The address is unknown (original registration may have expired).
 
-  .. ts:def:: IdentityKey {
+  .. _MailboxDetailResponse:
+  .. ts:def:: MailboxDetailResponse {
 
     // Registered public key of the user
     public_key: EdDSAPublicKey;
diff --git a/core/index.rst b/core/index.rst
index 6dd762fd..b54e48e3 100644
--- a/core/index.rst
+++ b/core/index.rst
@@ -35,6 +35,7 @@ interfaces between the core components of Taler.
   api-merchant
   api-auditor
   api-sync
+  api-taldir
   api-wire
   api-bank-merchant
   api-bank-integration