add mailbox api spec

3 files changed, 257 insertions, 3 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 1223086d..85d8e3a7 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2537,7 +2537,7 @@ denomination.
       // `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
     }
- 
+
   The deposit operation succeeds if the coin is valid for making a deposit and
   has enough residual value that has not already been deposited or melted.
 
@@ -2572,7 +2572,7 @@ denomination.
     }
 
   .. ts:def:: DepositConfirmationSignature
- 
+
     interface DepositConfirmationSignature {
       // The EdDSA signature of `TALER_DepositConfirmationPS` using a current
       // `signing key of the exchange <sign-key-priv>` affirming the successful
@@ -2581,7 +2581,7 @@ denomination.
       exchange_sig: EddsaSignature;
     }
 
-    
+
 ----------
 Refreshing
 ----------
diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst
new file mode 100644
index 00000000..25c9cd87
--- /dev/null
+++ b/core/api-mailbox.rst
@@ -0,0 +1,253 @@
+..
+  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
+
+
+=======================
+The Mailbox RESTful API
+=======================
+
+This is a proposed API for the GNU Taler Mailbox service which allows Taler
+wallets to securely send push and pull payment requests to other wallets
+without having to interact with the respective messaging service.
+
+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 Mailbox.
+
+.. http:get:: /terms
+
+  Get the terms of service of the Mailbox.
+  The Mailbox 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 Mailbox 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 Mailbox.
+  The Mailbox 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 Mailbox 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.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The body is a `VersionResponse`.
+
+  **Details:**
+
+  .. ts:def:: VersionResponse
+
+    interface VersionResponse {
+      // libtool-style representation of the Merchant protocol version, see
+      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+      // The format is "current:revision:age".
+      version: string;
+
+      // Name of the protocol.
+      name: "taler-mailbox";
+
+      // Fee per message.
+      message_fee: Amount;
+
+      // How long will the service store a message
+      // before giving up on delivery?
+      delivery_period: Duration;
+
+    }
+
+----------------
+Sending messages
+----------------
+
+.. http:post:: /$H_MAILBOX
+
+  Puts a message into ``$H_MAILBOX``.
+  ``$H_MAILBOX`` is the SHA512 of an EdDSA public key.
+
+  **Request**
+
+  The body of the request must be an `IdentityMessage`.
+
+  **Response**
+
+  :http:statuscode:`204 No Content`
+     Message was stored and will be delivered.
+  :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 sending
+     of this message. Possible reaons include the order
+     being for a different message, unpaid or
+     malformed.
+     This response comes with a standard `ErrorDetail` response.
+  :http:statuscode:`429 Too Many Requests`:
+    The system is currently experiencing a too high request
+    load and is unable to accept the message for delivery.
+    The response format is given by `MailboxRateLimitedResponse`_.
+
+  **Details:**
+
+  .. _IdentityMessage:
+  .. ts:def:: IdentityMessage {
+    // Public DH key used to encrypt the body. Must be fresh
+    // and only used once (ephemeral).
+    ephemeral_key: EcdhePublicKey;
+
+    // Encrypted message. Must be exactly 256-32 bytes long.
+    body: string;
+
+    // Order ID, if the client recently paid for this message.
+    order_id?: string;
+  }
+
+  .. _MailboxRateLimitedResponse:
+  .. ts:def:: MailboxRateLimitedResponse
+
+    interface MailboxRateLimitedResponse {
+
+      // Taler error code, TALER_EC_MAILBOX_DELIVERY_RATE_LIMITED.
+      code: number;
+
+      // When the client should retry.
+      retry_delay: RelativeTime;
+
+      // The human readable error message.
+      hint: string;
+
+    }
+
+------------------
+Receiving messages
+------------------
+
+.. http:get:: /$H_MAILBOX
+
+  Endpoint that returns unread messages in ``$H_MAILBOX``.
+  The number of messages returned by the service can be limited.
+  If the request is simply repeated, the same messages will be
+  returned again (or possibly more if additional messages arrived
+  and the total number is below the service's current internal limit).
+  To receive additional messages, the client generally has to first
+  explicitly DELETE already downloaded messages from the mailbox.
+
+  **Request:**
+
+  :query timeout_ms=NUMBER: *Optional.*  If specified,
+    the Mailbox service will wait up to ``NUMBER``
+    milliseconds for the arrival of new messages
+    before sending the HTTP response.  Note that if the
+    mailbox is non-empty, the service will always return
+    immediately with the messages in the mailbox, and not
+    wait for additional messages to arrive.
+
+  **Response**
+
+  :http:statuscode:`200 Ok`:
+    Messages are returned in binary format, 256 bytes per message,
+    starting with the ephemeral key and followed by
+    the encrypted body. Messages are not encapsulated in JSON!
+  :http:statuscode:`204 No Content`:
+    The mailbox is empty.
+  :http:statuscode:`429 Too Many Requests`:
+    The system is currently experiencing a too high request
+    load and is unable to accept the message for delivery.
+    The response format is given by `MailboxRateLimitedResponse`_.
+
+.. http:delete:: /$ADDRESS
+
+  Requests the deletion of already received messages from the
+  mailbox. Here, ``$ADDRESS`` must be the EdDSA public key
+  of the mailbox (not the hash!).
+
+  **Request**
+
+  The body of the request must be a ``MessageDeletionRequest``.
+
+  **Details:**
+
+  .. _MessageDeletionRequest:
+  .. ts:def:: MessageDeletionRequest {
+
+    // Number of messages to delete. (Starting from the beginning
+    // of the latest GET response).
+    count: Integer;
+
+    // SHA-512 hash over all messages to delete.
+    checksum: Hash;
+
+    // Signature by the mailbox's private key affirming
+    // the deletion of the messages, of purpuse
+    // ``TALER_SIGNATURE_WALLET_MAILBOX_DELETE_MESSAGES``.
+    wallet_sig: EddsaSignature;
+
+  }
+
+  **Response**
+
+  :http:statuscode:`204 No Content`:
+     Deletion complete.
+  :http:statuscode:`403 Forbidden`:
+     The ``wallet_sig`` is invalid.
+     This response comes with a standard `ErrorDetail` response.
+  :http:statuscode:`404 Not found`:
+     The checksum does not match the messages currently at the
+     head of the mailbox, or ``count`` is larger
+     than the number of messages currently in the mailbox.
+     This response comes with a standard `ErrorDetail` response.
diff --git a/core/index.rst b/core/index.rst
index b54e48e3..f44bc247 100644
--- a/core/index.rst
+++ b/core/index.rst
@@ -36,6 +36,7 @@ interfaces between the core components of Taler.
   api-auditor
   api-sync
   api-taldir
+  api-mailbox
   api-wire
   api-bank-merchant
   api-bank-integration