commit ba98ee169548b9abea881b24251537998cd75f90
parent 72f5f154b15f6974ac9c1b0c7477a62aca8332d4
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 10 Nov 2025 22:19:36 +0100
update mailbox API
Diffstat:
| M | core/api-mailbox.rst | | | 74 | ++++++++++++++++++++++++++++++++++++++++++++++++++------------------------ |
1 file changed, 50 insertions(+), 24 deletions(-)
diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst
@@ -81,6 +81,15 @@ Configuration information
// before giving up on delivery?
delivery_period: RelativeTime;
+ // How much is the cost of a single
+ // registration period of a mailbox
+ // May be 0 for a free registration.
+ registration_amount: Amount
+
+ // How long is a registration period
+ // a mailbox
+ registration_period: RelativeTime
+
}
----------------
@@ -96,17 +105,12 @@ Sending messages
The content of the request must be the message with a size of
exactly message_body_bytes (see `VersionResponse`).
- The header ``Mailbox-Order-Id`` may be provided if the client recently
- paid for this message.
**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`
+ :http:statuscode:`403 Forbidden`
The specified order ID in the ``Mailbox-Order-Id`` header does not
permit sending of this message. Possible reasons include the order
being for a different message, unpaid or
@@ -162,6 +166,10 @@ Receiving messages
immediately with the messages in the mailbox, and not
wait for additional messages to arrive.
+ The header ``Mailbox-Order-Id`` may be provided if the client recently
+ paid for this message.
+
+
**Response**
:http:statuscode:`200 Ok`:
@@ -175,7 +183,7 @@ Receiving messages
load and is unable to accept the message for delivery.
The response format is given by `MailboxRateLimitedResponse`_.
-.. http:post:: /private/$ADDRESS
+.. http:delete:: /$ADDRESS
Requests the deletion of already received messages from the
mailbox. Here, ``$ADDRESS`` must be the EdDSA public key
@@ -185,6 +193,7 @@ Receiving messages
This allows the caller to select a range of messages starting
from the first message received in the last GET call
to delete.
+ FIXME: do not use delete body somehow.
**Request**
@@ -210,7 +219,7 @@ Receiving messages
// Signature by the mailbox's private key affirming
// the deletion of the messages, of purpuse
- // ``TALER_SIGNATURE_WALLET_MAILBOX_DELETE_MESSAGES``.
+ // ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES``.
signature: string;
}
@@ -232,16 +241,16 @@ Receiving messages
Key directory
-------------
-.. http:get:: /keys/$H_MAILBOX
+.. http:get:: /$H_MAILBOX/info
- Endpoint that returns signing and encryption keys for ``$H_MAILBOX``.
+ Endpoint that returns mailbox metadata including signing and encryption keys for ``$H_MAILBOX``.
**Response**
:http:statuscode:`200 Ok`:
- Keys are returned in a `MailboxMessageKeys` response,
+ Keys are returned in a `MailboxInfo` response,
:http:statuscode:`404 Not Found`:
- The mailbox has no keys configured.
+ This mailbox is not registered.
: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.
@@ -250,6 +259,21 @@ Key directory
**Details:**
+ .. _MailboxInfo:
+ .. ts:def:: MailboxInfo
+
+ interface MailboxInfo {
+
+ // Keys to of the mailbox.
+ keys: MailboxMessageKeys;
+
+ // Expiration of this mailbox.
+ // Unix epoch (seconds)
+ expiration: Timestamp;
+
+ }
+
+
.. _MailboxMessageKeys:
.. ts:def:: MailboxMessageKeys
@@ -280,36 +304,34 @@ Key directory
// X25519 keys are supported.
encryptionKeyType: "X25519";
- // Expiration of this mapping.
- // Unix epoch (seconds)
- expiration: Timestamp;
-
}
-.. http:post:: /keys
+.. http:post:: /register
- Requests the update of the encryption key for the mailbox.
+ Requests the registration or update of a mailbox.
+ May be used to update encryption keys.
+ May incur cost.
The mailbox identity is given through the keys field
in the ``MailboxMessageKeys`` field.
**Request**
- The body of the request must be a ``KeyUpdateRequest``.
+ The body of the request must be a ``MailboxRegistrationRequest``.
**Details:**
- .. _KeyUpdateRequest:
- .. ts:def:: KeyUpdateRequest
+ .. _MailboxRegistrationRequest:
+ .. ts:def:: MailboxRegistrationRequest
- interface KeyUpdateRequest {
+ interface MailboxRegistrationRequest {
- // Keys to add/update for a mailbox.
+ // Keys to add/update for the mailbox.
keys: MailboxMessageKeys;
// Signature by the mailbox's signing key affirming
// the update of keys, of purpose
- // ``TALER_SIGNATURE_WALLET_MAILBOX_UPDATE_KEYS``.
+ // ``TALER_SIGNATURE_MAILBOX_REGISTER``.
// The signature is created over the SHA-512 hash
// of (encryptionKeyType||encryptionKey||expiration)
// Base32 crockford-encoded.
@@ -326,3 +348,7 @@ Key directory
:http:statuscode:`403 Forbidden`:
The ``signature`` is invalid.
This response comes with a standard `ErrorDetail` response.
+ :http:statuscode:`402 Payment Required`
+ Client needs to make a Taler payment before proceeding. See
+ standard Taler payment procedure.
+
